@cogcoin/client 1.0.2 → 1.1.1

package/dist/bitcoind/indexer-daemon.js

@@ -3,11 +3,18 @@ import { spawn } from "node:child_process";
 import { mkdir, readFile, rm } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import net from "node:net";
+import { compareSemver, parseSemver } from "../semver.js";
 import { acquireFileLock, FileLockBusyError } from "../wallet/fs/lock.js";
 import { writeRuntimeStatusFile } from "../wallet/fs/status-file.js";
 import { INDEXER_DAEMON_SCHEMA_VERSION, INDEXER_DAEMON_SERVICE_API_VERSION, } from "./types.js";
 import { resolveManagedServicePaths, UNINITIALIZED_WALLET_ROOT_ID } from "./service-paths.js";
 const DEFAULT_STARTUP_TIMEOUT_MS = 30_000;
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5_000;
+const FORCE_KILL_TIMEOUT_MS = 5_000;
+const INDEXER_DAEMON_REQUEST_TIMEOUT_MS = 15_000;
+const INDEXER_DAEMON_RESUME_BACKGROUND_FOLLOW_REQUEST_TIMEOUT_MS = 35_000;
+const INDEXER_DAEMON_BACKGROUND_FOLLOW_NOT_ACTIVE = "indexer_daemon_background_follow_not_active";
+export const INDEXER_DAEMON_BACKGROUND_FOLLOW_RECOVERY_FAILED = "indexer_daemon_background_follow_recovery_failed";
 async function readJsonFile(filePath) {
     try {
         return JSON.parse(await readFile(filePath, "utf8"));
@@ -53,11 +60,16 @@ async function clearIndexerDaemonRuntimeArtifacts(paths) {
     await rm(paths.indexerDaemonStatusPath, { force: true }).catch(() => undefined);
     await rm(paths.indexerDaemonSocketPath, { force: true }).catch(() => undefined);
 }
+function ignoreProcessNotFound(error) {
+    if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+        throw error;
+    }
+}
 export async function stopIndexerDaemonServiceWithLockHeld(options) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
     const paths = options.paths ?? resolveManagedServicePaths(options.dataDir, walletRootId);
     const status = await readJsonFile(paths.indexerDaemonStatusPath);
-    const processId = status?.processId ?? null;
+    const processId = options.processId ?? status?.processId ?? null;
     if (status === null || processId === null || !await isProcessAlive(processId)) {
         await clearIndexerDaemonRuntimeArtifacts(paths);
         return {
@@ -69,11 +81,23 @@ export async function stopIndexerDaemonServiceWithLockHeld(options) {
         process.kill(processId, "SIGTERM");
     }
     catch (error) {
-        if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+        ignoreProcessNotFound(error);
+    }
+    try {
+        await waitForProcessExit(processId, options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS, "indexer_daemon_stop_timeout");
+    }
+    catch (error) {
+        if (!(error instanceof Error) || error.message !== "indexer_daemon_stop_timeout") {
             throw error;
         }
+        try {
+            process.kill(processId, "SIGKILL");
+        }
+        catch (killError) {
+            ignoreProcessNotFound(killError);
+        }
+        await waitForProcessExit(processId, FORCE_KILL_TIMEOUT_MS, "indexer_daemon_stop_timeout");
     }
-    await waitForProcessExit(processId, options.shutdownTimeoutMs ?? 5_000, "indexer_daemon_stop_timeout");
     await clearIndexerDaemonRuntimeArtifacts(paths);
     return {
         status: "stopped",
@@ -95,7 +119,9 @@ function createIndexerDaemonClient(socketPath, closeOptions = null) {
                 socket.destroy();
                 handler();
             };
-            socket.setTimeout(15_000);
+            socket.setTimeout(request.method === "ResumeBackgroundFollow"
+                ? INDEXER_DAEMON_RESUME_BACKGROUND_FOLLOW_REQUEST_TIMEOUT_MS
+                : INDEXER_DAEMON_REQUEST_TIMEOUT_MS);
             socket.on("connect", () => {
                 socket.write(`${JSON.stringify(request)}\n`);
             });
@@ -169,12 +195,6 @@ function createIndexerDaemonClient(socketPath, closeOptions = null) {
                 token,
             });
         },
-        async pauseBackgroundFollow() {
-            await sendRequest({
-                id: randomUUID(),
-                method: "PauseBackgroundFollow",
-            });
-        },
         async resumeBackgroundFollow() {
             await sendRequest({
                 id: randomUUID(),
@@ -271,8 +291,23 @@ function buildStatusFromSnapshotHandle(handle) {
         lastAppliedAtUnixMs: handle.lastAppliedAtUnixMs,
         activeSnapshotCount: handle.activeSnapshotCount,
         lastError: handle.lastError,
+        backgroundFollowActive: handle.backgroundFollowActive,
+        bootstrapPhase: handle.bootstrapPhase,
+        bootstrapProgress: handle.bootstrapProgress,
+        cogcoinSyncHeight: handle.cogcoinSyncHeight,
+        cogcoinSyncTargetHeight: handle.cogcoinSyncTargetHeight,
     };
 }
+function isStaleIndexerDaemonVersion(status, expectedBinaryVersion) {
+    if (status === null || expectedBinaryVersion === null || expectedBinaryVersion === undefined) {
+        return false;
+    }
+    if (parseSemver(expectedBinaryVersion) === null) {
+        return false;
+    }
+    const comparison = compareSemver(status.binaryVersion, expectedBinaryVersion);
+    return comparison === null || comparison < 0;
+}
 async function probeIndexerDaemonAtSocket(socketPath, expectedWalletRootId) {
     const client = createIndexerDaemonClient(socketPath);
     try {
@@ -368,15 +403,84 @@ export async function readObservedIndexerDaemonStatus(options) {
     return readJsonFile(paths.indexerDaemonStatusPath);
 }
 export async function attachOrStartIndexerDaemon(options) {
+    const requestBackgroundFollow = async (client, observedStatus = null) => {
+        if (options.ensureBackgroundFollow !== true) {
+            return client;
+        }
+        if (observedStatus?.backgroundFollowActive === true) {
+            return client;
+        }
+        await client.resumeBackgroundFollow();
+        const status = await client.getStatus();
+        if (status.backgroundFollowActive !== true) {
+            throw new Error(INDEXER_DAEMON_BACKGROUND_FOLLOW_NOT_ACTIVE);
+        }
+        return client;
+    };
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
     const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
     const startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
     const serviceLifetime = options.serviceLifetime ?? "persistent";
+    const expectedBinaryVersion = options.expectedBinaryVersion ?? null;
+    const startDaemon = async () => {
+        await mkdir(paths.indexerServiceRoot, { recursive: true });
+        const daemonEntryPath = fileURLToPath(new URL("./indexer-daemon-main.js", import.meta.url));
+        const spawnOptions = serviceLifetime === "ephemeral"
+            ? {
+                stdio: "ignore",
+            }
+            : {
+                detached: true,
+                stdio: "ignore",
+            };
+        const child = spawn(process.execPath, [
+            daemonEntryPath,
+            `--data-dir=${options.dataDir}`,
+            `--database-path=${options.databasePath}`,
+            `--wallet-root-id=${walletRootId}`,
+        ], {
+            ...spawnOptions,
+        });
+        if (serviceLifetime !== "ephemeral") {
+            child.unref();
+        }
+        try {
+            await waitForIndexerDaemon(options.dataDir, walletRootId, startupTimeoutMs);
+        }
+        catch (error) {
+            if (child.pid !== undefined) {
+                try {
+                    process.kill(child.pid, "SIGTERM");
+                }
+                catch {
+                    // ignore shutdown failures while unwinding startup errors
+                }
+            }
+            throw error;
+        }
+        return createIndexerDaemonClient(paths.indexerDaemonSocketPath, {
+            dataDir: options.dataDir,
+            walletRootId,
+            serviceLifetime,
+            ownership: "started",
+            shutdownTimeoutMs: options.shutdownTimeoutMs,
+        });
+    };
     const existingProbe = await probeIndexerDaemonAtSocket(paths.indexerDaemonSocketPath, walletRootId);
     if (existingProbe.compatibility === "compatible" && existingProbe.client !== null) {
-        return existingProbe.client;
+        if (!isStaleIndexerDaemonVersion(existingProbe.status, expectedBinaryVersion)) {
+            try {
+                return await requestBackgroundFollow(existingProbe.client, existingProbe.status);
+            }
+            catch {
+                await existingProbe.client.close().catch(() => undefined);
+            }
+        }
+        else {
+            await existingProbe.client.close().catch(() => undefined);
+        }
     }
-    if (existingProbe.compatibility !== "unreachable") {
+    if (existingProbe.compatibility !== "unreachable" && existingProbe.compatibility !== "compatible") {
         throw new Error(existingProbe.error ?? "indexer_daemon_protocol_error");
     }
     try {
@@ -389,53 +493,43 @@ export async function attachOrStartIndexerDaemon(options) {
         try {
             const liveProbe = await probeIndexerDaemonAtSocket(paths.indexerDaemonSocketPath, walletRootId);
             if (liveProbe.compatibility === "compatible" && liveProbe.client !== null) {
-                return liveProbe.client;
+                if (!isStaleIndexerDaemonVersion(liveProbe.status, expectedBinaryVersion)) {
+                    try {
+                        return await requestBackgroundFollow(liveProbe.client, liveProbe.status);
+                    }
+                    catch {
+                        await liveProbe.client.close().catch(() => undefined);
+                        await stopIndexerDaemonServiceWithLockHeld({
+                            dataDir: options.dataDir,
+                            walletRootId,
+                            shutdownTimeoutMs: options.shutdownTimeoutMs,
+                            paths,
+                            processId: liveProbe.status?.processId ?? null,
+                        });
+                    }
+                }
+                else {
+                    await liveProbe.client.close().catch(() => undefined);
+                    await stopIndexerDaemonServiceWithLockHeld({
+                        dataDir: options.dataDir,
+                        walletRootId,
+                        shutdownTimeoutMs: options.shutdownTimeoutMs,
+                        paths,
+                        processId: liveProbe.status?.processId ?? null,
+                    });
+                }
             }
-            if (liveProbe.compatibility !== "unreachable") {
+            else if (liveProbe.compatibility !== "unreachable") {
                 throw new Error(liveProbe.error ?? "indexer_daemon_protocol_error");
             }
-            await mkdir(paths.indexerServiceRoot, { recursive: true });
-            const daemonEntryPath = fileURLToPath(new URL("./indexer-daemon-main.js", import.meta.url));
-            const spawnOptions = serviceLifetime === "ephemeral"
-                ? {
-                    stdio: "ignore",
-                }
-                : {
-                    detached: true,
-                    stdio: "ignore",
-                };
-            const child = spawn(process.execPath, [
-                daemonEntryPath,
-                `--data-dir=${options.dataDir}`,
-                `--database-path=${options.databasePath}`,
-                `--wallet-root-id=${walletRootId}`,
-            ], {
-                ...spawnOptions,
-            });
-            if (serviceLifetime !== "ephemeral") {
-                child.unref();
-            }
+            const daemon = await startDaemon();
             try {
-                await waitForIndexerDaemon(options.dataDir, walletRootId, startupTimeoutMs);
+                return await requestBackgroundFollow(daemon);
             }
             catch (error) {
-                if (child.pid !== undefined) {
-                    try {
-                        process.kill(child.pid, "SIGTERM");
-                    }
-                    catch {
-                        // ignore shutdown failures while unwinding startup errors
-                    }
-                }
-                throw error;
+                await daemon.close().catch(() => undefined);
+                throw new Error(INDEXER_DAEMON_BACKGROUND_FOLLOW_RECOVERY_FAILED, { cause: error });
             }
-            return createIndexerDaemonClient(paths.indexerDaemonSocketPath, {
-                dataDir: options.dataDir,
-                walletRootId,
-                serviceLifetime,
-                ownership: "started",
-                shutdownTimeoutMs: options.shutdownTimeoutMs,
-            });
         }
         finally {
             await lock.release();
@@ -444,13 +538,7 @@ export async function attachOrStartIndexerDaemon(options) {
     catch (error) {
         if (error instanceof FileLockBusyError) {
             await waitForIndexerDaemon(options.dataDir, walletRootId, startupTimeoutMs);
-            return createIndexerDaemonClient(paths.indexerDaemonSocketPath, {
-                dataDir: options.dataDir,
-                walletRootId,
-                serviceLifetime,
-                ownership: "attached",
-                shutdownTimeoutMs: options.shutdownTimeoutMs,
-            });
+            return attachOrStartIndexerDaemon(options);
         }
         throw error;
     }

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

@@ -0,0 +1,12 @@
+import type { ManagedIndexerDaemonObservedStatus } from "./types.js";
+export interface ManagedIndexerMonitor {
+    getStatus(): Promise<ManagedIndexerDaemonObservedStatus>;
+    close(): Promise<void>;
+}
+export declare function openManagedIndexerMonitor(options: {
+    dataDir: string;
+    databasePath: string;
+    walletRootId?: string;
+    startupTimeoutMs?: number;
+    expectedBinaryVersion?: string | null;
+}): Promise<ManagedIndexerMonitor>;

package/dist/bitcoind/indexer-monitor.js

@@ -0,0 +1,93 @@
+import { readFile } from "node:fs/promises";
+import { loadBundledGenesisParameters } from "@cogcoin/indexer";
+import { readPackageVersionFromDisk } from "../package-version.js";
+import { attachOrStartIndexerDaemon, readObservedIndexerDaemonStatus, } from "./indexer-daemon.js";
+import { resolveCogcoinProcessingStartHeight } from "./processing-start-height.js";
+import { resolveManagedServicePaths, UNINITIALIZED_WALLET_ROOT_ID } from "./service-paths.js";
+import { attachOrStartManagedBitcoindService } from "./service.js";
+async function readJsonFile(filePath) {
+    try {
+        return JSON.parse(await readFile(filePath, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+async function resolveStartOptions(options) {
+    const paths = resolveManagedServicePaths(options.dataDir, options.walletRootId);
+    const observedStatus = await readJsonFile(paths.bitcoindStatusPath).catch(() => null);
+    if (observedStatus !== null) {
+        return {
+            chain: observedStatus.chain,
+            startHeight: observedStatus.startHeight,
+        };
+    }
+    const genesisParameters = await loadBundledGenesisParameters();
+    return {
+        chain: "main",
+        startHeight: resolveCogcoinProcessingStartHeight(genesisParameters),
+    };
+}
+export async function openManagedIndexerMonitor(options) {
+    const expectedBinaryVersion = options.expectedBinaryVersion === undefined
+        ? await readPackageVersionFromDisk()
+        : options.expectedBinaryVersion;
+    const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
+    const startOptions = await resolveStartOptions({
+        dataDir: options.dataDir,
+        walletRootId,
+    });
+    await attachOrStartManagedBitcoindService({
+        dataDir: options.dataDir,
+        chain: startOptions.chain,
+        startHeight: startOptions.startHeight,
+        walletRootId,
+        startupTimeoutMs: options.startupTimeoutMs,
+    });
+    const daemon = await attachOrStartIndexerDaemon({
+        dataDir: options.dataDir,
+        databasePath: options.databasePath,
+        walletRootId,
+        startupTimeoutMs: options.startupTimeoutMs,
+        ensureBackgroundFollow: true,
+        expectedBinaryVersion,
+    });
+    return createManagedIndexerMonitor({
+        daemon,
+        dataDir: options.dataDir,
+        walletRootId,
+    });
+}
+function createManagedIndexerMonitor(options) {
+    let closed = false;
+    return {
+        async getStatus() {
+            if (closed) {
+                throw new Error("managed_indexer_monitor_closed");
+            }
+            try {
+                return await options.daemon.getStatus();
+            }
+            catch (error) {
+                const observed = await readObservedIndexerDaemonStatus({
+                    dataDir: options.dataDir,
+                    walletRootId: options.walletRootId,
+                }).catch(() => null);
+                if (observed !== null) {
+                    return observed;
+                }
+                throw error;
+            }
+        },
+        async close() {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            await options.daemon.close().catch(() => undefined);
+        },
+    };
+}

package/dist/bitcoind/progress/controller.js

@@ -128,8 +128,11 @@ export class ManagedProgressController {
             this.#cogcoinSyncTargetHeight = null;
         }
         if (this.#followVisualMode) {
+            const followIndexedHeight = phase === "follow_tip"
+                ? this.#cogcoinSyncHeight ?? this.#progress.blocks ?? this.#followScene.indexedHeight
+                : undefined;
             syncFollowSceneState(this.#followScene, {
-                indexedHeight: phase === "follow_tip" ? this.#cogcoinSyncHeight : undefined,
+                indexedHeight: followIndexedHeight,
                 nodeHeight: this.#progress.blocks,
                 liveActivated: phase === "follow_tip" || this.#followScene.liveActivated,
             });

package/dist/bitcoind/progress/follow-scene.d.ts

@@ -19,16 +19,20 @@ export interface FollowSceneStateForTesting {
 export interface FollowFrameRenderOptions {
     artworkCogText?: string | null;
     artworkSatText?: string | null;
+    artworkStatusLeftText?: string | null;
+    artworkStatusRightText?: string | null;
 }
 export declare function createFollowSceneState(indexedHeight?: number | null, blockTimesByHeight?: Record<number, number>): FollowSceneStateForTesting;
 export declare function setFollowBlockTime(state: FollowSceneStateForTesting, height: number, blockTime: number): void;
 export declare function replaceFollowBlockTimes(state: FollowSceneStateForTesting, blockTimesByHeight: Record<number, number>): void;
 export declare function formatCompactFollowAgeLabel(blockTime: number, now: number): string;
 export declare const formatCompactFollowAgeLabelForTesting: typeof formatCompactFollowAgeLabel;
-export declare function syncFollowSceneState(state: FollowSceneStateForTesting, { indexedHeight, nodeHeight, liveActivated, }: {
+export declare function syncFollowSceneState(state: FollowSceneStateForTesting, { indexedHeight, nodeHeight, liveActivated, authoritativeTip, settleLatest, }: {
     indexedHeight?: number | null;
     nodeHeight?: number | null;
     liveActivated?: boolean;
+    authoritativeTip?: boolean;
+    settleLatest?: boolean;
 }): void;
 export declare function advanceFollowSceneState(state: FollowSceneStateForTesting, now: number): void;
 export declare function renderFollowFrame(state: FollowSceneStateForTesting, statusFieldText: string, now: number, options?: FollowFrameRenderOptions): string[];
@@ -39,6 +43,8 @@ export declare function syncFollowSceneStateForTesting(state: FollowSceneStateFo
     indexedHeight?: number | null;
     nodeHeight?: number | null;
     liveActivated?: boolean;
+    authoritativeTip?: boolean;
+    settleLatest?: boolean;
 }): FollowSceneStateForTesting;
 export declare function advanceFollowSceneStateForTesting(state: FollowSceneStateForTesting, now: number): FollowSceneStateForTesting;
 export declare function renderFollowFrameForTesting(state: FollowSceneStateForTesting, statusFieldText?: string, now?: number, options?: FollowFrameRenderOptions): string[];

package/dist/bitcoind/progress/follow-scene.js

@@ -1,12 +1,13 @@
 import { loadArtTemplate, loadFollowCarTemplate } from "./assets.js";
 import { FIELD_LEFT, FIELD_WIDTH, FOLLOW_AGE_ROW, FOLLOW_APPROACH_MS, FOLLOW_CAR_HEIGHT, FOLLOW_CAR_PITCH, FOLLOW_CAR_TOP, FOLLOW_CAR_WIDTH, FOLLOW_CENTER_SLOT_X, FOLLOW_CLIP_MAX_COLUMN, FOLLOW_CLIP_MIN_COLUMN, FOLLOW_CONNECTION_SLOT_X, FOLLOW_FAST_APPROACH_MS, FOLLOW_FAST_SHIFT_MS, FOLLOW_PENDING_ENTER_MS, FOLLOW_PENDING_LABEL, FOLLOW_PENDING_OFFSCREEN_LEFT_X, FOLLOW_PENDING_SLOT_X, FOLLOW_RIGHT_SLOT_XS, FOLLOW_SHIFT_MS, FOLLOW_WINDOW_LEFT, MESSAGE_FIELD_ROW, NEUTRAL_MESSAGE_TITLE, STATUS_FIELD_ROW, } from "./constants.js";
-import { centerLine, computeCenteredLeftPadding, overlayCenteredField, replaceSegment, rightAlignLine, truncateLine, } from "./formatting.js";
+import { centerLine, computeCenteredLeftPadding, replaceSegment, rightAlignLine, truncateLine, } from "./formatting.js";
 const FOLLOW_TITLE_LEFT = computeCenteredLeftPadding(NEUTRAL_MESSAGE_TITLE, FIELD_WIDTH);
 const FOLLOW_TITLE_WIDTH = NEUTRAL_MESSAGE_TITLE.length;
 const FOLLOW_COG_LEFT = 0;
 const FOLLOW_COG_WIDTH = FOLLOW_TITLE_LEFT;
 const FOLLOW_SAT_LEFT = FOLLOW_TITLE_LEFT + FOLLOW_TITLE_WIDTH;
 const FOLLOW_SAT_WIDTH = FIELD_WIDTH - FOLLOW_SAT_LEFT;
+const FOLLOW_STATUS_VERSION_GAP = 2;
 export function createFollowSceneState(indexedHeight = null, blockTimesByHeight = {}) {
     return {
         liveActivated: false,
@@ -79,8 +80,55 @@ function renderFollowHeaderField(options) {
     }
     return field;
 }
+function renderFollowStatusField(statusFieldText, options) {
+    const leftText = options.artworkStatusLeftText === null || options.artworkStatusLeftText === undefined
+        ? ""
+        : truncateLine(options.artworkStatusLeftText, FIELD_WIDTH);
+    const rightText = options.artworkStatusRightText === null || options.artworkStatusRightText === undefined
+        ? ""
+        : truncateLine(options.artworkStatusRightText, FIELD_WIDTH);
+    const leftWidth = Math.min(FIELD_WIDTH, leftText.length);
+    const rightWidth = Math.min(FIELD_WIDTH, rightText.length);
+    if (leftWidth === 0 && rightWidth === 0) {
+        return centerLine(statusFieldText, FIELD_WIDTH);
+    }
+    let field = centerLine(statusFieldText, FIELD_WIDTH);
+    if (leftWidth > 0) {
+        field = replaceSegment(field, 0, leftWidth, leftAlignLane(leftText, leftWidth));
+        if (leftWidth < FIELD_WIDTH) {
+            field = replaceSegment(field, leftWidth, Math.min(FOLLOW_STATUS_VERSION_GAP, FIELD_WIDTH - leftWidth), "".padEnd(Math.min(FOLLOW_STATUS_VERSION_GAP, FIELD_WIDTH - leftWidth), " "));
+        }
+    }
+    if (rightWidth > 0) {
+        if (rightWidth < FIELD_WIDTH) {
+            const gapStart = Math.max(0, FIELD_WIDTH - rightWidth - FOLLOW_STATUS_VERSION_GAP);
+            const gapWidth = Math.min(FOLLOW_STATUS_VERSION_GAP, FIELD_WIDTH - rightWidth);
+            field = replaceSegment(field, gapStart, gapWidth, "".padEnd(gapWidth, " "));
+        }
+        field = replaceSegment(field, FIELD_WIDTH - rightWidth, rightWidth, rightAlignLine(rightText, rightWidth));
+    }
+    return field;
+}
 function highestTrackedFollowHeight(state) {
-    return Math.max(state.indexedHeight ?? Number.NEGATIVE_INFINITY, state.displayedCenterHeight ?? Number.NEGATIVE_INFINITY, state.animation?.height ?? Number.NEGATIVE_INFINITY, ...state.queuedHeights);
+    let highest = Math.max(state.indexedHeight ?? Number.NEGATIVE_INFINITY, state.displayedCenterHeight ?? Number.NEGATIVE_INFINITY, state.animation?.height ?? Number.NEGATIVE_INFINITY);
+    for (const height of state.queuedHeights) {
+        if (height > highest) {
+            highest = height;
+        }
+    }
+    return highest;
+}
+function resolveLatestAuthoritativeFollowHeight(indexedHeight, nodeHeight) {
+    if (indexedHeight === null) {
+        return nodeHeight;
+    }
+    if (nodeHeight === null) {
+        return indexedHeight;
+    }
+    return Math.max(indexedHeight, nodeHeight);
+}
+function resolveDisplayedFollowHeight(state) {
+    return state.displayedCenterHeight ?? state.indexedHeight;
 }
 function resetFollowSceneState(state) {
     state.displayedCenterHeight = state.indexedHeight;
@@ -90,13 +138,33 @@ function resetFollowSceneState(state) {
     state.pendingStaticX = null;
     state.animation = null;
 }
+function resyncFollowSceneToLatestHeight(state, latestHeight) {
+    state.displayedCenterHeight = latestHeight;
+    state.queuedHeights = [];
+    state.pendingLabel = null;
+    state.pendingStaticX = null;
+    state.animation = null;
+}
+function shouldResyncAuthoritativeFollowScene(options) {
+    if (options.latestHeight === null) {
+        return false;
+    }
+    if (options.settleLatest) {
+        return true;
+    }
+    const displayedHeight = resolveDisplayedFollowHeight(options.state);
+    if (displayedHeight === null) {
+        return false;
+    }
+    return options.latestHeight - displayedHeight > 1;
+}
 function enqueueFollowHeights(state, nodeHeight) {
     const startHeight = Math.max(state.indexedHeight ?? -1, highestTrackedFollowHeight(state));
     for (let height = startHeight + 1; height <= nodeHeight; height += 1) {
         state.queuedHeights.push(height);
     }
 }
-export function syncFollowSceneState(state, { indexedHeight, nodeHeight, liveActivated, }) {
+export function syncFollowSceneState(state, { indexedHeight, nodeHeight, liveActivated, authoritativeTip, settleLatest, }) {
     const wasLive = state.liveActivated;
     const nextLive = liveActivated ?? state.liveActivated;
     let shouldReset = false;
@@ -119,7 +187,17 @@ export function syncFollowSceneState(state, { indexedHeight, nodeHeight, liveAct
     if (shouldReset) {
         resetFollowSceneState(state);
     }
-    if (state.liveActivated && state.observedNodeHeight !== null) {
+    const latestAuthoritativeHeight = resolveLatestAuthoritativeFollowHeight(state.indexedHeight, state.observedNodeHeight);
+    if (state.liveActivated
+        && authoritativeTip === true
+        && shouldResyncAuthoritativeFollowScene({
+            state,
+            latestHeight: latestAuthoritativeHeight,
+            settleLatest: settleLatest === true,
+        })) {
+        resyncFollowSceneToLatestHeight(state, latestAuthoritativeHeight);
+    }
+    else if (state.liveActivated && state.observedNodeHeight !== null) {
         enqueueFollowHeights(state, state.observedNodeHeight);
     }
     if (!wasLive && state.liveActivated && state.displayedCenterHeight === null) {
@@ -363,7 +441,18 @@ export function renderFollowFrame(state, statusFieldText, now, options = {}) {
     if (headerRow !== undefined) {
         frame[MESSAGE_FIELD_ROW] = replaceSegment(headerRow, FIELD_LEFT, FIELD_WIDTH, renderFollowHeaderField(options));
     }
-    overlayCenteredField(frame, STATUS_FIELD_ROW, statusFieldText);
+    if (statusFieldText.length > 0
+        || (options.artworkStatusLeftText !== null
+            && options.artworkStatusLeftText !== undefined
+            && options.artworkStatusLeftText.length > 0)
+        || (options.artworkStatusRightText !== null
+            && options.artworkStatusRightText !== undefined
+            && options.artworkStatusRightText.length > 0)) {
+        const statusRow = frame[STATUS_FIELD_ROW];
+        if (statusRow !== undefined) {
+            frame[STATUS_FIELD_ROW] = replaceSegment(statusRow, FIELD_LEFT, FIELD_WIDTH, renderFollowStatusField(statusFieldText, options));
+        }
+    }
     return frame;
 }
 export function createFollowSceneStateForTesting(indexedHeight = null, blockTimesByHeight = {}) {

package/dist/bitcoind/progress/tty-renderer.d.ts

@@ -10,6 +10,8 @@ interface RenderStream {
 export interface FollowSceneRenderOptions {
     artworkCogText?: string | null;
     artworkSatText?: string | null;
+    artworkStatusLeftText?: string | null;
+    artworkStatusRightText?: string | null;
     extraLines?: string[];
 }
 export declare class TtyProgressRenderer {

package/dist/bitcoind/progress/tty-renderer.js

@@ -94,6 +94,8 @@ export class TtyProgressRenderer {
             ? [...renderFollowFrame(followScene, statusFieldText, now, {
                     artworkCogText: renderOptions.artworkCogText ?? null,
                     artworkSatText: renderOptions.artworkSatText ?? null,
+                    artworkStatusLeftText: renderOptions.artworkStatusLeftText ?? null,
+                    artworkStatusRightText: renderOptions.artworkStatusRightText ?? null,
                 }), "", progressLine, "", ...extraLines]
             : [truncateLine(NEUTRAL_MESSAGE_TITLE, width), progressLine, "", ...extraLines];
         const frame = lines.join("\n");

package/dist/bitcoind/testing.d.ts

@@ -1,6 +1,5 @@
 export { openManagedBitcoindClientInternal } from "./client.js";
 export { DefaultManagedBitcoindClient } from "./client/managed-client.js";
-export { pauseIndexerDaemonForForegroundClientForTesting } from "./client/factory.js";
 export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, stopIndexerDaemonService, shutdownIndexerDaemonForTesting, } from "./indexer-daemon.js";
 export { normalizeRpcBlock } from "./normalize.js";
 export { BitcoinRpcClient } from "./rpc.js";

package/dist/bitcoind/testing.js

@@ -1,6 +1,5 @@
 export { openManagedBitcoindClientInternal } from "./client.js";
 export { DefaultManagedBitcoindClient } from "./client/managed-client.js";
-export { pauseIndexerDaemonForForegroundClientForTesting } from "./client/factory.js";
 export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, stopIndexerDaemonService, shutdownIndexerDaemonForTesting, } from "./indexer-daemon.js";
 export { normalizeRpcBlock } from "./normalize.js";
 export { BitcoinRpcClient } from "./rpc.js";

package/dist/bitcoind/types.d.ts

@@ -154,7 +154,6 @@ export interface ManagedGetblockArchiveRestartRequest {
 }
 export interface ManagedBitcoindOptions extends ClientOptions {
     dataDir?: string;
-    databasePath?: string;
     rpcPort?: number;
     zmqPort?: number;
     p2pPort?: number;
@@ -173,7 +172,6 @@ export interface ManagedBitcoindClient extends Client {
     syncToTip(): Promise<SyncResult>;
     startFollowingTip(): Promise<void>;
     getNodeStatus(): Promise<ManagedBitcoindStatus>;
-    detachToBackgroundFollow(): Promise<void>;
     close(): Promise<void>;
 }
 export interface InternalManagedBitcoindOptions extends ManagedBitcoindOptions {
@@ -235,6 +233,11 @@ export interface ManagedIndexerDaemonStatus {
     lastAppliedAtUnixMs: number | null;
     activeSnapshotCount: number;
     lastError: string | null;
+    backgroundFollowActive?: boolean;
+    bootstrapPhase?: BootstrapPhase | null;
+    bootstrapProgress?: BootstrapProgress | null;
+    cogcoinSyncHeight?: number | null;
+    cogcoinSyncTargetHeight?: number | null;
 }
 export interface ManagedIndexerDaemonObservedStatus extends Omit<ManagedIndexerDaemonStatus, "serviceApiVersion" | "schemaVersion"> {
     serviceApiVersion: string;