@cogcoin/client 0.5.6 → 0.5.7

package/dist/bitcoind/client/factory.js

@@ -1,12 +1,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 { AssumeUtxoBootstrapController, DEFAULT_SNAPSHOT_METADATA, prepareLatestGetblockArchiveForTesting, resolveBootstrapPathsForTesting, } from "../bootstrap.js";
 import { attachOrStartIndexerDaemon } 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 { attachOrStartManagedBitcoindService, probeManagedBitcoindService, stopManagedBitcoindService, } from "../service.js";
 import { DefaultManagedBitcoindClient } from "./managed-client.js";
 const DEFAULT_SYNC_DEBOUNCE_MS = 250;
 async function createManagedBitcoindClient(options) {
@@ -17,40 +17,94 @@ async function createManagedBitcoindClient(options) {
         genesisParameters,
     });
     const dataDir = options.dataDir ?? resolveDefaultBitcoindDataDirForTesting();
-    const node = await attachOrStartManagedBitcoindService({
-        ...options,
-        dataDir,
-    });
-    const rpc = createRpcClient(node.rpc);
     const progress = new ManagedProgressController({
         onProgress: options.onProgress,
         progressOutput: options.progressOutput,
-        quoteStatePath: resolveBootstrapPathsForTesting(node.dataDir, DEFAULT_SNAPSHOT_METADATA).quoteStatePath,
-        snapshot: DEFAULT_SNAPSHOT_METADATA,
-    });
-    const bootstrap = new AssumeUtxoBootstrapController({
-        rpc,
-        dataDir: node.dataDir,
-        progress,
+        quoteStatePath: resolveBootstrapPathsForTesting(dataDir, DEFAULT_SNAPSHOT_METADATA).quoteStatePath,
         snapshot: DEFAULT_SNAPSHOT_METADATA,
     });
-    const client = await openClient({
-        store: options.store,
-        genesisParameters,
-        snapshotInterval: options.snapshotInterval,
-    });
-    const indexerDaemon = options.databasePath
-        ? await attachOrStartIndexerDaemon({
+    let progressStarted = false;
+    try {
+        await progress.start();
+        progressStarted = true;
+        let getblockArchive = options.chain === "main"
+            ? await prepareLatestGetblockArchiveForTesting({
+                dataDir,
+                progress,
+                fetchImpl: options.fetchImpl,
+            })
+            : null;
+        if (options.chain === "main" && getblockArchive !== null) {
+            const existingProbe = await probeManagedBitcoindService({
+                ...options,
+                dataDir,
+            });
+            if (existingProbe.compatibility === "compatible" && existingProbe.status !== null) {
+                const currentArchiveEndHeight = existingProbe.status.getblockArchiveEndHeight ?? null;
+                const currentArchiveSha256 = existingProbe.status.getblockArchiveSha256 ?? null;
+                const nextArchiveEndHeight = getblockArchive.manifest.endHeight;
+                const nextArchiveSha256 = getblockArchive.manifest.artifactSha256;
+                const needsRestart = currentArchiveEndHeight !== nextArchiveEndHeight
+                    || currentArchiveSha256 !== nextArchiveSha256;
+                if (needsRestart) {
+                    const restartApproved = options.confirmGetblockArchiveRestart === undefined
+                        ? false
+                        : await options.confirmGetblockArchiveRestart({
+                            currentArchiveEndHeight,
+                            nextArchiveEndHeight,
+                        });
+                    if (restartApproved) {
+                        await stopManagedBitcoindService({
+                            dataDir,
+                            walletRootId: options.walletRootId,
+                            shutdownTimeoutMs: options.shutdownTimeoutMs,
+                        });
+                    }
+                    else {
+                        getblockArchive = null;
+                    }
+                }
+            }
+        }
+        const node = await attachOrStartManagedBitcoindService({
+            ...options,
             dataDir,
-            databasePath: options.databasePath,
-            walletRootId: options.walletRootId,
-            startupTimeoutMs: options.startupTimeoutMs,
-        })
-        : 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.
-    return new DefaultManagedBitcoindClient(client, options.store, node, rpc, progress, bootstrap, indexerDaemon, options.startHeight, options.syncDebounceMs ?? DEFAULT_SYNC_DEBOUNCE_MS);
+            getblockArchivePath: getblockArchive?.artifactPath ?? null,
+            getblockArchiveEndHeight: getblockArchive?.manifest.endHeight ?? null,
+            getblockArchiveSha256: getblockArchive?.manifest.artifactSha256 ?? null,
+        });
+        const rpc = createRpcClient(node.rpc);
+        const bootstrap = new AssumeUtxoBootstrapController({
+            rpc,
+            dataDir: node.dataDir,
+            progress,
+            snapshot: DEFAULT_SNAPSHOT_METADATA,
+        });
+        const client = await openClient({
+            store: options.store,
+            genesisParameters,
+            snapshotInterval: options.snapshotInterval,
+        });
+        const indexerDaemon = options.databasePath
+            ? await attachOrStartIndexerDaemon({
+                dataDir,
+                databasePath: options.databasePath,
+                walletRootId: options.walletRootId,
+                startupTimeoutMs: options.startupTimeoutMs,
+            })
+            : null;
+        await indexerDaemon?.pauseBackgroundFollow();
+        // 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.
+        return new DefaultManagedBitcoindClient(client, options.store, node, rpc, progress, bootstrap, indexerDaemon, options.startHeight, options.syncDebounceMs ?? DEFAULT_SYNC_DEBOUNCE_MS);
+    }
+    catch (error) {
+        if (progressStarted) {
+            await progress.close().catch(() => undefined);
+        }
+        throw error;
+    }
 }
 export async function openManagedBitcoindClient(options) {
     const genesisParameters = options.genesisParameters ?? await loadBundledGenesisParameters();

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

@@ -176,8 +176,9 @@ export class DefaultManagedBitcoindClient {
         await this.#syncPromise.catch(() => undefined);
         await this.#progress.close();
         await this.#node.stop();
-        await this.#indexerDaemon?.close();
         await this.#client.close();
+        await this.#indexerDaemon?.resumeBackgroundFollow().catch(() => undefined);
+        await this.#indexerDaemon?.close();
     }
     async playSyncCompletionScene() {
         this.#assertOpen();

package/dist/bitcoind/client/sync-engine.js

@@ -1,3 +1,4 @@
+import { waitForGetblockArchiveImport } from "../bootstrap.js";
 import { formatManagedSyncErrorMessage } from "../errors.js";
 import { normalizeRpcBlock } from "../normalize.js";
 import { MANAGED_RPC_RETRY_MESSAGE, consumeManagedRpcRetryDelayMs, createManagedRpcRetryState, describeManagedRpcRetryError, isRetryableManagedRpcError, resetManagedRpcRetryState, } from "../retryable-rpc.js";
@@ -151,6 +152,12 @@ export async function syncToTip(dependencies) {
             signal: dependencies.abortSignal,
             retryState,
         }));
+        if (dependencies.node.expectedChain === "main"
+            && dependencies.node.getblockArchiveEndHeight !== null) {
+            await waitForGetblockArchiveImport({
+                getBlockchainInfo: () => runRpc(() => dependencies.rpc.getBlockchainInfo()),
+            }, dependencies.progress, dependencies.node.getblockArchiveEndHeight, dependencies.abortSignal);
+        }
         const startTip = await dependencies.client.getTip();
         const aggregate = {
             appliedBlocks: 0,

package/dist/bitcoind/errors.js

@@ -5,6 +5,24 @@ function appendNextStep(message, nextStep) {
     return `${message} Next: ${nextStep}`;
 }
 export function formatManagedSyncErrorMessage(message) {
+    if (message.startsWith("managed_getblock_archive_manifest_http_")) {
+        return appendNextStep(`Getblock archive manifest request failed (${message.replace("managed_getblock_archive_manifest_http_", "HTTP ")}).`, "Wait a moment, confirm the snapshot host is reachable, then rerun sync.");
+    }
+    if (message.startsWith("managed_getblock_archive_http_")) {
+        return appendNextStep(`Getblock archive request failed (${message.replace("managed_getblock_archive_http_", "HTTP ")}).`, "Wait a moment, confirm the snapshot host is reachable, then rerun sync.");
+    }
+    if (message === "managed_getblock_archive_response_body_missing") {
+        return appendNextStep("Getblock archive server returned an empty response body.", "Wait a moment, confirm the snapshot host is reachable, then rerun sync.");
+    }
+    if (message === "managed_getblock_archive_resume_requires_partial_content") {
+        return appendNextStep("Getblock archive server ignored the resume request for a partial download.", "Wait a moment and rerun sync. If this keeps happening, confirm the snapshot host supports HTTP range requests.");
+    }
+    if (message.startsWith("managed_getblock_archive_chunk_sha256_mismatch_")) {
+        return appendNextStep("A downloaded getblock archive chunk was corrupted and was rolled back to the last verified checkpoint.", "Wait a moment and rerun sync. If this keeps happening, check local disk health and the stability of the archive download.");
+    }
+    if (message === "managed_getblock_archive_sha256_mismatch" || message === "managed_getblock_archive_truncated") {
+        return appendNextStep("The downloaded getblock archive did not match the published manifest.", "Rerun sync so the archive can be downloaded again. If this keeps happening, check local disk health and the snapshot host.");
+    }
     if (message === "bitcoind_no_peers_for_header_sync_check_internet_or_firewall") {
         return appendNextStep("No Bitcoin peers were available for header sync.", "Check your internet access and firewall rules for outbound Bitcoin connections, then rerun sync.");
     }

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

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import net from "node:net";
 import { access, constants, mkdir, readFile, rm } from "node:fs/promises";
 import { serializeIndexerState } from "@cogcoin/indexer";
+import { openManagedBitcoindClientInternal } from "./client.js";
 import { openClient } from "../client.js";
 import { openSqliteStore } from "../sqlite/index.js";
 import { writeRuntimeStatusFile } from "../wallet/fs/status-file.js";
@@ -29,6 +30,9 @@ async function readJsonFile(filePath) {
         throw error;
     }
 }
+async function readManagedBitcoindStatus(paths) {
+    return readJsonFile(paths.bitcoindStatusPath);
+}
 async function readPackageVersionFromDisk() {
     try {
         const raw = await readFile(new URL("../../package.json", import.meta.url), "utf8");
@@ -168,6 +172,9 @@ async function main() {
     let lastAppliedAtUnixMs = null;
     let lastError = null;
     let hasSuccessfulCoreTipRefresh = false;
+    let backgroundStore = null;
+    let backgroundClient = null;
+    let backgroundResumePromise = null;
     await mkdir(paths.indexerServiceRoot, { recursive: true });
     await rm(paths.indexerDaemonSocketPath, { force: true }).catch(() => undefined);
     const observeAppliedTip = (appliedTip, now) => {
@@ -264,6 +271,58 @@ async function main() {
         lastError = leaseState.lastError;
         return writeStatus();
     };
+    const pauseBackgroundFollow = async () => {
+        const pendingResume = backgroundResumePromise;
+        backgroundResumePromise = null;
+        await pendingResume?.catch(() => undefined);
+        const client = backgroundClient;
+        const store = backgroundStore;
+        backgroundClient = null;
+        backgroundStore = null;
+        await client?.close().catch(() => undefined);
+        await store?.close().catch(() => undefined);
+    };
+    const resumeBackgroundFollow = async () => {
+        if (backgroundClient !== null) {
+            return;
+        }
+        if (backgroundResumePromise !== null) {
+            return backgroundResumePromise;
+        }
+        backgroundResumePromise = (async () => {
+            const bitcoindStatus = await readManagedBitcoindStatus(paths);
+            const store = await openSqliteStore({ filename: databasePath });
+            try {
+                const client = await openManagedBitcoindClientInternal({
+                    store,
+                    dataDir,
+                    chain: bitcoindStatus?.chain ?? "main",
+                    startHeight: bitcoindStatus?.startHeight ?? 0,
+                    walletRootId,
+                    progressOutput: "none",
+                });
+                try {
+                    await client.startFollowingTip();
+                    backgroundStore = store;
+                    backgroundClient = client;
+                }
+                catch (error) {
+                    await client.close().catch(() => undefined);
+                    throw error;
+                }
+            }
+            catch (error) {
+                await store.close().catch(() => undefined);
+                throw error;
+            }
+        })();
+        try {
+            await backgroundResumePromise;
+        }
+        finally {
+            backgroundResumePromise = null;
+        }
+    };
     const heartbeat = setInterval(() => {
         void refreshStatus().catch(() => undefined);
         const now = Date.now();
@@ -427,6 +486,24 @@ 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();
+                            writeResponse({
+                                id: request.id,
+                                ok: true,
+                                result: null,
+                            });
+                            return;
+                        }
                         throw new Error(`indexer_daemon_unknown_method_${request.method}`);
                     }
                     catch (error) {
@@ -443,6 +520,7 @@ async function main() {
     });
     const shutdown = async () => {
         clearInterval(heartbeat);
+        await pauseBackgroundFollow().catch(() => undefined);
         state = "stopping";
         heartbeatAtUnixMs = Date.now();
         updatedAtUnixMs = heartbeatAtUnixMs;

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

@@ -2,7 +2,7 @@ import { type ManagedIndexerDaemonObservedStatus, type ManagedIndexerDaemonStatu
 import { resolveManagedServicePaths } from "./service-paths.js";
 interface DaemonRequest {
     id: string;
-    method: "GetStatus" | "OpenSnapshot" | "ReadSnapshot" | "CloseSnapshot";
+    method: "GetStatus" | "OpenSnapshot" | "ReadSnapshot" | "CloseSnapshot" | "PauseBackgroundFollow" | "ResumeBackgroundFollow";
     token?: string;
 }
 interface DaemonResponse {
@@ -65,6 +65,8 @@ 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>;
 }
 export type IndexerDaemonCompatibility = "compatible" | "service-version-mismatch" | "wallet-root-mismatch" | "schema-mismatch" | "unreachable" | "protocol-error";

package/dist/bitcoind/indexer-daemon.js

@@ -168,6 +168,18 @@ function createIndexerDaemonClient(socketPath) {
                 token,
             });
         },
+        async pauseBackgroundFollow() {
+            await sendRequest({
+                id: randomUUID(),
+                method: "PauseBackgroundFollow",
+            });
+        },
+        async resumeBackgroundFollow() {
+            await sendRequest({
+                id: randomUUID(),
+                method: "ResumeBackgroundFollow",
+            });
+        },
         async close() {
             return;
         },
@@ -177,9 +189,6 @@ function validateIndexerRuntimeIdentity(identity, expectedWalletRootId) {
     if (identity.serviceApiVersion !== INDEXER_DAEMON_SERVICE_API_VERSION) {
         throw new Error("indexer_daemon_service_version_mismatch");
     }
-    if (identity.walletRootId !== expectedWalletRootId) {
-        throw new Error("indexer_daemon_wallet_root_mismatch");
-    }
     if (identity.schemaVersion !== INDEXER_DAEMON_SCHEMA_VERSION || identity.state === "schema-mismatch") {
         throw new Error("indexer_daemon_schema_mismatch");
     }
@@ -271,9 +280,7 @@ async function probeIndexerDaemonAtSocket(socketPath, expectedWalletRootId) {
                 compatibility: error instanceof Error
                     ? error.message === "indexer_daemon_service_version_mismatch"
                         ? "service-version-mismatch"
-                        : error.message === "indexer_daemon_wallet_root_mismatch"
-                            ? "wallet-root-mismatch"
-                            : "schema-mismatch"
+                        : "schema-mismatch"
                     : "protocol-error",
                 status,
                 client: null,

package/dist/bitcoind/node.js

@@ -182,6 +182,8 @@ export async function launchManagedBitcoindNode(options) {
         expectedChain: resolvedOptions.chain,
         startHeight: resolvedOptions.startHeight,
         dataDir: resolvedOptions.dataDir,
+        getblockArchiveEndHeight: null,
+        getblockArchiveSha256: null,
         async validate() {
             await validateNodeConfigForTesting(rpcClient, resolvedOptions.chain, zmqEndpoint);
         },

package/dist/bitcoind/progress/constants.d.ts

@@ -1,4 +1,5 @@
 export declare const PROGRESS_TICK_MS = 250;
+export declare const HEADLESS_PROGRESS_TICK_MS = 1000;
 export declare const PREPARING_SYNC_LINE = "Preparing managed Cogcoin sync...";
 export declare const ART_WIDTH = 80;
 export declare const ART_HEIGHT = 13;

package/dist/bitcoind/progress/constants.js

@@ -1,4 +1,5 @@
 export const PROGRESS_TICK_MS = 250;
+export const HEADLESS_PROGRESS_TICK_MS = 1_000;
 export const PREPARING_SYNC_LINE = "Preparing managed Cogcoin sync...";
 export const ART_WIDTH = 80;
 export const ART_HEIGHT = 13;

package/dist/bitcoind/progress/controller.d.ts

@@ -1,9 +1,31 @@
+import type { QuoteDisplayPhase } from "../quotes.js";
 import type { BootstrapPhase, BootstrapProgress, ManagedBitcoindProgressEvent, ProgressOutputMode, SnapshotMetadata, WritingQuote } from "../types.js";
+import { type FollowSceneStateForTesting } from "./follow-scene.js";
+import { type RenderClock, type TtyRenderStream } from "./render-policy.js";
+interface QuoteRotatorLike {
+    current(now?: number): Promise<{
+        displayPhase: QuoteDisplayPhase;
+        currentQuote: WritingQuote | null;
+        displayStartedAt: number;
+    }>;
+}
+interface ProgressRendererLike {
+    render(displayPhase: QuoteDisplayPhase, quote: WritingQuote | null, progress: BootstrapProgress, cogcoinSyncHeight: number | null, cogcoinSyncTargetHeight: number | null, introElapsedMs?: number, statusFieldText?: string): void;
+    renderTrainScene(kind: "intro" | "completion", progress: BootstrapProgress, cogcoinSyncHeight: number | null, cogcoinSyncTargetHeight: number | null, elapsedMs: number, statusFieldText?: string): void;
+    renderFollowScene(progress: BootstrapProgress, cogcoinSyncHeight: number | null, cogcoinSyncTargetHeight: number | null, followScene: FollowSceneStateForTesting, statusFieldText?: string): void;
+    close(): void;
+}
 interface ProgressControllerOptions {
     onProgress?: (event: ManagedBitcoindProgressEvent) => void;
     progressOutput?: ProgressOutputMode;
     quoteStatePath: string;
     snapshot: SnapshotMetadata;
+    quoteRotator?: QuoteRotatorLike;
+    rendererFactory?: (stream: TtyRenderStream) => ProgressRendererLike;
+    stream?: TtyRenderStream;
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    clock?: RenderClock;
 }
 export declare class ManagedProgressController {
     #private;

package/dist/bitcoind/progress/controller.js

@@ -1,12 +1,17 @@
 import { WritingQuoteRotator as QuoteRotator } from "../quotes.js";
-import { INTRO_TOTAL_MS, PROGRESS_TICK_MS } from "./constants.js";
+import { INTRO_TOTAL_MS } from "./constants.js";
 import { advanceFollowSceneState, createFollowSceneState, replaceFollowBlockTimes, setFollowBlockTime, syncFollowSceneState, } from "./follow-scene.js";
 import { createBootstrapProgress, createDefaultMessage, resolveStatusFieldText, } from "./formatting.js";
+import { DEFAULT_RENDER_CLOCK, resolveTtyRenderPolicy, TtyRenderThrottle, } from "./render-policy.js";
 import { TtyProgressRenderer } from "./tty-renderer.js";
 export class ManagedProgressController {
     #options;
     #snapshot;
     #outputMode;
+    #clock;
+    #renderStream;
+    #renderThrottle;
+    #renderIntervalMs;
     #quoteRotator = null;
     #renderer = null;
     #ticker = null;
@@ -24,26 +29,47 @@ export class ManagedProgressController {
         this.#snapshot = options.snapshot;
         this.#outputMode = options.progressOutput ?? "auto";
         this.#progress = createBootstrapProgress("paused", options.snapshot);
+        this.#clock = options.clock ?? DEFAULT_RENDER_CLOCK;
+        this.#renderStream = options.stream ?? process.stderr;
+        const renderPolicy = resolveTtyRenderPolicy(this.#outputMode, this.#renderStream, {
+            platform: options.platform,
+            env: options.env,
+        });
+        this.#renderIntervalMs = renderPolicy.repaintIntervalMs;
+        this.#renderThrottle = new TtyRenderThrottle({
+            clock: this.#clock,
+            intervalMs: this.#renderIntervalMs,
+            onRender: () => {
+                this.#renderToTty();
+            },
+            throttled: renderPolicy.linuxHeadlessThrottle,
+        });
     }
     async start() {
         if (this.#started) {
             return;
         }
         this.#started = true;
-        this.#quoteRotator = await QuoteRotator.create(this.#options.quoteStatePath);
-        if (this.#shouldRenderToTty()) {
-            this.#renderer = new TtyProgressRenderer();
+        this.#quoteRotator = this.#options.quoteRotator
+            ?? await QuoteRotator.create(this.#options.quoteStatePath);
+        if (resolveTtyRenderPolicy(this.#outputMode, this.#renderStream, {
+            platform: this.#options.platform,
+            env: this.#options.env,
+        }).enabled) {
+            this.#renderer = this.#options.rendererFactory?.(this.#renderStream)
+                ?? new TtyProgressRenderer(this.#renderStream);
         }
         await this.#refresh();
-        this.#ticker = setInterval(() => {
+        this.#ticker = this.#clock.setInterval(() => {
             void this.#refresh();
-        }, PROGRESS_TICK_MS);
+        }, this.#renderIntervalMs);
     }
     async close() {
         if (this.#ticker !== null) {
-            clearInterval(this.#ticker);
+            this.#clock.clearInterval(this.#ticker);
             this.#ticker = null;
         }
+        this.#renderThrottle.flush();
         this.#renderer?.close();
         this.#renderer = null;
         this.#started = false;
@@ -72,19 +98,20 @@ export class ManagedProgressController {
         if (!this.#started || this.#renderer === null) {
             return;
         }
+        this.#renderThrottle.flush();
         if (this.#ticker !== null) {
-            clearInterval(this.#ticker);
+            this.#clock.clearInterval(this.#ticker);
             this.#ticker = null;
         }
-        const startedAt = Date.now();
+        const startedAt = this.#clock.now();
         while (true) {
-            const elapsedMs = Math.min(INTRO_TOTAL_MS, Date.now() - startedAt);
+            const elapsedMs = Math.min(INTRO_TOTAL_MS, this.#clock.now() - startedAt);
             this.#renderer.renderTrainScene("completion", this.#progress, this.#cogcoinSyncHeight, this.#cogcoinSyncTargetHeight, elapsedMs);
             if (elapsedMs >= INTRO_TOTAL_MS) {
                 break;
             }
             await new Promise((resolve) => {
-                setTimeout(resolve, PROGRESS_TICK_MS);
+                this.#clock.setTimeout(resolve, this.#renderIntervalMs);
             });
         }
     }
@@ -143,7 +170,7 @@ export class ManagedProgressController {
         if (!this.#started || this.#quoteRotator === null) {
             return;
         }
-        const now = Date.now();
+        const now = this.#clock.now();
         if (this.#followVisualMode) {
             advanceFollowSceneState(this.#followScene, now);
             this.#currentQuote = null;
@@ -170,20 +197,18 @@ export class ManagedProgressController {
         catch {
             // User progress callbacks should never break managed sync.
         }
+        this.#renderThrottle.request();
+    }
+    #renderToTty() {
+        if (!this.#started || this.#renderer === null) {
+            return;
+        }
+        const now = this.#clock.now();
         const statusFieldText = resolveStatusFieldText(this.#progress, this.#snapshot.height, now);
         if (this.#followVisualMode) {
-            this.#renderer?.renderFollowScene(this.#progress, this.#cogcoinSyncHeight, this.#cogcoinSyncTargetHeight, this.#followScene, statusFieldText);
+            this.#renderer.renderFollowScene(this.#progress, this.#cogcoinSyncHeight, this.#cogcoinSyncTargetHeight, this.#followScene, statusFieldText);
             return;
         }
-        this.#renderer?.render(this.#currentDisplayPhase, this.#currentQuote, this.#progress, this.#cogcoinSyncHeight, this.#cogcoinSyncTargetHeight, Math.max(0, now - this.#currentDisplayStartedAt), statusFieldText);
-    }
-    #shouldRenderToTty() {
-        if (this.#outputMode === "none") {
-            return false;
-        }
-        if (this.#outputMode === "tty") {
-            return true;
-        }
-        return process.stderr.isTTY === true;
+        this.#renderer.render(this.#currentDisplayPhase, this.#currentQuote, this.#progress, this.#cogcoinSyncHeight, this.#cogcoinSyncTargetHeight, Math.max(0, now - this.#currentDisplayStartedAt), statusFieldText);
     }
 }

package/dist/bitcoind/progress/formatting.js

@@ -1,6 +1,10 @@
 import { FIELD_LEFT, FIELD_WIDTH, PREPARING_SYNC_LINE, PROGRESS_TICK_MS, SCROLL_WINDOW_LEFT, SCROLL_WINDOW_WIDTH, STATUS_ELLIPSIS_TICK_MS, STATUS_ELLIPSIS_WIDTH, } from "./constants.js";
 export function createDefaultMessage(phase) {
     switch (phase) {
+        case "getblock_archive_download":
+            return "Downloading getblock archive.";
+        case "getblock_archive_import":
+            return "Bitcoin Core is importing getblock archive blocks.";
         case "snapshot_download":
             return "Downloading UTXO snapshot.";
         case "wait_headers_for_snapshot":
@@ -121,6 +125,10 @@ function animateStatusEllipsis(now) {
 }
 export function resolveStatusFieldText(progress, snapshotHeight, now = 0) {
     switch (progress.phase) {
+        case "getblock_archive_download":
+            return `Downloading getblock archive${animateStatusEllipsis(now)}`;
+        case "getblock_archive_import":
+            return `Importing getblock archive${animateStatusEllipsis(now)}`;
         case "paused":
         case "snapshot_download":
             return `Downloading snapshot to ${snapshotHeight}${animateStatusEllipsis(now)}`;
@@ -166,6 +174,16 @@ export const formatQuoteLineForTesting = formatQuoteLine;
 export function formatProgressLine(progress, cogcoinSyncHeight, cogcoinSyncTargetHeight, width = 120, now = Date.now()) {
     let line;
     switch (progress.phase) {
+        case "getblock_archive_download": {
+            const current = progress.downloadedBytes ?? 0;
+            const total = progress.totalBytes ?? 0;
+            const bar = renderBar(current, total, 20);
+            const percent = progress.percent ?? (total > 0 ? (current / total) * 100 : 0);
+            const speed = progress.bytesPerSecond === null ? "--" : `${formatBytes(progress.bytesPerSecond)}/s`;
+            const resumed = progress.resumed ? " resumed" : "";
+            line = `${bar} ${percent.toFixed(2)}% ${formatBytes(current)} / ${formatBytes(total)} ${speed} ETA ${formatDuration(progress.etaSeconds)}${resumed}`;
+            break;
+        }
         case "snapshot_download": {
             const current = progress.downloadedBytes ?? 0;
             const total = progress.totalBytes ?? 0;
@@ -190,6 +208,13 @@ export function formatProgressLine(progress, cogcoinSyncHeight, cogcoinSyncTarge
             line = `${bar} Bitcoin ${blocks.toLocaleString()} / ${target.toLocaleString()} ETA ${formatDuration(progress.etaSeconds)} ${progress.message}`;
             break;
         }
+        case "getblock_archive_import": {
+            const blocks = progress.blocks ?? 0;
+            const target = progress.targetHeight ?? blocks;
+            const bar = renderBar(blocks, target, 20);
+            line = `${bar} Bitcoin ${blocks.toLocaleString()} / ${target.toLocaleString()} ${progress.message}`;
+            break;
+        }
         case "cogcoin_sync": {
             const current = cogcoinSyncHeight ?? 0;
             const target = cogcoinSyncTargetHeight ?? current;

package/dist/bitcoind/progress/render-policy.d.ts

@@ -0,0 +1,35 @@
+import type { ProgressOutputMode } from "../types.js";
+export interface TtyRenderStream {
+    isTTY?: boolean;
+    columns?: number;
+    write(chunk: string): boolean | void;
+}
+export interface RenderClock {
+    now(): number;
+    setTimeout: typeof setTimeout;
+    clearTimeout: typeof clearTimeout;
+    setInterval: typeof setInterval;
+    clearInterval: typeof clearInterval;
+}
+export interface TtyRenderPolicy {
+    enabled: boolean;
+    linuxHeadlessThrottle: boolean;
+    repaintIntervalMs: number;
+}
+export declare const DEFAULT_RENDER_CLOCK: RenderClock;
+export declare function resolveTtyRenderPolicy(progressOutput: ProgressOutputMode, stream: Pick<TtyRenderStream, "isTTY">, options?: {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+}): TtyRenderPolicy;
+export declare class TtyRenderThrottle {
+    #private;
+    constructor(options: {
+        clock?: RenderClock;
+        intervalMs: number;
+        onRender: () => void;
+        throttled: boolean;
+    });
+    request(): void;
+    flush(): void;
+    cancel(): void;
+}