fix(b03): address both blocking review findings

An independent FreePi review of tree 5aacf17 returned VERDICT: FAIL with two
blocking findings. Both were correct.

1. The setup guide told a human to run `npm run check` in packages/arc-adapter
   and called it "the readiness probe". It is not. That command runs lint,
   typecheck, and unit tests against stubbed endpoints; it proves the probe's
   logic and says nothing about whether a particular operator's endpoint,
   chain, and token are correct. A human following the guide would have
   believed their setup was verified when nothing had contacted it.

   Adds a real read-only probe. createViemProbe implements the RpcProbe
   interface over viem, and `npm run probe` loads configuration from the
   environment, asks the configured endpoint which chain it is actually on,
   checks the USDC address holds bytecode, and prints a per-check report. It
   cannot sign, send, or mutate, and it prints no credential. Section 7 now
   points at it and explains why `npm run check` is not a substitute.

2. AttemptLog was in-memory, so B03.2's requirement to persist request identity
   in ignored test runtime state before submission was not met, and the
   at-most-once claims were an artifact of a shared process rather than a
   demonstration of durability. Restart is a boundary the failure-injection
   skill requires be exercised.

   Adds FileAttemptStore, writing through to JSON under an ignored tmp/
   directory, and moves the store behind an AttemptStore interface. Writes are
   immediate: buffering would reopen the crash window the store exists to
   close. New restart tests build a fresh store from the same file, as a
   restarted process would, and prove a restarted worker is refused a second
   submission right, including after an outcome that was never learned, and
   that ten restarted workers still broadcast exactly once.

Author: selezenart

docs/settlement/LIVE_EVIDENCE.md

@@ -30,6 +30,10 @@ providers with a deterministic broadcast counter:
 - Every policy denial family produces **zero** external broadcasts.
 - Duplicate delivery, ten sequential retries, and ten parallel workers sharing
   durable state each produce **exactly one** broadcast.
+- Process restart is exercised against file-backed durable state: an attempt is
+  written to disk before the provider is called, and a restarted worker reading
+  that file is refused a second submission right, including after an outcome
+  that was never learned.
 - An ambiguous outcome does not grant a fresh submission right, so the
   dangerous retry after a possible payment cannot happen.
 - Every ambiguous or unrecognized provider response classifies as

docs/settlement/PROVIDER_SETUP.md

@@ -78,17 +78,30 @@ They are both called USDC. Read balances carefully.
 ## 7. Verification (read-only, safe to automate)
 
 Set the variables from `packages/arc-adapter/.env.example` in your shell or
-secret store, then run the readiness probe. It performs no mutation and prints
-no credential:
+secret store, then run the readiness probe:
 
 ```bash
-cd packages/arc-adapter
-npm run check
+cd packages/arc-adapter && npm run probe
 ```
 
-A `MISMATCH` result means a value is wrong and a human must fix it. It must
-never be retried into working. An `UNAVAILABLE` result means the endpoint could
-not be reached and may resolve on its own.
+This contacts the endpoint you configured, asks it which chain it is actually
+on, and checks that the configured USDC address holds contract bytecode. It is
+read-only: it cannot sign, send, or mutate anything, and it prints no
+credential. Exit code 0 means ready, 1 means not ready.
+
+Read the result carefully, because the two failure modes need opposite
+responses:
+
+- **`MISMATCH`** — the endpoint answered and the answer was wrong. Your
+  configuration points somewhere it should not. A human must fix it. Do not
+  retry; it will not resolve on its own.
+- **`UNAVAILABLE`** — the endpoint could not be reached. Your configuration may
+  be perfectly correct. Retrying later is reasonable.
+
+Note that `npm run check` is a different thing: it runs lint, typecheck, and
+the unit tests against stubbed endpoints. It proves the probe's logic is
+correct and tells you nothing about whether *your* setup is correct. Only
+`npm run probe` does that.
 
 ## 8. Storing the values
 

packages/arc-adapter/bin/probe.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runProbe } from '../dist/probe-cli.js';
+
+const code = await runProbe(process.env);
+process.exit(code);

packages/arc-adapter/package.json

@@ -17,15 +17,17 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "bin"
   ],
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src test",
     "test": "vitest run",
     "test:watch": "vitest",
-    "check": "npm run lint && npm run typecheck && npm run test && npm run build"
+    "check": "npm run lint && npm run typecheck && npm run test && npm run build",
+    "probe": "npm run build && node bin/probe.js"
   },
   "dependencies": {
     "viem": "2.56.3"
@@ -38,4 +40,4 @@
     "typescript-eslint": "8.69.0",
     "vitest": "5.0.0"
   }
-}
+}

packages/arc-adapter/src/index.ts

@@ -5,3 +5,5 @@ export * from './config.js';
 export * from './readiness.js';
 export * from './receipt.js';
 export * from './outcome.js';
+export * from './viem-probe.js';
+export * from './probe-cli.js';

packages/arc-adapter/src/probe-cli.ts

@@ -0,0 +1,63 @@
+/**
+ * Read-only readiness command (B03.1 §7).
+ *
+ * Loads configuration from the environment, probes the configured Arc
+ * endpoint, and prints a per-check report. It performs no mutation, signs
+ * nothing, and prints no credential.
+ *
+ * This exists because `npm run check` runs unit tests against stubs. Those
+ * prove the probe's logic; they say nothing about whether a particular
+ * operator's endpoint, chain, and token are correct. Only this command does.
+ *
+ * Exit codes: 0 ready, 1 not ready.
+ */
+
+import { loadSettlementConfig } from './config.js';
+import { probeReadiness } from './readiness.js';
+import { createViemProbe } from './viem-probe.js';
+
+const SYMBOL: Readonly<Record<string, string>> = {
+  PASS: 'PASS   ',
+  MISMATCH: 'MISMATCH',
+  UNAVAILABLE: 'UNAVAIL',
+  SKIPPED: 'SKIP   ',
+};
+
+export async function runProbe(env: NodeJS.ProcessEnv): Promise<number> {
+  let config;
+  try {
+    config = loadSettlementConfig(env);
+  } catch (error) {
+    // Configuration errors name the variable, never its value.
+    console.error(`Configuration error: ${(error as Error).message}`);
+    return 1;
+  }
+
+  console.log(`profile : ${config.profile.id} (chain ${config.profile.chainId})`);
+  console.log(`token   : ${config.profile.tokenContract}`);
+  console.log(`settle  : ${config.profile.tokenDecimals} decimals`);
+  console.log(`gas     : ${config.profile.nativeDecimals} decimals`);
+  console.log('');
+
+  const report = await probeReadiness(config, createViemProbe(config));
+
+  for (const check of report.checks) {
+    console.log(`${SYMBOL[check.status] ?? check.status}  ${check.name}: ${check.detail}`);
+  }
+
+  console.log('');
+  if (report.ready) {
+    console.log('READY');
+    return 0;
+  }
+
+  if (report.hasMismatch) {
+    // The distinction that matters to whoever is reading this output.
+    console.log('NOT READY: identity mismatch. A human must fix the configuration.');
+    console.log('Do not retry; a mismatch will not resolve on its own.');
+  } else {
+    console.log('NOT READY: endpoint unavailable. Configuration may be correct.');
+    console.log('Retrying later is reasonable.');
+  }
+  return 1;
+}

packages/arc-adapter/src/viem-probe.ts

@@ -0,0 +1,38 @@
+/**
+ * Live RPC probe backed by viem.
+ *
+ * The offline `RpcProbe` stubs prove the probe's logic. This implementation is
+ * what actually contacts a configured endpoint, and it is the only thing that
+ * can tell an operator whether THEIR setup is correct.
+ *
+ * Read-only by construction: it exposes `eth_chainId` and `eth_getCode` and
+ * nothing that can sign, send, or mutate.
+ */
+
+import { createPublicClient, http } from 'viem';
+import type { SettlementConfig } from './config.js';
+import type { RpcProbe } from './readiness.js';
+
+/**
+ * Build a probe against the configured endpoint.
+ *
+ * The chain is declared from the profile, but `checkChainId` still asks the
+ * endpoint what chain it is actually on. Trusting the declared value would
+ * defeat the check entirely.
+ */
+export function createViemProbe(config: SettlementConfig): RpcProbe {
+  const client = createPublicClient({
+    transport: http(config.rpcUrl, { timeout: config.rpcTimeoutMs }),
+  });
+
+  return {
+    async getChainId(): Promise<number> {
+      return await client.getChainId();
+    },
+
+    async getCode(address: `0x${string}`): Promise<string | null> {
+      const code = await client.getCode({ address });
+      return code ?? null;
+    },
+  };
+}

packages/testkit-settlement/src/attempt-store.ts

@@ -0,0 +1,107 @@
+/**
+ * Durable attempt store for the harness (B03.2).
+ *
+ * B03.2 requires request identity to be persisted in ignored test runtime
+ * state before submission. An in-memory map cannot satisfy that: it proves
+ * concurrency inside one process and disappears on restart, which is exactly
+ * the boundary `.agents/skills/oneshot-failure-injection/SKILL.md` requires be
+ * exercised ("restart services between durable transitions and external
+ * responses").
+ *
+ * This writes to a JSON file under an ignored `tmp/` directory. It is a stand-in
+ * for the PostgreSQL state Coder A owns, not a production store, and it exists
+ * so restart recovery can actually be tested rather than assumed.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export interface PersistedAttempt {
+  readonly businessIntentId: string;
+  readonly payloadFingerprint: string;
+  readonly idempotencyKey: string;
+  readonly referenceId: string;
+  /** Set before the external boundary is crossed, never after. */
+  submissionAttempted: boolean;
+}
+
+export interface AttemptStore {
+  recordOrGet(attempt: PersistedAttempt): { entry: PersistedAttempt; isNew: boolean };
+  get(businessIntentId: string): PersistedAttempt | undefined;
+  readonly size: number;
+}
+
+/** In-memory store. Fine for single-process tests; cannot survive a restart. */
+export class MemoryAttemptStore implements AttemptStore {
+  protected readonly entries = new Map<string, PersistedAttempt>();
+
+  recordOrGet(attempt: PersistedAttempt): { entry: PersistedAttempt; isNew: boolean } {
+    const existing = this.entries.get(attempt.businessIntentId);
+    if (existing) return { entry: existing, isNew: false };
+    this.entries.set(attempt.businessIntentId, attempt);
+    return { entry: attempt, isNew: true };
+  }
+
+  get(businessIntentId: string): PersistedAttempt | undefined {
+    return this.entries.get(businessIntentId);
+  }
+
+  get size(): number {
+    return this.entries.size;
+  }
+}
+
+/**
+ * File-backed store.
+ *
+ * Every mutation is written through immediately. Buffering writes would
+ * reintroduce the crash window the store exists to close: an attempt that was
+ * recorded but not yet flushed is, after a kill, indistinguishable from one
+ * that never happened.
+ */
+export class FileAttemptStore implements AttemptStore {
+  constructor(private readonly filePath: string) {
+    mkdirSync(dirname(filePath), { recursive: true });
+  }
+
+  private read(): Record<string, PersistedAttempt> {
+    try {
+      const raw = readFileSync(this.filePath, 'utf8');
+      return JSON.parse(raw) as Record<string, PersistedAttempt>;
+    } catch {
+      // A missing or unreadable file means no attempts recorded yet. It must
+      // never be treated as "no attempt exists" for an intent we have not
+      // checked; callers only reach this through recordOrGet, which writes.
+      return {};
+    }
+  }
+
+  private write(state: Record<string, PersistedAttempt>): void {
+    writeFileSync(this.filePath, JSON.stringify(state, null, 2), 'utf8');
+  }
+
+  recordOrGet(attempt: PersistedAttempt): { entry: PersistedAttempt; isNew: boolean } {
+    const state = this.read();
+    const existing = state[attempt.businessIntentId];
+    if (existing) return { entry: existing, isNew: false };
+
+    state[attempt.businessIntentId] = attempt;
+    this.write(state);
+    return { entry: attempt, isNew: true };
+  }
+
+  /** Persist a mutation made to an entry the caller already holds. */
+  update(attempt: PersistedAttempt): void {
+    const state = this.read();
+    state[attempt.businessIntentId] = attempt;
+    this.write(state);
+  }
+
+  get(businessIntentId: string): PersistedAttempt | undefined {
+    return this.read()[businessIntentId];
+  }
+
+  get size(): number {
+    return Object.keys(this.read()).length;
+  }
+}