@cogcoin/client 0.5.3 → 0.5.4

package/dist/cli/context.js

@@ -1,10 +1,17 @@
 import { mkdir, readFile } from "node:fs/promises";
+import { attachOrStartIndexerDaemon, probeIndexerDaemon, readObservedIndexerDaemonStatus, stopIndexerDaemonService, } from "../bitcoind/indexer-daemon.js";
+import { createRpcClient } from "../bitcoind/node.js";
+import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, stopManagedBitcoindService, } from "../bitcoind/service.js";
 import { resolveDefaultBitcoindDataDirForTesting, resolveDefaultClientDatabasePathForTesting, } from "../app-paths.js";
 import { openManagedBitcoindClient } from "../bitcoind/index.js";
 import { inspectPassiveClientStatus } from "../passive-status.js";
 import { openSqliteStore } from "../sqlite/index.js";
-import { exportWallet, importWallet, initializeWallet, lockWallet, repairWallet, unlockWallet, } from "../wallet/lifecycle.js";
+import { exportWallet, importWallet, initializeWallet, lockWallet, previewResetWallet, repairWallet, resetWallet, restoreWalletFromMnemonic, unlockWallet, } from "../wallet/lifecycle.js";
+import { resolveWalletRuntimePathsForTesting } from "../wallet/runtime.js";
 import { openWalletReadContext } from "../wallet/read/index.js";
+import { loadWalletExplicitLock } from "../wallet/state/explicit-lock.js";
+import { loadUnlockSession } from "../wallet/state/session.js";
+import { loadWalletState } from "../wallet/state/storage.js";
 import { disableMiningHooks, enableMiningHooks, followMiningLog, inspectMiningControlPlane, readMiningLog, runForegroundMining, setupBuiltInMining, startBackgroundMining, stopBackgroundMining, } from "../wallet/mining/index.js";
 import { createLazyDefaultWalletSecretProvider } from "../wallet/state/provider.js";
 import { anchorDomain, buyDomain, claimCogLock, clearDomainDelegate, clearDomainEndpoint, clearDomainMiner, clearField, createField, giveReputation, lockCogToDomain, registerDomain, reclaimCogLock, revokeReputation, sendCog, setField, setDomainCanonical, setDomainDelegate, setDomainEndpoint, setDomainMiner, sellDomain, transferDomain, } from "../wallet/tx/index.js";
@@ -28,6 +35,8 @@ export function createDefaultContext(overrides = {}) {
         inspectPassiveClientStatus: overrides.inspectPassiveClientStatus ?? inspectPassiveClientStatus,
         openWalletReadContext: overrides.openWalletReadContext ?? openWalletReadContext,
         initializeWallet: overrides.initializeWallet ?? initializeWallet,
+        restoreWalletFromMnemonic: overrides.restoreWalletFromMnemonic ?? restoreWalletFromMnemonic,
+        previewResetWallet: overrides.previewResetWallet ?? previewResetWallet,
         exportWallet: overrides.exportWallet ?? exportWallet,
         importWallet: overrides.importWallet ?? importWallet,
         unlockWallet: overrides.unlockWallet ?? unlockWallet,
@@ -63,13 +72,26 @@ export function createDefaultContext(overrides = {}) {
         readMiningLog: overrides.readMiningLog ?? readMiningLog,
         followMiningLog: overrides.followMiningLog ?? followMiningLog,
         repairWallet: overrides.repairWallet ?? repairWallet,
+        resetWallet: overrides.resetWallet ?? resetWallet,
         walletSecretProvider: overrides.walletSecretProvider ?? createLazyDefaultWalletSecretProvider(),
         createPrompter: overrides.createPrompter ?? (() => createTerminalPrompter(overrides.stdin ?? process.stdin, overrides.stdout ?? process.stdout)),
         ensureDirectory: overrides.ensureDirectory ?? (async (path) => {
             await mkdir(path, { recursive: true });
         }),
+        attachManagedBitcoindService: overrides.attachManagedBitcoindService ?? attachOrStartManagedBitcoindService,
+        probeManagedBitcoindService: overrides.probeManagedBitcoindService ?? probeManagedBitcoindService,
+        stopManagedBitcoindService: overrides.stopManagedBitcoindService ?? stopManagedBitcoindService,
+        createBitcoinRpcClient: overrides.createBitcoinRpcClient ?? createRpcClient,
+        attachIndexerDaemon: overrides.attachIndexerDaemon ?? attachOrStartIndexerDaemon,
+        probeIndexerDaemon: overrides.probeIndexerDaemon ?? probeIndexerDaemon,
+        readObservedIndexerDaemonStatus: overrides.readObservedIndexerDaemonStatus ?? readObservedIndexerDaemonStatus,
+        stopIndexerDaemonService: overrides.stopIndexerDaemonService ?? stopIndexerDaemonService,
         readPackageVersion: overrides.readPackageVersion ?? readPackageVersionFromDisk,
+        loadWalletState: overrides.loadWalletState ?? loadWalletState,
+        loadUnlockSession: overrides.loadUnlockSession ?? loadUnlockSession,
+        loadWalletExplicitLock: overrides.loadWalletExplicitLock ?? loadWalletExplicitLock,
         resolveDefaultBitcoindDataDir: overrides.resolveDefaultBitcoindDataDir ?? resolveDefaultBitcoindDataDirForTesting,
         resolveDefaultClientDatabasePath: overrides.resolveDefaultClientDatabasePath ?? resolveDefaultClientDatabasePathForTesting,
+        resolveWalletRuntimePaths: overrides.resolveWalletRuntimePaths ?? resolveWalletRuntimePathsForTesting,
     };
 }

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

@@ -1,5 +1,5 @@
 import type { AnchorDomainResult, CogMutationResult, DomainAdminMutationResult, DomainMarketMutationResult, FieldMutationResult, RegisterDomainResult, ReputationMutationResult } from "../wallet/tx/index.js";
-import type { WalletInitializationResult, WalletExportResult, WalletImportResult, WalletRepairResult, WalletUnlockResult } from "../wallet/lifecycle.js";
+import type { WalletInitializationResult, WalletExportResult, WalletImportResult, WalletRepairResult, WalletResetResult, WalletRestoreResult, WalletUnlockResult } from "../wallet/lifecycle.js";
 export declare function buildSingleTxMutationData(options: {
     kind: string;
     localStatus: string;
@@ -222,6 +222,13 @@ export declare function buildAnchorMutationData(result: AnchorDomainResult, opti
     };
     intent: Record<string, unknown>;
 };
+export declare function buildResetMutationData(result: WalletResetResult): {
+    resultType: "operation";
+    operation: {
+        kind: string;
+    };
+    state: Record<string, unknown> | null;
+};
 export declare function buildDomainAdminMutationData(result: DomainAdminMutationResult, options: {
     commandKind: "domain-endpoint-set" | "domain-endpoint-clear" | "domain-delegate-set" | "domain-delegate-clear" | "domain-miner-set" | "domain-miner-clear" | "domain-canonical";
 }): {
@@ -394,6 +401,15 @@ export declare function buildInitMutationData(result: WalletInitializationResult
     };
     state: Record<string, unknown>;
 };
+export declare function buildRestoreMutationData(result: WalletRestoreResult): {
+    resultType: "state-change";
+    stateChange: {
+        kind: string;
+        before: Record<string, unknown> | null;
+        after: Record<string, unknown> | null;
+    };
+    state: Record<string, unknown>;
+};
 export declare function buildUnlockMutationData(result: WalletUnlockResult): {
     resultType: "state-change";
     stateChange: {

package/dist/cli/mutation-json.js

@@ -140,6 +140,35 @@ export function buildAnchorMutationData(result, options) {
         },
     });
 }
+export function buildResetMutationData(result) {
+    return buildOperationData({
+        kind: "reset",
+        state: {
+            dataRoot: result.dataRoot,
+            factoryResetReady: result.factoryResetReady,
+            walletAction: result.walletAction,
+            walletOldRootId: result.walletOldRootId,
+            walletNewRootId: result.walletNewRootId,
+            bootstrapSnapshot: result.bootstrapSnapshot,
+            stoppedProcesses: result.stoppedProcesses,
+            secretCleanupStatus: result.secretCleanupStatus,
+        },
+        operation: {
+            dataRoot: result.dataRoot,
+            factoryResetReady: result.factoryResetReady,
+            stoppedProcesses: result.stoppedProcesses,
+            secretCleanupStatus: result.secretCleanupStatus,
+            deletedSecretRefs: result.deletedSecretRefs,
+            failedSecretRefs: result.failedSecretRefs,
+            preservedSecretRefs: result.preservedSecretRefs,
+            walletAction: result.walletAction,
+            walletOldRootId: result.walletOldRootId,
+            walletNewRootId: result.walletNewRootId,
+            bootstrapSnapshot: result.bootstrapSnapshot,
+            removedPaths: result.removedPaths,
+        },
+    });
+}
 export function buildDomainAdminMutationData(result, options) {
     const data = buildSingleTxMutationData({
         kind: options.commandKind,
@@ -242,6 +271,19 @@ export function buildInitMutationData(result) {
         after,
     });
 }
+export function buildRestoreMutationData(result) {
+    const after = {
+        walletRootId: result.walletRootId,
+        fundingAddress: result.fundingAddress,
+        unlockUntilUnixMs: result.unlockUntilUnixMs,
+        locked: false,
+    };
+    return buildStateChangeData({
+        kind: "restore",
+        state: after,
+        after,
+    });
+}
 export function buildUnlockMutationData(result) {
     const after = {
         walletRootId: result.state.walletRootId,

package/dist/cli/output.js

@@ -152,7 +152,12 @@ export function classifyCliError(error) {
     if (message === "wallet_typed_confirmation_rejected"
         || message === "wallet_export_overwrite_declined"
         || message === "wallet_prompt_value_required"
-        || message === "wallet_archive_passphrase_mismatch") {
+        || message === "wallet_archive_passphrase_mismatch"
+        || message === "wallet_restore_mnemonic_invalid"
+        || message === "wallet_restore_replace_confirmation_required"
+        || message === "reset_wallet_choice_invalid"
+        || message === "reset_wallet_passphrase_required"
+        || message === "reset_wallet_access_failed") {
         return { exitCode: 2, errorCode: message, message };
     }
     if (message === "not_found") {
@@ -161,6 +166,12 @@ export function classifyCliError(error) {
     if (message === "wallet_import_archive_not_found") {
         return { exitCode: 3, errorCode: message, message };
     }
+    if (message === "reset_process_shutdown_failed"
+        || message === "reset_data_root_delete_failed"
+        || message === "reset_secret_cleanup_failed"
+        || message === "reset_snapshot_preserve_failed") {
+        return { exitCode: 5, errorCode: message, message };
+    }
     if (isBlockedError(message)) {
         return { exitCode: 4, errorCode: message, message };
     }
@@ -215,6 +226,62 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
             next: "Run `cogcoin unlock --for 15m` and retry.",
         };
     }
+    if (errorCode === "reset_wallet_choice_invalid") {
+        return {
+            what: "Wallet reset choice is invalid.",
+            why: "This reset path accepts only Enter for the default entropy-retaining reset, \"skip\", or \"delete wallet\".",
+            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.",
+            why: "Cogcoin found wallet state, but it could not safely load and reconstruct it into a fresh wallet while preserving only the mnemonic-derived continuity data.",
+            next: "Rerun `cogcoin reset` and choose \"skip\" to keep the wallet unchanged, or type \"delete wallet\" to erase it fully.",
+        };
+    }
+    if (errorCode === "reset_process_shutdown_failed") {
+        return {
+            what: "Reset could not stop all tracked managed processes.",
+            why: "At least one Cogcoin-managed background process remained alive after the reset shutdown attempt, so the filesystem reset was aborted before deleting local state.",
+            next: "Stop the remaining managed process and rerun `cogcoin reset`.",
+        };
+    }
+    if (errorCode === "reset_data_root_delete_failed") {
+        return {
+            what: "Reset could not remove the local Cogcoin data roots.",
+            why: "The reset flow reached the destructive phase, but at least one local Cogcoin data root could not be deleted completely.",
+            next: "Check permissions and any open file handles under the Cogcoin data roots, then rerun `cogcoin reset`.",
+        };
+    }
+    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.",
+        };
+    }
+    if (errorCode === "reset_snapshot_preserve_failed") {
+        return {
+            what: "Reset could not preserve the downloaded 910000 UTXO snapshot.",
+            why: "You asked reset to keep the valid snapshot, but staging or restoring that large bootstrap file did not complete successfully.",
+            next: "Rerun `cogcoin reset` and choose to delete the snapshot, or restore the snapshot file manually before retrying.",
+        };
+    }
     if (errorCode === "wallet_uninitialized") {
         return {
             what: "Wallet is not initialized.",
@@ -222,6 +289,13 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
             next: "Run `cogcoin init` first.",
         };
     }
+    if (errorCode === "wallet_repair_indexer_reset_requires_yes") {
+        return {
+            what: "Repair needs permission to reset the local indexer database.",
+            why: "The local indexer database could not be opened as a healthy Cogcoin store, so repair would need to delete and rebuild it before continuing.",
+            next: "Rerun `cogcoin repair --yes` to allow repair to recreate the local indexer database.",
+        };
+    }
     if (errorCode === "wallet_already_initialized") {
         return {
             what: "Wallet is already initialized.",
@@ -264,6 +338,20 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
             next: "Run `cogcoin init` again and re-enter the requested confirmation words carefully.",
         };
     }
+    if (errorCode === "wallet_restore_mnemonic_invalid") {
+        return {
+            what: "Recovery phrase is invalid.",
+            why: "Mnemonic-only restore accepts only a valid 24-word English BIP39 phrase with a matching checksum.",
+            next: "Rerun `cogcoin restore` and enter the 24 recovery words in the original order.",
+        };
+    }
+    if (errorCode === "wallet_restore_replace_confirmation_required") {
+        return {
+            what: "Typed replacement acknowledgement is still required.",
+            why: "Mnemonic restore will replace the existing local wallet state and managed Core wallet replica only after you type the exact replacement acknowledgement.",
+            next: "Rerun `cogcoin restore` in an interactive terminal and type \"RESTORE\" when prompted.",
+        };
+    }
     if (errorCode === "mining_hooks_enable_trust_acknowledgement_required") {
         return {
             what: "Trust acknowledgement is still required.",
@@ -644,9 +732,14 @@ export function describeCanonicalCommand(parsed) {
         case "init":
         case "wallet-init":
             return "cogcoin init";
+        case "restore":
+        case "wallet-restore":
+            return "cogcoin restore";
         case "unlock":
         case "wallet-unlock":
             return "cogcoin unlock";
+        case "reset":
+            return "cogcoin reset";
         case "repair":
             return "cogcoin repair";
         case "wallet-lock":
@@ -767,6 +860,18 @@ export function resolveStableJsonSchema(parsed) {
     switch (parsed.command) {
         case "status":
             return "cogcoin/status/v1";
+        case "bitcoin-start":
+            return "cogcoin/bitcoin-start/v1";
+        case "bitcoin-stop":
+            return "cogcoin/bitcoin-stop/v1";
+        case "bitcoin-status":
+            return "cogcoin/bitcoin-status/v1";
+        case "indexer-start":
+            return "cogcoin/indexer-start/v1";
+        case "indexer-stop":
+            return "cogcoin/indexer-stop/v1";
+        case "indexer-status":
+            return "cogcoin/indexer-status/v1";
         case "wallet-address":
         case "address":
             return "cogcoin/address/v1";
@@ -808,9 +913,14 @@ export function resolveStableMutationJsonSchema(parsed) {
         case "init":
         case "wallet-init":
             return "cogcoin/init/v1";
+        case "restore":
+        case "wallet-restore":
+            return "cogcoin/restore/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":
@@ -897,6 +1007,7 @@ export function resolvePreviewJsonSchema(parsed) {
     const stableMiningControlSchema = resolveStableMiningControlJsonSchema(parsed);
     switch (parsed.command) {
         case "wallet-lock":
+        case "reset":
         case "repair":
         case "anchor":
         case "domain-anchor":

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  init                    Initialize a new local wallet root\n  init --output json      Emit the stable v1 machine-readable init result envelope\n  repair                  Recover bounded wallet/indexer/runtime state\n  unlock                  Clear an explicit wallet lock and unlock for a limited duration\n  wallet address          Alias for address\n  wallet ids              Alias for ids\n  hooks enable mining     Enable a validated custom mining hook\n  hooks disable mining    Return to built-in mining hooks\n  hooks status            Show mining hook validation and trust status\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 Tx1/Tx2 family\n  register <domain> [--from <identity>]\n                         Register a root domain or subdomain\n  transfer <domain> --to <btc-target>\n                          Transfer an unanchored domain to another BTC identity\n  sell <domain> <price>   List an unanchored domain for sale in COG\n  unsell <domain>         Clear an active domain listing\n  buy <domain> [--from <identity>]\n                         Buy an unanchored listed domain in COG\n  send <amount> --to <btc-target>\n                         Send COG from one local identity 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 unlock           Clear an explicit wallet lock and unlock for a limited duration\n  wallet lock             Lock the local wallet and disable on-demand unlock\n  wallet export <path>    Export a portable encrypted wallet archive\n  wallet import <path>    Import a portable encrypted wallet archive\n  address                 Show the BTC funding identity for this wallet\n  ids                     List locally controlled identities\n  balance                 Show per-identity 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 anchored field, optionally with an initial value\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>  Unlock duration like 15m, 2h, or 1d when unlocking explicitly\n  --message <text>  Founding message text for anchor\n  --to <btc-target> Transfer or send target as an address or spk:<hex>\n  --from <identity> Resolve sender identity as id:<n>, domain:<name>, 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  --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  --verify         Run full custom-hook verification\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  --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 init --output json\n  cogcoin wallet address\n  cogcoin domain list --mineable\n  cogcoin register alpha-child\n  cogcoin register weatherbot --from id:1\n  cogcoin anchor alpha\n  cogcoin buy alpha\n  cogcoin buy alpha --from id:1\n  cogcoin field create alpha bio --text \"hello\"\n  cogcoin rep give alpha beta 10 --review \"great operator\"\n  cogcoin hooks status\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  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  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 a fresh local wallet 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  unlock                  Clear an explicit wallet lock and unlock for a limited duration\n  wallet address          Alias for address\n  wallet ids              Alias for ids\n  hooks enable mining     Enable a validated custom mining hook\n  hooks disable mining    Return to built-in mining hooks\n  hooks status            Show mining hook validation and trust status\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 Tx1/Tx2 family\n  register <domain> [--from <identity>]\n                         Register a root domain or subdomain\n  transfer <domain> --to <btc-target>\n                          Transfer an unanchored domain to another BTC identity\n  sell <domain> <price>   List an unanchored domain for sale in COG\n  unsell <domain>         Clear an active domain listing\n  buy <domain> [--from <identity>]\n                         Buy an unanchored listed domain in COG\n  send <amount> --to <btc-target>\n                         Send COG from one local identity 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 a fresh local wallet from a 24-word mnemonic; run sync afterward\n  wallet unlock           Clear an explicit wallet lock and unlock for a limited duration\n  wallet lock             Lock the local wallet and disable on-demand unlock\n  wallet export <path>    Export a portable encrypted wallet archive\n  wallet import <path>    Import a portable encrypted wallet archive\n  address                 Show the BTC funding identity for this wallet\n  ids                     List locally controlled identities\n  balance                 Show per-identity 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 anchored field, optionally with an initial value\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>  Unlock duration like 15m, 2h, or 1d when unlocking explicitly\n  --message <text>  Founding message text for anchor\n  --to <btc-target> Transfer or send target as an address or spk:<hex>\n  --from <identity> Resolve sender identity as id:<n>, domain:<name>, 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  --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  --verify         Run full custom-hook verification\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  --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 wallet address\n  cogcoin domain list --mineable\n  cogcoin register alpha-child\n  cogcoin register weatherbot --from id:1\n  cogcoin anchor alpha\n  cogcoin buy alpha\n  cogcoin buy alpha --from id:1\n  cogcoin field create alpha bio --text \"hello\"\n  cogcoin rep give alpha beta 10 --review \"great operator\"\n  cogcoin hooks status\n  cogcoin mine setup --output json\n  cogcoin register alpha-child --output preview-json\n  cogcoin mine status\n";
 export declare function parseCliArgs(argv: string[]): ParsedCliArgs;

package/dist/cli/parse.js

@@ -4,8 +4,16 @@ 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
+  bitcoin start           Start the managed Bitcoin daemon
+  bitcoin stop            Stop the managed Bitcoin daemon and paired indexer
+  bitcoin status          Show managed Bitcoin daemon status without starting it
+  indexer start           Start the managed Cogcoin indexer (and bitcoind if needed)
+  indexer stop            Stop the managed Cogcoin indexer only
+  indexer status          Show managed Cogcoin indexer status without starting it
   init                    Initialize a new local wallet root
   init --output json      Emit the stable v1 machine-readable init result envelope
+  restore                 Restore a fresh local wallet from a 24-word mnemonic; run sync afterward
+  reset                   Factory-reset local Cogcoin state with interactive retention prompts
   repair                  Recover bounded wallet/indexer/runtime state
   unlock                  Clear an explicit wallet lock and unlock for a limited duration
   wallet address          Alias for address
@@ -39,6 +47,7 @@ Commands:
                          Lock COG to an anchored recipient domain
   wallet status           Show detailed wallet-local status and service health
   wallet init             Initialize a new local wallet root
+  wallet restore          Restore a fresh local wallet from a 24-word mnemonic; run sync afterward
   wallet unlock           Clear an explicit wallet lock and unlock for a limited duration
   wallet lock             Lock the local wallet and disable on-demand unlock
   wallet export <path>    Export a portable encrypted wallet archive
@@ -110,6 +119,8 @@ Quickstart:
 
 Examples:
   cogcoin status --output json
+  cogcoin bitcoin status
+  cogcoin indexer status
   cogcoin init --output json
   cogcoin wallet address
   cogcoin domain list --mineable
@@ -435,6 +446,11 @@ export function parseCliArgs(argv) {
                     index += 1;
                     continue;
                 }
+                if (subcommand === "restore") {
+                    command = "wallet-restore";
+                    index += 1;
+                    continue;
+                }
                 if (subcommand === "unlock") {
                     command = "wallet-unlock";
                     index += 1;
@@ -457,6 +473,44 @@ export function parseCliArgs(argv) {
                 }
                 throw new Error(`cli_unknown_command_wallet${subcommand === null ? "" : `_${subcommand}`}`);
             }
+            if (token === "bitcoin") {
+                const subcommand = argv[index + 1] ?? null;
+                if (subcommand === "start") {
+                    command = "bitcoin-start";
+                    index += 1;
+                    continue;
+                }
+                if (subcommand === "stop") {
+                    command = "bitcoin-stop";
+                    index += 1;
+                    continue;
+                }
+                if (subcommand === "status") {
+                    command = "bitcoin-status";
+                    index += 1;
+                    continue;
+                }
+                throw new Error(`cli_unknown_command_bitcoin${subcommand === null ? "" : `_${subcommand}`}`);
+            }
+            if (token === "indexer") {
+                const subcommand = argv[index + 1] ?? null;
+                if (subcommand === "start") {
+                    command = "indexer-start";
+                    index += 1;
+                    continue;
+                }
+                if (subcommand === "stop") {
+                    command = "indexer-stop";
+                    index += 1;
+                    continue;
+                }
+                if (subcommand === "status") {
+                    command = "indexer-status";
+                    index += 1;
+                    continue;
+                }
+                throw new Error(`cli_unknown_command_indexer${subcommand === null ? "" : `_${subcommand}`}`);
+            }
             if (token === "hooks") {
                 const subcommand = argv[index + 1] ?? null;
                 if (subcommand === "status") {
@@ -678,6 +732,8 @@ export function parseCliArgs(argv) {
                 continue;
             }
             if (token === "init"
+                || token === "restore"
+                || token === "reset"
                 || token === "repair"
                 || token === "sync"
                 || token === "status"
@@ -707,9 +763,18 @@ export function parseCliArgs(argv) {
         args.push(token);
     }
     if ((command === "status"
+        || command === "bitcoin-start"
+        || command === "bitcoin-stop"
+        || command === "bitcoin-status"
+        || command === "indexer-start"
+        || command === "indexer-stop"
+        || command === "indexer-status"
         || command === "init"
+        || command === "restore"
+        || command === "reset"
         || command === "unlock"
         || command === "wallet-init"
+        || command === "wallet-restore"
         || command === "wallet-lock"
         || command === "wallet-unlock"
         || command === "wallet-status"

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

@@ -1,5 +1,5 @@
 import type { AnchorDomainResult, CogMutationResult, DomainAdminMutationResult, DomainMarketMutationResult, FieldMutationResult, RegisterDomainResult, ReputationMutationResult } from "../wallet/tx/index.js";
-import type { WalletRepairResult } from "../wallet/lifecycle.js";
+import type { WalletRepairResult, WalletResetPreview } from "../wallet/lifecycle.js";
 import type { MiningControlPlaneView, MiningRuntimeStatusV1 } from "../wallet/mining/index.js";
 export declare function buildSingleTxMutationPreviewData(options: {
     kind: string;
@@ -71,6 +71,17 @@ export declare function buildStateChangePreviewData(options: {
     };
     state: Record<string, unknown>;
 };
+export declare function buildOperationPreviewData(options: {
+    kind: string;
+    state?: Record<string, unknown> | null;
+    operation: Record<string, unknown>;
+}): {
+    resultType: "operation";
+    operation: {
+        kind: string;
+    };
+    state: Record<string, unknown> | null;
+};
 export declare function buildRegisterPreviewData(result: RegisterDomainResult, options: {
     forceRace: boolean;
     fromIdentity: string | null;
@@ -375,6 +386,13 @@ export declare function buildWalletLockPreviewData(result: {
     };
     state: Record<string, unknown>;
 };
+export declare function buildResetPreviewData(result: WalletResetPreview): {
+    resultType: "operation";
+    operation: {
+        kind: string;
+    };
+    state: Record<string, unknown> | null;
+};
 export declare function buildRepairPreviewData(result: WalletRepairResult): {
     resultType: "state-change";
     stateChange: {

package/dist/cli/preview-json.js

@@ -47,6 +47,16 @@ export function buildStateChangePreviewData(options) {
         state: options.state,
     };
 }
+export function buildOperationPreviewData(options) {
+    return {
+        resultType: "operation",
+        operation: {
+            kind: options.kind,
+            ...options.operation,
+        },
+        state: options.state ?? null,
+    };
+}
 export function buildRegisterPreviewData(result, options) {
     return {
         ...buildSingleTxMutationPreviewData({
@@ -216,6 +226,27 @@ export function buildWalletLockPreviewData(result) {
         },
     });
 }
+export function buildResetPreviewData(result) {
+    return buildOperationPreviewData({
+        kind: "reset",
+        state: {
+            dataRoot: result.dataRoot,
+            trackedProcessKinds: result.trackedProcessKinds,
+            willDeleteOsSecrets: result.willDeleteOsSecrets,
+            bootstrapSnapshot: result.bootstrapSnapshot,
+            walletPrompt: result.walletPrompt,
+        },
+        operation: {
+            dataRoot: result.dataRoot,
+            confirmationPhrase: result.confirmationPhrase,
+            walletPrompt: result.walletPrompt,
+            bootstrapSnapshot: result.bootstrapSnapshot,
+            trackedProcessKinds: result.trackedProcessKinds,
+            willDeleteOsSecrets: result.willDeleteOsSecrets,
+            removedPaths: result.removedPaths,
+        },
+    });
+}
 export function buildRepairPreviewData(result) {
     return buildStateChangePreviewData({
         kind: "repair",

package/dist/cli/prompt.js

@@ -1,25 +1,53 @@
 import { createInterface } from "node:readline/promises";
 const CLEAR_SENSITIVE_DISPLAY_SEQUENCE = "\u001B[2J\u001B[3J\u001B[H";
 export function createTerminalPrompter(input, output) {
+    const ensureReadableInput = () => {
+        if (!("on" in input) || !("off" in input)) {
+            throw new Error("wallet_prompt_input_unavailable");
+        }
+        return input;
+    };
+    const ensureWritableOutput = () => output;
+    const ask = async (message, questionOutput) => {
+        const readline = createInterface({
+            input: ensureReadableInput(),
+            output: questionOutput,
+        });
+        try {
+            return await readline.question(message);
+        }
+        finally {
+            readline.close();
+        }
+    };
     return {
         isInteractive: Boolean(input.isTTY && output.isTTY),
         writeLine(message) {
             output.write(`${message}\n`);
         },
         async prompt(message) {
-            if (!("on" in input) || !("off" in input)) {
-                throw new Error("wallet_prompt_input_unavailable");
-            }
-            const readline = createInterface({
-                input: input,
-                output: output,
+            return await ask(message, ensureWritableOutput());
+        },
+        async promptHidden(message) {
+            const writableOutput = ensureWritableOutput();
+            let promptShown = false;
+            const hiddenOutput = Object.create(writableOutput);
+            hiddenOutput.write = ((chunk) => {
+                if (!promptShown) {
+                    promptShown = true;
+                    output.write(chunk);
+                    return true;
+                }
+                if (chunk === "\n" || chunk === "\r\n") {
+                    output.write(chunk);
+                }
+                return true;
             });
-            try {
-                return await readline.question(message);
-            }
-            finally {
-                readline.close();
-            }
+            hiddenOutput.on ??= (() => hiddenOutput);
+            hiddenOutput.once ??= (() => hiddenOutput);
+            hiddenOutput.off ??= (() => hiddenOutput);
+            hiddenOutput.removeListener ??= (() => hiddenOutput);
+            return await ask(message, hiddenOutput);
         },
         clearSensitiveDisplay(scope) {
             if (!input.isTTY || !output.isTTY) {