@cogcoin/client 0.5.2 → 0.5.3

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@0.5.2` is the store-backed Cogcoin client package for applications that want a local wallet, durable SQLite-backed state, and a managed Bitcoin Core integration around `@cogcoin/indexer`. It publishes the reusable client APIs, the SQLite adapter, the managed `bitcoind` integration, and the first-party `cogcoin` CLI in one package.
+`@cogcoin/client@0.5.3` is the store-backed Cogcoin client package for applications that want a local wallet, durable SQLite-backed state, and a managed Bitcoin Core integration around `@cogcoin/indexer`. It publishes the reusable client APIs, the SQLite adapter, the managed `bitcoind` integration, and the first-party `cogcoin` CLI in one package.
 
 Use Node 22 or newer.
 
@@ -32,6 +32,8 @@ npx cogcoin sync
 
 Verify the installed genesis artifacts before using the client in a production implementation.
 The installed package provides the `cogcoin` command for local wallet setup, sync, reads, writes, and mining workflows.
+Provider-backed local wallets unlock on demand by default; `cogcoin wallet lock` suppresses that behavior until `cogcoin unlock` is run again.
+Passphrase-wrapped wallet-state flows still require explicit passphrase-based access.
 
 ## Dependency Surface
 
@@ -79,6 +81,7 @@ The installed `cogcoin` command covers the first-party local wallet and node wor
 - mining and hook commands such as `mine`, `mine start`, `mine stop`, `mine status`, `mine log`, `mine setup`, and `hooks status`
 
 The CLI also supports stable `--output json` and `--output preview-json` envelopes on the commands that advertise machine-readable output.
+For provider-backed local wallets, normal reads, mutations, export, and mining setup flows auto-materialize a local unlock session when the wallet is not explicitly locked.
 
 ## SQLite Store
 

package/dist/app-paths.d.ts

@@ -18,6 +18,7 @@ export interface CogcoinResolvedPaths {
     walletStatePath: string;
     walletStateBackupPath: string;
     walletUnlockSessionPath: string;
+    walletExplicitLockPath: string;
     walletControlLockPath: string;
     bitcoindLockPath: string;
     bitcoindStatusPath: string;

package/dist/app-paths.js

@@ -64,6 +64,7 @@ export function resolveCogcoinPathsForTesting(resolution = {}) {
     const walletStatePath = joinForPlatform(platform, walletStateDirectory, "wallet-state.enc");
     const walletStateBackupPath = joinForPlatform(platform, walletStateDirectory, "wallet-state.enc.bak");
     const walletUnlockSessionPath = joinForPlatform(platform, runtimeRoot, "wallet-unlock-session.enc");
+    const walletExplicitLockPath = joinForPlatform(platform, runtimeRoot, "wallet-explicit-lock.json");
     const walletControlLockPath = joinForPlatform(platform, runtimeRoot, "wallet-control.lock");
     const bitcoindLockPath = joinForPlatform(platform, runtimeRoot, "bitcoind.lock");
     const bitcoindStatusPath = joinForPlatform(platform, runtimeRoot, "bitcoind-status.json");
@@ -91,6 +92,7 @@ export function resolveCogcoinPathsForTesting(resolution = {}) {
         walletStatePath,
         walletStateBackupPath,
         walletUnlockSessionPath,
+        walletExplicitLockPath,
         walletControlLockPath,
         bitcoindLockPath,
         bitcoindStatusPath,

package/dist/cli/output.js

@@ -211,7 +211,7 @@ export function createCliErrorPresentation(errorCode, fallbackMessage) {
     if (errorCode === "wallet_locked") {
         return {
             what: "Wallet is locked.",
-            why: "This command needs access to the unlocked local wallet state before it can continue.",
+            why: "This command needs access to the unlocked local wallet state before it can continue. Provider-backed wallets unlock on demand unless they were explicitly locked or the local secret store is unavailable.",
             next: "Run `cogcoin unlock --for 15m` and retry.",
         };
     }

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                  Unlock the local wallet 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           Unlock the local wallet for a limited duration\n  wallet lock             Lock the local wallet immediately\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\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  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 function parseCliArgs(argv: string[]): ParsedCliArgs;

package/dist/cli/parse.js

@@ -7,7 +7,7 @@ Commands:
   init                    Initialize a new local wallet root
   init --output json      Emit the stable v1 machine-readable init result envelope
   repair                  Recover bounded wallet/indexer/runtime state
-  unlock                  Unlock the local wallet for a limited duration
+  unlock                  Clear an explicit wallet lock and unlock for a limited duration
   wallet address          Alias for address
   wallet ids              Alias for ids
   hooks enable mining     Enable a validated custom mining hook
@@ -39,8 +39,8 @@ 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 unlock           Unlock the local wallet for a limited duration
-  wallet lock             Lock the local wallet immediately
+  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
   wallet import <path>    Import a portable encrypted wallet archive
   address                 Show the BTC funding identity for this wallet
@@ -68,7 +68,7 @@ Commands:
 Options:
   --db <path>       Override the SQLite database path
   --data-dir <path> Override the managed bitcoin datadir
-  --for <duration>  Unlock duration like 15m, 2h, or 1d
+  --for <duration>  Unlock duration like 15m, 2h, or 1d when unlocking explicitly
   --message <text>  Founding message text for anchor
   --to <btc-target> Transfer or send target as an address or spk:<hex>
   --from <identity> Resolve sender identity as id:<n>, domain:<name>, address, or spk:<hex>

package/dist/wallet/lifecycle.d.ts

@@ -127,6 +127,16 @@ export declare function loadUnlockedWalletState(options?: {
     attachService?: typeof attachOrStartManagedBitcoindService;
     rpcFactory?: (config: Parameters<typeof createRpcClient>[0]) => WalletLifecycleRpcClient;
 }): Promise<LoadedUnlockedWalletState | null>;
+export declare function loadOrAutoUnlockWalletState(options?: {
+    provider?: WalletSecretProvider;
+    nowUnixMs?: number;
+    unlockDurationMs?: number;
+    paths?: WalletRuntimePaths;
+    dataDir?: string;
+    controlLockHeld?: boolean;
+    attachService?: typeof attachOrStartManagedBitcoindService;
+    rpcFactory?: (config: Parameters<typeof createRpcClient>[0]) => WalletLifecycleRpcClient;
+}): Promise<LoadedUnlockedWalletState | null>;
 export declare function initializeWallet(options: {
     dataDir: string;
     provider?: WalletSecretProvider;
@@ -146,6 +156,7 @@ export declare function unlockWallet(options?: {
 export declare function lockWallet(options: {
     dataDir: string;
     provider?: WalletSecretProvider;
+    nowUnixMs?: number;
     paths?: WalletRuntimePaths;
     attachService?: typeof attachOrStartManagedBitcoindService;
     rpcFactory?: (config: Parameters<typeof createRpcClient>[0]) => WalletLifecycleRpcClient;

package/dist/wallet/lifecycle.js

@@ -17,6 +17,7 @@ import { loadClientConfig } from "./mining/config.js";
 import { inspectMiningHookState } from "./mining/hooks.js";
 import { loadMiningRuntimeStatus, saveMiningRuntimeStatus } from "./mining/runtime-artifacts.js";
 import { normalizeMiningStateRecord } from "./mining/state.js";
+import { clearWalletExplicitLock, loadWalletExplicitLock, saveWalletExplicitLock, } from "./state/explicit-lock.js";
 import { clearUnlockSession, loadUnlockSession, saveUnlockSession } from "./state/session.js";
 import { createDefaultWalletSecretProvider, createWalletRootId, createWalletSecretReference, } from "./state/provider.js";
 import { loadWalletState, saveWalletState } from "./state/storage.js";
@@ -142,6 +143,54 @@ function createUnlockSession(state, unlockUntilUnixMs, secretKeyId, nowUnixMs) {
         wrappedSessionKeyMaterial: secretKeyId,
     };
 }
+function createWalletExplicitLock(walletRootId, nowUnixMs) {
+    return {
+        schemaVersion: 1,
+        walletRootId,
+        lockedAtUnixMs: nowUnixMs,
+    };
+}
+async function normalizeUnlockedWalletStateIfNeeded(options) {
+    let state = options.state;
+    let session = options.session;
+    let source = options.source;
+    if (options.dataDir !== undefined) {
+        const node = await (options.attachService ?? attachOrStartManagedBitcoindService)({
+            dataDir: options.dataDir,
+            chain: "main",
+            startHeight: 0,
+            walletRootId: state.walletRootId,
+        });
+        try {
+            const normalized = await persistNormalizedWalletDescriptorStateIfNeeded({
+                state,
+                access: {
+                    provider: options.provider,
+                    secretReference: createWalletSecretReference(state.walletRootId),
+                },
+                session,
+                paths: options.paths,
+                nowUnixMs: options.nowUnixMs,
+                replacePrimary: options.source === "backup",
+                rpc: (options.rpcFactory ?? createRpcClient)(node.rpc),
+            });
+            state = normalized.state;
+            session = normalized.session ?? session;
+            source = normalized.changed ? "primary" : options.source;
+        }
+        finally {
+            await node.stop?.().catch(() => undefined);
+        }
+    }
+    return {
+        session,
+        state: {
+            ...state,
+            miningState: normalizeMiningStateRecord(state.miningState),
+        },
+        source,
+    };
+}
 function createPortableWalletArchivePayload(state, exportedAtUnixMs) {
     return {
         schemaVersion: 1,
@@ -791,47 +840,95 @@ export async function loadUnlockedWalletState(options = {}) {
             await clearUnlockSession(paths.walletUnlockSessionPath);
             return null;
         }
-        let state = loaded.state;
-        let source = loaded.source;
-        if (options.dataDir !== undefined) {
-            const node = await (options.attachService ?? attachOrStartManagedBitcoindService)({
-                dataDir: options.dataDir,
-                chain: "main",
-                startHeight: 0,
-                walletRootId: state.walletRootId,
+        return await normalizeUnlockedWalletStateIfNeeded({
+            provider,
+            session,
+            state: loaded.state,
+            source: loaded.source,
+            nowUnixMs,
+            paths,
+            dataDir: options.dataDir,
+            attachService: options.attachService,
+            rpcFactory: options.rpcFactory,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+export async function loadOrAutoUnlockWalletState(options = {}) {
+    const provider = options.provider ?? createDefaultWalletSecretProvider();
+    const nowUnixMs = options.nowUnixMs ?? Date.now();
+    const unlockDurationMs = options.unlockDurationMs ?? DEFAULT_UNLOCK_DURATION_MS;
+    const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
+    const loadExisting = () => loadUnlockedWalletState({
+        provider,
+        nowUnixMs,
+        paths,
+        dataDir: options.dataDir,
+        attachService: options.attachService,
+        rpcFactory: options.rpcFactory,
+    });
+    const existing = await loadExisting();
+    if (existing !== null) {
+        return existing;
+    }
+    const loadAndMaybeAutoUnlock = async () => {
+        const reloaded = await loadExisting();
+        if (reloaded !== null) {
+            return reloaded;
+        }
+        let loaded;
+        try {
+            loaded = await loadWalletState({
+                primaryPath: paths.walletStatePath,
+                backupPath: paths.walletStateBackupPath,
+            }, {
+                provider,
             });
-            try {
-                const normalized = await persistNormalizedWalletDescriptorStateIfNeeded({
-                    state,
-                    access: {
-                        provider,
-                        secretReference: createWalletSecretReference(state.walletRootId),
-                    },
-                    session,
-                    paths,
-                    nowUnixMs,
-                    replacePrimary: loaded.source === "backup",
-                    rpc: (options.rpcFactory ?? createRpcClient)(node.rpc),
-                });
-                state = normalized.state;
-                session = normalized.session ?? session;
-                source = normalized.changed ? "primary" : loaded.source;
-            }
-            finally {
-                await node.stop?.().catch(() => undefined);
+        }
+        catch {
+            return null;
+        }
+        const explicitLock = await loadWalletExplicitLock(paths.walletExplicitLockPath);
+        if (explicitLock !== null) {
+            if (explicitLock.walletRootId === loaded.state.walletRootId) {
+                await clearUnlockSession(paths.walletUnlockSessionPath);
+                return null;
             }
+            await clearWalletExplicitLock(paths.walletExplicitLockPath);
         }
-        return {
+        const secretReference = createWalletSecretReference(loaded.state.walletRootId);
+        const unlockUntilUnixMs = nowUnixMs + unlockDurationMs;
+        const session = createUnlockSession(loaded.state, unlockUntilUnixMs, secretReference.keyId, nowUnixMs);
+        await saveUnlockSession(paths.walletUnlockSessionPath, session, {
+            provider,
+            secretReference,
+        });
+        return await normalizeUnlockedWalletStateIfNeeded({
+            provider,
             session,
-            state: {
-                ...state,
-                miningState: normalizeMiningStateRecord(state.miningState),
-            },
-            source,
-        };
+            state: loaded.state,
+            source: loaded.source,
+            nowUnixMs,
+            paths,
+            dataDir: options.dataDir,
+            attachService: options.attachService,
+            rpcFactory: options.rpcFactory,
+        });
+    };
+    if (options.controlLockHeld) {
+        return await loadAndMaybeAutoUnlock();
     }
-    catch {
-        return null;
+    const controlLock = await acquireFileLock(paths.walletControlLockPath, {
+        purpose: "wallet-auto-unlock",
+        walletRootId: null,
+    });
+    try {
+        return await loadAndMaybeAutoUnlock();
+    }
+    finally {
+        await controlLock.release();
     }
 }
 export async function initializeWallet(options) {
@@ -884,6 +981,7 @@ export async function initializeWallet(options) {
         });
         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,
@@ -917,6 +1015,7 @@ export async function unlockWallet(options = {}) {
         });
         const secretReference = createWalletSecretReference(loaded.state.walletRootId);
         const unlockUntilUnixMs = nowUnixMs + unlockDurationMs;
+        await clearWalletExplicitLock(paths.walletExplicitLockPath);
         await saveUnlockSession(paths.walletUnlockSessionPath, createUnlockSession(loaded.state, unlockUntilUnixMs, secretReference.keyId, nowUnixMs), {
             provider,
             secretReference,
@@ -933,6 +1032,7 @@ export async function unlockWallet(options = {}) {
 }
 export async function lockWallet(options) {
     const provider = options.provider ?? createDefaultWalletSecretProvider();
+    const nowUnixMs = options.nowUnixMs ?? Date.now();
     const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
     const controlLock = await acquireFileLock(paths.walletControlLockPath, {
         purpose: "wallet-lock",
@@ -968,6 +1068,9 @@ export async function lockWallet(options) {
             walletRootId = null;
         }
         await clearUnlockSession(paths.walletUnlockSessionPath);
+        if (walletRootId !== null) {
+            await saveWalletExplicitLock(paths.walletExplicitLockPath, createWalletExplicitLock(walletRootId, nowUnixMs));
+        }
         return {
             walletRootId,
             coreLocked,
@@ -989,10 +1092,11 @@ export async function exportWallet(options) {
         walletRootId: null,
     });
     try {
-        const unlocked = await loadUnlockedWalletState({
+        const unlocked = await loadOrAutoUnlockWalletState({
             provider,
             nowUnixMs,
             paths,
+            controlLockHeld: true,
         });
         if (unlocked === null) {
             throw new Error("wallet_locked");
@@ -1071,6 +1175,7 @@ export async function importWallet(options) {
             internalCoreWalletPassphrase: createInternalCoreWalletPassphrase(),
         });
         await clearUnlockSession(paths.walletUnlockSessionPath);
+        await clearWalletExplicitLock(paths.walletExplicitLockPath);
         await saveWalletState({
             primaryPath: paths.walletStatePath,
             backupPath: paths.walletStateBackupPath,
@@ -1083,6 +1188,7 @@ export async function importWallet(options) {
             rpcFactory: options.rpcFactory,
         });
         const unlockUntilUnixMs = nowUnixMs + unlockDurationMs;
+        await clearWalletExplicitLock(paths.walletExplicitLockPath);
         await saveUnlockSession(paths.walletUnlockSessionPath, createUnlockSession(importedState, unlockUntilUnixMs, secretReference.keyId, nowUnixMs), {
             provider,
             secretReference,

package/dist/wallet/mining/control.js

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { acquireFileLock } from "../fs/lock.js";
-import { loadUnlockedWalletState } from "../lifecycle.js";
+import { loadOrAutoUnlockWalletState } from "../lifecycle.js";
 import { resolveWalletRuntimePathsForTesting } from "../runtime.js";
 import { saveWalletState } from "../state/storage.js";
 import { createDefaultWalletSecretProvider, createWalletSecretReference, } from "../state/provider.js";
@@ -397,7 +397,7 @@ export async function enableMiningHooks(options) {
             paths,
             reason: "hooks-enable-mining",
         });
-        const unlocked = await loadUnlockedWalletState({
+        const unlocked = await loadOrAutoUnlockWalletState({
             provider,
             nowUnixMs,
             paths,
@@ -556,7 +556,7 @@ export async function disableMiningHooks(options) {
             paths,
             reason: "hooks-disable-mining",
         });
-        const unlocked = await loadUnlockedWalletState({
+        const unlocked = await loadOrAutoUnlockWalletState({
             provider,
             nowUnixMs,
             paths,
@@ -664,7 +664,7 @@ export async function setupBuiltInMining(options) {
             paths,
             reason: "mine-setup",
         });
-        const unlocked = await loadUnlockedWalletState({
+        const unlocked = await loadOrAutoUnlockWalletState({
             provider,
             nowUnixMs,
             paths,

package/dist/wallet/mining/runner.js

@@ -10,7 +10,7 @@ import { COG_OPCODES, COG_PREFIX } from "../cogop/constants.js";
 import { extractOpReturnPayloadFromScriptHex } from "../tx/register.js";
 import { DEFAULT_WALLET_MUTATION_FEE_RATE_SAT_VB, buildWalletMutationTransaction, isAlreadyAcceptedError, isBroadcastUnknownError, saveWalletStatePreservingUnlock, } from "../tx/common.js";
 import { acquireFileLock } from "../fs/lock.js";
-import { loadUnlockedWalletState } from "../lifecycle.js";
+import { loadOrAutoUnlockWalletState } from "../lifecycle.js";
 import { isMineableWalletDomain, openWalletReadContext, } from "../read/index.js";
 import { resolveWalletRuntimePathsForTesting } from "../runtime.js";
 import { createDefaultWalletSecretProvider, } from "../state/provider.js";
@@ -1567,7 +1567,7 @@ async function publishCandidate(options) {
     };
 }
 async function ensureBuiltInSetupIfNeeded(options) {
-    const unlocked = await loadUnlockedWalletState({
+    const unlocked = await loadOrAutoUnlockWalletState({
         provider: options.provider,
         paths: options.paths,
     });

package/dist/wallet/read/context.d.ts

@@ -8,12 +8,14 @@ declare function inspectWalletLocalState(options?: {
     secretProvider?: WalletSecretProvider;
     now?: number;
     paths?: WalletRuntimePaths;
+    walletControlLockHeld?: boolean;
 }): Promise<WalletLocalStateStatus>;
 export declare function openWalletReadContext(options: {
     dataDir: string;
     databasePath: string;
     walletStatePassphrase?: Uint8Array | string;
     secretProvider?: WalletSecretProvider;
+    walletControlLockHeld?: boolean;
     startupTimeoutMs?: number;
     now?: number;
     paths?: WalletRuntimePaths;

package/dist/wallet/read/context.js

@@ -5,11 +5,12 @@ import { createRpcClient } from "../../bitcoind/node.js";
 import { UNINITIALIZED_WALLET_ROOT_ID } from "../../bitcoind/service-paths.js";
 import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, } from "../../bitcoind/service.js";
 import {} from "../../bitcoind/types.js";
-import { loadUnlockedWalletState, verifyManagedCoreWalletReplica, } from "../lifecycle.js";
+import { loadOrAutoUnlockWalletState, verifyManagedCoreWalletReplica, } from "../lifecycle.js";
 import { persistNormalizedWalletDescriptorStateIfNeeded } from "../descriptor-normalization.js";
 import { inspectMiningControlPlane } from "../mining/index.js";
 import { normalizeMiningStateRecord } from "../mining/state.js";
 import { resolveWalletRuntimePathsForTesting } from "../runtime.js";
+import { loadWalletExplicitLock } from "../state/explicit-lock.js";
 import { loadWalletState } from "../state/storage.js";
 import { createDefaultWalletSecretProvider, createWalletSecretReference, } from "../state/provider.js";
 import { createWalletReadModel } from "./project.js";
@@ -24,6 +25,30 @@ async function pathExists(path) {
         return false;
     }
 }
+function isLockedWalletAccessError(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 describeLockedWalletMessage(options) {
+    if (options.explicitlyLocked) {
+        return "Wallet state exists but is explicitly locked until `cogcoin unlock` is run.";
+    }
+    const message = options.accessError instanceof Error ? options.accessError.message : String(options.accessError ?? "");
+    if (message === "wallet_envelope_missing_secret_provider") {
+        return "Wallet state exists but requires the local wallet-state passphrase.";
+    }
+    if (message.startsWith("wallet_secret_provider_")) {
+        return "Wallet state exists but the local secret provider is unavailable.";
+    }
+    if (message.startsWith("wallet_secret_missing_")) {
+        return "Wallet state exists but its local secret-provider material is unavailable.";
+    }
+    return options.hasUnlockSessionFile
+        ? "Wallet state exists but the unlock session is expired, invalid, or belongs to a different wallet root."
+        : "Wallet state exists but is currently locked.";
+}
 async function normalizeLoadedWalletStateForRead(options) {
     if (options.dataDir === undefined) {
         return options.loaded;
@@ -82,13 +107,16 @@ async function inspectWalletLocalState(options = {}) {
     if (options.passphrase === undefined) {
         try {
             const provider = options.secretProvider ?? createDefaultWalletSecretProvider();
-            const unlocked = await loadUnlockedWalletState({
+            const unlocked = await loadOrAutoUnlockWalletState({
                 provider,
                 nowUnixMs: now,
                 paths,
                 dataDir: options.dataDir,
+                controlLockHeld: options.walletControlLockHeld,
             });
             if (unlocked === null) {
+                const explicitLock = await loadWalletExplicitLock(paths.walletExplicitLockPath);
+                const hasUnlockSessionFileNow = await pathExists(paths.walletUnlockSessionPath);
                 try {
                     const loaded = await loadWalletState({
                         primaryPath: paths.walletStatePath,
@@ -103,8 +131,39 @@ async function inspectWalletLocalState(options = {}) {
                         now,
                         paths,
                     });
+                    return {
+                        availability: "locked",
+                        walletRootId: loaded.state.walletRootId,
+                        state: null,
+                        source: loaded.source,
+                        unlockUntilUnixMs: null,
+                        hasPrimaryStateFile,
+                        hasBackupStateFile,
+                        hasUnlockSessionFile: hasUnlockSessionFileNow,
+                        message: describeLockedWalletMessage({
+                            explicitlyLocked: explicitLock?.walletRootId === loaded.state.walletRootId,
+                            hasUnlockSessionFile: hasUnlockSessionFileNow,
+                        }),
+                    };
                 }
                 catch (error) {
+                    if (isLockedWalletAccessError(error)) {
+                        return {
+                            availability: "locked",
+                            walletRootId: null,
+                            state: null,
+                            source: null,
+                            unlockUntilUnixMs: null,
+                            hasPrimaryStateFile,
+                            hasBackupStateFile,
+                            hasUnlockSessionFile: hasUnlockSessionFileNow,
+                            message: describeLockedWalletMessage({
+                                accessError: error,
+                                explicitlyLocked: false,
+                                hasUnlockSessionFile: hasUnlockSessionFileNow,
+                            }),
+                        };
+                    }
                     return {
                         availability: "local-state-corrupt",
                         walletRootId: null,
@@ -113,23 +172,10 @@ async function inspectWalletLocalState(options = {}) {
                         unlockUntilUnixMs: null,
                         hasPrimaryStateFile,
                         hasBackupStateFile,
-                        hasUnlockSessionFile,
+                        hasUnlockSessionFile: hasUnlockSessionFileNow,
                         message: error instanceof Error ? error.message : String(error),
                     };
                 }
-                return {
-                    availability: "locked",
-                    walletRootId: null,
-                    state: null,
-                    source: null,
-                    unlockUntilUnixMs: null,
-                    hasPrimaryStateFile,
-                    hasBackupStateFile,
-                    hasUnlockSessionFile,
-                    message: hasUnlockSessionFile
-                        ? "Wallet state exists but the unlock session is expired, invalid, or belongs to a different wallet root."
-                        : "Wallet state exists but is currently locked.",
-                };
             }
             return {
                 availability: "ready",
@@ -142,7 +188,7 @@ async function inspectWalletLocalState(options = {}) {
                 unlockUntilUnixMs: unlocked.session.unlockUntilUnixMs,
                 hasPrimaryStateFile,
                 hasBackupStateFile,
-                hasUnlockSessionFile,
+                hasUnlockSessionFile: true,
                 message: null,
             };
         }
@@ -460,6 +506,7 @@ export async function openWalletReadContext(options) {
         dataDir: options.dataDir,
         passphrase: options.walletStatePassphrase,
         secretProvider: options.secretProvider,
+        walletControlLockHeld: options.walletControlLockHeld,
         now,
         paths: options.paths,
     });

package/dist/wallet/runtime.d.ts

@@ -10,6 +10,7 @@ export interface WalletRuntimePaths {
     walletStatePath: string;
     walletStateBackupPath: string;
     walletUnlockSessionPath: string;
+    walletExplicitLockPath: string;
     walletControlLockPath: string;
     bitcoindLockPath: string;
     bitcoindStatusPath: string;

package/dist/wallet/runtime.js

@@ -12,6 +12,7 @@ export function resolveWalletRuntimePathsForTesting(resolution = {}) {
         walletStatePath: paths.walletStatePath,
         walletStateBackupPath: paths.walletStateBackupPath,
         walletUnlockSessionPath: paths.walletUnlockSessionPath,
+        walletExplicitLockPath: paths.walletExplicitLockPath,
         walletControlLockPath: paths.walletControlLockPath,
         bitcoindLockPath: paths.bitcoindLockPath,
         bitcoindStatusPath: paths.bitcoindStatusPath,

package/dist/wallet/state/explicit-lock.d.ts

@@ -0,0 +1,4 @@
+import type { WalletExplicitLockStateV1 } from "../types.js";
+export declare function loadWalletExplicitLock(lockPath: string): Promise<WalletExplicitLockStateV1 | null>;
+export declare function saveWalletExplicitLock(lockPath: string, state: WalletExplicitLockStateV1): Promise<void>;
+export declare function clearWalletExplicitLock(lockPath: string): Promise<void>;

package/dist/wallet/state/explicit-lock.js

@@ -0,0 +1,19 @@
+import { readFile, rm } from "node:fs/promises";
+import { writeJsonFileAtomic } from "../fs/atomic.js";
+export async function loadWalletExplicitLock(lockPath) {
+    try {
+        return JSON.parse(await readFile(lockPath, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function saveWalletExplicitLock(lockPath, state) {
+    await writeJsonFileAtomic(lockPath, state, { mode: 0o600 });
+}
+export async function clearWalletExplicitLock(lockPath) {
+    await rm(lockPath, { force: true });
+}

package/dist/wallet/tx/anchor.js

@@ -996,6 +996,7 @@ export async function anchorDomain(options) {
             dataDir: options.dataDir,
             databasePath: options.databasePath,
             secretProvider: provider,
+            walletControlLockHeld: true,
             paths,
         });
         try {

package/dist/wallet/tx/cog.js

@@ -623,6 +623,7 @@ export async function sendCog(options) {
             dataDir: options.dataDir,
             databasePath: options.databasePath,
             secretProvider: provider,
+            walletControlLockHeld: true,
             paths,
         });
         try {
@@ -763,6 +764,7 @@ export async function lockCogToDomain(options) {
             dataDir: options.dataDir,
             databasePath: options.databasePath,
             secretProvider: provider,
+            walletControlLockHeld: true,
             paths,
         });
         try {
@@ -918,6 +920,7 @@ async function runClaimLikeMutation(options, reclaim) {
             dataDir: options.dataDir,
             databasePath: options.databasePath,
             secretProvider: provider,
+            walletControlLockHeld: true,
             paths,
         });
         try {

package/dist/wallet/tx/domain-admin.js

@@ -557,6 +557,7 @@ async function submitDomainAdminMutation(options) {
             dataDir: options.dataDir,
             databasePath: options.databasePath,
             secretProvider: provider,
+            walletControlLockHeld: true,
             paths,
         });
         try {

package/dist/wallet/tx/domain-market.js

@@ -683,6 +683,7 @@ export async function transferDomain(options) {
             dataDir: options.dataDir,
             databasePath: options.databasePath,
             secretProvider: provider,
+            walletControlLockHeld: true,
             paths,
         });
         try {
@@ -916,6 +917,7 @@ async function runSellMutation(options) {
             dataDir: options.dataDir,
             databasePath: options.databasePath,
             secretProvider: provider,
+            walletControlLockHeld: true,
             paths,
         });
         try {
@@ -1143,6 +1145,7 @@ export async function buyDomain(options) {
             dataDir: options.dataDir,
             databasePath: options.databasePath,
             secretProvider: provider,
+            walletControlLockHeld: true,
             paths,
         });
         try {

package/dist/wallet/tx/field.js

@@ -1267,6 +1267,7 @@ async function submitStandaloneFieldMutation(options) {
             dataDir: options.dataDir,
             databasePath: options.databasePath,
             secretProvider: provider,
+            walletControlLockHeld: true,
             paths,
         });
         try {
@@ -1418,6 +1419,7 @@ async function submitFieldCreateFamily(options) {
             dataDir: options.dataDir,
             databasePath: options.databasePath,
             secretProvider: provider,
+            walletControlLockHeld: true,
             paths,
         });
         try {

package/dist/wallet/tx/register.js

@@ -686,6 +686,7 @@ export async function registerDomain(options) {
             dataDir: options.dataDir,
             databasePath: options.databasePath,
             secretProvider: provider,
+            walletControlLockHeld: true,
             paths,
         });
         try {

package/dist/wallet/tx/reputation.js

@@ -528,6 +528,7 @@ async function submitReputationMutation(options) {
             dataDir: options.dataDir,
             databasePath: options.databasePath,
             secretProvider: provider,
+            walletControlLockHeld: true,
             paths,
         });
         try {

package/dist/wallet/types.d.ts

@@ -247,3 +247,8 @@ export interface UnlockSessionStateV1 {
     sourceStateRevision: number;
     wrappedSessionKeyMaterial: string;
 }
+export interface WalletExplicitLockStateV1 {
+    schemaVersion: 1;
+    walletRootId: string;
+    lockedAtUnixMs: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cogcoin/client",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Store-backed Cogcoin client with wallet flows, SQLite persistence, and managed Bitcoin Core integration.",
   "license": "MIT",
   "type": "module",