Notify the operator when a mirror coin cannot be created or reclaimed for want of funds

[MichaelTaylor3d]

Task

When a mirror coin cannot be created or reclaimed because the operator wallet lacks funds, raise an OS notification. Today it is logged and nothing else, so an operator learns their node stopped collateralising content only by reading logs they have no reason to open.

Why this is a user-facing defect, not a nicety

The mirror pass runs unattended every 10 minutes (MIRROR_PASS_INTERVAL = dig_constants::MIRROR_ROUND_LENGTH_MS = 600,000 ms, server.rs:2855). When funding is short, mirror/funding.rs:25-29 refuses the whole create rather than partially funding it — the correct behaviour — and the pass moves on. It will do that silently, every ten minutes, indefinitely.

The consequence is not a failed operation the user retries. It is that their content quietly stops being bonded, they earn nothing from it, and every surface continues to look healthy. A silent recurring failure on a money path is exactly the class this project treats as a lie by omission.

Scope

Notify on the two funding-related outcomes, and only those:

1. A create refused for want of funds — mirror/funding.rs FundingError (insufficient $DIG, and the TooManyInputs case, where the wallet holds enough but in too many pieces — that one has a different remedy and must say so: consolidate, not top up).
2. A reclaim that could not pay its fee. Note reclaims are deliberately not gated on funds and support a zero fee, so verify this state is actually reachable before building for it — if it is not, say so and cover only case 1.

Do NOT notify on:

• the balance being merely unreadable (FundsUnknown) — that is a different condition with a different remedy, and reporting a shortfall on no evidence is the money lie BalanceUnreadable exists to prevent
• observe-only mode (no operator wallet, DIG_WALLET_ENABLE_LIVE_BROADCAST off, mirror_enabled false, or no DIG_MIRROR_ADVERTISE_URLS) — the node is configured not to spend, which is not a failure

The thing to get right: do not notify every ten minutes

A notification that repeats 144 times a day is worse than none — it trains the operator to dismiss it, and the one that matters is lost with the rest. Notify on the transition into the funding-short state, and again only when it changes (recovered, or the shortfall materially worsened). The pass runner already holds cross-round state for presence debouncing (runner.rs:243-245), so there is a precedent for where this belongs.

State the chosen policy explicitly in the code, because "how often does this fire" is the whole design.

The message must be actionable

An operator seeing it should know what to do without reading source. Name the amount short, the epoch's requirement, and the remedy — top up versus consolidate are different actions and the code already distinguishes them. Do not name a coin id or an address in a desktop notification.

Context

• dig-node already ships desktop notification capability — check how the updater surfaces its own messages and reuse that path rather than adding a second mechanism (§2.0: reuse before building).
• Funding refusal: crates/dig-node-service/src/mirror/funding.rs.
• Pass runner and its cross-round state: crates/dig-node-service/src/mirror/runner.rs, spawned at server.rs:2136.

Acceptance

On a node whose operator wallet is short, a person sees an OS notification naming the shortfall and the remedy, once on entering that state — not once per pass. Proven by a test that drives several consecutive short passes and asserts exactly one notification, plus one that asserts a recovered-then-short-again cycle notifies again.

[MichaelTaylor3d]

Lane owns this. Worktree C:/tmp/worktrees/dn-fund, branch loop/mc-fund, base 95c9582.
Draft PR: #469 (paired with #461).

Case 2 is UNREACHABLE — verified, so this ticket covers case 1 only.
mirror/lifecycle.rs:385-388 builds every reclaim with fee = 0 and an empty fee-coin vector,
unconditionally, and the comment there records why (§25.4.4: a zero-fee reclaim may not be admitted
under fee pressure and the next pass retries it, whereas a reclaim gated on selectable XCH would be
blocked by an empty XCH wallet). Funds::dig_balance's Err is documented at :126 and :144 as
deferring creates and never reclaims. There is no path on which a reclaim fails for want of funds,
so building a notification for one would be a surface reporting a condition that cannot occur.

Notification policy, stated here because "how often does this fire" is the design.

• Alert on the TRANSITION into the funding-short state, never per pass.
• While short, re-alert only when the REMEDY changes (top up vs consolidate are different actions)
  or when the deficit grows by at least 10% over the deficit last alerted on.
• Alert once on RECOVERY, so the operator learns the node resumed bonding without watching for it.
• Never on Chain/CommitmentsUnreadable (the balance is unreadable, not short) and never in
  observe-only mode.

Next action: implement the gate in mirror/funding.rs. Delivery is a one-call wiring in
mirror/runner.rs, which belongs to a live sibling lane — it will be reported, not made here.

[MichaelTaylor3d]

Gate pushed on loop/mc-fund (head 0ff6147), PR #469. Reclaims confirmed unreachable for want of funds, so case 1 only. dig-node has no OS-notification mechanism at all — the updater surfaces its messages over the control.* RPC surface that dig-app polls, so delivery is a control-surface event plus dig-app's half, not a toast dig-node raises. Recorded rather than worked around. Tests written and unrun (host disk full).

[MichaelTaylor3d]

Correction to this ticket's premise — dig-node has NO OS-notification mechanism

I wrote "dig-node already ships desktop notification capability — check how the updater surfaces its own messages and reuse that path." That is wrong. The #461/#463 lane checked instead of taking my word, and found:

• There is no notify-rust or equivalent anywhere in the tree.
• The updater does not raise OS notifications. It surfaces state over the control.* RPC surface that dig-app polls.

So a genuine desktop toast is dig-app's half, and this ticket cannot close on dig-node alone.

What that changes

The work splits cleanly, and the dig-node half is the harder one and is already done:

dig-node (this ticket, landed on PR #469): decide when to alert, which is the whole design — FundingAlertGate::observe(&FundingObservation) -> Option<FundingAlert>, pure, no clock. Alert on the transition into short; while short, again only if the remedy changes or the deficit grows ≥50%; once on recovery; never on Unknown, which also does not clear the state — treating an unreadable balance as recovery would re-alert on the next short pass. FundingObservation::from_error is an exhaustive match, so a new FundingError variant will not compile until someone decides its remedy.

dig-app (owed, a sibling ticket): consume the alert over the control surface and raise the actual OS notification.

Wiring still owed inside dig-node, and it belongs to the #464 lane's file: mirror/runner.rs must hold the gate beside its presence state (runner.rs:243-245), feed it from_error(&e) on refusal and Healthy on a funded pass, and deliver the returned alert.

Also confirmed while there

The reclaim case named in this ticket is UNREACHABLE. mirror/lifecycle.rs:385-388 builds every reclaim at fee = 0 with no fee coins, unconditionally — so a reclaim cannot fail for want of funds. Case 1 only, as the ticket allowed for. That is the right answer to the question rather than a gap.

And a correction to my #461 citation

MAX_SELECTED_FUNDING_COINS = 32 does not exist on main — it is in unmerged PR #457. Any reasoning citing funding.rs:69 for it is citing an unmerged tree, mine included.