@jinn-network/client 0.1.8 → 0.1.9-canary.023faefb

package/dist/preflight/deployment-readiness.js

@@ -0,0 +1,308 @@
+/**
+ * Deployment-readiness preflight (issue #958).
+ *
+ * Hosted deploys have no boot-time guard that the environment is fit to run;
+ * misconfig fails silently or mid-run. This module adds a set of checks that
+ * answer "is this environment fit to run the daemon?" and a boot gate that
+ * **fails loud — but only in a deployment context**.
+ *
+ * Load-bearing constraint: a plain local `jinn run` (no `JINN_STATE_DIR`,
+ * running as the user) must NEVER be newly gated. The
+ * fail-loud boot gate fires only when `isDeploymentContext()` is true; outside
+ * that, every check is advisory (surfaced in `doctor`, never boot-fatal). The
+ * `doctor` command runs all checks regardless of context.
+ *
+ * The checks compose existing primitives where possible:
+ *   - `writable_volume`        — the one genuinely new primitive (write+fsync+unlink probe)
+ *   - `state_on_volume`        — assert resolved state lives on the configured volume
+ *   - `credentials_resolvable` — reuses `detectAuthContext`; presence-only, NEVER echoes secrets
+ *   - `agent_cli_non_root`     — uid 0 is unfit (the agent CLI refuses to run as root)
+ *
+ * Every check is side-effect-light and NEVER throws — a failure becomes a
+ * structured fail result, not an exception. The aggregate is the safe caller
+ * surface; the gate adds the fail-loud envelope on top.
+ */
+import { promises as fs } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { emitEnvelope } from '../errors/envelope.js';
+import { emitStructured } from '../events/emitter.js';
+/** Hard checks — failing one of these in a deployment context refuses the boot. */
+const HARD_CHECK_NAMES = new Set([
+    'writable_volume',
+    'state_on_volume',
+    'agent_cli_non_root',
+]);
+// ---------------------------------------------------------------------------
+// isDeploymentContext
+// ---------------------------------------------------------------------------
+/**
+ * Deployment context = `JINN_STATE_DIR` set OR `config.stateDir` set OR the
+ * auth context is a container / docker-compose. A plain local operator (bare
+ * context, no state-dir) is NOT a deployment context, so the boot gate stays
+ * disarmed for them.
+ */
+export function isDeploymentContext(input) {
+    if (typeof input.env['JINN_STATE_DIR'] === 'string' && input.env['JINN_STATE_DIR'].length > 0) {
+        return true;
+    }
+    if (typeof input.stateDir === 'string' && input.stateDir.length > 0)
+        return true;
+    return input.authContext === 'container' || input.authContext === 'docker-compose';
+}
+// ---------------------------------------------------------------------------
+// writable_volume — the new primitive
+// ---------------------------------------------------------------------------
+/**
+ * Attempt to write + fsync + unlink a temp file under `dir`. ok when it
+ * succeeds; structured fail (never throws) on EACCES / EROFS / ENOSPC / missing
+ * dir / any other fs error.
+ */
+export async function checkWritableVolume(dir) {
+    const probePath = join(dir, `.jinn-writeprobe-${process.pid}-${randomBytes(4).toString('hex')}`);
+    let handle;
+    try {
+        handle = await fs.open(probePath, 'w', 0o600);
+        await handle.write('jinn-writable-volume-probe');
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await fs.unlink(probePath);
+        return {
+            name: 'writable_volume',
+            ok: true,
+            detail: `${dir} is writable`,
+        };
+    }
+    catch (err) {
+        // Best-effort cleanup; ignore whatever it throws.
+        if (handle)
+            await handle.close().catch(() => undefined);
+        await fs.unlink(probePath).catch(() => undefined);
+        const code = err.code;
+        return {
+            name: 'writable_volume',
+            ok: false,
+            detail: `${dir} is not writable${code ? ` (${code})` : ''}`,
+            remedy: 'Ensure the daemon process can write to the state directory. In hosted deploys, mount a writable ' +
+                'persistent volume at the path pointed to by JINN_STATE_DIR (or earningDir) and give the daemon user write access.',
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// state_on_volume
+// ---------------------------------------------------------------------------
+/**
+ * In a deployment context, assert resolved state lives on the configured
+ * volume — i.e. `stateDir` is set AND `earningDir` resolves under it. Advisory
+ * (always ok) outside a deployment context.
+ */
+export function checkStateOnVolume(input) {
+    if (!input.deployment) {
+        return {
+            name: 'state_on_volume',
+            ok: true,
+            detail: 'not a deployment context — state location is advisory only',
+        };
+    }
+    if (!input.stateDir) {
+        return {
+            name: 'state_on_volume',
+            ok: false,
+            detail: 'deployment context but JINN_STATE_DIR / stateDir is unset — state would land on the ephemeral ~/.jinn-client default and be lost on redeploy',
+            remedy: 'Set JINN_STATE_DIR to the mounted persistent volume (e.g. JINN_STATE_DIR=/data).',
+        };
+    }
+    const root = resolve(input.stateDir);
+    const earning = resolve(input.earningDir);
+    const under = earning === root || earning.startsWith(root + '/');
+    if (!under) {
+        return {
+            name: 'state_on_volume',
+            ok: false,
+            detail: `earningDir (${earning}) does not resolve under the configured volume (${root})`,
+            remedy: 'Remove the per-key earningDir/dbPath override so state derives under JINN_STATE_DIR, or point them at the volume.',
+        };
+    }
+    return {
+        name: 'state_on_volume',
+        ok: true,
+        detail: `state resolves under the configured volume ${root}`,
+    };
+}
+// ---------------------------------------------------------------------------
+// credentials_resolvable
+// ---------------------------------------------------------------------------
+/**
+ * Presence-only credential check. In a bare context the operator authenticates
+ * the agent CLI interactively (claude session auth), so credentials are not
+ * env-resolvable and that is fine. In a container / compose context there is no
+ * interactive login, so SOME agent-CLI auth signal must be present in the env.
+ *
+ * NEVER returns or logs a secret value — only presence + context.
+ */
+export function checkCredentialsResolvable(input) {
+    // Env vars that, if present and non-empty, indicate the agent CLI can resolve
+    // credentials non-interactively. Presence only — values are never read out.
+    const AUTH_ENV_KEYS = [
+        'ANTHROPIC_API_KEY',
+        'CLAUDE_CODE_OAUTH_TOKEN',
+        'OPENROUTER_API_KEY',
+        'OPENAI_API_KEY',
+    ];
+    const present = AUTH_ENV_KEYS.filter((k) => {
+        const v = input.env[k];
+        return typeof v === 'string' && v.trim().length > 0;
+    });
+    if (input.context === 'bare') {
+        return {
+            name: 'credentials_resolvable',
+            ok: true,
+            detail: present.length > 0
+                ? `bare context; agent-CLI auth env present (${present.length} key(s))`
+                : 'bare context; agent CLI uses interactive session auth',
+        };
+    }
+    // container / docker-compose: no interactive login path — need an env signal.
+    if (present.length > 0) {
+        return {
+            name: 'credentials_resolvable',
+            ok: true,
+            detail: `${input.context} context; agent-CLI auth env present (${present.length} key(s))`,
+        };
+    }
+    return {
+        name: 'credentials_resolvable',
+        ok: false,
+        detail: `${input.context} context but no agent-CLI auth credential is resolvable from the environment`,
+        remedy: 'Provide the agent CLI credentials the harness needs (e.g. ANTHROPIC_API_KEY / CLAUDE_CODE_OAUTH_TOKEN, ' +
+            'or OPENROUTER_API_KEY for the hermes harness) as a secret in the deploy environment.',
+    };
+}
+// ---------------------------------------------------------------------------
+// agent_cli_non_root
+// ---------------------------------------------------------------------------
+/**
+ * ok when uid !== 0 (or no getuid on the platform). Fail when running as root —
+ * the agent CLI refuses to run as root, so a root daemon is unfit. Never throws.
+ */
+export function checkAgentCliNonRoot(getuid) {
+    if (typeof getuid !== 'function') {
+        return {
+            name: 'agent_cli_non_root',
+            ok: true,
+            detail: 'platform has no uid concept — non-root assumption holds',
+        };
+    }
+    let uid;
+    try {
+        uid = getuid();
+    }
+    catch {
+        // Can't determine uid: don't crash, treat as non-fatal (conservative ok —
+        // we'd rather not falsely gate a boot on an unreadable uid).
+        return {
+            name: 'agent_cli_non_root',
+            ok: true,
+            detail: 'could not read process uid — assuming non-root',
+        };
+    }
+    if (uid === 0) {
+        return {
+            name: 'agent_cli_non_root',
+            ok: false,
+            detail: 'daemon is running as root (uid 0); the agent CLI refuses to run as root',
+            remedy: 'Run the daemon as a non-root user. In containers, create and drop to a non-root user (e.g. via gosu) before launching.',
+        };
+    }
+    return {
+        name: 'agent_cli_non_root',
+        ok: true,
+        detail: `running as non-root (uid ${uid})`,
+    };
+}
+// ---------------------------------------------------------------------------
+// runDeploymentReadinessChecks — the aggregate
+// ---------------------------------------------------------------------------
+/**
+ * Run every deployment-readiness check and assemble a report. Detects the
+ * deployment context internally and decides `bootFatal` accordingly. Never
+ * throws — each check degrades to a structured fail.
+ */
+export async function runDeploymentReadinessChecks(inputs, deps) {
+    const authContext = (() => {
+        try {
+            return deps.detectAuthContext({
+                cwd: process.cwd(),
+                env: deps.env,
+                configuredMode: inputs.runtimeMode,
+            });
+        }
+        catch {
+            return 'bare';
+        }
+    })();
+    const deployment = isDeploymentContext({
+        env: deps.env,
+        authContext,
+        stateDir: inputs.stateDir,
+    });
+    // The writable-volume probe targets the volume root when set, else earningDir.
+    const probeDir = inputs.stateDir ?? inputs.earningDir;
+    const checks = [
+        await checkWritableVolume(probeDir),
+        checkStateOnVolume({ deployment, stateDir: inputs.stateDir, earningDir: inputs.earningDir }),
+        checkCredentialsResolvable({ context: authContext, env: deps.env }),
+        checkAgentCliNonRoot(deps.getuid),
+    ];
+    const bootFatal = deployment && checks.some((c) => !c.ok && HARD_CHECK_NAMES.has(c.name));
+    return { deployment, authContext, checks, bootFatal };
+}
+// ---------------------------------------------------------------------------
+// applyDeploymentReadinessGate — the boot gate (fail-loud only in deployment)
+// ---------------------------------------------------------------------------
+/**
+ * Boot gate for `jinn run`. Runs the readiness aggregate; in a deployment
+ * context, fail loud (emit `invalid_invocation` envelope + non-zero exit) when
+ * a hard check fails. Outside a deployment context, log advisories for any
+ * failing check and proceed. Mirrors `applyPidfileLivenessGate`'s contract:
+ * `emitEnvelope` does not return in production (it `process.exit`s).
+ */
+export async function applyDeploymentReadinessGate(inputs, deps, sinks = {}) {
+    const report = await runDeploymentReadinessChecks(inputs, deps);
+    const failed = report.checks.filter((c) => !c.ok);
+    if (report.bootFatal) {
+        const hardFailures = failed.filter((c) => HARD_CHECK_NAMES.has(c.name));
+        const summary = hardFailures.map((c) => `${c.name}: ${c.detail}`).join('; ');
+        emitEnvelope({
+            code: 'invalid_invocation',
+            message: `Environment is not fit to run the daemon in this deployment — ${summary}`,
+            hint: 'Run `jinn doctor --human` for the full readiness report. Fix the failing check(s) and restart.',
+            exampleCli: 'jinn doctor --human',
+            details: {
+                field: 'deployment_readiness',
+                authContext: report.authContext,
+                // Names + ok only — no secret material, no raw env values.
+                failed: hardFailures.map((c) => ({ name: c.name, detail: c.detail })),
+            },
+        }, sinks);
+        // emitEnvelope calls process.exit in production; in tests the injected exit
+        // is a no-op. Either way, do not fall through to "proceed" logging.
+        return;
+    }
+    // Advisory path (local operator, or non-hard failures in a deployment ctx):
+    // surface each failing check but never gate the boot.
+    for (const c of failed) {
+        emitStructured({
+            kind: 'system',
+            message: `deployment-readiness advisory — ${c.name}: ${c.detail}`,
+            details: {
+                phase: 'preflight',
+                check: c.name,
+                deployment: report.deployment,
+                ...(c.remedy ? { remedy: c.remedy } : {}),
+            },
+        });
+    }
+}
+//# sourceMappingURL=deployment-readiness.js.map

package/dist/preflight/deployment-readiness.js.map

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

package/dist/preflight/pidfile-liveness.d.ts

@@ -6,11 +6,17 @@
  * Branches (load-bearing — see #649 acceptance criteria):
  *   - File missing               → { decision: 'proceed' }
  *   - File malformed (NaN/empty) → { decision: 'unlink-stale', reason: 'malformed' }
+ *   - PID 1 or our own pid       → { decision: 'unlink-stale', reason: 'self-or-pid1-container' }
  *   - process.kill(pid, 0) ESRCH → { decision: 'unlink-stale', reason: 'esrch' }
  *   - process.kill(pid, 0) ok    → { decision: 'refuse', reason: 'alive' }
  *   - process.kill(pid, 0) EPERM → { decision: 'refuse', reason: 'eperm' }
  *   - any other errno            → { decision: 'refuse', reason: 'unknown' }
  *
+ * The PID-1/self branch classifies *before* the `process.kill` probe (#805): in
+ * a container the daemon is PID 1, whose pidfile outlives the container on the
+ * persistent volume; `process.kill(1, 0)` always succeeds, so a probe-first
+ * order would mis-classify the stale record as a live sibling and crash-loop.
+ *
  * `.trim()` before `parseInt` is required: `main.ts` writes the PID with a
  * trailing `\n` (see `client/src/main.ts` writeFileSync near the pidfile site).
  */
@@ -21,7 +27,7 @@ export type PidfileLivenessDecision = {
     decision: 'unlink-stale';
     pid: number | null;
     pidfilePath: string;
-    reason: 'malformed' | 'esrch';
+    reason: 'malformed' | 'esrch' | 'self-or-pid1-container';
 } | {
     decision: 'refuse';
     pid: number;

package/dist/preflight/pidfile-liveness.js

@@ -6,11 +6,17 @@
  * Branches (load-bearing — see #649 acceptance criteria):
  *   - File missing               → { decision: 'proceed' }
  *   - File malformed (NaN/empty) → { decision: 'unlink-stale', reason: 'malformed' }
+ *   - PID 1 or our own pid       → { decision: 'unlink-stale', reason: 'self-or-pid1-container' }
  *   - process.kill(pid, 0) ESRCH → { decision: 'unlink-stale', reason: 'esrch' }
  *   - process.kill(pid, 0) ok    → { decision: 'refuse', reason: 'alive' }
  *   - process.kill(pid, 0) EPERM → { decision: 'refuse', reason: 'eperm' }
  *   - any other errno            → { decision: 'refuse', reason: 'unknown' }
  *
+ * The PID-1/self branch classifies *before* the `process.kill` probe (#805): in
+ * a container the daemon is PID 1, whose pidfile outlives the container on the
+ * persistent volume; `process.kill(1, 0)` always succeeds, so a probe-first
+ * order would mis-classify the stale record as a live sibling and crash-loop.
+ *
  * `.trim()` before `parseInt` is required: `main.ts` writes the PID with a
  * trailing `\n` (see `client/src/main.ts` writeFileSync near the pidfile site).
  */
@@ -35,6 +41,14 @@ export function checkPidfileLiveness(input) {
     if (!Number.isFinite(parsed) || parsed <= 0) {
         return { decision: 'unlink-stale', pid: null, pidfilePath: pidPath, reason: 'malformed' };
     }
+    // #805: in a container the daemon is PID 1; the pidfile on the persistent
+    // volume outlives the container, and `process.kill(1, 0)` always succeeds, so
+    // we must classify the self/PID-1 record as stale *before* the liveness probe
+    // below — otherwise the probe reports it alive and the daemon crash-loops. A
+    // record of our own pid is likewise self, never a live sibling.
+    if (parsed === 1 || parsed === process.pid) {
+        return { decision: 'unlink-stale', pid: parsed, pidfilePath: pidPath, reason: 'self-or-pid1-container' };
+    }
     try {
         process.kill(parsed, 0);
         return { decision: 'refuse', pid: parsed, pidfilePath: pidPath, reason: 'alive' };

package/dist/preflight/pidfile-liveness.js.map

@@ -1 +1 @@
-{"version":3,"file":"pidfile-liveness.js","sourceRoot":"","sources":["../../src/preflight/pidfile-liveness.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pidfile-liveness.js","sourceRoot":"","sources":["../../src/preflight/pidfile-liveness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE/D,OAAO,EAAE,YAAY,EAAsB,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAqBtD,MAAM,UAAU,oBAAoB,CAClC,KAAgC;IAEhC,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAC1B,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;IACjC,CAAC;IAED,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,4EAA4E;QAC5E,sDAAsD;QACtD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC5F,CAAC;IAED,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAC5C,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC5F,CAAC;IAED,0EAA0E;IAC1E,8EAA8E;IAC9E,8EAA8E;IAC9E,6EAA6E;IAC7E,gEAAgE;IAChE,IAAI,MAAM,KAAK,CAAC,IAAI,MAAM,KAAK,OAAO,CAAC,GAAG,EAAE,CAAC;QAC3C,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IAC3G,CAAC;IAED,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QACxB,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IACpF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,KAAK,GAAI,GAA6B,CAAC,IAAI,CAAC;QAClD,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;YACtB,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QAC1F,CAAC;QACD,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;YACtB,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QACpF,CAAC;QACD,2EAA2E;QAC3E,qBAAqB;QACrB,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IACtF,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAe,EACf,QAAuB,EAAE;IAEzB,MAAM,QAAQ,GAAG,oBAAoB,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IACnD,IAAI,QAAQ,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACnC,YAAY,CACV;YACE,IAAI,EAAE,oBAAoB;YAC1B,OAAO,EAAE,+CAA+C,QAAQ,CAAC,GAAG,IAAI;YACxE,IAAI,EAAE,4FAA4F;YAClG,UAAU,EAAE,WAAW;YACvB,OAAO,EAAE;gBACP,KAAK,EAAE,gBAAgB;gBACvB,GAAG,EAAE,QAAQ,CAAC,GAAG;gBACjB,WAAW,EAAE,OAAO;gBACpB,MAAM,EAAE,QAAQ,CAAC,MAAM;aACxB;SACF,EACD,KAAK,CACN,CAAC;QACF,yEAAyE;QACzE,0EAA0E;QAC1E,iBAAiB;QACjB,OAAO;IACT,CAAC;IACD,IAAI,QAAQ,CAAC,QAAQ,KAAK,cAAc,EAAE,CAAC;QACzC,cAAc,CAAC;YACb,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,8BAA8B,QAAQ,CAAC,MAAM,GAAG;YACzD,OAAO,EAAE;gBACP,KAAK,EAAE,WAAW;gBAClB,WAAW,EAAE,OAAO;gBACpB,MAAM,EAAE,QAAQ,CAAC,MAAM;gBACvB,GAAG,EAAE,QAAQ,CAAC,GAAG;aAClB;SACF,CAAC,CAAC;QACH,IAAI,CAAC;YACH,UAAU,CAAC,OAAO,CAAC,CAAC;QACtB,CAAC;QAAC,MAAM,CAAC;YACP,4EAA4E;QAC9E,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/preflight/rpc-network.d.ts

@@ -48,14 +48,19 @@ export type ProbeOk = {
     ok: true;
     host: string;
     latencyMs: number;
+    expectedChainId: number;
+    actualChainId: number;
+    localDev?: true;
 };
 export type ProbeFail = {
     ok: false;
     host: string;
+    expectedChainId: number;
+    actualChainId?: number;
     /** HTTP status when applicable (4xx / 5xx). */
     code?: number;
     /** Failure shape when no HTTP status is available. */
-    reason?: 'unreachable' | 'unknown';
+    reason?: 'chain_mismatch' | 'unreachable' | 'unknown';
     message: string;
 };
 export type ProbeResult = ProbeOk | ProbeFail;
@@ -64,8 +69,9 @@ export interface ProbeFallbackChainOptions {
     log?: (message: string) => void;
 }
 /**
- * Probe each URL in a fallback chain with a per-slot `eth_blockNumber` call.
- * Records ok/latency or a structured failure (HTTP status / unreachable).
+ * Probe each URL in a fallback chain with per-slot `eth_chainId` +
+ * `eth_blockNumber` calls. Records ok/latency or a structured failure
+ * (chain mismatch / 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
@@ -73,6 +79,7 @@ export interface ProbeFallbackChainOptions {
  *
  * Per AC9 (issue #592): emits one log line per slot
  *   `[rpc] <layer> <host> ok latency=Nms`
+ *   `[rpc] <layer> <host> warn chain_mismatch expected=<id> actual=<id>`
  *   `[rpc] <layer> <host> warn <http-status>`     (e.g. 429, 503)
  *   `[rpc] <layer> <host> warn unreachable: <message>`
  */

package/dist/preflight/rpc-network.js

@@ -1,5 +1,5 @@
 import { createPublicClient, http, HttpRequestError } from 'viem';
-import { base, baseSepolia } from 'viem/chains';
+import { base, baseSepolia, mainnet, sepolia } from 'viem/chains';
 import { describeFallbackChain, maskRpcHost } from '../rpc/transport.js';
 export function expectedChainIdForNetwork(network) {
     return network === 'testnet' ? 84532 : 8453;
@@ -119,24 +119,35 @@ 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) {
+function expectedChainIdForProbe(network, layer) {
+    if (layer === 'L1')
+        return network === 'testnet' ? sepolia.id : mainnet.id;
+    return expectedChainIdForNetwork(network);
+}
+function expectedChainForProbe(network, layer) {
+    if (layer === 'L1')
+        return network === 'testnet' ? sepolia : mainnet;
+    return expectedChainForNetwork(network);
+}
+function classifyProbeError(host, expectedChainId, actualChainId, 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 };
+        return { ok: false, host, expectedChainId, actualChainId, 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 };
+            return { ok: false, host, expectedChainId, actualChainId, code: cur.status, message };
         }
         cur = cur.cause;
     }
-    return { ok: false, host, reason: 'unreachable', message };
+    return { ok: false, host, expectedChainId, actualChainId, 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).
+ * Probe each URL in a fallback chain with per-slot `eth_chainId` +
+ * `eth_blockNumber` calls. Records ok/latency or a structured failure
+ * (chain mismatch / 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
@@ -144,28 +155,50 @@ function classifyProbeError(host, err) {
  *
  * Per AC9 (issue #592): emits one log line per slot
  *   `[rpc] <layer> <host> ok latency=Nms`
+ *   `[rpc] <layer> <host> warn chain_mismatch expected=<id> actual=<id>`
  *   `[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 expectedChainId = expectedChainIdForProbe(network, layer);
+    const chain = expectedChainForProbe(network, layer);
     const results = [];
     for (const url of urls) {
         const host = maskRpcHost(url);
         const client = createPublicClient({ chain, transport: http(url, { retryCount: 0 }) });
         const t0 = performance.now();
+        let actualChainId;
         try {
+            actualChainId = await client.getChainId();
+            const localDev = evmLocalDevOverrideAcceptable(expectedChainId, actualChainId, url);
+            if (actualChainId !== expectedChainId && !localDev) {
+                const failure = {
+                    ok: false,
+                    host,
+                    expectedChainId,
+                    actualChainId,
+                    reason: 'chain_mismatch',
+                    message: `expected chain ${expectedChainId}, got ${actualChainId}`,
+                };
+                log(`[rpc] ${layer} ${host} warn chain_mismatch expected=${expectedChainId} actual=${actualChainId}`);
+                results.push(failure);
+                continue;
+            }
             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 });
+            results.push({
+                ok: true,
+                host,
+                latencyMs,
+                expectedChainId,
+                actualChainId,
+                ...(localDev ? { localDev: true } : {}),
+            });
         }
         catch (err) {
-            const failure = classifyProbeError(host, err);
+            const failure = classifyProbeError(host, expectedChainId, actualChainId, err);
             if (failure.code !== undefined) {
                 log(`[rpc] ${layer} ${host} warn ${failure.code}`);
             }

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

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

package/dist/preflight/stable-cwd.d.ts

@@ -0,0 +1,29 @@
+export interface ResolveStableCwdInput {
+    currentCwd: string;
+    earningDir: string;
+    homeDir: string;
+    exists: (p: string) => boolean;
+    sep?: string;
+}
+export interface ResolveStableCwdResult {
+    chosenCwd: string;
+    needsChdir: boolean;
+    logLine: string;
+}
+/**
+ * Pure resolver — no fs/os/process access. All inputs are injected so this can
+ * be unit-tested deterministically.
+ */
+export declare function resolveStableCwd(input: ResolveStableCwdInput): ResolveStableCwdResult;
+/**
+ * Real-world wrapper: gathers `process.cwd()`, `os.homedir()`, and `existsSync`,
+ * delegates the decision to `resolveStableCwd`, then performs the chdir.
+ *
+ * `earningDir` comes in as a param to keep this decoupled from the config
+ * module. Never crashes boot: a `process.cwd()` read can itself throw ENOENT
+ * (when the launch dir was deleted), and `process.chdir` can fail — both are
+ * caught and logged.
+ */
+export declare function ensureStableCwd(opts: {
+    earningDir: string;
+}): ResolveStableCwdResult;