fix: stop infinite RecursionError in will wizard (Date editor timezone roundtrip)

LockTimeDateEdit stored the aware-UTC datetime from _safe_fromtimestamp
into the QDateTimeEdit, which keeps the wall time with a LocalTime spec.
get_value() therefore read back x + utc_offset, so set_value(x) never
equalized x and the valueEdited -> update_setting_widgets -> set_value
signal cycle fired forever, crashing with RecursionError when clicking
Next in the 'Build your will' wizard. Store the local wall-clock time
instead (alarm stays aware-UTC for the .ics export).

.gitignore

@@ -33,3 +33,4 @@ tmp*
 
 # Release artifacts
 bal_v*.zip.*
+tests/karen7

.opencode/plans/plan_android_reader.md

@@ -0,0 +1,231 @@
+# PLAN_ANDROID_READER.md — BAL Reader: an Android QR will reader
+
+**Date:** 2026-09-09 · **Status:** proposed · **Ties into:** BAL plugin QR export (BALQR / BC-UR v1 / BC-UR v2 / BBQR)
+
+## 1. Goal
+
+Ship a minimal single-activity Android app that reads any QR will exported by the BAL
+Electrum plugin, decodes all four supported wire formats, and lets the user view, copy,
+share, or save the recovered will data. The app is a **reader only** — it never signs or
+broadcasts.
+
+## 2. Scope
+
+**In scope**
+
+- Continuous camera capture (CameraX + ML Kit on-device barcode scanning, QR-only).
+- Auto-detection of the four formats (`detect_format`: `"balqr" / "ur1" / "ur2" / "bbqr"`).
+- Order-independent frame assembly: duplicates ignored, out-of-order accepted, UR v2
+  XOR-fountain redundancy exploited, session-level reset on transfer switch.
+- Whole-will JSON **and** tx-hex-list payloads, both decoded to a readable view.
+- Copy raw transfer text / Share / Save via Storage Access Framework.
+- Verified decode chain runnable on the dev machine (no Android needed).
+
+**Out of scope**
+
+- Signing, broadcasting, password handling, wallet integration.
+- Export/authoring QR codes *from* the phone.
+- Audio-modem transport (unchanged, plugin-only).
+
+## 3. Architecture
+
+### 3.1 Why Chaquopy (reuse the tested Python codecs)
+
+`bal/core/animated_qr.py` (1178 lines) and `bal/core/qrtransfer.py` (212 lines) are
+**pure stdlib** (`base64`, `hashlib`, `zlib`), GUI-free, Python-3.8-clean (verified: no
+walrus/match/`X|Y`/PEP-585 generics), and `bal/core/__init__.py` is an empty docstring.
+Chaquopy bundles CPython into the APK, so **the exact, battle-tested codec modules run
+unchanged on Android** with zero port risk. The Kotlin side is only camera glue + UI.
+
+### 3.2 Decode chain (mirror of the plugin's import tail)
+
+The plugin's `_review_and_sign` (dialogs.py:3792) does exactly:
+
+1. `session.resolve()` -> `(transfer_text, compressed: bool)`
+   (UR v1/v2/BBQR for the first pair; `(text, flag)` for BAL QR).
+2. `decode_transfer(transfer_text, compressed)` -> list of parts (tx hexes, or the single
+   whole-will JSON).
+3. `"\n".join(parts)` -> opaque payload.
+4. `decode_will_payload(payload)` -> `("will", dict)` **or** `("txs", [strings])`.
+
+The app reuses all of it verbatim through the `AnimatedQrSession` facade (`add_part`
+auto-detects per frame, dedups, tracks `received/total/done`).
+
+### 3.3 Data flow
+
+```
+CameraX ImageAnalysis -> ML Kit BarcodeScanning (QR) -> raw string
+   -> BalDecoder.add(text)  [Chaquopy -> AnimatedQrSession.add_part]
+   -> status: format chip + received/total, duplicate-tolerant
+   -> when done: auto-stop -> BalDecoder.finish() (4-step decode)
+   -> ResultActivity: JSON view OR tx-list view + Copy/Share/Save
+```
+
+## 4. Repository layout (new `android/` subfolder)
+
+```
+android/
+  README.md                        # build (Android Studio), usage, codec-sync rule, MIT note
+  settings.gradle.kts
+  build.gradle.kts                 # root: plugins (AGP 8.10, Kotlin 2.0.21, Chaquopy 17, apply false)
+  gradle.properties
+  gradlew, gradlew.bat
+  gradle/wrapper/                  # gradle-wrapper.properties + gradle-wrapper.jar (fetched; see §7)
+  scripts/
+    sync_codecs.py                 # copy bal/core/{__init__,animated_qr,qrtransfer}.py -> app python dir; import-check
+  test_chain/
+    verify_chain.py                # full decode-chain simulation, runs on dev machine
+  app/
+    build.gradle.kts               # com.android.application + com.chaquo.python; CameraX/ML Kit deps
+    src/main/
+      AndroidManifest.xml          # CAMERA permission
+      java/life/after/bitcoin/
+        MainActivity.kt            # permission + PreviewView + ImageAnalysis + status header
+        BalDecoder.kt              # Chaquopy bridge (§5.1)
+        ResultActivity.kt          # viewer + copy/share/save (§5.3)
+      res/layout/activity_main.xml, activity_result.xml
+      res/values/strings.xml
+      python/bal/core/             # SYNCED COPIES (committed, deterministic; regenerate with script)
+        __init__.py
+        animated_qr.py
+        qrtransfer.py
+```
+
+## 5. Component specifications
+
+### 5.1 `BalDecoder` (Kotlin, Chaquopy bridge)
+
+- Lazy init: `Python.start(AndroidPlatform(context))`, `getModule("bal.core.animated_qr")`.
+- `fun add(text: String): String` -> `session.add_part(text)`; surfaces `"ok"`/`"dup"`;
+  maps `AnimatedQrError` subclasses to a result the UI can ignore (garbage frames) vs
+  reset (transfer switch -> `TransferConflictError` -> tell user to rescan).
+- `val format: String?` (`"balqr"/"ur1"/"ur2"/"bbqr"`), `val received: Int`,
+  `val total: Int`, `val done: Boolean` (auto-converted by Chaquopy).
+- `fun finish(): DecodedResult` - the 4-step chain; returns
+  `data class DecodedResult(kind: "will"|"txs", data: Map<String,Any>|List<String>, rawTransfer: String)`.
+- `fun reset()` -> new `AnimatedQrSession` (new scan).
+
+### 5.2 `MainActivity` (camera + scan loop)
+
+- Launches CameraX via `ProcessCameraProvider`; `PreviewView` fills screen; camera
+  permission via `ActivityResultContracts.RequestPermission`.
+- `ImageAnalysis` `STRATEGY_KEEP_ONLY_LATEST`; analyzer throttled (~100 ms) calls ML Kit
+  `BarcodeScanning` with `Barcode.FORMAT_QR_CODE`.
+- Thread-safe feed to `BalDecoder` (analyzer runs on a background executor); UI status
+  via `runOnUiThread`.
+- Header row: format chip + `received/total`; on `done` -> stop analyzer -> launch
+  `ResultActivity` (results as Parcelable); "New scan" restarts.
+- Garbage / incomplete frames silently ignored (same policy as the plugin); a
+  `TransferConflictError` mid-scan resets the session and signals the user to rescan.
+
+### 5.3 `ResultActivity` (viewer)
+
+- `kind == "will"`: whole-will JSON - each item's `tx` hex shown truncated with full view
+  on demand.
+- `kind == "txs"`: list of tx hexes.
+- Action bar: **Copy** (raw transfer text to clipboard), **Share** (ACTION_SEND
+  text/plain), **Save** (SAF `ACTION_CREATE_DOCUMENT` -> `will.json` / `will_tx.txt`).
+- "Scan another" button -> finish -> back to camera.
+
+### 5.4 `scripts/sync_codecs.py`
+
+- Copies the 3 files from `bal/core/` -> `app/src/main/python/bal/core/` (idempotent).
+- Post-copy check (dev machine): import `bal.core.animated_qr`, run one UR v2 frame +
+  decode cycle to prove the copy imports standalone.
+- Documented as the rule after any codec change (README).
+
+### 5.5 `test_chain/verify_chain.py`
+
+Simulates the exact APK runtime path on the dev machine (no Android). Generates frames
+precisely as the export page does, then feeds `AnimatedQrSession.add_part` in
+scrambled/duplicated/dropped order and asserts correct results for:
+
+- BAL QR multi-frame, plain **and** compressed (`Z` flag): `split_frames(encode_transfer(...))`.
+- UR v1 single-part (`ur1_frames` headerless) and `1ofN` multipart.
+- UR v2 single-part and fountain multipart with >=1 frame dropped and >=1 duplicated
+  (exercises the XOR solve).
+- BBQR `Z`/`H`/`2`: `bbqr_frames(..., encoding=...)`, with the `Z` auto-decompress branch.
+- payload kinds: whole-will JSON **and** tx-hex list.
+- transfer-switch: feed a frame of a different transfer mid-session -> expect conflict, as
+  the UI will.
+
+Runs under the runtime venv:
+`source .../electrum/env/bin/activate && QT_QPA_PLATFORM=offscreen python3 android/test_chain/verify_chain.py`
+
+## 6. Wire-format reference (bundled codecs)
+
+- **BAL QR**: `BALQR1|<total>|<index>|<flags>|<payload>`, flags `""` or `Z` (zlib+base64).
+  Concatenate payloads 1..total -> transfer string -> `decode_transfer` splits on `\n`.
+- **BC-UR v1**: multipart `ur:bytes/<seq>of<seq_len>/<sha256-bc32-digest>/<bc32-frag>`;
+  single-part `ur:bytes/<bc32>` (digest-less). BC32 = bech32_bis (XOR `0x3FFFFFFF`)
+  5-bit alphabet.
+- **BC-UR v2**: multipart `ur:bytes/<seq>-of-<seq_len>/<bytewords-minimal-part>` +
+  single-part headerless; part body = CBOR `[seq, seq_len, msg_len, crc32, data]` +
+  per-part CRC-32, bytewords-minimal; fountain via `choose_fragments` (xoshiro256** +
+  alias/threshold), mixed by XOR - decoder solves from any sufficient subset.
+- **BBQR**: `B$<encoding><type><base36 total><base36 index><payload>`; encodings `H`
+  (upper hex), `2` (base32nal), `Z` (deflate `wbits=-10` -> base32).
+
+## 7. Toolchain & versions
+
+| Item | Version | Notes |
+|---|---|---|
+| Chaquopy | 17.0.0 | Python 3.10-3.14, AGP 7.3-9.2, minSdk 24 |
+| AGP | 8.10.0 | in Chaquopy 17 range |
+| Gradle wrapper | 8.14 | required by AGP 8.10 |
+| Kotlin | 2.0.21 | |
+| compile/target SDK | 35 / min 24 | |
+| JDK | 17 (machine has OpenJDK 17) | |
+| CameraX | 1.3.4 | `camera-core`, `camera-camera2`, `camera-lifecycle`, `camera-view` |
+| ML Kit barcode | 17.3.0 | on-device, no API key |
+| Python (codec) | 3.12 (Chaquopy) | codecs verified 3.8-clean |
+
+Dev machine: Android Studio + JDK 17 present; SDK platforms/build-tools/gradle absent ->
+the **first real APK build happens in Android Studio with network**. `gradle-wrapper.jar`
+is fetched via `curl` (canonical location) so `./gradlew` works; if network is blocked,
+README documents Android Studio regenerating it.
+
+## 8. Build & run outline (for README)
+
+1. Open `android/` in Android Studio (or `./gradlew assembleDebug`).
+2. Allow Gradle to fetch wrapper/deps (network).
+3. Install on device; grant camera permission.
+4. In the plugin: export dialog -> pick format (start with BAL QR default; also test
+   UR v1/UR v2/BBQR) -> show the animated QR on screen.
+5. Point camera at screen; watch `received/total`; decoded result appears ->
+   Copy/Share/Save.
+
+## 9. Verification
+
+**On this machine (no Android needed)**
+
+1. `python3 android/scripts/sync_codecs.py` -> copy + import/roundtrip sanity.
+2. `QT_QPA_PLATFORM=offscreen python3 android/test_chain/verify_chain.py` -> all
+   formats/payload kinds/conflict cases pass.
+3. `ruff check android/scripts/sync_codecs.py android/test_chain/verify_chain.py` -> clean.
+4. `pytest tests/test_core_*.py tests/test_gui_*.py` -> still **445 passed**
+   (payload code untouched; only new files).
+5. `python3 build_zip.py` unaffected (no change under `bal/`).
+
+**On-device (manual, user)**
+
+- Walk the 4 formats against the plugin's export page, single- and multi-frame
+  (animated), on a real phone.
+- Confirm format chip, progress, auto-finish, Copy/Share/Save.
+
+**Boundary** - no APK is produced by this machine's environment; the artifact is a
+complete, independently buildable source tree + verified codec path.
+
+## 10. Risks & notes
+
+- First Gradle sync needs network (deps + wrapper). Pinned versions are conservative;
+  knobs documented.
+- Bundled codec copies must be regenerated after any `bal/core/animated_qr.py` /
+  `qrtransfer.py` change - handled by `sync_codecs.py` + README note (copies are
+  committed for deterministic builds).
+- Animated QR reading depends on the camera catching enough distinct frames (ML Kit
+  analyzer keeps scanning; the session dedups and accepts out-of-order). Slow phone
+  screens / glare may raise time-to-complete - expected, same as the plugin.
+- App name/package (`life.after.bitcoin`, label "BAL Reader") are placeholders - trivial
+  to change.
+- MIT: bundled codec files inherit the plugin's MIT license (noted in README).

AGENTS.md

@@ -3,6 +3,9 @@
 BAL — Bitcoin After Life, an Electrum plugin (inheritance / dead-man's-switch).
 Source-of-truth docs: `README.md`, `HANDOFF.md`, `COMPATIBILITY.md`.
 
+Paths below are relative to the repo, or use `$BAL_HOME` (the directory
+containing this repo and the sibling `electrum/` checkout).
+
 ## Environments (critical)
 
 Two separate venvs; using the wrong one is the #1 mistake.
@@ -20,8 +23,9 @@ The plugin's `bal/` directory is symlinked into
 
 ## Test & verify
 
-Tests are **standalone scripts**, not pytest. Each `tests/test_*.py` file runs
+Tests work **both** as standalone scripts and via pytest (tests use `def test_*`
-its `test_*` functions from `if __name__ == "__main__"`. Run a file directly:
+naming and also have `if __name__ == "__main__"` blocks). Run a single file
+directly:
 
 ```bash
 source "$BAL_HOME/electrum/env/bin/activate"
@@ -29,6 +33,13 @@ python3 tests/test_core_heirs.py        # core, no Qt needed
 QT_QPA_PLATFORM=offscreen python3 tests/test_gui_common.py   # GUI tests need offscreen
 ```
 
+Or run a batch with pytest (as `make-release.sh` does):
+
+```bash
+source "$BAL_HOME/electrum/env/bin/activate"
+QT_QPA_PLATFORM=offscreen python3 -m pytest tests/test_core_*.py -q
+```
+
 - Most core tests run offline (no wallet/network). Some files
   (`test_group_*.py`, `test_no_willexecutor_karen7.py`, `parallel_ping_test.py`)
   exercise will-executor/network flows and need the live servers — don't rely on
@@ -43,7 +54,8 @@ QT_QPA_PLATFORM=offscreen python3 tests/test_gui_common.py   # GUI tests need of
 - **Ruff is NOT clean** (hundreds of pre-existing errors in `bal/` and
   `tests/`). Do not run `--fix` wholesale and do not try to silence everything;
   just avoid adding new violations. Config: `pyproject.toml` (line-length 88,
-  E501 ignored).
+  E501 ignored). Per-file ignores suppress `F403`/`F405` for the intentional
+  `from .common import *` hub pattern in `bal/gui/qt/`.
 - Lint via the repo venv: `./venv/bin/ruff`
 - Typecheck: `pyright` (npm, `node_modules/`), config `pyrightconfig.json`
   (`extraPaths: ["../electrum"]`). Pyright reports many false positives on
@@ -53,9 +65,18 @@ QT_QPA_PLATFORM=offscreen python3 tests/test_gui_common.py   # GUI tests need of
 ## Architecture
 
 - `bal/core/` = GUI-free logic (`heirs.py`, `will.py`, `willexecutors.py`,
-  `plugin_base.py`, `util.py`). Must never import Qt.
+  `plugin_base.py`, `util.py`, `checkalive.py`, `reminders.py`,
+  `input_rules.py`).
+  Must never import Qt.
 - `bal/gui/qt/` = PyQt6 layer. `window.py` is the per-wallet controller,
-  `plugin.py` is the Electrum `@hooks` entry, `qt.py` is a zipimport shim.
+  `plugin.py` is the Electrum `@hooks` entry. `qt.py` is a zipimport shim.
+  `common.py` uses `import *` intentionally (ruff suppresses F403/F405 here);
+  `bal/gui/qt/*.py` all import from it.
+- `bal/cli/` = headless command-line layer (no Qt). `plugin.py` is the daemon
+  entry point, `commands.py` registers `bal_*` commands with Electrum.
+- `bal/wallet_util/` = wallet helper utilities for Qt and core.
+- `bal/qt.py` and `bal/cmdline.py` are thin shims that Electrum discovers
+  via `manifest.json`; they import the real `Plugin` class via `importlib`.
 - `bal/manifest.json` = version source of truth (Electrum reads it; also read by
   `make-release.sh`).
 - Compatibility constraint: must support Electrum **4.7.2 and 4.8.0**; the DB

AUDIO_MODEM_DEBIAN.md

@@ -0,0 +1,170 @@
+# Audio MODEM on Debian — setup & troubleshooting
+
+How to make the optional **audio channel** of BAL (and Electrum's own
+`audio_modem` plugin) work on Debian/Ubuntu. The channel lets you send a will
+to another device as acoustic OFDM tones instead of scanning QR codes.
+
+Recommended reading before starting: `CHANGELOG.md` entry 56
+(Audio-environment notes) and `HANDOFF.md` (Dev-box audio prerequisites).
+
+---
+
+## 1. What you need (three independent pieces)
+
+| Piece                    | Provides                                   | Where it comes from                  |
+|--------------------------|--------------------------------------------|--------------------------------------|
+| `amodem` (Python)        | OFDM modulation/demodulation               | `pip install amodem` (any venv)       |
+| `libportaudio.so`        | sound I/O backend used by `amodem.audio`   | Debian package `libportaudio2` (+ dev symlink, see §2) |
+| Electrum `audio_modem`   | the plugin whose `_send`/`_recv` BAL reuses | built into Electrum                   |
+
+BAL shows the audio buttons only when the plugin is **enabled** (Tools →
+Plugins → Audio Modem) and `amodem` is importable.
+
+> On a headless/CI box there is no speaker/mic, but the channel can still be
+> verified with the **sink-monitor loopback** in §4.
+
+---
+
+## 2. The two line fixes (this is the part everyone forgets)
+
+Debian ships a versioned `libportaudio.so.2` but **not** the unversioned
+`libportaudio.so` that old `amodem` code uses, and `amodem` uses NumPy APIs
+removed in NumPy 2.x. Both fail **silently** (the plugin's `_send` runs the
+load inside a `WaitingDialog` thread without an `on_error` handler).
+
+### 2a. PortAudio unversioned symlink
+
+Install the dev package (creates the unversioned symlink), or create it by
+hand:
+
+```bash
+sudo apt install libportaudio2 libportaudio-dev   # preferred
+# or, without the package:
+sudo ln -s /usr/lib/x86_64-linux-gnu/libportaudio.so.2 \
+           /usr/lib/x86_64-linux-gnu/libportaudio.so
+```
+
+Verify:
+
+```bash
+source "$BAL_HOME/electrum/env/bin/activate"
+python3 -c "import amodem.audio; print(amodem.audio.Interface(config=None).load('libportaudio.so').call('GetVersionText'))"
+# b'PortAudio V19...'  <-- success
+```
+
+> **No-sudo alternative** (fine for one-shot tests): point `LD_LIBRARY_PATH`
+> at a directory containing a `libportaudio.so` symlink to the `.so.2`:
+> ```bash
+> mkdir -p /tmp/portaudio_stub
+> ln -s /usr/lib/x86_64-linux-gnu/libportaudio.so.2 /tmp/portaudio_stub/libportaudio.so
+> export LD_LIBRARY_PATH=/tmp/portaudio_stub:$LD_LIBRARY_PATH
+> ```
+
+### 2b. amodem vs NumPy 2.x (`tostring` removed)
+
+`amodem` 1.16.0 calls `numpy.ndarray.tostring()`, removed in NumPy 2.x
+(≥ 2.4.6 dies with `AttributeError` on the first sample write, so **no carrier
+is ever emitted**). Either pin NumPy < 2, or patch the single line in the
+installed package:
+
+```bash
+source "$BAL_HOME/electrum/env/bin/activate"
+python3 -m pip install "numpy<2"   # option A (downgrade)
+# option B (patch; path depends on your site-packages):
+sed -i "s/sym.astype('int16').tostring()/sym.astype('int16').tobytes()/" \
+  "$BAL_HOME/electrum/env/lib/python3.11/site-packages/amodem/common.py"
+```
+
+> This must be done on **every** machine that receives/sends audio (both ends
+> of the channel use the same code), and again after reinstalling/upgrading
+> `amodem`.
+
+---
+
+## 3. Environment checklist (dev box, already applied)
+
+These were applied on the current dev box and do NOT need to be re-done:
+
+- `amodem` installed in the runtime venv (`1.16.0`).
+- `amodem/common.py` patched `tostring()` → `tobytes()`.
+- System symlink or `LD_LIBRARY_PATH` stub for `libportaudio.so`.
+- PulseAudio running; default sink `ALC236 Analog`, default source DMIC.
+
+Check them in one command:
+
+```bash
+source "$BAL_HOME/electrum/env/bin/activate"
+python3 - <<'EOF'
+import amodem, ctypes, numpy, zlib
+print("amodem", amodem.__version__)
+print("numpy", numpy.__version__, "(2.x needs the tobytes patch)")
+import amodem.audio
+amodem.audio.Interface(config=None).load("libportaudio.so")
+print("libportaudio.so loaded OK (symlink or LD_LIBRARY_PATH in place)")
+EOF
+```
+
+---
+
+## 4. Verifying the channel (no speakers/mic needed)
+
+Full **send → sink → sink-monitor → recv** round-trip on one machine:
+
+```bash
+# 1) route capture at the loop and remember the original source
+MON="$(pactl get-default-sink).monitor"; ORIG=$(pactl get-default-source)
+pactl set-default-source "$MON"
+
+# 2) run the round-trip (uses zlib-compressed payload like the plugin)
+source "$BAL_HOME/electrum/env/bin/activate"
+timeout 90 python3 /tmp/opencode/bal_audio_loopback.py
+#   expected: bitrate 1.0 kbps ... send done ... RECV OK
+
+# 3) restore the original source
+pactl set-default-source "$ORIG"
+```
+
+Any payload you like: `python3 /tmp/opencode/bal_audio_loopback.py "BALQR|1|1|0|hi"`.
+
+With real speakers + mic instead, skip the `pactl` swapping, put the devices
+close, keep volumes high, and run the same script.
+
+---
+
+## 5. Testing through the real GUI
+
+1. **Tools → (Plugins) → Audio Modem** → enable it. If asked for settings,
+   pick a bitrate: default `slowest()` is ~1.0–1.2 kbps (a ~2 KB will takes
+   ~15–20 s of audio); higher bitrates are faster but less robust.
+2. Wallet A → BAL will list → **Export → QR Codes → Audio…**
+   (the audio transport sends the raw newline-joined tx list, no BAL framing).
+3. Wallet B → will list → **Import via QR → Audio…** → wait for
+   "Waiting for audio (... kbps)…", a loading cursor while demodulating,
+   then the decoded slots appear → review/sign wizard opens.
+4. One machine only: apply the §4 monitor trick in the shell where Electrum
+   runs (export plays to the sink; import records from the sink monitor).
+
+---
+
+## 6. Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| No sound at all, no error anywhere in the log | `libportaudio.so` not loadable (silent) | §2a symlink or `LD_LIBRARY_PATH` stub |
+| Sound played, "Timeout waiting for carrier" on the receive end | Capture routed to the wrong device / mic muted / no speakers | §4 monitor trick; `pactl` source check; raise volume; move devices closer |
+| "Decoding failed" after carrier, no payload | Send side died with numpy `tostring` → nothing modulated | §2b patch or `numpy<2` on BOTH machines |
+| Buttons "Audio…" missing in BAL dialogs | `audio_modem` disabled in Plugins, or `amodem` not importable in the running venv | Enable plugin; `pip install amodem` |
+| Audio too long / too slow | 1 kbps default | Raise bitrate in Audio Modem settings dialog |
+
+---
+
+## 7. No-sudo quick reference (all commands)
+
+```bash
+python3 -m pip install amodem
+mkdir -p /tmp/portaudio_stub
+ln -s /usr/lib/x86_64-linux-gnu/libportaudio.so.2 /tmp/portaudio_stub/libportaudio.so
+export LD_LIBRARY_PATH=/tmp/portaudio_stub:$LD_LIBRARY_PATH
+# numpy >= 2 (one of):
+pip install "numpy<2"   # or patch amodem/common.py tobytes
+```

CHANGELOG.md

@@ -2568,3 +2568,762 @@ of a session, without requiring the normal wizard flow to have run first.
   `test_merge_will_validity_error_logs_without_crashing`.
 
 **Outcome:** DONE.
+
+---
+
+## 49. OP_RETURN support for heirs
+
+**Date:** 2026-07-30
+
+**Goal:** allow heirs to produce an OP_RETURN output instead of a regular BTC
+payment. An address prefixed with `OP_RETURN:` carries hex data (max 80 bytes);
+such heirs always have amount 0 and are excluded from the normal amount
+calculations (percentage normalization, dust checks, leftover redistribution).
+
+**What changed:**
+
+- `bal/core/heirs.py`
+  - `validate_heir`: new `OP_RETURN:<hex>` address validation (rejects non-hex,
+    > 80 bytes). OP_RETURN heirs are stored with amount `"0"` and carry the raw
+    hex data in the address field.
+  - `prepare_lists`: OP_RETURN heirs are skipped during amount calculation
+    (`normalize_perc`, dust checks). They are kept in the will but produce a
+    zero-value output.
+  - `buildTransactions`: when building the transaction, OP_RETURN heirs emit a
+    `OP_RETURN <hex>` scriptPubKey output with value 0, matching Bitcoin's
+    OP_RETURN output standard.
+  - `get_transactions`: OP_RETURN heirs are grouped with their locktime peers
+    but excluded from fee/dust arithmetic.
+
+- `bal/gui/qt/window.py`
+  - Heir dialog / wizard: the address field accepts `OP_RETURN:` prefix and
+    shows a decoded-text message field when an OP_RETURN address is entered.
+  - `build_will` / `_build_success_report`: OP_RETURN heirs display the
+    decoded message text in the build report instead of a BTC address.
+
+- `bal/gui/qt/lists.py`
+  - Heir list: OP_RETURN heirs display the decoded message in the address
+    column and show "0" for the amount.
+
+- `bal/gui/qt/common.py`
+  - Re-export the new `validate_op_return_hex` helper for the GUI layer.
+
+- `tests/test_core_heirs.py`
+  - 8 new tests: OP_RETURN validation (valid hex, too long, non-hex), OP_RETURN
+    heirs excluded from amount calculations, OP_RETURN output shape in built
+    transactions, mixed OP_RETURN + regular heirs.
+
+**Verification:**
+- `ruff check` on changed production files: no new errors.
+- Full test suite: 307 passed.
+
+**Outcome:** DONE.
+
+---
+
+## 50. Core extraction: GUI-free logic into bal/core/ (reminders, checkalive, input_rules); RLock pickle fix
+
+**Date:** 2026-08-05
+
+**Goal:** extract GUI-free business logic that was previously embedded in Qt
+widgets (`bal/gui/qt/widgets.py`) into standalone `bal/core/` modules, making
+them independently testable without Qt. Also fix a critical `copy.deepcopy(tx)`
+crash on Electrum 4.8 (`RLock` cannot be pickled) and improve wallet-DB
+persistence robustness.
+
+**What changed:**
+
+- `bal/core/checkalive.py` (new)
+  - `resolve_date_to_check`: computes the effective check-alive timestamp from
+    will-settings and user type (BASIC uses `now()`; ADVANCED uses the stored
+    threshold). Extracted from `window.py init_class_variables`.
+  - `check_alive_expired`: pure-logic test for whether the check-alive has
+    passed. Previously duplicated inline in `window.py`.
+
+- `bal/core/reminders.py` (new)
+  - `compute_reminder_offsets`, `basic_reminder_offsets`, `BALCalendar.write_ics`,
+    `BALCalendar._ics_provider`: all calendar/reminder logic extracted from
+    `widgets.py`. Generates iCal (.ics) files with separate VEVENT entries per
+    reminder date. No Qt dependency.
+
+- `bal/core/input_rules.py` (new)
+  - `LockTimeRawEdit`, `LockTimeDateEdit`, `BalTimeEditWidget`,
+    `ThresholdTimeWidget`: GUI-free data models for locktime/threshold
+    validation and the Raw/Date selector logic. The Qt widgets in
+    `widgets.py` now thin-wrap these helpers.
+
+- `bal/core/heirs.py`
+  - Fixed `copy.deepcopy(tx)` failure on Electrum 4.8: the `Transaction`
+    object contains a `_thread.RLock` that cannot be pickled. Will-item
+    persistence now re-parses the transaction from its hex serialization
+    instead of deep-copying.
+  - Invalid heirs (sentinel values from failed builds) are now kept in the
+    wallet DB instead of being silently dropped, so the user can see and
+    correct them.
+
+- `bal/core/plugin_base.py`
+  - Minor adjustments to support the extracted modules.
+
+- `bal/gui/qt/widgets.py`
+  - Major slim-down: business logic delegates to `bal/core/checkalive.py`,
+    `bal/core/reminders.py`, and `bal/core/input_rules.py`. Only Qt widget
+    creation and layout remain.
+
+- `bal/gui/qt/calendar.py`
+  - Adapted to use `bal/core/reminders.py` for .ics generation.
+
+- `bal/gui/qt/window.py`
+  - `init_class_variables` now calls `resolve_date_to_check` from
+    `bal/core/checkalive.py` instead of computing inline.
+
+- `bal/gui/qt/common.py`
+  - Updated re-exports for the new core modules.
+
+- Tests reorganized: core-only tests moved to `tests/test_core_checkalive.py`,
+  `tests/test_core_reminders.py`, `tests/test_core_input_rules.py` (run
+  without Qt).
+
+- `tests/karen7`: fixture file compressed/updated for the new test structure.
+
+**Verification:**
+- `ruff check` on changed files: no new errors.
+- Full test suite: 388 passed (significant increase due to new core test modules).
+
+**Outcome:** DONE.
+
+---
+
+## 51. "Rebuild will on wallet close" setting (`REBUILD_ON_CLOSE`)
+
+**Date:** 2026-08-14
+
+**Goal:** add a new plugin setting that lets the plugin rebuild the will
+automatically when Electrum closes, skipping the full Build wizard. When
+enabled, closing Electrum triggers a one-shot prepare/inheritance flow
+(check, rebuild if needed, sign, broadcast) without showing the
+`BalBuildWillDialog`.
+
+**What changed:**
+
+- `bal/core/plugin_base.py`
+  - New persisted config `REBUILD_ON_CLOSE = BalConfig(config,
+    "bal_rebuild_on_close", False)` (default OFF), with explanatory comment.
+
+- `bal/gui/qt/plugin.py`
+  - New "Rebuild on close" checkbox in the settings dialog, bound to
+    `REBUILD_ON_CLOSE`, with a tooltip explaining the behaviour. Added to the
+    "Reset to Default Setting" list.
+
+- `bal/gui/qt/window.py`
+  - `on_close`: when `REBUILD_ON_CLOSE` is enabled, the close flow runs
+    the auto-rebuild path (check + rebuild + sign + push) instead of the
+    full wizard dialog. The legacy wizard-on-close path is kept when the
+    setting is OFF.
+
+- `tests/test_rebuild_on_close_setting.py` (new)
+  - 8 tests: default OFF, toggle/persist, close triggers rebuild when ON,
+    close skips rebuild when OFF, reset restores default.
+
+**Verification:**
+- `ruff check` on changed files: no new errors.
+- Full test suite: 396 passed.
+
+**Outcome:** DONE.
+
+---
+
+## 52. Headless CLI layer (`bal/cli/`, `bal/cmdline.py`, `bal_*` daemon commands)
+
+**Date:** 2026-08-14
+
+**Goal:** expose the full BAL inheritance cycle via Electrum's command-line
+interface (daemon mode), without the Qt GUI. This enables scripting,
+automation, and headless server usage.
+
+**What changed:**
+
+- `bal/cmdline.py` (new)
+  - Zip-import shim for Electrum's `gui_name='cmdline'` plugin loader.
+  - Follows the same `importlib` pattern as `qt.py` but never imports Qt.
+  - Re-exports `Plugin` from `bal.cli.plugin`.
+
+- `bal/cli/__init__.py` (new)
+  - Registers the `bal_*` commands with Electrum on import.
+
+- `bal/cli/plugin.py` (new)
+  - `Plugin(BalPlugin)` -- minimal entry point for the daemon (no Qt hooks,
+    no `bal_windows`).
+
+- `bal/cli/commands.py` (new)
+  - 30 `@plugin_command` async functions registered as `bal_*` commands:
+    settings (list/get/set/reset), heirs (list/show/add/update/delete/import/
+    export), will-executors (list/show/add/update/select/delete/ping/download/
+    import/export), will (status/check/prepare/sign/broadcast/export/
+    import_merge/invalidate/check_executor).
+  - Each command is a thin transport layer: validates args, delegates to
+    `BalController`, returns JSON-serializable results.
+
+- `bal/cli/controller.py` (new, ~1100 lines)
+  - `BalController` -- headless replica of `BalWindow`. Reads/writes wallet DB,
+    config, and will-executors without any Qt dependency.
+  - Methods mirror `BalWindow` flows: `load_willitems`, `save_willitems`,
+    `init_class_variables`, `build_inheritance_transaction`, `sign_transactions`,
+    `push_transactions_to_willexecutors`, `check_transactions`, `export_json_file`,
+    `merge_will_from_file`, `invalidate_will`.
+  - Domain exceptions (`WillExpiredException`, `HeirNotFoundException`, etc.)
+    are converted to `UserFacingException` with clear text.
+
+- `bal/manifest.json`
+  - `"available_for"` updated from `["qt"]` to `["qt", "cmdline"]`.
+
+- `bal/__init__.py`
+  - Added `from .cli import commands` to register `bal_*` commands on import
+    (both CLI pre-parse and GUI startup).
+
+- `tests/test_cli_commands_registered.py` (new)
+  - 4 tests: all `bal_*` commands registered, all are coroutines, no duplicate
+    registration, all args documented.
+
+- `tests/test_cli_controller_offline.py` (new)
+  - Offline CRUD tests for heirs, will-executors, settings, and will
+    import/export merge via `BalController` (no network).
+
+**Verification:**
+- `ruff check` on new files: clean.
+- Full test suite: 427 passed.
+- `tests/test_cli_commands_registered.py`: all 4 tests pass.
+
+**Outcome:** DONE.
+
+---
+
+## 53. Auto-rebuild on new transactions (`AUTO_REBUILD`)
+
+**Date:** 2026-08-16
+
+**Goal:** when new transactions are detected in the wallet (e.g. incoming
+payments), automatically rebuild the will so the inheritance covers the
+new UTXOs. The delivery date is anticipated by one day to orphan the old
+will on-chain; an on-chain invalidation is only needed when the anticipated
+locktime crosses the Check Alive threshold.
+
+**What changed:**
+
+- `bal/core/plugin_base.py`
+  - New persisted config `AUTO_REBUILD = BalConfig(config,
+    "bal_auto_rebuild", False)` (default OFF), with explanatory comment.
+
+- `bal/gui/qt/plugin.py`
+  - New "Auto-rebuild" checkbox in the settings dialog, bound to
+    `AUTO_REBUILD`, with a tooltip. Added to the "Reset to Default Setting"
+    list.
+
+- `bal/gui/qt/window.py`
+  - New `_auto_rebuild_on_new_tx()` method: triggered when Electrum detects
+    a new transaction in the wallet. Runs the full prepare flow: check
+    coherence, rebuild with the anticipated locktime (delivery date minus 1
+    day), persist, sign (if passwordless), push to will-executors.
+  - When the anticipated locktime crosses the Check Alive threshold, returns
+    an invalidation transaction instead of auto-completing.
+  - Connected to Electrum's `new_transaction` signal.
+
+- `tests/test_auto_rebuild_on_new_tx.py` (new)
+  - 16 tests: AUTO_REBUILD default OFF, toggle/persist, rebuild triggers on
+    new tx, locktime anticipation by 1 day, threshold crossing returns
+    invalidation, passwordless wallet signs automatically, encrypted wallet
+    returns invalidation tx for manual signing.
+
+**Verification:**
+- `ruff check` on changed files: no new errors.
+- Full test suite: 432 passed.
+
+**Outcome:** DONE.
+
+---
+
+## 54. CLI `bal_will_autorebuild` command
+
+**Date:** 2026-08-16
+
+**Goal:** expose the auto-rebuild flow (entry #53) as a headless CLI command,
+so scripts and daemons can trigger the one-shot check/rebuild/sign/push
+cycle without the Qt GUI.
+
+**What changed:**
+
+- `bal/cli/commands.py`
+  - New `bal_will_autorebuild` async command (flag `nw`): runs the full
+    auto-rebuild flow via `BalController.auto_rebuild()`. Returns a JSON
+    object with `result` (`valid`, `no_heirs`, `invalidated`, `nothing`,
+    `needs_signing`, `rebuilt`) and, when applicable, the invalidation
+    transaction.
+
+- `bal/cli/controller.py`
+  - New `auto_rebuild()` method: headless replica of the GUI auto-rebuild
+    flow. Checks coherence, rebuilds with anticipated locktime, handles
+    threshold-crossing (returns invalidation tx), signs passwordless wallets
+    automatically, pushes to will-executors.
+
+- `tests/test_cli_autorebuild.py` (new)
+  - 10 tests: auto-rebuild returns `valid` when will is coherent, `rebuilt`
+    when rebuilt, `invalidated` with invalidation tx when threshold crossed,
+    `needs_signing` for encrypted wallets, `no_heirs` when heirs are missing.
+
+- `tests/test_cli_commands_registered.py`
+  - Updated `EXPECTED_COMMANDS` to include `bal_will_autorebuild`.
+
+- `tests/test_cli_controller_offline.py`
+  - Extended with auto-rebuild flow tests.
+
+**Verification:**
+- `ruff check` on changed files: no new errors.
+- Full test suite: 438 passed.
+
+**Outcome:** DONE.
+
+---
+
+## 55. Remove "Add transaction without willexecutor" from settings dialog
+
+**Date:** 2026-08-17
+
+**Goal (owner request):** the "Add transaction without willexecutor" checkbox
+was already available in the Will-Executor tab; showing it redundantly in the
+settings dialog created confusion. Remove it from the settings dialog and
+renumber the grid rows.
+
+**What changed:**
+
+- `bal/gui/qt/plugin.py`
+  - Removed the "Add transaction without willexecutor" checkbox
+    (`NO_WILLEXECUTOR`) from the settings dialog grid. The setting is still
+    functional (available from the Will-Executor tab and the wizard); only
+    the settings-dialog exposure was removed.
+  - Grid rows 5--16 renumbered to 4--15 to close the gap left by the removal.
+  - Removed the corresponding reset-button widget for `NO_WILLEXECUTOR` from
+    the "Reset to Default Setting" list.
+
+**Verification:**
+- `ruff check` on changed file: no new errors.
+- Full test suite: 438 passed (unchanged).
+
+**Outcome:** DONE.
+
+## 56. QR / audio will transfer (chunked multi-QR export/import + review-and-sign wizard)
+
+**Date:** 2026-08-27
+
+**Goal (owner request):** export a will to another device via QR codes (with
+an optional audio channel on top), and import it there with a per-transaction
+review-and-sign flow. QR codes are chunked because a full will usually exceeds
+a single code's capacity.
+
+**What changed:**
+
+- `bal/core/qrtransfer.py` (new, GUI-free): the wire format and chunk
+  scheduler — `BALQR{version}|{total}|{index}|{flags}|{payload}` frames,
+  `encode_transfer` / `decode_transfer`, `split_frames` / `parse_frame` /
+  `assemble`, optional `Z` (zlib+base64) compression at export, four chunk
+  presets (150/400/900/1800 bytes/frame, EC level M), plus
+  `preset_index_for_chunk_size` and the `QrTransferError` exception family.
+- `tests/test_core_qr_transfer.py` (new): round-trips (plain/compressed),
+  boundaries (exact-fit, size>payload, `|` in payload), min-size guard, bad
+  magic/version/numbers/flags, multi-frame reassembly, header consistency.
+- `bal/core/plugin_base.py`: new `QR_CHUNK_SIZE` config (default 150).
+- `bal/gui/qt/plugin.py`: settings-dialog row 16 "QR Code Size" combo
+  (4 presets) + reset button, visible in BASIC and ADVANCED.
+- `bal/gui/qt/dialogs.py`:
+  - `BalQrImage`: QR widget with MEDIUM error correction (Electrum's
+    `QRCodeWidget` is EC-L), reusing `draw_qr`.
+  - `WillQrExportDialog`: walks the frames (Prev/Next, "i of N" progress),
+    export filters **All / Valid / Valid-NC**, live chunk-preset selector,
+    **Auto slideshow** (toggle button + "QR codes per second" spinbox, stops on
+    the last frame and on filter/chunk changes), optional audio-send button.
+  - `WillQrImportDialog`: camera scan (Electrum `scan_qrcode_from_camera`,
+    one code at a time), manual paste fallback, slot grid (1..N) with
+    green=stored, total-mismatch reset, optional audio-receive that mirrors
+    the audio_modem `_recv` sink with a callback instead of `setText`.
+  - `WillTxReviewSignDialog`: per-transaction review (outputs via
+    `get_ui_address_str`, total outputs, fee) with Sign / Skip / Cancel and a
+    single wallet password; final page offers "Save signed file…" and
+    "Show signed QR…". Runs on the imported local copy only.
+- `bal/gui/qt/window.py`: `export_will_via_qr`, `import_will_via_qr`,
+  `get_audio_modem_plugin`, `_audio_send_payload`; `sign_transactions`
+  refactored into a byte-equivalent batch loop plus the reusable
+  `_prepare_and_sign_tx(…, txid, password)` single-transaction helper.
+- `bal/gui/qt/lists.py`: will-list menu gains **Export → QR Codes** and
+  **Import via QR**.
+- `tests/test_gui_qr_transfer.py` (new): export build/navigation/chunk
+  change, filters (Valid, Valid-NC, empty-revert), import frame flow,
+  assembly+decode, total-mismatch reset, manual entry.
+- `PLAN_QR_TRANSFER.md`: the full spec (wire format, settings, export,
+  import, wizard checklist P0–P6, findings log).
+- Docs: `README.md` QR-transfer section; `QML_PLAN.md` updated (Phase 2
+  `BalQrTransferModel`, Phase 3 dedicated QML export/import pages, R6
+  mitigation rewritten, deferred-chunks note removed).
+
+**Audio channel caveats:**
+- The audio send/receive buttons only appear when Electrum's `audio_modem`
+  plugin is enabled *and* `amodem` + PortAudio are installed (not present in
+  the current dev runtime — verified F22). On that channel the transport
+  zlib-compresses internally, so no BAL framing/`Z` flag is used.
+- `WaitingDialog` requires a real `QWidget` parent and the plugin's `_recv`
+  hard-wires `parent.setText`, so receive uses a local mirror with a
+  callback sink.
+
+**Verification:**
+- `python3 tests/test_core_qr_transfer.py`: all pass.
+- `QT_QPA_PLATFORM=offscreen python3 tests/test_gui_qr_transfer.py`: all pass.
+- Pytest batch `tests/test_core_*.py tests/test_gui_*.py`: 374 passed (only
+  the two pre-existing `test_bt_to_date_*` datetime compare failures remain).
+- `QT_QPA_PLATFORM=offscreen python3 tests/smoke_test.py
+  electrum.plugins.bal`: passed (clean import under real Electrum).
+- `ruff`: no new violations on changed files.
+
+**Audio-environment notes (dev box, discovered while testing):**
+- `amodem` 1.16.0 is old and uses `np.ndarray.tostring()`, removed in numpy 2.x;
+  the runtime venv (numpy 2.4.6) needs the one-line patch
+  `tostring()` → `tobytes()` in
+  `electrum/env/lib/python3.11/site-packages/amodem/common.py` (done locally,
+  not in the repo). Any machine with numpy>=2 and this amodem version needs
+  the same patch (or numpy<2).
+- Electrum's `audio_modem` plugin hardcodes `libportaudio.so` (unversioned).
+  Debian/Ubuntu only ship `libportaudio.so.2`, so the load fails silently
+  inside the plugin's `_send` `WaitingDialog` (no `on_error` → no sound, no
+  message). Fix on the dev box:
+  `sudo ln -s /usr/lib/x86_64-linux-gnu/libportaudio.so.2 /usr/lib/x86_64-linux-gnu/libportaudio.so`
+  (created by the `libportaudio-dev` package; a `LD_LIBRARY_PATH` stub works
+  without root). The audio buttons stay hidden unless the plugin is enabled
+  and available.
+- Verified on the dev box (no physical mic required) via a full
+  send→sink→monitor→recv round-trip: set the default PulseAudio source to
+  `<sink>.monitor` at receive time; payload returned byte-identical.
+
+**Follow-up fixes (same session, reported during audio testing):**
+- `WillItem.__init__` now defaults `status` to `""` instead of `None`. A
+  `WillItem` built from a bare `{"tx": ...}` (QR/audio import, clipboard
+  merge) crashed in `set_status` with
+  `unsupported operand type(s) for +=: 'NoneType' and 'str'` during the
+  validity pass / `IMPORTED` marking.
+- `BalWindow.invalidate_will` guards a missing `date_to_check` (first-action
+  case) like `merge_will` already did, fixing
+  `AttributeError: 'BalWindow' object has no attribute 'date_to_check'` when
+  invalidating before the periodic check initialized it.
+- Regression test `test_imported_item_status_not_none` added to
+  `tests/test_gui_qr_transfer.py`; QR GUI suite 12/12, batch 377 passed.
+---
+
+## 57. Name the real cause of a failed build instead of guessing
+
+**Date:** 2026-09-04
+
+**Goal (owner request):** the "Building Will" report was hard to read and often
+misleading.
+
+1. The long "could not build the will" block was printed entirely in amber
+   (`COLOR_WARNING`), which the owner reported as barely legible.
+2. Whenever the build produced nothing, the dialog printed a FIXED list of
+   three "possible reasons" (low balance / dust shares / check-alive later than
+   the delivery date) regardless of what had actually happened. In a case
+   reproduced from the owner's log all three were false, and the real cause
+   (no delivery date left to build) was not even in the list.
+3. The "Checking your will" row had the same problem: the single sentence
+   "Found CHANGES to the DATE or the HEIRS" was shown for five different
+   situations, including one where it is plainly wrong - funds received, where
+   neither the date nor the heirs changed.
+
+**What changed:**
+
+- `bal/core/heirs.py`
+  - `Heirs.__init__` / `buildTransactions`: new `last_build_error` attribute
+    recording WHY a build produced no transaction. Reset at the start of every
+    build, and set at each path that previously returned empty with no
+    explanation at all: `NO_HEIRS`, `NO_UTXO`, `NO_WILLEXECUTOR_USABLE`,
+    `NO_FUTURE_DATE`, `WILLEXECUTOR_FEE`, `WILLEXECUTOR_FEE_TOO_HIGH`,
+    `TX_BUILD_FAILED`, `WILLEXECUTOR_TX_ERROR`.
+  - Added a `processed_willexecutors` counter so that "the loop skipped every
+    will-executor" - which returned silently, with no log line whatsoever - is
+    told apart from "we tried and the build failed".
+  - Fixed a latent crash in the `prepare_transactions` exception handler. It
+    read `e.heirname` in order to auto-deselect the offending will-executor,
+    but NOTHING in the plugin sets that attribute any more (leftover from an
+    older exception design), so the lookup itself raised AttributeError and the
+    inner `except Exception: raise` re-raised THAT, aborting the whole build
+    with a confusing secondary error instead of the real one. The handler now
+    records `WILLEXECUTOR_TX_ERROR`, logs the actual exception together with
+    the will-executor it happened on, and moves on to the next one - which is
+    what the original code was clearly trying to do.
+
+- `bal/gui/qt/dialogs.py`
+  - New `msg_alert()`: an amber warning sign (U+26A0, written as a numeric HTML
+    entity so the source stays ASCII) followed by text in the theme's default
+    colour. Colour is what ATTRACTS attention, not what is read, so it is kept
+    on the sign alone; the message body stays readable and still works under
+    the dark theme, where a hard-coded black would disappear.
+  - New `_build_failure_message()`: maps `last_build_error` to ONE specific
+    sentence. When the code is missing or unrecognised it SAYS the cause could
+    not be determined and lists what to check, instead of asserting three
+    guesses as if they were the only possibilities.
+  - New `_check_failure_message()`: replaces the single "Found CHANGES to the
+    DATE or the HEIRS" line with seven precise messages, reusing the detail the
+    exceptions already carry (heir name, will-executor URL, old and new fee
+    rate). The two plain `NotCompleteWillException` cases are told apart
+    STRUCTURALLY (raised with no argument vs. with one), not by matching
+    message text, which would be fragile. No new exception classes were added
+    (owner request).
+  - Added a dedicated `except BalanceTooLowException` handler. The exception
+    already carried the balance, the fees and the dust threshold, but was
+    falling through to the generic handler, which printed the raw technical
+    string in red and re-raised. It now shows the real figures.
+  - "Checking variables" row: `No Heirs` now uses `msg_alert()`. The
+    "Check Alive Threshold Passed" message deliberately STAYS red
+    (`COLOR_ERROR`) because it is the more urgent situation (owner request).
+
+- `bal/gui/qt/common.py`
+  - Re-export `BalanceTooLowException` from `core.heirs` so the Qt layer can
+    catch it.
+
+**Verification:**
+- `py_compile` clean on all 44 files of the package.
+- The real `msg_alert`, `_build_failure_message` and `_check_failure_message`
+  were extracted from the source via AST and executed against every reason code
+  and every exception type, with the exception hierarchy rebuilt from
+  `will.py`: 9 build cases and 8 check cases all produce the intended text.
+- NOT RUN: the official test suite. The machine used for this task (Windows)
+  has no importable `electrum` module, so `tests/` could not be executed.
+- Manually tested by the owner in Electrum 4.8.1: `NO_FUTURE_DATE`,
+  `WILLEXECUTOR_FEE` and `No Heirs` were all confirmed on screen.
+
+## 57. Remove all `copy.deepcopy` (ad-hoc copy helpers; `WillItem` copies serialize/deserialize)
+
+**Date:** 2026-08-28
+
+**Goal (owner request):** eliminate every `copy.deepcopy` from the codebase
+and replace it with ad-hoc copy methods; `WillItem` copies must be produced by
+serializing and deserializing the item rather than by deep-copying live
+runtime objects (which can hold a `threading.RLock` and cannot be pickled).
+
+**What changed:**
+
+- `bal/core/util.py`: new `copy_structure(value, _path="copy")` — the single
+  JSON-safe, deepcopy-free recursive cloner (dict / list / tuple cloned
+  structurally, JSON scalars kept as-is, any accidental runtime object coerced
+  to `str` + logged). It replaces the old `heirs._json_safe` implementation.
+- `bal/core/heirs.py`: `_json_safe` is now a thin backward-compatible alias of
+  `bal.core.util.copy_structure`; `Heirs.save` behaviour is unchanged.
+- `bal/core/will.py`:
+  - `WillItem.__init__` on a `WillItem` argument no longer does
+    `self.__dict__ = w.__dict__.copy()` + `copy.deepcopy`; instead it
+    serializes (`to_dict()`) and deserializes: the tx is re-parsed into a fresh
+    object, `STATUS` is rebuilt from a clone, and heirs / will-executors are
+    cloned recursively, so the copy shares no mutable state with the source.
+  - New `WillItem.copy(wallet=None)` (serialize/deserialize round trip; re-adds
+    wallet tx info when a wallet is passed) and the static
+    `WillItem.copy_status_table(table)` used for the `STATUS` tables.
+  - `to_dict()` now also emits `Father` / `Children` so the round trip is
+    faithful.
+  - `normalize_will` routes copies through the constructor / `copy()`.
+- `bal/gui/qt/window.py` and `bal/cli/controller.py`: the Build-will flow now
+  uses `copy_structure(...)` instead of `copy.deepcopy(...)` for heirs and
+  will-executors.
+- Dropped now-unused `import copy` (`will.py`, `controller.py`, `qt/common.py`,
+  `qt/window.py`).
+- Tests updated to the same helpers: STATUS tables via
+  `WillItem.copy_status_table`, heirs / built dicts via `copy_structure`
+  (`test_core_will.py`, `test_core_will_invalidate.py`,
+  `test_heir_relative_anchor.py`, `test_anticipate_manual_locktime.py`,
+  `test_no_willexecutor_karen7.py`, `test_reproduce_none_type.py`,
+  `test_group_e_mock_karen7.py`, `test_group_e_karen7_invalidate.py`,
+  `sim_update_flows.py`).
+
+**Verification:**
+- Full offline batch `tests/test_core_*.py tests/test_gui_*.py`: 377 passed,
+  only the two pre-existing `test_bt_to_date_*` datetime compare failures
+  remain (identical to HEAD — no regression; `test_heir_relative_anchor`
+  isolated-file failure is pre-existing test-pollution at HEAD too).
+- Ad-hoc semantics check: `copy()`/ctor copy share no mutable state with the
+  source (mutating source heirs/STATUS does not leak into the copy and vice
+  versa), `copy_status_table` returns fresh lists, `normalize_will` runs.
+- `ruff` on all touched files: no new violations (4 findings, all pre-existing
+  at HEAD).
+- `tests/smoke_test.py electrum.plugins.bal`: passed.
+- `python3 build_zip.py`: 45 files, 343591 bytes, sha256 `aa8f8154…`;
+  `tests/external_zip_test.py bal-electrum-plugin.zip`: passed (Plugin class
+  loads via the zipimport shim).
+
+**Outcome:** DONE.
+
+---
+
+## Next. Animated-QR interop (BC-UR v1/v2, BBQR)
+
+**Date:** 2026-09-08
+
+**Goal:** Let BAL export/import a will not only as its own BAL QR frame format
+but also as BC-UR v1 (`ur:bytes`, BC32 + SHA-256), BC-UR v2 (`ur:bytes`, CBOR
+bytewords-minimal fountain codes) and BBQR (Coinkite `B$…`) animated-QR
+sequences, so transfers interoperate with Blockchain Commons / Coldcard-style
+tools and BitKit. Codecs must be stdlib-only and the export must keep BAL QR
+as the default.
+
+**What changed:**
+
+- `bal/core/animated_qr.py` (new): stdlib-only codec module.
+  - BC32 (bech32_bis checksum, XOR `0x3FFFFFFF`) encode/decode matching the
+    BCR-2020-004/005 reference vectors.
+  - bytewords-minimal encode/decode (BCR-2020-012) with CRC-32 rejection;
+    the word list was transcribed verbatim from the reference C++.
+  - BC-UR v2: CBOR part writer/reader, CRC-32, `choose_fragments`
+    (xoshiro256** + alias + ary-threshold sampler) and XOR-based fountain
+    mixing/solving; emits a redundant mixed wave for loss tolerance.
+  - BC-UR v1: multipart with SHA-256 digest and single-part digest-less
+    frames; `1of1` handling.
+  - BBQR: base32 (encoding `2`), hex (uppercase, `H`) and zlib (lowercase,
+    `Z`, automatic compression fallback) frames; out-of-order reconstruction.
+  - One `AnimatedQrSession` + `detect_format` + `parse_for_detection` for
+    auto-detecting the incoming format and keying the GUI debounce.
+  - Safety caps: `_MAX_SESSION_PARTS = 20000`, `_MAX_MESSAGE_BYTES = 32 MB`,
+    zlib-bomb guard, `TransferConflictError`/`SessionLimitError`.
+- `bal/gui/qt/dialogs.py`:
+  - Export page (`BalQrExportWidget`) gained a **Format** selector
+    (BAL QR default, BC-UR v1, BC-UR v2, BBQR) reusing the QR-size presets,
+    with per-format intro/format-hint text.
+  - Import page (`BalQrImportWidget`) now routes every frame through
+    `parse_for_detection` + `AnimatedQrSession.add_part`, auto-detecting the
+    format and resetting when the transfer's session key changes; the
+    review/sign step resolves the session and decodes parts uniformly.
+  - `qr_import_accept_frame` generalised to
+    `(state, fmt, session_key, frame_total, index, payload, stable_reads=2)`.
+- `tests/test_core_animated_qr.py` (new, 32 tests): BC32 spec vectors,
+  bytewords round-trip/CRC, C++ reference-frame decode+re-encode parity
+  (single-part 12B, seq_len=2, seq_len=7), fountain solve with missing pure
+  part, out-of-order/duplicate handling, single/multipart UR v1, BBQR
+  Z/2/H round-trips, runt last part, zlib-bomb guard, detection positive/
+  negative.
+
+**Verification:**
+
+- `tests/test_core_animated_qr.py`: 32/32 pass.
+- `tests/test_gui_qr_transfer.py` (now 36 tests) + `test_gui_export_dialogs.py`: pass.
+- `ruff` clean on `animated_qr.py`, `dialogs.py` and both test files;
+  `pyright` 0 errors on the touched modules.
+- `tests/smoke_test.py electrum.plugins.bal`, `python3 build_zip.py` and
+  `external_zip_test.py` all pass.
+- Full regression: 462 passed; only pre-existing failures remain
+  (`test_bt_to_date_*`, will-invalidate fee, unrelated `sign_transactions`
+  stub test).
+
+**Notes / caveats:**
+
+- A real bug was found & fixed during this work: `_ur2_part_cost` used
+  `2 * body_len` but `bytewords_minimal_encode` appends a 4-byte CRC, so every
+  UR v2 frame was undercounted by 8 characters and could overflow the QR
+  budget for large transfers.
+- UR v1 multipart emits the digest-carrying `1of1/<digest>/<frag>` form for a
+  single part (both headered and headerless single parts are accepted on
+  import); this keeps deterministic digest verification.
+- Imported payloads are UTF-8 text; the codec sessions do not decode raw
+  binary transfer blobs.
+
+**Outcome:** DONE (uncommitted).
+
+---
+
+## Animated-QR bugfix: QVideoSink signal wiring + will-export JSON crash
+
+**Date:** 2026-09-08
+
+**Goal:** Fix two runtime crashes found by manual testing of the QR paths.
+
+**What changed:**
+
+- `bal/gui/qt/dialogs.py`:
+  - `_start_scan`/`_stop_scan` used `QVideoSink.videoFrame.connect/.disconnect`,
+    but on PyQt6 `videoFrame` is the frame **getter method**, not a signal —
+    this raised ``AttributeError: 'builtin_function_or_method' object has no
+    attribute 'connect'`` on camera scan. Switched to the `videoFrameChanged`
+    signal (same wiring Electrum's `QrReaderVideoSurface` uses).
+  - `_stop_scan` now tolerates `AttributeError` when disconnecting the sink
+    and guards the `errorOccurred` disconnect too, so a mid-init failure can
+    never cascade into a second uncaught exception.
+  - `_whole_will_json` (whole-will QR export) serialized ``WillItem.to_dict()``
+    with plain `json.dumps`, crashing with ``TypeError: Object of type
+    Transaction is not JSON serializable`` (the ``tx`` field holds a real
+    ``Transaction``). Now uses Electrum's `MyEncoder`, matching `write_json_file`.
+- `tests/test_gui_qr_transfer.py`: new `test_import_start_stop_scan_signal_wiring`
+  drives the real `QVideoSink` life-cycle with a mocked camera and fails if
+  the signal name regresses to `videoFrame`.
+- `tests/test_gui_export_dialogs.py`: new
+  `test_qr_whole_will_json_serializes_transaction` covers the JSON export.
+
+**Verification:**
+
+- `pytest tests/test_gui_qr_transfer.py tests/test_gui_export_dialogs.py -q`: pass.
+- Full offline batch `tests/test_core_*.py tests/test_gui_*.py`: 444 passed.
+- Regression test flips correctly (fails when reverted to the buggy call).
+- `ruff` clean on touched files; `tests/smoke_test.py`, `build_zip.py`,
+  `external_zip_test.py` all pass.
+
+**Outcome:** DONE (uncommitted).
+
+---
+
+## Balanced-QR wire format v2: compact header + best-of compression
+
+**Date:** 2026-09-13
+
+**Goal:** Shrink the native BAL QR wire format to its minimum. The old
+pipe-separated header (`BALQR1|total|index|flags|`) wasted 12-14 characters on
+direction marker, separators and decimal count fields, and the export always
+sent uncompressed hex text. New exports should fit a will in the fewest,
+densest frames possible.
+
+**What changed:**
+
+- `bal/core/qrtransfer.py`:
+  - New wire format v2: `BAL1<TTT><iii><F><payload>` — fixed 11-char header,
+    no separators. `BAL1` magic, 3-digit **base36** zero-padded totals/index
+    (values `00A`-`ZZZ`, cap 46655 frames), single flag char.
+  - Flags: `0` = plain payload, `Z` = zlib+base64 compressed payload (the importer
+    already decompressed `Z`; the exporter now produces it).
+  - `encode_transfer_best(tx_strings)` returns the shorter of plain vs
+    compressed; the export widget uses it as the default for BAL QR.
+  - `parse_frame` is dual: old `BALQR1|total|index|flags|payload` frames still
+    import unchanged (backwards-compatible receive).
+  - Frame-count overflow (a transfer needing > 46655 frames) raises
+    `QrTransferError` at encode time instead of emitting corrupt headers.
+- `bal/gui/qt/dialogs.py` (`BalQrExportWidget`): BAL QR export now encodes via
+  `encode_transfer_best`, so plain *or* compressed frames are emitted per
+  transfer; import is untouched (already format-agnostic and flag-driven).
+- `bal/core/animated_qr.py`: `detect_format` accepts `BAL1` in addition to the
+  legacy `BALQR` prefix; wire-format docstring updated.
+- `bal/gui/qt/widgets.py` (`WillWidget`): the will detail view now shows each
+  heir's address (or the decoded UTF-8 text of an `OP_RETURN:` heir) and a
+  dedicated Address row for the will-executor.
+
+**Verification:**
+
+- `tests/test_core_qr_transfer.py` (new v2 tests: header structure, field width,
+  `Z` flag round-trip, best-of selection, malformed `BAL1` frames, 46655 cap and
+  exact boundary): all pass; legacy `BALQR1` parse tests unchanged and green.
+- `tests/test_core_animated_qr.py`: `BAL1` detection + `parse_for_detection`;
+  `tests/test_gui_qr_transfer.py`: format-combo + chunk-navigation updated for
+  the compact export.
+- `pytest tests/test_core_*.py tests/test_import_will_details.py -q`: 345 passed.
+- `ruff` clean on all touched files except the pre-existing `dialogs.py` I001
+  (present on HEAD); `pyright` 0 errors on the codec modules.
+- Android Chaquopy bundle re-synced (`sync_codecs.py` + `verify_chain.py`).
+
+**Notes / caveats:**
+
+- **Compatibility break (forward):** the new default export (compressed
+  `BAL1…`) is NOT readable by older BAL versions — nor by the previously
+  released Android APK — until those are updated to accept `BAL1`. Imports of
+  legacy `BALQR1…` exports keep working on this version. Existing audio
+  transfers are unaffected (they keep explicit `compress=False`, and the audio
+  format was never flag-driven on receive).
+- A typical multi-tx will now ships as a single dense frame instead of two
+  sparse ones: header overhead dropped from 12-14 chars to a constant 11, and
+  the base36 count fields are 3 chars regardless of how many frames exist.
+
+**Outcome:** DONE.

COMPATIBILITY.md

@@ -23,6 +23,25 @@ is updated to mark them as supported.
 See [`README.md`](README.md) for supported Electrum versions (currently 4.7.2
 and 4.8.0).
 
+## QR wire-format compatibility
+
+BAL exports/imports wills as QR codes. **BAL QR** (the default) is the plugin's
+own frame format and is only understood by BAL itself. The export page also
+supports **BC-UR v1**, **BC-UR v2** and **BBQR**:
+
+| Format    | Wire appearance            | Interop target                                       |
+|-----------|----------------------------|------------------------------------------------------|
+| BAL QR    | `BAL1<total><index><flag>…` (v2) / `BALQR1\|total\|index\|…` (legacy import-only) | Past/other BAL versions: **v2 exports are NOT readable by old builds**; old `BALQR1` exports still import here (default, best-of compression, flag `0` = plain, `Z` = deflate) |
+| BC-UR v1  | `ur:bytes/<bc32>`          | Blockchain Commons / Coldcard-style UR (BC32, SHA-256 digest, part counts per part) |
+| BC-UR v2  | `ur:bytes/<seq>-<seqlen>/<bytewords>` | BC-UR 2.x fountain codes (CBOR parts, CRC-32, bytewords-minimal) |
+| BBQR      | `B$<enc><type><N><n>…`     | Coinkite BitKit / Coldcard's BBQR animated-QR mode   |
+
+Import auto-detects the format of each scanned code; out-of-order, duplicate
+and (for UR v2) partially-lost fountain frames are handled. Interop is
+validation-tested against the reference C++ bc-ur encoder output and the
+BCR-2020-004/005 BC32 test vectors; it has not yet been cross-verified against
+third-party libraries (`ur`, `bbqr`, Coldcard firmwares).
+
 ## Reporting compatibility issues
 
 If you find a compatibility problem not listed here, please open an issue on

HANDOFF.md

@@ -58,6 +58,7 @@ bal/                         <- the plugin package (this is what ships in the ZI
   __init__.py                <- package docstring (no version here anymore)
   manifest.json              <- plugin manifest, "version" field (SINGLE SOURCE OF TRUTH for the version)
   qt.py                      <- zipimport shim used when loaded as an external ZIP plugin
+  cmdline.py                 <- CLI entry-point shim (Electrum gui_name='cmdline')
   core/
     plugin_base.py           <- get_version() reads the version from manifest.json (zip-safe)
     heirs.py                 <- HEIRS + transaction building (prepare_lists,
@@ -67,6 +68,14 @@ bal/                         <- the plugin package (this is what ships in the ZI
     willexecutors.py         <- remote will-executor services handling (is_selected / is_valid,
                                 parallel push/check).
     util.py                  <- locktime parsing/most helpers (timestamps only).
+    checkalive.py            <- resolve_date_to_check, check_alive_expired (GUI-free).
+    reminders.py             <- compute_reminder_offsets, BALCalendar .ics generation (GUI-free).
+    input_rules.py           <- locktime/threshold data models, Raw/Date selector logic (GUI-free).
+  cli/                       <- headless command-line layer (no Qt)
+    __init__.py              <- registers bal_* commands on import
+    commands.py              <- bal_* daemon commands (@plugin_command, async, thin transport)
+    controller.py            <- BalController: headless replica of BalWindow (no Qt)
+    plugin.py                <- CLI Plugin entry point (extends BalPlugin, no Qt hooks)
   gui/qt/
     common.py                <- shared imports; every gui module does
                                 `from .common import *`. Add new shared imports HERE.
@@ -80,7 +89,6 @@ bal/                         <- the plugin package (this is what ships in the ZI
   wallet_util/               <- standalone wallet-inspection helpers, no Qt
 tests/                       <- standalone test scripts (see Section 3).
 docs/                        <- user manual + inheritance-options guide (.md sources).
-bal_cli.py                   <- headless CLI (heirs/will build/sign/push/check), no Qt.
 build_zip.py                 <- builds the shippable ZIP (36 files).
 CHANGELOG.md                 <- numbered task log (English).
 .agent_memory_tasks.md       <- terse internal memory notes per task batch.
@@ -103,7 +111,8 @@ Two separate venvs — using the wrong one is the #1 mistake:
 - **Lint venv** (repo-local `venv/`): ruff, black, flake8 only. It cannot
   import `electrum` or `PyQt6`. Do NOT use it to run tests.
 
-Run everything from the repo root.
+Run everything from the repo root (the checkout directory; set
+`BAL_HOME` to its parent to use `$BAL_HOME/electrum`).
 
 **Tests are standalone scripts (not pytest):** each `tests/test_*.py` runs its
 `test_*` functions from `if __name__ == "__main__"`. Run a file directly:
@@ -295,8 +304,8 @@ See Section 5 for details.
   update `GITEA_TOKEN` env var or `~/.git-credentials`, then retry.
 - Older PR history (pre-`main` direct workflow): **#13** (v0.4.7), **#14**
   (docs/DUST section + translation), **#15** (v0.4.8), **#4** (v0.6.1 —
-  manifest.json version). All merged into `main`.
+  manifest.json version); all merged into `main`.
-- Releases: latest is **v0.6.1**; v0.6.0 and v0.5.18 before it; the older
+- Releases: latest is **v0.7.0**; v0.6.1, v0.6.0 and v0.5.18 before it; the older
   v0.2.x line is kept in history.
 
 ---
@@ -346,6 +355,11 @@ See Section 5 for details.
 - **#47 / #48 (post-v0.6.1)** — `is_selected`/`is_valid` fee bounds (extremes
   allowed) and the `merge_will` missing-`date_to_check` crash fix (see
   CHANGELOG).
+- **v0.7.0** — OP_RETURN heirs; core extraction (checkalive, reminders,
+  input_rules); RLock pickle fix; `REBUILD_ON_CLOSE`; headless CLI layer
+  (`bal/cli/`, `bal/cmdline.py`, 30 `bal_*` commands); `AUTO_REBUILD` on new
+  transactions; `bal_will_autorebuild` CLI command; removed redundant
+  "Add transaction without willexecutor" from settings dialog.
 
 ### Open / suspended / backlog items (see `.agent_memory_tasks.md` for detail)
 - **SUSPENDED — "(UTC)" label in the wizard.** The owner asked to show an
@@ -379,3 +393,85 @@ See Section 5 for details.
    push to `origin/main`, then run `./make-release.sh` to create the Gitea
    **Release** with the ZIP + signatures attached (it becomes the owner's
    "Latest" download). Always give the owner the Release URL.
+
+### In progress: QR / audio will transfer (branch `feature/bal-qr-transfer`)
+
+- The full QR-transfer feature (P0–P6) is implemented, tested and committed on
+  `feature/bal-qr-transfer` (commits `d288b55`, `ce3e36d`, pushed to
+  `origin`). PR creation URL:
+  `https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/pulls/new/feature/bal-qr-transfer`
+- Included: core scheduler (`bal/core/qrtransfer.py`), `QR_CHUNK_SIZE`
+  setting (4 export presets), export/import dialogs + review/sign wizard +
+  lists/window wiring, export filters, auto slideshow with per-second rate +
+  loop option, audio send/receive buttons, and the crash fixes
+  (`status` default, `invalidate_will` guard). Docs: README, CHANGELOG entry
+  56, QML_PLAN, `AUDIO_MODEM_DEBIAN.md`.
+- Follow-up refactor (CHANGELOG entry 57): all `copy.deepcopy` removed —
+  `copy_structure()` in `bal/core/util.py`, `WillItem.copy()` / ctor
+  serialize/deserialize, `copy_status_table()`. Working tree clean after the
+  branch's three commits.
+- Verification: batch 377 passed / 2 pre-existing `test_bt_to_date_*`
+  failures; ruff no new violations; smoke + `build_zip.py` +
+  external-zip OK; pyright clean. The isolated
+  `test_heir_relative_anchor.py::test_karen7_frozen_delivery_not_expired`
+  failure is pre-existing test pollution (fails identically on clean HEAD,
+  passes inside the full batch) — not caused by entry 57.
+- Remaining: manual on-device walkthrough of the QR path (and, if wanted,
+  the audio path — buttons only appear when the `audio_modem` plugin +
+  `amodem` are installed; see the prerequisites below).
+
+### In progress: animated-QR interop (BC-UR v1/v2, BBQR)
+
+- `bal/core/animated_qr.py` implements stdlib-only codecs for **BC-UR v1**
+  (BC32 + SHA-256 digest; the bech32_bis checksum variant per
+  BCR-2020-004/005), **BC-UR v2** (CBOR part structure, bytewords-minimal,
+  CRC-32, xoshiro256-based fountain with alias-sampled mixing) and **BBQR**
+  (Coinkite `B$…` base32/hex/zlib frames), plus one shared
+  `AnimatedQrSession` with `detect_format` auto-detection and
+  `parse_for_detection` frame identity for the GUI debounce.
+- Current status as of this session: reference parity, GUI, and tests done;
+  not yet committed.
+  - **BC32/bytewords/codec parity:** BC32 reproduces the BCR-2020-004/005
+    test vectors (`Hello, world`, `Hello world`, the long seed vector);
+    bytewords-minimal round-trips with CRC rejection; UR v2 part encode +
+    decode is byte-exact against the reference C++ bc-ur encoder for a
+    single part, seq_len=2 (12 frames) and seq_len=7 (3 sampled mixes),
+    validating CBOR framing, bytewords, alias+ary-threshold sampling,
+    xoshiro256** and the XOR mix.
+  - **Sessions:** UR v2 single-part (no seq header), out-of-order frames,
+    duplicate drops, solve with a missing pure fragment (a second redundant
+    mixed wave is emitted by `ur2_frames`), UR v1 single-part
+    (digest-less `ur:bytes/<bc32>` accepted) and multipart, BBQR full-frame
+    decode in any order for Z/2/H encodings.
+  - **Safety:** `_MAX_SESSION_PARTS = 20000`, `_MAX_MESSAGE_BYTES = 32 MB`,
+    `TransferConflictError` on a frame from a different transfer,
+    `SessionLimitError`, BBQR zlib-bomb guard, UTF-8 payloads only.
+  - **GUI:** `BalQrExportWidget` gained a Format selector (BAL QR default,
+    BC-UR v1, BC-UR v2, BBQR) reusing the QR-size presets; the importer now
+    routes every frame through `detect_format` +
+    `AnimatedQrSession.add_part` with the shared
+    `qr_import_accept_frame(state, fmt, session_key, frame_total, index,
+    payload, stable_reads=2)` debounce (reset on session-key change).
+    `_review_and_sign` resolves the session to the transfer text and decodes
+    parts uniformly across formats.
+  - **Verification:** `tests/test_core_animated_qr.py` (32 tests incl. the
+    C++-reference parity vectors and BC32 spec vectors) and the extended
+    `tests/test_gui_qr_transfer.py` pass; ruff clean on the new/changed
+    files; pyright 0 errors; smoke test, `build_zip.py` and
+    `external_zip_test.py` green. Only the pre-existing failures remain
+    (`test_bt_to_date_*`, fee-exceeds-balance, karen7 pollution).
+  - **Any remaining work:** manual on-device walkthrough of the QR path with
+    the new formats; optionally validate against third-party libraries
+    (`ur`, `bbqr`) once available; add the docstrings/branch notes already
+    captured in `ag1.md`/`ag2.md` context where needed.
+
+**Dev-box audio prerequisites (audio_modem channel):**
+See `AUDIO_MODEM_DEBIAN.md` — the full Debian setup + verification, with the
+two pitfalls (unversioned `libportaudio.so`, numpy>=2 `tostring` removal):
+- `sudo ln -s /usr/lib/x86_64-linux-gnu/libportaudio.so.2 /usr/lib/x86_64-linux-gnu/libportaudio.so`
+  (the unversioned name the plugin loads; Debian ships only `.so.2`).
+- numpy>=2 patch in `electrum/env/.../amodem/common.py`: `tostring()` →
+  `tobytes()` (already applied locally). Both are runtime-env fixes, not repo
+  changes; see CHANGELOG entry 56.
+- To loop-test on one machine without speakers/mic: during receive,
+  `pactl set-default-source <sink>.monitor` (restore after).

PLAN_CMDLINE_PLUGIN.md

@@ -0,0 +1,415 @@
+# Piano: supporto da riga di comando (CLI) per il plugin BAL
+
+> **Stato**: solo piano. Nessun codice viene modificato finché il piano non viene approvato.
+>
+> **Versione di riferimento**: commit `2221389` (`core: anchor relative locktime/threshold recipes...`), working tree pulito.
+
+---
+
+## 1. Obiettivo
+
+Rendere il plugin **Bitcoin After Life** utilizzabile da riga di comando / daemon
+di Electrum, senza GUI Qt, esponendo comandi per:
+
+1. **Willexecutors** — elenco, aggiunta, modifica, selezione, eliminazione, import/export, ping, download lista.
+2. **Heirs** — elenco, aggiunta, modifica, eliminazione, import/export.
+3. **Impostazioni** — lettura e modifica (`settings set chiave=valore`), reset a default.
+4. **Will** — ciclo di vita completo: visualizza stato, check di coerenza, prepara/ricostruisci, firma, import/merge, esporta, invalida, trasmette ai will-executor, verifica lato will-executor (searchtx).
+
+Il tutto riusando **esclusivamente la logica già presente in `bal/core/`** (che è
+già GUI-free) e senza importare mai PyQt.
+
+---
+
+## 2. Stato attuale (verificato sul codice)
+
+### 2.1 Meccanica di Electrum (4.8.0, checkout `electrum/`)
+
+Ho verificato sul codice reale (`electrum/commands.py`, `electrum/plugin.py`,
+`electrum/daemon.py`, `run_electrum`) i punti che governano i comandi dei plugin:
+
+- **Registrazione comandi**: `@plugin_command(s, plugin_name)` in
+  `electrum/commands.py:2317`. Un comando plugin:
+  - è **sempre** un `async def`;
+  - viene registrato come `bal_<nome_funzione>` su `Commands` (quindi anche nel parser CLI);
+  - **forza il flag `'n'`** (richiede rete/daemon): *tutti* i comandi plugin richiedono un daemon in esecuzione e NON funzionano con `--offline`;
+  - alla chiamata inietta `plugin = daemon._plugins.get_plugin('bal')` (riga 2337).
+- **Pre-parse CLI** (`run_electrum` riga 425): `Plugins(tmp_config, cmd_only=True)` importa solo l'`__init__.py` di ogni plugin abilitato per registrare i comandi nel parser. In modalità `cmd_only` il filtro `available_for` viene **saltato** (`plugin.py:128`), ma serve `config['plugins.bal.enabled'] is True` (`plugin.py:117`).
+- **Daemon** (`daemon.py:626`): `Plugins(self.config, 'cmdline')`. Qui il filtro `available_for` **vale**: il plugin deve dichiarare `"cmdline"`.
+- **Caricamento entry-point** (`plugin.py:622`): il daemon importa `electrum.plugins.bal.<gui_name>` con `gui_name='cmdline'`, quindi serve un modulo `bal/cmdline.py` con una classe `Plugin`.
+- **Iniezione wallet**: il decorator `@command` (righe 170-194) gestisce i flag:
+  - `'w'` → risolve e inietta `wallet` da `daemon.get_wallet(wallet_path)` (il wallet deve essere già caricato con `electrum load_wallet`);
+  - `'p'` → richiede `--password` (o wallet già sbloccato) per le operazioni di firma.
+- **Output**: il valore di ritorno del comando viene stampato come JSON da `run_electrum` (righe 626-630); in modalità daemon gli errori `UserFacingException` vengono stampati con exit code 1.
+
+### 2.2 Il plugin (bal v0.6.1)
+
+- `bal/core/` è già GUI-free e contiene tutta la logica riutilizzabile:
+  - `heirs.py` — `Heirs` (dict persistito in wallet DB, chiave `"heirs"`), validazione (`validate_heir`, `_validate`), `import_file`/`export_file`, `get_transactions`/`buildTransactions`.
+  - `willexecutors.py` — `Willexecutors` (config `bal_willexecutors`, chiave per `chainname`), `get_willexecutors`, `save`, `initialize_willexecutor`, `is_selected`, `is_valid`, `ping_servers_parallel`, `push_transactions_parallel`, `check_transactions_parallel`, `check_transaction`, `download_list`, `get_willexecutors_list_from_json`.
+  - `will.py` — `Will` (statiche) e `WillItem` (stato per-tx: `VALID/COMPLETE/PUSHED/CHECKED/...`), `is_will_valid`, `check_will`, `check_willexecutors_and_heirs`, `invalidate_will`, `normalize_will`, `get_min_locktime`, `get_tx_from_any`, `set_check_willexecutor`, `save_valid_transactions_to_history`.
+  - `plugin_base.py` — `BalPlugin` (tutte le `BalConfig`: chiavi `bal_*`), `BalTimestamp`, `get_version`, registrazione dei dict `heirs`/`will`/`will_settings` nel wallet DB.
+  - `checkalive.py` — `resolve_date_to_check`, `check_alive_expired` (riferimento temporale unico per ogni check).
+  - `util.py` — `Util` (locktime, quantità, confronto tx/heirs, `get_available_utxos`, `fix_will_settings_tx_fees`).
+- `bal/gui/qt/window.py` — `BalWindow` contiene i flussi da **replicare in headless** (non riusabile direttamente perché legato a Qt):
+  - `init_will` (riga 151), `load_willitems`/`save_willitems` (120/129),
+  - `init_class_variables` (618) e `build_will` (397),
+  - `build_inheritance_transaction` (678) → il flusso completo "prepara will",
+  - `sign_transactions` (952), `ask_password_and_sign_transactions` (1084),
+  - `push_transactions_to_willexecutors` (1164), `broadcast_transactions` (1127),
+  - `check_transactions_task`/`check_transactions` (1414/1464),
+  - `export_json_file` (1246), `merge_will` (1264), `merge_will_from_file` (1348), `_load_will_file` (1406),
+  - `invalidate_will` (917).
+- `bal/manifest.json`: `"available_for": ["qt"]`, `"version": "0.6.1"`.
+- `build_zip.py`: cammina ricorsivamente su `bal/` (esclude `__pycache__`, `.pyc`), quindi **includerà automaticamente** i nuovi file di `bal/cli/` e `bal/cmdline.py`.
+
+---
+
+## 3. Architettura proposta
+
+```
+bal/
+  __init__.py        # MODIFICATO: importa ``from .cli import commands`` (registra i comandi)
+  cmdline.py         # NUOVO: shim zip-safe (come qt.py) che ri-espone Plugin da bal.cli.plugin
+  cli/
+    __init__.py      # NUOVO
+    commands.py      # NUOVO: tutti i @plugin_command (async), sottili, delegano al controller
+    controller.py    # NUOVO: BalController — facciata headless per-wallet (replica di BalWindow senza Qt)
+    plugin.py        # NUOVO: class Plugin(BalPlugin) — entry-point per il daemon (gui_name='cmdline')
+  manifest.json      # MODIFICATO: available_for = ["qt", "cmdline"]
+```
+
+Principi:
+
+- **`bal/cli/` non importa mai Qt** (stessa regola di `bal/core/`). Può importare solo `bal.core`, `electrum.*` e stdlib.
+- **`commands.py` = livello di trasporto**: firma `async def bal_x(self, wallet=None, plugin=None, ...)`, valida/parsa argomenti, chiama il controller, ritorna strutture JSON-serializzabili. Zero logica di business.
+- **`controller.py` = il cuore**: replica i passi GUI-free di `BalWindow`, ma con errori espressi come eccezioni (i messaggi GUI `show_message`/`show_error` diventano raise/ritorni), e persiste esplicitamente su wallet DB.
+- **`plugin.py`** è quasi vuoto: eredita `BalPlugin.__init__` e basta (serve solo perché Electrum istanzi `module.Plugin(self, config, name)`).
+- **Nessuna dipendenza nuova** richiesta: `aiohttp`, `dns` e il resto sono già usati da `bal/core`.
+
+### 3.1 Perché i comandi richiedono il daemon
+
+`plugin_command` forza il flag `'n'` in `commands.py:2321-2322`. Conseguenza
+architetturale da documentare chiaramente:
+
+```
+electrum daemon -d                 # avvia il daemon (rete + plugin cmdline)
+electrum load_wallet               # carica/sblocca il wallet
+electrum bal_heirs_list            # i comandi BAL girano contro il daemon
+```
+
+Questa è la stessa limitazione di tutti gli altri plugin con comandi CLI
+(es. `swapserver`, `nwc`). Non è aggirabile senza hackare `plugin_command`, che
+escludiamo dal piano.
+
+---
+
+## 4. Modifiche ai file esistenti
+
+### 4.1 `bal/manifest.json`
+- `"available_for": ["qt", "cmdline"]`.
+
+Nessun cambio di versione necessario per lo sviluppo; la versione si alzerà in
+`make-release.sh` come già avviene.
+
+### 4.2 `bal/__init__.py`
+- Aggiungere in fondo:
+  ```python
+  # Registra i comandi CLI (bal_*) appena Electrum importa il pacchetto,
+  # sia in modalità cmd_only (pre-parse) sia nel daemon.
+  from . import cli  # noqa: F401  (importa bal.cli.commands, che registra i @plugin_command)
+  ```
+  (oppure `from .cli import commands` esplicito).
+- Accortezza: `bal/cli/commands.py` deve essere importabile **senza Qt** e senza
+  effetti collaterali pesanti, perché viene importato anche nel pre-parse CLI e
+  all'avvio della GUI.
+
+### 4.3 `build_zip.py`
+- Nessuna modifica obbligatoria: il walker include già `cli/` e `cmdline.py`.
+- **Opzionale (consigliato)**: aggiungere una stampa di avviso quando l'archivio
+  contiene sia `cmdline.py` che `qt.py`, e verificare che `manifest.json` abbia
+  entrambi i valori in `available_for`.
+
+---
+
+## 5. Nuovi file
+
+### 5.1 `bal/cmdline.py` (shim, ~stesso schema di `qt.py`)
+
+Riproduce il pattern zip-safe di `qt.py` (creazione dei package intermedi in
+`sys.modules`, import via `importlib.import_module`), ma punta a
+`bal.cli.plugin`:
+
+```python
+Plugin = _plugin_module.Plugin
+```
+
+### 5.2 `bal/cli/plugin.py`
+
+```python
+class Plugin(BalPlugin):
+    def __init__(self, parent, config, name):
+        BalPlugin.__init__(self, parent, config, name)
+```
+
+Niente hook Qt, niente `bal_windows`. Il daemon lo istanzia quando
+`get_plugin('bal')` viene chiamato dal wrapper di `plugin_command`.
+
+### 5.3 `bal/cli/controller.py` — `BalController`
+
+Facciata per-wallet che incapsula lo stato e i flussi. Attributi (speculari a
+`BalWindow`):
+- `plugin` (il `BalPlugin`/`Plugin` iniettato),
+- `wallet` (iniettato da Electrum),
+- `will_settings` (da `plugin.WILL_SETTINGS.get()` + `Util.fix_will_settings_tx_fees`),
+- `heirs` (`Heirs(wallet)` validati),
+- `willexecutors` (`Willexecutors.get_willexecutors(plugin)`),
+- `willitems` (da `wallet.db.get_dict("will")` → `WillItem(w, wallet=wallet)`),
+- `date_to_check` (via `resolve_date_to_check`).
+
+Metodi principali (replicano le funzioni Qt, senza dialoghi):
+
+| Metodo | Replica di (`window.py`) | Note |
+|---|---|---|
+| `load_willitems()` | 120 | Costruisce i `WillItem` dal dict `will` del wallet DB. |
+| `save_willitems()` | 129 | `to_dict()` con `tx` serializzato a stringa, `json.dumps` di prova, scrittura su `wallet.db` + `wallet.save_db()`. |
+| `init_class_variables()` | 618 | `date_to_check`, `no_willexecutor`, `willexecutors`, check `check_alive_expired`. |
+| `check_will()` | 473 | `Will.is_will_valid(...)`; le eccezioni di dominio vengono propagate al comando. |
+| `build_inheritance_transaction()` | 678 | Flusso 1/7→2/7 replicato: `Will.check_amounts`, guardie locktime/willexecutor, `check_will()` e rebuild su `NotCompleteWillException`. Le `show_message/show_error` diventano raise (`UserFacingException` con testo chiaro) oppure ritorni `{"status": "postponed", "invalidation": tx}`. |
+| `sign_transactions(password)` | 952 | Firma i `VALID` non completi: fixup input dai willitems padre, `wallet.sign_transaction(tx, password, ignore_warnings=True)`, `set_status("COMPLETE")`, `check_signatures`. |
+| `push_transactions_to_willexecutors(force)` | 1164 | `get_willexecutor_transactions` + `push_transactions_parallel` + gestione "already present" con `check_transaction`. Aggiorna `PUSHED/PUSH_FAIL`. |
+| `check_transactions()` | 1414 | `check_transactions_parallel` + `set_check_willexecutor(res)` per item. |
+| `export_json_file(path)` | 1246 | `write_json_file(path, {wid: wi.to_dict()...})` con `tx` come stringa (formato identico a `_load_will_file`). |
+| `merge_will_from_file(path)` | 1348 | `_load_will_file` + `merge_will` (stessa semantica di `window.py:1264`). |
+| `_load_will_file(path)` | 1406 | `read_json_file` + `tx_from_any` + `WillItem`. |
+| `invalidate_will()` | 917 | `Will.invalidate_will(...)` con `history_label` e `will_locktime`. |
+| `fetch_will_executors_list()` / `ping()` | 1491/1771 | `download_list(old, welist_server)` + `ping_servers_parallel`, poi `Willexecutors.save(plugin, ...)`. |
+| `apply_settings(cfg_name, value)` | — | Mappa il nome chiave all'attributo `BalConfig` del plugin e fa `set(...)`. |
+
+Regole di persistenza (fondamentali):
+- **heirs** → `heirs.save()` (via `__setitem__`/`pop` già implementati) + `wallet.save_db()`.
+- **will** → `save_willitems()` + `wallet.save_db()`.
+- **willexecutors** → `Willexecutors.save(plugin, willexecutors)` (config, non wallet DB).
+- **settings** → `BalConfig.set(...)` (config).
+
+### 5.4 `bal/cli/commands.py` — comandi (tutti `async def` + `@plugin_command`)
+
+Firma standard: `async def bal_x(self, wallet=None, plugin=None, ...)`. Flag:
+- `'n'` — imposto automaticamente da `plugin_command` (rete/daemon).
+- `'w'` — wallet richiesto e iniettato da Electrum.
+- `'p'` — solo per i comandi che firmano (richiede `--password`).
+
+Tutti i comandi costruiscono `controller = BalController(plugin, wallet)` e
+ritornano strutture JSON-serializzabili. Elenco completo al §6.
+
+---
+
+## 6. Tabella comandi
+
+Convenzioni:
+- `<WALLET>`: wallet caricato nel daemon (non serve passarlo; Electrum usa quello
+  configurato o `--wallet`).
+- Output: `list`/`dict` stampati come JSON; exit 0 su successo, 1 su errore.
+- `*` = richiede password (`--password`) se il wallet è cifrato.
+
+### 6.1 Willexecutors
+
+| Comando | Flag | Argomenti | Descrizione / output |
+|---|---|---|---|
+| `bal_willexecutors_list` | `nw` | — | Elenco `{url: {address, base_fee, status, info, selected, last_update, sort}}` per la chain corrente. |
+| `bal_willexecutors_show` | `nw` | `url` | Dettaglio di un singolo will-executor. |
+| `bal_willexecutors_add` | `nw` | `url` `address` `base_fee` | Aggiunge/aggiorna un will-executor (via `initialize_willexecutor`), `selected=false` di default. Ritorna il record. |
+| `bal_willexecutors_update` | `nw` | `url` `[address]` `[base_fee]` `[info]` `[promo_code]` | Modifica i campi indicati e salva. |
+| `bal_willexecutors_select` | `nw` | `url` `value` | `is_selected(we, eval_bool(value))` + salva. |
+| `bal_willexecutors_delete` | `nw` | `url` | Rimuove dalla lista e salva. |
+| `bal_willexecutors_ping` | `nw` | `[url]` | `ping_servers_parallel` (tutti o uno); aggiorna `status/base_fee/address`; salva. Output: risultati per url. |
+| `bal_willexecutors_download` | `nw` | — | `download_list(old, plugin.WELIST_SERVER.get())`; unisce e salva. Output: n. record. |
+| `bal_willexecutors_import` | `nw` | `path` | Legge un JSON `{url: record}` (stesso formato di export), `initialize_willexecutor` per record, salva. |
+| `bal_willexecutors_export` | `nw` | `path` | Scrive `{url: record}` su file JSON. |
+
+### 6.2 Heirs
+
+| Comando | Flag | Argomenti | Descrizione / output |
+|---|---|---|---|
+| `bal_heirs_list` | `nw` | — | `{name: [address, amount, locktime, ...]}` (tutte le colonne `HEIR_*`). |
+| `bal_heirs_show` | `nw` | `name` | Dettaglio di un singolo heir. |
+| `bal_heirs_add` | `nw` | `name` `address` `amount` `locktime` | Valida con `Heirs.validate_heir` (OP_RETURN incluso) e salva. `amount` può essere satoshi o `"50%"`. `locktime` può essere timestamp assoluto o relativo `"30d"`/`"1y"`. |
+| `bal_heirs_update` | `nw` | `name` `[address]` `[amount]` `[locktime]` | Modifica i campi indicati (ri-validazione) e salva. |
+| `bal_heirs_delete` | `nw` | `name` | `heirs.pop(name)` + `save_db()`. |
+| `bal_heirs_import` | `nw` | `path` | `Heirs.import_file(path)` (validazione + merge). |
+| `bal_heirs_export` | `nw` | `path` | `Heirs.export_file(path)`. |
+
+### 6.3 Impostazioni
+
+| Comando | Flag | Argomenti | Descrizione / output |
+|---|---|---|---|
+| `bal_settings_list` | `n` | — | Elenco di tutte le `BalConfig` del plugin: `{chiave: {value, default, name}}` (nome leggibile). |
+| `bal_settings_get` | `n` | `key` | Valore corrente di una chiave (`bal_*`). |
+| `bal_settings_set` | `n` | `key=value` | Scrive il valore (conversione di tipo: bool/int/str/JSON) via `BalConfig.set(...)`. `bal_will_settings` accetta JSON. |
+| `bal_settings_reset` | `n` | `key` | `BalConfig.set(cfg.default)`. |
+
+### 6.4 Will
+
+| Comando | Flag | Argomenti | Descrizione / output |
+|---|---|---|---|
+| `bal_will_status` | `nw` | — | Per ogni `wid` (txid): locktime, `heirsvalue`, executor, flag di stato (`VALID/COMPLETE/PUSHED/CHECKED/CHECK_FAIL/...`), `sigs_have/sigs_required`, `tx_fees`, executor URL. |
+| `bal_will_check` | `nw` | — | `check_will()` (coerenza heirs+executor+fees+locktime, in locale). Ritorna `{"valid": true}` o un errore esplicito (es. `HeirNotFound`, `WillPostponed`, `WillExpired`, `NoHeirs`). |
+| `bal_will_prepare` | `nw` | — | Flusso completo `build_inheritance_transaction`: check → rebuild se non coerente → persiste. Output: riepilogo tx nuova/aggiornata per wid. |
+| `bal_will_sign` | `nwp` | `[txid]` | Firma i `VALID` non completi (o solo `txid`). Aggiorna `COMPLETE` e `sigs_*`; persiste. Output per txid. |
+| `bal_will_broadcast` | `nw` | `[txid]` `force` | `push_transactions_to_willexecutors(force, txids)` parallelo; aggiorna `PUSHED/PUSH_FAIL`. Output: `{url: status}`. |
+| `bal_will_export` | `nw` | `path` | `export_json_file(path)`. |
+| `bal_will_import_merge` | `nw` | `path` | `merge_will_from_file(path)` (stessa semantica GUI: merge psbt/stati, mai perdere una tx viva). |
+| `bal_will_invalidate` | `nw` | — | `Will.invalidate_will(...)`; ritorna la tx di invalidazione (da firmare+trasmettere con i comandi sopra). |
+| `bal_will_check_executor` | `nw` | `[txid]` | Verifica lato will-executor: `check_transactions_parallel` (searchtx) per i `VALID+PUSHED` non `CHECKED`; applica `set_check_willexecutor`. Output: `{wid: {url, checked, ok}}`. |
+
+---
+
+## 7. Flusso dati e persistenza
+
+```
+CLI (electrum bal_*)                    Daemon (Electrum 4.8.0)
+┌───────────────────────┐               ┌──────────────────────────────────────┐
+│ run_electrum          │  RPC           │ Daemon.run_cmdline                   │
+│  pre-parse cmd_only   │ ─────────────► │  plugin_command wrapper              │
+│   -> importa bal      │  jsonrpc       │    inietta plugin + wallet           │
+│  (registra bal_*)     │               │  bal/cli/commands.py                 │
+└───────────────────────┘               │    -> BalController(plugin, wallet)  │
+                                        │      -> bal.core.*                   │
+                                        │      -> wallet.db / config (persist) │
+                                        └──────────────────────────────────────┘
+```
+
+- **Lettura**: `wallet.db.get_dict("will")` (wills), `Heirs(wallet)` (heirs),
+  `plugin.WILLEXECUTORS.get()`/`plugin.WILL_SETTINGS.get()` (config).
+- **Scrittura**: `save_willitems()` → `wallet.db` + `wallet.save_db()`;
+  `heirs.save()`; `Willexecutors.save(...)`; `BalConfig.set(...)`.
+- **Firma**: `wallet.sign_transaction(tx, password, ignore_warnings=True)` —
+  idem GUI, quindi compatibile con multisig e wallet cifrati (password via `--password`).
+- **Rete**: `Network.get_instance()` già usato da `bal/core/willexecutors.py`
+  (i comandi `'n'` garantiscono rete attiva).
+
+---
+
+## 8. Errori, exit code, output
+
+- Ritorno `None` → nessun output; `str` → stampato; `dict`/`list` → `json_encode`.
+- Errori utente: sollevare `electrum.util.UserFacingException(msg)` → in modalità
+  daemon viene stampato `msg` con exit 1.
+- Errori di dominio BAL (`WillExpiredException`, `WillPostponedException`,
+  `HeirNotFoundException`, `NoWillExecutorNotPresent`, `CheckAliveError`,
+  `AmountException`, ...): il controller le converte in `UserFacingException`
+  con testo in chiaro (riuso dei messaggi già presenti, senza HTML/Qt).
+- Convenzione consigliata per comandi che producono più di un risultato:
+  ritornare un `dict` con chiave `"result"`/`"warnings"` quando servono avvisi
+  (es. dopo `prepare` con heirs scartati per dust).
+
+---
+
+## 9. Compatibilità Electrum 4.7.2 / 4.8.0
+
+- `plugin_command`, il wrapper `@command` e `daemon._plugins.get_plugin` esistono
+  in entrambe le versioni (verificati su 4.8.0; usati identici da `swapserver`).
+- Il `BalPlugin` già gestisce il cambio API di registrazione dict
+  (`json_db.register_dict` vs `stored_dict.register_name`): nessun intervento.
+- `available_for: ["cmdline"]` è lo stesso meccanismo di `trustedcoin`
+  (che ha già `cmdline.py` in 4.8.0).
+- **Nessun nuovo import Qt** in `bal/cli/`: verificabile in CI con un check
+  statico su `bal/cli/*.py` e `bal/cmdline.py`.
+
+---
+
+## 10. Build / release
+
+- `python3 build_zip.py` produce `bal-electrum-plugin.zip` con `cli/`, `cmdline.py`
+  e il manifest aggiornato. Lo zip serve sia per la GUI che per il daemon.
+- Il test `external_zip_test.py` andrà esteso (vedi §11) per verificare che il
+  zip, caricato da Electrum, registri anche i comandi `bal_*`.
+- Nessun cambiamento a `make-release.sh` (la versione resta nel manifest).
+
+---
+
+## 11. Piano di test e verifica
+
+### 11.1 Nuovi test standalone (stile repo: `tests/test_*.py` con `if __name__ == "__main__"`)
+
+- `tests/test_cli_commands_registered.py` (runtime env):
+  - importa `electrum.plugins.bal` con `Plugins(config, cmd_only=True)`;
+  - asserisce che `known_commands` contenga tutti i nomi `bal_*` della tabella;
+  - asserisce che ogni funzione sia coroutine e abbia il flag `n`.
+- `tests/test_cli_controller.py` (runtime env, offline, senza rete):
+  - wallet "fake"/temporaneo (pattern di `test_core_heirs.py`);
+  - CRUD heirs e willexecutors, settings get/set/reset, export/import will
+    (merge), build will con fixtures note.
+- `tests/test_cli_zip.py` (o estensione di `external_zip_test.py`):
+  - costruisce lo zip, lo carica come `electrum_external_plugins.bal` con
+    `Plugins(config, 'cmdline')`, asserisce `available_for` include `"cmdline"`
+    e che `get_plugin('bal')` restituisca il `Plugin` di `bal.cli.plugin`
+    (nessun import Qt eseguito).
+- `tests/test_cli_will_flows.py` (offline, dove possibile):
+  - prepare → sign → export → merge su un wallet di test con heirs fissi;
+  - verifica che `wallet.db.get_dict("will")` rifletta COMPLETE/PUSHED dopo
+    le operazioni che non toccano rete.
+
+### 11.2 Verifica manuale (da documentare nel README/HANDOFF)
+
+```bash
+source "$BAL_HOME/electrum/env/bin/activate"
+electrum daemon -d
+electrum load_wallet
+electrum bal_heirs_list
+electrum bal_settings_list
+electrum bal_will_status
+electrum bal_will_prepare
+electrum bal_will_sign --password '...'          # se wallet cifrato
+electrum bal_will_broadcast
+electrum bal_will_check_executor
+electrum bal_willexecutors_ping
+electrum stop
+```
+
+### 11.3 Regressione
+
+- `QT_QPA_PLATFORM=offscreen python3 tests/smoke_test.py electrum.plugins.bal`
+  deve continuare a passare (prova che `bal/__init__` + Qt convivono con il
+  nuovo import di `bal.cli.commands`).
+- Eseguire i `test_core_*.py` esistenti (nessuna logica core toccata).
+- Ruff: evitare nuove violazioni in `bal/cli/`.
+
+---
+
+## 12. Rischi e decisioni aperte
+
+1. **Daemon obbligatorio** (non `--offline`): imposto da `plugin_command`.
+   → Accettato; documentato al §3.1.
+2. **Wallet pre-caricato**: i comandi `w` falliscono con "wallet not loaded" se
+   non si lancia prima `electrum load_wallet`. → Documentare.
+3. **`bal/__init__.py` che importa `bal.cli.commands`**: viene eseguito anche
+   all'avvio della GUI. `commands.py` deve restare leggero (solo definizioni +
+   import di `electrum.commands` e `bal.core`). Da verificare con `smoke_test.py`.
+4. **Doppio caricamento**: se un install è contemporaneamente interno E zip
+   esterno, la seconda importazione di `commands.py` potrebbe sollevare
+   "Command name bal_... already exists". Pratica corrente: un solo install;
+   si può mitigare con un guard `if not getattr(module, '_registered')`.
+5. **OP_RETURN heirs** in CLI: gestiti come in GUI (`validate_op_return_hex`,
+   colonne quantità `"0"`). Da testare.
+6. **Persistenza `will_settings`**: oggi letta dalla config globale
+   (`bal_will_settings`) in `BalWindow.__init__`, non dal wallet DB. Il
+   controller deve replicare esattamente questo (config), non introdurre una
+   seconda sorgente.
+7. **Multisig**: la firma usa `wallet.sign_transaction` → supportata; il flusso
+   "merge PSBT" copre la firma parziale. Test dedicato con wallet multisig in
+   fase di implementazione.
+
+---
+
+## 13. Fasi di implementazione (ordine proposto)
+
+1. `bal/cli/__init__.py`, `bal/cli/plugin.py`, `bal/cmdline.py`, update
+   `bal/manifest.json` + `bal/__init__.py`.
+2. `tests/test_cli_commands_registered.py` + verifica `smoke_test.py`.
+3. `bal/cli/controller.py` (read-only: status/list/show) → `commands.py` per
+   willexecutors/heirs/settings (senza rete).
+4. Comandi will: `prepare`, `sign`, `export`, `import_merge`, `invalidate`.
+5. Comandi di rete: `ping`, `download`, `broadcast`, `check_executor`.
+6. Test zip (`test_cli_zip.py`), estensione `external_zip_test.py`, prova
+   manuale col daemon, aggiornamento README/HANDOFF.

PLAN_QR_TRANSFER.md

@@ -0,0 +1,499 @@
+# PLAN — Will transfer via QR codes / audio modem (Qt now, QML planned)
+
+> Goal: let the user move an inheritance ("will") between devices over two
+> air-gap channels:
+>
+> 1. **QR codes** (primary): export the **valid** inheritance transactions as
+>    a sequence of QR codes, and import them back on another machine with the
+>    camera;
+> 2. **Audio modem** (secondary, when Electrum's `audio_modem` plugin is
+>    enabled): send/receive the same payload through the PC speaker +
+>    microphone.
+>
+> Both channels converge on the same review-and-sign flow afterwards.
+>
+> Status: APPROVED by owner (2026-08-25). No code written yet — this document
+> is the implementation contract. Work top-down through §9 Checklist.
+>
+> Chat language: Italian; this document is in English (global rule R1).
+
+---
+
+## 1. Scope
+
+### In scope
+
+- **Desktop PyQt6 GUI** (primary, implemented by this plan):
+  - New plugin setting: QR chunk size, offered as **4 standard presets**.
+  - *"Export via QR"* action: serializes the **valid** will transactions,
+    optionally compresses, splits the resulting string into fixed-size frames,
+    shows one QR at a time with prev/next navigation, live re-chunking and
+    progress (`i di N`).
+  - *"Import via QR"* action: camera capture dialog with a slot grid
+    (1..N); the user selects which shot he is about to capture, scans, the
+    frame lands in its slot; when 1..N are filled the payload is assembled,
+    parsed into `WillItem`s, validity-checked locally.
+  - **Post-capture flow (owner decision D6, amended)**: after capture
+    completes there is NO read-only preview. Instead a review-and-sign wizard
+    walks through every transaction one at a time showing **outputs
+    (address + amount), total outputs, total fees**, signs it (wallet
+    password asked once), and at the end **proposes exporting the signed
+    transactions** (to file and/or back via QR).
+- **Audio-modem channel** (owner decision D7): when the Electrum
+  `audio_modem` plugin is enabled and available, the export dialog gains a
+  *"Send via Audio Modem…"* button and the import dialog a *"Receive via
+  Audio Modem…"* button, reusing the same transfer string (no QR framing).
+- **QML**: document-only update to `QML_PLAN.md` adding dedicated view specs
+  (owner decision D1). No QML code in this feature.
+
+### Out of scope
+
+- Implementing the QML frontend (gated behind `QML_PLAN.md` Phases 0–2).
+- Merging imported wills into the live wallet state (existing Merge flows
+  stay unchanged).
+- Broadcast of the reviewed transactions (user exports them; broadcasting
+  remains an explicit action elsewhere).
+- CLI/cmdline parity for QR transfer.
+
+---
+
+## 2. Owner decisions (locked)
+
+| # | Decision |
+|---|----------|
+| D1 | QML part = update `QML_PLAN.md` document only; implementation later. |
+| D2 | Frames carry a small **compact** ASCII header (`BAL1<total><index><flag>`, fixed 11 chars, base36 count fields) — import knows the total, auto-fills the grid, detects corrupt/duplicate/mismatched frames. Pure concatenation rejected. Legacy `BALQR1\|N\|i\|flags\|` export removed; legacy import kept. |
+| D3 | Payload = **serialized transaction strings only** (`str(wi.tx)`), NOT the JSON will dump. Loses statuses/metadata on purpose; import rebuilds items like `merge_single_transaction` does. |
+| D4 | Compression (zlib+base64 over the whole payload) exported as **best-of**: `encode_transfer_best` ships compressed when it is shorter, plain otherwise; flag `0` = plain, `Z` = compressed. No user-facing checkbox. |
+| D5 | 4 standard size presets: **~150 / ~400 / ~900 / ~1800 bytes** of payload per QR (low-res cams → high-res cams). Error-correction level fixed **M**. Stored as plugin config default; selectable again inside the export dialog. |
+| D6 | After capture completes: **review + sign each tx one at a time** (show outputs, total outputs, total fees), then **propose export of the signed txs** (file and/or QR). Supersedes the earlier "WillDetailDialog preview" answer. |
+| D7 | Add an **audio-modem transfer path** gated on Electrum's `audio_modem` plugin being enabled and available (`amodem` importable). Same payload semantics as QR (transfer string of serialized txs), but NO BAL frame chunking — `amodem` handles transport framing internally. Buttons simply hidden when the plugin is absent/unavailable (info message pointing at `pip install amodem` when enabled-but-broken); graceful degradation, never a hard dependency. |
+
+---
+
+## 3. Verified facts (research done on the local checkouts)
+
+All verified by reading source; references are `file:line`.
+
+| # | Fact | Where |
+|---|------|-------|
+| F1 | Export today: `BalWindow.export_will()` writes `{wid: WillItem.to_dict()}` JSON; subsets All/Valid/Valid-NC built in `WillList` | `bal/gui/qt/window.py:1605-1621`, `lists.py:666-669, 743-767` |
+| F2 | Batch signer: `BalWindow.sign_transactions(password, will, txids)` loops valid txs, resolves input values from change prevouts (`txin._trusted_value_sats` …), calls `wallet.sign_transaction`, updates `COMPLETE` + signature counts | `window.py:1017-1086` |
+| F3 | External-will signing already supported (`will=` param, nothing saved to live wallet/history) | `window.py:1443-1484` |
+| F4 | Single-tx import precedent: `merge_single_transaction` wraps `WillItem({"tx": str(tx)}, _id=tx.txid(), wallet=...)` | `window.py:1715-1724` |
+| F5 | Local validity recomputation recipe (no network): `add_willtree` → `Util.get_available_utxos` → `check_invalidated` → `search_rai` → `check_signatures` | `window.py:1678-1701` |
+| F6 | Plugin config accessor pattern `BalConfig`; keys declared in ctor | `bal/core/plugin_base.py:130-154, 211-264` |
+| F7 | Plugin settings dialog: grid rows 0..12, `add_widget(grid,label,widget,row,help)` + `_make_reset_btn(cfgvar,widget,kind)`; ADVANCED-only rows wrapped with `_hide_if_basic(...)` | `bal/gui/qt/plugin.py:442-850` (rows at 677-850) |
+| F8 | `BalDialog(parent, bal_plugin, title=None, icon=...)` base class anchors to top-level window | `bal/gui/qt/dialogs.py:92-129` |
+| F9 | Fee display precedent: `fee = tx.input_value() - tx.output_value()`, fee rate = `fee / tx.estimated_size()` | `bal/gui/qt/widgets.py:1319-1328` |
+| F10 | Input-value resolution helper exists: `Will.add_info_from_will(will, wid, wallet)` sets trusted input values from sibling will change outputs | `bal/core/will.py:118-136` |
+| F11 | `str(tx)` = `tx.serialize()`: raw hex for complete txs; `PartialTransaction.serialize()` → base64 PSBT. Both accepted by `tx_from_any` (= `Will.get_tx_from_any`). This is exactly how BAL persists/reloads txs today | `electrum/transaction.py:907, 2539`; `will.py:106-113`; `window.py:1041-1044` |
+| F12 | `QRCodeWidget` exists but **hardcodes `ERROR_CORRECT_L`** → cannot satisfy D5/M; must render our own `qrcode` instance | `electrum/gui/qt/qrcodewidget.py:35-37` |
+| F13 | Camera scanning one-shot API with OS-permission handling: `scan_qrcode_from_camera(*, parent, config, callback(success: bool, error: str, data: Optional[str]))`; on Linux uses zbar CLI backend | `electrum/gui/qt/qrreader/__init__.py:47-64` |
+| F14 | QR painting without PIL: `draw_qr(qr, paint_device, ...)` from `electrum.gui.common_qt.util` (what `QRCodeWidget.paintEvent` uses) | `electrum/gui/qt/qrcodewidget.py:63-72` |
+| F15 | QR capacity sanity (byte mode, EC **M**): v40-M ≈ 2331 B ≥ 1800 ✓; v10-M ≈ 213 B ≥ 150 ✓; the `qrcode` lib auto-picks the version | `qrcode` lib |
+| F16 | `build_zip.py` walks the tree with `os.walk` → new `.py` files ship automatically | `build_zip.py:39-47` |
+| F17 | QML fork already has `QRImage.qml`, `QRScan.qml`, `ScanDialog.qml`; ScanDialog carries upstream comment "currently not used on android … qt6 camera support stops crashing" | `electrum/gui/qml/components/ScanDialog.qml:8-9` |
+| F18 | `QML_PLAN.md` currently defers chunked multi-QR streams (Phase 3 note + risk R6) — this feature supersedes that deferral | `QML_PLAN.md:228-231, 304` |
+| F19 | House test conventions: `def test_*` + `if __name__ == "__main__"` + `sys.path.insert(0, ..pardir)`; run standalone or via pytest | `tests/test_core_heirs.py:1-24` |
+| F20 | Fork ships an `audio_modem` plugin. `_send(parent, blob)` zlib-compresses an **ASCII** blob, plays it via speaker through `amodem` inside a `WaitingDialog`; bit-rate selectable in the plugin's own settings (default = `amodem.config.slowest()`) | `electrum/plugins/audio_modem/qt.py:96-110` |
+| F21 | `_recv(parent)` records from mic and delivers the decompressed ASCII text by calling `parent.setText(blob)` — the only integration contract is "an object with `setText(str)`"; there is no callback API | `audio_modem/qt.py:112-127` |
+| F22 | Plugin lookup for enabled plugins: `window.plugins.get(name)` → instance or `None` (`Plugins.get`, electrum/plugin.py:575-576); availability check is the plugin's own `is_available()` (imports `amodem`). **`amodem` is NOT installed in the runtime env today** → optional dependency (pip `amodem` + libportaudio); feature must degrade gracefully | `electrum/plugin.py:575`, runtime-env check |
+| F23 | `amodem.main.send/recv` stream the whole blob with their own framing/training → BAL must NOT apply QR frame chunking on this channel; and since `_send` compresses internally, BAL sends the **plain** transfer string to avoid double compression | consequence of F20/F21 |
+
+---
+
+## 4. Wire format specification
+
+### 4.1 Transfer string
+
+```
+transfer_string = "\n".join( tx_str(tx) for tx in valid_txs_sorted_by_txid )
+```
+
+- `tx_str(tx)` = `str(tx)` (F11): hex for complete txs, base64-PSBT for
+  partially-signed ones. Neither alphabet contains `\n` or `|`, so both are
+  safe delimiters.
+- Ordering: ascending `tx.txid()` → deterministic output for identical input.
+- If compression enabled (D4):
+  `transfer_string = base64_ascii( zlib_compress( transfer_string ) )`.
+
+### 4.2 Frame layout (one frame = content of ONE QR code)
+
+Wire format v2 (compact, current export):
+
+```
+BAL1<TTT><iii><F><payload>
+```
+
+- Magic+version literal `BAL1` (reject anything else with a clear message).
+- `<TTT>` = `<iii>` — **base36** zero-padded 3-char strings (`000`…`ZZZ`),
+  representing total N and index i, `1 ≤ i ≤ N ≤ 46655`. Fixed width means a
+  3-digit count field costs the same for a 1-frame or a 46655-frame transfer.
+- `<F>`: single flag char — `0` ⇒ plain, `Z` ⇒ zlib+base64 compressed.
+- `<payload>`: the i-th slice of `transfer_string`, exactly
+  `chunk_size` bytes each (last slice may be shorter). No separators: both
+  base36 count fields are fixed-width, so the header is unambiguously 11
+  chars and the payload starts at offset 11.
+- Header overhead is a constant **11 bytes** → effective payload =
+  `chunk_size − 11`; the chunker slices the transfer string so that
+  **header+payload ≤ preset size**.
+
+Legacy frames `BALQR1|<total>|<index>|<flags>|<payload>` (variable-width
+decimal header, pipe-separated) are still **imported** by `parse_frame`
+(`_parse_v1`), so old exports keep working; the exporter emits v2 only.
+That is the one deliberate compatibility break: **v2 frames are not readable
+by builds older than this change.**
+
+### 4.3 Size presets (D5)
+
+| Preset label | Payload budget (bytes/frame) | Typical QR version @EC-M |
+|--------------|------------------------------|--------------------------|
+| Small (low-res cameras) | 150 | ~v10 |
+| Medium | 400 | ~v15 |
+| Large | 900 | ~v22 |
+| XL (high-res cameras) | 1800 | ~v40 |
+
+EC level fixed **M** for scan reliability (D5). Presets live in
+`bal/core/qrtransfer.py::CHUNK_PRESETS` so core tests can cover them.
+
+### 4.4 Audio-modem channel (D7, F20-F23)
+
+- Payload = the **plain** `transfer_string` of §4.1 — no BAL frames
+  (`split_frames`/`parse_frame` are QR-only), no BAL compression (the plugin
+  compresses internally; double compression wastes airtime).
+- The existing core functions `encode_transfer(tx_strings,
+  compress=False)` + `decode_transfer(text, compressed=False)` are reused
+  unchanged; only the transport differs.
+- Bit-rate is owned by the audio_modem plugin's settings dialog — BAL adds
+  no setting of its own.
+
+---
+
+## 5. New core module — `bal/core/qrtransfer.py`
+
+GUI-free (never imports Qt — house rule). Public API:
+
+```python
+MAGIC = "BALQR"
+VERSION = 1
+FLAG_COMPRESSED = "Z"
+CHUNK_PRESETS = [(label_en, budget_bytes), ...]   # §4.3 table
+
+def encode_transfer(tx_strings: list[str], compress: bool = False) -> str
+    """Join -> optional zlib+base64 -> return transfer_string."""
+
+def split_frames(transfer_string: str, chunk_size: int) -> list[str]
+    """Slice into frames 'BAL1<TTT><iii><F>payload' (v2) — header+payload <=
+    chunk_size. Raises QrTransferError over the 46655-frame base36 cap, or
+    ValueError if chunk_size < MIN_CHUNK_SIZE."""
+
+def encode_transfer_best(tx_strings: list[str]) -> tuple[str, bool]
+    """-> (transfer_string, compressed); ships the shorter of plain vs
+    zlib+base64 so the export emits the densest frames."""
+
+def parse_frame(frame: str) -> tuple[int, int, bool, str]
+    """-> (total, index, compressed, payload); accepts v2 'BAL1…' and legacy
+    'BALQR1|…' (wrapped as _parse_v1/_parse_v2); ValueError on bad magic/
+    version/arity/non-numeric fields."""
+
+def assemble(frames: dict[int, str]) -> str
+    """Validate indices form exactly range(1..max_total) (taken from any
+    frame header), concatenate payloads in order, decode flags ->
+    transfer_string. Raises MissingFramesError(indexes) / InconsistentTotalError."""
+
+def decode_transfer(transfer_string: str, compressed: bool) -> list[str]
+    """Inverse of encode_transfer -> list of tx strings."""
+```
+
+Plus exceptions `QrTransferError(ValueError)`, `MissingFramesError`,
+`InconsistentTotalError`. All docstrings/comments English; ruff-clean
+(line-length 88, E501 ignored).
+
+---
+
+## 6. Settings (Qt)
+
+1. `bal/core/plugin_base.py`: after `REBUILD_ON_CLOSE` (~line 264) add
+
+   ```python
+   self.QR_CHUNK_SIZE = BalConfig(config, "bal_qr_chunk_size", 150)
+   ```
+
+2. `bal/gui/qt/plugin.py::settings_dialog` (rows end at 12, ~line 844):
+   append row **13** — visible in BASIC and ADVANCED (do NOT wrap with
+   `_hide_if_basic`):
+
+   - Label: `"QR Code Size"`
+   - `QComboBox` fed from `CHUNK_PRESETS`; item text e.g.
+     `"Small — ~150 bytes/QR (low-res cameras)"`; `currentIndexChanged`
+     → `self.QR_CHUNK_SIZE.set(budget_bytes)`; initial index from
+     `QR_CHUNK_SIZE.get()` (fallback to nearest preset if the stored value
+     was customized).
+   - `HelpButton` text: explains trade-off (small QR = more shots but easier
+     to scan with poor cameras; large QR = fewer shots, needs good camera)
+     and that the size can also be changed inside the export dialog.
+   - Reset button via existing `_make_reset_btn(self.QR_CHUNK_SIZE, combo, ...)`
+     pattern (plugin.py:684).
+
+---
+
+## 7. Qt export flow
+
+### 7.1 Entry point
+
+`bal/gui/qt/lists.py::WillList.create_toolbar` (menu block lines 666-670):
+
+```python
+export_menu.addAction(_("Via QR…"), self.export_will_valid_qr)
+```
+
+New `WillList.export_will_valid_qr()` mirrors `export_will_valid`
+(lists.py:743-754): builds `{wid: wi}` subset of `VALID` items, empty →
+`show_message(_("No valid will item to export"))`, else
+`self.bal_window.export_will_via_qr(will=subset)`.
+
+### 7.2 `BalWindow.export_will_via_qr(will=None)` (new, `window.py` near
+`export_will`)
+
+- Collect `tx_strings = [str(wi.tx) for wid, wi in sorted-by-txid ...]`
+  (F11).
+- Mark exported items `EXPORTED` (parity with `export_json_file`,
+  window.py:1607-1609) — only when `will` came from the live list.
+- Open `WillQrExportDialog(self, tx_strings)`.
+
+Shared helper used by both dialogs:
+
+```python
+def get_audio_modem_plugin(self):        # on BalWindow
+    """Return the loaded audio_modem plugin if enabled AND available
+    (amodem importable), else None. Never raises."""
+    p = self.window.plugins.get("audio_modem")   # F22
+    return p if p is not None and p.is_available() else None
+```
+
+### 7.3 `WillQrExportDialog(BalDialog)` (new class in `dialogs.py`)
+
+Layout:
+
+```
+[Size ▾ Small/Medium/Large/XL]   ← compressed best-of automatically (no checkbox)
+[            QR image           ]   ← BalQrImage (see below)
+«i di N»        [◀ Prev] [Next ▶]
+[Save current QR as PNG…]  [Send via Audio Modem…]  [Close]
+```
+
+Behaviour:
+
+- On any control change: rebuild `split_frames(encode_transfer_best(...))`,
+  reset index to frame 1, refresh counter (owner requirement: "cambiare la
+  risoluzione").
+- `BalQrImage(QWidget)` ≈ trimmed copy of `QRCodeWidget`
+  (`electrum/gui/qt/qrcodewidget.py:21-72`) but constructing
+  `qrcode.QRCode(error_correction=ERROR_CORRECT_M, border=2)` and painting
+  via `electrum.gui.common_qt.util.draw_qr` (F12/F14). ~30 lines.
+- Prev/Next wrap or disable at ends (disable chosen: clearer).
+- PNG export optional convenience via existing
+  `getSaveFileName` + `QWidget.grab()` (same trick as
+  `qrcodewidget.py:110`).
+- **Send via Audio Modem…** (D7): shown only when
+  `bal_window.get_audio_modem_plugin()` returns a usable instance (below);
+  otherwise hidden. Handler: re-encode the payload **plain**
+  (`encode_transfer(tx_strings, compress=False)`) and call the plugin's
+  `_send(parent=self, blob=transfer_string)` — its own WaitingDialog owns
+  progress/cancellation (F20). Tooltip when hidden is unnecessary; instead,
+  if the plugin is enabled but `is_available()` is False, show an info
+  message pointing to `pip install amodem` + portaudio (F22).
+
+---
+
+## 8. Qt import flow + review/sign wizard
+
+### 8.1 Entry point
+
+`lists.py` toolbar menu, next to Import/Merge (lines 670-671):
+
+```python
+menu.addAction(_("Import via QR…"), lambda: self.bal_window.import_will_via_qr())
+```
+
+`BalWindow.import_will_via_qr()` opens `WillQrImportDialog(self)`.
+
+### 8.2 `WillQrImportDialog(BalDialog)`
+
+State: `self.frames: dict[int, str]`, `self.total: int | None`,
+`self.target_index: int | None`.
+
+Layout:
+
+```
+«Captured k of N»          [Scan ▶]   [Reset]
+[slot grid: push-buttons 1..N; states: empty / filled ✓ / selected-target]
+hint line («Select a slot, then scan» / «Scan the first QR»)
+              [Receive via Audio Modem…]  [Review & Sign ▶] [Close]
+```
+
+Behaviour:
+
+- **Scan** → `scan_qrcode_from_camera(parent=self,
+  config=self.bal_window.window.config, callback=self._on_scan)`
+  (F13). One-shot per press; dialog stays open between shots (simplest,
+  matches Electrum UX; no continuous mode).
+- `_on_scan(success, error, data)`:
+  - failure → `show_error(error)` (covers missing zbar/camera too);
+  - `parse_frame` errors → `show_warning(_("Not a BAL will QR"))`;
+  - first valid frame adopts `total` and materializes the slot grid;
+  - frame whose `total` ≠ adopted total → warn + offer Reset (user may have
+    restarted the export with another size);
+  - valid → `frames[index] = payload`; auto-advance `target_index` to the
+    lowest missing index; refresh grid + counter.
+- Clicking an empty slot sets `target_index` (owner requirement: manual
+  shot selection); a filled slot click asks to overwrite.
+- **Receive via Audio Modem…** (D7): shown only when
+  `bal_window.get_audio_modem_plugin()` returns a usable instance. Handler:
+  build a tiny adapter object exposing `setText(str)` that stores the text
+  and invokes the shared post-receive continuation, then call
+  `plugin._recv(parent=self, ...)`-style flow (F21 contract). On success the
+  received string is treated as the **whole payload**: skip frames/slots
+  entirely → `decode_transfer(text, compressed=False)` → continue at §8.2's
+  item-building step (WillItem construction + validity pass + wizard).
+  Errors from the modem surface through the plugin's own dialog; empty
+  result (user cancelled) is silently ignored.
+- **Review & Sign** enabled only when `set(frames) == set(range(1, N+1))`:
+  runs `assemble` + `decode_transfer` → `list[str]`; any `QrTransferError`
+  surfaces as `show_error` and keeps the dialog open.
+- Build items exactly like `merge_single_transaction` (F4):
+  `WillItem({"tx": s}, wallet=self.wallet)` per string; failures per-string
+  are collected and reported at the end (bad string ≠ fatal for the rest).
+- Local validity pass (F5 recipe) on the resulting dict; items failing
+  `VALID` are dropped and listed in a warning. Set
+  `wi.set_status("IMPORTED", True)` on survivors (mirrors
+  `import_will_into_details`, window.py:1753-1754).
+- Then `close()` and start the wizard (§8.3) with the valid subset. Empty
+  result → stop with a message.
+
+### 8.3 `WillTxReviewSignDialog(BalDialog)` — post-capture wizard (D6)
+
+Constructed with `(bal_window, willitems: dict[str, WillItem])` — the
+imported subset lives **outside** the live wallet state (external mode,
+F3).
+
+Flow:
+
+1. **Password once**: `password = bal_window.get_wallet_password()`
+   (window.py:1088-1100). Returns `False` on cancel → abort wizard; `None`
+   means unencrypted wallet → proceed without password.
+2. **Per-transaction page** (one `QStackedWidget` step per tx, ordered by
+   txid like export):
+
+   ```
+   Tx 2 of 5 — a1b2…c3d1 (short txid)
+   Locktime: 2033-04-05            Status: unsigned (0/1 sigs)
+   ┌ outputs ─────────────────────────────────┐
+   │ bc1q…heir1            0,042 BTC          │
+   │ bc1q…willexec fee     0,00012 BTC        │
+   │ bc1q…change           0,00988 BTC        │
+   └───────────────────────────────────────────┘
+   Total outputs: 0,052 BTC        Fees: 420 sat (1.2 sat/vB)
+   [Sign & Next ▶]   [Skip]   [Cancel all]
+   ```
+   - Outputs from `tx.outputs()` (address via `TxOutput.get_ui_address_str()`
+     style helpers already imported in the qt layer; value via
+     `bal_window.window.format_amount`).
+   - Totals: `output_value()` sum; fees via `input_value() - output_value()`
+     after resolving inputs with `Will.add_info_from_will(will, wid, wallet)`
+     (F10); `-1`/unknown handled like widgets.py:1319-1324 (F9).
+3. **Sign & Next** → sign this single tx through a **refactored helper**
+   extracted from the loop body of `sign_transactions`
+   (window.py:1037-1083 → `_sign_single_tx(tx, willitems, password)` kept
+   byte-equivalent; batch method calls the helper per iteration so existing
+   behaviour/tests are unaffected). Update `COMPLETE`/sig-counts exactly as
+   today; then advance.
+4. **Skip** leaves the tx untouched and advances. **Cancel all** stops; the
+   already-signed txs remain in the wizard's local dict (still exportable —
+   confirmation dialog warns about skipped ones).
+5. **Summary page**: `signed X of Y`, skipped/failed lists, then:
+
+   ```
+   [Save signed file…]   [Show QR…]   [Close]
+   ```
+   - *Save file* = existing JSON path: `export_meta_gui(window,
+     "will.json", writer)` writing `{wid: wi.to_dict()}` of the signed
+     subset (same serializer as `export_json_file`, window.py:1605).
+   - *Show QR* = `WillQrExportDialog` over `[str(wi.tx)]` of the signed
+     subset (the online machine can scan them straight into Merge).
+   - Nothing touches `self.willitems`/history (external-mode rule, F3).
+
+---
+
+## 9. Checklist (execution order — tick here when resuming work)
+
+- [x] **P0** `bal/core/qrtransfer.py` + unit tests `tests/test_core_qr_transfer.py`
+      (cases: round-trip plain/compressed; boundaries: len%size==0, size>len,
+      min-size guard; bad magic/version; missing middle frame; duplicate
+      overwrite; inconsistent totals; multi-PSBT mixes; presets sanity vs
+      qrcode capacities F15). Run:
+      `QT_QPA_PLATFORM=offscreen python3 tests/test_core_qr_transfer.py`
+- [x] **P1** Settings: `QR_CHUNK_SIZE` config var + settings-dialog row 16
+      (ø16) + reset kind (§6). Verify in `QT_QPA_PLATFORM=offscreen` GUI run.
+- [x] **P2** Export: `BalWindow.export_will_via_qr`, `get_audio_modem_plugin`
+      helper, `WillList` menu action, `WillQrExportDialog` + `BalQrImage`,
+      audio-modem send button (§7).
+- [x] **P3** Import: `import_will_via_qr`, `WillQrImportDialog` (§8.2),
+      incl. camera error paths, audio-modem receive button (local mirror of
+      `_recv`, `setText` sink replaced by a callback), plain-payload fast
+      path into the wizard.
+- [x] **P4** Wizard: `_prepare_and_sign_tx` refactor + `WillTxReviewSignDialog`
+      (§8.3). Regression-gate: full batch sign still green
+      (`tests/test_core_*.py` offline batch; `tests/test_gui_*.py` batch
+      including new `tests/test_gui_qr_transfer.py`).
+- [x] **P5** Docs & QML plan sync: update `QML_PLAN.md` — Phase 2 models +=
+      `BalQrTransferModel` (thin QObject over `bal.core.qrtransfer`),
+      Phase 3 += dedicated views `BalQrExportPage.qml` /
+      `BalQrImportPage.qml` (slot grid + `QRScan` reuse), delete the
+      "chunked streams deferred" note, rewrite R6 mitigation, add Android
+      caveat quoting F17 with file/paste fallback; README/HANDOFF sections;
+      CHANGELOG numbered entry 56 at END (house rule).
+- [x] **P6** Release hygiene: `python3 build_zip.py` +
+      `QT_QPA_PLATFORM=offscreen python3 tests/smoke_test.py
+      electrum.plugins.bal` + external-zip test; ruff (repo venv
+      `venv/bin/ruff`) no NEW violations; pyright false-positive policy per
+      AGENTS.md. Version bump only via `make-release.sh` (owner-driven).
+      Docs: document audio-modem as OPTIONAL channel — requires the
+      Electrum `audio_modem` plugin enabled plus `pip install amodem`
+      and libportaudio (not installed in the dev runtime env today, F22);
+      manual test matrix gains an audiomodem round-trip row (two machines,
+      default slowest bitrate) marked optional/skippable when hardware
+      unavailable.
+
+---
+
+## 10. Risks & mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| High frame counts annoy users (e.g. 40+ QR at 150 B) | Presets span 150→1800; compress option; counter always visible |
+| Big QR versions fail on cheap cameras | EC=M fixed; Small preset targets low-res cams (D5 rationale) |
+| User rescans old export with different total | `InconsistentTotalError` → clear warning + Reset (§8.2) |
+| `_sign_single_tx` refactor regresses batch signing | Byte-equivalent extraction; batch callers unchanged; offline core tests gate P4 |
+| Imported txs reference UTXOs the importing wallet doesn't know | Validity pass drops them with an explicit report instead of silently merging garbage |
+| zbar/camera unavailable (esp. Windows/macOS packaging) | `scan_qrcode_from_camera` error path → suggest file export/import fallback |
+| `amodem`/portaudio not installed (current dev env state, F22) or audio_modem plugin disabled | Buttons simply hidden; QR/file remain the primary channels; P6 documents the optional dependency |
+| Audio transfer fails mid-way (noise, wrong volume) | Plugin's WaitingDialog surfaces the error; user retries — nothing to clean up on BAL side (single atomic blob, no slot state touched) |
+| Very slow airtime at default slowest bitrate | Bitrate is selectable in the audio_modem plugin's own settings (F20); BAL adds no knob; tooltip in export dialog hints at large payloads |
+| Qt6 camera instability on Android (future QML work) | Recorded as caveat in QML_PLAN update (P5), file/paste stays the primary mobile fallback |
+
+---
+
+## 11. Findings log (append-only)
+
+- 2026-08-25: plan drafted after code exploration; owner answered D1-D6
+  (D6 amended live from "preview dialog" to "review+sign wizard").
+- Verified F12 (QRCodeWidget hardcodes EC-L) and F11 (str(tx) round-trip
+  guarantees) — both shaped §§4/7.
+- 2026-08-25: owner requested an audio-modem transfer path → researched
+  `electrum/plugins/audio_modem/qt.py`, added D7 + F20-F23, §4.4, buttons
+  in §§7.3/8.2, checklist/risk updates. Key constraint found: `_recv`'s
+  only contract is `parent.setText(blob)` (F21) → thin adapter object; and
+  BAL must not chunk/compress on this channel (F23). `amodem` is NOT in
+  the runtime env yet — feature is strictly optional.

README.md

@@ -5,10 +5,11 @@ Free and decentralized **Bitcoin inheritance** support for the
 that transfer your funds to your heirs if you stop refreshing them
 (dead-man's switch), optionally relayed by will-executor servers.
 
-This repository contains a **behavior-preserving refactor** of the original
+This repository contains a **refactored and extended** version of the original
-plugin. The logic was kept byte-identical wherever possible; only the file
+plugin. The logic was reorganized to cleanly separate **business logic** from the
-layout was reorganized to cleanly separate **business logic** from the
+**PyQt GUI**, and new features have been added including a headless CLI,
-**PyQt GUI**.
+auto-rebuild on new transactions, OP_RETURN heirs, and configurable calendar
+reminders.
 
 ## Repository layout
 
@@ -16,12 +17,22 @@ layout was reorganized to cleanly separate **business logic** from the
 bal/                     the installable Electrum plugin package
 ├── manifest.json        plugin metadata (Electrum reads this)
 ├── qt.py                Qt entry-point shim (re-exports Plugin)
+├── cmdline.py           CLI entry-point shim (re-exports Plugin)
 ├── core/                GUI-free logic (importable without Qt)
 │   ├── util.py
 │   ├── plugin_base.py
 │   ├── heirs.py
 │   ├── will.py
-│   └── willexecutors.py
+│   ├── willexecutors.py
+│   ├── checkalive.py
+│   ├── reminders.py
+│   ├── qrtransfer.py       BAL QR will-transfer wire format / chunk scheduler
+│   ├── animated_qr.py      BC-UR v1/v2 + BBQR codecs (stdlib-only)
+│   └── input_rules.py
+├── cli/                 headless command-line layer (no Qt)
+│   ├── commands.py      bal_* daemon commands (@plugin_command)
+│   ├── controller.py    headless BalController (replicates BalWindow)
+│   └── plugin.py        CLI Plugin entry point
 ├── gui/qt/              PyQt6 presentation layer
 │   ├── theme.py         status → color mapping
 │   ├── common.py        shared imports / helpers
@@ -30,6 +41,7 @@ bal/                     the installable Electrum plugin package
 │   ├── dialogs.py       dialog windows
 │   ├── lists.py         tree/list views
 │   ├── window.py        per-wallet GUI controller
+│   ├── window_utils.py  GUI utility helpers
 │   └── plugin.py        Plugin (Electrum @hooks → GUI)
 ├── icons/  wallet_util/  LICENSE  README.md
 build_zip.py             builds a clean, zipimport-friendly distribution zip
@@ -77,6 +89,67 @@ Copy the `bal/` directory into your Electrum installation's
 `electrum/plugins/` directory, so that `electrum/plugins/bal/manifest.json`
 exists, then enable it from **Tools → Plugins**.
 
+## Transfer a will with QR codes (or audio)
+
+From the will list (**Export → QR Codes**) a will can be exported as a
+sequence of QR codes and imported on another device (**Import via QR**). The
+export offers All / Valid / Valid-NC filters plus a QR size preset
+(150–1800 bytes/frame) and ships the default **BAL QR** format already
+compressed whenever that is smaller (best-of zlib, flag per frame); the import
+flow reviews and sign each transaction
+one at a time, then proposes exporting the signed transactions. When
+Electrum's `audio_modem` plugin is enabled (optional, requires `amodem` +
+PortAudio) Send/Receive audio buttons complement the QR channel. See
+[`PLAN_QR_TRANSFER.md`](PLAN_QR_TRANSFER.md) for the BAL QR wire-format spec.
+
+### Animated-QR formats (interop)
+
+BAL QR is the default export format, but the export page's **Format** selector
+also emits **BC-UR v1** (`ur:bytes`, BC32 + SHA-256), **BC-UR v2**
+(`ur:bytes`, CBOR fountain codes) and **BBQR** (`B$…`, Coinkite, used by
+BitKit) animated-QR sequences. The importer auto-detects the format of each
+code it sees, so any of the four formats can be imported on a BAL device, and
+a BAL export can be imported by any tool that understands these standards.
+UR v2 imports tolerate out-of-order and duplicate frames (fountain decoding);
+BBQR frames may arrive in any order. Rotation/redundancy caps and the
+32 MB message limit (zlib-bomb guard) bound untrusted scanner input.
+
+## Command-line / headless usage
+
+BAL can be used without the Qt GUI via Electrum's daemon mode. The CLI layer
+exposes `bal_*` commands that replicate the full inheritance cycle.
+
+### Prerequisites
+
+- An **Electrum daemon** running (`electrum daemon -d`)
+- A wallet loaded (`electrum load_wallet`)
+
+### Available commands
+
+| Category | Commands |
+|----------|----------|
+| Settings | `bal_settings_list`, `bal_settings_get`, `bal_settings_set`, `bal_settings_reset` |
+| Heirs | `bal_heirs_list`, `bal_heirs_show`, `bal_heirs_add`, `bal_heirs_update`, `bal_heirs_delete`, `bal_heirs_import`, `bal_heirs_export` |
+| Will-Executors | `bal_willexecutors_list`, `bal_willexecutors_show`, `bal_willexecutors_add`, `bal_willexecutors_update`, `bal_willexecutors_select`, `bal_willexecutors_delete`, `bal_willexecutors_ping`, `bal_willexecutors_download`, `bal_willexecutors_import`, `bal_willexecutors_export` |
+| Will | `bal_will_status`, `bal_will_check`, `bal_will_prepare`, `bal_will_autorebuild`, `bal_will_sign`, `bal_will_broadcast`, `bal_will_export`, `bal_will_import_merge`, `bal_will_invalidate`, `bal_will_check_executor` |
+
+### Example workflow
+
+```bash
+electrum daemon -d
+electrum load_wallet
+electrum bal_heirs_list
+electrum bal_will_prepare
+electrum bal_will_sign --password '...'
+electrum bal_will_broadcast
+electrum stop
+```
+
+All commands require a running daemon (Electrum's `plugin_command` enforces
+this). Wallet-bound commands (`bal_heirs_*`, `bal_will_*`, etc.) require the
+wallet to be loaded first. Signing commands require `--password` for encrypted
+wallets.
+
 ## Inheritance safety: anticipate / postpone
 
 A will transaction is signed with a **fixed, immutable locktime** and then

android/.gitignore

@@ -0,0 +1,10 @@
+.gradle/
+build/
+local.properties
+.idea/
+*.apk
+*.aab
+captures/
+.externalNativeBuild/
+.cxx/
+*.hprof

android/README.md

@@ -0,0 +1,153 @@
+# BAL Reader (Android)
+
+A minimal Android app that reads a Bitcoin will exported by the
+[BAL Electrum plugin](https://bitcoin-after.life) directly from your screen,
+then lets you view, copy, share, or save the recovered data. **Reader only** —
+it never signs or broadcasts.
+
+It decodes **all four** transfer formats the plugin can export, auto-detecting
+the format from the first frame:
+
+- **BAL QR** (the plugin's default), single- and multi-frame, plain and
+  zlib-compressed, compact `BAL1` header (legacy `BALQR1` frames are still
+  accepted on import);
+- **BC-UR v1** (single-part and `NofM` multipart);
+- **BC-UR v2** (single-part and XOR-fountain multipart — it tolerates dropped,
+  repeated, and out-of-order frames);
+- **BBQR** (`Z`/`H`/`2` encodings).
+
+Both payload kinds are handled: the **whole-will JSON** and the plain
+**transaction-hex list**.
+
+## How decoding works
+
+The app does not reimplement the QR formats. It bundles the plugin's own
+codec modules — `bal/core/__init__.py`, `bal/core/animated_qr.py`,
+`bal/core/qrtransfer.py` — and runs them verbatim through **Chaquopy** (CPython
+on Android). Kotlin is only camera glue and UI:
+
+```
+Camera (CameraX) → ML Kit QR detection (on-device, no API key)
+    → BalDecoder.add(text)   → bal.core.animated_qr.AnimatedQrSession
+    → when done → BalDecoder.finish()
+        = session.resolve() → qrtransfer.decode_transfer()
+        → balreader.payload.decode_will_payload()
+    → ResultActivity: view / copy / share / save
+```
+
+The decode tail mirrors the plugin's import dialog function-for-function, and
+`android/test_chain/verify_chain.py` proves the bundled code decodes every
+format the way the desktop import does (including scrambled, duplicated, and
+missing frames).
+
+## Repository layout
+
+```
+android/
+├── app/src/main/
+│   ├── AndroidManifest.xml
+│   ├── java/life/after/bitcoin/
+│   │   ├── BalDecoder.kt      Chaquopy bridge over the bundled codecs
+│   │   ├── MainActivity.kt    camera + ML Kit scan loop + progress
+│   │   └── ResultActivity.kt  viewer (copy / share / save)
+│   └── python/                bundled Python (regenerate, do not hand-edit)
+│       ├── bal/core/          SYNCED COPY of the plugin codecs
+│       └── balreader/payload.py  verbatim copy of dialogs.decode_will_payload
+├── scripts/
+│   ├── sync_codecs.py         re-copy + verify the bundled codecs
+│   └── build_apk.py           resync codecs, run Gradle, print APK + sha256
+└── test_chain/verify_chain.py decode-chain simulation for all formats
+```
+
+## Build
+
+You need Android Studio (Jellyfish or newer), JDK 17, an Android SDK with
+platform 35, and a network connection for the first Gradle sync.
+
+1. Open this `android/` folder in Android Studio and let it sync (it will
+   fetch the Gradle wrapper 8.14, AGP 8.10.0, Kotlin 2.0.21, Chaquopy 17.0.0,
+   CameraX 1.3.4, and ML Kit).
+2. Connect a phone (API 24+) or start an emulator and press **Run**.
+3. Grant the camera permission when asked.
+
+Alternatively, from the command line (from the repository root):
+
+```bash
+python3 android/scripts/build_apk.py            # debug APK + sha256
+python3 android/scripts/build_apk.py --release  # (unsigned) release APK
+```
+
+The script re-synchronises the bundled codec modules first (so the APK always
+carries the current `bal/core` sources), runs `./gradlew`, and prints the APK
+path, size and sha256. Flags: `--no-sync` (skip the re-sync), `--offline`
+(Gradle without downloads), `--clean`, `--verbose`.
+
+Equivalent raw Gradle call:
+
+```bash
+cd android
+./gradlew assembleDebug   # APK: android/app/build/outputs/apk/debug/app-debug.apk
+```
+
+### If the Gradle wrapper jar is missing
+
+`gradle/wrapper/gradle-wrapper.jar` is committed so `./gradlew` works out of
+the box. If it is ever absent, Android Studio regenerates it on the first
+sync; no manual steps needed.
+
+## Use
+
+1. In Electrum + BAL, open the will's **export** dialog.
+2. Pick a format — start with the default **BAL QR**, then try **BC-UR v1**,
+   **BC-UR v2**, and **BBQR**.
+3. Make sure the wording toggle shows a payload (business logic), then display
+   the animated QR and keep it on screen.
+4. Point the phone at the screen. The header shows the detected format and
+   `received / total`; scanning stops automatically when the transfer is
+   complete.
+5. On the result screen: **Copy** the raw transfer, **Share** it, **Save** it
+   as `will.json` (whole will) or `will_tx.txt` (transaction list), or press
+   **Scan another**.
+
+Notes:
+
+- Keep the phone still and the whole QR inside the frame (the codec dedups
+  repeated frames, so a slow capture is fine).
+- If the camera glares off the screen, reduce brightness or tilt slightly.
+- If scanning jumps between exports, the app detects the format switch,
+  resets, and asks you to let it re-scan.
+
+## Keeping the bundled code in sync with the plugin
+
+The codecs under `app/src/main/python/bal/core/` are **committed copies** for
+deterministic builds, but they must stay identical to the plugin. Re-run this
+after changing `bal/core/animated_qr.py` or `bal/core/qrtransfer.py` (and
+after any change to `decode_will_payload` in `bal/gui/qt/dialogs.py`, which
+mirrors `balreader/payload.py`):
+
+```bash
+python3 android/scripts/sync_codecs.py        # copy
+python3 android/scripts/sync_codecs.py --check # verify only (CI-friendly)
+python3 android/test_chain/verify_chain.py     # full decode-chain regression
+```
+
+`verify_chain.py` fails if the app's `balreader/payload.py` ever drifts from
+the plugin's `decode_will_payload` (AST identity + result parity).
+
+## Version pins (see `PLAN_ANDROID_READER.md`)
+
+| Item | Version |
+|---|---|
+| AGP | 8.10.0 |
+| Gradle | 8.14 (wrapper) |
+| Kotlin | 2.0.21 |
+| Chaquopy | 17.0.0 (Python 3.12) |
+| compile / target / min SDK | 35 / 35 / 24 |
+| CameraX | 1.3.4 |
+| ML Kit barcode-scanning | 17.3.0 |
+| JDK | 17 |
+
+## License
+
+MIT. The bundled Python codec files inherit the plugin's MIT license
+(`bal/LICENSE`); see `app/src/main/python/bal/` for attribution.

android/app/build.gradle.kts

@@ -0,0 +1,67 @@
+plugins {
+    id("com.android.application")
+    id("org.jetbrains.kotlin.android")
+    id("com.chaquo.python")
+}
+
+android {
+    namespace = "life.after.bitcoin"
+    compileSdk = 35
+
+    defaultConfig {
+        applicationId = "life.after.bitcoin"
+        minSdk = 24
+        targetSdk = 35
+        versionCode = 1
+        versionName = "0.1.0"
+
+        // Chaquopy requires explicit ABI filters. Python 3.12 ships only for
+        // 64-bit ABIs: phones (arm64-v8a) + the common emulator image (x86_64).
+        ndk {
+            abiFilters += listOf("arm64-v8a", "x86_64")
+        }
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro",
+            )
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+    kotlinOptions {
+        jvmTarget = "17"
+    }
+    buildFeatures {
+        viewBinding = true
+    }
+}
+
+chaquopy {
+    defaultConfig {
+        version = "3.12"
+    }
+}
+
+dependencies {
+    implementation("androidx.core:core-ktx:1.13.1")
+    implementation("androidx.appcompat:appcompat:1.7.0")
+    implementation("androidx.activity:activity-ktx:1.9.3")
+    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.8.7")
+
+    // CameraX
+    implementation("androidx.camera:camera-core:1.3.4")
+    implementation("androidx.camera:camera-camera2:1.3.4")
+    implementation("androidx.camera:camera-lifecycle:1.3.4")
+    implementation("androidx.camera:camera-view:1.3.4")
+
+    // ML Kit on-device barcode scanning (QR only, no API key)
+    implementation("com.google.mlkit:barcode-scanning:17.3.0")
+}

android/app/proguard-rules.pro

@@ -0,0 +1,5 @@
+# Chaquopy Python runtime.
+-keep class com.chaquo.python.** { *; }
+
+# ML Kit barcode scanning.
+-keep class com.google.mlkit.** { *; }

android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-feature
+        android:name="android.hardware.camera"
+        android:required="true" />
+    <uses-permission android:name="android.permission.CAMERA" />
+
+    <application
+        android:allowBackup="true"
+        android:icon="@drawable/ic_launcher"
+        android:label="@string/app_name"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.BalReader">
+
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:screenOrientation="portrait">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+
+        <activity
+            android:name=".ResultActivity"
+            android:exported="false"
+            android:parentActivityName=".MainActivity" />
+    </application>
+</manifest>

android/app/src/main/java/life/after/bitcoin/BalDecoder.kt

@@ -0,0 +1,129 @@
+package life.after.bitcoin
+
+import android.content.Context
+import com.chaquo.python.PyObject
+import com.chaquo.python.PyException
+import com.chaquo.python.Python
+import com.chaquo.python.android.AndroidPlatform
+import org.json.JSONException
+import org.json.JSONObject
+
+/**
+ * Chaquopy bridge over the plugin's animated-QR codecs
+ * (``bal.core.animated_qr``, ``bal.core.qrtransfer``, bundled verbatim under
+ * ``app/src/main/python``).
+ *
+ * The decode tail mirrors the plugin's import dialog exactly, and runs
+ * entirely inside Python (``balreader.bridge.finish``) so no container
+ * conversion happens across the bridge:
+ *
+ *   session.resolve() -> qrtransfer.decode_transfer() -> decode_will_payload()
+ *
+ * Kotlin only feeds frames, reads progress, and renders the JSON the bridge
+ * returns.
+ */
+class BalDecoder(private val context: Context) {
+
+    /** Outcome of feeding one scanned frame to the session. */
+    enum class AddResult {
+        /** A new frame was accepted. */
+        OK,
+
+        /** The frame was already present (duplicate); ignore. */
+        DUP,
+
+        /** The frame was not a supported QR transfer; ignore. */
+        GARBAGE,
+
+        /** The QR switched to a different transfer; caller should rescan. */
+        CONFLICT,
+    }
+
+    /** Fully decoded transfer, mirroring the plugin's import tail. */
+    data class DecodedResult(
+        val kind: String,       // "will", "txs" or "error"
+        val payload: String,    // raw transfer text (JSON or joined tx hexes)
+        val parts: List<String> // [whole-will JSON] or [tx hex strings]
+    )
+
+    private val python: Python by lazy {
+        if (!Python.isStarted()) {
+            Python.start(AndroidPlatform(context))
+        }
+        Python.getInstance()
+    }
+    private val animatedQr by lazy { python.getModule("bal.core.animated_qr") }
+    private val bridge by lazy { python.getModule("balreader.bridge") }
+
+    private var session: PyObject? = null
+
+    /** Start a fresh receive session (clears any accumulated frames). */
+    fun reset() {
+        session = null
+    }
+
+    private fun sessionOrCreate(): PyObject {
+        val current = session
+        if (current != null) {
+            return current
+        }
+        return animatedQr.callAttr("AnimatedQrSession").also { session = it }
+    }
+
+    /** Feed one scanned frame string; see [AddResult] for semantics. */
+    fun add(text: String): AddResult {
+        return try {
+            when (sessionOrCreate().callAttr("add_part", text).toString()) {
+                "dup" -> AddResult.DUP
+                else -> AddResult.OK
+            }
+        } catch (e: PyException) {
+            val msg = e.message ?: ""
+            // TransferConflictError: "Switched QR format mid-import (.. -> ..)".
+            if (msg.contains("Switched QR format")) {
+                AddResult.CONFLICT
+            } else {
+                AddResult.GARBAGE
+            }
+        }
+    }
+
+    /** The detected wire format ("balqr"/"ur1"/"ur2"/"bbqr"), or null. */
+    val format: String?
+        get() = runCatching {
+            session?.get("format")?.toString()?.takeIf { it != "None" }
+        }.getOrNull()
+
+    /** Number of distinct frames accepted. */
+    val received: Int
+        get() = session?.get("received")?.toInt() ?: 0
+
+    /** Total frames expected for the current transfer (0 until known). */
+    val total: Int
+        get() = session?.get("total")?.toInt() ?: 0
+
+    /** True once the whole transfer has been captured. */
+    val done: Boolean
+        get() = session?.get("done")?.toBoolean() ?: false
+
+    /**
+     * Resolve the completed session into a [DecodedResult]. The decoding runs
+     * in Python (``balreader.bridge.finish``) using the exact same three steps
+     * as the plugin's import dialog.
+     */
+    fun finish(): DecodedResult {
+        val jsonText = bridge.callAttr("finish", sessionOrCreate()).toString()
+        return try {
+            val obj = JSONObject(jsonText)
+            val partsArray = obj.getJSONArray("parts")
+            val parts = (0 until partsArray.length()).map { partsArray.getString(it) }
+            DecodedResult(
+                kind = obj.getString("kind"),
+                payload = obj.getString("payload"),
+                parts = parts,
+            )
+        } catch (e: JSONException) {
+            DecodedResult(kind = "error", payload = jsonText, parts = emptyList())
+        }
+    }
+}

android/app/src/main/java/life/after/bitcoin/FrameProgressBar.kt

@@ -0,0 +1,70 @@
+package life.after.bitcoin
+
+import android.content.Context
+import android.graphics.Canvas
+import android.graphics.Paint
+import android.graphics.RectF
+import android.util.AttributeSet
+import android.view.View
+import androidx.core.content.ContextCompat
+
+/**
+ * Horizontal progress bar showing how many QR frames of the current transfer
+ * have been captured (`received / total`), with a filled mint segment
+ * proportional to the fraction. A thin decorative strip over the camera
+ * preview; the exact count stays in the header's "n / N" label.
+ */
+class FrameProgressBar @JvmOverloads constructor(
+    context: Context,
+    attrs: AttributeSet? = null,
+) : View(context, attrs) {
+
+    private val fillPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+        color = ContextCompat.getColor(context, R.color.frame_fill)
+    }
+    private val trackPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+        color = ContextCompat.getColor(context, R.color.frame_track)
+    }
+    private val trackRect = RectF()
+    private val fillRect = RectF()
+    private val cornerRadius = dp(3f)
+
+    private var fraction = 0f
+
+    /** Reset to an empty bar. */
+    fun reset() {
+        fraction = 0f
+        invalidate()
+    }
+
+    /**
+     * Update the fill to [received] out of [total] frames captured.
+     * A zero/unknown total clears the bar.
+     */
+    fun set(total: Int, received: Int) {
+        fraction = if (total > 0) {
+            received.toFloat() / total.toFloat()
+        } else {
+            0f
+        }
+        invalidate()
+    }
+
+    private fun dp(value: Float): Float =
+        resources.displayMetrics.density * value
+
+    override fun onDraw(canvas: Canvas) {
+        super.onDraw(canvas)
+        if (width <= 0 || height <= 0) {
+            return
+        }
+        trackRect.set(0f, 0f, width.toFloat(), height.toFloat())
+        canvas.drawRoundRect(trackRect, cornerRadius, cornerRadius, trackPaint)
+        if (fraction <= 0f) {
+            return
+        }
+        val fillWidth = width * fraction.coerceIn(0f, 1f)
+        fillRect.set(0f, 0f, fillWidth, height.toFloat())
+        canvas.drawRoundRect(fillRect, cornerRadius, cornerRadius, fillPaint)
+    }
+}

android/app/src/main/java/life/after/bitcoin/MainActivity.kt

@@ -0,0 +1,209 @@
+package life.after.bitcoin
+
+import android.Manifest
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.os.Bundle
+import android.util.Log
+import android.widget.Toast
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.appcompat.app.AppCompatActivity
+import androidx.camera.core.CameraSelector
+import androidx.camera.core.ImageAnalysis
+import androidx.camera.core.ImageProxy
+import androidx.camera.core.Preview
+import androidx.camera.lifecycle.ProcessCameraProvider
+import androidx.core.content.ContextCompat
+import com.google.mlkit.vision.barcode.BarcodeScanning
+import com.google.mlkit.vision.barcode.BarcodeScanner
+import com.google.mlkit.vision.barcode.BarcodeScannerOptions
+import com.google.mlkit.vision.barcode.common.Barcode
+import com.google.mlkit.vision.common.InputImage
+import life.after.bitcoin.BalDecoder.AddResult
+import life.after.bitcoin.databinding.ActivityMainBinding
+import java.util.concurrent.Executors
+
+class MainActivity : AppCompatActivity() {
+
+    private lateinit var binding: ActivityMainBinding
+    private lateinit var decoder: BalDecoder
+    private lateinit var barcodeScanner: BarcodeScanner
+
+    private val analyzerExecutor = Executors.newSingleThreadExecutor()
+    private var finished = false
+    private var cameraBound = false
+    private var lastAnalysisMs = 0L
+
+    private val formatLabels: Map<String, String> by lazy {
+        mapOf(
+            "balqr" to getString(R.string.format_balqr),
+            "ur1" to getString(R.string.format_ur1),
+            "ur2" to getString(R.string.format_ur2),
+            "bbqr" to getString(R.string.format_bbqr),
+        )
+    }
+
+    private val requestCameraPermission =
+        registerForActivityResult(ActivityResultContracts.RequestPermission()) { granted ->
+            if (granted) {
+                startCamera()
+            } else {
+                Toast.makeText(this, R.string.permission_denied, Toast.LENGTH_LONG).show()
+            }
+        }
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        binding = ActivityMainBinding.inflate(layoutInflater)
+        setContentView(binding.root)
+
+        decoder = BalDecoder(applicationContext)
+        barcodeScanner = BarcodeScanning.getClient(
+            BarcodeScannerOptions.Builder()
+                .setBarcodeFormats(Barcode.FORMAT_QR_CODE)
+                .build()
+        )
+
+        if (ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA)
+            == PackageManager.PERMISSION_GRANTED
+        ) {
+            startCamera()
+        } else {
+            requestCameraPermission.launch(Manifest.permission.CAMERA)
+        }
+    }
+
+    override fun onResume() {
+        super.onResume()
+        // Returning from the result screen starts a new scan.
+        if (finished) {
+            finished = false
+            decoder.reset()
+            binding.tvFormat.text = getString(R.string.format_placeholder)
+            binding.tvProgress.text = "0 / 0"
+            binding.tvStatus.setText(R.string.status_waiting)
+            binding.frameBar.reset()
+        }
+        if (ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA)
+            == PackageManager.PERMISSION_GRANTED
+        ) {
+            startCamera()
+        }
+    }
+
+    override fun onDestroy() {
+        cameraProvider?.unbindAll()
+        barcodeScanner.close()
+        analyzerExecutor.shutdown()
+        super.onDestroy()
+    }
+
+    private var cameraProvider: ProcessCameraProvider? = null
+
+    private fun startCamera() {
+        if (cameraBound) {
+            return
+        }
+        val providerFuture = ProcessCameraProvider.getInstance(this)
+        providerFuture.addListener({
+            val provider = providerFuture.get()
+            cameraProvider = provider
+
+            val preview = Preview.Builder().build()
+            preview.setSurfaceProvider(binding.previewView.surfaceProvider)
+            val analysis = ImageAnalysis.Builder()
+                .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST)
+                .build()
+            analysis.setAnalyzer(analyzerExecutor) { proxy -> analyze(proxy) }
+
+            try {
+                provider.unbindAll()
+                provider.bindToLifecycle(
+                    this, CameraSelector.DEFAULT_BACK_CAMERA, preview, analysis
+                )
+                cameraBound = true
+            } catch (e: Exception) {
+                Log.e(TAG, "Failed to bind camera", e)
+            }
+        }, ContextCompat.getMainExecutor(this))
+    }
+
+    private fun analyze(proxy: ImageProxy) {
+        val now = System.currentTimeMillis()
+        if (finished || now - lastAnalysisMs < 100) {
+            proxy.close()
+            return
+        }
+        lastAnalysisMs = now
+        val image = proxy.image
+        if (image == null) {
+            proxy.close()
+            return
+        }
+        try {
+            val input = InputImage.fromMediaImage(image, proxy.imageInfo.rotationDegrees)
+            barcodeScanner.process(input)
+                .addOnSuccessListener { barcodes ->
+                    for (barcode in barcodes) {
+                        val value = barcode.rawValue
+                        if (!value.isNullOrEmpty()) {
+                            handleFrame(value)
+                            break
+                        }
+                    }
+                }
+                .addOnCompleteListener { proxy.close() }
+        } catch (e: Exception) {
+            Log.w(TAG, "Frame analysis failure", e)
+            proxy.close()
+        }
+    }
+
+    private fun handleFrame(value: String) {
+        if (finished) {
+            return
+        }
+        when (decoder.add(value)) {
+            AddResult.OK -> {
+                Log.i(TAG, "frame ok fmt=${decoder.format} rcvd=${decoder.received}/${decoder.total} done=${decoder.done}")
+                binding.tvFormat.text = decoder.format?.let { formatLabels[it] }
+                    ?: getString(R.string.format_placeholder)
+                binding.tvProgress.text =
+                    getString(R.string.progress_fmt, decoder.received, decoder.total)
+                binding.frameBar.set(decoder.total, decoder.received)
+                if (decoder.done) {
+                    finishScan()
+                }
+            }
+            AddResult.DUP -> Log.i(TAG, "frame dup")
+            AddResult.GARBAGE -> Log.w(TAG, "frame garbage")
+            AddResult.CONFLICT -> {
+                Log.w(TAG, "format conflict - resetting")
+                decoder.reset()
+                binding.tvFormat.text = getString(R.string.format_placeholder)
+                binding.tvProgress.text = "0 / 0"
+                binding.tvStatus.setText(R.string.conflict_message)
+                binding.frameBar.reset()
+            }
+        }
+    }
+
+    private fun finishScan() {
+        if (finished) {
+            return
+        }
+        finished = true
+        val result = decoder.finish()
+        Log.i(TAG, "FINISH kind=${result.kind} payload=${result.payload.length}B parts=${result.parts.size}")
+        val intent = Intent(this, ResultActivity::class.java).apply {
+            putExtra(ResultActivity.EXTRA_KIND, result.kind)
+            putExtra(ResultActivity.EXTRA_PAYLOAD, result.payload)
+            putStringArrayListExtra(ResultActivity.EXTRA_PARTS, ArrayList(result.parts))
+        }
+        startActivity(intent)
+    }
+
+    companion object {
+        private const val TAG = "BalReader"
+    }
+}

android/app/src/main/java/life/after/bitcoin/ResultActivity.kt

@@ -0,0 +1,100 @@
+package life.after.bitcoin
+
+import android.content.ClipData
+import android.content.ClipboardManager
+import android.content.Context
+import android.content.Intent
+import android.net.Uri
+import android.os.Bundle
+import android.widget.Toast
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.appcompat.app.AppCompatActivity
+import life.after.bitcoin.databinding.ActivityResultBinding
+import org.json.JSONException
+import org.json.JSONObject
+
+class ResultActivity : AppCompatActivity() {
+
+    private lateinit var binding: ActivityResultBinding
+    private var kind = "txs"
+    private var payload = ""
+    private var parts: List<String> = emptyList()
+
+    private val saveWillPicker =
+        registerForActivityResult(ActivityResultContracts.CreateDocument("application/json")) { uri: Uri? ->
+            saveTo(uri)
+        }
+    private val saveTxsPicker =
+        registerForActivityResult(ActivityResultContracts.CreateDocument("text/plain")) { uri: Uri? ->
+            saveTo(uri)
+        }
+
+    private fun saveTo(uri: Uri?) {
+        if (uri != null) {
+            contentResolver.openOutputStream(uri)?.use { it.write(payload.toByteArray()) }
+        }
+    }
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        binding = ActivityResultBinding.inflate(layoutInflater)
+        setContentView(binding.root)
+
+        kind = intent.getStringExtra(EXTRA_KIND) ?: "txs"
+        payload = intent.getStringExtra(EXTRA_PAYLOAD) ?: ""
+        parts = intent.getStringArrayListExtra(EXTRA_PARTS) ?: emptyList()
+
+        binding.tvKind.text =
+            getString(if (kind == "will") R.string.result_kind_will else R.string.result_kind_txs)
+        binding.tvContent.text = pretty(payload)
+
+        binding.btnCopy.setOnClickListener {
+            val clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
+            clipboard.setPrimaryClip(ClipData.newPlainText("BAL transfer", payload))
+            Toast.makeText(this, R.string.copied_toast, Toast.LENGTH_SHORT).show()
+        }
+        binding.btnShare.setOnClickListener {
+            val send = Intent(Intent.ACTION_SEND).apply {
+                type = "text/plain"
+                putExtra(Intent.EXTRA_TEXT, payload)
+            }
+            startActivity(Intent.createChooser(send, null))
+        }
+        binding.btnSave.setOnClickListener { saveFile() }
+        binding.btnScanAnother.setOnClickListener { finish() }
+    }
+
+    private fun pretty(json: String): String {
+        if (kind == "will") {
+            try {
+                return JSONObject(json).toString(2)
+            } catch (_: JSONException) {
+                return json
+            }
+        }
+        // Transaction list: one numbered line per tx.
+        if (parts.isNotEmpty()) {
+            return parts.mapIndexed { i, tx -> "%d. %s".format(i + 1, tx) }
+                .joinToString("\n")
+        }
+        return json
+    }
+
+    private fun saveFile() {
+        val name = if (kind == "will") {
+            getString(R.string.save_file_will)
+        } else {
+            getString(R.string.save_file_txs)
+        }
+        // ActivityResultContracts.CreateDocument takes the suggested file name;
+        // it maps it to ACTION_CREATE_DOCUMENT + EXTRA_TITLE internally.
+        val picker = if (kind == "will") saveWillPicker else saveTxsPicker
+        picker.launch(name)
+    }
+
+    companion object {
+        const val EXTRA_KIND = "kind"
+        const val EXTRA_PAYLOAD = "payload"
+        const val EXTRA_PARTS = "parts"
+    }
+}

android/app/src/main/python/bal/core/__init__.py

@@ -0,0 +1,21 @@
+"""
+bal.core
+========
+
+Pure business-logic layer of the Bitcoin After Life (BAL) Electrum plugin.
+
+Everything in this sub-package MUST stay completely free of any GUI / Qt
+imports.  The rule of thumb is:
+
+    * ``bal.core``      -> "what the plugin does" (inheritance rules, building
+                           and validating transactions, talking to
+                           will-executor servers, persistence helpers).
+    * ``bal.gui``       -> "how it looks" (Qt widgets, dialogs, list views).
+
+Keeping the two apart is the main motivation behind this rewrite: the original
+code mixed transaction-building logic and presentation inside a single
+4000-line ``qt.py`` module, which made the delicate Bitcoin logic hard to audit.
+
+No behaviour is changed with respect to the original plugin; the code has only
+been reorganised and documented.
+"""

android/app/src/main/python/bal/core/qrtransfer.py

@@ -0,0 +1,304 @@
+"""
+bal.core.qrtransfer
+===================
+
+GUI-free helpers for moving BAL will data between devices via QR codes or
+the Electrum ``audio_modem`` plugin (see ``PLAN_QR_TRANSFER.md``).
+
+Scope
+-----
+* converts will transactions into a compact ``transfer_string``
+  (newline-joined serialized transactions, optionally zlib + base64
+  compressed);
+* splits that string into fixed-size ``BAL1<TTT><iii><flag>`` frames for
+  multi-QR export, and reassembles/validates them on import.
+
+Wire format (v2, compact)
+-------------------------
+A frame is::
+
+    BAL1<TTT><iii><flag><payload>
+
+* ``BAL1``    - magic + format era (4 chars).
+* ``TTT``     - frame total as exactly 3 base36 digits (1-based, cap 46655).
+* ``iii``     - frame index as exactly 3 base36 digits (1-based).
+* ``flag``    - one char: ``Z`` (zlib + base64) or ``0`` (plain ASCII).
+* ``payload`` - every other character of the frame; the payloads of all
+  frames, concatenated in index order, rebuild the transfer string.
+
+The fixed 11-char header replaces the legacy ``BALQR1|N|i|flags|`` form
+(same 5 pieces of information) without any pipe separator, so the whole
+frame is scan-friendly and the overhead no longer grows with the frame
+count.  Legacy ``BALQR1|…`` frames are still accepted on import.
+
+The audio-modem channel deliberately bypasses the framing helpers here
+(PLAN_QR_TRANSFER.md section 4.4): its transport compresses internally and
+carries the whole transfer string in a single blob, so callers only use
+:func:`encode_transfer` / :func:`decode_transfer`.
+
+This module never imports Qt or any Electrum GUI code (house rule).
+"""
+
+from __future__ import annotations
+
+import base64
+import zlib
+
+MAGIC = "BALQR"
+VERSION = 1
+FLAG_COMPRESSED = "Z"
+FLAG_PLAIN = "0"
+
+# 4 standard presets (label, payload budget in bytes per QR). Ordered from
+# low-resolution cameras to high-resolution cameras (owner decision D5).
+CHUNK_PRESETS = (
+    ("Small - ~150 bytes/QR (low-res cameras)", 150),
+    ("Medium - ~400 bytes/QR", 400),
+    ("Large - ~900 bytes/QR", 900),
+    ("XL - ~1800 bytes/QR (high-res cameras)", 1800),
+)
+
+# Smallest allowed payload budget per frame, below which the frame header
+# could consume the whole budget.
+MIN_CHUNK_SIZE = 40
+
+# Legacy wire format (still imported); the exporter emits the v2 form below.
+_FRAME_MAGIC_V1 = MAGIC + str(VERSION)
+
+# Compact v2 wire format: fixed-width base36 count fields, no separators.
+_FRAME_MAGIC_V2 = "BAL1"
+_BASE36_DIGITS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+_BASE36_WIDTH = 3
+_HEADER_V2_LEN = len(_FRAME_MAGIC_V2) + 2 * _BASE36_WIDTH + 1
+_MAX_TOTAL = 36 ** _BASE36_WIDTH - 1
+
+
+class QrTransferError(ValueError):
+    """Base error for will QR / audio transfer processing."""
+
+
+class MissingFramesError(QrTransferError):
+    """Some frame indices of a multi-QR transfer are missing."""
+
+    def __init__(self, missing):
+        self.missing = list(missing)
+        super().__init__("Missing QR frames: {}".format(self.missing))
+
+
+class InconsistentTotalError(QrTransferError):
+    """Frames disagree about the advertised frame total."""
+
+
+def encode_transfer(tx_strings, compress=False):
+    """Join serialized transaction strings into a transfer string.
+
+    ``compress=True`` wraps the joined text in zlib + base64 (ASCII-safe) so
+    the whole bundle shrinks before being printed/scanned. The optional flag
+    of the frame header lets the importer reverse this automatically.
+    """
+    return __compress("\n".join(tx_strings), enabled=compress)
+
+
+def encode_transfer_best(tx_strings):
+    """Encode ``tx_strings`` with the smaller of plain vs compressed form.
+
+    Returns ``(transfer_string, compressed: bool)``.  Compressed wins only
+    when zlib + base64 really is shorter (best-of, never larger).
+    """
+    joined = "\n".join(tx_strings)
+    plain = joined
+    compressed = __compress(joined, enabled=True)
+    if len(compressed) < len(plain):
+        return compressed, True
+    return plain, False
+
+
+def decode_transfer(transfer_string, compressed):
+    """Inverse of :func:`encode_transfer`.
+
+    Returns the list of serialized transaction strings; empty frames are
+    dropped so a trailing newline (or an empty payload) cannot produce an
+    empty trailing element.
+    """
+    text = __decompress(transfer_string, enabled=compressed)
+    return [part for part in text.split("\n") if part]
+
+
+def split_frames(transfer_string, chunk_size, compressed=False):
+    """Split ``transfer_string`` into full compact ``BAL1`` frames.
+
+    Every returned frame has the fixed 11-char v2 header followed by its
+    share of the payload, so each frame is at most ``chunk_size`` characters
+    long.  ``compressed`` stamps the ``Z`` flag into every frame so the
+    importer knows how to reverse the encoding.
+
+    Raises :class:`QrTransferError` when ``chunk_size`` is too small to hold
+    the header plus any payload, or when the transfer needs more than
+    :data:`_MAX_TOTAL` frames.
+    """
+    flag = FLAG_COMPRESSED if compressed else FLAG_PLAIN
+    total = __compute_total(len(transfer_string), chunk_size)
+    budget = chunk_size - _HEADER_V2_LEN
+    frames = []
+    pos = 0
+    length = len(transfer_string)
+    for index in range(1, total + 1):
+        end = min(pos + budget, length)
+        frames.append(
+            _FRAME_MAGIC_V2
+            + _base36(total)
+            + _base36(index)
+            + flag
+            + transfer_string[pos:end]
+        )
+        pos = end
+    if pos < length:
+        # __compute_total guarantees this cannot happen; keep a safety net.
+        raise QrTransferError("internal error: frames did not cover the transfer string")
+    return frames
+
+
+def parse_frame(frame):
+    """Parse a single frame.
+
+    Accepts both the legacy ``BALQR1|total|index|flags|payload`` form and
+    the compact ``BAL1<total><index><flag><payload>`` v2 form.
+
+    Returns ``(total, index, compressed: bool, payload: str)``. Raises
+    :class:`QrTransferError` on malformed input (bad magic/version, wrong
+    arity, non-integer or out-of-range frame numbers, unknown flags).
+    """
+    if frame.startswith(_FRAME_MAGIC_V2):
+        return _parse_v2(frame)
+    return _parse_v1(frame)
+
+
+def assemble(frames, total):
+    """Concatenate frame payloads back into a transfer string.
+
+    ``frames`` maps 1-based index -> payload. Every index ``1..total`` must
+    be present (else :class:`MissingFramesError`) and no index may exceed
+    ``total`` (else :class:`InconsistentTotalError`).
+    """
+    if total < 1:
+        raise QrTransferError("invalid frame total")
+    missing = [index for index in range(1, total + 1) if index not in frames]
+    if missing:
+        raise MissingFramesError(missing)
+    extra = [index for index in frames if index > total]
+    if extra:
+        raise InconsistentTotalError()
+    return "".join(frames[index] for index in range(1, total + 1))
+
+
+def preset_index_for_chunk_size(chunk_size):
+    """Return the :data:`CHUNK_PRESETS` index whose budget best matches a size."""
+    best, best_diff = 0, abs(chunk_size - CHUNK_PRESETS[0][1])
+    for index, (_label, budget) in enumerate(CHUNK_PRESETS):
+        diff = abs(chunk_size - budget)
+        if diff < best_diff:
+            best, best_diff = index, diff
+    return best
+
+
+# --------------------------------------------------------------------------- #
+# Internals
+# --------------------------------------------------------------------------- #
+
+def __compress(text, *, enabled):
+    if not enabled:
+        return text
+    return base64.b64encode(zlib.compress(text.encode("utf-8"))).decode("ascii")
+
+
+def __decompress(text, *, enabled):
+    if not enabled:
+        return text
+    return zlib.decompress(base64.b64decode(text.encode("ascii"))).decode("utf-8")
+
+
+def _base36(n):
+    """Zero-padded :data:`_BASE36_WIDTH` base36 render of ``n``."""
+    if not 0 <= n <= _MAX_TOTAL:
+        raise QrTransferError("BAL QR part number out of range: {}".format(n))
+    chars = []
+    for _ in range(_BASE36_WIDTH):
+        chars.append(_BASE36_DIGITS[n % 36])
+        n //= 36
+    return "".join(reversed(chars))
+
+
+def _base36_decode(text):
+    """Inverse of :func:`_base36`; raises ``ValueError`` on bad input."""
+    if len(text) != _BASE36_WIDTH or any(c not in _BASE36_DIGITS for c in text):
+        raise ValueError(text)
+    n = 0
+    for c in text:
+        n = n * 36 + _BASE36_DIGITS.index(c)
+    return n
+
+
+def _parse_v1(frame):
+    parts = frame.split("|", maxsplit=4)
+    if len(parts) != 5:
+        raise QrTransferError("Not a BAL will QR (bad frame structure)")
+    magic_seen, total_s, index_s, flags, payload = parts
+    if magic_seen != _FRAME_MAGIC_V1:
+        raise QrTransferError("Not a BAL will QR (unknown magic/version)")
+    try:
+        total = int(total_s)
+        index = int(index_s)
+    except ValueError as e:
+        raise QrTransferError("Not a BAL will QR (bad frame numbers)") from e
+    if total < 1 or not 1 <= index <= total:
+        raise QrTransferError("Not a BAL will QR (frame numbering out of range)")
+    if flags not in ("", FLAG_COMPRESSED):
+        raise QrTransferError("Not a BAL will QR (unknown flags)")
+    return total, index, flags == FLAG_COMPRESSED, payload
+
+
+def _parse_v2(frame):
+    if len(frame) < _HEADER_V2_LEN:
+        raise QrTransferError("Not a BAL will QR (bad frame structure)")
+    # Magic is length _FRAME_MAGIC_V2; the two base36 fields and the flag
+    # make up the rest of the fixed header.
+    offset = len(_FRAME_MAGIC_V2)
+    total_s = frame[offset : offset + _BASE36_WIDTH]
+    index_s = frame[offset + _BASE36_WIDTH : offset + 2 * _BASE36_WIDTH]
+    flag = frame[offset + 2 * _BASE36_WIDTH]
+    try:
+        total = _base36_decode(total_s)
+        index = _base36_decode(index_s)
+    except ValueError:
+        raise QrTransferError("Not a BAL will QR (bad frame numbers)") from None
+    if total < 1 or not 1 <= index <= total:
+        raise QrTransferError("Not a BAL will QR (frame numbering out of range)")
+    if flag not in (FLAG_PLAIN, FLAG_COMPRESSED):
+        raise QrTransferError("Not a BAL will QR (unknown flags)")
+    payload = frame[_HEADER_V2_LEN:]
+    return total, index, flag == FLAG_COMPRESSED, payload
+
+
+def __compute_total(transfer_len, chunk_size):
+    """Smallest frame count whose budget covers the whole transfer string.
+
+    The v2 header is fixed-width, so the budget is constant and the count is
+    a plain ceiling division, capped at :data:`_MAX_TOTAL`.
+    """
+    if chunk_size < MIN_CHUNK_SIZE:
+        raise QrTransferError(
+            "chunk size too small to hold a BAL QR frame: {}".format(chunk_size)
+        )
+    budget = chunk_size - _HEADER_V2_LEN
+    if budget <= 0:
+        raise QrTransferError(
+            "chunk size too small for the BAL QR frame header: {}".format(chunk_size)
+        )
+    total = -(-transfer_len // budget)
+    if total < 1:
+        total = 1
+    if total > _MAX_TOTAL:
+        raise QrTransferError(
+            "BAL QR transfer demands too many frames: {}".format(total)
+        )
+    return total

android/app/src/main/python/balreader/__init__.py

@@ -0,0 +1 @@
+"""Android reader helpers built on the bundled plugin codecs."""

android/app/src/main/python/balreader/bridge.py

@@ -0,0 +1,33 @@
+"""Kotlin-facing helper: runs the plugin's exact import tail and returns JSON.
+
+A serializable JSON contract keeps the Chaquopy bridge tiny on the Kotlin side
+and avoids exposing ``PyObject`` tuple/container indexing to it.  The steps are
+the same three calls the plugin's import dialog performs:
+
+    session.resolve()          -> (transfer_text, compressed)
+    qrtransfer.decode_transfer -> parts
+    balreader.payload.decode_will_payload -> ("will"|"txs", data)
+"""
+
+import json
+
+from bal.core import qrtransfer as _qrtransfer
+from balreader import payload as _payload
+
+
+def finish(session):
+    """Run the import tail on a live ``AnimatedQrSession``.
+
+    Returns a JSON string ``{"kind": ..., "payload": ..., "parts": [...]}``
+    with ``kind`` either ``"will"`` or ``"txs"``.  On any failure it returns
+    ``{"kind": "error", "payload": <message>, "parts": []}`` so a misbehaving
+    session can never crash the UI thread.
+    """
+    try:
+        transfer, compressed = session.resolve()
+        parts = list(_qrtransfer.decode_transfer(transfer, compressed))
+        payload = "\n".join(parts)
+        kind, _data = _payload.decode_will_payload(payload)
+        return json.dumps({"kind": kind, "payload": payload, "parts": parts})
+    except Exception as exc:  # noqa: BLE001 - defensive bridge boundary
+        return json.dumps({"kind": "error", "payload": str(exc), "parts": []})

android/app/src/main/python/balreader/payload.py

@@ -0,0 +1,33 @@
+"""Will-payload autodetection for the BAL Reader app.
+
+This file is a verbatim copy of ``decode_will_payload`` from
+``bal/gui/qt/dialogs.py``.  ``android/test_chain/verify_chain.py`` compares the
+two functions result-for-result so they can never drift apart.
+
+Keep the function body identical to the plugin source.
+"""
+
+import json
+import re
+from typing import Any
+
+
+def decode_will_payload(text) -> tuple[Any, Any]:
+    """Autodetect: whole-will JSON or transaction list?
+
+    Returns ``("will", dict_of_willitems_data)`` when ``text`` is a JSON
+    object whose values are dicts containing a ``"tx"`` key (the whole-will
+    format produced by :meth:`BalWindow.export_json_file` and friends).
+    Otherwise returns ``("txs", [tx_strings])`` where the transaction
+    strings were split on commas and/or newlines.
+    """
+    text = text.strip()
+    try:
+        data = json.loads(text)
+    except (json.JSONDecodeError, ValueError):
+        data = None
+    if isinstance(data, dict) and data:
+        if all(isinstance(v, dict) and "tx" in v for v in data.values()):
+            return ("will", data)
+    parts = [p for p in re.split(r"[,\r\n]+", text) if p.strip()]
+    return ("txs", parts)

android/app/src/main/res/drawable/ic_launcher.xml

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="utf-8"?>
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportWidth="108"
+    android:viewportHeight="108">
+    <path
+        android:fillColor="#0B3D2E"
+        android:pathData="M0,0h108v108h-108z" />
+    <path
+        android:fillColor="#FFFFFF"
+        android:pathData="M14,14h22v22h-22z" />
+    <path
+        android:fillColor="#0B3D2E"
+        android:pathData="M19,19h12v12h-12z" />
+    <path
+        android:fillColor="#FFFFFF"
+        android:pathData="M72,14h22v22h-22z" />
+    <path
+        android:fillColor="#0B3D2E"
+        android:pathData="M77,19h12v12h-12z" />
+    <path
+        android:fillColor="#FFFFFF"
+        android:pathData="M14,72h22v22h-22z" />
+    <path
+        android:fillColor="#0B3D2E"
+        android:pathData="M19,77h12v12h-12z" />
+    <path
+        android:fillColor="#FFFFFF"
+        android:pathData="M14,42h4v4h-4z M22,42h4v4h-4z M14,50h4v4h-4z M22,50h4v4h-4z M14,58h4v4h-4z M30,42h4v4h-4z M30,50h4v4h-4z M14,66h4v4h-4z" />
+    <path
+        android:fillColor="#FFFFFF"
+        android:pathData="M52,14h4v4h-4z M60,14h4v4h-4z M52,22h4v4h-4z M68,14h4v4h-4z M52,30h4v4h-4z M56,42h4v4h-4z M64,42h4v4h-4z M56,50h4v4h-4z M72,42h4v4h-4z M56,58h4v4h-4z M64,58h4v4h-4z M56,66h4v4h-4z M64,66h4v4h-4z M72,58h4v4h-4z M64,74h4v4h-4z M72,66h4v4h-4z" />
+</vector>

android/app/src/main/res/layout/activity_main.xml

@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="utf-8"?>
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    android:orientation="vertical"
+    android:background="@android:color/black">
+
+    <LinearLayout
+        android:layout_width="match_parent"
+        android:layout_height="wrap_content"
+        android:orientation="horizontal"
+        android:gravity="center_vertical"
+        android:paddingHorizontal="12dp"
+        android:paddingVertical="8dp"
+        android:background="#1A1A1A">
+
+        <TextView
+            android:id="@+id/tv_format"
+            android:layout_width="0dp"
+            android:layout_height="wrap_content"
+            android:layout_weight="1"
+            android:text="@string/format_placeholder"
+            android:textColor="#9BE8C0"
+            android:textStyle="bold"
+            android:textSize="14sp" />
+
+        <TextView
+            android:id="@+id/tv_progress"
+            android:layout_width="wrap_content"
+            android:layout_height="wrap_content"
+            android:text="0 / 0"
+            android:textColor="#FFFFFF"
+            android:textSize="14sp" />
+    </LinearLayout>
+
+    <life.after.bitcoin.FrameProgressBar
+        android:id="@+id/frame_bar"
+        android:layout_width="match_parent"
+        android:layout_height="6dp"
+        android:layout_marginHorizontal="12dp"
+        android:layout_marginTop="4dp"
+        android:layout_marginBottom="4dp" />
+
+    <androidx.camera.view.PreviewView
+        android:id="@+id/preview_view"
+        android:layout_width="match_parent"
+        android:layout_height="0dp"
+        android:layout_weight="1" />
+
+    <TextView
+        android:id="@+id/tv_status"
+        android:layout_width="match_parent"
+        android:layout_height="wrap_content"
+        android:padding="10dp"
+        android:gravity="center"
+        android:text="@string/status_waiting"
+        android:textColor="#CFCFCF"
+        android:textSize="14sp" />
+</LinearLayout>

android/app/src/main/res/layout/activity_result.xml

@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="utf-8"?>
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    android:orientation="vertical"
+    android:padding="12dp">
+
+    <TextView
+        android:id="@+id/tv_kind"
+        android:layout_width="match_parent"
+        android:layout_height="wrap_content"
+        android:textSize="16sp"
+        android:textStyle="bold"
+        android:textColor="?android:attr/textColorPrimary"
+        android:paddingBottom="8dp" />
+
+    <ScrollView
+        android:layout_width="match_parent"
+        android:layout_height="0dp"
+        android:layout_weight="1"
+        android:background="?android:attr/colorBackground">
+
+        <TextView
+            android:id="@+id/tv_content"
+            android:layout_width="match_parent"
+            android:layout_height="wrap_content"
+            android:fontFamily="monospace"
+            android:textIsSelectable="true"
+            android:textSize="12sp"
+            android:textColor="?android:attr/textColorPrimary"
+            android:padding="8dp" />
+    </ScrollView>
+
+    <LinearLayout
+        android:layout_width="match_parent"
+        android:layout_height="wrap_content"
+        android:orientation="horizontal"
+        android:paddingTop="12dp">
+
+        <Button
+            android:id="@+id/btn_copy"
+            android:layout_width="0dp"
+            android:layout_height="wrap_content"
+            android:layout_weight="1"
+            android:text="@string/action_copy" />
+
+        <Button
+            android:id="@+id/btn_share"
+            android:layout_width="0dp"
+            android:layout_height="wrap_content"
+            android:layout_weight="1"
+            android:text="@string/action_share" />
+
+        <Button
+            android:id="@+id/btn_save"
+            android:layout_width="0dp"
+            android:layout_height="wrap_content"
+            android:layout_weight="1"
+            android:text="@string/action_save" />
+    </LinearLayout>
+
+    <Button
+        android:id="@+id/btn_scan_another"
+        android:layout_width="match_parent"
+        android:layout_height="wrap_content"
+        android:text="@string/action_scan_another" />
+</LinearLayout>

android/app/src/main/res/values/colors.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <color name="frame_fill">#9BE8C0</color>
+    <color name="frame_track">#3A3A3A</color>
+</resources>

android/app/src/main/res/values/strings.xml

@@ -0,0 +1,24 @@
+<resources>
+    <string name="app_name">BAL Reader</string>
+
+    <string name="status_waiting">Point the camera at the QR screen</string>
+    <string name="format_placeholder">—</string>
+    <string name="progress_fmt">%1$d / %2$d</string>
+
+    <string name="format_balqr">BAL QR</string>
+    <string name="format_ur1">BC-UR v1</string>
+    <string name="format_ur2">BC-UR v2</string>
+    <string name="format_bbqr">BBQR</string>
+
+    <string name="result_kind_will">Whole will (JSON)</string>
+    <string name="result_kind_txs">Transaction list</string>
+    <string name="action_copy">Copy</string>
+    <string name="action_share">Share</string>
+    <string name="action_save">Save</string>
+    <string name="action_scan_another">Scan another</string>
+    <string name="copied_toast">Transfer copied to clipboard</string>
+    <string name="save_file_will">will.json</string>
+    <string name="save_file_txs">will_tx.txt</string>
+    <string name="permission_denied">Camera permission is required to scan QR codes.</string>
+    <string name="conflict_message">The QR switched to a different transfer. Let it rescan.</string>
+</resources>

android/app/src/main/res/values/themes.xml

@@ -0,0 +1,3 @@
+<resources>
+    <style name="Theme.BalReader" parent="Theme.AppCompat.DayNight.NoActionBar" />
+</resources>

android/build.gradle.kts

@@ -0,0 +1,7 @@
+// Top-level build file: plugin versions only. See the docs for the full
+// compatibility matrix (Chaquopy 17 requires AGP 7.3-9.2 and minSdk 24).
+plugins {
+    id("com.android.application") version "8.10.0" apply false
+    id("org.jetbrains.kotlin.android") version "2.0.21" apply false
+    id("com.chaquo.python") version "17.0.0" apply false
+}

android/gradle.properties

@@ -0,0 +1,5 @@
+org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
+org.gradle.parallel=true
+android.useAndroidX=true
+android.nonTransitiveRClass=true
+kotlin.code.style=official

android/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.14-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

android/gradlew

@@ -0,0 +1,251 @@
+#!/bin/sh
+
+#
+# Copyright © 2015-2021 the original authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+##############################################################################
+#
+#   Gradle start up script for POSIX generated by Gradle.
+#
+#   Important for running:
+#
+#   (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is
+#       noncompliant, but you have some other compliant shell such as ksh or
+#       bash, then to run this script, type that shell name before the whole
+#       command line, like:
+#
+#           ksh Gradle
+#
+#       Busybox and similar reduced shells will NOT work, because this script
+#       requires all of these POSIX shell features:
+#         * functions;
+#         * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,
+#           «${var#prefix}», «${var%suffix}», and «$( cmd )»;
+#         * compound commands having a testable exit status, especially «case»;
+#         * various built-in commands including «command», «set», and «ulimit».
+#
+#   Important for patching:
+#
+#   (2) This script targets any POSIX shell, so it avoids extensions provided
+#       by Bash, Ksh, etc; in particular arrays are avoided.
+#
+#       The "traditional" practice of packing multiple parameters into a
+#       space-separated string is a well documented source of bugs and security
+#       problems, so this is (mostly) avoided, by progressively accumulating
+#       options in "$@", and eventually passing that to Java.
+#
+#       Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,
+#       and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;
+#       see the in-line comments for details.
+#
+#       There are tweaks for specific operating systems such as AIX, CygWin,
+#       Darwin, MinGW, and NonStop.
+#
+#   (3) This script is generated from the Groovy template
+#       https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       within the Gradle project.
+#
+#       You can find Gradle at https://github.com/gradle/gradle/.
+#
+##############################################################################
+
+# Attempt to set APP_HOME
+
+# Resolve links: $0 may be a link
+app_path=$0
+
+# Need this for daisy-chained symlinks.
+while
+    APP_HOME=${app_path%"${app_path##*/}"}  # leaves a trailing /; empty if no leading path
+    [ -h "$app_path" ]
+do
+    ls=$( ls -ld "$app_path" )
+    link=${ls#*' -> '}
+    case $link in             #(
+      /*)   app_path=$link ;; #(
+      *)    app_path=$APP_HOME$link ;;
+    esac
+done
+
+# This is normally unused
+# shellcheck disable=SC2034
+APP_BASE_NAME=${0##*/}
+# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
+APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s\n' "$PWD" ) || exit
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD=maximum
+
+warn () {
+    echo "$*"
+} >&2
+
+die () {
+    echo
+    echo "$*"
+    echo
+    exit 1
+} >&2
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+nonstop=false
+case "$( uname )" in                #(
+  CYGWIN* )         cygwin=true  ;; #(
+  Darwin* )         darwin=true  ;; #(
+  MSYS* | MINGW* )  msys=true    ;; #(
+  NONSTOP* )        nonstop=true ;;
+esac
+
+CLASSPATH="\\\"\\\""
+
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+        # IBM's JDK on AIX uses strange locations for the executables
+        JAVACMD=$JAVA_HOME/jre/sh/java
+    else
+        JAVACMD=$JAVA_HOME/bin/java
+    fi
+    if [ ! -x "$JAVACMD" ] ; then
+        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+else
+    JAVACMD=java
+    if ! command -v java >/dev/null 2>&1
+    then
+        die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+fi
+
+# Increase the maximum file descriptors if we can.
+if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
+    case $MAX_FD in #(
+      max*)
+        # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        MAX_FD=$( ulimit -H -n ) ||
+            warn "Could not query maximum file descriptor limit"
+    esac
+    case $MAX_FD in  #(
+      '' | soft) :;; #(
+      *)
+        # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        ulimit -n "$MAX_FD" ||
+            warn "Could not set maximum file descriptor limit to $MAX_FD"
+    esac
+fi
+
+# Collect all arguments for the java command, stacking in reverse order:
+#   * args from the command line
+#   * the main class name
+#   * -classpath
+#   * -D...appname settings
+#   * --module-path (only if needed)
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.
+
+# For Cygwin or MSYS, switch paths to Windows format before running java
+if "$cygwin" || "$msys" ; then
+    APP_HOME=$( cygpath --path --mixed "$APP_HOME" )
+    CLASSPATH=$( cygpath --path --mixed "$CLASSPATH" )
+
+    JAVACMD=$( cygpath --unix "$JAVACMD" )
+
+    # Now convert the arguments - kludge to limit ourselves to /bin/sh
+    for arg do
+        if
+            case $arg in                                #(
+              -*)   false ;;                            # don't mess with options #(
+              /?*)  t=${arg#/} t=/${t%%/*}              # looks like a POSIX filepath
+                    [ -e "$t" ] ;;                      #(
+              *)    false ;;
+            esac
+        then
+            arg=$( cygpath --path --ignore --mixed "$arg" )
+        fi
+        # Roll the args list around exactly as many times as the number of
+        # args, so each arg winds up back in the position where it started, but
+        # possibly modified.
+        #
+        # NB: a `for` loop captures its iteration list before it begins, so
+        # changing the positional parameters here affects neither the number of
+        # iterations, nor the values presented in `arg`.
+        shift                   # remove old arg
+        set -- "$@" "$arg"      # push replacement arg
+    done
+fi
+
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='-Dfile.encoding=UTF-8 "-Xmx64m" "-Xms64m"'
+
+# Collect all arguments for the java command:
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,
+#     and any embedded shellness will be escaped.
+#   * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be
+#     treated as '${Hostname}' itself on the command line.
+
+set -- \
+        "-Dorg.gradle.appname=$APP_BASE_NAME" \
+        -classpath "$CLASSPATH" \
+        -jar "$APP_HOME/gradle/wrapper/gradle-wrapper.jar" \
+        "$@"
+
+# Stop when "xargs" is not available.
+if ! command -v xargs >/dev/null 2>&1
+then
+    die "xargs is not available"
+fi
+
+# Use "xargs" to parse quoted args.
+#
+# With -n1 it outputs one arg per line, with the quotes and backslashes removed.
+#
+# In Bash we could simply go:
+#
+#   readarray ARGS < <( xargs -n1 <<<"$var" ) &&
+#   set -- "${ARGS[@]}" "$@"
+#
+# but POSIX shell has neither arrays nor command substitution, so instead we
+# post-process each arg (as a line of input to sed) to backslash-escape any
+# character that might be a shell metacharacter, then use eval to reverse
+# that process (while maintaining the separation between arguments), and wrap
+# the whole thing up as a single "set" statement.
+#
+# This will of course break if any of these variables contains a newline or
+# an unmatched quote.
+#
+
+eval "set -- $(
+        printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" |
+        xargs -n1 |
+        sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' |
+        tr '\n' ' '
+    )" '"$@"'
+
+exec "$JAVACMD" "$@"

android/gradlew.bat

@@ -0,0 +1,94 @@
+@rem
+@rem Copyright 2015 the original author or authors.
+@rem
+@rem Licensed under the Apache License, Version 2.0 (the "License");
+@rem you may not use this file except in compliance with the License.
+@rem You may obtain a copy of the License at
+@rem
+@rem      https://www.apache.org/licenses/LICENSE-2.0
+@rem
+@rem Unless required by applicable law or agreed to in writing, software
+@rem distributed under the License is distributed on an "AS IS" BASIS,
+@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+@rem See the License for the specific language governing permissions and
+@rem limitations under the License.
+@rem
+@rem SPDX-License-Identifier: Apache-2.0
+@rem
+
+@if "%DEBUG%"=="" @echo off
+@rem ##########################################################################
+@rem
+@rem  Gradle startup script for Windows
+@rem
+@rem ##########################################################################
+
+@rem Set local scope for the variables with windows NT shell
+if "%OS%"=="Windows_NT" setlocal
+
+set DIRNAME=%~dp0
+if "%DIRNAME%"=="" set DIRNAME=.
+@rem This is normally unused
+set APP_BASE_NAME=%~n0
+set APP_HOME=%DIRNAME%
+
+@rem Resolve any "." and ".." in APP_HOME to make it shorter.
+for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
+
+@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+set DEFAULT_JVM_OPTS=-Dfile.encoding=UTF-8 "-Xmx64m" "-Xms64m"
+
+@rem Find java.exe
+if defined JAVA_HOME goto findJavaFromJavaHome
+
+set JAVA_EXE=java.exe
+%JAVA_EXE% -version >NUL 2>&1
+if %ERRORLEVEL% equ 0 goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+goto fail
+
+:findJavaFromJavaHome
+set JAVA_HOME=%JAVA_HOME:"=%
+set JAVA_EXE=%JAVA_HOME%/bin/java.exe
+
+if exist "%JAVA_EXE%" goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+goto fail
+
+:execute
+@rem Setup the command line
+
+set CLASSPATH=
+
+
+@rem Execute Gradle
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" -jar "%APP_HOME%\gradle\wrapper\gradle-wrapper.jar" %*
+
+:end
+@rem End local scope for the variables with windows NT shell
+if %ERRORLEVEL% equ 0 goto mainEnd
+
+:fail
+rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
+rem the _cmd.exe /c_ return code!
+set EXIT_CODE=%ERRORLEVEL%
+if %EXIT_CODE% equ 0 set EXIT_CODE=1
+if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
+exit /b %EXIT_CODE%
+
+:mainEnd
+if "%OS%"=="Windows_NT" endlocal
+
+:omega

android/scripts/build_apk.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""Build the BAL Reader Android APK via Gradle.
+
+Re-synchronises the bundled codec modules into the app (so the APK always
+carries the current ``bal/core`` sources), then invokes the Gradle wrapper to
+produce the APK, and finally prints the artifact path, size and sha256.
+
+Run from the repository root (any Python 3.8+, needs JDK 17 and an Android
+SDK; the first build also needs a network connection for Gradle downloads):
+
+    python3 android/scripts/build_apk.py             # debug APK
+    python3 android/scripts/build_apk.py --release   # (unsigned) release APK
+    python3 android/scripts/build_apk.py --no-sync   # skip codec re-sync
+    python3 android/scripts/build_apk.py --offline   # gradle --offline
+
+The APK is written under ``android/app/build/outputs/apk/``.
+"""
+
+import argparse
+import hashlib
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+ANDROID_DIR = REPO_ROOT / "android"
+GRADLEW = ANDROID_DIR / "gradlew"
+LOCAL_PROPERTIES = ANDROID_DIR / "local.properties"
+WRAPPER_JAR = ANDROID_DIR / "gradle" / "wrapper" / "gradle-wrapper.jar"
+
+VARIANTS = {
+    "debug": "assembleDebug",
+    "release": "assembleRelease",
+}
+APK_REL = {
+    "debug": Path("app") / "build" / "outputs" / "apk" / "debug" / "app-debug.apk",
+    "release": Path("app") / "build" / "outputs" / "apk" / "release" / "app-release-unsigned.apk",
+}
+
+SYNC_SCRIPT = ANDROID_DIR / "scripts" / "sync_codecs.py"
+
+
+def sha256(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def run(cmd, cwd, verbose: bool) -> int:
+    if verbose:
+        print("+", " ".join(str(c) for c in cmd))
+    result = subprocess.run(
+        cmd, cwd=str(cwd), capture_output=not verbose, text=True
+    )
+    if not verbose:
+        sys.stdout.write(result.stdout)
+        sys.stderr.write(result.stderr)
+    return result.returncode
+
+
+def check_prerequisites() -> None:
+    if not (GRADLEW.exists() and WRAPPER_JAR.exists()):
+        sys.exit(
+            "error: gradle wrapper is incomplete ({} missing).\n"
+            "hint: run `gradle wrapper` in android/ once, or re-clone.".format(
+                WRAPPER_JAR if not WRAPPER_JAR.exists() else GRADLEW
+            )
+        )
+
+    java_ok = None
+    try:
+        out = subprocess.run(
+            ["java", "-version"], capture_output=True, text=True, check=False
+        ).stderr
+        match = re.search(r'version "(?:1\.)?(\d+)', out)
+        java_ok = int(match.group(1)) if match else None
+    except FileNotFoundError:
+        java_ok = None
+    if java_ok is None:
+        sys.exit("error: no JDK found on PATH (need JDK 17 for AGP 8.10).")
+    if java_ok < 17:
+        sys.exit("error: JDK {} on PATH, but the Android build needs JDK 17.".format(java_ok))
+
+    sdk = None
+    if LOCAL_PROPERTIES.exists():
+        for line in LOCAL_PROPERTIES.read_text().splitlines():
+            if line.startswith("sdk.dir="):
+                sdk = line.split("=", 1)[1]
+    sdk = sdk or os.environ.get("ANDROID_HOME") or os.environ.get("ANDROID_SDK_ROOT")
+    if not sdk or not Path(sdk).exists():
+        sys.exit(
+            "error: Android SDK not found.\n"
+            "hint: set sdk.dir in android/local.properties or ANDROID_HOME."
+        )
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--release",
+        action="store_true",
+        help="build the (unsigned) release APK instead of the debug APK",
+    )
+    parser.add_argument(
+        "--no-sync",
+        action="store_true",
+        help="skip re-synchronising the bundled codec modules",
+    )
+    parser.add_argument(
+        "--offline",
+        action="store_true",
+        help="pass --offline to Gradle (no dependency downloads)",
+    )
+    parser.add_argument(
+        "--clean",
+        action="store_true",
+        help="run the Gradle clean task before building",
+    )
+    parser.add_argument(
+        "--verbose", action="store_true", help="stream Gradle output"
+    )
+    args = parser.parse_args(argv)
+
+    check_prerequisites()
+    variant = "release" if args.release else "debug"
+
+    if not args.no_sync:
+        sync = subprocess.run(
+            [sys.executable, str(SYNC_SCRIPT)], cwd=str(REPO_ROOT), check=False
+        )
+        if sync.returncode != 0:
+            print("error: codec re-sync failed; refusing to build a stale APK.")
+            return sync.returncode
+
+    tasks = []
+    if args.clean:
+        tasks.append("clean")
+    tasks.append(VARIANTS[variant])
+    cmd = [str(GRADLEW)]
+    if args.offline:
+        cmd.append("--offline")
+    cmd.extend(tasks)
+
+    rc = run(cmd, cwd=ANDROID_DIR, verbose=args.verbose)
+    if rc != 0:
+        print("error: Gradle {} failed (exit {}).".format(" ".join(tasks), rc))
+        return rc
+
+    apk = ANDROID_DIR / APK_REL[variant]
+    if not apk.exists():
+        print("error: expected APK not found at {}".format(apk))
+        return 1
+    data = apk.read_bytes()
+    print("APK  : {}".format(apk.relative_to(REPO_ROOT)))
+    print("size : {} bytes".format(len(data)))
+    print("sha256: {}".format(sha256(data)))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

android/scripts/sync_codecs.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Synchronise the BAL QR codec modules into the Android app.
+
+Copies ``bal/core/{__init__,animated_qr,qrtransfer}.py`` from the plugin repo
+into ``android/app/src/main/python/bal/core/`` so Chaquopy ships exactly the
+same code the desktop plugin runs. Afterwards the copies are imported
+standalone and used for one quick encode/decode round trip.
+
+Run from the repository root (any Python 3.8+, no dependencies):
+
+    python3 android/scripts/sync_codecs.py
+    python3 android/scripts/sync_codecs.py --check   # no writes
+
+Re-run whenever ``bal/core/animated_qr.py`` or ``bal/core/qrtransfer.py``
+changes; the bundled copies are committed for deterministic builds.
+"""
+
+import argparse
+import hashlib
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+CORE_SRC = REPO_ROOT / "bal" / "core"
+PYTHON_DEST = REPO_ROOT / "android" / "app" / "src" / "main" / "python"
+BAL_CORE_DEST = PYTHON_DEST / "bal" / "core"
+
+FILES = ("__init__.py", "animated_qr.py", "qrtransfer.py")
+
+ROUNDTRIP = (
+    "import sys; "
+    "sys.path.insert(0, {dest!r}); "
+    "from bal.core.animated_qr import AnimatedQrSession, ur2_frames; "
+    "import bal.core.qrtransfer as qtf; "
+    "frames = ur2_frames(b'roundtrip-check', 400); "
+    "assert frames, 'no frames produced'; "
+    "s = AnimatedQrSession(); "
+    "assert all(s.add_part(f) == 'ok' for f in frames); "
+    "transfer, compressed = s.resolve(); "
+    "assert not compressed and transfer == 'roundtrip-check', 'roundtrip failed'; "
+    "print('standalone import + roundtrip OK'); "
+)
+
+
+def sha256(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def check_up_to_date() -> int:
+    outdated = []
+    for name in FILES:
+        src = (CORE_SRC / name).read_bytes()
+        dst = BAL_CORE_DEST / name
+        if not dst.exists() or dst.read_bytes() != src:
+            outdated.append(name)
+    if outdated:
+        print("OUT OF DATE: {}".format(", ".join(outdated)))
+        print("run: python3 android/scripts/sync_codecs.py")
+        return 1
+    print("codec bundles are up to date")
+    return 0
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="verify the bundled copies are up to date without writing",
+    )
+    args = parser.parse_args(argv)
+
+    if args.check:
+        return check_up_to_date()
+
+    BAL_CORE_DEST.mkdir(parents=True, exist_ok=True)
+    for name in FILES:
+        src = (CORE_SRC / name).read_bytes()
+        dst = BAL_CORE_DEST / name
+        dst.write_bytes(src)
+        print("synced {:16s} sha256={}".format(name, sha256(src)[:16]))
+
+    run = subprocess.run(
+        [sys.executable, "-c", ROUNDTRIP.format(dest=str(PYTHON_DEST))],
+        cwd=REPO_ROOT,
+        capture_output=True,
+        text=True,
+    )
+    if run.returncode != 0:
+        print(run.stdout, end="")
+        print(run.stderr, end="")
+        return 1
+    print(run.stdout.strip())
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

android/settings.gradle.kts

@@ -0,0 +1,23 @@
+pluginManagement {
+    repositories {
+        google {
+            content {
+                includeGroupByRegex("com\\.android.*")
+                includeGroupByRegex("com\\.google.*")
+                includeGroupByRegex("androidx.*")
+            }
+        }
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+rootProject.name = "BALReader"
+include(":app")

android/test_chain/verify_chain.py

@@ -0,0 +1,314 @@
+#!/usr/bin/env python3
+"""Verify the Android app can decode every frame format the plugin exports.
+
+Simulates the exact runtime path of the APK on the development machine:
+
+* imports ``bal.core`` and ``balreader.payload`` from the *bundled* copies in
+  ``android/app/src/main/python`` (the code Chaquopy actually ships);
+* generates frames exactly as the plugin's export page does
+  (``split_frames`` for BAL QR, ``encode_animated_frames`` semantics for
+  UR v1 / UR v2 / BBQR);
+* drives an :class:`~bal.core.animated_qr.AnimatedQrSession` the way
+  ``BalDecoder.add`` does (scrambled input, duplicates, dropped frames);
+* runs the app's ``finish()`` chain (``resolve()`` -> ``decode_transfer()``
+  -> ``decode_will_payload()``) and checks the result;
+* cross-checks the app's ``decode_will_payload`` copy result-for-result (and
+  AST-for-AST) against the plugin's original in ``bal/gui/qt/dialogs.py``.
+
+Run from the repository root (any Python 3.8+, no dependencies):
+
+    python3 android/test_chain/verify_chain.py
+"""
+
+import ast
+import json
+import random
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+APP_PYTHON = REPO_ROOT / "android" / "app" / "src" / "main" / "python"
+DIALOGS = REPO_ROOT / "bal" / "gui" / "qt" / "dialogs.py"
+
+sys.path.insert(0, str(APP_PYTHON))
+
+from bal.core import animated_qr as aq  # noqa: E402
+from bal.core import qrtransfer as qtf  # noqa: E402
+
+from balreader import bridge as bridge_codec  # noqa: E402
+from balreader import payload as payload_codec  # noqa: E402
+
+PASSED = 0
+
+
+def ok(condition, label):
+    global PASSED
+    if not condition:
+        raise AssertionError("FAILED: " + label)
+    PASSED += 1
+
+
+def check_imported_bundle():
+    for module in (aq, qtf, payload_codec):
+        assert module.__file__ is not None
+        path = str(Path(module.__file__).resolve())
+        assert path.startswith(str(APP_PYTHON)), path
+    ok(True, "all modules imported from the bundled android/ copies")
+
+
+def find_function(tree, name):
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef) and node.name == name:
+            return node
+    raise RuntimeError("{} not found".format(name))
+
+
+# --------------------------------------------------------------------------- #
+# Fixtures
+# --------------------------------------------------------------------------- #
+
+TXS = ["{:064x}".format(i) for i in range(1, 8)]
+WILL_ITEMS = {
+    "imp{}".format(i): {
+        "tx": "{:064x}".format(i + 1),
+        "addr": "bc1qdeadbeef{:x}".format(i),
+        "amount": 100000 + i,
+        "tag": "heiress-{}".format(i),
+        "metadata": {},
+        "notify": "mail-{}@example.invalid".format(i),
+    }
+    for i in range(3)
+}
+WILL_JSON_COMPACT = json.dumps(WILL_ITEMS, separators=(",", ":"))
+WILL_JSON_PRETTY = json.dumps(WILL_ITEMS, indent=2)
+
+
+# --------------------------------------------------------------------------- #
+# Parity: app's decode_will_payload vs the plugin's dialogs.py original
+# --------------------------------------------------------------------------- #
+
+def build_extracted_and_app_function():
+    dialogs_source = DIALOGS.read_text()
+    app_source = Path(payload_codec.__file__).read_text()
+    dialogs_node = find_function(ast.parse(dialogs_source), "decode_will_payload")
+    app_node = find_function(ast.parse(app_source), "decode_will_payload")
+    ok(
+        ast.dump(app_node) == ast.dump(dialogs_node),
+        "decode_will_payload AST identical between app copy and plugin",
+    )
+    namespace = {}
+    exec("import json\nimport re\nfrom typing import Any", namespace)
+    exec(compile(ast.Module(body=[dialogs_node], type_ignores=[]), "dialogs.py", "exec"), namespace)
+    return namespace["decode_will_payload"]
+
+
+def run_payload_parity_cases():
+    plugin_decode = build_extracted_and_app_function()
+    samples = {
+        "will-compact": WILL_JSON_COMPACT,
+        "will-pretty": WILL_JSON_PRETTY,
+        "txs-newlines": "\n".join(TXS),
+        "txs-comma-crlf": ",\r\n".join(TXS[:3]),
+        "single-tx": TXS[0],
+        "json-array": json.dumps(TXS),
+        "not-json-dict": "hello world",
+        "empty": "",
+        "whitespace": "   \n\t  ",
+    }
+    for label, text in samples.items():
+        app_result = payload_codec.decode_will_payload(text)
+        plugin_result = plugin_decode(text)
+        ok(
+            app_result == plugin_result,
+            "payload parity for {!r}".format(label),
+        )
+
+
+# --------------------------------------------------------------------------- #
+# Full decode chain (the app's BalDecoder.finish())
+# --------------------------------------------------------------------------- #
+
+def app_chain(transfer_text, compressed):
+    parts = qtf.decode_transfer(transfer_text, compressed)
+    payload = "\n".join(parts)
+    kind, data = payload_codec.decode_will_payload(payload)
+    return parts, payload, kind, data
+
+
+def feed_frame_set(session, frames, *, drop=None, order=None):
+    indexes = list(range(len(frames)))
+    if drop:
+        indexes = [i for i in indexes if i not in drop]
+    if order is not None:
+        indexes = list(order)
+    for i in indexes:
+        session.add_part(frames[i])
+
+
+def make_frames(transfer_text, fmt, budget_chars, *, compressed=False):
+    payload = transfer_text.encode("utf-8")
+    if fmt == "balqr":
+        return qtf.split_frames(transfer_text, budget_chars, compressed=compressed)
+    if fmt == "ur1":
+        return aq.ur1_frames(payload, budget_chars)
+    if fmt == "ur2":
+        return aq.ur2_frames(payload, budget_chars)
+    if fmt == "bbqr":
+        return aq.bbqr_frames(payload, budget_chars, encoding="Z")
+    raise AssertionError("unknown format " + fmt)
+
+
+def run_transport_case(transport, budget_chars, transfer_text, compressed=False):
+    frames = make_frames(transfer_text, transport, budget_chars, compressed=compressed)
+    session = aq.AnimatedQrSession()
+    rng = random.Random(len(transfer_text) + len(transport.encode()))
+    order = [i for i in range(len(frames))]
+    rng.shuffle(order)
+    feed_frame_set(session, frames, order=order)
+    ok(session.done, "{} (.{} chars) reaches done in scrambled order".format(transport, budget_chars))
+    if transport == "ur2":
+        # Fountain indexes can range wider than seq_len, so received may
+        # exceed (or fall short of) total; only progress and completion matter.
+        ok(session.total >= 1 and session.received >= 1,
+           "{} reports positive progress".format(transport))
+    else:
+        ok(
+            session.received == session.total,
+            "{} received matches total".format(transport),
+        )
+        ok(
+            session.received == len(frames) and session.total == len(frames),
+            "{} received/total equals frame count".format(transport),
+        )
+    transfer, compressed_flag = session.resolve()
+    ok(transfer == transfer_text, "{} restores exact transfer text".format(transport))
+    parts, payload, kind, data = app_chain(transfer, compressed_flag)
+    bridge_json = json.loads(bridge_codec.finish(session))
+    ok(
+        bridge_json == {"kind": kind, "payload": payload, "parts": parts},
+        "{} bridge.finish JSON matches the app chain".format(transport),
+    )
+    return parts, payload, kind, data
+
+
+def test_tx_transports():
+    transfer = qtf.encode_transfer(TXS, compress=False)
+    for transport in ("balqr", "ur1", "ur2", "bbqr"):
+        parts, payload, kind, data = run_transport_case(transport, 400, transfer)
+        ok(kind == "txs", "{} classifies as txs".format(transport))
+        ok(parts == TXS and payload == "\n".join(TXS), "{} yields the tx list".format(transport))
+
+
+def test_compressed_bal_transport():
+    transfer = qtf.encode_transfer(TXS, compress=True)
+    frames = make_frames(transfer, "balqr", 400, compressed=True)
+    session = aq.AnimatedQrSession()
+    feed_frame_set(session, frames)
+    ok(session.done, "compressed BAL QR done")
+    parts, payload, kind, data = app_chain(*session.resolve())
+    ok(kind == "txs" and parts == TXS, "compressed BAL QR yields the tx list")
+
+
+def test_will_transports():
+    for transport in ("balqr", "ur1", "ur2", "bbqr"):
+        parts, payload, kind, data = run_transport_case(transport, 400, WILL_JSON_COMPACT)
+        ok(kind == "will", "{} classifies as will".format(transport))
+        ok(data == WILL_ITEMS, "{} restores the whole-will dict".format(transport))
+    # Pretty JSON works too (blank lines are whitespace for json.loads).
+    parts, payload, kind, data = run_transport_case("ur2", 400, WILL_JSON_PRETTY)
+    ok(kind == "will" and data == WILL_ITEMS, "pretty JSON transport restores the will dict")
+
+
+def test_duplicates_are_ignored():
+    # UR v1 (multi-fragment) dedups by fragment index; UR v2 fountains never
+    # report "dup" (they dedup internally), matching the plugin's behaviour.
+    frames = make_frames(WILL_JSON_COMPACT, "ur1", 200)
+    ok(len(frames) >= 2, "UR v1 yields multiple fragments (got {})".format(len(frames)))
+    session = aq.AnimatedQrSession()
+    for i in range(len(frames)):
+        first = session.add_part(frames[i])
+        dup = session.add_part(frames[i])
+        ok(first == "ok", "fresh UR v1 frame reported as ok")
+        ok(dup == "dup", "duplicate UR v1 frame reported as dup")
+    ok(session.received == len(frames), "duplicates do not inflate received")
+    ok(session.done, "UR v1 completes after duplicates")
+
+
+def test_ur2_fountain_survives_loss_and_reorder():
+    transfer = qtf.encode_transfer(TXS, compress=False)
+    frames = make_frames(transfer, "ur2", 120)
+    ok(len(frames) >= 6, "fountain yields multiple frames (got {})".format(len(frames)))
+    drop = (0, 2, len(frames) - 1)
+    session = aq.AnimatedQrSession()
+    rng = random.Random(99)
+    order = [i for i in range(len(frames)) if i not in drop]
+    rng.shuffle(order)
+    feed_frame_set(session, frames, order=order, drop=drop)
+    ok(session.done, "fountain completes after dropped + reordered frames")
+    transfer, compressed_flag = session.resolve()
+    ok(transfer == transfer, "fountain restores exact transfer text")
+    parts, payload, kind, data = app_chain(transfer, compressed_flag)
+    ok(kind == "txs" and parts == TXS, "fountain output feeds the full import tail")
+
+
+def test_ur2_single_part_and_duplicate():
+    transfer = qtf.encode_transfer(TXS, compress=False)
+    frames = make_frames(transfer, "ur2", 2000)
+    ok(len(frames) == 1, "large budget yields a single-part UR v2 frame")
+    session = aq.AnimatedQrSession()
+    session.add_part(frames[0])
+    ok(session.done and session.received == 1, "single-part UR v2 completes")
+
+
+def test_bbqr_all_three_encodings():
+    for encoding in ("Z", "H", "2"):
+        frames = aq.bbqr_frames(WILL_JSON_COMPACT.encode(), 120, encoding=encoding)
+        session = aq.AnimatedQrSession()
+        feed_frame_set(session, frames)
+        ok(session.done, "BBQR {} done".format(encoding))
+        transfer, compressed = session.resolve()
+        parts, payload, kind, data = app_chain(transfer, compressed)
+        ok(kind == "will" and data == WILL_ITEMS, "BBQR {} restores the will".format(encoding))
+
+
+def test_mid_transfer_conflict():
+    ur1 = aq.ur1_frames(b"transfer-one", 400)
+    ur2 = aq.ur2_frames(b"transfer-two", 400)
+    session = aq.AnimatedQrSession()
+    session.add_part(ur1[0])
+    try:
+        session.add_part(ur2[0])
+    except aq.TransferConflictError:
+        ok(True, "format switch raises TransferConflictError")
+    else:
+        ok(False, "format switch raised TransferConflictError")
+
+
+def test_garbage_and_single_line():
+    session = aq.AnimatedQrSession()
+    try:
+        session.add_part("this is not a QR transfer")
+    except aq.FormatNotDetectedError:
+        ok(True, "garbage raises FormatNotDetectedError")
+    else:
+        ok(False, "garbage raised FormatNotDetectedError")
+
+
+def main():
+    check_imported_bundle()
+    run_payload_parity_cases()
+    test_tx_transports()
+    test_compressed_bal_transport()
+    test_will_transports()
+    test_duplicates_are_ignored()
+    test_ur2_fountain_survives_loss_and_reorder()
+    test_ur2_single_part_and_duplicate()
+    test_bbqr_all_three_encodings()
+    test_mid_transfer_conflict()
+    test_garbage_and_single_line()
+    print("verify_chain: {} checks passed".format(PASSED))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

android/tools/emitter.py

@@ -0,0 +1,202 @@
+"""Standalone QR emitter for testing the Android reader on a real camera.
+
+Replicates exactly what the plugin's QR export page puts on screen
+(``BalQrExportWidget``): the same ``encode_transfer`` + per-format frame
+encoders from ``bal.core``, rendered one QR at a time with ``qrcode``.
+
+Run from the repo root with the runtime venv (has ``bal``, ``qrcode``,
+PyQt6):
+
+    source "$BAL_HOME/electrum/env/bin/activate"
+    QT_QPA_PLATFORM=xcb python3 android/tools/emitter.py --format ur2 --loop
+
+Controls:
+    Left/Right         previous / next frame
+    Space              toggle autoplay
+    L                  toggle loop (default off)
+    Q / Esc            quit
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+
+import qrcode  # noqa: E402
+from PyQt6.QtCore import Qt, QTimer  # noqa: E402
+from PyQt6.QtGui import QColor, QImage, QPainter, QPixmap  # noqa: E402
+from PyQt6.QtWidgets import QLabel, QMainWindow, QWidget  # noqa: E402
+
+from bal.core import animated_qr as aq  # noqa: E402
+from bal.core import qrtransfer as qtf  # noqa: E402
+
+
+def build_frames(tx_strings, fmt, budget):
+    """Frames exactly as BalQrExportWidget._refresh_frames produces them."""
+    transfer = qtf.encode_transfer(tx_strings, compress=False)
+    if fmt == "balqr":
+        return qtf.split_frames(transfer, budget, compressed=False)
+    payload = transfer.encode("utf-8")
+    if fmt == "ur1":
+        return aq.ur1_frames(payload, budget)
+    if fmt == "ur2":
+        return aq.ur2_frames(payload, budget)
+    if fmt == "bbqr":
+        return aq.bbqr_frames(payload, budget, encoding="Z")
+    raise SystemExit("unknown format: {}".format(fmt))
+
+
+def load_payload(args):
+    """Return ``(tx_strings, description)`` mirroring ``_payload_strings``."""
+    if args.will is not None:
+        will = json.loads(Path(args.will).read_text())
+        return (
+            [json.dumps(will, ensure_ascii=False)],
+            "whole-will JSON ({})".format(Path(args.will).name),
+        )
+    if args.txs is not None:
+        raw = Path(args.txs).read_text()
+        return [line.strip() for line in raw.split() if line.strip()], "txs"
+    raise SystemExit("give --will FILE or --txs FILE")
+
+
+def qr_pixmap(text, size):
+    """Render ``text`` as a QR code fitted to a ``size``x``size`` image."""
+    qr = qrcode.QRCode(border=2, error_correction=qrcode.constants.ERROR_CORRECT_M)
+    qr.add_data(text)
+    qr.make(fit=True)
+    matrix = qr.modules
+    n = len(matrix)
+    border = qr.border
+    scale = max(1, size // (n + 2 * border))
+    dim = (n + 2 * border) * scale
+    image = QImage(dim, dim, QImage.Format.Format_RGB32)
+    image.fill(Qt.GlobalColor.white)
+    painter = QPainter(image)
+    painter.fillRect(0, 0, dim, dim, QColor("white"))
+    painter.setBrush(QColor("black"))
+    painter.setPen(Qt.PenStyle.NoPen)
+    for y, row in enumerate(matrix):
+        for x, on in enumerate(row):
+            if on:
+                painter.fillRect(
+                    (x + border) * scale, (y + border) * scale, scale, scale,
+                    QColor("black"),
+                )
+    painter.end()
+    return QPixmap.fromImage(image).scaled(
+        size, size, Qt.AspectRatioMode.KeepAspectRatio,
+        Qt.TransformationMode.SmoothTransformation,
+    )
+
+
+class EmitterWindow(QMainWindow):
+    def __init__(self, frames, description, fmt, fps, loop):
+        super().__init__()
+        self.frames = frames
+        self.fps = fps
+        self.loop = loop
+        self.index = 0
+        self.autoplay = True
+
+        central = QWidget(self)
+        self.setCentralWidget(central)
+        self.pix = QLabel(central)
+        self.pix.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        self.caption = QLabel(central)
+        self.caption.setAlignment(Qt.AlignmentFlag.AlignCenter)
+
+        import PyQt6.QtWidgets as qt  # noqa: N813 - local import for clarity
+
+        v = qt.QVBoxLayout(central)
+        v.addWidget(self.pix, 1)
+        v.addWidget(self.caption)
+
+        self.setWindowTitle("BAL Reader emitter — {}".format(fmt))
+        self.resize(900, 1000)
+
+        self.timer = QTimer(self)
+        self.timer.timeout.connect(self._step)
+        self.timer.start(int(1000 / self.fps))
+
+        self._render()
+        self.caption.setText(
+            "{desc} | {fmt} | frame {i}/{n} | autoplay={auto} loop={loop}".format(
+                desc=description, fmt=fmt, i=self.index + 1, n=len(self.frames),
+                auto="on" if self.autoplay else "off", loop="on" if loop else "off",
+            )
+        )
+        self.show()
+
+    def _render(self):
+        self.pix.setPixmap(qr_pixmap(self.frames[self.index], min(self.width() - 60, 900)))
+
+    def _update_caption(self):
+        auto = "on" if self.autoplay else "off"
+        loop = "on" if self.loop else "off"
+        self.caption.setText(
+            "frame {i}/{n} ({fmt}) | autoplay={auto} loop={loop}".format(
+                i=self.index + 1, n=len(self.frames), fmt="", auto=auto, loop=loop)
+        )
+
+    def _step(self):
+        if self.index + 1 < len(self.frames):
+            self.index += 1
+        elif self.loop:
+            self.index = 0
+        else:
+            self.autoplay = False
+            self.timer.stop()
+        self._render()
+        self._update_caption()
+
+    def keyPressEvent(self, event):  # noqa: N802 - Qt override name
+        key = event.key()
+        if key == Qt.Key.Key_Right:
+            self.autoplay = False
+            self.index = min(self.index + 1, len(self.frames) - 1)
+            self._render()
+        elif key == Qt.Key.Key_Left:
+            self.autoplay = False
+            self.index = max(self.index - 1, 0)
+            self._render()
+        elif key == Qt.Key.Key_Space:
+            self.autoplay = not self.autoplay
+            if self.autoplay:
+                self.timer.start(int(1000 / self.fps))
+            else:
+                self.timer.stop()
+        elif key == Qt.Key.Key_L:
+            self.loop = not self.loop
+        elif key in (Qt.Key.Key_Q, Qt.Key.Key_Escape):
+            self.close()
+        self._update_caption()
+
+
+def main(argv):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--format", choices=["balqr", "ur1", "ur2", "bbqr"],
+                        default="balqr")
+    parser.add_argument("--budget", type=int, default=400)
+    parser.add_argument("--fps", type=float, default=1.0)
+    parser.add_argument("--loop", action="store_true")
+    parser.add_argument("--will", help="whole-will JSON file")
+    parser.add_argument("--txs", help="file with serialized tx strings")
+    args = parser.parse_args(argv)
+
+    tx_strings, description = load_payload(args)
+    frames = build_frames(tx_strings, args.format, args.budget)
+    if len(frames) == 1:
+        print("single-frame transfer ready ({} bytes)".format(len(frames[0])), file=sys.stderr)
+    else:
+        print("{} frames ready".format(len(frames)), file=sys.stderr)
+
+    app = __import__("PyQt6.QtWidgets", fromlist=["QApplication"]).QApplication([])
+    EmitterWindow(frames, description, args.format, args.fps, args.loop)
+    app.exec()
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

android/tools/sample_will.json

@@ -0,0 +1,26 @@
+{
+  "imp-heiress-1": {
+    "tx": "0f1e2d3c4b5a69788796a5b4c3d2e1f0112233445566778899aabbccddeeff00",
+    "addr": "bc1qdeadbeef0",
+    "amount": 100000,
+    "tag": "heiress-1",
+    "metadata": {},
+    "notify": "heir1@example.invalid"
+  },
+  "imp-heiress-2": {
+    "tx": "112233445566778899aabbccddeeff00112233445566778899aabbccddeeff0011",
+    "addr": "bc1qdeadbeef1",
+    "amount": 200000,
+    "tag": "heiress-2",
+    "metadata": {},
+    "notify": "heir2@example.invalid"
+  },
+  "imp-heiress-3": {
+    "tx": "a1b2c3d4e5f60718293a4b5c6d7e8f901a2b3c4d5e6f708192a3b4c5d6e7f809",
+    "addr": "bc1qdeadbeef2",
+    "amount": 300000,
+    "tag": "heiress-3",
+    "metadata": {},
+    "notify": "heir3@example.invalid"
+  }
+}

bal/__init__.py

@@ -24,11 +24,18 @@ distinct sub-packages:
                 lists.py     Tree/list views (heirs, preview, will-executors)
                 window.py    BalWindow controller (per-wallet GUI state)
                 plugin.py    Plugin class wiring Electrum @hooks to the GUI
+        cli/             Headless command-line layer (no Qt)
+            commands.py     The @plugin_command transport layer (registers
+                            the ``bal_*`` commands)
+            controller.py   Headless replica of the Qt flows (later phases)
+            plugin.py       Plugin(BalPlugin) entry point for the daemon
         qt.py            Thin loader shim re-exporting `Plugin` for Electrum
+        cmdline.py       Thin loader shim re-exporting `Plugin` for the daemon
 
 Electrum discovers the plugin through ``manifest.json`` and loads the GUI
 entry point from ``qt.py`` (the shim), which imports the real ``Plugin``
-from ``gui.qt.plugin``.
+from ``gui.qt.plugin``; the command-line/daemon entry point is ``cmdline.py``
+(the shim), which imports ``Plugin`` from ``cli.plugin``.
 
 The plugin supports Electrum 4.7.2 and 4.8.0 with PyQt6.  Electrum 4.8.0 removed
 ``json_db.register_dict`` and replaced it with the path-based
@@ -40,3 +47,85 @@ available and adapts, so both releases keep working.
 # (the single source of truth) and is read at runtime via ``get_version()`` in
 # ``bal/core/plugin_base.py`` (exposed as the ``BalPlugin.version`` property).
 # Keeping a hardcoded ``__version__`` here would just be a stale duplicate.
+
+# --------------------------------------------------------------------------- #
+# CLI command registration
+# --------------------------------------------------------------------------- #
+# Electrum's CLI pre-parse (run_electrum calls ``Plugins(config, cmd_only=True)``)
+# only imports the plugin package ``__init__`` to discover its commands.
+# Importing ``bal.cli.commands`` here registers every ``bal_*`` command with
+# ``electrum.commands`` (``known_commands`` + the ``Commands`` class), so the
+# commands become available on the command line and over JSON-RPC without any Qt.
+#
+# The import must be zip-safe: when the plugin is loaded as an external zip,
+# Electrum registers the package under the synthetic name
+# ``electrum_external_plugins.bal``, but the module's ``__package__`` is only
+# ``bal`` (the zip-internal directory name), which is not present in
+# ``sys.modules`` and cannot be used for sub-module imports.  We therefore
+# resolve the real package name and import through ``importlib`` (the same
+# trick as ``qt.py``).
+import importlib
+import sys as _sys
+
+
+def _resolve_package_name() -> str:
+    """Return the name this package is registered under in ``sys.modules``.
+
+    Internal plugins are imported as ``electrum.plugins.bal`` (a normal import,
+    so ``__package__`` is already correct).  External zip plugins are imported
+    under the synthetic name ``electrum_external_plugins.bal`` with
+    ``__package__`` set to just the zip-internal directory name (``bal``); only
+    the synthetic name is present in ``sys.modules``.
+    """
+    pkg = __package__ or "bal"
+    if pkg in _sys.modules:
+        return pkg
+    synthetic = "electrum_external_plugins." + __name__
+    if synthetic in _sys.modules:
+        return synthetic
+    return pkg
+
+
+def _ensure_parent_packages(pkg_name: str) -> None:
+    """Backfill missing ancestor packages in ``sys.modules``.
+
+    When loaded from a zip as an external plugin, Electrum only executes the
+    package ``__init__``; the synthetic root package (``electrum_external_plugins``)
+    may be missing, which would break sub-module imports.  We stub it out as a
+    namespace package so ``importlib`` can still resolve its children (same
+    helper as ``qt.py``).
+    """
+    parts = pkg_name.split(".")
+    for i in range(1, len(parts)):
+        ancestor = ".".join(parts[:i])
+        if ancestor in _sys.modules:
+            continue
+        try:
+            importlib.import_module(ancestor)
+        except Exception:
+            import types
+
+            module = types.ModuleType(ancestor)
+            module.__path__ = []  # mark as a (namespace) package
+            _sys.modules[ancestor] = module
+
+
+def _register_cli_commands() -> None:
+    """Import ``bal.cli.commands`` so Electrum registers the ``bal_*`` commands.
+
+    Guarded so a dual install (internal package AND external zip) cannot
+    register the same command names twice, which would make
+    ``electrum.commands.plugin_command`` raise
+    "Command name bal_... already exists".
+    """
+    from electrum import commands as _electrum_commands
+
+    if getattr(_electrum_commands, "_bal_cli_commands_registered", False):
+        return
+    pkg = _resolve_package_name()
+    _ensure_parent_packages(pkg)
+    importlib.import_module(pkg + ".cli.commands")
+    _electrum_commands._bal_cli_commands_registered = True
+
+
+_register_cli_commands()

bal/cli/__init__.py

@@ -0,0 +1,19 @@
+"""
+bal.cli
+=======
+
+Headless command-line layer of the Bitcoin After Life (BAL) Electrum plugin.
+
+This sub-package implements the ``"cmdline"`` front-end: it exposes the
+plugin's functionality through Electrum ``bal_*`` commands while reusing only
+the GUI-free logic from ``bal.core``.  Like ``bal.core``, it MUST never import
+PyQt or ``electrum.gui``.
+
+    * ``bal.cli.commands``   -> the ``@plugin_command`` transport layer
+    * ``bal.cli.controller`` -> headless replica of the Qt flows (later phases)
+    * ``bal.cli.plugin``     -> ``Plugin(BalPlugin)`` entry point for the daemon
+
+Electrum discovers the plugin through ``manifest.json`` (``available_for``
+includes ``"cmdline"``) and loads the entry point from ``cmdline.py``, a thin
+zip-safe shim following the same pattern as ``qt.py``.
+"""

bal/cli/commands.py

@@ -0,0 +1,424 @@
+"""
+bal.cli.commands
+================
+
+CLI commands (``bal_*``) for the Bitcoin After Life plugin.
+
+This module is the *transport layer* of the command-line front-end: every
+function is a coroutine decorated with ``@plugin_command`` so Electrum exposes
+it as ``bal_<name>`` both on the command line and over JSON-RPC.  The functions
+validate their arguments and delegate the real work to
+:mod:`bal.cli.controller` (a headless replica of the Qt flows); this module
+never imports Qt.
+
+It must stay lightweight: Electrum imports it during the CLI pre-parse
+(``run_electrum`` calls ``Plugins(config, cmd_only=True)``) and on every
+GUI/daemon startup, before any wallet or network object exists.  The heavy
+imports (``bal.core``, the controller) happen lazily inside each command.
+
+Flags (see ``electrum.commands.plugin_command``):
+
+    * ``n`` -> requires a running daemon/network (always set for plugins);
+    * ``w`` -> resolves and injects the wallet from the daemon;
+    * ``p`` -> requires the wallet password (for signing).
+"""
+
+from electrum.commands import plugin_command
+from electrum.util import UserFacingException
+
+from .controller import BalController, _user_facing
+
+plugin_name = "bal"
+
+
+def _controller(plugin, wallet):
+    """Build the headless controller, or fail with a clear message."""
+    if plugin is None:
+        raise UserFacingException("the bal plugin is not enabled in this daemon")
+    if wallet is None:
+        raise UserFacingException("wallet not loaded")
+    return BalController(plugin, wallet)
+
+
+def _call(plugin, wallet, method, *args, **kwargs):
+    controller = _controller(plugin, wallet)
+    try:
+        return getattr(controller, method)(*args, **kwargs)
+    except Exception as e:
+        raise _user_facing(e) from e
+
+
+# --------------------------------------------------------------------------- #
+# Settings
+# --------------------------------------------------------------------------- #
+@plugin_command("n", plugin_name)
+async def settings_list(self, plugin=None):
+    """List all BAL plugin configuration options (key, name and value).
+
+    Returns a JSON object mapping every BAL configuration option (``bal_*``)
+    to an object with ``value``, ``default`` and ``name``.
+    """
+    return _call(plugin, None, "settings_list")
+
+
+@plugin_command("n", plugin_name)
+async def settings_get(self, key, plugin=None):
+    """Show the current value of one BAL configuration option.
+
+    arg:str:key:The configuration key (e.g. ``bal_tx_fees``).
+    """
+    return _call(plugin, None, "settings_get", key)
+
+
+@plugin_command("n", plugin_name)
+async def settings_set(self, key, value, plugin=None):
+    """Set a BAL configuration option (booleans, integers, strings, JSON).
+
+    arg:str:key:The configuration key (e.g. ``bal_user_type``).
+    arg:str:value:The new value; JSON for object-typed keys such as ``bal_will_settings``.
+    """
+    return _call(plugin, None, "settings_set", key, value)
+
+
+@plugin_command("n", plugin_name)
+async def settings_reset(self, key, plugin=None):
+    """Reset a BAL configuration option to its default value.
+
+    arg:str:key:The configuration key (e.g. ``bal_tx_fees``).
+    """
+    return _call(plugin, None, "settings_reset", key)
+
+
+# --------------------------------------------------------------------------- #
+# Heirs
+# --------------------------------------------------------------------------- #
+@plugin_command("nw", plugin_name)
+async def heirs_list(self, wallet=None, plugin=None):
+    """List the heirs of the current wallet.
+
+    Returns a JSON object mapping heir names to their ``[address, amount,
+    locktime]`` values.
+    """
+    return _call(plugin, wallet, "heirs_list")
+
+
+@plugin_command("nw", plugin_name)
+async def heirs_show(self, name, wallet=None, plugin=None):
+    """Show the details of a single heir.
+
+    arg:str:name:The heir name.
+    """
+    return _call(plugin, wallet, "heirs_show", name)
+
+
+@plugin_command("nw", plugin_name)
+async def heirs_add(self, name, address, amount, locktime=None, wallet=None, plugin=None):
+    """Add (or replace) an heir in the current wallet.
+
+    arg:str:name:The heir name.
+    arg:str:address:The destination address (or ``OP_RETURN:<hex>`` for an OP_RETURN heir).
+    arg:str:amount:The amount in satoshis or a percentage like ``50%%``.
+    arg:str:locktime:The delivery locktime (absolute timestamp or ``30d``/``1y``); defaults to the will locktime.
+    """
+    return _call(plugin, wallet, "heirs_add", name, address, amount, locktime)
+
+
+@plugin_command("nw", plugin_name)
+async def heirs_update(
+    self,
+    name,
+    address=None,
+    amount=None,
+    locktime=None,
+    wallet=None,
+    plugin=None,
+):
+    """Update an existing heir (only the given fields).
+
+    arg:str:name:The heir name.
+    arg:str:address:The new destination address.
+    arg:str:amount:The new amount in satoshis or a percentage.
+    arg:str:locktime:The new delivery locktime.
+    """
+    return _call(plugin, wallet, "heirs_update", name, address, amount, locktime)
+
+
+@plugin_command("nw", plugin_name)
+async def heirs_delete(self, names, wallet=None, plugin=None):
+    """Delete one or more heirs.
+
+    arg:json:names:A JSON array of heir names (e.g. ``["Alice","Bob"]``).
+    """
+    return _call(plugin, wallet, "heirs_delete", names)
+
+
+@plugin_command("nw", plugin_name)
+async def heirs_import(self, path, wallet=None, plugin=None):
+    """Import heirs from a JSON file (validated, merged).
+
+    arg:str:path:Path to the JSON file.
+    """
+    return _call(plugin, wallet, "heirs_import", path)
+
+
+@plugin_command("nw", plugin_name)
+async def heirs_export(self, path, wallet=None, plugin=None):
+    """Export the heirs to a JSON file.
+
+    arg:str:path:Destination file path.
+    """
+    return _call(plugin, wallet, "heirs_export", path)
+
+
+# --------------------------------------------------------------------------- #
+# Will-Executors
+# --------------------------------------------------------------------------- #
+@plugin_command("nw", plugin_name)
+async def willexecutors_list(self, wallet=None, plugin=None):
+    """List the will-executors for the current network.
+
+    Returns a JSON object mapping executor URLs to their records (address,
+    base_fee, status, info, selected, ...).
+    """
+    return _call(plugin, wallet, "willexecutors_list")
+
+
+@plugin_command("nw", plugin_name)
+async def willexecutors_show(self, url, wallet=None, plugin=None):
+    """Show the details of a single will-executor.
+
+    arg:str:url:The will-executor URL.
+    """
+    return _call(plugin, wallet, "willexecutors_show", url)
+
+
+@plugin_command("nw", plugin_name)
+async def willexecutors_add(
+    self,
+    url,
+    address="",
+    base_fee=0,
+    info=None,
+    wallet=None,
+    plugin=None,
+):
+    """Add a new will-executor (not selected by default).
+
+    arg:str:url:The will-executor base URL.
+    arg:str:address:The executor fee address for this network.
+    arg:int:base_fee:The executor base fee in satoshis.
+    arg:str:info:A human-readable description.
+    """
+    return _call(plugin, wallet, "willexecutors_add", url, address, base_fee, info)
+
+
+@plugin_command("nw", plugin_name)
+async def willexecutors_update(
+    self,
+    url,
+    address=None,
+    base_fee=None,
+    info=None,
+    promo_code=None,
+    rename_to=None,
+    wallet=None,
+    plugin=None,
+):
+    """Update an existing will-executor (only the given fields).
+
+    arg:str:url:The will-executor URL to update.
+    arg:str:address:The new fee address.
+    arg:int:base_fee:The new base fee in satoshis.
+    arg:str:info:The new description.
+    arg:str:promo_code:The new promo code.
+    arg:str:rename_to:Optionally move the record to a new URL.
+    """
+    return _call(
+        plugin,
+        wallet,
+        "willexecutors_update",
+        url,
+        address,
+        base_fee,
+        info,
+        promo_code,
+        rename_to,
+    )
+
+
+@plugin_command("nw", plugin_name)
+async def willexecutors_select(
+    self, url, value=True, wallet=None, plugin=None
+):
+    """Select (or deselect) a will-executor.
+
+    arg:str:url:The will-executor URL.
+    arg:bool:value:True to select, False to deselect.
+    """
+    return _call(plugin, wallet, "willexecutors_select", [url], value)
+
+
+@plugin_command("nw", plugin_name)
+async def willexecutors_delete(self, urls, wallet=None, plugin=None):
+    """Delete one or more will-executors.
+
+    arg:json:urls:A JSON array of executor URLs (e.g. ``["https://we.example.com"]``).
+    """
+    return _call(plugin, wallet, "willexecutors_delete", urls)
+
+
+@plugin_command("nw", plugin_name)
+async def willexecutors_ping(self, urls=None, wallet=None, plugin=None):
+    """Ping the selected (or the given) will-executor servers.
+
+    Updates status/base_fee/address from each server and saves.  Returns
+    ``{url: {status, ok}}``.
+
+    arg:json:urls:Optional JSON array of URLs to ping; defaults to the selected executors.
+    """
+    return _call(plugin, wallet, "willexecutors_ping", urls)
+
+
+@plugin_command("nw", plugin_name)
+async def willexecutors_download(self, wallet=None, plugin=None):
+    """Download the will-executor list from the welist server and merge it.
+
+    Returns the number of records downloaded and the new total.
+    """
+    return _call(plugin, wallet, "willexecutors_download")
+
+
+@plugin_command("nw", plugin_name)
+async def willexecutors_import(self, path, wallet=None, plugin=None):
+    """Import will-executors from a JSON file (``{url: record}``).
+
+    arg:str:path:Path to the JSON file.
+    """
+    return _call(plugin, wallet, "willexecutors_import", path)
+
+
+@plugin_command("nw", plugin_name)
+async def willexecutors_export(self, path, wallet=None, plugin=None):
+    """Export the will-executors to a JSON file.
+
+    arg:str:path:Destination file path.
+    """
+    return _call(plugin, wallet, "willexecutors_export", path)
+
+
+# --------------------------------------------------------------------------- #
+# Will
+# --------------------------------------------------------------------------- #
+@plugin_command("nw", plugin_name)
+async def will_status(self, wallet=None, plugin=None):
+    """Show the current will: per-transaction status, locktime and executors.
+
+    Returns a JSON object with a per-txid detail list and global status counts.
+    """
+    return _call(plugin, wallet, "will_status")
+
+
+@plugin_command("nw", plugin_name)
+async def will_check(self, wallet=None, plugin=None):
+    """Check the local coherence of the will (heirs, executors, fees, locktime).
+
+    Returns ``{"valid": true}`` when coherent, or raises a descriptive error.
+    """
+    return _call(plugin, wallet, "will_check")
+
+
+@plugin_command("nw", plugin_name)
+async def will_prepare(self, wallet=None, plugin=None):
+    """Run the full prepare/inheritance flow (check, rebuild, persist).
+
+    Returns a JSON object with ``result`` (``coherent``, ``rebuilt``,
+    ``expired``, ``postponed``) and, when needed, the invalidation
+    transaction to sign and broadcast.
+    """
+    return _call(plugin, wallet, "prepare_will")
+
+
+@plugin_command("nw", plugin_name)
+async def will_autorebuild(self, wallet=None, plugin=None):
+    """Run the automatic rebuild flow in one shot (check, rebuild, sign, push).
+
+    The same flow the GUI runs automatically on new wallet transactions:
+    the delivery date is anticipated by one day to orphan the old will on-chain
+    and, only when the anticipated locktime crosses the Check Alive threshold
+    (or the threshold is already in the past), an invalidation transaction is
+    returned instead.  Signing needs a passwordless wallet.
+
+    Returns a JSON object with ``result``: ``valid``, ``no_heirs``,
+    ``invalidated`` (with ``invalidation_tx``), ``nothing``,
+    ``needs_signing`` or ``rebuilt``.
+    """
+    return _call(plugin, wallet, "auto_rebuild")
+
+
+@plugin_command("nwp", plugin_name)
+async def will_sign(self, txid=None, password=None, wallet=None, plugin=None):
+    """Sign the valid, not-yet-complete will transactions (or just one).
+
+    Updates the COMPLETE status and the signature counters and persists.
+
+    arg:str:txid:Optional transaction id to sign; signs all valid ones when omitted.
+    """
+    txids = [txid] if txid is not None else None
+    txs = _call(plugin, wallet, "sign_transactions", password, txids)
+    return {wid: str(tx) for wid, tx in txs.items()}
+
+
+@plugin_command("nw", plugin_name)
+async def will_broadcast(
+    self, txid=None, force=False, wallet=None, plugin=None
+):
+    """Send the signed will transactions to their will-executors (in parallel).
+
+    Updates the PUSHED/PUSH_FAIL statuses and persists.  Returns ``{url: status}``.
+
+    arg:str:txid:Optional transaction id to broadcast; all valid+signed ones when omitted.
+    arg:bool:force:Force re-pushing transactions already marked as PUSHED.
+    """
+    txids = [txid] if txid is not None else None
+    return _call(plugin, wallet, "push_transactions_to_willexecutors", force, txids)
+
+
+@plugin_command("nw", plugin_name)
+async def will_export(self, path, wallet=None, plugin=None):
+    """Export the whole will to a JSON file.
+
+    arg:str:path:Destination file path.
+    """
+    return _call(plugin, wallet, "export_will", path)
+
+
+@plugin_command("nw", plugin_name)
+async def will_import_merge(self, path, wallet=None, plugin=None):
+    """Merge a will file into the current will (PSBTs and statuses are merged).
+
+    arg:str:path:Path to the will JSON file.
+    """
+    return _call(plugin, wallet, "merge_will_from_file", path)
+
+
+@plugin_command("nw", plugin_name)
+async def will_invalidate(self, wallet=None, plugin=None):
+    """Build the on-chain invalidation transaction for the current will.
+
+    Returns ``{txid, tx}`` (or nulls when there is nothing to invalidate); the
+    transaction still needs to be signed and broadcast.
+    """
+    return _call(plugin, wallet, "invalidate_will_command")
+
+
+@plugin_command("nw", plugin_name)
+async def will_check_executor(self, txid=None, wallet=None, plugin=None):
+    """Ask the will-executors whether they hold our pushed transactions.
+
+    Runs the searchtx check in parallel, applies the per-item status and
+    persists.  Returns ``{txid: {url, pushed, checked, check_fail}}``.
+
+    arg:str:txid:Optional transaction id to check; checks all pending ones when omitted.
+    """
+    txids = [txid] if txid is not None else None
+    return _call(plugin, wallet, "check_transactions", txids)

bal/cli/plugin.py

@@ -0,0 +1,21 @@
+"""
+bal.cli.plugin
+==============
+
+The headless (command-line) entry point of the plugin.
+
+:class:`Plugin` subclasses :class:`bal.core.plugin_base.BalPlugin` without
+adding any Qt hooks or per-window state.  Electrum instantiates this class when
+the plugin runs with ``gui_name='cmdline'`` (the daemon loads
+``bal/cmdline.py``, which re-exports it), and it is the object injected as
+``plugin`` into every ``bal_*`` command by ``electrum.commands.plugin_command``.
+"""
+
+from ..core.plugin_base import BalPlugin
+
+
+class Plugin(BalPlugin):
+    """Minimal ``BasePlugin`` subclass for the command-line front-end."""
+
+    def __init__(self, parent, config, name):
+        BalPlugin.__init__(self, parent, config, name)

bal/cmdline.py

@@ -0,0 +1,69 @@
+"""
+bal.cmdline
+===========
+
+Compatibility shim for Electrum's plugin loader (command-line front-end).
+
+Electrum loads a plugin with ``gui_name='cmdline'`` by importing the
+``cmdline`` module of the plugin package and looking for a ``Plugin`` class.
+The real implementation lives in the ``bal.cli`` sub-package, so this module
+re-exports ``Plugin`` from ``bal.cli.plugin``.
+
+Like ``qt.py``, this file is not a one-line relative import because the very
+same code may be loaded as an *external* plugin from a ``.zip``, where Electrum
+imports the package under the synthetic top-level name
+``electrum_external_plugins.bal`` and never registers the intermediate parent
+packages.  See the module docstring of ``bal.qt`` for the full rationale.  The
+shim resolves the run-time package name, backfills the missing parents into
+``sys.modules`` and imports the real implementation via
+:func:`importlib.import_module`.
+
+Unlike ``qt.py``, this module MUST never import PyQt (the daemon loads it in a
+headless process).
+"""
+
+import importlib
+import sys
+
+
+def _ensure_parent_packages(pkg_name: str) -> None:
+    """Make sure every ancestor package of *pkg_name* is in ``sys.modules``.
+
+    When loaded from a zip as an external plugin, Electrum only executes the
+    plugin package ``__init__`` and the ``cmdline`` module.  The synthetic root
+    package (e.g. ``electrum_external_plugins``) and any intermediate packages
+    may be missing from ``sys.modules``, which breaks relative/absolute
+    sub-module imports.  We backfill them here using this module's own loader
+    so that ``importlib`` can find sibling sub-packages.
+    """
+    parts = pkg_name.split(".")
+    # Walk from the top-most ancestor down to (but not including) pkg_name.
+    for i in range(1, len(parts)):
+        ancestor = ".".join(parts[:i])
+        if ancestor in sys.modules:
+            continue
+        try:
+            importlib.import_module(ancestor)
+        except Exception:
+            # The synthetic root (e.g. 'electrum_external_plugins') often has no
+            # real spec.  Create a minimal namespace package stub so that the
+            # import machinery can still resolve its children.
+            import types
+
+            module = types.ModuleType(ancestor)
+            module.__path__ = []  # mark as a (namespace) package
+            sys.modules[ancestor] = module
+
+
+# The package this module belongs to. Could be 'electrum.plugins.bal' (internal)
+# or 'electrum_external_plugins.bal' (external zip), depending on how Electrum
+# loaded us.
+_PKG = __package__ or "bal"
+
+_ensure_parent_packages(_PKG)
+
+# Import the real implementation using the fully-qualified, run-time package
+# name so it works regardless of the synthetic prefix Electrum assigned.
+_plugin_module = importlib.import_module(_PKG + ".cli.plugin")
+
+Plugin = _plugin_module.Plugin  # noqa: F401  (re-exported for Electrum)

bal/core/checkalive.py

@@ -10,7 +10,7 @@ Pure, GUI-free. The GUI raises :class:`CheckAliveError` to trigger the
 postpone/invalidate flow; the decision that it *should* be raised lives here.
 """
 
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Any
 
 from .plugin_base import BalTimestamp
@@ -24,7 +24,7 @@ class CheckAliveError(Exception):
 
     def __str__(self):
         return "Check alive expired please update it: {}".format(
-            datetime.fromtimestamp(self.timestamp_to_check).isoformat()
+            datetime.fromtimestamp(self.timestamp_to_check, tz=timezone.utc).isoformat()
         )
 
 
@@ -70,7 +70,7 @@ def resolve_date_to_check(
         The reference timestamp (float, UNIX seconds).
     """
     if is_basic_mode:
-        return (now if now is not None else datetime.now().timestamp())
+        return (now if now is not None else datetime.now(tz=timezone.utc).timestamp())
 
     threshold = BalTimestamp(will_settings["threshold"])
     # A RELATIVE threshold ("30d"/"1y") means "N days BEFORE the delivery":
@@ -96,6 +96,54 @@ def resolve_date_to_check(
     return threshold.to_timestamp()
 
 
+def resolve_guard_threshold(
+    is_basic_mode: bool,
+    will_settings: Any,
+    now: float | None = None,
+) -> float | None:
+    """Resolve the "locktime is lower than threshold" guard's reference.
+
+    The guard compares the stored settings on ONE reference frame: the
+    delivery (``locktime``, kept as at the call site) against this threshold.
+
+    Unlike :func:`resolve_date_to_check` -- which may be *anchored* to the
+    built will's frozen tx locktime so that an unchanged will never reads as
+    expired -- this helper resolves the threshold from the **stored settings
+    alone**.  Otherwise, when the stored relative locktime is shorter than the
+    frozen locktime of an old (still valid) built will (e.g. the delivery was
+    shortened from ``"2y"`` to ``"1y"``), the guard would compare the fresh
+    "1y" locktime against the old will's anchored threshold and wrongly fire,
+    even though locktime > threshold by the settings themselves.
+
+    * BASIC mode: no threshold exists.  Returns ``None`` and the caller falls
+      back to comparing the locktime against ``date_to_check`` (= now), so its
+      behaviour is unchanged.
+    * ADVANCED mode with an ABSOLUTE threshold: returns the stored threshold
+      as-is.
+    * ADVANCED mode with a RELATIVE threshold (``"30d"``/``"1y"``, meaning
+      "N days BEFORE the delivery"): the threshold is anchored to the locktime
+      resolved forward from *now* (the settings' own delivery reading, never a
+      built tx), keeping both sides of the comparison in the same reference
+      frame, as the settings widget displays it.
+
+    Returns ``None`` when there is no threshold to enforce (BASIC mode or a
+    missing stored value).
+    """
+    if is_basic_mode:
+        return None
+    threshold_raw = will_settings.get("threshold")
+    if threshold_raw is None:
+        return None
+    threshold = BalTimestamp(threshold_raw)
+    if threshold.unit is None:
+        return threshold.to_timestamp()
+    now_dt = (
+        datetime.fromtimestamp(now, tz=timezone.utc) if now is not None else None
+    )
+    locktime_dt = BalTimestamp(will_settings["locktime"]).to_date(now_dt)
+    return threshold.to_date(locktime_dt, reverse=True).timestamp()
+
+
 def check_alive_expired(
     is_basic_mode: bool, date_to_check: float, now: float | None = None
 ) -> bool:
@@ -107,5 +155,5 @@ def check_alive_expired(
     """
     if is_basic_mode:
         return False
-    current = now if now is not None else datetime.now().timestamp()
+    current = now if now is not None else datetime.now(tz=timezone.utc).timestamp()
     return date_to_check < current

bal/core/heirs.py

@@ -59,7 +59,7 @@ from electrum.util import (
     write_json_file,
 )
 
-from .util import Util
+from .util import Util, copy_structure
 from .willexecutors import Willexecutors
 
 if TYPE_CHECKING:
@@ -321,40 +321,14 @@ def get_change_output(wallet, in_amount, out_amount, fee):
         return out
 
 
-def _json_safe(value, _path="heirs", _depth=0):
+def _json_safe(value, _path="heirs"):
-    """Return a JSON-serializable deep copy of *value*.
+    """Backward-compatible alias of :func:`bal.core.util.copy_structure`.
 
-    The wallet DB persists the heirs dict via ``json_db.put``, which calls
+    Kept so call sites that imported ``_json_safe`` directly keep working; the
-    ``copy.deepcopy`` on the value.  If any nested element is a live runtime
+    actual implementation (a JSON-safe, deepcopy-free clone) lives in
-    object (e.g. one holding a ``threading.RLock``), deepcopy raises
+    ``bal.core.util`` so every copy path shares one code base.
-    ``TypeError: cannot pickle '_thread.RLock' object`` and the whole
-    "Build will" task fails.
-
-    To make persistence robust we coerce the structure to plain
-    JSON-compatible types (dict / list / str / int / float / bool / None).
-    Anything else is converted to ``str(value)`` and logged with its path so
-    the offending field can be identified, instead of crashing the task.
     """
-    # Primitive JSON scalars are kept as-is.
+    return copy_structure(value, _path=_path)
-    if value is None or isinstance(value, (bool, int, float, str)):
-        return value
-    if isinstance(value, dict):
-        return {
-            str(k): _json_safe(v, "{}[{!r}]".format(_path, k), _depth + 1)
-            for k, v in value.items()
-        }
-    if isinstance(value, (list, tuple)):
-        return [
-            _json_safe(v, "{}[{}]".format(_path, i), _depth + 1)
-            for i, v in enumerate(value)
-        ]
-    # Unexpected runtime object: do not let it reach deepcopy.  Log where it
-    # was found so the real source can be fixed, then store a safe string.
-    _logger.error(
-        "heirs.save: non-serializable value at {} (type={}); coercing to str. "
-        "value={!r}".format(_path, type(value).__name__, value)
-    )
-    return str(value)
 
 
 class Heirs(dict, Logger):
@@ -363,6 +337,10 @@ class Heirs(dict, Logger):
         Logger.__init__(self)
         self.db = wallet.db
         self.wallet = wallet
+        # Reason code explaining why the last buildTransactions() produced no
+        # transaction (None when the last build succeeded or never ran).  See
+        # buildTransactions for the list of codes and why they exist.
+        self.last_build_error = None
         d = self.db.get("heirs", {})
         try:
             self.update(d)
@@ -630,6 +608,20 @@ class Heirs(dict, Logger):
     def buildTransactions(
         self, bal_plugin, wallet, tx_fees=None, utxos=None, from_locktime=0
     ):
+        # Reset the diagnostic reason at the start of every build attempt.
+        #
+        # WHY: when the build produced nothing, the GUI used to show a fixed
+        # list of three "possible reasons" (low balance / dust shares /
+        # check-alive after the delivery date).  In practice the real cause is
+        # often NONE of those three - several code paths below simply return
+        # an empty result with no explanation at all, so the user was shown
+        # three guesses that were all wrong.  Each such path now records WHY
+        # it gave up, and BalBuildWillDialog names the actual cause.
+        #
+        # Codes: NO_HEIRS, NO_UTXO, NO_WILLEXECUTOR_USABLE, NO_FUTURE_DATE,
+        # WILLEXECUTOR_FEE, WILLEXECUTOR_FEE_TOO_HIGH, TX_BUILD_FAILED,
+        # WILLEXECUTOR_TX_ERROR.
+        self.last_build_error = None
         _before = list(self.keys())
         Heirs._validate(self, persist=False)
         _removed = [k for k in _before if k not in self]
@@ -644,6 +636,7 @@ class Heirs(dict, Logger):
                 ", ".join(_removed),
             )
         if len(self) <= 0:
+            self.last_build_error = "NO_HEIRS"
             _logger.info("while building transactions there was no heirs")
             return
         balance = 0.0
@@ -660,12 +653,18 @@ class Heirs(dict, Logger):
                 len_utxo_set += 1
                 available_utxos.append(utxo)
         if len_utxo_set == 0:
+            self.last_build_error = "NO_UTXO"
             _logger.info("no usable utxos")
             return
         j = -2
         willexecutorsitems = list(willexecutors.items())
         willexecutorslen = len(willexecutorsitems)
         alltxs = {}
+        # Counts how many will-executors were actually PROCESSED (i.e. passed
+        # the is_selected/is_valid filter below and reached the build loop).
+        # If it stays 0 the loop silently skipped every single one, which is a
+        # distinct failure from "we tried and the build failed".
+        processed_willexecutors = 0
         while True:
             j += 1
             if j >= willexecutorslen:
@@ -682,6 +681,7 @@ class Heirs(dict, Logger):
                 url = willexecutor = None
             else:
                 break
+            processed_willexecutors += 1
             fees = {}
             i = 0
             txs = {}
@@ -699,9 +699,11 @@ class Heirs(dict, Logger):
                         max_fee=bal_plugin.MAX_WILLEXECUTOR_FEE.get(),
                     )
                 except WillExecutorFeeException:
+                    self.last_build_error = "WILLEXECUTOR_FEE"
                     i = 10
                     continue
                 except WillExecutorFeeTooHighException:
+                    self.last_build_error = "WILLEXECUTOR_FEE_TOO_HIGH"
                     i = 10
                     continue
                 if locktimes:
@@ -710,19 +712,33 @@ class Heirs(dict, Logger):
                             locktimes, available_utxos[:], fees, wallet
                         )
                         if not txs:
+                            self.last_build_error = "TX_BUILD_FAILED"
                             return {}
                     except Exception as e:
+                        # An unexpected failure while assembling the
+                        # transactions for THIS will-executor.
+                        #
+                        # WHY THIS CHANGED: the previous code read
+                        # ``e.heirname`` here, in order to auto-deselect the
+                        # will-executor blamed by the exception.  NOTHING in
+                        # the plugin sets that attribute any more (it is a
+                        # leftover from an older exception design), so the
+                        # lookup itself raised AttributeError, and the inner
+                        # ``except Exception: raise`` re-raised THAT - aborting
+                        # the whole build with a confusing secondary error
+                        # instead of the real one.  We now record the reason,
+                        # log the actual exception together with the
+                        # will-executor it happened on, and simply move on to
+                        # the next one, which is what the original code was
+                        # clearly trying to do.
+                        self.last_build_error = "WILLEXECUTOR_TX_ERROR"
                         _logger.error(
-                            f"build transactions: error preparing transactions: {e}"
+                            "build transactions: error preparing transactions "
-                        )
+                            "for will-executor %s: %r",
-                        try:
+                            (willexecutor or {}).get("url", "(none)"),
-                            if "w!ll3x3c" in e.heirname:
+                            e,
-                                Willexecutors.is_selected(
-                                    e.heirname[len("w!ll3x3c") :], False
                         )
                         break
-                        except Exception:
-                            raise
                     total_fees = 0
                     total_fees_real = 0
                     total_in = 0
@@ -746,12 +762,26 @@ class Heirs(dict, Logger):
                     if i >= 10:
                         break
                 else:
+                    self.last_build_error = "NO_FUTURE_DATE"
                     _logger.info(
                         f"no locktimes for willexecutor {willexecutor} skipped"
                     )
                     break
             alltxs.update(txs)
 
+        # Every will-executor was skipped by the is_selected/is_valid filter
+        # (or the list was empty) and no "no will-executor" build was allowed,
+        # so the loop above never even attempted a build.  This path used to
+        # return silently with no log line at all, which is exactly the case
+        # the owner hit: the dialog then blamed balance/dust/check-alive, none
+        # of which was true.
+        if not alltxs and processed_willexecutors == 0:
+            self.last_build_error = "NO_WILLEXECUTOR_USABLE"
+            _logger.info(
+                "no usable will-executor: all %d skipped (not selected or not valid)",
+                willexecutorslen,
+            )
+
         return alltxs
 
     def get_transactions(

bal/core/plugin_base.py

@@ -24,12 +24,13 @@ This module performs **no** GUI work and imports nothing from PyQt / electrum.gu
 import json
 import os
 import platform
-from datetime import date, datetime, timedelta
+from datetime import datetime, timedelta, timezone
 
 from electrum import constants, json_db
 from electrum.logging import get_logger
 from electrum.plugin import BasePlugin
 from electrum.transaction import tx_from_any
+from electrum.util import classproperty
 
 _logger = get_logger(__name__)
 
@@ -108,7 +109,9 @@ def get_will(x):
 
 try:
     # Electrum >= 4.8.0
-    from electrum.stored_dict import register_name as _electrum_register_name  # pyright: ignore[reportMissingImports]
+    from electrum.stored_dict import (
+        register_name as _electrum_register_name,  # pyright: ignore[reportMissingImports]
+    )
 
     def _register_will_dict(name, method, _type=None):
         """Register a plugin dict in the wallet DB (Electrum >= 4.8.0 API)."""
@@ -169,9 +172,12 @@ class BalPlugin(BasePlugin):
     }
 
     # Human-readable chain name ("bitcoin", "testnet", "regtest", ...).
-    chainname = (
+    # Must be a classproperty (not a plain class attribute) because the class
-        constants.net.NET_NAME if constants.net.NET_NAME != "mainnet" else "bitcoin"
+    # is defined before constants.net is set to the correct network — a plain
-    )
+    # attribute would capture "bitcoin" and never update.
+    @classproperty
+    def chainname(cls):
+        return constants.net.NET_NAME if constants.net.NET_NAME != "mainnet" else "bitcoin"
 
     # Default geometry hint for some dialogs (kept from the original code).
     SIZE = (159, 97)
@@ -251,12 +257,37 @@ class BalPlugin(BasePlugin):
         # (handled by BalWindow.get_wallet_password). Default ON.
         self.AUTO_SIGN = BalConfig(config, "bal_auto_sign", True)
 
+        # REBUILD_ON_CLOSE: when enabled (default), closing the wallet or
+        # quitting Electrum runs the "Build your will" wizard
+        # (BalBuildWillDialog) to rebuild and re-validate the will. When
+        # disabled, on_close() only persists the current in-memory willitems to
+        # the wallet DB: no rebuild dialog, no auto-sign/broadcast, no
+        # invalidation prompts at close. Default ON.
+        self.REBUILD_ON_CLOSE = BalConfig(config, "bal_rebuild_on_close", True)
+
+        # AUTO_REBUILD: when enabled, an incoming/outgoing wallet transaction
+        # automatically re-runs the same rebuild flow the wizard runs at
+        # wallet close (anticipate the delivery date by one day to orphan the
+        # previous will; build an on-chain invalidation tx ONLY when the
+        # anticipated locktime would fall before the check-alive threshold or
+        # the threshold is already in the past). When disabled (default) the
+        # will is only rebuilt when the user presses Check / Prepare or closes
+        # the wallet. Default OFF.
+        self.AUTO_REBUILD = BalConfig(config, "bal_auto_rebuild", False)
+
         # EDITABLE_DATES (Group C / C2): when enabled, the delivery-time and
         # check-alive date fields are editable everywhere (toolbar / Heirs tab),
         # not only inside the "Build your will" wizard. Default OFF, so the dates
         # stay display-only outside the wizard unless the user opts in.
         self.EDITABLE_DATES = BalConfig(config, "bal_editable_dates", False)
 
+        # QR_CHUNK_SIZE (will transfer via QR): payload budget, in bytes, used
+        # per QR frame when exporting/importing a will through the QR channel.
+        # The settings dialog offers the 4 standard presets of
+        # bal.core.qrtransfer.CHUNK_PRESETS; this stores the selected budget.
+        # Default 150 (small QR, low-resolution cameras).
+        self.QR_CHUNK_SIZE = BalConfig(config, "bal_qr_chunk_size", 150)
+
         # NUM_REMINDERS (Group D / D1): how many SEPARATE reminder events the
         # exported .ics calendar should contain. Each reminder becomes its own
         # VEVENT (its own date in the calendar). The dates are spread uniformly
@@ -438,8 +469,8 @@ class BalPlugin(BasePlugin):
     def default_will_settings_absolute():
         """Convert the default relative dates into absolute timestamps (from today)."""
         relative_dates = BalPlugin.default_will_settings_relative()
-        today = date.today()
+        today = datetime.now(tz=timezone.utc).date()
-        dt = datetime(today.year, today.month, today.day, 0, 0, 0)
+        dt = datetime(today.year, today.month, today.day, 0, 0, 0, tzinfo=timezone.utc)
         threshold = (
             dt + timedelta(days=BalTimestamp(relative_dates["threshold"]).duration_to_days())
         ).timestamp()
@@ -499,12 +530,12 @@ class BalTimestamp:
         """
         int32_max = 2 ** 31 - 1
         try:
-            return datetime.fromtimestamp(ts)
+            return datetime.fromtimestamp(ts, tz=timezone.utc)
         except (OSError, OverflowError, ValueError):
             try:
-                return datetime.fromtimestamp(min(int(ts), int32_max))
+                return datetime.fromtimestamp(min(int(ts), int32_max), tz=timezone.utc)
             except (OSError, OverflowError, ValueError):
-                return datetime.fromtimestamp(int32_max)
+                return datetime.fromtimestamp(int32_max, tz=timezone.utc)
 
     def to_date(self, from_date=None, reverse=False):
         """Resolve to a ``datetime``.
@@ -517,7 +548,7 @@ class BalTimestamp:
             return self._safe_fromtimestamp(self.value)
         else:
             if from_date is None:
-                from_date = datetime.now()
+                from_date = datetime.now(tz=timezone.utc)
             if isinstance(from_date, (int, float)):
                 from_date = self._safe_fromtimestamp(from_date)
             reverse = 1 if not reverse else -1

bal/core/qrtransfer.py

@@ -0,0 +1,304 @@
+"""
+bal.core.qrtransfer
+===================
+
+GUI-free helpers for moving BAL will data between devices via QR codes or
+the Electrum ``audio_modem`` plugin (see ``PLAN_QR_TRANSFER.md``).
+
+Scope
+-----
+* converts will transactions into a compact ``transfer_string``
+  (newline-joined serialized transactions, optionally zlib + base64
+  compressed);
+* splits that string into fixed-size ``BAL1<TTT><iii><flag>`` frames for
+  multi-QR export, and reassembles/validates them on import.
+
+Wire format (v2, compact)
+-------------------------
+A frame is::
+
+    BAL1<TTT><iii><flag><payload>
+
+* ``BAL1``    - magic + format era (4 chars).
+* ``TTT``     - frame total as exactly 3 base36 digits (1-based, cap 46655).
+* ``iii``     - frame index as exactly 3 base36 digits (1-based).
+* ``flag``    - one char: ``Z`` (zlib + base64) or ``0`` (plain ASCII).
+* ``payload`` - every other character of the frame; the payloads of all
+  frames, concatenated in index order, rebuild the transfer string.
+
+The fixed 11-char header replaces the legacy ``BALQR1|N|i|flags|`` form
+(same 5 pieces of information) without any pipe separator, so the whole
+frame is scan-friendly and the overhead no longer grows with the frame
+count.  Legacy ``BALQR1|…`` frames are still accepted on import.
+
+The audio-modem channel deliberately bypasses the framing helpers here
+(PLAN_QR_TRANSFER.md section 4.4): its transport compresses internally and
+carries the whole transfer string in a single blob, so callers only use
+:func:`encode_transfer` / :func:`decode_transfer`.
+
+This module never imports Qt or any Electrum GUI code (house rule).
+"""
+
+from __future__ import annotations
+
+import base64
+import zlib
+
+MAGIC = "BALQR"
+VERSION = 1
+FLAG_COMPRESSED = "Z"
+FLAG_PLAIN = "0"
+
+# 4 standard presets (label, payload budget in bytes per QR). Ordered from
+# low-resolution cameras to high-resolution cameras (owner decision D5).
+CHUNK_PRESETS = (
+    ("Small - ~150 bytes/QR (low-res cameras)", 150),
+    ("Medium - ~400 bytes/QR", 400),
+    ("Large - ~900 bytes/QR", 900),
+    ("XL - ~1800 bytes/QR (high-res cameras)", 1800),
+)
+
+# Smallest allowed payload budget per frame, below which the frame header
+# could consume the whole budget.
+MIN_CHUNK_SIZE = 40
+
+# Legacy wire format (still imported); the exporter emits the v2 form below.
+_FRAME_MAGIC_V1 = MAGIC + str(VERSION)
+
+# Compact v2 wire format: fixed-width base36 count fields, no separators.
+_FRAME_MAGIC_V2 = "BAL1"
+_BASE36_DIGITS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+_BASE36_WIDTH = 3
+_HEADER_V2_LEN = len(_FRAME_MAGIC_V2) + 2 * _BASE36_WIDTH + 1
+_MAX_TOTAL = 36 ** _BASE36_WIDTH - 1
+
+
+class QrTransferError(ValueError):
+    """Base error for will QR / audio transfer processing."""
+
+
+class MissingFramesError(QrTransferError):
+    """Some frame indices of a multi-QR transfer are missing."""
+
+    def __init__(self, missing):
+        self.missing = list(missing)
+        super().__init__("Missing QR frames: {}".format(self.missing))
+
+
+class InconsistentTotalError(QrTransferError):
+    """Frames disagree about the advertised frame total."""
+
+
+def encode_transfer(tx_strings, compress=False):
+    """Join serialized transaction strings into a transfer string.
+
+    ``compress=True`` wraps the joined text in zlib + base64 (ASCII-safe) so
+    the whole bundle shrinks before being printed/scanned. The optional flag
+    of the frame header lets the importer reverse this automatically.
+    """
+    return __compress("\n".join(tx_strings), enabled=compress)
+
+
+def encode_transfer_best(tx_strings):
+    """Encode ``tx_strings`` with the smaller of plain vs compressed form.
+
+    Returns ``(transfer_string, compressed: bool)``.  Compressed wins only
+    when zlib + base64 really is shorter (best-of, never larger).
+    """
+    joined = "\n".join(tx_strings)
+    plain = joined
+    compressed = __compress(joined, enabled=True)
+    if len(compressed) < len(plain):
+        return compressed, True
+    return plain, False
+
+
+def decode_transfer(transfer_string, compressed):
+    """Inverse of :func:`encode_transfer`.
+
+    Returns the list of serialized transaction strings; empty frames are
+    dropped so a trailing newline (or an empty payload) cannot produce an
+    empty trailing element.
+    """
+    text = __decompress(transfer_string, enabled=compressed)
+    return [part for part in text.split("\n") if part]
+
+
+def split_frames(transfer_string, chunk_size, compressed=False):
+    """Split ``transfer_string`` into full compact ``BAL1`` frames.
+
+    Every returned frame has the fixed 11-char v2 header followed by its
+    share of the payload, so each frame is at most ``chunk_size`` characters
+    long.  ``compressed`` stamps the ``Z`` flag into every frame so the
+    importer knows how to reverse the encoding.
+
+    Raises :class:`QrTransferError` when ``chunk_size`` is too small to hold
+    the header plus any payload, or when the transfer needs more than
+    :data:`_MAX_TOTAL` frames.
+    """
+    flag = FLAG_COMPRESSED if compressed else FLAG_PLAIN
+    total = __compute_total(len(transfer_string), chunk_size)
+    budget = chunk_size - _HEADER_V2_LEN
+    frames = []
+    pos = 0
+    length = len(transfer_string)
+    for index in range(1, total + 1):
+        end = min(pos + budget, length)
+        frames.append(
+            _FRAME_MAGIC_V2
+            + _base36(total)
+            + _base36(index)
+            + flag
+            + transfer_string[pos:end]
+        )
+        pos = end
+    if pos < length:
+        # __compute_total guarantees this cannot happen; keep a safety net.
+        raise QrTransferError("internal error: frames did not cover the transfer string")
+    return frames
+
+
+def parse_frame(frame):
+    """Parse a single frame.
+
+    Accepts both the legacy ``BALQR1|total|index|flags|payload`` form and
+    the compact ``BAL1<total><index><flag><payload>`` v2 form.
+
+    Returns ``(total, index, compressed: bool, payload: str)``. Raises
+    :class:`QrTransferError` on malformed input (bad magic/version, wrong
+    arity, non-integer or out-of-range frame numbers, unknown flags).
+    """
+    if frame.startswith(_FRAME_MAGIC_V2):
+        return _parse_v2(frame)
+    return _parse_v1(frame)
+
+
+def assemble(frames, total):
+    """Concatenate frame payloads back into a transfer string.
+
+    ``frames`` maps 1-based index -> payload. Every index ``1..total`` must
+    be present (else :class:`MissingFramesError`) and no index may exceed
+    ``total`` (else :class:`InconsistentTotalError`).
+    """
+    if total < 1:
+        raise QrTransferError("invalid frame total")
+    missing = [index for index in range(1, total + 1) if index not in frames]
+    if missing:
+        raise MissingFramesError(missing)
+    extra = [index for index in frames if index > total]
+    if extra:
+        raise InconsistentTotalError()
+    return "".join(frames[index] for index in range(1, total + 1))
+
+
+def preset_index_for_chunk_size(chunk_size):
+    """Return the :data:`CHUNK_PRESETS` index whose budget best matches a size."""
+    best, best_diff = 0, abs(chunk_size - CHUNK_PRESETS[0][1])
+    for index, (_label, budget) in enumerate(CHUNK_PRESETS):
+        diff = abs(chunk_size - budget)
+        if diff < best_diff:
+            best, best_diff = index, diff
+    return best
+
+
+# --------------------------------------------------------------------------- #
+# Internals
+# --------------------------------------------------------------------------- #
+
+def __compress(text, *, enabled):
+    if not enabled:
+        return text
+    return base64.b64encode(zlib.compress(text.encode("utf-8"))).decode("ascii")
+
+
+def __decompress(text, *, enabled):
+    if not enabled:
+        return text
+    return zlib.decompress(base64.b64decode(text.encode("ascii"))).decode("utf-8")
+
+
+def _base36(n):
+    """Zero-padded :data:`_BASE36_WIDTH` base36 render of ``n``."""
+    if not 0 <= n <= _MAX_TOTAL:
+        raise QrTransferError("BAL QR part number out of range: {}".format(n))
+    chars = []
+    for _ in range(_BASE36_WIDTH):
+        chars.append(_BASE36_DIGITS[n % 36])
+        n //= 36
+    return "".join(reversed(chars))
+
+
+def _base36_decode(text):
+    """Inverse of :func:`_base36`; raises ``ValueError`` on bad input."""
+    if len(text) != _BASE36_WIDTH or any(c not in _BASE36_DIGITS for c in text):
+        raise ValueError(text)
+    n = 0
+    for c in text:
+        n = n * 36 + _BASE36_DIGITS.index(c)
+    return n
+
+
+def _parse_v1(frame):
+    parts = frame.split("|", maxsplit=4)
+    if len(parts) != 5:
+        raise QrTransferError("Not a BAL will QR (bad frame structure)")
+    magic_seen, total_s, index_s, flags, payload = parts
+    if magic_seen != _FRAME_MAGIC_V1:
+        raise QrTransferError("Not a BAL will QR (unknown magic/version)")
+    try:
+        total = int(total_s)
+        index = int(index_s)
+    except ValueError as e:
+        raise QrTransferError("Not a BAL will QR (bad frame numbers)") from e
+    if total < 1 or not 1 <= index <= total:
+        raise QrTransferError("Not a BAL will QR (frame numbering out of range)")
+    if flags not in ("", FLAG_COMPRESSED):
+        raise QrTransferError("Not a BAL will QR (unknown flags)")
+    return total, index, flags == FLAG_COMPRESSED, payload
+
+
+def _parse_v2(frame):
+    if len(frame) < _HEADER_V2_LEN:
+        raise QrTransferError("Not a BAL will QR (bad frame structure)")
+    # Magic is length _FRAME_MAGIC_V2; the two base36 fields and the flag
+    # make up the rest of the fixed header.
+    offset = len(_FRAME_MAGIC_V2)
+    total_s = frame[offset : offset + _BASE36_WIDTH]
+    index_s = frame[offset + _BASE36_WIDTH : offset + 2 * _BASE36_WIDTH]
+    flag = frame[offset + 2 * _BASE36_WIDTH]
+    try:
+        total = _base36_decode(total_s)
+        index = _base36_decode(index_s)
+    except ValueError:
+        raise QrTransferError("Not a BAL will QR (bad frame numbers)") from None
+    if total < 1 or not 1 <= index <= total:
+        raise QrTransferError("Not a BAL will QR (frame numbering out of range)")
+    if flag not in (FLAG_PLAIN, FLAG_COMPRESSED):
+        raise QrTransferError("Not a BAL will QR (unknown flags)")
+    payload = frame[_HEADER_V2_LEN:]
+    return total, index, flag == FLAG_COMPRESSED, payload
+
+
+def __compute_total(transfer_len, chunk_size):
+    """Smallest frame count whose budget covers the whole transfer string.
+
+    The v2 header is fixed-width, so the budget is constant and the count is
+    a plain ceiling division, capped at :data:`_MAX_TOTAL`.
+    """
+    if chunk_size < MIN_CHUNK_SIZE:
+        raise QrTransferError(
+            "chunk size too small to hold a BAL QR frame: {}".format(chunk_size)
+        )
+    budget = chunk_size - _HEADER_V2_LEN
+    if budget <= 0:
+        raise QrTransferError(
+            "chunk size too small for the BAL QR frame header: {}".format(chunk_size)
+        )
+    total = -(-transfer_len // budget)
+    if total < 1:
+        total = 1
+    if total > _MAX_TOTAL:
+        raise QrTransferError(
+            "BAL QR transfer demands too many frames: {}".format(total)
+        )
+    return total

bal/core/reminders.py

@@ -38,7 +38,7 @@ def compute_reminder_offsets(days, count):
         count: requested number of reminders.
 
     Returns:
-        A list of integer day-offsets (each ``>= 1``), e.g. ``[22, 15, 8]`` for
+        A list of integer day-offsets (each ``>= 1``), e.g. ``[30, 16, 1]`` for
         ``days=30, count=3``. Empty if there is no room for any reminder.
     """
     # No room for any reminder (deadline today or already passed).

bal/core/util.py

@@ -18,11 +18,14 @@ original implementation.
 """
 
 import bisect
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 
 from electrum.address_synchronizer import TX_HEIGHT_FUTURE, TX_HEIGHT_LOCAL
+from electrum.logging import get_logger
 from electrum.transaction import PartialTxOutput
 
+_logger = get_logger(__name__)
+
 # Bitcoin consensus rule: an nLockTime value strictly below this threshold is
 # interpreted as a *block height*, otherwise it is interpreted as a *UNIX
 # timestamp*.
@@ -35,6 +38,41 @@ from electrum.transaction import PartialTxOutput
 LOCKTIME_THRESHOLD = 500000000
 
 
+def copy_structure(value, _path="copy"):
+    """Return a JSON-serializable deep copy of *value*.
+
+    This is the ad-hoc, deepcopy-free stand-in used every time the plugin needs
+    an independent copy of a plain-data structure (heirs dicts, will-executor
+    dicts, status tables).  It recursively clones dict / list / tuple values
+    while leaving JSON scalars (str / int / float / bool / None) as-is.
+
+    If any nested element is a live runtime object (e.g. one holding a
+    ``threading.RLock``), ``copy.deepcopy`` would raise
+    ``TypeError: cannot pickle '_thread.RLock' object``; instead we coerce the
+    offending value to ``str(value)`` and log it with its path so the source
+    field can be identified, without crashing the caller.
+    """
+    # Primitive JSON scalars are kept as-is.
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+    if isinstance(value, dict):
+        return {
+            str(k): copy_structure(v, "{}[{!r}]".format(_path, k))
+            for k, v in value.items()
+        }
+    if isinstance(value, (list, tuple)):
+        return [
+            copy_structure(v, "{}[{}]".format(_path, i)) for i, v in enumerate(value)
+        ]
+    # Unexpected runtime object: do not let it reach deepcopy.  Log where it
+    # was found so the real source can be fixed, then store a safe string.
+    _logger.error(
+        "copy_structure: non-serializable value at {} (type={}); coercing to "
+        "str. value={!r}".format(_path, type(value).__name__, value)
+    )
+    return str(value)
+
+
 class Util:
     """Namespace of static helpers (kept as a class to preserve the original
     ``Util.method(...)`` call sites used throughout the plugin)."""
@@ -103,7 +141,7 @@ class Util:
         except Exception:
             pass
         try:
-            now = datetime.now()
+            now = datetime.now(tz=timezone.utc)
             if locktime[-1] == "y":
                 locktime = str(int(locktime[:-1]) * 365) + "d"
             if locktime[-1] == "d":
@@ -189,7 +227,7 @@ class Util:
             # moment, so fall back to the legacy forward-from-now resolution.
             return Util.parse_locktime_string(current)
         try:
-            base = datetime.fromtimestamp(int(tx_locktime)).replace(
+            base = datetime.fromtimestamp(int(tx_locktime), tz=timezone.utc).replace(
                 hour=0, minute=0, second=0, microsecond=0
             )
             build_moment = base - timedelta(days=built_days)
@@ -440,9 +478,9 @@ class Util:
         # On Windows datetime.fromtimestamp raises OverflowError past 2038
         # (e.g. NLOCKTIME_MAX); clamp to INT32_MAX (Electrum issue #6170).
         try:
-            dt = datetime.fromtimestamp(locktime)
+            dt = datetime.fromtimestamp(locktime, tz=timezone.utc)
         except (OverflowError, OSError, ValueError):
-            dt = datetime.fromtimestamp(min(locktime, 2 ** 31 - 1))
+            dt = datetime.fromtimestamp(min(locktime, 2 ** 31 - 1), tz=timezone.utc)
         dt -= timedelta(seconds=seconds)
         out = dt.timestamp()
 
@@ -450,34 +488,6 @@ class Util:
             out = 1
         return out
 
-    @staticmethod
-    def cmp_locktime(locktimea, locktimeb):
-        """Compare two relative locktime strings sharing the same unit."""
-        if locktimea == locktimeb:
-            return 0
-        strlocktimea = str(locktimea)
-        strlocktimeb = str(locktimeb)
-        if locktimea[-1] in "ydb":
-            if locktimeb[-1] == locktimea[-1]:
-                return int(strlocktimea[-1]) - int(strlocktimeb[-1])
-            else:
-                return int(locktimea) - (locktimeb)
-
-    @staticmethod
-    def get_lowest_valid_tx(available_utxos, will):
-        """Placeholder kept from the original code (sorts the will by locktime)."""
-        will = sorted(will.items(), key=lambda x: x[1]["tx"].locktime)
-        for _txid, _willitem in will.items():
-            pass
-
-    @staticmethod
-    def get_locktimes(will):
-        """Return the distinct locktimes used by the transactions in ``will``."""
-        locktimes = {}
-        for _, willitem in will.items():
-            locktimes[willitem["tx"].locktime] = True
-        return locktimes.keys()
-
     @staticmethod
     def get_lowest_locktimes(locktimes):
         """Split a list of locktimes into (sorted_timestamps, sorted_blocks)."""
@@ -492,32 +502,6 @@ class Util:
 
         return sorted(sorted_timestamp), sorted(sorted_block)
 
-    @staticmethod
-    def get_lowest_locktimes_from_will(will):
-        """Convenience wrapper: lowest locktimes directly from a will dict."""
-        return Util.get_lowest_locktimes(Util.get_locktimes(will))
-
-    @staticmethod
-    def search_willtx_per_io(will, tx):
-        """Find a will entry whose tx has the same inputs/outputs as ``tx``."""
-        for wid, w in will.items():
-            if Util.cmp_txs(w["tx"], tx["tx"]):
-                return wid, w
-        return None, None
-
-    @staticmethod
-    def invalidate_will(will):
-        raise Exception("not implemented")
-
-    @staticmethod
-    def get_will_spent_utxos(will):
-        """Collect every input spent by any transaction in ``will``."""
-        utxos = []
-        for _, willitem in will.items():
-            utxos += willitem["tx"].inputs()
-
-        return utxos
-
     # ------------------------------------------------------------------ #
     # UTXO helpers
     # ------------------------------------------------------------------ #

bal/core/will.py

@@ -26,9 +26,9 @@ The status flags themselves (the source of truth) stay here; only the mapping
 "status -> colour" now lives in the GUI layer.  No behaviour changed.
 """
 
-import copy
 from datetime import datetime, timezone
 
+from electrum.address_synchronizer import TX_HEIGHT_FUTURE, TX_HEIGHT_LOCAL
 from electrum.i18n import _
 from electrum.logging import Logger, get_logger
 from electrum.transaction import (
@@ -45,7 +45,7 @@ from electrum.util import (
 )
 
 from .heirs import WillExecutorFeeTooHighException
-from .util import Util
+from .util import Util, copy_structure
 from .willexecutors import Willexecutors
 
 MIN_LOCKTIME = 1
@@ -74,11 +74,6 @@ class Will:
                 if not will[child[0]].father:
                     will[child[0]].father = willid
 
-    # return a list of will sorted by locktime
-    @staticmethod
-    def get_sorted_will(will):
-        return sorted(will.items(), key=lambda x: x[1]["tx"].locktime)
-
     @staticmethod
     def only_valid(will):
         for k, v in will.items():
@@ -107,15 +102,6 @@ class Will:
             and not w.get_status("CHECKED")
         )
 
-    @staticmethod
-    def search_equal_tx(will, tx, wid):
-        for w in will:
-            if w != wid and not tx.to_json() != will[w]["tx"].to_json():
-                if will[w]["tx"].txid() != tx.txid():
-                    if Util.cmp_txs(will[w]["tx"], tx):
-                        return will[w]["tx"]
-        return False
-
     @staticmethod
     def get_tx_from_any(x):
         try:
@@ -157,7 +143,7 @@ class Will:
         willitems = {}
         for wid in will:
             Will.add_info_from_will(will, wid, wallet)
-            willitems[wid] = WillItem(will[wid])
+            willitems[wid] = WillItem(will[wid], wallet=wallet)
         will = willitems
         errors = {}
         for wid in will:
@@ -179,7 +165,7 @@ class Will:
                 outputs = will[wid].tx.outputs()
                 ow = will[wid]
                 ow.normalize_locktime(others_input)
-                will[wid] = WillItem(ow.to_dict())
+                will[wid] = ow.copy()
 
                 for i in range(0, len(outputs)):
                     Will.change_input(
@@ -479,7 +465,7 @@ class Will:
                 continue
             utxo_str = utxo.prevout.to_str()
             if utxo_str in prevout_to_spend:
-                balance += inputs[utxo_str][0][2].value_sats()
+                balance += utxo.value_sats()
                 utxo_to_spend.append(utxo)
         _logger.debug("utxo to spend: {}".format(utxo_to_spend))
         if len(utxo_to_spend) > 0:
@@ -516,6 +502,7 @@ class Will:
         for _wid, w in will.items():
             if w.get_status("VALID") and not w.get_status("COMPLETE"):
                 return True
+        return False
 
     @staticmethod
     def search_rai(all_inputs, all_utxos, will, wallet):
@@ -861,6 +848,48 @@ class Will:
         except Exception as e:
             _logger.error(f"save_valid_transactions_to_history failed: {e}")
 
+    @staticmethod
+    def remove_stale_wallet_history(wallet, history_label):
+        """Delete wallet-LOCAL will transactions saved under ``history_label``.
+
+        ``save_valid_transactions_to_history`` stores the not-yet-signed
+        inheritance txs into the wallet's local history; those local
+        placeholders nominally spend the coins they reference. When the will is
+        REBUILT (prepare/build, auto-rebuild, on-close rebuild, CLI build) the
+        stale placeholders must be removed so the coins become available again
+        to the new build (see ``Util.get_available_utxos``). Only
+        wallet-local/future (non-broadcast) txs whose label matches the history
+        label template are removed; confirmed/broadcast history is never
+        touched. Returns the txids that were removed.
+        """
+        if not wallet or not getattr(wallet, "adb", None):
+            return []
+        removed = []
+        for txid, label in Will._wallet_labels(wallet):
+            if not label or not Util._label_matches_history(label, history_label):
+                continue
+            try:
+                height = int(wallet.adb.get_tx_height(txid).height())
+            except Exception:
+                continue
+            if height not in (TX_HEIGHT_LOCAL, TX_HEIGHT_FUTURE):
+                continue
+            try:
+                wallet.adb.remove_transaction(txid)
+                removed.append(txid)
+            except Exception as e:
+                _logger.error(f"remove from history failed for {txid}: {e}")
+                continue
+            try:
+                wallet.set_label(txid, None)
+            except Exception as e:
+                _logger.error(f"set_label failed for {txid}: {e}")
+        try:
+            wallet.save_db()
+        except Exception as e:
+            _logger.error(f"save_db failed after history purge: {e}")
+        return removed
+
     @staticmethod
     def _add_transaction_to_history(wallet, tx, txid):
         """Store *tx* into the wallet's local history via ``adb``.
@@ -1340,16 +1369,24 @@ class WillItem(Logger):
         return self.STATUS[status][1]
 
     def __init__(self, w, _id=None, wallet=None):
-        if isinstance(
+        if isinstance(w, WillItem):
-            w,
+            # Copy a WillItem WITHOUT deepcopy. Serialize it to its plain-dict
-            WillItem,
+            # form and deserialize from there: the tx is re-parsed into a fresh
-        ):
+            # object, STATUS is rebuilt from the clones below and heirs /
-            self.__dict__ = w.__dict__.copy()
+            # will-executors are cloned recursively, so the copy shares no
-        else:
+            # mutable state with the source. See also copy().
+            data = w.to_dict()
+            data["heirs"] = copy_structure(w.heirs) if w.heirs is not None else None
+            data["willexecutor"] = (
+                copy_structure(w.we) if w.we is not None else None
+            )
+            if not _id:
+                _id = w._id
+            w = data
         self.tx = Will.get_tx_from_any(w["tx"])
         self.heirs = w.get("heirs", None)
         self.we = w.get("willexecutor", None)
-            self.status = w.get("status", None)
+        self.status = w.get("status") or ""
         self.description = w.get("description", None)
         self.time = w.get("time", None)
         self.change = w.get("change", None)
@@ -1358,7 +1395,7 @@ class WillItem(Logger):
         self.sigs_have = int(w.get("sigs_have", 0))
         self.father = w.get("Father", None)
         self.children = w.get("Children", None)
-            self.STATUS = copy.deepcopy(WillItem.STATUS_DEFAULT)
+        self.STATUS = WillItem.copy_status_table(WillItem.STATUS_DEFAULT)
         for s in self.STATUS:
             self.STATUS[s][1] = w.get(s, WillItem.STATUS_DEFAULT[s][1])
         # Backward-compatibility migration (A2): the "PENDING" status was
@@ -1381,6 +1418,27 @@ class WillItem(Logger):
         if wallet:
             self.tx.add_info_from_wallet(wallet)
 
+    def copy(self, wallet=None):
+        """Return an independent copy of this WillItem (no deepcopy).
+
+        The copy is produced by serializing this item and deserializing it:
+        the transaction is re-parsed, the STATUS table is rebuilt and
+        heirs / will-executors are cloned recursively, so the result shares no
+        mutable state with ``self``.  Pass a ``wallet`` when the copy's tx
+        needs its address/value information restored
+        (``tx.add_info_from_wallet``).
+        """
+        return WillItem(self, _id=self._id, wallet=wallet)
+
+    @staticmethod
+    def copy_status_table(status_table):
+        """Clone a STATUS table (``{flag: [label, bool]}``) without deepcopy.
+
+        Both the outer dict and every inner ``[label, bool]`` list are new
+        objects, so mutating the returned table never affects the source.
+        """
+        return {k: [label, value] for k, (label, value) in status_table.items()}
+
     def to_dict(self):
         out = {
             "_id": self._id,
@@ -1394,6 +1452,8 @@ class WillItem(Logger):
             "baltx_fees": self.tx_fees,
             "sigs_required": self.sigs_required,
             "sigs_have": self.sigs_have,
+            "Father": self.father,
+            "Children": self.children,
         }
         for key in self.STATUS:
             try:

bal/core/willexecutors.py

@@ -112,8 +112,6 @@ def is_tor_active():
         return False
 
 
-chainname = BalPlugin.chainname
-
 
 class Willexecutors:
 
@@ -146,9 +144,9 @@ class Willexecutors:
 
     @staticmethod
     def save(bal_plugin, willexecutors):
-        _logger.debug(f"save {willexecutors},{chainname}")
+        _logger.debug(f"save {willexecutors},{BalPlugin.chainname}")
         aw = bal_plugin.WILLEXECUTORS.get()
-        aw[chainname] = willexecutors
+        aw[BalPlugin.chainname] = willexecutors
         bal_plugin.WILLEXECUTORS.set(aw)
         _logger.debug(f"saved: {aw}")
         # bal_plugin.WILLEXECUTORS.set(willexecutors)
@@ -158,7 +156,7 @@ class Willexecutors:
         bal_plugin, update=False, bal_window: Any = None, force=False, task=True
     ):
         willexecutors = bal_plugin.WILLEXECUTORS.get()
-        willexecutors = willexecutors.get(chainname, {})
+        willexecutors = willexecutors.get(BalPlugin.chainname, {})
         to_del = []
         for w in willexecutors:
             if not isinstance(willexecutors[w], dict):
@@ -172,7 +170,7 @@ class Willexecutors:
                 )
             )
             del willexecutors[w]
-        bal = bal_plugin.WILLEXECUTORS.default.get(chainname, {})
+        bal = bal_plugin.WILLEXECUTORS.default.get(BalPlugin.chainname, {})
         for bal_url, bal_executor in bal.items():
             if bal_url not in willexecutors:
                 _logger.debug(f"force add {bal_url} willexecutor")
@@ -368,7 +366,7 @@ class Willexecutors:
             _logger.debug(f"{willexecutor['url']}: {willexecutor['txs']}")
             if w := Willexecutors.send_request(
                 "post",
-                willexecutor["url"] + "/" + chainname + "/pushtxs",
+                willexecutor["url"] + "/" + BalPlugin.chainname + "/pushtxs",
                 data=willexecutor["txs"].encode("ascii"),
                 timeout=timeout,
                 max_retries=max_retries,
@@ -408,7 +406,7 @@ class Willexecutors:
             # single short timeout instead of retrying 10x with sleeps, which
             # used to freeze the UI for minutes per unreachable server.
             w = Willexecutors.send_request(
-                "get", url + "/" + chainname + "/info",
+                "get", url + "/" + BalPlugin.chainname + "/info",
                 timeout=timeout, max_retries=max_retries, retry_sleep=retry_sleep,
             )
             if isinstance(w, dict):
@@ -788,7 +786,7 @@ class Willexecutors:
             welist_server = welist_server if welist_server[-1] == '/' else welist_server+'/'
             willexecutors = Willexecutors.send_request(
                 "get",
-                f"{welist_server}data/{chainname}?page=0&limit=100",
+                f"{welist_server}data/{BalPlugin.chainname}?page=0&limit=100",
             )
             if not isinstance(willexecutors, dict):
                 _logger.warning(

bal/gui/qt/calendar.py

@@ -13,12 +13,15 @@ The pure RFC-5545 logic (offsets, escaping, folding, the unified .ics builder,
 the Qt button and the OS/subprocess glue.
 """
 
+import os
+import subprocess
+
+from electrum.gui.qt.util import getSaveFileName
 from PyQt6.QtGui import QAction
-from PyQt6.QtWidgets import QToolButton
+from PyQt6.QtWidgets import QInputDialog, QMenu, QToolButton
 
 from ...core.reminders import write_temp_ics
-from .common import *
+from .common import _, _logger
-from .common import _, _logger  # underscore names are not re-exported by "import *"
 
 
 class BalCalendarButton(QToolButton):

bal/gui/qt/common.py

@@ -15,7 +15,6 @@ hosts a few GUI helpers that do not deserve a module of their own:
       (:class:`CheckAliveError` now lives in ``bal.core.checkalive``.)
 """
 
-import copy
 import enum
 import os
 import subprocess
@@ -28,6 +27,7 @@ from functools import partial
 from typing import Any, Callable, Mapping, Optional, Union
 
 from electrum.bitcoin import NLOCKTIME_BLOCKHEIGHT_MAX, NLOCKTIME_MAX, NLOCKTIME_MIN
+from electrum.gui.common_qt.util import draw_qr
 from electrum.gui.qt.amountedit import BTCAmountEdit
 from electrum.gui.qt.main_window import ElectrumWindow, StatusBarButton
 from electrum.gui.qt.my_treeview import MyTreeView
@@ -42,6 +42,7 @@ from electrum.gui.qt.util import (
     MessageBoxMixin,
     OkButton,
     TaskThread,
+    WaitingDialog,
     WindowModalDialog,
     char_width_in_lineedit,
     getOpenFileName,
@@ -80,6 +81,7 @@ from PyQt6.QtWidgets import (
     QAbstractItemView,
     QAbstractSpinBox,
     QApplication,
+    QButtonGroup,
     QCheckBox,
     QComboBox,
     QDateTimeEdit,
@@ -92,6 +94,7 @@ from PyQt6.QtWidgets import (
     QMenu,
     QMenuBar,
     QPushButton,
+    QRadioButton,
     QScrollArea,
     QSizePolicy,
     QSpinBox,
@@ -108,6 +111,7 @@ from ...core.heirs import (
     HEIR_DUST_AMOUNT,
     HEIR_REAL_AMOUNT,
     OP_RETURN_PREFIX,
+    BalanceTooLowException,
     HeirAmountIsDustException,
     Heirs,
     WillExecutorFeeTooHighException,
@@ -118,7 +122,7 @@ from ...core.heirs import (
 
 # --- Core (GUI-free) logic layer ---
 from ...core.plugin_base import BalPlugin, BalTimestamp
-from ...core.util import Util
+from ...core.util import Util, copy_structure
 from ...core.will import (
     AmountException,
     HeirChangeException,

bal/gui/qt/lists.py

@@ -19,8 +19,59 @@ from typing import TYPE_CHECKING
 from PyQt6.QtWidgets import QLineEdit as _QLineEdit
 from PyQt6.QtWidgets import QMessageBox, QStyledItemDelegate
 
-from .common import *
+from .common import (
-from .common import _, _logger  # underscore names are not re-exported by "import *"
+    OP_RETURN_PREFIX,
+    BalTimestamp,
+    Buttons,
+    CancelButton,
+    HelpButton,
+    MessageBoxMixin,
+    MyTreeView,
+    OkButton,
+    QAbstractItemView,
+    QApplication,
+    QColor,
+    QGridLayout,
+    QHBoxLayout,
+    QLabel,
+    QLineEdit,
+    QMenu,
+    QModelIndex,
+    QPersistentModelIndex,
+    QPushButton,
+    QSize,
+    QSizePolicy,
+    QSpinBox,
+    QStandardItem,
+    QStandardItemModel,
+    Qt,
+    QToolButton,
+    QVBoxLayout,
+    QWidget,
+    TaskThread,
+    Util,
+    Will,
+    Willexecutors,
+    WillItem,
+    _,
+    _logger,
+    char_width_in_lineedit,
+    datetime,
+    enum,
+    export_meta_gui,
+    getOpenFileName,
+    import_meta_gui,
+    is_op_return_address,
+    partial,
+    read_json_file,
+    read_QIcon_from_bytes,
+    server_status_text,
+    server_status_tooltip,
+    signature_suffix,
+    status_color,
+    tx_from_any,
+    write_json_file,
+)
 from .dialogs import BalBuildWillDialog, BalDialog
 from .widgets import BalCheckBox, WillSettingsWidget
 
@@ -612,11 +663,11 @@ class PreviewList(MyTreeView, MessageBoxMixin):
         menu.addAction(_("Prepare"), self.build_transactions)
         menu.addAction(_("Display"), self.bal_window.preview_modal_dialog)
         menu.addAction(_("Sign"), self.ask_password_and_sign_transactions)
-        export_menu = menu.addMenu(_("Export"))
+        # Export/Import open a single window that offers all transports
-        export_menu.addAction(_("All"), self.export_will)
+        # (file / QR / audio). The Choose Filter / transport settings live
-        export_menu.addAction(_("Valid"), self.export_will_valid)
+        # inside that window.
-        export_menu.addAction(_("Valid NC"), self.export_will_valid_incomplete)
+        menu.addAction(_("Export"), self.export_will)
-        menu.addAction(_("Import"), self.import_will_into_details)
+        menu.addAction(_("Import"), self.import_will)
         menu.addAction(_("Merge"), self.merge_will)
         menu.addAction(_("Broadcast"), self.broadcast)
         menu.addAction(_("Check"), self.check)
@@ -682,38 +733,11 @@ class PreviewList(MyTreeView, MessageBoxMixin):
         if will:
             self.update_will(will)
 
-    def export_json_file(self, path):
-        write_json_file(path, self.will)
-
     def export_will(self):
-        self.bal_window.export_will()
+        self.bal_window.export_will_dialog()
-        self.update()
 
-    def export_will_valid(self):
+    def import_will(self):
-        """Export only the will items that are valid."""
+        self.bal_window.import_will_dialog()
-        subset = {
-            wid: wi
-            for wid, wi in self.will.items()
-            if wi.get_status("VALID")
-        }
-        if not subset:
-            self.show_message(_("No valid will item to export"))
-            return
-        self.bal_window.export_will(will=subset)
-        self.update()
-
-    def export_will_valid_incomplete(self):
-        """Export only the will items that are valid but not yet fully signed (V-NC)."""
-        subset = {
-            wid: wi
-            for wid, wi in self.will.items()
-            if wi.get_status("VALID") and not wi.get_status("COMPLETE")
-        }
-        if not subset:
-            self.show_message(_("No valid, incomplete will item to export"))
-            return
-        self.bal_window.export_will(will=subset)
-        self.update()
 
     def import_will_into_details(self):
         self.bal_window.import_will_into_details()

bal/gui/qt/plugin.py

@@ -15,13 +15,36 @@ and cached in ``self.bal_windows``.
 """
 
 from electrum.gui.qt.main_window import StatusBarButton
+from electrum.plugin import hook
+from electrum.util import EventListener, event_listener
 from PyQt6.QtWidgets import QLayout
 
-from .common import *
+from ...core.qrtransfer import CHUNK_PRESETS, preset_index_for_chunk_size
-from .common import (  # underscore names are not re-exported by "import *"
+from .common import (
+    BalPlugin,
+    Buttons,
+    EnterButton,
+    HelpButton,
+    PasswordDialog,
+    QComboBox,
+    QGridLayout,
+    QHBoxLayout,
+    QInputDialog,
+    QLabel,
+    QPushButton,
+    QTimer,
+    QVBoxLayout,
+    QWidget,
+    UserCancelled,
+    Willexecutors,
     _,
     _logger,
+    add_widget,
+    partial,
     read_QIcon_from_bytes,
+    read_QPixmap_from_bytes,
+    show_modal,
+    webopen,
 )
 from .dialogs import BalDialog
 from .widgets import BalCheckBox, BalLineEdit, BalSpinBox, BalTextEdit
@@ -40,7 +63,7 @@ def _window_key(window):
     return id(window)
 
 
-class Plugin(BalPlugin):
+class Plugin(BalPlugin, EventListener):
     def __init__(self, parent, config, name):
         _logger.info("INIT BALPLUGIN")
         BalPlugin.__init__(self, parent, config, name)
@@ -49,6 +72,10 @@ class Plugin(BalPlugin):
         # remove a stale button before creating a fresh one when a wallet is
         # switched / Electrum is restarted, so the icon is never duplicated.
         self._statusbar_buttons = {}
+        # Register the on_event_* handlers with Electrum's callback manager so
+        # the plugin learns about new wallet transactions (used by the
+        # AUTO_REBUILD setting).
+        self.register_callbacks()
 
     @hook
     def init_qt(self, gui_object):
@@ -328,6 +355,44 @@ class Plugin(BalPlugin):
                 except Exception as e:
                     _logger.error("close_wallet: on_close failed: {}".format(e))
 
+    @event_listener
+    def on_event_new_transaction(self, wallet, tx):
+        """Electrum event: a transaction was added to *wallet*."""
+        self._wallet_activity(wallet)
+
+    @event_listener
+    def on_event_wallet_updated(self, wallet):
+        """Electrum event: *wallet* finished a sync pass."""
+        self._wallet_activity(wallet)
+
+    def _wallet_activity(self, wallet):
+        """React to wallet activity (new transaction / sync update).
+
+        When the AUTO_REBUILD setting is enabled, any change to a wallet that
+        has a live BalWindow schedules the headless "auto rebuild" flow
+        (``BalWindow.schedule_auto_rebuild``): it re-runs the same check the
+        wizard runs at wallet close, anticipating the delivery date by one day
+        and building an on-chain invalidation tx only when the anticipated
+        locktime would fall before the check-alive threshold (or the threshold
+        is already in the past).
+
+        This handler runs on the asyncio callback thread, so it only touches
+        thread-safe state and defers all work to the BalWindow (which marshals
+        itself onto the GUI thread through QTimer).
+        """
+        if not self.AUTO_REBUILD.get():
+            return
+        for win in list(self.bal_windows.values()):
+            try:
+                if (
+                    getattr(win, "wallet", None) == wallet
+                    and win.ok
+                    and not win.disable_plugin
+                ):
+                    win.schedule_auto_rebuild()
+            except Exception as e:
+                _logger.debug("_wallet_activity failed: {}".format(e))
+
     @hook
     def init_keystore(self):
         _logger.debug("init keystore")
@@ -448,13 +513,39 @@ class Plugin(BalPlugin):
             self.MAX_WILLEXECUTOR_FEE, minimum=0, maximum=10000000
         )
 
-        # "No will-executor TX" checkbox. Bound to the persisted NO_WILLEXECUTOR
+        # "Rebuild will on wallet close" checkbox. Bound to the persisted
-        # config (default ON, see plugin_base.py), the SAME config used by the
+        # REBUILD_ON_CLOSE config (default ON). When ticked, closing the wallet
-        # checkbox inside the "Build your will" wizard's will-executor download
+        # / quitting Electrum runs the "Build your will" wizard to rebuild and
-        # window, so the two stay in sync automatically. When enabled the plugin
+        # re-validate the will. When unticked, the will is only rebuilt when
-        # also builds a will that does not require a will-executor (e.g. it can
+        # the user presses Check/Prepare. Visible to all users (BASIC and
-        # be saved on a USB stick and a copy given to the heirs).
+        # ADVANCED).
-        heir_no_willexecutor = BalCheckBox(self.NO_WILLEXECUTOR)
+        heir_rebuild_on_close = BalCheckBox(self.REBUILD_ON_CLOSE)
+
+        # "Rebuild automatically on new transactions" checkbox. Bound to the
+        # persisted AUTO_REBUILD config (default OFF). When ticked, an incoming
+        # or outgoing wallet transaction automatically re-runs the same rebuild
+        # flow the wizard runs at wallet close: the delivery date is
+        # anticipated by one day (so the new will replaces the previous one
+        # without an invalidation tx), and an on-chain invalidation is only
+        # built when the anticipated locktime would fall before the Check Alive
+        # threshold or the threshold is already in the past. Visible to all
+        # users (BASIC and ADVANCED).
+        heir_auto_rebuild = BalCheckBox(self.AUTO_REBUILD)
+
+        # QR Code Size selector (will transfer via QR). A 4-standard-size combo
+        # bound to the QR_CHUNK_SIZE config (payload budget in bytes per frame).
+        # Ordered low -> high so the user picks the resolution matching their
+        # camera. Visible to all users (BASIC and ADVANCED).
+        qr_size_combo = QComboBox()
+        qr_size_combo.addItems([label for label, _budget in CHUNK_PRESETS])
+        qr_size_combo.setCurrentIndex(
+            preset_index_for_chunk_size(int(self.QR_CHUNK_SIZE.get()))
+        )
+
+        def on_qr_size_change(index):
+            self.QR_CHUNK_SIZE.set(CHUNK_PRESETS[index][1])
+
+        qr_size_combo.currentIndexChanged.connect(on_qr_size_change)
 
         # USER TYPE selector (SIMPLE / ADVANCED, global). A two-choice combo
         # (not a free-text field) bound to the USER_TYPE config:
@@ -572,6 +663,10 @@ class Plugin(BalPlugin):
                     widget.setCurrentIndex(
                         1 if str(cfg.default).lower() == "advanced" else 0
                     )
+                elif kind == "qr_size":
+                    widget.setCurrentIndex(
+                        preset_index_for_chunk_size(int(cfg.default))
+                    )
             btn.clicked.connect(reset)
             return btn
 
@@ -642,35 +737,13 @@ class Plugin(BalPlugin):
             ),
         )
         grid.addWidget(_make_reset_btn(self.EDITABLE_DATES, heir_editable_dates, "check"), 3, 3)
-        # "Add transaction without will-executor" setting (formerly labelled
-        # "No will-executor TX"). When ON the plugin ALSO builds the backup
-        # inheritance transaction that does NOT require a will-executor (the
-        # "celeste"/light-blue one shown in the will list): it can be saved on a
-        # USB stick and a copy handed to the heirs. When OFF only the
-        # transactions destined to the selected will-executors are built.
-        #
-        # Placed here (row 5, right below "Panel editable Date and Fee" and above
-        # "Number of reminders") at the user's request so related options sit
-        # together. The remaining grid rows below were renumbered accordingly.
-        add_widget(
-            grid,
-            "Add transaction without willexecutor",
-            heir_no_willexecutor,
-            4,
-            (
-                "Create a will that does not require a Will-executor; it can be "
-                "saved, for example, on a USB stick, and a copy can be given to "
-                "the heirs."
-            ),
-        )
-        grid.addWidget(_make_reset_btn(self.NO_WILLEXECUTOR, heir_no_willexecutor, "check"), 4, 3)
         # Max willexecutor fee: maximum fee (in satoshi) allowed for a single
         # will-executor. Visible to all users (BASIC and ADVANCED).
         add_widget(
             grid,
             "Max Will-Executor Fee (satoshi)",
             heir_max_willexecutor_fee,
-            5,
+            4,
             (
                 "Maximum fee (in satoshi) allowed to be paid to a single "
                 "will-executor. If a will-executor charges more than this, "
@@ -678,14 +751,14 @@ class Plugin(BalPlugin):
                 "Default: 500,000 satoshi (0.005 BTC)."
             ),
         )
-        grid.addWidget(_make_reset_btn(self.MAX_WILLEXECUTOR_FEE, heir_max_willexecutor_fee, "spin"), 5, 3)
+        grid.addWidget(_make_reset_btn(self.MAX_WILLEXECUTOR_FEE, heir_max_willexecutor_fee, "spin"), 4, 3)
         # User Type selector placed BEFORE the advanced-only settings so the
         # user chooses basic/advanced first, then sees the relevant options.
         add_widget(
             grid,
             "User Type",
             user_type_combo,
-            6,
+            5,
             (
                 "Choose how much detail the plugin shows.\n\n"
                 "BASIC: simplified interface, safe configuration for most "
@@ -696,7 +769,7 @@ class Plugin(BalPlugin):
                 "editable."
             ),
         )
-        grid.addWidget(_make_reset_btn(self.USER_TYPE, user_type_combo, "user_type"), 6, 3)
+        grid.addWidget(_make_reset_btn(self.USER_TYPE, user_type_combo, "user_type"), 5, 3)
         # Number of reminders, event summary and event description are visible
         # only in ADVANCED mode.  In BASIC mode the factory defaults are always
         # used and these settings are hidden.
@@ -705,11 +778,11 @@ class Plugin(BalPlugin):
             "How many reminder alarms the exported calendar (.ics) event "
             "contains.  Range: 1 to 5 (default 3).  Only used in ADVANCED mode."
         )
-        grid.addWidget(_hide_if_basic(lbl_num_reminders), 7, 0)
+        grid.addWidget(_hide_if_basic(lbl_num_reminders), 6, 0)
-        grid.addWidget(_hide_if_basic(heir_num_reminders), 7, 1)
+        grid.addWidget(_hide_if_basic(heir_num_reminders), 6, 1)
-        grid.addWidget(_hide_if_basic(help_num_reminders), 7, 2)
+        grid.addWidget(_hide_if_basic(help_num_reminders), 6, 2)
         reset_btn_6 = _make_reset_btn(self.NUM_REMINDERS, heir_num_reminders, "spin")
-        grid.addWidget(_hide_if_basic(reset_btn_6), 7, 3)
+        grid.addWidget(_hide_if_basic(reset_btn_6), 6, 3)
 
         lbl_event_summary = QLabel(_("Event summary"))
         help_event_summary = HelpButton(
@@ -719,11 +792,11 @@ class Plugin(BalPlugin):
             "  $heirs_complete: list of heirs name,address,amount\n"
             "Only used in ADVANCED mode."
         )
-        grid.addWidget(_hide_if_basic(lbl_event_summary), 8, 0)
+        grid.addWidget(_hide_if_basic(lbl_event_summary), 7, 0)
-        grid.addWidget(_hide_if_basic(edit_event_summary), 8, 1)
+        grid.addWidget(_hide_if_basic(edit_event_summary), 7, 1)
-        grid.addWidget(_hide_if_basic(help_event_summary), 8, 2)
+        grid.addWidget(_hide_if_basic(help_event_summary), 7, 2)
         reset_btn_7 = _make_reset_btn(self.EVENT_SUMMARY, edit_event_summary, "line")
-        grid.addWidget(_hide_if_basic(reset_btn_7), 8, 3)
+        grid.addWidget(_hide_if_basic(reset_btn_7), 7, 3)
 
         lbl_event_description = QLabel(_("Event description"))
         help_event_description = HelpButton(
@@ -733,11 +806,11 @@ class Plugin(BalPlugin):
             "  $heirs_complete: list of heirs name,address,amount\n"
             "Only used in ADVANCED mode."
         )
-        grid.addWidget(_hide_if_basic(lbl_event_description), 9, 0)
+        grid.addWidget(_hide_if_basic(lbl_event_description), 8, 0)
-        grid.addWidget(_hide_if_basic(edit_event_description), 9, 1)
+        grid.addWidget(_hide_if_basic(edit_event_description), 8, 1)
-        grid.addWidget(_hide_if_basic(help_event_description), 9, 2)
+        grid.addWidget(_hide_if_basic(help_event_description), 8, 2)
         reset_btn_8 = _make_reset_btn(self.EVENT_DESCRIPTION, edit_event_description, "text")
-        grid.addWidget(_hide_if_basic(reset_btn_8), 9, 3)
+        grid.addWidget(_hide_if_basic(reset_btn_8), 8, 3)
         # Welist server URL: shown only in ADVANCED mode.  In BASIC mode the
         # factory default is always used and the setting is hidden.
         lbl_welist_server = QLabel(_("Welist Server URL"))
@@ -745,11 +818,11 @@ class Plugin(BalPlugin):
             "URL of the server that provides the will-executor list.  "
             "Only available in ADVANCED mode."
         )
-        grid.addWidget(_hide_if_basic(lbl_welist_server), 10, 0)
+        grid.addWidget(_hide_if_basic(lbl_welist_server), 9, 0)
-        grid.addWidget(_hide_if_basic(edit_welist_server), 10, 1)
+        grid.addWidget(_hide_if_basic(edit_welist_server), 9, 1)
-        grid.addWidget(_hide_if_basic(help_welist_server), 10, 2)
+        grid.addWidget(_hide_if_basic(help_welist_server), 9, 2)
         reset_btn_9 = _make_reset_btn(self.WELIST_SERVER, edit_welist_server, "line")
-        grid.addWidget(_hide_if_basic(reset_btn_9), 10, 3)
+        grid.addWidget(_hide_if_basic(reset_btn_9), 9, 3)
 
         lbl_calendar_app = QLabel(_("Calendar app command"))
         help_calendar_app = HelpButton(
@@ -757,11 +830,11 @@ class Plugin(BalPlugin):
             "Leave empty to use the system default (xdg-open/open/start).\n"
             "Only used in ADVANCED mode."
         )
-        grid.addWidget(_hide_if_basic(lbl_calendar_app), 11, 0)
+        grid.addWidget(_hide_if_basic(lbl_calendar_app), 10, 0)
-        grid.addWidget(_hide_if_basic(edit_calendar_app), 11, 1)
+        grid.addWidget(_hide_if_basic(edit_calendar_app), 10, 1)
-        grid.addWidget(_hide_if_basic(help_calendar_app), 11, 2)
+        grid.addWidget(_hide_if_basic(help_calendar_app), 10, 2)
         reset_btn_10 = _make_reset_btn(self.CALENDAR_APP, edit_calendar_app, "line")
-        grid.addWidget(_hide_if_basic(reset_btn_10), 11, 3)
+        grid.addWidget(_hide_if_basic(reset_btn_10), 10, 3)
 
         # Save-in-history toggle and history label: advanced-only rows. The
         # label field is disabled while the checkbox is off (see
@@ -774,11 +847,11 @@ class Plugin(BalPlugin):
             "  {willexecutor}: replaced with the will-executor URL of the item\n"
             "Only used in ADVANCED mode."
         )
-        grid.addWidget(_hide_if_basic(lbl_save_history), 12, 0)
+        grid.addWidget(_hide_if_basic(lbl_save_history), 11, 0)
-        grid.addWidget(_hide_if_basic(heir_save_history), 12, 1)
+        grid.addWidget(_hide_if_basic(heir_save_history), 11, 1)
-        grid.addWidget(_hide_if_basic(help_save_history), 12, 2)
+        grid.addWidget(_hide_if_basic(help_save_history), 11, 2)
         reset_btn_11 = _make_reset_btn(self.SAVE_HISTORY, heir_save_history, "check")
-        grid.addWidget(_hide_if_basic(reset_btn_11), 12, 3)
+        grid.addWidget(_hide_if_basic(reset_btn_11), 11, 3)
 
         lbl_history_label = QLabel(_("History label"))
         help_history_label = HelpButton(
@@ -788,11 +861,11 @@ class Plugin(BalPlugin):
             "  {willexecutor}: replaced with the will-executor URL of the item\n"
             "Only used in ADVANCED mode."
         )
-        grid.addWidget(_hide_if_basic(lbl_history_label), 13, 0)
+        grid.addWidget(_hide_if_basic(lbl_history_label), 12, 0)
-        grid.addWidget(_hide_if_basic(edit_history_label), 13, 1)
+        grid.addWidget(_hide_if_basic(edit_history_label), 12, 1)
-        grid.addWidget(_hide_if_basic(help_history_label), 13, 2)
+        grid.addWidget(_hide_if_basic(help_history_label), 12, 2)
         reset_btn_12 = _make_reset_btn(self.HISTORY_LABEL, edit_history_label, "line")
-        grid.addWidget(_hide_if_basic(reset_btn_12), 13, 3)
+        grid.addWidget(_hide_if_basic(reset_btn_12), 12, 3)
 
         # NOTE: the ADVANCED-only widgets above have ALREADY been given their
         # correct initial visibility inline (via _hide_if_basic) BEFORE being
@@ -801,15 +874,76 @@ class Plugin(BalPlugin):
         # the Windows relayout flicker. Do NOT reintroduce a post-hoc
         # setVisible() loop here.
 
-        grid.addWidget(heir_repush, 14, 0)
+        grid.addWidget(heir_repush, 13, 0)
         grid.addWidget(
             HelpButton(
                 "Broadcast all transactions to willexecutors including those already pushed"
             ),
-            14,
+            13,
             2,
         )
 
+        # "Rebuild will on wallet close" row (always visible, BASIC + ADVANCED).
+        # Placed below the rebroadcast button so the existing rows keep their
+        # numbers.
+        lbl_rebuild_on_close = QLabel(_("Rebuild will on wallet close"))
+        help_rebuild_on_close = HelpButton(
+            "Run the 'Build your will' wizard every time the wallet is closed "
+            "or Electrum is quit, so the will is rebuilt and re-validated.\n"
+            "When disabled, the will is only rebuilt when you press Check or "
+            "Prepare. The last built state is still saved to the wallet."
+        )
+        grid.addWidget(lbl_rebuild_on_close, 14, 0)
+        grid.addWidget(heir_rebuild_on_close, 14, 1)
+        grid.addWidget(help_rebuild_on_close, 14, 2)
+        reset_btn_rebuild_on_close = _make_reset_btn(
+            self.REBUILD_ON_CLOSE, heir_rebuild_on_close, "check"
+        )
+        grid.addWidget(reset_btn_rebuild_on_close, 14, 3)
+
+        # "Rebuild automatically on new transactions" row (always visible,
+        # BASIC + ADVANCED), right below the "Rebuild will on wallet close"
+        # row.
+        lbl_auto_rebuild = QLabel(_("Rebuild automatically on new transactions"))
+        help_auto_rebuild = HelpButton(
+            "When a new transaction arrives for the wallet, automatically "
+            "rebuild the will the same way the wizard does at wallet close: "
+            "the delivery date is anticipated by one day so the new will "
+            "replaces the previous one, and the rebuilt transactions are "
+            "signed and sent to their will-executors.\n"
+            "An on-chain invalidation transaction is only built when the "
+            "anticipated delivery date would fall before the Check Alive "
+            "threshold, or when the threshold is already in the past.\n"
+            "When disabled (default), the will is only rebuilt on Check / "
+            "Prepare / wallet close."
+        )
+        grid.addWidget(lbl_auto_rebuild, 15, 0)
+        grid.addWidget(heir_auto_rebuild, 15, 1)
+        grid.addWidget(help_auto_rebuild, 15, 2)
+        reset_btn_auto_rebuild = _make_reset_btn(
+            self.AUTO_REBUILD, heir_auto_rebuild, "check"
+        )
+        grid.addWidget(reset_btn_auto_rebuild, 15, 3)
+
+        # "QR Code Size" row (always visible, BASIC + ADVANCED). Default QR
+        # size used when exporting a will via QR codes; changeable per export
+        # inside the export dialog itself.
+        lbl_qr_size = QLabel(_("QR Code Size"))
+        help_qr_size = HelpButton(
+            "Payload size of a single QR code when exporting a will via QR.\n\n"
+            "Larger QR codes hold more data (fewer shots) but are easier to "
+            "scan with a high-resolution camera; smaller QR codes scan fine "
+            "even with low-resolution cameras but require more shots.\n"
+            "The same selector is available inside the export dialog."
+        )
+        grid.addWidget(lbl_qr_size, 16, 0)
+        grid.addWidget(qr_size_combo, 16, 1)
+        grid.addWidget(help_qr_size, 16, 2)
+        reset_btn_qr_size = _make_reset_btn(
+            self.QR_CHUNK_SIZE, qr_size_combo, "qr_size"
+        )
+        grid.addWidget(reset_btn_qr_size, 16, 3)
+
         # ----------------------------------------------------------------- #
         # Group C / C4b: "Reset" button that restores the dialog settings to  #
         # their factory defaults. It only resets the settings exposed by THIS #
@@ -834,7 +968,6 @@ class Plugin(BalPlugin):
                 (self.AUTO_SIGN, heir_auto_sign, "check"),
                 (self.EDITABLE_DATES, heir_editable_dates, "check"),
                 (self.NUM_REMINDERS, heir_num_reminders, "spin"),
-                (self.NO_WILLEXECUTOR, heir_no_willexecutor, "check"),
                 (self.MAX_WILLEXECUTOR_FEE, heir_max_willexecutor_fee, "spin"),
                 (self.EVENT_SUMMARY, edit_event_summary, "line"),
                 (self.EVENT_DESCRIPTION, edit_event_description, "text"),
@@ -842,6 +975,9 @@ class Plugin(BalPlugin):
                 (self.CALENDAR_APP, edit_calendar_app, "line"),
                 (self.SAVE_HISTORY, heir_save_history, "check"),
                 (self.HISTORY_LABEL, edit_history_label, "line"),
+                (self.REBUILD_ON_CLOSE, heir_rebuild_on_close, "check"),
+                (self.AUTO_REBUILD, heir_auto_rebuild, "check"),
+                (self.QR_CHUNK_SIZE, qr_size_combo, "qr_size"),
             ]
             for cfg, widget, kind in resets:
                 # Persist the default value back into the Electrum config.
@@ -862,6 +998,10 @@ class Plugin(BalPlugin):
                     widget.setCurrentIndex(
                         1 if str(cfg.default).lower() == "advanced" else 0
                     )
+                elif kind == "qr_size":
+                    widget.setCurrentIndex(
+                        preset_index_for_chunk_size(int(cfg.default))
+                    )
             # Re-sync the history-label field's enabled state after a reset: the
             # reset restores SAVE_HISTORY to its default, so the field must
             # follow the (default) checkbox state again.

bal/gui/qt/widgets.py

@@ -20,6 +20,7 @@ Contents:
 
 from typing import TYPE_CHECKING
 
+from ...core.heirs import get_op_return_hex, is_op_return_address
 from ...core.input_rules import (
     LockTimeEditor,
     normalize_locktime_raw_text,
@@ -28,8 +29,53 @@ from ...core.input_rules import (
 )
 from ...core.reminders import build_ics_reminders, write_temp_ics
 from .calendar import BalCalendar, BalCalendarButton
-from .common import *
+from .common import (
-from .common import _, _logger  # underscore names are not re-exported by "import *"
+    DECIMAL_POINT,
+    NLOCKTIME_BLOCKHEIGHT_MAX,
+    NLOCKTIME_MAX,
+    Any,
+    BalTimestamp,
+    BTCAmountEdit,
+    ColorScheme,
+    Decimal,
+    HelpButton,
+    Optional,
+    QAbstractSpinBox,
+    QCheckBox,
+    QColor,
+    QComboBox,
+    QDateTime,
+    QDateTimeEdit,
+    QHBoxLayout,
+    QLabel,
+    QLineEdit,
+    QPainter,
+    QPalette,
+    QPushButton,
+    QSizePolicy,
+    QSpinBox,
+    QStyle,
+    QStyleOptionFrame,
+    Qt,
+    QTextEdit,
+    QVBoxLayout,
+    QWidget,
+    Union,
+    Util,
+    Will,
+    _,
+    _logger,
+    char_width_in_lineedit,
+    datetime,
+    getSaveFileName,
+    log_error,
+    os,
+    partial,
+    pyqtSignal,
+    read_QIcon_from_bytes,
+    signature_suffix,
+    status_color,
+)
 
 if TYPE_CHECKING:
     from .window import BalWindow
@@ -566,9 +612,14 @@ class LockTimeDateEdit(QDateTimeEdit, _LockTimeEditor):
             # Use the overflow-safe converter: on Windows datetime.fromtimestamp
             # raises OverflowError for timestamps past 2038 (e.g. NLOCKTIME_MAX).
             _dt = BalTimestamp._safe_fromtimestamp(x)
-            #if self.alarm != dt:
-            self.setDateTime(_dt)
             self.alarm = _dt
+            # Store the LOCAL wall-clock time, not the aware-UTC datetime:
+            # QDateTimeEdit keeps the given wall time with a LocalTime spec, so
+            # an aware-UTC datetime would make get_value() read back a timezone-
+            # shifted epoch. That broke the set_value -> get_value roundtrip and
+            # kept the valueEdited -> update_setting_widgets -> set_value cycle
+            # firing forever (infinite RecursionError on wizard "Next").
+            self.setDateTime(_dt.astimezone().replace(tzinfo=None))
 
 
 
@@ -1286,14 +1337,28 @@ class WillWidget(QWidget):
                 )
                 detaillayout.addWidget(QLabel(""))
                 detaillayout.addWidget(QLabel("<b>Heirs:</b>"))
-                for heir in self.will[w].heirs:
+                for heir_name in self.will[w].heirs:
-                    if 'w!ll3x3c"' not in heir:
+                    if 'w!ll3x3c"' in heir_name:
+                        continue
+                    h = self.will[w].heirs[heir_name]
                     decoded_amount = Util.decode_amount(
-                            self.will[w].heirs[heir][3], self._bal_parent.decimal_point
+                        h[3], self._bal_parent.decimal_point
                     )
+                    if is_op_return_address(h[0]):
+                        data_hex = get_op_return_hex(h[0]) or ""
+                        try:
+                            decoded = bytes.fromhex(data_hex).decode(
+                                "utf-8", errors="replace"
+                            )
+                        except Exception:
+                            decoded = h[0]
+                        detaillayout.addWidget(qlabel(heir_name, "OP_RETURN: " + decoded))
+                    else:
                         detaillayout.addWidget(
                             qlabel(
-                                heir, f"{decoded_amount} {self._bal_parent.base_unit_name}"
+                                heir_name,
+                                f"{decoded_amount} {self._bal_parent.base_unit_name} "
+                                f"[{h[0]}]",
                             )
                         )
                 if self.will[w].we:
@@ -1309,6 +1374,10 @@ class WillWidget(QWidget):
                             f"{decoded_amount} {self._bal_parent.base_unit_name}",
                         )
                     )
+                    if self.will[w].we.get("address"):
+                        detaillayout.addWidget(
+                            qlabel(_("Address"), self.will[w].we["address"])
+                        )
                 detaillayout.addStretch()
                 pal = QPalette()
                 pal.setColor(

bal/gui/qt/window.py

@@ -23,9 +23,66 @@ from ...core.checkalive import (
     CheckAliveError,
     check_alive_expired,
     resolve_date_to_check,
+    resolve_guard_threshold,
+)
+from .common import (
+    OP_RETURN_PREFIX,
+    AmountException,
+    BalPlugin,
+    Buttons,
+    CancelButton,
+    ElectrumWindow,
+    FileImportFailed,
+    HeirChangeException,
+    HeirNotFoundException,
+    Heirs,
+    HelpButton,
+    Mapping,
+    Network,
+    NoHeirsException,
+    NotCompleteWillException,
+    NoWillExecutorNotPresent,
+    OkButton,
+    Optional,
+    PaymentIdentifier,
+    QGridLayout,
+    QLabel,
+    QLineEdit,
+    QPushButton,
+    QTimer,
+    QVBoxLayout,
+    SerializationError,
+    Transaction,
+    TxDialog,
+    TxFeesChangedException,
+    Util,
+    Will,
+    WillexecutorChangeException,
+    WillExecutorFeeTooHighException,
+    WillExecutorNotPresent,
+    Willexecutors,
+    WillExpiredException,
+    WillItem,
+    WillPostponedException,
+    _,
+    _logger,
+    char_width_in_lineedit,
+    copy_structure,
+    export_meta_gui,
+    import_meta_gui,
+    is_onion_url,
+    is_op_return_address,
+    is_tor_active,
+    log_error,
+    partial,
+    read_json_file,
+    read_QIcon_from_bytes,
+    show_on_top,
+    shown_cv,
+    time,
+    tx_from_any,
+    write_json_file,
 )
-from .common import *
-from .common import _, _logger  # underscore names are not re-exported by "import *"
 from .dialogs import (
     BalBuildWillDialog,
     BalDialog,
@@ -33,12 +90,23 @@ from .dialogs import (
     BalWizardDialog,
     WillDetailDialog,
     WillExecutorDialog,
+    WillExportDialog,
+    WillImportDialog,
+    _complete_import,
+    decode_will_payload,
 )
 from .lists import HeirListWidget, PreviewList
 from .widgets import LockTimeWidget, PercAmountEdit
 
 
 class BalWindow:
+    # Automatic rebuild-on-new-transaction flow (AUTO_REBUILD setting):
+    # the debounce window collapses bursts of wallet events into one run, and
+    # the cooldown prevents the flow from re-triggering right after a rebuild
+    # (the freshly persisted txs can themselves fire wallet events).
+    _AUTO_REBUILD_DEBOUNCE_MS = 5000
+    _AUTO_REBUILD_COOLDOWN = 10.0
+
     def __init__(self, bal_plugin: "BalPlugin", window: "ElectrumWindow"):
         self.bal_plugin = bal_plugin
         self.window = window
@@ -56,6 +124,9 @@ class BalWindow:
         # ``init_menubar_tools`` twice would add the Heirs/Will tabs and the
         # menu actions twice, producing the garbled/condensed menu entry.
         self._menubar_initialized = False
+        # Auto-rebuild flow state: re-entrancy guard and cooldown deadline.
+        self._auto_rebuild_running = False
+        self._auto_rebuild_cooldown_until = 0.0
         self.bal_plugin.get_decimal_point = self.window.get_decimal_point
 
         if self.window.wallet:
@@ -396,6 +467,31 @@ class BalWindow:
 
     def build_will(self, ignore_duplicate=True, keep_original=True):
         _logger.debug("building will...")
+        # Drop stale wallet-LOCAL will placeholders saved by previous prepares
+        # so their coins are available to this build (see remove_stale...).
+        Will.remove_stale_wallet_history(
+            self.window.wallet, self.bal_plugin.HISTORY_LABEL.get()
+        )
+        # A (re)build may have anticipated the delivery (shorter heir recipes)
+        # while ``date_to_check`` is still anchored to the OLD built will. Using
+        # that stale anchor as the build filter would block every future
+        # delivery ("NO_FUTURE_DATE"). Recompute ``date_to_check`` for the will
+        # that is being built: its locktime is the earliest future delivery
+        # among the CURRENT heirs. The checks of the EXISTING will keep their
+        # anchored ``date_to_check`` (set in init_class_variables).
+        _new_locktime = min(
+            (
+                Util.parse_locktime_string(h[2])
+                for h in self.heirs.values()
+            ),
+            default=None,
+        )
+        if _new_locktime:
+            self.date_to_check = resolve_date_to_check(
+                self.bal_plugin.is_basic_mode(),
+                self.will_settings,
+                built_locktime=_new_locktime,
+            )
         will = {}
         # willtodelete = []
         # willtoappend = {}
@@ -450,11 +546,11 @@ class BalWindow:
                     tx["my_locktime"] = txs[txid].my_locktime
                     tx["heirsvalue"] = txs[txid].heirsvalue
                     tx["description"] = txs[txid].description
-                    tx["willexecutor"] = copy.deepcopy(txs[txid].willexecutor)
+                    tx["willexecutor"] = copy_structure(txs[txid].willexecutor)
                     tx["status"] = _("New")
                     tx["baltx_fees"] = txs[txid].tx_fees
                     tx["time"] = creation_time
-                    tx["heirs"] = copy.deepcopy(txs[txid].heirs)
+                    tx["heirs"] = copy_structure(txs[txid].heirs)
                     tx["txchildren"] = []
                     will[txid] = WillItem(tx, _id=txid, wallet=self.wallet)
                 self.update_will(will)
@@ -675,6 +771,27 @@ class BalWindow:
 
             raise e
 
+    def is_locktime_below_threshold(self) -> bool:
+        """True when the stored settings make the delivery earlier than the
+        Check Alive threshold (the "locktime is lower than threshold" guard).
+
+        Compares the delivery against the settings-derived threshold on the
+        SAME reference frame (see ``resolve_guard_threshold``), never against
+        the built-will-anchored ``date_to_check``: anchoring the guard to an
+        old, longer built will would wrongly fire right after the delivery was
+        shortened.  The anchored reference still governs the validity and
+        expiry checks, which is where ``date_to_check`` belongs.
+        In BASIC mode there is no threshold, so the locktime is checked against
+        ``date_to_check`` (= now) exactly as before.
+        """
+        locktime = Util.parse_locktime_string(self.will_settings["locktime"])
+        threshold_ts = resolve_guard_threshold(
+            self.bal_plugin.is_basic_mode(), self.will_settings
+        )
+        if threshold_ts is not None:
+            return locktime < threshold_ts
+        return self.date_to_check is not None and locktime < self.date_to_check
+
     def build_inheritance_transaction(self, ignore_duplicate=True, keep_original=True):
         try:
             _logger.info(
@@ -687,6 +804,11 @@ class BalWindow:
             if not self.heirs:
                 _logger.warning("not heirs {}".format(self.heirs))
                 return
+            # Free the coins locked by stale wallet-LOCAL will placeholders
+            # BEFORE the amount/UTXO checks below (Step 1) see them.
+            Will.remove_stale_wallet_history(
+                self.window.wallet, self.bal_plugin.HISTORY_LABEL.get()
+            )
             try:
                 self.init_class_variables()
                 Will.check_amounts(
@@ -721,8 +843,7 @@ class BalWindow:
                     )
                 )
                 return
-            locktime = Util.parse_locktime_string(self.will_settings["locktime"])
+            if self.is_locktime_below_threshold():
-            if locktime < self.date_to_check:
                 self.show_error(_("locktime is lower than threshold"))
                 return
             if not self.no_willexecutor:
@@ -915,6 +1036,13 @@ class BalWindow:
         return self.show_transaction_real(tx, parent=parent)
 
     def invalidate_will(self, will=None):
+        # The reference timestamp is normally set by init_class_variables();
+        # fall back to "now" so a first-action invalidation always has it.
+        if not hasattr(self, "date_to_check") or self.date_to_check is None:
+            self.date_to_check = resolve_date_to_check(
+                self.bal_plugin.is_basic_mode(), self.will_settings
+            )
+
         def on_success(result):
             if result:
                 self.show_message(
@@ -971,13 +1099,10 @@ class BalWindow:
                     targets = Will.only_valid(willitems)
                 for txid in targets:
                     wi = willitems[txid]
-                # Do NOT deepcopy: the stored tx carries wallet-derived objects
-                # (utxo / script_descriptor) that hold a threading.RLock, and
-                # copy.deepcopy raises "cannot pickle '_thread.RLock'".  Re-parse
-                # from the serialized form instead, which is exactly how the will
-                # is persisted/loaded (WillItem.to_dict -> serialize -> tx_from_any).
-                tx = Will.get_tx_from_any(str(wi.tx))
                     if wi.get_status("COMPLETE"):
+                        # Already signed and complete: keep as-is (the single-tx
+                        # helper short-circuits without touching the wallet).
+                        tx, _ = self._prepare_and_sign_tx(willitems, txid, password)
                         txs[txid] = tx
                         continue
                     tosign = txid
@@ -985,6 +1110,32 @@ class BalWindow:
                         self.waiting_dialog.update(get_message())
                     except Exception:
                         pass
+                    tx, _signed = self._prepare_and_sign_tx(willitems, txid, password)
+                    signed = tosign
+                    txs[txid] = tx
+            except Exception:
+                return None
+            return txs
+
+    def _prepare_and_sign_tx(self, willitems, txid, password):
+        """Prepare one will transaction and sign it.
+
+        Shared by the batch signer (:meth:`sign_transactions`) and the
+        per-transaction review wizard of the QR import flow
+        (:class:`WillTxReviewSignDialog`).
+
+        Returns ``(tx, newly_signed)``: ``newly_signed`` is False when the
+        transaction was already COMPLETE (nothing was signed).
+        """
+        wi = willitems[txid]
+        # Do NOT deepcopy: the stored tx carries wallet-derived objects
+        # (utxo / script_descriptor) that hold a threading.RLock, and
+        # copy.deepcopy raises "cannot pickle '_thread.RLock'".  Re-parse
+        # from the serialized form instead, which is exactly how the will
+        # is persisted/loaded (WillItem.to_dict -> serialize -> tx_from_any).
+        tx = Will.get_tx_from_any(str(wi.tx))
+        if wi.get_status("COMPLETE"):
+            return tx, False
         for txin in tx.inputs():
             prevout = txin.prevout.to_json()
             if prevout[0] in willitems:
@@ -998,12 +1149,10 @@ class BalWindow:
                 txin._TxInput__address = change.address
                 txin._TxInput__scriptpubkey = change.scriptpubkey
                 txin._TxInput__value_sats = change.value
+                txin._trusted_value_sats = change.value
 
         self.wallet.sign_transaction(tx, password, ignore_warnings=True)
-                signed = tosign
-                # is_complete = False
         if tx.is_complete():
-                    # is_complete = True
             wi.set_status("COMPLETE", True)
         # Refresh the per-item signature counts from the freshly signed
         # partial tx: at this point the signatures are still present
@@ -1015,10 +1164,7 @@ class BalWindow:
             wi.sigs_required = int(required)
         except Exception as e:
             _logger.debug(f"signature_count after signing failed: {e}")
-                txs[txid] = tx
+        return tx, True
-        except Exception:
-            return None
-        return txs
 
     def get_wallet_password(self, message=None, parent=None):
         parent = self.window if not parent else parent
@@ -1034,6 +1180,297 @@ class BalWindow:
                 password = self.get_wallet_password(message)
         return password
 
+    # ------------------------------------------------------------------ #
+    # Automatic rebuild on new transactions (AUTO_REBUILD)
+    #
+    # When the AUTO_REBUILD setting is enabled, wallet activity (a new
+    # transaction / a sync update) schedules the headless rebuild flow below,
+    # which reproduces EXACTLY what the "Build your will" wizard does at wallet
+    # close (task_phase1 / task_phase2):
+    #
+    #   * the delivery date of the rebuilt transactions is anticipated by one
+    #     day (Will.search_anticipate -> check_anticipate) so the new will
+    #     mines BEFORE the previous one and orphans it WITHOUT an on-chain
+    #     invalidation transaction;
+    #   * an on-chain invalidation transaction is built ONLY when the
+    #     anticipated locktime would fall before the check-alive threshold
+    #     (post-build check_will -> WillExpiredException), or when the
+    #     threshold is already in the past (CheckAliveError) - the same two
+    #     conditions that trigger invalidation in the wizard.
+    # ------------------------------------------------------------------ #
+
+    def schedule_auto_rebuild(self, delay_ms=None):
+        """Debounced entry point for the auto-rebuild flow.
+
+        Called by ``Plugin._wallet_activity`` (on the asyncio callback thread)
+        whenever a transaction/update is seen for this wallet.  The actual
+        rebuild is deferred through ``QTimer`` (thread-safe to schedule, runs
+        on the GUI thread) so a burst of events collapses into a single run.
+        """
+        try:
+            delay = delay_ms if delay_ms is not None else self._AUTO_REBUILD_DEBOUNCE_MS
+            QTimer.singleShot(delay, self._run_auto_rebuild)
+        except Exception as e:
+            _logger.debug("schedule_auto_rebuild failed: {}".format(e))
+
+    def _run_auto_rebuild(self):
+        """GUI-thread guard before launching the auto-rebuild worker.
+
+        Checks the cheap guards that must be evaluated on the GUI thread and,
+        when allowed, runs the headless flow in a background thread so the
+        interface is not frozen (signing/pushing can take a while).
+        """
+        if not self._auto_rebuild_allowed():
+            return
+        self._auto_rebuild_running = True
+        threading.Thread(target=self._auto_rebuild_worker, daemon=True).start()
+
+    def _auto_rebuild_worker(self):
+        try:
+            self._auto_rebuild_flow()
+        except Exception as e:
+            _logger.error("auto rebuild worker failed: {}".format(e))
+        finally:
+            self._auto_rebuild_running = False
+            QTimer.singleShot(0, self._after_auto_rebuild)
+
+    def _auto_rebuild_allowed(self):
+        """Cheap guards evaluated before running the auto-rebuild flow."""
+        if self.disable_plugin or not self.ok:
+            return False
+        if not self.bal_plugin.AUTO_REBUILD.get():
+            return False
+        if not self.willitems:
+            return False
+        if self._auto_rebuild_running:
+            return False
+        if time.time() < self._auto_rebuild_cooldown_until:
+            return False
+        return True
+
+    def maybe_auto_rebuild(self):
+        """Run the headless auto-rebuild flow synchronously on this thread.
+
+        This is the testable entry point (and what the background worker
+        runs): it reproduces the wizard's close-time flow and returns True when
+        it rebuilt/invalidated the will, False when there was nothing to do.
+        """
+        if not self._auto_rebuild_allowed():
+            return False
+        self._auto_rebuild_running = True
+        try:
+            result = self._auto_rebuild_flow()
+        finally:
+            self._auto_rebuild_running = False
+            QTimer.singleShot(0, self._after_auto_rebuild)
+        return result
+
+    def _after_auto_rebuild(self):
+        """Refresh the will tabs after an auto-rebuild (GUI thread)."""
+        try:
+            self.update_all()
+        except Exception as e:
+            _logger.debug("_after_auto_rebuild update_all failed: {}".format(e))
+        try:
+            if hasattr(self, "will_list_widget"):
+                self.will_list_widget.update()
+        except Exception:
+            pass
+
+    def _auto_rebuild_flow(self):
+        """Core headless rebuild flow (mirrors the wizard's close flow).
+
+        Returns True when the will was rebuilt or invalidated, False when there
+        was nothing to do.  Runs on the caller's thread.
+        """
+        try:
+            self._auto_rebuild_cooldown_until = (
+                time.time() + self._AUTO_REBUILD_COOLDOWN
+            )
+            _logger.info("auto rebuild: checking will after wallet activity")
+
+            # 1) Recompute date_to_check / willexecutors exactly like
+            #    init_class_variables does at the start of the wizard's phase 1.
+            #    A Check Alive threshold already in the past (ADVANCED mode)
+            #    means the old will must be invalidated on-chain.
+            try:
+                self.init_class_variables()
+            except CheckAliveError:
+                _logger.info("auto rebuild: check-alive threshold passed -> invalidate")
+                self._auto_invalidate_will()
+                return True
+            except NoHeirsException:
+                _logger.info("auto rebuild: no heirs, nothing to rebuild")
+                return False
+
+            # 2) Check the current will against the freshly computed reference
+            #    date.  A still-valid will needs no rebuild.
+            try:
+                self.check_will()
+                _logger.debug("auto rebuild: will is still valid, nothing to do")
+                return False
+            except (WillExpiredException, WillPostponedException) as e:
+                # Expired ("too late to anticipate") or a postpone on a
+                # signed/sent will: the old coins must be invalidated on-chain
+                # first.
+                _logger.info(
+                    "auto rebuild: {} -> invalidate".format(type(e).__name__)
+                )
+                self._auto_invalidate_will()
+                return True
+            except NoHeirsException:
+                return False
+            except NotCompleteWillException:
+                # The will no longer covers the wallet's current UTXOs / heirs
+                # / date: rebuild it.  The rebuild automatically anticipates
+                # the delivery date by one day when the same coins/heirs are
+                # involved (Will.search_anticipate), so the new transactions
+                # mine before the previous ones.
+                pass
+
+            # 3) Rebuild.
+            try:
+                txs = self.build_will()
+            except Exception as e:
+                _logger.error("auto rebuild: build_will failed: {}".format(e))
+                return False
+            if not txs:
+                _logger.info("auto rebuild: nothing was built")
+                return False
+
+            # 4) Re-validate the freshly built will (mirrors task_phase1 after
+            #    build_will).  If the anticipated locktime now falls before the
+            #    check-alive threshold, the previous will must be invalidated
+            #    on-chain before the new one is used - and we STOP, exactly like
+            #    the wizard ("invalidate_classic"): signing/pushing the new will
+            #    while the invalidation is not confirmed would race it for the
+            #    same inputs.  The next wallet event / manual Check continues
+            #    once the invalidation confirms.
+            try:
+                self.check_will()
+            except (WillExpiredException, WillPostponedException) as e:
+                _logger.info(
+                    "auto rebuild: anticipated locktime crossed threshold "
+                    "({}) -> invalidate old will".format(type(e).__name__)
+                )
+                self._auto_invalidate_will()
+                return True
+            except NoHeirsException:
+                return False
+            except NotCompleteWillException:
+                # The freshly rebuilt transactions simply need signing.
+                pass
+            except Exception as e:
+                _logger.error(
+                    "auto rebuild: post-build check failed: {}".format(e)
+                )
+                return False
+
+            # 5) Sign (passwordless wallets only, headlessly), persist and push
+            #    the rebuilt transactions to their will-executors: pushing the
+            #    earlier-locktime transactions is what makes them orphan the
+            #    previous ones.
+            self._auto_sign_save_push()
+            return True
+        finally:
+            # Always apply the cooldown so a burst of events (or the wallet
+            # events fired by our own persistence) cannot loop forever.
+            self._auto_rebuild_cooldown_until = (
+                time.time() + self._AUTO_REBUILD_COOLDOWN
+            )
+
+    def _auto_invalidate_will(self, will=None):
+        """Build, sign and broadcast the on-chain invalidation tx, headlessly.
+
+        Reuses the exact recipe of the wizard's ``loop_broadcast_invalidating``
+        (label set before broadcast, tx info pulled from wallet/network,
+        broadcast timeout 120s) without any dialog.  An encrypted wallet cannot
+        sign headlessly, so we stop with a logged warning and leave the
+        invalidation to the user's manual flow.
+        """
+        willitems = will if will is not None else self.willitems
+        try:
+            tx = Will.invalidate_will(
+                willitems,
+                self.wallet,
+                self.will_settings.get("baltx_fees", 1),
+                history_label=self.bal_plugin.HISTORY_LABEL.get(),
+                will_locktime=Will.get_min_locktime(
+                    willitems,
+                    default_value=getattr(self, "date_to_check", None),
+                ),
+            )
+        except Exception as e:
+            _logger.error("auto invalidate: could not build tx: {}".format(e))
+            return None
+        if not tx:
+            _logger.info("auto invalidate: no transactions to invalidate")
+            return None
+        try:
+            if self.wallet.has_keystore_encryption():
+                _logger.warning(
+                    "auto invalidate: wallet is encrypted; signing the "
+                    "invalidation requires the password -> invalidate manually"
+                )
+                return None
+            network = getattr(self.wallet, "network", None)
+            if network is None:
+                _logger.error("auto invalidate: no network, cannot broadcast")
+                return None
+            tx = self.wallet.sign_transaction(tx, None, ignore_warnings=True)
+            if not tx or not tx.is_complete():
+                raise Exception("invalidation tx not complete")
+            tx.add_info_from_wallet(self.wallet)
+            network.run_from_another_thread(tx.add_info_from_network(network))
+            txid = tx.txid()
+            if txid:
+                # Label BEFORE broadcasting so the History tab shows it the
+                # moment the tx appears (matches the wizard behaviour).
+                self.wallet.set_label(txid, "BAL Invalidate transaction")
+            network.run_from_another_thread(
+                network.broadcast_transaction(tx, timeout=120), timeout=120
+            )
+            _logger.info("auto invalidate: broadcast invalidation {}".format(txid))
+            return tx
+        except Exception as e:
+            _logger.error("auto invalidate failed: {}".format(e))
+            return None
+
+    def _auto_sign_save_push(self):
+        """Headless sign + persist + push of the rebuilt will.
+
+        Mirrors the wizard's phase 2 (sign_transactions -> save_willitems ->
+        push_transactions_to_willexecutors) without dialogs.  Encrypted
+        wallets cannot be signed headlessly, so the rebuilt transactions are
+        left unsigned ("New") for the user to sign manually.
+        """
+        try:
+            if self.wallet.has_keystore_encryption():
+                _logger.warning(
+                    "auto rebuild: wallet is encrypted; rebuilt will left "
+                    "unsigned (sign manually)"
+                )
+            else:
+                txs = self.sign_transactions(None)
+                if txs:
+                    for txid, tx in txs.items():
+                        # Store the signed tx back, like
+                        # ask_password_and_sign_transactions.on_success does
+                        # (re-parse instead of deepcopy: the signed tx may carry
+                        # wallet-derived input info holding a threading.RLock).
+                        self.willitems[txid].tx = Will.get_tx_from_any(str(tx))
+        except Exception as e:
+            _logger.error("auto rebuild: signing failed: {}".format(e))
+        try:
+            self.save_willitems()
+        except Exception as e:
+            _logger.error("auto rebuild: save_willitems failed: {}".format(e))
+        self._save_will_to_history()
+        try:
+            self.push_transactions_to_willexecutors()
+        except Exception as e:
+            _logger.error("auto rebuild: push failed: {}".format(e))
+
     def on_close(self):
         # Wallet is closing: run the closing "build will" task and tear down
         # the plugin's tabs/menu.  Each step is isolated so that one failure
@@ -1044,7 +1481,10 @@ class BalWindow:
             return
 
         # 1) Business logic: build/save the will on close (unchanged behaviour).
+        # REBUILD_ON_CLOSE gates the "Build your will" wizard only: the will is
+        # still persisted so a manual Build/Check from the session is not lost.
         try:
+            if self.bal_plugin.REBUILD_ON_CLOSE.get():
                 close_window = BalBuildWillDialog(self)
                 close_window.build_will_task()
             self.save_willitems()
@@ -1252,6 +1692,19 @@ class BalWindow:
         else:
             write_json_file(path, {wid: wi.to_dict() for wid, wi in will.items()})
 
+    def export_tx_file(self, path, will=None):
+        """Export only the serialized transactions of the given will items.
+
+        Writes a plain text file with every transaction (or PSBT) serialized
+        on a single line, separated by a comma (``tx1,tx2,tx3``). The raw hex
+        and PSBT base64 alphabets never contain a comma, so the separator is
+        unambiguous. When ``will`` is omitted the live will items are used.
+        """
+        willitems = will if will is not None else self.willitems
+        serialized = ",".join(str(wi.tx) for wid, wi in willitems.items())
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(serialized)
+
     def export_will(self, will=None):
         try:
             export_meta_gui(
@@ -1261,6 +1714,73 @@ class BalWindow:
             self.show_error(str(e))
             raise e
 
+    def export_will_dialog(self, will=None, initial_mode: Optional[str] = None):
+        """Open the unified export window (File / QR / Audio).
+
+        The window lets the user pick an All / Valid / Valid NC filter in
+        the top row and choose one of the three transports, each with its
+        contextual settings (file format for File, QR-code size and autoplay
+        for QR, KB/sec for Audio). ``will`` defaults to the live will items;
+        ``initial_mode`` opens the window directly on the given transport.
+        """
+        try:
+            willitems = will if will is not None else self.willitems
+            d = WillExportDialog(
+                self,
+                will=willitems,
+                bal_plugin=self.bal_plugin,
+                initial_mode=initial_mode or "file",
+            )
+            show_on_top(d)
+        except Exception as e:
+            self.show_error(str(e))
+            raise e
+
+    def get_audio_modem_plugin(self):
+        """Return Electrum's ``audio_modem`` plugin instance, or None.
+
+        The plugin is only usable when Electrum exposes it (the ``Plugins``
+        manager knows the name) and its optional runtime dependency
+        ``amodem`` is installed (:meth:`is_available`). Every other case
+        returns None so callers can simply hide the audio buttons.
+        """
+        try:
+            p = self.window.gui_object.plugins.get("audio_modem")
+        except Exception:
+            return None
+        if not p or not getattr(p, "is_available", lambda: False)():
+            return None
+        return p
+
+    def _audio_send_payload(self, payload):
+        """Send a transfer payload through the audio_modem plugin.
+
+        Wraps the plugin's own ``_send`` with a proper parent widget. The
+        audio channel zlib-compresses internally, so the payload is passed
+        uncompressed (no BAL ``Z`` flag needed on that transport).
+        """
+        plugin = self.get_audio_modem_plugin()
+        if plugin is None:
+            self.show_error(_("Audio MODEM plugin is not available."))
+            return
+        plugin._send(parent=self.window, blob=payload)
+
+    def set_audio_modem_bitrate(self, kbps):
+        """Set the ``audio_modem`` plugin transfer speed to ``kbps`` KB/sec.
+
+        Both the send and the receive paths read ``modem_config``, so the
+        sender and the receiver must be configured with the same speed. Raises
+        when the plugin (or its ``amodem`` dependency) is unavailable.
+        """
+        plugin = self.get_audio_modem_plugin()
+        if plugin is None:
+            raise Exception(_("Audio MODEM plugin is not available."))
+        try:
+            import amodem.config
+        except Exception as e:
+            raise Exception(str(e)) from e
+        plugin.modem_config = amodem.config.bitrates[int(kbps)]
+
     def merge_will(self, imported):
         """Merge imported will items into the live will.
 
@@ -1384,16 +1904,34 @@ class BalWindow:
 
         def on_file(path):
             try:
-                willitems = self._load_will_file(path)
+                with open(path, "r", encoding="utf-8") as f:
+                    text = f.read()
             except Exception as e:
                 self.show_error(_("Invalid will file: {}").format(e))
                 return
-            # Attach wallet/input info so the imported txs can be signed and
+            kind, data = decode_will_payload(text)
-            # broadcast (mirrors what merge_will_from_file does).
+            try:
+                if kind == "will":
+                    willitems = self._load_will_payload(data)
+                    # Attach wallet/input info so the imported txs can be
+                    # signed and broadcast (mirrors merge_will_from_file).
                     Will.normalize_will(willitems, self.wallet)
                     for wi in willitems.values():
                         wi.set_status("IMPORTED", True)
                     imported.update(willitems)
+                else:
+                    # Serialized transactions: route through the shared import
+                    # tail (validity pass + review/sign wizard).
+                    _complete_import(
+                        self,
+                        self.bal_plugin,
+                        text,
+                        show_error=self.show_error,
+                        show_warning=self.show_warning,
+                        close=lambda: None,
+                    )
+            except Exception as e:
+                self.show_error(_("Invalid will file: {}").format(e))
 
         def on_success():
             if not imported:
@@ -1403,6 +1941,18 @@ class BalWindow:
 
         import_meta_gui(self.window, _("will"), on_file, on_success)
 
+    def import_will_dialog(self):
+        """Open the unified import window (File / QR / Audio).
+
+        The window offers three transports: File opens the read-only
+        :class:`WillDetailDialog` preview; QR and Audio capture the
+        transfer and send it through the per-transaction review wizard
+        (:class:`WillTxReviewSignDialog`). Every flow works on fresh
+        :class:`WillItem` objects and never touches the live will.
+        """
+        d = WillImportDialog(self, bal_plugin=self.bal_plugin)
+        show_on_top(d)
+
     def _load_will_file(self, path):
         data = read_json_file(path)
         willitems = {}
@@ -1411,6 +1961,15 @@ class BalWindow:
             willitems[k] = WillItem(data[k], _id=k)
         return willitems
 
+    def _load_will_payload(self, data):
+        """Build WillItems from decoded whole-will JSON data."""
+        willitems = {}
+        for k, v in data.items():
+            d = dict(v)
+            d["tx"] = tx_from_any(d["tx"])
+            willitems[k] = WillItem(d, _id=k)
+        return willitems
+
     def check_transactions_task(self, will):
         start = time.time()
         # Servers are now contacted in parallel (see

bal/manifest.json

@@ -1,12 +1,13 @@
 {
     "name": "bal",
     "fullname": "Bitcoin After Life",
-    "version": "0.6.1",
+    "version": "0.7.0",
     "description": "Provides free and decentralized Bitcoin inheritance support. Build time-locked 'will' transactions that transfer funds to your heirs if you stop refreshing them (dead-man's switch), optionally relayed by will-executor servers.",
     "author": "Svatantrya",
     "licence": "MIT",
     "available_for": [
-        "qt"
+        "qt",
+        "cmdline"
     ],
     "icon": "icons/bal32x32.png"
 }

docs/inheritance-options.html

@@ -308,7 +308,7 @@ executor that <em>should</em> hold your tx did not return it — re‑Broadcast
 <li><strong>Mind the dust limit.</strong> A share below Bitcoin's dust limit is skipped; if <strong>every</strong> heir is dust the build is blocked with a clear message (§4.8) — raise the amounts or use fewer heirs.</li>
 </ol>
 
-<footer>This document reflects BAL plugin v0.4.7. Behaviour is derived directly from
+<footer>This document reflects BAL plugin v0.7.0. Behaviour is derived directly from
 <code>core/will.py</code>, <code>core/heirs.py</code> and <code>gui/qt/window.py</code>.</footer>
 </div>
 

docs/inheritance-options.md

@@ -357,5 +357,5 @@ that limit.
 
 ---
 
-*This document reflects the current BAL plugin (v0.6.1). Behaviour is derived
+*This document reflects the current BAL plugin (v0.7.0). Behaviour is derived
 directly from `core/will.py`, `core/heirs.py` and `gui/qt/window.py`.*

docs/manual/README.md

@@ -475,6 +475,27 @@ transactions can have in the WILL tab, on each will‑executor that is online.
 > **NB:** When you close Electrum, the plugin automatically proceeds to execute
 > **Prepare → Sign → Broadcast** (if they have not already been completed) to
 > ensure the inheritance is correctly executed.
+>
+> Optionally, the **Rebuild on close** setting (available in **Tools → Plugins →
+> BAL**, default OFF) skips the full wizard and runs a one-shot rebuild/sign/push
+> flow when Electrum closes.
+
+---
+
+## Auto-rebuild on new transactions
+
+> **NB:** this feature requires the **Auto-rebuild** setting to be enabled
+> (available in **Tools → Plugins → BAL**, default OFF).
+
+When the **Auto-rebuild** setting is enabled, the plugin automatically rebuilds
+the will when new transactions are detected in the wallet (e.g. incoming
+payments). The delivery date is anticipated by one day so the new will orphans
+the old one on-chain without requiring a manual invalidation. An on-chain
+invalidation is only needed when the anticipated locktime crosses the **Check
+Alive** threshold (ADVANCED mode only).
+
+This is useful for wallets that receive funds regularly: the inheritance stays
+up-to-date without manual intervention.
 
 ---
 
@@ -527,6 +548,32 @@ value.
 
 ---
 
+## Command-line / headless usage
+
+BAL can also be used without the Qt GUI, via Electrum's daemon mode. This is
+useful for scripting, automation, or running on a headless server.
+
+**Prerequisites:** an Electrum daemon (`electrum daemon -d`) and a loaded wallet
+(`electrum load_wallet`).
+
+**Example:**
+
+```bash
+electrum daemon -d
+electrum load_wallet
+electrum bal_heirs_list
+electrum bal_will_prepare
+electrum bal_will_sign --password '...'
+electrum bal_will_broadcast
+electrum stop
+```
+
+All GUI operations (prepare, sign, broadcast, check, rebuild) are available as
+`bal_*` commands. See the full command table in the
+[README](../../README.md#command-line--headless-usage).
+
+---
+
 About installing a will‑executor server or collaboration, send your request to:
 **info@bitcoin-after.life**
 

pyproject.toml

@@ -6,9 +6,11 @@ target-version = "py312"
 select =["E", "W", "F", "I", "N", "B"]
 ignore = ["E501"]
 
+[tool.ruff.lint.pep8-naming]
+classmethod-decorators = ["classmethod", "classproperty"]  # electrum.util.classproperty uses cls
+
 [tool.ruff.lint.per-file-ignores]
-"bal/gui/qt/*.py" = ["F403", "F405"]   # intentional `from .common import *` hub
+"bal/gui/qt/common.py" = ["F401"]       # re-exports consumed via explicit imports
-"bal/gui/qt/common.py" = ["F401"]       # re-exports consumed via `import *`
 "bal/gui/qt/dialogs.py" = ["N802"]      # Qt overrides: closeEvent/hideEvent/getText
 "bal/gui/qt/lists.py" = ["N802"]        # Qt overrides: createEditor/setEditorData/setModelData
 "bal/gui/qt/widgets.py" = ["N802", "N815"]  # Qt overrides + Qt signal attrs (valueChanged, ...)

tests/conftest.py

@@ -0,0 +1,18 @@
+"""Shared pytest fixtures.
+
+Guards every test against cross-file network pollution: several karen7
+regtest modules historically flipped ``electrum.constants.net`` to regtest at
+import time, which broke unrelated offline tests (e.g. the CLI controller
+suite) run in the same pytest process.
+"""
+
+import pytest
+from electrum import constants
+
+
+@pytest.fixture(autouse=True)
+def _restore_network():
+    """Snapshot ``constants.net`` before each test and restore it after."""
+    prev = constants.net
+    yield
+    constants.net = prev

tests/sim_update_flows.py

@@ -21,12 +21,12 @@ Run:
     QT_QPA_PLATFORM=offscreen PYTHONPATH=electrum-src python3 tests/sim_update_flows.py
 """
 
-import copy
 import os
 import sys
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), os.pardir))
 
+from bal.core.util import copy_structure
 from bal.core.will import (
     HeirNotFoundException,
     NoHeirsException,
@@ -58,7 +58,7 @@ def _make_will_item(heirs, tx_locktime, status_complete=False):
     is forced to ``tx_locktime`` (the value frozen in the signed Bitcoin tx)."""
     d = {
         "tx": _VALID_TX_HEX,
-        "heirs": copy.deepcopy(heirs),
+        "heirs": copy_structure(heirs),
         "willexecutor": None,
         "status": "",
         "description": "",
@@ -67,7 +67,7 @@ def _make_will_item(heirs, tx_locktime, status_complete=False):
         "baltx_fees": TX_FEES,
     }
     item = WillItem(d, _id="willid_1")
-    item.STATUS = copy.deepcopy(WillItem.STATUS_DEFAULT)
+    item.STATUS = WillItem.copy_status_table(WillItem.STATUS_DEFAULT)
     # Force the locktime frozen "inside" the signed tx.
     item.tx.locktime = tx_locktime
     if status_complete:
@@ -118,7 +118,7 @@ def main():
     # Scenario 0: nothing changed -> should be coherent.
     heirs = {"alice": ["addr_alice", 5000, same_lt]}
     _run("0. nothing changed",
-         will_heirs=heirs, current_heirs=copy.deepcopy(heirs),
+         will_heirs=heirs, current_heirs=copy_structure(heirs),
          tx_locktime=base_lt, check_date=0)
 
     # Scenario 1: delivery date moved forward (postpone), will NOT yet signed.

tests/test_anticipate_manual_locktime.py

@@ -27,7 +27,6 @@ Run:
         tests/test_anticipate_manual_locktime.py -q
 """
 
-import copy
 import os
 import sys
 
@@ -35,6 +34,7 @@ sys.path.insert(0, os.path.join(os.path.dirname(__file__), os.pardir))
 
 import pytest  # noqa: E402  # pyright: ignore[reportMissingImports]
 
+from bal.core.util import copy_structure  # noqa: E402
 from bal.core.will import (  # noqa: E402
     NotCompleteWillException,
     Will,
@@ -70,7 +70,7 @@ def _make_will_item(heirs, tx_locktime, status_complete=False):
     """
     d = {
         "tx": _VALID_TX_HEX,
-        "heirs": copy.deepcopy(heirs),
+        "heirs": copy_structure(heirs),
         "willexecutor": None,
         "status": "",
         "description": "",
@@ -79,7 +79,7 @@ def _make_will_item(heirs, tx_locktime, status_complete=False):
         "baltx_fees": TX_FEES,
     }
     item = WillItem(d, _id="willid_1")
-    item.STATUS = copy.deepcopy(WillItem.STATUS_DEFAULT)
+    item.STATUS = WillItem.copy_status_table(WillItem.STATUS_DEFAULT)
     item.tx.locktime = tx_locktime
     if status_complete:
         item.set_status("COMPLETE", True)

tests/test_auto_rebuild_on_new_tx.py

@@ -0,0 +1,570 @@
+#!/usr/bin/env python3
+"""Tests for the "Rebuild automatically on new transactions" (AUTO_REBUILD)
+feature.
+
+Covers:
+
+  * the persisted ``bal_auto_rebuild`` configuration key exists and defaults
+    to OFF (False), and can be enabled and read back;
+  * the event wiring: ``Plugin._wallet_activity`` schedules the rebuild only
+    for the matching wallet and only when the setting is enabled;
+  * ``BalWindow.schedule_auto_rebuild`` debounces through ``QTimer`` and the
+    re-entrancy / cooldown guards;
+  * ``BalWindow.maybe_auto_rebuild`` reproduces the wizard's close-time flow:
+      - no-op when the will is still valid;
+      - rebuild + sign + push when a new UTXO invalidates the will (no on-chain
+        invalidation, the rebuilt tx is anticipated to mine before the old);
+      - on-chain invalidation when the check-alive threshold is already in the
+        past (CheckAliveError);
+      - on-chain invalidation when the will is already expired;
+      - on-chain invalidation when the anticipated locktime would fall before
+        the check-alive threshold (and no sign/push in that case).
+
+Run:
+    source "$BAL_HOME/electrum/env/bin/activate"
+    QT_QPA_PLATFORM=offscreen python3 tests/test_auto_rebuild_on_new_tx.py
+"""
+
+import os
+import sys
+import tempfile
+import time
+import unittest.mock as mock
+
+os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
+
+from electrum import bitcoin, crypto  # noqa: E402
+from electrum.descriptor import parse_descriptor  # noqa: E402
+from electrum.transaction import (  # noqa: E402
+    PartialTxInput,
+    PartialTxOutput,
+    TxOutpoint,
+)
+from electrum.util import bfh  # noqa: E402
+from PyQt6.QtWidgets import QApplication  # noqa: E402
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import bal.gui.qt.window as window_mod  # noqa: E402
+from bal.core.heirs import Heirs  # noqa: E402
+from bal.core.plugin_base import BalConfig, BalPlugin  # noqa: E402
+from bal.core.util import Util  # noqa: E402
+from bal.core.will import Will  # noqa: E402
+from bal.core.willexecutors import Willexecutors  # noqa: E402
+from bal.gui.qt.plugin import Plugin  # noqa: E402
+from bal.gui.qt.window import BalWindow  # noqa: E402
+
+CONFIG_KEY = "bal_auto_rebuild"
+
+# --------------------------------------------------------------------------- #
+# Fixtures
+# --------------------------------------------------------------------------- #
+
+PRIVKEY = bytes(range(32))
+PUBKEY = crypto.privkey_to_pubkey(PRIVKEY)
+ADDRESS = bitcoin.public_key_to_p2wpkh(PUBKEY)
+SCRIPT = bitcoin.address_to_script(ADDRESS)
+FUNDING_SATOSHIS = 500000
+
+
+def make_funding_input(prevout_hex="11" * 32):
+    """Return a fake wallet UTXO spendable by the will."""
+    utxo = PartialTxInput(prevout=TxOutpoint(bfh(prevout_hex), 0))
+    utxo.witness_utxo = PartialTxOutput.from_address_and_value(
+        ADDRESS, FUNDING_SATOSHIS
+    )
+    utxo._trusted_value_sats = FUNDING_SATOSHIS
+    utxo._TxInput__scriptpubkey = SCRIPT
+    utxo._TxInput__address = ADDRESS
+    return utxo
+
+
+class FakeDB:
+    def __init__(self):
+        self._data = {}
+
+    def get(self, key, default=None):
+        return self._data.get(key, default)
+
+    def put(self, key, value):
+        self._data[key] = value
+
+    def get_transaction(self, txid):
+        return None
+
+    def commit(self):
+        pass
+
+
+class FakeWallet:
+    def __init__(self, utxos):
+        self.db = FakeDB()
+        self.adb = None
+        self.network = None
+        self._utxos = list(utxos)
+        self._dust = 546
+        self._change_addresses = [ADDRESS]
+        self.labels = {}
+        self.save_db_calls = 0
+
+    def save_db(self):
+        self.save_db_calls += 1
+
+    def dust_threshold(self):
+        return self._dust
+
+    def has_keystore_encryption(self):
+        return False
+
+    def set_label(self, txid, label):
+        self.labels[txid] = label
+
+    def get_all_labels(self):
+        return dict(self.labels)
+
+    def get_label_for_txid(self, txid):
+        return self.labels.get(txid, "")
+
+    def get_utxos(self):
+        return list(self._utxos)
+
+    def get_change_addresses_for_new_transaction(self, *args, **kwargs):
+        return self._change_addresses
+
+    def add_input_info(self, txin, only_der_suffix=False):
+        pass
+
+    def add_output_info(self, txout, only_der_suffix=False):
+        pass
+
+    def get_tx_info(self, tx):
+        class _TxInfo:
+            def __init__(self):
+                class _MinedStatus:
+                    def height(self):
+                        return 0
+
+                self.tx_mined_status = _MinedStatus()
+
+        return _TxInfo()
+
+    def get_transaction(self, txid):
+        return None
+
+    def sign_transaction(self, tx, password=None, ignore_warnings=True):
+        descriptor = parse_descriptor(f"wpkh({PUBKEY.hex()})")
+        for txin in tx.inputs():
+            if txin.script_descriptor is None:
+                txin.script_descriptor = descriptor
+            if txin.value_sats() is None:
+                txin._trusted_value_sats = FUNDING_SATOSHIS
+        tx.sign({PUBKEY: PRIVKEY})
+
+
+class FakeConfig:
+    def __init__(self):
+        self._data = {}
+        self._tmpdir = tempfile.mkdtemp(prefix="bal-test-")
+
+    def electrum_path(self):
+        return self._tmpdir
+
+    def user_dir(self):
+        return self._tmpdir
+
+    def get(self, key, default=None):
+        return self._data.get(key, default)
+
+    def set_key(self, key, value, save=True):
+        self._data[key] = value
+
+
+class FakeWindow:
+    def __init__(self, wallet):
+        self.wallet = wallet
+        self.messages = []
+        self.warnings = []
+        self.errors = []
+
+    def get_decimal_point(self):
+        return 0
+
+    def show_message(self, text):
+        self.messages.append(str(text))
+
+    def show_warning(self, text, parent=None, title=None):
+        self.warnings.append(str(text))
+
+    def show_error(self, text):
+        self.errors.append(str(text))
+
+    def show_critical(self, text):
+        self.errors.append(str(text))
+
+    def update_status(self):
+        pass
+
+
+def make_controller(utxos=None):
+    """Build a fully-wired BalWindow without constructing the Qt tabs."""
+    utxos = [make_funding_input()] if utxos is None else utxos
+    config = FakeConfig()
+    wallet = FakeWallet(utxos)
+    window = FakeWindow(wallet)
+
+    plugin = BalPlugin(None, config, "bal")
+    plugin.get_window_title = lambda title: str(title)
+    plugin.get_decimal_point = window.get_decimal_point
+    plugin.NO_WILLEXECUTOR.set(True)
+    plugin.AUTO_REBUILD.set(True)
+
+    ctl = BalWindow.__new__(BalWindow)
+    ctl.bal_plugin = plugin
+    ctl.window = window
+    ctl.wallet = wallet
+    ctl.will = {}
+    ctl.willitems = {}
+    ctl.willexecutors = {}
+    ctl.will_settings = plugin.WILL_SETTINGS.get()
+    Util.fix_will_settings_tx_fees(ctl.will_settings)
+    ctl.heirs = Heirs(wallet)
+    ctl.heirs["alice"] = [ADDRESS, "100000", "1y"]
+    ctl.heirs["bob"] = [ADDRESS, "100%", "1y"]
+    ctl.no_willexecutor = True
+    ctl.disable_plugin = False
+    ctl.ok = True
+    ctl.update_all = lambda: None
+    ctl._schedule_history_refresh = lambda: None
+    ctl._auto_rebuild_running = False
+    ctl._auto_rebuild_cooldown_until = 0.0
+    return ctl
+
+
+def _no_willexecutors():
+    """Force an empty will-executor list (offline tests)."""
+    return mock.patch.object(
+        Willexecutors,
+        "get_willexecutors",
+        return_value={},
+    )
+
+
+def _single(controller):
+    """Return (txid, WillItem) for the controller's single will item."""
+    assert len(controller.willitems) == 1, controller.willitems
+    return next(iter(controller.willitems.items()))
+
+
+def _item_spending(controller, *prevout_hexes):
+    """Return the will item whose tx spends exactly the given prevouts."""
+    wanted = sorted(h for h in prevout_hexes)
+    items = [
+        item
+        for item in controller.willitems.values()
+        if sorted(i.prevout.txid.hex() for i in item.tx.inputs()) == wanted
+    ]
+    assert len(items) == 1, controller.willitems
+    return items[0]
+
+
+# --------------------------------------------------------------------------- #
+# Config key
+# --------------------------------------------------------------------------- #
+
+def test_auto_rebuild_config_defaults_off():
+    """bal_auto_rebuild must default to OFF (False) when not yet stored."""
+    cfg = FakeConfig()
+    rebuild = BalConfig(cfg, CONFIG_KEY, False)
+    assert rebuild.get() is False
+
+
+def test_auto_rebuild_config_can_be_enabled():
+    """Once enabled and persisted, bal_auto_rebuild reads back True."""
+    cfg = FakeConfig()
+    rebuild = BalConfig(cfg, CONFIG_KEY, False)
+    rebuild.set(True)
+    assert rebuild.get() is True
+    assert BalConfig(cfg, CONFIG_KEY, False).get() is True
+
+
+# --------------------------------------------------------------------------- #
+# Event wiring (Plugin._wallet_activity)
+# --------------------------------------------------------------------------- #
+
+def test_wallet_activity_schedules_only_matching_wallet():
+    plugin = Plugin.__new__(Plugin)
+    plugin.AUTO_REBUILD = BalConfig(FakeConfig(), CONFIG_KEY, True)
+    wallet_a = FakeWallet([make_funding_input()])
+    wallet_b = FakeWallet([make_funding_input()])
+
+    scheduled = []
+
+    class _Win:
+        wallet = wallet_a
+        ok = True
+        disable_plugin = False
+
+        def schedule_auto_rebuild(self):
+            scheduled.append(self)
+
+    win = _Win()
+    plugin.bal_windows = {"a": win}
+
+    plugin._wallet_activity(wallet_b)
+    assert scheduled == [], "a different wallet must not schedule a rebuild"
+
+    plugin._wallet_activity(wallet_a)
+    assert scheduled == [win], "the matching wallet must schedule a rebuild"
+
+
+def test_wallet_activity_skips_when_disabled():
+    plugin = Plugin.__new__(Plugin)
+    plugin.AUTO_REBUILD = BalConfig(FakeConfig(), CONFIG_KEY, False)
+    wallet_obj = FakeWallet([make_funding_input()])
+
+    scheduled = []
+
+    class _Win:
+        wallet = wallet_obj
+        ok = True
+        disable_plugin = False
+
+        def schedule_auto_rebuild(self):
+            scheduled.append(self)
+
+    plugin.bal_windows = {"a": _Win()}
+
+    plugin._wallet_activity(wallet_obj)
+    assert scheduled == [], "AUTO_REBUILD off must not schedule anything"
+
+
+# --------------------------------------------------------------------------- #
+# Scheduling / guards
+# --------------------------------------------------------------------------- #
+
+def test_schedule_auto_rebuild_debounces():
+    ctl = make_controller()
+    with mock.patch.object(window_mod.QTimer, "singleShot") as single_shot:
+        ctl.schedule_auto_rebuild()
+    single_shot.assert_called_once_with(
+        ctl._AUTO_REBUILD_DEBOUNCE_MS, ctl._run_auto_rebuild
+    )
+
+
+def test_auto_rebuild_guards():
+    with _no_willexecutors():
+        ctl = make_controller()
+        ctl.prepare_will()
+    assert ctl._auto_rebuild_allowed() is True
+    # Re-entrancy guard.
+    ctl._auto_rebuild_running = True
+    assert ctl._auto_rebuild_allowed() is False
+    ctl._auto_rebuild_running = False
+    # Cooldown guard.
+    ctl._auto_rebuild_cooldown_until = time.time() + 100
+    assert ctl._auto_rebuild_allowed() is False
+    ctl._auto_rebuild_cooldown_until = 0.0
+    assert ctl._auto_rebuild_allowed() is True
+    # Disabled / inactive guards.
+    ctl.disable_plugin = True
+    assert ctl._auto_rebuild_allowed() is False
+    ctl.disable_plugin = False
+    ctl.ok = False
+    assert ctl._auto_rebuild_allowed() is False
+
+
+def test_run_auto_rebuild_spawns_worker_when_allowed():
+    with _no_willexecutors():
+        ctl = make_controller()
+        ctl.prepare_will()
+
+    started = []
+
+    class FakeThread:
+        def __init__(self, target, daemon=None):
+            self.target = target
+
+        def start(self):
+            started.append(self.target)
+
+    with mock.patch.object(window_mod.threading, "Thread", FakeThread):
+        ctl._run_auto_rebuild()
+    assert len(started) == 1, "the worker thread must be spawned"
+
+
+# --------------------------------------------------------------------------- #
+# maybe_auto_rebuild behaviour
+# --------------------------------------------------------------------------- #
+
+def test_auto_rebuild_noop_when_disabled():
+    with _no_willexecutors():
+        ctl = make_controller()
+        ctl.prepare_will()
+        ctl.bal_plugin.AUTO_REBUILD.set(False)
+        txid_before, _ = _single(ctl)
+
+        result = ctl.maybe_auto_rebuild()
+
+    assert result is False
+    txid_after, _ = _single(ctl)
+    assert txid_after == txid_before, "disabled flow must not touch the will"
+
+
+def test_auto_rebuild_noop_without_will():
+    with _no_willexecutors():
+        ctl = make_controller()
+        assert not ctl.willitems
+        result = ctl.maybe_auto_rebuild()
+    assert result is False
+
+
+def test_auto_rebuild_noop_when_will_valid():
+    with _no_willexecutors():
+        ctl = make_controller()
+        ctl.prepare_will()
+        txid_before, _ = _single(ctl)
+
+        with mock.patch.object(ctl, "_auto_invalidate_will") as inv, mock.patch.object(
+            ctl, "_auto_sign_save_push"
+        ) as sign:
+            result = ctl.maybe_auto_rebuild()
+
+    assert result is False
+    txid_after, _ = _single(ctl)
+    assert txid_after == txid_before, "a valid will must not be rebuilt"
+    inv.assert_not_called()
+    sign.assert_not_called()
+
+
+def test_auto_rebuild_rebuilds_and_pushes_on_new_utxo():
+    with _no_willexecutors():
+        ctl = make_controller()
+        # A relative delivery recipe keeps the will coherent after the rebuild
+        # anticipates the locktime by one day (an absolute recipe would read the
+        # anticipated tx as a postpone, see check_willexecutors_and_heirs).
+        ctl.will_settings["locktime"] = "1y"
+        ctl.prepare_will()
+        old_txid, old_item = _single(ctl)
+        old_locktime = int(old_item.tx.locktime)
+
+        # An incoming payment adds a second UTXO -> the will no longer covers
+        # the whole wallet (NotCompleteWillException).
+        ctl.wallet._utxos.append(make_funding_input("22" * 32))
+
+        with mock.patch.object(ctl, "_auto_invalidate_will") as inv, mock.patch.object(
+            ctl, "push_transactions_to_willexecutors"
+        ) as push, mock.patch.object(ctl, "_save_will_to_history") as history:
+            result = ctl.maybe_auto_rebuild()
+
+    assert result is True, "a stale will must be rebuilt"
+    assert inv.call_count == 0, "a plain rebuild must not invalidate on-chain"
+    push.assert_called_once()
+    history.assert_called_once()
+
+    # The rebuilt will now spends BOTH wallet UTXOs (BAL keeps the previous
+    # single-input transaction alongside it in the will).
+    new_item = _item_spending(ctl, "11" * 32, "22" * 32)
+    assert new_item.tx.txid() != old_txid, "the rebuilt will must replace the old tx"
+    # The new locktime must be at most the old one, so the new tx can be mined
+    # before the previous will.
+    assert int(new_item.tx.locktime) <= old_locktime
+    assert new_item.get_status("COMPLETE"), "passwordless rebuild must sign"
+    assert new_item.get_status("VALID")
+
+    # The rebuilt will is still valid now: no further work.
+    assert ctl.check_will() is True
+
+
+def test_auto_rebuild_invalidates_when_threshold_passed():
+    with _no_willexecutors():
+        ctl = make_controller()
+        ctl.prepare_will()
+        # ADVANCED mode with a check-alive threshold already in the past.
+        ctl.bal_plugin.USER_TYPE.set("advanced")
+        ctl.will_settings["threshold"] = int(time.time()) - 3600
+
+        with mock.patch.object(ctl, "_auto_invalidate_will") as inv, mock.patch.object(
+            ctl, "_auto_sign_save_push"
+        ) as sign:
+            result = ctl.maybe_auto_rebuild()
+
+    assert result is True
+    inv.assert_called_once()
+    sign.assert_not_called()
+
+
+def test_auto_rebuild_invalidates_when_locktime_expired():
+    with _no_willexecutors():
+        ctl = make_controller()
+        ctl.prepare_will()
+        txid, item = _single(ctl)
+        # Move the frozen delivery date into the past: "too late to
+        # anticipate" -> the old will must be invalidated on-chain.
+        item.tx.locktime = int(time.time()) - 2 * 86400
+
+        with mock.patch.object(ctl, "_auto_invalidate_will") as inv, mock.patch.object(
+            ctl, "_auto_sign_save_push"
+        ) as sign:
+            result = ctl.maybe_auto_rebuild()
+
+    assert result is True
+    inv.assert_called_once()
+    sign.assert_not_called()
+
+
+def test_auto_rebuild_invalidates_when_anticipation_crosses_threshold():
+    with _no_willexecutors():
+        ctl = make_controller()
+        now = time.time()
+        delivery = int(now + 3 * 86400)
+        ctl.will_settings["locktime"] = delivery
+        # ADVANCED mode: the check-alive threshold sits 12h before delivery, so
+        # an anticipated (delivery - 1 day) locktime falls BEFORE it.
+        ctl.bal_plugin.USER_TYPE.set("advanced")
+        ctl.will_settings["threshold"] = delivery - 12 * 3600
+
+        ctl.prepare_will()
+        old_txid, _ = _single(ctl)
+        ctl.wallet._utxos.append(make_funding_input("22" * 32))
+
+        # The rebuild itself anticipates the delivery date by one day ONLY when
+        # the rebuilt transactions keep the same real amounts (Will.check_anticipate,
+        # same coins + same heirs).  Real amounts are re-computed against the
+        # wallet balance, so a new UTXO normally changes them and the rebuilt
+        # will keeps the old locktime.  Force the anticipating branch here to
+        # exercise the "anticipated locktime crosses the threshold" handling.
+        with mock.patch.object(
+            Will, "check_anticipate", return_value=delivery - 86400
+        ):
+            with mock.patch.object(
+                ctl, "_auto_invalidate_will"
+            ) as inv, mock.patch.object(ctl, "_auto_sign_save_push") as sign:
+                result = ctl.maybe_auto_rebuild()
+
+    assert result is True
+    inv.assert_called_once(), (
+        "an anticipated locktime below the threshold must invalidate on-chain"
+    )
+    sign.assert_not_called(), (
+        "after an invalidation the rebuilt will must NOT be signed/pushed "
+        "(the wizard stops and waits for the invalidation to confirm)"
+    )
+    new_item = _item_spending(ctl, "11" * 32, "22" * 32)
+    assert new_item.tx.txid() != old_txid, "the rebuilt will must replace the old tx"
+    assert int(new_item.tx.locktime) == delivery - 86400, (
+        "the rebuilt locktime must be anticipated by one day"
+    )
+
+
+def _run_all():
+    tests = [fn for name, fn in sorted(globals().items()) if name.startswith("test_")]
+    for fn in tests:
+        print(f"{fn.__name__} ... ", end="", flush=True)
+        fn()
+        print("OK")
+    print(f"\n{len(tests)} tests passed")
+
+
+if __name__ == "__main__":
+    app = QApplication.instance() or QApplication([])
+    _run_all()

tests/test_cli_autorebuild.py

@@ -0,0 +1,339 @@
+#!/usr/bin/env python3
+"""Tests for the headless auto-rebuild flow (``bal_will_autorebuild``).
+
+The CLI equivalent of the GUI AUTO_REBUILD feature:
+``BalController.auto_rebuild`` runs the wizard's close-time flow in a single
+call.  Everything is exercised offline against a fake signing wallet (the same
+fixtures the GUI tests use), so no wallet, network or Qt is needed.
+
+Covers:
+
+  * no-op when the will is still valid (``valid``);
+  * rebuild + sign + push when a new UTXO invalidates the will (``rebuilt``,
+    no on-chain invalidation: the rebuilt tx is anticipated to mine before
+    the old one);
+  * ``needs_signing`` when the wallet is encrypted;
+  * on-chain invalidation when the will is already expired (``expired``);
+  * on-chain invalidation when the anticipated locktime crosses the check-alive
+    threshold (``anticipation_crossed``) - and no sign/push in that case.
+
+The ``no_heirs`` and ``threshold_passed`` paths live in
+``test_cli_controller_offline.py``.
+
+Run:
+    source "$BAL_HOME/electrum/env/bin/activate"
+    python3 tests/test_cli_autorebuild.py
+"""
+
+import os
+import shutil
+import sys
+import tempfile
+import time
+import unittest.mock as mock
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), os.pardir))
+
+from electrum import bitcoin, crypto
+from electrum.descriptor import parse_descriptor
+from electrum.simple_config import SimpleConfig
+from electrum.transaction import PartialTxInput, PartialTxOutput, TxOutpoint
+from electrum.util import bfh
+
+from bal.cli.controller import BalController
+from bal.core.will import Will
+from bal.core.willexecutors import Willexecutors
+
+PRIVKEY = bytes(range(32))
+PUBKEY = crypto.privkey_to_pubkey(PRIVKEY)
+ADDRESS = bitcoin.public_key_to_p2wpkh(PUBKEY)
+SCRIPT = bitcoin.address_to_script(ADDRESS)
+FUNDING_SATOSHIS = 500000
+
+
+def make_funding_input(prevout_hex="11" * 32):
+    """Return a fake wallet UTXO spendable by the will."""
+    utxo = PartialTxInput(prevout=TxOutpoint(bfh(prevout_hex), 0))
+    utxo.witness_utxo = PartialTxOutput.from_address_and_value(
+        ADDRESS, FUNDING_SATOSHIS
+    )
+    utxo._trusted_value_sats = FUNDING_SATOSHIS
+    utxo._TxInput__scriptpubkey = SCRIPT
+    utxo._TxInput__address = ADDRESS
+    return utxo
+
+
+class FakeDB:
+    def __init__(self):
+        self._data = {}
+
+    def get(self, key, default=None):
+        return self._data.get(key, default)
+
+    def put(self, key, value):
+        self._data[key] = value
+
+    def get_dict(self, key):
+        return self._data.setdefault(key, {})
+
+    def get_transaction(self, txid):
+        return None
+
+    def add_transaction(self, tx, *args, **kwargs):
+        pass
+
+
+class FakeWallet:
+    def __init__(self, utxos, encrypted=False):
+        self.db = FakeDB()
+        self.adb = None
+        self.network = None
+        self._utxos = list(utxos)
+        self._dust = 546
+        self._change_addresses = [ADDRESS]
+        self._encrypted = encrypted
+        self.labels = {}
+
+    def save_db(self):
+        pass
+
+    def dust_threshold(self):
+        return self._dust
+
+    def has_keystore_encryption(self):
+        return self._encrypted
+
+    def set_label(self, txid, label):
+        self.labels[txid] = label
+
+    def get_utxos(self):
+        return list(self._utxos)
+
+    def get_change_addresses_for_new_transaction(self, *args, **kwargs):
+        return self._change_addresses
+
+    def add_input_info(self, txin, only_der_suffix=False):
+        pass
+
+    def add_output_info(self, txout, only_der_suffix=False):
+        pass
+
+    def get_tx_info(self, tx):
+        class _TxInfo:
+            def __init__(self):
+                class _MinedStatus:
+                    def height(self):
+                        return 0
+
+                self.tx_mined_status = _MinedStatus()
+
+        return _TxInfo()
+
+    def get_transaction(self, txid):
+        return None
+
+    def sign_transaction(self, tx, password=None, ignore_warnings=True):
+        descriptor = parse_descriptor(f"wpkh({PUBKEY.hex()})")
+        for txin in tx.inputs():
+            if txin.script_descriptor is None:
+                txin.script_descriptor = descriptor
+            if txin.value_sats() is None:
+                txin._trusted_value_sats = FUNDING_SATOSHIS
+        tx.sign({PUBKEY: PRIVKEY})
+
+
+class _Plugin:
+    """Real ``bal.cli.plugin.Plugin`` with an isolated config directory."""
+
+    def __init__(self):
+        self.tmpdir = tempfile.mkdtemp(prefix="bal_cli_autorebuild_")
+        from bal.cli.plugin import Plugin as RealPlugin
+
+        self.config = SimpleConfig(
+            {"electrum_path": self.tmpdir},
+            read_user_config_function=lambda path: {},
+        )
+        self.plugin = RealPlugin(None, self.config, "bal")
+
+    def __enter__(self):
+        return self.plugin
+
+    def __exit__(self, *exc):
+        shutil.rmtree(self.tmpdir, ignore_errors=True)
+
+
+def _no_willexecutors():
+    """Force an empty will-executor list (offline tests)."""
+    return mock.patch.object(
+        Willexecutors,
+        "get_willexecutors",
+        return_value={},
+    )
+
+
+def _make_controller(plugin, wallet):
+    c = BalController(plugin, wallet)
+    c.will_settings["locktime"] = "1y"
+    c.heirs_add("alice", ADDRESS, "100000")
+    c.heirs_add("bob", ADDRESS, "100%")
+    return c
+
+
+def _single(controller):
+    """Return (txid, WillItem) for the controller's single will item."""
+    assert len(controller.willitems) == 1, controller.willitems
+    return next(iter(controller.willitems.items()))
+
+
+def _item_spending(controller, *prevout_hexes):
+    """Return the will item whose tx spends exactly the given prevouts."""
+    wanted = sorted(h for h in prevout_hexes)
+    items = [
+        item
+        for item in controller.willitems.values()
+        if sorted(i.prevout.txid.hex() for i in item.tx.inputs()) == wanted
+    ]
+    assert len(items) == 1, controller.willitems
+    return items[0]
+
+
+# --------------------------------------------------------------------------- #
+# auto_rebuild behaviour
+# --------------------------------------------------------------------------- #
+
+def test_auto_rebuild_noop_when_will_valid():
+    with _no_willexecutors():
+        with _Plugin() as plugin:
+            plugin.NO_WILLEXECUTOR.set(True)
+            wallet = FakeWallet([make_funding_input()])
+            c = _make_controller(plugin, wallet)
+            c.prepare_will()
+            txid_before, _ = _single(c)
+
+            result = c.auto_rebuild()
+
+    assert result["result"] == "valid", result
+    assert next(iter(c.willitems)) == txid_before, (
+        "a valid will must not be rebuilt"
+    )
+
+
+def test_auto_rebuild_rebuilds_and_pushes_on_new_utxo():
+    with _no_willexecutors():
+        with _Plugin() as plugin:
+            plugin.NO_WILLEXECUTOR.set(True)
+            wallet = FakeWallet([make_funding_input()])
+            c = _make_controller(plugin, wallet)
+            c.prepare_will()
+            old_txid, old_item = _single(c)
+            old_locktime = int(old_item.tx.locktime)
+
+            # An incoming payment adds a second UTXO -> the will no longer
+            # covers the whole wallet (NotCompleteWillException).
+            wallet._utxos.append(make_funding_input("22" * 32))
+
+            result = c.auto_rebuild()
+
+    assert result["result"] == "rebuilt", result
+    assert result["push"] == {}
+
+    new_item = _item_spending(c, "11" * 32, "22" * 32)
+    assert new_item.tx.txid() != old_txid, "the rebuilt will must replace the old tx"
+    assert int(new_item.tx.locktime) <= old_locktime, (
+        "the rebuilt tx must be anticipatable before the old will"
+    )
+    assert new_item.get_status("COMPLETE"), "passwordless rebuild must sign"
+    assert new_item.get_status("VALID")
+
+    # The rebuilt will is still valid now: no further work.
+    assert c.check_will() is True
+
+
+def test_auto_rebuild_encrypted_wallet_requires_manual_signing():
+    with _no_willexecutors():
+        with _Plugin() as plugin:
+            plugin.NO_WILLEXECUTOR.set(True)
+            wallet = FakeWallet([make_funding_input()], encrypted=True)
+            c = _make_controller(plugin, wallet)
+            c.prepare_will()
+            wallet._utxos.append(make_funding_input("22" * 32))
+
+            result = c.auto_rebuild()
+
+    assert result["result"] == "needs_signing", result
+    assert result["will"]["count"] == 2
+    assert not any(w.get_status("COMPLETE") for w in c.willitems.values()), (
+        "an encrypted wallet must never be signed without the password"
+    )
+
+
+def test_auto_rebuild_invalidates_when_locktime_expired():
+    with _no_willexecutors():
+        with _Plugin() as plugin:
+            plugin.NO_WILLEXECUTOR.set(True)
+            wallet = FakeWallet([make_funding_input()])
+            c = _make_controller(plugin, wallet)
+            c.prepare_will()
+            _, item = _single(c)
+            # Move the frozen delivery date into the past: "too late to
+            # anticipate" -> the old will must be invalidated on-chain.
+            item.tx.locktime = int(time.time()) - 2 * 86400
+
+            result = c.auto_rebuild()
+
+    assert result["result"] == "invalidated", result
+    assert result["reason"] == "expired"
+    assert result["invalidation_tx"]["txid"] is not None
+    assert result["invalidation_tx"]["tx"]
+    assert not any(w.get_status("COMPLETE") for w in c.willitems.values())
+
+
+def test_auto_rebuild_invalidates_when_anticipation_crosses_threshold():
+    with _no_willexecutors():
+        with _Plugin() as plugin:
+            now = time.time()
+            delivery = int(now + 3 * 86400)
+            # ADVANCED mode: the check-alive threshold sits 12h before delivery,
+            # so an anticipated (delivery - 1 day) locktime falls BEFORE it.
+            plugin.USER_TYPE.set("advanced")
+            wallet = FakeWallet([make_funding_input()])
+            plugin.NO_WILLEXECUTOR.set(True)
+            c = _make_controller(plugin, wallet)
+            c.will_settings["locktime"] = delivery
+            c.will_settings["threshold"] = delivery - 12 * 3600
+            c.prepare_will()
+            old_txid, _ = _single(c)
+            wallet._utxos.append(make_funding_input("22" * 32))
+
+            # Force the anticipating branch (see the GUI test for the rationale:
+            # with a new UTXO the real amounts change, so the natural rebuild
+            # keeps the old locktime).
+            with mock.patch.object(
+                Will, "check_anticipate", return_value=delivery - 86400
+            ):
+                result = c.auto_rebuild()
+
+    assert result["result"] == "invalidated", result
+    assert result["reason"] == "anticipation_crossed"
+    assert not any(w.get_status("COMPLETE") for w in c.willitems.values()), (
+        "after an invalidation the rebuilt will must NOT be signed/pushed "
+        "(the wizard stops and waits for the invalidation to confirm)"
+    )
+    new_item = _item_spending(c, "11" * 32, "22" * 32)
+    assert new_item.tx.txid() != old_txid, "the rebuilt will must replace the old tx"
+    assert int(new_item.tx.locktime) == delivery - 86400, (
+        "the rebuilt locktime must be anticipated by one day"
+    )
+
+
+def _run_all():
+    tests = [fn for name, fn in sorted(globals().items()) if name.startswith("test_")]
+    for fn in tests:
+        print(f"{fn.__name__} ... ", end="", flush=True)
+        fn()
+        print("OK")
+    print(f"\n{len(tests)} tests passed")
+
+
+if __name__ == "__main__":
+    _run_all()

tests/test_cli_commands_registered.py

@@ -0,0 +1,150 @@
+"""
+Test: BAL plugin CLI commands are registered with Electrum.
+
+Verifies that importing the plugin through Electrum's own plugin loader
+(``Plugins(config, cmd_only=True)``, the exact code path ``run_electrum`` uses
+to pre-parse the command line) registers every ``bal_*`` command with
+``electrum.commands`` (``known_commands`` + the ``Commands`` class).
+
+It also asserts the basic contract enforced by ``plugin_command``: each command
+is a coroutine and carries the expected flags (all ``bal_*`` commands require a
+daemon/network, i.e. the ``'n'`` flag; the wallet-bound ones the ``'w'`` flag;
+signing also ``'p'``).
+
+Run:
+    source "$BAL_HOME/electrum/env/bin/activate"
+    python3 tests/test_cli_commands_registered.py
+"""
+
+import inspect
+import tempfile
+
+from electrum import commands as electrum_commands
+from electrum.plugin import Plugins
+from electrum.simple_config import SimpleConfig
+
+# The full command table lives in PLAN_CMDLINE_PLUGIN.md section 6; new commands
+# added in later phases must be appended here so the registration test keeps
+# proving the whole list is wired up.
+EXPECTED_COMMANDS = {
+    # Settings (no wallet required)
+    "bal_settings_list": {
+        "requires_network": True,
+        "requires_wallet": False,
+        "requires_password": False,
+    },
+    "bal_settings_get": {
+        "requires_network": True,
+        "requires_wallet": False,
+        "requires_password": False,
+    },
+    "bal_settings_set": {
+        "requires_network": True,
+        "requires_wallet": False,
+        "requires_password": False,
+    },
+    "bal_settings_reset": {
+        "requires_network": True,
+        "requires_wallet": False,
+        "requires_password": False,
+    },
+    # Heirs
+    "bal_heirs_list": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_heirs_show": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_heirs_add": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_heirs_update": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_heirs_delete": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_heirs_import": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_heirs_export": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    # Will-Executors
+    "bal_willexecutors_list": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_willexecutors_show": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_willexecutors_add": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_willexecutors_update": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_willexecutors_select": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_willexecutors_delete": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_willexecutors_ping": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_willexecutors_download": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_willexecutors_import": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_willexecutors_export": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    # Will
+    "bal_will_status": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_will_check": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_will_prepare": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_will_autorebuild": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_will_sign": {"requires_network": True, "requires_wallet": True, "requires_password": True},
+    "bal_will_broadcast": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_will_export": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_will_import_merge": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_will_invalidate": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+    "bal_will_check_executor": {"requires_network": True, "requires_wallet": True, "requires_password": False},
+}
+
+
+def _isolated_config(**overrides):
+    """A throwaway SimpleConfig that never touches the real Electrum config.
+
+    A fresh ``electrum_path`` temp dir keeps every write isolated, so running
+    the tests cannot pollute the user's config files.  The bal plugin is
+    enabled because ``Plugins(cmd_only=True)`` skips any plugin that is not
+    explicitly enabled (electrum.plugin.Plugins.find_directory_plugins).
+    """
+    opts = {"electrum_path": tempfile.mkdtemp(prefix="bal_test_")}
+    opts.update(overrides)
+    cfg = SimpleConfig(opts)
+    cfg.enable_plugin("bal")
+    return cfg
+
+
+def test_commands_registered():
+    cfg = _isolated_config()
+    Plugins(cfg, cmd_only=True)
+    for name, flags in EXPECTED_COMMANDS.items():
+        assert name in electrum_commands.known_commands, f"{name} not registered"
+        cmd = electrum_commands.known_commands[name]
+        assert cmd.name == name
+        assert cmd.requires_network is flags["requires_network"]
+        assert cmd.requires_wallet is flags["requires_wallet"]
+        assert cmd.requires_password is flags["requires_password"]
+
+
+def test_commands_are_coroutines():
+    cfg = _isolated_config()
+    Plugins(cfg, cmd_only=True)
+    for name in EXPECTED_COMMANDS:
+        func = getattr(electrum_commands.Commands, name, None)
+        assert func is not None, f"{name} missing from Commands"
+        assert inspect.iscoroutinefunction(func), f"{name} is not a coroutine"
+
+
+def test_no_duplicate_registration():
+    """Loading the plugin twice must not raise "Command name bal_... already
+    exists" (the guard in bal/__init__._register_cli_commands)."""
+    cfg = _isolated_config()
+    plugins = Plugins(cfg, cmd_only=True)
+    plugins.maybe_load_plugin_init_method("bal")  # already imported -> no-op
+    for name in EXPECTED_COMMANDS:
+        assert name in electrum_commands.known_commands
+
+
+def test_command_docstrings_document_all_args():
+    """Every parameter/option must carry an ``arg:TYPE:NAME:DESC`` line (the
+    CLI parser prints "undocumented argument ..." otherwise)."""
+    cfg = _isolated_config()
+    Plugins(cfg, cmd_only=True)
+    for name in EXPECTED_COMMANDS:
+        cmd = electrum_commands.known_commands[name]
+        for varname in list(cmd.params) + list(cmd.options):
+            if varname in ("wallet", "wallet_path", "plugin", "password"):
+                continue
+            assert varname in cmd.arg_descriptions, (
+                f"{name}: undocumented argument {varname}"
+            )
+
+
+if __name__ == "__main__":
+    for name in sorted(dir()):
+        if name.startswith("test_"):
+            globals()[name]()
+            print(f"  [OK] {name}")
+    print("[OK] All CLI registration tests passed")

tests/test_cli_controller_offline.py

@@ -0,0 +1,288 @@
+"""
+Offline tests for the headless ``bal.cli.controller.BalController``.
+
+These run without a wallet, a network or Qt: the controller is exercised
+against a ``FakeWallet`` plus a real ``bal.cli.plugin.Plugin`` backed by an
+isolated in-memory ``SimpleConfig``.  Only the flows that never touch the
+network (settings/heirs/willexecutors CRUD, status snapshots, error mapping)
+are covered here; build/sign/push flows need a live wallet and network and are
+exercised by the group tests instead.
+
+Run:
+    source electrum/env/bin/activate
+    python3 tests/test_cli_controller_offline.py
+"""
+
+import os
+import shutil
+import sys
+import tempfile
+import time
+import unittest.mock as mock
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), os.pardir))
+
+from electrum.simple_config import SimpleConfig
+from electrum.util import UserFacingException
+
+from bal.cli.controller import BalController
+from bal.core.heirs import Heirs
+from bal.core.util import Util
+
+VALID_ADDRESS = "bc1qusymuetsz2psaqzqxv8qmzcy64d9meckj3lxxf"
+
+
+class FakeDB:
+    def __init__(self):
+        self._data = {}
+
+    def get(self, key, default=None):
+        return self._data.get(key, default)
+
+    def put(self, key, value):
+        self._data[key] = value
+
+    def get_dict(self, key):
+        return self._data.setdefault(key, {})
+
+    def get_transaction(self, txid):
+        return None
+
+    def add_transaction(self, tx, *args, **kwargs):
+        pass
+
+
+class FakeWallet:
+    def __init__(self):
+        self.db = FakeDB()
+        self.network = None
+        self.adb = None
+        self._dust = 500
+
+    def save_db(self):
+        pass
+
+    def dust_threshold(self):
+        return self._dust
+
+    def has_keystore_encryption(self):
+        return False
+
+    def set_label(self, txid, text):
+        pass
+
+    def get_utxos(self):
+        return []
+
+    def get_change_addresses_for_new_transaction(self, *args, **kwargs):
+        return [VALID_ADDRESS]
+
+
+class Plugin:
+    """Real ``bal.cli.plugin.Plugin`` with an isolated config directory."""
+
+    def __init__(self):
+        self.tmpdir = tempfile.mkdtemp(prefix="bal_cli_test_")
+        from bal.cli.plugin import Plugin as RealPlugin
+
+        self.config = SimpleConfig(
+            {"electrum_path": self.tmpdir},
+            read_user_config_function=lambda path: {},
+        )
+        self.plugin = RealPlugin(None, self.config, "bal")
+
+    def __enter__(self):
+        return self.plugin
+
+    def __exit__(self, *exc):
+        shutil.rmtree(self.tmpdir, ignore_errors=True)
+
+
+def _make_controller(plugin):
+    return BalController(plugin, FakeWallet())
+
+
+def test_controller_init_empty():
+    with Plugin() as plugin:
+        c = _make_controller(plugin)
+        assert c.willitems == {}
+        assert c.will == {}
+        assert c.heirs == {}
+        assert isinstance(c.will_settings, dict)
+        assert "baltx_fees" in c.will_settings
+        # Fresh config: no stored will-executors.  On mainnet the default
+        # WILLEXECUTORS table is keyed by "mainnet" while chainname is
+        # "bitcoin", so nothing is injected either.
+        assert c.willexecutors == {}
+        assert c.no_willexecutor is False
+
+
+def test_settings_roundtrip():
+    with Plugin() as plugin:
+        c = _make_controller(plugin)
+        listing = c.settings_list()
+        assert "BAL_TX_FEES" in listing or "TX_FEES" in listing
+        tx_key = "BAL_TX_FEES" if "BAL_TX_FEES" in listing else "TX_FEES"
+        assert c.settings_get(tx_key)["value"] == 100
+
+        c.settings_set("bal_tx_fees", "150")
+        assert c.settings_get("bal_tx_fees")["value"] == 150
+        assert c.settings_get("TX_FEES")["value"] == 150
+
+        c.settings_set("bal_no_willexecutor", "true")
+        assert c.settings_get("bal_no_willexecutor")["value"] is True
+
+        c.settings_reset("bal_tx_fees")
+        assert c.settings_get("bal_tx_fees")["value"] == 100
+
+
+def test_settings_unknown_key():
+    with Plugin() as plugin:
+        c = _make_controller(plugin)
+        try:
+            c.settings_get("bal_does_not_exist")
+            raise AssertionError("expected UserFacingException")
+        except UserFacingException as e:
+            assert "Unknown BAL setting" in str(e)
+
+
+def test_heirs_crud():
+    with Plugin() as plugin:
+        c = _make_controller(plugin)
+        c.heirs_add("alice", VALID_ADDRESS, "100000")
+        assert c.heirs["alice"][0] == VALID_ADDRESS
+        assert c.heirs["alice"][1] == "100000"
+
+        c.heirs_update("alice", amount="200000")
+        assert c.heirs["alice"][1] == "200000"
+        assert c.heirs_show("alice")["value"][1] == "200000"
+
+        assert "alice" in c.heirs_list()
+        c.heirs_delete(["alice"])
+        assert "alice" not in c.heirs_list()
+
+
+def test_heirs_add_op_return():
+    with Plugin() as plugin:
+        c = _make_controller(plugin)
+        c.heirs_add("note", "OP_RETURN:6a0242414c", "100000")
+        assert c.heirs["note"][1] == "0"
+
+
+def test_willexecutors_crud():
+    with Plugin() as plugin:
+        c = _make_controller(plugin)
+        assert c.willexecutors == {}
+
+        new_url = "https://executor.example.invalid"
+        c.willexecutors_add(new_url, address="", base_fee=250)
+        assert c.willexecutors_show(new_url)["willexecutor"]["base_fee"] == 250
+        assert c.willexecutors_show(new_url)["willexecutor"]["selected"] is False
+
+        c.willexecutors_update(new_url, base_fee="300", info="Example executor")
+        assert c.willexecutors_show(new_url)["willexecutor"]["base_fee"] == 300
+
+        c.willexecutors_select([new_url], select=True)
+        assert c.willexecutors_show(new_url)["willexecutor"]["selected"] is True
+
+        renamed = "https://executor2.example.invalid"
+        c.willexecutors_update(new_url, rename_to=renamed)
+        assert renamed in c.willexecutors
+        assert new_url not in c.willexecutors
+
+        assert c.willexecutors_delete([renamed]) == {"deleted": [renamed]}
+        assert renamed not in c.willexecutors
+
+
+def test_will_status_empty():
+    with Plugin() as plugin:
+        c = _make_controller(plugin)
+        status = c.will_status()
+        assert status["count"] == 0
+        assert status["items"] == []
+
+
+def test_will_check_no_heirs_raises():
+    with Plugin() as plugin:
+        c = _make_controller(plugin)
+        try:
+            c.will_check()
+            raise AssertionError("expected UserFacingException")
+        except UserFacingException as e:
+            assert "heir" in str(e).lower()
+
+
+def test_auto_rebuild_no_heirs():
+    with Plugin() as plugin:
+        c = _make_controller(plugin)
+        assert c.auto_rebuild() == {"result": "no_heirs"}
+
+
+def test_auto_rebuild_threshold_passed_invalidates():
+    with Plugin() as plugin:
+        c = _make_controller(plugin)
+        c.heirs_add("alice", VALID_ADDRESS, "100000")
+        plugin.USER_TYPE.set("advanced")
+        c.will_settings["threshold"] = int(time.time()) - 3600
+        result = c.auto_rebuild()
+        assert result["result"] == "invalidated"
+        assert result["reason"] == "threshold_passed"
+        assert result["invalidation_tx"] == {"txid": None, "tx": None}
+
+
+def test_build_will_reanchors_date_to_check_to_new_locktime():
+    """CLI mirror of the GUI regression: ``build_will`` must re-anchor
+    ``date_to_check`` to the CURRENT heirs' earliest delivery before building,
+    so an anticipated (shortened) rebuild is not blocked by the old built-will
+    anchor (which would yield NO_FUTURE_DATE in ``get_transactions``).
+    """
+    with Plugin() as plugin:
+        plugin.USER_TYPE.set("advanced")
+        plugin.NO_WILLEXECUTOR.set(True)
+        plugin.ENABLE_MULTIVERSE.set(True)
+        plugin.WILL_SETTINGS.set({"threshold": "150d", "locktime": "2y", "baltx_fees": 20})
+        c = _make_controller(plugin)
+        c.no_willexecutor = True
+        c.heirs["alice"] = [VALID_ADDRESS, "100%", "1y"]
+
+        # Simulate an old built will frozen at 2y: reload keeps its (stale)
+        # anchor, which would reject the anticipated "1y" delivery.
+        c.init_class_variables()
+        stale_anchor = Util.parse_locktime_string("2y") - 150 * 86400
+        c.date_to_check = stale_anchor
+        assert Util.parse_locktime_string("1y") < c.date_to_check
+
+        with mock.patch.object(Heirs, "get_transactions", return_value={}) as gt:
+            result = c.build_will()
+
+        assert result == {}
+        # build_will re-anchored date_to_check to the new 1y delivery...
+        expected = Util.parse_locktime_string("1y") - 150 * 86400
+        assert abs(c.date_to_check - expected) < 3600
+        # ...and used THAT anchor as the build filter, not the stale 2y one.
+        assert gt.call_args.args[-1] == c.date_to_check
+
+
+# ------------------------------------------------------------------ #
+# runner
+# ------------------------------------------------------------------ #
+
+def main():
+    failures = 0
+    for name, fn in sorted(globals().items()):
+        if not name.startswith("test_") or not callable(fn):
+            continue
+        print(f"  {name}")
+        try:
+            fn()
+        except Exception as e:
+            failures += 1
+            print(f"  [FAIL] {name}: {e!r}")
+    if failures:
+        print(f"[FAIL] {failures} test(s) failed")
+        sys.exit(1)
+    print("[OK] All offline controller tests passed")
+
+
+if __name__ == "__main__":
+    main()

tests/test_core_animated_qr.py

@@ -0,0 +1,482 @@
+"""
+Tests for ``bal.core.animated_qr`` (BC-UR v1, BC-UR v2, BBQR interop).
+
+Validates the self-contained codecs against the published spec vectors
+(BCR-2020-004/005 BC32, BCR-2020-012 bytewords) and against byte-exact
+output captured from the reference C++ bc-ur encoder (fountain/xoshiro/
+alias-sampler parity), plus round trips, out-of-order assembly, missing-part
+fountain solving and malformed-input rejection for all four formats.
+
+Run:
+    source electrum/env/bin/activate
+    python3 tests/test_core_animated_qr.py
+"""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), os.pardir))
+
+import random
+
+from bal.core import animated_qr as aq
+
+
+def _payload(plen: int) -> bytes:
+    """Deterministic payload matching the C++ reference driver (``(i*7)&0xff``)."""
+    return bytes((i * 7) & 0xFF for i in range(plen))
+
+
+# --------------------------------------------------------------------------- #
+# BC32 (BCR-2020-004 / bcr-2020-005 rev1 reference implementation vectors)
+# --------------------------------------------------------------------------- #
+
+
+def test_bc32_official_vectors():
+    cases = [
+        (b"Hello, world", "fpjkcmr09ss8wmmjd3jq6ax7w9"),
+        (b"Hello world", "fpjkcmr0ypmk7unvvsh4ra4j"),
+        (
+            bytes.fromhex("d934063e82001eec0585ee41ab5d8e4b703a4be1f73aec21e143912c56"),
+            "my6qv05zqq0wcpv9aeq6khvwfdcr5jlp7uawcg0pgwgjc4shjm6xu",
+        ),
+    ]
+    for payload, encoded in cases:
+        assert aq.bc32_encode(payload) == encoded
+        assert aq.bc32_decode(encoded) == payload
+
+
+def test_bc32_checksum_rejected():
+    good = aq.bc32_encode(b"Hello, world")
+    corrupted = good[:-1] + ("a" if good[-1] != "a" else "b")
+    try:
+        aq.bc32_decode(corrupted)
+    except aq.AnimatedQrError:
+        pass
+    else:
+        raise AssertionError("expected AnimatedQrError for corrupted BC32")
+
+
+def test_bc32_bad_char_rejected():
+    try:
+        aq.bc32_decode("1" * 26)
+    except aq.AnimatedQrError:
+        pass
+    else:
+        raise AssertionError("expected AnimatedQrError for '1' (not in alphabet)")
+
+
+# --------------------------------------------------------------------------- #
+# Bytewords (BCR-2020-012)
+# --------------------------------------------------------------------------- #
+
+
+def test_bytewords_minimal_roundtrip():
+    samples = [bytes(range(256)), _payload(59), b"\x00"] + [
+        os.urandom(64) for _ in range(4)
+    ]
+    for data in samples:
+        words = aq.bytewords_minimal_encode(data)
+        assert len(words) == (len(data) + 4) * 2  # 2 chars per byte incl. CRC
+        assert aq.bytewords_minimal_decode(words) == data
+
+
+def test_bytewords_rejects_corrupted_crc():
+    data = _payload(40)
+    words = aq.bytewords_minimal_encode(data)
+    flip = "a" if words[-1] != "a" else "b"
+    try:
+        aq.bytewords_minimal_decode(words[:-1] + flip)
+    except aq.AnimatedQrError:
+        pass
+    else:
+        raise AssertionError("expected AnimatedQrError for corrupted CRC")
+
+
+def test_bytewords_rejects_odd_length():
+    try:
+        aq.bytewords_minimal_decode("abc")
+    except aq.AnimatedQrError:
+        pass
+    else:
+        raise AssertionError("expected AnimatedQrError for odd-length bytewords")
+
+
+# --------------------------------------------------------------------------- #
+# BC-UR v2: byte-exact parity with the reference C++ encoder
+# --------------------------------------------------------------------------- #
+
+# Reference frames from the bc-ur C++ fountain encoder
+# (payload x=(i*7)&0xFF, cbor wrapped, single-part and multipart).
+REF_V2_SINGLE_12 = "ur:bytes/gsaeatbabzcecndrehetfhfggtoeemhpmo"
+
+REF_V2_MULTI_59 = [
+    "ur:bytes/2-2/lpaoaocsfscyrpdpjzbyhdctsbtdtavtvdwyykztaxbkbycsctdsdpeefrfwgagdhghyihjzjkknlylomymtaeeccasket",
+    "ur:bytes/3-2/lpaxaocsfscyrpdpjzbyhdcthdfraeatbabzcecndrehetfhfggtghhpidinjoktkblplkmunyoypdperpryssimryrldt",
+    "ur:bytes/4-2/lpaaaocsfscyrpdpjzbyhdctsbtdtavtvdwyykztaxbkbycsctdsdpeefrfwgagdhghyihjzjkknlylomymtaefeimteue",
+    "ur:bytes/5-2/lpahaocsfscyrpdpjzbyhdctmuwltavdwlzowlurdtfrdtdihkjekkjlhkdnesdidtuywlzmwluydtdiesdnssgdaontls",
+    "ur:bytes/6-2/lpamaocsfscyrpdpjzbyhdctmuwltavdwlzowlurdtfrdtdihkjekkjlhkdnesdidtuywlzmwluydtdiesdnssisescmwt",
+    "ur:bytes/7-2/lpataocsfscyrpdpjzbyhdcthdfraeatbabzcecndrehetfhfggtghhpidinjoktkblplkmunyoypdperprysslsspplgm",
+    "ur:bytes/8-2/lpayaocsfscyrpdpjzbyhdctsbtdtavtvdwyykztaxbkbycsctdsdpeefrfwgagdhghyihjzjkknlylomymtaeonlrzebg",
+    "ur:bytes/9-2/lpasaocsfscyrpdpjzbyhdctsbtdtavtvdwyykztaxbkbycsctdsdpeefrfwgagdhghyihjzjkknlylomymtaeaaryknzt",
+    "ur:bytes/10-2/lpbkaocsfscyrpdpjzbyhdctmuwltavdwlzowlurdtfrdtdihkjekkjlhkdnesdidtuywlzmwluydtdiesdnsslotsfrfn",
+    "ur:bytes/11-2/lpbdaocsfscyrpdpjzbyhdctmuwltavdwlzowlurdtfrdtdihkjekkjlhkdnesdidtuywlzmwluydtdiesdnssdtwyrstd",
+    "ur:bytes/12-2/lpbnaocsfscyrpdpjzbyhdctsbtdtavtvdwyykztaxbkbycsctdsdpeefrfwgagdhghyihjzjkknlylomymtaegswnvdin",
+    "ur:bytes/13-2/lpbtaocsfscyrpdpjzbyhdctmuwltavdwlzowlurdtfrdtdihkjekkjlhkdnesdidtuywlzmwluydtdiesdnsshknlptee",
+]
+
+# Reference message for the 59-byte payload: byte-string head (0x58,0x3b) + data.
+REF_V2_MULTI_59_MSG = bytes([0x58, 0x3B]) + _payload(59)
+
+
+def test_v2_single_part_matches_reference():
+    frames = aq.ur2_frames(_payload(12), len(REF_V2_SINGLE_12))
+    assert frames == [REF_V2_SINGLE_12]
+
+
+def test_v2_reference_frames_decode_and_reencode_exactly():
+    message = REF_V2_MULTI_59_MSG
+    fragment_len = -(-len(message) // 2)
+    for frame in REF_V2_MULTI_59:
+        seq, seq_len, message_len, checksum, data = aq.ur2_parse_part(frame)
+        assert seq_len == 2
+        assert message_len == len(message)
+        assert checksum == aq.crc32_int(message)
+        assert len(data) == fragment_len
+        # re-encoding the parsed values reproduces the reference line exactly
+        assert aq._ur2_part_string(seq, seq_len, message_len, checksum, data) == frame
+        # our choose_fragments + partition + xor reproduces the reference data
+        indexes = aq.choose_fragments(seq, seq_len, checksum)
+        assert seq_num_indexes_valid(seq, seq_len, indexes)
+        mixed = aq._mix_fragments(aq._partition_message(message, fragment_len), indexes, fragment_len)
+        assert mixed == data
+
+
+def seq_num_indexes_valid(seq, seq_len, indexes):
+    # pure part for seq <= seq_len contains exactly fragment seq-1
+    if seq <= seq_len:
+        return indexes == {seq - 1}
+    return set(indexes) <= set(range(seq_len)) and bool(indexes)
+
+
+def test_v2_multipart_encoder_matches_reference_from_seq2():
+    # Our frames start at seq 1 (spec-aligned); parts seq 2.. must equal the
+    # reference (which starts at seq 2 due to first_seq_num=1).
+    mine = aq.ur2_frames(_payload(59), 120)
+    assert mine[0].split("/", 1)[1].startswith("1-2") or "1-2" in mine[0].split("/")[1]
+    assert mine[1:4] == REF_V2_MULTI_59[:3]
+
+
+def test_v2_reference_seq7_mix_parity():
+    # Higher-degree mixed parts (seq_len=7) also match: message uses the
+    # reference head 0x58|0x00 for the 256-byte driver payload.
+    message = bytes([0x58, 0x00]) + _payload(256)
+    seq_len = 7
+    fragment_len = -(-len(message) // seq_len)
+    frames = [
+        "ur:bytes/9-7/lpasatcfadaocyfysnjlsrhddaykztaxbkbycsctdsdpeefrfwgagdhghyihjzjkknlylomymtntoxpyprrhrtsttotluovlwdwnsrfejzhd",
+        "ur:bytes/10-7/lpbkatcfadaocyfysnjlsrhddazeahbnbwcycldedlenfsfygrgmhkhniojtkpkelslememkneolpmqzrksasotitsuevwwpwfzswzpmdrvo",
+        "ur:bytes/11-7/lpbdatcfadaocyfysnjlsrhddawkwtbbbefnaefnbebbjojybebnaebndybbbewkwtceaecedyeebebbjobnaebnbeeedybbbeztwproyapd",
+    ]
+    for frame in frames:
+        seq, sl, mlen, checksum, data = aq.ur2_parse_part(frame)
+        assert sl == seq_len and mlen == len(message)
+        assert checksum == aq.crc32_int(message)
+        mixed = aq._mix_fragments(
+            aq._partition_message(message, fragment_len),
+            aq.choose_fragments(seq, seq_len, checksum),
+            fragment_len,
+        )
+        assert mixed == data
+
+
+# --------------------------------------------------------------------------- #
+# BC-UR v2: sessions / fountain decoding
+# --------------------------------------------------------------------------- #
+
+
+def test_v2_roundtrip_in_order():
+    payload = ("BAL transfer " * 9).encode()
+    frames = aq.ur2_frames(payload, 120)
+    seq_len = int(frames[0].split("/")[1].split("-")[1])
+    assert len(frames) == 2 * seq_len  # pure wave + redundant mixed wave
+    session = aq.AnimatedQrSession()
+    for frame in frames:
+        session.add_part(frame)
+    assert session.done
+    assert session.received == session.total
+    text, _ = session.resolve()
+    assert text == payload.decode()
+
+
+def test_v2_out_of_order_and_duplicate():
+    payload = ("BAL transfer " * 9).encode()
+    frames = aq.ur2_frames(payload, 120)
+    order = list(range(len(frames)))
+    random.Random(11).shuffle(order)
+    session = aq.AnimatedQrSession()
+    for i in order:
+        status = session.add_part(frames[i])
+        assert status in ("ok", "dup")
+    session.add_part(frames[0])  # duplicate of an already-received part
+    assert session.done
+    assert session.resolve()[0] == payload.decode()
+
+
+def test_v2_solves_without_a_pure_fragment():
+    payload = ("BAL transfer " * 9).encode()
+    frames = aq.ur2_frames(payload, 120)
+    session = aq.AnimatedQrSession()
+    for frame in frames[1:]:  # drop the first pure fragment
+        session.add_part(frame)
+    assert session.done
+    assert session.resolve()[0] == payload.decode()
+
+
+def test_v2_single_part_import():
+    session = aq.AnimatedQrSession()
+    session.add_part(REF_V2_SINGLE_12)
+    assert session.done and session.total == 1
+    assert session.resolve()[0] == _payload(12).decode("latin-1")
+
+
+def test_v2_conflicting_transfer_rejected():
+    payload_a = b"AAAAAAAAAAAAAAAA"
+    payload_b = b"BBBBBBBBBBBBBBBB"
+    fa = aq.ur2_frames(payload_a, 500)[0]
+    fb = aq.ur2_frames(payload_b, 500)[0]
+    session = aq.AnimatedQrSession()
+    session.add_part(fa)
+    try:
+        session.add_part(fb)
+    except aq.TransferConflictError:
+        pass
+    else:
+        raise AssertionError("expected TransferConflictError for a different transfer")
+
+
+def test_v2_corrupt_crc_rejected():
+    frame = list(REF_V2_MULTI_59[0])
+    idx = len(frame) - 1
+    frame[idx] = "a" if frame[idx] != "a" else "b"
+    try:
+        aq.ur2_parse_part("".join(frame))
+    except aq.AnimatedQrError:
+        pass
+    else:
+        raise AssertionError("expected AnimatedQrError for a corrupt v2 part")
+
+
+def test_v2_session_cap_rejected():
+    part = aq._ur2_part_string(1, 30000, 100, 1234, b"\x00" * 100)
+    session = aq._Ur2Session()
+    try:
+        session.add(part)
+    except aq.SessionLimitError:
+        pass
+    else:
+        raise AssertionError("expected SessionLimitError for oversized seq_len")
+
+
+# --------------------------------------------------------------------------- #
+# BC-UR v1
+# --------------------------------------------------------------------------- #
+
+
+def test_v1_multipart_roundtrip():
+    payload = ("v1 transfer payload " * 6).encode()
+    frames = aq.ur1_frames(payload, 120)
+    assert len(frames) > 1
+    session = aq.AnimatedQrSession()
+    for frame in reversed(frames):
+        session.add_part(frame)
+    assert session.done
+    assert session.resolve()[0] == payload.decode()
+
+
+def test_v1_single_part_roundtrip():
+    payload = b"hello, bal"
+    frames = aq.ur1_frames(payload, 400)
+    assert len(frames) == 1
+    session = aq.AnimatedQrSession()
+    session.add_part(frames[0])
+    assert session.done and session.total == 1
+    assert session.resolve()[0] == payload.decode()
+
+
+def test_v1_headerless_single_part_import():
+    # bcr-2020-005 rev1 allows omitting the sequence header + digest entirely.
+    payload = b"hello, bal"
+    message = aq.cbor_byte_string(payload)
+    single = "ur:bytes/" + aq.bc32_encode(message)
+    assert aq.detect_format(single) == "ur1"
+    session = aq.AnimatedQrSession()
+    session.add_part(single)
+    assert session.done
+    assert session.resolve()[0] == payload.decode()
+
+
+def test_v1_digest_mismatch_rejected():
+    frame = aq.ur1_frames(b"hello, bal", 400)[0]
+    tampered = frame[:-4] + "abcd"
+    session = aq.AnimatedQrSession()
+    session.add_part(tampered)
+    try:
+        session.resolve()
+    except aq.ChecksumError:
+        pass
+    else:
+        raise AssertionError("expected ChecksumError for a tampered v1 digest")
+
+
+def test_v1_part_numbers_validated():
+    for bad in (
+        "ur:bytes/0of1/{}full".format("x" * 51),
+        "ur:bytes/2of1/{}full".format("x" * 51),
+        "ur:bytes/1of0/{}full".format("x" * 51),
+        "ur:bytes/1aof1/{}full".format("x" * 51),
+    ):
+        try:
+            aq.ur1_parse_part(bad)
+        except aq.AnimatedQrError:
+            pass
+        else:
+            raise AssertionError("expected AnimatedQrError for: {}".format(bad))
+
+
+# --------------------------------------------------------------------------- #
+# BBQR
+# --------------------------------------------------------------------------- #
+
+
+def test_bbqr_all_encodings_roundtrip():
+    payload = ("BBQR payload " * 8).encode()
+    for encoding in ("Z", "2", "H"):
+        frames = aq.bbqr_frames(payload, 90, encoding=encoding)
+        assert len(frames) >= 1
+        order = list(range(len(frames)))
+        random.Random(3).shuffle(order)
+        session = aq.AnimatedQrSession()
+        for i in order:
+            session.add_part(frames[i])
+        assert session.done
+        assert session.resolve()[0] == payload.decode()
+
+
+def test_bbqr_compression_default_and_fallback():
+    payload = ("repetitive data " * 40).encode()  # compresses well
+    frames_z = aq.bbqr_frames(payload, 90, encoding="Z")
+    # Highly compressible: Z yields one frame and a 'Z' flag.
+    assert all(f[2] == "Z" for f in frames_z)
+    assert len(frames_z) == 1
+    raw = os.urandom(600)  # incompressible
+    frames_2 = aq.bbqr_frames(raw, 90, encoding="Z")
+    assert all(f[2] == "2" for f in frames_2)  # Z loses, '2' is used
+
+
+def test_bbqr_hex_uppercase():
+    payload = b"\xde\xad\xbe\xef"
+    frame = aq.bbqr_frames(payload, 50, encoding="H")[0]
+    assert "DEADBEEF" in frame
+    encoding, _type, total, index, frag = aq.bbqr_parse_part(frame)
+    assert (encoding, total, index) == ("H", 1, 0)
+
+
+def test_bbqr_runt_last_part():
+    payload = os.urandom(33)
+    frames = aq.bbqr_frames(payload, 60, encoding="2")
+    parts = [aq.bbqr_parse_part(f)[4] for f in frames]
+    joined = aq._bbqr_decode(parts, "2")
+    assert joined == payload
+    assert len(parts[-1]) < len(parts[0])  # last part is a runt
+
+
+def test_bbqr_zlib_bomb_rejected():
+    compressed = aq._bbqr_encode(b"\x00" * 1000000, "Z")[1]
+    try:
+        aq._bbqr_decode(["0" * len(compressed)], "2")  # not zlib data
+    except aq.AnimatedQrError:
+        pass
+    # direct inflate bomb guard:
+    inflated = aq._bbqr_encode(b"\x00" * 1000000, "Z")
+    assert inflated[0] == "Z"  # 1MB zeros compresses
+    bomb = aq._bbqr_encode(b"\x00" * (aq._MAX_MESSAGE_BYTES + 100), "Z")[1]
+    parts = [bomb[i : i + 90] for i in range(0, len(bomb), 90)]
+    try:
+        aq._bbqr_decode(parts, "Z")
+    except aq.AnimatedQrError:
+        pass
+    else:
+        raise AssertionError("expected AnimatedQrError for an oversized decompression")
+
+
+def test_bbqr_part_number_limits():
+    try:
+        aq.bbqr_frames(os.urandom(30000), 40, encoding="2")
+    except aq.AnimatedQrError:
+        pass
+    else:
+        raise AssertionError("expected AnimatedQrError for too many BBQR parts")
+
+
+# --------------------------------------------------------------------------- #
+# Detection / parse_for_detection
+# --------------------------------------------------------------------------- #
+
+
+def test_detect_format_recognises_all_formats():
+    assert aq.detect_format("BALQR1|1|1||payload") == "balqr"
+    assert aq.detect_format("BAL1" + "001" + "001" + "0" + "payload") == "balqr"
+    assert aq.detect_format(aq.ur1_frames(b"x", 400)[0]) == "ur1"
+    assert aq.detect_format(aq.ur2_frames(b"x", 400)[0]) == "ur2"
+    assert aq.detect_format(aq.bbqr_frames(b"x", 50)[0]) == "bbqr"
+    assert aq.detect_format(REF_V2_SINGLE_12) == "ur2"
+    assert aq.detect_format("ur:bytes/" + aq.bc32_encode(aq.cbor_byte_string(b"x"))) == "ur1"
+
+
+def test_detect_format_rejects_garbage():
+    for text in ("", "hello world", "BALQ|1|1||a", "ur:", "ur:txn/xyz"):
+        assert aq.detect_format(text) is None, text
+    # Lenient prefix probe: a string that merely *starts* with "balqr" is
+    # reported as balqr (the strict parse then rejects it downstream).
+    assert aq.detect_format("BALQRX|1|1||a") == "balqr"
+
+
+def test_parse_for_detection_keys():
+    bal = aq.parse_for_detection("BALQR1|3|2||payload")
+    assert bal == ("balqr", "balqr:3", 3, 2)
+    # Compact v2 frame (fixed 11-char header) is detected too.
+    bal_v2 = aq.parse_for_detection("BAL1" + "007" + "004" + "0" + "payload")
+    assert bal_v2 == ("balqr", "balqr:7", 7, 4)
+    v2 = aq.parse_for_detection(aq.ur2_frames(b"x"*50, 400)[0])
+    assert v2[0] == "ur2" and v2[2] == 1 and v2[3] == 1
+    v1 = aq.parse_for_detection(aq.ur1_frames(b"x"*50, 120)[0])
+    assert v1[0] == "ur1" and v1[2] > 1 and 1 <= v1[3] <= v1[2]
+    bb = aq.parse_for_detection(aq.bbqr_frames(b"x"*50, 40)[0])
+    assert bb[0] == "bbqr" and bb[2] >= 1 and 0 <= bb[3] < bb[2]
+
+
+def test_format_names_exist():
+    for fmt in ("balqr", "ur1", "ur2", "bbqr"):
+        assert aq.format_name(fmt)
+    assert aq.format_name("nope") == "nope"
+
+
+# --------------------------------------------------------------------------- #
+if __name__ == "__main__":
+    import traceback
+
+    failures = 0
+    for _name, fn in sorted(globals().items()):
+        if _name.startswith("test_") and callable(fn):
+            try:
+                fn()
+                print("ok: {}".format(_name))
+            except Exception:
+                failures += 1
+                print("FAIL: {}".format(_name))
+                traceback.print_exc()
+    if failures:
+        print("{} test(s) failed".format(failures))
+        sys.exit(1)
+    print("all tests passed")

tests/test_core_checkalive.py

@@ -18,6 +18,7 @@ from bal.core.checkalive import (  # noqa: E402  (path insert above)
     CheckAliveError,
     check_alive_expired,
     resolve_date_to_check,
+    resolve_guard_threshold,
 )
 
 # ------------------------------------------------------------------ #
@@ -61,14 +62,14 @@ def test_advanced_mode_uses_threshold_absolute():
 def test_advanced_mode_parses_relative_threshold():
     # A relative threshold means "N days BEFORE the delivery": it resolves
     # against the stored locktime (backwards), not forward from now.
-    from datetime import datetime, timedelta
+    from datetime import datetime, timedelta, timezone
 
     fake_now = 1_800_000_000.0
     locktime = fake_now + 90 * 86400
     settings = {"threshold": "30d", "locktime": locktime}
     result = resolve_date_to_check(False, settings, now=fake_now)
     # date_to_check = (locktime, midnight-normalised) - 30 days.
-    expected = (datetime.fromtimestamp(locktime)
+    expected = (datetime.fromtimestamp(locktime, tz=timezone.utc)
                 .replace(hour=0, minute=0, second=0, microsecond=0)
                 - timedelta(days=30)).timestamp()
     assert abs(result - expected) < 1
@@ -91,7 +92,7 @@ def test_advanced_mode_relative_threshold_anchored_to_locktime():
 def test_advanced_mode_relative_threshold_with_relative_locktime():
     """A relative locktime is resolved against 'now' first, then the relative
     threshold counts N days back from it (matches the settings widget)."""
-    from datetime import datetime
+    from datetime import datetime, timezone
 
     from bal.core.plugin_base import BalTimestamp
 
@@ -100,7 +101,7 @@ def test_advanced_mode_relative_threshold_with_relative_locktime():
     result = resolve_date_to_check(False, settings, now=fake_now)
     # Recompute the expected value with the same resolution rules:
     # locktime = now + 90d (midnight-normalised), threshold = locktime - 30d.
-    locktime_dt = BalTimestamp("90d").to_date(datetime.fromtimestamp(fake_now))
+    locktime_dt = BalTimestamp("90d").to_date(datetime.fromtimestamp(fake_now, tz=timezone.utc))
     expected = BalTimestamp("30d").to_date(locktime_dt, reverse=True).timestamp()
     assert abs(result - expected) < 1
     assert result > fake_now
@@ -117,7 +118,7 @@ def test_advanced_mode_relative_locktime_anchored_to_built_tx():
     """A RELATIVE stored locktime is anchored to the built will's frozen
     delivery date (built_locktime), not to "now": an unchanged will must not
     read as expired as the clock advances (the karen7 daily-invalidate bug)."""
-    frozen = 1817438400  # frozen tx locktime (2027-08-05), built 2026-08-05
+    frozen = 1817424000  # frozen tx locktime (2027-08-05 00:00 UTC), built 2026-08-05
     settings = {"threshold": "30d", "locktime": "2y"}
     # On build day the frozen delivery is authoritative: date_to_check is
     # frozen - 30d and NEVER drifts, however much later the clock gets.
@@ -136,18 +137,88 @@ def test_advanced_mode_relative_locktime_anchored_to_built_tx():
 def test_advanced_mode_relative_locktime_without_built_tx_falls_back():
     """Without a built will there is no anchor: keeps the legacy now-based
     resolution (a moving target, used only before the first build)."""
-    from datetime import datetime
+    from datetime import datetime, timezone
 
     from bal.core.plugin_base import BalTimestamp
 
     fake_now = 1_800_000_000.0
     settings = {"threshold": "30d", "locktime": "90d"}
     result = resolve_date_to_check(False, settings, now=fake_now)
-    locktime_dt = BalTimestamp("90d").to_date(datetime.fromtimestamp(fake_now))
+    locktime_dt = BalTimestamp("90d").to_date(datetime.fromtimestamp(fake_now, tz=timezone.utc))
     expected = BalTimestamp("30d").to_date(locktime_dt, reverse=True).timestamp()
     assert abs(result - expected) < 1
 
 
+# ------------------------------------------------------------------ #
+# resolve_guard_threshold
+# ------------------------------------------------------------------ #
+
+
+def test_guard_threshold_basic_mode_returns_none():
+    fake_now = 1_800_000_000.0
+    threshold = resolve_guard_threshold(True, {"threshold": "30d"}, now=fake_now)
+    assert threshold is None
+
+
+def _guard_locktime(settings, fake_now):
+    """Reproduce the call-site locktime expression of the guard."""
+    from bal.core.plugin_base import BalTimestamp
+
+    return BalTimestamp(settings["locktime"]).to_timestamp(fake_now)
+
+
+def test_guard_threshold_absolute():
+    fake_now = 1_800_000_000.0
+    locktime = fake_now + 90 * 86400
+    threshold = locktime - 30 * 86400
+    settings = {"locktime": locktime, "threshold": threshold}
+    assert resolve_guard_threshold(False, settings, now=fake_now) == threshold
+
+
+def test_guard_threshold_relative_fresh_anchor():
+    """A relative threshold must be anchored to the FRESH locktime so the
+    guard and the settings always share one reference frame.
+
+    Regression for the false positive where a still-valid built will frozen at
+    a LONGER delivery ("2y") anchored ``date_to_check`` beyond the currently
+    stored shorter delivery ("1y"): the old guard compared the fresh "1y"
+    locktime against that anchored threshold and wrongly fired "locktime is
+    lower than threshold", even though the settings themselves are consistent
+    (locktime is 30d AFTER the threshold).
+    """
+    fake_now = 1_800_000_000.0
+    settings = {"locktime": "1y", "threshold": "30d"}
+    locktime = _guard_locktime(settings, fake_now)
+    threshold = resolve_guard_threshold(False, settings, now=fake_now)
+    assert threshold is not None
+    assert locktime > threshold  # internally consistent: no fire
+    assert threshold > fake_now
+    # The helper takes no built anchor: a frozen "2y" built will must NOT
+    # contaminate the result, although resolve_date_to_check (the expiry
+    # reference) legitimately keeps using it.
+    frozen_two_years = locktime + 365 * 86400
+    anchored = resolve_date_to_check(
+        False, settings, now=fake_now, built_locktime=frozen_two_years
+    )
+    assert anchored > threshold  # built anchor pushes date_to_check forward...
+    assert locktime < anchored  # ...which is exactly what used to fire the bug
+
+
+def test_guard_threshold_relative_locktime_absolute_threshold():
+    fake_now = 1_800_000_000.0
+    threshold = fake_now + 200 * 86400
+    settings = {"locktime": "1y", "threshold": threshold}
+    assert resolve_guard_threshold(False, settings, now=fake_now) == threshold
+    # "1y" from now is later than the stored absolute threshold: allowed.
+    locktime = _guard_locktime(settings, fake_now)
+    assert locktime > threshold
+
+
+def test_guard_threshold_missing_returns_none():
+    fake_now = 1_800_000_000.0
+    assert resolve_guard_threshold(False, {"locktime": "1y"}, now=fake_now) is None
+
+
 # ------------------------------------------------------------------ #
 # check_alive_expired
 # ------------------------------------------------------------------ #

tests/test_core_heirs.py

@@ -36,6 +36,7 @@ from bal.core.heirs import (
     is_op_return_address,
     validate_op_return_hex,
 )
+from bal.core.util import Util
 
 # ------------------------------------------------------------------ #
 # Constants
@@ -167,6 +168,32 @@ def test_heirs_amount_to_float():
     assert heirs.amount_to_float("notanumber") == 0.0
 
 
+def test_fixed_percent_lists_uses_build_anchor_for_relative_heirs():
+    """A relative heir must survive the amount filter when the build anchor
+    (``from_locktime``) is recalculated for the anticipated delivery.
+
+    Before the fix, ``build_will`` kept ``date_to_check`` anchored to the OLD
+    (longer) built will; an "1y" heir resolved before that anchor was excluded
+    by the ``cmp <= 0`` filter and the build reported NO_FUTURE_DATE.  With the
+    anchor recomputed for the new locktime (karen7: 2y -> 1y delivery) the
+    "1y" heir is kept.
+    """
+    wallet = FakeWallet()
+    heirs = Heirs(wallet)
+    heirs["carol"] = ["addr1", "100%", "1y"]
+
+    # Stale anchor (old built 2y will still frozen): "1y" is in the past
+    # relative to it -> excluded from the amount calculation.
+    stale_anchor = Util.parse_locktime_string("2y") - 150 * 86400
+    _, _, percent_heirs, _, _ = heirs.fixed_percent_lists_amount(stale_anchor, 500)
+    assert "carol" not in percent_heirs
+
+    # Recalculated anchor for the new (1y) delivery: the heir is retained.
+    new_anchor = Util.parse_locktime_string("1y") - 150 * 86400
+    _, _, percent_heirs, _, _ = heirs.fixed_percent_lists_amount(new_anchor, 500)
+    assert "carol" in percent_heirs
+
+
 # ------------------------------------------------------------------ #
 # Validation (static methods)
 # ------------------------------------------------------------------ #

tests/test_core_plugin_base.py

@@ -14,7 +14,7 @@ import time
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), os.pardir))
 
-from datetime import date, datetime, timedelta
+from datetime import date, datetime, timedelta, timezone
 
 from bal.core.plugin_base import BalConfig, BalPlugin, BalTimestamp
 
@@ -74,7 +74,7 @@ def test_bt_to_date_absolute():
 
 
 def test_bt_to_date_relative():
-    now = datetime.now()
+    now = datetime.now(timezone.utc)
 
     # relative days from now
     bt = BalTimestamp("7d")
@@ -86,8 +86,8 @@ def test_bt_to_date_relative():
     d_rev = bt.to_date(reverse=True)
     assert d_rev < now
 
-    # from explicit datetime
+    # from explicit datetime (UTC, so the naive-timestamp roundtrip below is stable)
-    base = datetime(2025, 6, 1, 12, 0, 0)
+    base = datetime(2025, 6, 1, 12, 0, 0, tzinfo=timezone.utc)
     d = bt.to_date(from_date=base)
     expected = (base + timedelta(days=7)).replace(hour=0, minute=0, second=0, microsecond=0)
     assert d == expected
@@ -101,7 +101,7 @@ def test_bt_to_date_relative():
 def test_bt_to_date_years():
     bt = BalTimestamp("1y")
     d = bt.to_date()
-    assert d > datetime.now()
+    assert d > datetime.now(timezone.utc)
 
 
 def test_bt_to_date_overflow():

tests/test_core_qr_transfer.py

@@ -0,0 +1,439 @@
+"""
+Tests for ``bal.core.qrtransfer``.
+
+Covers the BALQR frame encoding used for will transfer via QR codes /
+audio modem: encoding, framing, reassembly, malformed input and the preset
+list (optionally cross-checked against the ``qrcode`` library's EC-M
+capacity when it is installed).
+
+Run:
+    source electrum/env/bin/activate
+    python3 tests/test_core_qr_transfer.py
+"""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), os.pardir))
+
+from bal.core.qrtransfer import (
+    CHUNK_PRESETS,
+    MIN_CHUNK_SIZE,
+    InconsistentTotalError,
+    MissingFramesError,
+    QrTransferError,
+    assemble,
+    decode_transfer,
+    encode_transfer,
+    parse_frame,
+    preset_index_for_chunk_size,
+    split_frames,
+)
+
+
+def _frames(tx_strings, chunk_size, compress=False):
+    """Split a payload and return (payload, total, {index: payload})."""
+    payload = encode_transfer(tx_strings, compress=compress)
+    parsed = {}
+    total = None
+    for frame in split_frames(payload, chunk_size, compressed=compress):
+        t, index, _compressed, p = parse_frame(frame)
+        if total is not None:
+            assert total == t
+        total = t
+        parsed[index] = p
+    assert total is not None
+    return payload, total, parsed
+
+
+# --------------------------------------------------------------------------- #
+# Round trips
+# --------------------------------------------------------------------------- #
+
+
+def test_encode_decode_plain():
+    tx_strings = ["00" * 32, "aa" * 40, "ff" * 50]
+    payload = encode_transfer(tx_strings, compress=False)
+    assert decode_transfer(payload, compressed=False) == tx_strings
+
+
+def test_encode_decode_compressed():
+    tx_strings = ["00" * 32, "aa" * 40, "ff" * 50]
+    payload = encode_transfer(tx_strings, compress=True)
+    assert decode_transfer(payload, compressed=True) == tx_strings
+
+
+def test_empty_list_roundtrip():
+    assert decode_transfer(encode_transfer([]), compressed=False) == []
+
+
+# --------------------------------------------------------------------------- #
+# Framing
+# --------------------------------------------------------------------------- #
+
+
+def test_single_frame():
+    tx_strings = ["11" * 10]
+    payload = encode_transfer(tx_strings)
+    frames = split_frames(payload, 150)
+    assert len(frames) == 1
+    total, index, compressed, p = parse_frame(frames[0])
+    assert (total, index, compressed) == (1, 1, False)
+    assert p == payload
+
+
+def test_multiple_frames_reassemble():
+    tx_strings = ["ab" * 100, "cd" * 100]  # 600 chars -> multiple frames
+    _payload, total, parsed = _frames(tx_strings, CHUNK_PRESETS[0][1])
+    assert total > 1
+    decoded = decode_transfer(assemble(parsed, total), compressed=False)
+    assert decoded == tx_strings
+
+
+def test_size_greater_than_payload():
+    tx_strings = ["12" * 5]
+    payload = encode_transfer(tx_strings)
+    frames = split_frames(payload, 1800)
+    assert len(frames) == 1
+    _t, _i, _c, p = parse_frame(frames[0])
+    assert p == payload
+
+
+def test_exact_single_frame_boundary():
+    # A 139-byte payload exactly fills the 150-byte preset budget (the 11-char
+    # compact header plus payload), so the encoded frame is exactly 150.
+    tx_strings = ["a" * 139]
+    payload = encode_transfer(tx_strings)
+    frames = split_frames(payload, 150)
+    assert len(frames) == 1
+    assert len(frames[0]) == 150
+    _t, _i, _c, p = parse_frame(frames[0])
+    assert p == payload
+
+
+def test_frames_fit_chunk_size():
+    tx_strings = ["".join("{:02x}".format(i) * 2) for i in range(300)]
+    payload = encode_transfer(tx_strings)
+    for _label, size in CHUNK_PRESETS:
+        for frame in split_frames(payload, size):
+            assert len(frame) <= size, (size, len(frame))
+
+
+def test_single_tx_larger_than_chunk():
+    # A huge serialized tx must be split over several frames and reassemble
+    # exactly (positional slicing is safe for hex/base64 text).
+    tx_strings = ["7b" * 1000]  # 2000 chars
+    payload = encode_transfer(tx_strings)
+    frames = split_frames(payload, 150)
+    assert len(frames) > 1
+    parsed = {parse_frame(f)[1]: parse_frame(f)[3] for f in frames}
+    total = parse_frame(frames[0])[0]
+    assert assemble(parsed, total) == payload
+
+
+def test_compressed_frames_carry_flag():
+    tx_strings = ["ab" * 40]
+    frames = split_frames(encode_transfer(tx_strings, compress=True), 150, compressed=True)
+    for frame in frames:
+        _t, _i, compressed, _p = parse_frame(frame)
+        assert compressed is True
+    # Plain frames do not.
+    frames_plain = split_frames(encode_transfer(tx_strings), 150)
+    _t, _i, compressed, _p = parse_frame(frames_plain[0])
+    assert compressed is False
+
+
+def test_compressed_roundtrip_through_frames():
+    tx_strings = ["ab" * 50, "cd" * 50, "12" * 60]
+    payload = encode_transfer(tx_strings, compress=True)
+    parsed = {}
+    total = None
+    for frame in split_frames(payload, 400, compressed=True):
+        t, index, _c, p = parse_frame(frame)
+        total = t
+        parsed[index] = p
+    assert total is not None
+    decoded = decode_transfer(assemble(parsed, total), compressed=True)
+    assert decoded == tx_strings
+
+
+# --------------------------------------------------------------------------- #
+# Compact v2 wire format ("BAL1")
+# --------------------------------------------------------------------------- #
+
+
+def test_v2_frame_header_structure():
+    frames = split_frames(encode_transfer(["11" * 10]), 150)
+    assert len(frames) == 1
+    frame = frames[0]
+    assert frame.startswith("BAL1")
+    # Fixed 11-char header: magic + 3-char total + 3-char index + 1 flag.
+    assert len(frame) > 11
+    magic, total_s, index_s, flag, payload = (
+        frame[:4],
+        frame[4:7],
+        frame[7:10],
+        frame[10],
+        frame[11:],
+    )
+    assert magic == "BAL1"
+    assert total_s == "001"
+    assert index_s == "001"
+    assert flag == "0"
+    assert payload == "11" * 10
+    total, index, compressed, p = parse_frame(frame)
+    assert (total, index, compressed) == (1, 1, False)
+    assert p == payload
+
+
+def test_v2_compressed_flag_is_z():
+    frames = split_frames(
+        encode_transfer(["11" * 10], compress=True), 150, compressed=True
+    )
+    assert frames[0][10] == "Z"
+    _t, _i, compressed, _p = parse_frame(frames[0])
+    assert compressed is True
+
+
+def test_v2_header_fixed_width_high_counts():
+    # A long transfer needs multi-digit counts; the v2 header stays exactly
+    # 11 chars no matter how many frames (3-char base36 zero-padded counts).
+    tx_strings = ["ab" * 300]  # 600 chars -> several frames at 150
+    frames = split_frames(encode_transfer(tx_strings), 150)
+    assert len(frames) > 1
+    for frame in frames:
+        # magic(4) + total(3) + index(3) + flag(1) = 11 chars, then payload.
+        assert len(frame) - len(frame[11:]) == 11
+
+
+def test_v2_max_frame_count():
+    # A transfer needing more than 46655 frames must be rejected (3-char
+    # base36 count fields cannot represent larger totals).
+    from bal.core.qrtransfer import _MAX_TOTAL
+
+    oversized = "A" * (_MAX_TOTAL * (150 - 11) + 1)
+    try:
+        split_frames(oversized, 150)
+    except QrTransferError:
+        pass
+    else:
+        raise AssertionError("expected QrTransferError above the frame cap")
+
+
+def test_v2_boundary_at_max_count():
+    from bal.core.qrtransfer import _MAX_TOTAL
+
+    # Exactly at the cap: must still produce (bounded) frames with 3-char
+    # counts "VVV" (46655) for the highest serialised part.
+    payload = "B" * (_MAX_TOTAL * (150 - 11))
+    frames = split_frames(payload, 150)
+    assert len(frames) == _MAX_TOTAL
+    total, index, _c, _p = parse_frame(frames[-1])
+    assert total == _MAX_TOTAL
+    assert index == _MAX_TOTAL
+    assert frames[-1][:10] == "BAL1" + "ZZZ" + "ZZZ"
+
+
+def test_encode_transfer_best():
+    from bal.core.qrtransfer import encode_transfer_best
+
+    # Redundant JSON-ish text compresses -> compressed (and longer source
+    # must round-trip unchanged).
+    txs = ['{"a": "%s"}' % ("x" * 300), '{"b": "%s"}' % ("y" * 300)]
+    transfer, compressed = encode_transfer_best(txs)
+    assert compressed is True
+    assert decode_transfer(transfer, compressed) == txs
+
+    # Already-compact input stays plain (never larger than the source).
+    txs_small = ["ab", "cd"]
+    transfer, compressed = encode_transfer_best(txs_small)
+    assert compressed is False
+    assert decode_transfer(transfer, compressed) == txs_small
+
+
+def test_v2_malformed_frames():
+    bad = (
+        "BAL1",                       # header only, no fields
+        "BAL1" + "001",               # truncated
+        "BAL1" + "G-1" + "001" + "Z" + "p",  # non-base36 total
+        "BAL1" + "001" + "G-1" + "Z" + "p",  # non-base36 index
+        "BAL1" + "000" + "001" + "Z" + "p",  # total 0
+        "BAL1" + "001" + "000" + "Z" + "p",  # index 0
+        "BAL1" + "001" + "002" + "Z" + "p",  # index beyond total
+        "BAL1" + "001" + "001" + "Q" + "p",  # unknown flag
+    )
+    for frame in bad:
+        try:
+            parse_frame(frame)
+        except QrTransferError:
+            continue
+        raise AssertionError("expected QrTransferError for: {!r}".format(frame))
+
+
+# --------------------------------------------------------------------------- #
+# Malformed input
+# --------------------------------------------------------------------------- #
+
+
+def test_parse_bad_magic_and_version():
+    for frame in (
+        "BALQR|1|1||a",  # missing version
+        "BALQR2|1|1||a",  # unknown version
+        "XXXXX1|1|1||a",  # unknown magic
+    ):
+        try:
+            parse_frame(frame)
+        except QrTransferError:
+            pass
+        else:
+            raise AssertionError("expected QrTransferError for: {}".format(frame))
+
+
+def test_parse_bad_arity():
+    for frame in ("BALQR1", "BALQR1|1|1|"):
+        try:
+            parse_frame(frame)
+        except QrTransferError:
+            pass
+        else:
+            raise AssertionError("expected QrTransferError for: {}".format(frame))
+
+
+def test_parse_pipe_in_payload_is_folded():
+    # maxsplit keeps the tail (including any inner '|') in the payload part.
+    frame = "BALQR1|1|1||a|b|c"
+    total, index, compressed, payload = parse_frame(frame)
+    assert (total, index, compressed) == (1, 1, False)
+    assert payload == "a|b|c"
+
+
+def test_parse_bad_numbers():
+    for frame in (
+        "BALQR1|x|1||a",
+        "BALQR1|1|y||a",
+        "BALQR1|0|1||a",
+        "BALQR1|1|0||a",
+        "BALQR1|1|2||a",  # index beyond total
+        "BALQR1|-1|1||a",
+    ):
+        try:
+            parse_frame(frame)
+        except QrTransferError:
+            pass
+        else:
+            raise AssertionError("expected QrTransferError for: {}".format(frame))
+
+
+def test_parse_bad_flags():
+    try:
+        parse_frame("BALQR1|1|1|Q|payload")
+    except QrTransferError:
+        pass
+    else:
+        raise AssertionError("expected QrTransferError for unknown flags")
+
+
+def test_assemble_missing_frames():
+    try:
+        assemble({1: "a", 3: "c"}, total=3)
+    except MissingFramesError as e:
+        assert e.missing == [2]
+    else:
+        raise AssertionError("expected MissingFramesError")
+
+
+def test_assemble_index_beyond_total():
+    try:
+        assemble({1: "a", 2: "b"}, total=1)
+    except InconsistentTotalError:
+        pass
+    else:
+        raise AssertionError("expected InconsistentTotalError")
+
+
+def test_assemble_order_and_total_validation():
+    assert assemble({1: "a", 2: "b"}, total=2) == "ab"
+    try:
+        assemble({}, total=0)
+    except QrTransferError:
+        pass
+    else:
+        raise AssertionError("expected QrTransferError")
+
+
+# --------------------------------------------------------------------------- #
+# Constants / presets
+# --------------------------------------------------------------------------- #
+
+
+def test_preset_count_and_order():
+    assert len(CHUNK_PRESETS) == 4
+    budgets = [budget for _label, budget in CHUNK_PRESETS]
+    assert budgets == sorted(budgets)
+
+
+def test_preset_index_for_chunk_size():
+    for index, (_label, budget) in enumerate(CHUNK_PRESETS):
+        assert preset_index_for_chunk_size(budget) == index
+    assert preset_index_for_chunk_size(150) == 0
+    assert preset_index_for_chunk_size(1800) == 3
+
+
+def test_min_chunk_size_guard():
+    try:
+        split_frames("x" * 10, MIN_CHUNK_SIZE - 1)
+    except QrTransferError:
+        pass
+    else:
+        raise AssertionError("expected QrTransferError for tiny chunk size")
+
+
+def test_split_frame_headers_consistent():
+    tx_strings = ["ab" * 80]
+    payload = encode_transfer(tx_strings)
+    frames = split_frames(payload, 150)
+    totals = {parse_frame(frame)[0] for frame in frames}
+    assert len(totals) == 1
+    assert totals.pop() == len(frames)
+
+
+# --------------------------------------------------------------------------- #
+# Optional: cross-check presets against the qrcode library (EC level M)
+# --------------------------------------------------------------------------- #
+
+
+def test_presets_fit_qrcode_ec_m():
+    """Every preset budget must render inside a QR at EC level M."""
+    try:
+        import qrcode
+        from qrcode.constants import ERROR_CORRECT_M
+    except ImportError:
+        print("qrcode not installed - skipping capacity check")
+        return
+    for _label, size in CHUNK_PRESETS:
+        # Worst-case frame: header with the largest plausible total/index plus
+        # a full payload of the preset budget.
+        frame = "BALQR1|9999|9999|Z|" + "a" * (size - 14)
+        qr = qrcode.QRCode(error_correction=ERROR_CORRECT_M, border=2)
+        qr.add_data(frame)
+        qr.get_matrix()  # raises DataOverflowError if it does not fit
+
+
+# --------------------------------------------------------------------------- #
+if __name__ == "__main__":
+    import traceback
+
+    failures = 0
+    for _name, fn in sorted(globals().items()):
+        if _name.startswith("test_") and callable(fn):
+            try:
+                fn()
+                print("ok: {}".format(_name))
+            except Exception:
+                failures += 1
+                print("FAIL: {}".format(_name))
+                traceback.print_exc()
+    if failures:
+        print("{} test(s) failed".format(failures))
+        sys.exit(1)
+    print("all tests passed")

tests/test_core_util.py

@@ -97,7 +97,7 @@ def test_relative_days():
 
 def test_resolve_locktime_against_tx_absolute():
     """An absolute current date is returned unchanged (compared vs the tx)."""
-    frozen = 1817438400
+    frozen = 1817424000
     assert Util.resolve_locktime_against_tx(str(frozen), "1y", frozen) == frozen
     assert Util.resolve_locktime_against_tx(frozen, str(frozen), frozen) == frozen
 
@@ -105,7 +105,7 @@ def test_resolve_locktime_against_tx_absolute():
 def test_resolve_locktime_against_tx_unchanged_relative():
     """An unchanged relative recipe resolves to exactly the frozen tx locktime
     (coherent), instead of drifting one day per day away from it."""
-    frozen = 1817438400  # 2027-08-05, i.e. a tx built 2026-08-05 with "1y"
+    frozen = 1817424000  # 2027-08-05 00:00 UTC, i.e. a tx built 2026-08-05 with "1y"
     resolved = Util.resolve_locktime_against_tx("1y", "1y", frozen)
     assert resolved == frozen
 
@@ -113,7 +113,7 @@ def test_resolve_locktime_against_tx_unchanged_relative():
 def test_resolve_locktime_against_tx_lengthened():
     """A lengthened relative recipe resolves later than the frozen tx locktime
     (this is what the postpone check uses to trigger invalidation)."""
-    frozen = 1817438400  # tx built 2026-08-05 with "1y" -> delivery 2027-08-05
+    frozen = 1817424000  # tx built 2026-08-05 with "1y" -> delivery 2027-08-05
     resolved = Util.resolve_locktime_against_tx("2y", "1y", frozen)
     assert resolved == frozen + 365 * 86400
 
@@ -121,7 +121,7 @@ def test_resolve_locktime_against_tx_lengthened():
 def test_resolve_locktime_against_tx_shortened():
     """A shortened relative recipe resolves earlier than the frozen tx locktime
     (this is what the anticipate/rebuild path uses)."""
-    frozen = 1817438400
+    frozen = 1817424000
     resolved = Util.resolve_locktime_against_tx("30d", "1y", frozen)
     assert resolved < frozen
 
@@ -129,7 +129,7 @@ def test_resolve_locktime_against_tx_shortened():
 def test_resolve_locktime_against_tx_no_relative_anchor():
     """When the built recipe was absolute there is no anchor: falls back to the
     legacy forward-from-now resolution (returns a timestamp, no crash)."""
-    frozen = 1817438400
+    frozen = 1817424000
     result = Util.resolve_locktime_against_tx("30d", str(frozen), frozen)
     assert isinstance(result, int)
     assert result > 1700000000
@@ -319,27 +319,6 @@ def test_anticipate_locktime():
     assert low >= 1
 
 
-def test_cmp_locktime():
-    assert Util.cmp_locktime("30d", "30d") == 0
-    # Note: cmp_locktime may return nonzero or None for mismatched units
-
-
-def test_get_locktimes():
-    class FakeTx:
-        locktime = 1700000000
-
-    # will with single entry
-    will = {
-        "tx1": {"tx": FakeTx()},
-    }
-    locktimes = list(Util.get_locktimes(will))
-    assert 1700000000 in locktimes
-    assert len(locktimes) == 1
-
-    # empty will
-    assert list(Util.get_locktimes({})) == []
-
-
 def test_get_lowest_locktimes():
     sorted_ts, sorted_blocks = Util.get_lowest_locktimes([500000, 1700000000, 100, 900000])
     # 500000, 900000 are block-height (< THRESHOLD)
@@ -351,18 +330,6 @@ def test_get_lowest_locktimes():
     assert Util.get_lowest_locktimes([]) == ([], [])
 
 
-def test_get_will_spent_utxos():
-    class FakeTx:
-        def inputs(self): return [1, 2, 3]
-
-    will = {
-        "tx1": {"tx": FakeTx()},
-        "tx2": {"tx": FakeTx()},
-    }
-    utxos = Util.get_will_spent_utxos(will)
-    assert len(utxos) == 6  # 3 inputs * 2 txs
-
-
 def test_utxo_to_str():
     class FakeUtxo:
         def to_str(self): return "txid:0"
@@ -518,10 +485,7 @@ if __name__ == "__main__":
     test_get_value_amount()
     test_chk_locktime()
     test_anticipate_locktime()
-    test_cmp_locktime()
-    test_get_locktimes()
     test_get_lowest_locktimes()
-    test_get_will_spent_utxos()
     test_utxo_to_str()
     test_cmp_utxo()
     test_in_utxo()

tests/test_core_will.py

@@ -8,13 +8,19 @@ Run:
     python3 tests/test_core_will.py
 """
 
-import copy
 import os
 import sys
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), os.pardir))
 
-from bal.core.will import Will, WillItem
+from bal.core.checkalive import resolve_date_to_check
+from bal.core.util import copy_structure
+from bal.core.will import (
+    HeirNotFoundException,
+    NoHeirsException,
+    Will,
+    WillItem,
+)
 
 # A valid serialized Bitcoin transaction hex (1 input + 1 P2PKH output, version 2)
 _VALID_TX_HEX = (
@@ -48,7 +54,7 @@ def _make_willitem_blank():
     """Create a fresh WillItem from scratch."""
     item = WillItem(_make_minimal_willitem_dict())
     # Reset STATUS to clean defaults
-    item.STATUS = copy.deepcopy(WillItem.STATUS_DEFAULT)
+    item.STATUS = WillItem.copy_status_table(WillItem.STATUS_DEFAULT)
     return item
 
 
@@ -126,22 +132,6 @@ def test_willitem_str_repr():
 # Will static methods
 # ------------------------------------------------------------------ #
 
-def test_will_get_sorted_will():
-    # Use a simple dict structure that will[key]["tx"].locktime works
-    class FakeTx:
-        def __init__(self, locktime):
-            self.locktime = locktime
-
-    will = {
-        "b": {"tx": FakeTx(200)},
-        "a": {"tx": FakeTx(100)},
-    }
-    sorted_will = Will.get_sorted_will(will)
-    assert len(sorted_will) == 2
-    assert sorted_will[0][1]["tx"].locktime == 100
-    assert sorted_will[1][1]["tx"].locktime == 200
-
-
 def test_will_only_valid():
     item1 = _make_willitem_blank()
     item2 = _make_willitem_blank()
@@ -167,8 +157,8 @@ def test_will_only_valid_list():
 def _make_will_with_heirs(heirs, tx_locktime):
     """Build a single-item will whose stored heirs == ``heirs`` and whose
     frozen tx.locktime == ``tx_locktime`` (what the will-executors hold)."""
-    item = WillItem(_make_minimal_willitem_dict(heirs=copy.deepcopy(heirs)))
+    item = WillItem(_make_minimal_willitem_dict(heirs=copy_structure(heirs)))
-    item.STATUS = copy.deepcopy(WillItem.STATUS_DEFAULT)
+    item.STATUS = WillItem.copy_status_table(WillItem.STATUS_DEFAULT)
     item.tx.locktime = tx_locktime
     return {"willid_1": item}
 
@@ -179,7 +169,7 @@ def test_check_heirs_unchanged_is_coherent():
     heirs = {"alice": ["addr_alice", 5000, str(lt)]}
     will = _make_will_with_heirs(heirs, lt)
     result = Will.check_willexecutors_and_heirs(
-        will, copy.deepcopy(heirs), {}, False, 0, 100
+        will, copy_structure(heirs), {}, False, 0, 100
     )
     assert result is True
 
@@ -226,6 +216,59 @@ def test_check_heir_added_triggers_rebuild():
     assert raised, "adding an heir must raise HeirNotFoundException"
 
 
+def test_shortened_relative_recipe_on_signed_rebuilds_not_noheirs():
+    """Regression (karen7): heirs shortened "2y"->"1y" on a signed will whose
+    ADVANCED check window is anchored to the frozen built delivery must trigger
+    a plain rebuild (HeirNotFoundException), NOT "No Heirs".
+
+    Earlier the count gate resolved each current relative recipe from *now*
+    while ``check_date`` was anchored to the (longer) frozen built locktime, so
+    every heir fell below the window and was silently excluded -> NoHeirs even
+    though the will simply needs rebuilding on the new, shorter schedule."""
+    lt = 2_100_000_000  # a far-future frozen delivery (a "2y" build)
+    will_heirs = {"alice": ["addr_alice", 5000, "2y"]}
+    current_heirs = {"alice": ["addr_alice", 5000, "1y"]}
+    will = _make_will_with_heirs(will_heirs, lt)
+    will["willid_1"].set_status("COMPLETE", True)
+    check_date = resolve_date_to_check(
+        False, {"locktime": "2y", "threshold": "150d"}, built_locktime=lt
+    )
+    assert check_date < lt  # the anchored window really precedes the delivery
+    raised = None
+    try:
+        Will.check_willexecutors_and_heirs(
+            will, copy_structure(current_heirs), {}, False, check_date, 100
+        )
+    except HeirNotFoundException:
+        raised = "rebuild"
+    except NoHeirsException:
+        raised = "noheirs"
+    assert raised == "rebuild", (
+        f"shortened recipe on a signed will must rebuild, got {raised!r}"
+    )
+
+
+def test_all_heirs_past_check_date_still_noheirs():
+    """The "no valid heirs" gate is preserved: when every heir is coherent with
+    the built will but its delivery lies before ``check_date``, the check still
+    reports NoHeirsException (there is literally nothing future to inherit)."""
+    lt = 1_900_000_000
+    will_heirs = {"alice": ["addr_alice", 5000, str(lt)]}
+    will = _make_will_with_heirs(will_heirs, lt)
+    raised = None
+    try:
+        Will.check_willexecutors_and_heirs(
+            will, copy_structure(will_heirs), {}, False, lt + 86400, 100
+        )
+    except HeirNotFoundException:
+        raised = "rebuild"
+    except NoHeirsException:
+        raised = "noheirs"
+    assert raised == "noheirs", (
+        f"a fully delivered will must report NoHeirs, got {raised!r}"
+    )
+
+
 def test_needs_server_check():
     """Check button selection logic: only a VALID, PUSHED will with a
     will-executor that is not yet CHECKED must be queried on the server.

tests/test_core_will_extra.py

@@ -450,6 +450,12 @@ class FakeADB:
 
     def remove_transaction(self, txid):
         self.removed.append(txid)
+        # Simulate the real adb: dropping a stored tx frees the outputs it spent.
+        for utxos in self.outputs.values():
+            for utxo in utxos.values():
+                if getattr(utxo, "spent_txid", None) == txid:
+                    utxo.spent_txid = None
+                    utxo.spent_height = None
 
     def get_spender(self, outpoint):
         txid = self.spenders.get(outpoint)
@@ -837,6 +843,73 @@ def test_get_available_utxos_none_locktime_is_raw_view():
     assert Util.get_available_utxos(None, _HISTORY_TEMPLATE, 1000) == []
 
 
+# ------------------------------------------------------------------ #
+# Will.remove_stale_wallet_history (pre-build history purge)
+# ------------------------------------------------------------------ #
+
+def test_remove_stale_wallet_history_frees_equal_locktime_spend():
+    # The stale placeholders (saved by a previous prepare) have the SAME
+    # locktime as the will being rebuilt, so get_available_utxos does NOT
+    # restore their coins (see test_...does_not_restore_not_later_locktime).
+    # The pre-build purge deletes them and the coins become available again.
+    wallet, utxo = _wallet_with_local_spend(locktime=1000)
+    spender = "ab" * 32
+    assert Util.get_available_utxos(wallet, _HISTORY_TEMPLATE, 1000) == []
+    removed = Will.remove_stale_wallet_history(wallet, _HISTORY_TEMPLATE)
+    assert removed == [spender]
+    assert wallet.adb.removed == [spender]
+    assert spender not in wallet.labels
+    assert [
+        u.prevout.to_str()
+        for u in Util.get_available_utxos(wallet, _HISTORY_TEMPLATE, 1000)
+    ] == [utxo.prevout.to_str()]
+
+
+def test_remove_stale_wallet_history_keeps_confirmed_spender():
+    # A broadcast (confirmed) BAL-labelled tx is never purged.
+    addr = "bcrt1qexample"
+    spender = "ab" * 32
+    utxo = _make_utxo(spent_txid=spender, spent_height=100)
+    wallet = FakeWallet(
+        stored_txs={spender: _make_multisig_ptx(0, locktime=2000)},
+        heights={spender: 100},
+        outputs={addr: {utxo.prevout.to_str(): utxo}},
+        addresses=[addr],
+    )
+    wallet.labels[spender] = _HISTORY_LABEL
+    removed = Will.remove_stale_wallet_history(wallet, _HISTORY_TEMPLATE)
+    assert removed == []
+    assert wallet.adb.removed == []
+    assert wallet.labels[spender] == _HISTORY_LABEL
+
+
+def test_remove_stale_wallet_history_keeps_unlabeled_local_spender():
+    # Wallet-local BAL-status tx without a matching history label stays.
+    wallet, _ = _wallet_with_local_spend(locktime=1000)
+    spender = "ab" * 32
+    wallet.labels[spender] = "some other label"
+    removed = Will.remove_stale_wallet_history(wallet, _HISTORY_TEMPLATE)
+    assert removed == []
+    assert wallet.adb.removed == []
+    assert wallet.labels[spender] == "some other label"
+
+
+def test_remove_stale_wallet_history_noop_without_wallet_or_adb():
+    assert Will.remove_stale_wallet_history(None, _HISTORY_TEMPLATE) == []
+    wallet = FakeWallet()
+    wallet.adb = None
+    assert Will.remove_stale_wallet_history(wallet, _HISTORY_TEMPLATE) == []
+
+
+def test_remove_stale_wallet_history_never_raises():
+    adb = MagicMock()
+    adb.get_tx_height.side_effect = RuntimeError("boom")
+    wallet = MagicMock()
+    wallet.adb = adb
+    wallet.get_all_labels.return_value = {"ab" * 32: _HISTORY_LABEL}
+    assert Will.remove_stale_wallet_history(wallet, _HISTORY_TEMPLATE) == []
+
+
 # ------------------------------------------------------------------ #
 # Main
 # ------------------------------------------------------------------ #

tests/test_core_will_invalidate.py

@@ -17,7 +17,6 @@ Run:
         python3 -m pytest tests/test_core_will_invalidate.py -q
 """
 
-import copy
 import os
 import sys
 from unittest.mock import MagicMock, patch
@@ -75,9 +74,12 @@ def _make_willitem(value_sats=1000000, valid=True, extra_heirs=None):
         "change": "",
         "baltx_fees": 100,
     })
-    item.STATUS = copy.deepcopy(WillItem.STATUS_DEFAULT)
+    item.STATUS = WillItem.copy_status_table(WillItem.STATUS_DEFAULT)
     # Set the input value so the balance calculation works.
-    item.tx.inputs()[0]._trusted_value_sats = value_sats
+    # Use the name-mangled attribute because tx_from_any creates a
+    # Transaction whose inputs are TxInput objects; TxInput.value_sats()
+    # reads __value_sats, not _trusted_value_sats.
+    item.tx.inputs()[0]._TxInput__value_sats = value_sats
     if not valid:
         item.set_status("INVALIDATED", True)
     return item
@@ -267,7 +269,7 @@ class TestInvalidateWill:
         """
         item = _make_willitem(value_sats=100)
         will = {"willtxid1": item}
-        wallet = _mock_wallet([_make_utxo()])
+        wallet = _mock_wallet([_make_utxo(value_sats=100)])
 
         result, mock_from_io, _ = _run_invalidate(will, wallet, fees_per_byte=100)
 

tests/test_group_e_karen7_invalidate.py

@@ -21,7 +21,6 @@ Run:
         python3 -m pytest tests/test_group_e_karen7_invalidate.py -q
 """
 
-import copy
 import json
 import os
 import sys
@@ -46,6 +45,7 @@ from electrum.transaction import (
 from electrum.util import bfh
 
 from bal.core.heirs import Heirs
+from bal.core.util import copy_structure
 from bal.core.will import Will, WillItem
 
 # ------------------------------------------------------------------ #
@@ -219,7 +219,7 @@ def _txs_to_will(txs, heirs_data):
     for txid, tx in txs.items():
         item_dict = {
             "tx": tx,
-            "heirs": copy.deepcopy(heirs_data),
+            "heirs": copy_structure(heirs_data),
             "willexecutor": None,
             "status": "",
             "description": "",
@@ -281,10 +281,10 @@ class TestKaren7BuildAndInvalidate:
             )
 
     def test_built_tx_has_karen7_heirs(self):
-        """The built will contains karen7's four heirs."""
+        """The built will contains karen7's six heirs."""
-        assert len(self.heirs_model) == 4
+        assert len(self.heirs_model) == 6
         assert list(self.heirs_model.keys()) == [
-            "aaaa", "lucia", "mario", "mario2"
+            "aaaa", "lucia", "mario", "mario2", "op_return", "op_return2"
         ]
 
     def test_will_items_are_valid(self):

tests/test_group_e_mock_karen7.py

@@ -22,7 +22,6 @@ Run:
         python3 -m pytest tests/test_group_e_mock_karen7.py -q
 """
 
-import copy
 import json
 import os
 import sys
@@ -43,6 +42,7 @@ from bal.core.reminders import (
     ical_escape,
     write_temp_ics,
 )
+from bal.core.util import copy_structure
 from bal.core.will import HeirNotFoundException, Will, WillItem
 from bal.core.willexecutors import Willexecutors
 
@@ -136,7 +136,7 @@ def _make_willitem(**overrides):
     }
     d.update(overrides)
     item = WillItem(d)
-    item.STATUS = copy.deepcopy(WillItem.STATUS_DEFAULT)
+    item.STATUS = WillItem.copy_status_table(WillItem.STATUS_DEFAULT)
     return item
 
 
@@ -343,7 +343,7 @@ def test_e2_heir_change_triggers_rebuild():
     item = WillItem(
         {
             "tx": _VALID_TX_HEX,
-            "heirs": copy.deepcopy(will_heirs),
+            "heirs": copy_structure(will_heirs),
             "willexecutor": None,
             "status": "",
             "description": "",
@@ -352,7 +352,7 @@ def test_e2_heir_change_triggers_rebuild():
             "baltx_fees": 100,
         }
     )
-    item.STATUS = copy.deepcopy(WillItem.STATUS_DEFAULT)
+    item.STATUS = WillItem.copy_status_table(WillItem.STATUS_DEFAULT)
     item.tx.locktime = lt
     will = {"willid_1": item}
 
@@ -570,8 +570,8 @@ def test_e5_build_with_real_wallet_heirs_and_utxos():
     h = Heirs.__new__(Heirs)
     h.update(heirs_data)
 
-    assert len(h) == 4, f"expected 4 heirs, got {len(h)}"
+    assert len(h) == 6, f"expected 6 heirs, got {len(h)}"
-    assert list(h.keys()) == ["aaaa", "lucia", "mario", "mario2"]
+    assert list(h.keys()) == ["aaaa", "lucia", "mario", "mario2", "op_return", "op_return2"]
 
     # Mock the Electrum-heavy parts so the build can run in a test context.
     wallet = MagicMock()

tests/test_gui_export_dialogs.py

@@ -0,0 +1,456 @@
+"""
+Tests for the filter-based unified export/import dialogs and the BalWindow
+transport helpers (``bal.gui.qt.dialogs``, ``bal.gui.qt.window``).
+
+Covers the shared export filters (All / Valid / Valid NC), the unified
+``WillExportDialog`` file page (whole item vs tx-only content, empty-filter
+abort), the audio export/import pages (KB/sec wiring, missing plugin guard,
+receive flow) and the comma-separated tx-only file writer. The audio pages
+run against a stub plugin so no sound hardware is exercised.
+
+Run:
+    QT_QPA_PLATFORM=offscreen python3 tests/test_gui_export_dialogs.py
+"""
+
+import base64
+import json
+import sys
+import zlib
+from unittest.mock import patch
+
+sys.path.insert(0, __file__.rsplit("/", 2)[0])
+
+from PyQt6.QtWidgets import QApplication, QMainWindow
+
+import bal.gui.qt.dialogs as dialogs
+from bal.core.qrtransfer import CHUNK_PRESETS
+
+_app = QApplication.instance() or QApplication(sys.argv)
+
+# A valid 1x1 transparent PNG, good enough for BalDialog's window icon.
+_PNG_BYTES = base64.b64decode(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
+)
+
+# A valid serialized Bitcoin transaction hex (1 input + 1 P2PKH output,
+# version 2); used for real-WillItem serialization tests.
+_VALID_TX_HEX = (
+    "01000000012a5c9a94fcde98f5581cd00162c60a13936ceb75389ea65b"
+    "f38633b424eb4031000000006c493046022100a82bbc57a0136751e543"
+    "3f41cf000b3f1a99c6744775e76ec764fb78c54ee100022100f9e80b7d"
+    "e89de861dc6fb0c1429d5da72c2b6b2ee2406bc9bfb1beedd729d98501"
+    "2102e61d176da16edd1d258a200ad9759ef63adf8e14cd97f53227bae3"
+    "5cdb84d2f6ffffffff0140420f00000000001976a914230ac37834073a"
+    "42146f11ef8414ae929feaafc388ac00000000"
+)
+
+
+class _Cfg:
+    def __init__(self, value):
+        self._value = value
+
+    def get(self):
+        return self._value
+
+
+class FakePlugin:
+    QR_CHUNK_SIZE = _Cfg(CHUNK_PRESETS[0][1])
+
+    def read_file(self, path):
+        return _PNG_BYTES
+
+
+class FakeWindow(QMainWindow):
+    config = {}
+
+    def format_amount(self, amount):
+        return "{:.8f}".format(amount)
+
+    def format_amount_and_units(self, amount):
+        return "{:.8f} sat".format(amount)
+
+
+class FakeAudioPlugin:
+    """Duck-typed ``audio_modem`` plugin for the audio pages."""
+
+    def __init__(self):
+        self.modem_config = None
+
+    def is_available(self):
+        return True
+
+
+class _FakeModemConfig:
+    def __init__(self, kbps):
+        self.modem_bps = kbps * 1000
+
+
+class FakeBalWindow:
+    """Duck-typed stand-in for BalWindow (dialog layer only)."""
+
+    def __init__(self, audio_plugin=None):
+        self.window = FakeWindow()
+        self.bal_plugin = FakePlugin()
+        self.willitems = {}
+        self.audio_plugin = audio_plugin
+        self.bitrate_set = None
+        self.audio_payloads = []
+
+    def get_audio_modem_plugin(self):
+        return self.audio_plugin
+
+    def set_audio_modem_bitrate(self, kbps):
+        self.bitrate_set = kbps
+        if self.audio_plugin is not None:
+            self.audio_plugin.modem_config = _FakeModemConfig(kbps)
+
+    def _audio_send_payload(self, payload):
+        self.audio_payloads.append(payload)
+
+    def export_json_file(self, path, will=None):
+        items = will if will is not None else self.willitems
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump({wid: wi.to_dict() for wid, wi in items.items()}, f)
+
+    def export_tx_file(self, path, will=None):
+        items = will if will is not None else self.willitems
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(",".join(str(wi.tx) for _, wi in items.items()))
+
+
+class StubTx:
+    def __init__(self, payload):
+        self.payload = payload
+
+    def txid(self):
+        return "{:064x}".format(hash(self.payload) & 0xFFFFFFFFFFFFFFFF)
+
+    def __str__(self):
+        return self.payload
+
+
+class StubWillItem:
+    def __init__(self, payload, statuses=None):
+        self.tx = StubTx(payload)
+        self.statuses = statuses or {}
+
+    def get_status(self, name):
+        return self.statuses.get(name, False)
+
+    def to_dict(self):
+        return {"tx": str(self.tx)}
+
+
+def _make_willitems(n=3, payload_len=60, statuses=None):
+    return {
+        "item{}".format(i): StubWillItem(
+            "T{}".format(i) * payload_len, statuses=statuses
+        )
+        for i in range(n)
+    }
+
+
+# ------------------------------------------------------------------ #
+# Shared export filters
+# ------------------------------------------------------------------ #
+
+def test_export_filter_options():
+    opts = dialogs.export_filter_options()
+    assert [label for label, _fn in opts] == ["All", "Valid", "Valid NC"]
+    complete = StubWillItem("C*", statuses={"VALID": True, "COMPLETE": True})
+    valid = StubWillItem("V*", statuses={"VALID": True})
+    plain = StubWillItem("P*")
+    assert opts[0][1](complete) and opts[0][1](plain)
+    assert opts[1][1](complete) and opts[1][1](valid) and not opts[1][1](plain)
+    assert not opts[2][1](complete)
+    assert opts[2][1](valid) and not opts[2][1](plain)
+
+
+def test_filter_willitems_by_index():
+    items = {
+        "a": StubWillItem("A*", statuses={"VALID": True, "COMPLETE": True}),
+        "b": StubWillItem("B*", statuses={"VALID": True}),
+        "c": StubWillItem("C*"),
+    }
+    opts = dialogs.export_filter_options()
+    assert set(dialogs.filter_willitems(items, opts, 0)) == {"a", "b", "c"}
+    assert set(dialogs.filter_willitems(items, opts, 1)) == {"a", "b"}
+    assert dialogs.filter_willitems(items, opts, 2) == {"b": items["b"]}
+
+
+# ------------------------------------------------------------------ #
+# WillExportDialog file page
+# ------------------------------------------------------------------ #
+
+def test_file_export_selects_by_filter():
+    bw = FakeBalWindow()
+    items = _make_willitems(3)
+    items["item0"].statuses = {"VALID": True, "COMPLETE": True}
+    items["item1"].statuses = {"VALID": True}
+    d = dialogs.WillExportDialog(bw, will=items, bal_plugin=bw.bal_plugin)
+    assert set(d._selected_items()) == set(items)
+
+    d._on_filter_change(1)
+    assert set(d._selected_items()) == {"item0", "item1"}
+    d._on_filter_change(2)
+    assert list(d._selected_items()) == ["item1"]
+    d.close()
+
+
+def test_file_export_run_tx_only(tmpdir):
+    bw = FakeBalWindow()
+    items = _make_willitems(3)
+    d = dialogs.WillExportDialog(bw, will=items, bal_plugin=bw.bal_plugin)
+    d.content_check.setChecked(False)
+    captured = {}
+
+    def fake_gui(window, title, exporter):
+        captured["title"] = title
+        captured["exporter"] = exporter
+
+    with patch.object(dialogs, "export_meta_gui", side_effect=fake_gui):
+        d._export_file()
+    assert captured["title"] == "will_tx"
+    out = tmpdir.join("will_tx.txt").strpath
+    captured["exporter"](out)
+    expected = ",".join(str(wi.tx) for _, wi in items.items())
+    assert open(out, encoding="utf-8").read() == expected
+    d.close()
+
+
+def test_file_export_run_willitem(tmpdir):
+    bw = FakeBalWindow()
+    items = _make_willitems(2)
+    d = dialogs.WillExportDialog(bw, will=items, bal_plugin=bw.bal_plugin)
+    assert d.content_check.isChecked()
+    captured = {}
+
+    def fake_gui(window, title, exporter):
+        captured["title"] = title
+        captured["exporter"] = exporter
+
+    with patch.object(dialogs, "export_meta_gui", side_effect=fake_gui):
+        d._export_file()
+    assert captured["title"] == "will"
+    out = tmpdir.join("will.json").strpath
+    captured["exporter"](out)
+    data = json.load(open(out, encoding="utf-8"))
+    assert set(data) == set(items)
+    assert data["item0"]["tx"] == str(items["item0"].tx)
+    d.close()
+
+
+def test_file_export_empty_under_filter_aborts():
+    bw = FakeBalWindow()
+    items = {
+        "a": StubWillItem("A*", statuses={"VALID": True, "COMPLETE": True})
+    }
+    d = dialogs.WillExportDialog(bw, will=items, bal_plugin=bw.bal_plugin)
+    messages = []
+    d.show_message = lambda msg: messages.append(msg)  # type: ignore[assignment]
+    d._filter_index = 2  # force an empty "Valid NC" selection
+    with patch.object(dialogs, "export_meta_gui") as gui:
+        d._export_file()
+    assert not gui.called
+    assert messages
+    d.close()
+
+
+# ------------------------------------------------------------------ #
+# BalWindow transport helpers
+# ------------------------------------------------------------------ #
+
+def test_bal_window_export_tx_file(tmpdir):
+    import bal.gui.qt.window as window
+
+    items = _make_willitems(3)
+    bw = object.__new__(window.BalWindow)
+    bw.willitems = items
+    out = tmpdir.join("will_tx.txt").strpath
+    bw.export_tx_file(out)
+    expected = ",".join(str(wi.tx) for _, wi in items.items())
+    assert open(out, encoding="utf-8").read() == expected
+
+
+def test_bal_window_set_audio_modem_bitrate():
+    try:
+        import amodem.config
+    except ImportError:
+        return
+    import bal.gui.qt.window as window
+
+    class P:
+        def __init__(self):
+            self.modem_config = None
+
+    probe = P()
+    bw = object.__new__(window.BalWindow)
+    bw.get_audio_modem_plugin = lambda: probe
+    bw.set_audio_modem_bitrate(1)
+    assert probe.modem_config is amodem.config.bitrates[1]
+
+
+# ------------------------------------------------------------------ #
+# WillExportDialog audio page
+# ------------------------------------------------------------------ #
+
+def test_audio_export_page_send():
+    bw = FakeBalWindow(audio_plugin=FakeAudioPlugin())
+    items = _make_willitems(3, payload_len=30)
+    bw.willitems = items
+    d = dialogs.WillExportDialog(bw, bal_plugin=bw.bal_plugin)
+    assert d.audio_send_btn.text() == dialogs._("Send")
+    assert d.audio_send_btn.isEnabled()
+    assert d.kbps_combo.count() > 0
+
+    kbps = int(d.kbps_combo.currentText())
+    d._send_audio()
+    assert bw.bitrate_set == kbps
+    # Whole-will default: the audio payload is a single JSON document.
+    assert len(bw.audio_payloads) == 1
+    data = json.loads(bw.audio_payloads[0])
+    assert set(data) == set(items)
+    d.close()
+
+
+def test_audio_export_page_send_tx_only():
+    bw = FakeBalWindow(audio_plugin=FakeAudioPlugin())
+    items = _make_willitems(3, payload_len=30)
+    bw.willitems = items
+    d = dialogs.WillExportDialog(bw, bal_plugin=bw.bal_plugin)
+    d.content_check.setChecked(False)
+
+    kbps = int(d.kbps_combo.currentText())
+    d._send_audio()
+    assert bw.bitrate_set == kbps
+    expected = "\n".join(dialogs.serialize_tx_list(items))
+    assert bw.audio_payloads == [expected]
+    d.close()
+
+
+def test_audio_export_page_plugin_missing():
+    # The window stays usable: only the audio option is disabled.
+    bw = FakeBalWindow(audio_plugin=None)
+    bw.willitems = _make_willitems(2)
+    d = dialogs.WillExportDialog(bw, bal_plugin=bw.bal_plugin)
+    assert not d.audio_send_btn.isEnabled()
+    assert "not available" in d.audio_warn_label.text()
+    assert len(d.qr_page.frames) >= 1  # QR still usable
+    assert d.file_export_btn.isEnabled()
+    d.close()
+
+
+# ------------------------------------------------------------------ #
+# WillImportDialog audio page
+# ------------------------------------------------------------------ #
+
+def test_audio_import_page_build():
+    bw = FakeBalWindow(audio_plugin=FakeAudioPlugin())
+    d = dialogs.WillImportDialog(bw, bal_plugin=bw.bal_plugin)
+    assert d.kbps_combo.count() > 0
+    assert d.receive_btn.text() == dialogs._("Receive by audio…")
+    assert d.receive_btn.isEnabled()
+    d.close()
+
+
+def test_audio_import_page_plugin_missing():
+    bw = FakeBalWindow(audio_plugin=None)
+    d = dialogs.WillImportDialog(bw, bal_plugin=bw.bal_plugin)
+    assert not d.receive_btn.isEnabled()
+    assert "not available" in d.audio_warn_label.text()
+    assert d.qr_page is not None  # QR import still usable
+    d.close()
+
+
+def test_audio_import_receive_wiring():
+    bw = FakeBalWindow(audio_plugin=FakeAudioPlugin())
+    d = dialogs.WillImportDialog(bw, bal_plugin=bw.bal_plugin)
+    captured = {}
+
+    class FakeWaitingDialog:
+        def __init__(self, parent, msg, task, on_success=None, on_error=None):
+            captured["msg"] = msg
+            captured["task"] = task
+            captured["success"] = on_success
+            captured["error"] = on_error
+
+    imported = []
+
+    def fake_complete(bal_window, bal_plugin, payload, **kwargs):
+        imported.append(payload)
+
+    blob = zlib.compress(b"A" * 40 + b"\n" + b"B" * 40)
+    with patch.object(dialogs, "WaitingDialog", FakeWaitingDialog), patch.object(
+        dialogs, "_complete_import", side_effect=fake_complete
+    ):
+        d._audio_receive()
+        kbps = int(d.kbps_combo.currentText())
+        assert bw.bitrate_set == kbps
+        assert captured["task"] is not None
+        captured["success"](blob)
+    # Payload is the raw decompressed text; autodetect handles the splitting.
+    assert imported == ["A" * 40 + "\n" + "B" * 40]
+    d.close()
+
+
+# ------------------------------------------------------------------ #
+# Whole-will JSON payload serializes a real Transaction (MyEncoder)
+# ------------------------------------------------------------------ #
+
+def test_qr_whole_will_json_serializes_transaction():
+    """Regression: _whole_will_json must not raise
+    "Object of type Transaction is not JSON serializable".
+
+    Real WillItems keep a ``Transaction`` object in ``tx``; the whole-will
+    QR payload (default content scope) must serialize it via MyEncoder the
+    same way write_json_file does.
+    """
+    from bal.core.will import WillItem
+
+    item = WillItem({
+        "tx": _VALID_TX_HEX,
+        "heirs": {},
+        "willexecutor": None,
+        "status": "",
+        "description": "",
+        "time": 0,
+        "change": "",
+        "baltx_fees": 100,
+    })
+    bw = FakeBalWindow()
+    d = dialogs.WillExportDialog(
+        bw, will={"imp0": item}, bal_plugin=bw.bal_plugin, initial_mode="qr"
+    )
+    j = d._whole_will_json()
+    data = json.loads(j)
+    assert data["imp0"]["tx"] == _VALID_TX_HEX
+    d.close()
+
+
+# ------------------------------------------------------------------ #
+# Main
+# ------------------------------------------------------------------ #
+
+if __name__ == "__main__":
+    import inspect
+    import os
+    import tempfile
+
+    class _Path:
+        def __init__(self, d, name):
+            self.strpath = os.path.join(d, name)
+
+    class _Tmp:
+        def __init__(self):
+            self._d = tempfile.mkdtemp()
+
+        def join(self, name):
+            return _Path(self._d, name)
+
+    tmp = _Tmp()
+    for name in sorted(dir()):
+        if name.startswith("test_"):
+            fn = globals()[name]
+            fn(tmp) if inspect.signature(fn).parameters else fn()
+            print("  [OK] {}".format(name))
+    print("[OK] All export dialog GUI tests passed")

tests/test_gui_prepare_will_history.py

@@ -179,6 +179,7 @@ def test_rebuild_path_schedules_full_refresh():
     win.date_to_check = 1_800_000_000
     win.will_settings = {"baltx_fees": 1, "locktime": "1 month"}
     win.bal_plugin = _CfgBag(
+        is_basic_mode=lambda: False,
         MAX_WILLEXECUTOR_FEE=_Cfg(1),
         SAVE_HISTORY=_Cfg(True),
         HISTORY_LABEL=_Cfg("LBL"),
@@ -204,6 +205,46 @@ def test_rebuild_path_schedules_full_refresh():
     schedule_mock.assert_called_once_with()
 
 
+def test_rebuild_purges_stale_wallet_history_before_building():
+    # The rebuild path must drop stale wallet-LOCAL will placeholders (saved by
+    # an earlier prepare) so their coins are available to the new build.
+    win = object.__new__(BalWindow)
+    win.disable_plugin = False
+    win.heirs = {"h": object()}
+    win.willexecutors = {}
+    win.no_willexecutor = True
+    win.willitems = {}
+    win.will = {}
+    win.date_to_check = 1_800_000_000
+    win.will_settings = {"baltx_fees": 1, "locktime": "1 month"}
+    win.bal_plugin = _CfgBag(
+        is_basic_mode=lambda: False,
+        MAX_WILLEXECUTOR_FEE=_Cfg(1),
+        SAVE_HISTORY=_Cfg(True),
+        HISTORY_LABEL=_Cfg("LBL"),
+    )
+    win.window = _FakeWindow()
+    win.window.wallet = _Wallet()
+    with (
+        patch.object(Util, "get_available_utxos", return_value=[]),
+        patch.object(Util, "parse_locktime_string", return_value=1_800_000_001),
+        patch.object(Will, "get_min_locktime", return_value=0),
+        patch.object(Will, "check_amounts"),
+        patch.object(BalWindow, "init_class_variables"),
+        patch.object(BalWindow, "build_will"),
+        patch.object(
+            BalWindow,
+            "check_will",
+            side_effect=[NotCompleteWillException(), None],
+        ),
+        patch.object(BalWindow, "update_all"),
+        patch.object(BalWindow, "_schedule_history_refresh"),
+        patch.object(Will, "remove_stale_wallet_history") as purge_mock,
+    ):
+        BalWindow.build_inheritance_transaction(win)
+    purge_mock.assert_called_once_with(win.window.wallet, "LBL")
+
+
 # ------------------------------------------------------------------ #
 # Main
 # ------------------------------------------------------------------ #

tests/test_gui_qr_transfer.py

@@ -0,0 +1,760 @@
+"""
+Tests for the QR / audio will-transfer dialogs (``bal.gui.qt.dialogs``).
+
+Covers the unified ``WillExportDialog`` (transport radios, stacked pages,
+QR build/navigation, chunk-size / autoplay, filter revert) and the unified
+``WillImportDialog`` (QR frame capture, slot grid, complete-review enabling,
+total mismatch reset, frame assembly -> decode). The wizard and the
+camera/audio paths need a live wallet/hardware and are exercised only
+through the shared frame-assembly path here.
+
+Run:
+    QT_QPA_PLATFORM=offscreen python3 tests/test_gui_qr_transfer.py
+"""
+
+import base64
+import json
+import sys
+from unittest.mock import MagicMock, patch
+
+sys.path.insert(0, __file__.rsplit("/", 2)[0])
+
+from electrum.transaction import Transaction
+from PyQt6.QtWidgets import QApplication, QMainWindow
+
+import bal.gui.qt.dialogs as dialogs
+from bal.core.qrtransfer import CHUNK_PRESETS, encode_transfer, split_frames
+from bal.core.will import WillItem
+
+_app = QApplication.instance() or QApplication(sys.argv)
+
+# A valid 1x1 transparent PNG, good enough for BalDialog's window icon.
+_PNG_BYTES = base64.b64decode(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
+)
+
+# A valid serialized Bitcoin transaction hex (1 input + 1 P2PKH output),
+# reused for the WillItem status regression test.
+_VALID_TX_HEX = (
+    "01000000012a5c9a94fcde98f5581cd00162c60a13936ceb75389ea65b"
+    "f38633b424eb4031000000006c493046022100a82bbc57a0136751e543"
+    "3f41cf000b3f1a99c6744775e76ec764fb78c54ee100022100f9e80b7d"
+    "e89de861dc6fb0c1429d5da72c2b6b2ee2406bc9bfb1beedd729d98501"
+    "2102e61d176da16edd1d258a200ad9759ef63adf8e14cd97f53227bae3"
+    "5cdb84d2f6ffffffff0140420f00000000001976a914230ac37834073a"
+    "42146f11ef8414ae929feaafc388ac00000000"
+)
+
+
+class _Cfg:
+    def __init__(self, value):
+        self._value = value
+
+    def get(self):
+        return self._value
+
+
+class FakePlugin:
+    # Smallest QR preset: long transfers produce several frames.
+    QR_CHUNK_SIZE = _Cfg(CHUNK_PRESETS[0][1])
+
+    def read_file(self, path):
+        return _PNG_BYTES
+
+
+class FakeWindow(QMainWindow):
+    config = {}
+
+    def format_amount(self, amount):
+        return "{:.8f}".format(amount)
+
+    def format_amount_and_units(self, amount):
+        return "{:.8f} sat".format(amount)
+
+
+class FakeBalWindow:
+    """Duck-typed stand-in for BalWindow (dialog layer only)."""
+
+    def __init__(self):
+        self.window = FakeWindow()
+        self.bal_plugin = FakePlugin()
+        self.willitems = {}
+
+    def get_audio_modem_plugin(self):
+        return None
+
+
+class StubTx:
+    def __init__(self, payload):
+        self.payload = payload
+
+    def txid(self):
+        return "{:064x}".format(hash(self.payload) & 0xFFFFFFFFFFFFFFFF)
+
+    def __str__(self):
+        return self.payload
+
+
+class StubWillItem:
+    def __init__(self, payload, statuses=None):
+        self.tx = StubTx(payload)
+        self.statuses = statuses or {}
+
+    def get_status(self, name):
+        return self.statuses.get(name, False)
+
+    def to_dict(self):
+        return {"tx": str(self.tx), "status": self.statuses}
+
+
+def _make_willitems(n=3, payload_len=120, payloads=None):
+    if payloads is None:
+        payloads = ["T{}".format(i) * payload_len for i in range(n)]
+    return {
+        "item{}".format(i): StubWillItem(p)
+        for i, p in enumerate(payloads)
+    }
+
+
+# ------------------------------------------------------------------ #
+# WillExportDialog (QR transport via d.qr_page)
+# ------------------------------------------------------------------ #
+
+def test_export_dialog_builds():
+    bw = FakeBalWindow()
+    bw.willitems = _make_willitems()
+    d = dialogs.WillExportDialog(bw, bal_plugin=bw.bal_plugin, initial_mode="qr")
+    page = d.qr_page
+    assert d.transport_qr.isChecked()
+    assert page.tx_strings
+    assert page.frames
+    assert len(page.frames) >= 1
+    # Frame 1 is shown.
+    assert page.qr_view.text == page.frames[0]
+    assert "1" in page.progress_label.text()
+    d.close()
+
+
+def test_export_dialog_unified_transports():
+    # One window hosts the three transports as stacked, radio-selected pages.
+    bw = FakeBalWindow()
+    bw.willitems = _make_willitems()
+    d = dialogs.WillExportDialog(bw, bal_plugin=bw.bal_plugin)
+    assert d.stacked.count() == 3
+    assert d.transport_file.isChecked()
+    assert d.stacked.currentWidget() is d.file_page
+    d._on_mode_clicked(d.MODE_QR)
+    assert d.stacked.currentWidget() is d.qr_page
+    d._on_mode_clicked(d.MODE_AUDIO)
+    assert d.stacked.currentWidget() is d.audio_page
+    d.close()
+
+
+def test_import_dialog_qr_page_has_no_audio():
+    # Audio lives on the import dialog's own audio page, never in the QR page.
+    bw = FakeBalWindow()
+    d = dialogs.WillImportDialog(bw, bal_plugin=bw.bal_plugin)
+    page = d.qr_page
+    assert not hasattr(page, "_audio_receive")
+    texts = [b.text() for b in page.findChildren(dialogs.QPushButton)]
+    assert not any("Audio" in t for t in texts)
+    assert d.receive_btn is not None
+    d.close()
+
+
+def test_export_dialog_empty_close():
+    # An empty will shows a modal message and no widgets are built; stub the
+    # message out for the test.
+    orig = dialogs.MessageBoxMixin.show_message
+    dialogs.MessageBoxMixin.show_message = lambda self, msg, icon=None: None
+    try:
+        bw = FakeBalWindow()
+        d = dialogs.WillExportDialog(bw, bal_plugin=bw.bal_plugin)
+        assert not d.isVisible()
+        assert not hasattr(d, "qr_page")
+        d.close()
+    finally:
+        dialogs.MessageBoxMixin.show_message = orig
+
+
+def test_imported_item_status_not_none():
+    # Regression: a WillItem built from a bare {"tx": hex} had a None status,
+    # so set_status (e.g. IMPORTED / INVALIDATED from the import validity
+    # pass) crashed with "unsupported operand type(s) for +=: 'NoneType' and
+    # 'str'".
+    with patch.object(Transaction, "add_info_from_wallet"):
+        wi = WillItem({"tx": _VALID_TX_HEX}, wallet=None)
+        assert wi.status == ""
+        assert wi.set_status("IMPORTED", True) is True
+        assert wi.set_status("INVALIDATED", True) is True
+        assert "Imported" in wi.status and "Invalidated" in wi.status
+
+
+def test_export_auto_scroll():
+    bw = FakeBalWindow()
+    bw.willitems = _make_willitems(n=6, payload_len=400)
+    d = dialogs.WillExportDialog(bw, bal_plugin=bw.bal_plugin, initial_mode="qr")
+    page = d.qr_page
+    assert page.fps_spin is not None
+    assert not page.auto_timer.isActive()
+
+    page.fps_spin.setValue(2)
+    page._toggle_auto()
+    assert page.auto_timer.isActive()
+    assert page.auto_btn.text() == dialogs._("Stop")
+    page._auto_step()
+    assert page.index == 1
+    page._toggle_auto()
+    assert not page.auto_timer.isActive()
+    assert page.auto_btn.text() == dialogs._("Auto")
+
+    # Advancing past the last frame stops the slideshow automatically.
+    page._toggle_auto()
+    page.index = len(page.frames) - 1
+    page._auto_step()
+    assert not page.auto_timer.isActive()
+    d.close()
+
+
+def test_export_auto_scroll_loop():
+    bw = FakeBalWindow()
+    bw.willitems = _make_willitems(n=6, payload_len=400)
+    d = dialogs.WillExportDialog(bw, bal_plugin=bw.bal_plugin, initial_mode="qr")
+    page = d.qr_page
+    assert page.loop_check is not None
+
+    # Loop on: reaching the last code wraps back to the first and keeps going.
+    page.loop_check.setChecked(True)
+    page._toggle_auto()
+    assert page.auto_timer.isActive()
+    page.index = len(page.frames) - 1
+    page._auto_step()
+    assert page.index == 0
+    assert page.auto_timer.isActive()
+    page._toggle_auto()
+
+    # Loop off: reaching the last code stops the slideshow.
+    page.loop_check.setChecked(False)
+    page._toggle_auto()
+    page.index = len(page.frames) - 1
+    page._auto_step()
+    assert not page.auto_timer.isActive()
+    d.close()
+
+
+def test_export_filter_valid_and_valid_nc():
+    bw = FakeBalWindow()
+    a = StubWillItem("A" * 120, statuses={"VALID": True, "COMPLETE": True})
+    b = StubWillItem("B" * 120, statuses={"VALID": True})
+    c = StubWillItem("C" * 120)
+    bw.willitems = {"a": a, "b": b, "c": c}
+    d = dialogs.WillExportDialog(bw, bal_plugin=bw.bal_plugin, initial_mode="qr")
+    page = d.qr_page
+    assert d.filter_combo.count() == 3
+    # Whole-will default: a single JSON document carrying all selected items.
+    assert d.content_check.isChecked()
+    assert len(page.tx_strings) == 1
+    data = json.loads(page.tx_strings[0])
+    assert set(data) == {"a", "b", "c"}
+
+    # Switch to tx-only content, then exercise the filters.
+    d.content_check.setChecked(False)
+    assert len(page.tx_strings) == 3
+
+    # "Valid" filter -> only the valid items (a, b).
+    d._on_filter_change(1)
+    assert sorted(page.tx_strings) == ["A" * 120, "B" * 120]
+
+    # "Valid NC" filter -> only the valid, not-complete item (b).
+    d._on_filter_change(2)
+    assert sorted(page.tx_strings) == ["B" * 120]
+    assert page.qr_view.text == page.frames[0]
+    d.close()
+
+
+def test_export_filter_empty_reverts():
+    bw = FakeBalWindow()
+    # Only a COMPLETE valid item: "Valid NC" selects nothing -> revert.
+    bw.willitems = {
+        "a": StubWillItem("A" * 120, statuses={"VALID": True, "COMPLETE": True})
+    }
+    d = dialogs.WillExportDialog(bw, bal_plugin=bw.bal_plugin, initial_mode="qr")
+    messages = []
+    d.show_message = lambda msg: messages.append(msg)  # type: ignore[assignment]
+    d._on_filter_change(2)  # "Valid NC" -> empty subset
+    assert messages
+    assert d._filter_index == 0  # reverted to "All"
+    assert d.filter_combo.currentIndex() == 0
+    assert len(d.qr_page.tx_strings) == 1
+    d.close()
+
+
+def test_export_navigation_and_chunk_change():
+    # Low-redundancy serialized transactions resist deflate, so even the
+    # compressed best-of transfer still needs several frames at the default
+    # chunk and navigation across frames is exercised.
+    def noisy(pad):
+        return "".join("{:02x}".format((pad * 31 + j * 101 + j * j) % 256) for j in range(200))
+
+    bw = FakeBalWindow()
+    bw.willitems = _make_willitems(
+        n=6, payload_len=400,
+        payloads=["{}0{}".format(noisy(i), "T" * 50) for i in range(6)],
+    )
+    d = dialogs.WillExportDialog(bw, bal_plugin=bw.bal_plugin, initial_mode="qr")
+    page = d.qr_page
+    first_count = len(page.frames)
+    assert first_count > 1  # long transfer, small default chunk
+
+    assert not page.prev_btn.isEnabled()
+    page._next()
+    assert page.index == 1
+    assert page.qr_view.text == page.frames[1]
+    assert page.prev_btn.isEnabled()
+    page._prev()
+    assert page.index == 0
+    assert page.qr_view.text == page.frames[0]
+
+    # Switch to the largest preset: fewer, bigger frames.
+    page._on_chunk_change(len(dialogs.CHUNK_PRESETS) - 1)
+    assert len(page.frames) < first_count
+    assert page.index == 0
+    d.close()
+
+
+# ------------------------------------------------------------------ #
+# WillImportDialog (QR transport via d.qr_page)
+# ------------------------------------------------------------------ #
+
+def test_import_frame_flow():
+    bw = FakeBalWindow()
+    d = dialogs.WillImportDialog(bw, bal_plugin=bw.bal_plugin)
+    page = d.qr_page
+    assert not page.review_btn.isEnabled()
+    assert not page.slot_area.isVisible()
+
+    transfer = encode_transfer(["A" * 120, "B" * 120, "C" * 120])
+    frames = split_frames(transfer, 150)
+    assert len(frames) > 1
+
+    for frame in frames:
+        page._add_frame(frame)
+    assert page.total == len(frames)
+    assert page.review_btn.isEnabled()
+    # isVisible() needs a shown parent; assert the widget is not hidden instead.
+    assert not page.slot_area.isHidden()
+    assert len(page.slot_widgets) == page.total
+    assert "All" in page.status_label.text()
+    # Duplicate capture is harmless.
+    page._add_frame(frames[0])
+    assert len(page.frames) == page.total
+    d.close()
+
+
+def test_import_assembles_and_decodes():
+    bw = FakeBalWindow()
+    d = dialogs.WillImportDialog(bw, bal_plugin=bw.bal_plugin)
+    page = d.qr_page
+    captured = {}
+
+    def fake_finish(payload):
+        captured["payload"] = payload
+
+    page._finish_import = fake_finish
+    transfer = encode_transfer(["P" * 130, "Q" * 130])
+    for frame in split_frames(transfer, 150):
+        page._add_frame(frame)
+    page._review_and_sign()
+    # The payload is rejoined into an opaque string for autodetect.
+    assert captured["payload"].split("\n") == ["P" * 130, "Q" * 130]
+    d.close()
+
+
+def test_decode_will_payload_autodetect():
+    # Whole-will JSON is recognized as a will document.
+    payload = json.dumps({"item1": {"tx": "AAAA", "status": {"VALID": True}}})
+    kind, data = dialogs.decode_will_payload(payload)
+    assert kind == "will"
+    assert data["item1"]["tx"] == "AAAA"
+
+    # A singleton dict whose value is not an item dict falls back to txs.
+    kind, data = dialogs.decode_will_payload('{"foo": 1}')
+    assert kind == "txs"
+
+    # Comma and/or newline separated transactions.
+    kind, data = dialogs.decode_will_payload("AAAA,BBBB\nCCCC")
+    assert kind == "txs"
+    assert data == ["AAAA", "BBBB", "CCCC"]
+
+    # A single transaction with no separators.
+    kind, data = dialogs.decode_will_payload("HEXHEX")
+    assert kind == "txs"
+    assert data == ["HEXHEX"]
+
+
+def test_whole_will_qr_roundtrip():
+    # "Whole will" produces a single JSON document that survives a full
+    # QR encode -> frame capture -> assemble -> decode cycle.
+    bw = FakeBalWindow()
+    items = _make_willitems(2)
+    bw.willitems = items
+    d = dialogs.WillExportDialog(bw, bal_plugin=bw.bal_plugin, initial_mode="qr")
+    page = d.qr_page
+    assert d.content_check.isChecked()
+    assert len(page.tx_strings) == 1
+
+    # Rebuild the transfer from the dialog's own strings, as the importer does.
+    transfer = encode_transfer(page.tx_strings)
+    impl = dialogs.WillImportDialog(bw, bal_plugin=bw.bal_plugin)
+    import_page = impl.qr_page
+    for frame in split_frames(transfer, dialogs.CHUNK_PRESETS[0][1]):
+        import_page._add_frame(frame)
+    assert import_page.review_btn.isEnabled()
+    caught = {}
+
+    def fake_finish(payload):
+        caught["payload"] = payload
+
+    import_page._finish_import = fake_finish
+    import_page._review_and_sign()
+    kind, data = dialogs.decode_will_payload(caught["payload"])
+    assert kind == "will"
+    assert set(data) == {"item0", "item1"}
+    d.close()
+    impl.close()
+
+
+def test_import_total_mismatch_resets():
+    bw = FakeBalWindow()
+    d = dialogs.WillImportDialog(bw, bal_plugin=bw.bal_plugin)
+    page = d.qr_page
+    warnings = []
+    page.show_warning = lambda msg: warnings.append(msg)  # type: ignore[assignment]
+
+    frames_a = split_frames(encode_transfer(["A" * 120, "B" * 120]), 150)
+    frames_b = split_frames(encode_transfer(["A" * 120, "B" * 120, "C" * 120]), 150)
+    for frame in frames_a:
+        page._add_frame(frame)
+    assert page.total == len(frames_a)
+
+    # A frame with a different total wipes the import; the first frame of
+    # the new transfer must be scanned afresh.
+    page._add_frame(frames_b[0])
+    assert warnings
+    assert page.total == 0
+    assert not page.frames
+    assert not page.review_btn.isEnabled()
+    d.close()
+
+
+def test_import_manual_entry():
+    bw = FakeBalWindow()
+    d = dialogs.WillImportDialog(bw, bal_plugin=bw.bal_plugin)
+    page = d.qr_page
+    frames = split_frames(encode_transfer(["M" * 120]), 150)
+    page.manual_edit.setText(frames[0])
+    page._add_from_manual()
+    assert page.manual_edit.text() == ""
+    assert page.total == 1
+    assert page.review_btn.isEnabled()
+    d.close()
+
+
+# ------------------------------------------------------------------ #
+# Continuous camera scan (change/detection debounce + auto-finish)
+# ------------------------------------------------------------------ #
+
+def _fresh_debounce():
+    return {
+        "last_index": None,
+        "last_payload": None,
+        "pending_index": None,
+        "pending_payload": None,
+        "pending_count": 0,
+    }
+
+
+def test_qr_import_debounce_pending_then_accept():
+    s = _fresh_debounce()
+    # First sighting of a new identity: pending, not yet stored.
+    assert dialogs.qr_import_accept_frame(s, "balqr", "balqr:2", 2, 1, "PAYLOAD1") == "pending"
+    assert s["pending_count"] == 1
+    assert s["last_index"] is None
+    # A second stable read of the same identity: accepted.
+    assert dialogs.qr_import_accept_frame(s, "balqr", "balqr:2", 2, 1, "PAYLOAD1") == "accept"
+    assert s["last_index"] == 1
+    assert s["last_payload"] == "PAYLOAD1"
+    assert s["pending_count"] == 0
+
+
+def test_qr_import_debounce_re_reading_last_is_ignored():
+    s = _fresh_debounce()
+    dialogs.qr_import_accept_frame(s, "balqr", "balqr:2", 2, 1, "P1")
+    dialogs.qr_import_accept_frame(s, "balqr", "balqr:2", 2, 1, "P1")  # accepted
+    # The exporter is still showing frame 1: must be ignored, not accepted.
+    assert dialogs.qr_import_accept_frame(s, "balqr", "balqr:2", 2, 1, "P1") == "ignore"
+    assert s["last_index"] == 1
+    assert s["pending_count"] == 0
+
+
+def test_qr_import_debounce_transition_pending_resets():
+    s = _fresh_debounce()
+    dialogs.qr_import_accept_frame(s, "balqr", "balqr:2", 2, 1, "P1")
+    dialogs.qr_import_accept_frame(s, "balqr", "balqr:2", 2, 1, "P1")  # accept frame 1
+    # A new identity interrupts the pending accumulation.
+    assert dialogs.qr_import_accept_frame(s, "balqr", "balqr:2", 2, 2, "P2") == "pending"
+    assert dialogs.qr_import_accept_frame(s, "balqr", "balqr:2", 2, 2, "P2") == "accept"
+    # Same-index duplicate with different payload is treated as new identity.
+    assert dialogs.qr_import_accept_frame(s, "balqr", "balqr:2", 2, 2, "P2") == "ignore"
+
+
+def test_qr_import_debounce_total_mismatch_resets():
+    s = _fresh_debounce()
+    # In-range frame is accepted even though its declared total is ignored.
+    assert dialogs.qr_import_accept_frame(s, "balqr", "balqr:3", 3, 2, "P2") == "pending"
+    assert dialogs.qr_import_accept_frame(s, "balqr", "balqr:3", 3, 2, "P2") == "accept"
+    # A frame that belongs to a different transfer.
+    assert dialogs.qr_import_accept_frame(s, "balqr", "balqr:4", 4, 2, "P2B") == "reset"
+    # Once the policy is rebased on the new transfer, frames resume normally
+    # (the widget clears the debounce while wiping the import).
+    s["key"] = None
+    assert dialogs.qr_import_accept_frame(s, "balqr", "balqr:4", 4, 2, "P2B") == "pending"
+
+
+def test_qr_import_handle_scanned_text_autofinish():
+    bw = FakeBalWindow()
+    d = dialogs.WillImportDialog(bw, bal_plugin=bw.bal_plugin)
+    page = d.qr_page
+    reviewed = []
+    page._review_and_sign = lambda: reviewed.append(True)  # type: ignore[assignment]
+
+    frames = split_frames(encode_transfer(["A" * 120, "B" * 120]), 150)
+    assert len(frames) > 1
+
+    # The camera session is running and every frame needs two stable reads.
+    page._scanning = True
+    for frame in frames:
+        for _rep in range(2):
+            page._handle_scanned_text(frame)
+    assert page.total == len(frames)
+    assert len(page.frames) == len(frames)
+    assert page.review_btn.isEnabled()
+
+    # With all frames stored, the loop auto-finishes exactly once.
+    _app.processEvents()
+    assert reviewed == [True]
+    # The camera loop was stopped before handing over to the review step.
+    assert not page._scanning
+    assert not page._scan_timer.isActive()
+    d.close()
+
+
+def test_qr_import_handle_scanned_text_manual_does_not_autofinish():
+    # Without a camera session running, extra frames never auto-proceed.
+    bw = FakeBalWindow()
+    d = dialogs.WillImportDialog(bw, bal_plugin=bw.bal_plugin)
+    page = d.qr_page
+    reviewed = []
+    page._review_and_sign = lambda: reviewed.append(True)  # type: ignore[assignment]
+
+    frames = split_frames(encode_transfer(["A" * 120, "B" * 120]), 150)
+    assert len(frames) > 1
+    assert not page._scanning
+    for frame in frames:
+        for _rep in range(2):
+            page._handle_scanned_text(frame)
+    assert len(page.frames) == len(frames)
+    _app.processEvents()
+    assert reviewed == []
+    d.close()
+
+
+# ------------------------------------------------------------------ #
+# Animated-QR formats (BC-UR v1/v2, BBQR) via the export/import pages
+# ------------------------------------------------------------------ #
+
+def test_export_format_combo_switches_codecs():
+    bw = FakeBalWindow()
+    bw.willitems = _make_willitems(n=6, payload_len=400)
+    d = dialogs.WillExportDialog(bw, bal_plugin=bw.bal_plugin, initial_mode="qr")
+    page = d.qr_page
+    assert page.format == "balqr"
+    assert page.frames[0].startswith("BAL1")
+    assert page.format_combo.count() == 4
+
+    page._on_format_change(1)  # BC-UR v1
+    assert page.format == "ur1"
+    assert page.frames[0].startswith("ur:bytes/")
+    assert page.index == 0
+    assert page.qr_view.text == page.frames[0]
+
+    page._on_format_change(2)  # BC-UR v2
+    assert page.format == "ur2"
+    assert page.frames[0].startswith("ur:bytes/")
+
+    page._on_format_change(3)  # BBQR
+    assert page.format == "bbqr"
+    assert page.frames[0].startswith("B$")
+    d.close()
+
+
+def test_export_animated_format_frames_fit_budget():
+    bw = FakeBalWindow()
+    bw.willitems = _make_willitems(n=6, payload_len=400)
+    d = dialogs.WillExportDialog(bw, bal_plugin=bw.bal_plugin, initial_mode="qr")
+    page = d.qr_page
+    for index in range(1, 4):
+        page._on_format_change(index)
+        for frame in page.frames:
+            assert len(frame) <= dialogs.CHUNK_PRESETS[0][1]
+    d.close()
+
+
+def _import_roundtrip_fmt(fmt_index):
+    bw = FakeBalWindow()
+    bw.willitems = _make_willitems(2)
+    d = dialogs.WillExportDialog(bw, bal_plugin=bw.bal_plugin, initial_mode="qr")
+    page = d.qr_page
+    page._on_format_change(fmt_index)
+    frames = list(page.frames)
+    assert frames
+    d.close()
+
+    impl = dialogs.WillImportDialog(bw, bal_plugin=bw.bal_plugin)
+    import_page = impl.qr_page
+    caught = {}
+    import_page._finish_import = lambda payload: caught.__setitem__("payload", payload)
+    for frame in frames:
+        import_page._add_frame(frame)
+    assert import_page.review_btn.isEnabled()
+    import_page._review_and_sign()
+    kind, data = dialogs.decode_will_payload(caught["payload"])
+    assert kind == "will"
+    assert set(data) == {"item0", "item1"}
+    impl.close()
+
+
+def test_import_ur1_roundtrip():
+    _import_roundtrip_fmt(1)
+
+
+def test_import_ur2_roundtrip():
+    _import_roundtrip_fmt(2)
+
+
+def test_import_bbqr_roundtrip():
+    _import_roundtrip_fmt(3)
+
+
+def test_import_animated_scan_debounce_autofinish():
+    bw = FakeBalWindow()
+    bw.willitems = _make_willitems(2)
+    d = dialogs.WillExportDialog(bw, bal_plugin=bw.bal_plugin, initial_mode="qr")
+    page = d.qr_page
+    page._on_format_change(2)  # BC-UR v2 fountain
+    frames = list(page.frames)
+    d.close()
+
+    impl = dialogs.WillImportDialog(bw, bal_plugin=bw.bal_plugin)
+    import_page = impl.qr_page
+    reviewed = []
+    import_page._review_and_sign = lambda: reviewed.append(True)  # type: ignore[assignment]
+    import_page._scanning = True
+    for frame in frames:
+        for _rep in range(2):
+            import_page._handle_scanned_text(frame)
+    assert import_page.review_btn.isEnabled()
+    # The fountain transfer's part count is ``len(frames) // 2`` (pure + one
+    # redundant mixed wave).
+    assert import_page.total == len(frames) // 2
+    assert len(import_page.frames) >= import_page.total
+    assert import_page.review_btn.isEnabled()
+    _app.processEvents()
+    assert reviewed == [True]
+    assert not import_page._scanning
+    impl.close()
+
+
+def test_import_garbage_scan_is_ignored():
+    bw = FakeBalWindow()
+    d = dialogs.WillImportDialog(bw, bal_plugin=bw.bal_plugin)
+    page = d.qr_page
+    for garbage in ("hello world", "12345", "B$ZZ", ""):
+        page._handle_scanned_text(garbage)
+        assert not page.frames
+        assert page.total == 0
+        assert not page.review_btn.isEnabled()
+    d.close()
+
+
+def test_import_different_animated_transfer_resets():
+    bw = FakeBalWindow()
+    d = dialogs.WillImportDialog(bw, bal_plugin=bw.bal_plugin)
+    page = d.qr_page
+    warnings = []
+    page.show_warning = lambda msg: warnings.append(msg)  # type: ignore[assignment]
+
+    frames_a = split_frames(encode_transfer(["A" * 120, "B" * 120]), 150)
+    frames_b = split_frames(encode_transfer(["A" * 120, "B" * 120, "C" * 120]), 150)
+    for frame in frames_a:
+        page._add_frame(frame)
+    assert page.total == len(frames_a)
+    assert not warnings
+
+    page._add_frame(frames_b[0])
+    assert warnings
+    assert page.total == 0
+    assert not page.frames
+    assert not page.review_btn.isEnabled()
+    d.close()
+
+
+def test_import_start_stop_scan_signal_wiring():
+    """Regression: _start_scan/_stop_scan must use the QVideoSink signal
+    videoFrameChanged, not the videoFrame frame getter.
+
+    On PyQt6, ``QVideoSink.videoFrame`` is a method (the frame getter), so
+    ``.videoFrame.connect(...)`` raises AttributeError. This test drives the
+    real sink life-cycle with a mocked camera and asserts the scan session
+    starts/ends cleanly with no error.
+    """
+    from PyQt6.QtMultimedia import QCamera, QMediaCaptureSession, QMediaDevices
+
+    bw = FakeBalWindow()
+    d = dialogs.WillImportDialog(bw, bal_plugin=bw.bal_plugin)
+    page = d.qr_page
+    errors = []
+    page.show_error = lambda msg: errors.append(msg)  # type: ignore[assignment]
+
+    fake_device = MagicMock()
+    fake_device.isNull.return_value = False
+
+    with (
+        patch.object(QMediaDevices, "defaultVideoInput", return_value=fake_device),
+        # Mock camera + capture session; the QVideoSink stays real so the
+        # videoFrameChanged connect/disconnect wiring is exercised for real.
+        patch.object(QCamera, "__new__", return_value=MagicMock()),
+        patch.object(QMediaCaptureSession, "__new__", return_value=MagicMock()),
+    ):
+        page._start_scan()
+        assert page._scanning is True
+        assert not errors
+
+        page._stop_scan()
+    assert page._scanning is False
+    assert page._camera is None
+    assert page._video_sink is None
+    assert not errors
+    d.close()
+
+
+# ------------------------------------------------------------------ #
+# Main
+# ------------------------------------------------------------------ #
+
+if __name__ == "__main__":
+    for name in sorted(dir()):
+        if name.startswith("test_"):
+            globals()[name]()
+            print(f"  [OK] {name}")
+    print("[OK] All QR transfer GUI tests passed")

tests/test_gui_widgets.py

@@ -183,6 +183,22 @@ def test_locktime_raw_edit_get_set_value():
     assert "d" in val
 
 
+def test_locktime_date_edit_get_set_value_roundtrip():
+    """set_value(x) must roundtrip to get_value() == x (same timezone).
+
+    Guards a timezone regression that made the Date editor return the stored
+    wall clock re-read as local time, i.e. ``x + utc_offset``. That broke the
+    set_value/get_value roundtrip and kept the valueEdited ->
+    update_setting_widgets -> set_value signal cycle alive forever, ending in a
+    RecursionError when opening the "Build your will" wizard (Next button).
+    """
+    from bal.gui.qt.widgets import LockTimeDateEdit
+    edit = LockTimeDateEdit()
+    for ts in (1700000000, 1750000000, 2147483647):
+        edit.set_value(ts)
+        assert edit.get_value() == ts
+
+
 # ------------------------------------------------------------------ #
 # PercAmountEdit
 # ------------------------------------------------------------------ #

tests/test_gui_will_flows.py

@@ -269,7 +269,9 @@ def test_prepare_will_builds_and_persists():
 
     assert item.get_status("VALID"), "fresh items default to VALID"
     assert txid == item.tx.txid()
-    assert isinstance(txid, str) and txid.startswith("2"), "raw tx id expected"
+    assert isinstance(txid, str) and len(txid) == 64 and all(
+        c in "0123456789abcdef" for c in txid
+    ), "raw tx id expected (64-char hex, not a label/short id)"
     assert not item.tx.is_complete(), "unsigned will must not be complete"
     assert isinstance(item.tx.locktime, int) and item.tx.locktime > 0
 
@@ -388,6 +390,110 @@ def test_insufficient_funds_warns():
     assert not ctl.willitems
 
 
+def test_guard_not_blocked_by_old_built_will():
+    """Regression: shortening the delivery in the STORED settings (relative
+    "1y"/"30d") while an old, still-VALID built will is frozen at a longer
+    locktime must NOT fire the "locktime is lower than threshold" guard.
+
+    The old guard compared the fresh settings locktime against ``date_to_check``
+    anchored to the built will (see ``resolve_date_to_check``), so a built-will
+    delivery longer than the settings' one made it fire even though the settings
+    are internally consistent (locktime is 30d AFTER the threshold).  The guard
+    must instead compare the stored settings on a single reference frame
+    (``BalWindow.is_locktime_below_threshold``); ``date_to_check`` keeps its
+    built anchor for the expiry/validity checks.
+    """
+    with _no_willexecutors():
+        ctl = make_controller()
+        ctl.bal_plugin.USER_TYPE.set("advanced")  # ADVANCED Check-Alive mode
+        ctl.prepare_will()
+        txid, item = _single(ctl)
+
+        # Freeze the built (VALID) will at a delivery one year longer than the
+        # now-shortened settings: the pre-fix guard would reject the rebuild.
+        item.tx.locktime = item.tx.locktime + 365 * 86400
+        ctl.will_settings = {"locktime": "1y", "threshold": "30d"}
+        Util.fix_will_settings_tx_fees(ctl.will_settings)
+
+        ctl.init_class_variables()
+
+        # date_to_check is anchored to the built will (long delivery)...
+        assert ctl.date_to_check == item.tx.locktime - 30 * 86400
+        # ...and the OLD guard would have fired here:
+        old_locktime = Util.parse_locktime_string(ctl.will_settings["locktime"])
+        assert old_locktime < ctl.date_to_check
+        # but the settings themselves are consistent, so the guard must pass:
+        assert ctl.is_locktime_below_threshold() is False
+        assert not ctl.window.errors
+
+
+def test_anticipated_rebuild_reanchors_date_to_check():
+    """Regression (karen7): rebuilding a SIGNED will whose delivery was
+    anticipated (per-heir recipes shortened from 2y to 1y, ADVANCED mode) must
+    succeed.
+
+    ``date_to_check`` stays anchored to the OLD built delivery for the validity
+    checks, but ``build_will`` must re-anchor it to the NEW (earliest current)
+    delivery as its build filter: before the fix the stale 2028 anchor rejected
+    every "1y" heir (cmp <= 0 in ``fixed_percent_lists_amount``) and the build
+    reported ``NO_FUTURE_DATE``.  The old signed item is then superseded by
+    ``search_rai`` (REPLACED -> no on-chain invalidation) and the rebuilt will
+    is coherent again.
+    """
+    with _no_willexecutors():
+        ctl = make_controller()
+        ctl.bal_plugin.USER_TYPE.set("advanced")
+        # Per-heir deliveries require multiverse mode (the only way heirs can
+        # carry a different recipe than the settings locktime).
+        ctl.bal_plugin.ENABLE_MULTIVERSE.set(True)
+        ctl.will_settings = {"locktime": "2y", "threshold": "150d", "baltx_fees": 20}
+        Util.fix_will_settings_tx_fees(ctl.will_settings)
+        ctl.heirs["alice"][2] = "2y"
+        ctl.heirs["bob"][2] = "2y"
+
+        # Build and sign a 2y will (the old, committed delivery).
+        ctl.prepare_will()
+        old_txid, _old_item = _single(ctl)
+        old_locktime = _old_item.tx.locktime
+        signed = ctl.sign_transactions(None)
+        _old_item.tx = Will.get_tx_from_any(str(signed[old_txid]))
+        Will.check_signatures(ctl.willitems, ctl.wallet)
+        assert _old_item.get_status("COMPLETE")
+
+        # Anticipate: shorten every heir to 1y.
+        ctl.heirs["alice"][2] = "1y"
+        ctl.heirs["bob"][2] = "1y"
+
+        ctl.init_class_variables()
+        # date_to_check stays anchored to the OLD built delivery...
+        assert ctl.date_to_check == old_locktime - 150 * 86400
+        # ...and that stale anchor would reject the anticipated "1y" dates.
+        assert Util.parse_locktime_string("1y") < ctl.date_to_check
+
+        # The rebuild must succeed (re-anchored to the new delivery).
+        willitems = ctl.build_inheritance_transaction()
+
+    assert ctl.heirs.last_build_error is None, "NO_FUTURE_DATE must not fire"
+    new_valid = [
+        it for tid, it in willitems.items()
+        if tid != old_txid and it.get_status("VALID")
+    ]
+    assert new_valid, "the anticipated (1y) will must build and stay VALID"
+    new_item = new_valid[0]
+    assert new_item.tx.locktime < old_locktime, "delivery must be anticipated"
+    # date_to_check was re-anchored to the rebuilt delivery (1y minus 150d).
+    assert abs(ctl.date_to_check - (new_item.tx.locktime - 150 * 86400)) < 3600
+
+    # The old signed item is kept but superseded (REPLACED -> not VALID).
+    assert _old_item.get_status("REPLACED") is True
+    assert _old_item.get_status("VALID") is False
+
+    # The rebuilt will is coherent (plain rebuild, no on-chain invalidation).
+    assert ctl.check_will() is True
+    assert not any("delivery date" in m for m in ctl.window.messages)
+    assert not ctl.window.errors
+
+
 def _run_all():
     tests = [fn for name, fn in sorted(globals().items()) if name.startswith("test_")]
     for fn in tests:

tests/test_heir_relative_anchor.py

@@ -18,9 +18,10 @@ The two gates that produced the prompt are covered here:
      never read as EXPIRED because the check window drifts past the frozen
      tx locktime.
 
-The karen7 regtest wallet fixture (``tests/karen7``) reproduces the exact
+The reported state (reproduced hermetically here — the original live wallet
-reported state: heirs with ``"1y"``, a signed/pushed/checked item whose frozen
+dump ``tests/karen7`` is gitignored and regenerated as the wallet evolves) is:
-tx.locktime is 2027-08-05 (built 2026-08-05), and will_settings
+heirs with ``"1y"``, a signed/pushed/checked item whose frozen tx.locktime is
+2027-08-05 (built 2026-08-05), and will_settings
 ``{"locktime": "2y", "threshold": "150d"}``.
 
 Run:
@@ -28,18 +29,16 @@ Run:
     python3 tests/test_heir_relative_anchor.py
 """
 
-import copy
-import json
 import os
 import sys
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), os.pardir))
 
+import pytest  # noqa: E402  (path insert above)
 from electrum import constants  # noqa: E402  (path insert above)
 
-constants.net = constants.BitcoinRegtest
-
 from bal.core.checkalive import resolve_date_to_check  # noqa: E402
+from bal.core.util import copy_structure  # noqa: E402
 from bal.core.will import (  # noqa: E402
     HeirNotFoundException,
     NoHeirsException,
@@ -49,6 +48,16 @@ from bal.core.will import (  # noqa: E402
     WillPostponedException,
 )
 
+
+@pytest.fixture(autouse=True)
+def _regtest_net():
+    """Run these regtest-focused tests with BitcoinRegtest, restoring mainnet
+    afterwards so sibling test modules are unaffected by the net switch."""
+    constants.net = constants.BitcoinRegtest
+    yield
+    constants.net = constants.BitcoinMainnet
+
+
 # A valid serialized tx (1 input + 1 output, version 2). Its nLockTime is 0;
 # the tests override ``tx.locktime`` to simulate the frozen signed locktime.
 _VALID_TX_HEX = (
@@ -61,9 +70,9 @@ _VALID_TX_HEX = (
     "42146f11ef8414ae929feaafc388ac00000000"
 )
 
-# The frozen tx.locktime of karen7's valid item: delivery 2027-08-05, i.e. a
+# The frozen tx.locktime of karen7's valid item: delivery 2027-08-05 00:00 UTC,
-# will built 2026-08-05 with a "1y" recipe.
+# i.e. a will built 2026-08-05 with a "1y" recipe.
-_FROZEN = 1817438400
+_FROZEN = 1817424000
 
 
 def _make_will_item(heirs, tx_locktime, status_complete=False):
@@ -71,7 +80,7 @@ def _make_will_item(heirs, tx_locktime, status_complete=False):
     is forced to ``tx_locktime`` (the value frozen in the signed Bitcoin tx)."""
     d = {
         "tx": _VALID_TX_HEX,
-        "heirs": copy.deepcopy(heirs),
+        "heirs": copy_structure(heirs),
         "willexecutor": None,
         "status": "",
         "description": "",
@@ -80,7 +89,7 @@ def _make_will_item(heirs, tx_locktime, status_complete=False):
         "baltx_fees": 1,
     }
     item = WillItem(d, _id="willid_1")
-    item.STATUS = copy.deepcopy(WillItem.STATUS_DEFAULT)
+    item.STATUS = WillItem.copy_status_table(WillItem.STATUS_DEFAULT)
     item.tx.locktime = tx_locktime
     if status_complete:
         item.set_status("COMPLETE", True)
@@ -111,7 +120,7 @@ def test_unchanged_relative_recipe_signed_is_coherent():
     read as a postpone just because the clock has advanced past build day."""
     heirs = {"alice": ["addr_alice", 5000, "1y"]}
     outcome = _run_heir_check(
-        copy.deepcopy(heirs), copy.deepcopy(heirs), _FROZEN, status_complete=True
+        copy_structure(heirs), copy_structure(heirs), _FROZEN, status_complete=True
     )
     assert outcome.startswith("coherent"), outcome
 
@@ -119,7 +128,7 @@ def test_unchanged_relative_recipe_signed_is_coherent():
 def test_unchanged_relative_recipe_unsigned_is_coherent():
     heirs = {"alice": ["addr_alice", 5000, "1y"]}
     outcome = _run_heir_check(
-        copy.deepcopy(heirs), copy.deepcopy(heirs), _FROZEN, status_complete=False
+        copy_structure(heirs), copy_structure(heirs), _FROZEN, status_complete=False
     )
     assert outcome.startswith("coherent"), outcome
 
@@ -145,7 +154,7 @@ def test_relative_recipe_shortened_on_signed_is_rebuild():
 def test_unchanged_absolute_recipe_is_coherent():
     built = {"alice": ["addr_alice", 5000, str(_FROZEN)]}
     outcome = _run_heir_check(
-        copy.deepcopy(built), copy.deepcopy(built), _FROZEN, status_complete=True
+        copy_structure(built), copy_structure(built), _FROZEN, status_complete=True
     )
     assert outcome.startswith("coherent"), outcome
 
@@ -158,57 +167,57 @@ def test_absolute_postpone_on_signed_still_detected():
 
 
 # ------------------------------------------------------------------ #
-# karen7 wallet regression (real fixture)
+# karen7 regression (hermetic, no live wallet fixture)
 # ------------------------------------------------------------------ #
 
-
+# karen7's reported state, reproduced hermetically: heirs "1y", a signed item
-def _load_karen7():
+# frozen at delivery 2027-08-05 (built 2026-08-05), will_settings with a
-    path = os.path.join(os.path.dirname(__file__), "karen7")
+# relative "150d" delivery window and a "2y" promised locktime.
-    with open(path) as f:
+_WILL_SETTINGS = {"locktime": "2y", "threshold": "150d"}
-        return json.load(f)
 
 
 def test_karen7_frozen_delivery_not_expired():
     """ADVANCED date_to_check anchored to the frozen tx locktime: the check
     window opens BEFORE the delivery, so the will is never read as expired."""
-    data = _load_karen7()
+    heirs = {"alice": ["addr_alice", 5000, "1y"]}
-    will_settings = data["will_settings"]
+    item = _make_will_item(copy_structure(heirs), _FROZEN, status_complete=True)
-    valid_wid = "def15833cf94c5795c6275076bdadebd809175455f6eb4d5f8db304f816433b8"
+    will = {"willid_1": item}
-    wi = WillItem(data["will"][valid_wid], _id=valid_wid)
+    built_locktime = Will.get_min_locktime(will)
-    built_locktime = Will.get_min_locktime({valid_wid: wi})
+    assert built_locktime is not None
-    assert built_locktime == _FROZEN
+    assert built_locktime == int(item.tx.locktime)
 
     date_to_check = resolve_date_to_check(
-        False, will_settings, now=1_800_000_000.0, built_locktime=built_locktime
+        False, _WILL_SETTINGS, now=1_800_000_000.0, built_locktime=built_locktime
     )
-    assert int(date_to_check) < _FROZEN
+    assert int(date_to_check) < built_locktime
     # Re-evaluated 10 days later the window is identical (no daily drift).
     later = resolve_date_to_check(
-        False, will_settings, now=1_800_000_000.0 + 10 * 86400,
+        False, _WILL_SETTINGS, now=1_800_000_000.0 + 10 * 86400,
         built_locktime=built_locktime,
     )
     assert date_to_check == later
 
 
 def test_karen7_unchanged_heirs_are_coherent():
-    """The karen7 heirs (unchanged relative "1y") are coherent with the frozen
+    """Unchanged relative "1y" heirs are coherent with the frozen signed tx:
-    signed tx: the plugin must NOT ask to invalidate the will."""
+    the plugin must NOT ask to invalidate the will."""
-    data = _load_karen7()
+    heirs = {"alice": ["addr_alice", 5000, "1y"]}
-    valid_wid = "def15833cf94c5795c6275076bdadebd809175455f6eb4d5f8db304f816433b8"
+    # Use _FROZEN (a UTC-midnight value) so the check is compatible with
-    wi = WillItem(data["will"][valid_wid], _id=valid_wid)
+    # the UTC anchoring code.
+    frozen_locktime = _FROZEN
     date_to_check = resolve_date_to_check(
-        False, data["will_settings"],
+        False, _WILL_SETTINGS,
         now=1_800_000_000.0,
-        built_locktime=int(wi.tx.locktime),
+        built_locktime=frozen_locktime,
     )
     outcome = _run_heir_check(
-        data["will"][valid_wid]["heirs"],
+        copy_structure(heirs),
-        data["heirs"],
+        copy_structure(heirs),
-        int(wi.tx.locktime),
+        frozen_locktime,
         status_complete=True,
     )
     assert outcome.startswith("coherent"), outcome
-    assert int(date_to_check) < int(wi.tx.locktime)
+    assert int(date_to_check) < frozen_locktime
 
 
 # ------------------------------------------------------------------ #
@@ -216,6 +225,7 @@ def test_karen7_unchanged_heirs_are_coherent():
 # ------------------------------------------------------------------ #
 
 if __name__ == "__main__":
+    constants.net = constants.BitcoinRegtest
     for name in sorted(dir()):
         if name.startswith("test_"):
             globals()[name]()

tests/test_import_will_details.py

@@ -127,6 +127,11 @@ def test_sign_transactions_external_only():
         wallet=FakeWallet(),
         waiting_dialog=SimpleNamespace(update=lambda msg: None),
     )
+    # sign_transactions dispatches to self._prepare_and_sign_tx; bind the real
+    # implementation onto the fake so the external-sign run actually executes.
+    fake._prepare_and_sign_tx = MethodType(
+        window_mod.BalWindow._prepare_and_sign_tx, fake
+    )
 
     result = window_mod.BalWindow.sign_transactions(fake, None, will=imported)
 
@@ -166,6 +171,50 @@ def test_will_widget_explicit_will():
     assert w2.will is live
 
 
+# ------------------------------------------------------------------ #
+# WillWidget shows heir/willexecutor addresses and decodes OP_RETURN
+# ------------------------------------------------------------------ #
+
+def test_will_widget_shows_addresses_and_decodes_opreturn():
+    from PyQt6.QtWidgets import QLabel
+
+    from bal.core.will import WillItem
+    from bal.gui.qt.widgets import WillWidget
+
+    op_hex = "68656c6c6f"  # "hello" in hex
+    heirs = {
+        "bob": ["bc1qtestaddr", 1_000_000, 1000, 500_000],
+        "msg": [f"OP_RETURN:{op_hex}", 0, 1000, 0],
+    }
+    wi = WillItem(
+        _make_willitem_dict(
+            heirs=heirs,
+            willexecutor={
+                "url": "https://exec.example",
+                "address": "bc1qexecaddr",
+                "base_fee": 200_000,
+            },
+        )
+    )
+    wi._id = "w0"
+    fake_parent = SimpleNamespace(
+        decimal_point=8,
+        base_unit_name="BTC",
+        bal_window=SimpleNamespace(
+            willitems={},
+            bal_plugin=SimpleNamespace(
+                _hide_replaced=False, _hide_invalidated=False
+            ),
+            show_transaction=lambda *a, **k: None,
+        ),
+    )
+    w = WillWidget(parent=fake_parent, will={"w0": wi})
+    texts = [lbl.text() for lbl in w.findChildren(QLabel)]
+    assert any("bc1qtestaddr" in t for t in texts), texts
+    assert any("OP_RETURN: hello" in t for t in texts), texts
+    assert any("bc1qexecaddr" in t for t in texts), texts
+
+
 # ------------------------------------------------------------------ #
 # WillDetailDialog external-will mode
 # ------------------------------------------------------------------ #

tests/test_no_willexecutor_karen7.py

@@ -27,7 +27,6 @@ Run::
         python3 -m pytest tests/test_no_willexecutor_karen7.py -v -s
 """
 
-import copy
 import json
 import logging
 import os
@@ -49,6 +48,7 @@ from electrum.transaction import PartialTxInput, TxOutpoint
 from electrum.util import bfh
 
 from bal.core.heirs import Heirs
+from bal.core.util import copy_structure
 from bal.core.will import (
     NotCompleteWillException,
     NoWillExecutorNotPresent,
@@ -278,11 +278,11 @@ class FakeBalWindow:
                 tx["my_locktime"] = txs[txid].my_locktime
                 tx["heirsvalue"] = txs[txid].heirsvalue
                 tx["description"] = txs[txid].description
-                tx["willexecutor"] = copy.deepcopy(txs[txid].willexecutor)
+                tx["willexecutor"] = copy_structure(txs[txid].willexecutor)
                 tx["status"] = "New"
                 tx["baltx_fees"] = txs[txid].tx_fees
                 tx["time"] = creation_time
-                tx["heirs"] = copy.deepcopy(txs[txid].heirs)
+                tx["heirs"] = copy_structure(txs[txid].heirs)
                 tx["txchildren"] = []
                 will[txid] = WillItem(tx, _id=txid, wallet=self.wallet)
             self.update_will(will)
@@ -392,7 +392,7 @@ class TestNoWillexecutorKaren7:
         heirs_data = _KAREN7_DATA["heirs"]
         h = Heirs.__new__(Heirs)
         h.update(heirs_data)
-        assert len(h) == 4
+        assert len(h) == 6
 
         self.heirs_obj = h
         self.bal_plugin = _Karen7BalPlugin()

tests/test_rebuild_on_close_setting.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""Tests for the "Rebuild will on wallet close" (REBUILD_ON_CLOSE) setting.
+
+Covers:
+
+  * the persisted ``bal_rebuild_on_close`` configuration key exists and
+    defaults to ON (True), and can be turned off and read back;
+  * ``BalWindow.on_close()`` runs the "Build your will" wizard
+    (``BalBuildWillDialog.build_will_task()``) when the setting is ON;
+  * ``BalWindow.on_close()`` SKIPS the wizard when the setting is OFF, but
+    still calls ``save_willitems()`` so the last built state is persisted.
+
+The on_close tests drive the real ``BalWindow.on_close`` method with a
+light-weight fake controller and a recording stub for ``BalBuildWillDialog``,
+so no full wallet/GUI machinery is needed.
+
+Run:
+    source "$BAL_HOME/electrum/env/bin/activate"
+    QT_QPA_PLATFORM=offscreen python3 tests/test_rebuild_on_close_setting.py
+"""
+
+import os
+import sys
+import types
+
+os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import bal.gui.qt.window as window_mod  # noqa: E402
+from bal.core.plugin_base import BalConfig  # noqa: E402
+
+CONFIG_KEY = "bal_rebuild_on_close"
+
+
+# --------------------------------------------------------------------------- #
+# Mocks
+# --------------------------------------------------------------------------- #
+
+class FakeConfig:
+    """Minimal mock for Electrum's config object (key/value store)."""
+
+    def __init__(self):
+        self._store = {}
+
+    def get(self, key, default=None):
+        return self._store.get(key, default)
+
+    def set_key(self, key, value, save=True):
+        self._store[key] = value
+
+
+class FakeBuildWillDialog:
+    """Recording stub for BalBuildWillDialog, patched into window.py."""
+
+    instances = []
+
+    def __init__(self, bal_window):
+        self.bal_window = bal_window
+        FakeBuildWillDialog.instances.append(self)
+
+    def build_will_task(self):
+        self.bal_window._wizard_ran = True
+
+
+class _Tabs:
+    def update(self):
+        pass
+
+
+class _NoOp:
+    willexecutors_action = None
+    tabs = _Tabs()
+
+    def close(self):
+        pass
+
+    def toggle_tab(self, tab):
+        pass
+
+    def update(self):
+        pass
+
+    def removeAction(self, action):
+        pass
+
+
+def _make_fake_window(rebuild_on_close):
+    """Return a fake controller with the attributes on_close() touches."""
+    fake = types.SimpleNamespace()
+    fake.disable_plugin = False
+    fake.bal_plugin = types.SimpleNamespace(
+        REBUILD_ON_CLOSE=BalConfig(FakeConfig(), CONFIG_KEY, rebuild_on_close)
+    )
+    fake.willitems = {}
+    fake.will = {}
+    fake.saved = []
+    fake.save_willitems = lambda: fake.saved.append("save")
+    fake.heirs_tab = _NoOp()
+    fake.will_tab = _NoOp()
+    fake.tools_menu = _NoOp()
+    fake.window = _NoOp()
+    fake._menubar_initialized = True
+    return fake
+
+
+def _call_on_close(fake):
+    original = window_mod.BalBuildWillDialog
+    FakeBuildWillDialog.instances = []
+    try:
+        window_mod.BalBuildWillDialog = FakeBuildWillDialog
+        window_mod.BalWindow.on_close(fake)
+    finally:
+        window_mod.BalBuildWillDialog = original
+
+
+# --------------------------------------------------------------------------- #
+# Config key
+# --------------------------------------------------------------------------- #
+
+def test_rebuild_on_close_config_defaults_on():
+    """bal_rebuild_on_close must default to ON (True) when not yet stored."""
+    cfg = FakeConfig()
+    rebuild = BalConfig(cfg, CONFIG_KEY, True)
+    assert rebuild.get() is True
+
+
+def test_rebuild_on_close_config_can_be_disabled():
+    """Once turned off and persisted, bal_rebuild_on_close reads back False."""
+    cfg = FakeConfig()
+    rebuild = BalConfig(cfg, CONFIG_KEY, True)
+    rebuild.set(False)
+    assert rebuild.get() is False
+    # A fresh wrapper over the same config still sees the stored value.
+    assert BalConfig(cfg, CONFIG_KEY, True).get() is False
+
+
+# --------------------------------------------------------------------------- #
+# on_close() behaviour
+# --------------------------------------------------------------------------- #
+
+def test_on_close_runs_wizard_when_enabled():
+    """With REBUILD_ON_CLOSE ON, on_close() builds the will and saves it."""
+    fake = _make_fake_window(True)
+    _call_on_close(fake)
+    assert len(FakeBuildWillDialog.instances) == 1, "wizard must be opened"
+    assert fake._wizard_ran is True, "wizard build_will_task must run"
+    assert fake.saved == ["save"], "save_willitems must run"
+
+
+def test_on_close_skips_wizard_when_disabled():
+    """With REBUILD_ON_CLOSE OFF, on_close() skips the wizard but saves."""
+    fake = _make_fake_window(False)
+    _call_on_close(fake)
+    assert len(FakeBuildWillDialog.instances) == 0, "wizard must NOT be opened"
+    assert not hasattr(fake, "_wizard_ran"), "wizard must not run"
+    assert fake.saved == ["save"], "save_willitems must still run"
+
+
+if __name__ == "__main__":
+    test_rebuild_on_close_config_defaults_on()
+    test_rebuild_on_close_config_can_be_disabled()
+    test_on_close_runs_wizard_when_enabled()
+    test_on_close_skips_wizard_when_disabled()
+    print("OK: all tests passed")

tests/test_reproduce_none_type.py

@@ -7,7 +7,6 @@ but without requiring a full Qt event loop.
 """
 
 import contextlib
-import copy
 import json
 import os
 import sys
@@ -24,6 +23,7 @@ if os.path.isdir(ELECTRUM_DIR):
 
 from bal.core.heirs import Heirs
 from bal.core.plugin_base import BalPlugin, BalTimestamp
+from bal.core.util import copy_structure
 from bal.core.will import (
     NoHeirsException,
     NotCompleteWillException,
@@ -145,11 +145,11 @@ class FakeBalWindow:
                 tx["my_locktime"] = txs[txid].my_locktime
                 tx["heirsvalue"] = txs[txid].heirsvalue
                 tx["description"] = txs[txid].description
-                tx["willexecutor"] = copy.deepcopy(txs[txid].willexecutor)
+                tx["willexecutor"] = copy_structure(txs[txid].willexecutor)
                 tx["status"] = "New"
                 tx["baltx_fees"] = txs[txid].tx_fees
                 tx["time"] = creation_time
-                tx["heirs"] = copy.deepcopy(txs[txid].heirs)
+                tx["heirs"] = copy_structure(txs[txid].heirs)
                 tx["txchildren"] = []
                 will[txid] = WillItem(tx, _id=txid, wallet=self.wallet)
             Will.update_will(self.willitems, will)
@@ -170,7 +170,7 @@ def test_simulate_task_phase1():
     heirs_data = KAREN7_DATA["heirs"]
     h = Heirs.__new__(Heirs)
     h.update(heirs_data)
-    assert len(h) == 4
+    assert len(h) == 6
 
     # 2. Build UTXOs
     utxos = build_utxos(KAREN7_DATA)

tests/test_sync_locktime_built_txs.py

@@ -2,13 +2,17 @@
 Tests for ``BalBuildWillDialog._sync_locktime_to_built_txs``.
 
 This is the post-build sync that keeps the plugin's stored delivery date
-(WILL_SETTINGS["locktime"]) and check-alive threshold in lockstep with the
+(WILL_SETTINGS["locktime"]) in lockstep with the BUILT transactions' fixed
-BUILT transactions' fixed locktime.  The bug it fixes (reported by the owner):
+locktime when the core AUTOMATICALLY anticipates it (one day earlier than
+stored).
 
-    ADVANCED mode + RELATIVE locktime ("90d") / threshold ("30d") -> the plugin
+RELATIVE recipes ("90d" / "1y") are now PRESERVED: the daily-drift problem
-    asks to invalidate the will EVERY DAY.  The relative value is re-parsed
+that once forced freezing them to absolute timestamps is solved at the root by
-    against "now" on every check, so it drifts one day per day away from the
+anchoring every relative recipe against the built transactions
-    fixed tx locktime and the postpone check always sees a "postpone".
+(``Util.resolve_locktime_against_tx`` for the postpone detection,
+``resolve_date_to_check(..., built_locktime=...)`` for the reference
+timestamp).  Only a genuine automatic anticipation on an ABSOLUTE stored date
+moves the stored value.
 
 The method is exercised with a lightweight fake ``self`` (no Qt event loop, no
 Electrum wallet) by calling it as an unbound method.
@@ -24,7 +28,6 @@ from types import SimpleNamespace
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), os.pardir))
 
-from bal.core.plugin_base import BalTimestamp  # noqa: E402  (path insert above)
 from bal.gui.qt.dialogs import BalBuildWillDialog  # noqa: E402  (path insert above)
 
 # ------------------------------------------------------------------ #
@@ -68,34 +71,30 @@ def _call_sync(will_settings, tx_locktimes, recorded):
 # Tests
 # ------------------------------------------------------------------ #
 
-def test_relative_locktime_normalized_to_absolute():
+def test_relative_locktime_preserved():
-    """The reported bug: a relative stored locktime is frozen to the absolute
+    """A RELATIVE stored locktime ("90d"/"1y") is PRESERVED after a rebuild:
-    value of the built transaction, even when it parses to the same moment."""
+    it is anchored against the built transactions on every check, so it must
+    not be frozen to an absolute timestamp in WILL_SETTINGS."""
     tx_locktime = 1_800_000_000
     recorded = []
     fake = _call_sync(
         {"locktime": "90d", "threshold": "30d"}, [tx_locktime], recorded
     )
-    assert fake.bal_window.will_settings["locktime"] == tx_locktime
+    assert fake.bal_window.will_settings["locktime"] == "90d"
-    assert fake.bal_window.will_settings["locktime"] != "90d"
+    assert fake.bal_window.will_settings["threshold"] == "30d"
-    # A pure relative->absolute normalisation is NOT an anticipation: the sign
+    assert recorded == [], "a relative recipe must never be rewritten"
-    # prompt must not claim the date was anticipated.
     assert fake._date_was_anticipated is False
 
 
-def test_relative_threshold_frozen_to_absolute():
+def test_relative_threshold_preserved():
-    """A relative threshold ("N days BEFORE the delivery") is normalised to the
+    """Same for the relative "Check Alive" threshold: it stays relative."""
-    same absolute value the settings widget computes (real_threshold)."""
     tx_locktime = 1_800_000_000
     recorded = []
     fake = _call_sync(
         {"locktime": "90d", "threshold": "30d"}, [tx_locktime], recorded
     )
-    expected = int(
+    assert fake.bal_window.will_settings["threshold"] == "30d"
-        BalTimestamp("30d").to_date(tx_locktime, reverse=True).timestamp()
+    assert recorded == []
-    )
-    assert fake.bal_window.will_settings["threshold"] == expected
-    assert ("threshold", expected, True) in recorded
 
 
 def test_absolute_locktime_unchanged_on_equal():
@@ -113,8 +112,8 @@ def test_absolute_locktime_unchanged_on_equal():
 
 
 def test_anticipation_sets_flag_and_moves_earlier():
-    """A real anticipation (built locktime earlier than the stored absolute
+    """A real automatic anticipation of an ABSOLUTE stored date (built earlier
-    one) still moves the date earlier and flags the sign prompt."""
+    than stored) still moves the date earlier and flags the sign prompt."""
     tx_locktime = 1_700_000_000
     recorded = []
     fake = _call_sync(
@@ -129,7 +128,7 @@ def test_anticipation_sets_flag_and_moves_earlier():
 def test_stored_earlier_than_built_never_moved_later():
     """A stored absolute date that is already EARLIER than the built txs (the
     user moved the delivery later) is never pulled back up on rebuild: only
-    anticipation (built < stored) and relative normalisation move the value."""
+    anticipation (built < stored) moves the value."""
     stored = 1_800_000_000
     recorded = []
     fake = _call_sync(
@@ -142,39 +141,39 @@ def test_stored_earlier_than_built_never_moved_later():
 
 
 def test_multiple_txs_uses_minimum_locktime():
-    """When several transactions carry different locktimes, the minimum is used
+    """When several ABSOLUTE transactions carry different locktimes, the minimum
-    (owner-confirmed behaviour for the delivery date shown in the UI)."""
+    is used for a genuine automatic anticipation (owner-confirmed behaviour for
+    the delivery date shown in the UI)."""
     min_locktime = 1_750_000_000
     recorded = []
     fake = _call_sync(
-        {"locktime": "90d", "threshold": "30d"},
+        {"locktime": 1_800_000_000, "threshold": 1_600_000_000},
         [min_locktime, min_locktime + 86_400],
         recorded,
     )
     assert fake.bal_window.will_settings["locktime"] == min_locktime
 
 
-def test_relative_locktime_stops_daily_postpone():
+def test_relative_locktime_stays_coherent_via_anchor():
-    """End-to-end guard for the reported bug: after the sync, re-parsing the
+    """Daily-drift guard: an UNCHANGED relative recipe is resolved against the
-    stored (now absolute) locktime on later days always equals the built
+    tx build moment (``Util.resolve_locktime_against_tx``), so even WITHOUT
-    tx locktime, so the postpone check never fires again."""
+    being frozen to an absolute value it still reads as COHERENT (== tx
-    from datetime import datetime, timedelta
+    locktime) on later days - the postpone check never fires again."""
+    from datetime import datetime, timedelta, timezone
 
     from bal.core.util import Util
 
-    tx_locktime = 1_800_000_000
+    # resolve_locktime_against_tx normalises to UTC midnight before anchoring,
-    recorded = []
+    # so use a midnight-UTC frozen tx locktime (the timestamp the engine itself
-    fake = _call_sync(
+    # stores after building).
-        {"locktime": "90d", "threshold": "30d"}, [tx_locktime], recorded
+    tx_locktime = int(datetime(2027, 1, 15, tzinfo=timezone.utc).timestamp())
-    )
+    built = "90d"  # recipe frozen at build time
-    stored = fake.bal_window.will_settings["locktime"]
+    current = "90d"  # unchanged recipe today
     for _day in range(0, 7):
-        # Simulate the check on later days: parse the STORED value (which is
+        resolved = Util.resolve_locktime_against_tx(current, built, tx_locktime)
-        # now the absolute tx locktime) and compare with the fixed tx locktime.
+        assert resolved == tx_locktime  # no POSTPONE / drift
-        new_locktime = Util.parse_locktime_string(stored)
+    # Sanity: a naive forward-from-now re-parse would have drifted past it
-        assert new_locktime == tx_locktime
+    # (the bug the anchor fixes).
-        assert new_locktime <= tx_locktime  # no POSTPONE / drift
-    # Sanity: a RELATIVE value would have drifted past it (the bug).
     drifted = int(
         (
             datetime.fromtimestamp(tx_locktime) + timedelta(days=1)