@cogcoin/client 1.0.1 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@1.0.0` is the reference 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@1.0.2` is the reference 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.
 
@@ -130,6 +130,7 @@ Managed node subpath:
 
 The installed `cogcoin` command covers the first-party local wallet and node workflow:
 
+- update commands such as `update` to compare the current CLI version with the latest npm release and install it
 - wallet lifecycle commands such as `init`, `restore`, `wallet delete`, `wallet show-mnemonic`, and `repair`
 - sync and service commands such as `status`, `sync`, `follow`, `bitcoin start`, `bitcoin stop`, `bitcoin status`, `indexer start`, `indexer stop`, and `indexer status`
 - domain and field commands such as `register`, `anchor`, `show`, `domains`, `fields`, `buy`, `sell`, and `transfer`

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

@@ -84,6 +84,7 @@ export interface CoherentIndexerSnapshotLease {
     payload: IndexerSnapshotPayload;
     status: ManagedIndexerDaemonStatus;
 }
+type ManagedIndexerDaemonServiceLifetime = "persistent" | "ephemeral";
 export declare function stopIndexerDaemonServiceWithLockHeld(options: {
     dataDir: string;
     walletRootId?: string;
@@ -104,6 +105,8 @@ export declare function attachOrStartIndexerDaemon(options: {
     databasePath: string;
     walletRootId?: string;
     startupTimeoutMs?: number;
+    shutdownTimeoutMs?: number;
+    serviceLifetime?: ManagedIndexerDaemonServiceLifetime;
 }): Promise<IndexerDaemonClient>;
 export declare function stopIndexerDaemonService(options: {
     dataDir: string;

package/dist/bitcoind/indexer-daemon.js

@@ -80,7 +80,8 @@ export async function stopIndexerDaemonServiceWithLockHeld(options) {
         walletRootId,
     };
 }
-function createIndexerDaemonClient(socketPath) {
+function createIndexerDaemonClient(socketPath, closeOptions = null) {
+    let closed = false;
     async function sendRequest(request) {
         return new Promise((resolve, reject) => {
             const socket = net.createConnection(socketPath);
@@ -181,7 +182,18 @@ function createIndexerDaemonClient(socketPath) {
             });
         },
         async close() {
-            return;
+            if (closed) {
+                return;
+            }
+            closed = true;
+            if (closeOptions === null || closeOptions.serviceLifetime !== "ephemeral" || closeOptions.ownership === "attached") {
+                return;
+            }
+            await stopIndexerDaemonService({
+                dataDir: closeOptions.dataDir,
+                walletRootId: closeOptions.walletRootId,
+                shutdownTimeoutMs: closeOptions.shutdownTimeoutMs,
+            });
         },
     };
 }
@@ -308,7 +320,8 @@ async function waitForIndexerDaemon(dataDir, walletRootId, timeoutMs) {
     while (Date.now() < deadline) {
         const probe = await probeIndexerDaemonAtSocket(paths.indexerDaemonSocketPath, walletRootId);
         if (probe.compatibility === "compatible" && probe.client !== null) {
-            return probe.client;
+            await probe.client.close().catch(() => undefined);
+            return;
         }
         if (probe.compatibility !== "unreachable") {
             throw new Error(probe.error ?? "indexer_daemon_protocol_error");
@@ -358,6 +371,7 @@ export async function attachOrStartIndexerDaemon(options) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
     const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
     const startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
+    const serviceLifetime = options.serviceLifetime ?? "persistent";
     const existingProbe = await probeIndexerDaemonAtSocket(paths.indexerDaemonSocketPath, walletRootId);
     if (existingProbe.compatibility === "compatible" && existingProbe.client !== null) {
         return existingProbe.client;
@@ -382,17 +396,46 @@ export async function attachOrStartIndexerDaemon(options) {
             }
             await mkdir(paths.indexerServiceRoot, { recursive: true });
             const daemonEntryPath = fileURLToPath(new URL("./indexer-daemon-main.js", import.meta.url));
+            const spawnOptions = serviceLifetime === "ephemeral"
+                ? {
+                    stdio: "ignore",
+                }
+                : {
+                    detached: true,
+                    stdio: "ignore",
+                };
             const child = spawn(process.execPath, [
                 daemonEntryPath,
                 `--data-dir=${options.dataDir}`,
                 `--database-path=${options.databasePath}`,
                 `--wallet-root-id=${walletRootId}`,
             ], {
-                detached: true,
-                stdio: "ignore",
+                ...spawnOptions,
+            });
+            if (serviceLifetime !== "ephemeral") {
+                child.unref();
+            }
+            try {
+                await waitForIndexerDaemon(options.dataDir, walletRootId, startupTimeoutMs);
+            }
+            catch (error) {
+                if (child.pid !== undefined) {
+                    try {
+                        process.kill(child.pid, "SIGTERM");
+                    }
+                    catch {
+                        // ignore shutdown failures while unwinding startup errors
+                    }
+                }
+                throw error;
+            }
+            return createIndexerDaemonClient(paths.indexerDaemonSocketPath, {
+                dataDir: options.dataDir,
+                walletRootId,
+                serviceLifetime,
+                ownership: "started",
+                shutdownTimeoutMs: options.shutdownTimeoutMs,
             });
-            child.unref();
-            return await waitForIndexerDaemon(options.dataDir, walletRootId, startupTimeoutMs);
         }
         finally {
             await lock.release();
@@ -400,7 +443,14 @@ export async function attachOrStartIndexerDaemon(options) {
     }
     catch (error) {
         if (error instanceof FileLockBusyError) {
-            return waitForIndexerDaemon(options.dataDir, walletRootId, startupTimeoutMs);
+            await waitForIndexerDaemon(options.dataDir, walletRootId, startupTimeoutMs);
+            return createIndexerDaemonClient(paths.indexerDaemonSocketPath, {
+                dataDir: options.dataDir,
+                walletRootId,
+                serviceLifetime,
+                ownership: "attached",
+                shutdownTimeoutMs: options.shutdownTimeoutMs,
+            });
         }
         throw error;
     }

package/dist/bitcoind/retryable-rpc.js

@@ -19,6 +19,9 @@ export function isRetryableManagedRpcError(error) {
     if (message === "bitcoind_rpc_timeout") {
         return true;
     }
+    if (/^bitcoind_rpc_[^_]+_-28(?:_|$)/.test(message)) {
+        return true;
+    }
     if (message.startsWith("The managed Bitcoin RPC request to ")) {
         return message.includes(" failed");
     }

package/dist/bitcoind/service.d.ts

@@ -24,6 +24,7 @@ type ManagedBitcoindServiceOptions = Pick<InternalManagedBitcoindOptions, "dataD
     getblockArchivePath?: string | null;
     getblockArchiveEndHeight?: number | null;
     getblockArchiveSha256?: string | null;
+    serviceLifetime?: "persistent" | "ephemeral";
 };
 export type ManagedBitcoindServiceCompatibility = "compatible" | "service-version-mismatch" | "wallet-root-mismatch" | "runtime-mismatch" | "unreachable" | "protocol-error";
 export interface ManagedBitcoindServiceProbeResult {

package/dist/bitcoind/service.js

@@ -681,9 +681,10 @@ async function refreshManagedBitcoindStatus(status, paths, options) {
         return nextStatus;
     }
 }
-function createNodeHandle(status, paths, options) {
+function createNodeHandle(status, paths, options, ownership) {
     let currentStatus = status;
     const rpc = createRpcClient(currentStatus.rpc);
+    let stopped = false;
     return {
         rpc: currentStatus.rpc,
         zmq: currentStatus.zmq,
@@ -706,9 +707,20 @@ function createNodeHandle(status, paths, options) {
             return currentStatus;
         },
         async stop() {
-            // Public managed clients detach from the persistent service instead of
-            // shutting it down on ordinary command exit.
-            return;
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            if (options.serviceLifetime !== "ephemeral" || ownership === "attached") {
+                // Public managed clients detach from persistent services, and ephemeral
+                // attach callers must not shut down services they did not launch.
+                return;
+            }
+            await stopManagedBitcoindService({
+                dataDir: currentStatus.dataDir,
+                walletRootId: currentStatus.walletRootId,
+                shutdownTimeoutMs: options.shutdownTimeoutMs,
+            });
         },
     };
 }
@@ -720,7 +732,7 @@ async function tryAttachExistingManagedBitcoindService(options) {
         return null;
     }
     const refreshed = await refreshManagedBitcoindStatus(probe.status, paths, options);
-    return createNodeHandle(refreshed, paths, options);
+    return createNodeHandle(refreshed, paths, options, "attached");
 }
 async function waitForManagedBitcoindService(options, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
@@ -765,6 +777,7 @@ export async function attachOrStartManagedBitcoindService(options) {
     const resolvedOptions = {
         ...options,
         dataDir: options.dataDir,
+        serviceLifetime: options.serviceLifetime ?? "persistent",
         walletRootId: options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID,
     };
     const startupTimeoutMs = resolvedOptions.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
@@ -815,11 +828,20 @@ export async function attachOrStartManagedBitcoindService(options) {
                         port: runtimeConfig.zmqPort,
                         pollIntervalMs: startOptions.pollIntervalMs ?? 15_000,
                     };
+                    const spawnOptions = startOptions.serviceLifetime === "ephemeral"
+                        ? {
+                            stdio: "ignore",
+                        }
+                        : {
+                            detached: true,
+                            stdio: "ignore",
+                        };
                     const child = spawn(bitcoindPath, buildManagedServiceArgs(startOptions, runtimeConfig), {
-                        detached: true,
-                        stdio: "ignore",
+                        ...spawnOptions,
                     });
-                    child.unref();
+                    if (startOptions.serviceLifetime !== "ephemeral") {
+                        child.unref();
+                    }
                     const rpc = createRpcClient(rpcConfig);
                     try {
                         await waitForRpcReady(rpc, rpcConfig.cookieFile, startOptions.chain, startupTimeoutMs);
@@ -876,7 +898,7 @@ export async function attachOrStartManagedBitcoindService(options) {
                     });
                 }
                 await writeBitcoindStatus(paths, status);
-                return createNodeHandle(status, paths, resolvedOptions);
+                return createNodeHandle(status, paths, resolvedOptions, "started");
             }
             finally {
                 await lock.release();

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

@@ -36,6 +36,15 @@ export async function runMiningAdminCommand(parsed, context) {
             }
             writeLine(context.stdout, "Built-in mining provider configured.");
             writeLine(context.stdout, `Provider: ${view.provider.provider ?? "unknown"}`);
+            if (view.provider.modelId !== null) {
+                writeLine(context.stdout, `Selected model: ${view.provider.modelId}`);
+            }
+            if (view.provider.modelSelectionSource !== null) {
+                writeLine(context.stdout, `Selection source: ${view.provider.modelSelectionSource}`);
+            }
+            if (view.provider.estimatedDailyCostDisplay !== null) {
+                writeLine(context.stdout, `Approximate daily cost: ${view.provider.estimatedDailyCostDisplay}`);
+            }
             for (const line of formatNextStepLines(nextSteps)) {
                 writeLine(context.stdout, line);
             }

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

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

package/dist/cli/commands/update.js

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

package/dist/cli/context.js

@@ -1,3 +1,4 @@
+import { spawn } from "node:child_process";
 import { mkdir, readFile } from "node:fs/promises";
 import { attachOrStartIndexerDaemon, probeIndexerDaemon, readObservedIndexerDaemonStatus, stopIndexerDaemonService, } from "../bitcoind/indexer-daemon.js";
 import { createRpcClient } from "../bitcoind/node.js";
@@ -36,6 +37,35 @@ export async function readPackageVersionFromDisk() {
     }
     return "0.0.0";
 }
+async function runGlobalClientUpdateInstall(options) {
+    const binary = process.platform === "win32" ? "npm.cmd" : "npm";
+    await new Promise((resolve, reject) => {
+        const child = spawn(binary, ["install", "-g", "@cogcoin/client"], {
+            env: options.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        child.stdout?.on("data", (chunk) => {
+            options.stdout.write(typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+        });
+        child.stderr?.on("data", (chunk) => {
+            options.stderr.write(typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+        });
+        child.on("error", (error) => {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+                reject(new Error("cli_update_npm_not_found"));
+                return;
+            }
+            reject(new Error("cli_update_install_failed"));
+        });
+        child.on("close", (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error("cli_update_install_failed"));
+        });
+    });
+}
 export function createDefaultContext(overrides = {}) {
     return {
         stdout: overrides.stdout ?? process.stdout,
@@ -48,6 +78,7 @@ export function createDefaultContext(overrides = {}) {
             process.exit(code);
         }),
         fetchImpl: overrides.fetchImpl ?? fetch,
+        runGlobalClientUpdateInstall: overrides.runGlobalClientUpdateInstall ?? runGlobalClientUpdateInstall,
         openSqliteStore: overrides.openSqliteStore ?? openSqliteStore,
         openManagedBitcoindClient: overrides.openManagedBitcoindClient ?? openManagedBitcoindClient,
         inspectPassiveClientStatus: overrides.inspectPassiveClientStatus ?? inspectPassiveClientStatus,

package/dist/cli/mining-format.js

@@ -13,6 +13,20 @@ function formatIndexerTruthSource(source) {
             return "none";
     }
 }
+function formatProviderModel(mining) {
+    if (mining.provider.effectiveModel === null || mining.provider.usingDefaultModel === null) {
+        return null;
+    }
+    return `${mining.provider.effectiveModel} (${mining.provider.usingDefaultModel ? "default" : "override"})`;
+}
+function formatProviderModelSource(mining) {
+    return mining.provider.modelSelectionSource;
+}
+function resolveProviderNotFoundNextStep(mining) {
+    return mining.provider.usingDefaultModel === false
+        ? "Next: run `cogcoin mine setup` and clear or correct the provider model."
+        : "Next: run `cogcoin mine setup` and choose a valid provider model.";
+}
 export function formatMiningSummaryLine(mining) {
     const provider = mining.provider.configured
         ? `${mining.provider.provider} configured`
@@ -42,6 +56,17 @@ export function formatMineStatusReport(mining) {
         lines.push(`Last suspend detected: ${formatMaybeIso(mining.runtime.lastSuspendDetectedAtUnixMs)}`);
     }
     lines.push(`Provider: ${mining.provider.configured ? `${mining.provider.provider} configured` : mining.provider.status}`);
+    const providerModel = formatProviderModel(mining);
+    if (providerModel !== null) {
+        lines.push(`Provider model: ${providerModel}`);
+    }
+    const providerModelSource = formatProviderModelSource(mining);
+    if (providerModelSource !== null) {
+        lines.push(`Provider model source: ${providerModelSource}`);
+    }
+    if (mining.provider.estimatedDailyCostDisplay !== null) {
+        lines.push(`Estimated daily cost: ${mining.provider.estimatedDailyCostDisplay}`);
+    }
     if (mining.provider.message !== null) {
         lines.push(`Provider note: ${mining.provider.message}`);
     }
@@ -105,6 +130,9 @@ export function formatMineStatusReport(mining) {
     if (mining.runtime.miningState === "repair-required") {
         lines.push("Next: run `cogcoin repair` before mining again.");
     }
+    else if (mining.runtime.providerState === "not-found") {
+        lines.push(resolveProviderNotFoundNextStep(mining));
+    }
     else if (mining.runtime.pauseReason === "zero-reward") {
         lines.push("Next: wait for the next positive-reward target height; mining resumes automatically.");
     }

package/dist/cli/mining-json.js

@@ -18,8 +18,14 @@ export function buildMineSetupData(view) {
             configured: view.provider.configured,
             provider: view.provider.provider,
             status: view.provider.status,
+            modelId: view.provider.modelId,
             modelOverride: view.provider.modelOverride,
+            modelSelectionSource: view.provider.modelSelectionSource,
+            effectiveModel: view.provider.effectiveModel,
+            usingDefaultModel: view.provider.usingDefaultModel,
             extraPromptConfigured: view.provider.extraPromptConfigured,
+            estimatedDailyCostUsd: view.provider.estimatedDailyCostUsd,
+            estimatedDailyCostDisplay: view.provider.estimatedDailyCostDisplay,
         },
         runtime: summarizeRuntime(view.runtime),
     };

package/dist/cli/output.js

@@ -127,7 +127,9 @@ export function classifyCliError(error) {
         return { exitCode: 2, errorCode: message, message };
     }
     if (message === "mining_setup_invalid_provider"
-        || message === "mining_setup_missing_api_key") {
+        || message === "mining_setup_missing_api_key"
+        || message === "mining_setup_missing_model_id"
+        || message === "mining_setup_canceled") {
         return { exitCode: 2, errorCode: message, message };
     }
     if (message.endsWith("_typed_ack_required")) {
@@ -507,6 +509,20 @@ export function createCliErrorPresentation(errorCode, fallbackMessage, error) {
             next: "Rerun `cogcoin mine setup` and enter the provider API key when prompted.",
         };
     }
+    if (errorCode === "mining_setup_missing_model_id") {
+        return {
+            what: "Mining model ID is required.",
+            why: "Built-in mining setup cannot save a custom mining model choice unless it has a non-empty model ID.",
+            next: "Rerun `cogcoin mine setup`, choose `Custom model ID...`, and enter the model ID when prompted.",
+        };
+    }
+    if (errorCode === "mining_setup_canceled") {
+        return {
+            what: "Mining setup was canceled.",
+            why: "The interactive mining-model selection was canceled before any provider configuration was saved.",
+            next: "Rerun `cogcoin mine setup` when you are ready to choose a provider model.",
+        };
+    }
     if (errorCode.endsWith("_confirmation_rejected")) {
         return {
             what: "Confirmation was declined.",
@@ -561,7 +577,7 @@ export function createCliErrorPresentation(errorCode, fallbackMessage, error) {
             next: "Restore or otherwise recover the wallet into the current format, then retry the command.",
         };
     }
-    if (errorCode.endsWith("_requires_tty")) {
+    if (errorCode.endsWith("_requires_tty") && errorCode !== "cli_update_requires_tty") {
         return {
             what: "Interactive terminal input is required.",
             why: "This command needs terminal input before it can continue safely.",
@@ -860,6 +876,34 @@ export function createCliErrorPresentation(errorCode, fallbackMessage, error) {
             next: "Rerun the command in an interactive terminal, or add `--yes` if that is appropriate for your workflow.",
         };
     }
+    if (errorCode === "cli_update_requires_tty") {
+        return {
+            what: "Updating Cogcoin needs an interactive terminal or `--yes`.",
+            why: "When a newer client release is available, `cogcoin update` prompts before running the global npm install unless `--yes` is provided.",
+            next: "Rerun `cogcoin update` in an interactive terminal, or add `--yes` to apply the update non-interactively.",
+        };
+    }
+    if (errorCode === "cli_update_registry_unavailable") {
+        return {
+            what: "Cogcoin could not read the latest client version from the npm registry.",
+            why: "The explicit update command requires a fresh registry lookup before it can compare versions or run the install.",
+            next: "Check network access and rerun `cogcoin update`.",
+        };
+    }
+    if (errorCode === "cli_update_npm_not_found") {
+        return {
+            what: "Cogcoin could not find npm to install the update.",
+            why: "The update command runs `npm install -g @cogcoin/client`, and no usable `npm` executable was available on PATH.",
+            next: "Install Node.js/npm or fix PATH, then rerun `cogcoin update`.",
+        };
+    }
+    if (errorCode === "cli_update_install_failed") {
+        return {
+            what: "Cogcoin update installation failed.",
+            why: "The global npm install exited unsuccessfully before the client update completed.",
+            next: "Review the npm output above, fix the installation issue, then rerun `cogcoin update`.",
+        };
+    }
     if (errorCode === "wallet_claim_sender_not_local") {
         return {
             what: "The claim sender is not locally controlled.",
@@ -918,6 +962,8 @@ export function describeCanonicalCommand(parsed) {
             return "cogcoin reset";
         case "repair":
             return "cogcoin repair";
+        case "update":
+            return "cogcoin update";
         case "anchor":
         case "domain-anchor":
             return `cogcoin anchor ${args[0] ?? "<domain>"}`;
@@ -1096,6 +1142,8 @@ export function resolveStableMutationJsonSchema(parsed) {
             return "cogcoin/reset/v1";
         case "repair":
             return "cogcoin/repair/v1";
+        case "update":
+            return "cogcoin/update/v1";
         case "anchor":
         case "domain-anchor":
             return "cogcoin/anchor/v1";

package/dist/cli/parse.d.ts

@@ -1,3 +1,3 @@
 import type { ParsedCliArgs } from "./types.js";
-export declare const HELP_TEXT = "Usage: cogcoin <command> [options]\n\nCommands:\n  status                  Show wallet-aware local service and chain status\n  status --output json    Emit the stable v1 machine-readable status envelope\n  client unlock           Unlock password-protected local wallet secrets for a limited time\n  client lock             Flush the cached client password unlock session\n  client change-password  Rotate the client password that protects local wallet secrets\n  bitcoin start           Start the managed Bitcoin daemon\n  bitcoin stop            Stop the managed Bitcoin daemon and paired indexer\n  bitcoin status          Show managed Bitcoin daemon status without starting it\n  bitcoin transfer <sats> --to <address>\n                         Send plain BTC from the wallet address\n  indexer start           Start the managed Cogcoin indexer (and bitcoind if needed)\n  indexer stop            Stop the managed Cogcoin indexer only\n  indexer status          Show managed Cogcoin indexer status without starting it\n  init                    Initialize a new local wallet root\n  init --output json      Emit the stable v1 machine-readable init result envelope\n  restore                 Restore an imported named seed from a 24-word mnemonic; run sync afterward\n  reset                   Factory-reset local Cogcoin state with interactive retention prompts\n  repair                  Recover bounded wallet/indexer/runtime state\n  wallet address          Alias for address\n  wallet ids              Alias for ids\n  mine                    Run the miner in the foreground\n  mine start              Start the miner as a background worker\n  mine stop               Stop the active background miner\n  mine setup              Configure the built-in mining provider\n  mine setup --output json\n                         Emit the stable v1 machine-readable mine setup result envelope\n  mine status             Show mining control-plane health and readiness\n  mine log                Show recent mining control-plane events\n  anchor <domain>         Anchor an owned unanchored domain with the wallet address\n  register <domain>\n                         Register a root domain or subdomain\n  transfer <domain> --to <btc-target>\n                          Transfer an unanchored domain to another BTC address or script\n  sell <domain> <price>   List an unanchored domain for sale in COG\n  unsell <domain>         Clear an active domain listing\n  buy <domain>\n                         Buy an unanchored listed domain in COG\n  send <amount> --to <btc-target>\n                         Send COG from the wallet address to another BTC target\n  claim <lock-id> --preimage <32-byte-hex>\n                         Claim an active COG lock before timeout\n  reclaim <lock-id>      Reclaim an expired COG lock as the original locker\n  cog lock <amount> --to-domain <domain> (--for <blocks-or-duration> | --until-height <height>) --condition <sha256hex>\n                         Lock COG to an anchored recipient domain\n  wallet status           Show detailed wallet-local status and service health\n  wallet init             Initialize a new local wallet root\n  wallet restore          Restore an imported named seed from a 24-word mnemonic; run sync afterward\n  wallet delete           Delete one imported named seed without affecting main\n  wallet show-mnemonic    Reveal the initialized wallet recovery phrase after typed confirmation\n  address                 Show the BTC wallet address for this wallet\n  ids                     Show the local wallet address\n  balance                 Show local wallet COG balances\n  locks                   Show locally related active COG locks\n  domain list             Alias for domains\n  domain show <domain>    Alias for show <domain>\n  domains [--anchored] [--listed] [--mineable]\n                         Show locally related domains\n  show <domain>           Show one domain and its local-wallet relationship\n  fields <domain>         List current fields on a domain\n  field <domain> <field>  Show one current field value\n  field create <domain> <field>\n                         Create a new empty anchored field\n  field set <domain> <field>\n                         Update an existing anchored field value\n  field clear <domain> <field>\n                         Clear an existing anchored field value\n  rep give <source-domain> <target-domain> <amount>\n                         Burn COG as anchored-domain reputation support\n  rep revoke <source-domain> <target-domain> <amount>\n                         Revoke visible support without refunding burned COG\n\nOptions:\n  --db <path>       Override the SQLite database path\n  --data-dir <path> Override the managed bitcoin datadir\n  --for <duration>  Relative timeout for cog lock, like 15m, 2h, or 1d\n  --message <text>  Founding message text for anchor\n  --to <btc-target> Transfer or send target as an address or spk:<hex>\n  --to-domain <domain>\n                    Recipient domain for cog lock\n  --condition <sha256hex>\n                    32-byte lock condition hash\n  --until-height <height>\n                    Absolute timeout height for cog lock\n  --preimage <32-byte-hex>\n                    Claim preimage for an active lock\n  --review <text>   Optional public review text for reputation operations\n  --satvb <n>       Override the mutation fee rate in sat/vB\n  --text <utf8>     UTF-8 payload text for endpoint or field writes\n  --json <json>     UTF-8 payload JSON text for endpoint or field writes\n  --bytes <spec>    Payload bytes as hex:<hex> or @<path>\n  --permanent       Create the field as permanent\n  --format <spec>   Advanced field format as raw:<u8>\n  --value <spec>    Advanced field value as hex:<hex>, @<path>, or utf8:<text>\n  --claimable      Show only currently claimable locks\n  --reclaimable    Show only currently reclaimable locks\n  --anchored       Show only anchored domains\n  --listed         Show only currently listed domains\n  --mineable       Show only locally mineable root domains\n  --limit <n>      Limit list rows (1..1000)\n  --all            Show all rows for list commands\n  --follow         Follow mining log output\n  --output <mode>  Output mode: text, json, or preview-json\n  --progress <mode> Progress output mode: auto, tty, or none\n  --seed <name>    Select an imported wallet seed for wallet-aware commands\n  --force          Reserved for future use\n  --force-race      Allow a visible root registration race\n  --yes             Approve eligible plain yes/no mutation confirmations non-interactively\n  --help            Show help\n  --version         Show package version\n\nQuickstart:\n  1. Run `cogcoin init` to create the wallet.\n  2. Run `cogcoin sync` to bootstrap assumeutxo and the managed Bitcoin/indexer state.\n  3. Run `cogcoin address`, then fund the wallet with about 0.0015 BTC so you can buy a 6+ character domain to start mining and still keep BTC available for mining transaction fees.\n\nExamples:\n  cogcoin status --output json\n  cogcoin bitcoin status\n  cogcoin indexer status\n  cogcoin init --output json\n  cogcoin restore --seed trading\n  cogcoin wallet address\n  cogcoin domain list --mineable\n  cogcoin register alpha-child\n  cogcoin anchor alpha\n  cogcoin register alpha --satvb 12.5\n  cogcoin buy alpha\n  cogcoin field set alpha bio --text \"hello\"\n  cogcoin rep give alpha beta 10 --review \"great operator\"\n  cogcoin mine setup --output json\n  cogcoin register alpha-child --output preview-json\n  cogcoin mine status\n";
+export declare const HELP_TEXT = "Usage: cogcoin <command> [options]\n\nCommands:\n  status                  Show wallet-aware local service and chain status\n  status --output json    Emit the stable v1 machine-readable status envelope\n  update                  Show the current and latest client versions and install updates\n  update --output json    Emit the stable v1 machine-readable update result envelope\n  client unlock           Unlock password-protected local wallet secrets for a limited time\n  client lock             Flush the cached client password unlock session\n  client change-password  Rotate the client password that protects local wallet secrets\n  bitcoin start           Start the managed Bitcoin daemon\n  bitcoin stop            Stop the managed Bitcoin daemon and paired indexer\n  bitcoin status          Show managed Bitcoin daemon status without starting it\n  bitcoin transfer <sats> --to <address>\n                         Send plain BTC from the wallet address\n  indexer start           Start the managed Cogcoin indexer (and bitcoind if needed)\n  indexer stop            Stop the managed Cogcoin indexer only\n  indexer status          Show managed Cogcoin indexer status without starting it\n  init                    Initialize a new local wallet root\n  init --output json      Emit the stable v1 machine-readable init result envelope\n  restore                 Restore an imported named seed from a 24-word mnemonic; run sync afterward\n  reset                   Factory-reset local Cogcoin state with interactive retention prompts\n  repair                  Recover bounded wallet/indexer/runtime state\n  wallet address          Alias for address\n  wallet ids              Alias for ids\n  mine                    Run the miner in the foreground\n  mine start              Start the miner as a background worker\n  mine stop               Stop the active background miner\n  mine setup              Configure the built-in mining provider\n  mine setup --output json\n                         Emit the stable v1 machine-readable mine setup result envelope\n  mine status             Show mining control-plane health and readiness\n  mine log                Show recent mining control-plane events\n  anchor <domain>         Anchor an owned unanchored domain with the wallet address\n  register <domain>\n                         Register a root domain or subdomain\n  transfer <domain> --to <btc-target>\n                          Transfer an unanchored domain to another BTC address or script\n  sell <domain> <price>   List an unanchored domain for sale in COG\n  unsell <domain>         Clear an active domain listing\n  buy <domain>\n                         Buy an unanchored listed domain in COG\n  send <amount> --to <btc-target>\n                         Send COG from the wallet address to another BTC target\n  claim <lock-id> --preimage <32-byte-hex>\n                         Claim an active COG lock before timeout\n  reclaim <lock-id>      Reclaim an expired COG lock as the original locker\n  cog lock <amount> --to-domain <domain> (--for <blocks-or-duration> | --until-height <height>) --condition <sha256hex>\n                         Lock COG to an anchored recipient domain\n  wallet status           Show detailed wallet-local status and service health\n  wallet init             Initialize a new local wallet root\n  wallet restore          Restore an imported named seed from a 24-word mnemonic; run sync afterward\n  wallet delete           Delete one imported named seed without affecting main\n  wallet show-mnemonic    Reveal the initialized wallet recovery phrase after typed confirmation\n  address                 Show the BTC wallet address for this wallet\n  ids                     Show the local wallet address\n  balance                 Show local wallet COG balances\n  locks                   Show locally related active COG locks\n  domain list             Alias for domains\n  domain show <domain>    Alias for show <domain>\n  domains [--anchored] [--listed] [--mineable]\n                         Show locally related domains\n  show <domain>           Show one domain and its local-wallet relationship\n  fields <domain>         List current fields on a domain\n  field <domain> <field>  Show one current field value\n  field create <domain> <field>\n                         Create a new empty anchored field\n  field set <domain> <field>\n                         Update an existing anchored field value\n  field clear <domain> <field>\n                         Clear an existing anchored field value\n  rep give <source-domain> <target-domain> <amount>\n                         Burn COG as anchored-domain reputation support\n  rep revoke <source-domain> <target-domain> <amount>\n                         Revoke visible support without refunding burned COG\n\nOptions:\n  --db <path>       Override the SQLite database path\n  --data-dir <path> Override the managed bitcoin datadir\n  --for <duration>  Relative timeout for cog lock, like 15m, 2h, or 1d\n  --message <text>  Founding message text for anchor\n  --to <btc-target> Transfer or send target as an address or spk:<hex>\n  --to-domain <domain>\n                    Recipient domain for cog lock\n  --condition <sha256hex>\n                    32-byte lock condition hash\n  --until-height <height>\n                    Absolute timeout height for cog lock\n  --preimage <32-byte-hex>\n                    Claim preimage for an active lock\n  --review <text>   Optional public review text for reputation operations\n  --satvb <n>       Override the mutation fee rate in sat/vB\n  --text <utf8>     UTF-8 payload text for endpoint or field writes\n  --json <json>     UTF-8 payload JSON text for endpoint or field writes\n  --bytes <spec>    Payload bytes as hex:<hex> or @<path>\n  --permanent       Create the field as permanent\n  --format <spec>   Advanced field format as raw:<u8>\n  --value <spec>    Advanced field value as hex:<hex>, @<path>, or utf8:<text>\n  --claimable      Show only currently claimable locks\n  --reclaimable    Show only currently reclaimable locks\n  --anchored       Show only anchored domains\n  --listed         Show only currently listed domains\n  --mineable       Show only locally mineable root domains\n  --limit <n>      Limit list rows (1..1000)\n  --all            Show all rows for list commands\n  --follow         Follow mining log output\n  --output <mode>  Output mode: text, json, or preview-json\n  --progress <mode> Progress output mode: auto, tty, or none\n  --seed <name>    Select an imported wallet seed for wallet-aware commands\n  --force          Reserved for future use\n  --force-race      Allow a visible root registration race\n  --yes             Approve eligible plain yes/no mutation confirmations non-interactively\n  --help            Show help\n  --version         Show package version\n\nQuickstart:\n  1. Run `cogcoin init` to create the wallet.\n  2. Run `cogcoin sync` to bootstrap assumeutxo and the managed Bitcoin/indexer state.\n  3. Run `cogcoin address`, then fund the wallet with about 0.0015 BTC so you can buy a 6+ character domain to start mining and still keep BTC available for mining transaction fees.\n\nExamples:\n  cogcoin status --output json\n  cogcoin bitcoin status\n  cogcoin indexer status\n  cogcoin init --output json\n  cogcoin restore --seed trading\n  cogcoin wallet address\n  cogcoin domain list --mineable\n  cogcoin register alpha-child\n  cogcoin anchor alpha\n  cogcoin register alpha --satvb 12.5\n  cogcoin buy alpha\n  cogcoin field set alpha bio --text \"hello\"\n  cogcoin rep give alpha beta 10 --review \"great operator\"\n  cogcoin mine setup --output json\n  cogcoin register alpha-child --output preview-json\n  cogcoin mine status\n";
 export declare function parseCliArgs(argv: string[]): ParsedCliArgs;

package/dist/cli/parse.js

@@ -5,6 +5,8 @@ export const HELP_TEXT = `Usage: cogcoin <command> [options]
 Commands:
   status                  Show wallet-aware local service and chain status
   status --output json    Emit the stable v1 machine-readable status envelope
+  update                  Show the current and latest client versions and install updates
+  update --output json    Emit the stable v1 machine-readable update result envelope
   client unlock           Unlock password-protected local wallet secrets for a limited time
   client lock             Flush the cached client password unlock session
   client change-password  Rotate the client password that protects local wallet secrets
@@ -138,6 +140,7 @@ Examples:
 `;
 function supportsYesFlag(command) {
     switch (command) {
+        case "update":
         case "sync":
         case "follow":
         case "bitcoin-transfer":
@@ -834,6 +837,7 @@ export function parseCliArgs(argv) {
                 || token === "restore"
                 || token === "reset"
                 || token === "repair"
+                || token === "update"
                 || token === "sync"
                 || token === "status"
                 || token === "follow"
@@ -864,6 +868,7 @@ export function parseCliArgs(argv) {
         args.push(token);
     }
     if ((command === "status"
+        || command === "update"
         || command === "bitcoin-start"
         || command === "bitcoin-stop"
         || command === "bitcoin-status"