@cogcoin/client 1.1.5 → 1.1.7

package/dist/wallet/lifecycle/types.d.ts

@@ -3,7 +3,6 @@ import type { createRpcClient } from "../../bitcoind/node.js";
 import type { attachOrStartManagedBitcoindService, probeManagedBitcoindService } from "../../bitcoind/service.js";
 import type { RpcListUnspentEntry } from "../../bitcoind/types.js";
 import type { requestMiningGenerationPreemption } from "../mining/coordination.js";
-import type { startBackgroundMining } from "../mining/runner.js";
 import type { WalletRuntimePaths } from "../runtime.js";
 import type { WalletSecretProvider } from "../state/provider.js";
 import type { WalletStateV1 } from "../types.js";
@@ -45,7 +44,7 @@ export interface WalletRepairResult {
     indexerCompatibilityIssue: "none" | "service-version-mismatch" | "wallet-root-mismatch" | "schema-mismatch";
     indexerPostRepairHealth: "starting" | "catching-up" | "synced" | "failed";
     miningPreRepairRunMode: "stopped" | "foreground" | "background";
-    miningResumeAction: "none" | "skipped-not-resumable" | "skipped-post-repair-blocked" | "resumed-background" | "resume-failed";
+    miningResumeAction: "none" | "skipped-not-resumable" | "skipped-post-repair-blocked" | "skipped-background-mode-removed";
     miningPostRepairRunMode: "stopped" | "background";
     miningResumeError: string | null;
     note: string | null;
@@ -107,7 +106,18 @@ export interface WalletLifecycleResolvedContext {
     paths: WalletRuntimePaths;
     nowUnixMs: number;
 }
-export interface WalletSetupContext extends WalletLifecycleResolvedContext, WalletSetupDependencies {
+export interface WalletManagedCoreContext extends WalletLifecycleResolvedContext {
+    attachService: NonNullable<WalletManagedCoreDependencies["attachService"]>;
+    rpcFactory: NonNullable<WalletManagedCoreDependencies["rpcFactory"]>;
+}
+export interface WalletAccessContext extends WalletManagedCoreContext {
+    dataDir?: string;
+}
+export interface WalletLoadedState {
+    state: WalletStateV1;
+    source: "primary" | "backup";
+}
+export interface WalletSetupContext extends WalletManagedCoreContext {
     dataDir: string;
     prompter: WalletPrompter;
 }
@@ -116,10 +126,28 @@ export interface WalletRepairDependencies extends WalletManagedCoreDependencies
     attachIndexerDaemon?: typeof attachOrStartIndexerDaemon;
     probeIndexerDaemon?: typeof probeIndexerDaemon;
     requestMiningPreemption?: typeof requestMiningGenerationPreemption;
-    startBackgroundMining?: typeof startBackgroundMining;
 }
-export interface WalletRepairContext extends WalletLifecycleResolvedContext, WalletRepairDependencies {
+export interface WalletRepairContext extends WalletManagedCoreContext {
     dataDir: string;
     databasePath: string;
     assumeYes: boolean;
+    probeBitcoindService: NonNullable<WalletRepairDependencies["probeBitcoindService"]>;
+    attachIndexerDaemon: NonNullable<WalletRepairDependencies["attachIndexerDaemon"]>;
+    probeIndexerDaemon: NonNullable<WalletRepairDependencies["probeIndexerDaemon"]>;
+    requestMiningPreemption?: WalletRepairDependencies["requestMiningPreemption"];
+}
+export interface WalletBitcoindRepairStageResult {
+    state: WalletStateV1;
+    repairStateNeedsPersist: boolean;
+    recreatedManagedCoreWallet: boolean;
+    bitcoindServiceAction: WalletRepairResult["bitcoindServiceAction"];
+    bitcoindCompatibilityIssue: WalletRepairResult["bitcoindCompatibilityIssue"];
+    managedCoreReplicaAction: WalletRepairResult["managedCoreReplicaAction"];
+    bitcoindPostRepairHealth: WalletRepairResult["bitcoindPostRepairHealth"];
+}
+export interface WalletIndexerRepairStageResult {
+    resetIndexerDatabase: boolean;
+    indexerDaemonAction: WalletRepairResult["indexerDaemonAction"];
+    indexerCompatibilityIssue: WalletRepairResult["indexerCompatibilityIssue"];
+    indexerPostRepairHealth: WalletRepairResult["indexerPostRepairHealth"];
 }

package/dist/wallet/managed-core-wallet.d.ts

@@ -8,6 +8,8 @@ export declare function withUnlockedManagedCoreWallet<T>(options: {
     walletName: string;
     internalPassphrase: string;
     timeoutSeconds?: number;
+    recoverLockedWalletOnce?: boolean;
+    onLockedWalletRecoveryOutcome?: (outcome: "recovered" | "still-locked") => void;
     run: () => Promise<T>;
 }): Promise<T>;
 export declare function clearLegacyWalletLockArtifacts(walletRuntimeRoot: string): Promise<void>;

package/dist/wallet/managed-core-wallet.js

@@ -3,10 +3,36 @@ import { join } from "node:path";
 export const MANAGED_CORE_WALLET_UNLOCK_TIMEOUT_SECONDS = 10;
 const LEGACY_UNLOCK_SESSION_FILENAME = "wallet-unlock-session.enc";
 const LEGACY_EXPLICIT_LOCK_FILENAME = "wallet-explicit-lock.json";
+const MANAGED_CORE_WALLET_PROCESS_PSBT_LOCKED_ERROR_PREFIX = "bitcoind_rpc_walletprocesspsbt_-13_";
+const MANAGED_CORE_WALLET_PROCESS_PSBT_LOCKED_ERROR_SUFFIX = "Please enter the wallet passphrase with walletpassphrase first.";
+function isManagedCoreWalletProcessPsbtLockedError(error) {
+    return error instanceof Error
+        && error.message.startsWith(MANAGED_CORE_WALLET_PROCESS_PSBT_LOCKED_ERROR_PREFIX)
+        && error.message.endsWith(MANAGED_CORE_WALLET_PROCESS_PSBT_LOCKED_ERROR_SUFFIX);
+}
 export async function withUnlockedManagedCoreWallet(options) {
     await options.rpc.walletPassphrase(options.walletName, options.internalPassphrase, options.timeoutSeconds ?? MANAGED_CORE_WALLET_UNLOCK_TIMEOUT_SECONDS);
     try {
-        return await options.run();
+        try {
+            return await options.run();
+        }
+        catch (error) {
+            if (!options.recoverLockedWalletOnce || !isManagedCoreWalletProcessPsbtLockedError(error)) {
+                throw error;
+            }
+            await options.rpc.walletPassphrase(options.walletName, options.internalPassphrase, options.timeoutSeconds ?? MANAGED_CORE_WALLET_UNLOCK_TIMEOUT_SECONDS);
+            try {
+                const result = await options.run();
+                options.onLockedWalletRecoveryOutcome?.("recovered");
+                return result;
+            }
+            catch (retryError) {
+                if (isManagedCoreWalletProcessPsbtLockedError(retryError)) {
+                    options.onLockedWalletRecoveryOutcome?.("still-locked");
+                }
+                throw retryError;
+            }
+        }
     }
     finally {
         await options.rpc.walletLock(options.walletName).catch(() => undefined);

package/dist/wallet/mining/candidate.d.ts

@@ -56,5 +56,6 @@ export declare function generateCandidatesForDomains(options: {
     indexerTruthKey: IndexerTruthKey | null;
     runId?: string | null;
     fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
 }): Promise<MiningCandidate[]>;
 export declare function chooseBestLocalCandidate(candidates: MiningCandidate[]): Promise<MiningCandidate | null>;

package/dist/wallet/mining/candidate.js

@@ -5,6 +5,7 @@ import { loadClientConfig } from "./config.js";
 import { isMiningGenerationAbortRequested, markMiningGenerationActive, markMiningGenerationInactive, } from "./coordination.js";
 import { createMiningSentenceRequestLimits } from "./sentence-protocol.js";
 import { generateMiningSentences } from "./sentences.js";
+import { createMiningStopRequestedError } from "./stop.js";
 import { isMineableWalletDomain } from "../read/index.js";
 import { lookupDomain } from "@cogcoin/indexer/queries";
 const BEST_BLOCK_POLL_INTERVAL_MS = 500;
@@ -142,6 +143,11 @@ export async function generateCandidatesForDomains(options) {
     let stale = false;
     let staleIndexerTruth = false;
     let preempted = false;
+    let stopRequested = false;
+    const handleStop = () => {
+        stopRequested = true;
+        abortController.abort(options.signal?.reason ?? createMiningStopRequestedError());
+    };
     const timer = setInterval(async () => {
         try {
             const [current, truthCurrent] = await Promise.all([
@@ -171,6 +177,12 @@ export async function generateCandidatesForDomains(options) {
         }
     }, BEST_BLOCK_POLL_INTERVAL_MS);
     try {
+        if (options.signal?.aborted) {
+            handleStop();
+        }
+        else {
+            options.signal?.addEventListener("abort", handleStop, { once: true });
+        }
         await markMiningGenerationActive({
             paths: options.paths,
             runId: options.runId ?? null,
@@ -185,12 +197,26 @@ export async function generateCandidatesForDomains(options) {
         });
         let generated;
         try {
-            generated = await generateMiningSentences(generationRequest, {
-                paths: options.paths,
-                provider: options.provider,
-                signal: abortController.signal,
-                fetchImpl: options.fetchImpl,
-            });
+            generated = await Promise.race([
+                generateMiningSentences(generationRequest, {
+                    paths: options.paths,
+                    provider: options.provider,
+                    signal: abortController.signal,
+                    fetchImpl: options.fetchImpl,
+                }),
+                new Promise((_resolve, reject) => {
+                    const handleAbort = () => {
+                        reject(abortController.signal.reason instanceof Error
+                            ? abortController.signal.reason
+                            : createMiningStopRequestedError());
+                    };
+                    if (abortController.signal.aborted) {
+                        handleAbort();
+                        return;
+                    }
+                    abortController.signal.addEventListener("abort", handleAbort, { once: true });
+                }),
+            ]);
         }
         catch (error) {
             if (stale) {
@@ -202,6 +228,11 @@ export async function generateCandidatesForDomains(options) {
             if (preempted) {
                 throw new Error("mining_generation_preempted");
             }
+            if (stopRequested || options.signal?.aborted) {
+                throw options.signal?.reason instanceof Error
+                    ? options.signal.reason
+                    : createMiningStopRequestedError();
+            }
             throw error;
         }
         if (stale) {
@@ -253,6 +284,7 @@ export async function generateCandidatesForDomains(options) {
     }
     finally {
         clearInterval(timer);
+        options.signal?.removeEventListener("abort", handleStop);
         await markMiningGenerationInactive({
             paths: options.paths,
             runId: options.runId ?? null,

package/dist/wallet/mining/competitiveness.d.ts

@@ -19,4 +19,5 @@ export declare function runCompetitivenessGate(options: {
     assaySentencesImpl?: typeof assaySentences;
     cooperativeYield?: MiningCooperativeYield;
     cooperativeYieldEvery?: number;
+    throwIfStopping?: () => void;
 }): Promise<CompetitivenessDecision>;

package/dist/wallet/mining/competitiveness.js

@@ -371,6 +371,7 @@ export async function runCompetitivenessGate(options) {
     let mempoolVerbose;
     try {
         mempoolVerbose = await options.rpc.getRawMempoolVerbose();
+        options.throwIfStopping?.();
     }
     catch {
         return createDecision({
@@ -415,6 +416,7 @@ export async function runCompetitivenessGate(options) {
             cooperativeYield: options.cooperativeYield,
             cooperativeYieldEvery: options.cooperativeYieldEvery,
         });
+        options.throwIfStopping?.();
         const txid = visibleTxids[index];
         if (txContexts.has(txid)) {
             continue;
@@ -423,6 +425,7 @@ export async function runCompetitivenessGate(options) {
             options.rpc.getRawTransaction(txid, true).catch(() => null),
             options.rpc.getMempoolEntry(txid).catch(() => null),
         ]);
+        options.throwIfStopping?.();
         if (tx === null || mempoolEntry === null) {
             continue;
         }
@@ -447,6 +450,7 @@ export async function runCompetitivenessGate(options) {
             cooperativeYield: options.cooperativeYield,
             cooperativeYieldEvery: options.cooperativeYieldEvery,
         });
+        options.throwIfStopping?.();
         const txid = visibleTxids[index];
         const context = txContexts.get(txid);
         if (context === undefined || context.payload === null || context.senderScriptHex === null) {
@@ -463,6 +467,7 @@ export async function runCompetitivenessGate(options) {
             domainId: decoded.domainId,
             senderScriptHex: context.senderScriptHex,
         });
+        options.throwIfStopping?.();
         if (overlayDomain === "indeterminate") {
             const decision = createDecision({
                 competitivenessGateIndeterminate: true,
@@ -487,6 +492,7 @@ export async function runCompetitivenessGate(options) {
             continue;
         }
         const assayed = await assaySentencesImpl(decoded.domainId, options.candidate.referencedBlockHashInternal, [Buffer.from(decoded.sentenceBytes).toString("utf8")]).catch(() => []);
+        options.throwIfStopping?.();
         const scored = assayed[0];
         if (scored === undefined || !scored.gatesPass || scored.encodedSentenceBytes === null || scored.canonicalBlend === null) {
             continue;

package/dist/wallet/mining/cycle.d.ts

@@ -27,6 +27,7 @@ export declare function runMiningPhaseMachine(options: {
     attachService: typeof attachOrStartManagedBitcoindService;
     rpcFactory: (config: Parameters<typeof createRpcClient>[0]) => MiningRpcClient;
     fetchImpl?: typeof fetch;
+    stopSignal?: AbortSignal;
     generateCandidatesForDomainsImpl?: typeof generateCandidatesForDomains;
     runCompetitivenessGateImpl?: typeof runCompetitivenessGate;
     assaySentencesImpl?: typeof assaySentences;
@@ -35,5 +36,6 @@ export declare function runMiningPhaseMachine(options: {
     nowImpl?: () => number;
     saveCycleStatus: (readContext: WalletReadContext, overrides: MiningRuntimeStatusOverrides) => Promise<MiningRuntimeStatusV1>;
     appendEvent: (event: MiningEventRecord) => Promise<void>;
+    throwIfStopping?: () => void;
     throwIfSuspendDetected?: () => void;
 }): Promise<void>;

package/dist/wallet/mining/cycle.js

@@ -59,7 +59,12 @@ export async function runMiningPhaseMachine(options) {
             return false;
         }
     };
+    const throwIfInterrupted = () => {
+        options.throwIfSuspendDetected?.();
+        options.throwIfStopping?.();
+    };
     while (true) {
+        throwIfInterrupted();
         switch (state.phase) {
             case "idle": {
                 if (options.corePublishState !== "healthy") {
@@ -198,8 +203,9 @@ export async function runMiningPhaseMachine(options) {
                         indexerTruthKey,
                         runId: options.backgroundWorkerRunId,
                         fetchImpl: options.fetchImpl,
+                        signal: options.stopSignal,
                     });
-                    options.throwIfSuspendDetected?.();
+                    throwIfInterrupted();
                 }
                 catch (error) {
                     if (error instanceof MiningProviderRequestError) {
@@ -341,8 +347,9 @@ export async function runMiningPhaseMachine(options) {
                     assaySentencesImpl: options.assaySentencesImpl,
                     cooperativeYield: options.cooperativeYieldImpl,
                     cooperativeYieldEvery: options.cooperativeYieldEvery,
+                    throwIfStopping: options.throwIfStopping,
                 });
-                options.throwIfSuspendDetected?.();
+                throwIfInterrupted();
                 state.gateSnapshot = {
                     higherRankedCompetitorDomainCount: gate.higherRankedCompetitorDomainCount,
                     dedupedCompetitorDomainCount: gate.dedupedCompetitorDomainCount,
@@ -421,7 +428,7 @@ export async function runMiningPhaseMachine(options) {
                     if (!await ensureCurrentIndexerTruthOrRestart()) {
                         return;
                     }
-                    options.throwIfSuspendDetected?.();
+                    throwIfInterrupted();
                     const published = await publishCandidate({
                         dataDir: options.dataDir,
                         databasePath: options.databasePath,
@@ -436,6 +443,7 @@ export async function runMiningPhaseMachine(options) {
                         appendEventFn: async (_paths, event) => {
                             await options.appendEvent(event);
                         },
+                        throwIfStopping: options.throwIfStopping,
                     });
                     if (state.tipKey !== null
                         && published.retryable !== true
@@ -462,6 +470,7 @@ export async function runMiningPhaseMachine(options) {
                             mempoolSequenceCacheStatus: state.gateSnapshot.mempoolSequenceCacheStatus,
                             lastMempoolSequence: state.gateSnapshot.lastMempoolSequence,
                             lastCompetitivenessGateAtUnixMs: now(),
+                            lastError: published.lastError ?? null,
                             note: published.note,
                             livePublishInMempool: published.state.miningState.livePublishInMempool,
                         });
@@ -473,7 +482,7 @@ export async function runMiningPhaseMachine(options) {
                         options.loopState.waitingNote = published.note;
                         const lastError = published.decision === "publish-paused-insufficient-funds"
                             ? published.lastError ?? createInsufficientFundsMiningPublishErrorMessage()
-                            : undefined;
+                            : null;
                         await options.saveCycleStatus({
                             ...options.readContext,
                             localState: {
@@ -526,6 +535,7 @@ export async function runMiningPhaseMachine(options) {
                         mempoolSequenceCacheStatus: state.gateSnapshot.mempoolSequenceCacheStatus,
                         lastMempoolSequence: state.gateSnapshot.lastMempoolSequence,
                         lastCompetitivenessGateAtUnixMs: now(),
+                        lastError: null,
                         note: options.loopState.waitingNote,
                         livePublishInMempool: published.state.miningState.livePublishInMempool,
                     });

package/dist/wallet/mining/engine-types.d.ts

@@ -103,6 +103,7 @@ export interface MiningPublishRetryResult {
     txid: null;
     decision: "publish-retry-pending";
     note: string;
+    lastError?: string | null;
     skipped?: false;
     retryable: true;
     candidate: MiningCandidate;

package/dist/wallet/mining/index.d.ts

@@ -1,7 +1,7 @@
 export { isMiningGenerationAbortRequested, markMiningGenerationActive, markMiningGenerationInactive, readMiningGenerationActivity, readMiningPreemptionRequest, requestMiningGenerationPreemption, } from "./coordination.js";
 export { canonicalizeMiningDomainPromptName, inspectMiningDomainPromptState, updateMiningDomainPrompt, } from "./domain-prompts.js";
 export { followMiningLog, inspectMiningControlPlane, readMiningLog, refreshMiningRuntimeStatus, setupBuiltInMining, } from "./control.js";
-export { ensureBuiltInMiningSetupIfNeeded, runBackgroundMiningWorker, runForegroundMining, startBackgroundMining, stopBackgroundMining, type MiningStartResult, } from "./runner.js";
+export { ensureBuiltInMiningSetupIfNeeded, runForegroundMining, } from "./runner.js";
 export { appendMiningEvent, loadMiningRuntimeStatus, readMiningEvents, resolveRotatedMiningEventsPath, saveMiningRuntimeStatus, } from "./runtime-artifacts.js";
 export type { MiningSentenceCandidateV1, MiningSentenceGenerationRequestV1, MiningSentenceGenerationResponseV1, } from "./sentence-protocol.js";
 export { loadClientConfig, saveBuiltInMiningProviderConfig, saveClientConfig, } from "./config.js";

package/dist/wallet/mining/index.js

@@ -1,6 +1,6 @@
 export { isMiningGenerationAbortRequested, markMiningGenerationActive, markMiningGenerationInactive, readMiningGenerationActivity, readMiningPreemptionRequest, requestMiningGenerationPreemption, } from "./coordination.js";
 export { canonicalizeMiningDomainPromptName, inspectMiningDomainPromptState, updateMiningDomainPrompt, } from "./domain-prompts.js";
 export { followMiningLog, inspectMiningControlPlane, readMiningLog, refreshMiningRuntimeStatus, setupBuiltInMining, } from "./control.js";
-export { ensureBuiltInMiningSetupIfNeeded, runBackgroundMiningWorker, runForegroundMining, startBackgroundMining, stopBackgroundMining, } from "./runner.js";
+export { ensureBuiltInMiningSetupIfNeeded, runForegroundMining, } from "./runner.js";
 export { appendMiningEvent, loadMiningRuntimeStatus, readMiningEvents, resolveRotatedMiningEventsPath, saveMiningRuntimeStatus, } from "./runtime-artifacts.js";
 export { loadClientConfig, saveBuiltInMiningProviderConfig, saveClientConfig, } from "./config.js";

package/dist/wallet/mining/publish.d.ts

@@ -14,6 +14,7 @@ export declare class MiningPublishRejectedError extends Error {
 }
 export declare function createStaleMiningCandidateWaitingNote(): string;
 export declare function createRetryableMiningPublishWaitingNote(): string;
+export declare function createManagedCoreWalletRelockRetryWaitingNote(): string;
 export declare function createInsufficientFundsMiningPublishWaitingNote(): string;
 export declare function createInsufficientFundsMiningPublishErrorMessage(): string;
 export declare function resolveMiningConflictOutpoint(options: {
@@ -56,6 +57,7 @@ export declare function publishCandidateOnce(options: {
     rpcFactory: (config: Parameters<typeof createRpcClient>[0]) => MiningRpcClient;
     runId: string | null;
     appendEventFn?: AppendMiningEventFn;
+    throwIfStopping?: () => void;
 }): Promise<{
     state: WalletStateV1;
     txid: string | null;
@@ -75,5 +77,6 @@ export declare function publishCandidate(options: {
     runId: string | null;
     publishAttempt?: typeof publishCandidateOnce;
     appendEventFn: AppendMiningEventFn;
+    throwIfStopping?: () => void;
 }): Promise<MiningPublishOutcome>;
 export {};

package/dist/wallet/mining/publish.js

@@ -22,12 +22,21 @@ export class MiningPublishRejectedError extends Error {
         this.revertedState = revertedState;
     }
 }
+class ManagedCoreWalletRelockPendingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ManagedCoreWalletRelockPendingError";
+    }
+}
 export function createStaleMiningCandidateWaitingNote() {
     return "Mining candidate changed before broadcast: the selected root domain is no longer locally mineable. Skipping this tip and waiting for the next block.";
 }
 export function createRetryableMiningPublishWaitingNote() {
     return "Selected mining candidate did not reach mempool and will be retried on the current tip with refreshed wallet state.";
 }
+export function createManagedCoreWalletRelockRetryWaitingNote() {
+    return "Mining temporarily lost the managed Bitcoin wallet unlock and is retrying.";
+}
 export function createInsufficientFundsMiningPublishWaitingNote() {
     return "Insufficient BTC to mine.";
 }
@@ -114,6 +123,8 @@ async function buildMiningTransaction(options) {
         mempoolRejectPrefix: "wallet_mining_mempool_rejected",
         feeRate: options.plan.feeRateSatVb,
         availableFundingMinConf: MINING_FUNDING_MIN_CONF,
+        recoverManagedCoreWalletLockedOnce: options.recoverManagedCoreWalletLockedOnce,
+        onManagedCoreWalletLockedRecoveryOutcome: options.onManagedCoreWalletLockedRecoveryOutcome,
     });
 }
 export async function probeMiningFundingAvailability(options) {
@@ -301,6 +312,7 @@ export async function publishCandidateOnce(options) {
         startHeight: 0,
         walletRootId: options.readContext.localState.state.walletRootId,
     });
+    options.throwIfStopping?.();
     const rpc = options.rpcFactory(service.rpc);
     let state = (await reconcileLiveMiningState({
         state: options.readContext.localState.state,
@@ -309,7 +321,9 @@ export async function publishCandidateOnce(options) {
         nodeBestHeight: options.readContext.nodeStatus?.nodeBestHeight ?? null,
         snapshotState: options.readContext.snapshot.state,
     })).state;
+    options.throwIfStopping?.();
     const allUtxos = await rpc.listUnspent(state.managedCoreWallet.walletName, MINING_FUNDING_MIN_CONF);
+    options.throwIfStopping?.();
     const conflictOutpoint = resolveMiningConflictOutpoint({
         state,
         allUtxos,
@@ -330,6 +344,7 @@ export async function publishCandidateOnce(options) {
     const feeSelection = await resolveWalletMutationFeeSelection({
         rpc,
     });
+    options.throwIfStopping?.();
     const nextFeeRate = feeSelection.feeRateSatVb;
     const plan = createMiningPlan({
         state,
@@ -338,12 +353,40 @@ export async function publishCandidateOnce(options) {
         allUtxos,
         feeRateSatVb: nextFeeRate,
     });
-    const built = await buildMiningTransaction({
-        rpc,
-        walletName: state.managedCoreWallet.walletName,
-        state,
-        plan,
-    });
+    let managedCoreWalletRelockOutcome = null;
+    let built;
+    try {
+        built = await buildMiningTransaction({
+            rpc,
+            walletName: state.managedCoreWallet.walletName,
+            state,
+            plan,
+            recoverManagedCoreWalletLockedOnce: true,
+            onManagedCoreWalletLockedRecoveryOutcome: (outcome) => {
+                managedCoreWalletRelockOutcome = outcome;
+            },
+        });
+    }
+    catch (error) {
+        if (managedCoreWalletRelockOutcome === "still-locked" && error instanceof Error) {
+            throw new ManagedCoreWalletRelockPendingError(error.message);
+        }
+        throw error;
+    }
+    options.throwIfStopping?.();
+    if (managedCoreWalletRelockOutcome === "recovered" && appendEventFn !== undefined) {
+        await appendEventFn(options.paths, createMiningEventRecord("managed-core-wallet-relock-recovered", "Managed Bitcoin Core wallet relocked during signing and was recovered automatically.", {
+            level: "warn",
+            runId: options.runId,
+            targetBlockHeight: options.candidate.targetBlockHeight,
+            referencedBlockHashDisplay: options.candidate.referencedBlockHashDisplay,
+            domainId: options.candidate.domainId,
+            domainName: options.candidate.domainName,
+            feeRateSatVb: nextFeeRate,
+            score: options.candidate.canonicalBlend.toString(),
+            reason: "managed-core-wallet-locked",
+        }));
+    }
     const intentFingerprintHex = computeIntentFingerprint(state, options.candidate);
     state = defaultMiningStatePatch(state, {
         state: "live",
@@ -375,8 +418,10 @@ export async function publishCandidateOnce(options) {
         provider: options.provider,
         paths: options.paths,
     });
+    options.throwIfStopping?.();
     try {
         await rpc.sendRawTransaction(built.rawHex);
+        options.throwIfStopping?.();
     }
     catch (error) {
         if (isAlreadyAcceptedError(error)) {
@@ -521,6 +566,7 @@ export async function publishCandidate(options) {
             candidate: null,
         };
     };
+    options.throwIfStopping?.();
     const lockedReadContext = await options.openReadContext({
         dataDir: options.dataDir,
         databasePath: options.databasePath,
@@ -529,6 +575,7 @@ export async function publishCandidate(options) {
         paths: options.paths,
     });
     try {
+        options.throwIfStopping?.();
         if (lockedReadContext.localState.availability !== "ready"
             || lockedReadContext.localState.state === null
             || lockedReadContext.snapshot === null
@@ -541,6 +588,7 @@ export async function publishCandidate(options) {
             return await createStaleCandidateSkipResult(readyReadContext.localState.state);
         }
         try {
+            options.throwIfStopping?.();
             const published = await publishAttempt({
                 readContext: readyReadContext,
                 candidate: refreshedCandidate,
@@ -551,6 +599,7 @@ export async function publishCandidate(options) {
                 rpcFactory: options.rpcFactory,
                 runId: options.runId,
                 appendEventFn: options.appendEventFn,
+                throwIfStopping: options.throwIfStopping,
             });
             return {
                 ...published,
@@ -558,6 +607,29 @@ export async function publishCandidate(options) {
             };
         }
         catch (error) {
+            if (error instanceof ManagedCoreWalletRelockPendingError) {
+                const note = createManagedCoreWalletRelockRetryWaitingNote();
+                const lastError = error.message;
+                await options.appendEventFn(options.paths, createMiningEventRecord("publish-retry-pending", "Managed Bitcoin Core wallet relocked during mining publish and will be retried on the current tip.", {
+                    level: "warn",
+                    runId: options.runId,
+                    targetBlockHeight: refreshedCandidate.targetBlockHeight,
+                    referencedBlockHashDisplay: refreshedCandidate.referencedBlockHashDisplay,
+                    domainId: refreshedCandidate.domainId,
+                    domainName: refreshedCandidate.domainName,
+                    score: refreshedCandidate.canonicalBlend.toString(),
+                    reason: "managed-core-wallet-locked",
+                }));
+                return {
+                    state: readyReadContext.localState.state,
+                    txid: null,
+                    decision: "publish-retry-pending",
+                    note,
+                    lastError,
+                    retryable: true,
+                    candidate: refreshedCandidate,
+                };
+            }
             if (error instanceof Error && error.message === "wallet_mining_mempool_rejected_missing-inputs") {
                 const note = createRetryableMiningPublishWaitingNote();
                 const revertedState = error instanceof MiningPublishRejectedError

package/dist/wallet/mining/runner.d.ts

@@ -1,4 +1,3 @@
-import { spawn } from "node:child_process";
 import { assaySentences } from "@cogcoin/scoring";
 import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, stopManagedBitcoindService } from "../../bitcoind/service.js";
 import { createRpcClient } from "../../bitcoind/node.js";
@@ -13,7 +12,6 @@ import { type MiningRuntimeLoopState } from "./engine-state.js";
 import { saveStopSnapshot } from "./lifecycle.js";
 import type { CompetitivenessDecision, MiningCandidate, MiningCooperativeYield, MiningRpcClient } from "./engine-types.js";
 import { requestMiningGenerationPreemption } from "./coordination.js";
-import type { MiningRuntimeStatusV1 } from "./types.js";
 import { MiningFollowVisualizer } from "./visualizer.js";
 interface RunnerDependencies {
     openReadContext?: typeof openWalletReadContext;
@@ -23,8 +21,6 @@ interface RunnerDependencies {
     requestMiningPreemption?: typeof requestMiningGenerationPreemption;
     runMiningLoopImpl?: typeof runMiningLoop;
     saveStopSnapshotImpl?: typeof saveStopSnapshot;
-    spawnWorkerProcess?: typeof spawn;
-    waitForBackgroundHealthyImpl?: typeof waitForBackgroundHealthy;
     shutdownGraceMs?: number;
     sleepImpl?: typeof sleep;
 }
@@ -63,24 +59,6 @@ export interface RunForegroundMiningOptions extends RunnerDependencies {
     paths?: WalletRuntimePaths;
     visualizer?: MiningFollowVisualizer;
 }
-export interface StartBackgroundMiningOptions extends RunnerDependencies {
-    dataDir: string;
-    databasePath: string;
-    provider?: WalletSecretProvider;
-    prompter: WalletPrompter;
-    builtInSetupEnsured?: boolean;
-    paths?: WalletRuntimePaths;
-}
-export interface StopBackgroundMiningOptions extends RunnerDependencies {
-    dataDir: string;
-    databasePath: string;
-    provider?: WalletSecretProvider;
-    paths?: WalletRuntimePaths;
-}
-export interface MiningStartResult {
-    started: boolean;
-    snapshot: MiningRuntimeStatusV1 | null;
-}
 declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
 declare function generateCandidatesForDomains(options: Parameters<typeof generateCandidatesForDomainsModule>[0]): Promise<MiningCandidate[]>;
 declare function runCompetitivenessGate(options: Parameters<typeof runCompetitivenessGateModule>[0]): Promise<CompetitivenessDecision>;
@@ -119,17 +97,7 @@ declare function runMiningLoop(options: {
     cooperativeYieldImpl?: MiningCooperativeYield;
     cooperativeYieldEvery?: number;
 }): Promise<void>;
-declare function waitForBackgroundHealthy(paths: WalletRuntimePaths): Promise<MiningRuntimeStatusV1 | null>;
 export declare function runForegroundMining(options: RunForegroundMiningOptions): Promise<void>;
-export declare function startBackgroundMining(options: StartBackgroundMiningOptions): Promise<MiningStartResult>;
-export declare function stopBackgroundMining(options: StopBackgroundMiningOptions): Promise<MiningRuntimeStatusV1 | null>;
-export declare function runBackgroundMiningWorker(options: RunnerDependencies & {
-    dataDir: string;
-    databasePath: string;
-    runId: string;
-    provider?: WalletSecretProvider;
-    paths?: WalletRuntimePaths;
-}): Promise<void>;
 export declare function performMiningCycleForTesting(options: {
     dataDir: string;
     databasePath: string;