@cogcoin/client 1.0.2 → 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/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

@@ -5,13 +5,14 @@ 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";
@@ -81,6 +82,7 @@ export function createDefaultContext(overrides = {}) {
         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,
@@ -111,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;

package/dist/cli/mining-format.js

@@ -27,6 +27,9 @@ function resolveProviderNotFoundNextStep(mining) {
         ? "Next: run `cogcoin mine setup` and clear or correct the provider model."
         : "Next: run `cogcoin mine setup` and choose a valid provider model.";
 }
+function resolveInsufficientFundsNextStep() {
+    return "Next: wait for enough safe BTC funding to become spendable for the next publish; mining resumes automatically.";
+}
 export function formatMiningSummaryLine(mining) {
     const provider = mining.provider.configured
         ? `${mining.provider.provider} configured`
@@ -133,6 +136,9 @@ export function formatMineStatusReport(mining) {
     else if (mining.runtime.providerState === "not-found") {
         lines.push(resolveProviderNotFoundNextStep(mining));
     }
+    else if (mining.runtime.currentPublishDecision === "publish-paused-insufficient-funds") {
+        lines.push(resolveInsufficientFundsNextStep());
+    }
     else if (mining.runtime.pauseReason === "zero-reward") {
         lines.push("Next: wait for the next positive-reward target height; mining resumes automatically.");
     }
@@ -150,3 +156,32 @@ export function formatMineStatusReport(mining) {
 export function formatMiningEventRecord(event) {
     return `${new Date(event.timestampUnixMs).toISOString()}  ${event.level.toUpperCase()}  ${event.kind}  ${event.message}`;
 }
+export function formatMiningPromptMutationReport(result) {
+    const lines = [
+        `Domain: ${result.domain.name}`,
+        `Domain prompt: ${result.prompt ?? "none"}`,
+        `Global fallback prompt: ${result.fallbackPromptConfigured ? "configured" : "not configured"}`,
+    ];
+    if (result.previousPrompt !== null) {
+        lines.push(`Previous domain prompt: ${result.previousPrompt}`);
+    }
+    lines.push(result.status === "updated"
+        ? "Per-domain mining prompt updated."
+        : "Per-domain mining prompt cleared.");
+    return lines.join("\n");
+}
+export function formatMiningPromptListReport(result) {
+    const lines = [
+        "Mining Prompt List",
+        `Global fallback prompt: ${result.fallbackPromptConfigured ? "configured" : "not configured"}`,
+    ];
+    if (result.prompts.length === 0) {
+        lines.push("No mineable root domains or stored per-domain mining prompts are configured.");
+        return lines.join("\n");
+    }
+    for (const entry of result.prompts) {
+        lines.push(`${entry.domain.name}  domainId=${entry.domain.domainId ?? "none"}  ${entry.mineable ? "mineable" : "dormant"}  source=${entry.effectivePromptSource}`);
+        lines.push(`  prompt: ${entry.prompt ?? "none"}`);
+    }
+    return lines.join("\n");
+}

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

@@ -1,4 +1,4 @@
-import type { MiningControlPlaneView, MiningRuntimeStatusV1 } from "../wallet/mining/index.js";
+import type { MiningControlPlaneView, MiningDomainPromptMutationResult, MiningRuntimeStatusV1 } from "../wallet/mining/index.js";
 export declare function buildMineSetupData(view: MiningControlPlaneView): {
     resultType: "state-change";
     stateChange: {
@@ -29,3 +29,13 @@ export declare function buildMineStopData(snapshot: MiningRuntimeStatusV1 | null
     };
     state: Record<string, unknown>;
 };
+export declare function buildMinePromptData(result: MiningDomainPromptMutationResult): {
+    domain: {
+        name: string;
+        domainId: number | null;
+    };
+    previousPrompt: string | null;
+    prompt: string | null;
+    status: "updated" | "cleared";
+    fallbackPromptConfigured: boolean;
+};

package/dist/cli/mining-json.js

@@ -58,3 +58,12 @@ export function buildMineStopData(snapshot) {
         after,
     });
 }
+export function buildMinePromptData(result) {
+    return {
+        domain: result.domain,
+        previousPrompt: result.previousPrompt,
+        prompt: result.prompt,
+        status: result.status,
+        fallbackPromptConfigured: result.fallbackPromptConfigured,
+    };
+}

package/dist/cli/output.js

@@ -185,6 +185,8 @@ function isBlockedError(message) {
         || message === "indexer_daemon_wallet_root_mismatch"
         || message === "indexer_daemon_schema_mismatch"
         || message === "mine_setup_requires_tty"
+        || message === "mine_prompt_requires_tty"
+        || message === "mine_prompt_domain_not_mineable"
         || message === "mining_preemption_timeout"
         || message === "wallet_client_password_setup_required"
         || message === "wallet_client_password_migration_required"
@@ -523,6 +525,13 @@ export function createCliErrorPresentation(errorCode, fallbackMessage, error) {
             next: "Rerun `cogcoin mine setup` when you are ready to choose a provider model.",
         };
     }
+    if (errorCode === "mine_prompt_domain_not_mineable") {
+        return {
+            what: "A new mining prompt override can only target a mineable anchored root domain.",
+            why: "Cogcoin only creates new domain prompt overrides for locally controlled anchored root domains that are currently mineable. Existing stored prompt entries can still be edited or cleared by name even when they are dormant.",
+            next: "Run `cogcoin domains --mineable` to see eligible domains, or rerun `cogcoin mine prompt <domain>` for an existing stored prompt entry.",
+        };
+    }
     if (errorCode.endsWith("_confirmation_rejected")) {
         return {
             what: "Confirmation was declined.",
@@ -591,6 +600,13 @@ export function createCliErrorPresentation(errorCode, fallbackMessage, error) {
             next: "Check `cogcoin status`, wait for services to settle, and retry. If the state stays degraded, run `cogcoin repair`.",
         };
     }
+    if (errorCode === "indexer_daemon_background_follow_recovery_failed") {
+        return {
+            what: "The managed indexer daemon could not recover automatic background follow.",
+            why: "Cogcoin tried to resume or restart the compatible managed indexer daemon, but it still failed to enter background follow.",
+            next: "Run `cogcoin repair` if this persists, then retry.",
+        };
+    }
     if (errorCode === "indexer_daemon_service_version_mismatch") {
         return {
             what: "The live indexer daemon is running an incompatible service API version.",
@@ -1027,6 +1043,10 @@ export function describeCanonicalCommand(parsed) {
             return "cogcoin wallet status";
         case "mine-setup":
             return "cogcoin mine setup";
+        case "mine-prompt":
+            return `cogcoin mine prompt ${args[0] ?? "<domain>"}`;
+        case "mine-prompt-list":
+            return "cogcoin mine prompt";
         case "mine-start":
             return "cogcoin mine start";
         case "mine-stop":
@@ -1098,6 +1118,8 @@ export function resolveStableJsonSchema(parsed) {
             return "cogcoin/mine-status/v1";
         case "mine-log":
             return "cogcoin/mine-log/v1";
+        case "mine-prompt-list":
+            return "cogcoin/mine-prompt-list/v1";
         case "balance":
         case "cog-balance":
             return "cogcoin/balance/v1";
@@ -1205,6 +1227,8 @@ export function resolveStableMiningControlJsonSchema(parsed) {
     switch (parsed.command) {
         case "mine-setup":
             return "cogcoin/mine-setup/v1";
+        case "mine-prompt":
+            return "cogcoin/mine-prompt/v1";
         case "mine-start":
             return "cogcoin/mine-start/v1";
         case "mine-stop":