@cogcoin/client 1.0.1 → 1.1.0

package/dist/wallet/mining/runner.js

@@ -1,16 +1,20 @@
 import { createHash, randomBytes } from "node:crypto";
 import { spawn } from "node:child_process";
+import { rm } from "node:fs/promises";
+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";
-import { assertFixedInputPrefixMatches, buildWalletMutationTransaction, outpointKey as walletMutationOutpointKey, isAlreadyAcceptedError, isBroadcastUnknownError, reconcilePersistentPolicyLocks, resolveWalletMutationFeeSelection, saveWalletStatePreservingUnlock, } from "../tx/common.js";
-import { acquireFileLock } from "../fs/lock.js";
+import { assertFixedInputPrefixMatches, buildWalletMutationTransaction, isInsufficientFundsError, outpointKey as walletMutationOutpointKey, isAlreadyAcceptedError, isBroadcastUnknownError, reconcilePersistentPolicyLocks, resolveWalletMutationFeeSelection, saveWalletStatePreservingUnlock, } from "../tx/common.js";
+import { FileLockBusyError, acquireFileLock, clearOrphanedFileLock, readLockMetadata, } from "../fs/lock.js";
 import { isMineableWalletDomain, openWalletReadContext, } from "../read/index.js";
 import { resolveWalletRuntimePathsForTesting } from "../runtime.js";
 import { createDefaultWalletSecretProvider, } from "../state/provider.js";
@@ -19,13 +23,45 @@ import { appendMiningEvent, loadMiningRuntimeStatus, saveMiningRuntimeStatus, }
 import { loadClientConfig } from "./config.js";
 import { MINING_LOOP_INTERVAL_MS, MINING_NETWORK_SETTLE_WINDOW_MS, MINING_PROVIDER_BACKOFF_BASE_MS, MINING_PROVIDER_BACKOFF_MAX_MS, MINING_SHUTDOWN_GRACE_MS, MINING_STATUS_HEARTBEAT_INTERVAL_MS, MINING_SUSPEND_GAP_THRESHOLD_MS, MINING_TIP_SETTLE_WINDOW_MS, MINING_WORKER_API_VERSION, } from "./constants.js";
 import { inspectMiningControlPlane, setupBuiltInMining } from "./control.js";
-import { isMiningGenerationAbortRequested, markMiningGenerationActive, markMiningGenerationInactive, readMiningPreemptionRequest, requestMiningGenerationPreemption, } from "./coordination.js";
+import { isMiningGenerationAbortRequested, markMiningGenerationActive, markMiningGenerationInactive, readMiningGenerationActivity, readMiningPreemptionRequest, requestMiningGenerationPreemption, } from "./coordination.js";
 import { clearMiningPublishState, miningPublishIsInMempool, miningPublishMayStillExist, normalizeMiningPublishState, normalizeMiningStateRecord, } from "./state.js";
 import { createMiningSentenceRequestLimits } from "./sentence-protocol.js";
 import { generateMiningSentences, MiningProviderRequestError } from "./sentences.js";
 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;
+}
 class MiningSuspendDetectedError extends Error {
     detectedAtUnixMs;
     constructor(detectedAtUnixMs) {
@@ -88,6 +124,239 @@ async function isProcessAlive(pid) {
         return true;
     }
 }
+function normalizeMiningPid(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0
+        ? value
+        : null;
+}
+function resolveMiningGenerationRequestPath(paths) {
+    return join(paths.miningRoot, "generation-request.json");
+}
+function resolveMiningGenerationActivityPath(paths) {
+    return join(paths.miningRoot, "generation-activity.json");
+}
+function createTakeoverStoppedMiningNote(livePublishInMempool) {
+    return livePublishInMempool
+        ? "Mining runtime replaced. The last mining transaction may still confirm from mempool."
+        : "Mining runtime replaced.";
+}
+function createStoppedMiningRuntimeSnapshotForTakeover(options) {
+    const note = createTakeoverStoppedMiningNote(options.snapshot?.livePublishInMempool);
+    if (options.snapshot !== null) {
+        return {
+            ...options.snapshot,
+            updatedAtUnixMs: options.nowUnixMs,
+            runMode: "stopped",
+            backgroundWorkerPid: null,
+            backgroundWorkerRunId: null,
+            backgroundWorkerHeartbeatAtUnixMs: null,
+            backgroundWorkerHealth: null,
+            currentPhase: "idle",
+            note,
+        };
+    }
+    return {
+        schemaVersion: 1,
+        walletRootId: options.walletRootId,
+        workerApiVersion: null,
+        workerBinaryVersion: null,
+        workerBuildId: null,
+        updatedAtUnixMs: options.nowUnixMs,
+        runMode: "stopped",
+        backgroundWorkerPid: null,
+        backgroundWorkerRunId: null,
+        backgroundWorkerHeartbeatAtUnixMs: null,
+        backgroundWorkerHealth: null,
+        indexerDaemonState: null,
+        indexerDaemonInstanceId: null,
+        indexerSnapshotSeq: null,
+        indexerSnapshotOpenedAtUnixMs: null,
+        indexerTruthSource: undefined,
+        indexerHeartbeatAtUnixMs: null,
+        coreBestHeight: null,
+        coreBestHash: null,
+        indexerTipHeight: null,
+        indexerTipHash: null,
+        indexerReorgDepth: null,
+        indexerTipAligned: null,
+        corePublishState: null,
+        providerState: null,
+        lastSuspendDetectedAtUnixMs: null,
+        reconnectSettledUntilUnixMs: null,
+        tipSettledUntilUnixMs: null,
+        miningState: "idle",
+        currentPhase: "idle",
+        currentPublishState: "none",
+        targetBlockHeight: null,
+        referencedBlockHashDisplay: null,
+        currentDomainId: null,
+        currentDomainName: null,
+        currentSentenceDisplay: null,
+        currentCanonicalBlend: null,
+        currentTxid: null,
+        currentWtxid: null,
+        livePublishInMempool: null,
+        currentFeeRateSatVb: null,
+        currentAbsoluteFeeSats: null,
+        currentBlockFeeSpentSats: "0",
+        sessionFeeSpentSats: "0",
+        lifetimeFeeSpentSats: "0",
+        sameDomainCompetitorSuppressed: null,
+        higherRankedCompetitorDomainCount: null,
+        dedupedCompetitorDomainCount: null,
+        competitivenessGateIndeterminate: null,
+        mempoolSequenceCacheStatus: null,
+        currentPublishDecision: null,
+        lastMempoolSequence: null,
+        lastCompetitivenessGateAtUnixMs: null,
+        pauseReason: null,
+        providerConfigured: false,
+        providerKind: null,
+        bitcoindHealth: "unavailable",
+        bitcoindServiceState: null,
+        bitcoindReplicaStatus: null,
+        nodeHealth: "unavailable",
+        indexerHealth: "unavailable",
+        tipsAligned: null,
+        lastEventAtUnixMs: null,
+        lastError: null,
+        note,
+    };
+}
+async function waitForMiningProcessExit(pid, timeoutMs, sleepImpl = sleep) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!await isProcessAlive(pid)) {
+            return true;
+        }
+        await sleepImpl(Math.min(250, Math.max(timeoutMs, 1)));
+    }
+    return !await isProcessAlive(pid);
+}
+async function terminateMiningRuntimePid(options) {
+    if (!await isProcessAlive(options.pid)) {
+        return false;
+    }
+    try {
+        process.kill(options.pid, "SIGTERM");
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+            throw error;
+        }
+    }
+    if (await waitForMiningProcessExit(options.pid, options.shutdownGraceMs, options.sleepImpl)) {
+        return true;
+    }
+    try {
+        process.kill(options.pid, "SIGKILL");
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+            throw error;
+        }
+    }
+    if (await waitForMiningProcessExit(options.pid, options.shutdownGraceMs, options.sleepImpl)) {
+        return true;
+    }
+    throw new Error("mining_process_stop_timeout");
+}
+async function takeOverMiningRuntime(options) {
+    const snapshot = await loadMiningRuntimeStatus(options.paths.miningStatusPath).catch(() => null);
+    const controlLockMetadata = options.controlLockMetadata ?? (options.clearControlLockFile === true
+        ? await readLockMetadata(options.paths.miningControlLockPath).catch(() => null)
+        : null);
+    const generationActivity = await readMiningGenerationActivity(options.paths).catch(() => null);
+    const shutdownGraceMs = options.shutdownGraceMs ?? MINING_SHUTDOWN_GRACE_MS;
+    const requestPreemption = options.requestMiningPreemption ?? requestMiningGenerationPreemption;
+    const controlLockPid = normalizeMiningPid(controlLockMetadata?.processId);
+    const backgroundWorkerPid = normalizeMiningPid(snapshot?.backgroundWorkerPid);
+    const generationOwnerPid = normalizeMiningPid(generationActivity?.generationOwnerPid);
+    const terminatedPids = [];
+    const discoveredPids = new Set();
+    for (const pid of [controlLockPid, backgroundWorkerPid, generationOwnerPid]) {
+        if (pid === null
+            || pid === process.pid
+            || discoveredPids.has(pid)
+            || !await isProcessAlive(pid)) {
+            continue;
+        }
+        discoveredPids.add(pid);
+    }
+    const shouldPreemptGeneration = discoveredPids.size > 0 && (generationActivity?.generationActive === true
+        || snapshot?.currentPhase === "generating"
+        || snapshot?.currentPhase === "scoring");
+    const preemption = shouldPreemptGeneration
+        ? await requestPreemption({
+            paths: options.paths,
+            reason: options.reason,
+            timeoutMs: Math.min(shutdownGraceMs, 15_000),
+        }).catch(() => null)
+        : null;
+    try {
+        for (const pid of discoveredPids) {
+            if (await terminateMiningRuntimePid({
+                pid,
+                shutdownGraceMs,
+                sleepImpl: options.sleepImpl,
+            })) {
+                terminatedPids.push(pid);
+            }
+        }
+    }
+    finally {
+        await preemption?.release().catch(() => undefined);
+    }
+    const controlLockCleared = options.clearControlLockFile === true
+        ? await clearOrphanedFileLock(options.paths.miningControlLockPath, isProcessAlive).catch(() => false)
+        : false;
+    await rm(resolveMiningGenerationRequestPath(options.paths), { force: true }).catch(() => undefined);
+    await rm(resolveMiningGenerationActivityPath(options.paths), { force: true }).catch(() => undefined);
+    const walletRootId = snapshot?.walletRootId
+        ?? (typeof controlLockMetadata?.walletRootId === "string" ? controlLockMetadata.walletRootId : null);
+    if (snapshot !== null || walletRootId !== null || terminatedPids.length > 0 || controlLockCleared) {
+        await saveMiningRuntimeStatus(options.paths.miningStatusPath, createStoppedMiningRuntimeSnapshotForTakeover({
+            snapshot,
+            walletRootId,
+            nowUnixMs: Date.now(),
+        }));
+    }
+    return {
+        controlLockCleared,
+        replaced: terminatedPids.length > 0,
+        snapshot,
+        terminatedPids,
+    };
+}
+async function acquireMiningStartControlLock(options) {
+    while (true) {
+        try {
+            return await acquireFileLock(options.paths.miningControlLockPath, {
+                purpose: options.purpose,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof FileLockBusyError)) {
+                throw error;
+            }
+            if (error.existingMetadata?.processId === process.pid) {
+                throw error;
+            }
+            const takeover = await takeOverMiningRuntime({
+                paths: options.paths,
+                reason: options.takeoverReason,
+                clearControlLockFile: true,
+                controlLockMetadata: error.existingMetadata,
+                requestMiningPreemption: options.requestMiningPreemption,
+                shutdownGraceMs: options.shutdownGraceMs,
+                sleepImpl: options.sleepImpl,
+            });
+            if (!takeover.replaced && !takeover.controlLockCleared) {
+                throw error;
+            }
+        }
+    }
+}
 function writeStdout(stream, line) {
     if (stream === undefined) {
         return;
@@ -204,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;
@@ -232,7 +531,7 @@ function fallbackSettledWinnerDomainName(domainId) {
     return `domain-${domainId}`;
 }
 function resolveCurrentMinedBlockBoard(options) {
-    const settledBlockHeight = options.nodeBestHeight ?? options.snapshotTipHeight ?? null;
+    const settledBlockHeight = options.snapshotTipHeight ?? null;
     if (settledBlockHeight === null) {
         return {
             settledBlockHeight,
@@ -245,12 +544,6 @@ function resolveCurrentMinedBlockBoard(options) {
             settledBoardEntries: [],
         };
     }
-    if (options.nodeBestHeight !== null && (options.snapshotTipHeight ?? -1) < options.nodeBestHeight) {
-        return {
-            settledBlockHeight,
-            settledBoardEntries: [],
-        };
-    }
     const settledBoardEntries = (getBlockWinners(options.snapshotState, settledBlockHeight) ?? [])
         .slice()
         .sort((left, right) => left.rank - right.rank || left.txIndex - right.txIndex)
@@ -259,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,
@@ -266,17 +564,42 @@ function resolveCurrentMinedBlockBoard(options) {
     };
 }
 export function resolveSettledBoardForTesting(options) {
-    return resolveCurrentMinedBlockBoard(options);
+    return resolveCurrentMinedBlockBoard({
+        ...options,
+        snapshotTipPreviousHashHex: options.snapshotTipPreviousHashHex ?? null,
+    });
 }
-function syncMiningUiSettledBoard(loopState, snapshotState, snapshotTipHeight, nodeBestHeight) {
+function syncMiningUiSettledBoard(loopState, snapshotState, snapshotTipHeight, snapshotTipPreviousHashHex) {
     const settledBoard = resolveCurrentMinedBlockBoard({
         snapshotState,
         snapshotTipHeight,
-        nodeBestHeight,
+        snapshotTipPreviousHashHex,
+        nodeBestHeight: null,
     });
     loopState.ui.settledBlockHeight = settledBoard.settledBlockHeight;
     loopState.ui.settledBoardEntries = settledBoard.settledBoardEntries;
 }
+function syncMiningUiForCurrentTip(options) {
+    const targetBlockHeight = options.nodeBestHeight === null
+        ? null
+        : options.nodeBestHeight + 1;
+    const tipKey = buildMiningTipKey(options.nodeBestHash, targetBlockHeight);
+    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, options.snapshotTipPreviousHashHex);
+    return {
+        targetBlockHeight,
+        tipKey,
+        tipChanged,
+    };
+}
 function setMiningUiCandidate(loopState, candidate) {
     loopState.ui.latestSentence = candidate.sentence;
     loopState.ui.provisionalRequiredWords = [...candidate.bip39Words];
@@ -306,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) => {
@@ -348,6 +788,22 @@ function syncMiningVisualizerBalances(loopState, readContext, balanceSats) {
         : getBalance(readContext.snapshot.state, readContext.localState.state.funding.scriptPubKeyHex);
     loopState.ui.balanceSats = balanceSats;
 }
+function createIndexedMiningFollowVisualizerState(readContext) {
+    const uiState = createEmptyMiningFollowVisualizerState();
+    const localState = readContext.localState;
+    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;
+    uiState.settledBoardEntries = settledBoard.settledBoardEntries;
+    if (readContext.snapshot !== null && localState.availability === "ready" && localState.state !== null) {
+        uiState.balanceCogtoshi = getBalance(readContext.snapshot.state, localState.state.funding.scriptPubKeyHex);
+    }
+    return uiState;
+}
 function syncMiningVisualizerBlockTimes(loopState, blockTimesByHeight) {
     loopState.ui.visibleBlockTimesByHeight = { ...blockTimesByHeight };
 }
@@ -642,28 +1098,73 @@ async function resolveOverlayAuthorizedMiningDomain(options) {
 function buildStatusSnapshot(view, overrides = {}) {
     return {
         ...view.runtime,
-        runMode: overrides.runMode ?? view.runtime.runMode,
-        backgroundWorkerPid: overrides.backgroundWorkerPid ?? view.runtime.backgroundWorkerPid,
-        backgroundWorkerRunId: overrides.backgroundWorkerRunId ?? view.runtime.backgroundWorkerRunId,
-        backgroundWorkerHeartbeatAtUnixMs: overrides.backgroundWorkerHeartbeatAtUnixMs ?? view.runtime.backgroundWorkerHeartbeatAtUnixMs,
-        currentPhase: overrides.currentPhase ?? view.runtime.currentPhase,
-        lastSuspendDetectedAtUnixMs: overrides.lastSuspendDetectedAtUnixMs ?? view.runtime.lastSuspendDetectedAtUnixMs,
-        providerState: overrides.providerState ?? view.runtime.providerState,
-        corePublishState: overrides.corePublishState ?? view.runtime.corePublishState,
-        currentPublishDecision: overrides.currentPublishDecision ?? view.runtime.currentPublishDecision,
-        sameDomainCompetitorSuppressed: overrides.sameDomainCompetitorSuppressed ?? view.runtime.sameDomainCompetitorSuppressed,
-        higherRankedCompetitorDomainCount: overrides.higherRankedCompetitorDomainCount ?? view.runtime.higherRankedCompetitorDomainCount,
-        dedupedCompetitorDomainCount: overrides.dedupedCompetitorDomainCount ?? view.runtime.dedupedCompetitorDomainCount,
-        competitivenessGateIndeterminate: overrides.competitivenessGateIndeterminate ?? view.runtime.competitivenessGateIndeterminate,
-        mempoolSequenceCacheStatus: overrides.mempoolSequenceCacheStatus ?? view.runtime.mempoolSequenceCacheStatus,
-        lastMempoolSequence: overrides.lastMempoolSequence ?? view.runtime.lastMempoolSequence,
-        lastCompetitivenessGateAtUnixMs: overrides.lastCompetitivenessGateAtUnixMs ?? view.runtime.lastCompetitivenessGateAtUnixMs,
-        lastError: overrides.lastError ?? view.runtime.lastError,
-        note: overrides.note ?? view.runtime.note,
-        livePublishInMempool: overrides.livePublishInMempool ?? view.runtime.livePublishInMempool,
+        runMode: resolveSnapshotOverride(overrides.runMode, view.runtime.runMode),
+        backgroundWorkerPid: resolveSnapshotOverride(overrides.backgroundWorkerPid, view.runtime.backgroundWorkerPid),
+        backgroundWorkerRunId: resolveSnapshotOverride(overrides.backgroundWorkerRunId, view.runtime.backgroundWorkerRunId),
+        backgroundWorkerHeartbeatAtUnixMs: resolveSnapshotOverride(overrides.backgroundWorkerHeartbeatAtUnixMs, view.runtime.backgroundWorkerHeartbeatAtUnixMs),
+        currentPhase: resolveSnapshotOverride(overrides.currentPhase, view.runtime.currentPhase),
+        currentPublishState: resolveSnapshotOverride(overrides.currentPublishState, view.runtime.currentPublishState),
+        targetBlockHeight: resolveSnapshotOverride(overrides.targetBlockHeight, view.runtime.targetBlockHeight),
+        referencedBlockHashDisplay: resolveSnapshotOverride(overrides.referencedBlockHashDisplay, view.runtime.referencedBlockHashDisplay),
+        currentDomainId: resolveSnapshotOverride(overrides.currentDomainId, view.runtime.currentDomainId),
+        currentDomainName: resolveSnapshotOverride(overrides.currentDomainName, view.runtime.currentDomainName),
+        currentSentenceDisplay: resolveSnapshotOverride(overrides.currentSentenceDisplay, view.runtime.currentSentenceDisplay),
+        currentCanonicalBlend: resolveSnapshotOverride(overrides.currentCanonicalBlend, view.runtime.currentCanonicalBlend),
+        currentTxid: resolveSnapshotOverride(overrides.currentTxid, view.runtime.currentTxid),
+        currentWtxid: resolveSnapshotOverride(overrides.currentWtxid, view.runtime.currentWtxid),
+        currentFeeRateSatVb: resolveSnapshotOverride(overrides.currentFeeRateSatVb, view.runtime.currentFeeRateSatVb),
+        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),
+        sameDomainCompetitorSuppressed: resolveSnapshotOverride(overrides.sameDomainCompetitorSuppressed, view.runtime.sameDomainCompetitorSuppressed),
+        higherRankedCompetitorDomainCount: resolveSnapshotOverride(overrides.higherRankedCompetitorDomainCount, view.runtime.higherRankedCompetitorDomainCount),
+        dedupedCompetitorDomainCount: resolveSnapshotOverride(overrides.dedupedCompetitorDomainCount, view.runtime.dedupedCompetitorDomainCount),
+        competitivenessGateIndeterminate: resolveSnapshotOverride(overrides.competitivenessGateIndeterminate, view.runtime.competitivenessGateIndeterminate),
+        mempoolSequenceCacheStatus: resolveSnapshotOverride(overrides.mempoolSequenceCacheStatus, view.runtime.mempoolSequenceCacheStatus),
+        lastMempoolSequence: resolveSnapshotOverride(overrides.lastMempoolSequence, view.runtime.lastMempoolSequence),
+        lastCompetitivenessGateAtUnixMs: resolveSnapshotOverride(overrides.lastCompetitivenessGateAtUnixMs, view.runtime.lastCompetitivenessGateAtUnixMs),
+        lastError: resolveSnapshotOverride(overrides.lastError, view.runtime.lastError),
+        note: resolveSnapshotOverride(overrides.note, view.runtime.note),
+        livePublishInMempool: resolveSnapshotOverride(overrides.livePublishInMempool, view.runtime.livePublishInMempool),
         updatedAtUnixMs: Date.now(),
     };
 }
+function buildPrePublishStatusOverrides(options) {
+    const replacing = options.state.miningState.currentTxid !== null;
+    const replacingAcrossTips = replacing && !livePublishTargetsCandidateTip({
+        liveState: options.state.miningState,
+        candidate: options.candidate,
+    });
+    return {
+        currentPhase: replacing ? "replacing" : "publishing",
+        currentPublishDecision: replacing ? "replacing" : "publishing",
+        targetBlockHeight: options.candidate.targetBlockHeight,
+        referencedBlockHashDisplay: options.candidate.referencedBlockHashDisplay,
+        currentDomainId: options.candidate.domainId,
+        currentDomainName: options.candidate.domainName,
+        currentSentenceDisplay: options.candidate.sentence,
+        currentCanonicalBlend: options.candidate.canonicalBlend.toString(),
+        note: replacing
+            ? "Replacing the live mining transaction for the current tip."
+            : "Broadcasting the best mining candidate for the current tip.",
+        ...(replacingAcrossTips
+            ? {
+                currentPublishState: "none",
+                currentTxid: null,
+                currentWtxid: null,
+                livePublishInMempool: false,
+                currentFeeRateSatVb: null,
+                currentAbsoluteFeeSats: null,
+                currentBlockFeeSpentSats: "0",
+            }
+            : {}),
+    };
+}
 async function refreshAndSaveStatus(options) {
     const view = await inspectMiningControlPlane({
         provider: options.provider,
@@ -682,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,
@@ -691,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,
@@ -703,8 +1292,10 @@ 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),
         });
     }
     finally {
@@ -768,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
@@ -821,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) {
@@ -897,6 +1489,37 @@ 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 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 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;
     if (bestBlockHash === null || bestBlockHash === undefined) {
@@ -908,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;
@@ -946,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, {
@@ -1103,6 +1723,7 @@ function toSentenceBoardEntries(entries) {
         rank: entry.rank,
         domainName: entry.domainName,
         sentence: entry.sentence,
+        requiredWords: resolveBip39WordsFromIndices(entry.bip39WordIndices),
     }));
 }
 async function runCompetitivenessGate(options) {
@@ -1534,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,
@@ -1801,6 +2422,29 @@ async function publishCandidate(options) {
                     candidate: refreshedCandidate,
                 };
             }
+            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 safe BTC.", {
+                    level: "warn",
+                    runId: options.runId,
+                    targetBlockHeight: refreshedCandidate.targetBlockHeight,
+                    referencedBlockHashDisplay: refreshedCandidate.referencedBlockHashDisplay,
+                    domainId: refreshedCandidate.domainId,
+                    domainName: refreshedCandidate.domainName,
+                    score: refreshedCandidate.canonicalBlend.toString(),
+                    reason: "insufficient-funds",
+                }));
+                return {
+                    state: readyReadContext.localState.state,
+                    txid: null,
+                    decision: "publish-paused-insufficient-funds",
+                    note,
+                    lastError,
+                    skipped: true,
+                    candidate: null,
+                };
+            }
             throw error;
         }
     }
@@ -1830,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,
@@ -1838,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;
         }
@@ -1911,18 +2565,25 @@ async function performMiningCycle(options) {
             indexedTipHashHex: indexedTip?.blockHashHex ?? null,
         }).catch(() => ({}));
         syncMiningVisualizerBlockTimes(options.loopState, visibleBlockTimes);
+        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;
         }
@@ -1944,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;
         }
@@ -1972,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;
         }
@@ -2003,53 +2650,36 @@ 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;
         }
-        const targetBlockHeight = (effectiveReadContext.nodeStatus?.nodeBestHeight ?? 0) + 1;
-        const tipKey = buildMiningTipKey(effectiveReadContext.nodeStatus?.nodeBestHashHex ?? null, targetBlockHeight);
-        if (tipKey !== options.loopState.currentTipKey) {
-            options.loopState.currentTipKey = tipKey;
-            resetMiningUiForTip(options.loopState, targetBlockHeight);
-            if (reconciliation.recentWin !== null) {
-                options.loopState.ui.recentWin = reconciliation.recentWin;
-            }
+        if (targetBlockHeight === null) {
+            await saveCycleStatus(effectiveReadContext, {
+                runMode: options.runMode,
+                currentPhase: "waiting-bitcoin-network",
+                note: "Mining is waiting for the local Bitcoin node to become publishable.",
+            });
+            return;
         }
-        syncMiningUiSettledBoard(options.loopState, effectiveReadContext.snapshot?.state ?? null, effectiveReadContext.snapshot?.tip?.height ?? effectiveReadContext.indexer.snapshotTip?.height ?? null, effectiveReadContext.nodeStatus?.nodeBestHeight ?? null);
-        const displaySats = await resolveFundingDisplaySats(effectiveReadContext.localState.state, rpc).catch(() => null);
-        syncMiningVisualizerBalances(options.loopState, effectiveReadContext, displaySats);
         if (getBlockRewardCogtoshi(targetBlockHeight) === 0n) {
             const nextState = defaultMiningStatePatch(effectiveReadContext.localState.state, {
                 state: "paused",
@@ -2060,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,
@@ -2087,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;
         }
@@ -2135,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,
@@ -2186,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",
@@ -2241,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",
@@ -2263,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) {
@@ -2282,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,
@@ -2340,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"
@@ -2387,21 +2954,12 @@ async function performMiningCycle(options) {
         if (!await ensureCurrentIndexerTruthOrRestart()) {
             return;
         }
-        await refreshAndSaveStatus({
-            paths: options.paths,
-            provider: options.provider,
-            readContext: effectiveReadContext,
-            overrides: {
-                runMode: options.runMode,
-                currentPhase: effectiveReadContext.localState.state.miningState.currentTxid === null
-                    ? "publishing"
-                    : "replacing",
-                note: effectiveReadContext.localState.state.miningState.currentTxid === null
-                    ? "Broadcasting the best mining candidate for the current tip."
-                    : "Replacing the live mining transaction for the current tip.",
-            },
-            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",
@@ -2432,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;
             }
@@ -2465,32 +3016,29 @@ async function performMiningCycle(options) {
                 clearSelectedCandidate(options.loopState);
                 setMiningUiCandidate(options.loopState, selectedCandidate);
                 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,
+                const lastError = published.decision === "publish-paused-insufficient-funds"
+                    ? published.lastError ?? createInsufficientFundsMiningPublishErrorMessage()
+                    : undefined;
+                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;
             }
@@ -2506,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 {
@@ -2540,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;
@@ -2555,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;
         }
@@ -2656,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,
     }));
@@ -2667,6 +3230,7 @@ async function runMiningLoop(options) {
             if (!(error instanceof MiningSuspendDetectedError)) {
                 throw error;
             }
+            discardMiningLoopTransientWork(loopState, null);
             await handleDetectedMiningRuntimeResume({
                 dataDir: options.dataDir,
                 databasePath: options.databasePath,
@@ -2678,6 +3242,7 @@ async function runMiningLoop(options) {
                 detectedAtUnixMs: error.detectedAtUnixMs,
                 openReadContext: options.openReadContext,
                 visualizer: options.visualizer,
+                loopState,
             });
             continue;
         }
@@ -2685,8 +3250,10 @@ 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,
@@ -2723,36 +3290,52 @@ export async function runForegroundMining(options) {
     const openReadContext = options.openReadContext ?? openWalletReadContext;
     const attachService = options.attachService ?? attachOrStartManagedBitcoindService;
     const rpcFactory = options.rpcFactory ?? createRpcClient;
-    const controlLock = await acquireFileLock(paths.miningControlLockPath, {
+    const requestMiningPreemption = options.requestMiningPreemption ?? requestMiningGenerationPreemption;
+    const runMiningLoopImpl = options.runMiningLoopImpl ?? runMiningLoop;
+    const saveStopSnapshotImpl = options.saveStopSnapshotImpl ?? saveStopSnapshot;
+    let visualizer = null;
+    const setupReady = options.builtInSetupEnsured === true
+        ? true
+        : await ensureBuiltInMiningSetupIfNeeded({
+            provider,
+            prompter: options.prompter,
+            paths,
+        });
+    if (!setupReady) {
+        throw new Error("Built-in mining provider is not configured. Run `cogcoin mine setup`.");
+    }
+    const controlLock = await acquireMiningStartControlLock({
+        paths,
         purpose: "mine-foreground",
+        takeoverReason: "mine-foreground-replace",
+        requestMiningPreemption,
+        shutdownGraceMs: options.shutdownGraceMs,
+        sleepImpl: options.sleepImpl,
     });
-    let visualizer = null;
+    const abortController = new AbortController();
+    const abortListener = () => {
+        abortController.abort();
+    };
+    const handleSigint = () => abortController.abort();
+    const handleSigterm = () => abortController.abort();
     try {
-        const existing = await loadMiningRuntimeStatus(paths.miningStatusPath).catch(() => null);
-        if (existing?.runMode === "background") {
-            throw new Error("Background mining is already active. Run `cogcoin mine stop` first.");
-        }
-        const setupReady = options.builtInSetupEnsured === true
-            ? true
-            : await ensureBuiltInMiningSetupIfNeeded({
-                provider,
-                prompter: options.prompter,
-                paths,
-            });
-        if (!setupReady) {
-            throw new Error("Built-in mining provider is not configured. Run `cogcoin mine setup`.");
-        }
+        await takeOverMiningRuntime({
+            paths,
+            reason: "mine-foreground-replace",
+            requestMiningPreemption,
+            shutdownGraceMs: options.shutdownGraceMs,
+            sleepImpl: options.sleepImpl,
+        });
         visualizer = new MiningFollowVisualizer({
+            clientVersion: options.clientVersion,
+            updateAvailable: options.updateAvailable,
             progressOutput: options.progressOutput ?? "auto",
             stream: options.stderr,
         });
-        const abortController = new AbortController();
-        options.signal?.addEventListener("abort", () => {
-            abortController.abort();
-        }, { once: true });
-        process.on("SIGINT", () => abortController.abort());
-        process.on("SIGTERM", () => abortController.abort());
-        await runMiningLoop({
+        options.signal?.addEventListener("abort", abortListener, { once: true });
+        process.on("SIGINT", handleSigint);
+        process.on("SIGTERM", handleSigterm);
+        await runMiningLoopImpl({
             dataDir: options.dataDir,
             databasePath: options.databasePath,
             provider,
@@ -2768,7 +3351,7 @@ export async function runForegroundMining(options) {
             stdout: options.stdout,
             visualizer,
         });
-        await saveStopSnapshot({
+        await saveStopSnapshotImpl({
             dataDir: options.dataDir,
             databasePath: options.databasePath,
             provider,
@@ -2780,6 +3363,9 @@ export async function runForegroundMining(options) {
         });
     }
     finally {
+        options.signal?.removeEventListener("abort", abortListener);
+        process.off("SIGINT", handleSigint);
+        process.off("SIGTERM", handleSigterm);
         visualizer?.close();
         await controlLock.release();
     }
@@ -2787,35 +3373,50 @@ export async function runForegroundMining(options) {
 export async function startBackgroundMining(options) {
     const provider = options.provider ?? createDefaultWalletSecretProvider();
     const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
-    const controlLock = await acquireFileLock(paths.miningControlLockPath, {
-        purpose: "mine-start",
-    });
+    const requestMiningPreemption = options.requestMiningPreemption ?? requestMiningGenerationPreemption;
+    const spawnWorkerProcess = options.spawnWorkerProcess ?? spawn;
+    const waitForBackgroundHealthyImpl = options.waitForBackgroundHealthyImpl ?? waitForBackgroundHealthy;
+    const setupReady = options.builtInSetupEnsured === true
+        ? true
+        : await ensureBuiltInMiningSetupIfNeeded({
+            provider,
+            prompter: options.prompter,
+            paths,
+        });
+    if (!setupReady) {
+        throw new Error("Built-in mining provider is not configured. Run `cogcoin mine setup`.");
+    }
+    let controlLock;
     try {
-        const existing = await loadMiningRuntimeStatus(paths.miningStatusPath).catch(() => null);
-        if (existing?.runMode === "background"
-            && existing.backgroundWorkerPid !== null
-            && await isProcessAlive(existing.backgroundWorkerPid)) {
+        controlLock = await acquireMiningStartControlLock({
+            paths,
+            purpose: "mine-start",
+            takeoverReason: "mine-start-replace",
+            requestMiningPreemption,
+            shutdownGraceMs: options.shutdownGraceMs,
+            sleepImpl: options.sleepImpl,
+        });
+    }
+    catch (error) {
+        if (error instanceof FileLockBusyError && error.existingMetadata?.processId === process.pid) {
             return {
                 started: false,
-                snapshot: existing,
+                snapshot: await loadMiningRuntimeStatus(paths.miningStatusPath).catch(() => null),
             };
         }
-        if (existing?.runMode === "foreground") {
-            throw new Error("Foreground mining is already active. Interrupt that process directly.");
-        }
-        const setupReady = options.builtInSetupEnsured === true
-            ? true
-            : await ensureBuiltInMiningSetupIfNeeded({
-                provider,
-                prompter: options.prompter,
-                paths,
-            });
-        if (!setupReady) {
-            throw new Error("Built-in mining provider is not configured. Run `cogcoin mine setup`.");
-        }
+        throw error;
+    }
+    try {
+        await takeOverMiningRuntime({
+            paths,
+            reason: "mine-start-replace",
+            requestMiningPreemption,
+            shutdownGraceMs: options.shutdownGraceMs,
+            sleepImpl: options.sleepImpl,
+        });
         const runId = randomBytes(16).toString("hex");
         const workerMainPath = fileURLToPath(new URL("./worker-main.js", import.meta.url));
-        const child = spawn(process.execPath, [
+        const child = spawnWorkerProcess(process.execPath, [
             workerMainPath,
             `--data-dir=${options.dataDir}`,
             `--database-path=${options.databasePath}`,
@@ -2825,7 +3426,7 @@ export async function startBackgroundMining(options) {
             stdio: "ignore",
         });
         child.unref();
-        const snapshot = await waitForBackgroundHealthy(paths);
+        const snapshot = await waitForBackgroundHealthyImpl(paths);
         return {
             started: true,
             snapshot,
@@ -2957,14 +3558,33 @@ 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);
 }
 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);
+}
+export function buildStatusSnapshotForTesting(view, overrides = {}) {
+    return buildStatusSnapshot(view, overrides);
+}
 export function shouldKeepCurrentTipLivePublishForTesting(options) {
     return livePublishTargetsCandidateTip(options);
 }