@cogcoin/client 1.0.1 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@1.0.0` 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.1.0` 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.
 
@@ -130,13 +130,15 @@ Managed node subpath:
 
 The installed `cogcoin` command covers the first-party local wallet and node workflow:
 
+- update commands such as `update` to compare the current CLI version with the latest npm release and install it
 - wallet lifecycle commands such as `init`, `restore`, `wallet delete`, `wallet show-mnemonic`, and `repair`
 - sync and service commands such as `status`, `sync`, `follow`, `bitcoin start`, `bitcoin stop`, `bitcoin status`, `indexer start`, `indexer stop`, and `indexer status`
 - domain and field commands such as `register`, `anchor`, `show`, `domains`, `fields`, `buy`, `sell`, and `transfer`
 - COG and reputation commands such as `send`, `cog lock`, `claim`, `reclaim`, `rep give`, and `rep revoke`
-- mining commands such as `mine`, `mine start`, `mine stop`, `mine status`, `mine log`, and `mine setup`
+- mining commands such as `mine`, `mine start`, `mine stop`, `mine status`, `mine log`, `mine setup`, `mine prompt`, and `mine prompt list`
 
 The CLI also supports stable `--output json` and `--output preview-json` envelopes on the commands that advertise machine-readable output.
+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.

package/dist/bitcoind/client/factory.d.ts

@@ -1,11 +1,3 @@
-import { stopIndexerDaemonService, type IndexerDaemonClient } from "../indexer-daemon.js";
 import type { InternalManagedBitcoindOptions, ManagedBitcoindClient } from "../types.js";
-export declare function pauseIndexerDaemonForForegroundClientForTesting(options: {
-    daemon: IndexerDaemonClient;
-    dataDir: string;
-    walletRootId: string;
-    shutdownTimeoutMs?: number;
-    stopDaemon?: typeof stopIndexerDaemonService;
-}): Promise<IndexerDaemonClient | null>;
 export declare function openManagedBitcoindClient(options: Omit<InternalManagedBitcoindOptions, "chain" | "startHeight">): Promise<ManagedBitcoindClient>;
 export declare function openManagedBitcoindClientInternal(options: InternalManagedBitcoindOptions): Promise<ManagedBitcoindClient>;

package/dist/bitcoind/client/factory.js

@@ -2,46 +2,12 @@ import { loadBundledGenesisParameters } from "@cogcoin/indexer";
 import { resolveDefaultBitcoindDataDirForTesting } from "../../app-paths.js";
 import { openClient } from "../../client.js";
 import { AssumeUtxoBootstrapController, DEFAULT_SNAPSHOT_METADATA, resolveBootstrapPathsForTesting, } from "../bootstrap.js";
-import { attachOrStartIndexerDaemon, stopIndexerDaemonService, } from "../indexer-daemon.js";
 import { createRpcClient } from "../node.js";
 import { assertCogcoinProcessingStartHeight, resolveCogcoinProcessingStartHeight, } from "../processing-start-height.js";
 import { ManagedProgressController } from "../progress.js";
 import { attachOrStartManagedBitcoindService, } from "../service.js";
 import { DefaultManagedBitcoindClient } from "./managed-client.js";
 const DEFAULT_SYNC_DEBOUNCE_MS = 250;
-function isRecoverableIndexerDaemonPauseError(error) {
-    if (!(error instanceof Error)) {
-        return false;
-    }
-    if (error.message === "indexer_daemon_request_timeout"
-        || error.message === "indexer_daemon_connection_closed"
-        || error.message === "indexer_daemon_protocol_error") {
-        return true;
-    }
-    if ("code" in error) {
-        const code = error.code;
-        return code === "ENOENT" || code === "ECONNREFUSED" || code === "ECONNRESET";
-    }
-    return false;
-}
-export async function pauseIndexerDaemonForForegroundClientForTesting(options) {
-    try {
-        await options.daemon.pauseBackgroundFollow();
-        return options.daemon;
-    }
-    catch (error) {
-        await options.daemon.close().catch(() => undefined);
-        if (!isRecoverableIndexerDaemonPauseError(error)) {
-            throw error;
-        }
-        await (options.stopDaemon ?? stopIndexerDaemonService)({
-            dataDir: options.dataDir,
-            walletRootId: options.walletRootId,
-            shutdownTimeoutMs: options.shutdownTimeoutMs,
-        });
-        return null;
-    }
-}
 async function createManagedBitcoindClient(options) {
     const genesisParameters = options.genesisParameters ?? await loadBundledGenesisParameters();
     assertCogcoinProcessingStartHeight({
@@ -83,31 +49,7 @@ async function createManagedBitcoindClient(options) {
             genesisParameters,
             snapshotInterval: options.snapshotInterval,
         });
-        const indexerDaemon = options.databasePath
-            ? await pauseIndexerDaemonForForegroundClientForTesting({
-                daemon: await attachOrStartIndexerDaemon({
-                    dataDir,
-                    databasePath: options.databasePath,
-                    walletRootId: options.walletRootId,
-                    startupTimeoutMs: options.startupTimeoutMs,
-                }),
-                dataDir,
-                walletRootId,
-                shutdownTimeoutMs: options.shutdownTimeoutMs,
-            })
-            : null;
-        // The persistent service may already exist from a non-processing attach path
-        // that used startHeight 0. Cogcoin replay still begins at the requested
-        // processing boundary for this managed client.
-        const databasePath = options.databasePath ?? null;
-        return new DefaultManagedBitcoindClient(client, options.store, node, rpc, progress, bootstrap, indexerDaemon, databasePath
-            ? async () => attachOrStartIndexerDaemon({
-                dataDir,
-                databasePath,
-                walletRootId: options.walletRootId,
-                startupTimeoutMs: options.startupTimeoutMs,
-            })
-            : null, options.startHeight, options.syncDebounceMs ?? DEFAULT_SYNC_DEBOUNCE_MS, dataDir, walletRootId, options.startupTimeoutMs, options.shutdownTimeoutMs, options.fetchImpl);
+        return new DefaultManagedBitcoindClient(client, options.store, node, rpc, progress, bootstrap, options.startHeight, options.syncDebounceMs ?? DEFAULT_SYNC_DEBOUNCE_MS, dataDir, walletRootId, options.startupTimeoutMs, options.shutdownTimeoutMs, options.fetchImpl);
     }
     catch (error) {
         if (progressStarted) {

package/dist/bitcoind/client/managed-client.d.ts

@@ -1,14 +1,13 @@
 import type { BitcoinBlock } from "@cogcoin/indexer/types";
 import type { ClientStoreAdapter } from "../../types.js";
 import { AssumeUtxoBootstrapController } from "../bootstrap.js";
-import type { IndexerDaemonClient } from "../indexer-daemon.js";
 import type { ManagedProgressController } from "../progress.js";
 import type { BitcoinRpcClient } from "../rpc.js";
 import type { ManagedBitcoindClient, ManagedBitcoindNodeHandle, ManagedBitcoindStatus, SyncResult } from "../types.js";
 import { type SyncRecoveryClient } from "./internal-types.js";
 export declare class DefaultManagedBitcoindClient implements ManagedBitcoindClient {
     #private;
-    constructor(client: SyncRecoveryClient, store: ClientStoreAdapter, node: ManagedBitcoindNodeHandle, rpc: BitcoinRpcClient, progress: ManagedProgressController, bootstrap: AssumeUtxoBootstrapController, indexerDaemon: IndexerDaemonClient | null, reattachIndexerDaemon: (() => Promise<IndexerDaemonClient | null>) | null, startHeight: number, syncDebounceMs: number, dataDir: string, walletRootId: string, startupTimeoutMs: number | undefined, shutdownTimeoutMs: number | undefined, fetchImpl: typeof fetch | undefined);
+    constructor(client: SyncRecoveryClient, store: ClientStoreAdapter, node: ManagedBitcoindNodeHandle, rpc: BitcoinRpcClient, progress: ManagedProgressController, bootstrap: AssumeUtxoBootstrapController, startHeight: number, syncDebounceMs: number, dataDir: string, walletRootId: string, startupTimeoutMs: number | undefined, shutdownTimeoutMs: number | undefined, fetchImpl: typeof fetch | undefined);
     getTip(): Promise<import("../../types.js").ClientTip | null>;
     getState(): Promise<import("@cogcoin/indexer/types").IndexerState>;
     applyBlock(block: BitcoinBlock): Promise<import("../../types.js").ApplyBlockResult>;
@@ -18,5 +17,4 @@ export declare class DefaultManagedBitcoindClient implements ManagedBitcoindClie
     getNodeStatus(): Promise<ManagedBitcoindStatus>;
     close(): Promise<void>;
     playSyncCompletionScene(): Promise<void>;
-    detachToBackgroundFollow(): Promise<void>;
 }

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

@@ -26,8 +26,6 @@ export class DefaultManagedBitcoindClient {
     #rpc;
     #progress;
     #bootstrap;
-    #indexerDaemon;
-    #reattachIndexerDaemon;
     #startHeight;
     #syncDebounceMs;
     #dataDir;
@@ -45,16 +43,13 @@ export class DefaultManagedBitcoindClient {
     #syncPromise = Promise.resolve(createInitialSyncResult());
     #debounceTimer = null;
     #syncAbortControllers = new Set();
-    #backgroundFollowResumed = false;
-    constructor(client, store, node, rpc, progress, bootstrap, indexerDaemon, reattachIndexerDaemon, startHeight, syncDebounceMs, dataDir, walletRootId, startupTimeoutMs, shutdownTimeoutMs, fetchImpl) {
+    constructor(client, store, node, rpc, progress, bootstrap, startHeight, syncDebounceMs, dataDir, walletRootId, startupTimeoutMs, shutdownTimeoutMs, fetchImpl) {
         this.#client = client;
         this.#store = store;
         this.#node = node;
         this.#rpc = rpc;
         this.#progress = progress;
         this.#bootstrap = bootstrap;
-        this.#indexerDaemon = indexerDaemon;
-        this.#reattachIndexerDaemon = reattachIndexerDaemon;
         this.#startHeight = startHeight;
         this.#syncDebounceMs = syncDebounceMs;
         this.#dataDir = dataDir;
@@ -119,7 +114,6 @@ export class DefaultManagedBitcoindClient {
         const indexedTip = await this.#client.getTip();
         const progressStatus = this.#progress.getStatusSnapshot();
         const serviceStatus = await this.#node.refreshServiceStatus?.();
-        const daemonStatus = await this.#indexerDaemon?.getStatus().catch(() => null);
         try {
             const info = await this.#rpc.getBlockchainInfo();
             return {
@@ -143,7 +137,7 @@ export class DefaultManagedBitcoindClient {
                 serviceUpdatedAtUnixMs: serviceStatus?.updatedAtUnixMs ?? null,
                 walletReplica: serviceStatus?.walletReplica ?? null,
                 serviceStatus: serviceStatus ?? null,
-                indexerDaemon: daemonStatus ?? null,
+                indexerDaemon: null,
             };
         }
         catch {
@@ -168,7 +162,7 @@ export class DefaultManagedBitcoindClient {
                 serviceUpdatedAtUnixMs: serviceStatus?.updatedAtUnixMs ?? null,
                 walletReplica: serviceStatus?.walletReplica ?? null,
                 serviceStatus: serviceStatus ?? null,
-                indexerDaemon: daemonStatus ?? null,
+                indexerDaemon: null,
             };
         }
     }
@@ -197,20 +191,11 @@ export class DefaultManagedBitcoindClient {
         await this.#progress.close();
         await this.#node.stop();
         await this.#client.close();
-        await this.#resumeIndexerBackgroundFollow();
-        await this.#indexerDaemon?.close();
-        this.#indexerDaemon = null;
     }
     async playSyncCompletionScene() {
         this.#assertOpen();
         await this.#progress.playCompletionScene();
     }
-    async detachToBackgroundFollow() {
-        this.#assertOpen();
-        await this.#resumeIndexerBackgroundFollow();
-        await this.#indexerDaemon?.close();
-        this.#indexerDaemon = null;
-    }
     async #setGetblockStatusMessage(currentHeight, message, targetHeight = currentHeight) {
         const safeTargetHeight = Math.max(currentHeight, targetHeight);
         await this.#progress.setPhase("bitcoin_sync", {
@@ -404,33 +389,4 @@ export class DefaultManagedBitcoindClient {
             throw new Error("managed_bitcoind_client_closed");
         }
     }
-    async #resumeIndexerBackgroundFollow() {
-        if (this.#backgroundFollowResumed) {
-            return;
-        }
-        if (this.#indexerDaemon === null && this.#reattachIndexerDaemon === null) {
-            this.#backgroundFollowResumed = true;
-            return;
-        }
-        if (this.#indexerDaemon !== null) {
-            try {
-                await this.#indexerDaemon.resumeBackgroundFollow();
-                this.#backgroundFollowResumed = true;
-                return;
-            }
-            catch (error) {
-                if (this.#reattachIndexerDaemon === null) {
-                    throw error;
-                }
-            }
-        }
-        const reattachIndexerDaemon = this.#reattachIndexerDaemon;
-        if (reattachIndexerDaemon === null) {
-            return;
-        }
-        const replacementDaemon = await reattachIndexerDaemon();
-        this.#indexerDaemon = replacementDaemon;
-        await replacementDaemon?.resumeBackgroundFollow();
-        this.#backgroundFollowResumed = true;
-    }
 }

package/dist/bitcoind/indexer-daemon-main.js

@@ -3,15 +3,20 @@ import net from "node:net";
 import { access, constants, mkdir, readFile, rm } from "node:fs/promises";
 import { loadBundledGenesisParameters, serializeIndexerState } from "@cogcoin/indexer";
 import { openManagedBitcoindClientInternal } from "./client.js";
+import { DEFAULT_SNAPSHOT_METADATA } from "./bootstrap.js";
 import { openClient } from "../client.js";
 import { openSqliteStore } from "../sqlite/index.js";
 import { writeRuntimeStatusFile } from "../wallet/fs/status-file.js";
 import { createRpcClient } from "./node.js";
 import { normalizeCogcoinProcessingStartHeight } from "./processing-start-height.js";
+import { createBootstrapProgress } from "./progress/formatting.js";
 import { resolveManagedServicePaths, UNINITIALIZED_WALLET_ROOT_ID } from "./service-paths.js";
 import { INDEXER_DAEMON_SCHEMA_VERSION, INDEXER_DAEMON_SERVICE_API_VERSION, } from "./types.js";
 const SNAPSHOT_TTL_MS = 30_000;
 const HEARTBEAT_INTERVAL_MS = 1_000;
+const FORCE_RESUME_ERROR_ENV = "COGCOIN_TEST_INDEXER_DAEMON_FORCE_RESUME_ERROR";
+const BACKGROUND_FOLLOW_RESUME_TIMEOUT_MS = 30_000;
+const BACKGROUND_FOLLOW_RESUME_TIMEOUT_ERROR = "indexer_daemon_background_follow_resume_timeout";
 function parseArg(name) {
     const prefix = `--${name}=`;
     const value = process.argv.find((entry) => entry.startsWith(prefix));
@@ -34,6 +39,22 @@ async function readJsonFile(filePath) {
 async function readManagedBitcoindStatus(paths) {
     return readJsonFile(paths.bitcoindStatusPath);
 }
+async function withTimeout(promise, timeoutMs, errorCode) {
+    let timeoutId = null;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timeoutId = setTimeout(() => reject(new Error(errorCode)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeoutId !== null) {
+            clearTimeout(timeoutId);
+        }
+    }
+}
 async function readPackageVersionFromDisk() {
     try {
         const raw = await readFile(new URL("../../package.json", import.meta.url), "utf8");
@@ -177,6 +198,12 @@ async function main() {
     let backgroundStore = null;
     let backgroundClient = null;
     let backgroundResumePromise = null;
+    let backgroundFollowError = null;
+    let backgroundFollowActive = false;
+    let bootstrapPhase = "paused";
+    let bootstrapProgress = createBootstrapProgress("paused", DEFAULT_SNAPSHOT_METADATA);
+    let cogcoinSyncHeight = null;
+    let cogcoinSyncTargetHeight = null;
     await mkdir(paths.indexerServiceRoot, { recursive: true });
     await rm(paths.indexerDaemonSocketPath, { force: true }).catch(() => undefined);
     const observeAppliedTip = (appliedTip, now) => {
@@ -240,12 +267,39 @@ async function main() {
         lastAppliedAtUnixMs,
         activeSnapshotCount: snapshots.size,
         lastError,
+        backgroundFollowActive,
+        bootstrapPhase,
+        bootstrapProgress: { ...bootstrapProgress },
+        cogcoinSyncHeight,
+        cogcoinSyncTargetHeight,
     });
     const writeStatus = async () => {
         const status = buildStatus();
         await writeRuntimeStatusFile(paths.indexerDaemonStatusPath, status);
         return status;
     };
+    const recordBackgroundFollowFailure = async (message) => {
+        const now = Date.now();
+        heartbeatAtUnixMs = now;
+        updatedAtUnixMs = now;
+        state = "failed";
+        lastError = message;
+        backgroundFollowError = message;
+        backgroundFollowActive = false;
+        bootstrapPhase = "error";
+        bootstrapProgress = {
+            ...createBootstrapProgress("error", DEFAULT_SNAPSHOT_METADATA),
+            blocks: coreBestHeight,
+            headers: coreBestHeight,
+            targetHeight: coreBestHeight,
+            message,
+            lastError: message,
+            updatedAt: now,
+        };
+        cogcoinSyncHeight = appliedTipHeight;
+        cogcoinSyncTargetHeight = coreBestHeight;
+        await writeStatus();
+    };
     const refreshStatus = async () => {
         const now = Date.now();
         heartbeatAtUnixMs = now;
@@ -254,23 +308,88 @@ async function main() {
             readCoreTipStatus(paths),
             readAppliedTipStatus(databasePath),
         ]);
+        const backgroundStatus = await backgroundClient?.getNodeStatus().catch(() => null) ?? null;
+        if (backgroundStatus?.following === true) {
+            backgroundFollowError = null;
+        }
         rpcReachable = coreStatus.rpcReachable;
         coreBestHeight = coreStatus.coreBestHeight;
         coreBestHash = coreStatus.coreBestHash;
         observeAppliedTip(indexedStatus.appliedTip, now);
+        backgroundFollowActive = backgroundStatus?.following ?? (backgroundClient !== null);
+        bootstrapPhase = backgroundStatus?.bootstrapPhase ?? (backgroundFollowActive ? "follow_tip" : "paused");
+        bootstrapProgress = backgroundStatus?.bootstrapProgress ?? createBootstrapProgress(bootstrapPhase, DEFAULT_SNAPSHOT_METADATA);
+        cogcoinSyncHeight = backgroundStatus?.cogcoinSyncHeight ?? indexedStatus.appliedTip?.height ?? null;
+        cogcoinSyncTargetHeight = backgroundStatus?.cogcoinSyncTargetHeight ?? coreStatus.coreBestHeight;
+        if (backgroundStatus === null && backgroundFollowError !== null) {
+            state = "failed";
+            lastError = backgroundFollowError;
+            backgroundFollowActive = false;
+            bootstrapPhase = "error";
+            bootstrapProgress = {
+                ...createBootstrapProgress("error", DEFAULT_SNAPSHOT_METADATA),
+                blocks: coreStatus.coreBestHeight,
+                headers: coreStatus.coreBestHeight,
+                targetHeight: coreStatus.coreBestHeight,
+                message: backgroundFollowError,
+                lastError: backgroundFollowError,
+                updatedAt: now,
+            };
+            cogcoinSyncHeight = indexedStatus.appliedTip?.height ?? null;
+            cogcoinSyncTargetHeight = coreStatus.coreBestHeight;
+            return writeStatus();
+        }
         if (indexedStatus.schemaMismatch) {
             state = "schema-mismatch";
             lastError = indexedStatus.error;
+            bootstrapPhase = "error";
+            bootstrapProgress = {
+                ...bootstrapProgress,
+                phase: "error",
+                message: indexedStatus.error ?? "Indexer schema mismatch.",
+                lastError: indexedStatus.error,
+                updatedAt: now,
+            };
             return writeStatus();
         }
         if (indexedStatus.error !== null) {
             state = "failed";
             lastError = indexedStatus.error;
+            bootstrapPhase = "error";
+            bootstrapProgress = {
+                ...bootstrapProgress,
+                phase: "error",
+                message: indexedStatus.error,
+                lastError: indexedStatus.error,
+                updatedAt: now,
+            };
             return writeStatus();
         }
         const leaseState = deriveLeaseState(coreStatus, indexedStatus.appliedTip);
         state = leaseState.state;
         lastError = leaseState.lastError;
+        if (lastError !== null) {
+            bootstrapPhase = leaseState.state === "starting" ? "paused" : "error";
+            bootstrapProgress = {
+                ...bootstrapProgress,
+                phase: bootstrapPhase,
+                message: lastError,
+                lastError,
+                updatedAt: now,
+            };
+        }
+        else if (backgroundStatus === null) {
+            bootstrapPhase = leaseState.state === "synced" ? "follow_tip" : "paused";
+            bootstrapProgress = {
+                ...createBootstrapProgress(bootstrapPhase, DEFAULT_SNAPSHOT_METADATA),
+                blocks: coreStatus.coreBestHeight,
+                headers: coreStatus.coreBestHeight,
+                targetHeight: coreStatus.coreBestHeight,
+                updatedAt: now,
+            };
+            cogcoinSyncHeight = indexedStatus.appliedTip?.height ?? null;
+            cogcoinSyncTargetHeight = coreStatus.coreBestHeight;
+        }
         return writeStatus();
     };
     const pauseBackgroundFollow = async () => {
@@ -283,6 +402,12 @@ async function main() {
         backgroundStore = null;
         await client?.close().catch(() => undefined);
         await store?.close().catch(() => undefined);
+        backgroundFollowError = null;
+        backgroundFollowActive = false;
+        bootstrapPhase = "paused";
+        bootstrapProgress = createBootstrapProgress("paused", DEFAULT_SNAPSHOT_METADATA);
+        cogcoinSyncHeight = appliedTipHeight;
+        cogcoinSyncTargetHeight = coreBestHeight;
     };
     const resumeBackgroundFollow = async () => {
         if (backgroundClient !== null) {
@@ -292,35 +417,50 @@ async function main() {
             return backgroundResumePromise;
         }
         backgroundResumePromise = (async () => {
-            const bitcoindStatus = await readManagedBitcoindStatus(paths);
-            const store = await openSqliteStore({ filename: databasePath });
-            const chain = bitcoindStatus?.chain ?? "main";
-            const startHeight = normalizeCogcoinProcessingStartHeight({
-                chain,
-                startHeight: bitcoindStatus?.startHeight,
-                genesisParameters,
-            });
+            let store = null;
             try {
+                const forcedResumeError = process.env[FORCE_RESUME_ERROR_ENV]?.trim();
+                if (forcedResumeError) {
+                    throw new Error(forcedResumeError);
+                }
+                const bitcoindStatus = await readManagedBitcoindStatus(paths);
+                store = await openSqliteStore({ filename: databasePath });
+                const openedStore = store;
+                const chain = bitcoindStatus?.chain ?? "main";
+                const startHeight = normalizeCogcoinProcessingStartHeight({
+                    chain,
+                    startHeight: bitcoindStatus?.startHeight,
+                    genesisParameters,
+                });
                 const client = await openManagedBitcoindClientInternal({
-                    store,
+                    store: openedStore,
                     dataDir,
                     chain,
                     startHeight,
                     walletRootId,
                     progressOutput: "none",
                 });
-                try {
-                    await client.startFollowingTip();
-                    backgroundStore = store;
-                    backgroundClient = client;
-                }
-                catch (error) {
+                backgroundStore = openedStore;
+                backgroundClient = client;
+                backgroundFollowError = null;
+                backgroundFollowActive = true;
+                void client.startFollowingTip().catch(async (error) => {
+                    if (backgroundClient !== client || backgroundStore !== openedStore) {
+                        return;
+                    }
+                    backgroundClient = null;
+                    backgroundStore = null;
+                    backgroundFollowActive = false;
                     await client.close().catch(() => undefined);
-                    throw error;
-                }
+                    await openedStore.close().catch(() => undefined);
+                    const message = error instanceof Error ? error.message : String(error);
+                    await recordBackgroundFollowFailure(message).catch(() => undefined);
+                });
             }
             catch (error) {
-                await store.close().catch(() => undefined);
+                await store?.close().catch(() => undefined);
+                const message = error instanceof Error ? error.message : String(error);
+                await recordBackgroundFollowFailure(message).catch(() => undefined);
                 throw error;
             }
         })();
@@ -434,6 +574,11 @@ async function main() {
                                 lastAppliedAtUnixMs: leaseStatus.lastAppliedAtUnixMs,
                                 activeSnapshotCount: leaseStatus.activeSnapshotCount,
                                 lastError: leaseStatus.lastError,
+                                backgroundFollowActive: leaseStatus.backgroundFollowActive ?? false,
+                                bootstrapPhase: leaseStatus.bootstrapPhase ?? null,
+                                bootstrapProgress: leaseStatus.bootstrapProgress ?? null,
+                                cogcoinSyncHeight: leaseStatus.cogcoinSyncHeight ?? null,
+                                cogcoinSyncTargetHeight: leaseStatus.cogcoinSyncTargetHeight ?? null,
                                 tipHeight: snapshot.tipHeight,
                                 tipHash: snapshot.tipHash,
                                 openedAtUnixMs: snapshot.openedAtUnixMs,
@@ -494,17 +639,17 @@ async function main() {
                             });
                             return;
                         }
-                        if (request.method === "PauseBackgroundFollow") {
-                            await pauseBackgroundFollow();
-                            writeResponse({
-                                id: request.id,
-                                ok: true,
-                                result: null,
-                            });
-                            return;
-                        }
                         if (request.method === "ResumeBackgroundFollow") {
-                            await resumeBackgroundFollow();
+                            try {
+                                await withTimeout(resumeBackgroundFollow(), BACKGROUND_FOLLOW_RESUME_TIMEOUT_MS, BACKGROUND_FOLLOW_RESUME_TIMEOUT_ERROR);
+                            }
+                            catch (error) {
+                                if (error instanceof Error
+                                    && error.message === BACKGROUND_FOLLOW_RESUME_TIMEOUT_ERROR) {
+                                    await recordBackgroundFollowFailure(error.message).catch(() => undefined);
+                                }
+                                throw error;
+                            }
                             writeResponse({
                                 id: request.id,
                                 ok: true,

package/dist/bitcoind/indexer-daemon.d.ts

@@ -1,8 +1,9 @@
-import { type ManagedIndexerDaemonObservedStatus, type ManagedIndexerDaemonStatus } from "./types.js";
+import { type BootstrapPhase, type BootstrapProgress, type ManagedIndexerDaemonObservedStatus, type ManagedIndexerDaemonStatus } from "./types.js";
 import { resolveManagedServicePaths } from "./service-paths.js";
+export declare const INDEXER_DAEMON_BACKGROUND_FOLLOW_RECOVERY_FAILED = "indexer_daemon_background_follow_recovery_failed";
 interface DaemonRequest {
     id: string;
-    method: "GetStatus" | "OpenSnapshot" | "ReadSnapshot" | "CloseSnapshot" | "PauseBackgroundFollow" | "ResumeBackgroundFollow";
+    method: "GetStatus" | "OpenSnapshot" | "ReadSnapshot" | "CloseSnapshot" | "ResumeBackgroundFollow";
     token?: string;
 }
 interface DaemonResponse {
@@ -35,6 +36,11 @@ export interface IndexerSnapshotHandle {
     lastAppliedAtUnixMs: number | null;
     activeSnapshotCount: number;
     lastError: string | null;
+    backgroundFollowActive: boolean;
+    bootstrapPhase: BootstrapPhase | null;
+    bootstrapProgress: BootstrapProgress | null;
+    cogcoinSyncHeight: number | null;
+    cogcoinSyncTargetHeight: number | null;
     tipHeight: number | null;
     tipHash: string | null;
     openedAtUnixMs: number;
@@ -65,7 +71,6 @@ export interface IndexerDaemonClient {
     openSnapshot(): Promise<IndexerSnapshotHandle>;
     readSnapshot(token: string): Promise<IndexerSnapshotPayload>;
     closeSnapshot(token: string): Promise<void>;
-    pauseBackgroundFollow(): Promise<void>;
     resumeBackgroundFollow(): Promise<void>;
     close(): Promise<void>;
 }
@@ -84,11 +89,13 @@ export interface CoherentIndexerSnapshotLease {
     payload: IndexerSnapshotPayload;
     status: ManagedIndexerDaemonStatus;
 }
+type ManagedIndexerDaemonServiceLifetime = "persistent" | "ephemeral";
 export declare function stopIndexerDaemonServiceWithLockHeld(options: {
     dataDir: string;
     walletRootId?: string;
     shutdownTimeoutMs?: number;
     paths?: ReturnType<typeof resolveManagedServicePaths>;
+    processId?: number | null;
 }): Promise<IndexerDaemonStopResult>;
 export declare function probeIndexerDaemon(options: {
     dataDir: string;
@@ -104,6 +111,10 @@ export declare function attachOrStartIndexerDaemon(options: {
     databasePath: string;
     walletRootId?: string;
     startupTimeoutMs?: number;
+    shutdownTimeoutMs?: number;
+    serviceLifetime?: ManagedIndexerDaemonServiceLifetime;
+    ensureBackgroundFollow?: boolean;
+    expectedBinaryVersion?: string | null;
 }): Promise<IndexerDaemonClient>;
 export declare function stopIndexerDaemonService(options: {
     dataDir: string;