@cogcoin/client 1.2.3 → 1.2.5

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.5` 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,14 @@ 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.5`
+
+`@cogcoin/client@1.2.5` keeps managed Bitcoin runtime settings in `bitcoin.conf` instead of duplicating RPC, P2P, wallet, and ZMQ settings on the `bitcoind` command line. This prevents duplicate `pubhashblock` and `pubrawtx` ZMQ registrations. Managed startup, repair, `bitcoin status`, and `status --live` also refresh runtime status after successful RPC/ZMQ checks so a stale `starting` status does not remain after Core is ready.
+
+## 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.
@@ -169,10 +177,12 @@ The installed `cogcoin` command covers the first-party local wallet and node wor
 - COG and reputation commands such as `send`, `cog lock`, `claim`, `reclaim`, `rep give`, and `rep revoke`
 - mining commands such as `mine`, `mine status`, `mine log`, `mine setup`, `mine prompt`, and `mine prompt list`
 
+`cogcoin status` is passive by default: it reads local SQLite/runtime status files without prompting for the client password, starting services, or making Bitcoin RPC calls. Use `cogcoin status --live` when you want the full RPC-backed wallet overview and balance report.
+
 Use `cogcoin mine prompt <domain>` to set or clear a per-domain mining prompt override for one anchored root domain, and `cogcoin mine prompt list` to inspect the current per-domain prompt state alongside the global fallback prompt.
 Interactive text invocations periodically check the npm registry for newer `@cogcoin/client` releases and print `npm install -g @cogcoin/client` when a newer version is available.
 Set `COGCOIN_DISABLE_UPDATE_CHECK=1` to disable the CLI update notice entirely.
-Ordinary `sync`, `follow`, and wallet-aware read/status flows detach from the managed Bitcoin and indexer services on exit instead of stopping them.
+Ordinary `sync`, `follow`, and wallet-aware live read flows detach from the managed Bitcoin and indexer services on exit instead of stopping them.
 Use the explicit `bitcoin ...` and `indexer ...` commands when you want direct service inspection or start/stop control.
 For provider-backed local wallets, normal reads, mutations, and mining setup flows load local wallet state on demand whenever the local secret provider is available.
 When no wallet exists yet, `cogcoin init` interactively lets you either create a new wallet or restore an existing one from a 24-word English BIP39 mnemonic, then continues into sync.

package/dist/bitcoind/managed-bitcoind-service-config.d.ts

@@ -26,5 +26,9 @@ export declare function writeManagedBitcoindRuntimeConfigFile(filePath: string,
 export declare function writeManagedBitcoindRuntimeConfigFileFromStatus(filePath: string, status: Pick<ManagedBitcoindServiceStatus, "chain" | "rpc" | "zmq" | "p2pPort" | "getblockArchiveEndHeight" | "getblockArchiveSha256">, dependencies?: ManagedBitcoindRuntimeConfigFileDeps): Promise<void>;
 export declare function writeBitcoinConfForTesting(filePath: string, options: ManagedBitcoindServiceOptions, runtimeConfig: ManagedBitcoindRuntimeConfig): Promise<void>;
 export declare function buildManagedServiceArgsForTesting(options: ManagedBitcoindServiceOptions, runtimeConfig: ManagedBitcoindRuntimeConfig): string[];
-export declare function waitForManagedBitcoindCookie(cookieFile: string, timeoutMs: number, sleepImpl: (ms: number) => Promise<void>): Promise<void>;
+export declare function waitForManagedBitcoindCookie(cookieFile: string, timeoutMs: number, sleepImpl: (ms: number) => Promise<void>, options?: {
+    now?: () => number;
+    progressIntervalMs?: number;
+    onProgress?: (elapsedMs: number) => void | Promise<void>;
+}): Promise<void>;
 export type { BitcoindRpcConfig, BitcoindZmqConfig, };

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

@@ -147,12 +147,14 @@ export async function writeBitcoinConfForTesting(filePath, options, runtimeConfi
     const walletDir = join(options.dataDir ?? "", "wallets");
     await mkdir(dirname(filePath), { recursive: true });
     await mkdir(walletDir, { recursive: true });
-    const lines = [
+    const commonLines = [
         "server=1",
         "prune=0",
+        `dbcache=${runtimeConfig.dbcacheMiB}`,
+    ];
+    const networkLines = [
         "dnsseed=1",
         "listen=0",
-        `dbcache=${runtimeConfig.dbcacheMiB}`,
         `rpcbind=${LOCAL_HOST}`,
         `rpcallowip=${LOCAL_HOST}`,
         `rpcport=${runtimeConfig.rpc.port}`,
@@ -161,25 +163,23 @@ export async function writeBitcoinConfForTesting(filePath, options, runtimeConfi
         `zmqpubrawtx=tcp://${LOCAL_HOST}:${runtimeConfig.zmqPort}`,
         `walletdir=${walletDir}`,
     ];
+    const lines = options.chain === "regtest"
+        ? [
+            ...commonLines,
+            "",
+            "[regtest]",
+            ...networkLines,
+        ]
+        : [
+            ...commonLines,
+            ...networkLines,
+        ];
     await writeFileAtomic(filePath, `${lines.join("\n")}\n`, { mode: 0o600 });
 }
 export function buildManagedServiceArgsForTesting(options, runtimeConfig) {
-    const walletDir = join(options.dataDir ?? "", "wallets");
     const args = [
         "-nosettings=1",
         `-datadir=${options.dataDir}`,
-        `-rpcbind=${LOCAL_HOST}`,
-        `-rpcallowip=${LOCAL_HOST}`,
-        `-rpcport=${runtimeConfig.rpc.port}`,
-        `-port=${runtimeConfig.p2pPort}`,
-        `-zmqpubhashblock=tcp://${LOCAL_HOST}:${runtimeConfig.zmqPort}`,
-        `-zmqpubrawtx=tcp://${LOCAL_HOST}:${runtimeConfig.zmqPort}`,
-        `-walletdir=${walletDir}`,
-        "-server=1",
-        "-prune=0",
-        "-dnsseed=1",
-        "-listen=0",
-        `-dbcache=${runtimeConfig.dbcacheMiB}`,
     ];
     if (options.chain === "regtest") {
         args.push("-chain=regtest");
@@ -189,14 +189,23 @@ export function buildManagedServiceArgsForTesting(options, runtimeConfig) {
     }
     return args;
 }
-export async function waitForManagedBitcoindCookie(cookieFile, timeoutMs, sleepImpl) {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
+export async function waitForManagedBitcoindCookie(cookieFile, timeoutMs, sleepImpl, options = {}) {
+    const now = options.now ?? Date.now;
+    const progressIntervalMs = options.progressIntervalMs ?? 30_000;
+    const startedAt = now();
+    const deadline = startedAt + timeoutMs;
+    let lastProgressAt = startedAt;
+    while (now() < deadline) {
         try {
             await access(cookieFile, constants.R_OK);
             return;
         }
         catch {
+            const currentTime = now();
+            if (currentTime - lastProgressAt >= progressIntervalMs) {
+                await options.onProgress?.(Math.max(0, currentTime - startedAt));
+                lastProgressAt = currentTime;
+            }
             await sleepImpl(250);
         }
     }

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,13 +193,52 @@ 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 waitForManagedBitcoindRpcReady(rpc, rpcConfig.cookieFile, startOptions.chain, startupTimeoutMs, {
+                            progress: startOptions.rpcReadyProgress,
+                        });
                         await validateNodeConfigForTesting(rpc, startOptions.chain, zmqConfig.endpoint, {
                             requireRawTxZmq: true,
                         });
                     }
                     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 +255,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 +269,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 +281,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.d.ts

@@ -1,10 +1,16 @@
 import { createRpcClient } from "./node.js";
 import { resolveManagedServicePaths } from "./service-paths.js";
 import { type ManagedBitcoindObservedStatus, type ManagedBitcoindNodeHandle, type ManagedBitcoindServiceStatus, type ManagedCoreWalletReplicaStatus } from "./types.js";
-import type { ManagedBitcoindServiceOwnership, ManagedBitcoindServiceOptions, ManagedBitcoindServiceStopResult } from "./managed-bitcoind-service-types.js";
+import type { ManagedBitcoindRpcReadyProgressReporter, ManagedBitcoindServiceOwnership, ManagedBitcoindServiceOptions, ManagedBitcoindServiceStopResult } from "./managed-bitcoind-service-types.js";
 import { type BitcoindRpcConfig, type BitcoindZmqConfig } from "./managed-bitcoind-service-config.js";
 import type { ManagedBitcoindServiceProbeResult } from "./managed-runtime/types.js";
-export declare function waitForManagedBitcoindRpcReady(rpc: ReturnType<typeof createRpcClient>, cookieFile: string, expectedChain: "main" | "regtest", timeoutMs: number): Promise<void>;
+interface WaitForManagedBitcoindRpcReadyOptions {
+    progress?: ManagedBitcoindRpcReadyProgressReporter;
+    progressIntervalMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare function waitForManagedBitcoindRpcReady(rpc: ReturnType<typeof createRpcClient>, cookieFile: string, expectedChain: "main" | "regtest", timeoutMs: number, options?: WaitForManagedBitcoindRpcReadyOptions): Promise<void>;
 export declare function createBitcoindServiceStatus(options: {
     binaryVersion: string;
     serviceInstanceId: string;
@@ -40,3 +46,4 @@ export declare function createManagedBitcoindNodeHandle(options: {
         shutdownTimeoutMs?: number;
     }): Promise<ManagedBitcoindServiceStopResult>;
 }): ManagedBitcoindNodeHandle;
+export {};

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

@@ -8,21 +8,71 @@ 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";
-export async function waitForManagedBitcoindRpcReady(rpc, cookieFile, expectedChain, timeoutMs) {
-    await waitForManagedBitcoindCookie(cookieFile, timeoutMs, sleep);
-    const deadline = Date.now() + timeoutMs;
+import { isManagedRpcWarmupError } from "./retryable-rpc.js";
+function describeRpcReadyError(error) {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    const warmupMatch = /^bitcoind_rpc_[^_]+_-28_(.+)$/u.exec(error.message);
+    if (warmupMatch !== null) {
+        return warmupMatch[1].replaceAll("_", " ");
+    }
+    return error.message;
+}
+export async function waitForManagedBitcoindRpcReady(rpc, cookieFile, expectedChain, timeoutMs, options = {}) {
+    const sleepImpl = options.sleep ?? sleep;
+    const now = options.now ?? Date.now;
+    const progressIntervalMs = options.progressIntervalMs ?? 30_000;
+    const startedAt = now();
+    await options.progress?.({
+        code: "bitcoind-rpc-wait",
+        message: "Waiting for Bitcoin Core RPC readiness...",
+        elapsedMs: 0,
+        lastError: null,
+    });
+    await waitForManagedBitcoindCookie(cookieFile, timeoutMs, sleepImpl, {
+        now,
+        progressIntervalMs,
+        onProgress: async (elapsedMs) => {
+            await options.progress?.({
+                code: "bitcoind-rpc-wait-progress",
+                message: `Still waiting for Bitcoin Core RPC readiness (${Math.floor(elapsedMs / 1000)}s elapsed). Last RPC state: cookie not ready.`,
+                elapsedMs,
+                lastError: "cookie not ready",
+            });
+        },
+    });
+    const deadline = now() + timeoutMs;
     let lastError = null;
-    while (Date.now() < deadline) {
+    let lastProgressAt = startedAt;
+    while (now() < deadline) {
         try {
             const info = await rpc.getBlockchainInfo();
             if (info.chain !== expectedChain) {
                 throw new Error(`bitcoind_chain_expected_${expectedChain}_got_${info.chain}`);
             }
+            await options.progress?.({
+                code: "bitcoind-rpc-ready",
+                message: "Bitcoin Core RPC is ready.",
+                elapsedMs: Math.max(0, now() - startedAt),
+                lastError: null,
+            });
             return;
         }
         catch (error) {
             lastError = error;
-            await sleep(250);
+            const currentTime = now();
+            if (currentTime - lastProgressAt >= progressIntervalMs) {
+                const lastErrorText = describeRpcReadyError(lastError);
+                await options.progress?.({
+                    code: "bitcoind-rpc-wait-progress",
+                    message: `Still waiting for Bitcoin Core RPC readiness (${Math.floor((currentTime - startedAt) / 1000)}s elapsed). Last RPC state: ${lastErrorText}.`,
+                    elapsedMs: Math.max(0, currentTime - startedAt),
+                    lastError: lastErrorText,
+                });
+                lastProgressAt = currentTime;
+            }
+            await sleepImpl(250);
         }
     }
     throw lastError instanceof Error ? lastError : new Error("bitcoind_rpc_timeout");
@@ -65,7 +115,9 @@ export async function probeManagedBitcoindStatusCandidate(status, options, runti
     }
     const rpc = createRpcClient(status.rpc);
     try {
-        await waitForManagedBitcoindRpcReady(rpc, status.rpc.cookieFile, status.chain, options.startupTimeoutMs ?? DEFAULT_MANAGED_BITCOIND_STARTUP_TIMEOUT_MS);
+        await waitForManagedBitcoindRpcReady(rpc, status.rpc.cookieFile, status.chain, options.startupTimeoutMs ?? DEFAULT_MANAGED_BITCOIND_STARTUP_TIMEOUT_MS, {
+            progress: options.rpcReadyProgress,
+        });
         await validateNodeConfigForTesting(rpc, status.chain, status.zmq.endpoint, {
             requireRawTxZmq: true,
         });
@@ -97,7 +149,9 @@ export async function refreshManagedBitcoindStatus(status, paths, options) {
     const rpc = createRpcClient(status.rpc);
     const targetWalletRootId = options.walletRootId ?? status.walletRootId;
     try {
-        await waitForManagedBitcoindRpcReady(rpc, status.rpc.cookieFile, status.chain, options.startupTimeoutMs ?? DEFAULT_MANAGED_BITCOIND_STARTUP_TIMEOUT_MS);
+        await waitForManagedBitcoindRpcReady(rpc, status.rpc.cookieFile, status.chain, options.startupTimeoutMs ?? DEFAULT_MANAGED_BITCOIND_STARTUP_TIMEOUT_MS, {
+            progress: options.rpcReadyProgress,
+        });
         await validateNodeConfigForTesting(rpc, status.chain, status.zmq.endpoint, {
             requireRawTxZmq: true,
         });
@@ -117,12 +171,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-bitcoind-service-types.d.ts

@@ -1,4 +1,11 @@
 import type { InternalManagedBitcoindOptions } from "./types.js";
+export interface ManagedBitcoindRpcReadyProgressEvent {
+    code: "bitcoind-rpc-wait" | "bitcoind-rpc-wait-progress" | "bitcoind-rpc-ready";
+    message: string;
+    elapsedMs: number;
+    lastError: string | null;
+}
+export type ManagedBitcoindRpcReadyProgressReporter = (event: ManagedBitcoindRpcReadyProgressEvent) => void | Promise<void>;
 export interface ManagedWalletReplicaRpc {
     listWallets(): Promise<string[]>;
     loadWallet(walletName: string, loadOnStartup?: boolean): Promise<{
@@ -23,6 +30,7 @@ export type ManagedBitcoindServiceOptions = Pick<InternalManagedBitcoindOptions,
     getblockArchiveEndHeight?: number | null;
     getblockArchiveSha256?: string | null;
     serviceLifetime?: "persistent" | "ephemeral";
+    rpcReadyProgress?: ManagedBitcoindRpcReadyProgressReporter;
 };
 export type ResolvedManagedBitcoindServiceOptions = ManagedBitcoindServiceOptions & {
     dataDir: string;

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/command-registry.js

@@ -7,8 +7,8 @@ const commandSpecs = [
         aliases: [{ tokens: ["status"] }],
         helpEntries: [
             {
-                usage: "status",
-                description: "Show wallet-aware local service and chain status",
+                usage: "status [--live]",
+                description: "Show passive local status; use --live for RPC-backed wallet balance",
             },
         ],
         describeCommand() {

package/dist/cli/commands/service-runtime.js

@@ -44,19 +44,33 @@ async function resolveEffectiveWalletRootId(context) {
         source: "default-uninitialized",
     }));
 }
+function createRpcReadyProgressReporter(context) {
+    return async (event) => {
+        writeLine(context.stdout, event.message);
+    };
+}
 async function inspectManagedBitcoindStatus(dataDir, context) {
     const resolution = await resolveEffectiveWalletRootId(context);
+    const rpcReadyProgress = createRpcReadyProgressReporter(context);
     const probe = await context.probeManagedBitcoindService({
         dataDir,
         chain: "main",
         startHeight: 0,
         walletRootId: resolution.walletRootId,
+        rpcReadyProgress,
     });
     let node = null;
     let nodeError = null;
+    let service = probe.status;
     if (probe.compatibility === "compatible" && probe.status !== null) {
         try {
-            const rpc = context.createBitcoinRpcClient(probe.status.rpc);
+            service = await context.refreshManagedBitcoindServiceStatus(probe.status, resolveManagedServicePaths(dataDir, resolution.walletRootId), {
+                dataDir,
+                chain: "main",
+                startHeight: 0,
+                walletRootId: resolution.walletRootId,
+            });
+            const rpc = context.createBitcoinRpcClient(service.rpc);
             const [blockchainInfo, networkInfo] = await Promise.all([
                 rpc.getBlockchainInfo(),
                 rpc.getNetworkInfo(),
@@ -82,7 +96,7 @@ async function inspectManagedBitcoindStatus(dataDir, context) {
         walletRootId: resolution.walletRootId,
         walletRootSource: resolution.source,
         compatibility: probe.compatibility,
-        service: probe.status,
+        service,
         node,
         nodeError,
     };
@@ -304,11 +318,13 @@ export async function runServiceRuntimeCommand(parsed, context) {
         }
         if (parsed.command === "bitcoin-start") {
             const resolution = await resolveEffectiveWalletRootId(context);
+            const rpcReadyProgress = createRpcReadyProgressReporter(context);
             const probe = await context.probeManagedBitcoindService({
                 dataDir,
                 chain: "main",
                 startHeight: 0,
                 walletRootId: resolution.walletRootId,
+                rpcReadyProgress,
             });
             const genesis = await loadBundledGenesisParameters();
             await context.attachManagedBitcoindService({
@@ -316,6 +332,7 @@ export async function runServiceRuntimeCommand(parsed, context) {
                 chain: "main",
                 startHeight: resolveCogcoinProcessingStartHeight(genesis),
                 walletRootId: resolution.walletRootId,
+                rpcReadyProgress: probe.compatibility === "compatible" ? undefined : rpcReadyProgress,
             });
             const bitcoindStatus = probe.compatibility === "compatible" ? "already-running" : "started";
             const payload = {
@@ -356,17 +373,20 @@ export async function runServiceRuntimeCommand(parsed, context) {
             const dbPath = parsed.dbPath ?? context.resolveDefaultClientDatabasePath();
             await context.ensureDirectory(dirname(dbPath));
             const genesis = await loadBundledGenesisParameters();
+            const rpcReadyProgress = createRpcReadyProgressReporter(context);
             const bitcoindProbe = await context.probeManagedBitcoindService({
                 dataDir,
                 chain: "main",
                 startHeight: 0,
                 walletRootId: resolution.walletRootId,
+                rpcReadyProgress,
             });
             await context.attachManagedBitcoindService({
                 dataDir,
                 chain: "main",
                 startHeight: resolveCogcoinProcessingStartHeight(genesis),
                 walletRootId: resolution.walletRootId,
+                rpcReadyProgress: bitcoindProbe.compatibility === "compatible" ? undefined : rpcReadyProgress,
             });
             const indexerProbe = await context.probeIndexerDaemon({
                 dataDir,

package/dist/cli/commands/status.js

@@ -1,13 +1,19 @@
 import { dirname } from "node:path";
 import { formatBalanceReport, formatWalletOverviewReport } from "../wallet-format.js";
+import { formatStatusReport } from "../status-format.js";
 import { writeLine } from "../io.js";
 import { createTerminalPrompter } from "../prompt.js";
 import { withInteractiveWalletSecretProvider } from "../../wallet/state/provider.js";
 export async function runStatusCommand(parsed, context) {
     const dbPath = parsed.dbPath ?? context.resolveDefaultClientDatabasePath();
     const dataDir = parsed.dataDir ?? context.resolveDefaultBitcoindDataDir();
-    const packageVersion = await context.readPackageVersion();
     const runtimePaths = context.resolveWalletRuntimePaths();
+    const packageVersion = await context.readPackageVersion();
+    if (!parsed.statusLive) {
+        const status = await context.inspectPassiveClientStatus(dbPath, dataDir, runtimePaths);
+        writeLine(context.stdout, formatStatusReport(status, packageVersion));
+        return 0;
+    }
     await context.ensureDirectory(dirname(dbPath));
     const provider = withInteractiveWalletSecretProvider(context.walletSecretProvider, context.createPrompter?.() ?? createTerminalPrompter(context.stdin, context.stdout));
     const readContext = await context.openWalletReadContext({