refactor(balances): share leaf parsing between bulk + single-chain paths; repair the push pipeline

[BitHighlander]

Stacked on #314 — retarget to develop after it merges.

Why

getBalance was a ~470-line hand-mirrored fork of getBalances, and every one of the six drift bugs the refresh audit found lived in a mirrored leaf (the hive publicKey fallback fixed in #314 being the user-facing one). This PR extracts the leaves into shared module helpers so the paths cannot diverge again — orchestration stays per-handler, only the leaf logic is shared.

Shared helpers (bun/index.ts module scope)

Helper	Was duplicated	Drift it retires
deriveChainAddress()	2×	{ publicKey } fallback; unknown-message capability recording (getBalance never recorded misses → kept re-sending rejected messages, the #310 USB-detach class)
isTokenEntry / parseTokenEntry / CONTRACT_CAIP_RE	3×	single-chain + watch-only paths regain denom|bank contract match (TCY/RUJI) and the caip-prefix networkId fallback
dedupeTokensByCaip	5× byte-identical loops	—
mapServerDefiPosition	3×	—
fetchShieldedZecToken	2× (now)	a single-chain zcash refresh used to WIPE the cached shielded zZEC sub-row (its tokens_json overwrite carried no shielded merge)

getBalance behavior fixes

• Honors response meta: degraded Pioneer data surfaces on the warning banner and is treated as UNCONFIRMED — no force cache overwrite, so a degraded zero can't clobber a good cached balance.
• Applies the same firmware/feature-flag chain gates as getBalances (returns the empty-balance sentinel rather than deriving a flag-off chain).
• Optional forceRefresh param (default TRUE — user refresh / post-send / tx pushes must bypass Pioneer's cache).

Push pipeline (socket leg)

• Parses JSON-stringified payloads and resolves the chain from caip/networkId (the server's chain field is symbol-ish, so genuine watchtower transaction:incoming events were mostly dropped before); maps server payload types into the schema union (confirmation_update → confirmed) so the incoming toast works from this leg.
• Deliberately consumes ONLY transaction:incoming. Adversarial review caught that Pioneer's balance:update/balance:cache:update fire from inside its GetPortfolioBalances controller, per request, to the requester's own socket — consuming them creates a self-sustaining refresh feedback loop (every balance query schedules the next one, with device USB traffic per cycle). Documented in docs/handoff-pioneer-hive-push-refresh.md §7 for the server-side fix.
• Dedups pushes by txid across the SSE and socket legs — one deposit no longer double-toasts and double-fetches.
• Debounced forwards keep/merge pending payloads so a confirmation update landing in the 2s window can't eat an incoming-payment toast.
• Debounce map hoisted to module scope and cleared on disconnect (pending timers used to fire getBalance at an unplugged device); SSE tx:confirmed forwards debounced per network (they re-fire per confirmation, each costing a forced fetch).

Review

Same multi-agent adversarial pass as #314 (4 review dimensions → 12 findings → 8 confirmed after refutation → all fixed across the two PRs; 4 refuted as pre-existing on develop). Typecheck differential vs develop baseline (619 pre-existing errors): no new error classes — see #314's note about the broken @types/minimatch making plain tsc a silent false-green.

🤖 Generated with Claude Code