@cogcoin/client 1.0.1 → 1.1.0

package/dist/cli/mining-format.js

@@ -13,6 +13,23 @@ 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.";
+}
+function resolveInsufficientFundsNextStep() {
+    return "Next: wait for enough safe BTC funding to become spendable for the next publish; mining resumes automatically.";
+}
 export function formatMiningSummaryLine(mining) {
     const provider = mining.provider.configured
         ? `${mining.provider.provider} configured`
@@ -42,6 +59,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 +133,12 @@ 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.currentPublishDecision === "publish-paused-insufficient-funds") {
+        lines.push(resolveInsufficientFundsNextStep());
+    }
     else if (mining.runtime.pauseReason === "zero-reward") {
         lines.push("Next: wait for the next positive-reward target height; mining resumes automatically.");
     }
@@ -122,3 +156,32 @@ export function formatMineStatusReport(mining) {
 export function formatMiningEventRecord(event) {
     return `${new Date(event.timestampUnixMs).toISOString()}  ${event.level.toUpperCase()}  ${event.kind}  ${event.message}`;
 }
+export function formatMiningPromptMutationReport(result) {
+    const lines = [
+        `Domain: ${result.domain.name}`,
+        `Domain prompt: ${result.prompt ?? "none"}`,
+        `Global fallback prompt: ${result.fallbackPromptConfigured ? "configured" : "not configured"}`,
+    ];
+    if (result.previousPrompt !== null) {
+        lines.push(`Previous domain prompt: ${result.previousPrompt}`);
+    }
+    lines.push(result.status === "updated"
+        ? "Per-domain mining prompt updated."
+        : "Per-domain mining prompt cleared.");
+    return lines.join("\n");
+}
+export function formatMiningPromptListReport(result) {
+    const lines = [
+        "Mining Prompt List",
+        `Global fallback prompt: ${result.fallbackPromptConfigured ? "configured" : "not configured"}`,
+    ];
+    if (result.prompts.length === 0) {
+        lines.push("No mineable root domains or stored per-domain mining prompts are configured.");
+        return lines.join("\n");
+    }
+    for (const entry of result.prompts) {
+        lines.push(`${entry.domain.name}  domainId=${entry.domain.domainId ?? "none"}  ${entry.mineable ? "mineable" : "dormant"}  source=${entry.effectivePromptSource}`);
+        lines.push(`  prompt: ${entry.prompt ?? "none"}`);
+    }
+    return lines.join("\n");
+}

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

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

package/dist/cli/mining-json.js

@@ -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),
     };
@@ -52,3 +58,12 @@ export function buildMineStopData(snapshot) {
         after,
     });
 }
+export function buildMinePromptData(result) {
+    return {
+        domain: result.domain,
+        previousPrompt: result.previousPrompt,
+        prompt: result.prompt,
+        status: result.status,
+        fallbackPromptConfigured: result.fallbackPromptConfigured,
+    };
+}

package/dist/cli/output.js

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

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 prompt             Show per-domain mining prompt state\n  mine prompt --output json\n                         Emit the stable v1 machine-readable mine prompt list envelope\n  mine prompt <domain>    Configure a per-domain mining prompt override\n  mine prompt <domain> --output json\n                         Emit the stable v1 machine-readable mine prompt result envelope\n  mine prompt list        Alias for mine prompt\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 mine prompt\n  cogcoin mine prompt alpha\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
@@ -29,6 +31,13 @@ Commands:
   mine setup              Configure the built-in mining provider
   mine setup --output json
                          Emit the stable v1 machine-readable mine setup result envelope
+  mine prompt             Show per-domain mining prompt state
+  mine prompt --output json
+                         Emit the stable v1 machine-readable mine prompt list envelope
+  mine prompt <domain>    Configure a per-domain mining prompt override
+  mine prompt <domain> --output json
+                         Emit the stable v1 machine-readable mine prompt result envelope
+  mine prompt list        Alias for mine prompt
   mine status             Show mining control-plane health and readiness
   mine log                Show recent mining control-plane events
   anchor <domain>         Anchor an owned unanchored domain with the wallet address
@@ -133,11 +142,14 @@ Examples:
   cogcoin field set alpha bio --text "hello"
   cogcoin rep give alpha beta 10 --review "great operator"
   cogcoin mine setup --output json
+  cogcoin mine prompt
+  cogcoin mine prompt alpha
   cogcoin register alpha-child --output preview-json
   cogcoin mine status
 `;
 function supportsYesFlag(command) {
     switch (command) {
+        case "update":
         case "sync":
         case "follow":
         case "bitcoin-transfer":
@@ -220,6 +232,8 @@ function supportsSeedFlag(command) {
         case "mine-start":
         case "mine-stop":
         case "mine-setup":
+        case "mine-prompt":
+        case "mine-prompt-list":
         case "mine-status":
         case "mine-log":
         case "wallet-delete":
@@ -645,6 +659,14 @@ export function parseCliArgs(argv) {
                     index += 1;
                     continue;
                 }
+                if (subcommand === "prompt") {
+                    const action = argv[index + 2] ?? null;
+                    command = action === null || action.startsWith("--") || action === "list"
+                        ? "mine-prompt-list"
+                        : "mine-prompt";
+                    index += action === "list" ? 2 : 1;
+                    continue;
+                }
                 if (subcommand === "status") {
                     command = "mine-status";
                     index += 1;
@@ -834,6 +856,7 @@ export function parseCliArgs(argv) {
                 || token === "restore"
                 || token === "reset"
                 || token === "repair"
+                || token === "update"
                 || token === "sync"
                 || token === "status"
                 || token === "follow"
@@ -864,6 +887,7 @@ export function parseCliArgs(argv) {
         args.push(token);
     }
     if ((command === "status"
+        || command === "update"
         || command === "bitcoin-start"
         || command === "bitcoin-stop"
         || command === "bitcoin-status"
@@ -884,6 +908,7 @@ export function parseCliArgs(argv) {
         || command === "mine-start"
         || command === "mine-stop"
         || command === "mine-setup"
+        || command === "mine-prompt-list"
         || command === "mine-status"
         || command === "mine-log"
         || command === "wallet-address"
@@ -907,6 +932,9 @@ export function parseCliArgs(argv) {
         && args.length !== 1) {
         throw new Error("cli_missing_domain_argument");
     }
+    if (command === "mine-prompt" && args.length !== 1) {
+        throw new Error("cli_missing_domain_argument");
+    }
     if ((command === "domain-endpoint-set"
         || command === "domain-endpoint-clear"
         || command === "domain-delegate-clear"

package/dist/cli/prompt.js

@@ -1,5 +1,9 @@
 import { createInterface } from "node:readline/promises";
 const CLEAR_SENSITIVE_DISPLAY_SEQUENCE = "\u001B[2J\u001B[3J\u001B[H";
+const CLEAR_MENU_SEQUENCE = "\u001B[0J";
+function countRenderedLines(text) {
+    return text.endsWith("\n") ? text.split("\n").length - 1 : text.split("\n").length;
+}
 export function createTerminalPrompter(input, output) {
     const ensureReadableInput = () => {
         if (!("on" in input) || !("off" in input)) {
@@ -8,6 +12,12 @@ export function createTerminalPrompter(input, output) {
         return input;
     };
     const ensureWritableOutput = () => output;
+    const supportsRawSelection = () => {
+        const readable = ensureReadableInput();
+        return Boolean(readable.isTTY
+            && output.isTTY
+            && typeof readable.setRawMode === "function");
+    };
     const ask = async (message, questionOutput) => {
         const readline = createInterface({
             input: ensureReadableInput(),
@@ -20,6 +30,99 @@ export function createTerminalPrompter(input, output) {
             readline.close();
         }
     };
+    const promptSelectionFallback = async (options) => {
+        const writableOutput = ensureWritableOutput();
+        writableOutput.write(`${options.message}\n`);
+        for (const [index, option] of options.options.entries()) {
+            const description = option.description == null || option.description.length === 0
+                ? ""
+                : ` - ${option.description}`;
+            writableOutput.write(`${index + 1}. ${option.label}${description}\n`);
+        }
+        if (options.footer != null && options.footer.length > 0) {
+            writableOutput.write(`${options.footer}\n`);
+        }
+        while (true) {
+            const answer = (await ask(`Choice [1-${options.options.length}]: `, writableOutput)).trim();
+            if (/^(q|quit|esc|escape)$/i.test(answer)) {
+                throw new Error("mining_setup_canceled");
+            }
+            const selection = Number.parseInt(answer, 10);
+            if (Number.isInteger(selection) && selection >= 1 && selection <= options.options.length) {
+                return options.options[selection - 1].value;
+            }
+            writableOutput.write(`Enter a number from 1 to ${options.options.length}, or q to cancel.\n`);
+        }
+    };
+    const promptSelectionRaw = async (options) => {
+        const readableInput = ensureReadableInput();
+        const writableOutput = ensureWritableOutput();
+        const initialIndex = options.initialValue == null
+            ? -1
+            : options.options.findIndex((option) => option.value === options.initialValue);
+        let selectedIndex = initialIndex === -1 ? 0 : initialIndex;
+        let renderedLineCount = 0;
+        const renderMenu = () => {
+            if (renderedLineCount > 0) {
+                writableOutput.write(`\u001B[${renderedLineCount}A${CLEAR_MENU_SEQUENCE}`);
+            }
+            const lines = [
+                options.message,
+                "Use Up/Down to choose, Enter to confirm, or q/Esc/Ctrl+C to cancel.",
+                ...options.options.map((option, index) => {
+                    const prefix = index === selectedIndex ? ">" : " ";
+                    const description = option.description == null || option.description.length === 0
+                        ? ""
+                        : ` - ${option.description}`;
+                    return `${prefix} ${option.label}${description}`;
+                }),
+            ];
+            if (options.footer != null && options.footer.length > 0) {
+                lines.push(options.footer);
+            }
+            const rendered = `${lines.join("\n")}\n`;
+            renderedLineCount = countRenderedLines(rendered);
+            writableOutput.write(rendered);
+        };
+        return await new Promise((resolve, reject) => {
+            const finish = (handler) => {
+                readableInput.off("data", onData);
+                readableInput.setRawMode(false);
+                readableInput.pause?.();
+                writableOutput.write("\n");
+                handler();
+            };
+            const onData = (chunk) => {
+                const value = Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk;
+                switch (value) {
+                    case "\u001B[A":
+                        selectedIndex = selectedIndex === 0 ? options.options.length - 1 : selectedIndex - 1;
+                        renderMenu();
+                        return;
+                    case "\u001B[B":
+                        selectedIndex = selectedIndex === options.options.length - 1 ? 0 : selectedIndex + 1;
+                        renderMenu();
+                        return;
+                    case "\r":
+                    case "\n":
+                        finish(() => resolve(options.options[selectedIndex].value));
+                        return;
+                    case "\u001B":
+                    case "\u0003":
+                    case "q":
+                    case "Q":
+                        finish(() => reject(new Error("mining_setup_canceled")));
+                        return;
+                    default:
+                        return;
+                }
+            };
+            readableInput.setRawMode(true);
+            readableInput.resume?.();
+            readableInput.on("data", onData);
+            renderMenu();
+        });
+    };
     return {
         isInteractive: Boolean(input.isTTY && output.isTTY),
         writeLine(message) {
@@ -44,6 +147,12 @@ export function createTerminalPrompter(input, output) {
                 output.write("\n");
             }
         },
+        async selectOption(options) {
+            if (!supportsRawSelection()) {
+                return await promptSelectionFallback(options);
+            }
+            return await promptSelectionRaw(options);
+        },
         clearSensitiveDisplay(scope) {
             if (!input.isTTY || !output.isTTY) {
                 return;

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

@@ -1,5 +1,5 @@
 import type { WalletDomainView, WalletFieldView, WalletLockView, WalletReadContext } from "../wallet/read/index.js";
-import type { MiningControlPlaneView, MiningEventRecord } from "../wallet/mining/index.js";
+import type { MiningControlPlaneView, MiningDomainPromptListResult, MiningEventRecord } from "../wallet/mining/index.js";
 import type { PendingMutationRecord } from "../wallet/types.js";
 import type { JsonAvailabilityEntry, JsonPage } from "./output.js";
 export interface ReadJsonResult<T> {
@@ -114,6 +114,19 @@ export declare function buildMineStatusJson(mining: MiningControlPlaneView): Rea
     phase: string;
     lastSuspendDetectedAtUnixMs: number | null;
     pauseReason: string | null;
+    providerState: string | null;
+    provider: {
+        configured: boolean;
+        kind: string | null;
+        modelId: string | null;
+        effectiveModel: string | null;
+        modelOverride: string | null;
+        modelSelectionSource: string | null;
+        usingDefaultModel: boolean | null;
+        extraPromptConfigured: boolean;
+        estimatedDailyCostUsd: number | null;
+        estimatedDailyCostDisplay: string | null;
+    };
     fees: Record<string, unknown>;
     worker: Record<string, unknown>;
     availability: Record<string, JsonAvailabilityEntry>;
@@ -124,6 +137,18 @@ export declare function buildMineLogJson(events: MiningEventRecord[], page: Json
     rotation: number[];
     page: JsonPage;
 }>;
+export declare function buildMinePromptListJson(result: MiningDomainPromptListResult): ReadJsonResult<{
+    fallbackPromptConfigured: boolean;
+    prompts: Array<{
+        domain: {
+            name: string;
+            domainId: number | null;
+        };
+        mineable: boolean;
+        prompt: string | null;
+        effectivePromptSource: "domain" | "global-fallback" | "none";
+    }>;
+}>;
 export declare function buildBalanceJson(context: WalletReadContext): ReadJsonResult<{
     assetLabel: string;
     totalCogtoshi: string | null;