@cogcoin/client 0.5.11 → 0.5.13

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@0.5.11` is the store-backed Cogcoin client package for applications that want a local wallet, durable SQLite-backed state, and a managed Bitcoin Core integration around `@cogcoin/indexer`. It publishes the reusable client APIs, the SQLite adapter, the managed `bitcoind` integration, and the first-party `cogcoin` CLI in one package.
+`@cogcoin/client@0.5.13` is the store-backed Cogcoin client package for applications that want a local wallet, durable SQLite-backed state, and a managed Bitcoin Core integration around `@cogcoin/indexer`. It publishes the reusable client APIs, the SQLite adapter, the managed `bitcoind` integration, and the first-party `cogcoin` CLI in one package.
 
 Use Node 22 or newer.
 
@@ -81,6 +81,8 @@ The installed `cogcoin` command covers the first-party local wallet and node wor
 - mining and hook commands such as `mine`, `mine start`, `mine stop`, `mine status`, `mine log`, `mine setup`, and `hooks status`
 
 The CLI also supports stable `--output json` and `--output preview-json` envelopes on the commands that advertise machine-readable output.
+Interactive text invocations periodically check the npm registry for newer `@cogcoin/client` releases and print `npm install -g @cogcoin/client` when a newer version is available.
+Set `COGCOIN_DISABLE_UPDATE_CHECK=1` to disable the CLI update notice entirely.
 Ordinary `sync`, `follow`, and wallet-aware read/status flows detach from the managed Bitcoin and indexer services on exit instead of stopping them.
 Use the explicit `bitcoin ...` and `indexer ...` commands when you want direct service inspection or start/stop control.
 For provider-backed local wallets, normal reads, mutations, export, and mining setup flows auto-materialize a local unlock session when the wallet is not explicitly locked.

package/dist/app-paths.d.ts

@@ -39,3 +39,4 @@ export declare function resolveCogcoinAppRootForTesting(resolution?: CogcoinPath
 export declare function resolveDefaultBitcoindDataDirForTesting(resolution?: CogcoinPathResolution): string;
 export declare function resolveDefaultClientDatabasePathForTesting(resolution?: CogcoinPathResolution): string;
 export declare function resolveDefaultClientDatabaseDirectoryForTesting(resolution?: CogcoinPathResolution): string;
+export declare function resolveDefaultUpdateCheckStatePathForTesting(resolution?: CogcoinPathResolution): string;

package/dist/app-paths.js

@@ -125,3 +125,6 @@ export function resolveDefaultClientDatabaseDirectoryForTesting(resolution = {})
     const dbPath = resolveDefaultClientDatabasePathForTesting(resolution);
     return platform === "win32" ? win32Path.dirname(dbPath) : dirname(dbPath);
 }
+export function resolveDefaultUpdateCheckStatePathForTesting(resolution = {}) {
+    return joinForPlatform(resolution.platform ?? process.platform, resolveCogcoinPathsForTesting(resolution).stateRoot, "update-check.json");
+}

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

@@ -3,6 +3,7 @@ import { ManagedProgressController } from "../progress.js";
 import { BitcoinRpcClient } from "../rpc.js";
 import { type ManagedRpcRetryState } from "../retryable-rpc.js";
 import type { BootstrapPhase, SnapshotMetadata, SnapshotChunkManifest } from "../types.js";
+type ResumeDisplayMode = "sync" | "follow";
 export declare class AssumeUtxoBootstrapController {
     #private;
     constructor(options: {
@@ -18,6 +19,7 @@ export declare class AssumeUtxoBootstrapController {
     ensureReady(indexedTip: ClientTip | null, expectedChain: "main" | "regtest", options?: {
         signal?: AbortSignal;
         retryState?: ManagedRpcRetryState;
+        resumeDisplayMode?: ResumeDisplayMode;
     }): Promise<void>;
     getStateForTesting(): Promise<{
         metadataVersion: number;
@@ -35,3 +37,4 @@ export declare class AssumeUtxoBootstrapController {
         updatedAt: number;
     }>;
 }
+export {};

package/dist/bitcoind/bootstrap/controller.js

@@ -44,11 +44,13 @@ export class AssumeUtxoBootstrapController {
             return;
         }
         if (indexedTip !== null) {
-            await this.#progress.setPhase("follow_tip", {
-                blocks: indexedTip.height,
-                targetHeight: indexedTip.height,
-                message: "Resuming from the persisted Cogcoin indexed tip.",
-            });
+            if ((options.resumeDisplayMode ?? "sync") === "follow") {
+                await this.#progress.setPhase("follow_tip", {
+                    blocks: indexedTip.height,
+                    targetHeight: indexedTip.height,
+                    message: "Resuming from the persisted Cogcoin indexed tip.",
+                });
+            }
             return;
         }
         const { state, snapshotIdentity } = await this.#loadStateRecord();

package/dist/bitcoind/client/factory.d.ts

@@ -1,3 +1,11 @@
+import { stopIndexerDaemonService, type IndexerDaemonClient } from "../indexer-daemon.js";
 import type { InternalManagedBitcoindOptions, ManagedBitcoindClient } from "../types.js";
+export declare function pauseIndexerDaemonForForegroundClientForTesting(options: {
+    daemon: IndexerDaemonClient;
+    dataDir: string;
+    walletRootId: string;
+    shutdownTimeoutMs?: number;
+    stopDaemon?: typeof stopIndexerDaemonService;
+}): Promise<IndexerDaemonClient | null>;
 export declare function openManagedBitcoindClient(options: Omit<InternalManagedBitcoindOptions, "chain" | "startHeight">): Promise<ManagedBitcoindClient>;
 export declare function openManagedBitcoindClientInternal(options: InternalManagedBitcoindOptions): Promise<ManagedBitcoindClient>;

package/dist/bitcoind/client/factory.js

@@ -2,13 +2,46 @@ import { loadBundledGenesisParameters } from "@cogcoin/indexer";
 import { resolveDefaultBitcoindDataDirForTesting } from "../../app-paths.js";
 import { openClient } from "../../client.js";
 import { AssumeUtxoBootstrapController, DEFAULT_SNAPSHOT_METADATA, resolveBootstrapPathsForTesting, } from "../bootstrap.js";
-import { attachOrStartIndexerDaemon } from "../indexer-daemon.js";
+import { attachOrStartIndexerDaemon, stopIndexerDaemonService, } from "../indexer-daemon.js";
 import { createRpcClient } from "../node.js";
 import { assertCogcoinProcessingStartHeight, resolveCogcoinProcessingStartHeight, } from "../processing-start-height.js";
 import { ManagedProgressController } from "../progress.js";
 import { attachOrStartManagedBitcoindService, } from "../service.js";
 import { DefaultManagedBitcoindClient } from "./managed-client.js";
 const DEFAULT_SYNC_DEBOUNCE_MS = 250;
+function isRecoverableIndexerDaemonPauseError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    if (error.message === "indexer_daemon_request_timeout"
+        || error.message === "indexer_daemon_connection_closed"
+        || error.message === "indexer_daemon_protocol_error") {
+        return true;
+    }
+    if ("code" in error) {
+        const code = error.code;
+        return code === "ENOENT" || code === "ECONNREFUSED" || code === "ECONNRESET";
+    }
+    return false;
+}
+export async function pauseIndexerDaemonForForegroundClientForTesting(options) {
+    try {
+        await options.daemon.pauseBackgroundFollow();
+        return options.daemon;
+    }
+    catch (error) {
+        await options.daemon.close().catch(() => undefined);
+        if (!isRecoverableIndexerDaemonPauseError(error)) {
+            throw error;
+        }
+        await (options.stopDaemon ?? stopIndexerDaemonService)({
+            dataDir: options.dataDir,
+            walletRootId: options.walletRootId,
+            shutdownTimeoutMs: options.shutdownTimeoutMs,
+        });
+        return null;
+    }
+}
 async function createManagedBitcoindClient(options) {
     const genesisParameters = options.genesisParameters ?? await loadBundledGenesisParameters();
     assertCogcoinProcessingStartHeight({
@@ -51,14 +84,18 @@ async function createManagedBitcoindClient(options) {
             snapshotInterval: options.snapshotInterval,
         });
         const indexerDaemon = options.databasePath
-            ? await attachOrStartIndexerDaemon({
+            ? await pauseIndexerDaemonForForegroundClientForTesting({
+                daemon: await attachOrStartIndexerDaemon({
+                    dataDir,
+                    databasePath: options.databasePath,
+                    walletRootId: options.walletRootId,
+                    startupTimeoutMs: options.startupTimeoutMs,
+                }),
                 dataDir,
-                databasePath: options.databasePath,
-                walletRootId: options.walletRootId,
-                startupTimeoutMs: options.startupTimeoutMs,
+                walletRootId,
+                shutdownTimeoutMs: options.shutdownTimeoutMs,
             })
             : null;
-        await indexerDaemon?.pauseBackgroundFollow();
         // The persistent service may already exist from a non-processing attach path
         // that used startHeight 0. Cogcoin replay still begins at the requested
         // processing boundary for this managed client.

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

@@ -292,7 +292,10 @@ export class DefaultManagedBitcoindClient {
     async #ensureBootstrapReady(signal) {
         await this.#node.validate();
         const indexedTipBeforeBootstrap = await this.#client.getTip();
-        await this.#bootstrap.ensureReady(indexedTipBeforeBootstrap, this.#node.expectedChain, { signal });
+        await this.#bootstrap.ensureReady(indexedTipBeforeBootstrap, this.#node.expectedChain, {
+            signal,
+            resumeDisplayMode: this.#following ? "follow" : "sync",
+        });
     }
     async #restartManagedNodeWithRange(readyRange, abortSignal) {
         if (abortSignal.aborted) {
@@ -372,19 +375,25 @@ export class DefaultManagedBitcoindClient {
         }
     }
     async #resumeIndexerBackgroundFollow() {
-        if (this.#indexerDaemon === null) {
+        if (this.#indexerDaemon === null && this.#reattachIndexerDaemon === null) {
             return;
         }
-        try {
-            await this.#indexerDaemon.resumeBackgroundFollow();
-            return;
-        }
-        catch (error) {
-            if (this.#reattachIndexerDaemon === null) {
-                throw error;
+        if (this.#indexerDaemon !== null) {
+            try {
+                await this.#indexerDaemon.resumeBackgroundFollow();
+                return;
             }
+            catch (error) {
+                if (this.#reattachIndexerDaemon === null) {
+                    throw error;
+                }
+            }
+        }
+        const reattachIndexerDaemon = this.#reattachIndexerDaemon;
+        if (reattachIndexerDaemon === null) {
+            return;
         }
-        const replacementDaemon = await this.#reattachIndexerDaemon();
+        const replacementDaemon = await reattachIndexerDaemon();
         this.#indexerDaemon = replacementDaemon;
         await replacementDaemon?.resumeBackgroundFollow();
     }

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

@@ -4,6 +4,7 @@ import { normalizeRpcBlock } from "../normalize.js";
 import { MANAGED_RPC_RETRY_MESSAGE, consumeManagedRpcRetryDelayMs, createManagedRpcRetryState, describeManagedRpcRetryError, isRetryableManagedRpcError, resetManagedRpcRetryState, } from "../retryable-rpc.js";
 import { estimateEtaSeconds } from "./rate-tracker.js";
 const DEFAULT_SYNC_CATCH_UP_POLL_MS = 2_000;
+const BITCOIN_SYNC_PHASE_DEBOUNCE_MS = DEFAULT_SYNC_CATCH_UP_POLL_MS * 3;
 function createAbortError(signal) {
     const reason = signal?.reason;
     if (reason instanceof Error) {
@@ -53,6 +54,22 @@ async function setBitcoinSyncProgress(dependencies, info, targetHeightCap) {
             : "Reading blocks from the managed Bitcoin node.",
     });
 }
+function resolveIndexedHeightForReplayWindow(tip, startHeight) {
+    return tip?.height ?? (startHeight - 1);
+}
+function hasPendingCogcoinReplay(tip, startHeight, bestHeight) {
+    if (bestHeight < startHeight) {
+        return false;
+    }
+    return resolveIndexedHeightForReplayWindow(tip, startHeight) < bestHeight;
+}
+function shouldPreserveCogcoinSyncPhase(dependencies) {
+    const status = dependencies.progress.getStatusSnapshot();
+    // Keep the TTY on Cogcoin replay through brief idle gaps so it does not
+    // bounce back to Bitcoin sync between closely spaced replay passes.
+    return status.bootstrapPhase === "cogcoin_sync"
+        && Date.now() - status.bootstrapProgress.updatedAt < BITCOIN_SYNC_PHASE_DEBOUNCE_MS;
+}
 async function setRetryingProgress(dependencies, error) {
     const status = dependencies.progress.getStatusSnapshot();
     const { phase: _phase, updatedAt: _updatedAt, ...progress } = status.bootstrapProgress;
@@ -152,6 +169,7 @@ export async function syncToTip(dependencies) {
         await runRpc(() => dependencies.bootstrap.ensureReady(indexedTipBeforeBootstrap, dependencies.node.expectedChain, {
             signal: dependencies.abortSignal,
             retryState,
+            resumeDisplayMode: dependencies.isFollowing() ? "follow" : "sync",
         }));
         if (dependencies.node.expectedChain === "main"
             && dependencies.node.getblockArchiveEndHeight !== null) {
@@ -175,7 +193,11 @@ export async function syncToTip(dependencies) {
             const cappedBestHeight = dependencies.targetHeightCap === null || dependencies.targetHeightCap === undefined
                 ? startInfo.blocks
                 : Math.min(startInfo.blocks, dependencies.targetHeightCap);
-            await setBitcoinSyncProgress(dependencies, startInfo, dependencies.targetHeightCap ?? null);
+            const tipBeforePass = await dependencies.client.getTip();
+            if (!hasPendingCogcoinReplay(tipBeforePass, dependencies.startHeight, cappedBestHeight)
+                && !shouldPreserveCogcoinSyncPhase(dependencies)) {
+                await setBitcoinSyncProgress(dependencies, startInfo, dependencies.targetHeightCap ?? null);
+            }
             const pass = await syncAgainstBestHeight(dependencies, cappedBestHeight, runRpc);
             aggregate.appliedBlocks += pass.appliedBlocks;
             aggregate.rewoundBlocks += pass.rewoundBlocks;
@@ -193,8 +215,15 @@ export async function syncToTip(dependencies) {
             aggregate.endingHeight = finalTip?.height ?? null;
             aggregate.bestHeight = endBestHeight;
             aggregate.bestHashHex = endInfo.bestblockhash;
-            if ((dependencies.targetHeightCap !== null && dependencies.targetHeightCap !== undefined && caughtUpCogcoin)
-                || (endInfo.blocks === endInfo.headers && caughtUpCogcoin)) {
+            const reachedTargetHeightCap = dependencies.targetHeightCap !== null
+                && dependencies.targetHeightCap !== undefined
+                && endBestHeight >= dependencies.targetHeightCap;
+            if (reachedTargetHeightCap && caughtUpCogcoin) {
+                return aggregate;
+            }
+            if (dependencies.targetHeightCap === null
+                && endInfo.blocks === endInfo.headers
+                && caughtUpCogcoin) {
                 if (dependencies.isFollowing()) {
                     dependencies.progress.replaceFollowBlockTimes(await runRpc(() => dependencies.loadVisibleFollowBlockTimes(finalTip)));
                 }
@@ -209,10 +238,12 @@ export async function syncToTip(dependencies) {
                 });
                 return aggregate;
             }
-            await setBitcoinSyncProgress(dependencies, endInfo, dependencies.targetHeightCap ?? null);
             if (endBestHeight >= dependencies.startHeight && finalTip?.height !== endBestHeight) {
                 continue;
             }
+            if (!shouldPreserveCogcoinSyncPhase(dependencies)) {
+                await setBitcoinSyncProgress(dependencies, endInfo, dependencies.targetHeightCap ?? null);
+            }
             await sleep(DEFAULT_SYNC_CATCH_UP_POLL_MS, dependencies.abortSignal);
         }
     }

package/dist/bitcoind/progress/formatting.js

@@ -144,7 +144,7 @@ export function resolveStatusFieldText(progress, snapshotHeight, now = 0) {
         case "follow_tip":
             return `Waiting for next block to be mined${animateStatusEllipsis(now)}`;
         case "complete":
-            return `Syncing Cogcoin Blocks${animateStatusEllipsis(now)}`;
+            return `Sync complete${animateStatusEllipsis(now)}`;
         case "error":
             return progress.lastError === null
                 ? progress.message

package/dist/bitcoind/testing.d.ts

@@ -1,5 +1,6 @@
 export { openManagedBitcoindClientInternal } from "./client.js";
 export { DefaultManagedBitcoindClient } from "./client/managed-client.js";
+export { pauseIndexerDaemonForForegroundClientForTesting } from "./client/factory.js";
 export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, stopIndexerDaemonService, shutdownIndexerDaemonForTesting, } from "./indexer-daemon.js";
 export { normalizeRpcBlock } from "./normalize.js";
 export { BitcoinRpcClient } from "./rpc.js";

package/dist/bitcoind/testing.js

@@ -1,5 +1,6 @@
 export { openManagedBitcoindClientInternal } from "./client.js";
 export { DefaultManagedBitcoindClient } from "./client/managed-client.js";
+export { pauseIndexerDaemonForForegroundClientForTesting } from "./client/factory.js";
 export { attachOrStartIndexerDaemon, readIndexerDaemonStatusForTesting, stopIndexerDaemonService, shutdownIndexerDaemonForTesting, } from "./indexer-daemon.js";
 export { normalizeRpcBlock } from "./normalize.js";
 export { BitcoinRpcClient } from "./rpc.js";

package/dist/cli/commands/follow.js

@@ -1,22 +1,38 @@
 import { dirname } from "node:path";
+import { FileLockBusyError, acquireFileLock } from "../../wallet/fs/lock.js";
 import { resolveWalletRootIdFromLocalArtifacts } from "../../wallet/root-resolution.js";
 import { usesTtyProgress, writeLine } from "../io.js";
-import { classifyCliError } from "../output.js";
+import { classifyCliError, formatCliTextError } from "../output.js";
 import { createStopSignalWatcher } from "../signals.js";
 export async function runFollowCommand(parsed, context) {
     const dbPath = parsed.dbPath ?? context.resolveDefaultClientDatabasePath();
     const dataDir = parsed.dataDir ?? context.resolveDefaultBitcoindDataDir();
-    const walletRoot = await resolveWalletRootIdFromLocalArtifacts({
-        paths: context.resolveWalletRuntimePaths(),
-        provider: context.walletSecretProvider,
-        loadRawWalletStateEnvelope: context.loadRawWalletStateEnvelope,
-        loadUnlockSession: context.loadUnlockSession,
-        loadWalletExplicitLock: context.loadWalletExplicitLock,
-    });
-    await context.ensureDirectory(dirname(dbPath));
-    const store = await context.openSqliteStore({ filename: dbPath });
+    const runtimePaths = context.resolveWalletRuntimePaths();
+    let controlLock = null;
+    let store = null;
     let storeOwned = true;
     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, {
+                purpose: "managed-follow",
+                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 });
         const client = await context.openManagedBitcoindClient({
             store,
             databasePath: dbPath,
@@ -25,7 +41,7 @@ export async function runFollowCommand(parsed, context) {
             progressOutput: parsed.progressOutput,
         });
         storeOwned = false;
-        const stopWatcher = createStopSignalWatcher(context.signalSource, context.stderr, client, context.forceExit);
+        const stopWatcher = createStopSignalWatcher(context.signalSource, context.stderr, client, context.forceExit, [runtimePaths.walletControlLockPath]);
         try {
             await client.startFollowingTip();
             if (!usesTtyProgress(parsed.progressOutput, context.stderr)) {
@@ -43,10 +59,27 @@ export async function runFollowCommand(parsed, context) {
         }
     }
     catch (error) {
-        writeLine(context.stderr, `follow failed: ${error instanceof Error ? error.message : String(error)}`);
-        if (storeOwned) {
+        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 {
+            writeLine(context.stderr, `follow failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (storeOwned && store !== null) {
             await store.close().catch(() => undefined);
         }
-        return classifyCliError(error).exitCode;
+        return classified.exitCode;
+    }
+    finally {
+        await controlLock?.release().catch(() => undefined);
     }
 }

package/dist/cli/commands/sync.js

@@ -1,23 +1,39 @@
 import { dirname } from "node:path";
 import { formatManagedSyncErrorMessage } from "../../bitcoind/errors.js";
+import { FileLockBusyError, acquireFileLock } from "../../wallet/fs/lock.js";
 import { resolveWalletRootIdFromLocalArtifacts } from "../../wallet/root-resolution.js";
 import { writeLine } from "../io.js";
-import { classifyCliError } from "../output.js";
+import { classifyCliError, formatCliTextError } from "../output.js";
 import { createStopSignalWatcher, waitForCompletionOrStop } from "../signals.js";
 export async function runSyncCommand(parsed, context) {
     const dbPath = parsed.dbPath ?? context.resolveDefaultClientDatabasePath();
     const dataDir = parsed.dataDir ?? context.resolveDefaultBitcoindDataDir();
-    const walletRoot = await resolveWalletRootIdFromLocalArtifacts({
-        paths: context.resolveWalletRuntimePaths(),
-        provider: context.walletSecretProvider,
-        loadRawWalletStateEnvelope: context.loadRawWalletStateEnvelope,
-        loadUnlockSession: context.loadUnlockSession,
-        loadWalletExplicitLock: context.loadWalletExplicitLock,
-    });
-    await context.ensureDirectory(dirname(dbPath));
-    const store = await context.openSqliteStore({ filename: dbPath });
+    const runtimePaths = context.resolveWalletRuntimePaths();
+    let controlLock = null;
+    let store = null;
     let storeOwned = true;
     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, {
+                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 });
         const client = await context.openManagedBitcoindClient({
             store,
             databasePath: dbPath,
@@ -26,7 +42,7 @@ export async function runSyncCommand(parsed, context) {
             progressOutput: parsed.progressOutput,
         });
         storeOwned = false;
-        const stopWatcher = createStopSignalWatcher(context.signalSource, context.stderr, client, context.forceExit);
+        const stopWatcher = createStopSignalWatcher(context.signalSource, context.stderr, client, context.forceExit, [runtimePaths.walletControlLockPath]);
         try {
             const syncOutcome = await waitForCompletionOrStop(client.syncToTip(), stopWatcher);
             if (syncOutcome.kind === "stopped") {
@@ -51,11 +67,28 @@ export async function runSyncCommand(parsed, context) {
         }
     }
     catch (error) {
-        const message = formatManagedSyncErrorMessage(error instanceof Error ? error.message : String(error));
-        writeLine(context.stderr, `sync failed: ${message}`);
-        if (storeOwned) {
+        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 classifyCliError(error).exitCode;
+        return classified.exitCode;
+    }
+    finally {
+        await controlLock?.release().catch(() => undefined);
     }
 }

package/dist/cli/context.js

@@ -2,7 +2,7 @@ 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, } from "../app-paths.js";
+import { resolveDefaultBitcoindDataDirForTesting, resolveDefaultClientDatabasePathForTesting, resolveDefaultUpdateCheckStatePathForTesting, } from "../app-paths.js";
 import { openManagedBitcoindClient } from "../bitcoind/index.js";
 import { inspectPassiveClientStatus } from "../passive-status.js";
 import { openSqliteStore } from "../sqlite/index.js";
@@ -26,10 +26,13 @@ export function createDefaultContext(overrides = {}) {
         stdout: overrides.stdout ?? process.stdout,
         stderr: overrides.stderr ?? process.stderr,
         stdin: overrides.stdin ?? process.stdin,
+        env: overrides.env ?? process.env,
+        now: overrides.now ?? (() => Date.now()),
         signalSource: overrides.signalSource ?? process,
         forceExit: overrides.forceExit ?? ((code) => {
             process.exit(code);
         }),
+        fetchImpl: overrides.fetchImpl ?? fetch,
         openSqliteStore: overrides.openSqliteStore ?? openSqliteStore,
         openManagedBitcoindClient: overrides.openManagedBitcoindClient ?? openManagedBitcoindClient,
         inspectPassiveClientStatus: overrides.inspectPassiveClientStatus ?? inspectPassiveClientStatus,
@@ -96,6 +99,7 @@ export function createDefaultContext(overrides = {}) {
         loadWalletExplicitLock: overrides.loadWalletExplicitLock ?? loadWalletExplicitLock,
         resolveDefaultBitcoindDataDir: overrides.resolveDefaultBitcoindDataDir ?? resolveDefaultBitcoindDataDirForTesting,
         resolveDefaultClientDatabasePath: overrides.resolveDefaultClientDatabasePath ?? resolveDefaultClientDatabasePathForTesting,
+        resolveUpdateCheckStatePath: overrides.resolveUpdateCheckStatePath ?? resolveDefaultUpdateCheckStatePathForTesting,
         resolveWalletRuntimePaths: overrides.resolveWalletRuntimePaths ?? ((seedName) => resolveWalletRuntimePathsForTesting({ seedName })),
     };
 }

package/dist/cli/output.js

@@ -187,6 +187,10 @@ export function classifyCliError(error) {
     return { exitCode: 5, errorCode: message, message };
 }
 function isBlockedError(message) {
+    if (message === "wallet_control_lock_busy"
+        || message.startsWith("file_lock_busy_")) {
+        return true;
+    }
     if (message === "wallet_locked"
         || message === "wallet_uninitialized"
         || message === "local-state-corrupt"
@@ -239,6 +243,13 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
             next: "Run `cogcoin unlock --for 15m` and retry.",
         };
     }
+    if (errorCode === "wallet_control_lock_busy") {
+        return {
+            what: "Another Cogcoin command is already controlling this wallet.",
+            why: "Commands that sync, follow, or mutate the local index take an exclusive wallet control lock so they do not write the same sqlite store concurrently.",
+            next: "Wait for the other Cogcoin command to finish, or stop it cleanly before retrying.",
+        };
+    }
     if (errorCode === "reset_wallet_choice_invalid") {
         return {
             what: "Wallet reset choice is invalid.",

package/dist/cli/runner.js

@@ -12,6 +12,7 @@ import { runSyncCommand } from "./commands/sync.js";
 import { runWalletAdminCommand } from "./commands/wallet-admin.js";
 import { runWalletMutationCommand } from "./commands/wallet-mutation.js";
 import { runWalletReadCommand } from "./commands/wallet-read.js";
+import { maybeNotifyAboutCliUpdate } from "./update-notifier.js";
 import { findWalletSeedRecord, loadWalletSeedIndex } from "../wallet/state/seed-index.js";
 function commandUsesExistingWalletSeed(parsed) {
     return parsed.seedName !== null
@@ -48,6 +49,7 @@ export async function runCli(argv, contextOverrides = {}) {
         writeLine(context.stdout, HELP_TEXT.trimEnd());
         return parsed.help ? 0 : 2;
     }
+    await maybeNotifyAboutCliUpdate(parsed, context);
     try {
         if (commandUsesExistingWalletSeed(parsed)) {
             const mainPaths = context.resolveWalletRuntimePaths("main");

package/dist/cli/signals.d.ts

@@ -1,4 +1,4 @@
 import type { InterruptibleOutcome, ManagedClientLike, SignalSource, StopSignalWatcher, WritableLike } from "./types.js";
-export declare function createStopSignalWatcher(signalSource: SignalSource, stderr: WritableLike, client: ManagedClientLike, forceExit: (code: number) => never | void): StopSignalWatcher;
+export declare function createStopSignalWatcher(signalSource: SignalSource, stderr: WritableLike, client: ManagedClientLike, forceExit: (code: number) => never | void, lockPaths?: readonly string[]): StopSignalWatcher;
 export declare function createOwnedLockCleanupSignalWatcher(signalSource: SignalSource, forceExit: (code: number) => never | void, lockPaths: readonly string[]): StopSignalWatcher;
 export declare function waitForCompletionOrStop<T>(promise: Promise<T>, stopWatcher: StopSignalWatcher): Promise<InterruptibleOutcome<T>>;

package/dist/cli/signals.js

@@ -1,6 +1,6 @@
 import { writeLine } from "./io.js";
 import { clearLockIfOwnedByCurrentProcess } from "../wallet/fs/lock.js";
-export function createStopSignalWatcher(signalSource, stderr, client, forceExit) {
+export function createStopSignalWatcher(signalSource, stderr, client, forceExit, lockPaths = []) {
     let closing = false;
     let resolved = false;
     let onSignal = () => { };
@@ -17,16 +17,23 @@ export function createStopSignalWatcher(signalSource, stderr, client, forceExit)
             cleanup();
             resolve(code);
         };
+        const releaseOwnedLocks = async () => {
+            await Promise.allSettled([...new Set(lockPaths)].map(async (lockPath) => {
+                await clearLockIfOwnedByCurrentProcess(lockPath);
+            }));
+        };
         const onFirstSignal = () => {
             closing = true;
             writeLine(stderr, "Detaching from managed Cogcoin client and resuming background indexer follow...");
-            void client.close().then(() => {
+            void client.close().then(async () => {
+                await releaseOwnedLocks();
                 if (resolved) {
                     return;
                 }
                 writeLine(stderr, "Detached cleanly; background indexer follow resumed.");
                 settle(0);
-            }, () => {
+            }, async () => {
+                await releaseOwnedLocks();
                 if (resolved) {
                     return;
                 }
@@ -40,7 +47,13 @@ export function createStopSignalWatcher(signalSource, stderr, client, forceExit)
                 return;
             }
             settle(130);
-            forceExit(130);
+            if (lockPaths.length === 0) {
+                forceExit(130);
+                return;
+            }
+            void releaseOwnedLocks().finally(() => {
+                forceExit(130);
+            });
         };
     });
     signalSource.on("SIGINT", onSignal);

package/dist/cli/types.d.ts

@@ -87,8 +87,11 @@ export interface CliRunnerContext {
     stdout?: WritableLike;
     stderr?: WritableLike;
     stdin?: ReadableLike;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
     signalSource?: SignalSource;
     forceExit?: (code: number) => never | void;
+    fetchImpl?: typeof fetch;
     openSqliteStore?: typeof openSqliteStore;
     openManagedBitcoindClient?: (options: {
         store: ClientStoreAdapter;
@@ -163,6 +166,7 @@ export interface CliRunnerContext {
     readPackageVersion?: () => Promise<string>;
     resolveDefaultBitcoindDataDir?: () => string;
     resolveDefaultClientDatabasePath?: () => string;
+    resolveUpdateCheckStatePath?: () => string;
     resolveWalletRuntimePaths?: (seedName?: string | null) => WalletRuntimePaths;
 }
 export interface StopSignalWatcher {