@cogcoin/client 1.2.3 → 1.2.4

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@1.2.3` is the reference Cogcoin client package for applications that want a local wallet, durable SQLite-backed state, and a managed Bitcoin Core integration around `@cogcoin/indexer`. It publishes the reusable client APIs, the SQLite adapter, the managed `bitcoind` integration, and the first-party `cogcoin` CLI in one package.
+`@cogcoin/client@1.2.4` is the reference Cogcoin client package for applications that want a local wallet, durable SQLite-backed state, and a managed Bitcoin Core integration around `@cogcoin/indexer`. It publishes the reusable client APIs, the SQLite adapter, the managed `bitcoind` integration, and the first-party `cogcoin` CLI in one package.
 
 Use Node 22 or newer.
 
@@ -126,6 +126,10 @@ The published package depends on:
 
 `@cogcoin/vectors@1.0.1` is kept as a repository development dependency for conformance tests and is not part of the published runtime dependency surface.
 
+## Upgrade Notes For `1.2.4`
+
+`@cogcoin/client@1.2.4` treats a live managed Bitcoin Core process returning startup `-28 Loading block index...` as a normal `starting` state. `cogcoin mine` waits instead of repeatedly restarting the process, and `cogcoin repair` prints progress during long checks. If repair restarts a stale managed bitcoind to add raw transaction ZMQ support and Core is still loading, repair exits with a clear note to wait and rerun `cogcoin status` or `cogcoin mine`.
+
 ## Upgrade Notes For `1.2.0`
 
 `@cogcoin/client@1.2.0` updates the runtime indexer to `@cogcoin/indexer@1.0.2`. Existing wallet state, mining configuration, Bitcoin Core data, and secrets remain compatible and are not reset.

package/dist/bitcoind/managed-bitcoind-service-lifecycle.js

@@ -7,6 +7,7 @@ import { stopIndexerDaemonServiceWithLockHeld } from "./indexer-daemon.js";
 import { readManagedBitcoindObservedStatus, listManagedBitcoindStatusCandidates } from "./managed-runtime/bitcoind-status.js";
 import { attachOrStartManagedBitcoindRuntime, probeManagedBitcoindRuntime } from "./managed-runtime/bitcoind-runtime.js";
 import { createRpcClient, validateNodeConfigForTesting } from "./node.js";
+import { isManagedRpcWarmupError } from "./retryable-rpc.js";
 import { resolveManagedServicePaths, UNINITIALIZED_WALLET_ROOT_ID } from "./service-paths.js";
 import { DEFAULT_MANAGED_BITCOIND_FOLLOW_POLL_INTERVAL_MS, } from "./types.js";
 import { buildManagedServiceArgsForTesting, LOCAL_HOST, resolveManagedBitcoindRuntimeConfig, SUPPORTED_BITCOIND_VERSION, verifyManagedBitcoindVersion, writeManagedBitcoindRuntimeConfigFile, writeManagedBitcoindRuntimeConfigFileFromStatus, writeBitcoinConfForTesting, } from "./managed-bitcoind-service-config.js";
@@ -192,6 +193,30 @@ export async function attachOrStartManagedBitcoindService(options) {
                         child.unref();
                     }
                     const rpc = createRpcClient(rpcConfig);
+                    const startedAtUnixMs = Date.now();
+                    const serviceInstanceId = randomBytes(16).toString("hex");
+                    const startingStatus = createBitcoindServiceStatus({
+                        binaryVersion,
+                        serviceInstanceId,
+                        state: "starting",
+                        processId: child.pid ?? null,
+                        walletRootId: startOptions.walletRootId,
+                        chain: startOptions.chain,
+                        dataDir: startOptions.dataDir,
+                        runtimeRoot: paths.walletRuntimeRoot,
+                        startHeight: startOptions.startHeight,
+                        rpc: rpcConfig,
+                        zmq: zmqConfig,
+                        p2pPort: runtimeConfig.p2pPort,
+                        getblockArchiveEndHeight: runtimeConfig.getblockArchiveEndHeight ?? null,
+                        getblockArchiveSha256: runtimeConfig.getblockArchiveSha256 ?? null,
+                        walletReplica: null,
+                        startedAtUnixMs,
+                        heartbeatAtUnixMs: startedAtUnixMs,
+                        lastError: "Managed bitcoind service is starting.",
+                    });
+                    await writeManagedBitcoindRuntimeConfigFile(paths.bitcoindRuntimeConfigPath, runtimeConfig);
+                    await writeManagedBitcoindStatus(paths, startingStatus);
                     try {
                         await waitForManagedBitcoindRpcReady(rpc, rpcConfig.cookieFile, startOptions.chain, startupTimeoutMs);
                         await validateNodeConfigForTesting(rpc, startOptions.chain, zmqConfig.endpoint, {
@@ -199,6 +224,19 @@ export async function attachOrStartManagedBitcoindService(options) {
                         });
                     }
                     catch (error) {
+                        const processAlive = child.pid !== undefined && await isManagedBitcoindProcessAlive(child.pid);
+                        if (startOptions.serviceLifetime !== "ephemeral"
+                            && processAlive
+                            && isManagedRpcWarmupError(error)) {
+                            const nowUnixMs = Date.now();
+                            await writeManagedBitcoindStatus(paths, {
+                                ...startingStatus,
+                                heartbeatAtUnixMs: nowUnixMs,
+                                updatedAtUnixMs: nowUnixMs,
+                                lastError: error instanceof Error ? error.message : String(error),
+                            });
+                            throw new Error("managed_bitcoind_service_starting");
+                        }
                         if (child.pid !== undefined) {
                             try {
                                 process.kill(child.pid, "SIGTERM");
@@ -215,7 +253,7 @@ export async function attachOrStartManagedBitcoindService(options) {
                         runtimeConfig,
                         status: createBitcoindServiceStatus({
                             binaryVersion,
-                            serviceInstanceId: randomBytes(16).toString("hex"),
+                            serviceInstanceId,
                             state: "ready",
                             processId: child.pid ?? null,
                             walletRootId: startOptions.walletRootId,
@@ -229,7 +267,7 @@ export async function attachOrStartManagedBitcoindService(options) {
                             getblockArchiveEndHeight: runtimeConfig.getblockArchiveEndHeight ?? null,
                             getblockArchiveSha256: runtimeConfig.getblockArchiveSha256 ?? null,
                             walletReplica,
-                            startedAtUnixMs: nowUnixMs,
+                            startedAtUnixMs,
                             heartbeatAtUnixMs: nowUnixMs,
                             lastError: walletReplica.message ?? null,
                         }),
@@ -241,6 +279,9 @@ export async function attachOrStartManagedBitcoindService(options) {
                     ({ runtimeConfig, status } = await startManagedProcess(runtimeOptions));
                 }
                 catch (error) {
+                    if (isManagedRpcWarmupError(error)) {
+                        throw error;
+                    }
                     if (runtimeOptions.getblockArchivePath === undefined || runtimeOptions.getblockArchivePath === null) {
                         throw error;
                     }

package/dist/bitcoind/managed-bitcoind-service-status.js

@@ -8,6 +8,7 @@ import { MANAGED_BITCOIND_SERVICE_API_VERSION, } from "./types.js";
 import { createMissingManagedWalletReplicaStatus, loadManagedWalletReplicaIfPresent, } from "./managed-bitcoind-service-replica.js";
 import { DEFAULT_MANAGED_BITCOIND_STARTUP_TIMEOUT_MS, isManagedBitcoindProcessAlive, sleep, } from "./managed-bitcoind-service-process.js";
 import { waitForManagedBitcoindCookie, } from "./managed-bitcoind-service-config.js";
+import { isManagedRpcWarmupError } from "./retryable-rpc.js";
 export async function waitForManagedBitcoindRpcReady(rpc, cookieFile, expectedChain, timeoutMs) {
     await waitForManagedBitcoindCookie(cookieFile, timeoutMs, sleep);
     const deadline = Date.now() + timeoutMs;
@@ -117,12 +118,14 @@ export async function refreshManagedBitcoindStatus(status, paths, options) {
         return nextStatus;
     }
     catch (error) {
+        const processAlive = await isManagedBitcoindProcessAlive(status.processId);
+        const stillStarting = processAlive && isManagedRpcWarmupError(error);
         const nextStatus = {
             ...status,
             walletRootId: targetWalletRootId,
             runtimeRoot: paths.walletRuntimeRoot,
-            state: "failed",
-            processId: await isManagedBitcoindProcessAlive(status.processId) ? status.processId : null,
+            state: stillStarting ? "starting" : "failed",
+            processId: processAlive ? status.processId : null,
             heartbeatAtUnixMs: nowUnixMs,
             updatedAtUnixMs: nowUnixMs,
             lastError: error instanceof Error ? error.message : String(error),

package/dist/bitcoind/managed-runtime/bitcoind-policy.js

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import { isManagedRpcWarmupError } from "../retryable-rpc.js";
 import { resolveManagedServicePaths } from "../service-paths.js";
 import { MANAGED_BITCOIND_SERVICE_API_VERSION } from "../types.js";
 function isRuntimeMismatchError(error) {
@@ -64,6 +65,13 @@ export function mapManagedBitcoindRuntimeProbeFailure(error, status) {
             error: "managed_bitcoind_runtime_mismatch",
         };
     }
+    if (isManagedRpcWarmupError(error)) {
+        return {
+            compatibility: "starting",
+            status,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
     if (isUnreachableManagedBitcoindError(error)) {
         return {
             compatibility: "unreachable",
@@ -84,6 +92,12 @@ export function resolveManagedBitcoindProbeDecision(probe) {
             error: null,
         };
     }
+    if (probe.compatibility === "starting") {
+        return {
+            action: "wait",
+            error: probe.error ?? "managed_bitcoind_service_starting",
+        };
+    }
     if (probe.compatibility === "unreachable") {
         return {
             action: "start",
@@ -121,6 +135,12 @@ function mapManagedBitcoindStartupError(message) {
                 status: null,
                 message: "The live managed bitcoind service runtime does not match this wallet's expected data directory or chain.",
             };
+        case "managed_bitcoind_service_starting":
+            return {
+                health: "starting",
+                status: null,
+                message: "Managed bitcoind service is still starting.",
+            };
         case "managed_bitcoind_protocol_error":
             return {
                 health: "unavailable",
@@ -128,6 +148,13 @@ function mapManagedBitcoindStartupError(message) {
                 message: "The managed bitcoind runtime artifacts are invalid or incomplete.",
             };
         default:
+            if (/^bitcoind_rpc_[^_]+_-28(?:_|$)/.test(message)) {
+                return {
+                    health: "starting",
+                    status: null,
+                    message,
+                };
+            }
             return {
                 health: "unavailable",
                 status: null,

package/dist/bitcoind/managed-runtime/bitcoind-runtime.js

@@ -40,6 +40,9 @@ export async function attachOrStartManagedBitcoindRuntime(options, dependencies)
         }
         throw new Error("managed_bitcoind_protocol_error");
     }
+    if (existingDecision.action === "wait") {
+        return waitForManagedBitcoindRuntime(options, dependencies);
+    }
     if (existingDecision.action === "reject") {
         throw new Error(existingDecision.error ?? "managed_bitcoind_protocol_error");
     }
@@ -56,6 +59,9 @@ export async function attachOrStartManagedBitcoindRuntime(options, dependencies)
                 }
                 throw new Error("managed_bitcoind_protocol_error");
             }
+            if (liveDecision.action === "wait") {
+                return waitForManagedBitcoindRuntime(options, dependencies);
+            }
             if (liveDecision.action === "reject") {
                 throw new Error(liveDecision.error ?? "managed_bitcoind_protocol_error");
             }

package/dist/bitcoind/managed-runtime/types.d.ts

@@ -2,7 +2,7 @@ import type { ClientTip } from "../../types.js";
 import type { ManagedServicePaths } from "../service-paths.js";
 import type { ManagedBitcoindObservedStatus, ManagedIndexerDaemonObservedStatus, ManagedIndexerTruthSource } from "../types.js";
 import type { WalletBitcoindStatus, WalletIndexerStatus, WalletNodeStatus, WalletServiceHealth, WalletSnapshotView } from "../../wallet/read/types.js";
-export type ManagedBitcoindServiceCompatibility = "compatible" | "service-version-mismatch" | "wallet-root-mismatch" | "runtime-mismatch" | "rawtx-zmq-missing" | "unreachable" | "protocol-error";
+export type ManagedBitcoindServiceCompatibility = "compatible" | "starting" | "service-version-mismatch" | "wallet-root-mismatch" | "runtime-mismatch" | "rawtx-zmq-missing" | "unreachable" | "protocol-error";
 export interface ManagedBitcoindServiceProbeResult {
     compatibility: ManagedBitcoindServiceCompatibility;
     status: ManagedBitcoindObservedStatus | null;
@@ -20,7 +20,7 @@ export interface ManagedIndexerDaemonProbeResult<TClient> {
     error: string | null;
 }
 export interface ManagedBitcoindProbeDecision {
-    action: "attach" | "start" | "reject";
+    action: "attach" | "wait" | "start" | "reject";
     error: string | null;
 }
 export interface IndexerDaemonProbeDecision {

package/dist/bitcoind/retryable-rpc.d.ts

@@ -8,4 +8,5 @@ export declare function createManagedRpcRetryState(): ManagedRpcRetryState;
 export declare function resetManagedRpcRetryState(state: ManagedRpcRetryState): void;
 export declare function consumeManagedRpcRetryDelayMs(state: ManagedRpcRetryState): number;
 export declare function isRetryableManagedRpcError(error: unknown): boolean;
+export declare function isManagedRpcWarmupError(error: unknown): boolean;
 export declare function describeManagedRpcRetryError(error: unknown): string;

package/dist/bitcoind/retryable-rpc.js

@@ -15,15 +15,32 @@ export function consumeManagedRpcRetryDelayMs(state) {
     return delayMs;
 }
 export function isRetryableManagedRpcError(error) {
+    if (isManagedRpcWarmupError(error)) {
+        return true;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.startsWith("The managed Bitcoin RPC request to ")) {
+        return message.includes(" failed");
+    }
+    return false;
+}
+export function isManagedRpcWarmupError(error) {
     const message = error instanceof Error ? error.message : String(error);
-    if (message === "bitcoind_rpc_timeout") {
+    if (message === "managed_bitcoind_service_starting"
+        || message === "bitcoind_rpc_timeout"
+        || message === "bitcoind_cookie_timeout") {
         return true;
     }
     if (/^bitcoind_rpc_[^_]+_-28(?:_|$)/.test(message)) {
         return true;
     }
     if (message.startsWith("The managed Bitcoin RPC request to ")) {
-        return message.includes(" failed");
+        return message.includes(" failed")
+            && (message.includes("ECONNREFUSED")
+                || message.includes("ECONNRESET")
+                || message.includes("socket hang up")
+                || message.includes("timeout")
+                || message.includes("aborted"));
     }
     return message.startsWith("The managed Bitcoin RPC cookie file is unavailable at ")
         || message.startsWith("The managed Bitcoin RPC cookie file could not be read at ");

package/dist/cli/commands/wallet-admin.js

@@ -38,7 +38,10 @@ function getResetNextSteps(result) {
         ? ["Run `cogcoin init` to create or restore a wallet."]
         : ["Run `cogcoin sync` to bootstrap assumeutxo and the managed Bitcoin/indexer state."];
 }
-function getRepairNextSteps() {
+function getRepairNextSteps(result) {
+    if (result.bitcoindPostRepairHealth === "starting") {
+        return ["Wait for Bitcoin Core to finish loading, then run `cogcoin status` or rerun `cogcoin mine`."];
+    }
     return ["Run `cogcoin status` to review the repaired local state."];
 }
 function formatResetBitcoinDataDirStatus(result) {
@@ -116,7 +119,7 @@ function buildRepairWarningEntries(result) {
     return entries;
 }
 function formatRepairResultText(result) {
-    const nextStep = getRepairNextSteps()[0] ?? null;
+    const nextStep = getRepairNextSteps(result)[0] ?? null;
     const warningEntries = buildRepairWarningEntries(result);
     const sections = [
         formatAdminSection("Wallet", [
@@ -244,6 +247,9 @@ export async function runWalletAdminCommand(parsed, context) {
                     provider: repairProvider,
                     assumeYes: parsed.assumeYes,
                     paths: runtimePaths,
+                    progress: async (event) => {
+                        writeLine(context.stdout, event.message);
+                    },
                 });
                 writeLine(context.stdout, formatRepairResultText(result));
                 return 0;

package/dist/cli/output/rules/services.js

@@ -21,6 +21,13 @@ export const serviceErrorRules = [
                 next: "Rerun the command in an interactive terminal.",
             };
         }
+        if (errorCode === "managed_bitcoind_service_starting" || /^bitcoind_rpc_[^_]+_-28(?:_|$)/.test(errorCode)) {
+            return {
+                what: "Bitcoin Core is still loading.",
+                why: "The managed Bitcoin RPC service is alive, but Bitcoin Core is still warming up and returned its normal startup -28 response.",
+                next: "Wait for the node to finish loading, then rerun the command. Use `cogcoin status` to check readiness.",
+            };
+        }
         if (errorCode.includes("tip_mismatch") || errorCode.includes("stale") || errorCode.includes("catching_up") || errorCode.includes("starting")) {
             return {
                 what: "Trusted service state is not ready.",

package/dist/wallet/lifecycle/context.js

@@ -47,6 +47,7 @@ export function resolveWalletRepairContext(options) {
         attachIndexerDaemon: options.attachIndexerDaemon ?? attachOrStartIndexerDaemon,
         probeIndexerDaemon: options.probeIndexerDaemon ?? probeIndexerDaemon,
         requestMiningPreemption: options.requestMiningPreemption,
+        progress: options.progress ?? (() => undefined),
     };
 }
 export async function acquireWalletControlLock(paths, purpose) {

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

@@ -4,7 +4,7 @@ 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 { clearManagedBitcoindArtifactsForDataDir, isManagedBitcoindRpcUnavailableError, mapBitcoindCompatibilityToRepairIssue, mapBitcoindRepairHealth, waitForProcessExit, } from "./repair-runtime.js";
+import { clearManagedBitcoindArtifactsForDataDir, isManagedBitcoindRpcUnavailableError, isManagedBitcoindStartupWarmupError, mapBitcoindCompatibilityToRepairIssue, mapBitcoindRepairHealth, reportRepairProgress, waitForProcessExit, } from "./repair-runtime.js";
 export async function repairManagedBitcoindStage(options) {
     let state = options.state;
     let repairStateNeedsPersist = options.repairStateNeedsPersist;
@@ -24,6 +24,7 @@ export async function repairManagedBitcoindStage(options) {
         dataDir: options.context.dataDir,
     });
     try {
+        await reportRepairProgress(options.context, "bitcoind-check", "Checking managed bitcoind...");
         initialBitcoindProbe = await options.context.probeBitcoindService({
             dataDir: options.context.dataDir,
             chain: "main",
@@ -31,6 +32,18 @@ export async function repairManagedBitcoindStage(options) {
             walletRootId: state.walletRootId,
         });
         bitcoindCompatibilityIssue = mapBitcoindCompatibilityToRepairIssue(initialBitcoindProbe.compatibility);
+        if (initialBitcoindProbe.compatibility === "starting") {
+            await reportRepairProgress(options.context, "bitcoind-starting", "Bitcoin Core is loading the block index; leaving managed bitcoind running.");
+            return {
+                state,
+                repairStateNeedsPersist,
+                recreatedManagedCoreWallet,
+                bitcoindServiceAction,
+                bitcoindCompatibilityIssue,
+                managedCoreReplicaAction,
+                bitcoindPostRepairHealth: "starting",
+            };
+        }
         if (initialBitcoindProbe.compatibility === "service-version-mismatch"
             || initialBitcoindProbe.compatibility === "wallet-root-mismatch"
             || initialBitcoindProbe.compatibility === "runtime-mismatch"
@@ -40,10 +53,14 @@ export async function repairManagedBitcoindStage(options) {
                 if (initialBitcoindProbe.compatibility !== "rawtx-zmq-missing") {
                     throw new Error("managed_bitcoind_process_id_unavailable");
                 }
+                await reportRepairProgress(options.context, "bitcoind-clear-stale-rawtx", "Clearing stale managed bitcoind runtime missing rawtx ZMQ...");
                 await clearManagedBitcoindArtifactsForDataDir(options.servicePaths, options.context.dataDir);
                 bitcoindServiceAction = "restarted-missing-rawtx-zmq";
             }
             else {
+                await reportRepairProgress(options.context, "bitcoind-stop-incompatible", initialBitcoindProbe.compatibility === "rawtx-zmq-missing"
+                    ? "Stopping stale managed bitcoind missing rawtx ZMQ..."
+                    : "Stopping incompatible managed bitcoind service...");
                 try {
                     process.kill(processId, "SIGTERM");
                 }
@@ -53,6 +70,7 @@ export async function repairManagedBitcoindStage(options) {
                     }
                 }
                 await waitForProcessExit(processId, 15_000, "managed_bitcoind_stop_timeout");
+                await reportRepairProgress(options.context, "bitcoind-clear-artifacts", "Clearing managed bitcoind runtime artifacts...");
                 await clearManagedBitcoindArtifactsForDataDir(options.servicePaths, options.context.dataDir);
                 bitcoindServiceAction = initialBitcoindProbe.compatibility === "rawtx-zmq-missing"
                     ? "restarted-missing-rawtx-zmq"
@@ -68,6 +86,7 @@ export async function repairManagedBitcoindStage(options) {
                 options.servicePaths.bitcoindWalletStatusPath,
             ].map(pathExists));
             if (hasStaleArtifacts.some(Boolean)) {
+                await reportRepairProgress(options.context, "bitcoind-clear-stale", "Clearing stale managed bitcoind artifacts...");
                 await clearManagedBitcoindArtifactsForDataDir(options.servicePaths, options.context.dataDir);
                 bitcoindServiceAction = "cleared-stale-artifacts";
             }
@@ -83,12 +102,17 @@ export async function repairManagedBitcoindStage(options) {
         let bitcoindHandle = null;
         let handleClosed = false;
         try {
+            await reportRepairProgress(options.context, attachAttempt === 0 ? "bitcoind-start" : "bitcoind-retry-start", bitcoindServiceAction === "none"
+                ? "Attaching to managed bitcoind..."
+                : "Starting managed bitcoind with current ZMQ config...");
+            await reportRepairProgress(options.context, "bitcoind-wait-rpc", "Waiting for Bitcoin Core RPC readiness...");
             bitcoindHandle = await options.context.attachService({
                 dataDir: options.context.dataDir,
                 chain: "main",
                 startHeight: 0,
                 walletRootId: state.walletRootId,
             });
+            await reportRepairProgress(options.context, "bitcoind-normalize-wallet", "Checking managed Bitcoin wallet state...");
             const rpc = options.context.rpcFactory(bitcoindHandle.rpc);
             const normalizedDescriptorState = await normalizeWalletDescriptorState(state, rpc);
             if (normalizedDescriptorState.changed) {
@@ -116,6 +140,7 @@ export async function repairManagedBitcoindStage(options) {
                 rpcFactory: options.context.rpcFactory,
             });
             if (replica.proofStatus !== "ready") {
+                await reportRepairProgress(options.context, "bitcoind-recreate-replica", "Recreating managed Core wallet replica...");
                 state = await recreateManagedCoreWalletReplica(state, options.context.provider, options.context.paths, options.context.dataDir, options.context.nowUnixMs, {
                     attachService: options.context.attachService,
                     rpcFactory: options.context.rpcFactory,
@@ -129,6 +154,7 @@ export async function repairManagedBitcoindStage(options) {
                     rpcFactory: options.context.rpcFactory,
                 });
             }
+            await reportRepairProgress(options.context, "bitcoind-final-health", "Checking managed bitcoind post-repair health...");
             const finalBitcoindStatus = await bitcoindHandle.refreshServiceStatus?.() ?? null;
             const chainInfo = await rpc.getBlockchainInfo();
             bitcoindPostRepairHealth = mapBitcoindRepairHealth({
@@ -150,6 +176,18 @@ export async function repairManagedBitcoindStage(options) {
             };
         }
         catch (error) {
+            if (isManagedBitcoindStartupWarmupError(error)) {
+                await reportRepairProgress(options.context, "bitcoind-starting", "Bitcoin Core is loading the block index; leaving managed bitcoind running.");
+                return {
+                    state,
+                    repairStateNeedsPersist,
+                    recreatedManagedCoreWallet,
+                    bitcoindServiceAction,
+                    bitcoindCompatibilityIssue,
+                    managedCoreReplicaAction,
+                    bitcoindPostRepairHealth: "starting",
+                };
+            }
             if (bitcoindHandle !== null) {
                 await bitcoindHandle.stop?.().catch(() => undefined);
                 handleClosed = true;
@@ -161,6 +199,7 @@ export async function repairManagedBitcoindStage(options) {
                     dataDir: options.context.dataDir,
                 });
                 try {
+                    await reportRepairProgress(options.context, "bitcoind-clear-stale-rpc", "Clearing stale managed bitcoind RPC artifacts...");
                     await clearManagedBitcoindArtifactsForDataDir(options.servicePaths, options.context.dataDir);
                 }
                 finally {

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

@@ -2,7 +2,7 @@ import { attachOrStartIndexerDaemon, probeIndexerDaemon } from "../../bitcoind/i
 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";
+import type { WalletRepairContext, WalletRepairResult } from "./types.js";
 export declare function ensureIndexerDatabaseHealthy(options: {
     databasePath: string;
     dataDir: string;
@@ -18,6 +18,8 @@ export declare function mapBitcoindRepairHealth(options: {
         proofStatus?: "missing" | "mismatch" | "ready" | "not-proven";
     } | null;
 }): WalletRepairResult["bitcoindPostRepairHealth"];
+export declare function reportRepairProgress(context: Pick<WalletRepairContext, "progress">, code: string, message: string): Promise<void>;
+export declare function isManagedBitcoindStartupWarmupError(error: unknown): boolean;
 export declare function verifyIndexerPostRepairHealth(options: {
     daemon: Awaited<ReturnType<typeof attachOrStartIndexerDaemon>>;
     probeIndexerDaemon: typeof probeIndexerDaemon;

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

@@ -93,6 +93,18 @@ export function mapBitcoindRepairHealth(options) {
     }
     return "ready";
 }
+export async function reportRepairProgress(context, code, message) {
+    await context.progress({ code, message });
+}
+export function isManagedBitcoindStartupWarmupError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message === "managed_bitcoind_service_starting"
+        || message === "bitcoind_rpc_timeout"
+        || message === "bitcoind_cookie_timeout"
+        || /^bitcoind_rpc_[^_]+_-28(?:_|$)/.test(message)
+        || message.startsWith("The managed Bitcoin RPC cookie file is unavailable at ")
+        || message.startsWith("The managed Bitcoin RPC cookie file could not be read at ");
+}
 function mapLeaseStateToRepairHealth(state) {
     switch (state) {
         case "synced":

package/dist/wallet/lifecycle/repair.js

@@ -6,7 +6,7 @@ import { acquireWalletControlLock, resolveWalletRepairContext, } from "./context
 import { repairManagedBitcoindStage } from "./repair-bitcoind.js";
 import { repairManagedIndexerStage } from "./repair-indexer.js";
 import { applyRepairStoppedMiningState, cleanupMiningForRepair, persistRepairState, resumeBackgroundMiningAfterRepair, } from "./repair-mining.js";
-import { clearOrphanedRepairLocks, ensureIndexerDatabaseHealthy, } from "./repair-runtime.js";
+import { clearOrphanedRepairLocks, ensureIndexerDatabaseHealthy, reportRepairProgress, } from "./repair-runtime.js";
 export async function repairWallet(options) {
     const context = resolveWalletRepairContext(options);
     await clearOrphanedRepairLocks([
@@ -17,6 +17,7 @@ export async function repairWallet(options) {
     try {
         let loaded;
         try {
+            await reportRepairProgress(context, "wallet-check", "Checking wallet state...");
             loaded = await loadWalletState({
                 primaryPath: context.paths.walletStatePath,
                 backupPath: context.paths.walletStateBackupPath,
@@ -31,10 +32,12 @@ export async function repairWallet(options) {
         let repairedState = loaded.state;
         let repairStateNeedsPersist = false;
         const servicePaths = resolveManagedServicePaths(context.dataDir, repairedState.walletRootId);
+        await reportRepairProgress(context, "lock-cleanup", "Checking repair locks...");
         await clearOrphanedRepairLocks([
             servicePaths.bitcoindLockPath,
             servicePaths.indexerDaemonLockPath,
         ]);
+        await reportRepairProgress(context, "mining-cleanup", "Checking mining runtime...");
         const preRepairMiningRuntime = await loadMiningRuntimeStatus(context.paths.miningStatusPath).catch(() => null);
         const miningCleanup = await cleanupMiningForRepair({
             paths: context.paths,
@@ -48,6 +51,7 @@ export async function repairWallet(options) {
             repairStateNeedsPersist = true;
         }
         if (!context.assumeYes) {
+            await reportRepairProgress(context, "indexer-database-check", "Checking local indexer database...");
             await ensureIndexerDatabaseHealthy({
                 databasePath: context.databasePath,
                 dataDir: context.dataDir,
@@ -64,7 +68,12 @@ export async function repairWallet(options) {
         });
         repairedState = bitcoindStage.state;
         repairStateNeedsPersist = bitcoindStage.repairStateNeedsPersist;
+        const repairNotes = [];
+        if (bitcoindStage.bitcoindPostRepairHealth === "starting") {
+            repairNotes.push("Managed bitcoind was restarted and is still loading the block index; rerun mining after it reaches ready.");
+        }
         if (recoveredFromBackup) {
+            await reportRepairProgress(context, "wallet-state-persist", "Persisting repaired wallet state...");
             repairedState = await persistRepairState({
                 state: repairedState,
                 provider: context.provider,
@@ -75,6 +84,7 @@ export async function repairWallet(options) {
             repairStateNeedsPersist = false;
         }
         else if (repairStateNeedsPersist) {
+            await reportRepairProgress(context, "wallet-state-persist", "Persisting repaired wallet state...");
             repairedState = await persistRepairState({
                 state: repairedState,
                 provider: context.provider,
@@ -83,11 +93,25 @@ export async function repairWallet(options) {
             });
             repairStateNeedsPersist = false;
         }
-        const indexerStage = await repairManagedIndexerStage({
-            context,
-            servicePaths,
-            state: repairedState,
-        });
+        const indexerStage = bitcoindStage.bitcoindPostRepairHealth === "starting"
+            ? {
+                resetIndexerDatabase: false,
+                indexerDaemonAction: "none",
+                indexerCompatibilityIssue: "none",
+                indexerPostRepairHealth: "starting",
+            }
+            : await (async () => {
+                await reportRepairProgress(context, "indexer-check", "Checking indexer...");
+                return repairManagedIndexerStage({
+                    context,
+                    servicePaths,
+                    state: repairedState,
+                });
+            })();
+        if (indexerStage.resetIndexerDatabase) {
+            repairNotes.push("Indexer artifacts were reset and may still be catching up.");
+        }
+        await reportRepairProgress(context, "mining-resume", "Checking whether mining should resume...");
         const miningResume = await resumeBackgroundMiningAfterRepair({
             miningPreRepairRunMode,
             provider: context.provider,
@@ -113,9 +137,7 @@ export async function repairWallet(options) {
             miningResumeAction: miningResume.miningResumeAction,
             miningPostRepairRunMode: miningResume.miningPostRepairRunMode,
             miningResumeError: miningResume.miningResumeError,
-            note: indexerStage.resetIndexerDatabase
-                ? "Indexer artifacts were reset and may still be catching up."
-                : null,
+            note: repairNotes.length > 0 ? repairNotes.join(" ") : null,
         };
     }
     finally {

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

@@ -49,6 +49,11 @@ export interface WalletRepairResult {
     miningResumeError: string | null;
     note: string | null;
 }
+export interface WalletRepairProgressEvent {
+    code: string;
+    message: string;
+}
+export type WalletRepairProgressReporter = (event: WalletRepairProgressEvent) => void | Promise<void>;
 export interface WalletLifecycleRpcClient {
     getDescriptorInfo(descriptor: string): Promise<{
         descriptor: string;
@@ -126,6 +131,7 @@ export interface WalletRepairDependencies extends WalletManagedCoreDependencies
     attachIndexerDaemon?: typeof attachOrStartIndexerDaemon;
     probeIndexerDaemon?: typeof probeIndexerDaemon;
     requestMiningPreemption?: typeof requestMiningGenerationPreemption;
+    progress?: WalletRepairProgressReporter;
 }
 export interface WalletRepairContext extends WalletManagedCoreContext {
     dataDir: string;
@@ -135,6 +141,7 @@ export interface WalletRepairContext extends WalletManagedCoreContext {
     attachIndexerDaemon: NonNullable<WalletRepairDependencies["attachIndexerDaemon"]>;
     probeIndexerDaemon: NonNullable<WalletRepairDependencies["probeIndexerDaemon"]>;
     requestMiningPreemption?: WalletRepairDependencies["requestMiningPreemption"];
+    progress: WalletRepairProgressReporter;
 }
 export interface WalletBitcoindRepairStageResult {
     state: WalletStateV1;

package/dist/wallet/mining/lifecycle.js

@@ -159,6 +159,10 @@ export async function handleRecoverableMiningBitcoindFailure(options) {
             rememberMiningBitcoindRecoveryIdentity(options.loopState, probe.status);
             options.loopState.bitcoinRecoveryFirstUnreachableAtUnixMs = null;
         }
+        else if (probe.compatibility === "starting") {
+            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);

package/dist/wallet/read/managed-bitcoind.js

@@ -54,6 +54,15 @@ async function attachNodeStatus(options, dependencies) {
             startupTimeoutMs: options.startupTimeoutMs,
         });
         const decision = resolveManagedBitcoindProbeDecision(probe);
+        if (decision.action === "wait") {
+            return {
+                handle: null,
+                rpc: null,
+                status: null,
+                observedStatus: probe.status,
+                error: null,
+            };
+        }
         if (decision.action === "reject") {
             return {
                 handle: null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cogcoin/client",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "Store-backed Cogcoin client with wallet flows, SQLite persistence, and managed Bitcoin Core integration.",
   "license": "MIT",
   "type": "module",