@cogcoin/client 0.5.14 → 1.0.0

package/dist/bitcoind/types.d.ts

@@ -173,6 +173,7 @@ export interface ManagedBitcoindClient extends Client {
     syncToTip(): Promise<SyncResult>;
     startFollowingTip(): Promise<void>;
     getNodeStatus(): Promise<ManagedBitcoindStatus>;
+    detachToBackgroundFollow(): Promise<void>;
     close(): Promise<void>;
 }
 export interface InternalManagedBitcoindOptions extends ManagedBitcoindOptions {
@@ -275,6 +276,7 @@ export interface RpcPrevout {
 }
 export interface RpcVin {
     txid?: string;
+    vout?: number;
     coinbase?: string;
     prevout?: RpcPrevout;
 }
@@ -298,6 +300,11 @@ export interface RpcMempoolEntry {
     ancestorsize?: number;
     descendantsize?: number;
 }
+export interface RpcEstimateSmartFeeResult {
+    feerate?: number;
+    errors?: string[];
+    blocks?: number;
+}
 export interface RpcRawMempoolVerbose {
     txids: string[];
     mempool_sequence: string | number;
@@ -310,6 +317,11 @@ export interface RpcWalletTransaction {
     blockheight?: number;
     time?: number;
     timereceived?: number;
+    details?: Array<{
+        address?: string;
+        vout?: number;
+    }>;
+    decoded?: RpcTransaction;
 }
 export interface RpcBlock {
     hash: string;
@@ -409,6 +421,10 @@ export interface RpcListUnspentEntry {
 }
 export interface RpcDecodedPsbt {
     tx: RpcTransaction;
+    inputs?: Array<{
+        witness_utxo?: RpcVout;
+        non_witness_utxo?: RpcTransaction;
+    }>;
 }
 export interface RpcFinalizePsbtResult {
     psbt?: string;

package/dist/bytes.d.ts

@@ -1,6 +1,7 @@
 export declare function bytesToHex(bytes: Uint8Array): string;
 export declare function hexToBytes(hex: string): Uint8Array;
 export declare function cloneBytes(bytes: Uint8Array): Uint8Array;
+export declare function reverseBytes(bytes: Uint8Array): Uint8Array;
 export declare function encodeText(value: string): Uint8Array;
 export declare function decodeText(bytes: Uint8Array): string;
 export declare function encodeNullableText(value: string | null): Uint8Array;

package/dist/bytes.js

@@ -9,6 +9,9 @@ export function hexToBytes(hex) {
 export function cloneBytes(bytes) {
     return new Uint8Array(bytes);
 }
+export function reverseBytes(bytes) {
+    return Uint8Array.from([...bytes].reverse());
+}
 export function encodeText(value) {
     return textEncoder.encode(value);
 }

package/dist/cli/art.d.ts

@@ -0,0 +1,2 @@
+export declare function loadWelcomeArtText(): string;
+export declare function loadBalanceArtText(): string;

package/dist/cli/art.js

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+let welcomeArtCache = null;
+let balanceArtCache = null;
+const FIXED_ART_WIDTH = 80;
+const BALANCE_ART_HEIGHT = 10;
+function normalizeFixedArtText(raw, options) {
+    const lines = raw.replaceAll("\r\n", "\n").split("\n");
+    if (lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    if (lines.length !== options.height) {
+        throw new Error(`${options.name}_art_height_invalid_${lines.length}`);
+    }
+    for (const line of lines) {
+        if (line.length !== FIXED_ART_WIDTH) {
+            throw new Error(`${options.name}_art_width_invalid_${line.length}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function loadWelcomeArtText() {
+    if (welcomeArtCache !== null) {
+        return welcomeArtCache;
+    }
+    welcomeArtCache = readFileSync(new URL("../art/welcome.txt", import.meta.url), "utf8");
+    return welcomeArtCache;
+}
+export function loadBalanceArtText() {
+    if (balanceArtCache !== null) {
+        return balanceArtCache;
+    }
+    balanceArtCache = normalizeFixedArtText(readFileSync(new URL("../art/balance.txt", import.meta.url), "utf8"), {
+        name: "balance",
+        height: BALANCE_ART_HEIGHT,
+    });
+    return balanceArtCache;
+}

package/dist/cli/commands/client-admin.d.ts

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

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

@@ -0,0 +1,91 @@
+import { writeLine } from "../io.js";
+import { createTerminalPrompter } from "../prompt.js";
+import { createMutationSuccessEnvelope, describeCanonicalCommand, resolveStableMutationJsonSchema, writeHandledCliError, writeJsonValue, } from "../output.js";
+import { changeClientPassword, lockClientPassword, unlockClientPassword, } from "../../wallet/state/provider.js";
+function createCommandPrompter(parsed, context) {
+    return parsed.outputMode !== "text"
+        ? createTerminalPrompter(context.stdin, context.stderr)
+        : context.createPrompter();
+}
+export async function runClientAdminCommand(parsed, context) {
+    try {
+        if (parsed.command === "client-lock") {
+            const status = await lockClientPassword(context.walletSecretProvider);
+            if (parsed.outputMode === "json") {
+                writeJsonValue(context.stdout, createMutationSuccessEnvelope(resolveStableMutationJsonSchema(parsed), describeCanonicalCommand(parsed), "locked", {
+                    resultType: "operation",
+                    operation: {
+                        kind: "client-lock",
+                        locked: true,
+                        unlockUntilUnixMs: status.unlockUntilUnixMs,
+                    },
+                    state: {
+                        locked: true,
+                        unlockUntilUnixMs: status.unlockUntilUnixMs,
+                    },
+                }));
+                return 0;
+            }
+            writeLine(context.stdout, "Client locked.");
+            return 0;
+        }
+        if (parsed.command === "client-unlock") {
+            const prompter = createCommandPrompter(parsed, context);
+            const status = await unlockClientPassword(context.walletSecretProvider, prompter);
+            if (parsed.outputMode === "json") {
+                writeJsonValue(context.stdout, createMutationSuccessEnvelope(resolveStableMutationJsonSchema(parsed), describeCanonicalCommand(parsed), "unlocked", {
+                    resultType: "operation",
+                    operation: {
+                        kind: "client-unlock",
+                        unlocked: status.unlocked,
+                        unlockUntilUnixMs: status.unlockUntilUnixMs,
+                    },
+                    state: {
+                        unlocked: status.unlocked,
+                        unlockUntilUnixMs: status.unlockUntilUnixMs,
+                    },
+                }));
+                return 0;
+            }
+            writeLine(context.stdout, status.unlockUntilUnixMs === null
+                ? "Client unlocked."
+                : `Client unlocked until ${new Date(status.unlockUntilUnixMs).toISOString()}.`);
+            return 0;
+        }
+        if (parsed.command === "client-change-password") {
+            const prompter = createCommandPrompter(parsed, context);
+            const status = await changeClientPassword(context.walletSecretProvider, prompter);
+            if (parsed.outputMode === "json") {
+                writeJsonValue(context.stdout, createMutationSuccessEnvelope(resolveStableMutationJsonSchema(parsed), describeCanonicalCommand(parsed), "changed", {
+                    resultType: "operation",
+                    operation: {
+                        kind: "client-change-password",
+                        changed: true,
+                        unlocked: status.unlocked,
+                        unlockUntilUnixMs: status.unlockUntilUnixMs,
+                    },
+                    state: {
+                        changed: true,
+                        unlocked: status.unlocked,
+                        unlockUntilUnixMs: status.unlockUntilUnixMs,
+                    },
+                }));
+                return 0;
+            }
+            writeLine(context.stdout, status.unlockUntilUnixMs === null
+                ? "Client password changed."
+                : `Client password changed. Client unlocked until ${new Date(status.unlockUntilUnixMs).toISOString()}.`);
+            return 0;
+        }
+        writeLine(context.stderr, `client admin command not implemented: ${parsed.command}`);
+        return 1;
+    }
+    catch (error) {
+        return writeHandledCliError({
+            parsed,
+            stdout: context.stdout,
+            stderr: context.stderr,
+            error,
+        });
+    }
+}

package/dist/cli/commands/follow.js

@@ -16,8 +16,6 @@ export async function runFollowCommand(parsed, context) {
             paths: runtimePaths,
             provider: context.walletSecretProvider,
             loadRawWalletStateEnvelope: context.loadRawWalletStateEnvelope,
-            loadUnlockSession: context.loadUnlockSession,
-            loadWalletExplicitLock: context.loadWalletExplicitLock,
         });
         try {
             controlLock = await acquireFileLock(runtimePaths.walletControlLockPath, {

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

@@ -1,9 +1,10 @@
-import { buildHooksDisableMiningData, buildHooksEnableMiningData, buildMineSetupData, } from "../mining-json.js";
-import { buildHooksPreviewData } from "../preview-json.js";
+import { buildMineSetupData, } from "../mining-json.js";
+import { buildMineSetupPreviewData } from "../preview-json.js";
 import { writeLine } from "../io.js";
 import { createTerminalPrompter } from "../prompt.js";
 import { createPreviewSuccessEnvelope, createMutationSuccessEnvelope, describeCanonicalCommand, resolvePreviewJsonSchema, resolveStableMiningControlJsonSchema, writeHandledCliError, writeJsonValue, } from "../output.js";
-import { formatNextStepLines, getHooksEnableMiningNextSteps, getMineSetupNextSteps, } from "../workflow-hints.js";
+import { formatNextStepLines, getMineSetupNextSteps, } from "../workflow-hints.js";
+import { withInteractiveWalletSecretProvider } from "../../wallet/state/provider.js";
 function createCommandPrompter(parsed, context) {
     return parsed.outputMode !== "text"
         ? createTerminalPrompter(context.stdin, context.stderr)
@@ -11,52 +12,10 @@ function createCommandPrompter(parsed, context) {
 }
 export async function runMiningAdminCommand(parsed, context) {
     try {
-        const provider = context.walletSecretProvider;
         const runtimePaths = context.resolveWalletRuntimePaths(parsed.seedName);
-        if (parsed.command === "hooks-mining-enable") {
-            const prompter = createCommandPrompter(parsed, context);
-            const view = await context.enableMiningHooks({
-                provider,
-                prompter,
-                paths: runtimePaths,
-            });
-            const nextSteps = getHooksEnableMiningNextSteps();
-            if (parsed.outputMode === "preview-json") {
-                writeJsonValue(context.stdout, createPreviewSuccessEnvelope(resolvePreviewJsonSchema(parsed), describeCanonicalCommand(parsed), "enabled", buildHooksPreviewData("hooks-enable-mining", view), {
-                    nextSteps,
-                }));
-                return 0;
-            }
-            if (parsed.outputMode === "json") {
-                writeJsonValue(context.stdout, createMutationSuccessEnvelope(resolveStableMiningControlJsonSchema(parsed), "cogcoin hooks enable mining", "enabled", buildHooksEnableMiningData(view), {
-                    nextSteps,
-                }));
-                return 0;
-            }
-            writeLine(context.stdout, "Custom mining hook enabled.");
-            for (const line of formatNextStepLines(nextSteps)) {
-                writeLine(context.stdout, line);
-            }
-            return 0;
-        }
-        if (parsed.command === "hooks-mining-disable") {
-            const view = await context.disableMiningHooks({
-                provider,
-                paths: runtimePaths,
-            });
-            if (parsed.outputMode === "preview-json") {
-                writeJsonValue(context.stdout, createPreviewSuccessEnvelope(resolvePreviewJsonSchema(parsed), describeCanonicalCommand(parsed), "disabled", buildHooksPreviewData("hooks-disable-mining", view)));
-                return 0;
-            }
-            if (parsed.outputMode === "json") {
-                writeJsonValue(context.stdout, createMutationSuccessEnvelope(resolveStableMiningControlJsonSchema(parsed), "cogcoin hooks disable mining", "disabled", buildHooksDisableMiningData(view)));
-                return 0;
-            }
-            writeLine(context.stdout, "Mining hooks switched back to builtin mode.");
-            return 0;
-        }
         if (parsed.command === "mine-setup") {
             const prompter = createCommandPrompter(parsed, context);
+            const provider = withInteractiveWalletSecretProvider(context.walletSecretProvider, prompter);
             const view = await context.setupBuiltInMining({
                 provider,
                 prompter,
@@ -64,7 +23,7 @@ export async function runMiningAdminCommand(parsed, context) {
             });
             const nextSteps = getMineSetupNextSteps();
             if (parsed.outputMode === "preview-json") {
-                writeJsonValue(context.stdout, createPreviewSuccessEnvelope(resolvePreviewJsonSchema(parsed), describeCanonicalCommand(parsed), "configured", buildHooksPreviewData("mine-setup", view), {
+                writeJsonValue(context.stdout, createPreviewSuccessEnvelope(resolvePreviewJsonSchema(parsed), describeCanonicalCommand(parsed), "configured", buildMineSetupPreviewData(view), {
                     nextSteps,
                 }));
                 return 0;

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

@@ -1,10 +1,10 @@
 import { dirname } from "node:path";
 import { stat } from "node:fs/promises";
-import { formatHooksStatusReport, formatMineStatusReport, formatMiningEventRecord } from "../mining-format.js";
+import { formatMineStatusReport, formatMiningEventRecord } from "../mining-format.js";
 import { writeLine } from "../io.js";
-import { inspectWalletLocalState } from "../../wallet/read/index.js";
 import { createErrorEnvelope, createSuccessEnvelope, describeCanonicalCommand, normalizeListPage, writeJsonValue, } from "../output.js";
-import { buildHooksStatusJson, buildMineLogJson, buildMineStatusJson } from "../read-json.js";
+import { buildMineLogJson, buildMineStatusJson } from "../read-json.js";
+import { withInteractiveWalletSecretProvider } from "../../wallet/state/provider.js";
 async function readRotationIndices(paths) {
     const rotation = [];
     for (let index = 1; index <= 4; index += 1) {
@@ -26,46 +26,6 @@ export async function runMiningReadCommand(parsed, context) {
         const dataDir = parsed.dataDir ?? context.resolveDefaultBitcoindDataDir();
         const runtimePaths = context.resolveWalletRuntimePaths(parsed.seedName);
         await context.ensureDirectory(dirname(dbPath));
-        if (parsed.command === "hooks-mining-status") {
-            const localState = await inspectWalletLocalState({
-                secretProvider: context.walletSecretProvider,
-                paths: runtimePaths,
-            });
-            const view = await context.inspectMiningControlPlane({
-                provider: context.walletSecretProvider,
-                localState,
-                bitcoind: {
-                    health: "unavailable",
-                    status: null,
-                    message: "Managed bitcoind status unavailable during hook inspection.",
-                },
-                nodeStatus: null,
-                nodeHealth: "unavailable",
-                indexer: {
-                    health: "unavailable",
-                    status: null,
-                    message: null,
-                    snapshotTip: null,
-                    source: "none",
-                    daemonInstanceId: null,
-                    snapshotSeq: null,
-                    openedAtUnixMs: null,
-                },
-                verify: parsed.verify,
-                paths: runtimePaths,
-            });
-            if (parsed.outputMode === "json") {
-                const result = buildHooksStatusJson(view);
-                writeJsonValue(context.stdout, createSuccessEnvelope("cogcoin/hooks-status/v1", describeCanonicalCommand(parsed), result.data, {
-                    warnings: result.warnings,
-                    explanations: result.explanations,
-                    nextSteps: result.nextSteps,
-                }));
-                return 0;
-            }
-            writeLine(context.stdout, formatHooksStatusReport(view));
-            return 0;
-        }
         if (parsed.command === "mine-log") {
             if (!parsed.follow) {
                 const allEvents = await context.readMiningLog({
@@ -128,15 +88,18 @@ export async function runMiningReadCommand(parsed, context) {
             }
             return 0;
         }
+        const provider = parsed.outputMode === "text"
+            ? withInteractiveWalletSecretProvider(context.walletSecretProvider, context.createPrompter())
+            : context.walletSecretProvider;
         const readContext = await context.openWalletReadContext({
             dataDir,
             databasePath: dbPath,
-            secretProvider: context.walletSecretProvider,
+            secretProvider: provider,
             paths: runtimePaths,
         });
         try {
             const mining = readContext.mining ?? await context.inspectMiningControlPlane({
-                provider: context.walletSecretProvider,
+                provider,
                 localState: readContext.localState,
                 bitcoind: readContext.bitcoind,
                 nodeStatus: readContext.nodeStatus,
@@ -163,11 +126,9 @@ export async function runMiningReadCommand(parsed, context) {
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         if (parsed.outputMode === "json") {
-            writeJsonValue(context.stdout, createErrorEnvelope(parsed.command === "hooks-mining-status"
-                ? "cogcoin/hooks-status/v1"
-                : parsed.command === "mine-log"
-                    ? "cogcoin/mine-log/v1"
-                    : "cogcoin/mine-status/v1", describeCanonicalCommand(parsed), message, message));
+            writeJsonValue(context.stdout, createErrorEnvelope(parsed.command === "mine-log"
+                ? "cogcoin/mine-log/v1"
+                : "cogcoin/mine-status/v1", describeCanonicalCommand(parsed), message, message));
             return 5;
         }
         writeLine(context.stderr, message);

package/dist/cli/commands/mining-runtime.js

@@ -5,19 +5,42 @@ import { writeLine } from "../io.js";
 import { createTerminalPrompter } from "../prompt.js";
 import { createPreviewSuccessEnvelope, createMutationSuccessEnvelope, describeCanonicalCommand, resolvePreviewJsonSchema, resolveStableMiningControlJsonSchema, writeHandledCliError, writeJsonValue, } from "../output.js";
 import { formatNextStepLines, getMineStopNextSteps, } from "../workflow-hints.js";
+import { withInteractiveWalletSecretProvider } from "../../wallet/state/provider.js";
 function createCommandPrompter(parsed, context) {
     return parsed.outputMode !== "text"
         ? createTerminalPrompter(context.stdin, context.stderr)
         : context.createPrompter();
 }
+async function prestartManagedMiningServices(options) {
+    let readContext = null;
+    try {
+        readContext = await options.context.openWalletReadContext({
+            dataDir: options.dataDir,
+            databasePath: options.databasePath,
+            secretProvider: options.provider,
+            paths: options.runtimePaths,
+        });
+    }
+    finally {
+        await readContext?.close();
+    }
+}
 export async function runMiningRuntimeCommand(parsed, context) {
     try {
         const dbPath = parsed.dbPath ?? context.resolveDefaultClientDatabasePath();
         const dataDir = parsed.dataDir ?? context.resolveDefaultBitcoindDataDir();
-        const provider = context.walletSecretProvider;
         const runtimePaths = context.resolveWalletRuntimePaths(parsed.seedName);
         await context.ensureDirectory(dirname(dbPath));
         if (parsed.command === "mine") {
+            const prompter = context.createPrompter();
+            const provider = withInteractiveWalletSecretProvider(context.walletSecretProvider, prompter);
+            await prestartManagedMiningServices({
+                context,
+                dataDir,
+                databasePath: dbPath,
+                provider,
+                runtimePaths,
+            });
             const abortController = new AbortController();
             const onStop = () => {
                 abortController.abort();
@@ -29,7 +52,7 @@ export async function runMiningRuntimeCommand(parsed, context) {
                     dataDir,
                     databasePath: dbPath,
                     provider,
-                    prompter: context.createPrompter(),
+                    prompter,
                     signal: abortController.signal,
                     stdout: context.stdout,
                     stderr: context.stderr,
@@ -44,11 +67,20 @@ export async function runMiningRuntimeCommand(parsed, context) {
             return 0;
         }
         if (parsed.command === "mine-start") {
+            const prompter = createCommandPrompter(parsed, context);
+            const provider = withInteractiveWalletSecretProvider(context.walletSecretProvider, prompter);
+            await prestartManagedMiningServices({
+                context,
+                dataDir,
+                databasePath: dbPath,
+                provider,
+                runtimePaths,
+            });
             const result = await context.startBackgroundMining({
                 dataDir,
                 databasePath: dbPath,
                 provider,
-                prompter: createCommandPrompter(parsed, context),
+                prompter,
                 paths: runtimePaths,
             });
             if (parsed.outputMode === "preview-json") {
@@ -73,6 +105,9 @@ export async function runMiningRuntimeCommand(parsed, context) {
             return 0;
         }
         if (parsed.command === "mine-stop") {
+            const provider = parsed.outputMode === "text"
+                ? withInteractiveWalletSecretProvider(context.walletSecretProvider, context.createPrompter())
+                : context.walletSecretProvider;
             const snapshot = await context.stopBackgroundMining({
                 dataDir,
                 databasePath: dbPath,

package/dist/cli/commands/service-runtime.js

@@ -38,8 +38,6 @@ async function resolveEffectiveWalletRootId(context) {
         paths: context.resolveWalletRuntimePaths(),
         provider: context.walletSecretProvider,
         loadRawWalletStateEnvelope: context.loadRawWalletStateEnvelope,
-        loadUnlockSession: context.loadUnlockSession,
-        loadWalletExplicitLock: context.loadWalletExplicitLock,
     }).catch(() => ({
         walletRootId: UNINITIALIZED_WALLET_ROOT_ID,
         source: "default-uninitialized",

package/dist/cli/commands/status.js

@@ -1,17 +1,22 @@
 import { dirname } from "node:path";
 import { buildStatusJson } from "../read-json.js";
-import { formatWalletOverviewReport } from "../wallet-format.js";
+import { formatBalanceReport, formatWalletOverviewReport } from "../wallet-format.js";
 import { writeLine } from "../io.js";
+import { createTerminalPrompter } from "../prompt.js";
 import { createSuccessEnvelope, describeCanonicalCommand, writeJsonValue } from "../output.js";
+import { withInteractiveWalletSecretProvider } from "../../wallet/state/provider.js";
 export async function runStatusCommand(parsed, context) {
     const dbPath = parsed.dbPath ?? context.resolveDefaultClientDatabasePath();
     const dataDir = parsed.dataDir ?? context.resolveDefaultBitcoindDataDir();
     const runtimePaths = context.resolveWalletRuntimePaths(parsed.seedName);
     await context.ensureDirectory(dirname(dbPath));
+    const provider = parsed.outputMode === "text"
+        ? withInteractiveWalletSecretProvider(context.walletSecretProvider, context.createPrompter?.() ?? createTerminalPrompter(context.stdin, context.stdout))
+        : context.walletSecretProvider;
     const readContext = await context.openWalletReadContext({
         dataDir,
         databasePath: dbPath,
-        secretProvider: context.walletSecretProvider,
+        secretProvider: provider,
         paths: runtimePaths,
     });
     try {
@@ -25,6 +30,7 @@ export async function runStatusCommand(parsed, context) {
             return 0;
         }
         writeLine(context.stdout, formatWalletOverviewReport(readContext, await context.readPackageVersion()));
+        writeLine(context.stdout, formatBalanceReport(readContext));
         return 0;
     }
     finally {

package/dist/cli/commands/sync.js

@@ -3,10 +3,29 @@ import { formatManagedSyncErrorMessage } from "../../bitcoind/errors.js";
 import { formatBytes, formatDuration } from "../../bitcoind/progress/formatting.js";
 import { FileLockBusyError, acquireFileLock } from "../../wallet/fs/lock.js";
 import { resolveWalletRootIdFromLocalArtifacts } from "../../wallet/root-resolution.js";
+import { withInteractiveWalletSecretProvider } from "../../wallet/state/provider.js";
 import { usesTtyProgress, writeLine } from "../io.js";
 import { classifyCliError, formatCliTextError } from "../output.js";
+import { createTerminalPrompter } from "../prompt.js";
 import { createStopSignalWatcher, waitForCompletionOrStop } from "../signals.js";
+import { formatBalanceReport } from "../wallet-format.js";
 const SYNC_PROGRESS_LOG_INTERVAL_MS = 5_000;
+async function writePostSyncBalanceReport(options) {
+    const provider = withInteractiveWalletSecretProvider(options.context.walletSecretProvider, options.context.createPrompter?.() ?? createTerminalPrompter(options.context.stdin, options.context.stdout));
+    const readContext = await options.context.openWalletReadContext({
+        dataDir: options.dataDir,
+        databasePath: options.databasePath,
+        secretProvider: provider,
+        walletControlLockHeld: true,
+        paths: options.runtimePaths,
+    });
+    try {
+        writeLine(options.context.stdout, formatBalanceReport(readContext));
+    }
+    finally {
+        await readContext.close().catch(() => undefined);
+    }
+}
 function createSyncProgressReporter(options) {
     let lastPhase = null;
     let lastMessage = "";
@@ -104,13 +123,13 @@ export async function runSyncCommand(parsed, context) {
     let controlLock = null;
     let store = null;
     let storeOwned = true;
+    let client = null;
+    let clientClosed = false;
     try {
         const walletRoot = await resolveWalletRootIdFromLocalArtifacts({
             paths: runtimePaths,
             provider: context.walletSecretProvider,
             loadRawWalletStateEnvelope: context.loadRawWalletStateEnvelope,
-            loadUnlockSession: context.loadUnlockSession,
-            loadWalletExplicitLock: context.loadWalletExplicitLock,
         });
         try {
             controlLock = await acquireFileLock(runtimePaths.walletControlLockPath, {
@@ -126,7 +145,7 @@ export async function runSyncCommand(parsed, context) {
         }
         await context.ensureDirectory(dirname(dbPath));
         store = await context.openSqliteStore({ filename: dbPath });
-        const client = await context.openManagedBitcoindClient({
+        client = await context.openManagedBitcoindClient({
             store,
             databasePath: dbPath,
             dataDir,
@@ -147,6 +166,32 @@ export async function runSyncCommand(parsed, context) {
                 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") {
@@ -161,7 +206,9 @@ export async function runSyncCommand(parsed, context) {
         }
         finally {
             stopWatcher.cleanup();
-            await client.close();
+            if (!clientClosed) {
+                await client.close();
+            }
         }
     }
     catch (error) {