feat(mcp): headless masternode/evonode credit withdrawals (det-cli)

[lklimek]

Why this PR exists

• Problem: There is no headless (det-cli / MCP) path to operate a masternode/evonode identity's Platform credits. Operators must use the desktop GUI to load a node identity and withdraw its credits.
• What breaks without it: A node operator running headless — a server, CI, or scripted environment with no GUI — cannot (1) load a masternode/evonode identity from its ProTxHash + owner/voting/payout keys, nor (2) withdraw the node's Platform credits. The only existing withdrawal tooling assumes a User identity and the GUI.
• Blocking relationship: Based on PR feat: platform-wallet backend rewrite (spec + implementation) #860 (docs/platform-wallet-migration-design); merged up to its tip 0d301d01 (incl. overlay feat(overlay): blocking progress overlay + SPV-sync hard-block #863), so the diff here is masternode-only.

What was done

Two new MCP tools — no backend change; both dispatch existing IdentityTasks:

• identity_masternode_load — load a masternode/evonode identity by ProTxHash + owner/voting/payout private keys (WIF or hex), persisted locally. Non-destructive. Reports keys loaded, available withdrawal modes, and the registered payout address.
• identity_masternode_credits_withdraw — withdraw the node identity's Platform credits. key_mode=owner forces the destination to the registered payout address (dispatches to_address = None so Platform consensus routes the payout — matches the GUI/locked design); key_mode=transfer sends to any Core address (Platform/bech32m rejected). Destructive; SPV-gated.

Thin tool layer over IdentityTask::LoadIdentity / WithdrawFromIdentity; stateless parsing in model/masternode_input.rs. Private keys wrapped in Secret with a hand-written redacting Debug — never reach logs or the MCP error payload.

Headless lifecycle fixes (found + validated during live testing)

Live headless runs surfaced several standalone-det-cli lifecycle bugs (general to the headless path, fixed here so the feature is usable end-to-end):

• Backend-wiring ordering (acb06b14): withdraw resolved the identity (get_identity_by_id → wallet_backend()) before ensure_spv_synced built the backend → cold-process WalletBackendNotYetWired ("wallet is still starting up", -32603). Moved the gate ahead of the lookup. Live-validated: owner-mode withdrawal completes to the payout address.
• Cold-start migration race (7b5353f4): ensure_spv_synced waits for the storage migration (ensure_storage_ready, new StorageNotReady = -32005) before dispatch.
• Graceful backend stop on exit (ec983601): standalone/headless exit awaits WalletBackend::shutdown() (stops SPV, drains the persister) before terminating.
• Exit-time Tokio panic — deterministic hard-exit (98e96380 → superseded by 74cf43af): the sync coordinators (identity/platform-address/shielded) run on detached OS threads whose tokio::select!{ sleep | cancel } loop can poll the timer wheel against a shutting-down runtime and panic. A 100 ms grace (98e96380) was tried and failed live (it races the teardown). The deterministic fix (74cf43af): the one-shot CLI flushes stdout/stderr and std::process::exit() after the result — the runtime is never gracefully dropped while coordinator threads are alive, so there's no teardown for them to race. Safe because the withdrawal's state transition is already on-chain, SQLite is transaction-atomic, and the storage-registry lock is process-global (reclaimed on exit).

Testing

• Unit + tool registration/schema tests; masternode validators, key-redaction, owner/transfer pre-flight.
• Backend-e2e (#[ignore], E2E_MN_*) compiles; network-gated cases run manually against testnet.
• QA at the tip — PASS, zero regressions: cargo test --lib 971/971, --test kittest 146/146, doctests, e2e/backend-e2e compile, clippy -D warnings clean, fmt clean.
• Live: owner-mode withdraw succeeds end-to-end (det-cli, testnet). The hard-exit's confirmation (clean exit, no coordinator panic) is a manual headless retest — can't be unit-reproduced.

Breaking changes

None.

Checklist

• No backend / TaskError change for the tools (lifecycle fixes touch the MCP/CLI seam + a new StorageNotReady MCP error)
• No real secrets in the diff (verified)
• QA fix-pass landed + re-verified post-merge
• Merged up to date with feat: platform-wallet backend rewrite (spec + implementation) #860 tip (incl. overlay feat(overlay): blocking progress overlay + SPV-sync hard-block #863)
• Headless lifecycle fixes (ordering, migration race, graceful stop, deterministic hard-exit) — QA-green; ordering + withdraw live-validated
• Manual headless retest confirming clean exit (code 0, no coordinator panic)

Follow-ups (tracked, not in this PR)

• Security (codebase-wide audit): encrypt directly-loaded identity keys at rest (PrivateKeyData::Clear → SecretStore/AES-GCM at the DetKv seam, HIGH); SecretStore vault opened with empty passphrase (MED); ClosedSingleKey derives Debug over raw key bytes (MED); det-cli keys via argv — implement stdin/env input (MED); .env plaintext creds (LOW); non-Zeroizing no-password key material (LOW).
• Upstream: quiesce() should join the coordinator JoinHandle (then DET could keep the graceful teardown instead of hard-exit).
• ensure_spv_synced swallows backend-wiring errors → misleading SpvSyncFailed timeout.
• Credit-withdrawal fee estimate over-shoots actual (~2×).

_{🤖 Co-authored by Claudius the Magnificent AI Agent}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (2)

• master
• v1.0-dev

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 8b91955d-9ab1-4f7d-8674-1adc231bf25e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/masternode-cli-withdraw

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[thepastaclaw]

✅ Review complete (commit a88a5b3)

[thepastaclaw]

Code Review

Owner-mode withdraw dispatches Some(payout_address) instead of None, diverging from the locked design and the e2e test's assumption — confirmed blocking. The new transfer-mode path also newly exposes a pre-existing non-ASCII panic in is_platform_address_string through the MCP surface. Remaining items are test-coverage and Rust-quality refinements.

🔴 2 blocking | 🟡 4 suggestion(s) | 💬 1 nitpick(s)

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `src/mcp/tools/identity.rs`:
- [BLOCKING] src/mcp/tools/identity.rs:978-1013: Owner-mode withdraw dispatches Some(payout_address); spec and e2e expect None
  The owner-mode arm at lines 979–1000 unconditionally wraps the resolved payout address in `Some(...)`, so `IdentityTask::WithdrawFromIdentity` is dispatched with `Some(payout_address)`. The locked design (`docs/ai-design/2026-06-18-masternode-cli-withdraw/03-dev-plan.md:21`) and the e2e test (`tests/backend-e2e/identity_masternode_withdraw.rs:296-302`, TC-MN-050) both require owner mode to dispatch `to_address = None` so Platform consensus authoritatively routes the payout to the registered address — the resolved payout address should only be echoed in the output. Because the test hand-constructs the task with `None`, the divergence is silently uncaught. The owner arm should resolve the payout address only for the output echo and pass `None` to the dispatched task; the transfer arm continues to pass `Some(checked)`. After this fix, also reconsider the trailing `unwrap_or_default()` on `dispatched_address` (line 1034) which becomes a real `None` branch in owner mode — replace it with a branch-specific value so the caller always learns where the funds went.
- [SUGGESTION] src/mcp/tools/identity.rs:739-749: Wrap private keys in Secret before the SPV await
  Cheap validation runs at lines 732–737, then the tool awaits `ensure_spv_synced` before moving `owner_private_key`, `voting_private_key`, and `payout_private_key` into `Secret`. If the SPV wait is long or times out, those key strings sit in the async state machine as ordinary `String`s — not mlocked, not zeroized on drop. The rest of the crate moves sensitive values into `Secret`/`Zeroizing` at the boundary, before any await. Wrap the three key params into `Secret::new` immediately after key-presence validation; the validation ordering is preserved and the plaintext lifetime is bounded.
- [SUGGESTION] src/mcp/tools/identity.rs:732-741: Validate pro_tx_hash before the SPV wait
  The load tool already validates network, node type, and key-presence before `ensure_spv_synced`, but skips `pro_tx_hash`. A malformed ProTxHash therefore waits on SPV and, if SPV is unavailable, returns an SPV error instead of an input error. `masternode_input::decode_identity_id` is already available and cheap. Calling it before `ensure_spv_synced` keeps the cheap-validation-before-SPV pattern consistent with the other parameters and lets the load tool reuse the decoded `Identifier` in `IdentityInputToLoad` (the backend currently re-parses the string).
- [SUGGESTION] src/mcp/tools/identity.rs:766-781: KeyMode vocabulary duplicated between Tool A output and Tool B input
  The `available_withdrawal_keys` output writes literal `"owner"` / `"transfer"` strings, and `parse_key_mode` (`src/model/masternode_input.rs:55`) parses the same vocabulary — but each side hand-writes its own literals. A typo on either side becomes silent contract drift between Tool A's output and Tool B's input. Both pieces live in this PR, so adding a small `KeyMode::as_str()` (or `Display`) in `model/masternode_input.rs` and using it on both sides removes the duplication without adding any abstraction overhead.

In `src/model/address.rs`:
- [BLOCKING] src/model/address.rs:14-24: is_platform_address_string panics on non-ASCII input — now reachable from the new MCP tool
  `is_platform_address_string` slices `s[..hrp.len()]` by byte offset after only a length check. A non-ASCII string whose first code point straddles the HRP boundary (4 for `dash`, 5 for `tdash`) panics on the string slice. The function pre-dates this PR, but the new `parse_transfer_core_address` in `src/mcp/tools/identity.rs:876` feeds it user-controlled `to_address` from a JSON MCP request after only `trim()`, which does not normalize non-ASCII. A single bad request to `identity_masternode_credits_withdraw` can panic the in-process MCP server. Comparing on `s.as_bytes()` (e.g. `s.as_bytes().get(..hrp.len()).is_some_and(|h| h.eq_ignore_ascii_case(hrp.as_bytes())) && s.as_bytes().get(hrp.len()) == Some(&b'1')`) makes the check non-panicking. Add a regression test for non-ASCII input at the same time.

In `tests/backend-e2e/identity_masternode_withdraw.rs`:
- [SUGGESTION] tests/backend-e2e/identity_masternode_withdraw.rs:264-314: TC-MN-050/051 bypass the tool — owner-mode dispatch is never exercised
  `test_mn050_owner_withdraw_to_payout` and the companion TC-MN-051 build `IdentityTask::WithdrawFromIdentity` directly rather than calling `IdentityMasternodeCreditsWithdraw::invoke`. The tool's owner/transfer destination resolution, purpose→KeyID mapping, `payout_address` echo, owner+address contradiction guard, and SPV gate are therefore never exercised end-to-end on testnet — exactly how the blocking owner-mode mismatch went undetected. Drive these tests through the tool's `invoke()` so the production code path is what the suite verifies. The test comment on line 296 ("OWNER mode dispatches to_address = None") then becomes an actual assertion on the tool's behavior rather than a description of the hand-built task.

Note: this review is pinned to dispatcher-claimed commit 6d823786; the PR branch had already advanced to b9cb11bb before posting, so findings are posted body-only rather than inline-mapped against the newer live diff.

[thepastaclaw]

Code Review

Verifier pass against b9cb11b. The prior blocking owner-mode dispatch bug (QA-001) is RESOLVED via the new pure resolve_withdrawal_plan (owner -> dispatch_address: None) wired in at line 1066, with new unit-test coverage. One prior blocking finding still applies: is_platform_address_string byte-slices a &str and panics on non-ASCII input, and this path is now reachable from the new identity_masternode_credits_withdraw tool BEFORE the SPV gate. Five lower-severity carried-forward quality items (Secret-wrap timing, pre-SPV ProTxHash validation, duplicate withdrawal-mode labels, KeyMode vocabulary duplication, and e2e tests bypassing invoke()) are unchanged at HEAD. No new latest-delta defects beyond these carried-forward items.

🔴 1 blocking | 🟡 4 suggestion(s) | 💬 1 nitpick(s)

1 additional finding(s) omitted (not in diff).

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `src/model/address.rs`:
- [BLOCKING] src/model/address.rs:14-24: is_platform_address_string panics on non-ASCII input; reachable from the new withdraw tool
  STILL VALID at b9cb11bb. The helper byte-slices `s[..hrp.len()]` after only a `s.len() > hrp.len()` length check — if `hrp.len()` (4 for `dash`, 5 for `tdash`) falls inside a multi-byte UTF-8 code point, the slice panics. The new `identity_masternode_credits_withdraw` tool feeds user-controlled `to_address` straight through `parse_transfer_core_address` (src/mcp/tools/identity.rs:888), which is called by `resolve_withdrawal_plan` at line 1057 — BEFORE the SPV gate at line 1062. A single MCP request with `key_mode=transfer` and a non-ASCII `to_address` whose first character is multi-byte (e.g. `日本人ABC`, 9 bytes with char boundaries at 0/3/6/9) panics the in-process MCP server instead of returning `InvalidParam`. The fix compares on bytes (the function is ASCII-only by design). Add a regression test for non-ASCII input — the new withdraw tests cover only ASCII.

In `src/mcp/tools/identity.rs`:
- [SUGGESTION] src/mcp/tools/identity.rs:743-768: Wrap masternode private keys in Secret before the SPV await
  STILL VALID. Cheap validation runs at lines 746-752, then `ensure_spv_synced(&ctx).await` runs at line 756 with `param.{owner,voting,payout}_private_key` still held as ordinary `String`s. Only at lines 762-764 are they moved into `Secret::new(...)`. If the SPV gate waits a long time or times out (up to the 10-minute cap), the plaintext key material sits in the async state machine without zeroize/mlock protection. The rest of the crate moves sensitive values into `Secret`/`Zeroizing` at the input boundary. Wrap the three keys into `Secret::new` immediately after `require_at_least_one_signing_key` so plaintext lifetime is bounded; validation ordering is preserved.
- [SUGGESTION] src/mcp/tools/identity.rs:743-759: Validate pro_tx_hash before the SPV wait
  STILL VALID. The load tool validates network presence/match, node type, and the at-least-one-signing-key rule before `ensure_spv_synced`, but does not validate `pro_tx_hash` — line 759 forwards the raw `String` into `IdentityInputToLoad.identity_id_input` for the backend task to re-parse after SPV. `masternode_input::decode_identity_id` is a stateless cheap check; calling it before the SPV gate keeps the cheap-validation-before-network pattern consistent and lets a malformed ProTxHash fail as `InvalidParam` rather than as an SPV error when the chain is unavailable. The decoded `Identifier` could then be reused instead of having the backend re-parse the string.
- [SUGGESTION] src/mcp/tools/identity.rs:781-805: KeyMode vocabulary duplicated between Tool A output and Tool B input/output
  STILL VALID. The load tool's `available_withdrawal_keys` output hand-writes literal `"owner"` / `"transfer"` strings at lines 788 and 792; the withdraw tool's `key_mode` echo writes the same literals again at 1083-1084; `parse_key_mode` in src/model/masternode_input.rs:55 parses the same vocabulary. A typo on either side becomes silent contract drift between Tool A's advertised modes and Tool B's accepted input. All three call sites live in this PR — adding a small `KeyMode::as_str()` (or `Display`) in `model/masternode_input.rs` and using it on both sides removes the duplication without adding abstraction overhead.

In `tests/backend-e2e/identity_masternode_withdraw.rs`:
- [SUGGESTION] tests/backend-e2e/identity_masternode_withdraw.rs:264-382: E2E withdrawal tests still hand-build IdentityTask::WithdrawFromIdentity instead of driving invoke()
  PARTIALLY MITIGATED, STILL VALID. The latest delta adds unit tests against the new pure `resolve_withdrawal_plan` resolver, which is the regression guard for the QA-001 owner-mode dispatch bug. But `git grep -n 'IdentityMasternodeCreditsWithdraw::invoke\|IdentityMasternodeLoad::invoke' tests/` returns nothing: TC-MN-050 (lines 297-302) and TC-MN-051 (lines 365-370) still construct `IdentityTask::WithdrawFromIdentity` directly rather than calling `IdentityMasternodeCreditsWithdraw::invoke`. As a result the SPV gate ordering, network echo, owner+address contradiction check, identity DB lookup, and `IdentityMasternodeWithdrawOutput::to_address` echo are not exercised against a real chain — only the pure resolver is. Drive at least TC-MN-050/051 through `IdentityMasternodeCreditsWithdraw::invoke` so the production code path is what the e2e suite verifies on testnet.

[thepastaclaw]

Code Review

Carried-forward + incremental review at acb06b1. The non-ASCII panic in is_platform_address_string remains the sole blocking issue — reproduced locally: slicing s[..hrp.len()] panics on UTF-8 boundary inputs and is still reachable through the new MCP withdraw tool's transfer-mode path. The new lifecycle delta (graceful wallet-backend shutdown, storage-migration wait, withdraw-tool reordering) is mostly sound, but the shutdown is incomplete on two paths (stdio ? error short-circuits, and headless after network_switch) and the storage-migration wait observes a migration state that is never set in standalone MCP. Five prior quality/test findings still apply unchanged; one (pre-SPV ID validation) was partially fixed for the withdraw tool but not for the load tool.

🔴 1 blocking | 🟡 4 suggestion(s)

1 additional finding(s) omitted (not in diff).

4 carried-forward finding(s) already raised on this PR; not re-posting as new inline comments.

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `src/model/address.rs`:
- [BLOCKING] src/model/address.rs:14-24: is_platform_address_string panics on non-ASCII input; reachable from the new MCP withdraw tool
  Line 17 still slices `s[..hrp.len()]` against a `&str`. Rust panics if the byte offset falls inside a multi-byte UTF-8 code point. With `hrp.len() == 4` (`dash`) or `5` (`tdash`), any input whose first character is a 3-byte sequence (e.g. `日本ABC`, char boundaries 0/3/6/9) trips the slice at byte 4 — verified locally: `&"日本ABC"[..4]` panics with `byte index 4 is not a char boundary`. The new `identity_masternode_credits_withdraw` tool feeds user-controlled `to_address` through `parse_transfer_core_address` (src/mcp/tools/identity.rs:1066, inside `resolve_withdrawal_plan`) — on a synced standalone process, one MCP request with `key_mode=transfer` and a non-ASCII `to_address` panics the in-process MCP server instead of returning `InvalidParam`. Switch to byte comparison (HRPs are ASCII by design) and add a non-ASCII regression test.

In `src/bin/det_cli/headless.rs`:
- [SUGGESTION] src/bin/det_cli/headless.rs:48-56: Headless shutdown only stops the current backend after a network_switch
  The headless exit path shuts down only `swappable.load_full()`'s currently active context. `BackendTask::SwitchNetwork` (src/backend_task/mod.rs:572-628) builds a fresh `AppContext` for the new network and wires its backend, but never calls `stop_spv()` on the old context. After a session that switches networks, the previous network's `WalletBackend` (run loop + periodic coordinators) is still alive and is then dropped during runtime teardown — exactly the timer-registration panic class this delta is meant to prevent. The stdio path has the same shape via `DashMcpService::shutdown_wallet_backend`. Track every context wired during the session (or shut down the outgoing backend at the `swap_context` callsite in src/mcp/tools/network.rs:250) so all backends are quiesced before runtime drop.

In `src/mcp/mod.rs`:
- [SUGGESTION] src/mcp/mod.rs:29-44: start_stdio skips shutdown_wallet_backend() on the `?` error paths
  Both `service.serve(...).await?` at :36 and `server.waiting().await?` at :37 short-circuit with `?` before the shutdown at :42. If `waiting()` errors after a tool has already wired the wallet backend (e.g. mid-session transport hiccup), the runtime drops the backend uncleanly — the same panic class the commit was meant to eliminate. The 5-second `runtime.shutdown_timeout(...)` backstop in `src/bin/det_cli/connect.rs:36` only bounds the wait, it doesn't quiesce the coordinators. Capture `let result = server.waiting().await;` (no `?`), call `service_for_shutdown.shutdown_wallet_backend().await` unconditionally, then return `result` — mirroring the layout already used in `src/bin/det_cli/headless.rs:30-58` where shutdown runs regardless of the server result.

In `src/mcp/resolve.rs`:
- [SUGGESTION] src/mcp/resolve.rs:130-161: ensure_storage_ready waits for a migration that standalone MCP never starts
  `ensure_storage_ready` only blocks when `ctx.migration_status().state().is_running()`. In standalone/headless MCP, `init_app_context` (src/mcp/server.rs:232) does not dispatch any migration task, and `MigrationTask::FinishUnwire` is only ever dispatched from the GUI cold-start path (`AppState::dispatch_cold_start_migration` at src/app.rs:1121,1881) or the shielded-tab retry button. That means det-cli/headless always sees `MigrationState::Idle`, the new wait short-circuits, and the underlying `run_backend_task` gate (`is_wallet_touching` short-circuits only when migration is *Running*) also passes — so wallet-touching tools may run against not-yet-migrated sidecars on a cold standalone process. Either dispatch the migration from the headless/CLI context path before serving tools, or kick it off inside `ensure_spv_synced` before observing its state.

In `src/mcp/tools/identity.rs`:
- [SUGGESTION] src/mcp/tools/identity.rs:781-1088: KeyMode vocabulary duplicated across load output, withdraw echo, and parser
  `available_withdrawal_keys` writes literal `"owner"` / `"transfer"` at :788 and :792; the withdraw tool repeats the same literals at :1087-1088; `parse_key_mode` (src/model/masternode_input.rs:55) parses the same vocabulary from raw strings. All three sites live in this PR, so a typo on any side becomes silent contract drift between Tool A's advertised modes and Tool B's accepted input. A small `KeyMode::as_str()` (or `Display`) in `model/masternode_input.rs` used at every site removes the duplication with no abstraction overhead.

[thepastaclaw]

Code Review

Incremental review at 98e9638. The latest delta (acb06b1..98e9638) adds a documented 100 ms post-shutdown grace sleep in DashMcpService::shutdown_wallet_backend (stdio path) plus block-comment documentation. All 9 prior findings from the acb06b1 review remain valid at HEAD: the non-ASCII slice panic in is_platform_address_string is reachable from the new MCP withdraw tool's parse_transfer_core_address before the SPV gate; Secret-wrap timing, pre-SPV ProTxHash validation in the load tool, KeyMode vocabulary duplication, available_withdrawal_keys duplicates, ensure_storage_ready/migration mismatch, start_stdio error-path skip, network-switch lifecycle leak, and the e2e bypass of invoke() are all unchanged. The new delta also exposes a related gap: the 100 ms coordinator-thread grace lives only in the stdio shutdown helper — the headless HTTP path in src/bin/det_cli/headless.rs:54-56 calls backend.shutdown().await directly without the same grace.

🔴 1 blocking | 🟡 1 suggestion(s)

1 additional finding(s) omitted (not in diff).

8 carried-forward finding(s) already raised on this PR; not re-posting as new inline comments.

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `src/model/address.rs`:
- [BLOCKING] src/model/address.rs:14-24: is_platform_address_string panics on non-ASCII input; reachable from the new MCP withdraw tool
  CARRIED FORWARD from prior reviews. Line 17 slices `s[..hrp.len()]` against a `&str` after only a `s.len() > hrp.len()` length check. Rust panics if the byte offset falls inside a multi-byte UTF-8 code point. With `PLATFORM_HRP_MAINNET="dash"` (4 bytes) or `PLATFORM_HRP_TESTNET="tdash"` (5 bytes), any input whose first character is a 3-byte UTF-8 sequence (e.g. `日本ABC` — char boundaries 0/3/6/9) trips the slice at byte 4 with `byte index 4 is not a char boundary`. The new `identity_masternode_credits_withdraw` tool feeds user-controlled `to_address` through `parse_transfer_core_address` (src/mcp/tools/identity.rs:888), called from `resolve_withdrawal_plan` at line 974 AFTER the SPV gate but before any address parsing — so a single MCP request with `key_mode="transfer"` and a non-ASCII `to_address` panics the in-process MCP server instead of returning `InvalidParam`. The HRPs are ASCII by design; switch to byte comparison and add a non-ASCII regression test.

In `src/bin/det_cli/headless.rs`:
- [SUGGESTION] src/bin/det_cli/headless.rs:53-56: Headless HTTP shutdown skips the new coordinator-grace window
  NEW IN LATEST DELTA. Commit 98e96380 adds a 100 ms post-`backend.shutdown()` sleep in `DashMcpService::shutdown_wallet_backend` (src/mcp/server.rs:179-190), explicitly documenting that `backend.shutdown()` cancels coordinators but does NOT join their dedicated OS threads — they may still reach the outer `tokio::select!` and call `tokio::time::sleep(interval)` as the runtime begins shutdown, panicking with `A Tokio 1.x context was found, but it is being shutdown.` The headless HTTP exit path here does NOT use that helper: it calls `backend.shutdown().await` directly at line 55, then exits the `block_on` block and enters `runtime.shutdown_timeout(Duration::from_secs(5))` at line 63. This is the primary `det-cli --headless` path the PR adds for operators, so the exit-panic mitigation is incomplete in the path that needs it most. Either share the grace via a helper, or call the existing `service.shutdown_wallet_backend()` from here.

[thepastaclaw]

Code Review

Cumulative verification at 74cf43a. The latest delta replaces the 100ms post-shutdown grace with std::process::exit in run_stdio_server, run_headless, and the one-shot CLI path — this deterministically eliminates the coordinator-thread/timer-wheel panic class, fully resolving prior finding #2. Nine prior findings remain STILL VALID and are carried forward; one new low-confidence finding (one-shot CLI hard-exits without draining the in-process backend, codex-rust-quality only) is added. The lone blocking issue is the non-ASCII slice panic in is_platform_address_string, reachable from the new MCP withdraw tool's transfer-mode path with user-controlled input.

🔴 1 blocking | 🟡 1 suggestion(s)

1 additional finding(s) omitted (not in diff).

8 carried-forward finding(s) already raised on this PR; not re-posting as new inline comments.

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `src/model/address.rs`:
- [BLOCKING] src/model/address.rs:14-24: is_platform_address_string panics on non-ASCII input; reachable from the new MCP withdraw tool
  CARRIED FORWARD — STILL VALID at 74cf43af. Line 17 still does `s[..hrp.len()].eq_ignore_ascii_case(hrp)` against a `&str` after only a byte-length check `s.len() > hrp.len()`. Rust panics when the byte offset falls inside a multi-byte UTF-8 code point. With `PLATFORM_HRP_MAINNET = "dash"` (4 bytes) or `PLATFORM_HRP_TESTNET = "tdash"` (5 bytes), any input whose first character is a 3-byte UTF-8 sequence (e.g. `日本ABC`) trips the slice at byte 4 with `byte index 4 is not a char boundary`. The new `identity_masternode_credits_withdraw` tool feeds user-controlled `to_address` through `parse_transfer_core_address` (src/mcp/tools/identity.rs:888), invoked from `resolve_withdrawal_plan` at line 974 — so a single MCP request with `key_mode="transfer"` and a non-ASCII `to_address` panics the in-process MCP service instead of returning `InvalidParam`. The unit tests at lines 410-425 only cover ASCII inputs. HRPs are ASCII by design — compare on bytes and add a non-ASCII regression test.

In `src/bin/det_cli/main.rs`:
- [SUGGESTION] src/bin/det_cli/main.rs:129-146: One-shot standalone CLI hard-exits without draining the in-process backend
  NEW IN LATEST DELTA. The one-shot CLI now calls `std::process::exit` immediately after `runtime.block_on(run(cli))`. In standalone mode `run()` uses `connect_in_process()`, which spawns a local `DashMcpService`; wallet-facing tools such as `identity_masternode_credits_withdraw` wire the wallet backend and start coordinator persisters via `ensure_spv_synced`. Unlike `start_stdio` and `run_headless`, this path has no handle to the service after the call and never awaits `DashMcpService::shutdown_wallet_backend()`, so process exit kills in-flight coordinator change-set writes. The inline comment correctly notes that SQLite transaction atomicity prevents corruption and that the tool's own writes are committed, but it does not address pending coordinator persister writes that were started in the background during the tool invocation. Capture the service from `connect_in_process` for one-shot calls and run `shutdown_wallet_backend().await` before computing `exit_code`.

[lklimek]

Review fix-pass — 51a12f81 (pushed for review)

Addresses the outstanding review findings. QA is still running (independent clippy/test re-run + finding verification) and a docs commit is still landing (see caveats) — pushed now so review can start in parallel.

Findings addressed

#	Finding	What changed	File(s)
B1 🔴	non-ASCII panic in is_platform_address_string	&str byte-slice → byte comparison; added non-ASCII regression test	src/model/address.rs
H2	split masternode tools into their own module + rename	new masternode.rs; tools renamed masternode_identity_load / masternode_credits_withdraw; structs Masternode*; registered in tool_router()	src/mcp/tools/masternode.rs, identity.rs, mod.rs, server.rs
H1 + S1	use a zeroizing secret type; bound plaintext lifetime	Secret gains Deserialize (+feature-gated JsonSchema); load-tool key params are Secret from deserialization — no plain String across the SPV wait	src/model/secret.rs, masternode.rs
S2	validate pro_tx_hash before SPV (load tool)	decode_identity_id(...) now runs before ensure_spv_synced	masternode.rs
S3	KeyMode vocabulary duplicated ×3	impl Display for KeyMode → canonical "owner"/"transfer"; all sites use it	src/model/masternode_input.rs, masternode.rs
S4	e2e tests bypassed invoke()	TC-MN-050/051 now drive MasternodeCreditsWithdraw::invoke(); owner-mode to_address=None is a real assertion	tests/backend-e2e/identity_masternode_withdraw.rs
S5	network-switch backend leak	headless exit now drains the initial context too (see caveat)	src/bin/det_cli/headless.rs
S6	start_stdio skipped shutdown on ? error paths	shutdown now runs unconditionally; result propagated after	src/mcp/mod.rs
S7	ensure_storage_ready never waited in standalone	ensure_spv_synced dispatches MigrationTask::FinishUnwire before the storage-ready wait	src/mcp/resolve.rs

S8 (one-shot hard-exit) was already correct by design — no change.

Tool name change (heads-up for reviewers)

identity_masternode_load → masternode_identity_load, identity_masternode_credits_withdraw → masternode_credits_withdraw (CLI: masternode-identity-load, masternode-credits-withdraw). Safe — these tools are new in this unmerged PR, no external consumers.

⚠️ Caveats still in flight

• Docs (docs/MCP.md, docs/CLI.md) not yet updated for the rename — fix commit incoming.
• S5 drains the initial context at exit, not at the swap point — a single switch is covered, but a multi-switch session (A→B→C) still orphans the intermediate backend. Under consideration; hard-exit prevents the teardown panic regardless.
• S7 migration-dispatch idempotency/safety is under QA review.

I'll follow up here once QA + the docs commit land.

_{🤖 Co-authored by Claudius the Magnificent AI Agent}

[lklimek]

I don't really like this approach. We should rather shutdown the OS threads first, retrieve their shutdown status, and then shutdown the tokio runtime.

[lklimek]

Final fix-pass pushed — 33ef8a13 (QA-green)

Advances the branch 51a12f81 → 33ef8a13 (2 commits). This is the verified push candidate.

Delta since 51a12f81:

• S5 strengthened — backend drain moved to the swap_context callsite (src/mcp/tools/network.rs:250-258); now covers multiple consecutive network switches (A→B→C), not just one. headless.rs simplified accordingly.
• Tool name corrected — masternode_credits_withdraw (the user-confirmed name), MasternodeCreditsWithdraw struct. Zero stale names in src//tests//docs/.
• Docs updated — docs/MCP.md + docs/CLI.md now use the final tool names; a stale CLI name in a masternode_input.rs error message (and its test) was also fixed.

QA gate on 33ef8a13 (SHA-verified): clippy --all-features --all-targets -D warnings clean · cargo test --all-features --workspace 1136 passed / 0 failed · fmt --check clean. All findings (B1 panic, S1–S7, H1, H2) confirmed fixed, with deep-verifies on S5 (multi-switch) and S7 (migration idempotency).

Still open (tracked, not blocking this tip):

• The hard-exit teardown (main.rs:137) — per the reviewer's request to shut down the coordinator threads and collect status before the runtime, a feasibility investigation is underway (it likely needs an upstream platform_wallet change to join the coordinator JoinHandles). Will follow up with the verdict.
• One LOW doc-accuracy tweak (MCP.md:110 slightly overstates the no-plain-String guarantee) — will fold into the next commit.

_{🤖 Co-authored by Claudius the Magnificent AI Agent}

[thepastaclaw]

Code Review

Cumulative review at 51a12f8. The latest delta is a heavy fix-pass: 7 of 10 prior findings are FIXED (B1 non-ASCII slice panic, S1 Secret-wrap timing, S2 pre-SPV ProTxHash validation, S3 KeyMode unification, S4 e2e MasternodeCreditsWithdraw::invoke coverage, S6 unconditional start_stdio shutdown, S7 standalone MigrationTask dispatch). Three prior findings remain — partial S5 (multi-switch headless drain), and unchanged S9/S10 (one-shot CLI hard-exit, duplicate withdrawal-mode labels). New in this delta: an H2 refactor renamed the masternode tools from identity_masternode_* to masternode_*, but docs/MCP.md, docs/CLI.md, and the ai-design specs still advertise the old names — every documented headless workflow is now broken. Requesting changes for the naming/doc mismatch only.

🔴 1 blocking | 🟡 1 suggestion(s) | 💬 1 nitpick(s)

1 carried-forward finding(s) already raised on this PR; not re-posting as new inline comments.

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `docs/MCP.md`:
- [BLOCKING] docs/MCP.md:85-86: Documented MCP/CLI tool names don't match the registered names
  The H2 refactor renamed the registered tools to `masternode_identity_load` (src/mcp/tools/masternode.rs:124) and `masternode_credits_withdraw` (src/mcp/tools/masternode.rs:425), but the public-facing docs still advertise the old `identity_masternode_*` names:

  - docs/MCP.md:85-86 lists `identity_masternode_load` and `identity_masternode_credits_withdraw` with example CLI commands `det-cli identity-masternode-load` and `det-cli identity-masternode-credits-withdraw`.
  - docs/CLI.md:158, 169, 176 walk users through `det-cli identity-masternode-load` / `det-cli identity-masternode-credits-withdraw`.
  - The PR's ai-design spec (`docs/ai-design/2026-06-18-masternode-cli-withdraw/{01,02,03}-*.md`) uses the old names throughout.

  The CLI discovers tools dynamically via `tools/list` and hyphen-translates them, so `det-cli identity-masternode-load` resolves to `identity_masternode_load`, which is not registered — every documented workflow fails with an unknown-tool error. Either (a) update all three doc surfaces to the new `masternode_*` names (preferred — the new layout follows the `{domain}_{object}_{action}` convention in CLAUDE.md and matches the new src/mcp/tools/masternode.rs module split), or (b) revert the registered names back to `identity_masternode_*` and keep masternode tools nested under the identity domain. The in-code error-message references (masternode.rs:376, 381, 485) already use the new `masternode-identity-load` spelling, so option (a) is the consistent path.

In `src/bin/det_cli/headless.rs`:
- [SUGGESTION] src/bin/det_cli/headless.rs:54-68: Headless drain still misses intermediate backends after multiple network switches
  CARRIED FORWARD from prior S5 — PARTIALLY FIXED at 51a12f81. The new drain shuts down both the currently-active context and the initial context (covering the single-switch case), but a headless session that issues `network_switch` more than once (e.g. mainnet → testnet → devnet) still leaks every intermediate `AppContext`: `service.swap_context()` in src/mcp/server.rs replaces the active `ArcSwap` pointer without first calling `shutdown()` on the outgoing backend, and the exit-path drain only sees the first and last pointers. The cleanest fix is to shut down the outgoing backend inside `swap_context` (or at the `network_switch` tool callsite, src/mcp/tools/network.rs) before storing the new context, so the lifecycle is local to the swap and headless exit only needs to drain the active pointer. Hard-exit at line 85 still prevents the coordinator-panic class regardless, so this is a refinement rather than a regression.

[lklimek]

Responses to review threads

(Posted as a PR comment — inline replies are currently blocked by a stale pending review on the bot account. Addressing all three threads here.)

Hard-exit teardown — main.rs:137

Your instinct is right, but the graceful sequence can't be done DET-side today:

• Coordinators run on std::thread OS threads (not tokio tasks) because the SDK futures are !Send (they use Handle::block_on) — which is exactly why dropping the runtime underneath them panics.
• Their JoinHandle is dropped at spawn inside upstream platform_wallet::start() (identity_sync.rs:409, platform_address_sync.rs:208, shielded_sync.rs:239). DET's accessor surface only exposes start/stop/quiesce, and quiesce() is a persister-drain barrier, not a thread-liveness one — no handle to join, no status to read.

The correct fix is a small upstream change (the 3 *_sync.rs + manager/mod.rs): each thread fires a oneshot/Notify as its last act after block_on returns; shutdown() awaits it after the existing drain and returns a CoordinatorExitStatus. Then DET drops the process::exit stopgaps.
Done: filed the upstream feature request, and scaffolded the graceful path on the DET side as commented pseudocode + a TODO(upstream platform_wallet) at the shutdown seam (anchored at the existing src/mcp/server.rs:137 note), keeping the process::exit as the documented stopgap until the upstream API lands. Incoming commit.

SecretString for private keys — r3442257333 (+ the two duplicate threads)

We evaluated it and chose not to adopt it, for a security reason: platform_wallet_storage::SecretString implements neither Deserialize nor JsonSchema, so using it in the MCP param struct would force deserialize-into-plain-String-then-rewrap at the JSON boundary — reintroducing the plaintext window the request aims to close. Instead we made the local crate::model::secret::Secret the param type and gave it Deserialize (zeroizing the transient plaintext) + feature-gated JsonSchema: keys land in a zeroizing, best-effort page-locked buffer at deserialization, Debug redacts to Secret(***), and they never reach logs or the MCP error payload. If you'd rather standardize on SecretString, the clean path is adding Deserialize/JsonSchema upstream — happy to file that.

Split masternode.rs + rename — r3442331993

✅ Done. Tools moved to src/mcp/tools/masternode.rs, renamed masternode_identity_load / masternode_credits_withdraw (structs MasternodeIdentityLoad / MasternodeCreditsWithdraw), registered in tool_router(), docs updated. Shipped in the latest tip.

_{🤖 Co-authored by Claudius the Magnificent AI Agent}

[lklimek]

Final commit pushed — a88a5b3b

Closes out the fix-pass:

• Graceful-teardown scaffold — shutdown_wallet_backend doc (src/mcp/server.rs) now carries a "plan for when upstream delivers" section with the shutdown_and_join().await → drop(runtime) → return result sequence (in a text fence, not a doctest), plus a TODO(graceful-teardown) one-liner at each of the three process::exit stopgaps (main.rs, connect.rs, headless.rs). The hard-exits remain as the documented, working stopgap until the upstream change lands.
• Upstream feature request filed (platform_wallet: shutdown() should join the coordinator OS threads and return a CoordinatorExitStatus).
• QA-008 — docs/MCP.md secret-handling wording corrected.

All review findings (B1 panic, S1–S7, H1, H2) are resolved and QA-green (clippy -D warnings clean; cargo test --all-features --workspace 1136 passed / 0 failed; fmt clean). Ready for review.

_{🤖 Co-authored by Claudius the Magnificent AI Agent}

[thepastaclaw]

Code Review

Cumulative review at 33ef8a1. The latest delta resolves the prior blocking docs/tool-naming mismatch (B1) and the multi-network-switch backend drain (S5). No new blocking defects. Two carried-forward findings remain: a nitpick that masternode_identity_load's available_withdrawal_keys may emit duplicate labels for identities with multiple keys per purpose, and a new error-propagation suggestion at the SPV gate. The prior one-shot CLI hard-exit suggestion is intentionally deferred (documented in 74cf43a and the inline comment) and is dropped.

🟡 1 suggestion(s)

1 carried-forward finding(s) already raised on this PR; not re-posting as new inline comments.

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `src/mcp/resolve.rs`:
- [SUGGESTION] src/mcp/resolve.rs:201-203: Backend wiring errors are logged-and-dropped before the SPV wait
  `ensure_wallet_backend_and_start_spv` returns a typed `TaskError` describing the precise failure (storage, secret store, backend setup, etc.), but `ensure_spv_synced` only logs it and falls through to the watcher loop. The loop sees `SpvStatus::Error` (which `ensure_wallet_backend_and_start_spv` sets on failure, per the comment in `context/wallet_lifecycle.rs:296-302`) and returns the generic `McpToolError::SpvSyncFailed`. Net effect: the caller correctly fails, but the typed root cause is discarded — the rest of the backend task system goes to lengths to preserve it. Propagating the original `TaskError` here gives MCP clients an actionable error instead of a bare "SPV sync failed."

[lklimek]

Round-2 review fixes pushed — 8cc11711

Addresses the latest review round (advances a88a5b3b → 8cc11711, one clean commit):

• Secret-typed key-presence check — require_at_least_one_signing_key now takes &Secret (was &str), backed by a new Secret::is_blank(). The call site no longer calls expose_secret() just to test presence — plaintext is never handed to the validator. (Answers the review question about accepting a secret type rather than exposing for the emptiness check.)
• Deduped available_withdrawal_keys — each owner/transfer label is emitted at most once, even for identities with multiple keys of the same purpose.
• Typed SPV-wiring error — ensure_spv_synced now propagates the typed TaskError from ensure_wallet_backend_and_start_spv as McpToolError::TaskFailed (was logged-and-dropped, masking the root cause as a generic SPV timeout).

QA on this delta (SHA-verified): clippy --all-features --all-targets -D warnings clean · cargo test --all-features --workspace 973 lib + 146 kittest + all suites, 0 failures · fmt clean.

All review threads are resolved except the hard-exit one (main.rs), intentionally kept open as the tracker for the upstream platform_wallet change (join coordinator threads + return exit status) — filed separately.

_{🤖 Co-authored by Claudius the Magnificent AI Agent}

[Copilot]

Pull request overview

Adds a headless (det-cli / MCP) flow for masternode/evonode identity loading and Platform credit withdrawals, plus several headless lifecycle fixes (SPV/storage gating, backend draining, and deterministic exit behavior) to make the end-to-end headless path reliable.

Changes:

• Introduces two new MCP tools: masternode_identity_load and masternode_credits_withdraw, with shared stateless parsing/validation helpers.
• Hardens headless lifecycle behavior: waits for cold-start migration, drains wallet backend on network switch/exit, and uses hard-exit to avoid Tokio teardown panics.
• Adds tests (unit + ignored backend-e2e) and updates CLI/MCP/user-story documentation for the new headless masternode workflows.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/backend-e2e/main.rs	Registers the new ignored backend-e2e module for masternode withdrawal scenarios.
tests/backend-e2e/identity_masternode_withdraw.rs	Adds ignored, env-gated backend-e2e tests covering masternode load + owner/transfer withdrawal flows.
src/model/secret.rs	Adds Secret::is_blank() plus Deserialize/JsonSchema support for MCP params carrying secrets.
src/model/mod.rs	Exposes masternode_input module behind mcp/cli features.
src/model/masternode_input.rs	Implements stateless parsing/validation for masternode tool inputs (node type, key mode, identity id, key presence).
src/model/address.rs	Fixes potential UTF-8 slicing panic in is_platform_address_string and adds regression tests.
src/mcp/tools/network.rs	Drains outgoing wallet backend during network switch before swapping contexts.
src/mcp/tools/mod.rs	Registers the new masternode MCP tool module.
src/mcp/tools/masternode.rs	Implements the two new MCP tools, including preflight validation, SPV gating, and destination/key-mode rules.
src/mcp/tests.rs	Adds StorageNotReady to error-code uniqueness tests and adds message/code checks.
src/mcp/server.rs	Registers masternode tools and adds wallet-backend shutdown helper with detailed rationale.
src/mcp/resolve.rs	Adds cold-start migration wait (ensure_storage_ready) and wires migration finishing into ensure_spv_synced.
src/mcp/mod.rs	Ensures stdio server path drains backend on shutdown and avoids short-circuiting shutdown on errors.
src/mcp/error.rs	Adds StorageNotReady MCP error variant + code mapping.
src/bin/det_cli/main.rs	Converts CLI flow to deterministic hard-exit after running commands to avoid runtime teardown races.
src/bin/det_cli/headless.rs	Drains backend on shutdown and hard-exits after HTTP server termination.
src/bin/det_cli/connect.rs	Makes stdio MCP server path hard-exit (never returns) and flushes output before exit.
docs/user-stories.md	Adds MCP-003/MCP-004 user stories for headless masternode identity load and credit withdrawal.
docs/MCP.md	Documents the two new tools, SPV gating notes, and private-key handling guidance.
docs/CLI.md	Adds CLI walkthrough for masternode identity load + credit withdraw in owner/transfer modes.
docs/ai-design/2026-06-18-masternode-cli-withdraw/01-requirements-ux.md	Adds requirements/UX spec for the feature.
docs/ai-design/2026-06-18-masternode-cli-withdraw/02-test-spec.md	Adds detailed test specification (unit/tool/e2e cases).
docs/ai-design/2026-06-18-masternode-cli-withdraw/03-dev-plan.md	Adds development plan outlining tasks, sequencing, and coverage gaps.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[lklimek]

Copilot review round addressed — d77cd4db

The three findings from GitHub Copilot's reviewer are fixed and pushed:

• Redaction e2e test (tests/backend-e2e/identity_masternode_withdraw.rs) now captures the actual WIF and asserts it does not appear in Display/Debug — the previous check tested the substring "bogus" (a variable name never present in a WIF), so it was vacuously true.
• src/model/secret.rs Deserialize doc corrected: it deserializes into a transient String first, so no long-lived plain copy persists (the prior "without ever living as a plain String" was inaccurate).
• src/mcp/mod.rs start_stdio doc corrected: shutdown_wallet_backend does not prevent the coordinator timer-wheel panic (it doesn't join the OS threads); std::process::exit is the deterministic mitigation.

Also retained a runnable params-Debug redaction unit test (sentinel keys absent + Secret(***) present). clippy -D warnings clean, lib tests pass, backend-e2e compiles.

All review threads are now resolved except the hard-exit one (main.rs), intentionally kept open as the tracker for the upstream platform_wallet graceful-teardown change.

_{🤖 Co-authored by Claudius the Magnificent AI Agent}

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated no new comments.

[thepastaclaw]

Code Review

Verifier confirms the latest delta (33ef8a1..a88a5b3) is documentation/comment-only — TODO(graceful-teardown) markers at three CLI exit call-sites, a planning doc-block in DashMcpService::shutdown_wallet_backend, and a docs/MCP.md wording refinement on Secret-wrap timing. No new defects introduced in this delta. Both prior findings are carried forward unchanged: resolve.rs still logs-and-drops the typed backend-wiring TaskError before entering the SPV wait, and masternode_identity_load can still emit duplicate withdrawal-mode labels for identities holding multiple OWNER or TRANSFER keys.

🟡 1 suggestion(s)

1 carried-forward finding(s) already raised on this PR; not re-posting as new inline comments.

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `src/mcp/resolve.rs`:
- [SUGGESTION] src/mcp/resolve.rs:201-203: Propagate the typed backend-wiring TaskError instead of dropping it before the SPV wait
  Carried forward from prior reviews — still valid at a88a5b3b. `ctx.ensure_wallet_backend_and_start_spv(sender)` returns a typed `TaskError` describing the precise startup failure (storage init, secret store, backend wiring, etc.), and `context/wallet_lifecycle.rs` also marks `SpvStatus::Error` before returning. `ensure_spv_synced` currently only logs that error via `tracing::warn!` and falls through into `ensure_storage_ready` + the SPV watcher loop, which then collapses the failure into the generic `McpToolError::SpvSyncFailed`. Net effect: the caller still fails, but the actionable root cause is discarded and the user can be made to wait through the full 10-minute SPV timeout for what is really a wiring failure. Returning the original error here preserves the typed-error boundary the rest of the backend task system maintains and gives MCP clients an actionable diagnosis.