@cogcoin/client 1.1.5 → 1.1.7

package/README.md

@@ -1,6 +1,6 @@
 # `@cogcoin/client`
 
-`@cogcoin/client@1.1.5` is the reference 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@1.1.7` is the reference 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.
 
@@ -135,7 +135,7 @@ The installed `cogcoin` command covers the first-party local wallet and node wor
 - sync and service commands such as `status`, `sync`, `follow`, `bitcoin start`, `bitcoin stop`, `bitcoin status`, `indexer start`, `indexer stop`, and `indexer status`
 - domain and field commands such as `register`, `anchor`, `show`, `domains`, `fields`, `buy`, `sell`, and `transfer`
 - COG and reputation commands such as `send`, `cog lock`, `claim`, `reclaim`, `rep give`, and `rep revoke`
-- mining commands such as `mine`, `mine start`, `mine stop`, `mine status`, `mine log`, `mine setup`, `mine prompt`, and `mine prompt list`
+- mining commands such as `mine`, `mine status`, `mine log`, `mine setup`, `mine prompt`, and `mine prompt list`
 
 Use `cogcoin mine prompt <domain>` to set or clear a per-domain mining prompt override for one anchored root domain, and `cogcoin mine prompt list` to inspect the current per-domain prompt state alongside the global fallback prompt.
 Interactive text invocations periodically check the npm registry for newer `@cogcoin/client` releases and print `npm install -g @cogcoin/client` when a newer version is available.

package/dist/bitcoind/indexer-daemon.d.ts

@@ -1,5 +1,7 @@
+import type { ManagedIndexerDaemonProbeResult } from "./managed-runtime/types.js";
 import { type BootstrapPhase, type BootstrapProgress, type ManagedIndexerDaemonObservedStatus, type ManagedIndexerDaemonStatus } from "./types.js";
 import { resolveManagedServicePaths } from "./service-paths.js";
+export type { IndexerDaemonCompatibility } from "./managed-runtime/types.js";
 export declare const INDEXER_DAEMON_BACKGROUND_FOLLOW_RECOVERY_FAILED = "indexer_daemon_background_follow_recovery_failed";
 interface DaemonRequest {
     id: string;
@@ -74,13 +76,7 @@ export interface IndexerDaemonClient {
     resumeBackgroundFollow(): Promise<void>;
     close(): Promise<void>;
 }
-export type IndexerDaemonCompatibility = "compatible" | "service-version-mismatch" | "wallet-root-mismatch" | "schema-mismatch" | "unreachable" | "protocol-error";
-export interface IndexerDaemonProbeResult {
-    compatibility: IndexerDaemonCompatibility;
-    status: ManagedIndexerDaemonObservedStatus | null;
-    client: IndexerDaemonClient | null;
-    error: string | null;
-}
+export type IndexerDaemonProbeResult = ManagedIndexerDaemonProbeResult<IndexerDaemonClient>;
 export interface IndexerDaemonStopResult {
     status: "stopped" | "not-running";
     walletRootId: string;

package/dist/bitcoind/indexer-daemon.js

@@ -1,12 +1,14 @@
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
-import { mkdir, readFile, rm } from "node:fs/promises";
+import { mkdir, rm } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import net from "node:net";
-import { compareSemver, parseSemver } from "../semver.js";
 import { acquireFileLock, FileLockBusyError } from "../wallet/fs/lock.js";
 import { writeRuntimeStatusFile } from "../wallet/fs/status-file.js";
-import { INDEXER_DAEMON_SCHEMA_VERSION, INDEXER_DAEMON_SERVICE_API_VERSION, } from "./types.js";
+import { buildManagedIndexerStatusFromSnapshotHandle, mapIndexerDaemonTransportError, mapIndexerDaemonValidationError, validateIndexerDaemonStatus, validateIndexerSnapshotHandle, validateIndexerSnapshotPayload, } from "./managed-runtime/indexer-policy.js";
+import { attachOrStartManagedIndexerRuntime } from "./managed-runtime/indexer-runtime.js";
+import { readJsonFileIfPresent } from "./managed-runtime/status.js";
+import {} from "./types.js";
 import { resolveManagedServicePaths, UNINITIALIZED_WALLET_ROOT_ID } from "./service-paths.js";
 const DEFAULT_STARTUP_TIMEOUT_MS = 30_000;
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5_000;
@@ -15,17 +17,6 @@ const INDEXER_DAEMON_REQUEST_TIMEOUT_MS = 15_000;
 const INDEXER_DAEMON_RESUME_BACKGROUND_FOLLOW_REQUEST_TIMEOUT_MS = 35_000;
 const INDEXER_DAEMON_BACKGROUND_FOLLOW_NOT_ACTIVE = "indexer_daemon_background_follow_not_active";
 export const INDEXER_DAEMON_BACKGROUND_FOLLOW_RECOVERY_FAILED = "indexer_daemon_background_follow_recovery_failed";
-async function readJsonFile(filePath) {
-    try {
-        return JSON.parse(await readFile(filePath, "utf8"));
-    }
-    catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-            return null;
-        }
-        throw error;
-    }
-}
 async function isProcessAlive(pid) {
     if (pid === null) {
         return false;
@@ -68,7 +59,7 @@ function ignoreProcessNotFound(error) {
 export async function stopIndexerDaemonServiceWithLockHeld(options) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
     const paths = options.paths ?? resolveManagedServicePaths(options.dataDir, walletRootId);
-    const status = await readJsonFile(paths.indexerDaemonStatusPath);
+    const status = await readJsonFileIfPresent(paths.indexerDaemonStatusPath);
     const processId = options.processId ?? status?.processId ?? null;
     if (status === null || processId === null || !await isProcessAlive(processId)) {
         await clearIndexerDaemonRuntimeArtifacts(paths);
@@ -217,97 +208,6 @@ function createIndexerDaemonClient(socketPath, closeOptions = null) {
         },
     };
 }
-function validateIndexerRuntimeIdentity(identity, expectedWalletRootId) {
-    if (identity.serviceApiVersion !== INDEXER_DAEMON_SERVICE_API_VERSION) {
-        throw new Error("indexer_daemon_service_version_mismatch");
-    }
-    if (identity.schemaVersion !== INDEXER_DAEMON_SCHEMA_VERSION || identity.state === "schema-mismatch") {
-        throw new Error("indexer_daemon_schema_mismatch");
-    }
-}
-function validateIndexerDaemonStatus(status, expectedWalletRootId) {
-    validateIndexerRuntimeIdentity(status, expectedWalletRootId);
-}
-function validateIndexerSnapshotHandle(handle, expectedWalletRootId) {
-    validateIndexerRuntimeIdentity(handle, expectedWalletRootId);
-}
-function validateIndexerSnapshotPayload(payload, handle, expectedWalletRootId) {
-    validateIndexerRuntimeIdentity(payload, expectedWalletRootId);
-    if (payload.token !== handle.token
-        || payload.daemonInstanceId !== handle.daemonInstanceId
-        || payload.processId !== handle.processId
-        || payload.startedAtUnixMs !== handle.startedAtUnixMs
-        || payload.snapshotSeq !== handle.snapshotSeq
-        || payload.tipHeight !== handle.tipHeight
-        || payload.tipHash !== handle.tipHash
-        || payload.openedAtUnixMs !== handle.openedAtUnixMs) {
-        throw new Error("indexer_daemon_snapshot_identity_mismatch");
-    }
-    if (payload.tip === null) {
-        if (payload.tipHeight !== null || payload.tipHash !== null) {
-            throw new Error("indexer_daemon_snapshot_identity_mismatch");
-        }
-    }
-    else if (payload.tip.height !== payload.tipHeight || payload.tip.blockHashHex !== payload.tipHash) {
-        throw new Error("indexer_daemon_snapshot_identity_mismatch");
-    }
-}
-function isUnreachableIndexerDaemonError(error) {
-    if (error instanceof Error) {
-        if (error.message === "indexer_daemon_connection_closed"
-            || error.message === "indexer_daemon_request_timeout"
-            || error.message === "indexer_daemon_protocol_error") {
-            return false;
-        }
-        if ("code" in error) {
-            const code = error.code;
-            return code === "ENOENT" || code === "ECONNREFUSED" || code === "ECONNRESET";
-        }
-    }
-    return false;
-}
-function buildStatusFromSnapshotHandle(handle) {
-    return {
-        serviceApiVersion: INDEXER_DAEMON_SERVICE_API_VERSION,
-        binaryVersion: handle.binaryVersion,
-        buildId: handle.buildId,
-        updatedAtUnixMs: Math.max(handle.heartbeatAtUnixMs, handle.openedAtUnixMs),
-        walletRootId: handle.walletRootId,
-        daemonInstanceId: handle.daemonInstanceId,
-        schemaVersion: INDEXER_DAEMON_SCHEMA_VERSION,
-        state: handle.state,
-        processId: handle.processId,
-        startedAtUnixMs: handle.startedAtUnixMs,
-        heartbeatAtUnixMs: handle.heartbeatAtUnixMs,
-        ipcReady: true,
-        rpcReachable: handle.rpcReachable,
-        coreBestHeight: handle.coreBestHeight,
-        coreBestHash: handle.coreBestHash,
-        appliedTipHeight: handle.appliedTipHeight,
-        appliedTipHash: handle.appliedTipHash,
-        snapshotSeq: handle.snapshotSeq,
-        backlogBlocks: handle.backlogBlocks,
-        reorgDepth: handle.reorgDepth,
-        lastAppliedAtUnixMs: handle.lastAppliedAtUnixMs,
-        activeSnapshotCount: handle.activeSnapshotCount,
-        lastError: handle.lastError,
-        backgroundFollowActive: handle.backgroundFollowActive,
-        bootstrapPhase: handle.bootstrapPhase,
-        bootstrapProgress: handle.bootstrapProgress,
-        cogcoinSyncHeight: handle.cogcoinSyncHeight,
-        cogcoinSyncTargetHeight: handle.cogcoinSyncTargetHeight,
-    };
-}
-function isStaleIndexerDaemonVersion(status, expectedBinaryVersion) {
-    if (status === null || expectedBinaryVersion === null || expectedBinaryVersion === undefined) {
-        return false;
-    }
-    if (parseSemver(expectedBinaryVersion) === null) {
-        return false;
-    }
-    const comparison = compareSemver(status.binaryVersion, expectedBinaryVersion);
-    return comparison === null || comparison < 0;
-}
 async function probeIndexerDaemonAtSocket(socketPath, expectedWalletRootId) {
     const client = createIndexerDaemonClient(socketPath);
     try {
@@ -323,30 +223,12 @@ async function probeIndexerDaemonAtSocket(socketPath, expectedWalletRootId) {
         }
         catch (error) {
             await client.close().catch(() => undefined);
-            return {
-                compatibility: error instanceof Error
-                    ? error.message === "indexer_daemon_service_version_mismatch"
-                        ? "service-version-mismatch"
-                        : "schema-mismatch"
-                    : "protocol-error",
-                status,
-                client: null,
-                error: error instanceof Error ? error.message : "indexer_daemon_protocol_error",
-            };
+            return mapIndexerDaemonValidationError(error, status);
         }
     }
     catch (error) {
         await client.close().catch(() => undefined);
-        return {
-            compatibility: isUnreachableIndexerDaemonError(error) ? "unreachable" : "protocol-error",
-            status: null,
-            client: null,
-            error: isUnreachableIndexerDaemonError(error)
-                ? null
-                : error instanceof Error
-                    ? "indexer_daemon_protocol_error"
-                    : "indexer_daemon_protocol_error",
-        };
+        return mapIndexerDaemonTransportError(error);
     }
 }
 async function waitForIndexerDaemon(dataDir, walletRootId, timeoutMs) {
@@ -380,7 +262,7 @@ export async function readSnapshotWithRetry(daemon, expectedWalletRootId) {
             validateIndexerSnapshotPayload(payload, handle, expectedWalletRootId);
             return {
                 payload,
-                status: buildStatusFromSnapshotHandle(handle),
+                status: buildManagedIndexerStatusFromSnapshotHandle(handle),
             };
         }
         catch (error) {
@@ -400,7 +282,7 @@ export async function readSnapshotWithRetry(daemon, expectedWalletRootId) {
 export async function readObservedIndexerDaemonStatus(options) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
     const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
-    return readJsonFile(paths.indexerDaemonStatusPath);
+    return readJsonFileIfPresent(paths.indexerDaemonStatusPath);
 }
 export async function attachOrStartIndexerDaemon(options) {
     const requestBackgroundFollow = async (client, observedStatus = null) => {
@@ -466,82 +348,35 @@ export async function attachOrStartIndexerDaemon(options) {
             shutdownTimeoutMs: options.shutdownTimeoutMs,
         });
     };
-    const existingProbe = await probeIndexerDaemonAtSocket(paths.indexerDaemonSocketPath, walletRootId);
-    if (existingProbe.compatibility === "compatible" && existingProbe.client !== null) {
-        if (!isStaleIndexerDaemonVersion(existingProbe.status, expectedBinaryVersion)) {
-            try {
-                return await requestBackgroundFollow(existingProbe.client, existingProbe.status);
-            }
-            catch {
-                await existingProbe.client.close().catch(() => undefined);
-            }
-        }
-        else {
-            await existingProbe.client.close().catch(() => undefined);
-        }
-    }
-    if (existingProbe.compatibility !== "unreachable" && existingProbe.compatibility !== "compatible") {
-        throw new Error(existingProbe.error ?? "indexer_daemon_protocol_error");
-    }
-    try {
-        const lock = await acquireFileLock(paths.indexerDaemonLockPath, {
+    return attachOrStartManagedIndexerRuntime({
+        ...options,
+        walletRootId,
+        startupTimeoutMs,
+        expectedBinaryVersion,
+    }, {
+        getPaths: (runtimeOptions) => resolveManagedServicePaths(runtimeOptions.dataDir, runtimeOptions.walletRootId),
+        probeDaemon: async (runtimeOptions, runtimePaths) => probeIndexerDaemonAtSocket(runtimePaths.indexerDaemonSocketPath, runtimeOptions.walletRootId),
+        requestBackgroundFollow,
+        closeClient: async (client) => {
+            await client.close();
+        },
+        acquireStartLock: async (runtimeOptions, runtimePaths) => acquireFileLock(runtimePaths.indexerDaemonLockPath, {
             purpose: "indexer-daemon-start",
-            walletRootId,
-            dataDir: options.dataDir,
-            databasePath: options.databasePath,
-        });
-        try {
-            const liveProbe = await probeIndexerDaemonAtSocket(paths.indexerDaemonSocketPath, walletRootId);
-            if (liveProbe.compatibility === "compatible" && liveProbe.client !== null) {
-                if (!isStaleIndexerDaemonVersion(liveProbe.status, expectedBinaryVersion)) {
-                    try {
-                        return await requestBackgroundFollow(liveProbe.client, liveProbe.status);
-                    }
-                    catch {
-                        await liveProbe.client.close().catch(() => undefined);
-                        await stopIndexerDaemonServiceWithLockHeld({
-                            dataDir: options.dataDir,
-                            walletRootId,
-                            shutdownTimeoutMs: options.shutdownTimeoutMs,
-                            paths,
-                            processId: liveProbe.status?.processId ?? null,
-                        });
-                    }
-                }
-                else {
-                    await liveProbe.client.close().catch(() => undefined);
-                    await stopIndexerDaemonServiceWithLockHeld({
-                        dataDir: options.dataDir,
-                        walletRootId,
-                        shutdownTimeoutMs: options.shutdownTimeoutMs,
-                        paths,
-                        processId: liveProbe.status?.processId ?? null,
-                    });
-                }
-            }
-            else if (liveProbe.compatibility !== "unreachable") {
-                throw new Error(liveProbe.error ?? "indexer_daemon_protocol_error");
-            }
-            const daemon = await startDaemon();
-            try {
-                return await requestBackgroundFollow(daemon);
-            }
-            catch (error) {
-                await daemon.close().catch(() => undefined);
-                throw new Error(INDEXER_DAEMON_BACKGROUND_FOLLOW_RECOVERY_FAILED, { cause: error });
-            }
-        }
-        finally {
-            await lock.release();
-        }
-    }
-    catch (error) {
-        if (error instanceof FileLockBusyError) {
-            await waitForIndexerDaemon(options.dataDir, walletRootId, startupTimeoutMs);
-            return attachOrStartIndexerDaemon(options);
-        }
-        throw error;
-    }
+            walletRootId: runtimeOptions.walletRootId,
+            dataDir: runtimeOptions.dataDir,
+            databasePath: runtimeOptions.databasePath,
+        }),
+        startDaemon: async () => startDaemon(),
+        stopWithLockHeld: async (runtimeOptions, runtimePaths, processId) => stopIndexerDaemonServiceWithLockHeld({
+            dataDir: runtimeOptions.dataDir,
+            walletRootId: runtimeOptions.walletRootId,
+            shutdownTimeoutMs: runtimeOptions.shutdownTimeoutMs,
+            paths: resolveManagedServicePaths(runtimeOptions.dataDir, runtimeOptions.walletRootId),
+            processId,
+        }),
+        isLockBusyError: (error) => error instanceof FileLockBusyError,
+        sleep,
+    });
 }
 export async function stopIndexerDaemonService(options) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
@@ -572,7 +407,7 @@ export async function shutdownIndexerDaemonForTesting(options) {
 export async function readIndexerDaemonStatusForTesting(options) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;
     const paths = resolveManagedServicePaths(options.dataDir, walletRootId);
-    return readJsonFile(paths.indexerDaemonStatusPath);
+    return readJsonFileIfPresent(paths.indexerDaemonStatusPath);
 }
 export async function writeIndexerDaemonStatusForTesting(options, status) {
     const walletRootId = options.walletRootId ?? UNINITIALIZED_WALLET_ROOT_ID;

package/dist/bitcoind/managed-runtime/bitcoind-policy.d.ts

@@ -0,0 +1,16 @@
+import type { ManagedBitcoindObservedStatus } from "../types.js";
+import type { WalletBitcoindStatus, WalletNodeStatus } from "../../wallet/read/types.js";
+import type { ManagedBitcoindProbeDecision, ManagedBitcoindServiceProbeResult } from "./types.js";
+export declare function validateManagedBitcoindObservedStatus(status: ManagedBitcoindObservedStatus, options: {
+    chain: "main" | "regtest";
+    dataDir: string;
+    runtimeRoot: string;
+}): void;
+export declare function mapManagedBitcoindValidationError(error: unknown, status: ManagedBitcoindObservedStatus): ManagedBitcoindServiceProbeResult;
+export declare function mapManagedBitcoindRuntimeProbeFailure(error: unknown, status: ManagedBitcoindObservedStatus): ManagedBitcoindServiceProbeResult;
+export declare function resolveManagedBitcoindProbeDecision(probe: ManagedBitcoindServiceProbeResult): ManagedBitcoindProbeDecision;
+export declare function deriveManagedBitcoindWalletStatus(options: {
+    status: ManagedBitcoindObservedStatus | null;
+    nodeStatus: WalletNodeStatus | null;
+    startupError: string | null;
+}): WalletBitcoindStatus;

package/dist/bitcoind/managed-runtime/bitcoind-policy.js

@@ -0,0 +1,177 @@
+import { join } from "node:path";
+import { resolveManagedServicePaths } from "../service-paths.js";
+import { MANAGED_BITCOIND_SERVICE_API_VERSION } from "../types.js";
+function isRuntimeMismatchError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    return error.message.startsWith("bitcoind_chain_expected_")
+        || error.message === "managed_bitcoind_runtime_mismatch";
+}
+function isUnreachableManagedBitcoindError(error) {
+    if (error instanceof Error) {
+        if ("code" in error) {
+            const code = error.code;
+            return code === "ENOENT" || code === "ECONNREFUSED" || code === "ECONNRESET";
+        }
+        return error.message === "bitcoind_cookie_timeout"
+            || error.message.includes("cookie file is unavailable")
+            || error.message.includes("ECONNREFUSED")
+            || error.message.includes("ECONNRESET")
+            || error.message.includes("socket hang up");
+    }
+    return false;
+}
+export function validateManagedBitcoindObservedStatus(status, options) {
+    const legacyRuntimeRoot = join(resolveManagedServicePaths(options.dataDir, status.walletRootId).runtimeRoot, status.walletRootId);
+    if (status.serviceApiVersion !== MANAGED_BITCOIND_SERVICE_API_VERSION) {
+        throw new Error("managed_bitcoind_service_version_mismatch");
+    }
+    // Managed bitcoind runtimes are adopted across wallet roots when the live
+    // runtime still points at the expected data dir and chain.
+    if (status.chain !== options.chain
+        || status.dataDir !== options.dataDir
+        || (status.runtimeRoot !== options.runtimeRoot && status.runtimeRoot !== legacyRuntimeRoot)) {
+        throw new Error("managed_bitcoind_runtime_mismatch");
+    }
+}
+export function mapManagedBitcoindValidationError(error, status) {
+    return {
+        compatibility: error instanceof Error
+            ? error.message === "managed_bitcoind_service_version_mismatch"
+                ? "service-version-mismatch"
+                : "runtime-mismatch"
+            : "protocol-error",
+        status,
+        error: error instanceof Error ? error.message : "managed_bitcoind_protocol_error",
+    };
+}
+export function mapManagedBitcoindRuntimeProbeFailure(error, status) {
+    if (isRuntimeMismatchError(error)) {
+        return {
+            compatibility: "runtime-mismatch",
+            status,
+            error: "managed_bitcoind_runtime_mismatch",
+        };
+    }
+    if (isUnreachableManagedBitcoindError(error)) {
+        return {
+            compatibility: "unreachable",
+            status,
+            error: null,
+        };
+    }
+    return {
+        compatibility: "protocol-error",
+        status,
+        error: "managed_bitcoind_protocol_error",
+    };
+}
+export function resolveManagedBitcoindProbeDecision(probe) {
+    if (probe.compatibility === "compatible") {
+        return {
+            action: "attach",
+            error: null,
+        };
+    }
+    if (probe.compatibility === "unreachable") {
+        return {
+            action: "start",
+            error: null,
+        };
+    }
+    return {
+        action: "reject",
+        error: probe.error ?? "managed_bitcoind_protocol_error",
+    };
+}
+function mapManagedBitcoindStartupError(message) {
+    switch (message) {
+        case "managed_bitcoind_service_start_timeout":
+            return {
+                health: "starting",
+                status: null,
+                message: "Managed bitcoind service is still starting.",
+            };
+        case "managed_bitcoind_service_version_mismatch":
+            return {
+                health: "service-version-mismatch",
+                status: null,
+                message: "The live managed bitcoind service is running an incompatible service version.",
+            };
+        case "managed_bitcoind_wallet_root_mismatch":
+            return {
+                health: "wallet-root-mismatch",
+                status: null,
+                message: "The live managed bitcoind service belongs to a different wallet root.",
+            };
+        case "managed_bitcoind_runtime_mismatch":
+            return {
+                health: "runtime-mismatch",
+                status: null,
+                message: "The live managed bitcoind service runtime does not match this wallet's expected data directory or chain.",
+            };
+        case "managed_bitcoind_protocol_error":
+            return {
+                health: "unavailable",
+                status: null,
+                message: "The managed bitcoind runtime artifacts are invalid or incomplete.",
+            };
+        default:
+            return {
+                health: "unavailable",
+                status: null,
+                message,
+            };
+    }
+}
+export function deriveManagedBitcoindWalletStatus(options) {
+    if (options.startupError !== null) {
+        const mapped = mapManagedBitcoindStartupError(options.startupError);
+        return {
+            ...mapped,
+            status: options.status,
+        };
+    }
+    if (options.status === null) {
+        return {
+            health: "unavailable",
+            status: null,
+            message: "Managed bitcoind service is unavailable.",
+        };
+    }
+    if (options.status.state === "starting") {
+        return {
+            health: "starting",
+            status: options.status,
+            message: options.status.lastError ?? "Managed bitcoind service is still starting.",
+        };
+    }
+    if (options.status.state === "failed") {
+        return {
+            health: "failed",
+            status: options.status,
+            message: options.status.lastError ?? "Managed bitcoind service refresh failed.",
+        };
+    }
+    const proofStatus = options.nodeStatus?.walletReplica?.proofStatus;
+    if (proofStatus === "missing") {
+        return {
+            health: "replica-missing",
+            status: options.status,
+            message: options.nodeStatus?.walletReplicaMessage ?? "Managed Core wallet replica is missing.",
+        };
+    }
+    if (proofStatus === "mismatch") {
+        return {
+            health: "replica-mismatch",
+            status: options.status,
+            message: options.nodeStatus?.walletReplicaMessage ?? "Managed Core wallet replica does not match trusted wallet state.",
+        };
+    }
+    return {
+        health: "ready",
+        status: options.status,
+        message: options.nodeStatus?.walletReplicaMessage ?? options.status.lastError,
+    };
+}

package/dist/bitcoind/managed-runtime/bitcoind-runtime.d.ts

@@ -0,0 +1,20 @@
+import type { ManagedBitcoindObservedStatus } from "../types.js";
+import type { ManagedBitcoindRuntimeOptionsLike, ManagedBitcoindRuntimePathsLike, ManagedBitcoindServiceProbeResult, ManagedBitcoindStatusCandidate, ManagedRuntimeLockLike } from "./types.js";
+type ManagedBitcoindRuntimeDependencies<TOptions, THandle> = {
+    getPaths(options: TOptions): ManagedBitcoindRuntimePathsLike;
+    listStatusCandidates(options: {
+        dataDir: string;
+        runtimeRoot: string;
+        expectedStatusPath: string;
+    }): Promise<ManagedBitcoindStatusCandidate[]>;
+    isProcessAlive(processId: number | null): Promise<boolean>;
+    probeStatusCandidate(status: ManagedBitcoindObservedStatus, options: TOptions, runtimeRoot: string): Promise<ManagedBitcoindServiceProbeResult>;
+    attachExisting(options: TOptions): Promise<THandle | null>;
+    acquireStartLock(options: TOptions, paths: ManagedBitcoindRuntimePathsLike): Promise<ManagedRuntimeLockLike>;
+    startService(options: TOptions, paths: ManagedBitcoindRuntimePathsLike): Promise<THandle>;
+    isLockBusyError(error: unknown): boolean;
+    sleep(ms: number): Promise<void>;
+};
+export declare function probeManagedBitcoindRuntime<TOptions extends ManagedBitcoindRuntimeOptionsLike>(options: TOptions, dependencies: Pick<ManagedBitcoindRuntimeDependencies<TOptions, never>, "getPaths" | "listStatusCandidates" | "isProcessAlive" | "probeStatusCandidate">): Promise<ManagedBitcoindServiceProbeResult>;
+export declare function attachOrStartManagedBitcoindRuntime<TOptions extends ManagedBitcoindRuntimeOptionsLike, THandle>(options: TOptions, dependencies: ManagedBitcoindRuntimeDependencies<TOptions, THandle>): Promise<THandle>;
+export {};

package/dist/bitcoind/managed-runtime/bitcoind-runtime.js

@@ -0,0 +1,74 @@
+import { resolveManagedBitcoindProbeDecision } from "./bitcoind-policy.js";
+async function waitForManagedBitcoindRuntime(options, dependencies) {
+    const deadline = Date.now() + options.startupTimeoutMs;
+    while (Date.now() < deadline) {
+        const attached = await dependencies.attachExisting(options).catch(() => null);
+        if (attached !== null) {
+            return attached;
+        }
+        await dependencies.sleep(250);
+    }
+    throw new Error("managed_bitcoind_service_start_timeout");
+}
+export async function probeManagedBitcoindRuntime(options, dependencies) {
+    const paths = dependencies.getPaths(options);
+    const candidates = await dependencies.listStatusCandidates({
+        dataDir: options.dataDir,
+        runtimeRoot: paths.runtimeRoot,
+        expectedStatusPath: paths.bitcoindStatusPath,
+    });
+    const expectedCandidate = candidates.find((candidate) => candidate.statusPath === paths.bitcoindStatusPath) ?? null;
+    for (const candidate of candidates) {
+        if (!await dependencies.isProcessAlive(candidate.status.processId)) {
+            continue;
+        }
+        return dependencies.probeStatusCandidate(candidate.status, options, paths.walletRuntimeRoot);
+    }
+    return {
+        compatibility: "unreachable",
+        status: expectedCandidate?.status ?? candidates[0]?.status ?? null,
+        error: null,
+    };
+}
+export async function attachOrStartManagedBitcoindRuntime(options, dependencies) {
+    const existingProbe = await probeManagedBitcoindRuntime(options, dependencies);
+    const existingDecision = resolveManagedBitcoindProbeDecision(existingProbe);
+    if (existingDecision.action === "attach") {
+        const existing = await dependencies.attachExisting(options);
+        if (existing !== null) {
+            return existing;
+        }
+        throw new Error("managed_bitcoind_protocol_error");
+    }
+    if (existingDecision.action === "reject") {
+        throw new Error(existingDecision.error ?? "managed_bitcoind_protocol_error");
+    }
+    const paths = dependencies.getPaths(options);
+    try {
+        const lock = await dependencies.acquireStartLock(options, paths);
+        try {
+            const liveProbe = await probeManagedBitcoindRuntime(options, dependencies);
+            const liveDecision = resolveManagedBitcoindProbeDecision(liveProbe);
+            if (liveDecision.action === "attach") {
+                const reattached = await dependencies.attachExisting(options);
+                if (reattached !== null) {
+                    return reattached;
+                }
+                throw new Error("managed_bitcoind_protocol_error");
+            }
+            if (liveDecision.action === "reject") {
+                throw new Error(liveDecision.error ?? "managed_bitcoind_protocol_error");
+            }
+            return await dependencies.startService(options, paths);
+        }
+        finally {
+            await lock.release();
+        }
+    }
+    catch (error) {
+        if (dependencies.isLockBusyError(error)) {
+            return waitForManagedBitcoindRuntime(options, dependencies);
+        }
+        throw error;
+    }
+}

package/dist/bitcoind/managed-runtime/bitcoind-status.d.ts

@@ -0,0 +1,11 @@
+import type { ManagedBitcoindObservedStatus } from "../types.js";
+import type { ManagedBitcoindStatusCandidate } from "./types.js";
+export declare function listManagedBitcoindStatusCandidates(options: {
+    dataDir: string;
+    runtimeRoot: string;
+    expectedStatusPath: string;
+}): Promise<ManagedBitcoindStatusCandidate[]>;
+export declare function readManagedBitcoindObservedStatus(options: {
+    dataDir: string;
+    walletRootId: string;
+}): Promise<ManagedBitcoindObservedStatus | null>;