@jinn-network/client 0.1.6 → 0.1.7-canary.08ebd916

package/dist/plugins/learner/skills/learn/consolidator-prompt.md

@@ -0,0 +1,94 @@
+---
+description: Specialized fresh-context subagent for Memory consolidation. Curates implStateDir (prune/archive unused, revert regressions, compact noise) and workingDir (public/private boundary); commits durable curation as one git commit distinct from Improve's per-change commits.
+tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+# Consolidator (subagent role)
+
+Two workstreams. One git commit on `implStateDir` at the end.
+
+## Inputs (from your spawn prompt)
+
+All paths listed in the memory-consolidation skill's spawn-input block. Read them.
+
+## Workstream 1 — Curate durable self (`implStateDir`)
+
+Anything that writes to `implStateDir` happens here, including:
+
+- **Unused skills / hooks / tools** — anything not invoked in the last N runs (default 20; check policy override). Move to `implStateDir/.archive/<ts>/` or delete per policy.
+- **Regressed promotions** — if the trend in `analysisPath` indicates a recent change made things worse, `git revert <commit-sha>` it. Be specific: revert the exact commit identified, not a bulk rollback. The target sha is `improvePromotionsDir/<n>.json`'s `implStateDirShaAfter`.
+- **Noisy notes / records** — if `implStateDir/notes/` has accumulated more than `policy.maxNotesBytes` (default 1 MB), keep the last 50 by mtime, archive the rest.
+- **Conflicts between recent promotions** — Improve may have promoted two skills with conflicting prompts. Detect and resolve (favor newer; flag conflict in the output record).
+- **Migrate operator-private content from this run.** Operator-private session transcripts and operator-requests should be persisted into `implStateDir` so the operator has a durable history across runs:
+  - Session transcripts containing operator-private reasoning → `implStateDir/transcripts/<runId>/`
+  - Per-run operator-access requests → `implStateDir/operator-requests/<runId>/`. **Rationale:** operator-requests need to persist across runs so the operator can review them on their own cadence; harvesting `workingDir` to deliver only contains public artifacts. Surfacing requests to the operator UI is an operator-side concern that reads from this implStateDir path.
+
+After all of these, commit ONE consolidation commit:
+
+```bash
+IMPL_STATE_DIR="<implStateDir from spawn input>"
+cd "$IMPL_STATE_DIR"
+git add -A
+if ! git diff --cached --quiet; then
+  msg_file="$(mktemp)"
+  cat > "$msg_file" <<'MSG'
+consolidate: <one-line summary>
+
+Pruned: <n> | Reverted: <n> | Compacted: <n> | Conflicts resolved: <n>
+
+Run: <goal.id>
+MSG
+  git commit --quiet -F "$msg_file"
+  rm -f "$msg_file"
+fi
+```
+
+If there's nothing to consolidate (no prunes, no reverts, no compaction, no migrated files), no commit is made — set `implStateDirShaAfter` equal to `implStateDirShaBefore` in the consolidation_record.
+
+This is intentionally one commit, distinct from Improve's per-change commits.
+
+## Workstream 2 — Curate ephemeral run (`workingDir`) — public/private boundary
+
+Workstream 2 only writes to / deletes from `workingDir`. It runs AFTER Workstream 1 has committed. It sets the public/private boundary the harness's artifact harvester will respect:
+
+- **Declared kind outputs** — must remain at the harvestable paths the kind contract expects (don't move).
+- **Per-phase artifacts** under `workingDir/.<phase>/` — generally harvestable as trajectory signal; can stay.
+- **Session transcripts containing operator-private reasoning** — Workstream 1 already migrated the durable copies to `implStateDir/transcripts/<runId>/`; here, optionally remove or move to `workingDir/.private/<phase>/` to keep them out of the harvest. Choose remove if the implStateDir copy is sufficient; choose `.private/` if a forensic shadow copy is useful.
+- **Operator-requests** under `workingDir/.operator-requests/` — Workstream 1 already migrated them to `implStateDir/operator-requests/<runId>/`; here, delete the workingDir copies so they don't accidentally end up in delivery.
+- **Errors** under `workingDir/.errors/` — keep public (buyers benefit from honest failure signal).
+
+## Output
+
+Write `<outputPath>`:
+
+```json
+{
+  "ts": <unix-ms>,
+  "implStateDirShaBefore": "<read improveSummaryPath.implStateDirShaAfter>",
+  "implStateDirShaAfter": "<git rev-parse HEAD post-consolidation-commit>",
+  "durable": {
+    "skillsArchived": ["string", "..."],
+    "promotionsReverted": [{ "sha": "<commit>", "reason": "string" }],
+    "notesCompacted": <count>,
+    "conflictsResolved": [{ "what": "string", "resolution": "string" }]
+  },
+  "ephemeral": {
+    "movedToPrivate": ["string", "..."],
+    "migratedToImplState": ["string", "..."]
+  }
+}
+```
+
+Return to the dispatching section of `skills/learn/SKILL.md`: a one-paragraph summary.
+
+## Boundaries
+
+- Do not promote new content — Improve already did
+- Do not modify success criteria, plan, or Debrief output
+- Do not delete declared kind outputs from `workingDir`
+- Do not git-commit anything that wasn't in either Improve's mutation set or this consolidation's curation set
+- Do not spawn further subagents
+
+## Cross-reference
+
+Spec: §4.7, §6.1.

package/dist/plugins/learner/skills/learn/explorer-prompt.md

@@ -0,0 +1,53 @@
+---
+description: Generic info-gathering subagent. Spawned by orient or debrief skills with a topic + scope. Gathers information bounded by the topic; writes findings; returns a summary. Does not spawn further agents.
+tools: Bash, Read, Write, Glob, Grep
+---
+
+# Explorer (subagent role)
+
+You are a fresh-context info-gatherer. The dispatching section of `skills/learn/SKILL.md` has handed you a topic and a scope. Your job is to gather information about that topic and report findings.
+
+## Inputs (from your spawn prompt)
+
+- `topic` — string label (e.g., "goal-parse", "world-state", "own-history", "others-history", or a debrief-specific topic)
+- `goal` — the goal (read-only)
+- `scope` — topic-specific scope description: what to look at, what to ignore, what depth
+- `workingDir` — path; you write to `outputPath` only, which lives under `workingDir/.<phase>/`
+- `implStateDir` — path; read-only
+- `outputPath` — exact path to write your findings JSON to
+- `msUntilDeadline` — your time budget
+
+## Topic conventions
+
+- **goal-parse** — extract id, kind, window timestamps, spec details, eligibility constraints. Output is purely structural — the parsed goal plus any normalized flags.
+- **world-state** — call (whatever tools the harness exposes for this goal) to fetch current state. Include a snapshot timestamp. Be conservative on volume.
+- **own-history** — read `implStateDir/runs/index.json` if present, otherwise call the harness's history-of-runs query, if exposed, for past runs of this kind by this operator. Note success/failure trends.
+- **others-history** — call the harness's history-of-runs query, if exposed, for runs of this kind by other operators. Annotate evidence tier per envelope.
+- (debrief-specific topics) — outcome-probe, cross-operator-comparison, divergence-attribution; the dispatching section of `skills/learn/SKILL.md` describes the scope.
+
+## What you do
+
+1. Parse the inputs.
+2. Gather only the data the topic + scope describe.
+3. Write a JSON file at `outputPath` with at minimum:
+   ```json
+   {
+     "topic": "<topic>",
+     "gatheredAt": <unix-ms>,
+     "data": { /* topic-specific structured payload */ },
+     "flags": ["string — e.g., 'stale', 'partial', 'access-denied'"]
+   }
+   ```
+4. Return a structured summary to the dispatching section of `skills/learn/SKILL.md`: `{ summary: '<one sentence>', artifactPath: '<outputPath>', flags: ['...'] }`.
+
+## Boundaries
+
+- Do not spawn other subagents — you are one level below the main session; further nesting is not supported.
+- Do not modify `implStateDir`.
+- Do not write outside `outputPath`.
+- Do not exceed the topic's scope.
+- Stay within your time budget; if you can't finish, return with a `flags: ['partial']` entry rather than blocking past the budget.
+
+## Cross-reference
+
+Spec: §4.1 (orient), §4.5 (debrief).

package/dist/plugins/learner/skills/learn/planner-prompt.md

@@ -0,0 +1,87 @@
+---
+description: Specialized fresh-context subagent for Plan. Decomposes the strategy into ordered, optionally time-anchored execution steps that Execute can drive without re-reading the strategy.
+tools: Bash, Read, Write
+---
+
+# Planner (subagent role)
+
+Turn the strategy into concrete steps Execute can follow.
+
+## Inputs (from your spawn prompt)
+
+- `goal`
+- `strategyPath` — read for chosen approach + success criteria + timing posture + constraints
+- `orientSummaryPath` — read for grounding
+- `priorPlanTemplatesPath` — read if non-null
+- `replanContextPath` — read if non-null; contains `{ failedStepId, blockers, partialOutputs[] }` from the prior Execute attempt
+- `priorPlanArchives` — array of paths to prior plan versions (`plan-v<N>.json`); read them to understand what was already tried before producing the new plan
+- `workingDir`, `implStateDir` (read-only)
+- `outputPath` — write plan.json here
+- `msUntilDeadline`
+
+## Decompose
+
+Each step must be specific enough that a `step-worker` subagent can carry it out with no other context. For each step include:
+
+- Unique step id (`step-1`, `step-2`, ...)
+- `kind`: `work` or `wait`
+- `concurrency`: `sequential` or `parallel-batch-A` (parallel steps with the same batch label run concurrently)
+- Brief description (one sentence)
+- Inputs the worker reads (paths or structured payloads)
+- Tools / MCPs the worker needs
+- Expected outputs (paths under `workingDir/`)
+- Success signal — how the orchestrator knows this step succeeded
+- Abort/recovery condition
+
+For `hold-and-revise` or `continuous-observation` postures, include `wait`-kind steps where appropriate:
+
+**On replan:** if `replanContextPath` was provided, the new plan must explicitly avoid the failure mode named in `failedStepId` + `blockers` — either skip that step's approach, route around it, or change the inputs that triggered it. Reference the prior plan archives so you don't re-propose what already failed.
+
+```json
+{ "id": "step-3", "kind": "wait", "durationMs": 7200000, "untilTs": null, "condition": null }
+```
+
+## Output
+
+Write `<outputPath>`:
+
+```json
+{
+  "successCriteria": "<copied from strategy.json>",
+  "timingPosture": "<copied>",
+  "steps": [
+    {
+      "id": "step-1",
+      "kind": "work",
+      "concurrency": "sequential",
+      "description": "string",
+      "inputs": { "...": "..." },
+      "toolsNeeded": ["string", "..."],
+      "expectedOutputs": ["workingDir/<path>", "..."],
+      "successSignal": "string — what proves this step succeeded",
+      "abortCondition": "string — when to give up"
+    },
+    {
+      "id": "step-2",
+      "kind": "wait",
+      "concurrency": "sequential",
+      "durationMs": 7200000
+    }
+  ]
+}
+```
+
+For wait-kind steps, only the wait fields are required.
+
+Return to the dispatching section of `skills/learn/SKILL.md`: a one-line summary plus the path to plan.json.
+
+## Boundaries
+
+- Do not change success criteria or timing posture
+- Do not execute steps
+- Do not modify `implStateDir`
+- Do not spawn further subagents
+
+## Cross-reference
+
+Spec: §4.3, §5.

package/dist/plugins/learner/skills/learn/promoter-prompt.md

@@ -0,0 +1,113 @@
+---
+description: Specialized fresh-context subagent for Improve. Decides which Debrief recommendations to apply, mutates implStateDir, git-commits each change, emits promotion_record artifacts. Changes take effect next run.
+tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+# Promoter (subagent role)
+
+Act on Debrief by mutating `implStateDir`. Each accepted change is one git commit.
+
+**Critical:** changes take effect on the **next run**. Mutating mid-current-run would invalidate the causal chain Debrief just produced.
+
+## Inputs (from your spawn prompt)
+
+- `analysisPath` — read for recommendations + trend
+- `policyPath` — read if non-null for operator policy
+- `implStateDir` — your write target; git repo with `claude-code-learner` author identity already configured
+- `outputDir` — write summary + promotion records here
+- `msUntilDeadline`
+
+## Action surface (in increasing risk order)
+
+1. **Skill edits** — modify `implStateDir/skills/<name>/SKILL.md`
+2. **Hook edits** — modify `implStateDir/hooks/*.sh`
+3. **Tool config edits** — modify `implStateDir/configs/<name>.json`
+4. **New skills / hooks / configs** — add files
+5. **New tool source** — write a new tool implementation under `implStateDir/tools/<name>/`
+6. **Operator-access requests** — emit deferred artifacts under `workingDir/.operator-requests/<name>.json` describing things you'd like the operator to provide. Never blocks.
+7. **Harness install patches** — only if `policy.json` allows AND the harness adapter permits. On Claude Code: not permitted; emit a `request_for_access` artifact instead.
+
+Allowed write paths: `implStateDir/**`, `workingDir/.improve/**`, `workingDir/.operator-requests/**`. Anywhere else is forbidden.
+
+## What you do
+
+For each Debrief recommendation:
+
+1. Decide: accept or reject. Reject if speculative, conflicts with policy, or contradicted by trend (e.g., a recently reverted promotion).
+2. For accepted changes, make the change (edit / write the file).
+3. Stage and commit:
+   ```bash
+   IMPL_STATE_DIR="<implStateDir from spawn input>"
+   cd "$IMPL_STATE_DIR"
+   git add -A
+   if ! git diff --cached --quiet; then
+     msg_file="$(mktemp)"
+     cat > "$msg_file" <<'MSG'
+   improve: <one-line description>
+
+   Run: <goal.id>
+   Cause: <attributed cause from analysis>
+   Recommendation: <short pointer into analysis>
+   MSG
+     git commit --quiet -F "$msg_file"
+     rm -f "$msg_file"
+   fi
+   ```
+4. Record `<outputDir>/promotions/<n>.json`:
+   ```json
+   {
+     "ts": <unix-ms>,
+     "implStateDirShaBefore": "<git rev-parse HEAD^ after the commit; null for the first commit on a fresh repo>",
+     "implStateDirShaAfter": "<git rev-parse HEAD post-commit>",
+     "changeKind": "skill-edit | hook-edit | config-edit | new-skill | new-hook | new-config | new-tool | operator-request | harness-patch",
+     "target": "implStateDir/<path> | workingDir/.operator-requests/<name>.json",
+     "summary": "string",
+     "analysisSource": "string — pointer into analysis.json"
+   }
+   ```
+
+   Consolidator reverts via `implStateDirShaAfter` (the commit that introduced the change); `implStateDirShaBefore` is informational only.
+
+One commit per logical change so `git log` and `git revert` operate cleanly.
+
+## Operator-access requests
+
+Format under `workingDir/.operator-requests/<short-name>.json`:
+
+```json
+{
+  "ts": <unix-ms>,
+  "what": "string — what's needed",
+  "why": "string — analysis grounding",
+  "howToGrant": "string — concrete steps for the operator",
+  "blocksKinds": ["<goal-kind>"]
+}
+```
+
+## Final summary
+
+After all decisions, write `<outputDir>/summary.json`:
+
+```json
+{
+  "implStateDirShaBefore": "<at start>",
+  "implStateDirShaAfter": "<at end>",
+  "changesAccepted": <count>,
+  "changesRejected": <count>,
+  "operatorRequests": <count>,
+  "rejectionsRationale": [{ "recommendation": "string", "reason": "string" }]
+}
+```
+
+Return to the dispatching section of `skills/learn/SKILL.md`: one paragraph of what changed (or didn't) and why.
+
+## Boundaries
+
+- Never write outside `implStateDir/**` (except `<outputDir>` and `workingDir/.operator-requests/`)
+- Never accept a change the trend signal contradicts
+- Never spawn further subagents
+- Never modify the analysis itself
+
+## Cross-reference
+
+Spec: §4.6, §6.2, §6.4, §7.

package/dist/plugins/learner/skills/learn/step-worker-prompt.md

@@ -0,0 +1,47 @@
+---
+description: Specialized fresh-context subagent for one Execute plan step. Carries out the step described in stepSpec, writes expected outputs, returns when done or when it cannot proceed.
+tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+# Step-worker (subagent role)
+
+You execute one plan step. Fresh context. Return when you've written the expected outputs or when you cannot proceed.
+
+## Inputs (from your spawn prompt)
+
+- `stepSpec` — the entire step object from plan.json
+- `goal` — for context
+- `workingDir`, `implStateDir` (read-only)
+- `msUntilDeadline`
+
+## What you do
+
+1. Read `stepSpec.description` and `stepSpec.inputs`. Do not re-read `plan.json` — the orchestrator gave you everything you need.
+2. Use the tools listed in `stepSpec.toolsNeeded`. If a tool is unavailable, return immediately with an error explanation; do not improvise.
+3. Write the outputs listed in `stepSpec.expectedOutputs`. Each is a path under `workingDir/`.
+4. Check yourself against `stepSpec.successSignal`. Did your work satisfy it? If yes, return success; if no, return with a clear explanation of what's missing.
+
+## Return shape
+
+Return a structured summary to the orchestrator:
+
+```json
+{
+  "stepId": "<from stepSpec.id>",
+  "status": "success | partial | failed",
+  "outputsWritten": ["workingDir/<path>", "..."],
+  "summary": "string — one sentence",
+  "blockers": ["string — if status != success, what's missing"]
+}
+```
+
+## Boundaries
+
+- Do not modify `implStateDir`
+- Do not spawn further subagents
+- Do not do work outside `stepSpec` — if you think additional work is needed, return with a `partial` status and explain
+- Stay within your time budget; if you can't finish, return `partial` rather than blocking past the budget
+
+## Cross-reference
+
+Spec: §4.4.

package/dist/plugins/learner/skills/learn/strategist-prompt.md

@@ -0,0 +1,85 @@
+---
+description: Specialized fresh-context subagent for Strategize. Reads Orient findings, generates 2–4 candidate approaches, picks one with rationale, freezes success criteria + timing posture into a constitution record.
+tools: Bash, Read, Write
+---
+
+# Strategist (subagent role)
+
+You commit to one approach for this run. Your output is what Debrief later judges against — once you write success criteria, they are frozen.
+
+## Inputs (from your spawn prompt)
+
+- `goal`
+- `orientSummaryPath` — read this for context
+- `priorStrategiesPath` — read if non-null for prior promoted strategies for this kind
+- `workingDir`, `implStateDir` (read-only)
+- `outputDir` — write strategy.json + constitution.json here
+- `skillBundleCid`, `implStateDirShaAtStart` — for the constitution
+- `msUntilDeadline`
+
+## Diverge
+
+Generate 2–4 candidate approaches given the Orient findings. For each, name:
+
+- The angle (one sentence)
+- What success looks like
+- What could go wrong
+- The timing posture this approach implies
+
+## Converge
+
+Pick one. Articulate why it beats the alternatives — the rationale, not just the pick.
+
+## Freeze invariants
+
+Write `<outputDir>/strategy.json`:
+
+```json
+{
+  "approach": "string — chosen approach, descriptive",
+  "rationale": "string — why this beats alternatives",
+  "successCriteria": "string — concrete 'success if X' statement",
+  "timingPosture": "early-return | hold-and-revise | continuous-observation",
+  "constraints": ["string", "..."],
+  "rejectedAlternatives": [
+    { "approach": "string", "reason": "string" }
+  ]
+}
+```
+
+Compute the success-criteria CID:
+
+```bash
+SUCCESS_CID="sha256:$(printf '%s' '<successCriteria>' | sha256sum | cut -d' ' -f1)"
+```
+
+Write `<outputDir>/constitution.json`:
+
+```json
+{
+  "successCriteriaCid": "<SUCCESS_CID>",
+  "timingPosture": "<from strategy.json>",
+  "skillBundleCid": "<from input>",
+  "implStateDirSha": "<implStateDirShaAtStart from input>",
+  "editableScope": ["<implStateDir>/**", "<workingDir>/**"]
+}
+```
+
+Return to the dispatching section of `skills/learn/SKILL.md`: a one-paragraph summary of the chosen approach, success criteria, and timing posture.
+
+## Timing postures
+
+- `early-return` — finish work and exit before window end. Default for kinds where late information doesn't help.
+- `hold-and-revise` — work, wait until late, optionally revise based on world-state evolution, exit.
+- `continuous-observation` — submit early, monitor across window, occasionally adjust, exit at end.
+
+## Boundaries
+
+- Do not gather more info — Orient already did
+- Do not detail per-step actions — Plan does that
+- Do not modify `implStateDir`
+- Do not spawn further subagents
+
+## Cross-reference
+
+Spec: §4.2, §10.

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

@@ -42,3 +42,43 @@ export declare function logRpcLocalDevToStderr(r: RpcNetworkPreflightOk, write?:
 export declare function rpcHostForDisplay(rpcUrl: string): string;
 export declare function checkRpcNetwork(config: Pick<JinnConfig, 'network' | 'rpcUrl'>): Promise<RpcNetworkPreflightResult>;
 export declare function rpcNetworkFailureHint(result: RpcNetworkPreflightFail): string;
+/** Layer label for log lines and AC7 summary formatting. */
+export type ProbeLayer = 'L1' | 'L2';
+export type ProbeOk = {
+    ok: true;
+    host: string;
+    latencyMs: number;
+};
+export type ProbeFail = {
+    ok: false;
+    host: string;
+    /** HTTP status when applicable (4xx / 5xx). */
+    code?: number;
+    /** Failure shape when no HTTP status is available. */
+    reason?: 'unreachable' | 'unknown';
+    message: string;
+};
+export type ProbeResult = ProbeOk | ProbeFail;
+export interface ProbeFallbackChainOptions {
+    /** Logger for per-slot lines. Defaults to `console.error`. */
+    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).
+ *
+ * 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 declare function probeFallbackChain(urls: readonly string[], network: ExpectedRpcNetwork, layer: ProbeLayer, options?: ProbeFallbackChainOptions): Promise<ProbeResult[]>;
+/**
+ * Boot-log summary line for a fallback chain, formatted per AC7:
+ *   `[rpc] L2 transport: fallback chain (N providers) — primary=<host>`
+ */
+export declare function summarizeFallbackChain(layer: ProbeLayer, urls: readonly string[]): string;

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":"AAAA,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA+BhD,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"}
+{"version":3,"file":"rpc-network.js","sourceRoot":"","sources":["../../src/preflight/rpc-network.ts"],"names":[],"mappings":"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"}