@cogcoin/client 0.5.4 → 0.5.6

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  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 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 show-mnemonic    Reveal the initialized wallet recovery phrase after typed confirmation\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

@@ -48,6 +48,7 @@ Commands:
   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 show-mnemonic    Reveal the initialized wallet recovery phrase after typed confirmation
   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
@@ -451,6 +452,11 @@ export function parseCliArgs(argv) {
                     index += 1;
                     continue;
                 }
+                if (subcommand === "show-mnemonic") {
+                    command = "wallet-show-mnemonic";
+                    index += 1;
+                    continue;
+                }
                 if (subcommand === "unlock") {
                     command = "wallet-unlock";
                     index += 1;

package/dist/cli/preview-json.js

@@ -234,6 +234,7 @@ export function buildResetPreviewData(result) {
             trackedProcessKinds: result.trackedProcessKinds,
             willDeleteOsSecrets: result.willDeleteOsSecrets,
             bootstrapSnapshot: result.bootstrapSnapshot,
+            bitcoinDataDir: result.bitcoinDataDir,
             walletPrompt: result.walletPrompt,
         },
         operation: {
@@ -241,6 +242,7 @@ export function buildResetPreviewData(result) {
             confirmationPhrase: result.confirmationPhrase,
             walletPrompt: result.walletPrompt,
             bootstrapSnapshot: result.bootstrapSnapshot,
+            bitcoinDataDir: result.bitcoinDataDir,
             trackedProcessKinds: result.trackedProcessKinds,
             willDeleteOsSecrets: result.willDeleteOsSecrets,
             removedPaths: result.removedPaths,

package/dist/cli/runner.js

@@ -77,6 +77,7 @@ export async function runCli(argv, contextOverrides = {}) {
             || parsed.command === "wallet-import"
             || parsed.command === "wallet-init"
             || parsed.command === "wallet-restore"
+            || parsed.command === "wallet-show-mnemonic"
             || parsed.command === "wallet-unlock"
             || parsed.command === "wallet-lock") {
             return runWalletAdminCommand(parsed, context);

package/dist/cli/types.d.ts

@@ -5,17 +5,17 @@ import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, stopM
 import { openSqliteStore } from "../sqlite/index.js";
 import type { ClientStoreAdapter } from "../types.js";
 import type { WalletRuntimePaths } from "../wallet/runtime.js";
-import type { exportWallet, WalletPrompter, importWallet, initializeWallet, lockWallet, previewResetWallet, repairWallet, resetWallet, restoreWalletFromMnemonic, unlockWallet } from "../wallet/lifecycle.js";
+import type { exportWallet, WalletPrompter, importWallet, initializeWallet, lockWallet, previewResetWallet, repairWallet, resetWallet, restoreWalletFromMnemonic, showWalletMnemonic, unlockWallet } from "../wallet/lifecycle.js";
 import type { 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 { loadRawWalletStateEnvelope, loadWalletState } from "../wallet/state/storage.js";
 import type { WalletSecretProvider } from "../wallet/state/provider.js";
 import type { disableMiningHooks, enableMiningHooks, followMiningLog, inspectMiningControlPlane, readMiningLog, runForegroundMining, setupBuiltInMining, startBackgroundMining, stopBackgroundMining } from "../wallet/mining/index.js";
 import type { 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";
 export type ProgressOutput = "auto" | "tty" | "none";
 export type OutputMode = "text" | "json" | "preview-json";
-export type CommandName = "init" | "restore" | "reset" | "repair" | "sync" | "status" | "follow" | "bitcoin-start" | "bitcoin-stop" | "bitcoin-status" | "indexer-start" | "indexer-stop" | "indexer-status" | "unlock" | "anchor" | "domain-anchor" | "register" | "domain-register" | "transfer" | "domain-transfer" | "sell" | "domain-sell" | "unsell" | "domain-unsell" | "buy" | "domain-buy" | "domain-endpoint-set" | "domain-endpoint-clear" | "domain-delegate-set" | "domain-delegate-clear" | "domain-miner-set" | "domain-miner-clear" | "domain-canonical" | "field-list" | "field-show" | "field-create" | "field-set" | "field-clear" | "send" | "claim" | "reclaim" | "cog-send" | "cog-claim" | "cog-reclaim" | "cog-lock" | "rep-give" | "rep-revoke" | "cog-balance" | "cog-locks" | "hooks-mining-enable" | "hooks-mining-disable" | "hooks-mining-status" | "mine" | "mine-start" | "mine-stop" | "mine-setup" | "mine-status" | "mine-log" | "wallet-export" | "wallet-import" | "wallet-init" | "wallet-restore" | "wallet-lock" | "wallet-unlock" | "wallet-status" | "wallet-address" | "wallet-ids" | "address" | "ids" | "balance" | "locks" | "domain-list" | "domains" | "domain-show" | "show" | "fields" | "field";
+export type CommandName = "init" | "restore" | "reset" | "repair" | "sync" | "status" | "follow" | "bitcoin-start" | "bitcoin-stop" | "bitcoin-status" | "indexer-start" | "indexer-stop" | "indexer-status" | "unlock" | "anchor" | "domain-anchor" | "register" | "domain-register" | "transfer" | "domain-transfer" | "sell" | "domain-sell" | "unsell" | "domain-unsell" | "buy" | "domain-buy" | "domain-endpoint-set" | "domain-endpoint-clear" | "domain-delegate-set" | "domain-delegate-clear" | "domain-miner-set" | "domain-miner-clear" | "domain-canonical" | "field-list" | "field-show" | "field-create" | "field-set" | "field-clear" | "send" | "claim" | "reclaim" | "cog-send" | "cog-claim" | "cog-reclaim" | "cog-lock" | "rep-give" | "rep-revoke" | "cog-balance" | "cog-locks" | "hooks-mining-enable" | "hooks-mining-disable" | "hooks-mining-status" | "mine" | "mine-start" | "mine-stop" | "mine-setup" | "mine-status" | "mine-log" | "wallet-export" | "wallet-import" | "wallet-init" | "wallet-restore" | "wallet-show-mnemonic" | "wallet-lock" | "wallet-unlock" | "wallet-status" | "wallet-address" | "wallet-ids" | "address" | "ids" | "balance" | "locks" | "domain-list" | "domains" | "domain-show" | "show" | "fields" | "field";
 export interface WritableLike {
     isTTY?: boolean;
     write(chunk: string): void;
@@ -93,6 +93,7 @@ export interface CliRunnerContext {
         store: ClientStoreAdapter;
         databasePath?: string;
         dataDir?: string;
+        walletRootId?: string;
         progressOutput?: ProgressOutput;
     }) => Promise<ManagedClientLike>;
     attachManagedBitcoindService?: typeof attachOrStartManagedBitcoindService;
@@ -106,6 +107,7 @@ export interface CliRunnerContext {
     inspectPassiveClientStatus?: typeof inspectPassiveClientStatus;
     openWalletReadContext?: typeof openWalletReadContext;
     loadWalletState?: typeof loadWalletState;
+    loadRawWalletStateEnvelope?: typeof loadRawWalletStateEnvelope;
     loadUnlockSession?: typeof loadUnlockSession;
     loadWalletExplicitLock?: typeof loadWalletExplicitLock;
     initializeWallet?: typeof initializeWallet;
@@ -113,6 +115,7 @@ export interface CliRunnerContext {
     previewResetWallet?: typeof previewResetWallet;
     exportWallet?: typeof exportWallet;
     importWallet?: typeof importWallet;
+    showWalletMnemonic?: typeof showWalletMnemonic;
     unlockWallet?: typeof unlockWallet;
     lockWallet?: typeof lockWallet;
     registerDomain?: typeof registerDomain;

package/dist/cli/types.js

@@ -5,4 +5,4 @@ import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, stopM
 import { openSqliteStore } from "../sqlite/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 { loadRawWalletStateEnvelope, loadWalletState } from "../wallet/state/storage.js";

package/dist/cli/wallet-format.js

@@ -329,24 +329,144 @@ function appendWalletAvailability(lines, context) {
         lines.push(`Mutation note: ${mutationRecommendation}`);
     }
 }
-export function formatWalletOverviewReport(context) {
+function overviewEntry(text, ok) {
+    return { text, ok };
+}
+function formatOverviewSection(header, entries) {
+    return [header, ...entries.map((entry) => `${entry.ok ? "✓" : "✗"} ${entry.text}`)].join("\n");
+}
+function isMiningOverviewOk(mining) {
+    return mining.runtime.bitcoindHealth === "ready"
+        && mining.runtime.nodeHealth === "synced"
+        && mining.runtime.indexerHealth === "synced"
+        && mining.runtime.miningState !== "repair-required"
+        && mining.runtime.miningState !== "paused-stale"
+        && !(mining.runtime.miningState === "paused" && mining.runtime.liveMiningFamilyInMempool === true);
+}
+function buildOverviewPathsSection(context) {
+    return [
+        overviewEntry(`DB path: ${context.databasePath}`, true),
+        overviewEntry(`Bitcoin datadir: ${context.dataDir}`, true),
+    ];
+}
+function buildOverviewWalletSection(context) {
+    const walletRoot = context.model?.walletRootId ?? context.localState.walletRootId ?? context.nodeStatus?.walletRootId ?? "none";
     const lines = [
-        "Cogcoin Status",
-        `DB path: ${context.databasePath}`,
-        `Bitcoin datadir: ${context.dataDir}`,
+        overviewEntry(`State: ${context.localState.availability}`, context.localState.availability === "ready"),
+        overviewEntry(`Root: ${walletRoot}`, walletRoot !== "none"),
+        overviewEntry(`Unlock: ${formatUnlockExpiry(context.localState.unlockUntilUnixMs)}`, context.localState.unlockUntilUnixMs !== null),
     ];
-    appendWalletAvailability(lines, context);
-    appendServiceSummary(lines, context);
-    if (context.model !== null) {
-        lines.push(`Local identities: ${context.model.identities.length}`);
-        lines.push(`Locally related domains: ${context.model.domains.length}`);
-        lines.push(`Read-only identities: ${context.model.readOnlyIdentityCount}`);
+    if (context.localState.message !== null) {
+        lines.push(overviewEntry(`Note: ${context.localState.message}`, false));
     }
-    else {
-        lines.push("Wallet-derived sections: unavailable");
+    const nodeStatus = context.nodeStatus;
+    const replica = nodeStatus?.walletReplica ?? null;
+    if (replica !== null) {
+        lines.push(overviewEntry(`Managed Core wallet: ${replica.proofStatus ?? "not-proven"}`, replica.proofStatus === "ready"));
     }
-    appendPendingMutationSummary(lines, context);
-    return lines.join("\n");
+    if (nodeStatus?.walletReplicaMessage) {
+        lines.push(overviewEntry(`Managed Core note: ${nodeStatus.walletReplicaMessage}`, replica?.proofStatus === "ready"));
+    }
+    return lines;
+}
+function buildOverviewServicesSection(context) {
+    const bitcoindOk = context.bitcoind.health === "ready";
+    const nodeOk = context.nodeHealth === "synced";
+    const indexerOk = context.indexer.health === "synced";
+    const lines = [
+        overviewEntry(`Managed bitcoind: ${formatServiceHealth(context.bitcoind.health)}`, bitcoindOk),
+    ];
+    if (context.bitcoind.message !== null) {
+        lines.push(overviewEntry(`Managed bitcoind note: ${context.bitcoind.message}`, bitcoindOk));
+    }
+    lines.push(overviewEntry(`Bitcoin service: ${formatServiceHealth(context.nodeHealth)}`, nodeOk));
+    if (context.nodeStatus !== null) {
+        lines.push(overviewEntry(`Bitcoin best height: ${formatMaybe(context.nodeStatus.nodeBestHeight)}`, nodeOk));
+        lines.push(overviewEntry(`Bitcoin headers: ${formatMaybe(context.nodeStatus.nodeHeaderHeight)}`, nodeOk));
+    }
+    if (context.nodeMessage !== null) {
+        lines.push(overviewEntry(`Bitcoin note: ${context.nodeMessage}`, nodeOk));
+    }
+    lines.push(overviewEntry(`Indexer service: ${formatServiceHealth(context.indexer.health)}`, indexerOk));
+    lines.push(overviewEntry(`Indexer truth source: ${formatIndexerTruthSource(context.indexer.source)}`, indexerOk));
+    if (context.indexer.daemonInstanceId !== null && context.indexer.daemonInstanceId !== undefined) {
+        lines.push(overviewEntry(`Indexer daemon instance: ${context.indexer.daemonInstanceId}`, indexerOk));
+    }
+    if (context.indexer.snapshotSeq !== null && context.indexer.snapshotSeq !== undefined) {
+        lines.push(overviewEntry(`Indexer snapshot sequence: ${context.indexer.snapshotSeq}`, indexerOk));
+    }
+    if (context.indexer.status?.reorgDepth !== null && context.indexer.status?.reorgDepth !== undefined) {
+        lines.push(overviewEntry(`Indexer reorg depth: ${context.indexer.status.reorgDepth}`, indexerOk));
+    }
+    lines.push(overviewEntry(`Indexer tip height: ${context.indexer.snapshotTip === null ? "unavailable" : context.indexer.snapshotTip.height}`, indexerOk));
+    if (context.indexer.message !== null) {
+        lines.push(overviewEntry(`Indexer note: ${context.indexer.message}`, indexerOk));
+    }
+    if (context.mining !== undefined) {
+        const miningOk = isMiningOverviewOk(context.mining);
+        lines.push(overviewEntry(`Mining: ${formatMiningSummaryLine(context.mining)}`, miningOk));
+        if (context.mining.runtime.note !== null) {
+            lines.push(overviewEntry(`Mining note: ${context.mining.runtime.note}`, miningOk));
+        }
+    }
+    return lines;
+}
+function buildOverviewLocalInventorySection(context) {
+    if (context.model === null) {
+        return [overviewEntry("Status: Wallet-derived sections unavailable", false)];
+    }
+    return [
+        overviewEntry(`Local identities: ${context.model.identities.length}`, true),
+        overviewEntry(`Locally related domains: ${context.model.domains.length}`, true),
+        overviewEntry(`Read-only identities: ${context.model.readOnlyIdentityCount}`, true),
+    ];
+}
+function buildOverviewPendingWorkSection(context) {
+    const pendingFamilies = (context.localState.state?.proactiveFamilies ?? [])
+        .filter((family) => (family.type === "anchor" || family.type === "field")
+        && family.status !== "confirmed"
+        && family.status !== "canceled");
+    const pendingMutations = (context.localState.state?.pendingMutations ?? [])
+        .filter((mutation) => mutation.status !== "confirmed" && mutation.status !== "canceled");
+    if (pendingFamilies.length === 0 && pendingMutations.length === 0) {
+        return [overviewEntry("Status: none", true)];
+    }
+    const lines = [];
+    for (const family of pendingFamilies) {
+        const label = family.type === "field"
+            ? `Field family: ${family.domainName ?? "unknown"}.${family.fieldName ?? "unknown"}`
+            : `Anchor family: ${family.domainName ?? "unknown"}`;
+        lines.push(overviewEntry(`${label}  ${family.status}${family.currentStep === null || family.currentStep === undefined ? "" : `  step ${family.currentStep}`}${family.reservedDedicatedIndex == null ? "" : `  index ${family.reservedDedicatedIndex}`}`, false));
+    }
+    for (const mutation of pendingMutations) {
+        lines.push(overviewEntry(`Mutation: ${formatPendingMutationSummaryLabel(mutation)}  ${mutation.status}  sender spk:${mutation.senderScriptPubKeyHex}${mutation.priceCogtoshi === undefined || mutation.priceCogtoshi === null ? "" : `  price ${formatCogAmount(mutation.priceCogtoshi)}`}${mutation.amountCogtoshi === undefined || mutation.amountCogtoshi === null ? "" : `  amount ${formatCogAmount(mutation.amountCogtoshi)}`}${isReputationMutation(mutation) ? "" : mutation.recipientDomainName === undefined || mutation.recipientDomainName === null ? "" : `  domain ${mutation.recipientDomainName}`}${mutation.lockId === undefined || mutation.lockId === null ? "" : `  lock ${mutation.lockId}`}${mutation.recipientScriptPubKeyHex === undefined || mutation.recipientScriptPubKeyHex === null ? "" : `  recipient spk:${mutation.recipientScriptPubKeyHex}`}${mutation.kind === "endpoint" ? (mutation.endpointValueHex === "" ? "  endpoint clear" : `  endpoint-bytes ${(mutation.endpointValueHex?.length ?? 0) / 2}`) : ""}${mutation.kind === "field-create" || mutation.kind === "field-set" ? `  format ${formatFieldFormat(mutation.fieldFormat ?? 0)}` : ""}${mutation.kind === "field-clear" ? "  clear" : ""}${mutation.reviewPayloadHex === undefined || mutation.reviewPayloadHex === null ? "" : "  review"}`, false));
+    }
+    return lines;
+}
+function getOverviewNextStep(context) {
+    const repairRecommendation = getRepairRecommendation(context);
+    if (repairRecommendation !== null) {
+        return repairRecommendation;
+    }
+    if (getBootstrapSyncNextStep(context) !== null) {
+        return "Run `cogcoin sync` to bootstrap assumeutxo and the managed Bitcoin/indexer state.";
+    }
+    return getMutationRecommendation(context);
+}
+export function formatWalletOverviewReport(context) {
+    const parts = [
+        "\n⛭ Cogcoin Status ⛭",
+        formatOverviewSection("Paths", buildOverviewPathsSection(context)),
+        formatOverviewSection("Wallet", buildOverviewWalletSection(context)),
+        formatOverviewSection("Services", buildOverviewServicesSection(context)),
+        formatOverviewSection("Local Inventory", buildOverviewLocalInventorySection(context)),
+        formatOverviewSection("Pending Work", buildOverviewPendingWorkSection(context)),
+    ];
+    const nextStep = getOverviewNextStep(context);
+    if (nextStep !== null) {
+        parts.push(`Next step: ${nextStep}`);
+    }
+    return parts.join("\n\n");
 }
 export function formatDetailedWalletStatusReport(context) {
     const lines = ["Cogcoin Wallet Status"];

package/dist/wallet/lifecycle.d.ts

@@ -156,6 +156,12 @@ export declare function initializeWallet(options: {
     attachService?: typeof attachOrStartManagedBitcoindService;
     rpcFactory?: (config: Parameters<typeof createRpcClient>[0]) => WalletLifecycleRpcClient;
 }): Promise<WalletInitializationResult>;
+export declare function showWalletMnemonic(options: {
+    provider?: WalletSecretProvider;
+    prompter: WalletPrompter;
+    nowUnixMs?: number;
+    paths?: WalletRuntimePaths;
+}): Promise<void>;
 export declare function unlockWallet(options?: {
     provider?: WalletSecretProvider;
     nowUnixMs?: number;

package/dist/wallet/lifecycle.js

@@ -3,7 +3,7 @@ import { access, constants, mkdir, readFile, readdir, rename, rm } from "node:fs
 import { dirname, join } from "node:path";
 import { openClient } from "../client.js";
 import { attachOrStartIndexerDaemon, probeIndexerDaemon, readSnapshotWithRetry, } from "../bitcoind/indexer-daemon.js";
-import { attachOrStartManagedBitcoindService, createManagedWalletReplica, probeManagedBitcoindService, } from "../bitcoind/service.js";
+import { attachOrStartManagedBitcoindService, createManagedWalletReplica, probeManagedBitcoindService, withClaimedUninitializedManagedRuntime, } from "../bitcoind/service.js";
 import { resolveManagedServicePaths } from "../bitcoind/service-paths.js";
 import { createRpcClient } from "../bitcoind/node.js";
 import { openSqliteStore } from "../sqlite/index.js";
@@ -19,9 +19,10 @@ import { loadMiningRuntimeStatus, saveMiningRuntimeStatus } from "./mining/runti
 import { normalizeMiningStateRecord } from "./mining/state.js";
 import { renderWalletMnemonicRevealArt } from "./mnemonic-art.js";
 import { clearWalletExplicitLock, loadWalletExplicitLock, saveWalletExplicitLock, } from "./state/explicit-lock.js";
+import { clearWalletPendingInitializationState, loadWalletPendingInitializationStateOrNull, saveWalletPendingInitializationState, } from "./state/pending-init.js";
 import { clearUnlockSession, loadUnlockSession, saveUnlockSession } from "./state/session.js";
-import { createDefaultWalletSecretProvider, createWalletRootId, createWalletSecretReference, } from "./state/provider.js";
-import { loadWalletState, saveWalletState } from "./state/storage.js";
+import { createDefaultWalletSecretProvider, createWalletPendingInitSecretReference, createWalletRootId, createWalletSecretReference, } from "./state/provider.js";
+import { extractWalletRootIdHintFromWalletStateEnvelope, loadRawWalletStateEnvelope, loadWalletState, saveWalletState, } from "./state/storage.js";
 export const DEFAULT_UNLOCK_DURATION_MS = 15 * 60 * 1000;
 export { previewResetWallet, resetWallet, } from "./reset.js";
 function sanitizeWalletName(walletRootId) {
@@ -47,20 +48,52 @@ async function readJsonFileOrNull(path) {
         return null;
     }
 }
-async function loadRawWalletEnvelope(paths) {
-    const primary = await readJsonFileOrNull(paths.walletStatePath);
-    if (primary !== null) {
-        return primary;
-    }
-    return readJsonFileOrNull(paths.walletStateBackupPath);
+function resolvePendingInitializationStoragePaths(paths) {
+    return {
+        primaryPath: paths.walletInitPendingPath,
+        backupPath: paths.walletInitPendingBackupPath,
+    };
 }
-function extractWalletRootIdFromEnvelope(envelope) {
-    const keyId = envelope?.secretProvider?.keyId ?? null;
-    const prefix = "wallet-state:";
-    if (keyId === null || !keyId.startsWith(prefix)) {
-        return null;
+async function clearPendingInitialization(paths, provider) {
+    await clearWalletPendingInitializationState(resolvePendingInitializationStoragePaths(paths), {
+        provider,
+        secretReference: createWalletPendingInitSecretReference(paths.stateRoot),
+    });
+}
+async function loadOrCreatePendingInitializationMaterial(options) {
+    try {
+        const loaded = await loadWalletPendingInitializationStateOrNull(resolvePendingInitializationStoragePaths(options.paths), {
+            provider: options.provider,
+        });
+        if (loaded !== null) {
+            return deriveWalletMaterialFromMnemonic(loaded.state.mnemonic.phrase);
+        }
+    }
+    catch {
+        await clearPendingInitialization(options.paths, options.provider);
+    }
+    const material = generateWalletMaterial();
+    const secretReference = createWalletPendingInitSecretReference(options.paths.stateRoot);
+    const pendingState = {
+        schemaVersion: 1,
+        createdAtUnixMs: options.nowUnixMs,
+        mnemonic: {
+            phrase: material.mnemonic.phrase,
+            language: material.mnemonic.language,
+        },
+    };
+    await options.provider.storeSecret(secretReference.keyId, randomBytes(32));
+    try {
+        await saveWalletPendingInitializationState(resolvePendingInitializationStoragePaths(options.paths), pendingState, {
+            provider: options.provider,
+            secretReference,
+        });
+    }
+    catch (error) {
+        await options.provider.deleteSecret(secretReference.keyId).catch(() => undefined);
+        throw error;
     }
-    return keyId.slice(prefix.length);
+    return material;
 }
 function createInitialWalletState(options) {
     return {
@@ -351,10 +384,10 @@ async function promptForRestoreMnemonic(prompter) {
     }
     return phrase;
 }
-async function confirmTypedAcknowledgement(prompter, expected, message) {
+async function confirmTypedAcknowledgement(prompter, expected, message, errorCode = "wallet_typed_confirmation_rejected") {
     const answer = (await prompter.prompt(message)).trim();
     if (answer !== expected) {
-        throw new Error("wallet_typed_confirmation_rejected");
+        throw new Error(errorCode);
     }
 }
 async function confirmRestoreReplacement(prompter) {
@@ -780,11 +813,29 @@ export function parseUnlockDurationToMs(raw) {
     }
     return duration;
 }
-async function ensureWalletNotInitialized(paths) {
+async function ensureWalletNotInitialized(paths, provider) {
     if (await pathExists(paths.walletStatePath) || await pathExists(paths.walletStateBackupPath)) {
+        await clearPendingInitialization(paths, provider);
         throw new Error("wallet_already_initialized");
     }
 }
+function isWalletSecretAccessError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message === "wallet_envelope_missing_secret_provider"
+        || message.startsWith("wallet_secret_missing_")
+        || message.startsWith("wallet_secret_provider_");
+}
+function writeMnemonicReveal(prompter, phrase, introLines) {
+    const words = phrase.trim().split(/\s+/);
+    for (const line of introLines) {
+        prompter.writeLine(line);
+    }
+    for (const line of renderWalletMnemonicRevealArt(words)) {
+        prompter.writeLine(line);
+    }
+    prompter.writeLine("Single-line copy:");
+    prompter.writeLine(phrase);
+}
 async function confirmMnemonic(prompter, words) {
     const challenge = createMnemonicConfirmationChallenge(words);
     for (const entry of challenge) {
@@ -1079,17 +1130,19 @@ export async function initializeWallet(options) {
         walletRootId: null,
     });
     try {
-        await ensureWalletNotInitialized(paths);
-        const material = generateWalletMaterial();
+        await ensureWalletNotInitialized(paths, provider);
+        const material = await loadOrCreatePendingInitializationMaterial({
+            provider,
+            paths,
+            nowUnixMs,
+        });
         let mnemonicRevealed = false;
-        options.prompter.writeLine("Cogcoin Wallet Initialization");
-        options.prompter.writeLine("Write down this 24-word recovery phrase. It will only be shown once:");
-        options.prompter.writeLine("");
-        for (const line of renderWalletMnemonicRevealArt(material.mnemonic.words)) {
-            options.prompter.writeLine(line);
-        }
-        options.prompter.writeLine("Single-line copy:");
-        options.prompter.writeLine(material.mnemonic.phrase);
+        writeMnemonicReveal(options.prompter, material.mnemonic.phrase, [
+            "Cogcoin Wallet Initialization",
+            "Write down this 24-word recovery phrase.",
+            "The same phrase will be shown again until confirmation succeeds:",
+            "",
+        ]);
         mnemonicRevealed = true;
         try {
             await confirmMnemonic(options.prompter, material.mnemonic.words);
@@ -1112,20 +1165,26 @@ export async function initializeWallet(options) {
             material,
             internalCoreWalletPassphrase,
         });
-        await saveWalletState({
-            primaryPath: paths.walletStatePath,
-            backupPath: paths.walletStateBackupPath,
-        }, initialState, {
-            provider,
-            secretReference,
+        const verifiedState = await withClaimedUninitializedManagedRuntime({
+            dataDir: options.dataDir,
+            walletRootId,
+        }, async () => {
+            await saveWalletState({
+                primaryPath: paths.walletStatePath,
+                backupPath: paths.walletStateBackupPath,
+            }, initialState, {
+                provider,
+                secretReference,
+            });
+            return importDescriptorIntoManagedCoreWallet(initialState, provider, paths, options.dataDir, nowUnixMs, options.attachService, options.rpcFactory);
         });
-        const verifiedState = await importDescriptorIntoManagedCoreWallet(initialState, provider, paths, options.dataDir, nowUnixMs, options.attachService, options.rpcFactory);
         const unlockUntilUnixMs = nowUnixMs + unlockDurationMs;
         await clearWalletExplicitLock(paths.walletExplicitLockPath);
         await saveUnlockSession(paths.walletUnlockSessionPath, createUnlockSession(verifiedState, unlockUntilUnixMs, secretReference.keyId, nowUnixMs), {
             provider,
             secretReference,
         });
+        await clearPendingInitialization(paths, provider);
         return {
             walletRootId,
             fundingAddress: verifiedState.funding.address,
@@ -1137,6 +1196,71 @@ export async function initializeWallet(options) {
         await controlLock.release();
     }
 }
+export async function showWalletMnemonic(options) {
+    if (!options.prompter.isInteractive) {
+        throw new Error("wallet_show_mnemonic_requires_tty");
+    }
+    const provider = options.provider ?? createDefaultWalletSecretProvider();
+    const nowUnixMs = options.nowUnixMs ?? Date.now();
+    const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
+    const controlLock = await acquireFileLock(paths.walletControlLockPath, {
+        purpose: "wallet-show-mnemonic",
+        walletRootId: null,
+    });
+    try {
+        const [hasPrimaryStateFile, hasBackupStateFile] = await Promise.all([
+            pathExists(paths.walletStatePath),
+            pathExists(paths.walletStateBackupPath),
+        ]);
+        if (!hasPrimaryStateFile && !hasBackupStateFile) {
+            throw new Error("wallet_uninitialized");
+        }
+        const unlocked = await loadOrAutoUnlockWalletState({
+            provider,
+            nowUnixMs,
+            paths,
+            controlLockHeld: true,
+        });
+        if (unlocked === null) {
+            try {
+                await loadWalletState({
+                    primaryPath: paths.walletStatePath,
+                    backupPath: paths.walletStateBackupPath,
+                }, {
+                    provider,
+                });
+            }
+            catch (error) {
+                if (isWalletSecretAccessError(error)) {
+                    throw new Error("wallet_locked");
+                }
+                throw new Error("local-state-corrupt");
+            }
+            throw new Error("wallet_locked");
+        }
+        await confirmTypedAcknowledgement(options.prompter, "show mnemonic", "Type \"show mnemonic\" to continue: ", "wallet_show_mnemonic_typed_ack_required");
+        let mnemonicRevealed = false;
+        writeMnemonicReveal(options.prompter, unlocked.state.mnemonic.phrase, [
+            "Cogcoin Wallet Recovery Phrase",
+            "This 24-word recovery phrase controls the wallet.",
+            "",
+        ]);
+        mnemonicRevealed = true;
+        try {
+            await options.prompter.prompt("Press Enter to clear the recovery phrase from the screen: ");
+        }
+        finally {
+            if (mnemonicRevealed) {
+                await Promise.resolve()
+                    .then(() => options.prompter.clearSensitiveDisplay?.("mnemonic-reveal"))
+                    .catch(() => undefined);
+            }
+        }
+    }
+    finally {
+        await controlLock.release();
+    }
+}
 export async function unlockWallet(options = {}) {
     const provider = options.provider ?? createDefaultWalletSecretProvider();
     const nowUnixMs = options.nowUnixMs ?? Date.now();
@@ -1290,6 +1414,7 @@ export async function importWallet(options) {
         const replacementStateExists = await pathExists(paths.walletStatePath) || await pathExists(paths.walletStateBackupPath);
         const importedWalletDir = join(options.dataDir, "wallets", sanitizeWalletName(payload.walletRootId));
         const replacementCoreWalletExists = await pathExists(importedWalletDir);
+        await clearPendingInitialization(paths, provider);
         if (replacementStateExists || replacementCoreWalletExists) {
             await confirmTypedAcknowledgement(options.prompter, "IMPORT", "Type IMPORT to replace the existing local wallet state and managed Core wallet replica: ");
         }
@@ -1333,6 +1458,7 @@ export async function importWallet(options) {
             provider,
             secretReference,
         });
+        await clearPendingInitialization(paths, provider);
         if (previousWalletRootId !== null && previousWalletRootId !== payload.walletRootId) {
             await provider.deleteSecret(createWalletSecretReference(previousWalletRootId).keyId).catch(() => undefined);
         }
@@ -1366,16 +1492,20 @@ export async function restoreWalletFromMnemonic(options) {
         walletRootId: null,
     });
     try {
-        const rawEnvelope = await loadRawWalletEnvelope(paths);
+        const rawEnvelope = await loadRawWalletStateEnvelope({
+            primaryPath: paths.walletStatePath,
+            backupPath: paths.walletStateBackupPath,
+        });
         const replacementStateExists = rawEnvelope !== null
             || await pathExists(paths.walletStatePath)
             || await pathExists(paths.walletStateBackupPath);
         const replacementCoreWalletExists = await detectExistingManagedWalletReplica(options.dataDir);
         const mnemonicPhrase = await promptForRestoreMnemonic(options.prompter);
+        await clearPendingInitialization(paths, provider);
         if (replacementStateExists || replacementCoreWalletExists) {
             await confirmRestoreReplacement(options.prompter);
         }
-        let previousWalletRootId = extractWalletRootIdFromEnvelope(rawEnvelope);
+        let previousWalletRootId = extractWalletRootIdHintFromWalletStateEnvelope(rawEnvelope?.envelope ?? null);
         try {
             const loaded = await loadWalletState({
                 primaryPath: paths.walletStatePath,
@@ -1425,6 +1555,7 @@ export async function restoreWalletFromMnemonic(options) {
                 provider,
                 secretReference,
             });
+            await clearPendingInitialization(paths, provider);
             if (previousWalletRootId !== null && previousWalletRootId !== walletRootId) {
                 try {
                     await clearPreviousManagedWalletRuntime({