@cogcoin/client 1.0.1 → 1.1.0

package/dist/bitcoind/indexer-daemon.js

@@ -3,11 +3,16 @@ 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 } 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 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"));
@@ -57,7 +62,7 @@ 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 {
@@ -80,7 +85,8 @@ export async function stopIndexerDaemonServiceWithLockHeld(options) {
         walletRootId,
     };
 }
-function createIndexerDaemonClient(socketPath) {
+function createIndexerDaemonClient(socketPath, closeOptions = null) {
+    let closed = false;
     async function sendRequest(request) {
         return new Promise((resolve, reject) => {
             const socket = net.createConnection(socketPath);
@@ -94,7 +100,9 @@ function createIndexerDaemonClient(socketPath) {
                 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`);
             });
@@ -168,12 +176,6 @@ function createIndexerDaemonClient(socketPath) {
                 token,
             });
         },
-        async pauseBackgroundFollow() {
-            await sendRequest({
-                id: randomUUID(),
-                method: "PauseBackgroundFollow",
-            });
-        },
         async resumeBackgroundFollow() {
             await sendRequest({
                 id: randomUUID(),
@@ -181,7 +183,18 @@ function createIndexerDaemonClient(socketPath) {
             });
         },
         async close() {
-            return;
+            if (closed) {
+                return;
+            }
+            closed = true;
+            if (closeOptions === null || closeOptions.serviceLifetime !== "ephemeral" || closeOptions.ownership === "attached") {
+                return;
+            }
+            await stopIndexerDaemonService({
+                dataDir: closeOptions.dataDir,
+                walletRootId: closeOptions.walletRootId,
+                shutdownTimeoutMs: closeOptions.shutdownTimeoutMs,
+            });
         },
     };
 }
@@ -259,8 +272,20 @@ 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;
+    }
+    const comparison = compareSemver(status.binaryVersion, expectedBinaryVersion);
+    return comparison !== null && comparison < 0;
+}
 async function probeIndexerDaemonAtSocket(socketPath, expectedWalletRootId) {
     const client = createIndexerDaemonClient(socketPath);
     try {
@@ -308,7 +333,8 @@ async function waitForIndexerDaemon(dataDir, walletRootId, timeoutMs) {
     while (Date.now() < deadline) {
         const probe = await probeIndexerDaemonAtSocket(paths.indexerDaemonSocketPath, walletRootId);
         if (probe.compatibility === "compatible" && probe.client !== null) {
-            return probe.client;
+            await probe.client.close().catch(() => undefined);
+            return;
         }
         if (probe.compatibility !== "unreachable") {
             throw new Error(probe.error ?? "indexer_daemon_protocol_error");
@@ -355,14 +381,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 {
@@ -375,24 +471,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 child = spawn(process.execPath, [
-                daemonEntryPath,
-                `--data-dir=${options.dataDir}`,
-                `--database-path=${options.databasePath}`,
-                `--wallet-root-id=${walletRootId}`,
-            ], {
-                detached: true,
-                stdio: "ignore",
-            });
-            child.unref();
-            return await waitForIndexerDaemon(options.dataDir, walletRootId, startupTimeoutMs);
+            const daemon = await startDaemon();
+            try {
+                return await requestBackgroundFollow(daemon);
+            }
+            catch (error) {
+                await daemon.close().catch(() => undefined);
+                throw new Error(INDEXER_DAEMON_BACKGROUND_FOLLOW_RECOVERY_FAILED, { cause: error });
+            }
         }
         finally {
             await lock.release();
@@ -400,7 +515,8 @@ export async function attachOrStartIndexerDaemon(options) {
     }
     catch (error) {
         if (error instanceof FileLockBusyError) {
-            return waitForIndexerDaemon(options.dataDir, walletRootId, startupTimeoutMs);
+            await waitForIndexerDaemon(options.dataDir, walletRootId, startupTimeoutMs);
+            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,89 @@
+import { readFile } from "node:fs/promises";
+import { loadBundledGenesisParameters } from "@cogcoin/indexer";
+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 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: options.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/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,9 +80,50 @@ 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);
 }
+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;
     state.blockTimesByHeight = {};
@@ -90,13 +132,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 +181,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 +435,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/retryable-rpc.js

@@ -19,6 +19,9 @@ export function isRetryableManagedRpcError(error) {
     if (message === "bitcoind_rpc_timeout") {
         return true;
     }
+    if (/^bitcoind_rpc_[^_]+_-28(?:_|$)/.test(message)) {
+        return true;
+    }
     if (message.startsWith("The managed Bitcoin RPC request to ")) {
         return message.includes(" failed");
     }

package/dist/bitcoind/service.d.ts

@@ -24,6 +24,7 @@ type ManagedBitcoindServiceOptions = Pick<InternalManagedBitcoindOptions, "dataD
     getblockArchivePath?: string | null;
     getblockArchiveEndHeight?: number | null;
     getblockArchiveSha256?: string | null;
+    serviceLifetime?: "persistent" | "ephemeral";
 };
 export type ManagedBitcoindServiceCompatibility = "compatible" | "service-version-mismatch" | "wallet-root-mismatch" | "runtime-mismatch" | "unreachable" | "protocol-error";
 export interface ManagedBitcoindServiceProbeResult {

package/dist/bitcoind/service.js

@@ -681,9 +681,10 @@ async function refreshManagedBitcoindStatus(status, paths, options) {
         return nextStatus;
     }
 }
-function createNodeHandle(status, paths, options) {
+function createNodeHandle(status, paths, options, ownership) {
     let currentStatus = status;
     const rpc = createRpcClient(currentStatus.rpc);
+    let stopped = false;
     return {
         rpc: currentStatus.rpc,
         zmq: currentStatus.zmq,
@@ -706,9 +707,20 @@ function createNodeHandle(status, paths, options) {
             return currentStatus;
         },
         async stop() {
-            // Public managed clients detach from the persistent service instead of
-            // shutting it down on ordinary command exit.
-            return;
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            if (options.serviceLifetime !== "ephemeral" || ownership === "attached") {
+                // Public managed clients detach from persistent services, and ephemeral
+                // attach callers must not shut down services they did not launch.
+                return;
+            }
+            await stopManagedBitcoindService({
+                dataDir: currentStatus.dataDir,
+                walletRootId: currentStatus.walletRootId,
+                shutdownTimeoutMs: options.shutdownTimeoutMs,
+            });
         },
     };
 }
@@ -720,7 +732,7 @@ async function tryAttachExistingManagedBitcoindService(options) {
         return null;
     }
     const refreshed = await refreshManagedBitcoindStatus(probe.status, paths, options);
-    return createNodeHandle(refreshed, paths, options);
+    return createNodeHandle(refreshed, paths, options, "attached");
 }
 async function waitForManagedBitcoindService(options, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
@@ -765,6 +777,7 @@ export async function attachOrStartManagedBitcoindService(options) {
     const resolvedOptions = {
         ...options,
         dataDir: options.dataDir,
+        serviceLifetime: options.serviceLifetime ?? "persistent",
         walletRootId: options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID,
     };
     const startupTimeoutMs = resolvedOptions.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
@@ -815,11 +828,20 @@ export async function attachOrStartManagedBitcoindService(options) {
                         port: runtimeConfig.zmqPort,
                         pollIntervalMs: startOptions.pollIntervalMs ?? 15_000,
                     };
+                    const spawnOptions = startOptions.serviceLifetime === "ephemeral"
+                        ? {
+                            stdio: "ignore",
+                        }
+                        : {
+                            detached: true,
+                            stdio: "ignore",
+                        };
                     const child = spawn(bitcoindPath, buildManagedServiceArgs(startOptions, runtimeConfig), {
-                        detached: true,
-                        stdio: "ignore",
+                        ...spawnOptions,
                     });
-                    child.unref();
+                    if (startOptions.serviceLifetime !== "ephemeral") {
+                        child.unref();
+                    }
                     const rpc = createRpcClient(rpcConfig);
                     try {
                         await waitForRpcReady(rpc, rpcConfig.cookieFile, startOptions.chain, startupTimeoutMs);
@@ -876,7 +898,7 @@ export async function attachOrStartManagedBitcoindService(options) {
                     });
                 }
                 await writeBitcoindStatus(paths, status);
-                return createNodeHandle(status, paths, resolvedOptions);
+                return createNodeHandle(status, paths, resolvedOptions, "started");
             }
             finally {
                 await lock.release();

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";