@cogcoin/client 1.1.4 → 1.1.6

package/dist/wallet/lifecycle/repair-bitcoind.js

@@ -0,0 +1,142 @@
+import { normalizeWalletDescriptorState } from "../descriptor-normalization.js";
+import { acquireFileLock } from "../fs/lock.js";
+import { persistWalletCoinControlStateIfNeeded } from "../coin-control.js";
+import { createWalletSecretReference } from "../state/provider.js";
+import { recreateManagedCoreWalletReplica, verifyManagedCoreWalletReplica } from "./managed-core.js";
+import { pathExists } from "./context.js";
+import { clearManagedBitcoindArtifacts, mapBitcoindCompatibilityToRepairIssue, mapBitcoindRepairHealth, waitForProcessExit, } from "./repair-runtime.js";
+export async function repairManagedBitcoindStage(options) {
+    let state = options.state;
+    let repairStateNeedsPersist = options.repairStateNeedsPersist;
+    let bitcoindServiceAction = "none";
+    let bitcoindCompatibilityIssue = "none";
+    let managedCoreReplicaAction = "none";
+    let recreatedManagedCoreWallet = false;
+    let initialBitcoindProbe = {
+        compatibility: "unreachable",
+        status: null,
+        error: null,
+    };
+    let bitcoindPostRepairHealth = "unavailable";
+    const bitcoindLock = await acquireFileLock(options.servicePaths.bitcoindLockPath, {
+        purpose: "managed-bitcoind-repair",
+        walletRootId: state.walletRootId,
+        dataDir: options.context.dataDir,
+    });
+    try {
+        initialBitcoindProbe = await options.context.probeBitcoindService({
+            dataDir: options.context.dataDir,
+            chain: "main",
+            startHeight: 0,
+            walletRootId: state.walletRootId,
+        });
+        bitcoindCompatibilityIssue = mapBitcoindCompatibilityToRepairIssue(initialBitcoindProbe.compatibility);
+        if (initialBitcoindProbe.compatibility === "service-version-mismatch"
+            || initialBitcoindProbe.compatibility === "wallet-root-mismatch"
+            || initialBitcoindProbe.compatibility === "runtime-mismatch") {
+            const processId = initialBitcoindProbe.status?.processId ?? null;
+            if (processId === null) {
+                throw new Error("managed_bitcoind_process_id_unavailable");
+            }
+            try {
+                process.kill(processId, "SIGTERM");
+            }
+            catch (error) {
+                if (!(error instanceof Error) || !("code" in error) || error.code !== "ESRCH") {
+                    throw error;
+                }
+            }
+            await waitForProcessExit(processId, 15_000, "managed_bitcoind_stop_timeout");
+            await clearManagedBitcoindArtifacts(options.servicePaths);
+            bitcoindServiceAction = "stopped-incompatible-service";
+        }
+        else if (initialBitcoindProbe.compatibility === "unreachable") {
+            const hasStaleArtifacts = await Promise.all([
+                options.servicePaths.bitcoindStatusPath,
+                options.servicePaths.bitcoindPidPath,
+                options.servicePaths.bitcoindReadyPath,
+                options.servicePaths.bitcoindWalletStatusPath,
+            ].map(pathExists));
+            if (hasStaleArtifacts.some(Boolean)) {
+                await clearManagedBitcoindArtifacts(options.servicePaths);
+                bitcoindServiceAction = "cleared-stale-artifacts";
+            }
+        }
+        else if (initialBitcoindProbe.compatibility === "protocol-error") {
+            throw new Error(initialBitcoindProbe.error ?? "managed_bitcoind_protocol_error");
+        }
+    }
+    finally {
+        await bitcoindLock.release();
+    }
+    const bitcoindHandle = await options.context.attachService({
+        dataDir: options.context.dataDir,
+        chain: "main",
+        startHeight: 0,
+        walletRootId: state.walletRootId,
+    });
+    try {
+        const rpc = options.context.rpcFactory(bitcoindHandle.rpc);
+        const normalizedDescriptorState = await normalizeWalletDescriptorState(state, rpc);
+        if (normalizedDescriptorState.changed) {
+            state = normalizedDescriptorState.state;
+            repairStateNeedsPersist = true;
+        }
+        const reconciledCoinControl = await persistWalletCoinControlStateIfNeeded({
+            state,
+            access: {
+                provider: options.context.provider,
+                secretReference: createWalletSecretReference(state.walletRootId),
+            },
+            paths: options.context.paths,
+            nowUnixMs: options.context.nowUnixMs,
+            replacePrimary: options.recoveredFromBackup && !repairStateNeedsPersist,
+            rpc,
+        });
+        state = reconciledCoinControl.state;
+        if (reconciledCoinControl.changed) {
+            repairStateNeedsPersist = false;
+        }
+        let replica = await verifyManagedCoreWalletReplica(state, options.context.dataDir, {
+            nodeHandle: bitcoindHandle,
+            attachService: options.context.attachService,
+            rpcFactory: options.context.rpcFactory,
+        });
+        if (replica.proofStatus !== "ready") {
+            state = await recreateManagedCoreWalletReplica(state, options.context.provider, options.context.paths, options.context.dataDir, options.context.nowUnixMs, {
+                attachService: options.context.attachService,
+                rpcFactory: options.context.rpcFactory,
+            });
+            recreatedManagedCoreWallet = true;
+            managedCoreReplicaAction = "recreated";
+            repairStateNeedsPersist = false;
+            replica = await verifyManagedCoreWalletReplica(state, options.context.dataDir, {
+                nodeHandle: bitcoindHandle,
+                attachService: options.context.attachService,
+                rpcFactory: options.context.rpcFactory,
+            });
+        }
+        const finalBitcoindStatus = await bitcoindHandle.refreshServiceStatus?.() ?? null;
+        const chainInfo = await rpc.getBlockchainInfo();
+        bitcoindPostRepairHealth = mapBitcoindRepairHealth({
+            serviceState: finalBitcoindStatus?.state ?? null,
+            catchingUp: chainInfo.blocks < chainInfo.headers,
+            replica,
+        });
+        if (bitcoindServiceAction === "none" && initialBitcoindProbe.compatibility === "unreachable") {
+            bitcoindServiceAction = "restarted-compatible-service";
+        }
+    }
+    finally {
+        await bitcoindHandle.stop?.().catch(() => undefined);
+    }
+    return {
+        state,
+        repairStateNeedsPersist,
+        recreatedManagedCoreWallet,
+        bitcoindServiceAction,
+        bitcoindCompatibilityIssue,
+        managedCoreReplicaAction,
+        bitcoindPostRepairHealth,
+    };
+}

package/dist/wallet/lifecycle/repair-indexer.d.ts

@@ -0,0 +1,8 @@
+import type { ManagedServicePaths } from "../../bitcoind/service-paths.js";
+import type { WalletStateV1 } from "../types.js";
+import type { WalletIndexerRepairStageResult, WalletRepairContext } from "./types.js";
+export declare function repairManagedIndexerStage(options: {
+    context: WalletRepairContext;
+    servicePaths: ManagedServicePaths;
+    state: WalletStateV1;
+}): Promise<WalletIndexerRepairStageResult>;

package/dist/wallet/lifecycle/repair-indexer.js

@@ -0,0 +1,117 @@
+import { acquireFileLock } from "../fs/lock.js";
+import { pathExists } from "./context.js";
+import { clearIndexerDaemonArtifacts, ensureIndexerDatabaseHealthy, mapIndexerCompatibilityToRepairIssue, verifyIndexerPostRepairHealth, waitForProcessExit, } from "./repair-runtime.js";
+export async function repairManagedIndexerStage(options) {
+    let indexerDaemonAction = "none";
+    let indexerCompatibilityIssue = "none";
+    let initialIndexerDaemonInstanceId = null;
+    const indexerLock = await acquireFileLock(options.servicePaths.indexerDaemonLockPath, {
+        purpose: "indexer-daemon-repair",
+        walletRootId: options.state.walletRootId,
+        dataDir: options.context.dataDir,
+        databasePath: options.context.databasePath,
+    });
+    let resetIndexerDatabase = false;
+    try {
+        const initialProbe = await options.context.probeIndexerDaemon({
+            dataDir: options.context.dataDir,
+            walletRootId: options.state.walletRootId,
+        });
+        indexerCompatibilityIssue = mapIndexerCompatibilityToRepairIssue(initialProbe.compatibility);
+        initialIndexerDaemonInstanceId = initialProbe.status?.daemonInstanceId ?? null;
+        if (initialProbe.compatibility === "compatible") {
+            await initialProbe.client?.close().catch(() => undefined);
+        }
+        else if (initialProbe.compatibility === "service-version-mismatch"
+            || initialProbe.compatibility === "wallet-root-mismatch"
+            || initialProbe.compatibility === "schema-mismatch") {
+            const processId = initialProbe.status?.processId ?? null;
+            if (processId === null) {
+                throw new Error("indexer_daemon_process_id_unavailable");
+            }
+            try {
+                process.kill(processId, "SIGTERM");
+            }
+            catch (error) {
+                if (!(error instanceof Error) || !("code" in error) || error.code !== "ESRCH") {
+                    throw error;
+                }
+            }
+            await waitForProcessExit(processId);
+            await clearIndexerDaemonArtifacts(options.servicePaths);
+            indexerDaemonAction = "stopped-incompatible-daemon";
+        }
+        else if (initialProbe.compatibility === "unreachable") {
+            const hasStaleArtifacts = await Promise.all([
+                options.servicePaths.indexerDaemonSocketPath,
+                options.servicePaths.indexerDaemonStatusPath,
+            ].map(pathExists));
+            if (hasStaleArtifacts.some(Boolean)) {
+                await clearIndexerDaemonArtifacts(options.servicePaths);
+                indexerDaemonAction = "cleared-stale-artifacts";
+            }
+        }
+        else {
+            throw new Error(initialProbe.error ?? "indexer_daemon_protocol_error");
+        }
+        resetIndexerDatabase = await ensureIndexerDatabaseHealthy({
+            databasePath: options.context.databasePath,
+            dataDir: options.context.dataDir,
+            walletRootId: options.state.walletRootId,
+            resetIfNeeded: options.context.assumeYes,
+        });
+    }
+    finally {
+        await indexerLock.release();
+    }
+    let preAttachIndexerDaemonInstanceId = null;
+    const preAttachProbe = await options.context.probeIndexerDaemon({
+        dataDir: options.context.dataDir,
+        walletRootId: options.state.walletRootId,
+    });
+    if (preAttachProbe.compatibility === "compatible") {
+        preAttachIndexerDaemonInstanceId = preAttachProbe.status?.daemonInstanceId ?? null;
+        await preAttachProbe.client?.close().catch(() => undefined);
+    }
+    else if (preAttachProbe.compatibility !== "unreachable") {
+        throw new Error(preAttachProbe.error ?? "indexer_daemon_protocol_error");
+    }
+    const daemon = await options.context.attachIndexerDaemon({
+        dataDir: options.context.dataDir,
+        databasePath: options.context.databasePath,
+        walletRootId: options.state.walletRootId,
+    });
+    try {
+        const { health: indexerPostRepairHealth, daemonInstanceId: postRepairDaemonInstanceId, } = await verifyIndexerPostRepairHealth({
+            daemon,
+            probeIndexerDaemon: options.context.probeIndexerDaemon,
+            dataDir: options.context.dataDir,
+            walletRootId: options.state.walletRootId,
+            nowUnixMs: options.context.nowUnixMs,
+        });
+        const restartedIndexerDaemon = indexerDaemonAction !== "none" || preAttachProbe.compatibility === "unreachable";
+        if (restartedIndexerDaemon
+            && initialIndexerDaemonInstanceId !== null
+            && postRepairDaemonInstanceId === initialIndexerDaemonInstanceId) {
+            throw new Error("indexer_daemon_repair_identity_not_rotated");
+        }
+        if (!restartedIndexerDaemon
+            && preAttachProbe.compatibility === "compatible"
+            && preAttachIndexerDaemonInstanceId !== null
+            && postRepairDaemonInstanceId !== preAttachIndexerDaemonInstanceId) {
+            throw new Error("indexer_daemon_repair_identity_changed");
+        }
+        if (indexerDaemonAction === "none" && preAttachProbe.compatibility === "unreachable") {
+            indexerDaemonAction = "restarted-compatible-daemon";
+        }
+        return {
+            resetIndexerDatabase,
+            indexerDaemonAction,
+            indexerCompatibilityIssue,
+            indexerPostRepairHealth,
+        };
+    }
+    finally {
+        await daemon.close().catch(() => undefined);
+    }
+}

package/dist/wallet/lifecycle/repair-mining.d.ts

@@ -0,0 +1,49 @@
+import type { MiningRuntimeStatusV1 } from "../mining/types.js";
+import type { WalletRuntimePaths } from "../runtime.js";
+import { type WalletSecretProvider } from "../state/provider.js";
+import type { WalletStateV1 } from "../types.js";
+import type { WalletPrompter, WalletRepairResult } from "./types.js";
+export declare function createSilentNonInteractivePrompter(): WalletPrompter;
+export declare function applyRepairStoppedMiningState(state: WalletStateV1): WalletStateV1;
+export declare function createStoppedMiningRuntimeSnapshotForRepair(options: {
+    state: WalletStateV1;
+    snapshot: MiningRuntimeStatusV1 | null;
+    nowUnixMs: number;
+}): MiningRuntimeStatusV1;
+export declare function persistRepairState(options: {
+    state: WalletStateV1;
+    provider: WalletSecretProvider;
+    paths: WalletRuntimePaths;
+    nowUnixMs: number;
+    replacePrimary?: boolean;
+}): Promise<WalletStateV1>;
+export declare function cleanupMiningForRepair(options: {
+    paths: WalletRuntimePaths;
+    state: WalletStateV1;
+    snapshot: MiningRuntimeStatusV1 | null;
+    nowUnixMs: number;
+}): Promise<{
+    preRepairRunMode: WalletRepairResult["miningPreRepairRunMode"];
+}>;
+export declare function canResumeBackgroundMiningAfterRepair(options: {
+    provider: WalletSecretProvider;
+    paths: WalletRuntimePaths;
+    repairedState: WalletStateV1;
+    bitcoindPostRepairHealth: WalletRepairResult["bitcoindPostRepairHealth"];
+    indexerPostRepairHealth: WalletRepairResult["indexerPostRepairHealth"];
+}): Promise<boolean>;
+export declare function resumeBackgroundMiningAfterRepair(options: {
+    miningPreRepairRunMode: WalletRepairResult["miningPreRepairRunMode"];
+    provider: WalletSecretProvider;
+    paths: WalletRuntimePaths;
+    repairedState: WalletStateV1;
+    bitcoindPostRepairHealth: WalletRepairResult["bitcoindPostRepairHealth"];
+    indexerPostRepairHealth: WalletRepairResult["indexerPostRepairHealth"];
+    dataDir: string;
+    databasePath: string;
+    startBackgroundMining?: typeof import("../mining/runner.js").startBackgroundMining;
+}): Promise<{
+    miningResumeAction: WalletRepairResult["miningResumeAction"];
+    miningPostRepairRunMode: WalletRepairResult["miningPostRepairRunMode"];
+    miningResumeError: string | null;
+}>;

package/dist/wallet/lifecycle/repair-mining.js

@@ -0,0 +1,304 @@
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { readLockMetadata } from "../fs/lock.js";
+import { readMiningGenerationActivity } from "../mining/coordination.js";
+import { loadClientConfig } from "../mining/config.js";
+import { saveMiningRuntimeStatus } from "../mining/runtime-artifacts.js";
+import { normalizeMiningStateRecord } from "../mining/state.js";
+import { createWalletSecretReference } from "../state/provider.js";
+import { persistWalletStateUpdate } from "../descriptor-normalization.js";
+import { isProcessAlive, stopRecordedManagedProcess } from "./repair-runtime.js";
+export function createSilentNonInteractivePrompter() {
+    return {
+        isInteractive: false,
+        writeLine() { },
+        async prompt() {
+            return "";
+        },
+    };
+}
+export function applyRepairStoppedMiningState(state) {
+    const miningState = normalizeMiningStateRecord(state.miningState);
+    return {
+        ...state,
+        miningState: {
+            ...miningState,
+            runMode: "stopped",
+            state: miningState.livePublishInMempool
+                ? miningState.state === "paused-stale"
+                    ? "paused-stale"
+                    : "paused"
+                : miningState.state === "repair-required"
+                    ? "repair-required"
+                    : "idle",
+            pauseReason: miningState.livePublishInMempool
+                ? miningState.state === "paused-stale"
+                    ? "stale-block-context"
+                    : "wallet-repair"
+                : miningState.state === "repair-required"
+                    ? miningState.pauseReason
+                    : null,
+        },
+    };
+}
+function createStoppedBackgroundRuntimeSnapshot(snapshot, nowUnixMs) {
+    return {
+        ...snapshot,
+        updatedAtUnixMs: nowUnixMs,
+        runMode: "stopped",
+        backgroundWorkerPid: null,
+        backgroundWorkerRunId: null,
+        backgroundWorkerHeartbeatAtUnixMs: null,
+        backgroundWorkerHealth: null,
+        currentPhase: "idle",
+        note: snapshot.livePublishInMempool
+            ? "Background mining stopped for wallet repair. The last mining transaction may still confirm from mempool."
+            : "Background mining stopped for wallet repair.",
+    };
+}
+function resolveMiningGenerationRequestPath(paths) {
+    return join(paths.miningRoot, "generation-request.json");
+}
+function resolveMiningGenerationActivityPath(paths) {
+    return join(paths.miningRoot, "generation-activity.json");
+}
+function normalizeRepairMiningPid(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0
+        ? value
+        : null;
+}
+function createRepairStoppedMiningNote(livePublishInMempool) {
+    return livePublishInMempool
+        ? "Background mining stopped for wallet repair. The last mining transaction may still confirm from mempool."
+        : "Background mining stopped for wallet repair.";
+}
+export function createStoppedMiningRuntimeSnapshotForRepair(options) {
+    const stoppedMiningState = normalizeMiningStateRecord(applyRepairStoppedMiningState(options.state).miningState);
+    const note = createRepairStoppedMiningNote(stoppedMiningState.livePublishInMempool);
+    if (options.snapshot !== null) {
+        return {
+            ...createStoppedBackgroundRuntimeSnapshot(options.snapshot, options.nowUnixMs),
+            miningState: stoppedMiningState.state,
+            currentPublishState: stoppedMiningState.currentPublishState,
+            targetBlockHeight: stoppedMiningState.currentBlockTargetHeight,
+            referencedBlockHashDisplay: stoppedMiningState.currentReferencedBlockHashDisplay,
+            currentDomainId: stoppedMiningState.currentDomainId,
+            currentDomainName: stoppedMiningState.currentDomain,
+            currentSentenceDisplay: stoppedMiningState.currentSentence,
+            currentTxid: stoppedMiningState.currentTxid,
+            currentWtxid: stoppedMiningState.currentWtxid,
+            livePublishInMempool: stoppedMiningState.livePublishInMempool,
+            currentFeeRateSatVb: stoppedMiningState.currentFeeRateSatVb,
+            currentAbsoluteFeeSats: stoppedMiningState.currentAbsoluteFeeSats,
+            currentBlockFeeSpentSats: stoppedMiningState.currentBlockFeeSpentSats,
+            sessionFeeSpentSats: stoppedMiningState.sessionFeeSpentSats,
+            lifetimeFeeSpentSats: stoppedMiningState.lifetimeFeeSpentSats,
+            currentPublishDecision: stoppedMiningState.currentPublishDecision,
+            pauseReason: stoppedMiningState.pauseReason,
+            note,
+        };
+    }
+    return {
+        schemaVersion: 1,
+        walletRootId: options.state.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: stoppedMiningState.state,
+        currentPhase: "idle",
+        currentPublishState: stoppedMiningState.currentPublishState,
+        targetBlockHeight: stoppedMiningState.currentBlockTargetHeight,
+        referencedBlockHashDisplay: stoppedMiningState.currentReferencedBlockHashDisplay,
+        currentDomainId: stoppedMiningState.currentDomainId,
+        currentDomainName: stoppedMiningState.currentDomain,
+        currentSentenceDisplay: stoppedMiningState.currentSentence,
+        currentCanonicalBlend: null,
+        currentTxid: stoppedMiningState.currentTxid,
+        currentWtxid: stoppedMiningState.currentWtxid,
+        livePublishInMempool: stoppedMiningState.livePublishInMempool,
+        currentFeeRateSatVb: stoppedMiningState.currentFeeRateSatVb,
+        currentAbsoluteFeeSats: stoppedMiningState.currentAbsoluteFeeSats,
+        currentBlockFeeSpentSats: stoppedMiningState.currentBlockFeeSpentSats,
+        sessionFeeSpentSats: stoppedMiningState.sessionFeeSpentSats,
+        lifetimeFeeSpentSats: stoppedMiningState.lifetimeFeeSpentSats,
+        sameDomainCompetitorSuppressed: null,
+        higherRankedCompetitorDomainCount: null,
+        dedupedCompetitorDomainCount: null,
+        competitivenessGateIndeterminate: null,
+        mempoolSequenceCacheStatus: null,
+        currentPublishDecision: stoppedMiningState.currentPublishDecision,
+        lastMempoolSequence: null,
+        lastCompetitivenessGateAtUnixMs: null,
+        pauseReason: stoppedMiningState.pauseReason,
+        providerConfigured: false,
+        providerKind: null,
+        bitcoindHealth: "unavailable",
+        bitcoindServiceState: null,
+        bitcoindReplicaStatus: null,
+        nodeHealth: "unavailable",
+        indexerHealth: "unavailable",
+        tipsAligned: null,
+        lastEventAtUnixMs: null,
+        lastError: null,
+        note,
+    };
+}
+export async function persistRepairState(options) {
+    return await persistWalletStateUpdate({
+        state: options.state,
+        access: {
+            provider: options.provider,
+            secretReference: createWalletSecretReference(options.state.walletRootId),
+        },
+        paths: options.paths,
+        nowUnixMs: options.nowUnixMs,
+        replacePrimary: options.replacePrimary,
+    });
+}
+export async function cleanupMiningForRepair(options) {
+    const controlLockMetadata = await readLockMetadata(options.paths.miningControlLockPath).catch(() => null);
+    const generationActivity = await readMiningGenerationActivity(options.paths).catch(() => null);
+    const controlLockPid = normalizeRepairMiningPid(controlLockMetadata?.processId);
+    const backgroundWorkerPid = normalizeRepairMiningPid(options.snapshot?.backgroundWorkerPid);
+    const generationOwnerPid = normalizeRepairMiningPid(generationActivity?.generationOwnerPid);
+    const discoveredPids = new Set();
+    let backgroundWorkerAlive = false;
+    let foregroundWorkerAlive = false;
+    const pidSources = [
+        { pid: backgroundWorkerPid, source: "background" },
+        { pid: controlLockPid, source: "foreground" },
+        { pid: generationOwnerPid, source: "foreground" },
+    ];
+    for (const source of pidSources) {
+        if (source.pid === null || source.pid === process.pid || !await isProcessAlive(source.pid)) {
+            continue;
+        }
+        discoveredPids.add(source.pid);
+        if (source.source === "background") {
+            backgroundWorkerAlive = true;
+        }
+        else {
+            foregroundWorkerAlive = true;
+        }
+    }
+    for (const pid of discoveredPids) {
+        await stopRecordedManagedProcess(pid, "mining_process_stop_timeout");
+    }
+    await rm(options.paths.miningControlLockPath, { force: true }).catch(() => undefined);
+    await rm(resolveMiningGenerationRequestPath(options.paths), { force: true }).catch(() => undefined);
+    await rm(resolveMiningGenerationActivityPath(options.paths), { force: true }).catch(() => undefined);
+    await saveMiningRuntimeStatus(options.paths.miningStatusPath, createStoppedMiningRuntimeSnapshotForRepair({
+        state: options.state,
+        snapshot: options.snapshot,
+        nowUnixMs: options.nowUnixMs,
+    }));
+    return {
+        preRepairRunMode: backgroundWorkerAlive
+            ? "background"
+            : foregroundWorkerAlive
+                ? "foreground"
+                : "stopped",
+    };
+}
+export async function canResumeBackgroundMiningAfterRepair(options) {
+    if (options.bitcoindPostRepairHealth !== "ready"
+        || options.indexerPostRepairHealth !== "synced"
+        || normalizeMiningStateRecord(options.repairedState.miningState).state === "repair-required") {
+        return false;
+    }
+    try {
+        const config = await loadClientConfig({
+            path: options.paths.clientConfigPath,
+            provider: options.provider,
+        });
+        return config?.mining.builtIn != null;
+    }
+    catch {
+        return false;
+    }
+}
+export async function resumeBackgroundMiningAfterRepair(options) {
+    const miningWasResumable = options.miningPreRepairRunMode === "background"
+        && normalizeMiningStateRecord(options.repairedState.miningState).state !== "repair-required";
+    if (options.miningPreRepairRunMode !== "background") {
+        return {
+            miningResumeAction: "none",
+            miningPostRepairRunMode: "stopped",
+            miningResumeError: null,
+        };
+    }
+    if (!miningWasResumable) {
+        return {
+            miningResumeAction: "skipped-not-resumable",
+            miningPostRepairRunMode: "stopped",
+            miningResumeError: null,
+        };
+    }
+    const postRepairResumeReady = await canResumeBackgroundMiningAfterRepair({
+        provider: options.provider,
+        paths: options.paths,
+        repairedState: options.repairedState,
+        bitcoindPostRepairHealth: options.bitcoindPostRepairHealth,
+        indexerPostRepairHealth: options.indexerPostRepairHealth,
+    });
+    if (!postRepairResumeReady) {
+        return {
+            miningResumeAction: "skipped-post-repair-blocked",
+            miningPostRepairRunMode: "stopped",
+            miningResumeError: null,
+        };
+    }
+    try {
+        const startBackgroundMining = options.startBackgroundMining
+            ?? (await import("../mining/runner.js")).startBackgroundMining;
+        const resumed = await startBackgroundMining({
+            dataDir: options.dataDir,
+            databasePath: options.databasePath,
+            provider: options.provider,
+            paths: options.paths,
+            prompter: createSilentNonInteractivePrompter(),
+        });
+        if (resumed.snapshot?.runMode === "background") {
+            return {
+                miningResumeAction: "resumed-background",
+                miningPostRepairRunMode: "background",
+                miningResumeError: null,
+            };
+        }
+        return {
+            miningResumeAction: "resume-failed",
+            miningPostRepairRunMode: "stopped",
+            miningResumeError: "Background mining did not report a background runtime after repair.",
+        };
+    }
+    catch (error) {
+        return {
+            miningResumeAction: "resume-failed",
+            miningPostRepairRunMode: "stopped",
+            miningResumeError: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/wallet/lifecycle/repair-runtime.d.ts

@@ -0,0 +1,36 @@
+import { attachOrStartIndexerDaemon, probeIndexerDaemon } from "../../bitcoind/indexer-daemon.js";
+import { probeManagedBitcoindService } from "../../bitcoind/service.js";
+import { resolveManagedServicePaths } from "../../bitcoind/service-paths.js";
+import type { ManagedBitcoindServiceStatus } from "../../bitcoind/types.js";
+import type { WalletRepairResult } from "./types.js";
+export declare function ensureIndexerDatabaseHealthy(options: {
+    databasePath: string;
+    dataDir: string;
+    walletRootId: string;
+    resetIfNeeded: boolean;
+}): Promise<boolean>;
+export declare function mapIndexerCompatibilityToRepairIssue(compatibility: Awaited<ReturnType<typeof probeIndexerDaemon>>["compatibility"]): WalletRepairResult["indexerCompatibilityIssue"];
+export declare function mapBitcoindCompatibilityToRepairIssue(compatibility: Awaited<ReturnType<typeof probeManagedBitcoindService>>["compatibility"]): WalletRepairResult["bitcoindCompatibilityIssue"];
+export declare function mapBitcoindRepairHealth(options: {
+    serviceState: ManagedBitcoindServiceStatus["state"] | null;
+    catchingUp: boolean;
+    replica: {
+        proofStatus?: "missing" | "mismatch" | "ready" | "not-proven";
+    } | null;
+}): WalletRepairResult["bitcoindPostRepairHealth"];
+export declare function verifyIndexerPostRepairHealth(options: {
+    daemon: Awaited<ReturnType<typeof attachOrStartIndexerDaemon>>;
+    probeIndexerDaemon: typeof probeIndexerDaemon;
+    dataDir: string;
+    walletRootId: string;
+    nowUnixMs: number;
+}): Promise<{
+    health: WalletRepairResult["indexerPostRepairHealth"];
+    daemonInstanceId: string;
+}>;
+export declare function isProcessAlive(pid: number | null): Promise<boolean>;
+export declare function waitForProcessExit(pid: number, timeoutMs?: number, errorCode?: string): Promise<void>;
+export declare function clearIndexerDaemonArtifacts(servicePaths: ReturnType<typeof resolveManagedServicePaths>): Promise<void>;
+export declare function clearManagedBitcoindArtifacts(servicePaths: ReturnType<typeof resolveManagedServicePaths>): Promise<void>;
+export declare function stopRecordedManagedProcess(pid: number | null, errorCode: string): Promise<void>;
+export declare function clearOrphanedRepairLocks(lockPaths: readonly string[]): Promise<void>;