@cogcoin/client 0.5.1 → 0.5.3

package/dist/wallet/lifecycle.js

@@ -8,6 +8,7 @@ import { resolveManagedServicePaths } from "../bitcoind/service-paths.js";
 import { createRpcClient } from "../bitcoind/node.js";
 import { openSqliteStore } from "../sqlite/index.js";
 import { readPortableWalletArchive, writePortableWalletArchive } from "./archive.js";
+import { normalizeWalletDescriptorState, persistNormalizedWalletDescriptorStateIfNeeded, persistWalletStateUpdate, resolveNormalizedWalletDescriptorState, stripDescriptorChecksum, } from "./descriptor-normalization.js";
 import { acquireFileLock } from "./fs/lock.js";
 import { createInternalCoreWalletPassphrase, createMnemonicConfirmationChallenge, deriveWalletMaterialFromMnemonic, generateWalletMaterial, } from "./material.js";
 import { resolveWalletRuntimePathsForTesting } from "./runtime.js";
@@ -16,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";
@@ -23,9 +25,6 @@ export const DEFAULT_UNLOCK_DURATION_MS = 15 * 60 * 1000;
 function sanitizeWalletName(walletRootId) {
     return `cogcoin-${walletRootId}`.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 63);
 }
-function stripDescriptorChecksum(descriptor) {
-    return descriptor.replace(/#[A-Za-z0-9]+$/, "");
-}
 async function pathExists(path) {
     try {
         await access(path, constants.F_OK);
@@ -144,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,
@@ -518,22 +565,16 @@ function createStoppedBackgroundRuntimeSnapshot(snapshot, nowUnixMs) {
     };
 }
 async function persistRepairState(options) {
-    const nextState = {
-        ...options.state,
-        stateRevision: options.state.stateRevision + 1,
-        lastWrittenAtUnixMs: options.nowUnixMs,
-    };
-    if (options.replacePrimary) {
-        await rm(options.paths.walletStatePath, { force: true }).catch(() => undefined);
-    }
-    await saveWalletState({
-        primaryPath: options.paths.walletStatePath,
-        backupPath: options.paths.walletStateBackupPath,
-    }, nextState, {
-        provider: options.provider,
-        secretReference: createWalletSecretReference(nextState.walletRootId),
+    return await persistWalletStateUpdate({
+        state: options.state,
+        access: {
+            provider: options.provider,
+            secretReference: createWalletSecretReference(options.state.walletRootId),
+        },
+        paths: options.paths,
+        nowUnixMs: options.nowUnixMs,
+        replacePrimary: options.replacePrimary,
     });
-    return nextState;
 }
 async function stopBackgroundMiningForRepair(options) {
     const pid = options.snapshot.backgroundWorkerPid;
@@ -630,13 +671,12 @@ async function importDescriptorIntoManagedCoreWallet(state, provider, paths, dat
     await createManagedWalletReplica(rpc, state.walletRootId, {
         managedWalletPassphrase: state.managedCoreWallet.internalPassphrase,
     });
-    const privateDescriptor = await rpc.getDescriptorInfo(state.descriptor.privateExternal);
-    const publicDescriptor = await rpc.getDescriptorInfo(state.descriptor.publicExternal);
+    const normalizedDescriptors = await resolveNormalizedWalletDescriptorState(state, rpc);
     const walletName = sanitizeWalletName(state.walletRootId);
     await rpc.walletPassphrase(walletName, state.managedCoreWallet.internalPassphrase, 10);
     try {
         const importResults = await rpc.importDescriptors(walletName, [{
-                desc: privateDescriptor.descriptor,
+                desc: normalizedDescriptors.privateExternal,
                 timestamp: state.walletBirthTime,
                 active: false,
                 internal: false,
@@ -649,12 +689,12 @@ async function importDescriptorIntoManagedCoreWallet(state, provider, paths, dat
     finally {
         await rpc.walletLock(walletName).catch(() => undefined);
     }
-    const derivedFunding = await rpc.deriveAddresses(publicDescriptor.descriptor, [0, 0]);
+    const derivedFunding = await rpc.deriveAddresses(normalizedDescriptors.publicExternal, [0, 0]);
     if (derivedFunding[0] !== state.funding.address) {
         throw new Error("wallet_funding_address_verification_failed");
     }
     const descriptors = await rpc.listDescriptors(walletName);
-    const importedDescriptor = descriptors.descriptors.find((entry) => entry.desc === privateDescriptor.descriptor);
+    const importedDescriptor = descriptors.descriptors.find((entry) => entry.desc === normalizedDescriptors.publicExternal);
     if (importedDescriptor == null) {
         throw new Error("wallet_descriptor_not_present_after_import");
     }
@@ -666,7 +706,7 @@ async function importDescriptorIntoManagedCoreWallet(state, provider, paths, dat
         privateKeysEnabled: true,
         created: false,
         proofStatus: "ready",
-        descriptorChecksum: privateDescriptor.checksum,
+        descriptorChecksum: normalizedDescriptors.checksum,
         fundingAddress0: state.funding.address,
         fundingScriptPubKeyHex0: state.funding.scriptPubKeyHex,
         message: null,
@@ -677,14 +717,14 @@ async function importDescriptorIntoManagedCoreWallet(state, provider, paths, dat
         lastWrittenAtUnixMs: nowUnixMs,
         descriptor: {
             ...state.descriptor,
-            privateExternal: privateDescriptor.descriptor,
-            publicExternal: publicDescriptor.descriptor,
-            checksum: privateDescriptor.checksum,
+            privateExternal: normalizedDescriptors.privateExternal,
+            publicExternal: normalizedDescriptors.publicExternal,
+            checksum: normalizedDescriptors.checksum,
         },
         managedCoreWallet: {
             ...state.managedCoreWallet,
             walletName,
-            descriptorChecksum: privateDescriptor.checksum,
+            descriptorChecksum: normalizedDescriptors.checksum,
             fundingAddress0: verifiedReplica.fundingAddress0 ?? null,
             fundingScriptPubKeyHex0: verifiedReplica.fundingScriptPubKeyHex0 ?? null,
             proofStatus: "ready",
@@ -782,7 +822,7 @@ export async function loadUnlockedWalletState(options = {}) {
     const nowUnixMs = options.nowUnixMs ?? Date.now();
     const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
     try {
-        const session = await loadUnlockSession(paths.walletUnlockSessionPath, {
+        let session = await loadUnlockSession(paths.walletUnlockSessionPath, {
             provider,
         });
         if (session.unlockUntilUnixMs <= nowUnixMs) {
@@ -800,19 +840,97 @@ export async function loadUnlockedWalletState(options = {}) {
             await clearUnlockSession(paths.walletUnlockSessionPath);
             return null;
         }
-        return {
+        return await normalizeUnlockedWalletStateIfNeeded({
+            provider,
             session,
-            state: {
-                ...loaded.state,
-                miningState: normalizeMiningStateRecord(loaded.state.miningState),
-            },
+            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,
+            });
+        }
+        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);
+        }
+        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: loaded.state,
+            source: loaded.source,
+            nowUnixMs,
+            paths,
+            dataDir: options.dataDir,
+            attachService: options.attachService,
+            rpcFactory: options.rpcFactory,
+        });
+    };
+    if (options.controlLockHeld) {
+        return await loadAndMaybeAutoUnlock();
+    }
+    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) {
     if (!options.prompter.isInteractive) {
         throw new Error("wallet_init_requires_tty");
@@ -863,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,
@@ -896,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,
@@ -912,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",
@@ -947,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,
@@ -968,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");
@@ -1050,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,
@@ -1062,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,
@@ -1242,6 +1369,11 @@ export async function repairWallet(options) {
                 walletRootId: repairedState.walletRootId,
             });
             const bitcoindRpc = (options.rpcFactory ?? createRpcClient)(bitcoindHandle.rpc);
+            const normalizedDescriptorState = await normalizeWalletDescriptorState(repairedState, bitcoindRpc);
+            if (normalizedDescriptorState.changed) {
+                repairedState = normalizedDescriptorState.state;
+                repairStateNeedsPersist = true;
+            }
             let replica = await verifyManagedCoreWalletReplica(repairedState, options.dataDir, {
                 nodeHandle: bitcoindHandle,
                 attachService: options.attachService,

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

@@ -3,16 +3,19 @@ import { type WalletSecretProvider } from "../state/provider.js";
 import type { WalletLocalStateStatus, WalletReadContext } from "./types.js";
 import type { WalletRuntimePaths } from "../runtime.js";
 declare function inspectWalletLocalState(options?: {
+    dataDir?: string;
     passphrase?: Uint8Array | string;
     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,12 +5,14 @@ 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, } from "../state/provider.js";
+import { createDefaultWalletSecretProvider, createWalletSecretReference, } from "../state/provider.js";
 import { createWalletReadModel } from "./project.js";
 const DEFAULT_SERVICE_START_TIMEOUT_MS = 10_000;
 const STALE_HEARTBEAT_THRESHOLD_MS = 15_000;
@@ -23,6 +25,64 @@ 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;
+    }
+    const node = await attachOrStartManagedBitcoindService({
+        dataDir: options.dataDir,
+        chain: "main",
+        startHeight: 0,
+        walletRootId: options.loaded.state.walletRootId,
+    });
+    try {
+        const access = typeof options.access === "string" || options.access instanceof Uint8Array
+            ? options.access
+            : {
+                provider: options.access.provider,
+                secretReference: createWalletSecretReference(options.loaded.state.walletRootId),
+            };
+        const normalized = await persistNormalizedWalletDescriptorStateIfNeeded({
+            state: options.loaded.state,
+            access,
+            paths: options.paths,
+            nowUnixMs: options.now,
+            replacePrimary: options.loaded.source === "backup",
+            rpc: createRpcClient(node.rpc),
+        });
+        return {
+            source: normalized.changed ? "primary" : options.loaded.source,
+            state: normalized.state,
+        };
+    }
+    finally {
+        await node.stop?.().catch(() => undefined);
+    }
+}
 async function inspectWalletLocalState(options = {}) {
     const paths = options.paths ?? resolveWalletRuntimePathsForTesting();
     const now = options.now ?? Date.now();
@@ -47,21 +107,63 @@ 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 {
-                    await loadWalletState({
+                    const loaded = await loadWalletState({
                         primaryPath: paths.walletStatePath,
                         backupPath: paths.walletStateBackupPath,
                     }, {
                         provider,
                     });
+                    await normalizeLoadedWalletStateForRead({
+                        loaded,
+                        access: { provider },
+                        dataDir: options.dataDir,
+                        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,
@@ -70,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",
@@ -99,7 +188,7 @@ async function inspectWalletLocalState(options = {}) {
                 unlockUntilUnixMs: unlocked.session.unlockUntilUnixMs,
                 hasPrimaryStateFile,
                 hasBackupStateFile,
-                hasUnlockSessionFile,
+                hasUnlockSessionFile: true,
                 message: null,
             };
         }
@@ -118,10 +207,16 @@ async function inspectWalletLocalState(options = {}) {
         }
     }
     try {
-        const loaded = await loadWalletState({
-            primaryPath: paths.walletStatePath,
-            backupPath: paths.walletStateBackupPath,
-        }, options.passphrase);
+        const loaded = await normalizeLoadedWalletStateForRead({
+            loaded: await loadWalletState({
+                primaryPath: paths.walletStatePath,
+                backupPath: paths.walletStateBackupPath,
+            }, options.passphrase),
+            access: options.passphrase,
+            dataDir: options.dataDir,
+            now,
+            paths,
+        });
         return {
             availability: "ready",
             walletRootId: loaded.state.walletRootId,
@@ -408,8 +503,10 @@ export async function openWalletReadContext(options) {
     const startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_SERVICE_START_TIMEOUT_MS;
     const now = options.now ?? Date.now();
     const localState = await inspectWalletLocalState({
+        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,