@cogcoin/client 0.5.3 → 0.5.4

package/dist/cli/runner.js

@@ -6,6 +6,7 @@ import { runFollowCommand } from "./commands/follow.js";
 import { runMiningAdminCommand } from "./commands/mining-admin.js";
 import { runMiningReadCommand } from "./commands/mining-read.js";
 import { runMiningRuntimeCommand } from "./commands/mining-runtime.js";
+import { runServiceRuntimeCommand } from "./commands/service-runtime.js";
 import { runStatusCommand } from "./commands/status.js";
 import { runSyncCommand } from "./commands/sync.js";
 import { runWalletAdminCommand } from "./commands/wallet-admin.js";
@@ -49,6 +50,14 @@ export async function runCli(argv, contextOverrides = {}) {
         if (parsed.command === "status") {
             return runStatusCommand(parsed, context);
         }
+        if (parsed.command === "bitcoin-start"
+            || parsed.command === "bitcoin-stop"
+            || parsed.command === "bitcoin-status"
+            || parsed.command === "indexer-start"
+            || parsed.command === "indexer-stop"
+            || parsed.command === "indexer-status") {
+            return runServiceRuntimeCommand(parsed, context);
+        }
         if (parsed.command === "mine"
             || parsed.command === "mine-start"
             || parsed.command === "mine-stop") {
@@ -60,11 +69,14 @@ export async function runCli(argv, contextOverrides = {}) {
             return runMiningAdminCommand(parsed, context);
         }
         if (parsed.command === "init"
+            || parsed.command === "restore"
+            || parsed.command === "reset"
             || parsed.command === "repair"
             || parsed.command === "unlock"
             || parsed.command === "wallet-export"
             || parsed.command === "wallet-import"
             || parsed.command === "wallet-init"
+            || parsed.command === "wallet-restore"
             || parsed.command === "wallet-unlock"
             || parsed.command === "wallet-lock") {
             return runWalletAdminCommand(parsed, context);

package/dist/cli/signals.d.ts

@@ -1,3 +1,4 @@
 import type { InterruptibleOutcome, ManagedClientLike, SignalSource, StopSignalWatcher, WritableLike } from "./types.js";
 export declare function createStopSignalWatcher(signalSource: SignalSource, stderr: WritableLike, client: ManagedClientLike, forceExit: (code: number) => never | void): StopSignalWatcher;
+export declare function createOwnedLockCleanupSignalWatcher(signalSource: SignalSource, forceExit: (code: number) => never | void, lockPaths: readonly string[]): StopSignalWatcher;
 export declare function waitForCompletionOrStop<T>(promise: Promise<T>, stopWatcher: StopSignalWatcher): Promise<InterruptibleOutcome<T>>;

package/dist/cli/signals.js

@@ -1,4 +1,5 @@
 import { writeLine } from "./io.js";
+import { clearLockIfOwnedByCurrentProcess } from "../wallet/fs/lock.js";
 export function createStopSignalWatcher(signalSource, stderr, client, forceExit) {
     let closing = false;
     let resolved = false;
@@ -42,6 +43,49 @@ export function createStopSignalWatcher(signalSource, stderr, client, forceExit)
         promise,
     };
 }
+export function createOwnedLockCleanupSignalWatcher(signalSource, forceExit, lockPaths) {
+    let stopping = false;
+    let resolved = false;
+    let onSignal = () => { };
+    const cleanup = () => {
+        signalSource.off("SIGINT", onSignal);
+        signalSource.off("SIGTERM", onSignal);
+    };
+    const promise = new Promise((resolve) => {
+        const settle = (code) => {
+            if (resolved) {
+                return;
+            }
+            resolved = true;
+            cleanup();
+            resolve(code);
+        };
+        const releaseOwnedLocks = async () => {
+            await Promise.allSettled([...new Set(lockPaths)].map(async (lockPath) => {
+                await clearLockIfOwnedByCurrentProcess(lockPath);
+            }));
+        };
+        onSignal = () => {
+            if (stopping) {
+                settle(130);
+                forceExit(130);
+                return;
+            }
+            stopping = true;
+            settle(130);
+            void releaseOwnedLocks().finally(() => {
+                forceExit(130);
+            });
+        };
+    });
+    signalSource.on("SIGINT", onSignal);
+    signalSource.on("SIGTERM", onSignal);
+    return {
+        cleanup,
+        isStopping: () => stopping,
+        promise,
+    };
+}
 export async function waitForCompletionOrStop(promise, stopWatcher) {
     const outcome = await Promise.race([
         promise.then((value) => ({ kind: "completed", value }), (error) => ({ kind: "error", error })),

package/dist/cli/types.d.ts

@@ -1,14 +1,21 @@
 import type { inspectPassiveClientStatus } from "../passive-status.js";
+import { createRpcClient } from "../bitcoind/node.js";
+import { attachOrStartIndexerDaemon, probeIndexerDaemon, readObservedIndexerDaemonStatus, stopIndexerDaemonService } from "../bitcoind/indexer-daemon.js";
+import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, stopManagedBitcoindService } from "../bitcoind/service.js";
 import { openSqliteStore } from "../sqlite/index.js";
 import type { ClientStoreAdapter } from "../types.js";
-import type { exportWallet, WalletPrompter, importWallet, initializeWallet, lockWallet, repairWallet, unlockWallet } from "../wallet/lifecycle.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 { 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 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" | "repair" | "sync" | "status" | "follow" | "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-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-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;
@@ -88,9 +95,22 @@ export interface CliRunnerContext {
         dataDir?: string;
         progressOutput?: ProgressOutput;
     }) => Promise<ManagedClientLike>;
+    attachManagedBitcoindService?: typeof attachOrStartManagedBitcoindService;
+    probeManagedBitcoindService?: typeof probeManagedBitcoindService;
+    stopManagedBitcoindService?: typeof stopManagedBitcoindService;
+    createBitcoinRpcClient?: typeof createRpcClient;
+    attachIndexerDaemon?: typeof attachOrStartIndexerDaemon;
+    probeIndexerDaemon?: typeof probeIndexerDaemon;
+    readObservedIndexerDaemonStatus?: typeof readObservedIndexerDaemonStatus;
+    stopIndexerDaemonService?: typeof stopIndexerDaemonService;
     inspectPassiveClientStatus?: typeof inspectPassiveClientStatus;
     openWalletReadContext?: typeof openWalletReadContext;
+    loadWalletState?: typeof loadWalletState;
+    loadUnlockSession?: typeof loadUnlockSession;
+    loadWalletExplicitLock?: typeof loadWalletExplicitLock;
     initializeWallet?: typeof initializeWallet;
+    restoreWalletFromMnemonic?: typeof restoreWalletFromMnemonic;
+    previewResetWallet?: typeof previewResetWallet;
     exportWallet?: typeof exportWallet;
     importWallet?: typeof importWallet;
     unlockWallet?: typeof unlockWallet;
@@ -126,12 +146,14 @@ export interface CliRunnerContext {
     readMiningLog?: typeof readMiningLog;
     followMiningLog?: typeof followMiningLog;
     repairWallet?: typeof repairWallet;
+    resetWallet?: typeof resetWallet;
     walletSecretProvider?: WalletSecretProvider;
     createPrompter?: () => WalletPrompter;
     ensureDirectory?: (path: string) => Promise<void>;
     readPackageVersion?: () => Promise<string>;
     resolveDefaultBitcoindDataDir?: () => string;
     resolveDefaultClientDatabasePath?: () => string;
+    resolveWalletRuntimePaths?: () => WalletRuntimePaths;
 }
 export interface StopSignalWatcher {
     cleanup(): void;

package/dist/cli/types.js

@@ -1,2 +1,8 @@
 import { openManagedBitcoindClient } from "../bitcoind/index.js";
+import { createRpcClient } from "../bitcoind/node.js";
+import { attachOrStartIndexerDaemon, probeIndexerDaemon, readObservedIndexerDaemonStatus, stopIndexerDaemonService, } from "../bitcoind/indexer-daemon.js";
+import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, stopManagedBitcoindService, } from "../bitcoind/service.js";
 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";

package/dist/cli/wallet-format.js

@@ -75,6 +75,9 @@ function formatPendingMutationDomainLabel(mutation) {
     return kind;
 }
 export function getRepairRecommendation(context) {
+    if (context.localState.availability === "uninitialized") {
+        return "Run `cogcoin init` to create a new local wallet root.";
+    }
     if (context.localState.availability === "local-state-corrupt") {
         return "Run `cogcoin repair` to recover local wallet state.";
     }

package/dist/cli/workflow-hints.d.ts

@@ -2,6 +2,7 @@ import type { WalletIdentityView, WalletLockView, WalletReadContext } from "../w
 export declare function formatNextStepLines(nextSteps: readonly string[]): string[];
 export declare function getFundingQuickstartGuidance(): string;
 export declare function getInitNextSteps(): string[];
+export declare function getRestoreNextSteps(): string[];
 export declare function getBootstrapSyncNextStep(context: Pick<WalletReadContext, "bitcoind" | "indexer" | "nodeHealth">): string | null;
 export declare function getRegisterNextSteps(domainName: string, registerKind: "root" | "subdomain"): string[];
 export declare function getAnchorNextSteps(domainName: string): string[];

package/dist/cli/workflow-hints.js

@@ -10,6 +10,9 @@ export function getFundingQuickstartGuidance() {
 export function getInitNextSteps() {
     return ["cogcoin sync", "cogcoin address"];
 }
+export function getRestoreNextSteps() {
+    return ["cogcoin sync", "cogcoin address"];
+}
 function blocksSyncBootstrap(context) {
     return context.bitcoind.health === "service-version-mismatch"
         || context.bitcoind.health === "wallet-root-mismatch"

package/dist/wallet/fs/lock.d.ts

@@ -16,4 +16,6 @@ export declare class FileLockBusyError extends Error {
     constructor(lockPath: string, existingMetadata: FileLockMetadata | null);
 }
 export declare function readLockMetadata(lockPath: string): Promise<FileLockMetadata | null>;
+export declare function clearLockIfOwnedByCurrentProcess(lockPath: string): Promise<boolean>;
+export declare function clearOrphanedFileLock(lockPath: string, isProcessAlive: (pid: number) => Promise<boolean>): Promise<boolean>;
 export declare function acquireFileLock(lockPath: string, metadata?: Partial<FileLockMetadata>): Promise<FileLockHandle>;

package/dist/wallet/fs/lock.js

@@ -22,6 +22,38 @@ export async function readLockMetadata(lockPath) {
         throw error;
     }
 }
+export async function clearLockIfOwnedByCurrentProcess(lockPath) {
+    const metadata = await readLockMetadata(lockPath);
+    if (metadata === null || metadata.processId !== (process.pid ?? null)) {
+        return false;
+    }
+    await rm(lockPath, { force: true });
+    return true;
+}
+export async function clearOrphanedFileLock(lockPath, isProcessAlive) {
+    let metadata = null;
+    try {
+        metadata = await readLockMetadata(lockPath);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return false;
+        }
+        await rm(lockPath, { force: true });
+        return true;
+    }
+    if (metadata === null) {
+        return false;
+    }
+    const processId = typeof metadata.processId === "number" && Number.isInteger(metadata.processId)
+        ? metadata.processId
+        : null;
+    if (processId === null || !await isProcessAlive(processId)) {
+        await rm(lockPath, { force: true });
+        return true;
+    }
+    return false;
+}
 export async function acquireFileLock(lockPath, metadata = {}) {
     await mkdir(dirname(lockPath), { recursive: true });
     const fullMetadata = {

package/dist/wallet/lifecycle.d.ts

@@ -11,6 +11,7 @@ export interface WalletPrompter {
     readonly isInteractive: boolean;
     writeLine(message: string): void;
     prompt(message: string): Promise<string>;
+    promptHidden?(message: string): Promise<string>;
     clearSensitiveDisplay?(scope: "mnemonic-reveal"): void | Promise<void>;
 }
 export interface WalletInitializationResult {
@@ -40,6 +41,13 @@ export interface WalletImportResult {
     unlockUntilUnixMs: number;
     state: WalletStateV1;
 }
+export interface WalletRestoreResult {
+    walletRootId: string;
+    fundingAddress: string;
+    unlockUntilUnixMs: number;
+    state: WalletStateV1;
+    warnings?: string[];
+}
 export interface WalletRepairResult {
     walletRootId: string;
     recoveredFromBackup: boolean;
@@ -58,6 +66,7 @@ export interface WalletRepairResult {
     miningResumeError: string | null;
     note: string | null;
 }
+export { previewResetWallet, resetWallet, type WalletResetPreview, type WalletResetResult, } from "./reset.js";
 interface WalletLifecycleRpcClient {
     getDescriptorInfo(descriptor: string): Promise<{
         descriptor: string;
@@ -189,6 +198,16 @@ export declare function importWallet(options: {
     attachIndexerDaemon?: typeof attachOrStartIndexerDaemon;
     rpcFactory?: (config: Parameters<typeof createRpcClient>[0]) => WalletLifecycleRpcClient;
 }): Promise<WalletImportResult>;
+export declare function restoreWalletFromMnemonic(options: {
+    dataDir: string;
+    provider?: WalletSecretProvider;
+    prompter: WalletPrompter;
+    nowUnixMs?: number;
+    unlockDurationMs?: number;
+    paths?: WalletRuntimePaths;
+    attachService?: typeof attachOrStartManagedBitcoindService;
+    rpcFactory?: (config: Parameters<typeof createRpcClient>[0]) => WalletLifecycleRpcClient;
+}): Promise<WalletRestoreResult>;
 export declare function repairWallet(options: {
     dataDir: string;
     databasePath: string;
@@ -204,4 +223,3 @@ export declare function repairWallet(options: {
     requestMiningPreemption?: typeof requestMiningGenerationPreemption;
     startBackgroundMining?: typeof import("./mining/runner.js").startBackgroundMining;
 }): Promise<WalletRepairResult>;
-export {};

package/dist/wallet/lifecycle.js

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import { access, constants, mkdir, readFile, rename, rm } from "node:fs/promises";
+import { access, constants, mkdir, readFile, readdir, rename, rm } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { openClient } from "../client.js";
 import { attachOrStartIndexerDaemon, probeIndexerDaemon, readSnapshotWithRetry, } from "../bitcoind/indexer-daemon.js";
@@ -9,19 +9,21 @@ 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 { acquireFileLock, clearOrphanedFileLock } from "./fs/lock.js";
+import { createInternalCoreWalletPassphrase, createMnemonicConfirmationChallenge, deriveWalletMaterialFromMnemonic, generateWalletMaterial, isEnglishMnemonicWord, validateEnglishMnemonic, } from "./material.js";
 import { resolveWalletRuntimePathsForTesting } from "./runtime.js";
 import { requestMiningGenerationPreemption } from "./mining/coordination.js";
 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 { renderWalletMnemonicRevealArt } from "./mnemonic-art.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";
 export const DEFAULT_UNLOCK_DURATION_MS = 15 * 60 * 1000;
+export { previewResetWallet, resetWallet, } from "./reset.js";
 function sanitizeWalletName(walletRootId) {
     return `cogcoin-${walletRootId}`.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 63);
 }
@@ -34,6 +36,32 @@ async function pathExists(path) {
         return false;
     }
 }
+async function readJsonFileOrNull(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        return null;
+    }
+}
+async function loadRawWalletEnvelope(paths) {
+    const primary = await readJsonFileOrNull(paths.walletStatePath);
+    if (primary !== null) {
+        return primary;
+    }
+    return readJsonFileOrNull(paths.walletStateBackupPath);
+}
+function extractWalletRootIdFromEnvelope(envelope) {
+    const keyId = envelope?.secretProvider?.keyId ?? null;
+    const prefix = "wallet-state:";
+    if (keyId === null || !keyId.startsWith(prefix)) {
+        return null;
+    }
+    return keyId.slice(prefix.length);
+}
 function createInitialWalletState(options) {
     return {
         schemaVersion: 1,
@@ -294,6 +322,12 @@ async function promptRequiredValue(prompter, message) {
     }
     return value;
 }
+async function promptHiddenValue(prompter, message) {
+    const value = prompter.promptHidden != null
+        ? await prompter.promptHidden(message)
+        : await prompter.prompt(message);
+    return value.trim();
+}
 async function promptForArchivePassphrase(prompter, promptPrefix) {
     const first = await promptRequiredValue(prompter, `${promptPrefix} passphrase: `);
     const second = await promptRequiredValue(prompter, `Confirm ${promptPrefix.toLowerCase()} passphrase: `);
@@ -302,12 +336,33 @@ async function promptForArchivePassphrase(prompter, promptPrefix) {
     }
     return first;
 }
+async function promptForRestoreMnemonic(prompter) {
+    const words = [];
+    for (let index = 0; index < 24; index += 1) {
+        const word = (await promptHiddenValue(prompter, `Word ${index + 1} of 24: `)).toLowerCase();
+        if (!isEnglishMnemonicWord(word)) {
+            throw new Error("wallet_restore_mnemonic_invalid");
+        }
+        words.push(word);
+    }
+    const phrase = words.join(" ");
+    if (!validateEnglishMnemonic(phrase)) {
+        throw new Error("wallet_restore_mnemonic_invalid");
+    }
+    return phrase;
+}
 async function confirmTypedAcknowledgement(prompter, expected, message) {
     const answer = (await prompter.prompt(message)).trim();
     if (answer !== expected) {
         throw new Error("wallet_typed_confirmation_rejected");
     }
 }
+async function confirmRestoreReplacement(prompter) {
+    const answer = (await prompter.prompt("Type \"RESTORE\" to replace the existing local wallet state and managed Core wallet replica: ")).trim();
+    if (answer !== "RESTORE") {
+        throw new Error("wallet_restore_replace_confirmation_required");
+    }
+}
 async function confirmOverwriteIfNeeded(prompter, path) {
     if (!await pathExists(path)) {
         return;
@@ -516,6 +571,86 @@ async function clearManagedBitcoindArtifacts(servicePaths) {
     await rm(servicePaths.bitcoindReadyPath, { force: true }).catch(() => undefined);
     await rm(servicePaths.bitcoindWalletStatusPath, { force: true }).catch(() => undefined);
 }
+async function detectExistingManagedWalletReplica(dataDir) {
+    try {
+        const entries = await readdir(join(dataDir, "wallets"), { withFileTypes: true });
+        return entries.some((entry) => entry.isDirectory() && entry.name.startsWith("cogcoin-"));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+async function stopRecordedManagedProcess(pid, errorCode) {
+    if (pid === null || !await isProcessAlive(pid)) {
+        return;
+    }
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+            throw error;
+        }
+    }
+    try {
+        await waitForProcessExit(pid, 5_000, errorCode);
+        return;
+    }
+    catch {
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+                throw error;
+            }
+        }
+    }
+    await waitForProcessExit(pid, 5_000, errorCode);
+}
+async function clearOrphanedRepairLocks(lockPaths) {
+    for (const lockPath of lockPaths) {
+        await clearOrphanedFileLock(lockPath, isProcessAlive);
+    }
+}
+async function clearPreviousManagedWalletRuntime(options) {
+    if (options.walletRootId === null) {
+        return;
+    }
+    const servicePaths = resolveManagedServicePaths(options.dataDir, options.walletRootId);
+    const bitcoindLock = await acquireFileLock(servicePaths.bitcoindLockPath, {
+        purpose: "wallet-restore-cleanup",
+        walletRootId: options.walletRootId,
+    });
+    const indexerLock = await acquireFileLock(servicePaths.indexerDaemonLockPath, {
+        purpose: "wallet-restore-cleanup",
+        walletRootId: options.walletRootId,
+    });
+    try {
+        const bitcoindStatus = await readJsonFileOrNull(servicePaths.bitcoindStatusPath);
+        const indexerStatus = await readJsonFileOrNull(servicePaths.indexerDaemonStatusPath);
+        await stopRecordedManagedProcess(bitcoindStatus?.processId ?? null, "managed_bitcoind_stop_timeout");
+        await stopRecordedManagedProcess(indexerStatus?.processId ?? null, "indexer_daemon_stop_timeout");
+        await clearManagedBitcoindArtifacts(servicePaths);
+        await clearIndexerDaemonArtifacts(servicePaths);
+        await rm(servicePaths.walletRuntimeRoot, { recursive: true, force: true }).catch(() => undefined);
+        await rm(servicePaths.indexerServiceRoot, { recursive: true, force: true }).catch(() => undefined);
+        await rm(join(options.dataDir, "wallets", sanitizeWalletName(options.walletRootId)), { recursive: true, force: true }).catch(() => undefined);
+    }
+    finally {
+        await indexerLock.release();
+        await bitcoindLock.release();
+    }
+}
+function formatRestoreCleanupWarning(error) {
+    const reason = error instanceof Error && error.message.trim().length > 0
+        ? ` (${error.message})`
+        : "";
+    return `Previous managed runtime cleanup did not complete${reason}. Run \`cogcoin repair\` if status shows stale or conflicting managed services.`;
+}
 function createSilentNonInteractivePrompter() {
     return {
         isInteractive: false,
@@ -949,6 +1084,11 @@ export async function initializeWallet(options) {
         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);
         mnemonicRevealed = true;
         try {
@@ -1213,6 +1353,106 @@ export async function importWallet(options) {
         await controlLock.release();
     }
 }
+export async function restoreWalletFromMnemonic(options) {
+    if (!options.prompter.isInteractive) {
+        throw new Error("wallet_restore_requires_tty");
+    }
+    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 controlLock = await acquireFileLock(paths.walletControlLockPath, {
+        purpose: "wallet-restore",
+        walletRootId: null,
+    });
+    try {
+        const rawEnvelope = await loadRawWalletEnvelope(paths);
+        const replacementStateExists = rawEnvelope !== null
+            || await pathExists(paths.walletStatePath)
+            || await pathExists(paths.walletStateBackupPath);
+        const replacementCoreWalletExists = await detectExistingManagedWalletReplica(options.dataDir);
+        const mnemonicPhrase = await promptForRestoreMnemonic(options.prompter);
+        if (replacementStateExists || replacementCoreWalletExists) {
+            await confirmRestoreReplacement(options.prompter);
+        }
+        let previousWalletRootId = extractWalletRootIdFromEnvelope(rawEnvelope);
+        try {
+            const loaded = await loadWalletState({
+                primaryPath: paths.walletStatePath,
+                backupPath: paths.walletStateBackupPath,
+            }, {
+                provider,
+            });
+            previousWalletRootId = loaded.state.walletRootId;
+        }
+        catch {
+            previousWalletRootId = previousWalletRootId ?? null;
+        }
+        const miningLock = await acquireFileLock(paths.miningControlLockPath, {
+            purpose: "wallet-restore",
+            walletRootId: previousWalletRootId,
+        });
+        try {
+            const warnings = [];
+            const material = deriveWalletMaterialFromMnemonic(mnemonicPhrase);
+            const walletRootId = createWalletRootId();
+            const internalCoreWalletPassphrase = createInternalCoreWalletPassphrase();
+            const secretReference = createWalletSecretReference(walletRootId);
+            const secret = randomBytes(32);
+            await provider.storeSecret(secretReference.keyId, secret);
+            const initialState = createInitialWalletState({
+                walletRootId,
+                nowUnixMs,
+                material,
+                internalCoreWalletPassphrase,
+            });
+            await clearUnlockSession(paths.walletUnlockSessionPath);
+            await clearWalletExplicitLock(paths.walletExplicitLockPath);
+            await saveWalletState({
+                primaryPath: paths.walletStatePath,
+                backupPath: paths.walletStateBackupPath,
+            }, initialState, {
+                provider,
+                secretReference,
+            });
+            const restoredState = await recreateManagedCoreWalletReplica(initialState, provider, paths, options.dataDir, nowUnixMs, {
+                attachService: options.attachService,
+                rpcFactory: options.rpcFactory,
+            });
+            const unlockUntilUnixMs = nowUnixMs + unlockDurationMs;
+            await clearWalletExplicitLock(paths.walletExplicitLockPath);
+            await saveUnlockSession(paths.walletUnlockSessionPath, createUnlockSession(restoredState, unlockUntilUnixMs, secretReference.keyId, nowUnixMs), {
+                provider,
+                secretReference,
+            });
+            if (previousWalletRootId !== null && previousWalletRootId !== walletRootId) {
+                try {
+                    await clearPreviousManagedWalletRuntime({
+                        dataDir: options.dataDir,
+                        walletRootId: previousWalletRootId,
+                    });
+                }
+                catch (error) {
+                    warnings.push(formatRestoreCleanupWarning(error));
+                }
+                await provider.deleteSecret(createWalletSecretReference(previousWalletRootId).keyId).catch(() => undefined);
+            }
+            return {
+                walletRootId,
+                fundingAddress: restoredState.funding.address,
+                unlockUntilUnixMs,
+                state: restoredState,
+                warnings,
+            };
+        }
+        finally {
+            await miningLock.release();
+        }
+    }
+    finally {
+        await controlLock.release();
+    }
+}
 export async function repairWallet(options) {
     const provider = options.provider ?? createDefaultWalletSecretProvider();
     const nowUnixMs = options.nowUnixMs ?? Date.now();
@@ -1222,6 +1462,10 @@ export async function repairWallet(options) {
     const probeManagedIndexerDaemon = options.probeIndexerDaemon ?? probeIndexerDaemon;
     const attachManagedIndexerDaemon = options.attachIndexerDaemon ?? attachOrStartIndexerDaemon;
     const requestMiningPreemptionForRepair = options.requestMiningPreemption ?? requestMiningGenerationPreemption;
+    await clearOrphanedRepairLocks([
+        paths.walletControlLockPath,
+        paths.miningControlLockPath,
+    ]);
     const controlLock = await acquireFileLock(paths.walletControlLockPath, {
         purpose: "wallet-repair",
         walletRootId: null,
@@ -1245,6 +1489,10 @@ export async function repairWallet(options) {
         let repairedState = loaded.state;
         let repairStateNeedsPersist = false;
         const servicePaths = resolveManagedServicePaths(options.dataDir, repairedState.walletRootId);
+        await clearOrphanedRepairLocks([
+            servicePaths.bitcoindLockPath,
+            servicePaths.indexerDaemonLockPath,
+        ]);
         const preRepairMiningRuntime = await loadMiningRuntimeStatus(paths.miningStatusPath).catch(() => null);
         const backgroundWorkerAlive = preRepairMiningRuntime?.runMode === "background"
             && preRepairMiningRuntime.backgroundWorkerPid !== null

package/dist/wallet/material.d.ts

@@ -36,6 +36,8 @@ export interface WalletDerivedIdentity {
     nostrNpub: string;
 }
 export declare function generateWalletMaterial(): WalletMaterial;
+export declare function isEnglishMnemonicWord(word: string): boolean;
+export declare function validateEnglishMnemonic(phrase: string): boolean;
 export declare function deriveWalletMaterialFromMnemonic(phrase: string): WalletMaterial;
 export declare function deriveWalletIdentityMaterial(accountKey: string, index: number): WalletDerivedIdentity;
 export declare function createInternalCoreWalletPassphrase(): string;