@cogcoin/client 1.0.1 → 1.1.0

package/dist/cli/commands/sync.js

@@ -1,12 +1,13 @@
 import { dirname } from "node:path";
+import { DEFAULT_SNAPSHOT_METADATA, resolveBootstrapPathsForTesting } from "../../bitcoind/bootstrap.js";
 import { formatManagedSyncErrorMessage } from "../../bitcoind/errors.js";
-import { FileLockBusyError, acquireFileLock } from "../../wallet/fs/lock.js";
 import { resolveWalletRootIdFromLocalArtifacts } from "../../wallet/root-resolution.js";
 import { withInteractiveWalletSecretProvider } from "../../wallet/state/provider.js";
+import { ManagedIndexerProgressObserver, pollManagedIndexerUntilCaughtUp, } from "../managed-indexer-observer.js";
 import { usesTtyProgress, writeLine } from "../io.js";
-import { classifyCliError, formatCliTextError } from "../output.js";
+import { classifyCliError } from "../output.js";
 import { createTerminalPrompter } from "../prompt.js";
-import { createStopSignalWatcher, waitForCompletionOrStop } from "../signals.js";
+import { createCloseSignalWatcher, waitForCompletionOrStop } from "../signals.js";
 import { createSyncProgressReporter } from "../sync-progress.js";
 import { formatBalanceReport } from "../wallet-format.js";
 async function writePostSyncBalanceReport(options) {
@@ -15,7 +16,7 @@ async function writePostSyncBalanceReport(options) {
         dataDir: options.dataDir,
         databasePath: options.databasePath,
         secretProvider: provider,
-        walletControlLockHeld: true,
+        expectedIndexerBinaryVersion: options.expectedIndexerBinaryVersion,
         paths: options.runtimePaths,
     });
     try {
@@ -28,38 +29,27 @@ async function writePostSyncBalanceReport(options) {
 export async function runSyncCommand(parsed, context) {
     const dbPath = parsed.dbPath ?? context.resolveDefaultClientDatabasePath();
     const dataDir = parsed.dataDir ?? context.resolveDefaultBitcoindDataDir();
+    const packageVersion = await context.readPackageVersion();
     const runtimePaths = context.resolveWalletRuntimePaths();
     const ttyProgressActive = usesTtyProgress(parsed.progressOutput, context.stderr);
-    let controlLock = null;
-    let store = null;
-    let storeOwned = true;
-    let client = null;
-    let clientClosed = false;
+    let monitor = null;
+    let observer = null;
     try {
         const walletRoot = await resolveWalletRootIdFromLocalArtifacts({
             paths: runtimePaths,
             provider: context.walletSecretProvider,
             loadRawWalletStateEnvelope: context.loadRawWalletStateEnvelope,
         });
-        try {
-            controlLock = await acquireFileLock(runtimePaths.walletControlLockPath, {
-                purpose: "managed-sync",
-                walletRootId: walletRoot.walletRootId,
-            });
-        }
-        catch (error) {
-            if (error instanceof FileLockBusyError) {
-                throw new Error("wallet_control_lock_busy");
-            }
-            throw error;
-        }
         await context.ensureDirectory(dirname(dbPath));
-        store = await context.openSqliteStore({ filename: dbPath });
-        client = await context.openManagedBitcoindClient({
-            store,
-            databasePath: dbPath,
+        monitor = await context.openManagedIndexerMonitor({
             dataDir,
+            databasePath: dbPath,
             walletRootId: walletRoot.walletRootId,
+            expectedBinaryVersion: packageVersion,
+        });
+        observer = new ManagedIndexerProgressObserver({
+            quoteStatePath: resolveBootstrapPathsForTesting(dataDir, DEFAULT_SNAPSHOT_METADATA).quoteStatePath,
+            stream: context.stderr,
             progressOutput: parsed.progressOutput,
             onProgress: ttyProgressActive ? undefined : createSyncProgressReporter({
                 progressOutput: parsed.progressOutput,
@@ -68,82 +58,52 @@ export async function runSyncCommand(parsed, context) {
                 },
             }),
         });
-        storeOwned = false;
-        const stopWatcher = createStopSignalWatcher(context.signalSource, context.stderr, client, context.forceExit, [runtimePaths.walletControlLockPath]);
+        const abortController = new AbortController();
+        const stopWatcher = createCloseSignalWatcher({
+            signalSource: context.signalSource,
+            stderr: context.stderr,
+            closeable: {
+                close: async () => {
+                    abortController.abort(new Error("managed_indexer_observer_aborted"));
+                    await observer?.close().catch(() => undefined);
+                    await monitor?.close().catch(() => undefined);
+                },
+            },
+            forceExit: context.forceExit,
+            firstMessage: "Stopping managed Cogcoin sync observation...",
+            successMessage: "Stopped observing managed Cogcoin sync.",
+            failureMessage: "Managed Cogcoin sync observation cleanup failed.",
+        });
         try {
-            const syncOutcome = await waitForCompletionOrStop(client.syncToTip(), stopWatcher);
+            const syncOutcome = await waitForCompletionOrStop(pollManagedIndexerUntilCaughtUp({
+                monitor,
+                observer,
+                signal: abortController.signal,
+            }), stopWatcher);
             if (syncOutcome.kind === "stopped") {
                 return syncOutcome.code;
             }
-            const result = syncOutcome.value;
-            if (result.endingHeight !== null && result.endingHeight === result.bestHeight) {
-                stopWatcher.cleanup();
-                const detachPromise = typeof client.detachToBackgroundFollow === "function"
-                    ? client.detachToBackgroundFollow()
-                    : Promise.resolve();
-                if (typeof client.playSyncCompletionScene === "function") {
-                    await client.playSyncCompletionScene().catch(() => undefined);
-                }
-                try {
-                    await detachPromise;
-                    await client.close();
-                    clientClosed = true;
-                    writeLine(context.stderr, "Detached cleanly; background indexer follow resumed.");
-                    await writePostSyncBalanceReport({
-                        context,
-                        dataDir,
-                        databasePath: dbPath,
-                        runtimePaths,
-                    }).catch(() => undefined);
-                    return 0;
-                }
-                catch {
-                    writeLine(context.stderr, "Detach failed before background indexer follow was confirmed.");
-                    return 1;
-                }
-            }
-            if (typeof client.playSyncCompletionScene === "function") {
-                const completionOutcome = await waitForCompletionOrStop(client.playSyncCompletionScene().catch(() => undefined), stopWatcher);
-                if (completionOutcome.kind === "stopped") {
-                    return completionOutcome.code;
-                }
+            if (ttyProgressActive) {
+                await observer.playCompletionScene().catch(() => undefined);
             }
-            writeLine(context.stdout, `Applied blocks: ${result.appliedBlocks}`);
-            writeLine(context.stdout, `Rewound blocks: ${result.rewoundBlocks}`);
-            writeLine(context.stdout, `Indexed ending height: ${result.endingHeight ?? "none"}`);
-            writeLine(context.stdout, `Node best height: ${result.bestHeight}`);
+            await writePostSyncBalanceReport({
+                context,
+                dataDir,
+                databasePath: dbPath,
+                expectedIndexerBinaryVersion: packageVersion,
+                runtimePaths,
+            }).catch(() => undefined);
             return 0;
         }
         finally {
             stopWatcher.cleanup();
-            if (!clientClosed) {
-                await client.close();
-            }
+            await observer?.close().catch(() => undefined);
+            await monitor?.close().catch(() => undefined);
         }
     }
     catch (error) {
-        const classified = classifyCliError(error);
-        if (classified.errorCode === "wallet_control_lock_busy") {
-            const formatted = formatCliTextError(error);
-            if (formatted !== null) {
-                for (const line of formatted) {
-                    writeLine(context.stderr, line);
-                }
-            }
-            else {
-                writeLine(context.stderr, classified.message);
-            }
-        }
-        else {
-            const message = formatManagedSyncErrorMessage(error instanceof Error ? error.message : String(error));
-            writeLine(context.stderr, `sync failed: ${message}`);
-        }
-        if (storeOwned && store !== null) {
-            await store.close().catch(() => undefined);
-        }
-        return classified.exitCode;
-    }
-    finally {
-        await controlLock?.release().catch(() => undefined);
+        const message = formatManagedSyncErrorMessage(error instanceof Error ? error.message : String(error));
+        writeLine(context.stderr, `sync failed: ${message}`);
+        return classifyCliError(error).exitCode;
     }
 }

package/dist/cli/commands/update.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedCliArgs, RequiredCliRunnerContext } from "../types.js";
+export declare function runUpdateCommand(parsed: ParsedCliArgs, context: RequiredCliRunnerContext): Promise<number>;

package/dist/cli/commands/update.js

@@ -0,0 +1,101 @@
+import { writeLine } from "../io.js";
+import { createMutationSuccessEnvelope, describeCanonicalCommand, resolveStableMutationJsonSchema, writeHandledCliError, writeJsonValue, } from "../output.js";
+import { CLI_INSTALL_COMMAND, EXPLICIT_UPDATE_CHECK_TIMEOUT_MS, applyUpdateCheckResult, compareSemver, createEmptyUpdateCheckCache, fetchLatestPublishedVersion, loadUpdateCheckCache, persistUpdateCheckCache, } from "../update-service.js";
+function createUpdateResult(currentVersion, latestVersion, status, applied) {
+    return {
+        currentVersion,
+        latestVersion,
+        installCommand: CLI_INSTALL_COMMAND,
+        status,
+        applied,
+    };
+}
+function writeVersionSummary(context, currentVersion, latestVersion) {
+    writeLine(context.stdout, `Current version: ${currentVersion}`);
+    writeLine(context.stdout, `Latest version: ${latestVersion}`);
+    writeLine(context.stdout, `Run: ${CLI_INSTALL_COMMAND}`);
+}
+async function confirmApplyUpdate(context) {
+    const prompter = context.createPrompter();
+    if (!prompter.isInteractive) {
+        throw new Error("cli_update_requires_tty");
+    }
+    while (true) {
+        const answer = (await prompter.prompt("Install update now? [Y/n]: ")).trim().toLowerCase();
+        if (answer === "" || answer === "y" || answer === "yes") {
+            return true;
+        }
+        if (answer === "n" || answer === "no") {
+            return false;
+        }
+        prompter.writeLine("Enter \"y\" to continue or \"n\" to cancel.");
+    }
+}
+function writeSuccessJson(parsed, context, result) {
+    writeJsonValue(context.stdout, createMutationSuccessEnvelope(resolveStableMutationJsonSchema(parsed), describeCanonicalCommand(parsed), result.status, result));
+    return 0;
+}
+export async function runUpdateCommand(parsed, context) {
+    try {
+        const currentVersion = await context.readPackageVersion();
+        const cachePath = context.resolveUpdateCheckStatePath();
+        const now = context.now();
+        const cache = await loadUpdateCheckCache(cachePath) ?? createEmptyUpdateCheckCache();
+        const updateResult = await fetchLatestPublishedVersion(context.fetchImpl, {
+            timeoutMs: EXPLICIT_UPDATE_CHECK_TIMEOUT_MS,
+        });
+        if (updateResult.kind !== "success") {
+            throw new Error("cli_update_registry_unavailable");
+        }
+        await persistUpdateCheckCache(cachePath, applyUpdateCheckResult(cache, updateResult, now));
+        const latestVersion = updateResult.latestVersion;
+        const comparison = compareSemver(latestVersion, currentVersion);
+        if (comparison === null) {
+            throw new Error("cli_update_registry_unavailable");
+        }
+        if (comparison <= 0) {
+            const result = createUpdateResult(currentVersion, latestVersion, "up-to-date", false);
+            if (parsed.outputMode === "json") {
+                return writeSuccessJson(parsed, context, result);
+            }
+            writeVersionSummary(context, currentVersion, latestVersion);
+            writeLine(context.stdout, "Cogcoin is already up to date.");
+            return 0;
+        }
+        if (!parsed.assumeYes) {
+            if (parsed.outputMode !== "text") {
+                throw new Error("cli_update_requires_tty");
+            }
+            writeVersionSummary(context, currentVersion, latestVersion);
+            if (!(await confirmApplyUpdate(context))) {
+                writeLine(context.stdout, "Update canceled.");
+                return 0;
+            }
+        }
+        else if (parsed.outputMode === "text") {
+            writeVersionSummary(context, currentVersion, latestVersion);
+        }
+        if (parsed.outputMode === "text") {
+            writeLine(context.stdout, "Installing update...");
+        }
+        await context.runGlobalClientUpdateInstall({
+            stdout: parsed.outputMode === "json" ? context.stderr : context.stdout,
+            stderr: context.stderr,
+            env: context.env,
+        });
+        const result = createUpdateResult(currentVersion, latestVersion, "updated", true);
+        if (parsed.outputMode === "json") {
+            return writeSuccessJson(parsed, context, result);
+        }
+        writeLine(context.stdout, "Update completed. The next cogcoin invocation will use the new install.");
+        return 0;
+    }
+    catch (error) {
+        return writeHandledCliError({
+            parsed,
+            stdout: context.stdout,
+            stderr: context.stderr,
+            error,
+        });
+    }
+}

package/dist/cli/commands/wallet-admin.js

@@ -29,6 +29,19 @@ function writeSetupUnlockGuidance(stdout) {
         writeLine(stdout, line);
     }
 }
+function writeWelcomeArtBlock(stdout) {
+    writeLine(stdout, "");
+    writeLine(stdout, loadWelcomeArtText());
+    writeLine(stdout, "");
+}
+function assertInitTextPreflight(options) {
+    if (!options.prompter.isInteractive) {
+        throw new Error("wallet_init_requires_tty");
+    }
+    if (options.runtimePaths.selectedSeedName !== "main") {
+        throw new Error("wallet_init_seed_not_supported");
+    }
+}
 function getResetNextSteps(result) {
     return result.walletAction === "deleted" || result.walletAction === "not-present"
         ? ["Run `cogcoin init` to create a new wallet."]
@@ -169,6 +182,13 @@ export async function runWalletAdminCommand(parsed, context) {
             if (parsed.command === "init" || parsed.command === "wallet-init") {
                 const dataDir = parsed.dataDir ?? context.resolveDefaultBitcoindDataDir();
                 const prompter = createCommandPrompter(parsed, context);
+                if (parsed.outputMode === "text") {
+                    assertInitTextPreflight({
+                        prompter,
+                        runtimePaths,
+                    });
+                    writeWelcomeArtBlock(context.stdout);
+                }
                 const interactiveProvider = withInteractiveWalletSecretProvider(provider, prompter);
                 const result = await context.initializeWallet({
                     dataDir,
@@ -184,9 +204,7 @@ export async function runWalletAdminCommand(parsed, context) {
                     }));
                     return 0;
                 }
-                writeLine(context.stdout, "");
-                writeLine(context.stdout, loadWelcomeArtText());
-                writeLine(context.stdout, "");
+                writeWelcomeArtBlock(context.stdout);
                 writeLine(context.stdout, result.walletAction === "already-initialized"
                     ? "Wallet already initialized."
                     : "Wallet initialized.");

package/dist/cli/commands/wallet-read.js

@@ -40,6 +40,7 @@ function emitJson(context, parsed, schema, result) {
 export async function runWalletReadCommand(parsed, context) {
     const dbPath = parsed.dbPath ?? context.resolveDefaultClientDatabasePath();
     const dataDir = parsed.dataDir ?? context.resolveDefaultBitcoindDataDir();
+    const packageVersion = await context.readPackageVersion();
     const runtimePaths = context.resolveWalletRuntimePaths(parsed.seedName);
     await context.ensureDirectory(dirname(dbPath));
     const provider = parsed.outputMode === "text"
@@ -49,6 +50,7 @@ export async function runWalletReadCommand(parsed, context) {
         dataDir,
         databasePath: dbPath,
         secretProvider: provider,
+        expectedIndexerBinaryVersion: packageVersion,
         paths: runtimePaths,
     });
     try {

package/dist/cli/context.js

@@ -1,16 +1,18 @@
+import { spawn } from "node:child_process";
 import { mkdir, readFile } from "node:fs/promises";
 import { attachOrStartIndexerDaemon, probeIndexerDaemon, readObservedIndexerDaemonStatus, stopIndexerDaemonService, } from "../bitcoind/indexer-daemon.js";
 import { createRpcClient } from "../bitcoind/node.js";
 import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, stopManagedBitcoindService, } from "../bitcoind/service.js";
 import { resolveDefaultBitcoindDataDirForTesting, resolveDefaultClientDatabasePathForTesting, resolveDefaultUpdateCheckStatePathForTesting, } from "../app-paths.js";
 import { openManagedBitcoindClient } from "../bitcoind/index.js";
+import { openManagedIndexerMonitor } from "../bitcoind/indexer-monitor.js";
 import { inspectPassiveClientStatus } from "../passive-status.js";
 import { openSqliteStore } from "../sqlite/index.js";
 import { initializeWallet, deleteImportedWalletSeed, previewResetWallet, repairWallet, resetWallet, restoreWalletFromMnemonic, showWalletMnemonic, } from "../wallet/lifecycle.js";
 import { resolveWalletRuntimePathsForTesting } from "../wallet/runtime.js";
 import { openWalletReadContext } from "../wallet/read/index.js";
 import { loadRawWalletStateEnvelope, loadWalletState } from "../wallet/state/storage.js";
-import { ensureBuiltInMiningSetupIfNeeded, followMiningLog, inspectMiningControlPlane, readMiningLog, runForegroundMining, setupBuiltInMining, startBackgroundMining, stopBackgroundMining, } from "../wallet/mining/index.js";
+import { ensureBuiltInMiningSetupIfNeeded, followMiningLog, inspectMiningControlPlane, inspectMiningDomainPromptState, readMiningLog, runForegroundMining, setupBuiltInMining, startBackgroundMining, stopBackgroundMining, updateMiningDomainPrompt, } from "../wallet/mining/index.js";
 import { createLazyDefaultWalletSecretProvider } from "../wallet/state/provider.js";
 import { anchorDomain, transferBitcoin, buyDomain, claimCogLock, clearDomainDelegate, clearDomainEndpoint, clearDomainMiner, clearField, createField, giveReputation, lockCogToDomain, registerDomain, reclaimCogLock, revokeReputation, sendCog, setField, setDomainCanonical, setDomainDelegate, setDomainEndpoint, setDomainMiner, sellDomain, transferDomain, } from "../wallet/tx/index.js";
 import { createTerminalPrompter } from "./prompt.js";
@@ -36,6 +38,35 @@ export async function readPackageVersionFromDisk() {
     }
     return "0.0.0";
 }
+async function runGlobalClientUpdateInstall(options) {
+    const binary = process.platform === "win32" ? "npm.cmd" : "npm";
+    await new Promise((resolve, reject) => {
+        const child = spawn(binary, ["install", "-g", "@cogcoin/client"], {
+            env: options.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        child.stdout?.on("data", (chunk) => {
+            options.stdout.write(typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+        });
+        child.stderr?.on("data", (chunk) => {
+            options.stderr.write(typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+        });
+        child.on("error", (error) => {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+                reject(new Error("cli_update_npm_not_found"));
+                return;
+            }
+            reject(new Error("cli_update_install_failed"));
+        });
+        child.on("close", (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error("cli_update_install_failed"));
+        });
+    });
+}
 export function createDefaultContext(overrides = {}) {
     return {
         stdout: overrides.stdout ?? process.stdout,
@@ -48,8 +79,10 @@ export function createDefaultContext(overrides = {}) {
             process.exit(code);
         }),
         fetchImpl: overrides.fetchImpl ?? fetch,
+        runGlobalClientUpdateInstall: overrides.runGlobalClientUpdateInstall ?? runGlobalClientUpdateInstall,
         openSqliteStore: overrides.openSqliteStore ?? openSqliteStore,
         openManagedBitcoindClient: overrides.openManagedBitcoindClient ?? openManagedBitcoindClient,
+        openManagedIndexerMonitor: overrides.openManagedIndexerMonitor ?? openManagedIndexerMonitor,
         inspectPassiveClientStatus: overrides.inspectPassiveClientStatus ?? inspectPassiveClientStatus,
         openWalletReadContext: overrides.openWalletReadContext ?? openWalletReadContext,
         initializeWallet: overrides.initializeWallet ?? initializeWallet,
@@ -80,11 +113,13 @@ export function createDefaultContext(overrides = {}) {
         giveReputation: overrides.giveReputation ?? giveReputation,
         revokeReputation: overrides.revokeReputation ?? revokeReputation,
         inspectMiningControlPlane: overrides.inspectMiningControlPlane ?? inspectMiningControlPlane,
+        inspectMiningDomainPromptState: overrides.inspectMiningDomainPromptState ?? inspectMiningDomainPromptState,
         ensureBuiltInMiningSetupIfNeeded: overrides.ensureBuiltInMiningSetupIfNeeded ?? ensureBuiltInMiningSetupIfNeeded,
         runForegroundMining: overrides.runForegroundMining ?? runForegroundMining,
         startBackgroundMining: overrides.startBackgroundMining ?? startBackgroundMining,
         stopBackgroundMining: overrides.stopBackgroundMining ?? stopBackgroundMining,
         setupBuiltInMining: overrides.setupBuiltInMining ?? setupBuiltInMining,
+        updateMiningDomainPrompt: overrides.updateMiningDomainPrompt ?? updateMiningDomainPrompt,
         readMiningLog: overrides.readMiningLog ?? readMiningLog,
         followMiningLog: overrides.followMiningLog ?? followMiningLog,
         repairWallet: overrides.repairWallet ?? repairWallet,

package/dist/cli/managed-indexer-observer.d.ts

@@ -0,0 +1,33 @@
+import type { ManagedBitcoindProgressEvent, ManagedIndexerDaemonObservedStatus } from "../bitcoind/types.js";
+import type { ProgressOutput, WritableLike } from "./types.js";
+export declare function isManagedIndexerCaughtUp(status: ManagedIndexerDaemonObservedStatus): boolean;
+export declare function assertManagedIndexerStatusRecoverable(status: ManagedIndexerDaemonObservedStatus): void;
+export declare class ManagedIndexerProgressObserver {
+    #private;
+    constructor(options: {
+        quoteStatePath: string;
+        stream: WritableLike;
+        progressOutput: ProgressOutput;
+        followVisualMode?: boolean;
+        onProgress?: (event: ManagedBitcoindProgressEvent) => void;
+    });
+    applyStatus(status: ManagedIndexerDaemonObservedStatus): Promise<void>;
+    playCompletionScene(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function pollManagedIndexerUntilCaughtUp(options: {
+    monitor: {
+        getStatus(): Promise<ManagedIndexerDaemonObservedStatus>;
+    };
+    observer: ManagedIndexerProgressObserver;
+    signal?: AbortSignal;
+    pollIntervalMs?: number;
+}): Promise<ManagedIndexerDaemonObservedStatus>;
+export declare function followManagedIndexerStatus(options: {
+    monitor: {
+        getStatus(): Promise<ManagedIndexerDaemonObservedStatus>;
+    };
+    observer: ManagedIndexerProgressObserver;
+    signal?: AbortSignal;
+    pollIntervalMs?: number;
+}): Promise<void>;

package/dist/cli/managed-indexer-observer.js

@@ -0,0 +1,163 @@
+import { DEFAULT_SNAPSHOT_METADATA } from "../bitcoind/bootstrap.js";
+import { ManagedProgressController } from "../bitcoind/progress.js";
+import { createBootstrapProgress, createDefaultMessage, } from "../bitcoind/progress/formatting.js";
+const INDEXER_MONITOR_POLL_INTERVAL_MS = 500;
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function isTransientIndexerFailureMessage(message) {
+    if (message === null) {
+        return false;
+    }
+    return message === "managed_bitcoind_runtime_config_unavailable"
+        || message.includes("cookie file is unavailable")
+        || message.includes("ECONNREFUSED")
+        || message.includes("ECONNRESET")
+        || message.includes("socket hang up");
+}
+function deriveFallbackPhase(status) {
+    switch (status.state) {
+        case "synced":
+            return "follow_tip";
+        case "catching-up":
+        case "reorging":
+            return "cogcoin_sync";
+        case "failed":
+            return "error";
+        case "starting":
+            return "paused";
+        case "stopping":
+            return "paused";
+        case "schema-mismatch":
+        case "service-version-mismatch":
+            return "error";
+        default:
+            return "paused";
+    }
+}
+function normalizeBootstrapProgress(status) {
+    const phase = status.bootstrapPhase ?? deriveFallbackPhase(status);
+    const sourceProgress = status.bootstrapProgress ?? createBootstrapProgress(phase, DEFAULT_SNAPSHOT_METADATA);
+    const progress = {
+        ...sourceProgress,
+        phase,
+        message: sourceProgress.message || createDefaultMessage(phase),
+        blocks: sourceProgress.blocks,
+        headers: sourceProgress.headers ?? status.coreBestHeight,
+        targetHeight: sourceProgress.targetHeight ?? status.coreBestHeight,
+        lastError: status.lastError ?? sourceProgress.lastError,
+        updatedAt: sourceProgress.updatedAt ?? status.updatedAtUnixMs,
+    };
+    const cogcoinSyncHeight = status.cogcoinSyncHeight ?? status.appliedTipHeight ?? null;
+    const cogcoinSyncTargetHeight = status.cogcoinSyncTargetHeight ?? status.coreBestHeight ?? null;
+    if (phase === "cogcoin_sync") {
+        progress.blocks = progress.blocks ?? cogcoinSyncHeight;
+        progress.headers = progress.headers ?? cogcoinSyncTargetHeight;
+        progress.targetHeight = progress.targetHeight ?? cogcoinSyncTargetHeight;
+    }
+    else if (phase === "follow_tip") {
+        progress.blocks = status.coreBestHeight ?? progress.blocks;
+        progress.headers = status.coreBestHeight ?? progress.headers;
+        progress.targetHeight = status.coreBestHeight ?? progress.targetHeight;
+    }
+    else if (phase === "error" && progress.message === createDefaultMessage("error") && status.lastError !== null) {
+        progress.message = status.lastError;
+    }
+    return {
+        phase,
+        progress,
+        cogcoinSyncHeight,
+        cogcoinSyncTargetHeight,
+    };
+}
+export function isManagedIndexerCaughtUp(status) {
+    return status.state === "synced"
+        && status.coreBestHeight !== null
+        && status.appliedTipHeight === status.coreBestHeight
+        && (status.coreBestHash === null
+            || status.appliedTipHash === null
+            || status.coreBestHash === status.appliedTipHash);
+}
+export function assertManagedIndexerStatusRecoverable(status) {
+    if (status.state === "schema-mismatch" || status.state === "service-version-mismatch") {
+        throw new Error(status.lastError ?? `indexer_daemon_${status.state}`);
+    }
+    if (status.state === "failed" && !isTransientIndexerFailureMessage(status.lastError)) {
+        throw new Error(status.lastError ?? "indexer_daemon_failed");
+    }
+}
+export class ManagedIndexerProgressObserver {
+    #progress;
+    #followVisualMode;
+    #started = false;
+    #followVisualModeEnabled = false;
+    constructor(options) {
+        this.#followVisualMode = options.followVisualMode ?? false;
+        this.#progress = new ManagedProgressController({
+            onProgress: options.onProgress,
+            progressOutput: options.progressOutput,
+            snapshot: DEFAULT_SNAPSHOT_METADATA,
+            quoteStatePath: options.quoteStatePath,
+            stream: options.stream,
+        });
+    }
+    async applyStatus(status) {
+        if (!this.#started) {
+            await this.#progress.start();
+            this.#started = true;
+        }
+        if (this.#followVisualMode && !this.#followVisualModeEnabled) {
+            await this.#progress.enableFollowVisualMode(status.appliedTipHeight ?? null);
+            this.#followVisualModeEnabled = true;
+        }
+        const normalized = normalizeBootstrapProgress(status);
+        if (normalized.phase === "cogcoin_sync"
+            || (normalized.phase === "follow_tip" && this.#followVisualMode)) {
+            await this.#progress.setCogcoinSync(normalized.cogcoinSyncHeight, normalized.cogcoinSyncTargetHeight, normalized.progress.etaSeconds);
+        }
+        const { phase: _phase, updatedAt: _updatedAt, ...patch } = normalized.progress;
+        await this.#progress.setPhase(normalized.phase, patch);
+    }
+    async playCompletionScene() {
+        if (!this.#started) {
+            return;
+        }
+        await this.#progress.playCompletionScene();
+    }
+    async close() {
+        if (!this.#started) {
+            return;
+        }
+        await this.#progress.close();
+        this.#started = false;
+    }
+}
+export async function pollManagedIndexerUntilCaughtUp(options) {
+    while (true) {
+        if (options.signal?.aborted) {
+            throw options.signal.reason instanceof Error
+                ? options.signal.reason
+                : new Error("managed_indexer_observer_aborted");
+        }
+        const status = await options.monitor.getStatus();
+        await options.observer.applyStatus(status);
+        assertManagedIndexerStatusRecoverable(status);
+        if (isManagedIndexerCaughtUp(status)) {
+            return status;
+        }
+        await sleep(options.pollIntervalMs ?? INDEXER_MONITOR_POLL_INTERVAL_MS);
+    }
+}
+export async function followManagedIndexerStatus(options) {
+    while (true) {
+        if (options.signal?.aborted) {
+            return;
+        }
+        const status = await options.monitor.getStatus();
+        await options.observer.applyStatus(status);
+        assertManagedIndexerStatusRecoverable(status);
+        await sleep(options.pollIntervalMs ?? INDEXER_MONITOR_POLL_INTERVAL_MS);
+    }
+}

package/dist/cli/mining-format.d.ts

@@ -1,4 +1,6 @@
-import type { MiningControlPlaneView, MiningEventRecord } from "../wallet/mining/index.js";
+import type { MiningControlPlaneView, MiningDomainPromptListResult, MiningDomainPromptMutationResult, MiningEventRecord } from "../wallet/mining/index.js";
 export declare function formatMiningSummaryLine(mining: MiningControlPlaneView): string;
 export declare function formatMineStatusReport(mining: MiningControlPlaneView): string;
 export declare function formatMiningEventRecord(event: MiningEventRecord): string;
+export declare function formatMiningPromptMutationReport(result: MiningDomainPromptMutationResult): string;
+export declare function formatMiningPromptListReport(result: MiningDomainPromptListResult): string;