wallet: a wallet imported with --birth-height still scans from the tip, so its history is lost

[defenwycke]

Found by FLOW 14 of scripts/smoke-test-wallet-e2e.sh on regtest, against work/post-merge
(f48fb6948, binaries built from that tree). Not a test artefact — the daemon's own log says
what went wrong.

Measured

The wallet spent the whole run building on-chain history, then was recovered two ways.

path	balance	history
wallet export / wallet restore (keystore file)	recovered	(not asserted)
wallet import --birth-height 101 (words)	2,896,345 sats — exact	1 of 13 entries

The history count was polled for 180 s (60 × 3 s) and never moved past 1.

before recovery: balance=2896345 history_entries=13
  PASS: words + birth height recover the balance (2896345 sats)
FAIL: the recovered wallet rebuilt 1 of 13 history entries from birth height 101
      — the coins are found but what they did is lost

The daemon says why

From the same run's wraithd.log — the original wallet, and then the two restored ones:

02:05:32Z INFO wraithd::server: block scanner rebuilding history from the wallet's birth height
                                birth_height=101 tip=108 behind=7
02:08:14Z INFO wraithd::server: block scanner started watching from the tip — this wallet has no
                                recorded birth height, so nothing before now will appear in its
                                history height=1133
02:08:37Z INFO wraithd::server: block scanner started watching from the tip — ... height=1133

So the machinery works (line 1, the original wallet); the imported wallet reaches the scanner with
no birth height, takes the birth.unwrap_or(tip) branch in block_scan and starts at 1133.
Everything the seed did below that height is outside its history for good.

What is already ruled out

• The CLI does forward the flag — WalletCommand::Import { name, birth_height } builds
  Request::WalletImport { .., birth_height } (apps/wraith-wallet/cli/src/main.rs:883).
• The handler does record it — record_birth_height(state, &name, birth_height)
  (apps/wraith-wallet/daemon/src/main.rs:4938), with the deliberate "nothing if they said
  nothing" comment, so it is not defaulting to the tip.
• The write did not fail: record_birth_height warns on error and there are 0 occurrences of
  could not record the wallet's birth height in the run's log.

So the value is written and then not seen. Root cause NOT established. The two things to check
first are (a) whether wallet_data_dir(state, wallet) at write time and wallet_meta_for(state)
at scan time resolve to the same directory for a freshly imported wallet, and (b) ordering —
whether a scan bookmark is already set for that wallet by the time the meta lands, since the birth
height is only consulted on the bookmark.point() == None branch.

Why it matters

This is the "device is lost" path. The money is reachable — balance and UTXO scan the whole UTXO
set — but a restored wallet shows one line of history where there were thirteen, and --birth-height
is the documented way to ask for the rest. The GUI restore flow rides on the same request.

Reproduce

WRAITH_BIN_DIR=<target>/debug ./scripts/smoke-test-wallet-e2e.sh

Stops at FLOW 14. (FLOW 15 and 16 are therefore also unexercised on that branch.)

[defenwycke]

Second run: FLOW 14 passed. This is intermittent, not deterministic.

Same script, same binaries (plus a logging change described below), regtest, ~3.5 hours later:

before recovery: balance=2896345 history_entries=13
  PASS: keystore backup restores the same wallet
  PASS: words + birth height recover the balance (2896345 sats)
  PASS: the whole history rebuilt from birth height 101 (13 of 13 entries)

And the daemon log shows the scanner doing exactly what it should for the restored wallet:

05:53:45Z INFO block scanner started watching from the tip — this wallet has no recorded
                birth height ... height=1133          <- restored-file, correct, it has none
05:54:08Z INFO block scanner rebuilding history from the wallet's birth height
                birth_height=101 tip=1133 behind=1032 <- restored-words, CORRECT this time

Compare the failing run, where the second line read no recorded birth height instead. Same 23-second gap between the two scans in both runs, so it is not a slow write being outpaced by a slow tick in any obvious way.

What this rules out

The write path is sound. A new test in the daemon's own harness — an_imported_birth_height_reaches_the_wallet_metadata in apps/wraith-wallet/daemon/tests/wallet_lifecycle.rs — imports with birth_height: Some(101) and asserts the value is in wallets/<name>/wallet-meta.json. It passes. So wallet import --birth-height does persist the value, and the earlier failure is on the read side or in the ordering between the import and the scanner's first pass for that wallet.

⚠ Do not treat this as fixed. One green run after one red run is a flake, not a repair, and the ordering hypothesis in the original report is still unproven either way. The failure mode is a silent one — a restored wallet that shows a balance and almost no history — so it will not announce itself in production.

Related change worth having regardless

The scanner could not previously say it had stopped: a failing tick logged at debug, so at default level a scanner that was broken and a scanner with nothing to do looked identical, while balance and the UTXO list kept working from scantxoutset and hid it further. It now reports a stop reason once, and again whenever the reason changes — warn for a fault, info for an ordinary idle state (no unlocked wallet, no reachable node RPC), plus a line when it starts working again. That is what made the second run legible at all.