@cogcoin/client 1.0.2 → 1.1.0

package/dist/wallet/mining/runner.js

@@ -5,9 +5,11 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getBalance, getBlockWinners, lookupDomain, lookupDomainById, } from "@cogcoin/indexer/queries";
 import { assaySentences, deriveBlendSeed, displayToInternalBlockhash, getWords, settleBlock, } from "@cogcoin/scoring";
+import { wordlist as englishWordlist } from "@scure/bip39/wordlists/english.js";
 import { probeIndexerDaemon } from "../../bitcoind/indexer-daemon.js";
+import { isRetryableManagedRpcError } from "../../bitcoind/retryable-rpc.js";
 import { FOLLOW_VISIBLE_PRIOR_BLOCKS } from "../../bitcoind/client/follow-block-times.js";
-import { attachOrStartManagedBitcoindService } from "../../bitcoind/service.js";
+import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, stopManagedBitcoindService, } from "../../bitcoind/service.js";
 import { createRpcClient } from "../../bitcoind/node.js";
 import { COG_OPCODES, COG_PREFIX } from "../cogop/constants.js";
 import { extractOpReturnPayloadFromScriptHex } from "../tx/register.js";
@@ -28,6 +30,35 @@ import { generateMiningSentences, MiningProviderRequestError } from "./sentences
 import { createEmptyMiningFollowVisualizerState, MiningFollowVisualizer, } from "./visualizer.js";
 const BEST_BLOCK_POLL_INTERVAL_MS = 500;
 const BACKGROUND_START_TIMEOUT_MS = 15_000;
+const MINING_BITCOIN_RECOVERY_GRACE_MS = 15_000;
+const MINING_BITCOIN_RECOVERY_RESTART_COOLDOWN_MS = 60_000;
+const MINING_BITCOIN_RECOVERY_NOTE = "Mining lost contact with the local Bitcoin RPC service and is waiting for it to recover.";
+function resolveBip39WordsFromIndices(indices) {
+    if (indices === null || indices === undefined) {
+        return [];
+    }
+    const words = [];
+    for (const index of indices) {
+        if (!Number.isInteger(index) || index < 0 || index >= englishWordlist.length) {
+            continue;
+        }
+        words.push(englishWordlist[index]);
+    }
+    return words;
+}
+function resolveSettledWinnerRequiredWords(options) {
+    const storedWords = resolveBip39WordsFromIndices(options.bip39WordIndices);
+    if (storedWords.length > 0) {
+        return storedWords;
+    }
+    if (options.snapshotTipPreviousHashHex === null
+        || options.snapshotTipPreviousHashHex === undefined
+        || !Number.isInteger(options.domainId)
+        || options.domainId <= 0) {
+        return [];
+    }
+    return resolveBip39WordsFromIndices(deriveMiningWordIndices(Buffer.from(displayToInternalBlockhash(options.snapshotTipPreviousHashHex), "hex"), options.domainId));
+}
 function resolveSnapshotOverride(override, fallback) {
     return override === undefined ? fallback : override;
 }
@@ -442,11 +473,41 @@ function createMiningLoopState() {
         selectedCandidate: null,
         ui: createEmptyMiningFollowVisualizerState(),
         waitingNote: null,
+        bitcoinRecoveryFirstFailureAtUnixMs: null,
+        bitcoinRecoveryFirstUnreachableAtUnixMs: null,
+        bitcoinRecoveryLastRestartAttemptAtUnixMs: null,
+        bitcoinRecoveryServiceInstanceId: null,
+        bitcoinRecoveryProcessId: null,
+        reconnectSettledUntilUnixMs: null,
+        tipSettledUntilUnixMs: null,
     };
 }
 export function createMiningLoopStateForTesting() {
     return createMiningLoopState();
 }
+function expireMiningSettleWindows(loopState, nowUnixMs) {
+    if (loopState.reconnectSettledUntilUnixMs !== null
+        && loopState.reconnectSettledUntilUnixMs <= nowUnixMs) {
+        loopState.reconnectSettledUntilUnixMs = null;
+    }
+    if (loopState.tipSettledUntilUnixMs !== null
+        && loopState.tipSettledUntilUnixMs <= nowUnixMs) {
+        loopState.tipSettledUntilUnixMs = null;
+    }
+}
+function setMiningReconnectSettleWindow(loopState, nowUnixMs) {
+    loopState.reconnectSettledUntilUnixMs = nowUnixMs + MINING_NETWORK_SETTLE_WINDOW_MS;
+}
+function setMiningTipSettleWindow(loopState, nowUnixMs) {
+    loopState.tipSettledUntilUnixMs = nowUnixMs + MINING_TIP_SETTLE_WINDOW_MS;
+}
+function buildMiningSettleWindowStatusOverrides(loopState, nowUnixMs) {
+    expireMiningSettleWindows(loopState, nowUnixMs);
+    return {
+        reconnectSettledUntilUnixMs: loopState.reconnectSettledUntilUnixMs,
+        tipSettledUntilUnixMs: loopState.tipSettledUntilUnixMs,
+    };
+}
 function buildMiningTipKey(bestBlockHash, targetBlockHeight) {
     if (bestBlockHash === null || targetBlockHeight === null) {
         return null;
@@ -491,6 +552,11 @@ function resolveCurrentMinedBlockBoard(options) {
         rank: winner.rank,
         domainName: lookupDomainById(options.snapshotState, winner.domainId)?.name ?? fallbackSettledWinnerDomainName(winner.domainId),
         sentence: winner.sentenceText ?? "[unavailable]",
+        requiredWords: resolveSettledWinnerRequiredWords({
+            domainId: winner.domainId,
+            bip39WordIndices: winner.bip39WordIndices,
+            snapshotTipPreviousHashHex: options.snapshotTipPreviousHashHex,
+        }),
     }));
     return {
         settledBlockHeight,
@@ -498,12 +564,16 @@ function resolveCurrentMinedBlockBoard(options) {
     };
 }
 export function resolveSettledBoardForTesting(options) {
-    return resolveCurrentMinedBlockBoard(options);
+    return resolveCurrentMinedBlockBoard({
+        ...options,
+        snapshotTipPreviousHashHex: options.snapshotTipPreviousHashHex ?? null,
+    });
 }
-function syncMiningUiSettledBoard(loopState, snapshotState, snapshotTipHeight) {
+function syncMiningUiSettledBoard(loopState, snapshotState, snapshotTipHeight, snapshotTipPreviousHashHex) {
     const settledBoard = resolveCurrentMinedBlockBoard({
         snapshotState,
         snapshotTipHeight,
+        snapshotTipPreviousHashHex,
         nodeBestHeight: null,
     });
     loopState.ui.settledBlockHeight = settledBoard.settledBlockHeight;
@@ -514,17 +584,20 @@ function syncMiningUiForCurrentTip(options) {
         ? null
         : options.nodeBestHeight + 1;
     const tipKey = buildMiningTipKey(options.nodeBestHash, targetBlockHeight);
-    if (tipKey !== options.loopState.currentTipKey) {
+    const priorTipKey = options.loopState.currentTipKey;
+    const tipChanged = tipKey !== null && tipKey !== priorTipKey;
+    if (tipKey !== priorTipKey) {
         options.loopState.currentTipKey = tipKey;
         resetMiningUiForTip(options.loopState, targetBlockHeight);
         if (options.recentWin !== null) {
             options.loopState.ui.recentWin = options.recentWin;
         }
     }
-    syncMiningUiSettledBoard(options.loopState, options.snapshotState, options.snapshotTipHeight);
+    syncMiningUiSettledBoard(options.loopState, options.snapshotState, options.snapshotTipHeight, options.snapshotTipPreviousHashHex);
     return {
         targetBlockHeight,
         tipKey,
+        tipChanged,
     };
 }
 function setMiningUiCandidate(loopState, candidate) {
@@ -556,6 +629,123 @@ function clearSelectedCandidate(loopState) {
     loopState.selectedCandidateTipKey = null;
     loopState.selectedCandidate = null;
 }
+function clearMiningUiTransientCandidate(loopState) {
+    loopState.ui.provisionalRequiredWords = [];
+    loopState.ui.provisionalEntry = {
+        domainName: null,
+        sentence: null,
+    };
+    loopState.ui.latestSentence = null;
+}
+function discardMiningLoopTransientWork(loopState, walletRootId) {
+    clearMiningGateCache(walletRootId);
+    clearSelectedCandidate(loopState);
+    clearMiningUiTransientCandidate(loopState);
+    loopState.waitingNote = null;
+}
+function resolveMiningBitcoindRecoveryIdentity(value) {
+    const raw = (value ?? {});
+    return {
+        serviceInstanceId: raw.serviceInstanceId ?? null,
+        processId: raw.processId ?? raw.pid ?? null,
+    };
+}
+function miningBitcoindRecoveryIdentityMatches(left, right) {
+    if (left.serviceInstanceId !== null && right.serviceInstanceId !== null) {
+        return left.serviceInstanceId === right.serviceInstanceId;
+    }
+    if (left.processId !== null && right.processId !== null) {
+        return left.processId === right.processId;
+    }
+    return false;
+}
+function rememberMiningBitcoindRecoveryIdentity(loopState, value) {
+    const next = resolveMiningBitcoindRecoveryIdentity(value);
+    if (next.serviceInstanceId === null && next.processId === null) {
+        return false;
+    }
+    const previous = {
+        serviceInstanceId: loopState.bitcoinRecoveryServiceInstanceId,
+        processId: loopState.bitcoinRecoveryProcessId,
+    };
+    const changed = (previous.serviceInstanceId !== null
+        || previous.processId !== null) && !miningBitcoindRecoveryIdentityMatches(previous, next);
+    loopState.bitcoinRecoveryServiceInstanceId = next.serviceInstanceId ?? (next.processId !== null && previous.processId === next.processId
+        ? previous.serviceInstanceId
+        : null);
+    loopState.bitcoinRecoveryProcessId = next.processId ?? (next.serviceInstanceId !== null && previous.serviceInstanceId === next.serviceInstanceId
+        ? previous.processId
+        : null);
+    return changed;
+}
+function resetMiningBitcoindRecoveryState(loopState, value) {
+    const hadRecovery = loopState.bitcoinRecoveryFirstFailureAtUnixMs !== null;
+    loopState.bitcoinRecoveryFirstFailureAtUnixMs = null;
+    loopState.bitcoinRecoveryFirstUnreachableAtUnixMs = null;
+    loopState.bitcoinRecoveryLastRestartAttemptAtUnixMs = null;
+    if (value !== undefined) {
+        rememberMiningBitcoindRecoveryIdentity(loopState, value);
+    }
+    return hadRecovery;
+}
+function isMiningBitcoindRecoveryPidAlive(pid) {
+    if (pid === null || pid === undefined || !Number.isInteger(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "EPERM") {
+            return true;
+        }
+        return false;
+    }
+}
+function describeRecoverableMiningBitcoindError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isRecoverableMiningBitcoindError(error) {
+    if (isRetryableManagedRpcError(error)) {
+        return true;
+    }
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    if ("code" in error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ECONNREFUSED" || code === "ECONNRESET") {
+            return true;
+        }
+    }
+    return error.message === "managed_bitcoind_service_start_timeout"
+        || error.message === "bitcoind_cookie_timeout"
+        || error.message.includes("cookie file is unavailable")
+        || error.message.includes("cookie file could not be read")
+        || error.message.includes("ECONNREFUSED")
+        || error.message.includes("ECONNRESET")
+        || error.message.includes("socket hang up");
+}
+async function attachManagedBitcoindForRecovery(options) {
+    try {
+        const service = await options.attachService({
+            dataDir: options.dataDir,
+            chain: "main",
+            startHeight: 0,
+            walletRootId: options.walletRootId,
+        });
+        const serviceStatus = await service.refreshServiceStatus?.().catch(() => null);
+        rememberMiningBitcoindRecoveryIdentity(options.loopState, serviceStatus ?? { pid: service.pid });
+        return true;
+    }
+    catch (error) {
+        if (!isRecoverableMiningBitcoindError(error)) {
+            throw error;
+        }
+        return false;
+    }
+}
 async function resolveFundingDisplaySats(state, rpc) {
     const utxos = await rpc.listUnspent(state.managedCoreWallet.walletName, 0);
     return utxos.reduce((sum, entry) => {
@@ -604,6 +794,7 @@ function createIndexedMiningFollowVisualizerState(readContext) {
     const settledBoard = resolveCurrentMinedBlockBoard({
         snapshotState: readContext.snapshot?.state ?? null,
         snapshotTipHeight: readContext.snapshot?.tip?.height ?? readContext.indexer.snapshotTip?.height ?? null,
+        snapshotTipPreviousHashHex: readContext.snapshot?.tip?.previousHashHex ?? readContext.indexer.snapshotTip?.previousHashHex ?? null,
         nodeBestHeight: readContext.nodeStatus?.nodeBestHeight ?? null,
     });
     uiState.settledBlockHeight = settledBoard.settledBlockHeight;
@@ -925,6 +1116,8 @@ function buildStatusSnapshot(view, overrides = {}) {
         currentAbsoluteFeeSats: resolveSnapshotOverride(overrides.currentAbsoluteFeeSats, view.runtime.currentAbsoluteFeeSats),
         currentBlockFeeSpentSats: resolveSnapshotOverride(overrides.currentBlockFeeSpentSats, view.runtime.currentBlockFeeSpentSats),
         lastSuspendDetectedAtUnixMs: resolveSnapshotOverride(overrides.lastSuspendDetectedAtUnixMs, view.runtime.lastSuspendDetectedAtUnixMs),
+        reconnectSettledUntilUnixMs: resolveSnapshotOverride(overrides.reconnectSettledUntilUnixMs, view.runtime.reconnectSettledUntilUnixMs),
+        tipSettledUntilUnixMs: resolveSnapshotOverride(overrides.tipSettledUntilUnixMs, view.runtime.tipSettledUntilUnixMs),
         providerState: resolveSnapshotOverride(overrides.providerState, view.runtime.providerState),
         corePublishState: resolveSnapshotOverride(overrides.corePublishState, view.runtime.corePublishState),
         currentPublishDecision: resolveSnapshotOverride(overrides.currentPublishDecision, view.runtime.currentPublishDecision),
@@ -990,6 +1183,93 @@ async function refreshAndSaveStatus(options) {
 async function appendEvent(paths, event) {
     await appendMiningEvent(paths.miningEventsPath, event);
 }
+async function handleRecoverableMiningBitcoindFailure(options) {
+    const failureMessage = describeRecoverableMiningBitcoindError(options.error);
+    const walletRootId = options.readContext.localState.walletRootId ?? undefined;
+    if (options.loopState.bitcoinRecoveryFirstFailureAtUnixMs === null) {
+        options.loopState.bitcoinRecoveryFirstFailureAtUnixMs = options.nowUnixMs;
+    }
+    let restartedService = false;
+    const probe = await options.probeService({
+        dataDir: options.dataDir,
+        chain: "main",
+        startHeight: 0,
+        walletRootId,
+    }).catch((probeError) => {
+        if (!isRecoverableMiningBitcoindError(probeError)) {
+            throw probeError;
+        }
+        return null;
+    });
+    if (probe !== null) {
+        if (probe.compatibility === "compatible") {
+            rememberMiningBitcoindRecoveryIdentity(options.loopState, probe.status);
+            options.loopState.bitcoinRecoveryFirstUnreachableAtUnixMs = null;
+        }
+        else if (probe.compatibility === "unreachable") {
+            const identityChanged = rememberMiningBitcoindRecoveryIdentity(options.loopState, probe.status);
+            const livePid = isMiningBitcoindRecoveryPidAlive(probe.status?.processId ?? null);
+            if (identityChanged || options.loopState.bitcoinRecoveryFirstUnreachableAtUnixMs === null) {
+                options.loopState.bitcoinRecoveryFirstUnreachableAtUnixMs = options.nowUnixMs;
+            }
+            if (!livePid) {
+                restartedService = await attachManagedBitcoindForRecovery({
+                    dataDir: options.dataDir,
+                    walletRootId,
+                    attachService: options.attachService,
+                    loopState: options.loopState,
+                });
+            }
+            else {
+                const graceElapsed = (options.loopState.bitcoinRecoveryFirstUnreachableAtUnixMs !== null
+                    && options.nowUnixMs - options.loopState.bitcoinRecoveryFirstUnreachableAtUnixMs
+                        >= MINING_BITCOIN_RECOVERY_GRACE_MS);
+                const cooldownElapsed = (options.loopState.bitcoinRecoveryLastRestartAttemptAtUnixMs === null
+                    || options.nowUnixMs - options.loopState.bitcoinRecoveryLastRestartAttemptAtUnixMs
+                        >= MINING_BITCOIN_RECOVERY_RESTART_COOLDOWN_MS);
+                if (graceElapsed && cooldownElapsed) {
+                    options.loopState.bitcoinRecoveryLastRestartAttemptAtUnixMs = options.nowUnixMs;
+                    await options.stopService({
+                        dataDir: options.dataDir,
+                        walletRootId,
+                    }).catch((stopError) => {
+                        if (!isRecoverableMiningBitcoindError(stopError)) {
+                            throw stopError;
+                        }
+                    });
+                    await attachManagedBitcoindForRecovery({
+                        dataDir: options.dataDir,
+                        walletRootId,
+                        attachService: options.attachService,
+                        loopState: options.loopState,
+                    });
+                    restartedService = true;
+                }
+            }
+        }
+        else {
+            throw new Error(probe.error ?? "managed_bitcoind_protocol_error");
+        }
+    }
+    if (restartedService) {
+        discardMiningLoopTransientWork(options.loopState, walletRootId);
+        setMiningReconnectSettleWindow(options.loopState, options.nowUnixMs);
+    }
+    await refreshAndSaveStatus({
+        paths: options.paths,
+        provider: options.provider,
+        readContext: options.readContext,
+        overrides: {
+            runMode: options.runMode,
+            currentPhase: "waiting-bitcoin-network",
+            lastError: failureMessage,
+            note: MINING_BITCOIN_RECOVERY_NOTE,
+            ...buildMiningSettleWindowStatusOverrides(options.loopState, options.nowUnixMs),
+        },
+        visualizer: options.visualizer,
+        visualizerState: options.loopState.ui,
+    });
+}
 async function handleDetectedMiningRuntimeResume(options) {
     const readContext = await options.openReadContext({
         dataDir: options.dataDir,
@@ -999,6 +1279,7 @@ async function handleDetectedMiningRuntimeResume(options) {
     });
     try {
         clearMiningGateCache(readContext.localState.walletRootId);
+        setMiningReconnectSettleWindow(options.loopState, options.detectedAtUnixMs);
         await refreshAndSaveStatus({
             paths: options.paths,
             provider: options.provider,
@@ -1011,6 +1292,7 @@ async function handleDetectedMiningRuntimeResume(options) {
                 currentPhase: "resuming",
                 lastSuspendDetectedAtUnixMs: options.detectedAtUnixMs,
                 note: "Mining discarded stale in-flight work after a large local runtime gap and is rechecking health.",
+                ...buildMiningSettleWindowStatusOverrides(options.loopState, options.detectedAtUnixMs),
             },
             visualizer: options.visualizer,
             visualizerState: createIndexedMiningFollowVisualizerState(readContext),
@@ -1077,7 +1359,7 @@ function determineCorePublishState(info) {
 }
 function createMiningPlan(options) {
     const fundingUtxos = options.allUtxos.filter((entry) => entry.scriptPubKey === options.state.funding.scriptPubKeyHex
-        && entry.confirmations >= 1
+        && entry.confirmations >= MINING_FUNDING_MIN_CONF
         && entry.spendable !== false
         && entry.safe !== false
         && !(options.conflictOutpoint !== null
@@ -1130,6 +1412,7 @@ async function buildMiningTransaction(options) {
         finalizeErrorCode: "wallet_mining_finalize_failed",
         mempoolRejectPrefix: "wallet_mining_mempool_rejected",
         feeRate: options.plan.feeRateSatVb,
+        availableFundingMinConf: MINING_FUNDING_MIN_CONF,
     });
 }
 export function createMiningPlanForTesting(options) {
@@ -1206,11 +1489,36 @@ function createStaleMiningCandidateWaitingNote() {
 function createRetryableMiningPublishWaitingNote() {
     return "Selected mining candidate did not reach mempool and will be retried on the current tip with refreshed wallet state.";
 }
+const MINING_FUNDING_MIN_CONF = 0;
 function createInsufficientFundsMiningPublishWaitingNote() {
-    return "Mining is waiting for enough confirmed safe BTC funding that Bitcoin Core can use for the next publish.";
+    return "Mining is waiting for enough safe BTC funding that Bitcoin Core can use for the next publish.";
 }
 function createInsufficientFundsMiningPublishErrorMessage() {
-    return "Bitcoin Core could not fund the next mining publish with confirmed safe BTC.";
+    return "Bitcoin Core could not fund the next mining publish with safe BTC.";
+}
+function buildMiningGenerationRequest(options) {
+    return {
+        schemaVersion: 1,
+        requestId: options.requestId ?? `mining-${options.targetBlockHeight}-${randomBytes(8).toString("hex")}`,
+        targetBlockHeight: options.targetBlockHeight,
+        referencedBlockHashDisplay: options.referencedBlockHashDisplay,
+        generatedAtUnixMs: options.generatedAtUnixMs ?? Date.now(),
+        extraPrompt: options.extraPrompt,
+        limits: createMiningSentenceRequestLimits(),
+        rootDomains: options.domains.map((domain) => ({
+            domainId: domain.domainId,
+            domainName: domain.domainName,
+            requiredWords: domain.requiredWords,
+            extraPrompt: options.domainExtraPrompts[domain.domainName.toLowerCase()] ?? null,
+        })),
+    };
+}
+export function buildMiningGenerationRequestForTesting(options) {
+    return buildMiningGenerationRequest({
+        ...options,
+        domainExtraPrompts: options.domainExtraPrompts ?? {},
+        extraPrompt: options.extraPrompt ?? null,
+    });
 }
 async function generateCandidatesForDomains(options) {
     const bestBlockHash = options.readContext.nodeStatus?.nodeBestHashHex;
@@ -1223,6 +1531,10 @@ async function generateCandidatesForDomains(options) {
         ...domain,
         requiredWords: getWords(domain.domainId, referencedBlockHashInternal),
     }));
+    const clientConfig = await loadClientConfig({
+        path: options.paths.clientConfigPath,
+        provider: options.provider,
+    }).catch(() => null);
     const abortController = new AbortController();
     let stale = false;
     let staleIndexerTruth = false;
@@ -1261,20 +1573,13 @@ async function generateCandidatesForDomains(options) {
             runId: options.runId ?? null,
             pid: process.pid ?? null,
         });
-        const generationRequest = {
-            schemaVersion: 1,
-            requestId: `mining-${targetBlockHeight}-${randomBytes(8).toString("hex")}`,
+        const generationRequest = buildMiningGenerationRequest({
             targetBlockHeight,
             referencedBlockHashDisplay: bestBlockHash,
-            generatedAtUnixMs: Date.now(),
-            extraPrompt: null,
-            limits: createMiningSentenceRequestLimits(),
-            rootDomains: rootDomains.map((domain) => ({
-                domainId: domain.domainId,
-                domainName: domain.domainName,
-                requiredWords: domain.requiredWords,
-            })),
-        };
+            domains: rootDomains,
+            domainExtraPrompts: clientConfig?.mining.domainExtraPrompts ?? {},
+            extraPrompt: clientConfig?.mining.builtIn?.extraPrompt ?? null,
+        });
         let generated;
         try {
             generated = await generateMiningSentences(generationRequest, {
@@ -1418,6 +1723,7 @@ function toSentenceBoardEntries(entries) {
         rank: entry.rank,
         domainName: entry.domainName,
         sentence: entry.sentence,
+        requiredWords: resolveBip39WordsFromIndices(entry.bip39WordIndices),
     }));
 }
 async function runCompetitivenessGate(options) {
@@ -1839,7 +2145,6 @@ async function publishCandidateOnce(options) {
         dataDir: options.dataDir,
         chain: "main",
         startHeight: 0,
-        serviceLifetime: "ephemeral",
         walletRootId: options.readContext.localState.state.walletRootId,
     });
     const rpc = options.rpcFactory(service.rpc);
@@ -1850,7 +2155,7 @@ async function publishCandidateOnce(options) {
         nodeBestHeight: options.readContext.nodeStatus?.nodeBestHeight ?? null,
         snapshotState: options.readContext.snapshot.state,
     })).state;
-    const allUtxos = await rpc.listUnspent(state.managedCoreWallet.walletName, 0);
+    const allUtxos = await rpc.listUnspent(state.managedCoreWallet.walletName, MINING_FUNDING_MIN_CONF);
     const conflictOutpoint = resolveMiningConflictOutpoint({
         state,
         allUtxos,
@@ -2120,7 +2425,7 @@ async function publishCandidate(options) {
             if (isInsufficientFundsError(error)) {
                 const note = createInsufficientFundsMiningPublishWaitingNote();
                 const lastError = createInsufficientFundsMiningPublishErrorMessage();
-                await appendEventFn(options.paths, createEvent("publish-paused-insufficient-funds", "Paused mining publish because Bitcoin Core could not fund the next mining transaction with confirmed safe BTC.", {
+                await appendEventFn(options.paths, createEvent("publish-paused-insufficient-funds", "Paused mining publish because Bitcoin Core could not fund the next mining transaction with safe BTC.", {
                     level: "warn",
                     runId: options.runId,
                     targetBlockHeight: refreshedCandidate.targetBlockHeight,
@@ -2169,6 +2474,7 @@ export async function ensureBuiltInMiningSetupIfNeeded(options) {
     return true;
 }
 async function performMiningCycle(options) {
+    const now = options.nowImpl ?? Date.now;
     let readContext = await options.openReadContext({
         dataDir: options.dataDir,
         databasePath: options.databasePath,
@@ -2177,30 +2483,39 @@ async function performMiningCycle(options) {
     });
     let readContextClosed = false;
     try {
-        checkpointMiningSuspendDetector(options.suspendDetector);
-        await refreshAndSaveStatus({
-            paths: options.paths,
-            provider: options.provider,
-            readContext,
-            overrides: {
-                runMode: options.runMode,
-                backgroundWorkerPid: options.backgroundWorkerPid,
-                backgroundWorkerRunId: options.backgroundWorkerRunId,
-                backgroundWorkerHeartbeatAtUnixMs: options.runMode === "background" ? Date.now() : null,
-            },
-        });
-        if (readContext.localState.availability !== "ready" || readContext.localState.state === null) {
-            await refreshAndSaveStatus({
+        let clearRecoveredBitcoindError = false;
+        const saveCycleStatus = async (readContext, overrides, includeVisualizer = true) => {
+            const statusNowUnixMs = now();
+            const resolvedOverrides = clearRecoveredBitcoindError && overrides.lastError === undefined
+                ? {
+                    ...overrides,
+                    lastError: null,
+                }
+                : overrides;
+            return await refreshAndSaveStatus({
                 paths: options.paths,
                 provider: options.provider,
                 readContext,
                 overrides: {
-                    runMode: options.runMode,
-                    currentPhase: "waiting",
-                    note: "Wallet state must be locally available for mining to continue.",
+                    ...buildMiningSettleWindowStatusOverrides(options.loopState, statusNowUnixMs),
+                    ...resolvedOverrides,
                 },
-                visualizer: options.visualizer,
-                visualizerState: options.loopState.ui,
+                visualizer: includeVisualizer ? options.visualizer : undefined,
+                visualizerState: includeVisualizer ? options.loopState.ui : undefined,
+            });
+        };
+        checkpointMiningSuspendDetector(options.suspendDetector);
+        await saveCycleStatus(readContext, {
+            runMode: options.runMode,
+            backgroundWorkerPid: options.backgroundWorkerPid,
+            backgroundWorkerRunId: options.backgroundWorkerRunId,
+            backgroundWorkerHeartbeatAtUnixMs: options.runMode === "background" ? now() : null,
+        }, false);
+        if (readContext.localState.availability !== "ready" || readContext.localState.state === null) {
+            await saveCycleStatus(readContext, {
+                runMode: options.runMode,
+                currentPhase: "waiting",
+                note: "Wallet state must be locally available for mining to continue.",
             });
             return;
         }
@@ -2208,7 +2523,6 @@ async function performMiningCycle(options) {
             dataDir: options.dataDir,
             chain: "main",
             startHeight: 0,
-            serviceLifetime: "ephemeral",
             walletRootId: readContext.localState.state.walletRootId,
         });
         checkpointMiningSuspendDetector(options.suspendDetector);
@@ -2251,28 +2565,25 @@ async function performMiningCycle(options) {
             indexedTipHashHex: indexedTip?.blockHashHex ?? null,
         }).catch(() => ({}));
         syncMiningVisualizerBlockTimes(options.loopState, visibleBlockTimes);
-        const { targetBlockHeight, tipKey } = syncMiningUiForCurrentTip({
+        const { targetBlockHeight, tipKey, tipChanged } = syncMiningUiForCurrentTip({
             loopState: options.loopState,
             snapshotState: effectiveReadContext.snapshot?.state ?? null,
             snapshotTipHeight: effectiveReadContext.snapshot?.tip?.height ?? effectiveReadContext.indexer.snapshotTip?.height ?? null,
+            snapshotTipPreviousHashHex: effectiveReadContext.snapshot?.tip?.previousHashHex ?? effectiveReadContext.indexer.snapshotTip?.previousHashHex ?? null,
             nodeBestHeight: effectiveReadContext.nodeStatus?.nodeBestHeight ?? null,
             nodeBestHash: effectiveReadContext.nodeStatus?.nodeBestHashHex ?? null,
             recentWin: reconciliation.recentWin,
         });
+        if (tipChanged) {
+            setMiningTipSettleWindow(options.loopState, now());
+        }
         const displaySats = await resolveFundingDisplaySats(effectiveReadContext.localState.state, rpc).catch(() => null);
         syncMiningVisualizerBalances(options.loopState, effectiveReadContext, displaySats);
         if (effectiveReadContext.localState.state.miningState.state === "repair-required") {
-            await refreshAndSaveStatus({
-                paths: options.paths,
-                provider: options.provider,
-                readContext: effectiveReadContext,
-                overrides: {
-                    runMode: options.runMode,
-                    currentPhase: "waiting",
-                    note: "Mining is blocked until the current mining publish is repaired or reconciled.",
-                },
-                visualizer: options.visualizer,
-                visualizerState: options.loopState.ui,
+            await saveCycleStatus(effectiveReadContext, {
+                runMode: options.runMode,
+                currentPhase: "waiting",
+                note: "Mining is blocked until the current mining publish is repaired or reconciled.",
             });
             return;
         }
@@ -2294,17 +2605,10 @@ async function performMiningCycle(options) {
                     state: nextState,
                 },
             };
-            await refreshAndSaveStatus({
-                paths: options.paths,
-                provider: options.provider,
-                readContext: effectiveReadContext,
-                overrides: {
-                    runMode: options.runMode,
-                    currentPhase: "waiting",
-                    note: "Mining is paused while another wallet mutation is active.",
-                },
-                visualizer: options.visualizer,
-                visualizerState: options.loopState.ui,
+            await saveCycleStatus(effectiveReadContext, {
+                runMode: options.runMode,
+                currentPhase: "waiting",
+                note: "Mining is paused while another wallet mutation is active.",
             });
             return;
         }
@@ -2322,23 +2626,16 @@ async function performMiningCycle(options) {
                 provider: options.provider,
                 paths: options.paths,
             });
-            await refreshAndSaveStatus({
-                paths: options.paths,
-                provider: options.provider,
-                readContext: {
-                    ...effectiveReadContext,
-                    localState: {
-                        ...effectiveReadContext.localState,
-                        state: nextState,
-                    },
-                },
-                overrides: {
-                    runMode: options.runMode,
-                    currentPhase: "waiting",
-                    note: "Mining is paused while another wallet command is preempting sentence generation.",
+            await saveCycleStatus({
+                ...effectiveReadContext,
+                localState: {
+                    ...effectiveReadContext.localState,
+                    state: nextState,
                 },
-                visualizer: options.visualizer,
-                visualizerState: options.loopState.ui,
+            }, {
+                runMode: options.runMode,
+                currentPhase: "waiting",
+                note: "Mining is paused while another wallet command is preempting sentence generation.",
             });
             return;
         }
@@ -2353,53 +2650,33 @@ async function performMiningCycle(options) {
             network: networkInfo,
             mempool: mempoolInfo,
         });
+        clearRecoveredBitcoindError = resetMiningBitcoindRecoveryState(options.loopState, effectiveReadContext.nodeStatus?.serviceStatus ?? { pid: service.pid });
         if (corePublishState !== "healthy") {
-            await refreshAndSaveStatus({
-                paths: options.paths,
-                provider: options.provider,
-                readContext: effectiveReadContext,
-                overrides: {
-                    runMode: options.runMode,
-                    currentPhase: "waiting-bitcoin-network",
-                    corePublishState,
-                    note: "Mining is waiting for the local Bitcoin node to become publishable.",
-                },
-                visualizer: options.visualizer,
-                visualizerState: options.loopState.ui,
+            await saveCycleStatus(effectiveReadContext, {
+                runMode: options.runMode,
+                currentPhase: "waiting-bitcoin-network",
+                corePublishState,
+                note: "Mining is waiting for the local Bitcoin node to become publishable.",
             });
             return;
         }
         if (effectiveReadContext.indexer.health !== "synced" || effectiveReadContext.nodeHealth !== "synced") {
-            await refreshAndSaveStatus({
-                paths: options.paths,
-                provider: options.provider,
-                readContext: effectiveReadContext,
-                overrides: {
-                    runMode: options.runMode,
-                    currentPhase: effectiveReadContext.indexer.health !== "synced"
-                        ? "waiting-indexer"
-                        : "waiting-bitcoin-network",
-                    note: effectiveReadContext.indexer.health !== "synced"
-                        ? "Mining is waiting for Bitcoin Core and the indexer to align."
-                        : "Mining is waiting for the local Bitcoin node to become publishable.",
-                },
-                visualizer: options.visualizer,
-                visualizerState: options.loopState.ui,
+            await saveCycleStatus(effectiveReadContext, {
+                runMode: options.runMode,
+                currentPhase: effectiveReadContext.indexer.health !== "synced"
+                    ? "waiting-indexer"
+                    : "waiting-bitcoin-network",
+                note: effectiveReadContext.indexer.health !== "synced"
+                    ? "Mining is waiting for Bitcoin Core and the indexer to align."
+                    : "Mining is waiting for the local Bitcoin node to become publishable.",
             });
             return;
         }
         if (targetBlockHeight === null) {
-            await refreshAndSaveStatus({
-                paths: options.paths,
-                provider: options.provider,
-                readContext: effectiveReadContext,
-                overrides: {
-                    runMode: options.runMode,
-                    currentPhase: "waiting-bitcoin-network",
-                    note: "Mining is waiting for the local Bitcoin node to become publishable.",
-                },
-                visualizer: options.visualizer,
-                visualizerState: options.loopState.ui,
+            await saveCycleStatus(effectiveReadContext, {
+                runMode: options.runMode,
+                currentPhase: "waiting-bitcoin-network",
+                note: "Mining is waiting for the local Bitcoin node to become publishable.",
             });
             return;
         }
@@ -2413,24 +2690,17 @@ async function performMiningCycle(options) {
                 provider: options.provider,
                 paths: options.paths,
             });
-            await refreshAndSaveStatus({
-                paths: options.paths,
-                provider: options.provider,
-                readContext: {
-                    ...effectiveReadContext,
-                    localState: {
-                        ...effectiveReadContext.localState,
-                        state: nextState,
-                    },
-                },
-                overrides: {
-                    runMode: options.runMode,
-                    currentPhase: "idle",
-                    currentPublishDecision: "publish-skipped-zero-reward",
-                    note: "Mining is disabled because the target block reward is zero.",
+            await saveCycleStatus({
+                ...effectiveReadContext,
+                localState: {
+                    ...effectiveReadContext.localState,
+                    state: nextState,
                 },
-                visualizer: options.visualizer,
-                visualizerState: options.loopState.ui,
+            }, {
+                runMode: options.runMode,
+                currentPhase: "idle",
+                currentPublishDecision: "publish-skipped-zero-reward",
+                note: "Mining is disabled because the target block reward is zero.",
             });
             await appendEvent(options.paths, createEvent("publish-skipped-zero-reward", "Skipped mining because the target block reward is zero.", {
                 targetBlockHeight,
@@ -2440,17 +2710,10 @@ async function performMiningCycle(options) {
             return;
         }
         if (tipKey !== null && options.loopState.attemptedTipKey === tipKey) {
-            await refreshAndSaveStatus({
-                paths: options.paths,
-                provider: options.provider,
-                readContext: effectiveReadContext,
-                overrides: {
-                    runMode: options.runMode,
-                    currentPhase: "waiting",
-                    note: options.loopState.waitingNote ?? "Waiting for the next block after the last mining attempt on this tip.",
-                },
-                visualizer: options.visualizer,
-                visualizerState: options.loopState.ui,
+            await saveCycleStatus(effectiveReadContext, {
+                runMode: options.runMode,
+                currentPhase: "waiting",
+                note: options.loopState.waitingNote ?? "Waiting for the next block after the last mining attempt on this tip.",
             });
             return;
         }
@@ -2488,31 +2751,17 @@ async function performMiningCycle(options) {
         if (selectedCandidate === null) {
             const domains = resolveEligibleAnchoredRoots(effectiveReadContext);
             if (domains.length === 0) {
-                await refreshAndSaveStatus({
-                    paths: options.paths,
-                    provider: options.provider,
-                    readContext: effectiveReadContext,
-                    overrides: {
-                        runMode: options.runMode,
-                        currentPhase: "idle",
-                        note: "No locally controlled anchored root domains are currently eligible to mine.",
-                    },
-                    visualizer: options.visualizer,
-                    visualizerState: options.loopState.ui,
+                await saveCycleStatus(effectiveReadContext, {
+                    runMode: options.runMode,
+                    currentPhase: "idle",
+                    note: "No locally controlled anchored root domains are currently eligible to mine.",
                 });
                 return;
             }
-            await refreshAndSaveStatus({
-                paths: options.paths,
-                provider: options.provider,
-                readContext: effectiveReadContext,
-                overrides: {
-                    runMode: options.runMode,
-                    currentPhase: "generating",
-                    note: "Generating mining sentences for eligible root domains.",
-                },
-                visualizer: options.visualizer,
-                visualizerState: options.loopState.ui,
+            await saveCycleStatus(effectiveReadContext, {
+                runMode: options.runMode,
+                currentPhase: "generating",
+                note: "Generating mining sentences for eligible root domains.",
             });
             await appendEvent(options.paths, createEvent("sentence-generation-start", "Started mining sentence generation.", {
                 targetBlockHeight,
@@ -2539,19 +2788,12 @@ async function performMiningCycle(options) {
                         options.loopState.attemptedTipKey = tipKey;
                         options.loopState.waitingNote = "Mining is waiting for the sentence provider to recover.";
                     }
-                    await refreshAndSaveStatus({
-                        paths: options.paths,
-                        provider: options.provider,
-                        readContext: effectiveReadContext,
-                        overrides: {
-                            runMode: options.runMode,
-                            currentPhase: "waiting-provider",
-                            providerState: error.providerState,
-                            lastError: error.message,
-                            note: "Mining is waiting for the sentence provider to recover.",
-                        },
-                        visualizer: options.visualizer,
-                        visualizerState: options.loopState.ui,
+                    await saveCycleStatus(effectiveReadContext, {
+                        runMode: options.runMode,
+                        currentPhase: "waiting-provider",
+                        providerState: error.providerState,
+                        lastError: error.message,
+                        note: "Mining is waiting for the sentence provider to recover.",
                     });
                     await appendEvent(options.paths, createEvent("publish-paused-provider", error.message, {
                         level: "warn",
@@ -2594,19 +2836,12 @@ async function performMiningCycle(options) {
                     options.loopState.attemptedTipKey = tipKey;
                     options.loopState.waitingNote = "Mining sentence generation failed for the current tip.";
                 }
-                await refreshAndSaveStatus({
-                    paths: options.paths,
-                    provider: options.provider,
-                    readContext: effectiveReadContext,
-                    overrides: {
-                        runMode: options.runMode,
-                        currentPhase: "waiting-provider",
-                        providerState: "unavailable",
-                        lastError: failureMessage,
-                        note: "Mining sentence generation failed for the current tip.",
-                    },
-                    visualizer: options.visualizer,
-                    visualizerState: options.loopState.ui,
+                await saveCycleStatus(effectiveReadContext, {
+                    runMode: options.runMode,
+                    currentPhase: "waiting-provider",
+                    providerState: "unavailable",
+                    lastError: failureMessage,
+                    note: "Mining sentence generation failed for the current tip.",
                 });
                 await appendEvent(options.paths, createEvent("sentence-generation-failed", failureMessage, {
                     level: "error",
@@ -2616,17 +2851,10 @@ async function performMiningCycle(options) {
                 }));
                 return;
             }
-            await refreshAndSaveStatus({
-                paths: options.paths,
-                provider: options.provider,
-                readContext: effectiveReadContext,
-                overrides: {
-                    runMode: options.runMode,
-                    currentPhase: "scoring",
-                    note: "Scoring mining candidates for the current tip.",
-                },
-                visualizer: options.visualizer,
-                visualizerState: options.loopState.ui,
+            await saveCycleStatus(effectiveReadContext, {
+                runMode: options.runMode,
+                currentPhase: "scoring",
+                note: "Scoring mining candidates for the current tip.",
             });
             const best = await chooseBestLocalCandidate(candidates);
             if (best === null) {
@@ -2635,18 +2863,11 @@ async function performMiningCycle(options) {
                     options.loopState.waitingNote = "No publishable mining candidate passed scoring gates for the current tip.";
                 }
                 clearSelectedCandidate(options.loopState);
-                await refreshAndSaveStatus({
-                    paths: options.paths,
-                    provider: options.provider,
-                    readContext: effectiveReadContext,
-                    overrides: {
-                        runMode: options.runMode,
-                        currentPhase: "idle",
-                        currentPublishDecision: "publish-skipped-no-candidate",
-                        note: "No publishable mining candidate passed scoring gates for the current tip.",
-                    },
-                    visualizer: options.visualizer,
-                    visualizerState: options.loopState.ui,
+                await saveCycleStatus(effectiveReadContext, {
+                    runMode: options.runMode,
+                    currentPhase: "idle",
+                    currentPublishDecision: "publish-skipped-no-candidate",
+                    note: "No publishable mining candidate passed scoring gates for the current tip.",
                 });
                 await appendEvent(options.paths, createEvent("publish-skipped-no-candidate", "No publishable mining candidate passed scoring gates.", {
                     targetBlockHeight,
@@ -2693,25 +2914,18 @@ async function performMiningCycle(options) {
                     : gate.decision === "suppressed-top5-mempool"
                         ? `Best local sentence found, but ${gate.higherRankedCompetitorDomainCount} stronger competitor root domains are already in mempool.`
                         : "Mining skipped this tick because the mempool competitiveness gate could not be verified safely.";
-                await refreshAndSaveStatus({
-                    paths: options.paths,
-                    provider: options.provider,
-                    readContext: effectiveReadContext,
-                    overrides: {
-                        runMode: options.runMode,
-                        currentPhase: "waiting",
-                        currentPublishDecision: gate.decision,
-                        sameDomainCompetitorSuppressed: gate.sameDomainCompetitorSuppressed,
-                        higherRankedCompetitorDomainCount: gate.higherRankedCompetitorDomainCount,
-                        dedupedCompetitorDomainCount: gate.dedupedCompetitorDomainCount,
-                        competitivenessGateIndeterminate: gate.competitivenessGateIndeterminate,
-                        mempoolSequenceCacheStatus: gate.mempoolSequenceCacheStatus,
-                        lastMempoolSequence: gate.lastMempoolSequence,
-                        lastCompetitivenessGateAtUnixMs: Date.now(),
-                        note: options.loopState.waitingNote,
-                    },
-                    visualizer: options.visualizer,
-                    visualizerState: options.loopState.ui,
+                await saveCycleStatus(effectiveReadContext, {
+                    runMode: options.runMode,
+                    currentPhase: "waiting",
+                    currentPublishDecision: gate.decision,
+                    sameDomainCompetitorSuppressed: gate.sameDomainCompetitorSuppressed,
+                    higherRankedCompetitorDomainCount: gate.higherRankedCompetitorDomainCount,
+                    dedupedCompetitorDomainCount: gate.dedupedCompetitorDomainCount,
+                    competitivenessGateIndeterminate: gate.competitivenessGateIndeterminate,
+                    mempoolSequenceCacheStatus: gate.mempoolSequenceCacheStatus,
+                    lastMempoolSequence: gate.lastMempoolSequence,
+                    lastCompetitivenessGateAtUnixMs: now(),
+                    note: options.loopState.waitingNote,
                 });
                 await appendEvent(options.paths, createEvent(gate.decision === "suppressed-same-domain-mempool"
                     ? "publish-skipped-same-domain-mempool"
@@ -2740,19 +2954,12 @@ async function performMiningCycle(options) {
         if (!await ensureCurrentIndexerTruthOrRestart()) {
             return;
         }
-        await refreshAndSaveStatus({
-            paths: options.paths,
-            provider: options.provider,
-            readContext: effectiveReadContext,
-            overrides: {
-                runMode: options.runMode,
-                ...buildPrePublishStatusOverrides({
-                    state: effectiveReadContext.localState.state,
-                    candidate: selectedCandidate,
-                }),
-            },
-            visualizer: options.visualizer,
-            visualizerState: options.loopState.ui,
+        await saveCycleStatus(effectiveReadContext, {
+            runMode: options.runMode,
+            ...buildPrePublishStatusOverrides({
+                state: effectiveReadContext.localState.state,
+                candidate: selectedCandidate,
+            }),
         });
         const publishLock = await acquireFileLock(options.paths.walletControlLockPath, {
             purpose: "wallet-mine",
@@ -2783,32 +2990,25 @@ async function performMiningCycle(options) {
             if (published.retryable === true) {
                 cacheSelectedCandidateForTip(options.loopState, tipKey, published.candidate);
                 options.loopState.waitingNote = published.note;
-                await refreshAndSaveStatus({
-                    paths: options.paths,
-                    provider: options.provider,
-                    readContext: {
-                        ...effectiveReadContext,
-                        localState: {
-                            ...effectiveReadContext.localState,
-                            state: published.state,
-                        },
-                    },
-                    overrides: {
-                        runMode: options.runMode,
-                        currentPhase: "waiting",
-                        currentPublishDecision: published.decision,
-                        sameDomainCompetitorSuppressed: false,
-                        higherRankedCompetitorDomainCount: gateSnapshot.higherRankedCompetitorDomainCount,
-                        dedupedCompetitorDomainCount: gateSnapshot.dedupedCompetitorDomainCount,
-                        competitivenessGateIndeterminate: false,
-                        mempoolSequenceCacheStatus: gateSnapshot.mempoolSequenceCacheStatus,
-                        lastMempoolSequence: gateSnapshot.lastMempoolSequence,
-                        lastCompetitivenessGateAtUnixMs: Date.now(),
-                        note: published.note,
-                        livePublishInMempool: published.state.miningState.livePublishInMempool,
+                await saveCycleStatus({
+                    ...effectiveReadContext,
+                    localState: {
+                        ...effectiveReadContext.localState,
+                        state: published.state,
                     },
-                    visualizer: options.visualizer,
-                    visualizerState: options.loopState.ui,
+                }, {
+                    runMode: options.runMode,
+                    currentPhase: "waiting",
+                    currentPublishDecision: published.decision,
+                    sameDomainCompetitorSuppressed: false,
+                    higherRankedCompetitorDomainCount: gateSnapshot.higherRankedCompetitorDomainCount,
+                    dedupedCompetitorDomainCount: gateSnapshot.dedupedCompetitorDomainCount,
+                    competitivenessGateIndeterminate: false,
+                    mempoolSequenceCacheStatus: gateSnapshot.mempoolSequenceCacheStatus,
+                    lastMempoolSequence: gateSnapshot.lastMempoolSequence,
+                    lastCompetitivenessGateAtUnixMs: now(),
+                    note: published.note,
+                    livePublishInMempool: published.state.miningState.livePublishInMempool,
                 });
                 return;
             }
@@ -2819,33 +3019,26 @@ async function performMiningCycle(options) {
                 const lastError = published.decision === "publish-paused-insufficient-funds"
                     ? published.lastError ?? createInsufficientFundsMiningPublishErrorMessage()
                     : undefined;
-                await refreshAndSaveStatus({
-                    paths: options.paths,
-                    provider: options.provider,
-                    readContext: {
-                        ...effectiveReadContext,
-                        localState: {
-                            ...effectiveReadContext.localState,
-                            state: published.state,
-                        },
-                    },
-                    overrides: {
-                        runMode: options.runMode,
-                        currentPhase: "waiting",
-                        currentPublishDecision: published.decision,
-                        sameDomainCompetitorSuppressed: false,
-                        higherRankedCompetitorDomainCount: gateSnapshot.higherRankedCompetitorDomainCount,
-                        dedupedCompetitorDomainCount: gateSnapshot.dedupedCompetitorDomainCount,
-                        competitivenessGateIndeterminate: false,
-                        mempoolSequenceCacheStatus: gateSnapshot.mempoolSequenceCacheStatus,
-                        lastMempoolSequence: gateSnapshot.lastMempoolSequence,
-                        lastCompetitivenessGateAtUnixMs: Date.now(),
-                        lastError,
-                        note: published.note,
-                        livePublishInMempool: published.state.miningState.livePublishInMempool,
+                await saveCycleStatus({
+                    ...effectiveReadContext,
+                    localState: {
+                        ...effectiveReadContext.localState,
+                        state: published.state,
                     },
-                    visualizer: options.visualizer,
-                    visualizerState: options.loopState.ui,
+                }, {
+                    runMode: options.runMode,
+                    currentPhase: "waiting",
+                    currentPublishDecision: published.decision,
+                    sameDomainCompetitorSuppressed: false,
+                    higherRankedCompetitorDomainCount: gateSnapshot.higherRankedCompetitorDomainCount,
+                    dedupedCompetitorDomainCount: gateSnapshot.dedupedCompetitorDomainCount,
+                    competitivenessGateIndeterminate: false,
+                    mempoolSequenceCacheStatus: gateSnapshot.mempoolSequenceCacheStatus,
+                    lastMempoolSequence: gateSnapshot.lastMempoolSequence,
+                    lastCompetitivenessGateAtUnixMs: now(),
+                    lastError,
+                    note: published.note,
+                    livePublishInMempool: published.state.miningState.livePublishInMempool,
                 });
                 return;
             }
@@ -2861,32 +3054,25 @@ async function performMiningCycle(options) {
                     : `Mining candidate ${published.decision === "replaced"
                         ? "replaced"
                         : "broadcast"} as ${published.txid}. Waiting for the next block.`;
-            await refreshAndSaveStatus({
-                paths: options.paths,
-                provider: options.provider,
-                readContext: {
-                    ...effectiveReadContext,
-                    localState: {
-                        ...effectiveReadContext.localState,
-                        state: published.state,
-                    },
-                },
-                overrides: {
-                    runMode: options.runMode,
-                    currentPhase: "waiting",
-                    currentPublishDecision: published.decision,
-                    sameDomainCompetitorSuppressed: false,
-                    higherRankedCompetitorDomainCount: gateSnapshot.higherRankedCompetitorDomainCount,
-                    dedupedCompetitorDomainCount: gateSnapshot.dedupedCompetitorDomainCount,
-                    competitivenessGateIndeterminate: false,
-                    mempoolSequenceCacheStatus: gateSnapshot.mempoolSequenceCacheStatus,
-                    lastMempoolSequence: gateSnapshot.lastMempoolSequence,
-                    lastCompetitivenessGateAtUnixMs: Date.now(),
-                    note: options.loopState.waitingNote,
-                    livePublishInMempool: published.state.miningState.livePublishInMempool,
+            await saveCycleStatus({
+                ...effectiveReadContext,
+                localState: {
+                    ...effectiveReadContext.localState,
+                    state: published.state,
                 },
-                visualizer: options.visualizer,
-                visualizerState: options.loopState.ui,
+            }, {
+                runMode: options.runMode,
+                currentPhase: "waiting",
+                currentPublishDecision: published.decision,
+                sameDomainCompetitorSuppressed: false,
+                higherRankedCompetitorDomainCount: gateSnapshot.higherRankedCompetitorDomainCount,
+                dedupedCompetitorDomainCount: gateSnapshot.dedupedCompetitorDomainCount,
+                competitivenessGateIndeterminate: false,
+                mempoolSequenceCacheStatus: gateSnapshot.mempoolSequenceCacheStatus,
+                lastMempoolSequence: gateSnapshot.lastMempoolSequence,
+                lastCompetitivenessGateAtUnixMs: now(),
+                note: options.loopState.waitingNote,
+                livePublishInMempool: published.state.miningState.livePublishInMempool,
             });
         }
         finally {
@@ -2895,6 +3081,7 @@ async function performMiningCycle(options) {
     }
     catch (error) {
         if (error instanceof MiningSuspendDetectedError) {
+            discardMiningLoopTransientWork(options.loopState, readContext?.localState.walletRootId ?? undefined);
             if (readContext !== null && !readContextClosed) {
                 await readContext.close();
                 readContextClosed = true;
@@ -2910,6 +3097,24 @@ async function performMiningCycle(options) {
                 detectedAtUnixMs: error.detectedAtUnixMs,
                 openReadContext: options.openReadContext,
                 visualizer: options.visualizer,
+                loopState: options.loopState,
+            });
+            return;
+        }
+        if (readContext !== null && isRecoverableMiningBitcoindError(error)) {
+            await handleRecoverableMiningBitcoindFailure({
+                error,
+                dataDir: options.dataDir,
+                provider: options.provider,
+                paths: options.paths,
+                runMode: options.runMode,
+                readContext,
+                loopState: options.loopState,
+                attachService: options.attachService,
+                probeService: options.probeService,
+                stopService: options.stopService,
+                nowUnixMs: now(),
+                visualizer: options.visualizer,
             });
             return;
         }
@@ -2935,7 +3140,6 @@ async function saveStopSnapshot(options) {
                 dataDir: options.dataDir,
                 chain: "main",
                 startHeight: 0,
-                serviceLifetime: "ephemeral",
                 walletRootId: localState.state.walletRootId,
             }).catch(() => null);
             if (service !== null) {
@@ -3012,6 +3216,9 @@ async function attemptSaveMempool(rpc, paths, runId) {
 async function runMiningLoop(options) {
     const suspendDetector = createMiningSuspendDetector();
     const loopState = createMiningLoopState();
+    const probeService = options.probeService ?? probeManagedBitcoindService;
+    const stopService = options.stopService ?? stopManagedBitcoindService;
+    const sleepImpl = options.sleepImpl ?? sleep;
     await appendEvent(options.paths, createEvent("runtime-start", `Started ${options.runMode} mining runtime.`, {
         runId: options.backgroundWorkerRunId,
     }));
@@ -3023,6 +3230,7 @@ async function runMiningLoop(options) {
             if (!(error instanceof MiningSuspendDetectedError)) {
                 throw error;
             }
+            discardMiningLoopTransientWork(loopState, null);
             await handleDetectedMiningRuntimeResume({
                 dataDir: options.dataDir,
                 databasePath: options.databasePath,
@@ -3034,6 +3242,7 @@ async function runMiningLoop(options) {
                 detectedAtUnixMs: error.detectedAtUnixMs,
                 openReadContext: options.openReadContext,
                 visualizer: options.visualizer,
+                loopState,
             });
             continue;
         }
@@ -3041,14 +3250,15 @@ async function runMiningLoop(options) {
             ...options,
             suspendDetector,
             loopState,
+            probeService,
+            stopService,
         });
-        await sleep(Math.min(MINING_LOOP_INTERVAL_MS, MINING_STATUS_HEARTBEAT_INTERVAL_MS), options.signal);
+        await sleepImpl(Math.min(MINING_LOOP_INTERVAL_MS, MINING_STATUS_HEARTBEAT_INTERVAL_MS), options.signal);
     }
     const service = await options.attachService({
         dataDir: options.dataDir,
         chain: "main",
         startHeight: 0,
-        serviceLifetime: "ephemeral",
         walletRootId: undefined,
     }).catch(() => null);
     if (service !== null) {
@@ -3117,6 +3327,8 @@ export async function runForegroundMining(options) {
             sleepImpl: options.sleepImpl,
         });
         visualizer = new MiningFollowVisualizer({
+            clientVersion: options.clientVersion,
+            updateAvailable: options.updateAvailable,
             progressOutput: options.progressOutput ?? "auto",
             stream: options.stderr,
         });
@@ -3346,7 +3558,10 @@ export async function runBackgroundMiningWorker(options) {
     });
 }
 export async function handleDetectedMiningRuntimeResumeForTesting(options) {
-    await handleDetectedMiningRuntimeResume(options);
+    await handleDetectedMiningRuntimeResume({
+        ...options,
+        loopState: options.loopState ?? createMiningLoopState(),
+    });
 }
 export async function takeOverMiningRuntimeForTesting(options) {
     return await takeOverMiningRuntime(options);
@@ -3354,9 +3569,16 @@ export async function takeOverMiningRuntimeForTesting(options) {
 export async function performMiningCycleForTesting(options) {
     await performMiningCycle({
         ...options,
+        probeService: options.probeService ?? probeManagedBitcoindService,
+        stopService: options.stopService ?? stopManagedBitcoindService,
         loopState: options.loopState ?? createMiningLoopState(),
     });
 }
+export async function runMiningLoopForTesting(options) {
+    await runMiningLoop({
+        ...options,
+    });
+}
 export function buildPrePublishStatusOverridesForTesting(options) {
     return buildPrePublishStatusOverrides(options);
 }