@cogcoin/client 0.5.15 → 1.0.0

package/dist/cli/output.js

@@ -1,3 +1,4 @@
+import { FileLockBusyError } from "../wallet/fs/lock.js";
 export function writeJsonValue(stream, value) {
     stream.write(`${JSON.stringify(value, jsonReplacer)}\n`);
 }
@@ -125,50 +126,26 @@ export function classifyCliError(error) {
     if (/^wallet_init_confirmation_failed_word_\d+$/.test(message)) {
         return { exitCode: 2, errorCode: message, message };
     }
-    if (message === "mining_hooks_enable_trust_acknowledgement_required") {
-        return { exitCode: 2, errorCode: message, message };
-    }
     if (message === "mining_setup_invalid_provider"
         || message === "mining_setup_missing_api_key") {
         return { exitCode: 2, errorCode: message, message };
     }
-    if (message.startsWith("mining_hooks_enable_template_created:")) {
-        return {
-            exitCode: 4,
-            errorCode: "mining_hooks_enable_template_created",
-            message,
-        };
-    }
-    if (message.startsWith("mining_hooks_enable_validation_failed:")) {
-        return {
-            exitCode: 5,
-            errorCode: "mining_hooks_enable_validation_failed",
-            message,
-        };
-    }
     if (message.endsWith("_typed_ack_required")) {
         return { exitCode: 2, errorCode: message, message };
     }
     if (message === "wallet_typed_confirmation_rejected"
-        || message === "wallet_export_overwrite_declined"
         || message === "wallet_delete_confirmation_required"
         || message === "wallet_prompt_value_required"
-        || message === "wallet_archive_passphrase_mismatch"
         || message === "wallet_restore_mnemonic_invalid"
         || message === "wallet_restore_replace_confirmation_required"
         || message === "wallet_seed_name_invalid"
         || message === "wallet_seed_name_reserved"
-        || message === "reset_wallet_choice_invalid"
-        || message === "reset_wallet_passphrase_required"
-        || message === "reset_wallet_access_failed") {
+        || message === "reset_wallet_choice_invalid") {
         return { exitCode: 2, errorCode: message, message };
     }
     if (message === "not_found") {
         return { exitCode: 3, errorCode: "not_found", message: "Requested object not found." };
     }
-    if (message === "wallet_import_archive_not_found") {
-        return { exitCode: 3, errorCode: message, message };
-    }
     if (message === "wallet_seed_not_found") {
         return { exitCode: 3, errorCode: message, message };
     }
@@ -188,17 +165,12 @@ export function classifyCliError(error) {
 }
 function isBlockedError(message) {
     if (message === "wallet_control_lock_busy"
-        || message.startsWith("file_lock_busy_")
-        || message.startsWith("wallet_anchor_clear_pending_first_")) {
+        || message.startsWith("file_lock_busy_")) {
         return true;
     }
-    if (message === "wallet_locked"
-        || message === "wallet_uninitialized"
+    if (message === "wallet_uninitialized"
         || message === "local-state-corrupt"
         || message === "wallet_already_initialized"
-        || message === "wallet_export_core_replica_not_ready"
-        || message === "wallet_export_tip_mismatch"
-        || message === "wallet_export_requires_quiescent_local_state"
         || message === "wallet_restore_requires_main_wallet"
         || message === "wallet_seed_name_exists"
         || message === "wallet_seed_not_found"
@@ -211,11 +183,14 @@ function isBlockedError(message) {
         || message === "indexer_daemon_wallet_root_mismatch"
         || message === "indexer_daemon_schema_mismatch"
         || message === "mine_setup_requires_tty"
-        || message === "mining_hooks_enable_requires_tty"
         || message === "mining_preemption_timeout"
-        || message === "wallet_secret_provider_linux_secret_tool_missing"
-        || message === "wallet_secret_provider_linux_secret_service_unavailable"
-        || message === "wallet_secret_provider_linux_runtime_error") {
+        || message === "wallet_client_password_setup_required"
+        || message === "wallet_client_password_migration_required"
+        || message === "wallet_client_password_locked"
+        || message === "wallet_secret_provider_linux_runtime_error"
+        || message === "wallet_secret_provider_macos_runtime_error"
+        || message === "wallet_secret_provider_windows_runtime_error"
+        || message === "wallet_state_legacy_envelope_unsupported") {
         return true;
     }
     return /(?:^|_)(?:locked|uninitialized|repair_required|requires_tty|typed_ack_required|confirmation_rejected|tip_mismatch|core_replica_not_ready|setup|no_eligible_sender|ambiguous_sender|insufficient|stale|paused|validation|catching_up|starting|unavailable|schema_mismatch|service_version_mismatch|wallet_root_mismatch|runtime_mismatch|replica_missing|replica_mismatch|failed)(?:_|$)/.test(message)
@@ -223,7 +198,7 @@ function isBlockedError(message) {
 }
 export function formatCliTextError(error) {
     const classified = classifyCliError(error);
-    const presentation = createCliErrorPresentation(classified.errorCode, classified.message);
+    const presentation = createCliErrorPresentation(classified.errorCode, classified.message, error);
     if (presentation === null) {
         return null;
     }
@@ -236,19 +211,41 @@ export function formatCliTextError(error) {
     }
     return lines;
 }
-export function createCliErrorPresentation(errorCode, fallbackMessage) {
-    if (errorCode === "wallet_locked") {
+export function createCliErrorPresentation(errorCode, fallbackMessage, error) {
+    if (errorCode.endsWith("_sender_utxo_unavailable")) {
         return {
-            what: "Wallet is locked.",
-            why: "This command needs access to the unlocked local wallet state before it can continue. Provider-backed wallets unlock on demand unless they were explicitly locked or the local secret store is unavailable.",
-            next: "Run `cogcoin unlock --for 15m` and retry.",
+            what: "Sender identity has no spendable confirmed BTC input.",
+            why: "This command preserves the Cogcoin sender identity in vin[0]. The selected sender currently has no confirmed spendable UTXO available for that role.",
+            next: "Wait for the sender's BTC output to confirm, or fund that sender identity 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.",
+            next: "Run `cogcoin repair` to reset the local lock state, then retry.",
+        };
+    }
+    if (errorCode.startsWith("file_lock_busy_")) {
+        const lockPath = errorCode.slice("file_lock_busy_".length);
+        const lockPurpose = error instanceof FileLockBusyError
+            ? error.existingMetadata?.purpose ?? null
+            : null;
+        if (lockPath.includes("wallet-control.lock")) {
+            return {
+                what: lockPurpose === null
+                    ? "Wallet control lock is busy."
+                    : `Wallet control lock is busy (purpose: ${lockPurpose}).`,
+                why: "Another Cogcoin command currently holds the exclusive wallet control lock for this wallet.",
+                next: "Run `cogcoin repair` to reset the local lock state, then retry.",
+            };
+        }
+        return {
+            what: lockPurpose === null
+                ? `Lock file is busy: ${lockPath}.`
+                : `Lock file is busy: ${lockPath} (purpose: ${lockPurpose}).`,
+            why: "The command was blocked by the current local wallet or service state.",
+            next: "Run `cogcoin repair` to reset the local lock state, then retry.",
         };
     }
     if (errorCode === "reset_wallet_choice_invalid") {
@@ -258,20 +255,6 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
             next: "Rerun `cogcoin reset` and enter one of the accepted wallet reset choices.",
         };
     }
-    if (errorCode === "reset_wallet_passphrase_required") {
-        return {
-            what: "Wallet-state passphrase is required.",
-            why: "The current wallet is passphrase-wrapped, so the entropy-retaining reset path needs that passphrase before it can rebuild a fresh local wallet from the retained mnemonic.",
-            next: "Rerun `cogcoin reset` and enter the wallet-state passphrase, or choose \"skip\" or \"delete wallet\" instead.",
-        };
-    }
-    if (errorCode === "reset_wallet_access_failed") {
-        return {
-            what: "Wallet state could not be opened for entropy-retaining reset.",
-            why: "The wallet-state passphrase was not accepted, or the passphrase-wrapped wallet state could not be decrypted cleanly.",
-            next: "Rerun `cogcoin reset`, enter the correct wallet-state passphrase, or choose \"skip\" or \"delete wallet\" instead.",
-        };
-    }
     if (errorCode === "reset_wallet_entropy_reset_unavailable") {
         return {
             what: "Entropy-retaining wallet reset is unavailable.",
@@ -295,9 +278,9 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
     }
     if (errorCode === "reset_secret_cleanup_failed") {
         return {
-            what: "Reset finished the filesystem wipe but could not fully clean up wallet secret-provider entries.",
-            why: "The local Cogcoin files were already removed or rewritten, but at least one discoverable OS secret-store entry could not be deleted cleanly.",
-            next: "Remove the remaining Cogcoin wallet secret from the local secret store, then rerun `cogcoin status` to confirm the new state.",
+            what: "Reset finished the filesystem wipe but could not fully clean up wallet secret-provider material.",
+            why: "The local Cogcoin files were already removed or rewritten, but at least one tracked wallet secret could not be deleted cleanly.",
+            next: "Remove the remaining wallet secret material, then rerun `cogcoin status` to confirm the new state.",
         };
     }
     if (errorCode === "reset_snapshot_preserve_failed") {
@@ -325,7 +308,35 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
         return {
             what: "Wallet is already initialized.",
             why: "This machine already has a local wallet root, so initialization cannot safely create a second one in the same runtime location.",
-            next: "Run `cogcoin status` to inspect the existing wallet, or export/import it instead of reinitializing.",
+            next: "Run `cogcoin status` to inspect the existing wallet.",
+        };
+    }
+    if (errorCode === "wallet_client_password_setup_required") {
+        return {
+            what: "Client password setup is still required.",
+            why: "This machine has not finished configuring password-protected local wallet secrets yet.",
+            next: "Run `cogcoin init` to create the client password and finish local secret setup.",
+        };
+    }
+    if (errorCode === "wallet_client_password_migration_required") {
+        return {
+            what: "Client password migration is still required.",
+            why: "This machine still has wallet secrets in the older platform-specific local format, so Cogcoin will not use them until they are migrated into password-protected local files.",
+            next: "Run `cogcoin init` to create the client password and migrate local wallet secrets.",
+        };
+    }
+    if (errorCode === "wallet_client_password_locked") {
+        return {
+            what: "Client password is locked.",
+            why: "This command needs the password-protected local wallet secret, but no active unlock session is available.",
+            next: "Run `cogcoin client unlock`, or rerun the command in an interactive terminal so Cogcoin can prompt for the client password.",
+        };
+    }
+    if (errorCode === "wallet_client_password_change_requires_tty") {
+        return {
+            what: "Client password change needs an interactive terminal.",
+            why: "Cogcoin has to securely prompt for the current client password and the new password twice before it can rotate local wallet-secret protection.",
+            next: "Run `cogcoin client change-password` in an interactive terminal.",
         };
     }
     if (errorCode === "wallet_restore_requires_main_wallet") {
@@ -384,13 +395,6 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
             next: "Rerun the command in an interactive terminal and type the requested acknowledgement.",
         };
     }
-    if (errorCode === "wallet_export_overwrite_declined") {
-        return {
-            what: "Archive overwrite was declined.",
-            why: "The export path already exists, and the command will not replace that archive unless you explicitly approve it.",
-            next: "Rerun the command and type `yes` when prompted if you want to overwrite the archive.",
-        };
-    }
     if (/^wallet_init_confirmation_failed_word_\d+$/.test(errorCode)) {
         return {
             what: "Mnemonic confirmation failed.",
@@ -426,54 +430,67 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
             next: "Rerun the command with `--seed <name>`.",
         };
     }
-    if (errorCode === "cli_seed_not_supported_for_command" || errorCode === "wallet_init_seed_not_supported" || errorCode === "wallet_import_seed_not_supported") {
+    if (errorCode === "cli_seed_not_supported_for_command" || errorCode === "wallet_init_seed_not_supported") {
         return {
             what: "This command does not support `--seed`.",
             why: "Only wallet-aware commands are seed-selectable. Global lifecycle and shared service commands still operate on the shared local client state.",
             next: "Drop `--seed` for this command and retry.",
         };
     }
-    if (errorCode === "wallet_anchor_clear_inconsistent_state") {
+    if (errorCode === "cli_from_not_supported_for_command") {
+        return {
+            what: "`--from` is no longer supported.",
+            why: "Cogcoin now uses a single wallet address for local transaction authorship, so sender selection is no longer part of the CLI.",
+            next: "Retry the command without `--from`.",
+        };
+    }
+    if (errorCode === "cli_missing_satvb") {
+        return {
+            what: "A sat/vB value is required.",
+            why: "`--satvb` needs an explicit positive fee rate value in sat/vB for the mutation you are submitting.",
+            next: "Rerun the command with `--satvb <number>`.",
+        };
+    }
+    if (errorCode === "cli_invalid_satvb") {
         return {
-            what: "Pending anchor state is inconsistent.",
-            why: "The domain still shows local pending anchor state, but the wallet could not find a matching clearable reserved anchor family.",
-            next: "Run `cogcoin repair`, then inspect the domain again before retrying `cogcoin anchor clear`.",
+            what: "The sat/vB value is invalid.",
+            why: "`--satvb` accepts only a positive finite decimal number such as `12` or `12.5`.",
+            next: "Choose a positive sat/vB value and retry.",
         };
     }
-    if (errorCode.startsWith("wallet_anchor_clear_pending_first_")) {
-        const domainName = errorCode.slice("wallet_anchor_clear_pending_first_".length) || "<domain>";
+    if (errorCode === "cli_satvb_not_supported_for_command") {
         return {
-            what: `A local pending anchor already exists for "${domainName}".`,
-            why: "The wallet found a same-domain anchor reservation that is still local-only and safely clearable, so it stopped before creating a conflicting family.",
-            next: `Run \`cogcoin anchor clear ${domainName}\`, then rerun \`cogcoin anchor ${domainName}\`.`,
+            what: "This command does not support `--satvb`.",
+            why: "The fee-rate override only applies to wallet mutation commands that build and broadcast transactions.",
+            next: "Drop `--satvb` for this command, or use it with a wallet mutation command like `cogcoin register` or `cogcoin send`.",
         };
     }
-    if (errorCode.startsWith("wallet_anchor_clear_not_clearable_")) {
+    if (errorCode === "cli_anchor_clear_removed") {
         return {
-            what: "Pending anchor cannot be cleared safely.",
-            why: "This command only clears a local pre-broadcast reservation. The anchor family is already beyond that safe stage or may have been observed by the wallet.",
-            next: "Rerun `cogcoin anchor <domain>` to reconcile the family, or run `cogcoin repair` if it remains unresolved.",
+            what: "`anchor clear` is no longer available.",
+            why: "Anchor is now a direct single-transaction wallet mutation, so there is no separate cleanup command for reserved local workflow state.",
+            next: "Retry with `cogcoin anchor <domain>` or inspect the domain with `cogcoin show <domain>`.",
         };
     }
-    if (errorCode === "mining_hooks_enable_trust_acknowledgement_required") {
+    if (errorCode === "cli_wallet_export_removed") {
         return {
-            what: "Trust acknowledgement is still required.",
-            why: "Enabling a custom mining hook grants unsandboxed local JavaScript full access to the current OS account and readable local data.",
-            next: "Rerun `cogcoin hooks enable mining` in an interactive terminal and type the requested trust acknowledgement.",
+            what: "`wallet export` is no longer available.",
+            why: "Portable encrypted wallet archives were removed from the client, so wallet state is no longer exported through a `.cogcoin` archive file.",
+            next: "Use the wallet mnemonic as the supported recovery path, or retry with another wallet command.",
         };
     }
-    if (errorCode === "mining_hooks_enable_template_created") {
+    if (errorCode === "cli_wallet_import_removed") {
         return {
-            what: "Default mining hook template was created.",
-            why: "The wallet wrote starter custom-hook files and stopped before enabling custom mode so you can review and edit them first.",
-            next: "Edit `generate-sentences.js`, then rerun `cogcoin hooks enable mining`.",
+            what: "`wallet import` is no longer available.",
+            why: "Portable encrypted wallet archives were removed from the client, so this version no longer imports wallet state from archive files.",
+            next: "Use `cogcoin restore --seed <name>` with the recovery mnemonic instead.",
         };
     }
-    if (errorCode === "mining_hooks_enable_validation_failed") {
+    if (errorCode === "cli_field_create_initial_value_not_supported") {
         return {
-            what: "Custom mining hook validation failed.",
-            why: "The hook files, package shape, trust checks, or isolated validation run did not pass the required checks.",
-            next: "Fix the custom mining hook and rerun `cogcoin hooks enable mining`.",
+            what: "`field create` no longer accepts an initial value.",
+            why: "Field creation is now always a single FIELD_REG transaction. Any field value must be written afterward with a separate `field set` command.",
+            next: "Create the field first, then run `cogcoin field set <domain> <field> ...`.",
         };
     }
     if (errorCode === "mining_setup_invalid_provider") {
@@ -516,32 +533,32 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
             next: "Rerun the command in an interactive terminal and enter the requested value.",
         };
     }
-    if (errorCode === "wallet_archive_passphrase_mismatch") {
+    if (errorCode === "wallet_secret_provider_linux_runtime_error") {
         return {
-            what: "Archive passphrases did not match.",
-            why: "The archive passphrase must be entered the same way twice so the wallet does not seal the archive with a typo.",
-            next: "Rerun the command and enter the same archive passphrase both times.",
+            what: "Linux local wallet-secret access failed.",
+            why: "Cogcoin could not read or write the local wallet secret file for this Linux account.",
+            next: "Check that the Cogcoin state directory is readable and writable for this Linux user, then retry.",
         };
     }
-    if (errorCode === "wallet_secret_provider_linux_secret_tool_missing") {
+    if (errorCode === "wallet_secret_provider_macos_runtime_error") {
         return {
-            what: "Linux secret-store support (`secret-tool`) is not installed.",
-            why: "Cogcoin uses `secret-tool` to talk to Secret Service on Linux, but that helper is not available in this environment.",
-            next: "Install `secret-tool`/libsecret for this machine, then rerun the command.",
+            what: "macOS local wallet-secret access failed.",
+            why: "Cogcoin could not read or write the password-protected local wallet secret file for this macOS account.",
+            next: "Check that the Cogcoin state directory is readable and writable for this macOS user, then retry.",
         };
     }
-    if (errorCode === "wallet_secret_provider_linux_secret_service_unavailable") {
+    if (errorCode === "wallet_secret_provider_windows_runtime_error") {
         return {
-            what: "Linux Secret Service is unavailable or locked.",
-            why: "The local Secret Service session could not be reached for wallet-secret storage, so the wallet cannot read or write its encryption keys.",
-            next: "Start or unlock your desktop keyring/Secret Service session, then rerun the command.",
+            what: "Windows local wallet-secret access failed.",
+            why: "Cogcoin could not read or write the local wallet secret file for this Windows account.",
+            next: "Check that the Cogcoin state directory is readable and writable for this Windows user, then retry.",
         };
     }
-    if (errorCode === "wallet_secret_provider_linux_runtime_error") {
+    if (errorCode === "wallet_state_legacy_envelope_unsupported") {
         return {
-            what: "Linux secret-store operation failed.",
-            why: "`secret-tool` ran but did not complete a usable wallet-secret operation for this command.",
-            next: "Check that Secret Service is running correctly on this machine, then retry.",
+            what: "Legacy wallet state is no longer supported.",
+            why: "This wallet state was created by an older Cogcoin format that this version no longer loads directly.",
+            next: "Restore or otherwise recover the wallet into the current format, then retry the command.",
         };
     }
     if (errorCode.endsWith("_requires_tty")) {
@@ -551,20 +568,6 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
             next: "Rerun the command in an interactive terminal.",
         };
     }
-    if (errorCode === "wallet_import_archive_not_found") {
-        return {
-            what: "Wallet archive was not found.",
-            why: "The specified import archive path does not exist or is not readable from this machine.",
-            next: "Check the archive path and retry.",
-        };
-    }
-    if (errorCode === "wallet_export_requires_quiescent_local_state") {
-        return {
-            what: "Wallet export is blocked until local state is quiescent.",
-            why: "Portable export waits for mining, proactive families, and pending mutations to settle so the archive reflects trustworthy local state.",
-            next: "Wait for active local work to finish or repair it, then retry the export.",
-        };
-    }
     if (errorCode.includes("tip_mismatch") || errorCode.includes("stale") || errorCode.includes("catching_up") || errorCode.includes("starting")) {
         return {
             what: "Trusted service state is not ready.",
@@ -656,95 +659,102 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
             next: "Review the local status output, finish the required setup or repair step, and retry.",
         };
     }
+    if (errorCode === "wallet_bitcoin_transfer_insufficient_funds") {
+        return {
+            what: "Wallet address does not have enough BTC.",
+            why: "The requested satoshi amount plus the mining fee exceeds the wallet's spendable BTC balance.",
+            next: "Reduce the amount or add more BTC to the wallet address, then retry.",
+        };
+    }
     if (errorCode.includes("insufficient")) {
         return {
             what: "Available funds are insufficient.",
-            why: "The selected wallet identity does not currently have enough spendable funds for this operation.",
-            next: "Choose a different identity or add more funds, then retry.",
+            why: "The wallet address does not currently have enough spendable funds for this operation.",
+            next: "Add more funds to the wallet address, then retry.",
         };
     }
     if (errorCode === "wallet_register_from_not_supported_for_subdomain") {
         return {
             what: "`--from` is not supported for subdomain registration.",
-            why: "Subdomain registration always derives the sender from the anchored parent owner, so this command will not accept an explicit sender override.",
-            next: "Retry without `--from`, or register a root domain if you need explicit sender selection.",
+            why: "Cogcoin now uses a single wallet address for local writes, so sender overrides are no longer part of subdomain registration.",
+            next: "Retry without `--from`.",
         };
     }
     if (errorCode === "wallet_register_sender_not_root_eligible") {
         return {
-            what: "Selected sender is not eligible for root registration.",
-            why: "Root registration can use funding identity `0` or a locally controlled anchored owner identity with a current canonical anchor outpoint.",
-            next: "Run `cogcoin ids`, then retry with `--from id:0` or an anchored local owner selector.",
+            what: "Root registration sender is not eligible.",
+            why: "Root registration now always uses the wallet address, and the local wallet state did not produce a usable sender.",
+            next: "Inspect `cogcoin address` and retry.",
         };
     }
     if (errorCode === "wallet_register_sender_not_found") {
         return {
-            what: "Selected sender was not found locally.",
-            why: "The provided selector did not resolve to a locally controlled identity in this wallet.",
-            next: "Run `cogcoin ids` and retry with one of the listed selectors.",
+            what: "Local sender was not found.",
+            why: "The wallet could not resolve a usable local wallet sender for this command.",
+            next: "Inspect `cogcoin address` and retry.",
         };
     }
     if (errorCode === "wallet_register_sender_read_only") {
         return {
-            what: "Selected sender is read-only.",
-            why: "This local identity is tracked for visibility only and cannot author new owner transactions.",
-            next: "Retry with a locally controlled non-read-only sender.",
+            what: "Wallet sender is not spendable.",
+            why: "This command needs the wallet address to author the transaction, but the local wallet sender is not spendable.",
+            next: "Check `cogcoin address`, restore the spendable wallet, and retry.",
         };
     }
     if (errorCode === "wallet_register_sender_address_unavailable") {
         return {
-            what: "Selected sender could not be displayed.",
-            why: "The selector resolved to a local identity, but the wallet does not have a usable display address for it.",
-            next: "Run `cogcoin ids` and retry with a different local sender selector.",
+            what: "Wallet address is unavailable.",
+            why: "The local wallet sender was resolved, but the wallet does not currently have a usable display address for it.",
+            next: "Inspect `cogcoin address` and retry.",
         };
     }
     if (errorCode === "wallet_buy_sender_not_found") {
         return {
-            what: "Selected buyer was not found locally.",
-            why: "The provided `--from` selector did not resolve to a locally controlled identity in this wallet.",
-            next: "Run `cogcoin ids` and retry with one of the listed selectors.",
+            what: "Local buyer was not found.",
+            why: "The wallet could not resolve a usable local wallet sender for this purchase.",
+            next: "Inspect `cogcoin address` and retry.",
         };
     }
     if (errorCode === "wallet_buy_sender_read_only") {
         return {
-            what: "Selected buyer is read-only.",
-            why: "This local identity is tracked for visibility only and cannot author a domain purchase.",
-            next: "Retry with a locally controlled non-read-only buyer selector.",
+            what: "Wallet sender is not spendable.",
+            why: "Buying now always uses the wallet address, but the local wallet sender is not spendable.",
+            next: "Check `cogcoin address`, restore the spendable wallet, and retry.",
         };
     }
     if (errorCode === "wallet_buy_sender_address_unavailable") {
         return {
-            what: "Selected buyer could not be displayed.",
-            why: "The selector resolved to a local identity, but the wallet does not have a usable display address for it.",
-            next: "Run `cogcoin ids` and retry with a different local buyer selector.",
+            what: "Wallet address is unavailable.",
+            why: "The wallet could not produce a usable display address for the local sender.",
+            next: "Inspect `cogcoin address` and retry.",
         };
     }
     if (errorCode === "wallet_buy_already_owner") {
         return {
-            what: "Selected buyer already owns the domain.",
-            why: "A buy mutation must come from a different local identity than the current domain owner.",
-            next: "Choose a different buyer with `--from`, or inspect the current owner with `cogcoin show <domain>`.",
+            what: "The wallet already owns the domain.",
+            why: "A buy mutation cannot target a domain already owned by this wallet address.",
+            next: "Inspect the current owner with `cogcoin show <domain>` and choose a different domain.",
         };
     }
     if (errorCode === "wallet_buy_insufficient_cog_balance") {
         return {
-            what: "Selected buyer does not have enough COG.",
-            why: "The chosen local identity does not currently have the listed domain price available in spendable COG balance.",
-            next: "Choose a different buyer or add more COG to that identity, then retry.",
+            what: "The wallet does not have enough COG.",
+            why: "The wallet address does not currently have the listed domain price available in spendable COG balance.",
+            next: "Add more COG to the wallet address, then retry.",
         };
     }
     if (errorCode === "wallet_transfer_owner_not_locally_controlled" || errorCode === "wallet_sell_owner_not_locally_controlled") {
         return {
             what: "Domain owner is not locally controlled.",
-            why: "This command must be authored by the current unanchored domain owner, and that owner identity is not available in this wallet with a usable address.",
-            next: "Inspect the current owner with `cogcoin show <domain>`, then retry from the wallet that controls that owner identity.",
+            why: "This command must be authored by the current unanchored domain owner, and that current owner script/address is not controlled by this wallet.",
+            next: "Inspect the current owner with `cogcoin show <domain>`, then retry from the wallet that controls the owner.",
         };
     }
     if (errorCode === "wallet_transfer_owner_read_only" || errorCode === "wallet_sell_owner_read_only") {
         return {
-            what: "Domain owner is read-only.",
-            why: "The current domain owner is tracked locally for visibility, but this wallet cannot author owner mutations from a read-only identity.",
-            next: "Use the wallet that controls the owner identity, or import the spendable owner into this wallet before retrying.",
+            what: "Domain owner is not spendable in this wallet.",
+            why: "The current domain owner is visible locally, but this wallet cannot author owner mutations from it.",
+            next: "Use the wallet that controls the owner, or import the spendable owner into this wallet before retrying.",
         };
     }
     if (errorCode === "wallet_field_create_owner_not_locally_controlled"
@@ -752,17 +762,17 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
         || errorCode === "wallet_field_clear_owner_not_locally_controlled") {
         return {
             what: "Anchored field owner is not locally controlled.",
-            why: "Field mutations must be authored by the current anchored owner of the domain, and that owner identity is not available in this wallet with a usable address.",
-            next: "Inspect the current owner with `cogcoin show <domain>`, then retry from the wallet that controls that anchored owner identity.",
+            why: "Field mutations must be authored by the current anchored owner of the domain, and that current owner script/address is not controlled by this wallet.",
+            next: "Inspect the current owner with `cogcoin show <domain>`, then retry from the wallet that controls the owner.",
         };
     }
     if (errorCode === "wallet_field_create_owner_read_only"
         || errorCode === "wallet_field_set_owner_read_only"
         || errorCode === "wallet_field_clear_owner_read_only") {
         return {
-            what: "Anchored field owner is read-only.",
-            why: "The current anchored owner is tracked locally for visibility, but this wallet cannot author field mutations from a read-only identity.",
-            next: "Use the wallet that controls the anchored owner identity, or import the spendable owner into this wallet before retrying.",
+            what: "Anchored field owner is not spendable in this wallet.",
+            why: "The current anchored owner is visible locally, but this wallet cannot author field mutations from it.",
+            next: "Use the wallet that controls the owner, or import the spendable owner into this wallet before retrying.",
         };
     }
     if (errorCode === "wallet_domain_endpoint_owner_not_locally_controlled"
@@ -771,8 +781,8 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
         || errorCode === "wallet_domain_canonical_owner_not_locally_controlled") {
         return {
             what: "Anchored domain owner is not locally controlled.",
-            why: "This anchored domain-admin command must be authored by the current anchored owner, and that owner identity is not available in this wallet with a usable address.",
-            next: "Inspect the current owner with `cogcoin show <domain>`, then retry from the wallet that controls that anchored owner identity.",
+            why: "This anchored domain-admin command must be authored by the current anchored owner, and that current owner script/address is not controlled by this wallet.",
+            next: "Inspect the current owner with `cogcoin show <domain>`, then retry from the wallet that controls the owner.",
         };
     }
     if (errorCode === "wallet_domain_endpoint_owner_read_only"
@@ -780,53 +790,95 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
         || errorCode === "wallet_domain_miner_owner_read_only"
         || errorCode === "wallet_domain_canonical_owner_read_only") {
         return {
-            what: "Anchored domain owner is read-only.",
-            why: "The current anchored owner is tracked locally for visibility, but this wallet cannot author anchored admin mutations from a read-only identity.",
-            next: "Use the wallet that controls the anchored owner identity, or import the spendable owner into this wallet before retrying.",
+            what: "Anchored domain owner is not spendable in this wallet.",
+            why: "The current anchored owner is visible locally, but this wallet cannot author anchored admin mutations from it.",
+            next: "Use the wallet that controls the owner, or import the spendable owner into this wallet before retrying.",
         };
     }
     if (errorCode === "wallet_rep_give_source_owner_not_locally_controlled"
         || errorCode === "wallet_rep_revoke_source_owner_not_locally_controlled") {
         return {
             what: "Anchored reputation source owner is not locally controlled.",
-            why: "Reputation mutations must be authored by the current anchored owner of the source domain, and that owner identity is not available in this wallet with a usable address.",
-            next: "Inspect the current source-domain owner with `cogcoin show <domain>`, then retry from the wallet that controls that anchored owner identity.",
+            why: "Reputation mutations must be authored by the current anchored owner of the source domain, and that current owner script/address is not controlled by this wallet.",
+            next: "Inspect the current source-domain owner with `cogcoin show <domain>`, then retry from the wallet that controls the owner.",
         };
     }
     if (errorCode === "wallet_rep_give_source_owner_read_only"
         || errorCode === "wallet_rep_revoke_source_owner_read_only") {
         return {
-            what: "Anchored reputation source owner is read-only.",
-            why: "The current anchored source-domain owner is tracked locally for visibility, but this wallet cannot author reputation mutations from a read-only identity.",
-            next: "Use the wallet that controls the anchored source-domain owner identity, or import the spendable owner into this wallet before retrying.",
+            what: "Anchored reputation source owner is not spendable in this wallet.",
+            why: "The current anchored source-domain owner is visible locally, but this wallet cannot author reputation mutations from it.",
+            next: "Use the wallet that controls the owner, or import the spendable owner into this wallet before retrying.",
         };
     }
     if (errorCode === "wallet_send_sender_address_unavailable" || errorCode === "wallet_lock_sender_address_unavailable") {
         return {
-            what: "Selected sender could not be displayed.",
-            why: "The wallet resolved a local sender identity, but it does not have a usable display address for that identity.",
-            next: "Run `cogcoin ids` and retry with a different local sender selector.",
+            what: "Wallet address is unavailable.",
+            why: "The wallet could not produce a usable display address for the local sender.",
+            next: "Inspect `cogcoin address` and retry.",
+        };
+    }
+    if (errorCode === "wallet_bitcoin_transfer_invalid_amount") {
+        return {
+            what: "Bitcoin transfer amount is invalid.",
+            why: "This command accepts only a positive whole-number satoshi amount such as `1200`.",
+            next: "Rerun `cogcoin bitcoin transfer <sats> --to <address>` with a positive integer satoshi amount.",
+        };
+    }
+    if (errorCode === "wallet_bitcoin_transfer_invalid_address") {
+        return {
+            what: "Bitcoin transfer recipient address is invalid.",
+            why: "This command only accepts a standard mainnet BTC address in `--to`.",
+            next: "Rerun `cogcoin bitcoin transfer <sats> --to <address>` with a valid mainnet BTC address.",
+        };
+    }
+    if (errorCode === "wallet_bitcoin_transfer_address_required") {
+        return {
+            what: "Bitcoin transfer recipient must be a standard BTC address.",
+            why: "V1 of this command does not support opaque script targets such as `spk:<hex>`.",
+            next: "Rerun `cogcoin bitcoin transfer <sats> --to <address>` with a standard mainnet BTC address.",
+        };
+    }
+    if (errorCode === "wallet_bitcoin_transfer_self_transfer") {
+        return {
+            what: "Bitcoin transfer recipient matches the wallet address.",
+            why: "This command rejects self-transfers to the wallet funding script/address.",
+            next: "Choose a different recipient address and retry.",
+        };
+    }
+    if (errorCode === "wallet_bitcoin_transfer_confirmation_rejected") {
+        return {
+            what: "Bitcoin transfer confirmation was rejected.",
+            why: "The interactive confirmation was declined before the BTC payment was broadcast.",
+            next: "Review the recipient address and amount, then rerun the command if you still want to send BTC.",
+        };
+    }
+    if (errorCode === "wallet_bitcoin_transfer_requires_tty") {
+        return {
+            what: "Bitcoin transfer confirmation needs an interactive terminal.",
+            why: "Without `--yes`, Cogcoin must ask for an interactive confirmation before publishing a BTC payment.",
+            next: "Rerun the command in an interactive terminal, or add `--yes` if that is appropriate for your workflow.",
         };
     }
     if (errorCode === "wallet_claim_sender_not_local") {
         return {
             what: "The claim sender is not locally controlled.",
             why: "Before timeout, the wallet may only claim as the current recipient-domain owner, and that owner is not available in this wallet.",
-            next: "Check the current recipient-domain owner with `cogcoin show <domain>` or use the wallet that controls that owner identity.",
+            next: "Check the current recipient-domain owner with `cogcoin show <domain>` or use the wallet that controls the owner.",
         };
     }
     if (errorCode === "wallet_reclaim_sender_not_local") {
         return {
             what: "The reclaim sender is not locally controlled.",
-            why: "After timeout, the wallet may only reclaim as the original locker, and that locker identity is not available in this wallet.",
-            next: "Use the wallet that controls the original locker identity, or inspect the lock details with `cogcoin locks`.",
+            why: "After timeout, the wallet may only reclaim as the original locker, and that locker is not controlled by this wallet.",
+            next: "Use the wallet that controls the original locker, or inspect the lock details with `cogcoin locks`.",
         };
     }
     if (errorCode.includes("ambiguous_sender") || errorCode.includes("no_eligible_sender")) {
         return {
             what: "Sender selection could not be resolved.",
-            why: "The wallet could not determine one eligible local sender for this command.",
-            next: "Inspect `cogcoin ids` and rerun the command with an explicit `--from` selector when supported.",
+            why: "The wallet could not determine a usable local sender for this command.",
+            next: "Inspect `cogcoin address` and `cogcoin status`, then retry.",
         };
     }
     if (classifiedAsBlockedMessage(errorCode)) {
@@ -854,21 +906,21 @@ export function describeCanonicalCommand(parsed) {
             return "cogcoin wallet delete";
         case "wallet-show-mnemonic":
             return "cogcoin wallet show-mnemonic";
-        case "unlock":
-        case "wallet-unlock":
-            return "cogcoin unlock";
+        case "client-unlock":
+            return "cogcoin client unlock";
+        case "client-lock":
+            return "cogcoin client lock";
+        case "client-change-password":
+            return "cogcoin client change-password";
+        case "bitcoin-transfer":
+            return `cogcoin bitcoin transfer ${args[0] ?? "<sats>"}`;
         case "reset":
             return "cogcoin reset";
         case "repair":
             return "cogcoin repair";
-        case "wallet-lock":
-            return "cogcoin wallet lock";
         case "anchor":
         case "domain-anchor":
             return `cogcoin anchor ${args[0] ?? "<domain>"}`;
-        case "anchor-clear":
-        case "domain-anchor-clear":
-            return `cogcoin anchor clear ${args[0] ?? "<domain>"}`;
         case "register":
         case "domain-register":
             return `cogcoin register ${args[0] ?? "<domain>"}`;
@@ -927,12 +979,6 @@ export function describeCanonicalCommand(parsed) {
             return "cogcoin ids";
         case "wallet-status":
             return "cogcoin wallet status";
-        case "hooks-mining-status":
-            return `cogcoin hooks status${parsed.verify ? " --verify" : ""}`;
-        case "hooks-mining-enable":
-            return "cogcoin hooks enable mining";
-        case "hooks-mining-disable":
-            return "cogcoin hooks disable mining";
         case "mine-setup":
             return "cogcoin mine setup";
         case "mine-start":
@@ -1002,8 +1048,6 @@ export function resolveStableJsonSchema(parsed) {
             return "cogcoin/ids/v1";
         case "wallet-status":
             return "cogcoin/wallet-status/v1";
-        case "hooks-mining-status":
-            return "cogcoin/hooks-status/v1";
         case "mine-status":
             return "cogcoin/mine-status/v1";
         case "mine-log":
@@ -1038,27 +1082,23 @@ export function resolveStableMutationJsonSchema(parsed) {
         case "restore":
         case "wallet-restore":
             return "cogcoin/restore/v1";
+        case "client-unlock":
+            return "cogcoin/client-unlock/v1";
+        case "client-lock":
+            return "cogcoin/client-lock/v1";
+        case "client-change-password":
+            return "cogcoin/client-change-password/v1";
+        case "bitcoin-transfer":
+            return "cogcoin/bitcoin-transfer/v1";
         case "wallet-delete":
             return "cogcoin/wallet-delete/v1";
-        case "unlock":
-        case "wallet-unlock":
-            return "cogcoin/unlock/v1";
         case "reset":
             return "cogcoin/reset/v1";
-        case "wallet-export":
-            return "cogcoin/wallet-export/v1";
-        case "wallet-import":
-            return "cogcoin/wallet-import/v1";
-        case "wallet-lock":
-            return "cogcoin/wallet-lock/v1";
         case "repair":
             return "cogcoin/repair/v1";
         case "anchor":
         case "domain-anchor":
             return "cogcoin/anchor/v1";
-        case "anchor-clear":
-        case "domain-anchor-clear":
-            return "cogcoin/anchor-clear/v1";
         case "register":
         case "domain-register":
             return "cogcoin/register/v1";
@@ -1115,10 +1155,6 @@ export function resolveStableMutationJsonSchema(parsed) {
 }
 export function resolveStableMiningControlJsonSchema(parsed) {
     switch (parsed.command) {
-        case "hooks-mining-enable":
-            return "cogcoin/hooks-enable-mining/v1";
-        case "hooks-mining-disable":
-            return "cogcoin/hooks-disable-mining/v1";
         case "mine-setup":
             return "cogcoin/mine-setup/v1";
         case "mine-start":
@@ -1133,13 +1169,10 @@ export function resolvePreviewJsonSchema(parsed) {
     const stableMutationSchema = resolveStableMutationJsonSchema(parsed);
     const stableMiningControlSchema = resolveStableMiningControlJsonSchema(parsed);
     switch (parsed.command) {
-        case "wallet-lock":
         case "reset":
         case "repair":
         case "anchor":
-        case "anchor-clear":
         case "domain-anchor":
-        case "domain-anchor-clear":
         case "register":
         case "domain-register":
         case "transfer":
@@ -1172,8 +1205,6 @@ export function resolvePreviewJsonSchema(parsed) {
             return stableMutationSchema === null
                 ? null
                 : stableMutationSchema.replace(/^cogcoin\//, "cogcoin-preview/");
-        case "hooks-mining-enable":
-        case "hooks-mining-disable":
         case "mine-setup":
         case "mine-start":
         case "mine-stop":
@@ -1197,6 +1228,7 @@ function createSchemaProbe(command) {
         seedName: null,
         unlockFor: null,
         assumeYes: false,
+        force: false,
         forceRace: false,
         anchorMessage: null,
         transferTarget: null,
@@ -1206,12 +1238,12 @@ function createSchemaProbe(command) {
         fieldPermanent: false,
         fieldFormat: null,
         fieldValue: null,
-        fromIdentity: null,
         lockRecipientDomain: null,
         conditionHex: null,
         untilHeight: null,
         preimageHex: null,
         reviewText: null,
+        satvb: null,
         locksClaimableOnly: false,
         locksReclaimableOnly: false,
         domainsAnchoredOnly: false,
@@ -1219,7 +1251,6 @@ function createSchemaProbe(command) {
         domainsMineableOnly: false,
         listLimit: null,
         listAll: false,
-        verify: false,
         follow: false,
     };
 }
@@ -1246,7 +1277,7 @@ export function isPreviewJsonOutputSupportedCommand(command) {
 }
 export function createCommandJsonErrorEnvelope(parsed, error) {
     const classified = classifyCliError(error);
-    const presentation = createCliErrorPresentation(classified.errorCode, classified.message);
+    const presentation = createCliErrorPresentation(classified.errorCode, classified.message, error);
     const humanMessage = presentation?.what ?? classified.message;
     const explanations = presentation?.why === null || presentation?.why === undefined ? [] : [presentation.why];
     const nextSteps = presentation?.next === null || presentation?.next === undefined ? [] : [presentation.next];
@@ -1291,17 +1322,9 @@ export function createCommandJsonErrorEnvelope(parsed, error) {
 function createCliErrorDetails(errorCode, humanMessage, rawMessage) {
     const details = {};
     const initMatch = /^wallet_init_confirmation_failed_word_(\d+)$/.exec(errorCode);
-    const hooksTemplateMatch = /^mining_hooks_enable_template_created:(.+)$/.exec(rawMessage);
-    const hooksValidationMatch = /^mining_hooks_enable_validation_failed:(.+)$/.exec(rawMessage);
     if (initMatch !== null) {
         details.wordIndex = Number.parseInt(initMatch[1], 10);
     }
-    if (hooksTemplateMatch !== null) {
-        details.hookRootPath = hooksTemplateMatch[1];
-    }
-    if (hooksValidationMatch !== null) {
-        details.validationError = hooksValidationMatch[1];
-    }
     if (humanMessage !== rawMessage) {
         details.rawMessage = rawMessage;
     }