@jinn-network/client 0.1.6 → 0.1.7-canary.0a586ca9

package/dist/preflight/rpc-network.js

@@ -1,5 +1,6 @@
-import { createPublicClient, http } from 'viem';
+import { createPublicClient, http, HttpRequestError } from 'viem';
 import { base, baseSepolia } from 'viem/chains';
+import { describeFallbackChain, maskRpcHost } from '../rpc/transport.js';
 export function expectedChainIdForNetwork(network) {
     return network === 'testnet' ? 84532 : 8453;
 }
@@ -118,4 +119,69 @@ export function rpcNetworkFailureHint(result) {
     }
     return 'Set rpcUrl to a Base mainnet endpoint such as https://mainnet.base.org, or set BASE_RPC_URL.';
 }
+function classifyProbeError(host, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof HttpRequestError && typeof err.status === 'number') {
+        return { ok: false, host, code: err.status, message };
+    }
+    // viem wraps HTTP errors inside other shapes; walk the cause chain.
+    let cur = err?.cause;
+    while (cur) {
+        if (cur instanceof HttpRequestError && typeof cur.status === 'number') {
+            return { ok: false, host, code: cur.status, message };
+        }
+        cur = cur.cause;
+    }
+    return { ok: false, host, reason: 'unreachable', message };
+}
+/**
+ * Probe each URL in a fallback chain with a per-slot `eth_blockNumber` call.
+ * Records ok/latency or a structured failure (HTTP status / unreachable).
+ *
+ * The probe is **log-only** — it never throws on per-slot failures. Startup
+ * gating remains the job of {@link checkRpcNetwork}, which fails loud on
+ * chain-id mismatch.
+ *
+ * Per AC9 (issue #592): emits one log line per slot
+ *   `[rpc] <layer> <host> ok latency=Nms`
+ *   `[rpc] <layer> <host> warn <http-status>`     (e.g. 429, 503)
+ *   `[rpc] <layer> <host> warn unreachable: <message>`
+ */
+export async function probeFallbackChain(urls, network, layer, options = {}) {
+    const log = options.log ?? ((m) => process.stderr.write(`${m}\n`));
+    // Chain is informational only — eth_blockNumber doesn't depend on chain
+    // identity. Both L1 and L2 layers reuse the same Base/Base-Sepolia pair
+    // since this is just used to satisfy viem's typing.
+    const chain = network === 'testnet' ? baseSepolia : base;
+    const results = [];
+    for (const url of urls) {
+        const host = maskRpcHost(url);
+        const client = createPublicClient({ chain, transport: http(url, { retryCount: 0 }) });
+        const t0 = performance.now();
+        try {
+            await client.getBlockNumber();
+            const latencyMs = Math.max(0, Math.round(performance.now() - t0));
+            log(`[rpc] ${layer} ${host} ok latency=${latencyMs}ms`);
+            results.push({ ok: true, host, latencyMs });
+        }
+        catch (err) {
+            const failure = classifyProbeError(host, err);
+            if (failure.code !== undefined) {
+                log(`[rpc] ${layer} ${host} warn ${failure.code}`);
+            }
+            else {
+                log(`[rpc] ${layer} ${host} warn unreachable: ${failure.message.split('\n')[0]}`);
+            }
+            results.push(failure);
+        }
+    }
+    return results;
+}
+/**
+ * Boot-log summary line for a fallback chain, formatted per AC7:
+ *   `[rpc] L2 transport: fallback chain (N providers) — primary=<host>`
+ */
+export function summarizeFallbackChain(layer, urls) {
+    return `[rpc] ${layer} transport: ${describeFallbackChain(urls)}`;
+}
 //# sourceMappingURL=rpc-network.js.map

package/dist/preflight/rpc-network.js.map

@@ -1 +1 @@
-{"version":3,"file":"rpc-network.js","sourceRoot":"","sources":["../../src/preflight/rpc-network.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"rpc-network.js","sourceRoot":"","sources":["../../src/preflight/rpc-network.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,MAAM,CAAC;AAClE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AA8BzE,MAAM,UAAU,yBAAyB,CAAC,OAA2B;IACnE,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AAEvD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC;QACnC,OAAO,CAAC,KAAK,WAAW,IAAI,CAAC,KAAK,WAAW,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,OAAO,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,6BAA6B,CAC3C,eAAuB,EACvB,aAAqB,EACrB,MAAc;IAEd,OAAO,CACL,aAAa,KAAK,eAAe;QACjC,uBAAuB,CAAC,GAAG,CAAC,aAAa,CAAC;QAC1C,gBAAgB,CAAC,MAAM,CAAC,CACzB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,CAAwB,EACxB,QAA6B,CAAC,CAAC,EAAE,EAAE;IACjC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACxD,CAAC;IAED,IAAI,CAAC,CAAC,CAAC,QAAQ;QAAE,OAAO;IACxB,KAAK,CACH,qBAAqB,CAAC,CAAC,OAAO,gBAAgB,CAAC,CAAC,aAAa,yBAAyB,CAAC,CAAC,OAAO,MAAM;QACnG,GAAG,CAAC,CAAC,eAAe,6DAA6D,CACpF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;QAC/B,OAAO,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,QAAQ,IAAI,gBAAgB,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,mBAAmB,CAAC;IAC7B,CAAC;AACH,CAAC;AAED,SAAS,uBAAuB,CAAC,OAA2B;IAC1D,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC;AACpD,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC;IACzE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAA8C;IAE9C,MAAM,eAAe,GAAG,yBAAyB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAClE,MAAM,OAAO,GAAG,iBAAiB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,kBAAkB,CAAC;QAChC,KAAK,EAAE,uBAAuB,CAAC,MAAM,CAAC,OAAO,CAAC;QAC9C,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;KAC/B,CAAC,CAAC;IAEH,IAAI,aAAqB,CAAC;IAC1B,IAAI,CAAC;QACH,aAAa,GAAG,MAAM,MAAM,CAAC,UAAU,EAAE,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,eAAe;YACf,OAAO;YACP,MAAM,EAAE,aAAa;YACrB,OAAO,EAAE,4BAA4B,MAAM,CAAC,OAAO,QAAQ,OAAO,KAAK,YAAY,CAAC,KAAK,CAAC,EAAE;SAC7F,CAAC;IACJ,CAAC;IAED,IAAI,aAAa,KAAK,eAAe,EAAE,CAAC;QACtC,IAAI,6BAA6B,CAAC,eAAe,EAAE,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YACjF,OAAO;gBACL,EAAE,EAAE,IAAI;gBACR,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,eAAe;gBACf,aAAa;gBACb,OAAO;gBACP,QAAQ,EAAE,IAAI;aACf,CAAC;QACJ,CAAC;QACD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,eAAe;YACf,aAAa;YACb,OAAO;YACP,MAAM,EAAE,gBAAgB;YACxB,OAAO,EACL,0BAA0B,MAAM,CAAC,OAAO,oBAAoB,eAAe,IAAI;gBAC/E,OAAO,aAAa,SAAS,OAAO,GAAG;SAC1C,CAAC;IACJ,CAAC;IAED,OAAO;QACL,EAAE,EAAE,IAAI;QACR,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,eAAe;QACf,aAAa;QACb,OAAO;KACR,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAA+B;IACnE,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,sGAAsG,CAAC;IAChH,CAAC;IACD,OAAO,8FAA8F,CAAC;AACxG,CAAC;AA8BD,SAAS,kBAAkB,CAAC,IAAY,EAAE,GAAY;IACpD,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,IAAI,GAAG,YAAY,gBAAgB,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QACtE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;IACxD,CAAC;IACD,oEAAoE;IACpE,IAAI,GAAG,GAAa,GAAuC,EAAE,KAAK,CAAC;IACnE,OAAO,GAAG,EAAE,CAAC;QACX,IAAI,GAAG,YAAY,gBAAgB,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YACtE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QACxD,CAAC;QACD,GAAG,GAAI,GAA2B,CAAC,KAAK,CAAC;IAC3C,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAuB,EACvB,OAA2B,EAC3B,KAAiB,EACjB,UAAqC,EAAE;IAEvC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3E,wEAAwE;IACxE,wEAAwE;IACxE,oDAAoD;IACpD,MAAM,KAAK,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC;IAEzD,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAC9B,MAAM,MAAM,GAAG,kBAAkB,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACtF,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,cAAc,EAAE,CAAC;YAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;YAClE,GAAG,CAAC,SAAS,KAAK,IAAI,IAAI,eAAe,SAAS,IAAI,CAAC,CAAC;YACxD,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QAC9C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,kBAAkB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC9C,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC/B,GAAG,CAAC,SAAS,KAAK,IAAI,IAAI,SAAS,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;YACrD,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,SAAS,KAAK,IAAI,IAAI,sBAAsB,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACpF,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAiB,EAAE,IAAuB;IAC/E,OAAO,SAAS,KAAK,eAAe,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAAC;AACpE,CAAC"}

package/dist/restart-daemon.d.ts

@@ -0,0 +1,90 @@
+/**
+ * In-process respawn helper for operator-triggered daemon restarts.
+ *
+ * Issue #289 added respawn-instead-of-exit so the operator panel survives a
+ * restart click. Issue #561 fixed the follow-on bug: the original respawn
+ * spawned the child *before* the parent had released its server sockets, so
+ * the child raced into `.listen(7332)` while the parent still held the port
+ * and died with EADDRINUSE / exitCode 11. The fix is `preSpawnCleanup` — an
+ * async hook the caller uses to close API + OTLP receivers before the child
+ * is spawned. With cleanup in place the port is free synchronously and the
+ * child binds on first try; without it (older callers, tests) the helper
+ * behaves as before.
+ *
+ * Every restart-required config change funnels through the same handler:
+ *
+ *   - POST /v1/setup/network              — RPC URL change
+ *   - POST /v1/setup/change-password      — keystore password rotation
+ *   - POST /v1/setup/solvernets/:name     — SolverNet enable/disable
+ *   - POST /v1/operator/join/:cid         — SolverNet join
+ *
+ * Headless gate: `JINN_NO_UI=1` (already the established headless flag in
+ * main.ts) skips the respawn — operators running `jinn run --no-ui` from a
+ * supervisor / systemd unit / docker entrypoint want the supervisor to
+ * decide whether to restart, not the daemon.
+ *
+ * The helper is split out from main.ts so it's unit-testable without
+ * touching the entry-point bootstrap path.
+ */
+import { spawn } from 'node:child_process';
+/**
+ * Options for `requestDaemonRestart`. All optional in production; the helper
+ * defaults to `process` / `node:child_process`. Tests inject doubles.
+ */
+export interface RequestDaemonRestartOptions {
+    /** Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Defaults to `process.argv` (`[node, scriptPath, ...args]`). */
+    argv?: readonly string[];
+    /** Defaults to `process.execPath` (the node binary). */
+    execPath?: string;
+    /**
+     * Defaults to `node:child_process.spawn`. Injected for tests so we can
+     * assert what was spawned without actually forking node.
+     */
+    spawnFn?: typeof spawn;
+    /** Defaults to `(code) => process.exit(code)`. Injected for tests. */
+    exitFn?: (code: number) => void;
+    /** Defaults to `console.log`. Injected for tests to capture output. */
+    log?: (message: string) => void;
+    /**
+     * Delay (ms) between spawning the child and exiting the parent. Gives the
+     * child a moment to bind the API port before the parent vacates it.
+     * Defaults to 250ms per the issue body. Tests can pass 0 for synchrony.
+     */
+    exitDelayMs?: number;
+    /**
+     * Bypass the headless gate. The operator-dashboard Restart button passes
+     * this — when the operator clicks Restart, they explicitly want the
+     * daemon to come back, even under a supervisor. Supervisor-driven
+     * restart flows (MCP tools, signals) leave this `false` so the
+     * supervisor stays in charge.
+     */
+    forceRespawn?: boolean;
+    /**
+     * Optional async hook run *before* the replacement child is spawned. The
+     * caller uses this to close listening sockets the child will need to
+     * bind — API server (7332) and OTLP receiver (4317/4318) — so the child
+     * doesn't lose an EADDRINUSE race with the parent. Errors are caught and
+     * logged; the respawn still proceeds because leaving the operator
+     * stranded is worse than a noisy close. Skipped in headless mode.
+     */
+    preSpawnCleanup?: () => Promise<void>;
+}
+/**
+ * Pure predicate: true when the current env is headless and respawn should
+ * be skipped. Exposed so callers and tests can share the same check.
+ */
+export declare function isHeadless(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Handle an operator-triggered restart request.
+ *
+ * - In **interactive** mode (default), spawn a detached child that re-runs
+ *   the current node invocation, then exit after a short delay so the child
+ *   can bind the API port.
+ * - In **headless** mode (`JINN_NO_UI=1`), exit without respawning. The
+ *   supervisor is responsible for relaunching the daemon if it wants to.
+ *
+ * Returns the action taken (for tests). Production callers ignore the return.
+ */
+export declare function requestDaemonRestart(opts?: RequestDaemonRestartOptions): Promise<'respawned' | 'headless-exit'>;

package/dist/restart-daemon.js

@@ -0,0 +1,95 @@
+/**
+ * In-process respawn helper for operator-triggered daemon restarts.
+ *
+ * Issue #289 added respawn-instead-of-exit so the operator panel survives a
+ * restart click. Issue #561 fixed the follow-on bug: the original respawn
+ * spawned the child *before* the parent had released its server sockets, so
+ * the child raced into `.listen(7332)` while the parent still held the port
+ * and died with EADDRINUSE / exitCode 11. The fix is `preSpawnCleanup` — an
+ * async hook the caller uses to close API + OTLP receivers before the child
+ * is spawned. With cleanup in place the port is free synchronously and the
+ * child binds on first try; without it (older callers, tests) the helper
+ * behaves as before.
+ *
+ * Every restart-required config change funnels through the same handler:
+ *
+ *   - POST /v1/setup/network              — RPC URL change
+ *   - POST /v1/setup/change-password      — keystore password rotation
+ *   - POST /v1/setup/solvernets/:name     — SolverNet enable/disable
+ *   - POST /v1/operator/join/:cid         — SolverNet join
+ *
+ * Headless gate: `JINN_NO_UI=1` (already the established headless flag in
+ * main.ts) skips the respawn — operators running `jinn run --no-ui` from a
+ * supervisor / systemd unit / docker entrypoint want the supervisor to
+ * decide whether to restart, not the daemon.
+ *
+ * The helper is split out from main.ts so it's unit-testable without
+ * touching the entry-point bootstrap path.
+ */
+import { spawn } from 'node:child_process';
+/**
+ * Pure predicate: true when the current env is headless and respawn should
+ * be skipped. Exposed so callers and tests can share the same check.
+ */
+export function isHeadless(env = process.env) {
+    return env['JINN_NO_UI'] === '1';
+}
+/**
+ * Handle an operator-triggered restart request.
+ *
+ * - In **interactive** mode (default), spawn a detached child that re-runs
+ *   the current node invocation, then exit after a short delay so the child
+ *   can bind the API port.
+ * - In **headless** mode (`JINN_NO_UI=1`), exit without respawning. The
+ *   supervisor is responsible for relaunching the daemon if it wants to.
+ *
+ * Returns the action taken (for tests). Production callers ignore the return.
+ */
+export async function requestDaemonRestart(opts = {}) {
+    const env = opts.env ?? process.env;
+    const argv = opts.argv ?? process.argv;
+    const execPath = opts.execPath ?? process.execPath;
+    const spawnFn = opts.spawnFn ?? spawn;
+    const exitFn = opts.exitFn ?? ((code) => process.exit(code));
+    const log = opts.log ?? ((message) => console.log(message));
+    const exitDelayMs = opts.exitDelayMs ?? 250;
+    if (isHeadless(env) && !opts.forceRespawn) {
+        log('[main] Restart requested via operator MCP, but JINN_NO_UI=1 — exiting without respawn (let the supervisor decide).');
+        exitFn(0);
+        return 'headless-exit';
+    }
+    log('[main] Restart requested via operator MCP. Spawning replacement and exiting...');
+    // jinn-mono #561: release server sockets BEFORE the child spawns. Without
+    // this, the child loses an EADDRINUSE race on 7332 (and OTLP 4317/4318)
+    // and dies with exitCode 11 before it can take over.
+    if (opts.preSpawnCleanup) {
+        try {
+            await opts.preSpawnCleanup();
+        }
+        catch (err) {
+            log(`[main] preSpawnCleanup error (proceeding with respawn anyway): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // argv[0] is the node binary; argv[1..] are the script + flags. The child
+    // re-runs the same script with the same flags, under the same node binary.
+    const childArgs = argv.slice(1);
+    const spawnOptions = {
+        detached: true,
+        stdio: 'inherit',
+        env,
+    };
+    const child = spawnFn(execPath, childArgs, spawnOptions);
+    // Detach so the parent can exit without taking the child with it.
+    child.unref();
+    // With preSpawnCleanup the port is already free; the small delay is kept
+    // as a paranoid belt-and-suspenders against any kernel-level lingering on
+    // SO_LINGER-disabled sockets. Tests pass 0.
+    if (exitDelayMs <= 0) {
+        exitFn(0);
+    }
+    else {
+        setTimeout(() => exitFn(0), exitDelayMs);
+    }
+    return 'respawned';
+}
+//# sourceMappingURL=restart-daemon.js.map

package/dist/restart-daemon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restart-daemon.js","sourceRoot":"","sources":["../src/restart-daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,KAAK,EAAqB,MAAM,oBAAoB,CAAC;AA+C9D;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,OAAO,GAAG,CAAC,YAAY,CAAC,KAAK,GAAG,CAAC;AACnC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAoC,EAAE;IAEtC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;IACnD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC;IACtC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACrE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IACpE,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,GAAG,CAAC;IAE5C,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;QAC1C,GAAG,CACD,oHAAoH,CACrH,CAAC;QACF,MAAM,CAAC,CAAC,CAAC,CAAC;QACV,OAAO,eAAe,CAAC;IACzB,CAAC;IAED,GAAG,CAAC,gFAAgF,CAAC,CAAC;IAEtF,0EAA0E;IAC1E,wEAAwE;IACxE,qDAAqD;IACrD,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,eAAe,EAAE,CAAC;QAC/B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CACD,kEACE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,EAAE,CACH,CAAC;QACJ,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,2EAA2E;IAC3E,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAChC,MAAM,YAAY,GAAiB;QACjC,QAAQ,EAAE,IAAI;QACd,KAAK,EAAE,SAAS;QAChB,GAAG;KACJ,CAAC;IACF,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;IACzD,kEAAkE;IAClE,KAAK,CAAC,KAAK,EAAE,CAAC;IAEd,yEAAyE;IACzE,0EAA0E;IAC1E,4CAA4C;IAC5C,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;QACrB,MAAM,CAAC,CAAC,CAAC,CAAC;IACZ,CAAC;SAAM,CAAC;QACN,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/rpc/transport.d.ts

@@ -0,0 +1,109 @@
+/**
+ * RPC transport helper — builds a viem `fallback()` transport from a single
+ * URL, an array of URLs, or a comma-separated string. The substrate for issue
+ * #592 (multi-RPC fallback chain across daemon / relayer / indexer / CI).
+ *
+ * Design:
+ * - `parseRpcUrls` normalises `string | readonly string[]` to a deduplicated
+ *   non-empty array, splits comma-strings, trims, drops empties, and caps the
+ *   chain at {@link MAX_RPC_CHAIN_LENGTH} providers (extras are dropped with a
+ *   warning). Throws when no URLs remain.
+ * - `buildFallbackTransport` wraps `http(url)` per slot inside viem's
+ *   `fallback([...], { rank: false, retryCount: 0 })`. `rank: false` is
+ *   explicit — the issue's "Tenderly stays in slot 3" constraint requires
+ *   order preservation (no latency-based reshuffling). `retryCount: 0` keeps
+ *   the helper from doubling retries on top of the existing
+ *   `withRecoverableRetry` wrapper used by callers like the mech adapter.
+ * - On exhausted fall-through the helper rejects with `AllRpcsFailedError`,
+ *   which carries a structured `providers: readonly string[]` list of masked
+ *   hosts so callers and tests can assert on it.
+ * - `describeFallbackChain` formats the canonical AC7 boot-log summary line:
+ *   `fallback chain (N providers) — primary=<host>`.
+ *
+ * Do not conflate with `discovery.fallbackToOnchain` — that's a separate layer
+ * at the read-API level (Ponder → eth_getLogs floor). This helper sits beneath
+ * both layers at the JSON-RPC transport level.
+ */
+import { type FallbackTransport, type Transport } from 'viem';
+/**
+ * Hard cap on the number of providers in a single fallback chain. Four covers
+ * the "operator paid primary + public publicnode + public sepolia.base.org +
+ * Tenderly slot-3" shape from the issue; beyond that the boot probe takes too
+ * long and slot 5+ is almost always copy-paste noise.
+ */
+export declare const MAX_RPC_CHAIN_LENGTH = 4;
+export interface ParseRpcUrlsOptions {
+    /** Logger used to emit the "capped" warning. Defaults to `console.error`. */
+    log?: (message: string) => void;
+}
+/**
+ * Normalise `string | readonly string[]` into a non-empty, deduplicated,
+ * capped list of RPC URLs. Comma-separated strings are split (operator
+ * convention, see `peers` in `config.ts`). Duplicates are removed before the
+ * cap is applied so the effective chain length matches operator intent (an
+ * operator who prepends their paid primary to the existing fallback list
+ * shouldn't burn a slot on the duplicate).
+ *
+ * @throws if the input yields zero non-empty URLs.
+ */
+export declare function parseRpcUrls(input: string | readonly string[], options?: ParseRpcUrlsOptions): string[];
+/**
+ * Error thrown when every provider in a fallback chain has failed. Carries
+ * the masked host list so callers can surface a useful operator-facing message
+ * without leaking secret query strings (api-key paths).
+ */
+export declare class AllRpcsFailedError extends Error {
+    readonly providers: readonly string[];
+    readonly cause?: unknown;
+    constructor(providers: readonly string[], cause?: unknown);
+}
+/**
+ * Detect errors that viem's `fallback()` short-circuits on (via its
+ * `shouldThrow(err)` fast-exit) — `ExecutionRevertedError`,
+ * `TransactionRejectedRpcError`, `UserRejectedRequestError`,
+ * `WalletConnectSessionSettlementError`, and CAIP user-rejected (code
+ * `5000`). These are EVM- or wallet-level signals, NOT transport-level
+ * failures, so they must propagate unchanged. Wrapping them as
+ * `AllRpcsFailedError` would give the operator-app a false-positive
+ * "all RPCs failed" message when the actual problem is e.g. a contract
+ * revert on a view function.
+ *
+ * Mirrors viem's own predicate at
+ * `node_modules/viem/clients/transports/fallback.ts` (`shouldThrow`),
+ * dispatching by **numeric JSON-RPC code** (the path that catches real
+ * `RpcRequestError` instances coming out of the HTTP transport) plus the
+ * `ExecutionRevertedError.nodeMessage` regex (the path that catches reverts
+ * surfaced as plain `Error` with no numeric code). The cause-chain walk by
+ * class `name` remains as a third path for wallet-provider stacks that
+ * deliver proper class instances (and for already-normalised errors after
+ * viem's `buildRequest` re-wrap pass).
+ */
+export declare function isViemShouldThrowError(err: unknown): boolean;
+/**
+ * Mask an RPC URL down to its hostname for display / error reporting. Drops
+ * the path so api-key segments in the URL don't leak into logs.
+ */
+export declare function maskRpcHost(url: string): string;
+export interface BuildFallbackTransportOptions {
+    /**
+     * Set to `true` to let viem rank providers by latency. Default `false` —
+     * order matters for operator-configured paid primaries and the
+     * "Tenderly stays in slot 3" constraint from the issue.
+     */
+    rank?: boolean;
+}
+/**
+ * Build a viem fallback transport over the given URLs. Returns a callable
+ * transport suitable for `createPublicClient({ transport })`.
+ *
+ * Errors that exhaust the chain are wrapped in `AllRpcsFailedError`.
+ */
+export declare function buildFallbackTransport(urls: readonly string[], options?: BuildFallbackTransportOptions): FallbackTransport;
+export declare namespace buildFallbackTransport {
+    var buildFromTransports: (transports: readonly Transport[], urls: readonly string[], options?: BuildFallbackTransportOptions) => FallbackTransport;
+}
+/**
+ * Boot-log summary line for a fallback chain. Matches the canonical AC7
+ * format: `fallback chain (N providers) — primary=<host>`.
+ */
+export declare function describeFallbackChain(urls: readonly string[]): string;

package/dist/rpc/transport.js

@@ -0,0 +1,220 @@
+/**
+ * RPC transport helper — builds a viem `fallback()` transport from a single
+ * URL, an array of URLs, or a comma-separated string. The substrate for issue
+ * #592 (multi-RPC fallback chain across daemon / relayer / indexer / CI).
+ *
+ * Design:
+ * - `parseRpcUrls` normalises `string | readonly string[]` to a deduplicated
+ *   non-empty array, splits comma-strings, trims, drops empties, and caps the
+ *   chain at {@link MAX_RPC_CHAIN_LENGTH} providers (extras are dropped with a
+ *   warning). Throws when no URLs remain.
+ * - `buildFallbackTransport` wraps `http(url)` per slot inside viem's
+ *   `fallback([...], { rank: false, retryCount: 0 })`. `rank: false` is
+ *   explicit — the issue's "Tenderly stays in slot 3" constraint requires
+ *   order preservation (no latency-based reshuffling). `retryCount: 0` keeps
+ *   the helper from doubling retries on top of the existing
+ *   `withRecoverableRetry` wrapper used by callers like the mech adapter.
+ * - On exhausted fall-through the helper rejects with `AllRpcsFailedError`,
+ *   which carries a structured `providers: readonly string[]` list of masked
+ *   hosts so callers and tests can assert on it.
+ * - `describeFallbackChain` formats the canonical AC7 boot-log summary line:
+ *   `fallback chain (N providers) — primary=<host>`.
+ *
+ * Do not conflate with `discovery.fallbackToOnchain` — that's a separate layer
+ * at the read-API level (Ponder → eth_getLogs floor). This helper sits beneath
+ * both layers at the JSON-RPC transport level.
+ */
+import { ExecutionRevertedError, fallback, http, TransactionRejectedRpcError, UserRejectedRequestError, } from 'viem';
+/**
+ * Hard cap on the number of providers in a single fallback chain. Four covers
+ * the "operator paid primary + public publicnode + public sepolia.base.org +
+ * Tenderly slot-3" shape from the issue; beyond that the boot probe takes too
+ * long and slot 5+ is almost always copy-paste noise.
+ */
+export const MAX_RPC_CHAIN_LENGTH = 4;
+/**
+ * Normalise `string | readonly string[]` into a non-empty, deduplicated,
+ * capped list of RPC URLs. Comma-separated strings are split (operator
+ * convention, see `peers` in `config.ts`). Duplicates are removed before the
+ * cap is applied so the effective chain length matches operator intent (an
+ * operator who prepends their paid primary to the existing fallback list
+ * shouldn't burn a slot on the duplicate).
+ *
+ * @throws if the input yields zero non-empty URLs.
+ */
+export function parseRpcUrls(input, options = {}) {
+    const log = options.log ?? ((m) => process.stderr.write(`${m}\n`));
+    const raw = typeof input === 'string' ? input.split(',') : [...input];
+    const cleaned = raw.map((u) => u.trim()).filter((u) => u.length > 0);
+    if (cleaned.length === 0) {
+        throw new Error('parseRpcUrls: at least one RPC URL is required');
+    }
+    // Dedup before applying the cap so repeated URLs (easy to introduce when an
+    // operator prepends a paid primary that already exists in the fallback list)
+    // don't burn slots of the 4-slot chain. `Set` preserves first-seen insertion
+    // order, which matches the "primary stays in slot 0" constraint.
+    const deduped = [...new Set(cleaned)];
+    if (deduped.length > MAX_RPC_CHAIN_LENGTH) {
+        log(`[rpc] capped fallback chain to ${MAX_RPC_CHAIN_LENGTH} providers ` +
+            `(dropped ${deduped.length - MAX_RPC_CHAIN_LENGTH} extra slots)`);
+        return deduped.slice(0, MAX_RPC_CHAIN_LENGTH);
+    }
+    return deduped;
+}
+/**
+ * Error thrown when every provider in a fallback chain has failed. Carries
+ * the masked host list so callers can surface a useful operator-facing message
+ * without leaking secret query strings (api-key paths).
+ */
+export class AllRpcsFailedError extends Error {
+    providers;
+    cause;
+    constructor(providers, cause) {
+        super(`All RPC providers in the fallback chain failed (providers=${providers.join(', ')})`);
+        this.name = 'AllRpcsFailedError';
+        this.providers = providers;
+        this.cause = cause;
+    }
+}
+/**
+ * Detect errors that viem's `fallback()` short-circuits on (via its
+ * `shouldThrow(err)` fast-exit) — `ExecutionRevertedError`,
+ * `TransactionRejectedRpcError`, `UserRejectedRequestError`,
+ * `WalletConnectSessionSettlementError`, and CAIP user-rejected (code
+ * `5000`). These are EVM- or wallet-level signals, NOT transport-level
+ * failures, so they must propagate unchanged. Wrapping them as
+ * `AllRpcsFailedError` would give the operator-app a false-positive
+ * "all RPCs failed" message when the actual problem is e.g. a contract
+ * revert on a view function.
+ *
+ * Mirrors viem's own predicate at
+ * `node_modules/viem/clients/transports/fallback.ts` (`shouldThrow`),
+ * dispatching by **numeric JSON-RPC code** (the path that catches real
+ * `RpcRequestError` instances coming out of the HTTP transport) plus the
+ * `ExecutionRevertedError.nodeMessage` regex (the path that catches reverts
+ * surfaced as plain `Error` with no numeric code). The cause-chain walk by
+ * class `name` remains as a third path for wallet-provider stacks that
+ * deliver proper class instances (and for already-normalised errors after
+ * viem's `buildRequest` re-wrap pass).
+ */
+export function isViemShouldThrowError(err) {
+    // 1. Code-based dispatch — matches what viem's own `shouldThrow` does,
+    //    so a raw `RpcRequestError { code: 3 | -32003 | 4001 | 7000 | 5000 }`
+    //    from the HTTP transport is caught here regardless of class name.
+    //    Codes are pulled from the viem error classes (no magic numbers) where
+    //    available; 7000 and 5000 are inline because
+    //    `WalletConnectSessionSettlementError` is not re-exported from the
+    //    top-level `viem` package and 5000 is the CAIP user-rejected code
+    //    viem hard-codes alongside it.
+    if (err instanceof Error && 'code' in err && typeof err.code === 'number') {
+        const code = err.code;
+        if (code === ExecutionRevertedError.code || // 3 — contract revert
+            code === TransactionRejectedRpcError.code || // -32003 — tx rejected
+            code === UserRejectedRequestError.code || // 4001 — user-rejected
+            code === 7000 || // WalletConnectSessionSettlementError
+            code === 5000 // CAIP user-rejected
+        )
+            return true;
+        // 2. nodeMessage regex — catches reverts that arrive as a plain `Error`
+        //    (no numeric code, no recognised class name). Viem's own
+        //    `shouldThrow` runs this check too.
+        if (ExecutionRevertedError.nodeMessage.test(err.message))
+            return true;
+    }
+    // 3. Cause-chain walk — viem wraps low-level RPC errors in higher-level
+    //    error classes (e.g. `ContractFunctionExecutionError` →
+    //    `RpcRequestError` → `ExecutionRevertedError`), and wallet providers
+    //    can deliver proper class instances directly. Walk with cycle
+    //    detection so a self-referential `.cause` cannot infinite-loop.
+    const seen = new Set();
+    let cursor = err;
+    while (cursor instanceof Error && !seen.has(cursor)) {
+        seen.add(cursor);
+        if (cursor.name === 'ExecutionRevertedError')
+            return true;
+        if (cursor.name === 'TransactionRejectedRpcError')
+            return true;
+        if (cursor.name === 'UserRejectedRequestError')
+            return true;
+        if (cursor.name === 'WalletConnectSessionSettlementError')
+            return true;
+        cursor = cursor.cause;
+    }
+    return false;
+}
+/**
+ * Mask an RPC URL down to its hostname for display / error reporting. Drops
+ * the path so api-key segments in the URL don't leak into logs.
+ */
+export function maskRpcHost(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.hostname || '(unknown host)';
+    }
+    catch {
+        return '(invalid rpc url)';
+    }
+}
+/**
+ * Build a viem fallback transport over the given URLs. Returns a callable
+ * transport suitable for `createPublicClient({ transport })`.
+ *
+ * Errors that exhaust the chain are wrapped in `AllRpcsFailedError`.
+ */
+export function buildFallbackTransport(urls, options = {}) {
+    const transports = urls.map((url) => http(url));
+    return buildFallbackTransport.buildFromTransports(transports, urls, options);
+}
+/**
+ * Internal helper exposed for tests: build a fallback transport from
+ * pre-constructed viem transports (e.g. `custom()` mocks) so tests can drive
+ * each slot deterministically without an actual HTTP fetch.
+ */
+buildFallbackTransport.buildFromTransports = function buildFromTransports(transports, urls, options = {}) {
+    const maskedProviders = urls.map(maskRpcHost);
+    const inner = fallback(transports, {
+        rank: options.rank ?? false,
+        retryCount: 0,
+    });
+    // Wrap the transport so that the final exhausted-chain rejection surfaces
+    // as our structured `AllRpcsFailedError` (carrying the masked host list).
+    // We do the wrap at the transport-factory level rather than swapping the
+    // returned function's `request` so the FallbackTransport's typed shape
+    // (`onResponse`, `transports`, etc.) is preserved.
+    const wrapped = ((config) => {
+        const t = inner(config);
+        const originalRequest = t.request.bind(t);
+        t.request = (async (args) => {
+            try {
+                return await originalRequest(args);
+            }
+            catch (err) {
+                // viem's fallback() short-circuits on shouldThrow-class errors
+                // (contract revert, user-rejected, CAIP 5000) — those are
+                // EVM/wallet-level, not transport-level failures. Propagate them
+                // unchanged so callers (and the operator-app's `rpc_all_failed`
+                // state message) don't misread a single-slot revert as an
+                // exhausted-chain outage.
+                if (isViemShouldThrowError(err))
+                    throw err;
+                // Otherwise: viem doesn't expose a distinct "all transports failed"
+                // error class — when fallback exhausts the chain it throws the last
+                // underlying error. Wrap so the caller gets a stable structural
+                // error carrying the masked provider list.
+                throw new AllRpcsFailedError(maskedProviders, err);
+            }
+        });
+        return t;
+    });
+    return wrapped;
+};
+/**
+ * Boot-log summary line for a fallback chain. Matches the canonical AC7
+ * format: `fallback chain (N providers) — primary=<host>`.
+ */
+export function describeFallbackChain(urls) {
+    if (urls.length === 0)
+        return 'fallback chain (0 providers)';
+    return `fallback chain (${urls.length} providers) — primary=${maskRpcHost(urls[0])}`;
+}
+//# sourceMappingURL=transport.js.map

package/dist/rpc/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/rpc/transport.ts"],"names":[],"mappings":"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"}