diff --git a/.github/workflows/brand-sync.yml b/.github/workflows/brand-sync.yml
index 43926f8..c6c69be 100644
--- a/.github/workflows/brand-sync.yml
+++ b/.github/workflows/brand-sync.yml
@@ -12,6 +12,19 @@
 # branch is protected the push fails and the fallback opens a PR instead.
 # No third-party actions beyond actions/checkout — supply-chain surface stays
 # at one GitHub-owned action.
+#
+# In THIS repo main is protected (required check `test`), so the direct push
+# always fails, and GitHub Actions is not permitted to open PRs in this org
+# (PR #141: "it pushed brand-sync/20260905 and left it for a manual PR"). The
+# fallback's `|| echo …` then swallowed that too, and the run went GREEN having
+# landed nothing — a stale count sat in the README for 26 days (#123) behind a
+# green badge, which is the exact failure the header above promises cannot
+# happen. A drift this job cannot land is a FAILURE: the run is red until a
+# human opens the PR, and the branch name is fixed (`brand-sync`, force-pushed)
+# so a month of Mondays does not leave a month of orphan branches.
+# To make the fallback land on its own: enable "Allow GitHub Actions to create
+# and approve pull requests" in the org/repo Actions settings, or give the step
+# a PAT with pull-requests:write.
 name: brand-sync
 on:
   schedule:
@@ -41,11 +54,21 @@ jobs:
           git commit -m "chore: sync brand numbers from blockrun.ai/brand/numbers.json"
           if git push origin "HEAD:${GITHUB_REF_NAME}"; then
             echo "pushed to ${GITHUB_REF_NAME}"
-          else
-            BR="brand-sync/$(date +%Y%m%d)"
-            git push -f origin "HEAD:${BR}"
-            gh pr create --head "$BR" \
+            exit 0
+          fi
+          # One fixed branch, force-pushed: the rewrite is regenerated from the
+          # artifact every run, so the previous week's branch has nothing worth
+          # keeping and a dated name per run only accumulates orphans.
+          BR="brand-sync"
+          git push -f origin "HEAD:${BR}"
+          if gh pr create --head "$BR" \
               --title "chore: sync brand numbers" \
-              --body "Automated marker refresh from https://blockrun.ai/brand/numbers.json (scripts/sync-brand-numbers.mjs --refresh). Opened as a PR because the default branch is protected." \
-              || echo "PR creation unavailable — branch ${BR} pushed, needs manual PR"
+              --body "Automated marker refresh from https://blockrun.ai/brand/numbers.json (scripts/sync-brand-numbers.mjs --refresh). Opened as a PR because the default branch is protected."; then
+            echo "opened a PR from ${BR}"
+            exit 0
           fi
+          # Not a warning. The numbers drifted, this job could not land the fix,
+          # and a green run here is how a stale count sat in the README for 26
+          # days. Red until a human opens the PR from the pushed branch.
+          echo "::error::brand numbers drifted and could not be landed: push to ${GITHUB_REF_NAME} was rejected and PR creation is unavailable to GITHUB_TOKEN. Branch ${BR} is pushed — open the PR by hand (or enable 'Allow GitHub Actions to create and approve pull requests')."
+          exit 1
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 47b4a5f..45f682a 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -37,7 +37,21 @@ jobs:
         id: v
         run: |
           PKG=$(node -p "require('./package.json').version")
-          NPM=$(npm view @blockrun/mcp version 2>/dev/null || echo "none")
+          # "none" ONLY on npm's own E404 (the package has never been published).
+          # Any other failure — a registry 5xx, a network error, a bad token —
+          # is "unknown", which the version gate step refuses. Spelling every
+          # failure as "none" made the gate pass on the one input where it must
+          # not: a package.json below latest during a registry blip, which would
+          # publish and downgrade `latest`.
+          if NPM=$(npm view @blockrun/mcp version 2>npm-view.err); then
+            :
+          elif grep -q "E404" npm-view.err; then
+            NPM=none
+          else
+            echo "::warning::npm view failed and it was not an E404:"; cat npm-view.err
+            NPM=unknown
+          fi
+          rm -f npm-view.err
           # `version=latest` is load-bearing. Without it the search endpoint pages
           # at 30 results with every isLatest=false, so the old `|| a[a.length-1]`
           # fallback returned the last row of PAGE ONE — 0.32.8, frozen since July —
@@ -55,15 +69,33 @@ jobs:
           # latest, isLatest=true.
           REG=$(curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.BlockRunAI/blockrun-mcp&version=latest" \
                 | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{const j=JSON.parse(s);const a=j.servers||[];console.log(a[0]?.server?.version||'none')}catch{console.log('none')}})")
+          # The tag is the third target, and it needs its OWN guard computed
+          # here, not derived from the npm one. Ask the remote: actions/checkout
+          # fetches no tags, so a local lookup always says "missing".
+          if git ls-remote --exit-code --tags origin "refs/tags/v${PKG}" >/dev/null 2>&1; then
+            TAG_MISSING=false
+          else
+            TAG_MISSING=true
+          fi
           echo "pkg=$PKG"  >> "$GITHUB_OUTPUT"
           echo "npm=$NPM"  >> "$GITHUB_OUTPUT"
           echo "reg=$REG"  >> "$GITHUB_OUTPUT"
-          echo "package.json=$PKG | npm=$NPM | registry=$REG"
+          echo "tag_missing=$TAG_MISSING" >> "$GITHUB_OUTPUT"
+          echo "package.json=$PKG | npm=$NPM | registry=$REG | tag v$PKG missing=$TAG_MISSING"
+
+      # `pkg != npm` is inequality, not order. npm publish does not compare
+      # semver and points `latest` at whatever it just published, so a
+      # package.json LOWER than npm latest (a typo'd 0.5.1 for 0.51.0, or a
+      # number proposed off a stale VERSION file) would ship and downgrade
+      # every `npx -y @blockrun/mcp@latest` user. Plain Node: runs before npm ci.
+      - name: Refuse a version below npm latest
+        run: node scripts/version-gate.mjs "${{ steps.v.outputs.pkg }}" "${{ steps.v.outputs.npm }}"
 
       - name: Install dependencies
         run: npm ci
 
       - name: Build, typecheck, test
+        id: build
         run: |
           npm run build
           npm run typecheck
@@ -71,6 +103,7 @@ jobs:
 
       # ---- npm ----
       - name: Publish to npm
+        id: npm
         if: steps.v.outputs.pkg != steps.v.outputs.npm
         run: npm publish --provenance --access public
         env:
@@ -81,12 +114,31 @@ jobs:
         run: echo "npm already at ${{ steps.v.outputs.pkg }} — skipping npm publish"
 
       # ---- MCP registry ----
+      # PINNED, and checksum-verified against the same release.
+      #
+      # This used to curl `releases/latest` straight into `tar -xz` and then into
+      # /usr/local/bin — an unpinned third-party binary, executed in a job that
+      # holds the npm publish token, whose contents could change between two runs
+      # of the same commit with nothing in this repo recording it. Pinning is the
+      # part that matters: the version moves when someone here changes this line.
+      # The checksum file ships from the same release, so it proves the download
+      # is intact, not that the release is trustworthy — that is what pinning is
+      # for. Bump deliberately; the registry's own releases page lists the tag.
       - name: Install mcp-publisher
         if: steps.v.outputs.pkg != steps.v.outputs.reg
+        env:
+          MCP_PUBLISHER_VERSION: v1.8.1
         run: |
-          curl -sL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_amd64.tar.gz" \
-            | tar -xz mcp-publisher
+          set -euo pipefail
+          os=$(uname -s | tr '[:upper:]' '[:lower:]')
+          tarball="mcp-publisher_${os}_amd64.tar.gz"
+          base="https://github.com/modelcontextprotocol/registry/releases/download/${MCP_PUBLISHER_VERSION}"
+          curl -fsSL -o "$tarball" "${base}/${tarball}"
+          curl -fsSL -o checksums.txt "${base}/registry_${MCP_PUBLISHER_VERSION#v}_checksums.txt"
+          grep " ${tarball}$" checksums.txt | sha256sum -c -
+          tar -xzf "$tarball" mcp-publisher
           sudo mv mcp-publisher /usr/local/bin/
+          rm -f "$tarball" checksums.txt
 
       - name: Stamp + publish server.json to MCP registry
         if: steps.v.outputs.pkg != steps.v.outputs.reg
@@ -108,12 +160,30 @@ jobs:
       # Same independent-guard shape as the two publishes above — it checks
       # whether the tag already exists rather than assuming, so re-runs and
       # workflow_dispatch are safe.
-      # Gated on the same version diff as the npm publish above. Without it, a
-      # push that only touched publish.yml (or a workflow_dispatch) would tag
-      # HEAD and title the release from an unrelated commit subject — precisely
-      # in the "release is missing" state this automation exists to repair.
+      #
+      # INDEPENDENT means its own guard, not npm's. This step used to be gated
+      # on `pkg != npm`, which is false the moment npm has published — so a
+      # job that went red AFTER npm (the mcp-publisher download, a registry
+      # 400, the tag push itself) could never be repaired by re-running it: the
+      # re-run found npm == pkg, skipped this step by its `if:`, and went green
+      # with no tag and no release. The in-step `gh release view` / `git
+      # ls-remote` checks that make re-runs safe never executed, because the
+      # outer condition short-circuited them. That is the drift this step was
+      # written to end, reported as success.
+      #
+      # So the gate is: the tag is ABSENT (resolved against origin, up front),
+      # and npm carries this version — either this run published it, or it was
+      # already there. A push that only touched publish.yml still cannot tag
+      # HEAD under a stale number, because then the tag already exists. A run
+      # whose build or npm publish FAILED does not tag either: `!cancelled()`
+      # lets this step run past a registry failure, and the outcome checks
+      # keep it from running past a real one.
       - name: Tag + GitHub release
-        if: steps.v.outputs.pkg != steps.v.outputs.npm
+        if: >-
+          !cancelled()
+          && steps.v.outputs.tag_missing == 'true'
+          && steps.build.outcome == 'success'
+          && (steps.npm.outcome == 'success' || steps.v.outputs.pkg == steps.v.outputs.npm)
         env:
           GH_TOKEN: ${{ github.token }}
           VERSION: ${{ steps.v.outputs.pkg }}
diff --git a/.gitignore b/.gitignore
index 3e67ea3..fd36f80 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,4 @@
-node_modules/
+node_modules
 dist/
 *.log
 .DS_Store
diff --git a/AGENTS.md b/AGENTS.md
index 13456fd..f25daf0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
 # BlockRun MCP
 
-MCP server giving Codex real-time data — markets, research, X/Twitter, crypto. Pay per call with USDC.
+MCP server giving Codex real-time data — markets, research, web search, crypto. Pay per call with USDC.
 
 ## Commands
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9d57e4c..cc39624 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,395 @@
 
 All notable changes to BlockRun MCP will be documented in this file.
 
+## 0.51.0
+
+**Round four went at round three.** 0.50.0's changelog said the general sweep
+was spent and the surfaces no sweep had opened were where the money was. Round
+three opened them — it is the fifty-nine hundred lines behind this release, nine
+commits that replaced every hand-copied `paidRequestInFlight` boolean with one
+per-call tracker, made every chat path stream and classify its failure by what
+the wire said, sealed `BLOCKRUN_BUDGET_LIMIT` as a ceiling the session cannot
+raise, and closed four ways a funded key could be lost. Round four then audited
+round three with the same adversarial loop, and found the pattern the loop has
+found every time: a fix that reaches one rail and not its siblings, a comment
+that states a contract one branch does not honour, and a fix whose own shape
+is the next bug. Fourteen findings survived two verifiers each — one P0, three
+P1 — and every one of them is in this release with the test that pins it.
+
+### The money paths
+
+- **A settled chat call is booked at what the rail bills, on every rail.** The
+  account rail books exact usage at the model's rate — no fee, no floor —
+  instead of the gate reserve that ran 3–50x high and tripped
+  `BLOCKRUN_BUDGET_LIMIT` at a fraction of real spend; a settled
+  `x-blockrun-cost-usd`, zero included, wins when present. The wallet rails
+  read the SDK's counter and, where the counter cannot see (a payment signed
+  and sent, no verdict back), book the reserve as a precaution and stop the
+  routing loop instead of paying a second model under the same reservation.
+  Before this, five typo'd model ids exhausted a delegated cap at $0 real
+  spend on the account rail, and a 524 after the gateway settled read as
+  "temporary API issue, try again" on the native claude-* path — with the SDK
+  retrying the settled request twice more, each retry a fresh x402 payment.
+- **Solana chat streams.** The default chain ran every paid chat through the
+  SDK's non-streaming path with a 60s abort, so a generation over a minute was
+  cancelled client-side after the SPL payment was sent. The native claude-*
+  path streams too (`maxRetries: 0`): the SDK refused non-streaming thinking
+  budgets above ~21k tokens with an error that blamed the caller.
+- **One in-flight tracker, per call, on every rail** (`utils/in-flight.ts`).
+  0.50.0's copies were wrong in five different ways — cleared in a `.finally`
+  that runs before the catch, set on Base only, module-global so one call's
+  outstanding payment booked a phantom charge against another call's failure,
+  armed before the unpaid quote probe. And round four found the tracker's own
+  shape: a helper that inspects the response and THROWS on it leaves the
+  tracker armed with an answer in hand, so `blockrun_image` on the account
+  rail booked a whole render for a `not_charged` job whose upstream text read
+  "aborted due to timeout" and told the user the charge may have gone through.
+  The verdict now comes off the error — a status, a typed job verdict, the
+  gateway's own uncharged marker — never its prose. The rail-parity matrix
+  gained the cell.
+- **Settled-at-submit routes are billed on every escape.** `sol.blockrun.ai`
+  settles the audio route optimistically at POST (the 202 says
+  `settled_optimistic`); the helper assumed payment-on-completion for every
+  route and said "No payment was taken" for a failed track the gateway had
+  already charged. Round three typed the failed-job, poll-error and deadline
+  exits; round four found the reactive re-sign path still throwing "No charge
+  was made" — every post-submit throw on that model is now a certain charge.
+  Music's Solana submit timeout is the 95s the route needs, not the 30s video
+  default that aborted every track slower than 30s after the money had moved.
+- **The seven path tools book a payment the origin never answered.** They did
+  `formatError(extractErrorMessage(err))` and nothing else, so a call whose
+  payment left and whose origin never answered booked $0 and read "try again
+  in a few minutes". The rule is narrower than chat's on purpose — the search
+  route's bare 500 is pre-settle, and booking it would invent $0.26 of phantom
+  spend per Grok blip. And a throw AFTER the SDK counted the settlement (a
+  non-JSON 200: no status, no transport words) now books the counted amount as
+  a certain charge instead of "none".
+- **`BLOCKRUN_BUDGET_LIMIT` is a ceiling the session cannot raise.** It seeded
+  the same mutable cap that `blockrun_wallet action:"budget"` writes, so the
+  agent it constrained could clear or raise it in one free tool call — and the
+  denial text at the cap pointed it at exactly that tool. `set` clamps to it,
+  `clear` restores it, `delegate` clamps the child cap to it, and every reply
+  says when and why it clamped. A revoked agent keeps its ledger — revoke +
+  delegate was still a refill, and round four found the last form of it: a
+  call that settled while its id was revoked landed on the global ledger
+  only, and the next delegate carried a ledger that had forgotten it.
+- **Unknown is never a plain error on Polymarket.** A submit that threw with no
+  4xx behind it (dropped socket, relay 502/504) released the reservation and
+  rendered as a plain error, steering the agent into a second real order
+  while the session cap saw one. The notional stays booked as unconfirmed, the
+  message says what to check, the balance-cache retry never re-submits on top
+  of a possibly-live order, and the order card keeps its lock across Re-quote.
+  `fund` arms a `pendingFund` guard for the 300s a lost EIP-3009 authorization
+  stays executable, so a retry cannot double-send; its $0.01 gateway fee is
+  reserved and booked like any paid call — round four found the ledger had
+  never been handed to the tool, so that booking existed only in the unit
+  test. A bare `confirm:true` on a market order is held to the worst fill of
+  the last preview, and `BLOCKRUN_CONFIRM_SPEND=on` finally asks the human
+  before buy/sell/fund/withdraw sign — a $0.004 rpc call got the dialog while
+  a $25 bet did not.
+- **Three pre-payment guards for paid mistakes.** `blockrun_modal` trims `gpu`
+  the way the gateway prices it — `" H100 "` quoted $8.001 against a $0.102
+  reserve, and $192 against $2.40 at 24h, past the cap and the confirm dialog
+  — and refuses a tier the gateway would 400. `blockrun_search` refuses the
+  X/Twitter source the gateway removed on 2026-07-05 and this tool advertised
+  for two months. `blockrun_markets` refuses a `?` in `path`, which bypassed
+  every params-based check. And `hasPathTraversal` decodes per segment: one
+  malformed `%` after a `#` blinded the whole-string decode, and
+  `%2e%2e/phone/numbers/buy#%` priced as a $0.003 modal op and POSTed the
+  $5.001 number purchase.
+
+### The keys
+
+- **A `secret-tool` exit 1 is read by stderr.** libsecret returns 1 for a miss
+  and for a fault alike; only the fault prints why. Round three's tri-state
+  keychain read was macOS-only, so on Linux a locked collection, a missing
+  D-Bus session or a dismissed unlock prompt all read as "absent" — and under
+  `BLOCKRUN_KEYCHAIN=strict` both provisioners minted over the funded wallet
+  the process merely could not open. A silent exit 1 is a miss; one that said
+  something is an error, with the tool's reason in the detail.
+- **The legacy `wallet.key` ranks below the keychain.** Strict mode retires
+  `.session` and never `wallet.key`, so a stale legacy file from an older
+  install outranked the keychain the moment `.session` was gone, and its key
+  was stored over the funded one with `-U`. `.session` stays the rotation
+  seam; the legacy file is consulted only after the keychain says "absent".
+- **An env key is a signer override, not a wallet this machine owns.** It is
+  never mirrored into the keychain and never retires the file — one run with
+  a different key in the environment used to leave the funded wallet, also
+  the Polymarket deposit signer, in no store at all. `BASE_CHAIN_WALLET_KEY`,
+  the SDK's own spelling, is honoured by the gates that read only
+  `BLOCKRUN_WALLET_KEY`.
+- **Two servers on a fresh machine could both mint.** Claude Code, Cursor and
+  Desktop are commonly all installed `-s user`; the last writer won on disk
+  and USDC sent to the loser's address was unrecoverable once that process
+  exited. The mint is published exclusively and the loser adopts the winner's
+  key; an empty placeholder is claimed, not overwritten.
+- **A locked keychain never routes a Base user to Solana.** The chain
+  selector's probes collapsed a read error into "absent" and memoised it for
+  the process. "Unknown" is never memoised and never a Solana signal; the
+  Base path fails loudly with its unlock message.
+- **The onramp's $0 quote is enforced**, not commented: the code signed
+  whatever the 402 said, on the path that runs when something has already
+  gone wrong. A keychain replacement of a DIFFERENT key is announced on
+  stderr with the address being replaced, so a rotation nobody meant is
+  visible the run it happens.
+
+### Saying the true thing
+
+- **`served_model`, `finish_reason` and `truncated_output` ride on every chat
+  reply**, and partial text survives a mid-stream failure. The free tier was
+  re-swept with a realistic prompt: six of eleven routed ids answered as
+  another model on both chains, so the tier keeps the five that echo their
+  own name. `anthropic/claude-opus-4` — hidden from every listing, billed
+  $15/$75 on the account rail — has a price row instead of reserving the
+  $5/$30 default.
+- **`blockrun_speech` says when the charge stands** — a settled 200 whose body
+  is unusable, on all three rails — the step video and music got in round
+  three. `blockrun_realface` reads the status off the Solana helper's error
+  instead of a regex that turned any "402" in a quote fault into "out of
+  funds" plus a top-up page, and `action:"list"` asks the active chain's
+  gateway with the active chain's address instead of minting an EVM key on a
+  Solana install. `blockrun_image` polls the 202 the account rail hands back
+  for any render past its 30s window instead of reporting "No image URL", and
+  drops the `quality` parameter the gateway 400s for every listed model — the
+  zod default of `"standard"` was failing every Base generate.
+- **`formatError` knows the rail.** An account-rail 402 says "out of credit",
+  never "run setup"; a 5xx or transport failure after the payment left says
+  the charge MAY stand instead of "try again in a few minutes"; the Base-only
+  replay-nonce reading of "Payment was rejected" is a shared hedge, so a
+  30-second Exa blip stops telling a $50 wallet to top up.
+- **`action:"status"` reports this session's spend and cap next to the
+  balance**, and `action:"report"` lists revoked agents with their kept spend.
+  Polymarket `setup` no longer prints "🎯 Ready to trade" two lines under
+  "❌ Region: BLOCKED", and the relayer SDK's progress lines go to stderr
+  instead of the JSON-RPC channel.
+
+### The release machinery
+
+`publish.yml` refuses a `package.json` below npm latest (npm publish does not
+compare semver; a typo'd `0.5.1` would have become `latest` and downgraded
+every `npx` user) — and only npm's own E404 is "none": a registry failure is
+"unknown" and refused, because that is the one input where the two differ and
+the downgrade goes through. The tag/release step is gated on the tag being
+absent, so a job that went red after the npm publish can be repaired by a
+re-run. `brand-sync` goes red when it cannot land a drift — a green run behind
+a 26-day-stale README was the exact failure it promised could not happen.
+`verify:prices` exits 2 when it could not look and reads the account rail's
+public pricing sheet as a third catalogue. The live Polymarket e2e scripts
+require `--confirm` before signing anything; every one installs the redacted
+exit handler. The test suite pins `HOME` and every rail-selecting variable for
+every file — ten mocked-handler suites were running their Base assertions on
+the account rail on any machine with `~/.blockrun/.api-key` — and a
+`node_modules` symlink that pointed at itself is no longer tracked.
+
+Context cost re-measured: 13.0K tokens for the full profile, `--profile
+trading` 58% less.
+
+## 0.50.0
+
+**Three audit rounds, each aimed at the one before it.** 0.49.0's thirty-seven fixes
+were written by six agents working in parallel, and this round went looking for
+what that costs. It found the shape immediately: each agent had hardened the
+rail it was looking at. The quote guard landed on video and image but not music
+and speech. The in-flight booking landed on Base and the account rail but not
+Solana, the default chain. Music's Solana call passed no `onQuote` at all, so
+the guard hook fired against nobody while the transfer was signed. Every one of
+those was a money path and every one passed CI.
+
+Thirty findings survived adversarial verification, and **not one was a P0 or a
+P1** — 0.49.0's own list had one of each. The read at the time was that the
+general search was spent, so the next change was not a fix but a table.
+
+That read was half right, and the half it got wrong is worth stating plainly.
+The general SWEEP was spent: another pass over the same files would have
+returned docs and cosmetics. What was not spent was the surfaces no sweep had
+opened. Round 3 went at the four the critic named and found a path that
+destroys a funded wallet key: an empty `~/.blockrun/.session` made the keychain
+gate and the loader behind it disagree, and the disagreement minted a new
+wallet over the funded one. Round 4 went at the surfaces still unread — the CI
+and publish workflows, `verify-prices`, the Apps UI, the protocol entry — and
+at the class that produced four of round 3's five findings: a comment stating a
+contract the code does not honour on some branch, platform or early return.
+Comments cannot fail a test, so nothing had ever checked them.
+
+The durable output of all three rounds is the same shape: where an assumption
+was load-bearing and lived only in prose, it is now a test. `rail-parity`,
+`axios-scope`, `scripts-redaction`, `scripts-spend-gate`, `doc-file-refs`.
+
+**The rail-parity matrix.** `test/rail-parity.test.ts` states, per paid tool and
+per rail, which treatments a paid call needs: a quote checked before signing, a
+re-reservation at the real price, in-flight booking, honest give-up wording, and
+the right ledger figure. A cell is a claim about the source, so adding a
+rail-specific guard without filling in its siblings turns the file red. It also
+pins the division that is deliberate — the seven tools whose 402 the SDK owns
+must NOT grow a quote guard, because they cannot see the quote — and fails when
+a paid tool is missing from the table altogether. It found four more gaps on its
+first run.
+
+### The money paths
+
+- **A strict-keychain wallet could be moved off its funded chain by reading its
+  own status.** 0.49.0's own P0 fix stored the new Solana key and deleted the
+  session file, which is exactly what `getChain()` keys on — so the continuity
+  pin was never written and the next start moved a funded Base user onto an
+  empty Solana wallet. The pin is now written off the provisioning fact rather
+  than re-derived from caches the mint just invalidated.
+- **Two concurrent callers minted two Solana wallets.** The cache was assigned
+  after the await, and 0.49.0 made that reachable from two entry points at once,
+  so one caller could be handed a funding QR for an address whose key was thrown
+  away. Single-flighted — and the rejection is deliberately not cached, or
+  unlocking a keychain and retrying would stay broken until restart.
+- **The order card could submit the same order twice.** The stale-amount guard
+  re-enabled an armed Place button mid-submit, and its catch treated every
+  transport failure as "nothing happened". Both now distinguish "we know nothing
+  was signed" from "we do not know", which is the difference between a retry and
+  a duplicate bet.
+- **The previewed worst fill is now enforced across the confirm**, not just
+  inside one call: `max_fill_price` refuses a book that moved against the quote
+  before anything is signed, and the card carries its own displayed figure.
+- **A chat call the account rail billed and then dropped booked $0** and read as
+  a free failure, whose obvious next step is to pay for it again.
+- **An empty `~/.blockrun/.session` overwrote a funded key in the keychain.**
+  The gate that decides whether to consult the keychain asked `existsSync`; the
+  loaders on the far side of it trim the file and treat whitespace as no key.
+  A zero-byte session file therefore read as present to the gate and absent to
+  the loader, so the keychain was skipped, a new wallet was minted, and the
+  mirror-back overwrote the entry that still held the funded key. `saveWallet`
+  is a plain non-atomic write, so an interrupted one is enough to produce that
+  file. Both rails now ask whether the file HOLDS a key, which is what
+  `getChain()` already asked, twice, with comments saying why.
+- **`blockrun_music`, `blockrun_speech` and `blockrun_realface` signed whatever
+  the 402 quoted**, with no sanity check and no re-reservation. **Giving up on
+  Solana booked nothing** in video and music, and **speech, image and realface
+  had no in-flight tracking at all**, so an abort after the gateway settled left
+  a real charge unbooked.
+- **The ledger booked the reserve, not the charge.** `tx-fee.ts` has said since
+  0.40.1 that the gate and the ledger are different numbers, and one file
+  honoured it. On Solana, where the gateway charges no transaction fee, an agent
+  capped at $1.00 making only `blockrun_rpc` calls was cut off after 250 of them
+  having actually spent $0.50 — and `action:"report"` said $1.00.
+- **A per-agent cap could refill itself.** `delegate` wrote `spent: 0`
+  unconditionally, and `delegate` is a tool the model can call. A limit is the
+  operator's to raise; spend already happened and is not theirs to erase.
+- **The Polymarket approval prompt never said what it was worth**: the default
+  grants an unlimited pUSD allowance to four spenders. It says so now, before
+  the signature, and names `POLYMARKET_BOUNDED_APPROVALS`.
+- **The relayer's double-send guard armed on failures that signed nothing** —
+  credential derivation happens before the batch exists — and its 4xx detector
+  never saw a CLOB `ApiError`'s status, so definite refusals looked ambiguous
+  and wedged the user behind a deadline for a transfer that was never made.
+
+### Saying the true thing
+
+- **"Your wallet needs funding" no longer appears on messages that say nothing
+  was charged.** The uncharged markers gated one keyword clause, so a bare 402
+  or the word "balance" still earned the footer — including on this repo's own
+  unreadable-quote refusal, which told a wallet holding $1,000 to top up.
+- **Account-rail errors are classified at all.** The status boundary excluded a
+  following dot, which is what keeps `$402.50` from reading as a status — and
+  also what made every `BlockRun account API error: 502.` fall through silently
+  while the identical wallet-rail message got guidance.
+- **A locked keychain is not a missing wallet**, and telling that user to run
+  setup invites a second one.
+- **`blockrun_video` and `blockrun_realface`** stopped offering a card top-up
+  for a wallet that is not paying on the account rail, and the wallet card
+  stopped offering card top-up on Solana, where it is not available.
+
+### Around the edges
+
+The model catalogue cache is keyed by rail and chain (the two gateways do not
+serve the same one), `blockrun_models` is annotated as reaching the network
+because it does, the video poll timeout matches the gateway route's own 60s
+limit, `SOLANA_RPC_HEADERS` is honoured again so a private RPC works, a settled
+Solana response whose body will not parse still books the charge, and the MCP
+registry publisher is pinned and checksum-verified instead of curled from
+`releases/latest` into the job that holds the npm token. `keychainDelete` now
+answers the same on both backends: it documents "gone, including was never
+there", and only macOS honoured that, so a Linux miss reported the key as still
+in the keychain when it was not.
+
+Two comments were retired for saying things the code no longer does.
+`l1-auth-1271.ts` still opened by describing the ERC-7739 wrapped L1 signature
+as the workaround in force and closed by telling a future maintainer to delete
+the module once the upstream issue is fixed. The wrap was the wrong diagnosis
+-- the CLOB answers "Invalid L1 Request headers", both call sites derive as a
+plain EOA -- and the module now holds `deriveApiCreds`, so following that
+instruction would remove credential derivation and stop all trading. And the
+argument that `applyClobProxyOnce`'s process-wide `axios.defaults` mutation is
+safe (every axios importer is a Polymarket one, everything else uses fetch)
+lived only in a comment, which cannot fail; `test/axios-scope.test.ts` now
+fails the day a non-Polymarket module imports axios and would start routing
+through an operator's `POLYMARKET_CLOB_PROXY` unasked.
+
+**The live e2e scripts printed the wallet address they promised to hide.** Three
+of the four say in their own header that wallet addresses and transaction ids
+are never printed, and each implemented it with a different regex. The one in
+the two scripts that actually move money matched 64-hex only, which is a
+transaction hash; a 40-hex address went through untouched, and the withdrawal
+path really does interpolate a bridge response carrying an address into its
+error text. Worse, only the `isError` branch was ever redacted — a thrown
+exception printed the raw message and stack. There is now one redaction,
+covering every exit path, and a test that fails if a script grows its own regex
+again. `scripts/` is also in the typecheck now: these files import from `src`
+and were checked by nothing, so a signature change surfaced when someone ran
+them against a funded wallet.
+
+**`scripts/smoke-speech.ts` charged the wallet for being run.** No flag, no
+prompt, `limit: null` so nothing capped it, under a header advertising "real
+$0.001 speak" while the run ends with a $0.0525 sound effect. It now refuses
+without `--confirm`, states the real total, and carries its own budget cap. A
+static test holds the line for the next script like it: the check is
+deliberately not behavioural, since a test that proved the gate by running the
+script would charge the wallet on the day the gate broke.
+
+**The release automation could publish wrong numbers without failing.** Four
+scripts nobody had audited, each able to produce confident output from a
+failure. `measure-tool-schema.mjs` ignored JSON-RPC errors, so a server that
+answered `tools/list` with an error was measured as zero tokens across zero
+tools and printed as a real figure at exit 0 — with `--svg` that reached the
+context-cost cards as "0.0K tokens" and a literal "NaN% less". It also decoded
+the child's stdout per chunk, so an em dash split across a 16KB pipe boundary
+became a replacement character and quietly changed the count, which the
+in-process test could never catch because it measures through
+`InMemoryTransport`. `stamp-server-json.mjs` stamped nothing when no package
+entry matched, left the template's `0.0.0-template` in place (valid semver, so
+validation passes) and printed a success line claiming it had stamped —
+pointing every registry consumer at an npm version that does not exist. And
+`changelog-section.mjs` compared a realpath'd module URL against a
+non-realpath'd `argv[1]`, so from any checkout reached through a symlink it
+exited 0 with empty stdout, which in `publish.yml` skips the fallback and
+publishes a release with an empty body. All four now fail instead.
+
+**The brand-number sync wrote unvalidated remote JSON into the README.** Values
+fetched from blockrun.ai were rendered with `String(value)` and interpolated
+into `src="…"` and `alt="…"` with no escaping, then committed and pushed to the
+default branch weekly by an unattended bot with `contents: write`. A value
+carrying a quote or an angle bracket closed the attribute and injected markup
+into every consuming repo. Rendered values are now checked at the point of use
+— a number or a short plain label, nothing else — and escaped on top of that.
+Its `--check` also no longer prints the stale markers it found and then
+declares everything up to date.
+
+Two documentation claims that nothing was watching: the README said "same 20
+tools either way" two lines below a marker rendering 19, and
+`docs/mcp-schema-overhead.md` kept a second copy of the profile-cost table that
+no test pinned. Both are now covered, along with the profile list itself, which
+was hardcoded in two places and would have left a newly added profile measured
+by neither.
+
+**CONTRIBUTING told new contributors to call the SDK directly.** Step 1 of
+"Adding a new MCP tool" was "copy `src/tools/surf.ts`", a file deleted with the
+tool in 0.49.0, and the payment section documented
+`client.getWithPaymentRaw` / `requestWithPaymentRaw` as the way to make a paid
+call. There are three payment rails and the SDK knows two: on the account rail
+it degrades to a plain Bearer fetch and discards the `x-blockrun-cost-usd`
+header, so a tool written from those instructions cannot report what it cost
+and books the wrong ledger figure. `src/utils/raw-call.ts` exists precisely so
+no tool picks a rail for itself, and every rail-parity bug this project has
+shipped came from one doing so. The steps now name files that exist and the
+helper that handles all three rails. `test/doc-file-refs.test.ts` fails when a
+doc names a repo path that is not there, and asserts that every path-based tool
+really does route through `raw-call`.
+
 ## 0.49.0
 
 **The error says whether money moved.** Issue #132 reported `blockrun_markets`
diff --git a/CLAUDE.md b/CLAUDE.md
index fed4bfb..2c204a1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,6 @@
 # BlockRun MCP
 
-MCP server giving Claude real-time data — markets, research, X/Twitter, crypto. Pay per call with USDC.
+MCP server giving Claude real-time data — markets, research, web search, crypto. Pay per call with USDC.
 
 ## Commands
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 17e3900..272fa54 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -37,19 +37,19 @@ Two ways to expose a new API. Pick the right one:
 - The API is core to BlockRun value-prop (chat, image, wallet)
 
 **Add a skill** when:
-- The API is path-based passthrough (mirrors `blockrun_markets` / `blockrun_surf`)
+- The API is path-based passthrough (mirrors `blockrun_markets` / `blockrun_exa`)
 - The endpoint catalog is large (≥10 endpoints) and benefits from a Quick Decision Table
 - LLM routing needs trigger keywords beyond what tool descriptions can carry
 
 Reference examples in the repo:
-- Path-based tool: `src/tools/surf.ts` — 57 lines, exposes 84 endpoints behind it
-- Long-tail skill: `skills/surf/SKILL.md` — full endpoint catalog + 7 worked examples
+- Path-based tool: `src/tools/markets.ts` — 154 lines, one `path` parameter in front of the whole Predexon catalog
+- Long-tail skill: `skills/prediction-markets/SKILL.md` — endpoint catalog, Quick Decision Table, worked examples
 - Async payment-on-completion: `src/tools/video.ts` — submit + poll + settle-on-complete
 - Typed structured tool: `src/tools/chat.ts` — multi-mode routing + budget gating + multi-turn
 
 ## Adding a new MCP tool
 
-1. Copy `src/tools/surf.ts` as a starting template
+1. Copy `src/tools/markets.ts` as a starting template for a path-based tool, or `src/tools/exa.ts` for a single-endpoint one
 2. Use `getClient()` from `src/utils/wallet.ts` — it auto-routes Base vs Solana
 3. Keep tool description ≤ 30 lines. Long endpoint catalogs belong in `skills/<name>/SKILL.md`, not in the tool description
 4. Register in `src/mcp-handler.ts` (one import + one `register*Tool()` call)
@@ -70,8 +70,8 @@ Reference examples in the repo:
    ---
    ```
 
-2. Mirror the structure of `skills/surf/SKILL.md`: Quick Decision Table → Worked Examples → Full Reference (organized by category)
-3. Triggers should cover the long tail. Users won't always say "Surf" or "BlockRun" — they'll say "wallet labels", "on-chain SQL", "mindshare". Cover the synonyms
+2. Mirror the structure of `skills/prediction-markets/SKILL.md`: Quick Decision Table → Worked Examples → Full Reference (organized by category). `skills/surf/SKILL.md` is NOT a template — it is a retirement map for a removed tool
+3. Triggers should cover the long tail. Users won't always say the vendor's name or "BlockRun" — for prediction markets they'll say "odds", "will X happen", "betting line". Cover the synonyms
 
 ## Chain-aware code
 
@@ -83,7 +83,9 @@ Never hardcode chain ID, RPC URL, or address format. Use:
 
 Two flavors. Pick the right one:
 
-- **Sync, single-call**: use `client.getWithPaymentRaw(endpoint, params)` (GET) or `client.requestWithPaymentRaw(endpoint, body)` (POST). One signature, one settlement. See `src/tools/surf.ts`, `src/tools/exa.ts`.
+- **Sync, single-call**: use `rawGet(client, endpoint, params)` (GET) or `rawPost(client, endpoint, body)` (POST) from `src/utils/raw-call.ts`. See `src/tools/markets.ts`, `src/tools/exa.ts`.
+
+  Do **not** reach for `client.getWithPaymentRaw` / `client.requestWithPaymentRaw` directly. There are three payment rails (Base wallet, Solana wallet, account API key) and the SDK only knows about the two wallet ones — on the account rail it degrades to a plain Bearer fetch and throws away the `x-blockrun-cost-usd` header, so the call cannot report what it cost. `raw-call.ts` exists so no tool picks a rail for itself, and book the ledger with its `ledgerFallback()` rather than the reserved amount: the gate and the ledger are deliberately different numbers, and Solana has no gateway transaction fee at all.
 - **Async, payment-on-completion**: copy the `src/tools/video.ts` pattern — submit → 402 → sign → poll the same URL with the same `PAYMENT-SIGNATURE` header → settle on the first `completed` response. Upstream failures or client-side timeout = no charge. See `src/tools/music.ts` for the simpler synchronous-blocking variant.
 
 ## CHANGELOG
diff --git a/README.md b/README.md
index e144737..6973257 100644
--- a/README.md
+++ b/README.md
@@ -4,10 +4,10 @@
 
 <h3>Real-time data — and real trades — for Claude and any AI agent.</h3>
 
-<p>Agents can't sign up for accounts. Agents can't enter credit cards.<br>
-Agents can only sign transactions.<br><br>
+<p>Agents can pay like agents: sign transactions from a wallet.<br>
+Teams can pay like teams: get a BlockRun API key at <a href="https://user.blockrun.ai">user.blockrun.ai</a>, add credit by card or wire, and let the MCP call <code>api.blockrun.ai</code>.<br><br>
 <strong>BlockRun MCP gives your agent <!-- br:mcp.tools -->19<!-- /br:mcp.tools --> tools — markets, research, web search, images, video, on-chain data, and live Polymarket trading — paid per call.</strong><br><br>
-<strong>Two ways to pay, same tools:</strong> a self-custody <strong>wallet</strong> (USDC on Solana or Base, no account needed) — or a <strong>BlockRun API key</strong> for teams that can't run wallets. <a href="https://user.blockrun.ai">Sign up at user.blockrun.ai →</a><br><br>
+<strong>Two ways to pay, same tools:</strong> a self-custody <strong>wallet</strong> (USDC on Solana or Base, no account needed) — or a <strong>BlockRun API key</strong> backed by account credit. <a href="https://user.blockrun.ai">Sign up at user.blockrun.ai →</a><br><br>
 <em>Read the odds <strong>and</strong> place the bet, from one self-custody wallet.</em></p>
 
 <br>
@@ -16,7 +16,7 @@ Agents can only sign transactions.<br><br>
 <img src="https://img.shields.io/badge/🤖_Agent--Native-black?style=for-the-badge" alt="Agent native">&nbsp;
 <img src="https://img.shields.io/badge/🔑_Wallet_or_API_Key-blue?style=for-the-badge" alt="Wallet or API key">&nbsp;
 <img src="https://img.shields.io/badge/📈_Read_+_Trade_Polymarket-e11d48?style=for-the-badge" alt="Read and trade Polymarket">&nbsp;
-<img src="https://img.shields.io/badge/💰_x402_USDC-purple?style=for-the-badge" alt="x402 USDC">&nbsp;
+<img src="https://img.shields.io/badge/💳_Card_Credit_or_USDC-purple?style=for-the-badge" alt="Card credit or USDC">&nbsp;
 <img src="https://img.shields.io/badge/🔓_Open_Source-green?style=for-the-badge" alt="Open source">
 
 [![npm version](https://img.shields.io/npm/v/@blockrun/mcp.svg?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@blockrun/mcp)
@@ -39,12 +39,12 @@ Agents can only sign transactions.<br><br>
 claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest
 ```
 
-<div align="center"><em>Wallet auto-created on first run. Fund with $5 USDC — or set <code>BLOCKRUN_API_KEY</code> and skip the wallet entirely. Ask Claude anything.</em></div>
+<div align="center"><em>Wallet auto-created on first run. Fund with $5 USDC — or get a key at <a href="https://user.blockrun.ai">user.blockrun.ai</a>, top up by card, and call through <code>api.blockrun.ai</code>. Ask Claude anything.</em></div>
 
 <div align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="assets/context-cost-dark.svg">
-    <img src="assets/context-cost.svg" width="620" alt="Context cost: 12.7K tokens, 6% of a 200K context window, charged every turn whether or not you call a tool. 5.2K with --profile trading, 59% less.">
+    <img src="assets/context-cost.svg" width="620" alt="Context cost: 13.0K tokens, 7% of a 200K context window, charged every turn whether or not you call a tool. 5.4K with --profile trading, 58% less.">
   </picture>
 </div>
 
@@ -54,7 +54,7 @@ claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest
 
 > **BlockRun MCP** is an open-source [Model Context Protocol](https://modelcontextprotocol.io) server that gives Claude — and any MCP-compatible agent — <!-- br:mcp.tools -->19<!-- /br:mcp.tools --> tools for real-time data and real actions: <!-- br:models.chatVisible -->78<!-- /br:models.chatVisible --> LLMs, image & video generation, prediction-market data, live web/X search, on-chain queries across <!-- br:chains.rpc -->40<!-- /br:chains.rpc --> chains, and **the ability to place real, USDC-settled bets on Polymarket**.
 
-You pay per call, and you choose how. **Wallet mode** authenticates with a signature and settles each call in USDC via the [x402](https://x402.org) protocol — no account, no credit card, no subscription, on Solana or Base. **Account mode** authenticates with a BlockRun API key (`brk_live_…`) from [user.blockrun.ai](https://user.blockrun.ai) and bills prepaid credit at exact usage — for teams that can't hand a wallet to an agent. Same 20 tools either way. MIT licensed.
+You pay per call, and you choose how. **Wallet mode** authenticates with a signature and settles each call in USDC via the [x402](https://x402.org) protocol — no account, no credit card, no subscription, on Solana or Base. **Account mode** authenticates with a BlockRun API key (`brk_live_…`) from [user.blockrun.ai](https://user.blockrun.ai), routes service calls through [api.blockrun.ai](https://api.blockrun.ai), and draws down card- or wire-funded account credit at exact usage. Same <!-- br:mcp.tools -->19<!-- /br:mcp.tools --> tools either way. MIT licensed.
 
 ## 🏆 First of its kind — the signal → trade loop in Claude Code
 
@@ -66,11 +66,12 @@ Read live Polymarket odds *and* place the bet, from one self-custody wallet, pay
 
 Every other data integration was built for **human developers** — create an account, copy an API key into `.env`, add a credit card, repeat for every vendor.
 
-**Agents can't do any of that.** BlockRun MCP is built for the agent-first world:
+**BlockRun gives you both payment rails without rebuilding the integration.** Use a wallet when the agent should self-custody funds, or use an account key when a team wants card-funded credits and a dashboard.
 
 - **One wallet, every source** — <!-- br:mcp.tools -->19<!-- /br:mcp.tools --> tools behind a single self-custody wallet. No per-vendor signups.
-- **No API key required** — your wallet signature *is* authentication. (One is available at [user.blockrun.ai](https://user.blockrun.ai) for teams who need an invoice instead of a keypair.)
-- **No credit cards** — pay per request in USDC via [x402](https://x402.org), fractions of a cent each.
+- **One account key, every source** — mint a key at [user.blockrun.ai](https://user.blockrun.ai), top up by card or wire, then the MCP calls [api.blockrun.ai](https://api.blockrun.ai) with that key.
+- **No API key required in wallet mode** — your wallet signature *is* authentication.
+- **No credit card required in wallet mode** — pay per request in USDC via [x402](https://x402.org), fractions of a cent each.
 - **Starts free** — the free tier (`blockrun_chat mode:"free"`, `blockrun_dex`, crypto `blockrun_price`, `blockrun_models`) costs $0.
 - **Reads *and* acts** — most tools deliver data; `blockrun_polymarket` places real, confirm-gated trades.
 - **Human-in-the-loop payments** — turn on `BLOCKRUN_CONFIRM_SPEND=on` and the agent pauses before any paid call above your threshold; nothing is signed until you approve. [Details ↓](#%EF%B8%8F-human-in-the-loop-payments)
@@ -83,17 +84,17 @@ Every other data integration was built for **human developers** — create an ac
 
 |                     | Raw provider APIs                | Typical single-vendor MCP | **BlockRun MCP**                          |
 | ------------------- | -------------------------------- | ------------------------- | ----------------------------------------- |
-| **Setup**           | Account + API key *per vendor*   | Account/key for 1 vendor  | **Wallet auto-created — or one key for everything** |
-| **Payment**         | Credit card, monthly minimums    | Credit card / vendor plan | **USDC per-call via x402, or prepaid credit** |
+| **Setup**           | Account + API key *per vendor*   | Account/key for 1 vendor  | **Wallet auto-created — or one BlockRun key for everything** |
+| **Payment**         | Credit card, monthly minimums    | Credit card / vendor plan | **USDC per-call via x402, or card/wire-funded account credit** |
 | **Data sources**    | One per integration              | One vendor                | **<!-- br:mcp.tools -->19<!-- /br:mcp.tools --> tools — LLMs, media, markets, chain**|
 | **Place real bets** | Build it yourself                | Rare                      | **Yes — Polymarket CLOB, confirm-gated**  |
-| **Pay-chain**       | —                                | —                         | **Solana + Base (or no chain at all)**    |
+| **Pay-chain**       | —                                | —                         | **Solana + Base, or `api.blockrun.ai` with no chain at all** |
 | **Agent budgets**   | Manual                           | —                         | **Built-in per-agent delegation**         |
 | **Spend approval**  | —                                | —                         | **Ask-before-pay dialog (MCP elicitation)** |
 | **Generative UI**   | —                                | Rare                      | **Order card + wallet panel (MCP Apps)**  |
 | **Open source**     | Varies                           | Varies                    | **Yes (MIT)**                             |
 
-✓ One wallet · ✓ Pay-per-call · ✓ Reads **and** trades · ✓ Multi-chain · ✓ Agent-ready · ✓ Open source
+✓ One wallet or one account key · ✓ Pay-per-call · ✓ Reads **and** trades · ✓ Multi-chain · ✓ Agent-ready · ✓ Open source
 
 ---
 
@@ -107,7 +108,7 @@ Before BlockRun, Claude can't answer:
 - *"What's the 24h volume on the PEPE/ETH pair on Uniswap?"*
 - *"Polymarket has the Fed holding at 73% — put $2 on it."* ← and now it can **place the trade**, not just read the odds.
 
-After BlockRun, it can. Each query costs fractions of a cent — billed from a local USDC wallet, or from prepaid credit on a [BlockRun account](https://user.blockrun.ai). No subscriptions, no per-vendor signups.
+After BlockRun, it can. Each query costs fractions of a cent — billed from a local USDC wallet, or from card-funded credit on a [BlockRun account](https://user.blockrun.ai) through [api.blockrun.ai](https://api.blockrun.ai). No subscriptions, no per-vendor signups.
 
 ---
 
@@ -117,14 +118,14 @@ After BlockRun, it can. Each query costs fractions of a cent — billed from a l
 
 |  | **Wallet** *(default)* | **API key** |
 |---|---|---|
-| Setup | Nothing — a wallet is created on first run | Sign in at [user.blockrun.ai](https://user.blockrun.ai), mint a key |
-| Funding | Send USDC (Solana or Base) | Card / wire → prepaid credit |
-| Billing | Per call, settled on-chain, + $0.001 network fee | Post-paid at **exact** usage, no per-call fee, no minimum |
-| Identity | A keypair on your machine | An account with members and an invoice |
+| Setup | Nothing — a wallet is created on first run | Sign in at [user.blockrun.ai](https://user.blockrun.ai), mint a key, use it against [api.blockrun.ai](https://api.blockrun.ai) |
+| Funding | Send USDC (Solana or Base) | Credit card / wire → account credit |
+| Billing | Per call, settled on-chain, + $0.001 network fee | Exact-usage account credit, no per-call network fee, no minimum |
+| Identity | A keypair on your machine | An account with members, credits, and a usage ledger |
 | Best for | Agents, solo devs, anything self-custody | Teams, companies, anyone who can't run a wallet |
 | Trade on Polymarket | ✅ | ❌ — needs a keypair to sign |
 
-Both modes reach the same <!-- br:mcp.tools -->19<!-- /br:mcp.tools --> tools. You can switch at any time; setting `BLOCKRUN_API_KEY` takes priority over a wallet, and unsetting it hands the wallet back.
+Both modes reach the same <!-- br:mcp.tools -->19<!-- /br:mcp.tools --> tools. Account mode sends service calls to `https://api.blockrun.ai` by default. You can switch at any time; setting `BLOCKRUN_API_KEY` takes priority over a wallet, and unsetting it hands the wallet back.
 
 ### 1. Install
 
@@ -251,13 +252,13 @@ Package managers have shown install size for decades. Almost no MCP server shows
 
 | Profile | Tools | Context |
 |---------|-------|---------|
-| `full` *(default)* | 19 | 12,657 |
-| `trading` | 8 | 5,160 |
-| `media` | 7 | 5,603 |
-| `research` | 5 | 2,635 |
-| `chat` | 3 | 1,976 |
+| `full` *(default)* | 19 | 13,006 |
+| `trading` | 8 | 5,411 |
+| `media` | 7 | 5,790 |
+| `research` | 5 | 2,752 |
+| `chat` | 3 | 2,079 |
 
-Running `--profile trading` instead of the default costs **59% less context** for the same trading
+Running `--profile trading` instead of the default costs **58% less context** for the same trading
 workflow. If you only ever ask about markets, that is the single cheapest change you can make.
 
 Measure it yourself — against us, or against any other stdio MCP server:
@@ -291,11 +292,11 @@ with the [Stanford runbook](docs/stanford-trading-demo.md).
 
 ### 3. Add funds
 
-**Option A — API key (no wallet).** Sign in at **[user.blockrun.ai](https://user.blockrun.ai)** with Google, then:
+**Option A — API key + account credit (no wallet).** Sign in at **[user.blockrun.ai](https://user.blockrun.ai)** with Google. This is the dashboard for keys, credits, and activity; the MCP uses the key to call **[api.blockrun.ai](https://api.blockrun.ai)** for the actual services.
 
 1. **[Dashboard → Keys](https://user.blockrun.ai/dashboard/keys)** — mint a key. It looks like `brk_live_…` and is shown once.
-2. **[Dashboard → Credits](https://user.blockrun.ai/dashboard/credits)** — top up by card or wire.
-3. Point the server at it:
+2. **[Dashboard → Credits](https://user.blockrun.ai/dashboard/credits)** — top up by credit card or wire.
+3. Point the server at it. By default, account-mode calls go to `https://api.blockrun.ai`:
 
 ```bash
 claude mcp add blockrun -s user -e BLOCKRUN_API_KEY=brk_live_… -- npx -y @blockrun/mcp@latest
@@ -314,13 +315,12 @@ balance, and what this session has spent:
 ```
 Paying with: BlockRun account API key (no wallet, no chain)
 
-  Account:  acme (ungated)
-  Spent to date: $4.5239 (invoiced account — no prepaid ceiling)
+  Account:  acme (gated)
+  Credit remaining: $12.5000 of $50.00 granted
   Top up:   https://user.blockrun.ai/dashboard/credits
 ```
 
-A prepaid account shows `Credit remaining: $12.50 of $50.00 granted` instead. If
-the account is blocked, status says so and why *before* you spend a call finding out.
+Invoiced accounts show `Spent to date: $4.5239 (invoiced account — no prepaid ceiling)` instead. If the account is blocked, status says so and why *before* you spend a call finding out.
 
 **Option B — wallet (no account).** Run `blockrun_wallet` to see your addresses. New installs default to **Solana**; send USDC (SPL) on Solana from Coinbase (pick "Solana"), Phantom, Solflare, or Backpack. To pay on Base instead: `blockrun_wallet action:"chain" chain:"base"`, then send USDC on Base. Full instructions: [Fund your wallet](#fund-your-wallet).
 
@@ -330,7 +330,7 @@ the account is blocked, status says so and why *before* you spend a call finding
 
 > *"What's Polymarket saying about the next Fed decision? If 'hold' is above 70%, put $2 on it."*
 
-Claude reads the odds with `blockrun_markets` and — with your confirmation — places the trade with `blockrun_polymarket`. One wallet. Gasless. Confirm-gated.
+Claude reads the odds with `blockrun_markets`. In wallet mode, and only after your confirmation, it can also place the trade with `blockrun_polymarket`. In API-key mode, the data/media/research calls run through `api.blockrun.ai`; Polymarket trading still requires a local keypair to sign.
 
 ### 5. Install the agent skills (optional)
 
@@ -380,7 +380,7 @@ npx -y @blockrun/mcp@latest skills install --to ~/.codex/skills
 | `blockrun_polymarket_read` | Read-only Polymarket positions/open orders plus executable live order previews, separated for MCP clients that enforce tool safety annotations | free |
 | `blockrun_polymarket` | **Trade on Polymarket** (CLOB V2): place/cancel real bets, positions, redeem winnings — signed locally, settled in pUSD from a gasless deposit wallet. Confirm-gated, $25/order default cap. [Details ↓](#-polymarket-trading) | free tool; bets are your funds |
 | `blockrun_exa` | Neural web search (Exa) — research, competitors, papers, URL content | $0.01 + fee/query |
-| `blockrun_search` | Grok Live Search — web + X/Twitter + news with citations | $0.025 × max_results |
+| `blockrun_search` | Grok Live Search — web + news with citations | $0.025 × max_results |
 | `blockrun_dex` | Live DEX prices via DexScreener | free |
 | `blockrun_rpc` | Raw JSON-RPC on <!-- br:chains.rpc -->40<!-- /br:chains.rpc --> chains (Ethereum, Base, Solana, Bitcoin, Sui, NEAR, …) via Tatum | $0.002 + fee/call |
 | `blockrun_defi` | DefiLlama — protocol TVL, chain TVL, yield pools (APY), token prices | $0.001–0.005 + fee/call |
@@ -492,7 +492,7 @@ On hosts that support the [MCP Apps extension](https://modelcontextprotocol.io/e
 
 ## Fund your wallet
 
-> Paying with an API key instead? There is no wallet to fund — top up credit at **[user.blockrun.ai/dashboard/credits](https://user.blockrun.ai/dashboard/credits)** and skip this section.
+> Paying with an API key instead? There is no wallet to fund — top up credit by card or wire at **[user.blockrun.ai/dashboard/credits](https://user.blockrun.ai/dashboard/credits)**. The MCP will use that key against **[api.blockrun.ai](https://api.blockrun.ai)** and skip the wallet rail entirely.
 
 The server keeps **two** wallets — one on Solana, one on Base — and pays from one at a time. Run `blockrun_wallet` to see both addresses, balances, and which is active.
 
@@ -553,7 +553,7 @@ A blocked capability returns a message naming the fix, not a raw error.
 
 Anything estimated is printed with a `~` and says so. Estimates run **high** on
 the account rail — they add a transaction fee it does not charge — so a budget
-cap trips early rather than late. The invoice is always
+cap trips early rather than late. The source of truth is always
 [Dashboard → Activity](https://user.blockrun.ai/dashboard/activity).
 
 ---
@@ -573,7 +573,7 @@ cap trips early rather than late. The invoice is always
 
 ## Showcase
 
-Posters generated through `blockrun_image` with `openai/gpt-image-2` — each a single API call routed through BlockRun, paid in USDC on Base.
+Posters generated through `blockrun_image` with `openai/gpt-image-2` — each a single API call routed through BlockRun, paid from either account credit or a USDC wallet.
 
 <p align="center">
   <img src="assets/posters/gpt-5-5-launch.png" width="600" alt="gpt-5.5 — now live on BlockRun. Pay per call. No subscription. No keys.">
@@ -592,12 +592,12 @@ Prompts and a worked example are in [`skills/image-prompting/SKILL.md`](skills/i
 
 | | Direct APIs | BlockRun |
 |---|---|---|
-| Exa | Sign up, $20/mo minimum | $0.011/call on Base ($0.01 + fee), no subscription |
-| Polymarket | Undocumented, rate-limited | $0.0085/call on Base ($0.0075 + fee), clean JSON — plus you can **trade** |
-| DefiLlama | Free tier, rate-limited, no SLA | $0.006/call on Base ($0.005 + fee), same JSON, one wallet |
-| Multiple sources | 3 accounts, 3 API keys, 3 billing pages | **1 wallet** |
+| Exa | Sign up, $20/mo minimum | $0.011/call on Base ($0.01 + fee), or exact account usage via `api.blockrun.ai` |
+| Polymarket | Undocumented, rate-limited | $0.0085/call on Base ($0.0075 + fee), or exact account usage for reads — plus wallet mode can **trade** |
+| DefiLlama | Free tier, rate-limited, no SLA | $0.006/call on Base ($0.005 + fee), or exact account usage via `api.blockrun.ai` |
+| Multiple sources | 3 accounts, 3 API keys, 3 billing pages | **1 wallet, or 1 BlockRun account key** |
 
-One wallet. All sources. No dashboards.
+One wallet, or one dashboard-backed API key. All sources.
 
 ---
 
@@ -608,9 +608,9 @@ One wallet. All sources. No dashboards.
 
 | Variable / File | Default | Effect |
 |---|---|---|
-| `BLOCKRUN_API_KEY` | unset | A BlockRun account key (`brk_live_…`) from [user.blockrun.ai/dashboard/keys](https://user.blockrun.ai/dashboard/keys). **Set → account billing: no wallet is created, read or used, and no chain applies.** Takes priority over every wallet setting below. A malformed value is a startup error, never a silent fall back to the wallet. |
+| `BLOCKRUN_API_KEY` | unset | A BlockRun account key (`brk_live_…`) from [user.blockrun.ai/dashboard/keys](https://user.blockrun.ai/dashboard/keys). **Set → account billing through `api.blockrun.ai`: no wallet is created, read or used, and no chain applies.** Takes priority over every wallet setting below. A malformed value is a startup error, never a silent fall back to the wallet. |
 | `~/.blockrun/.api-key` | not created | The same key on disk, for clients that make env vars awkward. Read only when `BLOCKRUN_API_KEY` is unset; an empty or unreadable file falls through to wallet mode. |
-| `BLOCKRUN_API_BASE_URL` | `https://api.blockrun.ai` | Account API base, for staging. Accepts the OpenAI-style `…/v1` form too. |
+| `BLOCKRUN_API_BASE_URL` | `https://api.blockrun.ai` | Account API service endpoint used after you get a key at `user.blockrun.ai`. Override only for staging. Accepts the OpenAI-style `…/v1` form too. |
 | `~/.blockrun/.session` | auto-created on first run | EVM private key (0x…). File exists → use Base. Also the Polymarket signer (unless `BLOCKRUN_WALLET_KEY` or an agent `wallet.json` takes precedence). |
 | `BLOCKRUN_WALLET_KEY` | unset | Env override of the EVM key — takes precedence over `.session` / `wallet.json` as the Base + Polymarket signer. |
 | `~/.blockrun/.chain` | unset | Explicit chain preference: `base` or `solana`. Written only by `blockrun_wallet action:"chain"` — i.e. only when you choose. |
@@ -669,13 +669,13 @@ An open-source MCP server that gives Claude and other agents <!-- br:mcp.tools -
 **Do I need an API key or an account?**
 No. A wallet is auto-created locally on first run; you fund it with USDC and there are no signups, dashboards or keys to rotate.
 
-But you *can* have one. If your team can't hand a wallet to an agent, sign in at **[user.blockrun.ai](https://user.blockrun.ai)**, mint a key at [Dashboard → Keys](https://user.blockrun.ai/dashboard/keys), top up at [Dashboard → Credits](https://user.blockrun.ai/dashboard/credits), and set `BLOCKRUN_API_KEY`. You then get post-paid billing at **exact** usage — no $0.001 per-call minimum, no per-call network fee — and a per-call ledger at [Dashboard → Activity](https://user.blockrun.ai/dashboard/activity). Everything works except the parts that genuinely need a keypair: Polymarket trading, wallet balances/top-ups, and the wallet-indexed `blockrun_realface action:"list"`.
+But you *can* have one. If your team can't hand a wallet to an agent, sign in at **[user.blockrun.ai](https://user.blockrun.ai)**, mint a key at [Dashboard → Keys](https://user.blockrun.ai/dashboard/keys), top up account credit by card or wire at [Dashboard → Credits](https://user.blockrun.ai/dashboard/credits), and set `BLOCKRUN_API_KEY`. The MCP then sends paid service calls to **[api.blockrun.ai](https://api.blockrun.ai)** and bills exact usage against that account credit — no $0.001 per-call network fee, no per-call minimum — with a ledger at [Dashboard → Activity](https://user.blockrun.ai/dashboard/activity). Everything works except the parts that genuinely need a keypair: Polymarket trading, wallet balances/top-ups, and the wallet-indexed `blockrun_realface action:"list"`.
 
 **Which is cheaper?**
 Account billing, slightly — it charges exact metered usage with no per-call minimum and no $0.001 transaction fee. Wallet mode buys you self-custody and Polymarket trading instead.
 
 **How much does it cost?**
-Pay-per-call — fractions of a cent to a few cents. The free tier (`blockrun_chat mode:"free"`, `blockrun_dex`, crypto `blockrun_price`, `blockrun_models`) is $0. $5 of USDC covers thousands of queries.
+Pay-per-call — fractions of a cent to a few cents. The free tier (`blockrun_chat mode:"free"`, `blockrun_dex`, crypto `blockrun_price`, `blockrun_models`) is $0. $5 of USDC or account credit covers thousands of queries.
 
 **Is it safe / non-custodial?**
 Yes. Your private key never leaves your machine (`~/.blockrun/.session` by default, `0600`). x402 payments and Polymarket orders are signed locally — BlockRun forwards signed payloads and cannot move your funds.
@@ -693,13 +693,13 @@ Yes — `BLOCKRUN_CONFIRM_SPEND=on`. Every paid tool pauses with the estimated c
 Yes. `blockrun_polymarket` places real, USDC-settled orders on Polymarket's CLOB — confirm-gated and capped. Read the odds with `blockrun_markets`, place with `blockrun_polymarket`.
 
 **Base or Solana?**
-Both. Switch instantly with `blockrun_wallet action:"chain"`. A few media/paid tools settle on Base only (noted above).
+Both. Switch instantly with `blockrun_wallet action:"chain"`. Three things are Base-only, and each says so when you call them on Solana: `blockrun_defi` (DefiLlama) and `blockrun_modal`, which the Solana gateway does not serve, and native Anthropic `claude-*` chat. Media generation, markets, search and Polymarket all settle on either chain.
 
 ---
 
 ## From the BlockRun ecosystem
 
-BlockRun is agent-native AI infrastructure — one wallet, x402 USDC micropayments, across every surface:
+BlockRun is agent-native AI infrastructure — one wallet with x402 USDC micropayments, or one account API key with card-funded credit, across every surface:
 
 - **⚡ [ClawRouter](https://github.com/BlockRunAI/ClawRouter)** — the agent-native LLM router for OpenClaw. <!-- br:models.chatVisible -->78<!-- /br:models.chatVisible --> models, <1ms local routing, USDC on Base & Solana.
 - **🤖 [BRCC](https://blockrun.ai/brcc.md)** — BlockRun for Claude Code: smart routing + x402 payments, purpose-built for Claude Code.
diff --git a/VERSION b/VERSION
index 9ed317f..c5d4cee 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.41.1
+0.51.0
diff --git a/apps/order-preview.ts b/apps/order-preview.ts
index 87a67ce..d278fa7 100644
--- a/apps/order-preview.ts
+++ b/apps/order-preview.ts
@@ -7,6 +7,7 @@
 // prompt and the server's caps (POLYMARKET_MAX_BET_USD, session cap) are
 // unchanged; this card only replaces the model typing the call.
 import { $, autoSize, bootApp, el, resultText, setBusy, structured, usd, type ToolResult } from "./shared";
+import { declinedByUser, outcomeIsUnknown } from "./order-safety.js";
 
 interface Preview {
   dryRun: true;
@@ -52,6 +53,29 @@ const body = $("body");
 
 /** The arguments the model passed to blockrun_polymarket_read (we re-use them to re-quote). */
 let toolArgs: Record<string, unknown> = {};
+
+/**
+ * Orders whose submit ended with an UNKNOWN outcome, keyed by token+side, with
+ * the message the user saw. This must outlive the card that set it: the lock
+ * used to be a `let` inside renderPreview, so Re-quote — which the unknown
+ * path re-enables so the user can see the new price — rendered a fresh card
+ * with Place enabled, and one more click was a second real order on top of
+ * one that may already be resting at the CLOB. A fresh preview for the same
+ * token+side now renders locked until the user has checked positions/orders
+ * (a new session clears it: the card has no state beyond this page).
+ */
+const unknownOutcomes = new Map<string, string>();
+const outcomeKey = (p: { tokenId: string; action: string }) => `${p.tokenId}:${p.action}`;
+
+/**
+ * Tell the model what happened on the card. The success path already does
+ * this; the unknown-outcome path did not, so the conversation had no record
+ * that an order may be live and the agent could re-place it from the text
+ * path with no idea the card had already tried.
+ */
+function tellModel(text: string, structuredContent: Record<string, unknown> = {}): void {
+  void app.updateModelContext({ content: [{ type: "text", text }], structuredContent }).catch(() => {});
+}
 app.ontoolinput = (p) => { toolArgs = { ...(p.arguments ?? {}) }; };
 app.ontoolresult = (r) => render(r as ToolResult);
 
@@ -119,7 +143,11 @@ function renderPreview(p: Preview): void {
     // Market orders are SIGNED at this bound (the server walks the book), so
     // the fill can never be worse than the number shown here.
     ...(!isLimit && typeof p.worstFillPrice === "number"
-      ? [kv(isBuy ? "Worst fill (signed max)" : "Worst fill (signed min)", `${(p.worstFillPrice * 100).toFixed(1)}¢  ·  ${p.worstFillPrice.toFixed(3)}`)]
+      // "signed max/min" read as a guarantee about the order about to be
+      // placed. It is the bound from THIS quote; Place re-walks a fresh book on
+      // the server and signs that one, so the figure can move if the book does.
+      // Say "at this quote" and let the server's own result be the record.
+      ? [kv(isBuy ? "Worst fill at this quote (max)" : "Worst fill at this quote (min)", `${(p.worstFillPrice * 100).toFixed(1)}¢  ·  ${p.worstFillPrice.toFixed(3)}`)]
       : []),
     kv("Shares", shares !== undefined ? `${isLimit ? "" : "≈ "}${shares.toFixed(4)}` : "—"),
     kv("Max payout if right", isBuy && shares !== undefined ? usd(shares) : "—"),
@@ -184,16 +212,45 @@ function renderPreview(p: Preview): void {
   // allowed while the field still equals the quoted amount; a change disarms
   // and disables Place until Re-quote renders a fresh card.
   const quotedAmount = parseFloat(amountField.value);
+  // Submitting, or submitted-with-unknown-outcome. Either way this card must
+  // not offer Place again: the first is a duplicate in flight, the second is a
+  // duplicate bet on an order that may already be live at the CLOB. The
+  // unknown flag is read from module scope so it survives Re-quote.
+  let submitting = false;
+  let outcomeUnknown = unknownOutcomes.has(outcomeKey(p));
+  const lockUnknown = (message: string, structuredContent?: Record<string, unknown>) => {
+    outcomeUnknown = true;
+    unknownOutcomes.set(outcomeKey(p), message);
+    tellModel(
+      `Order card: the ${p.action} of ${usd(p.notionalUsd)} on ${p.outcome ?? p.tokenId} did NOT complete and its outcome is UNKNOWN — ` +
+        `the order MAY already be live at the exchange. Check blockrun_polymarket_read action:"orders" (limit) / action:"positions" (market) ` +
+        `before placing it again. Card message: ${message}`,
+      { outcome: "unknown", action: p.action, tokenId: p.tokenId, notionalUsd: p.notionalUsd, ...(structuredContent ?? {}) },
+    );
+  };
   const syncPlace = () => {
     const stale = parseFloat(amountField.value) !== quotedAmount;
     if (stale && armed) disarm();
-    place.disabled = stale;
-    place.title = stale ? "Amount changed — Re-quote first" : "";
+    // Never re-enable during or after a submit. The stale guard wrote
+    // `place.disabled = stale` unconditionally on every input event, so
+    // nudging the amount up and back down while the CLOB round-trip was
+    // outstanding re-enabled an ARMED button reading "Submitting…" — one more
+    // click placed a second identical real-money order with no confirmation.
+    place.disabled = stale || submitting || outcomeUnknown;
+    place.title = stale ? "Amount changed — Re-quote first" : outcomeUnknown ? "Outcome unknown — check your positions before retrying" : "";
     if (stale) { note.className = "note"; note.textContent = "Amount changed — Re-quote first to refresh the price and notional before placing."; }
   };
   amountField.addEventListener("input", syncPlace);
+  if (outcomeUnknown) {
+    // Re-rendered (Re-quote) after an unknown outcome: keep the lock and the
+    // warning on the fresh card, so the new price is visible but not placeable.
+    note.className = "note err";
+    note.textContent = `${unknownOutcomes.get(outcomeKey(p)) ?? "A previous submit of this order did not complete."}\n\nThis order MAY already be live at the exchange. Check your positions/orders before placing it again — this card will not re-submit it.`;
+    syncPlace();
+  }
 
   place.addEventListener("click", async () => {
+    if (submitting || outcomeUnknown) return;
     if (parseFloat(amountField.value) !== quotedAmount) { syncPlace(); return; }
     if (!armed) {
       armed = true;
@@ -202,24 +259,48 @@ function renderPreview(p: Preview): void {
       cancel.hidden = false;
       return;
     }
-    const args = { action: p.action, ...currentArgs(), confirm: true };
-    delete (args as Record<string, unknown>).side;
+    // Carry the bound the user was actually shown into the confirm. Without it
+    // the server re-walks a fresh book and signs THAT worst fill, so a book
+    // that moved between the quote and the click filled at a price this card
+    // never displayed. With it, a worse walk is refused unsigned.
+    const args: Record<string, unknown> = { action: p.action, ...currentArgs(), confirm: true };
+    delete args.side;
+    if (typeof p.worstFillPrice === "number") args.max_fill_price = p.worstFillPrice;
+    submitting = true;
     setBusy(place, true, "Submitting…"); setBusy(requote, true); cancel.hidden = true;
+    amountField.disabled = true;
     try {
       const r = (await app.callServerTool({ name: "blockrun_polymarket", arguments: args })) as ToolResult;
+      submitting = false; amountField.disabled = false;
       if (r.isError) {
-        note.className = "note err"; note.textContent = resultText(r);
-        disarm(); setBusy(place, false); setBusy(requote, false);
+        // A tool-level error is the server's own report, so it knows whether
+        // anything was signed — and it says so. Only re-arm when it tells us
+        // nothing landed; otherwise this card must not invite a second bet.
+        const text = resultText(r);
+        note.className = "note err"; note.textContent = text;
+        if (outcomeIsUnknown(text)) { lockUnknown(text, (r.structuredContent ?? {}) as Record<string, unknown>); setBusy(place, false); setBusy(requote, false); syncPlace(); }
+        else { disarm(); setBusy(place, false); setBusy(requote, false); }
         return;
       }
       renderPlaced(p, structured<Placed>(r) ?? {}, resultText(r));
-      void app.updateModelContext({
-        content: [{ type: "text", text: `User placed the order from the order card: ${resultText(r)}` }],
-        structuredContent: (r.structuredContent ?? {}) as Record<string, unknown>,
-      }).catch(() => {});
+      tellModel(`User placed the order from the order card: ${resultText(r)}`, (r.structuredContent ?? {}) as Record<string, unknown>);
     } catch (e) {
-      note.className = "note err"; note.textContent = String((e as Error).message ?? e);
-      disarm(); setBusy(place, false); setBusy(requote, false);
+      submitting = false; amountField.disabled = false;
+      const msg = String((e as Error).message ?? e);
+      note.className = "note err";
+      // A THROW is transport-level — a host/SDK timeout, a dropped connection,
+      // a torn-down sandbox — which is exactly when the order may already be
+      // live at the CLOB. Re-arming here reads as "nothing happened, try
+      // again" and places a duplicate. A refusal at the consent prompt is the
+      // one case where nothing was signed, and it says so.
+      if (declinedByUser(msg)) {
+        note.textContent = msg;
+        disarm(); setBusy(place, false); setBusy(requote, false);
+      } else {
+        lockUnknown(msg);
+        note.textContent = `${msg}\n\nThe request did not complete, so this order MAY already be live at the exchange. Check your positions before placing it again — this card will not re-submit it.`;
+        setBusy(place, false); setBusy(requote, false); syncPlace();
+      }
     }
   });
 }
diff --git a/apps/order-safety.ts b/apps/order-safety.ts
new file mode 100644
index 0000000..adb3237
--- /dev/null
+++ b/apps/order-safety.ts
@@ -0,0 +1,35 @@
+// apps/order-safety.ts
+//
+// The two questions the order card has to answer after a submit fails, split
+// out of the DOM so they can be tested as logic rather than grepped out of a
+// minified bundle.
+//
+// Both exist because of the same asymmetry: a card that re-arms after an
+// ambiguous failure reads as "nothing happened, try again", and one more click
+// is a second real-money order at the CLOB. Re-arming is only safe when we KNOW
+// nothing was signed.
+
+/**
+ * Did the server's own error say the money did not move?
+ *
+ * The server knows whether it signed; when it does, it says so in the wording
+ * this repo standardised on ("no charge was made", "Nothing withdrawn", …).
+ * Anything else — a bare failure, a transport error, a timeout — is
+ * outcome-unknown and must NOT re-arm the card.
+ */
+export function outcomeIsUnknown(text: string): boolean {
+  const t = text.toLowerCase();
+  const uncharged =
+    /no charge was made|no payment was made|no payment was taken|no payment taken|nothing was charged|not charged|nothing withdrawn|refusing to sign/.test(t);
+  return !uncharged;
+}
+
+/**
+ * Did the user decline a consent prompt? That signs nothing, it is the
+ * commonest reason the submit throws, and it is the one throw that may safely
+ * restore the card to its pre-click state.
+ */
+export function declinedByUser(message: string): boolean {
+  const m = message.toLowerCase();
+  return /declin|denied|cancell?ed|rejected by (the )?user|not approved|permission/.test(m);
+}
diff --git a/apps/wallet.ts b/apps/wallet.ts
index 7c841aa..c7fe436 100644
--- a/apps/wallet.ts
+++ b/apps/wallet.ts
@@ -105,11 +105,19 @@ function renderStatus(s: Status): void {
     );
   };
 
-  const buy = el("button", { class: "primary" }, "Buy USDC with card") as HTMLButtonElement;
+  // Card top-up is Base-only (utils/onramp.ts returns address+QR guidance on
+  // Solana, with no link). The primary CTA read "Buy USDC with card" on both
+  // chains, so a Solana user clicked it, watched "Minting link…", and landed on
+  // a plain-text fallback explaining it is not available. Say what this chain
+  // can actually do.
+  const onSolana = s.activeChain === "solana";
+  const buyLabel = onSolana ? "Fund with USDC (SPL)" : "Buy USDC with card";
+  const buy = el("button", { class: "primary" }, buyLabel) as HTMLButtonElement;
+  if (onSolana) buy.title = "Card top-up is Base-only — this shows your Solana address and QR to send USDC (SPL) to.";
   buy.addEventListener("click", async () => {
-    setBusy(buy, true, "Minting link…");
+    setBusy(buy, true, onSolana ? "Fetching address…" : "Minting link…");
     try { render(await call({ action: "deposit" })); } catch (e) { note.hidden = false; note.className = "note err"; note.textContent = String((e as Error).message ?? e); }
-    finally { setBusy(buy, false, "Buy USDC with card"); }
+    finally { setBusy(buy, false, buyLabel); }
   });
   const explorer = el("button", { class: "small" }, s.explorerLabel || "Explorer") as HTMLButtonElement;
   explorer.addEventListener("click", () => { void app.openLink({ url: s.explorerUrl }); });
diff --git a/assets/context-cost-dark.svg b/assets/context-cost-dark.svg
index 015e3e4..4ed5a10 100644
--- a/assets/context-cost-dark.svg
+++ b/assets/context-cost-dark.svg
@@ -1,10 +1,10 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="620" height="150" viewBox="0 0 620 150" role="img" aria-label="Context cost: 12.7K tokens, 6% of a 200K context window; 5.2K with --profile trading, 59% less">
+<svg xmlns="http://www.w3.org/2000/svg" width="620" height="150" viewBox="0 0 620 150" role="img" aria-label="Context cost: 13.0K tokens, 7% of a 200K context window; 5.4K with --profile trading, 58% less">
   <defs><clipPath id="card-d"><rect x="0.5" y="0.5" width="619" height="149" rx="12"/></clipPath></defs>
   <rect x="0.5" y="0.5" width="619" height="149" rx="12" fill="#0B0A0F" stroke="#26242E"/>
   <rect x="0.5" y="0.5" width="5" height="149" fill="#5B9BF6" clip-path="url(#card-d)"/>
   <text x="28" y="34" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="11" font-weight="600" letter-spacing="1.6" fill="#8A8797">CONTEXT COST</text>
-  <text x="28" y="78" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="34" font-weight="700" fill="#FFFFFF">12.7K tokens</text>
-  <text x="28" y="103" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#6E6B7B">6% of a 200K context window · every turn, whether or not you call a tool</text>
-  <text x="28" y="127" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#8A8797">5.2K with <tspan font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#5B9BF6">--profile trading</tspan> — 59% less</text>
+  <text x="28" y="78" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="34" font-weight="700" fill="#FFFFFF">13.0K tokens</text>
+  <text x="28" y="103" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#6E6B7B">7% of a 200K context window · every turn, whether or not you call a tool</text>
+  <text x="28" y="127" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#8A8797">5.4K with <tspan font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#5B9BF6">--profile trading</tspan> — 58% less</text>
   <text x="592" y="34" text-anchor="end" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="10.5" fill="#6E6B7B">measured, not estimated</text>
 </svg>
diff --git a/assets/context-cost.svg b/assets/context-cost.svg
index 665256a..948669e 100644
--- a/assets/context-cost.svg
+++ b/assets/context-cost.svg
@@ -1,10 +1,10 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="620" height="150" viewBox="0 0 620 150" role="img" aria-label="Context cost: 12.7K tokens, 6% of a 200K context window; 5.2K with --profile trading, 59% less">
+<svg xmlns="http://www.w3.org/2000/svg" width="620" height="150" viewBox="0 0 620 150" role="img" aria-label="Context cost: 13.0K tokens, 7% of a 200K context window; 5.4K with --profile trading, 58% less">
   <defs><clipPath id="card-l"><rect x="0.5" y="0.5" width="619" height="149" rx="12"/></clipPath></defs>
   <rect x="0.5" y="0.5" width="619" height="149" rx="12" fill="#FFFFFF" stroke="#E4E2E8"/>
   <rect x="0.5" y="0.5" width="5" height="149" fill="#2563EB" clip-path="url(#card-l)"/>
   <text x="28" y="34" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="11" font-weight="600" letter-spacing="1.6" fill="#6E6B7B">CONTEXT COST</text>
-  <text x="28" y="78" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="34" font-weight="700" fill="#0B0A0F">12.7K tokens</text>
-  <text x="28" y="103" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#8A8797">6% of a 200K context window · every turn, whether or not you call a tool</text>
-  <text x="28" y="127" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#6E6B7B">5.2K with <tspan font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#2563EB">--profile trading</tspan> — 59% less</text>
+  <text x="28" y="78" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="34" font-weight="700" fill="#0B0A0F">13.0K tokens</text>
+  <text x="28" y="103" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#8A8797">7% of a 200K context window · every turn, whether or not you call a tool</text>
+  <text x="28" y="127" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#6E6B7B">5.4K with <tspan font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" fill="#2563EB">--profile trading</tspan> — 58% less</text>
   <text x="592" y="34" text-anchor="end" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="10.5" fill="#8A8797">measured, not estimated</text>
 </svg>
diff --git a/docs/mcp-schema-overhead.md b/docs/mcp-schema-overhead.md
index fab5cec..c506af1 100644
--- a/docs/mcp-schema-overhead.md
+++ b/docs/mcp-schema-overhead.md
@@ -9,21 +9,28 @@ Harness: [`scripts/measure-tool-schema.mjs`](../scripts/measure-tool-schema.mjs)
 (`npm run measure:schema`). Guard: [`test/schema-tokens.test.ts`](../test/schema-tokens.test.ts),
 which fails the build when the README card disagrees with a live measurement.
 
-Written 2026-09-01, verified against `@modelcontextprotocol/sdk` 1.29.0.
+Written 2026-09-01, verified against `@modelcontextprotocol/sdk` 1.29.0. Numbers re-measured
+2026-09-09 at 0.49.0.
 
 ## Our number
 
 | Profile | Tools | Context |
 |---------|-------|---------|
-| `full` *(default)* | 20 | 12,900 |
-| `trading` | 9 | 5,554 |
-| `media` | 7 | 5,436 |
-| `research` | 6 | 3,024 |
-| `chat` | 3 | 1,924 |
+| `full` *(default)* | 19 | 13,006 |
+| `trading` | 8 | 5,411 |
+| `media` | 7 | 5,790 |
+| `research` | 5 | 2,752 |
+| `chat` | 3 | 2,079 |
 
-Descriptions are ~54% of it, input schemas ~41%. `--profile trading` costs 57% less than the
+Descriptions are ~55% of it, input schemas ~40%. `--profile trading` costs 58% less than the
 default for the same workflow.
 
+These figures move with every description edit, so they are not the source of truth — the README
+card is, and `test/schema-tokens.test.ts` fails the build when it disagrees with a live
+measurement. This page is dated prose; re-run `npm run measure:schema` before quoting it. (It was
+20 tools and 12,900 tokens until 2026-09-06, when the gateway retired Surf and `blockrun_surf`
+went with it.)
+
 Measure it yourself, against us or anyone else:
 
 ```bash
@@ -50,7 +57,7 @@ It is a JSON Schema *dialect declaration*, and as far as can be verified it does
 block the model carries on every turn, and the server author never wrote it and cannot see it in
 their source.
 
-Cost: **~15 tokens per tool.** For us, 20 tools → 300 tokens. On a 49-tool server of the kind
+Cost: **~15 tokens per tool.** For us, 19 tools → ~285 tokens. On a 49-tool server of the kind
 Uber cited, ~735 tokens. Nobody's tool budget is blown by this, but it is 100% waste, it is
 invisible from the source code, and it is in essentially every SDK-built server in the ecosystem.
 
@@ -63,7 +70,7 @@ Stronger than inference, weaker than "every client ignores it". Verified:
 - **The SDK's bundled validator never receives it.** ajv (`validation/ajv-provider.js`) is invoked
   on `tool.outputSchema` and on elicitation `requestedSchema` — never on `inputSchema`. In the
   reference implementation the header is not even handed to a validator.
-- **It is inert for ajv anyway.** Compiling all 20 tool schemas under the SDK's exact ajv config,
+- **It is inert for ajv anyway.** Compiling all 20 tool schemas (the count at the time) under the SDK's exact ajv config,
   with and without the header, against 5 input samples each: identical verdicts on **100/100**
   pairs, 0 differences.
 
diff --git a/package-lock.json b/package-lock.json
index 7dd42a7..055b772 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@blockrun/mcp",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@blockrun/mcp",
-      "version": "0.49.0",
+      "version": "0.51.0",
       "license": "MIT",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.123.0",
diff --git a/package.json b/package.json
index d88d833..a968162 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/mcp",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "mcpName": "io.github.BlockRunAI/blockrun-mcp",
   "description": "BlockRun MCP Server - Give your AI agent web search, deep research, prediction markets, and crypto data. Pay per call from a USDC wallet (Solana or Base) or a BlockRun API key.",
   "type": "module",
@@ -20,7 +20,7 @@
     "dev": "tsx watch src/index.ts",
     "start": "node dist/index.js",
     "typecheck": "tsc --noEmit",
-    "test": "tsx --experimental-test-module-mocks --test test/*.test.ts",
+    "test": "tsx --experimental-test-module-mocks --import ./test/_setup.ts --test test/*.test.ts",
     "prepublishOnly": "npm run build",
     "verify:prices": "tsx scripts/verify-prices.ts",
     "measure:schema": "node scripts/measure-tool-schema.mjs",
diff --git a/scripts/changelog-section.mjs b/scripts/changelog-section.mjs
index b1348c8..567b66c 100644
--- a/scripts/changelog-section.mjs
+++ b/scripts/changelog-section.mjs
@@ -6,7 +6,7 @@
 // Usage: node scripts/changelog-section.mjs 0.32.2
 // Exits 1 with nothing on stdout when the version has no section, so the
 // workflow can fall back to a generic note instead of publishing an empty one.
-import { readFileSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -40,7 +40,16 @@ export function extractSection(changelog, version) {
 }
 
 // Only run as a CLI when invoked directly, so the test can import it.
-if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+//
+// realpath BOTH sides. Node realpaths the ESM main entry but leaves
+// process.argv[1] as resolve(cwd, arg), so a checkout reached through a
+// symlink (macOS /tmp -> /private/tmp, npm link, a symlinked working dir) made
+// these differ and this block silently did nothing at exit 0. publish.yml
+// guards on `if ! node scripts/changelog-section.mjs "$VERSION" > notes.md`,
+// so exit 0 with empty stdout skips the generic fallback and publishes a
+// release with an EMPTY body -- the one thing the header above promises
+// cannot happen.
+if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) {
   const version = process.argv[2];
   if (!version) {
     console.error("usage: node scripts/changelog-section.mjs <version>");
diff --git a/scripts/e2e-confirm.ts b/scripts/e2e-confirm.ts
new file mode 100644
index 0000000..eb5c9f4
--- /dev/null
+++ b/scripts/e2e-confirm.ts
@@ -0,0 +1,46 @@
+/**
+ * The confirm gate for every script under scripts/ that moves real funds.
+ *
+ *   npx tsx scripts/polymarket-e2e-live.ts --confirm
+ *   POLYMARKET_E2E_CONFIRM=1 npm run e2e:polymarket:withdraw
+ *
+ * Nothing in scripts/ may spend by being run. smoke-speech.ts got its gate
+ * after a bare invocation charged for a sound effect it advertised as a
+ * $0.001 speak; the three Polymarket scripts that submit a $2 withdrawal or
+ * sign the unlimited approval batch were carved out of that rule because they
+ * go through utils/ rather than a tool handler — a distinction that matters
+ * to a test and not at all to the wallet. This repo has already lost $0.42 to
+ * an agent that ran a paid path because it looked like a read.
+ *
+ * Its own switch, not smoke-speech's: BLOCKRUN_SMOKE_CONFIRM exported for a
+ * $0.06 smoke run must not have pre-authorised a $2 bridge.
+ *
+ * Injectable argv/env/exit so test/e2e-confirm.test.ts can prove the refusal
+ * without running a script.
+ */
+export const CONFIRM_FLAG = "--confirm";
+export const CONFIRM_ENV = "POLYMARKET_E2E_CONFIRM";
+
+type Io = {
+  argv?: string[];
+  env?: NodeJS.ProcessEnv;
+  stderr?: (line: string) => void;
+  exit?: (code: number) => never;
+};
+
+/**
+ * Print what the script is about to do with real money and stop, unless the
+ * caller said --confirm (or POLYMARKET_E2E_CONFIRM=1). Call it before the
+ * first await: a gate that comes after the withdrawal is a receipt.
+ */
+export function requireLiveConfirm(wouldMove: string[], io: Io = {}): void {
+  const argv = io.argv ?? process.argv.slice(2);
+  const env = io.env ?? process.env;
+  if (argv.includes(CONFIRM_FLAG) || env[CONFIRM_ENV] === "1") return;
+  const stderr = io.stderr ?? ((line: string) => console.error(line));
+  const exit = io.exit ?? ((code: number) => process.exit(code));
+  stderr("This script moves REAL funds from the machine-global wallet. Without confirmation it would have:");
+  for (const line of wouldMove) stderr(`  - ${line}`);
+  stderr(`Nothing was submitted. Re-run with ${CONFIRM_FLAG}, or set ${CONFIRM_ENV}=1, to authorise it.`);
+  exit(1);
+}
diff --git a/scripts/measure-tool-schema.mjs b/scripts/measure-tool-schema.mjs
index dd42c80..00be9e5 100755
--- a/scripts/measure-tool-schema.mjs
+++ b/scripts/measure-tool-schema.mjs
@@ -34,7 +34,7 @@
  * percent higher on JSON, so every number here is a slight UNDER-count.
  */
 import { spawn } from "node:child_process";
-import { writeFileSync } from "node:fs";
+import { writeFileSync, realpathSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { encode } from "gpt-tokenizer/encoding/o200k_base";
 
@@ -79,9 +79,26 @@ export function listTools(cmd, { timeoutMs = 120_000 } = {}) {
     };
 
     const send = (m) => child.stdin.write(`${JSON.stringify(m)}\n`);
+    // Reject on a JSON-RPC error rather than resolving with a message that has
+    // no `result`. Callers destructure `{ result }`, so swallowing an error
+    // handed them `undefined` -> `result?.tools ?? []` -> a measurement of ZERO
+    // tokens across ZERO tools, printed as a real figure with exit 0. With
+    // --svg that reaches the cards as "0.0K tokens" and, because `cut` divides
+    // by the total, a literal "NaN% less". A server answering `initialize`
+    // with an error -- the foreign-server case this tool advertises, when the
+    // package wants auth -- is all it takes.
     const rpc = (method, params) =>
-      new Promise((res) => {
-        pending.set(++id, res);
+      new Promise((res, rej) => {
+        pending.set(++id, (msg) => {
+          if (msg.error) {
+            rej(new Error(
+              `${cmd.join(" ")} answered ${method} with JSON-RPC error ` +
+              `${msg.error.code}: ${msg.error.message ?? "(no message)"}`,
+            ));
+            return;
+          }
+          res(msg);
+        });
         send({ jsonrpc: "2.0", id, method, params });
       });
 
@@ -103,6 +120,15 @@ export function listTools(cmd, { timeoutMs = 120_000 } = {}) {
     // EPIPE rather than an unhandled crash when the child is already gone.
     child.stdin.on("error", () => {});
 
+    // Decode as a STREAM. Without this each Buffer is toString()'d on its own,
+    // so a multi-byte character split across a chunk boundary becomes U+FFFD.
+    // JSON.parse still succeeds (U+FFFD is a legal string char) and only the
+    // token count comes out wrong -- and the tool descriptions this measures
+    // are full of em dashes. The payload is ~50KB against a 16KB pipe buffer,
+    // so multi-chunk delivery is the normal case, and the in-process test that
+    // pins these numbers uses InMemoryTransport and never exercises this
+    // reader. The disagreement would surface as an unexplainable README diff.
+    child.stdout.setEncoding("utf8");
     child.stdout.on("data", (chunk) => {
       buf += chunk;
       let i;
@@ -198,7 +224,11 @@ export function renderCard({ total, tradingTotal, cut, dark }) {
 
 // Importable: test/schema-tokens.test.ts reuses measure()/asK() to pin the
 // published number, so the CLI half must not run on import.
-const isCli = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+// realpath BOTH sides. Node realpaths the ESM main entry but leaves
+// process.argv[1] as resolve(cwd, arg), so any checkout reached through a
+// symlink (macOS /tmp -> /private/tmp, npm link, a symlinked working dir) made
+// these differ and the CLI half silently did nothing at exit 0.
+const isCli = process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
 if (!isCli) { /* library use */ } else await main();
 
 async function main() {
@@ -207,7 +237,18 @@ for (const profile of PROFILES) {
   const cmd = userCmd.length
     ? userCmd
     : ["node", SERVER, ...(profile && profile !== "full" ? ["--profile", profile] : [])];
-  results[profile ?? userCmd.join(" ")] = measure(await listTools(cmd), PREFIX);
+  const tools = await listTools(cmd);
+  // A profile that projects nothing is a broken measurement, not a small one.
+  // Every figure downstream (the README table, the badge, the percentage) is
+  // derived from these totals, and printing 0 with exit 0 publishes a wrong
+  // number rather than reporting a failure.
+  if (tools.length === 0) {
+    throw new Error(
+      `${cmd.join(" ")} listed no tools for profile "${profile ?? "custom"}" — ` +
+      `refusing to report a measurement of zero.`,
+    );
+  }
+  results[profile ?? userCmd.join(" ")] = measure(tools, PREFIX);
 }
 
 if (flags.has("--svg")) {
diff --git a/scripts/polymarket-e2e-approve.ts b/scripts/polymarket-e2e-approve.ts
index 8ce8159..b31473c 100644
--- a/scripts/polymarket-e2e-approve.ts
+++ b/scripts/polymarket-e2e-approve.ts
@@ -3,8 +3,18 @@
  * batch (including the two collateral-adapter operators redeem requires),
  * then re-reads the resulting on-chain state. Prints no wallet address or
  * transaction id. From @KillerQueen-Z's #66.
+ *
+ * Signs on-chain approvals with the real wallet, so it refuses to run without
+ * --confirm (or POLYMARKET_E2E_CONFIRM=1) — see ./e2e-confirm.ts.
  */
 import { runSetup } from "../src/utils/polymarket/setup.js";
+import { requireLiveConfirm } from "./e2e-confirm.js";
+import { failRedacted, installRedactedExit } from "./redact.js";
+
+installRedactedExit();
+requireLiveConfirm([
+  "sign and submit the Polymarket operator approval batch (unlimited allowances unless POLYMARKET_BOUNDED_APPROVALS is set) from the funded wallet",
+]);
 
 try {
   const submitted = await runSetup({ confirm: true });
@@ -16,7 +26,5 @@ try {
     approvalsPending: verified.structured.approvalsPending,
   }, null, 2));
 } catch (error) {
-  const message = error instanceof Error ? error.message : String(error);
-  console.error(JSON.stringify({ failed: true, error: message.replace(/0x[a-fA-F0-9]{40,}/g, "<redacted>") }));
-  process.exitCode = 1;
+  failRedacted("", error);
 }
diff --git a/scripts/polymarket-e2e-live.ts b/scripts/polymarket-e2e-live.ts
index 56ea147..0ac6af4 100644
--- a/scripts/polymarket-e2e-live.ts
+++ b/scripts/polymarket-e2e-live.ts
@@ -4,10 +4,26 @@
  * moving more than $2.00. Wallet addresses and transaction IDs are never
  * printed. From @KillerQueen-Z's #66; success check updated for the tri-state
  * redeem statuses main ships (only status:"redeemed" counts).
+ *
+ * The redaction covers every exit path, thrown errors included — see
+ * ./redact.ts for why that is not the same regex it used to be.
+ *
+ * Moves real funds, so it refuses to run without --confirm (or
+ * POLYMARKET_E2E_CONFIRM=1) — see ./e2e-confirm.ts. `npm run
+ * e2e:polymarket:live -- --confirm`.
  */
 import { fetchPositions, getFundsAddress } from "../src/utils/polymarket/positions.js";
 import { redeemPosition } from "../src/utils/polymarket/redeem.js";
 import { withdrawFunds } from "../src/utils/polymarket/withdraw.js";
+import { requireLiveConfirm } from "./e2e-confirm.js";
+import { failRedacted, installRedactedExit, redactChainValues } from "./redact.js";
+
+installRedactedExit();
+// Gate first: a check that runs after the redeem is a receipt.
+requireLiveConfirm([
+  "redeem one resolved position worth <= $0.001 (burns the shares)",
+  "withdraw $2.00 USDC from the Polymarket deposit wallet through the bridge",
+]);
 
 const owner = getFundsAddress();
 const positions = await fetchPositions(owner);
@@ -23,12 +39,12 @@ if (!target?.conditionId) {
 
 const redeem = await redeemPosition({ condition_id: target.conditionId, confirm: true });
 if (redeem.isError || redeem.structured?.status !== "redeemed") {
-  throw new Error(`Redeem verification did not complete cleanly: ${redeem.text.replace(/0x[a-fA-F0-9]{64}/g, "<tx>")}`);
+  failRedacted("Redeem verification did not complete cleanly: ", redactChainValues(redeem.text));
 }
 
 const withdrawal = await withdrawFunds({ amount_usd: 2, confirm: true });
 if (withdrawal.isError) {
-  throw new Error(`Withdrawal submission failed: ${withdrawal.text.replace(/0x[a-fA-F0-9]{64}/g, "<tx>")}`);
+  failRedacted("Withdrawal submission failed: ", redactChainValues(withdrawal.text));
 }
 
 console.log(JSON.stringify({
diff --git a/scripts/polymarket-e2e-readonly.ts b/scripts/polymarket-e2e-readonly.ts
index e2adc94..741759c 100644
--- a/scripts/polymarket-e2e-readonly.ts
+++ b/scripts/polymarket-e2e-readonly.ts
@@ -1,17 +1,30 @@
 /**
  * Read-only local-wallet preflight for Polymarket redeem/withdraw changes.
  * Never supplies confirm:true; never emits a wallet address, private key, or
- * transaction identifier. From @KillerQueen-Z's #66.
+ * transaction identifier — on any exit path, a thrown RPC error included
+ * (installRedactedExit below; the header promise used to hold only for the
+ * isError branch).
+ *
+ * An error is reported AS an error. listPositions() catches every failure
+ * and returns `{ text, isError: true }` with no `structured`, and this script
+ * used to read `structured?.positions ?? []` and print `positions: []` under
+ * a success-shaped JSON — so a Data-API outage looked like an empty wallet,
+ * and an operator concluded there was nothing to redeem. Now either side
+ * failing prints the redacted message in its place and exits 1.
+ * From @KillerQueen-Z's #66.
  */
 import { listPositions } from "../src/utils/polymarket/positions.js";
 import { withdrawFunds } from "../src/utils/polymarket/withdraw.js";
+import { installRedactedExit, redactChainValues } from "./redact.js";
+
+installRedactedExit();
 
 const [positionsResult, withdrawalResult] = await Promise.all([
   listPositions(),
   withdrawFunds({}),
 ]);
 
-const positions = ((positionsResult.structured as {
+const positions = positionsResult.isError ? { error: redactChainValues(positionsResult.text) } : ((positionsResult.structured as {
   positions?: Array<{
     title?: string;
     outcome?: string;
@@ -31,10 +44,12 @@ const positions = ((positionsResult.structured as {
   condition: position.conditionId ? `${position.conditionId.slice(0, 10)}…` : undefined,
 }));
 
+const failed = Boolean(positionsResult.isError || withdrawalResult.isError);
 console.log(JSON.stringify({
+  ok: !failed,
   positions,
   withdrawalPreview: withdrawalResult.isError
-    ? withdrawalResult.text.replace(/0x[a-fA-F0-9]{40}/g, "<wallet>")
+    ? redactChainValues(withdrawalResult.text)
     : {
       dryRun: withdrawalResult.structured?.dryRun,
       amountUsd: withdrawalResult.structured?.amountUsd,
@@ -44,3 +59,4 @@ console.log(JSON.stringify({
       toChainId: withdrawalResult.structured?.toChainId,
     },
 }, null, 2));
+if (failed) process.exit(1);
diff --git a/scripts/polymarket-e2e-verify-approvals.ts b/scripts/polymarket-e2e-verify-approvals.ts
index e70c3ba..a9d9ec4 100644
--- a/scripts/polymarket-e2e-verify-approvals.ts
+++ b/scripts/polymarket-e2e-verify-approvals.ts
@@ -1,5 +1,13 @@
-/** Read-only: report the on-chain approval state for the local wallet. */
+/**
+ * Read-only: report the on-chain approval state for the local wallet. Never
+ * supplies confirm:true. Prints no wallet address on any exit path — the
+ * on-chain reads go through a Polygon RPC, and a viem error interpolates the
+ * owner address into its message, so the redacted exit is installed first.
+ */
 import { runSetup } from "../src/utils/polymarket/setup.js";
+import { installRedactedExit } from "./redact.js";
+
+installRedactedExit();
 
 const result = await runSetup({ confirm: false });
 const approvals = result.structured.approvals as Array<{ label: string; granted: boolean }>;
diff --git a/scripts/polymarket-e2e-withdraw.ts b/scripts/polymarket-e2e-withdraw.ts
index 855d428..e6f5eb5 100644
--- a/scripts/polymarket-e2e-withdraw.ts
+++ b/scripts/polymarket-e2e-withdraw.ts
@@ -1,9 +1,23 @@
-/** Bounded live withdrawal check ($2 cap), independent of the approval flow. From #66. */
+/**
+ * Bounded live withdrawal check ($2 cap), independent of the approval flow.
+ * Wallet addresses and transaction ids are never printed, on any exit path.
+ * From #66.
+ *
+ * Moves real funds, so it refuses to run without --confirm (or
+ * POLYMARKET_E2E_CONFIRM=1) — see ./e2e-confirm.ts.
+ */
 import { withdrawFunds } from "../src/utils/polymarket/withdraw.js";
+import { requireLiveConfirm } from "./e2e-confirm.js";
+import { failRedacted, installRedactedExit, redactChainValues } from "./redact.js";
 
-const result = await withdrawFunds({ amount_usd: 2, confirm: true });
+installRedactedExit();
+requireLiveConfirm(["withdraw $2.00 USDC from the Polymarket deposit wallet through the bridge"]);
+
+const result = await withdrawFunds({ amount_usd: 2, confirm: true }).catch((error) =>
+  failRedacted("Withdrawal submission threw: ", error),
+);
 if (result.isError) {
-  throw new Error(result.text.replace(/0x[a-fA-F0-9]{64}/g, "<tx>"));
+  failRedacted("", redactChainValues(result.text));
 }
 console.log(JSON.stringify({
   submitted: true,
diff --git a/scripts/redact.ts b/scripts/redact.ts
new file mode 100644
index 0000000..e217d9b
--- /dev/null
+++ b/scripts/redact.ts
@@ -0,0 +1,54 @@
+/**
+ * One redaction for every live Polymarket e2e script.
+ *
+ * These scripts run against a real funded wallet and their output goes into
+ * terminals, CI logs and issue comments. Three of them promised in their own
+ * doc comment that "wallet addresses and transaction IDs are never printed",
+ * and each implemented a different regex: `{64}` (transaction hashes only, so
+ * a 40-hex ADDRESS printed in full), `{40}` (addresses only), and `{40,}`
+ * (both, but labelled `<redacted>` either way). The first is the one that
+ * broke the promise, and withdraw.ts really does interpolate a bridge response
+ * carrying an address into its error text.
+ *
+ * Longest-match-first in a single pass, so there is no ordering trap: a
+ * transaction hash cannot be half-eaten by the address rule. A private key is
+ * also 32 bytes and comes out as `<tx>` — mislabelled but redacted, which is
+ * the direction that matters.
+ */
+export function redactChainValues(text: string): string {
+  return text.replace(/0x[a-fA-F0-9]{40,}/g, (match) => {
+    if (match.length === 66) return "<tx>";
+    if (match.length === 42) return "<wallet>";
+    return "<redacted>";
+  });
+}
+
+/**
+ * Redact whatever a script is about to die with.
+ *
+ * The `isError` branch of a tool result was the only path any of these guarded.
+ * A thrown exception — a network failure inside fetchPositions(), a viem revert
+ * — bypassed it entirely and Node printed the raw message and stack. Install
+ * this and every exit path is covered.
+ */
+export function failRedacted(prefix: string, error: unknown): never {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(JSON.stringify({ failed: true, error: redactChainValues(`${prefix}${message}`) }));
+  process.exit(1);
+}
+
+/**
+ * Route every uncaught exception and unhandled rejection through failRedacted.
+ *
+ * Call it before the first await. Only -live.ts had these two lines; the
+ * other four scripts either wrapped one call in try/catch (fine until a
+ * second call is added outside it) or had nothing at all — and the read-only
+ * preflight, whose header promises it never emits a wallet address, would
+ * have printed one on the first RPC failure. One installer means the promise
+ * is kept by every script the same way, and test/redact-exit.test.ts checks
+ * that each one calls it.
+ */
+export function installRedactedExit(): void {
+  process.on("uncaughtException", (error) => failRedacted("", error));
+  process.on("unhandledRejection", (error) => failRedacted("", error));
+}
diff --git a/scripts/smoke-speech-plan.ts b/scripts/smoke-speech-plan.ts
new file mode 100644
index 0000000..ae120c9
--- /dev/null
+++ b/scripts/smoke-speech-plan.ts
@@ -0,0 +1,36 @@
+/**
+ * What scripts/smoke-speech.ts is about to charge, computed from the same
+ * estimator the tool reserves with — never typed by hand.
+ *
+ * The header used to say "$0.001 speak" and "$0.054 total". The 51-character
+ * speak on flash-v2.5 reserves (51/1000) x $0.05 x 1.05 = $0.0026775 plus the
+ * tx fee, ceiled: $0.004678 — and the run is $0.059179, not $0.054. The 0.50.0
+ * changelog claimed the script "states the real total" while the figures it
+ * asked the operator to authorise were the old ones. A confirm gate that
+ * quotes the wrong price is the thing the gate exists to prevent.
+ *
+ * Kept out of smoke-speech.ts so a test can import it: importing the script
+ * itself runs the paid calls.
+ */
+import { speechCost } from "../src/tools/speech.js";
+import { withTxFee } from "../src/utils/tx-fee.js";
+
+export const SPEAK_MODEL = "elevenlabs/flash-v2.5";
+export const SPEAK_INPUT = "Hello from BlockRun. Pay per call, no subscription.";
+export const SOUND_EFFECT_INPUT = "soft rain on a tin roof with distant thunder";
+
+/**
+ * Mirrors SOUND_EFFECT_COST in src/tools/speech.ts, which is not exported:
+ * $0.05 base x 1.05 margin, plus the tx fee, ceiled to the micro — the
+ * live-verified 54501 micro. If speech.ts ever exports its constant, import
+ * it here instead of restating the formula.
+ */
+export const SOUND_EFFECT_USD = withTxFee(0.05 * 1.05);
+
+export function smokeSpeechPlan(): { speakUsd: number; soundEffectUsd: number; totalUsd: number } {
+  const speakUsd = speechCost(SPEAK_MODEL, SPEAK_INPUT);
+  const soundEffectUsd = SOUND_EFFECT_USD;
+  return { speakUsd, soundEffectUsd, totalUsd: Math.round((speakUsd + soundEffectUsd) * 1e6) / 1e6 };
+}
+
+export const usd = (n: number) => `$${n.toFixed(6).replace(/0+$/, "").replace(/\.$/, ".0")}`;
diff --git a/scripts/smoke-speech.ts b/scripts/smoke-speech.ts
index 2a019c3..f268384 100644
--- a/scripts/smoke-speech.ts
+++ b/scripts/smoke-speech.ts
@@ -1,7 +1,43 @@
-// One-off smoke test for blockrun_speech. Run: npx tsx scripts/smoke-speech.ts
-// Exercises: voices (fallback path), over-length free-fail, real $0.001 speak.
+/**
+ * One-off smoke test for blockrun_speech. SPENDS REAL USDC — about six cents
+ * per run (the exact figure is printed by the gate, computed from the
+ * estimator), from the machine-global wallet at ~/.blockrun/.session.
+ *
+ * Run: npx tsx scripts/smoke-speech.ts --confirm
+ *
+ * The flag is not ceremony. The header used to say "real $0.001 speak" while
+ * the run ends with a sound effect fifty times that, and a bare
+ * `npx tsx scripts/smoke-speech.ts` charged for both immediately. This repo
+ * has already lost $0.42 to a subagent that ran a paid handler because it
+ * looked like a read. Nothing in scripts/ should spend money by being run.
+ *
+ * The figures are NOT typed here. The gate once quoted "$0.001 speak, $0.054
+ * total" for a run the estimator reserves $0.004678 + $0.054501 = $0.059179
+ * for — a confirm gate that understates the charge is the defect it exists
+ * to prevent. ./smoke-speech-plan.ts computes them from speechCost() and
+ * test/smoke-speech-plan.test.ts pins them; this file may not contain a
+ * dollar literal other than the cap.
+ *
+ * The budget limit below is a second backstop: if a price moves or a retry
+ * doubles a call, the run stops instead of draining the wallet.
+ *
+ * Exercises: voices (fallback path), over-length free-fail, speak,
+ * sound_effect.
+ */
 import { registerSpeechTool } from "../src/tools/speech.js";
 import type { BudgetState } from "../src/types.js";
+import { SOUND_EFFECT_INPUT, SPEAK_INPUT, SPEAK_MODEL, smokeSpeechPlan, usd } from "./smoke-speech-plan.js";
+
+const SPEND_CAP_USD = 0.15;
+const plan = smokeSpeechPlan();
+
+if (!process.argv.includes("--confirm") && process.env.BLOCKRUN_SMOKE_CONFIRM !== "1") {
+  console.error(
+    `smoke-speech spends about ${usd(plan.totalUsd)} of real USDC (speak ${usd(plan.speakUsd)} + sound_effect ${usd(plan.soundEffectUsd)}).\n` +
+      "Re-run with --confirm, or set BLOCKRUN_SMOKE_CONFIRM=1, to authorise the charge.",
+  );
+  process.exit(1);
+}
 
 type Handler = (args: Record<string, unknown>) => Promise<{ content: Array<{ text: string }>; isError?: boolean }>;
 let handler: Handler;
@@ -9,7 +45,7 @@ const fakeServer = {
   registerTool: (_name: string, _cfg: unknown, h: Handler) => { handler = h; },
 } as never;
 
-const budget: BudgetState = { limit: null, spent: 0, calls: 0, agents: new Map() };
+const budget: BudgetState = { limit: SPEND_CAP_USD, spent: 0, calls: 0, agents: new Map() };
 registerSpeechTool(fakeServer, budget);
 
 async function run(label: string, args: Record<string, unknown>) {
@@ -22,7 +58,7 @@ async function run(label: string, args: Record<string, unknown>) {
 await run("voices", { action: "voices" });
 await run("over-length free-fail", { action: "speak", input: "x".repeat(6000), model: "elevenlabs/v3" });
 // Pass defaults explicitly — the stub bypasses the MCP SDK's zod parsing.
-await run("real speak ($0.001)", { action: "speak", input: "Hello from BlockRun. Pay per call, no subscription.", voice: "sarah", model: "elevenlabs/flash-v2.5", response_format: "mp3" });
+await run(`real speak (${usd(plan.speakUsd)})`, { action: "speak", input: SPEAK_INPUT, voice: "sarah", model: SPEAK_MODEL, response_format: "mp3" });
 console.log(`\nBudget spent: $${budget.spent.toFixed(4)} across ${budget.calls} calls`);
-await run("real sound_effect ($0.0525)", { action: "sound_effect", input: "soft rain on a tin roof with distant thunder", duration_seconds: 4, response_format: "mp3" });
+await run(`real sound_effect (${usd(plan.soundEffectUsd)})`, { action: "sound_effect", input: SOUND_EFFECT_INPUT, duration_seconds: 4, response_format: "mp3" });
 console.log(`\nFinal budget: $${budget.spent.toFixed(4)} across ${budget.calls} calls`);
diff --git a/scripts/stamp-server-json.mjs b/scripts/stamp-server-json.mjs
index 283c7fd..5b4cda7 100644
--- a/scripts/stamp-server-json.mjs
+++ b/scripts/stamp-server-json.mjs
@@ -20,9 +20,27 @@ if (!version || version.includes("template")) {
 
 const manifest = JSON.parse(readFileSync(join(root, "server.template.json"), "utf8"));
 manifest.version = version;
+let stamped = 0;
 for (const p of manifest.packages ?? []) {
   // Pin the registry entry to the exact npm version we publish.
-  if (p.identifier === pkg.name) p.version = version;
+  if (p.identifier === pkg.name) { p.version = version; stamped++; }
+}
+
+// The input was guarded against a placeholder; the OUTPUT was not. With no
+// matching entry this loop did nothing, the template's own "0.0.0-template"
+// survived into server.json -- valid semver, so `mcp-publisher validate`
+// passes it -- and the success line below announced a stamp that never
+// happened. publish.yml would then point PulseMCP, Glama and the rest of the
+// registry consumers at an npm version that does not exist. One rename of the
+// package, one typo in the template, or one registry schema change away.
+if (stamped === 0) {
+  console.error(
+    `Refusing to stamp: no package entry in server.template.json has ` +
+    `identifier "${pkg.name}" (found: ` +
+    `${(manifest.packages ?? []).map((p) => JSON.stringify(p.identifier)).join(", ") || "none"}). ` +
+    `server.json would ship the template's placeholder version.`,
+  );
+  process.exit(1);
 }
 
 writeFileSync(join(root, "server.json"), JSON.stringify(manifest, null, 2) + "\n");
diff --git a/scripts/sync-brand-numbers.mjs b/scripts/sync-brand-numbers.mjs
index dee309b..bd4ab15 100644
--- a/scripts/sync-brand-numbers.mjs
+++ b/scripts/sync-brand-numbers.mjs
@@ -18,6 +18,19 @@
  * Markers look like:  <!-- br:models.chatVisible -->66<!-- /br:models.chatVisible -->
  * and wrap the WHOLE token, so a badge URL, its alt text and the prose number
  * can all regenerate from one key.
+ *
+ * THIS COPY IS AHEAD OF THE SOURCE. blockrun's `brand-script-sync` CI job
+ * diffs every consumer against brand/sync-brand-numbers.mjs and its printed
+ * remediation is "copy the source over the consumer" — twice that overwrote a
+ * fix made here (#84, #128). What this copy carries that the source does not,
+ * as of 2026-09-13: assertRenderable + escAttr (a value from the mirror is
+ * refused, and attribute-escaped, before it is written into a README that the
+ * brand-sync bot then pushes unattended with contents:write), keyOf() on the
+ * keys-in-use count, and the --check summary that does not say "up to date"
+ * under a list of stale fenced markers. Resync source <- consumer: land THIS
+ * file in blockrun/brand and fan it out; do not copy the source over it.
+ * test/brand-sync-script.test.ts fails on a copy without the guard, so a
+ * consumer <- source resync cannot pass this repo's required `test` check.
  */
 import { execFileSync } from "node:child_process";
 import { existsSync, lstatSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
@@ -101,15 +114,58 @@ function flatten(obj, prefix = "") {
  * Renderers are registered under the FULL marker name so a badge's label is
  * written out rather than guessed from the key.
  */
+/**
+ * What a brand value is allowed to be, checked at the moment it is USED.
+ *
+ * These values arrive over the network from blockrun.ai (or the
+ * awesome-blockrun mirror) and are written verbatim into README.md,
+ * CONTRIBUTING.md and skills/*\/SKILL.md, which `.github/workflows/brand-sync.yml`
+ * then commits and pushes to the default branch weekly, unattended, with
+ * `contents: write`. Rendering was `String(value)` and the badge renderer
+ * interpolated straight into `src="..."` and `alt="..."`, so a value carrying
+ * a quote or an angle bracket closed the attribute and injected markup into
+ * every consuming repo's README. Write access to one mirror repo was enough.
+ *
+ * Checked here rather than over the whole artifact on purpose: the payload
+ * legitimately carries prose fields we never render (`savings.baselineModel`
+ * is a string), and refusing those would break the sync on an unrelated
+ * addition upstream.
+ */
+const SAFE_TEXT = /^[\p{L}\p{N} .,%+/·—–-]{1,64}$/u;
+
+function assertRenderable(marker, value) {
+  const what = () => `${marker} = ${JSON.stringify(value)}`;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) fail(`brand-numbers: refusing to render ${what()} — not a finite number`);
+    return value;
+  }
+  if (typeof value === "string") {
+    if (!SAFE_TEXT.test(value)) {
+      fail(
+        `brand-numbers: refusing to render ${what()} — a rendered value must be ` +
+        `a number or a short plain label. This value would be written verbatim ` +
+        `into README/CONTRIBUTING/SKILL.md and pushed by the brand-sync bot.`,
+      );
+    }
+    return value;
+  }
+  fail(`brand-numbers: refusing to render ${what()} — expected a number or a string, got ${Array.isArray(value) ? "an array" : typeof value}`);
+}
+
+/** Escape for an HTML attribute. Belt to assertRenderable's braces. */
+const escAttr = (v) =>
+  String(v).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+
 const badge = (label) => (n) =>
-  `<img src="https://img.shields.io/badge/${label}-${n}-5B9BF6?style=flat-square&labelColor=0B0A0F" alt="${n} ${label}">`;
+  `<img src="https://img.shields.io/badge/${label}-${escAttr(n)}-5B9BF6?style=flat-square&labelColor=0B0A0F" alt="${escAttr(n)} ${label}">`;
 
 const RENDER = {
   "mcp.tools@badge": badge("tools"),
   "models.totalVisible@badge": badge("models"),
   "models.chatVisible@badge": badge("models"),
 };
-const render = (marker, value) => (RENDER[marker] ?? String)(value);
+const render = (marker, value) => (RENDER[marker] ?? String)(assertRenderable(marker, value));
 
 /** `mcp.tools@badge` looks up `mcp.tools`. Unmodified markers are unaffected. */
 const keyOf = (marker) => marker.split("@")[0];
@@ -308,7 +364,8 @@ const everUsed = new Set();
 
 for (const file of walk(ROOT)) {
   const { before, after, changed, used } = syncFile(file, numbers, problems, skipped);
-  used.forEach((k) => everUsed.add(k));
+  // keyOf: mcp.tools and mcp.tools@badge are ONE key in use, not two.
+  used.forEach((k) => everUsed.add(keyOf(k)));
   if (!changed) continue;
   drifted.push({ file: relative(ROOT, file), before, after });
   if (!check) writeFileSync(file, after);
@@ -332,7 +389,16 @@ if (problems.length) {
 
 if (check) {
   if (drifted.length === 0) {
-    console.log(`brand-numbers: up to date (${everUsed.size} keys in use)`);
+    // Do not say "up to date" straight after listing markers known to be
+    // stale. The skip stays non-fatal for the reason above, but a CI log that
+    // prints the stale ones and then declares everything current is a log
+    // nobody reads twice.
+    console.log(
+      skipped.length
+        ? `brand-numbers: no drift outside code fences (${everUsed.size} keys in use), ` +
+          `but ${skipped.length} fenced marker(s) listed above are stale — add @live to sync them`
+        : `brand-numbers: up to date (${everUsed.size} keys in use)`,
+    );
     process.exit(0);
   }
   console.error("brand-numbers: these files disagree with brand-numbers.json\n");
diff --git a/scripts/verify-prices-verdict.ts b/scripts/verify-prices-verdict.ts
new file mode 100644
index 0000000..564de62
--- /dev/null
+++ b/scripts/verify-prices-verdict.ts
@@ -0,0 +1,91 @@
+// scripts/verify-prices-verdict.ts — the exit decision of `npm run verify:prices`.
+//
+// Split out of verify-prices.ts so the decision can be tested without probing
+// the network (the script itself is top-level `await` over sixty live 402
+// probes and cannot be imported by a test). Pure: tallies in, exit code and
+// summary lines out.
+//
+// WHY THIS IS ITS OWN DECISION: only a confirmed under-reserve failed the run.
+// `unreachable` — no 402, an undecodable header, a missing `amount` — printed a
+// warning and exit 0, so the day the gateway renamed a header field every row
+// printed `?` and the release gate went green having verified nothing. A gate
+// that cannot tell "checked and fine" from "could not check" is not a gate.
+//
+// Exit codes are deliberately distinct so a caller can tell them apart:
+//   0  every probe and every catalogue was read, nothing under-reserves
+//   1  a CONFIRMED under-reserve — an estimator, or the price table, reserves
+//      less than a gateway charges. Fix the estimator before publishing.
+//   2  the run could not verify enough to say: more than UNREACHABLE_FRACTION
+//      of the routes, or any catalogue, could not be read. Fix the probe (or
+//      wait out the outage) and run again. NEVER read as pass.
+// When both apply, 1 wins — money is the more urgent message — but the
+// unverified rows are still named so a partial run is never mistaken for a
+// complete one.
+
+export type Tally = {
+  /** Routes the script tried to probe. */
+  probes: number;
+  /** Base charges more than the estimator reserves. */
+  short: number;
+  /** Solana charges more than the estimator reserves. */
+  solShort: number;
+  /** Probes that produced no usable quote (no 402, bad header, no `amount`). */
+  unreachable: number;
+  /** Live chat models the price table under-reserves (any catalogue). */
+  catalogueGaps: number;
+  /** Catalogues the script tried to read (Base, Solana, the account-rail sheet). */
+  catalogues: number;
+  /** Catalogues that could not be read. */
+  catalogueUnreachable: number;
+};
+
+export type Verdict = { code: 0 | 1 | 2; lines: string[] };
+
+/**
+ * A quarter. A single transient miss (one route mid-deploy, one 5xx) should
+ * not block a release — the row prints `?` and the operator re-runs. A quarter
+ * of the matrix is not transient: at that point the probe method or the
+ * network is broken, and "verified" would be a lie about 15+ estimators.
+ */
+export const UNREACHABLE_FRACTION = 0.25;
+
+export function verdict(t: Tally): Verdict {
+  const lines: string[] = [];
+
+  const unverified = t.probes === 0 || t.unreachable > t.probes * UNREACHABLE_FRACTION;
+  if (t.probes === 0) {
+    lines.push("no routes were probed — the probe list is empty, so nothing was verified.");
+  } else if (unverified) {
+    lines.push(
+      `${t.unreachable} of ${t.probes} routes could not be verified (above the ${UNREACHABLE_FRACTION * 100}% tolerance). ` +
+        "Their estimators are NOT verified — fix the probe (has the 402 header shape changed?) or the network, then run again.",
+    );
+  } else if (t.unreachable) {
+    lines.push(
+      `${t.unreachable} unreachable route${t.unreachable === 1 ? "" : "s"} were NOT verified — treat them as unknown, not as passing.`,
+    );
+  }
+  if (t.catalogueUnreachable) {
+    lines.push(
+      `${t.catalogueUnreachable} of ${t.catalogues} price catalogues could not be read. ` +
+        "The catalogue sweep is the only check that sees a model the price table does NOT list — an unread catalogue is NOT verified.",
+    );
+  }
+
+  const money = t.short || t.solShort || t.catalogueGaps;
+  if (money) {
+    const why = [
+      t.short || t.solShort ? `an estimator reserves less than the gateway charges${t.solShort ? " (on Solana)" : ""}` : "",
+      t.catalogueGaps
+        ? `${t.catalogueGaps} live chat model${t.catalogueGaps === 1 ? "" : "s"} disagree${t.catalogueGaps === 1 ? "s" : ""} with the price table in a direction that costs money`
+        : "",
+    ].filter(Boolean).join("; ");
+    lines.push(`FAIL: ${why}. Fix it before publishing.`);
+    return { code: 1, lines };
+  }
+  if (unverified || t.catalogueUnreachable) {
+    lines.push("UNVERIFIED: this run could not check enough to pass. Exit 2 — not a pass, not a confirmed under-reserve.");
+    return { code: 2, lines };
+  }
+  return { code: 0, lines };
+}
diff --git a/scripts/verify-prices.ts b/scripts/verify-prices.ts
index 0220db3..e48b69e 100644
--- a/scripts/verify-prices.ts
+++ b/scripts/verify-prices.ts
@@ -24,6 +24,25 @@
 // The header is x402Version 2, so the field is `amount` (micro-USDC). v1's
 // `maxAmountRequired` is absent; read that key and you get `null`, which reads
 // as "free" rather than raising. Hence the explicit check below.
+//
+// THE ACCOUNT RAIL (api.blockrun.ai, Bearer key, no tx fee) CANNOT BE PROBED
+// PER ROUTE. Probed 2026-09-13: with no credential, or an invalid one, every
+// path answers 401 `invalid_api_key` — including GET /v1/models — and there is
+// no dry-run or quote-only header. With a VALID key a paid route bills; that is
+// the rail's whole design, and a script that attaches a real key to sixty
+// routes is a script that spends. So the per-route rows below stay wallet-
+// only, and the account rail is covered where it CAN be, for free: it prices
+// chat "from this sheet by design" (blockrun's src/lib/models.ts), and the
+// sheet is public at blockrun.ai/api/pricing. The catalogue sweep reads it as
+// a third source. What this does NOT cover on the account rail: media, pm,
+// modal, search, exa, phone — every non-chat estimator is verified on the
+// wallet gateways only, and the account rail's ledger books whatever
+// x-blockrun-cost-usd says (an overrun past the reserve is visible there, after
+// the fact, not here). That is a known gap, not an oversight.
+//
+// EXIT CODES: 0 verified clean; 1 a confirmed under-reserve; 2 the run could
+// not verify enough to say (see ./verify-prices-verdict.ts). 2 exists because
+// this used to exit 0 with every row printing `?`.
 import { estimateModalCost } from "../src/tools/modal.js";
 import { estimatePhoneCost } from "../src/tools/phone.js";
 import { estimateSearchCost } from "../src/tools/search.js";
@@ -34,6 +53,7 @@ import { estimateVideoCost } from "../src/tools/video.js";
 import { MARKETS_PRICE_USD } from "../src/tools/markets.js";
 import { withTxFee } from "../src/utils/tx-fee.js";
 import { CHAT_PRICE_PER_MTOKEN, DEFAULT_CHAT_PRICE, FREE_CHAT_MODELS, MODEL_TIERS } from "../src/utils/constants.js";
+import { verdict } from "./verify-prices-verdict.js";
 
 // TWO gateways, and they do not agree. Base and Solana are separate deployments
 // with separate env, and TRANSACTION_FEE_USD is env-overridable in the gateway —
@@ -52,6 +72,11 @@ import { CHAT_PRICE_PER_MTOKEN, DEFAULT_CHAT_PRICE, FREE_CHAT_MODELS, MODEL_TIER
 // users, which is a release blocker exactly like a Base shortfall.
 const BASE = "https://blockrun.ai/api/v1/";
 const SOL = "https://sol.blockrun.ai/api/v1/";
+// The public price sheet the ACCOUNT rail bills chat from (see the header).
+// Free, unauthenticated, and not the /v1/models population: it carries the
+// hidden-but-served SKUs that the catalogue omits, which is exactly the set
+// api.blockrun.ai settled at $0 for a week because nothing priced them (#516).
+const ACCOUNT_SHEET = "https://blockrun.ai/api/pricing";
 
 type Probe = {
   label: string;
@@ -62,6 +87,11 @@ type Probe = {
   // which model a tier will settle on until after the call). For those, over-
   // reserving is the design, not drift — but under-reserving is still a bug.
   allowOver?: boolean;
+  // A combination the CLIENT refuses before payment, probed to check that the
+  // gateway refuses it too. An unpaid 4xx with no 402 is the expected answer
+  // and counts as verified, not unreachable; a quote is the finding — the
+  // gateway sells a tier this client's guard says it cannot render.
+  expectRefused?: boolean;
 };
 
 type Quote = { usd: number; description?: string };
@@ -179,13 +209,15 @@ const PROBES: Probe[] = [
     ["bytedance/seedance-2.5", 30, undefined],
     // A combination the client-side guard REFUSES, probed anyway because a
     // guard is a claim about the gateway and this is the only thing checking
-    // it: the gateway still QUOTES 2.5@1080p ($3.55) even though token360
-    // rejects it at submit (probed 2026-08-07) — a known gateway defect, fixed
-    // by blockrun PR #353. Once that deploys, this probe reports `no 402` and
-    // the guard is vindicated. (2.0@360p left the matrix: 360p is out of the
-    // schema for every model and out of this client's enum, so the estimator
-    // now throws on it — it can no longer even be expressed from here.)
-    ["bytedance/seedance-2.5", undefined, "1080p"],
+    // it. The gateway used to QUOTE 2.5@1080p ($3.55) even though token360
+    // rejected it at submit (probed 2026-08-07); blockrun PR #353 deployed and
+    // since 2026-09-15 the probe answers 400 with no 402 — the guard is
+    // vindicated, and the row is marked so that answer reads as verified
+    // rather than as an unreachable route. (2.0@360p left the matrix: 360p is
+    // out of the schema for every model and out of this client's enum, so the
+    // estimator now throws on it — it can no longer even be expressed from
+    // here.)
+    ["bytedance/seedance-2.5", undefined, "1080p", true],
     // Each model probed at (or near) its ceiling and floor tier, so a gateway
     // whose capability surface diverges from SEEDANCE_RESOLUTIONS — in either
     // direction — shows up here as `no 402` or a price mismatch. 1.5-pro@1080p
@@ -195,9 +227,10 @@ const PROBES: Probe[] = [
     ["bytedance/seedance-2.0-fast", undefined, "480p"],
     ["bytedance/seedance-2.5", undefined, "480p"],
     ["bytedance/seedance-2.0", undefined, "480p"],
-  ] as Array<[string, number | undefined, string | undefined]>).map(([model, seconds, resolution]) => ({
+  ] as Array<[string, number | undefined, string | undefined, boolean?]>).map(([model, seconds, resolution, expectRefused]) => ({
     label: `video ${model.split("/")[1]}${seconds ? ` ${seconds}s` : ""}${resolution ? ` ${resolution}` : ""}`,
     path: "videos/generations",
+    ...(expectRefused ? { expectRefused: true } : {}),
     body: {
       model,
       prompt: "a cube rotating",
@@ -299,6 +332,21 @@ for (const probe of PROBES) {
     quote(BASE, probe.path, probe.body),
     quote(SOL, probe.path, probe.body),
   ]);
+  if (probe.expectRefused) {
+    // The guard says this cannot render; the gateway is expected to refuse
+    // it unpaid. Either side quoting it is the finding, on whichever chain.
+    const refused = (q: Quote | string) => typeof q === "string" && /no 402 \(HTTP 4\d\d\)/.test(q);
+    if (refused(liveQ) && refused(solQ)) {
+      console.log(`  ✓  ${probe.label.padEnd(26)} refused unpaid on both gateways, as the client-side guard expects`);
+    } else {
+      const sold = [
+        !refused(liveQ) ? `Base ${typeof liveQ === "string" ? liveQ : `quotes $${liveQ.usd.toFixed(6)}`}` : "",
+        !refused(solQ) ? `Solana ${typeof solQ === "string" ? solQ : `quotes $${solQ.usd.toFixed(6)}`}` : "",
+      ].filter(Boolean).join("; ");
+      console.log(`  !  ${probe.label.padEnd(26)} the client refuses this tier but the gateway does not: ${sold} — the guard still blocks it before payment`);
+    }
+    continue;
+  }
   const live = typeof liveQ === "string" ? liveQ : liveQ.usd;
   const solLive = typeof solQ === "string" ? solQ : solQ.usd;
   const liveProduct = typeof liveQ === "string" ? undefined : product(liveQ.description);
@@ -384,7 +432,8 @@ console.log(
   `\n${short} under-reserving, ${over} over-reserving, ${unreachable} unreachable, ` +
     `${PROBES.length - short - over - unreachable} exact`,
 );
-if (unreachable) console.log("Unreachable routes were NOT verified — treat them as unknown, not as passing.");
+// The unreachable verdict is printed once, at the end, by verdict() — with the
+// exit code it now carries.
 
 console.log(
   `Solana: ${solShort} under-reserved (BLOCKER), ${solDearer} dearer than Base but covered, ${solCheaper} cheaper, ${solMissing} not served, ${solSubstituted} substituted`,
@@ -450,12 +499,43 @@ async function catalogue(host: string): Promise<CatalogueModel[] | string> {
   }
 }
 
+// The account rail's sheet, reshaped to the catalogue's row so one loop judges
+// all three sources. `inputPricePerMillion` is the billed rate (margin already
+// applied — chatMarginPercent is 0 today, but the field is the one that would
+// move if that changed); `inputPrice` is the pre-margin figure and is NOT what
+// settles. Long-context ladders (a model repricing above N input tokens) are
+// on the sheet too and are deliberately not compared: no estimator in this
+// repo models them, so they are a separate finding, not a row here.
+type SheetModel = { id: string; available?: boolean; billingMode?: string; inputPricePerMillion?: unknown; outputPricePerMillion?: unknown };
+
+async function accountSheet(): Promise<CatalogueModel[] | string> {
+  try {
+    const res = await fetch(ACCOUNT_SHEET);
+    if (!res.ok) return `HTTP ${res.status}`;
+    const body = (await res.json()) as { models?: unknown };
+    if (!Array.isArray(body.models)) return "no `models` array in the response";
+    return (body.models as SheetModel[]).map((m) => ({
+      id: m.id,
+      available: m.available,
+      pricing: { input: m.inputPricePerMillion, output: m.outputPricePerMillion },
+    }));
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+}
+
 const catalogueGaps: string[] = []; // fail
 const catalogueNotes: string[] = []; // report only
 let catalogueUnreachable = 0;
+const CATALOGUES: Array<[string, () => Promise<CatalogueModel[] | string>]> = [
+  ["Base", () => catalogue(BASE)],
+  ["Solana", () => catalogue(SOL)],
+  ["Account (pricing sheet)", accountSheet],
+];
 console.log("\nCatalogue sweep: every live chat model must be covered by its price row, by the default, or by FREE_CHAT_MODELS");
-for (const [name, host] of [["Base", BASE], ["Solana", SOL]] as const) {
-  const models = await catalogue(host);
+console.log("  (Base and Solana: GET /v1/models. Account rail: the public sheet api.blockrun.ai bills chat from — its other routes cannot be quoted without a key that would be charged.)");
+for (const [name, read] of CATALOGUES) {
+  const models = await read();
   if (typeof models === "string") {
     console.log(`  ?  ${name.padEnd(26)} ${models}`);
     catalogueUnreachable++;
@@ -471,7 +551,11 @@ for (const [name, host] of [["Base", BASE], ["Solana", SOL]] as const) {
     if (typeof input !== "number" || typeof output !== "number") continue;
     // Base marks retired rows `available:false`; Solana omits the field
     // entirely, and an omitted flag is a served model, not an unknown one.
-    if (m.available === false) continue;
+    //
+    // A model FREE_CHAT_MODELS claims is free is checked even when unavailable:
+    // the dangerous direction is a $0 reserve for a call that costs money, and
+    // "retired today" does not promise "still free when it comes back".
+    if (m.available === false && !FREE_CHAT_MODELS.has(m.id)) continue;
     checked++;
     listed.add(m.id);
     const isFree = FREE_CHAT_MODELS.has(m.id);
@@ -503,14 +587,23 @@ for (const [name, host] of [["Base", BASE], ["Solana", SOL]] as const) {
       catalogueNotes.push(`${name}: ${m.id} is billed $0 but FREE_CHAT_MODELS does not list it — an explicit call reserves the default, and an exhausted budget refuses a free call`);
     }
   }
-  for (const id of MODEL_TIERS.free) {
-    if (!listed.has(id)) catalogueNotes.push(`${name}: free[] routes ${id}, which the catalogue does not list — not a death certificate (gpt-oss-120b is hidden-alive); probe with a realistic POST before removing`);
+  // Every id we reserve $0 for, not just the routing tier — FREE_CHAT_MODELS is
+  // the classifier estimateChatCost actually consults, and it has members the
+  // tier list does not. An unlisted one is UNVERIFIED, not verified-free: the
+  // sweep can only price what the catalogue reports.
+  let unverifiedFree = 0;
+  for (const id of FREE_CHAT_MODELS) {
+    if (listed.has(id)) continue;
+    unverifiedFree++;
+    catalogueNotes.push(`${name}: reserves $0 for ${id}, which the catalogue does not list — UNVERIFIED, not confirmed free (delisting is not death: gpt-oss-120b is hidden-alive). Probe with a realistic POST before trusting or removing it`);
   }
-  console.log(`  ${gaps ? "✗" : "✓"}  ${name.padEnd(26)} ${checked} chat models checked, ${gaps} would settle above the reserve`);
+  console.log(
+    `  ${gaps ? "✗" : "✓"}  ${name.padEnd(26)} ${checked} chat models checked, ${gaps} would settle above the reserve` +
+      (unverifiedFree ? `, ${unverifiedFree} free-list members unverified (not in the catalogue)` : ""),
+  );
 }
 for (const g of catalogueGaps) console.log(`  ✗  ${g}`);
 for (const n of catalogueNotes) console.log(`  !  ${n}`);
-if (catalogueUnreachable) console.log("  A catalogue that could not be read was NOT verified — treat it as unknown, not as passing.");
 
 // Under-reserving is a release blocker: it means the budget cap is a lie. That is
 // true per CHAIN — an estimator built off Base is a lie on Solana the moment
@@ -518,11 +611,19 @@ if (catalogueUnreachable) console.log("  A catalogue that could not be read was
 // true for a catalogue model the table does not know: the gate reserves the
 // default for it, and the default is a claim about the catalogue.
 // Over-reserving only blocks affordable calls, so it warns without failing.
-if (short || solShort || catalogueGaps.length) {
-  const why = [
-    short || solShort ? `an estimator reserves less than the gateway charges${solShort ? " (on Solana)" : ""}` : "",
-    catalogueGaps.length ? `${catalogueGaps.length} live chat model${catalogueGaps.length === 1 ? "" : "s"} disagree${catalogueGaps.length === 1 ? "s" : ""} with the price table in a direction that costs money` : "",
-  ].filter(Boolean).join("; ");
-  console.log(`\nFAIL: ${why}. Fix it before publishing.`);
-  process.exit(1);
-}
+//
+// And a run that could not LOOK is not a run that passed: too many `?` rows, or
+// a catalogue that would not read, exits 2. The decision lives in
+// verify-prices-verdict.ts so a test can pin it without the network.
+const result = verdict({
+  probes: PROBES.length,
+  short,
+  solShort,
+  unreachable,
+  catalogueGaps: catalogueGaps.length,
+  catalogues: CATALOGUES.length,
+  catalogueUnreachable,
+});
+if (result.lines.length) console.log("");
+for (const line of result.lines) console.log(line);
+process.exit(result.code);
diff --git a/scripts/version-gate.mjs b/scripts/version-gate.mjs
new file mode 100644
index 0000000..cb1d287
--- /dev/null
+++ b/scripts/version-gate.mjs
@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// Refuse to publish a version that is not ABOVE what npm already serves.
+//
+//   node scripts/version-gate.mjs <package.json version> <npm latest | none>
+//
+// publish.yml's npm step was gated on `pkg != npm` — inequality, not order.
+// `npm publish` does not compare semver: without `--tag` it points `latest` at
+// whatever it just published, so a release PR that wrote 0.5.1 for 0.51.0
+// would have shipped and downgraded every `npx -y @blockrun/mcp@latest` user
+// to a build with 0.5-era price tables. That number is not hypothetical:
+// VERSION sat nine minors behind package.json, and the release tooling that
+// computes the next version reads VERSION.
+//
+// Plain Node on purpose — this runs before `npm ci`, so there is no `semver`
+// package to lean on. Exported for test/version-gate.test.ts; the CLI is what
+// the workflow calls.
+//
+// "none" (nothing on npm yet — npm's E404) passes; "unknown" (npm could not be
+// read at all) is refused; equal passes (that is the re-run of an
+// already-published version, which the workflow skips on its own); prereleases
+// and anything that is not X.Y.Z are refused, because the workflow has no
+// dist-tag path for them and a malformed string must not compare as 0.0.0.
+
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
+
+/** -1 / 0 / 1, numerically per component. Throws on anything that is not X.Y.Z. */
+export function compareSemver(a, b) {
+  const pa = a.match(SEMVER);
+  const pb = b.match(SEMVER);
+  if (!pa) throw new Error(`"${a}" is not a bare X.Y.Z version`);
+  if (!pb) throw new Error(`"${b}" is not a bare X.Y.Z version`);
+  for (let i = 1; i <= 3; i++) {
+    const d = Number(pa[i]) - Number(pb[i]);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+/** { ok: true } or { ok: false, reason } — never throws; a bad input is a refusal. */
+export function gate({ pkg, npm }) {
+  if (!SEMVER.test(pkg)) return { ok: false, reason: `package.json version "${pkg}" is not a bare X.Y.Z version — refusing to publish it` };
+  if (npm === "none") return { ok: true, reason: `nothing on npm yet — ${pkg} will be the first publish` };
+  // The workflow spells a registry/network failure "unknown" (only npm's own
+  // E404 is "none"). A gate that could not look has not passed: refuse, and
+  // say re-run — the one input where "none" and "unknown" differ is a
+  // package.json below latest during a registry blip, which is exactly the
+  // downgrade this script exists to stop.
+  if (npm === "unknown") return { ok: false, reason: `npm latest could not be read (registry or network failure) — cannot order ${pkg} against it, refusing; re-run the job` };
+  if (!SEMVER.test(npm)) return { ok: false, reason: `npm latest "${npm}" is not a bare X.Y.Z version — cannot order ${pkg} against it, refusing` };
+  const order = compareSemver(pkg, npm);
+  if (order < 0) {
+    return {
+      ok: false,
+      reason:
+        `package.json ${pkg} is LOWER than npm latest ${npm}. npm publish would accept it and it would become \`latest\`, ` +
+        `downgrading every \`npx -y @blockrun/mcp@latest\` user. Bump package.json (and VERSION) above ${npm}.`,
+    };
+  }
+  if (order === 0) return { ok: true, reason: `package.json ${pkg} == npm latest — already published, the workflow skips npm` };
+  return { ok: true, reason: `package.json ${pkg} > npm latest ${npm}` };
+}
+
+const isMain = process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href;
+if (isMain) {
+  const [pkg, npm] = process.argv.slice(2);
+  if (!pkg || !npm) {
+    console.error("usage: node scripts/version-gate.mjs <package.json version> <npm latest | none>");
+    process.exit(2);
+  }
+  const r = gate({ pkg, npm });
+  console[r.ok ? "log" : "error"](`version-gate: ${r.reason}`);
+  process.exit(r.ok ? 0 : 1);
+}
diff --git a/skills/blockrun/SKILL.md b/skills/blockrun/SKILL.md
index 68dfa4e..17c06a6 100644
--- a/skills/blockrun/SKILL.md
+++ b/skills/blockrun/SKILL.md
@@ -2,7 +2,7 @@
 name: blockrun
 description: |
   Pay-per-call access to AI models, real-time data, media generation and multi-chain RPC over
-  x402 micropayments (USDC on Base or Solana). No API keys, no accounts, no subscriptions.
+  x402 micropayments (USDC on Base or Solana), or a BlockRun account API key. No subscriptions.
   Start here when you have the BlockRun MCP installed and need to know WHICH tool answers a
   question, how the wallet works, or how to make a first call for free.
   TOOLS: blockrun_chat, blockrun_image, blockrun_video, blockrun_music, blockrun_speech,
diff --git a/skills/rpc/SKILL.md b/skills/rpc/SKILL.md
index f494803..e9362d7 100644
--- a/skills/rpc/SKILL.md
+++ b/skills/rpc/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: rpc
-description: Use when the user needs raw blockchain JSON-RPC access — contract reads (eth_call), native balances, blocks, transactions, logs, gas estimates, or any chain-native RPC method across 40 chains. One endpoint per chain via BlockRun's Tatum-backed gateway, $0.0030 per call, no node, no API key. Prefer blockrun_price / blockrun_dex / blockrun_surf when they already cover the question.
+description: Use when the user needs raw blockchain JSON-RPC access — contract reads (eth_call), native balances, blocks, transactions, logs, gas estimates, or any chain-native RPC method across 40 chains. One endpoint per chain via BlockRun's Tatum-backed gateway, $0.0030 per call, no node, no API key. Prefer blockrun_price / blockrun_dex / the paid tools when they already cover the question.
 triggers:
   - "rpc"
   - "json-rpc"
diff --git a/skills/search/SKILL.md b/skills/search/SKILL.md
index 47504db..dad6e37 100644
--- a/skills/search/SKILL.md
+++ b/skills/search/SKILL.md
@@ -32,7 +32,7 @@ blockrun_search({ body: {
 | Field | Required | Type | Notes |
 |---|---|---|---|
 | `query` | yes | string | Natural-language search query |
-| `sources` | no | string[] | Subset of `["web","news"]`. Default: both. Does NOT multiply price. |
+| `sources` | no | string[] | Subset of `["web","news"]`. Default: `["web"]` — pass both for news coverage. There is no X/Twitter source (removed upstream 2026-07-05; asking for `"x"` is refused before payment). Does NOT multiply price. |
 | `max_results` | no | number | 1–50, default 10. **Drives the price** — ~$0.0263 charged per source. Pass a small number to cap spend; the gateway prices the raw value and does not floor fractions. |
 | `from_date` | no | string | `YYYY-MM-DD` lower bound on result date |
 | `to_date` | no | string | `YYYY-MM-DD` upper bound |
@@ -42,9 +42,9 @@ blockrun_search({ body: {
 | User intent | `sources` setting |
 |---|---|
 | Breaking news / today's headlines | `["news"]` |
-| What's the CT / KOL sentiment on X | `["x"]` |
+| Social / X sentiment | not served — there is no X source; use `["news","web"]` and say so, or `blockrun_exa` for a targeted crawl |
 | Backgrounder / explainer / docs | `["web"]` |
-| General "find current info" question | omit — defaults to all three |
+| General "find current info" question | `["web","news"]` (omitting it searches the web only) |
 
 ## Worked Examples
 
@@ -55,12 +55,14 @@ blockrun_search({ body: { query: "Ethereum ETF approval SEC", sources: ["news","
 ```
 **Cost: ~$0.2110** (8 sources: $0.025 × 8 × 1.05 + $0.001).
 
-### 2. "What is X saying about Solana's latest outage?"
+### 2. "What happened in Solana's latest outage?"
 
 ```ts
-blockrun_search({ body: { query: "Solana outage today", sources: ["x"], max_results: 15 } })
+blockrun_search({ body: { query: "Solana outage today", sources: ["news","web"], max_results: 15 } })
 ```
-**Cost: ~$0.3948** (15 sources: $0.025 × 15 × 1.05 + $0.001).
+**Cost: ~$0.3948** (15 sources: $0.025 × 15 × 1.05 + $0.001). There is no
+X/Twitter source: `sources: ["x"]` is refused before payment with the live
+list, so do not promise "what X is saying" — say what the news and web say.
 
 ### 3. "Background on Pectra upgrade, last 90 days only"
 
diff --git a/skills/signal-to-trade-demo/SKILL.md b/skills/signal-to-trade-demo/SKILL.md
index 3a312aa..7cae43a 100644
--- a/skills/signal-to-trade-demo/SKILL.md
+++ b/skills/signal-to-trade-demo/SKILL.md
@@ -33,8 +33,10 @@ or preparing a fallback.
 
 ## 1. Private operator preflight
 
-- Confirm the Trading profile exposes nine tools and no image/video/media tool:
-  wallet, price, dex, markets, surf, defi, rpc, polymarket_read, polymarket.
+- Confirm the Trading profile exposes eight tools and no image/video/media tool:
+  wallet, price, dex, markets, defi, rpc, polymarket_read, polymarket.
+  (It was nine until 2026-09-06, when the gateway retired Surf and
+  `blockrun_surf` went with it — a preflight that still counts nine fails.)
 - Before screen sharing, the human operator may check `blockrun_wallet`, run
   setup, and inspect positions/orders. Never include those raw calls in the
   presentation conversation.
diff --git a/src/index.ts b/src/index.ts
index d18646f..d0d749a 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -105,8 +105,10 @@ async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
   // resolveTools falls back to "full" for a name it does not know. Say so:
-  // a user who typed `--profile tradng` wanted 9 tools and got 20, and the
-  // "20 tools" startup line alone reads as if the flag was honoured.
+  // a user who typed `--profile tradng` wanted the trading set and got the full
+  // one, and a startup line that states only the count reads as if the flag was
+  // honoured. (The numbers moved with the Surf removal; the point did not, so
+  // this says which profile rather than how many tools.)
   const requestedProfile = resolveProfileName();
   if (requestedProfile !== profile) {
     console.error(
diff --git a/src/mcp-handler.ts b/src/mcp-handler.ts
index 60caf61..27f7523 100644
--- a/src/mcp-handler.ts
+++ b/src/mcp-handler.ts
@@ -1,8 +1,9 @@
 // src/mcp-handler.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { BudgetState } from "./types.js";
-import { getClient, getWalletInfo } from "./utils/wallet.js";
-import { loadModels, type ModelCache } from "./utils/model-cache.js";
+import { getChain, getClient, getWalletInfo } from "./utils/wallet.js";
+import { loadModels, modelCacheKey, type ModelCache } from "./utils/model-cache.js";
+import { getAuthMode } from "./utils/auth.js";
 import { parseBudgetLimitEnv } from "./utils/budget.js";
 
 import { registerWalletTool } from "./tools/wallet.js";
@@ -92,7 +93,10 @@ export function initializeMcpServer(
     rpc: () => registerRpcTool(server, budget),
     defi: () => registerDefiTool(server, budget),
     polymarket_read: () => registerPolymarketReadTool(server),
-    polymarket: () => registerPolymarketTool(server),
+    // The budget too: fund's $0.01 gateway fee is Base-wallet API spend, and the
+    // registrar books it like any paid call — without the ledger it was
+    // neither reserved nor booked outside the unit test (audit round 4).
+    polymarket: () => registerPolymarketTool(server, budget),
   };
 
   for (const [name, register] of Object.entries(registrars) as [ToolName, () => void][]) {
@@ -125,7 +129,7 @@ export function initializeMcpServer(
       "blockrun://models",
       { description: "Available AI models with pricing", mimeType: "application/json" },
       async () => {
-        const models = await loadModels(getClient(), modelCache);
+        const models = await loadModels(getClient(), modelCache, modelCacheKey(getAuthMode(), getChain()));
         return {
           contents: [{
             uri: "blockrun://models",
diff --git a/src/tools/chat-anthropic.ts b/src/tools/chat-anthropic.ts
index de242dc..fdaf3d0 100644
--- a/src/tools/chat-anthropic.ts
+++ b/src/tools/chat-anthropic.ts
@@ -16,8 +16,10 @@
 import type Anthropic from "@anthropic-ai/sdk";
 import { extractErrorMessage, formatError } from "../utils/errors.js";
 import { recordActualSpend } from "../utils/budget.js";
+import { isApiKeyMode } from "../utils/auth.js";
 import { OBSERVED_GATEWAY_TX_FEE_USD } from "../utils/tx-fee.js";
 import { CHAT_PRICE_PER_MTOKEN, GATEWAY_CHARS_PER_TOKEN_OBSERVED } from "../utils/constants.js";
+import { AcceptedThenFailedError, settlementOnThrow, settledCostFromHeaders } from "../utils/chat-stream.js";
 import type { BudgetState } from "../types.js";
 
 /**
@@ -120,9 +122,143 @@ export function anthropicCallCost(
   return Math.ceil(charged * 1e6) / 1e6; // the gateway settles in whole micro-USDC
 }
 
+/**
+ * The ACCOUNT rail's ledger entry for a native call, when the response carried
+ * no `x-blockrun-cost-usd` (chat settles after the response, so it never does).
+ *
+ * Not anthropicCallCost: that is the x402 QUOTE the wallet rails settle —
+ * output at 0.1x max_tokens, a $0.001 floor, the observed transaction fee —
+ * and api.blockrun.ai settles none of it. It bills exact usage, base rate with
+ * no fee and no floor (reconciled against the dashboard 2026-09-05). Booking
+ * the quote formula here added $0.001 to every call on a rail that charges no
+ * fee — a $1 delegate cut off at 500 haiku calls that had cost $0.50 (D58).
+ *
+ * `usage` is the response's own input/output token counts when the call
+ * completed; on a failure after acceptance there is none, so the prompt at the
+ * observed chars/token and the full max_tokens stand in — the conservative
+ * side for a call that reported nothing. Null when the model has no row, so
+ * the caller falls back to the pre-call estimate.
+ */
+export function anthropicAccountLedgerUsd(
+  model: string,
+  promptChars: number,
+  maxTokens: number,
+  usage: { input_tokens: number; output_tokens: number } | null,
+): number | null {
+  const id = catalogueKeyForEcho(model);
+  const rate = Object.hasOwn(CHAT_PRICE_PER_MTOKEN, id) ? CHAT_PRICE_PER_MTOKEN[id] : undefined;
+  if (!rate) return null;
+  const inputTokens = usage?.input_tokens ?? Math.ceil(promptChars / GATEWAY_CHARS_PER_TOKEN_OBSERVED) + MESSAGE_TOKEN_OVERHEAD;
+  const outputTokens = usage?.output_tokens ?? maxTokens;
+  const usd = (inputTokens / 1_000_000) * rate.input + (outputTokens / 1_000_000) * rate.output;
+  return Math.ceil(usd * 1e6 - 1e-6) / 1e6; // whole micro-dollars, float noise excluded
+}
+
 // AnthropicClient.messages is typed as the official SDK's Messages resource.
 type AnthropicLike = { messages: Anthropic["messages"] };
 
+/**
+ * Nothing streamed for this long means the connection is dead, not slow: the
+ * API sends `ping` events every few seconds while a long thinking budget runs,
+ * and the gateway forwards them. Same figure as the OpenAI-compat assembler.
+ */
+const NATIVE_IDLE_TIMEOUT_MS = 120_000;
+
+/**
+ * Run the native call as a STREAM and assemble the final Message.
+ *
+ * Streaming, not create(): two reasons, both money or reach.
+ *
+ *   1. @anthropic-ai/sdk refuses a non-streaming request whose max_tokens
+ *      could run past ten minutes — `calculateNonstreamingTimeout` throws
+ *      "Streaming is required for operations that may take longer than 10
+ *      minutes" above 21,333 tokens — and effectiveMax is budget_tokens + 1024,
+ *      so every thinking budget from 20,310 up to the schema's 100,000 died in
+ *      this process with an error that blamed the caller (D51). The check is
+ *      skipped when `stream` is set.
+ *   2. A non-streaming request moves zero bytes while Claude thinks, and the
+ *      edge in front of the gateway 524s the idle connection at ~100s — after
+ *      the gateway verified the payment. Streaming keeps bytes flowing (pings,
+ *      thinking deltas), the same fix chat-stream.ts made for the compat paths.
+ *
+ * `maxRetries: 0`, always. @blockrun/llm builds the official SDK at its default
+ * of two retries with a fetch that signs a FRESH x402 payment on every 402 it
+ * sees — the PAYMENT-SIGNATURE header lives on a local copy, never on the
+ * SDK's request init — so a 5xx/524/timeout after settlement was retried up to
+ * twice more, each retry a new USDC settlement for an undelivered answer, none
+ * of it visible to the ledger (C20). The gateway already saw the payment; a
+ * retry is a second purchase, and the routing loop's one-settlement rule
+ * belongs here too. (The account rail's client is built with maxRetries 0 by
+ * the SDK itself; passing it per request covers both.)
+ *
+ * The SDK's MessageStream accumulates thinking and signature deltas, so the
+ * assembled Message carries the same verbatim thinking blocks the non-streaming
+ * response did — the test against the real SDK pins that.
+ *
+ * `accepted` is whether the stream CONNECTED (the SDK emits `connect` once the
+ * 2xx is in, before the first event). A throw after that point is wrapped as
+ * AcceptedThenFailedError: the payment settled (wallet) or the request is
+ * billed (account), and the caller books it.
+ */
+async function streamNativeMessage(
+  client: AnthropicLike,
+  params: Anthropic.MessageStreamParams,
+): Promise<{ message: Anthropic.Message; costHeaderUsd: number | null }> {
+  // The @blockrun/llm proxy wraps every messages.* call in an async function,
+  // so the MessageStream arrives behind a promise; the SDK returns it directly.
+  const stream = await client.messages.stream(params, { maxRetries: 0 });
+  let accepted = false;
+  stream.on("connect", () => { accepted = true; });
+
+  // Idle guard, reset on every event. The SDK has no per-event deadline of its
+  // own — its request timeout ends at the headers — and the fetch underneath
+  // clears its abort timer at the same point.
+  let idleTimer: NodeJS.Timeout | undefined;
+  let stalled: (err: Error) => void = () => undefined;
+  const stall = new Promise<never>((_, reject) => { stalled = reject; });
+  const armIdle = () => {
+    clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      stalled(new AcceptedThenFailedError(`stream stalled: no data from the gateway for ${Math.round(NATIVE_IDLE_TIMEOUT_MS / 1000)}s`));
+      stream.abort();
+    }, NATIVE_IDLE_TIMEOUT_MS);
+  };
+  stream.on("streamEvent", armIdle);
+  armIdle();
+  try {
+    const message = await Promise.race([stream.finalMessage(), stall]);
+    return { message, costHeaderUsd: settledCostFromHeaders(stream.response?.headers) };
+  } catch (error) {
+    if (error instanceof AcceptedThenFailedError) throw error;
+    if (accepted) {
+      throw new AcceptedThenFailedError(error instanceof Error ? error.message : String(error), "", { cause: error });
+    }
+    throw error;
+  } finally {
+    clearTimeout(idleTimer);
+  }
+}
+
+/**
+ * The note for a native call that cost money — or may have — and then failed.
+ * Same voice as chat.ts's settledThenFailedText; the two paths book the same
+ * way and must read the same way to the agent acting on them.
+ */
+function nativeFailedText(error: unknown, usd: number, certainty: "settled" | "unknown"): string {
+  const amount = `$${usd.toFixed(6)}`;
+  const what = isApiKeyMode()
+    ? certainty === "settled"
+      ? `Note: the gateway had accepted this request (HTTP 200) before it failed, so it is billed to your BlockRun account at exact usage — ` +
+        `an estimated ~${amount} has been recorded against your budget; https://user.blockrun.ai/dashboard/activity has the exact figure.`
+      : `Note: this request MAY have been billed to your BlockRun account — no response was observed, so this process cannot tell. ` +
+        `An estimated ~${amount} has been recorded against your budget as a precaution; https://user.blockrun.ai/dashboard/activity has the truth.`
+    : certainty === "settled"
+      ? `Note: payment had already settled when this failed, so the charge stands (~${amount}, the reconstructed quote) and it has been recorded against your budget.`
+      : `Note: the payment for this call had been signed and sent before it failed, and this process cannot tell whether the gateway settled it — ` +
+        `it may have settled after the connection dropped. The reconstructed quote (${amount}) has been recorded against your budget as a precaution.`;
+  return `${formatError(extractErrorMessage(error))}\n\n${what} Retrying will incur a second charge — check blockrun_wallet action:"report" first.`;
+}
+
 type TextPart = { type: "text"; text: string };
 type ImagePart = { type: "image_url"; image_url: { url: string } };
 type ContentPart = TextPart | ImagePart;
@@ -264,7 +400,7 @@ export async function handleAnthropicNative(args: AnthropicNativeArgs): Promise<
       ? m.content.length
       : JSON.stringify(m.content ?? "").length), 0);
 
-  const params: Anthropic.MessageCreateParamsNonStreaming = {
+  const params: Anthropic.MessageStreamParams = {
     model,
     max_tokens: effectiveMax,
     messages: apiMessages,
@@ -280,23 +416,52 @@ export async function handleAnthropicNative(args: AnthropicNativeArgs): Promise<
     params.temperature = Math.max(0, Math.min(1, temperature));
   }
 
+  // What a failure after the money moved is booked at. The wallet rails settle
+  // the quote (anthropicCallCost); the account rail bills exact usage, which a
+  // failed call never reports, so its ledger figure is the model's rate over
+  // the prompt and the full max_tokens. Either falls back to the reserve when
+  // the model has no row.
+  const failedLedgerUsd = () => (isApiKeyMode()
+    ? anthropicAccountLedgerUsd(model, anthropicPromptChars, effectiveMax, null)
+    : anthropicCallCost(model, anthropicPromptChars, effectiveMax)) ?? estimatedCost;
+
   let native: Anthropic.Message;
+  let costHeaderUsd: number | null;
   try {
-    native = await client.messages.create(params);
+    ({ message: native, costHeaderUsd } = await streamNativeMessage(client, params));
   } catch (error) {
-    return { content: [{ type: "text", text: formatError(extractErrorMessage(error)) }], isError: true };
+    // Until audit round 3 this returned formatError and booked nothing, on
+    // both rails — the settled-then-failed machinery the OpenAI-compat paths
+    // gained in 0.40.1/0.49.0/0.50.0 never reached here, so a 524 after the
+    // gateway settled read as "temporary API issue, try again" and the agent
+    // paid again (C20). Same classifier as those paths: a 4xx before the
+    // stream connected (the gateway's own refusal, or the SDK's) and a
+    // payment the wallet could not make are not money; a failure after the
+    // 2xx is; an origin that never answered may be.
+    const verdict = settlementOnThrow(error, { rail: isApiKeyMode() ? "account" : "wallet", estimateUsd: estimatedCost, transparentPayment: true });
+    if (verdict === "none") {
+      return { content: [{ type: "text", text: formatError(extractErrorMessage(error)) }], isError: true };
+    }
+    const usd = failedLedgerUsd();
+    recordActualSpend(budget, usd, estimatedCost, agentId);
+    return { content: [{ type: "text", text: nativeFailedText(error, usd, verdict) }], isError: true };
   }
 
-  // Book what the gateway actually charged (the quote it settled), not the flat
-  // estimate and not a token reconstruction at Anthropic's list prices.
+  // Book what the gateway actually charged: on the wallet rails the quote it
+  // settled (anthropicCallCost) — not the flat estimate and not a token
+  // reconstruction at Anthropic's list prices; on the account rail the
+  // response's settled cost when it carried one, else exact usage at the
+  // model's rate (anthropicAccountLedgerUsd), labelled as the estimate it is.
   // effectiveMax is the max_tokens the request was sent with — including the
   // auto-raise for a thinking budget, which is what the quote was priced on.
-  recordActualSpend(
-    budget,
-    anthropicCallCost(native.model, anthropicPromptChars, effectiveMax),
-    estimatedCost,
-    agentId,
-  );
+  const bookedUsd = isApiKeyMode()
+    ? (costHeaderUsd ?? anthropicAccountLedgerUsd(native.model, anthropicPromptChars, effectiveMax, native.usage))
+    : anthropicCallCost(native.model, anthropicPromptChars, effectiveMax);
+  const costIsEstimate = isApiKeyMode() && costHeaderUsd === null;
+  recordActualSpend(budget, bookedUsd, estimatedCost, agentId);
+  const costLine = costIsEstimate && bookedUsd !== null && bookedUsd > 0
+    ? `\n\n(Cost: ~$${bookedUsd.toFixed(4)}, estimated — billed to your BlockRun account at exact usage; https://user.blockrun.ai/dashboard/activity has the figure.)`
+    : "";
 
   const thinkingBlocks = native.content.filter(isThinkingBlock);
   const textBlocks = native.content.filter(isTextBlock);
@@ -310,7 +475,14 @@ export async function handleAnthropicNative(args: AnthropicNativeArgs): Promise<
   if (raisedMaxTokens) headerBits.push(`max_tokens→${effectiveMax}`);
   const header = `[${headerBits.join(" | ")}]`;
 
-  const content: { type: "text"; text: string }[] = [{ type: "text", text: `${header}\n\n${answerText}` }];
+  // stop_reason "max_tokens" is the native spelling of a reply cut short;
+  // surfaced in the text as the compat paths do, not only in structuredContent.
+  const truncated = native.stop_reason === "max_tokens"
+    ? `\n\n⚠️ TRUNCATED OUTPUT: the reply hit max_tokens=${effectiveMax} and stopped mid-way (stop_reason "max_tokens"). ` +
+      `Raise max_tokens to get the rest — thinking tokens count against it too.`
+    : "";
+
+  const content: { type: "text"; text: string }[] = [{ type: "text", text: `${header}\n\n${answerText}${truncated}${costLine}` }];
   if (thinkingText) {
     content.push({ type: "text", text: `🧠 Thinking (signature ${signaturePresent ? "present" : "absent"}):\n${thinkingText}` });
   }
@@ -328,7 +500,10 @@ export async function handleAnthropicNative(args: AnthropicNativeArgs): Promise<
       thinking_blocks: thinkingBlocks,
       signature_present: signaturePresent,
       stop_reason: native.stop_reason,
+      ...(native.stop_reason === "max_tokens" ? { truncated_output: true } : {}),
       usage: native.usage,
+      cost_usd: bookedUsd ?? estimatedCost,
+      cost_is_estimate: costIsEstimate || bookedUsd === null,
       native,
     },
   };
diff --git a/src/tools/chat.ts b/src/tools/chat.ts
index c78e0a2..5035ba0 100644
--- a/src/tools/chat.ts
+++ b/src/tools/chat.ts
@@ -4,7 +4,14 @@ import { TOOL_ANNOTATIONS } from "../tool-annotations.js";
 import { z } from "zod";
 import { buildClient, buildClientWithTimeout, getAnthropicClient, baseOnlyMessage } from "../utils/wallet.js";
 import { isApiKeyMode } from "../utils/auth.js";
-import { streamChatText, supportsStreaming, type StreamChatMessage } from "../utils/chat-stream.js";
+import {
+  completeChat,
+  settlementOnThrow,
+  AcceptedThenFailedError,
+  type ChatOutcome,
+  type ChatUsage,
+  type StreamChatMessage,
+} from "../utils/chat-stream.js";
 import { handleAnthropicNative, isAnthropicModel } from "./chat-anthropic.js";
 import { extractErrorMessage, formatError } from "../utils/errors.js";
 import {
@@ -18,6 +25,7 @@ import {
   canonicalChatModel,
   TIER_WORST_PRICE,
   GATEWAY_CHARS_PER_TOKEN,
+  GATEWAY_CHARS_PER_TOKEN_OBSERVED,
   type RoutingMode,
 } from "../utils/constants.js";
 import { reserveBudget, recordActualSpend } from "../utils/budget.js";
@@ -187,69 +195,154 @@ export function estimateChatCost(
 }
 
 /**
- * Settled cost of the LLMClient call that ran inside `run`, measured as the
- * delta of the client's own cumulative spend counter (getSpending().totalUsd),
- * which the SDK increments with the REAL on-chain amount per call. Returns the
- * result plus the booked cost so callers can record actual spend, falling back
- * to the estimate when the delta is unavailable (0/NaN).
+ * What the ACCOUNT rail is booked at when the response carried no settled cost.
  *
- * A THROW DOES NOT MEAN A REFUND. x402 settles when the gateway answers 200 —
- * the SDK increments its counter at that moment, before the body is read — and
- * every paid path here STREAMS, so the call can still fail afterwards: a
- * mid-stream error event, an idle stall, an empty completion. Until 0.40.1 the
- * delta was computed only after `run()` resolved, so on that path the USDC left
- * the wallet, `budget.spent` never moved, and the `finally` released the
- * reservation — the ledger recorded a free call. `onSettledThrow` is how the
- * charge still gets booked; it fires only when the delta is real (> 0), so an
- * ordinary pre-payment failure (400, timeout, refusal) still books nothing.
+ * api.blockrun.ai bills chat at exact usage, after the response is sent — which
+ * is why `x-blockrun-cost-usd` is absent on chat by design (api-key-call.ts).
+ * Until audit round 3 the three OpenAI-compat paths then booked the GATE
+ * reserve: the most expensive member of the tier, input at 2 chars/token,
+ * output at the full max_tokens, plus a $0.002 transaction fee this rail never
+ * charges — 3-6x the real charge on mode:"balanced", up to ~50x on "powerful"
+ * with a short reply, so BLOCKRUN_BUDGET_LIMIT tripped at a fraction of real
+ * spend and action:"report" overstated it (C33/D53). 0.50.0's ledgerFallback
+ * fixed the same reserve-as-ledger pattern for the path tools; this is chat's.
  *
- * ON THE ACCOUNT RAIL THERE IS NO COUNTER TO READ. getSpending() does not return
- * zero for an API-key client — it THROWS:
+ * The model's own rate — the SERVED model's when it has a row (the gateway
+ * aliases retired ids, and the bill follows what answered), else the requested
+ * one's; a free REQUEST is free whatever answered it (the $0 probes show every
+ * alias of a free id served without a payment header) — input and output at
+ * the token counts the stream reported when it did, else the prompt at the
+ * observed chars/token and the full max_tokens (the conservative side, for a
+ * failure that reported nothing). No fee, no floor: reconciled 2026-09-05, the
+ * account rail charges base × margin and nothing else. Still an estimate — the
+ * caller labels it as one.
+ */
+export function accountLedgerUsd(
+  requestedModel: string,
+  servedModel: string | null,
+  promptChars: number,
+  maxTokens: number,
+  usage: ChatUsage | null,
+): number {
+  const requested = canonicalChatModel(requestedModel);
+  if (FREE_CHAT_MODELS.has(requested)) return 0;
+  const served = servedModel ? canonicalChatModel(servedModel) : null;
+  const rate = served && Object.hasOwn(CHAT_PRICE_PER_MTOKEN, served) ? CHAT_PRICE_PER_MTOKEN[served]
+    : Object.hasOwn(CHAT_PRICE_PER_MTOKEN, requested) ? CHAT_PRICE_PER_MTOKEN[requested]
+    : DEFAULT_CHAT_PRICE;
+  const inTokens = usage?.promptTokens ?? Math.ceil(promptChars / GATEWAY_CHARS_PER_TOKEN_OBSERVED);
+  const outTokens = usage?.completionTokens ?? maxTokens;
+  const usd = (inTokens / 1_000_000) * rate.input + (outTokens / 1_000_000) * rate.output;
+  // Whole micro-dollars, rounded up as the gateway bills; the epsilon keeps a
+  // binary-float 4500.0000000001 from ceiling to 4501.
+  return Math.ceil(usd * 1e6 - 1e-6) / 1e6;
+}
+
+/** What a failed call cost, as far as this process can tell. */
+type FailedBooking = {
+  usd: number;
+  /** "settled": the charge is certain. "unknown": it may have happened; booked as a precaution. */
+  certainty: "settled" | "unknown";
+};
+
+/**
+ * Settled cost of the chat call that ran inside `run`.
  *
- *   "Account usage is available at https://user.blockrun.ai/dashboard;
- *    getSpending() tracks x402 settlements only."
+ * ON THE WALLET RAILS it is the delta of the client's own cumulative spend
+ * counter (getSpending().totalUsd), which the SDK increments with the REAL
+ * on-chain amount once the PAID response comes back OK. A THROW DOES NOT MEAN A
+ * REFUND: x402 settles on that 200, before the body is read, and the call can
+ * still fail afterwards — a mid-stream error event, an idle stall, an empty
+ * completion. Until 0.40.1 the delta was computed only after `run()` resolved,
+ * so the USDC left the wallet, `budget.spent` never moved, and the `finally`
+ * released the reservation — the ledger recorded a free call. `onSettledThrow`
+ * is how the charge still gets booked.
  *
- * and it is called three times here, on the very first line, outside the try.
- * Left alone, setting BLOCKRUN_API_KEY would not degrade blockrun_chat, it would
- * break every single call before the request was even sent. So account mode
- * skips the counter entirely and reports settledUsd 0, which every caller
- * already handles as "delta unavailable — fall back to the estimate".
+ * The counter has a blind spot, and it is on the DEFAULT chain. The SDK counts
+ * only after the paid retry was OK — SolanaLLMClient runs assertPaid() before
+ * recordSettlement(), LLMClient throws "API error after payment" before its
+ * increment, and a fetch timeout on the paid retry (60s on Solana) throws with
+ * no increment at all. The payment had been signed and SENT in every one of
+ * those; the gateway settles them after the client is gone. Until audit round
+ * 3 that read as a $0 delta: nothing booked, "temporary API issue — try again",
+ * and the routing loop signed a second payment for the next model under the
+ * same reservation (C19). settlementOnThrow classifies those as "unknown": the
+ * reserve is booked as a precaution, the loop stops, the note says MAY. An
+ * unpaid first-response 4xx, a refused payment, or a 4xx on the paid retry (the
+ * gateway's own refusal, before settlement starts) still books nothing.
  *
- * The estimate is genuinely all we have: the account API returns no per-call
- * cost header, and its dashboard is cookie-authenticated, so there is nothing
- * this process could read back. Callers label the number accordingly rather
- * than printing an estimate that looks like a settlement.
+ * ON THE ACCOUNT RAIL THERE IS NO COUNTER TO READ — getSpending() THROWS for an
+ * API-key client. What there is instead: the SDK's account transport throws an
+ * APIError carrying the status of the FIRST response, before any body, for
+ * every refusal (400 unknown model, 401, 402 out of credit, 429), so none of
+ * those is billed; a failure after the 2xx (AcceptedThenFailedError) is a
+ * billed call at exact usage; an origin that never answered is "unknown". The
+ * 0.50.0 fix for "a billed-then-dropped stream booked $0" caught EVERY
+ * rejection here and booked the full reserve for it with "the charge stands"
+ * — five typo'd model ids exhausted a delegated cap at $0 real spend, a 402
+ * out-of-credit read as billed, and mode:"free" died on its first timeout
+ * (C5/C18/C23/C31). On success the response may carry `x-blockrun-cost-usd`;
+ * when it does that is the entry (a settled zero included), and when it does
+ * not, accountLedgerUsd is — labelled as the estimate it is.
  */
-async function withSettledCost<T>(
+async function withSettledCost<T extends ChatOutcome>(
   client: ApiClient,
+  estimateUsd: number,
+  accountLedger: (outcome: T | null) => number,
   run: () => Promise<T>,
-  onSettledThrow?: (settledUsd: number) => void,
-): Promise<{ result: T; settledUsd: number }> {
+  onSettledThrow: (booking: FailedBooking) => void,
+): Promise<{ result: T; settledUsd: number; costIsEstimate: boolean }> {
   if (isApiKeyMode()) {
-    return { result: await run(), settledUsd: 0 };
+    try {
+      const result = await run();
+      return result.settledUsd === null
+        ? { result, settledUsd: accountLedger(result), costIsEstimate: true }
+        : { result, settledUsd: result.settledUsd, costIsEstimate: false };
+    } catch (error) {
+      const verdict = settlementOnThrow(error, { rail: "account", estimateUsd });
+      if (verdict !== "none") onSettledThrow({ usd: accountLedger(null), certainty: verdict });
+      throw error;
+    }
   }
   const before = client.getSpending().totalUsd;
+  const delta = () => {
+    const d = client.getSpending().totalUsd - before;
+    return Number.isFinite(d) && d >= 0 ? d : null;
+  };
   try {
     const result = await run();
-    return { result, settledUsd: client.getSpending().totalUsd - before };
+    // null = the counter could not be read: book the reserve rather than $0.
+    const d = delta();
+    return { result, settledUsd: d ?? estimateUsd, costIsEstimate: d === null };
   } catch (error) {
-    const settledUsd = client.getSpending().totalUsd - before;
-    if (Number.isFinite(settledUsd) && settledUsd > 0) onSettledThrow?.(settledUsd);
+    const d = delta();
+    if (d !== null && d > 0) {
+      onSettledThrow({ usd: d, certainty: "settled" });
+    } else if (settlementOnThrow(error, { rail: "wallet", estimateUsd }) === "unknown") {
+      onSettledThrow({ usd: estimateUsd, certainty: "unknown" });
+    }
+    // A counter that says $0 after a 2xx is a call the gateway served without
+    // charging (its free fallback); nothing to book.
     throw error;
   }
 }
 
 /**
- * The error text for a call that SETTLED and then failed.
+ * The error text for a call that cost money — or may have — and then failed.
  *
  * x402 settles on the 200, before the body is read, and every paid path streams,
  * so a stall or an in-band error event arrives with the money already gone.
  * withSettledCost books it (onSettledThrow); this is the sentence that tells the
  * CALLER. Without it the text was "Error: stream stalled: no data from the
  * gateway for 120s" — indistinguishable from a free failure, so the obvious next
- * step (retry) settled a second payment. The routing loop has said this since
- * 0.40.1; the explicit-model and multi-turn paths, which by construction fail
- * only after settlement, never did.
+ * step (retry) settled a second payment.
+ *
+ * The wording tracks the certainty, because the text is what an agent acts on.
+ * "The charge stands" is said only when it is known to (a counter delta, or an
+ * account request the gateway accepted with a 2xx). When the payment was sent
+ * and no verdict came back, the note says MAY, names the booked reserve as a
+ * precaution, and points at action:"report" — it does not assert a charge it
+ * cannot see, and it does not invite a retry that would pay again.
  *
  * formatError runs on the BARE error and the note is appended afterwards, on
  * purpose: formatError classifies on keywords, and this note contains the word
@@ -257,14 +350,74 @@ async function withSettledCost<T>(
  * text, the routing loop's version ended in "your wallet needs funding" — the
  * exact wrong advice for a call that just paid.
  */
-function settledThenFailedText(error: unknown, settledUsd: number, tail: string): string {
-  return (
-    `${formatError(extractErrorMessage(error))}\n\nNote: payment had already settled when this failed, ` +
-    `so the charge stands ($${settledUsd.toFixed(6)}) and it has been recorded against your budget. ${tail}`
-  );
+function settledThenFailedText(error: unknown, booking: FailedBooking, tail: string): string {
+  const usd = `$${booking.usd.toFixed(6)}`;
+  let what: string;
+  if (isApiKeyMode()) {
+    what = booking.certainty === "settled"
+      ? `Note: the gateway had accepted this request (HTTP 200) before it failed, so it is billed to your BlockRun account at exact usage — ` +
+        `an estimated ~${usd} has been recorded against your budget; https://user.blockrun.ai/dashboard/activity has the exact figure.`
+      : `Note: this request MAY have been billed to your BlockRun account — no response was observed, so this process cannot tell. ` +
+        `An estimated ~${usd} has been recorded against your budget as a precaution; https://user.blockrun.ai/dashboard/activity has the truth.`;
+  } else {
+    what = booking.certainty === "settled"
+      ? `Note: payment had already settled when this failed, so the charge stands (${usd}) and it has been recorded against your budget.`
+      : `Note: the payment for this call had been signed and sent before it failed, and this process cannot tell whether the gateway settled it — ` +
+        `it may have settled after the connection dropped. The reserved ${usd} has been recorded against your budget as a precaution.`;
+  }
+  const partial = error instanceof AcceptedThenFailedError && error.partialText
+    ? `\n\nPartial response received before the failure (${error.partialText.length.toLocaleString("en-US")} chars):\n${error.partialText}`
+    : "";
+  return `${formatError(extractErrorMessage(error))}\n\n${what} ${tail}${partial}`;
 }
 const RETRY_CHARGES_AGAIN = 'Retrying will incur a second charge — check blockrun_wallet action:"report" first.';
 
+/**
+ * Notes appended to a SUCCESSFUL reply about what the gateway said of it.
+ *
+ * `served_model`: constants.ts documents that the gateway aliases retired ids
+ * onto a live model instead of 404ing, and that "only the response's `model`
+ * field" tells you. The text and structuredContent used to echo the REQUESTED
+ * id, so an agent asking a stale id for "Kimi's opinion" presented another
+ * model's answer as Kimi's, paid for a model nobody chose (D55). The $0 probe
+ * on 2026-09-13 showed eight of eleven free[] ids answering as another model.
+ *
+ * `truncated_output`: finish_reason "length" is the model stopping at
+ * max_tokens mid-sentence (or mid-JSON, with response_format json_object). It
+ * was read and dropped, so a cut reply came back looking complete — the silent
+ * truncation shape the free-tier prompt note exists to make loud (D57).
+ */
+function servedNotes(requested: string, outcome: ChatOutcome, maxTokens: number | undefined): { text: string; fields: Record<string, unknown> } {
+  const fields: Record<string, unknown> = {};
+  let text = "";
+  const served = outcome.servedModel;
+  if (served) fields.served_model = served;
+  if (served && canonicalChatModel(served) !== canonicalChatModel(requested)) {
+    text += `\n\n(Served by ${served} — the gateway answered the requested id ${requested} with this model instead: retired, aliased, or at capacity.)`;
+  }
+  if (outcome.finishReason) fields.finish_reason = outcome.finishReason;
+  if (outcome.finishReason === "length" && outcome.text) {
+    fields.truncated_output = true;
+    text += `\n\n⚠️ TRUNCATED OUTPUT: the reply hit max_tokens=${maxTokens ?? 1024} and stopped mid-way (finish_reason "length"). ` +
+      `Raise max_tokens to get the rest — reasoning tokens count against it too.`;
+  }
+  return { text, fields };
+}
+
+/** The cost line for a reply, and its structuredContent fields. */
+function costNotes(settledUsd: number, costIsEstimate: boolean): { text: string; fields: Record<string, unknown> } {
+  const fields = { cost_usd: settledUsd, cost_is_estimate: costIsEstimate };
+  // Only an ESTIMATE is worth a line in the reply: a settled wallet delta is
+  // already in action:"report", and the account rail's exact figure lives on
+  // the dashboard. Saying "~" is what keeps the CHANGELOG's promise that an
+  // estimated figure never looks like a settlement.
+  if (!costIsEstimate || !(settledUsd > 0)) return { text: "", fields };
+  return {
+    text: `\n\n(Cost: ~$${settledUsd.toFixed(4)}, estimated${isApiKeyMode() ? " — billed to your BlockRun account at exact usage; https://user.blockrun.ai/dashboard/activity has the figure" : ""}.)`,
+    fields,
+  };
+}
+
 export function registerChatTool(server: McpServer, budget: BudgetState): void {
   server.registerTool(
     "blockrun_chat",
@@ -348,20 +501,36 @@ Run blockrun_models to see all available models with pricing.`,
       const confirm = await confirmSpend(server, { usd: estimatedCost, label: `chat · ${model ?? mode ?? "auto"}` });
       if (!confirm.ok) return { content: [{ type: "text", text: confirm.reason ?? "Charge cancelled." }] };
 
-      // Native Anthropic passthrough (EVM/Base only).
+      // Native Anthropic passthrough (Base wallet and the account rail).
       // An explicit anthropic/claude-* model goes DIRECT to the gateway's
       // /v1/messages endpoint, which forwards to api.anthropic.com VERBATIM:
       // zero model substitution, no cost routing, no fallback, and the real
       // native response — type:"thinking" blocks with their original signature.
       // This takes priority over mode/routing precisely because the requirement
       // is "claude-* must be verbatim, never routed". The OpenAI-compat paths
-      // below cannot carry thinking signatures, so claude never falls through.
+      // below cannot carry thinking signatures.
+      //
+      // ON SOLANA the AnthropicClient cannot pay (it signs EVM x402 only), and
+      // until audit round 3 every explicit claude-* id was refused there with
+      // "switch to Base" — while mode:"powerful"/"reasoning"/"coding" sent the
+      // very same ids through /v1/chat/completions on sol.blockrun.ai one
+      // branch lower, and a fresh install's Base wallet is empty. Verified
+      // 2026-09-13 with an unpaid POST: sol.blockrun.ai quotes claude-opus-5
+      // and claude-sonnet-5 on chat/completions (402, "Claude Opus 5 API
+      // call"), so the route exists. The refusal now applies only when
+      // `thinking` is requested — the one thing the compat path cannot carry —
+      // and a plain claude-* call on Solana takes the explicit-model path
+      // below like any other id (D5). Its price there is the Solana quote:
+      // output at full max_tokens, not Base's 0.1x — see D52 in the audit —
+      // which the reserve already covers.
       if (model && isAnthropicModel(model)) {
-        const solanaBlock = baseOnlyMessage("Native Anthropic (claude-*) calls");
-        if (solanaBlock) {
+        // Non-null only on a Solana wallet (null in API-key mode and on Base).
+        const solanaBlock = baseOnlyMessage("Native Anthropic (claude-*) calls with `thinking`");
+        if (solanaBlock && thinking) {
           return { content: [{ type: "text", text: solanaBlock }], isError: true };
         }
-        return await handleAnthropicNative({
+        // Solana without `thinking` falls through to the explicit-model path.
+        if (!solanaBlock) return await handleAnthropicNative({
           client: getAnthropicClient(),
           model,
           message,
@@ -388,6 +557,63 @@ Run blockrun_models to see all available models with pricing.`,
       // Callers wanting a cheap model should pass mode:"cheap"/"glm" or an explicit
       // model — both resolve here, with no router.
 
+      // One paid attempt, whichever path asked for it: run it, book what it
+      // cost, and hand back the outcome with the notes a reply carries.
+      //
+      // Paid calls STREAM and assemble (see utils/chat-stream.ts): a slow
+      // reasoning model generating for minutes over a non-streaming request
+      // moves zero bytes, and the edge in front of the gateway 524s the idle
+      // connection AFTER the x402 payment settled — charged, no reply (observed
+      // live with moonshot/kimi-k3, 2026-07-21). That includes Solana since
+      // audit round 3: the SDK's stream() pays and records the settlement
+      // before the first frame, where the old non-streaming path aborted at
+      // the Solana client's 60s default with the payment already sent.
+      //
+      // The SDK types ChatMessage.content as string-only, but the gateway
+      // forwards `messages` verbatim and accepts image_url content arrays for
+      // vision-capable models — so a multimodal array is runtime-valid.
+      // (claude-* with history is already handled by the native branch above.)
+      const attempt = async (
+        client: ApiClient,
+        targetModel: string,
+        fullMessages: StreamChatMessage[],
+        stream: boolean,
+        onFailedBooking: (booking: FailedBooking) => void,
+      ) => {
+        const { result, settledUsd, costIsEstimate } = await withSettledCost(
+          client,
+          estimatedCost,
+          (outcome) => accountLedgerUsd(targetModel, outcome?.servedModel ?? null, promptChars, max_tokens ?? 1024, outcome?.usage ?? null),
+          () => completeChat(client, targetModel, fullMessages, { maxTokens: max_tokens, temperature, responseFormat, stop }, { stream }),
+          (booking) => {
+            recordActualSpend(budget, booking.usd, estimatedCost, agent_id);
+            onFailedBooking(booking);
+          },
+        );
+        recordActualSpend(budget, settledUsd, estimatedCost, agent_id);
+        const served = servedNotes(targetModel, result, max_tokens);
+        const cost = costNotes(settledUsd, costIsEstimate);
+        const prompt = freeTierTruncationNote(promptChars, result.servedModel ?? targetModel);
+        return {
+          reply: result.text,
+          notes: `${served.text}${cost.text}${prompt ?? ""}`,
+          fields: { ...served.fields, ...cost.fields, ...(prompt ? { truncated: true } : {}) },
+        };
+      };
+      const failedText = (error: unknown, booking: FailedBooking | null, tail: string) => {
+        const partial = error instanceof AcceptedThenFailedError && error.partialText ? error.partialText : "";
+        // Nothing booked (a free model, or a served-free call that died): the
+        // partial text is still the caller's, so it still rides along.
+        const text = booking
+          ? settledThenFailedText(error, booking, tail)
+          : `${formatError(extractErrorMessage(error))}${partial ? `\n\nPartial response received before the failure (${partial.length.toLocaleString("en-US")} chars):\n${partial}` : ""}`;
+        return {
+          content: [{ type: "text" as const, text }],
+          ...(partial ? { structuredContent: { partial_response: partial } } : {}),
+          isError: true as const,
+        };
+      };
+
       // Multi-turn conversation
       if (messages && messages.length > 0) {
         const targetModel = model || MODEL_TIERS[(mode ?? "balanced") as RoutingMode]?.[0] || "openai/gpt-5.6-terra";
@@ -395,97 +621,34 @@ Run blockrun_models to see all available models with pricing.`,
           ...(system ? [{ role: "system" as const, content: system }] : []),
           ...messages,
           { role: "user" as const, content: message },
-        ];
-        // USDC that left the wallet before the failure, if any (see settledThenFailedText).
-        let settledOnFailure = 0;
+        ] as StreamChatMessage[];
+        // What a failed attempt cost, if anything (see settledThenFailedText).
+        let failedBooking: FailedBooking | null = null;
         try {
-          // The SDK types ChatMessage.content as string-only, but the gateway
-          // forwards `messages` verbatim and accepts image_url content arrays
-          // for vision-capable models — so a multimodal array is runtime-valid.
-          // (claude-* with history is already handled by the native branch above.)
-          //
-          // Paid calls STREAM and assemble (see utils/chat-stream.ts): a slow
-          // reasoning model generating for minutes over a non-streaming request
-          // moves zero bytes, and the edge in front of the gateway 524s the idle
-          // connection AFTER the x402 payment settled — charged, no reply
-          // (observed live with moonshot/kimi-k3, 2026-07-21). Solana clients
-          // have no streaming API and keep the old path.
-          const { result: reply, settledUsd } = await withSettledCost(llm(), async () => {
-            const client = llm();
-            if (supportsStreaming(client)) {
-              return streamChatText(client, targetModel, fullMessages as unknown as StreamChatMessage[], {
-                maxTokens: max_tokens,
-                temperature,
-                responseFormat,
-                stop,
-              });
-            }
-            const r = await client.chatCompletion(targetModel, fullMessages as unknown as Parameters<ReturnType<typeof llm>["chatCompletion"]>[1], {
-              maxTokens: max_tokens,
-              temperature,
-              responseFormat,
-              stop,
-            });
-            return r.choices?.[0]?.message?.content || "";
-          }, (usd) => {
-            recordActualSpend(budget, usd, estimatedCost, agent_id);
-            settledOnFailure = usd;
-          });
-          recordActualSpend(budget, settledUsd, estimatedCost, agent_id);
-          const note = freeTierTruncationNote(promptChars, targetModel);
+          const { reply, notes, fields } = await attempt(llm(), targetModel, fullMessages, true, (b) => { failedBooking = b; });
           return {
-            content: [{ type: "text", text: `[${targetModel} | ${fullMessages.length} msgs]\n\n${reply}${note ?? ""}` }],
-            structuredContent: { model_used: targetModel, response: reply, message_count: fullMessages.length, ...(note ? { truncated: true } : {}) },
+            content: [{ type: "text", text: `[${targetModel} | ${fullMessages.length} msgs]\n\n${reply}${notes}` }],
+            structuredContent: { model_used: targetModel, response: reply, message_count: fullMessages.length, ...fields },
           };
         } catch (error) {
-          return {
-            content: [{
-              type: "text",
-              text: settledOnFailure > 0
-                ? settledThenFailedText(error, settledOnFailure, RETRY_CHARGES_AGAIN)
-                : formatError(extractErrorMessage(error)),
-            }],
-            isError: true,
-          };
+          return failedText(error, failedBooking, RETRY_CHARGES_AGAIN);
         }
       }
 
-      // If specific model provided, use it directly — streamed when the client
-      // supports it (same 524 rationale as the multi-turn path above).
+      // If specific model provided, use it directly.
       if (model) {
-        let settledOnFailure = 0;
+        let failedBooking: FailedBooking | null = null;
         try {
-          const { result: response, settledUsd } = await withSettledCost(llm(), async () => {
-            const client = llm();
-            if (supportsStreaming(client)) {
-              return streamChatText(client, model, [
-                ...(system ? [{ role: "system" as const, content: system }] : []),
-                { role: "user" as const, content: message },
-              ], { maxTokens: max_tokens, temperature, responseFormat, stop });
-            }
-            return client.chat(model, message, {
-              system,
-              maxTokens: max_tokens,
-              temperature,
-              responseFormat,
-              stop,
-            });
-          }, (usd) => {
-            recordActualSpend(budget, usd, estimatedCost, agent_id);
-            settledOnFailure = usd;
-          });
-          recordActualSpend(budget, settledUsd, estimatedCost, agent_id);
-          return { content: [{ type: "text", text: `${response}${freeTierTruncationNote(promptChars, model) ?? ""}` }] };
-        } catch (error) {
+          const { reply, notes, fields } = await attempt(llm(), model, [
+            ...(system ? [{ role: "system" as const, content: system }] : []),
+            { role: "user" as const, content: message },
+          ], true, (b) => { failedBooking = b; });
           return {
-            content: [{
-              type: "text",
-              text: settledOnFailure > 0
-                ? settledThenFailedText(error, settledOnFailure, RETRY_CHARGES_AGAIN)
-                : formatError(extractErrorMessage(error)),
-            }],
-            isError: true,
+            content: [{ type: "text", text: `${reply}${notes}` }],
+            structuredContent: { model_used: model, response: reply, ...fields },
           };
+        } catch (error) {
+          return failedText(error, failedBooking, RETRY_CHARGES_AGAIN);
         }
       }
 
@@ -495,7 +658,7 @@ Run blockrun_models to see all available models with pricing.`,
 
       // Only the free tier gets a deadline. Paid tiers are frontier/reasoning
       // models where a multi-minute completion is the job, not a fault; free
-      // models fail by crawling and there are seven of them to fall through.
+      // models fail by crawling and there are several of them to fall through.
       // See FREE_MODEL_TIMEOUT_MS for the measurements behind the numbers.
       const freeClient = routingMode === "free" ? buildClientWithTimeout(FREE_MODEL_TIMEOUT_MS) : null;
       const routingClient = freeClient ?? llm();
@@ -503,8 +666,8 @@ Run blockrun_models to see all available models with pricing.`,
 
       let lastError: unknown = null;
       let deadlineHit = false;
-      // USDC that already left the wallet on a failed attempt in this loop.
-      let settledOnFailure = 0;
+      // What a failed attempt in this loop already cost — or may have.
+      let failedBooking: FailedBooking | null = null;
       for (const m of models) {
         // Stop starting NEW attempts once the loop has burned its whole budget —
         // otherwise the bound would be per-model only and would grow with the list.
@@ -516,59 +679,37 @@ Run blockrun_models to see all available models with pricing.`,
           // Paid tiers stream (frontier primaries can generate for minutes —
           // same 524 class as the explicit-model path). The free tier stays on
           // the non-streaming client whose short timeout the deadline loop
-          // depends on to fail fast through its seven candidates.
-          const { result: response, settledUsd } = await withSettledCost(routingClient, async () => {
-            if (!freeClient && supportsStreaming(routingClient)) {
-              return streamChatText(routingClient, m, [
-                ...(system ? [{ role: "system" as const, content: system }] : []),
-                { role: "user" as const, content: message },
-              ], { maxTokens: max_tokens, temperature, responseFormat, stop });
-            }
-            return routingClient.chat(m, message, {
-              system,
-              maxTokens: max_tokens,
-              temperature,
-              responseFormat,
-              stop,
-            });
-          }, (usd) => {
-            // Settled, then failed. Book it and remember that this tool call has
-            // already cost the caller money — see the break below.
-            recordActualSpend(budget, usd, estimatedCost, agent_id);
-            settledOnFailure = usd;
-          });
-          recordActualSpend(budget, settledUsd, estimatedCost, agent_id);
-          const note = freeTierTruncationNote(promptChars, m);
+          // depends on to fail fast through its candidates.
+          const { reply, notes, fields } = await attempt(routingClient, m, [
+            ...(system ? [{ role: "system" as const, content: system }] : []),
+            { role: "user" as const, content: message },
+          ], !freeClient, (b) => { failedBooking = b; });
           return {
-            content: [{ type: "text", text: `[${m}]\n\n${response}${note ?? ""}` }],
-            structuredContent: { model_used: m, response, ...(note ? { truncated: true } : {}) },
+            content: [{ type: "text", text: `[${m}]\n\n${reply}${notes}` }],
+            structuredContent: { model_used: m, response: reply, ...fields },
           };
         } catch (error) {
           lastError = error;
           // ONE RESERVATION MEANS ONE SETTLEMENT. The fallback loop exists for
-          // models that refuse before taking payment (400, refusal, timeout) —
-          // there, trying the next model costs nothing and is the whole point.
-          // But a model that settled and THEN failed has already charged the
-          // caller, and continuing would settle a second payment for the same
-          // tool call under the same reserved amount, unbounded by the gate.
-          // Free models settle $0, so mode:"free" still falls through as designed.
-          if (settledOnFailure > 0) break;
+          // models that refuse before taking payment (400, refusal, an unpaid
+          // timeout) — there, trying the next model costs nothing and is the
+          // whole point. But a model that settled and THEN failed has already
+          // charged the caller, and one whose payment was sent and never
+          // answered MAY have — continuing would settle a second payment for
+          // the same tool call under the same reserved amount, unbounded by
+          // the gate. Free models reserve $0, so mode:"free" always falls
+          // through, on every rail.
+          if (failedBooking) break;
           continue;
         }
       }
 
-      // Say it plainly: the payment settled before the failure, so the charge
-      // stands and no fallback was attempted. An agent that reads "failed" as
-      // "free" would retry in a loop and pay each time. (Free models settle $0,
-      // so the deadline case below can never also be a settled one.)
-      if (settledOnFailure > 0) {
-        return {
-          content: [{
-            type: "text",
-            text: settledThenFailedText(lastError, settledOnFailure, "No fallback model was tried — retrying will incur a second charge."),
-          }],
-          isError: true,
-        };
+      // Say it plainly: the payment settled (or may have) before the failure,
+      // so no fallback was attempted. An agent that reads "failed" as "free"
+      // would retry in a loop and pay each time. (Free models reserve $0, so
+      // the deadline case below can never also be a booked one.)
+      if (failedBooking) {
+        return failedText(lastError, failedBooking, "No fallback model was tried — retrying will incur a second charge.");
       }
       // Distinguish "every model rejected" from "we ran out of time" — they need
       // different things from the caller (retry vs. pick a paid model), and a bare
diff --git a/src/tools/defi.ts b/src/tools/defi.ts
index dca4415..282f334 100644
--- a/src/tools/defi.ts
+++ b/src/tools/defi.ts
@@ -12,8 +12,9 @@ import { reserveBudget, recordSpending, recordActualSpend } from "../utils/budge
 import { confirmSpend } from "../utils/confirm-spend.js";
 import { withTxFee } from "../utils/tx-fee.js";
 import { baseOnlyMessage, getClient } from "../utils/wallet.js";
-import { type RawClient, rawGet } from "../utils/raw-call.js";
-import { formatError, extractErrorMessage } from "../utils/errors.js";
+import { ledgerFallback, rawGet, type RawClient } from "../utils/raw-call.js";
+import { formatError } from "../utils/errors.js";
+import { pathToolFailure } from "../utils/path-tool-catch.js";
 import { hasPathTraversal } from "../utils/path-safety.js";
 import type { BudgetState } from "../types.js";
 
@@ -52,6 +53,9 @@ Use blockrun_price (free) for plain spot quotes, blockrun_dex (free) for DEX pai
       },
     },
     async ({ path, agent_id }) => {
+      // The reserve of the paid request in flight, for the catch: 0 until the
+      // line before rawGet, so nothing thrown earlier can book a charge.
+      let sentUsd = 0;
       try {
         // sol.blockrun.ai does not serve /v1/defillama/* at all — it 404s, which
         // reaches the agent as a bare "Not Found" with nothing to act on. Probed
@@ -84,8 +88,9 @@ Use blockrun_price (free) for plain spot quotes, blockrun_dex (free) for DEX pai
           const confirm = await confirmSpend(server, { usd: estimatedCost, label: `defi · ${cleanPath}` });
           if (!confirm.ok) return { content: [{ type: "text", text: confirm.reason ?? "Charge cancelled." }] };
           const client = getClient() as unknown as RawClient;
+          sentUsd = estimatedCost;
           const { data: result, paidUsd } = await rawGet(client, `/v1/defillama/${cleanPath}`);
-          recordActualSpend(budget, paidUsd, estimatedCost, agent_id);
+          recordActualSpend(budget, paidUsd, ledgerFallback(estimatedCost), agent_id);
           return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
             structuredContent: (typeof result === "object" && result !== null && !Array.isArray(result)
@@ -96,10 +101,13 @@ Use blockrun_price (free) for plain spot quotes, blockrun_dex (free) for DEX pai
           gate.release();
         }
       } catch (err) {
-        return {
-          content: [{ type: "text", text: formatError(extractErrorMessage(err)) }],
-          isError: true,
-        };
+        // Books the reserve when the payment went out and no origin answer came
+        // back (utils/path-tool-catch.ts). The gateway's defillama route, like
+        // exa's, answers an upstream 5xx with "Payment was NOT charged" WITHOUT
+        // releasing the payment nonce, so on Base the SDK's same-header retry is
+        // refused as a replay and surfaces as "Payment was rejected. Check your
+        // wallet balance." — replayUpstream adds the second reading on Base only.
+        return pathToolFailure(err, { budget, agentId: agent_id, sentUsd, replayUpstream: "DefiLlama" });
       }
     }
   );
diff --git a/src/tools/exa.ts b/src/tools/exa.ts
index 43b422d..2166ed6 100644
--- a/src/tools/exa.ts
+++ b/src/tools/exa.ts
@@ -12,8 +12,9 @@ import { confirmSpend } from "../utils/confirm-spend.js";
 import { withTxFee } from "../utils/tx-fee.js";
 import { asStructuredContent, coerceBody } from "../utils/body.js";
 import { getClient } from "../utils/wallet.js";
-import { type RawClient, rawPost } from "../utils/raw-call.js";
-import { formatError, extractErrorMessage } from "../utils/errors.js";
+import { ledgerFallback, rawPost, type RawClient } from "../utils/raw-call.js";
+import { formatError } from "../utils/errors.js";
+import { pathToolFailure } from "../utils/path-tool-catch.js";
 import { hasPathTraversal, normalizeClassifyPath } from "../utils/path-safety.js";
 import type { BudgetState } from "../types.js";
 
@@ -61,6 +62,9 @@ Full request/response shapes + worked research workflows in the \`exa-research\`
       },
     },
     async ({ path, body, agent_id }) => {
+      // The reserve of the paid request in flight, for the catch: 0 until the
+      // line before rawPost, so nothing thrown earlier can book a charge.
+      let sentUsd = 0;
       try {
         body = coerceBody(body);
         const cleanPath = path.replace(/^\/+/, "").replace(/^v1\/exa\//, "");
@@ -83,8 +87,9 @@ Full request/response shapes + worked research workflows in the \`exa-research\`
           if (!confirm.ok) return { content: [{ type: "text", text: confirm.reason ?? "Charge cancelled." }] };
           const client = getClient() as unknown as RawClient;
           const endpoint = `/v1/exa/${cleanPath}`;
+          sentUsd = estimatedCost;
           const { data: result, paidUsd } = await rawPost(client, endpoint, body ?? {});
-          recordActualSpend(budget, paidUsd, estimatedCost, agent_id);
+          recordActualSpend(budget, paidUsd, ledgerFallback(estimatedCost), agent_id);
           return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
             structuredContent: asStructuredContent(result),
@@ -93,7 +98,14 @@ Full request/response shapes + worked research workflows in the \`exa-research\`
           gate.release();
         }
       } catch (err) {
-        return { content: [{ type: "text", text: formatError(extractErrorMessage(err)) }], isError: true };
+        // Books the reserve when the payment went out and no origin answer came
+        // back (utils/path-tool-catch.ts). replayUpstream: the gateway's exa
+        // route answers an Exa 5xx with "Payment was NOT charged" WITHOUT
+        // releasing the payment nonce, so on Base the SDK's same-header retry
+        // is refused as a replay and surfaces as the SDK's "Payment was
+        // rejected. Check your wallet balance." — the hedge in utils/errors.ts
+        // adds that second reading on Base only.
+        return pathToolFailure(err, { budget, agentId: agent_id, sentUsd, replayUpstream: "Exa" });
       }
     }
   );
diff --git a/src/tools/image.ts b/src/tools/image.ts
index 8fe58b9..abe639d 100644
--- a/src/tools/image.ts
+++ b/src/tools/image.ts
@@ -3,14 +3,16 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { TOOL_ANNOTATIONS } from "../tool-annotations.js";
 import { z } from "zod";
 import { PaymentError } from "@blockrun/llm";
-import { BudgetExceededError, assertQuoteNearEstimate, reReserveIfHigher, recordActualSpend, recordSpending, reserveBudget } from "../utils/budget.js";
+import { BudgetExceededError, assertQuoteNearEstimate, reReserveIfHigher, recordActualSpend, reserveBudget } from "../utils/budget.js";
 import { withTxFee } from "../utils/tx-fee.js";
 import { formatError } from "../utils/errors.js";
 import { launchTopUp } from "../utils/onramp.js";
+import { sendPaid, settleGiveUp, trackPaidRequest } from "../utils/in-flight.js";
 import type { BudgetState } from "../types.js";
 import { getChain, getImageClient } from "../utils/wallet.js";
 import { isApiKeyMode } from "../utils/auth.js";
-import { apiKeyPost } from "../utils/api-key-call.js";
+import { apiKeyAsyncPost, BilledJobError } from "../utils/api-key-call.js";
+import { ledgerFallback } from "../utils/raw-call.js";
 import { solanaPaidPost } from "../utils/solana-402.js";
 import { isBlockedFetchHostResolved } from "../utils/ssrf.js";
 import { shouldInline, buildInlineImageBlock } from "../utils/inline-image.js";
@@ -230,6 +232,12 @@ function isLargerThanBase(model: string, size: string): boolean {
 // micro SHORT. So: do NOT use withTxFee() here (it rounds), and do not
 // pre-round the buffer. Same shape as the gateway's
 // usdToMicroUsdc(addTransactionFee(price)).
+//
+// This is the RESERVE. The gateway's fee has since dropped to $0.001 (the
+// same 402 probe quoted cogview-4 at $0.016750 on 2026-09-13) and has
+// flip-flopped before, so the gate keeps reserving the higher figure on
+// purpose (utils/tx-fee.ts) and the Base ledger books ledgerFallback() of it —
+// the two are different numbers by design; see the Base branch below.
 const IMAGE_QUOTE_BUFFER = 1.05;
 const IMAGE_TX_FEE_USD = 0.002;
 
@@ -247,6 +255,15 @@ export function estimateCost(model: string, size: string): number {
 // paid request's timeout must cover the whole render — not just a round-trip.
 const SOLANA_IMAGE_TIMEOUT_MS = 300_000;
 
+// The account rail answers inline when the render fits its 30s window and
+// otherwise 202 + poll_url (the vendored gateway route; "the account is
+// charged on completion"). gpt-image-2 — this tool's default — routinely takes
+// longer, and every edit does. The same total as the Solana render timeout,
+// in 5s polls that the account helper clamps to what is left of it.
+const ACCOUNT_IMAGE_POLL_BUDGET_MS = SOLANA_IMAGE_TIMEOUT_MS;
+const ACCOUNT_IMAGE_POLL_INTERVAL_MS = 5_000;
+const ACCOUNT_IMAGE_POLL_TIMEOUT_MS = 60_000;
+
 /**
  * The image2image routes (both gateways) ship the provider's output verbatim —
  * google/nano-banana returns a multi-megabyte base64 data URI, not a hosted
@@ -257,6 +274,9 @@ export async function materializeImageUrl(imageUrl: string): Promise<string> {
   if (!imageUrl.startsWith("data:image/")) return imageUrl;
   const m = /^data:image\/([a-z0-9.+-]+);base64,(.+)$/is.exec(imageUrl);
   if (!m) return imageUrl; // undecodable — better to return the paid result verbatim than drop it
+  // The subtype is upstream output, but the capture above admits no `/` or
+  // `\`, so it can only ever be the last segment of a name INSIDE tmpdir —
+  // see test/image-materialize.test.ts, which pins that property.
   const ext = m[1].toLowerCase() === "jpeg" ? "jpg" : m[1].toLowerCase();
   const file = join(tmpdir(), `blockrun-image-${Date.now()}-${randomBytes(4).toString("hex")}.${ext}`);
   await writeFile(file, Buffer.from(m[2], "base64"));
@@ -264,14 +284,19 @@ export async function materializeImageUrl(imageUrl: string): Promise<string> {
 }
 
 /**
- * Endpoint + body for a Solana-gateway image call. The gateway's zod schema
- * takes quality as low|medium|high|auto (the OpenAI latency knob), not this
- * tool's standard|hd — map hd→high and drop standard (the gateway default)
- * so the request isn't rejected with a 400.
+ * Endpoint + body for a gateway image call on the Solana and account rails.
+ *
+ * No `quality` key, ever. Since gateway commit 397e5d1c (live 2026-09-11)
+ * /v1/images/generations refuses ANY quality value for every model this tool
+ * lists — only the two gpt-image-2.5 ids accept one — and it refuses it
+ * BEFORE the 402, so the old standard|hd knob could only ever turn a paid call
+ * into a 400 (unpaid probes 2026-09-13: quality "standard", "hd" and "high"
+ * all 400 on Base and the account rail; the same body without it quotes). The
+ * parameter is gone from the schema for the same reason.
  */
 export function buildSolanaImageRequest(
   action: "generate" | "edit",
-  params: { model: string; prompt: string; size: string; quality?: string; image?: string | string[]; mask?: string },
+  params: { model: string; prompt: string; size: string; image?: string | string[]; mask?: string },
 ): { endpoint: string; body: Record<string, unknown> } {
   if (action === "edit") {
     return {
@@ -293,7 +318,6 @@ export function buildSolanaImageRequest(
       prompt: params.prompt,
       size: params.size,
       n: 1,
-      ...(params.quality === "hd" ? { quality: "high" } : {}),
     },
   };
 }
@@ -333,12 +357,26 @@ Source images and masks accept a base64 data URI, an http(s) URL, or a local fil
           .describe("Source image(s) for edit action: a base64 data URI, an http(s) URL, or a local file path (auto-encoded to a data URI) — or an array of 2–4 to fuse into one render (e.g. subject + layout guide, or reference + brand logo). openai/* accepts up to 4, google/* up to 3; a mask cannot be combined with multiple images."),
         mask: z.string().optional().describe("Inpaint mask for edit action (openai/gpt-image-* only): a base64 data URI, http(s) URL, or local file path. Transparent areas of the mask are regenerated. Cannot be combined with multiple source images."),
         size: z.string().optional().default("1024x1024").describe("Image size. Common values: 1024x1024 (all models), 1536x1024 / 1024x1536 (gpt-image-*), 2048x2048 / 4096x4096 (nano-banana-pro), 1280x720 / 2048x1024 / 2048x2048 / 2848x1600 (seedream-5-pro)"),
-        quality: z.enum(["standard", "hd"]).optional().default("standard"),
+        // There is deliberately NO `quality` parameter. The gateway refuses
+        // every quality value for every model listed here, before the 402
+        // (see buildSolanaImageRequest), so the old standard|hd knob — and its
+        // zod default of "standard", which the Base SDK path forwarded
+        // verbatim — 400'd every Base generate. A caller that still sends one
+        // has it stripped by the schema and nothing here reads it.
         inline: z.boolean().optional().describe("Return a small inline image preview (thumbnail) the client can render in-conversation, in addition to the full-resolution URL. Defaults to the BLOCKRUN_INLINE_IMAGES env setting (off unless set). Rich clients (e.g. the VS Code extension) render it; plain terminals ignore it. Off keeps responses lightweight."),
         agent_id: z.string().optional().describe("Agent identifier for budget tracking and enforcement."),
       },
     },
-    async ({ prompt, action, model, image, mask, size, quality, inline, agent_id }) => {
+    async ({ prompt, action, model, image, mask, size, inline, agent_id }) => {
+      // Hoisted for the outer catch: a timeout after the payment was sent has
+      // to be booked, and the catch needs the reserve when no quote was seen.
+      let estimatedCostForCatch = 0;
+      // Armed only while a request carrying the payment is outstanding, on
+      // every rail — settled by a response, per call. 0.50.0's boolean was
+      // cleared in a `.finally` the catch never observed on the account rail,
+      // never set on Base, and set BEFORE the unpaid quote probe on Solana, so
+      // a 15s probe timeout booked a whole render (audit round 3).
+      const paid = trackPaidRequest();
       try {
         const selectedModel = model || "openai/gpt-image-2";
 
@@ -408,6 +446,7 @@ Source images and masks accept a base64 data URI, an http(s) URL, or a local fil
         // record the real cost — releasing the reservation in finally on every
         // path (including a decline, which charges nothing).
         const estimatedCost = estimateCost(selectedModel, size);
+        estimatedCostForCatch = estimatedCost;
         let gate = reserveBudget(budget, agent_id, estimatedCost);
         if (!gate.allowed) {
           return {
@@ -434,15 +473,16 @@ Source images and masks accept a base64 data URI, an http(s) URL, or a local fil
           let imageUrl: string | undefined;
           // Actual USDC charged, surfaced in the result footer so the user always
           // sees the price without relying on the plugin's announce-cost skill.
-          // Base has no billed-amount in the SDK response, so the catalog estimate
-          // (which mirrors the live price table) is the best available figure;
-          // Solana returns the real 402-quoted amount.
+          // Base has no billed-amount in the SDK response, so the observed
+          // charge (ledgerFallback of the reserve — see the Base branch) is the
+          // best available figure; Solana returns the real 402-quoted amount
+          // and the account rail its settled cost header.
           let billedUsd = estimatedCost;
           // Whether `billedUsd` is still our own guess rather than a figure the
-          // rail settled. Seeded to the previous behaviour — the Base SDK rail
-          // reports the catalog price and has always been labelled exact — so
-          // this change only affects the account rail, which is the one that can
-          // now do better.
+          // rail settled. The Base SDK rail's observed charge is reconstructed
+          // from a live-verified rate table, not read off a response, and has
+          // always been labelled exact; the account rail flips this when its
+          // cost header is present, Solana when its 402 amount parses.
           let costIsEstimate = isApiKeyMode();
           // isApiKeyMode() first: on the account rail getChain() can still say
           // "solana" (it is the default for a machine with no wallet), and this
@@ -459,18 +499,34 @@ Source images and masks accept a base64 data URI, an http(s) URL, or a local fil
             // 2026-09-05 — a nano-banana image settles at $0.052500 and returns
             // both the header and `price.amount`, against a $0.0535 estimate.
             //
-            // apiKeyPost is the same helper music, speech, video and realface
-            // already use; image was the odd one out only because an SDK client
-            // existed for it.
+            // apiKeyAsyncPost, not apiKeyPost: the gateway answers 202 +
+            // poll_url for any render past its 30s inline window, and the
+            // single-POST helper handed that envelope back as if it were the
+            // image — "No image URL in response", job id and poll_url dropped,
+            // the render orphaned, and the agent's retry submitting another
+            // (audit round 3; a regression of #140, which replaced the SDK's
+            // polling ImageClient on this rail). The async helper handles the
+            // inline 200 and the 202 alike, and its BilledJobError carries
+            // the job id for the catch below.
             const { endpoint, body } = buildSolanaImageRequest(action, {
               model: selectedModel,
               prompt,
               size,
-              quality,
               image: normalizedImage,
               mask: normalizedMask,
             });
-            const r = await apiKeyPost(endpoint, body, { timeoutMs: SOLANA_IMAGE_TIMEOUT_MS });
+            //
+            // Not wrapped in sendPaid, like video and music: this rail bills
+            // at SUBMIT and the helper classifies every post-submit exit
+            // itself — BilledJobError for a billed or unknown outcome,
+            // JobFailedError for a not_charged one. Arming the tracker around
+            // it made a not_charged failure whose upstream text said
+            // "timeout" read as "MAY have settled" (audit round 4).
+            const r = await apiKeyAsyncPost(endpoint, body, {
+              pollBudgetMs: ACCOUNT_IMAGE_POLL_BUDGET_MS,
+              pollIntervalMs: ACCOUNT_IMAGE_POLL_INTERVAL_MS,
+              pollTimeoutMs: ACCOUNT_IMAGE_POLL_TIMEOUT_MS,
+            });
             // paidUsd null is "the rail settled nothing at response time", NOT
             // "free" — fall back to the estimate and say so, never book $0.
             billedUsd = r.paidUsd ?? estimatedCost;
@@ -486,11 +542,18 @@ Source images and masks accept a base64 data URI, an http(s) URL, or a local fil
               model: selectedModel,
               prompt,
               size,
-              quality,
               image: normalizedImage,
               mask: normalizedMask,
             });
+            // The quote, captured for the tracker: armed at the helper's
+            // onPaidRequest (the line before the signed POST leaves) and
+            // settled at onPaidResponse (any status), so the unpaid probe
+            // and the signing step are outside the window and an answered
+            // 5xx is never a maybe.
+            let solQuotedUsd: number | null = null;
             const { data, paidUsd } = await solanaPaidPost(endpoint, body, SOLANA_IMAGE_TIMEOUT_MS, {
+              onPaidRequest: () => paid.arm(solQuotedUsd),
+              onPaidResponse: () => paid.settle(),
               // The Solana gateway prices carry a markup over the Base estimate
               // table, so the real quote can exceed what we reserved. Re-reserve
               // the true amount against the cap BEFORE the transfer is signed
@@ -505,8 +568,11 @@ Source images and masks accept a base64 data URI, an http(s) URL, or a local fil
                 });
                 gate = reReserveIfHigher(budget, gate, agent_id, estimatedCost, quotedUsd);
                 if (!gate.allowed) {
-                  throw new BudgetExceededError(`${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget.`);
+                  // Says so, like the other four manual-402 tools: nothing
+                  // has been signed at this point.
+                  throw new BudgetExceededError(`${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget. No charge was made.`);
                 }
+                solQuotedUsd = quotedUsd;
               },
             });
             recordActualSpend(budget, paidUsd, estimatedCost, agent_id);
@@ -514,14 +580,34 @@ Source images and masks accept a base64 data URI, an http(s) URL, or a local fil
             costIsEstimate = paidUsd === null;
             imageUrl = (data as { data?: Array<{ url?: string }> }).data?.[0]?.url;
           } else {
-            const response = action === "edit"
-              ? await getImageClient().edit(prompt, normalizedImage!, {
+            // ---- Base rail: the SDK's ImageClient owns the 402. ----
+            //
+            // No quote is visible here, so the ledger gets what the gateway is
+            // observed to charge rather than the reserve: the reserve carries
+            // the $0.002 tx fee (rounded against us on purpose — see
+            // estimateCost) where a live 402 probe of the Base route on
+            // 2026-09-13 quoted cogview-4 at $0.016750, i.e. base x 1.05 +
+            // $0.001. Booking the reserve verbatim tripped caps early on
+            // every Base image (audit round 3); ledgerFallback is the same
+            // reconstruction the path tools use.
+            const observedUsd = ledgerFallback(estimatedCost);
+            // The SDK signs and sends the payment inside this call, so the
+            // whole call is the paid window. Its unpaid 402 probe is inside
+            // it too — the SDK offers no seam between the two — so a probe
+            // timeout here is booked as well; that is the conservative
+            // direction, and the gateway answers the probe in well under a
+            // second, so it is a far narrower window than the render.
+            const response = await sendPaid(paid, () => action === "edit"
+              ? getImageClient().edit(prompt, normalizedImage!, {
                   model: selectedModel,
                   size,
                   ...(normalizedMask ? { mask: normalizedMask } : {}),
                 })
-              : await getImageClient().generate(prompt, { model: selectedModel, size, quality: quality as "standard" | "hd" });
-            recordSpending(budget, estimatedCost, agent_id);
+              // No quality option: the SDK forwards any truthy value and the
+              // gateway 400s all of them for these models (see the schema).
+              : getImageClient().generate(prompt, { model: selectedModel, size }), observedUsd);
+            recordActualSpend(budget, null, observedUsd, agent_id);
+            billedUsd = observedUsd;
             imageUrl = response.data?.[0]?.url;
           }
 
@@ -534,12 +620,13 @@ Source images and masks accept a base64 data URI, an http(s) URL, or a local fil
 
           const delivered = await materializeImageUrl(imageUrl);
           const savedLocally = delivered !== imageUrl;
-          // On the wallet rails billedUsd is what was actually signed and settled
-          // (from the 402 quote). On the account rail nothing comes back to read,
-          // so it is this server's own estimate — and it is estimated HIGH, since
-          // estimateCost adds the $0.001 transaction fee that account billing
-          // does not charge. Printing that unlabelled invites someone to
-          // reconcile an invoice against a number we invented.
+          // On Solana billedUsd is what was actually signed and settled (from
+          // the 402 quote); on Base it is the observed charge the ledger books;
+          // on the account rail it is the settled cost header when the gateway
+          // sent one, else this server's own estimate — and that is estimated
+          // HIGH, since estimateCost adds a transaction fee that account
+          // billing does not charge. Printing that unlabelled invites someone
+          // to reconcile an invoice against a number we invented.
           // Label what the number IS, not which rail produced it. Calling a
           // settled amount "estimated" is as misleading as the reverse, and it
           // invites someone to discount a figure that reconciles exactly.
@@ -566,6 +653,27 @@ Source images and masks accept a base64 data URI, an http(s) URL, or a local fil
         if (err instanceof BudgetExceededError) {
           return { content: [{ type: "text", text: errMsg }], isError: true };
         }
+        // The account rail's async path: the gateway accepted the job (or may
+        // have — a submit that never answered), and it is charged when the
+        // render completes whether or not this client is still polling. Book
+        // it and name the job; the one thing not to do is submit again.
+        // Checked before the in-flight tracker, whose sentence would say
+        // "signature" for a rail that has none.
+        if (err instanceof BilledJobError) {
+          recordActualSpend(budget, err.paidUsd, estimatedCostForCatch, agent_id);
+          const what = err.billing === "billed"
+            ? `Image generation did not return an image, but the gateway accepted the render${err.jobId ? ` (job ${err.jobId})` : ""} and the account is charged when it completes.`
+            : `Image generation got no answer to its submit, so the render MAY have been accepted and billed to the BlockRun account.`;
+          return {
+            content: [{ type: "text", text: `${what} $${(err.paidUsd ?? estimatedCostForCatch).toFixed(4)} has been booked against your budget; check https://user.blockrun.ai/dashboard/activity before doing anything else — a new blockrun_image call starts and bills a second render.\nError: ${errMsg}` }],
+            isError: true,
+          };
+        }
+        // A paid request that never answered on the wallet rails (or an SDK
+        // call that dropped mid-payment on Base): the gateway settles on its
+        // own clock, so this is booked and said out loud.
+        const giveUp = settleGiveUp(paid, err, { budget, agentId: agent_id, estimateUsd: estimatedCostForCatch, what: "Image generation" });
+        if (giveUp) return { content: [{ type: "text", text: giveUp.text }], isError: true };
         if (err instanceof PaymentError) {
           return {
             content: [{ type: "text", text: `Image generation needs USDC — your wallet is out of funds. ${(await launchTopUp()).note}\nError: ${errMsg}` }],
diff --git a/src/tools/markets.ts b/src/tools/markets.ts
index 5f6ceea..1bee934 100644
--- a/src/tools/markets.ts
+++ b/src/tools/markets.ts
@@ -5,8 +5,9 @@ import { reserveBudget, recordActualSpend } from "../utils/budget.js";
 import { confirmSpend } from "../utils/confirm-spend.js";
 import { asStructuredContent, coerceBody } from "../utils/body.js";
 import { getClient } from "../utils/wallet.js";
-import { type RawClient, rawGet, rawPost } from "../utils/raw-call.js";
-import { extractErrorMessage, formatError } from "../utils/errors.js";
+import { ledgerFallback, rawGet, rawPost, type RawClient } from "../utils/raw-call.js";
+import { formatError } from "../utils/errors.js";
+import { pathToolFailure } from "../utils/path-tool-catch.js";
 import { hasPathTraversal } from "../utils/path-safety.js";
 import type { BudgetState } from "../types.js";
 import { TOOL_ANNOTATIONS } from "../tool-annotations.js";
@@ -37,7 +38,7 @@ export function registerMarketsTool(server: McpServer, budget: BudgetState): voi
 
 POLYMARKET (Tier 1):
 - polymarket/events, polymarket/markets — list events/markets (filter, sort, paginate)
-- polymarket/markets/keyset, polymarket/events/keyset — same data, cursor-based keyset pagination (use ?pagination_key=)
+- polymarket/markets/keyset, polymarket/events/keyset — same data, cursor-based keyset pagination (params: { pagination_key })
 - polymarket/crypto-updown — crypto up/down markets
 - polymarket/market-price/:token_id — current/historical price
 - polymarket/candlesticks/:condition_id — OHLCV by market
@@ -54,7 +55,7 @@ POLYMARKET (Tier 2 — wallet/smart-money analytics):
 - polymarket/wallet/:wallet — full smart-wallet profile
 - polymarket/wallet/:wallet/markets, .../similar
 - polymarket/wallet/pnl/:wallet, .../positions/:wallet, .../volume-chart/:wallet
-- polymarket/wallets/profiles, polymarket/wallets/filter — batch + AND/OR filter
+- polymarket/wallets/profiles — batch profiles, GET with params: { addresses } (POST 404s); polymarket/wallets/filter — AND/OR filter
 - polymarket/market/:condition_id/smart-money, polymarket/markets/smart-activity
 
 WALLET IDENTITY & CLUSTERING (Tier 2) — cross-context labels + on-chain relationship graph:
@@ -78,16 +79,23 @@ REQUEST CONTRACTS:
 - polymarket/orderbooks requires token_id plus start_time/end_time in Unix milliseconds.
 - Smart-money needs a smart-wallet CRITERION (min_trades, min_volume, min_roi, min_*_pnl, min_win_rate, min_profit_factor). "window" only scopes time and is NOT sufficient on its own. Default: { window: "30d", min_trades: "100" }.
 
-Pass query params via 'params' (GET). Use 'body' only for POST endpoints (e.g. polymarket/wallet/identities).`,
+Pass query params via 'params' (GET) — a '?' in 'path' is refused before payment, because path-carried values bypass the pre-payment checks above. Use 'body' only for POST endpoints (e.g. polymarket/wallet/identities).`,
       annotations: TOOL_ANNOTATIONS.readOnlyOpenWorld,
       inputSchema: {
-        path: z.string().describe("Endpoint path, e.g. 'polymarket/events', 'kalshi/markets/KXBTC-25MAR14', 'polymarket/wallet/0xabc...', 'markets/search'"),
+        // Bare route only. 'kalshi/markets/KXBTC-25MAR14' used to be the example
+        // here; the registry has only the 2-segment 'kalshi/markets' and the
+        // gateway 404s on a segment-count mismatch (probed unauthenticated
+        // 2026-09-13), so copying it cost a wasted turn. Filters go in params.
+        path: z.string().describe("Endpoint path, no query string, e.g. 'polymarket/events', 'kalshi/markets' (filter via params: { ticker: 'KXBTC-25MAR14' }), 'polymarket/wallet/0xabc...', 'markets/search'"),
         params: z.record(z.string(), z.string()).optional().describe("Query parameters for GET requests (e.g. markets/search uses { q: 'Bitcoin', status: 'open', venue: 'polymarket', limit: '20' })"),
         body: z.any().optional().describe("JSON body for POST queries (triggers pmQuery — most endpoints are GET)"),
         agent_id: z.string().optional().describe("Agent identifier for budget tracking and enforcement."),
       },
     },
     async ({ path, params, body, agent_id }) => {
+      // The reserve of the paid request in flight, for the catch: 0 until the
+      // line before rawGet/rawPost, so nothing thrown earlier can book a charge.
+      let sentUsd = 0;
       try {
         body = coerceBody(body);
         // `path` is forwarded verbatim into /v1/pm/${path}; a `..` segment would
@@ -126,10 +134,11 @@ Pass query params via 'params' (GET). Use 'body' only for POST endpoints (e.g. p
           // settled `x-blockrun-cost-usd` instead of discarding the response.
           const llm = getClient() as unknown as RawClient;
           const endpoint = `/v1/pm/${path}`;
+          sentUsd = estimatedCost;
           const { data: result, paidUsd } = body !== undefined
             ? await rawPost(llm, endpoint, body)
             : await rawGet(llm, endpoint, params);
-          recordActualSpend(budget, paidUsd, estimatedCost, agent_id);
+          recordActualSpend(budget, paidUsd, ledgerFallback(estimatedCost), agent_id);
 
           return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
@@ -139,15 +148,17 @@ Pass query params via 'params' (GET). Use 'body' only for POST endpoints (e.g. p
           gate.release();
         }
       } catch (err) {
-        const message = extractErrorMessage(err);
-        // A sports/* 5xx is the known Predexon outage, not a blip, and the
-        // gateway released the payment — say so instead of "after payment …
-        // try again in a few minutes" (blockrun-mcp#132).
-        const degraded = describeDegradedSportsFailure(path, message);
-        return {
-          content: [{ type: "text", text: degraded ?? formatError(message) }],
-          isError: true,
-        };
+        // Books the reserve when the payment went out and no origin answer came
+        // back (utils/path-tool-catch.ts). A sports/* 5xx is the known Predexon
+        // outage, not a blip, and the gateway released the payment — say so
+        // instead of "after payment … try again in a few minutes"
+        // (blockrun-mcp#132); the bespoke text replaces formatError's only.
+        return pathToolFailure(err, {
+          budget,
+          agentId: agent_id,
+          sentUsd,
+          describe: (message) => describeDegradedSportsFailure(path, message),
+        });
       }
     }
   );
diff --git a/src/tools/modal.ts b/src/tools/modal.ts
index 7c384e5..77b6bfd 100644
--- a/src/tools/modal.ts
+++ b/src/tools/modal.ts
@@ -12,8 +12,9 @@ import { confirmSpend } from "../utils/confirm-spend.js";
 import { withTxFee } from "../utils/tx-fee.js";
 import { asStructuredContent, coerceBody } from "../utils/body.js";
 import { baseOnlyMessage, buildClientWithTimeout } from "../utils/wallet.js";
-import { type RawClient, rawPost } from "../utils/raw-call.js";
-import { formatError, extractErrorMessage } from "../utils/errors.js";
+import { ledgerFallback, rawPost, type RawClient } from "../utils/raw-call.js";
+import { formatError } from "../utils/errors.js";
+import { pathToolFailure } from "../utils/path-tool-catch.js";
 import { normalizeClassifyPath } from "../utils/path-safety.js";
 import { hasPathTraversal } from "../utils/path-safety.js";
 import type { BudgetState } from "../types.js";
@@ -35,8 +36,9 @@ import type { BudgetState } from "../types.js";
 //   { timeout: 300 }                -> charged   $0.0120
 //
 // A $1 agent cap could settle $192 of non-refundable spend. Keep these tables in
-// step with the gateway's; an unknown gpu string falls back to the CPU rate there,
-// so it does here too.
+// step with the gateway's. The gateway's CreateRequestSchema 400s BEFORE payment
+// on any gpu string outside its five tiers (case-sensitive: "h100" is refused),
+// so the CPU rate is only ever what an ABSENT gpu pays.
 const MODAL_FLAT_RATE_MAX_SECONDS = 300;
 const MODAL_DEFAULT_CREATE_TIMEOUT_SECONDS = 300;
 const MODAL_CREATE_PRICE_USD = 0.01;
@@ -56,6 +58,47 @@ const MODAL_CPU_HOURLY_PRICE_USD = 0.1;
 const MODAL_GPU_HOURLY_PRICE_USD = new Map<string, number>([
   ["T4", 1.5], ["L4", 2.0], ["A10G", 2.5], ["A100", 4.0], ["H100", 8.0],
 ]);
+const MODAL_GPU_TIERS = [...MODAL_GPU_HOURLY_PRICE_USD.keys()];
+
+// NORMALISE THE BODY THE WAY THE GATEWAY DOES, BEFORE PRICING AND BEFORE
+// SENDING. The gateway's CreateRequestSchema declares `gpu: z.string().trim()`
+// and runs its allow-list check and getModalCreatePricing on the TRIMMED value,
+// so `" H100 "`, `"H100\n"` and an NBSP-padded `"H100"` are all accepted and
+// billed as H100. This estimator looked the raw string up in the Map, missed,
+// and priced the CPU rate — the path-classification bug below, on the body
+// field that carries the largest single charge this server can make. Unpaid
+// 402 probe 2026-09-13: `{ timeout: 3600, gpu: " H100 " }` quotes 8001000
+// micro ($8.001) against a $0.102 reserve; at 24h that is $192.002 against
+// $2.402 — past a $5 cap, past the confirm dialog, and booked as $2.40 on the
+// Base ledger. Trim (String.prototype.trim, same as zod's) and keep the case:
+// the gateway is case-sensitive and 400s "h100" before payment, so folding
+// case would turn a free refusal into a paid H100.
+//
+// The trimmed body is also what gets SENT, so the reserve and the wire agree by
+// construction rather than by a second normalisation on the far side.
+export function normalizeModalCreateBody(body: unknown): unknown {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return body;
+  const o = body as Record<string, unknown>;
+  if (typeof o.gpu !== "string") return body;
+  return { ...o, gpu: o.gpu.trim() };
+}
+
+/**
+ * The refusal for a gpu the gateway would 400 before payment — every string
+ * outside the five tiers, including lowercase and the empty string. Returns
+ * null when the body is fine. Refusing here costs nothing (the gateway would
+ * refuse the same call unpaid) and saves the round-trip; naming the tiers
+ * matters because "Unsupported GPU type" alone sends a model guessing again.
+ * Only sandbox/create carries a priced gpu, so callers gate on the route.
+ */
+export function unsupportedModalGpu(body: unknown): string | null {
+  if (!body || typeof body !== "object") return null;
+  const gpu = (body as { gpu?: unknown }).gpu;
+  if (gpu === undefined || gpu === null) return null;
+  if (typeof gpu === "string" && MODAL_GPU_HOURLY_PRICE_USD.has(gpu)) return null;
+  return `Unsupported GPU type ${JSON.stringify(gpu)}. Allowed: ${MODAL_GPU_TIERS.join(", ")} (case-sensitive), or omit gpu for a CPU sandbox. ` +
+    `The gateway rejects any other value before payment, so nothing would have been served. No payment was made.`;
+}
 
 /** Exported for tests. Returns what x402 will CHARGE (base + the flat tx fee). */
 export function estimateModalCost(path: string, body?: unknown): number {
@@ -71,7 +114,10 @@ export function estimateModalCost(path: string, body?: unknown): number {
   if (!normalizeClassifyPath(path).includes("sandbox/create")) return withTxFee(MODAL_OPERATION_PRICE_USD);
 
   const o = body && typeof body === "object" ? (body as { gpu?: unknown; timeout?: unknown }) : {};
-  const gpu = typeof o.gpu === "string" ? o.gpu : undefined;
+  // Trimmed, as the gateway prices it — see normalizeModalCreateBody. The
+  // handler sends a body normalised the same way; this is belt-and-braces so
+  // the estimator is right even for a caller that skipped the handler.
+  const gpu = typeof o.gpu === "string" ? o.gpu.trim() : undefined;
   // A non-numeric/absent timeout defaults to 300s upstream — the flat tier.
   const seconds =
     typeof o.timeout === "number" && Number.isFinite(o.timeout) && o.timeout > 0
@@ -79,8 +125,11 @@ export function estimateModalCost(path: string, body?: unknown): number {
       : MODAL_DEFAULT_CREATE_TIMEOUT_SECONDS;
 
   if (seconds > MODAL_FLAT_RATE_MAX_SECONDS) {
-    // An unknown or empty gpu falls back to the CPU rate — same as the gateway's
-    // `opts.gpu && opts.gpu in TABLE ? TABLE[gpu] : CPU_RATE`.
+    // An absent gpu is the CPU rate — same as the gateway's
+    // `opts.gpu && opts.gpu in TABLE ? TABLE[gpu] : CPU_RATE`, which runs on
+    // the trimmed value. An unknown gpu also falls back here, but only so the
+    // estimator stays total: the handler refuses it before the reserve
+    // (unsupportedModalGpu), and the gateway 400s it before payment.
     const hourly = gpu !== undefined ? MODAL_GPU_HOURLY_PRICE_USD.get(gpu) : undefined;
     return withTxFee((hourly ?? MODAL_CPU_HOURLY_PRICE_USD) * (seconds / 3600));
   }
@@ -132,6 +181,9 @@ Full pricing tables + GPU details in the \`modal\` skill.`,
       },
     },
     async ({ path, body, agent_id }) => {
+      // The reserve of the paid request in flight, for the catch: 0 until the
+      // line before rawPost, so nothing thrown earlier can book a charge.
+      let sentUsd = 0;
       try {
         // sol.blockrun.ai returns 503 for every /v1/modal/* route — the sandbox
         // backend is Base-only. Probed 2026-08-07 by the dual-chain sweep in
@@ -150,7 +202,18 @@ Full pricing tables + GPU details in the \`modal\` skill.`,
         if (hasPathTraversal(cleanPath)) {
           return { content: [{ type: "text", text: formatError(`Invalid path '${path}'.`) }], isError: true };
         }
-        // Pass the body: sandbox/create is priced from gpu + timeout, not the path.
+        // sandbox/create is priced from gpu + timeout. Normalise the gpu the way
+        // the gateway will (trim) BEFORE estimating and BEFORE sending, so the
+        // reserve, the confirm dialog, the ledger and the wire all describe the
+        // same tier — and refuse a tier the gateway would 400 unpaid, so the
+        // message names the five that exist instead of "API error: 400".
+        if (normalizeClassifyPath(cleanPath).includes("sandbox/create")) {
+          body = normalizeModalCreateBody(body);
+          const badGpu = unsupportedModalGpu(body);
+          if (badGpu) {
+            return { content: [{ type: "text", text: formatError(badGpu) }], isError: true };
+          }
+        }
         const estimatedCost = estimateModalCost(cleanPath, body);
         const gate = reserveBudget(budget, agent_id, estimatedCost);
         if (!gate.allowed) {
@@ -169,8 +232,9 @@ Full pricing tables + GPU details in the \`modal\` skill.`,
           // lengthening the 60s timeout the shared getClient() gives every other tool.
           const client = buildClientWithTimeout(modalTimeoutMs(body)) as unknown as RawClient;
           const endpoint = `/v1/modal/${cleanPath}`;
+          sentUsd = estimatedCost;
           const { data: result, paidUsd } = await rawPost(client, endpoint, body ?? {});
-          recordActualSpend(budget, paidUsd, estimatedCost, agent_id);
+          recordActualSpend(budget, paidUsd, ledgerFallback(estimatedCost), agent_id);
           return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
             structuredContent: asStructuredContent(result),
@@ -179,7 +243,11 @@ Full pricing tables + GPU details in the \`modal\` skill.`,
           gate.release();
         }
       } catch (err) {
-        return { content: [{ type: "text", text: formatError(extractErrorMessage(err)) }], isError: true };
+        // Books the reserve when the payment went out and no origin answer came
+        // back (utils/path-tool-catch.ts) — for sandbox/create that is the full
+        // reserve, which is the point: a create that timed out client-side may
+        // well be running and billed.
+        return pathToolFailure(err, { budget, agentId: agent_id, sentUsd });
       }
     }
   );
diff --git a/src/tools/models.ts b/src/tools/models.ts
index d1ad0db..eab12f5 100644
--- a/src/tools/models.ts
+++ b/src/tools/models.ts
@@ -3,9 +3,10 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { TOOL_ANNOTATIONS } from "../tool-annotations.js";
 import { z } from "zod";
 import type { ImageModel, Model } from "@blockrun/llm";
-import { getClient } from "../utils/wallet.js";
+import { getChain, getClient } from "../utils/wallet.js";
+import { getAuthMode } from "../utils/auth.js";
 import { extractErrorMessage, formatError } from "../utils/errors.js";
-import { loadModels, type ModelCache, type ModelEntry } from "../utils/model-cache.js";
+import { loadModels, modelCacheKey, type ModelCache, type ModelEntry } from "../utils/model-cache.js";
 
 function getModelType(model: ModelEntry): "llm" | "image" {
   return model.type === "image" || "pricePerImage" in model ? "image" : "llm";
@@ -16,7 +17,10 @@ export function registerModelsTool(server: McpServer, modelCache: ModelCache): v
     "blockrun_models",
     {
       description: "List available AI models with pricing. Use to discover models and compare costs.",
-      annotations: TOOL_ANNOTATIONS.readOnly,
+      // readOnlyOpenWorld, not readOnly: this reads the LIVE gateway catalogue
+      // over the network. openWorldHint describes whether the tool reaches
+      // outside the process, and this one does.
+      annotations: TOOL_ANNOTATIONS.readOnlyOpenWorld,
       inputSchema: {
         category: z.enum(["all", "chat", "reasoning", "image", "embedding"]).optional().default("all").describe("Filter by category"),
         provider: z.string().optional().describe("Filter by provider (e.g., 'openai', 'anthropic')"),
@@ -24,7 +28,7 @@ export function registerModelsTool(server: McpServer, modelCache: ModelCache): v
     },
     async ({ category, provider }) => {
       try {
-      let models = await loadModels(getClient(), modelCache);
+      let models = await loadModels(getClient(), modelCache, modelCacheKey(getAuthMode(), getChain()));
 
       if (provider) {
         const p = provider.toLowerCase();
diff --git a/src/tools/music.ts b/src/tools/music.ts
index 648d469..865dd71 100644
--- a/src/tools/music.ts
+++ b/src/tools/music.ts
@@ -2,13 +2,14 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { TOOL_ANNOTATIONS } from "../tool-annotations.js";
 import { z } from "zod";
-import { amountToUsd, reserveBudget, recordActualSpend } from "../utils/budget.js";
+import { amountToUsd, assertQuoteNearEstimate, reserveBudget, recordActualSpend } from "../utils/budget.js";
 import { confirmSpend } from "../utils/confirm-spend.js";
 import { withTxFee } from "../utils/tx-fee.js";
-import { formatError, isPaymentRejectionError } from "../utils/errors.js";
+import { formatError, hasLabelledServerStatus } from "../utils/errors.js";
 import { launchTopUp } from "../utils/onramp.js";
 import { fetchWithTimeout, isTimeoutError } from "../utils/http.js";
-import { pollDeadline, pollTimeoutFor } from "../utils/poll.js";
+import { JobFailedError, pollDeadline, pollTimeoutFor } from "../utils/poll.js";
+import { sendPaid, settleGiveUp, trackPaidRequest } from "../utils/in-flight.js";
 import type { BudgetState } from "../types.js";
 import { getApiBase, getChain, getOrCreateWalletKey, resolveGatewayUrl } from "../utils/wallet.js";
 import { isApiKeyMode } from "../utils/auth.js";
@@ -28,6 +29,16 @@ const MUSIC_COST = withTxFee(0.1575);
 const MUSIC_POLL_INTERVAL_MS = 5_000;
 export const MUSIC_POLL_BUDGET_MS = 240_000; // 4 min polling budget, measured from submit
 export const MUSIC_POLL_TIMEOUT_MS = 90_000;
+// The paid submit on EVERY rail. The audio route races generation against a
+// 60s inline window (blockrun src/app/api/v1/audio/generations/route.ts,
+// inlineGenTimeoutMs) and only then answers 202 + poll_url; fast tracks come
+// back 200 inline, after the GCS backup. The Solana route does the same and
+// settles the SPL transfer at POST regardless of what the client does next —
+// so its 30s helper default (sized for the always-202 video route) aborted
+// every track slower than 30s after the money had moved, with no job id to
+// reclaim it by (audit round 3, C15). One constant, shared, so the rails
+// cannot drift again; music-cost.test.ts pins it against the auth window.
+export const MUSIC_SUBMIT_TIMEOUT_MS = 95_000;
 // Lifetime of the signed payment authorization, in seconds, counted from the
 // moment createPaymentPayload() signs. The polling budget above is measured
 // from a LATER instant (after submit), so the two are not directly comparable —
@@ -92,10 +103,13 @@ export function registerMusicTool(server: McpServer, budget: BudgetState): void
       description: `Generate music tracks via BlockRun x402 (async, client-polled).
 
 Generates a full-length ~3 minute MP3 track. Takes 1-3 minutes to complete. The
-tool submits the job and, for slower tracks, polls until it is ready; payment
-settles only when a finished track is returned — if it fails you are not
-charged; if this client gives up while a paid request is still in flight the
-gateway may still settle, and the error text says so.
+tool submits the job and, for slower tracks, polls until it is ready. On Base
+and the account rail payment settles only when a finished track is returned —
+if the job fails you are not charged; if this client gives up while a paid
+request is still in flight the gateway may still settle, and the error text
+says so. On Solana the gateway settles the payment when it ACCEPTS the job, so
+a job that later fails or outlives the poll budget is still charged — the error
+text says so and names the job, which stays claimable for ~48h.
 
 Model: minimax/music-2.5+ ($0.1575/track, up to ~4 min)
 
@@ -123,11 +137,23 @@ Returns a permanent BlockRun-hosted URL.`,
       // flight can still settle server-side. Every give-up also names the job.
       let jobId: string | undefined;
       let quotedUsd: number | null = null;
-      // True while a Base request carrying the payment header — the submit,
-      // which can settle inline, or a poll — has been issued and has not
-      // answered. A poll that rejects leaves it true: that request may still be
-      // settling on the gateway, which does not stop on disconnect.
-      let paidRequestInFlight = false;
+      // Whether a request carrying the payment is outstanding, per call. Armed
+      // the moment a signed request is about to leave — the submit, which can
+      // settle inline, or a poll — never around the unpaid quote; settled on
+      // every answer. utils/in-flight.ts explains why the hand-rolled boolean
+      // this replaces was wrong on every rail.
+      const paid = trackPaidRequest();
+      // Set once a request carrying the payment has left at all (formatError's
+      // afterPayment: a 5xx that came back is an answer, not a verdict).
+      let paidRequestSent = false;
+      // The amount booked once settlement was OBSERVED. Read by the catch: an
+      // error after this point is a real charge with an unusable result, and
+      // the message must say the charge stands rather than "failed" (D13).
+      let bookedUsd: number | null = null;
+      const book = (paidUsd: number | null) => {
+        recordActualSpend(budget, paidUsd, MUSIC_COST, agent_id);
+        bookedUsd = paidUsd ?? MUSIC_COST;
+      };
       try {
         // NO CHAIN GUARD. This tool refused every Solana call until 2026-09-05
         // ("settles on Base only"), which stopped being true well before that:
@@ -161,12 +187,18 @@ Returns a permanent BlockRun-hosted URL.`,
 
         // ---- Rail 1: account API key. No quote, no signature, no expiry. ----
         if (isApiKeyMode()) {
+          // Not wrapped in sendPaid: this rail bills at SUBMIT and the helper
+          // classifies every post-submit exit as a BilledJobError itself.
+          // Arming here would make a not_charged terminal failure whose
+          // upstream text says "timeout" read as "may have settled".
+          paidRequestSent = true;
           const { data, paidUsd, txHash } = await apiKeyAsyncPost("/v1/audio/generations", body, {
             pollBudgetMs: MUSIC_POLL_BUDGET_MS,
             pollIntervalMs: MUSIC_POLL_INTERVAL_MS,
+            submitTimeoutMs: MUSIC_SUBMIT_TIMEOUT_MS,
             pollTimeoutMs: MUSIC_POLL_TIMEOUT_MS,
           });
-          recordActualSpend(budget, paidUsd, MUSIC_COST, agent_id);
+          book(paidUsd);
           const t = (data as { data?: Array<{ url: string; duration_seconds?: number; lyrics?: string }> }).data?.[0];
           if (!t?.url) throw new Error("Completed response missing track URL");
           // Estimated only when the rail gave us nothing to settle against.
@@ -174,14 +206,52 @@ Returns a permanent BlockRun-hosted URL.`,
         }
 
         // ---- Rail 2: Solana wallet. Same reusable helper blockrun_video uses. ----
+        // sol.blockrun.ai settles this route OPTIMISTICALLY at POST (the 202
+        // says payment_status "settled_optimistic"); the helper reads that
+        // from the wire and turns every later failure into a BilledJobError,
+        // which the catch books as a certain charge.
         if (getChain() === "solana") {
           const { solanaPaidAsyncPost } = await import("../utils/solana-402.js");
-          const { data, paidUsd, txHash } = await solanaPaidAsyncPost("/v1/audio/generations", body, {
+          const { data, paidUsd, txHash, jobId: solJobId } = await solanaPaidAsyncPost("/v1/audio/generations", body, {
             pollBudgetMs: MUSIC_POLL_BUDGET_MS,
+            submitTimeoutMs: MUSIC_SUBMIT_TIMEOUT_MS,
+            // The helper's messages name their caller; without these a music
+            // give-up said "Video generation did not complete" and told the
+            // agent that re-running blockrun_video would charge a new job.
+            what: "Music generation",
+            tool: "blockrun_music",
+            // The helper offers this hook and music passed nothing, so the
+            // guard fired against no one and the SPL transfer was signed for
+            // whatever the quote said (audit round 2).
+            onQuote: (solQuotedUsd, quoteDetails) => {
+              // Captured for the give-up path: on Solana the quote is only ever
+              // seen inside the helper.
+              quotedUsd = solQuotedUsd;
+              assertQuoteNearEstimate(solQuotedUsd, MUSIC_COST, {
+                what: `${model} music`,
+                quotedFor: quoteDetails?.resource?.description,
+                hint: `Retry on Base (blockrun_wallet action:"chain" chain:"base"), or report the quote.`,
+              });
+              if (solQuotedUsd !== null && solQuotedUsd > MUSIC_COST) {
+                gate?.release();
+                gate = reserveBudget(budget, agent_id, solQuotedUsd);
+                if (!gate.allowed) throw new Error(`${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget. No charge was made.`);
+              }
+              // Last: nothing can refuse the quote past this line and the
+              // helper signs next (see video.ts for the residual window).
+              paid.arm(solQuotedUsd);
+            },
+            // Exact edges of every signed request — submit and each poll — so
+            // a deadline reached with the last poll answered books nothing and
+            // one reached with a poll in flight books the quote (C32/C37).
+            onPaidRequest: () => { paidRequestSent = true; paid.arm(quotedUsd); },
+            onPaidResponse: () => paid.settle(),
           });
+          paid.settle();
+          jobId = solJobId;
           // Book before validating the payload: a malformed completed body must
           // not make a settled charge vanish from the local ledger.
-          recordActualSpend(budget, paidUsd, MUSIC_COST, agent_id);
+          book(paidUsd);
           const t = (data as { data?: Array<{ url: string; duration_seconds?: number; lyrics?: string }> }).data?.[0];
           if (!t?.url) throw new Error("Completed Solana response missing track URL");
           return musicResult(t, (data as { model?: string }).model || model, paidUsd ?? MUSIC_COST, txHash, false);
@@ -211,6 +281,23 @@ Returns a permanent BlockRun-hosted URL.`,
         const details = extractPaymentDetails(paymentRequired);
         quotedUsd = amountToUsd(details.amount);
 
+        // WHAT was quoted, before how much. 0.49.0 added this to video (both
+        // rails) and image (Solana) and left the identical hand-rolled flows
+        // here unguarded — so a gateway that quotes a different product, the
+        // way sol.blockrun.ai quoted azure/sora-2 as Seedance at 2.7x, was
+        // signed unseen. Refusing costs nothing: nothing is signed yet.
+        assertQuoteNearEstimate(quotedUsd, MUSIC_COST, {
+          what: `${model} music`,
+          quotedFor: details.resource?.description,
+          hint: `Retry on Solana (blockrun_wallet action:"chain" chain:"solana"), or report the quote.`,
+        });
+        // And the cap, against the REAL price rather than the estimate.
+        if (quotedUsd !== null && quotedUsd > MUSIC_COST) {
+          gate?.release();
+          gate = reserveBudget(budget, agent_id, quotedUsd);
+          if (!gate.allowed) throw new Error(`${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget. No charge was made.`);
+        }
+
         // validBefore is counted from HERE, so the authorization deadline has to
         // be stamped here too — not after submit, which can burn up to 95s.
         const signedAt = Date.now();
@@ -236,19 +323,23 @@ Returns a permanent BlockRun-hosted URL.`,
         // Step 2: submit with payment. Fast tracks complete inline (200); slower
         // ones (MiniMax music is 1-3 min) return 202 + poll_url — the server
         // verified the payment but does NOT settle until a completed poll.
-        paidRequestInFlight = true;
-        const submitResp = await fetchWithTimeout(url, {
+        // Armed for the round trip: an inline 200 IS a settlement, so a submit
+        // that leaves with the signature and never answers is not "no charge".
+        paidRequestSent = true;
+        const submitResp = await sendPaid(paid, () => fetchWithTimeout(url, {
           method: "POST",
           headers: {
             "Content-Type": "application/json",
             "PAYMENT-SIGNATURE": paymentPayload,
           },
           body: JSON.stringify(body),
-        }, 95_000);
-        paidRequestInFlight = false;
+        }, MUSIC_SUBMIT_TIMEOUT_MS), quotedUsd);
 
         if (submitResp.status === 402) {
-          throw new Error("Payment rejected. Check your wallet balance.");
+          // The one answer that IS a funding problem. Named like the SDK's
+          // class so the catch classifies it by type, not by its words.
+          await submitResp.json().catch(() => ({}));
+          throw Object.assign(new Error("Payment rejected. Check your wallet balance."), { name: "PaymentError" });
         }
         if (!submitResp.ok && submitResp.status !== 202) {
           const errBody = await submitResp.json().catch(() => ({ error: "Request failed" })) as Record<string, unknown>;
@@ -295,23 +386,21 @@ Returns a permanent BlockRun-hosted URL.`,
             if (pollTimeoutMs === 0) break;
 
             let pollResp: Response;
-            paidRequestInFlight = true;
             try {
-              pollResp = await fetchWithTimeout(pollAbsoluteUrl, {
+              pollResp = await sendPaid(paid, () => fetchWithTimeout(pollAbsoluteUrl, {
                 method: "GET",
                 headers: { "PAYMENT-SIGNATURE": paymentPayload },
-              }, pollTimeoutMs);
+              }, pollTimeoutMs), quotedUsd);
             } catch {
               // Polling is idempotent and settlement has not been observed. A
               // transient disconnect is safe to retry inside the existing
               // deadline (the EIP-3009 nonce is single-use, so re-sending the
               // same header after a lost-in-flight settlement cannot settle
-              // twice), and one reset must not abandon a paid job.
-              // paidRequestInFlight stays true: the request that never answered
-              // may still be settling server-side.
+              // twice), and one reset must not abandon a paid job. The tracker
+              // stays armed: the request that never answered may still be
+              // settling server-side.
               continue;
             }
-            paidRequestInFlight = false;
 
             const pollData = await pollResp.json().catch(() => ({})) as {
               status?: string;
@@ -329,12 +418,15 @@ Returns a permanent BlockRun-hosted URL.`,
             // a real charge the ledger never saw (the fix video.ts got in
             // 0.39.1, which music did not).
             if (lastStatus === "completed" && !spendBooked) {
-              recordActualSpend(budget, quotedUsd, MUSIC_COST, agent_id);
+              book(quotedUsd);
               spendBooked = true;
             }
 
             if (pollResp.status === 202 && (lastStatus === "queued" || lastStatus === "in_progress")) continue;
-            if (lastStatus === "failed") throw new Error(`Upstream generation failed: ${pollData.error || "unknown"}. No payment taken.`);
+            // Typed: the upstream text rides along verbatim and is not a
+            // verdict on the money; the gateway's contract is that a failed
+            // job on this route is not charged.
+            if (lastStatus === "failed") throw new JobFailedError(`Upstream generation failed: ${pollData.error || "unknown"}. No payment taken.`, { jobId });
             if (pollResp.ok && lastStatus === "completed") {
               const t = pollData.data?.[0];
               if (!t?.url) throw new Error("Completed poll missing track URL");
@@ -349,8 +441,8 @@ Returns a permanent BlockRun-hosted URL.`,
             // 504 on poll = transient upstream poll timeout — retry.
           }
           if (!track) {
-            // Whether money moved depends on paidRequestInFlight, which the
-            // catch reads; the message here states only what was observed.
+            // Whether money moved depends on the tracker, which the catch
+            // reads; the message here states only what was observed.
             throw new Error(`Music generation did not complete within ${Math.round(MUSIC_POLL_BUDGET_MS / 1000)}s (last status: ${lastStatus}).`);
           }
         } else {
@@ -359,7 +451,7 @@ Returns a permanent BlockRun-hosted URL.`,
           // before reading the body (speech.ts does the same): a truncated body
           // or a stripped receipt header must not un-record money that moved.
           txHash = submitResp.headers.get("X-Payment-Receipt") || submitResp.headers.get("x-payment-receipt");
-          recordActualSpend(budget, quotedUsd, MUSIC_COST, agent_id);
+          book(quotedUsd);
           spendBooked = true;
           const data = await submitResp.json().catch(() => null) as { data?: Array<{ url: string; duration_seconds?: number; lyrics?: string }>; model?: string } | null;
           track = data?.data?.[0];
@@ -373,64 +465,79 @@ Returns a permanent BlockRun-hosted URL.`,
         const billedUsd = quotedUsd ?? MUSIC_COST;
         // Backstop only — every reachable path here has already booked at the
         // moment settlement was observed.
-        if (!spendBooked) recordActualSpend(budget, quotedUsd, MUSIC_COST, agent_id);
+        if (!spendBooked) book(quotedUsd);
 
         return musicResult(track, modelReturned || model, billedUsd, txHash, false);
       } catch (err) {
         const errMsg = err instanceof Error ? err.message : String(err);
-        // The account rail bills at SUBMIT. A failure after that — deadline,
-        // poll error, terminal failure — leaves a charge the ledger must carry
-        // (finally releases the reservation, so without this booking the cap
-        // silently rises by the track price), and the one thing the caller must
-        // not do is "try again": that submits and bills a second job. Checked
-        // before isTimeoutError, which matches the deadline message and would
-        // glue retry advice onto a note saying the job was billed.
+        const reclaim = jobId ? ` The finished job stays claimable on the gateway for ~48h (job ${jobId}); re-running blockrun_music would start and charge a new job.` : "";
+        // Same classification, same order, on all three rails as video.ts —
+        // every step is something the code observed, never a word in the
+        // message (audit round 3, C13/C32/C36/C37).
+        //
+        // 1. Settlement was observed and booked, then the result could not be
+        //    used. The charge stands; do not run the tool again (D13).
+        if (bookedUsd !== null) {
+          return {
+            content: [{ type: "text", text: `Music generation completed and the charge stands — $${bookedUsd.toFixed(4)} was settled${jobId ? ` for job ${jobId}` : ""} and is booked against your budget — but the result could not be used: ${errMsg}${reclaim || " Re-running blockrun_music would start and charge a new job."}\nCheck blockrun_wallet action:"report" before doing anything else.` }],
+            isError: true,
+          };
+        }
+        // 2. Billed at SUBMIT — the account rail always, and the Solana audio
+        //    route (settled optimistically at POST) via the shared helper — and
+        //    the failure came after. The ledger must carry it, and the one
+        //    thing the caller must not do is "try again".
         if (err instanceof BilledJobError) {
           recordActualSpend(budget, err.paidUsd, MUSIC_COST, agent_id);
+          const account = isApiKeyMode();
+          const billedTo = account ? "the BlockRun account" : "the Solana wallet";
           const what = err.billing === "billed"
-            ? `Music generation did not return a track, but the job was billed to the BlockRun account when the gateway accepted it${err.jobId ? ` (job ${err.jobId})` : ""}.`
-            : `Music generation got no answer to its submit, so the job MAY have been accepted and billed to the BlockRun account.`;
+            ? `Music generation did not return a track, but the job was billed to ${billedTo} when the gateway accepted it${err.jobId ? ` (job ${err.jobId})` : ""}.`
+            : `Music generation got no answer to its submit, so the job MAY have been accepted and billed to ${billedTo}.`;
+          const where = account ? "https://user.blockrun.ai/dashboard/activity" : `blockrun_wallet action:"report" or the wallet's recent transactions`;
           return {
-            content: [{ type: "text", text: `${what} Check https://user.blockrun.ai/dashboard/activity before doing anything else — a new blockrun_music call starts and bills a second job.\nError: ${errMsg}` }],
+            content: [{ type: "text", text: `${what} Check ${where} before doing anything else — a new blockrun_music call starts and bills a second job.\nError: ${errMsg}` }],
             isError: true,
           };
         }
-        // "Fund your wallet" is the wrong remedy on the account rail — there is
-        // no wallet, and launchTopUp() would try to provision one to send a card
-        // onramp to. apiKeyAsyncPost already returns the correct message for a
-        // 402 there (top up credit at the portal), so let it through untouched.
-        if (isPaymentRejectionError(errMsg) && !isApiKeyMode()) {
+        // 3. The wallet refused to pay: a 402 on the signed request, by type.
+        //    "Fund your wallet" is the wrong remedy on the account rail — there
+        //    is no wallet — and apiKeyAsyncPost words its own 402, so this is
+        //    never reached there (the helper throws no PaymentError).
+        if (err instanceof Error && err.name === "PaymentError") {
           return {
             content: [{ type: "text", text: `Music generation needs USDC — your wallet is out of funds. ${(await launchTopUp()).note}\nError: ${errMsg}` }],
             isError: true,
           };
         }
+        // 4. A request carrying the payment was outstanding and no answer was
+        //    observed: an inline submit can settle (200) and the gateway
+        //    settles a completed poll whether or not we are still connected.
+        //    Booked and said out loud; the tracker decides, not the chain.
+        const giveUp = settleGiveUp(paid, err, { budget, agentId: agent_id, estimateUsd: MUSIC_COST, what: "Music generation", note: reclaim.trim() || undefined });
+        if (giveUp) return { content: [{ type: "text", text: giveUp.text }], isError: true };
+        // 5. The gateway said the job failed and nothing was charged — whatever
+        //    the upstream text says (MiniMax's is "aborted due to timeout").
+        if (err instanceof JobFailedError) {
+          return { content: [{ type: "text", text: formatError(`Music generation failed: ${errMsg}`) }], isError: true };
+        }
+        // 6. A labelled 5xx is an answer, not a timeout, however it reads.
+        if (hasLabelledServerStatus(errMsg)) {
+          return { content: [{ type: "text", text: formatError(`Music generation failed: ${errMsg}`, { afterPayment: paidRequestSent }) + reclaim }], isError: true };
+        }
+        // 7. A timeout with nothing outstanding: the unpaid quote probe, a
+        //    signing failure, or a deadline after the last poll was answered —
+        //    settlement needs a signed request the gateway answers as settled,
+        //    and the last one was not.
         if (isTimeoutError(err)) {
-          const reclaim = jobId ? ` The finished job stays claimable on the gateway for ~48h (job ${jobId}); re-running blockrun_music would start and charge a new job.` : "";
-          if (paidRequestInFlight) {
-            // A submit can settle inline (200) and the gateway settles a
-            // completed poll regardless of whether we are still connected, so
-            // a paid request that never answered is not "no charge". Book the
-            // quote conservatively — over-counting a slow request that settled
-            // nothing is the documented trade-off; under-counting a real charge
-            // is not.
-            recordActualSpend(budget, quotedUsd, MUSIC_COST, agent_id);
-            return {
-              content: [{ type: "text", text: `Music generation timed out while a request carrying the payment signature was still in flight, so the gateway MAY have settled the charge after this client gave up — check blockrun_wallet action:"report" or the wallet's recent transactions before retrying.${reclaim}\nError: ${errMsg}` }],
-              isError: true,
-            };
-          }
-          // On Base, settlement happens only on a response the gateway sends
-          // as settled; the last one was not, so nothing settled. The Solana
-          // helper describes its own money state in errMsg.
-          const base = !isApiKeyMode() && getChain() !== "solana";
+          const base = !isApiKeyMode();
           return {
             content: [{ type: "text", text: `Music generation timed out.${base ? ` No payment was taken.${reclaim}` : ""}\nError: ${errMsg}` }],
             isError: true,
           };
         }
         return {
-          content: [{ type: "text", text: formatError(`Music generation failed: ${errMsg}`) }],
+          content: [{ type: "text", text: formatError(`Music generation failed: ${errMsg}`, { afterPayment: paidRequestSent }) }],
           isError: true,
         };
       } finally {
diff --git a/src/tools/phone.ts b/src/tools/phone.ts
index e7f4383..cc6d777 100644
--- a/src/tools/phone.ts
+++ b/src/tools/phone.ts
@@ -13,8 +13,9 @@ import { confirmSpend } from "../utils/confirm-spend.js";
 import { withTxFee } from "../utils/tx-fee.js";
 import { asStructuredContent, coerceBody } from "../utils/body.js";
 import { getClient } from "../utils/wallet.js";
-import { type RawClient, rawPost, rawGet } from "../utils/raw-call.js";
-import { formatError, extractErrorMessage } from "../utils/errors.js";
+import { ledgerFallback, rawGet, rawPost, type RawClient } from "../utils/raw-call.js";
+import { formatError } from "../utils/errors.js";
+import { pathToolFailure } from "../utils/path-tool-catch.js";
 import { hasPathTraversal, normalizeClassifyPath } from "../utils/path-safety.js";
 import type { BudgetState } from "../types.js";
 
@@ -82,6 +83,9 @@ Voice call flow + voice preset details + full body shapes in the \`phone\` skill
       },
     },
     async ({ path, body, agent_id }) => {
+      // The reserve of the paid request in flight, for the catch: 0 until the
+      // line before rawGet/rawPost, so nothing thrown earlier can book a charge.
+      let sentUsd = 0;
       try {
         body = coerceBody(body);
         const cleanPath = path.replace(/^\/+/, "").replace(/^v1\//, "");
@@ -119,13 +123,14 @@ Voice call flow + voice preset details + full body shapes in the \`phone\` skill
           if (!confirm.ok) return { content: [{ type: "text", text: confirm.reason ?? "Charge cancelled." }] };
           const client = getClient() as unknown as RawClient;
           const endpoint = `/v1/${cleanPath}`;
+          sentUsd = estimatedCost;
           const { data: result, paidUsd } = body !== undefined
             ? await rawPost(client, endpoint, body)
             : await rawGet(client, endpoint);
           // Free phone reads estimate $0 and must stay free; a settled figure
           // from the account rail is authoritative for everything else.
           if (estimatedCost > 0 || (paidUsd ?? 0) > 0) {
-            recordActualSpend(budget, paidUsd, estimatedCost, agent_id);
+            recordActualSpend(budget, paidUsd, ledgerFallback(estimatedCost), agent_id);
           }
           return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
@@ -135,7 +140,9 @@ Voice call flow + voice preset details + full body shapes in the \`phone\` skill
           gate.release();
         }
       } catch (err) {
-        return { content: [{ type: "text", text: formatError(extractErrorMessage(err)) }], isError: true };
+        // Books the reserve when the payment went out and no origin answer came
+        // back (utils/path-tool-catch.ts). A free poll reserves $0 and books $0.
+        return pathToolFailure(err, { budget, agentId: agent_id, sentUsd });
       }
     }
   );
diff --git a/src/tools/polymarket.ts b/src/tools/polymarket.ts
index 96433e5..f112e23 100644
--- a/src/tools/polymarket.ts
+++ b/src/tools/polymarket.ts
@@ -3,7 +3,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { asStructuredContent } from "../utils/body.js";
 import { extractErrorMessage } from "../utils/errors.js";
-import { executeTrade, listOpenOrders, cancelOrdersAction, getSessionLedger, type ToolResult } from "../utils/polymarket/orders.js";
+import { confirmSpend } from "../utils/confirm-spend.js";
+import { executeTrade, listOpenOrders, cancelOrdersAction, getSessionLedger, type SpendGate, type ToolResult } from "../utils/polymarket/orders.js";
 import { listPositions } from "../utils/polymarket/positions.js";
 import { redeemPosition } from "../utils/polymarket/redeem.js";
 import { runSetup } from "../utils/polymarket/setup.js";
@@ -11,6 +12,7 @@ import { withdrawFunds } from "../utils/polymarket/withdraw.js";
 import { fundVault } from "../utils/polymarket/fund.js";
 import { TOOL_ANNOTATIONS } from "../tool-annotations.js";
 import { appToolMeta } from "../apps.js";
+import type { BudgetState } from "../types.js";
 
 /**
  * Trading is intentionally NOT gated on the x402 budget ledger: that ledger
@@ -18,8 +20,12 @@ import { appToolMeta } from "../apps.js";
  * user's own pUSD on Polygon — mixing them would corrupt both. The guardrails
  * here are confirm:true (hard-required to sign anything), the per-order
  * POLYMARKET_MAX_BET_USD cap, and the optional session cap (see orders.ts).
+ *
+ * The one exception is action:"fund"'s $0.01 gateway fee: that IS Base-wallet
+ * API spend, so when the registrar hands over the budget (mcp-handler.ts) fund
+ * reserves and books it like any paid call. Without it, legacy behaviour.
  */
-export function registerPolymarketTool(server: McpServer): void {
+export function registerPolymarketTool(server: McpServer, budget?: BudgetState): void {
   server.registerTool(
     "blockrun_polymarket",
     {
@@ -56,6 +62,8 @@ Prices are probabilities 0–1 on the market's tick grid. token_id comes from bl
           .describe("pUSD dollars — to spend (market buy) or to cash out (withdraw; default full balance)"),
         order_type: z.enum(["GTC", "GTD", "FOK", "FAK"]).optional()
           .describe("Default: GTC for limit orders, FOK for market orders"),
+        max_fill_price: z.number().gt(0).lt(1).optional()
+          .describe("Market orders only: the worst fill you accept (0-1). Defaults to the worst fill of this session's last preview for the same token+side, so a bare confirm:true is already held to what was quoted — a book that moved past it is refused, not signed. Pass this to widen or tighten that bound. Buy = ceiling, sell = floor."),
         expires_at: z.number().int().positive().optional()
           .describe("Unix seconds expiry (GTD only, ≥ ~3 min in the future)"),
         post_only: z.boolean().optional()
@@ -71,6 +79,13 @@ Prices are probabilities 0–1 on the market's tick grid. token_id comes from bl
       },
     },
     async (args) => {
+      // Human-in-the-loop (BLOCKRUN_CONFIRM_SPEND=on): the money-moving
+      // actions ask the user at the dialog the other paid tools use, with the
+      // real notional, right before they sign. `confirm:true` is a boolean the
+      // model supplies — it is the required floor, not the human's answer. A
+      // no-op when the flag is off or the client cannot elicit, so confirm:true
+      // alone still places, exactly as before.
+      const askUser: SpendGate = (usd, label) => confirmSpend(server, { usd, label });
       try {
         let result: ToolResult;
         switch (args.action) {
@@ -78,11 +93,11 @@ Prices are probabilities 0–1 on the market's tick grid. token_id comes from bl
             result = await runSetup({ confirm: args.confirm === true });
             break;
           case "fund":
-            result = await fundVault({ amount_usd: args.amount_usd, confirm: args.confirm });
+            result = await fundVault({ amount_usd: args.amount_usd, confirm: args.confirm, askUser, budget, agent_id: args.agent_id });
             break;
           case "buy":
           case "sell":
-            result = await executeTrade({ ...args, action: args.action });
+            result = await executeTrade({ ...args, action: args.action, askUser });
             break;
           case "orders":
             result = await listOpenOrders({ condition_id: args.condition_id });
@@ -97,7 +112,7 @@ Prices are probabilities 0–1 on the market's tick grid. token_id comes from bl
             result = await redeemPosition({ condition_id: args.condition_id, confirm: args.confirm });
             break;
           case "withdraw":
-            result = await withdrawFunds({ amount_usd: args.amount_usd, to_address: args.to_address, confirm: args.confirm });
+            result = await withdrawFunds({ amount_usd: args.amount_usd, to_address: args.to_address, confirm: args.confirm, askUser });
             break;
         }
         if (result.isError) {
diff --git a/src/tools/realface.ts b/src/tools/realface.ts
index 4206565..eb95e50 100644
--- a/src/tools/realface.ts
+++ b/src/tools/realface.ts
@@ -2,14 +2,16 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { TOOL_ANNOTATIONS } from "../tool-annotations.js";
 import { z } from "zod";
-import { amountToUsd, reserveBudget, recordActualSpend } from "../utils/budget.js";
+import { amountToUsd, assertQuoteNearEstimate, recordActualSpend, reserveBudget } from "../utils/budget.js";
 import { confirmSpend } from "../utils/confirm-spend.js";
 import { withTxFee } from "../utils/tx-fee.js";
 import { formatError, isPaymentRejectionError } from "../utils/errors.js";
 import { fetchWithTimeout } from "../utils/http.js";
+import { sendPaid, settleGiveUp, trackPaidRequest, type PaidRequest } from "../utils/in-flight.js";
+import { parseCostHeader } from "../utils/api-key-call.js";
 import type { BudgetState } from "../types.js";
-import { getApiBase, getChain, getOrCreateWalletKey } from "../utils/wallet.js";
-import { apiAuthHeaders, isApiKeyMode, requireWalletMode } from "../utils/auth.js";
+import { getApiBase, getChain, getOrCreateWalletKey, resolveSolanaKey } from "../utils/wallet.js";
+import { PORTAL_CREDITS_URL, apiAuthHeaders, isApiKeyMode, requireWalletMode } from "../utils/auth.js";
 import { generateUrlQrPng, openQrInViewer } from "../utils/qr.js";
 import { launchTopUp } from "../utils/onramp.js";
 import { privateKeyToAccount } from "viem/accounts";
@@ -36,18 +38,42 @@ async function payAndPostJson(
   path: string,
   reqBody: string,
   fallbackDescription: string,
+  /**
+   * The caller's per-call tracker for "a request carrying a payment is
+   * outstanding". Armed here on every rail the moment the paid request is
+   * about to go out, settled the moment a response arrives; the handler's
+   * catch reads it to book a give-up. Handed in rather than kept here because
+   * the MCP SDK dispatches calls concurrently and this function is shared: a
+   * module-level flag (0.50.0) made one call's outstanding payment book a
+   * phantom charge against another call's unrelated failure (audit round 3).
+   */
+  paid: PaidRequest,
+  /**
+   * Called with the authoritative quote BEFORE anything is signed, on whichever
+   * rail is active. Throwing aborts unpaid. realface was the one manual-402
+   * tool with no such hook: it read the 402 amount and signed it five lines
+   * later, so a gateway quoting a different product (as sol.blockrun.ai did for
+   * azure/sora-2 on 2026-09-08) was paid without a word.
+   */
+  onQuote?: (quotedUsd: number | null, quotedFor?: string) => void,
 ): Promise<{ status: number; data: Record<string, any>; settledUsd: number | null }> {
   // ---- Rail 1: account API key. ----
   if (isApiKeyMode()) {
-    const resp = await fetchWithTimeout(`${getApiBase()}${path}`, {
+    // No 402 on this rail: one POST, billed by the account. There is no quote
+    // to sanity-check, which is why onQuote is not called here. The Bearer is
+    // the payment, so the POST is armed like a signed one.
+    const resp = await sendPaid(paid, () => fetchWithTimeout(`${getApiBase()}${path}`, {
       method: "POST",
       headers: { "Content-Type": "application/json", ...apiAuthHeaders() },
       body: reqBody,
-    }, 90_000);
+    }, 90_000));
     const data = await resp.json().catch(() => ({})) as Record<string, any>;
-    // settledUsd null: the account API returns no per-call cost, so callers fall
-    // back to ENROLLMENT_PRICE_USD as an estimate.
-    return { status: resp.status, data, settledUsd: null };
+    // The account API reports what it settled in x-blockrun-cost-usd (since
+    // 2026-09-05 — see utils/api-key-call.ts). Absent reads as null, and the
+    // callers then fall back to ENROLLMENT_PRICE_USD; that estimate carries
+    // the $0.002 tx fee this rail does not charge, so booking it for a
+    // settled $0.010 over-counted every enrolment by 20%.
+    return { status: resp.status, data, settledUsd: parseCostHeader(resp.headers.get("x-blockrun-cost-usd")) };
   }
 
   // ---- Rail 2: Solana wallet. sol.blockrun.ai serves both enroll routes
@@ -55,15 +81,33 @@ async function payAndPostJson(
   if (getChain() === "solana") {
     const { solanaPaidPost } = await import("../utils/solana-402.js");
     try {
-      const r = await solanaPaidPost(path, JSON.parse(reqBody) as Record<string, unknown>, 90_000);
+      // The quote, captured for the tracker: armed at the helper's
+      // onPaidRequest (the line before the signed POST leaves) and settled at
+      // onPaidResponse (any status), so a refused quote (thrown from onQuote,
+      // nothing signed) never books and an answered 5xx is never a maybe.
+      let solQuotedUsd: number | null = null;
+      const r = await solanaPaidPost(path, JSON.parse(reqBody) as Record<string, unknown>, 90_000, {
+        onPaidRequest: () => paid.arm(solQuotedUsd),
+        onPaidResponse: () => paid.settle(),
+        onQuote: (quotedUsd, quoteDetails) => {
+          onQuote?.(quotedUsd, quoteDetails?.resource?.description);
+          solQuotedUsd = quotedUsd;
+        },
+      });
       return { status: 200, data: r.data as Record<string, any>, settledUsd: r.paidUsd };
     } catch (err) {
-      // solanaPaidPost throws on a non-2xx terminal response. Recover the status
-      // when it is one the callers branch on, so a 422 still reads as "rejected,
-      // not charged" rather than as an opaque failure.
-      const msg = err instanceof Error ? err.message : String(err);
-      const m = /\b(4\d\d|5\d\d)\b/.exec(msg);
-      if (m) return { status: Number(m[1]), data: { error: msg }, settledUsd: null };
+      // solanaPaidPost throws on a non-2xx answer to the PAID request with the
+      // status on the error (`statusCode`, the SDK's shape): a 422 still reads
+      // as "rejected, not charged" and a 402 as the wallet's refusal. Read
+      // the property, never the prose — the regex this replaces turned any
+      // quote fault whose text mentioned "402" (an unreadable amount, a
+      // missing feePayer) into "out of funds" plus a top-up page, for a call
+      // where nothing had been signed (audit round 4).
+      const status = (err as { statusCode?: unknown } | undefined)?.statusCode;
+      if (typeof status === "number") {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { status, data: { error: msg }, settledUsd: null };
+      }
       throw err;
     }
   }
@@ -90,6 +134,7 @@ async function payAndPostJson(
   const paymentRequired = parsePaymentRequired(prHeader);
   const details = extractPaymentDetails(paymentRequired);
 
+  onQuote?.(amountToUsd(details.amount), details.resource?.description);
   const paymentPayload = await createPaymentPayload(
     privateKey,
     account.address,
@@ -104,14 +149,16 @@ async function payAndPostJson(
     }
   );
 
-  const resp = await fetchWithTimeout(url, {
+  // Armed for exactly this fetch — the signature is on it — and settled by a
+  // response of any status before the status is read.
+  const resp = await sendPaid(paid, () => fetchWithTimeout(url, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       "PAYMENT-SIGNATURE": paymentPayload,
     },
     body: reqBody,
-  }, 90_000);
+  }, 90_000), amountToUsd(details.amount));
 
   const data = await resp.json().catch(() => ({})) as Record<string, any>;
   return { status: resp.status, data, settledUsd: amountToUsd(details.amount) };
@@ -152,6 +199,9 @@ Privacy: BlockRun does not store face/liveness data — only the asset id, name,
       // Reserve the estimate up front so concurrent calls can't each pass a
       // stale budget; release in finally once the call settles or fails.
       let gate: ReturnType<typeof reserveBudget> | undefined;
+      // THIS call's outstanding-payment state, read by the catch below. Per
+      // call on purpose — see payAndPostJson.
+      const paid = trackPaidRequest();
       try {
         // ---- init (free) ----
         if (action === "init") {
@@ -254,7 +304,39 @@ Privacy: BlockRun does not store face/liveness data — only the asset id, name,
           // getOrCreateWalletKey() below from minting one to ask with.
           const listBlock = requireWalletMode('blockrun_realface action:"list"');
           if (listBlock) return { content: [{ type: "text", text: listBlock }], isError: true };
-          const account = privateKeyToAccount(getOrCreateWalletKey());
+          // The ACTIVE chain's payer address against the ACTIVE chain's
+          // gateway. Assets are stored under whichever wallet paid the
+          // enrolment, and sol.blockrun.ai's /v1/wallet/{address} routes
+          // accept base58 only (probed 2026-09-13: an 0x address is a 400,
+          // "expected Solana base58"). 0.46.0 pointed this URL at getApiBase()
+          // and left the address EVM, so on the default chain every list
+          // failed — and minted an EVM keypair on a Solana-only install just
+          // to ask (audit round 3). On Solana the key is READ, never minted:
+          // a free listing must not provision a wallet.
+          const chain = getChain();
+          let address: string;
+          if (chain === "solana") {
+            const solanaKey = resolveSolanaKey();
+            if (!solanaKey) {
+              // Dynamic so the handler suites that mock utils/wallet.js by
+              // name (and predate this branch) keep linking; the same reason
+              // the Solana helper below is imported lazily.
+              const { solanaKeyUnavailableReason } = await import("../utils/wallet.js");
+              const why = solanaKeyUnavailableReason?.();
+              return {
+                content: [{ type: "text", text: formatError(why
+                  ? `Cannot list RealFace assets: ${why}. Unlock the keychain and retry.`
+                  : `No Solana wallet yet, so there is nothing enrolled to list. Run blockrun_wallet action:"setup" to provision one, or switch to Base (blockrun_wallet action:"chain" chain:"base") to list assets paid from the Base wallet.`) }],
+                isError: true,
+              };
+            }
+            const { solanaPublicKey } = await import("@blockrun/llm");
+            address = await solanaPublicKey(solanaKey);
+          } else {
+            address = privateKeyToAccount(getOrCreateWalletKey()).address;
+          }
+          const account = { address };
+          const chainLabel = chain === "solana" ? "Solana" : "Base";
           const [rfResp, vpResp] = await Promise.all([
             fetchWithTimeout(`${getApiBase()}/v1/wallet/${account.address}/realfaces`, { method: "GET" }, 30_000),
             fetchWithTimeout(`${getApiBase()}/v1/wallet/${account.address}/portraits`, { method: "GET" }, 30_000)
@@ -284,13 +366,13 @@ Privacy: BlockRun does not store face/liveness data — only the asset id, name,
               ? `\n⚠️ The Virtual Portrait lookup failed, so this covers RealFace only — do NOT re-enroll a portrait on the strength of this listing; retry first.`
               : "";
             return {
-              content: [{ type: "text", text: `No RealFace${portraitsUnavailable ? "" : " or Virtual Portrait"} assets enrolled for ${account.address}.${caveat}\nEnroll one: blockrun_realface action:"init" name:"…" (real person) or action:"portrait" name:"…" image_url:"https://…" (AI character).` }],
-              structuredContent: { wallet: account.address, realfaces: [], portraits: [], count: 0, portraitsUnavailable },
+              content: [{ type: "text", text: `No RealFace${portraitsUnavailable ? "" : " or Virtual Portrait"} assets enrolled for ${account.address} (${chainLabel} wallet — assets are per paying wallet and per chain).${caveat}\nEnroll one: blockrun_realface action:"init" name:"…" (real person) or action:"portrait" name:"…" image_url:"https://…" (AI character).` }],
+              structuredContent: { wallet: account.address, chain, realfaces: [], portraits: [], count: 0, portraitsUnavailable },
             };
           }
           const first = faces[0] ?? portraits[0];
           const lines = [
-            `Assets for ${account.address} (${faces.length} RealFace, ${portraits.length} Virtual Portrait):`,
+            `Assets for ${account.address} on ${chainLabel} (${faces.length} RealFace, ${portraits.length} Virtual Portrait; assets are per paying wallet and per chain):`,
             ...faces.map((f) => `  • ${f.assetId}  —  "${f.name}" [realface]${f.createdAt ? `  (${f.createdAt})` : ""}`),
             ...portraits.map((p) => `  • ${p.assetId}  —  "${p.name}" [portrait]${p.createdAt ? `  (${p.createdAt})` : ""}`),
             ``,
@@ -298,7 +380,7 @@ Privacy: BlockRun does not store face/liveness data — only the asset id, name,
           ];
           return {
             content: [{ type: "text", text: lines.join("\n") }],
-            structuredContent: { wallet: account.address, realfaces: faces, portraits, count: faces.length + portraits.length },
+            structuredContent: { wallet: account.address, chain, realfaces: faces, portraits, count: faces.length + portraits.length },
           };
         }
 
@@ -325,6 +407,21 @@ Privacy: BlockRun does not store face/liveness data — only the asset id, name,
             "/v1/portrait/enroll",
             JSON.stringify({ name, image_url }),
             "BlockRun Virtual Portrait enrollment",
+            paid,
+            (quotedUsd, quotedFor) => {
+              // Same rule as video, music, image and speech: refuse a quote far
+              // above the published rate before signing, then re-check the cap
+              // at the REAL price.
+              assertQuoteNearEstimate(quotedUsd, ENROLLMENT_PRICE_USD, {
+                what: "portrait enrollment",
+                quotedFor,
+                hint: `Report the quote — the published rate is $${ENROLLMENT_PRICE_USD.toFixed(4)}.`,
+              });
+              if (quotedUsd === null || quotedUsd <= ENROLLMENT_PRICE_USD) return;
+              gate?.release();
+              gate = reserveBudget(budget, agent_id, quotedUsd);
+              if (!gate.allowed) throw new Error(`${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget. No charge was made.`);
+            },
           );
 
           if (status === 402) {
@@ -352,7 +449,7 @@ Privacy: BlockRun does not store face/liveness data — only the asset id, name,
             `✅ Virtual Portrait enrolled!`,
             `Asset ID: ${assetId}`,
             `Name: ${data.name || name}`,
-            `Cost: $${ENROLLMENT_PRICE_USD.toFixed(2)} USDC`,
+            `Cost: $${(settledUsd ?? ENROLLMENT_PRICE_USD).toFixed(4)} USDC`,
             ...(txHash ? [`Tx: ${txHash}`] : []),
             ``,
             `Use it: blockrun_video model:"bytedance/seedance-2.0" real_face_asset_id:"${assetId}" prompt:"…".`,
@@ -364,7 +461,7 @@ Privacy: BlockRun does not store face/liveness data — only the asset id, name,
               group_id: data.group_id,
               name: data.name || name,
               image_url: data.image_url,
-              price_usd: ENROLLMENT_PRICE_USD,
+              price_usd: settledUsd ?? ENROLLMENT_PRICE_USD,
               ...(txHash ? { txHash } : {}),
             },
           };
@@ -396,6 +493,21 @@ Privacy: BlockRun does not store face/liveness data — only the asset id, name,
             "/v1/realface/enroll",
             JSON.stringify({ name, image_url, group_id }),
             "BlockRun RealFace enrollment",
+            paid,
+            (quotedUsd, quotedFor) => {
+              // Same rule as video, music, image and speech: refuse a quote far
+              // above the published rate before signing, then re-check the cap
+              // at the REAL price.
+              assertQuoteNearEstimate(quotedUsd, ENROLLMENT_PRICE_USD, {
+                what: "RealFace enrollment",
+                quotedFor,
+                hint: `Report the quote — the published rate is $${ENROLLMENT_PRICE_USD.toFixed(4)}.`,
+              });
+              if (quotedUsd === null || quotedUsd <= ENROLLMENT_PRICE_USD) return;
+              gate?.release();
+              gate = reserveBudget(budget, agent_id, quotedUsd);
+              if (!gate.allowed) throw new Error(`${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget. No charge was made.`);
+            },
           );
 
           if (status === 402) {
@@ -423,7 +535,7 @@ Privacy: BlockRun does not store face/liveness data — only the asset id, name,
             `✅ RealFace enrolled!`,
             `Asset ID: ${assetId}`,
             `Name: ${data.name || name}`,
-            `Cost: $${ENROLLMENT_PRICE_USD.toFixed(2)} USDC`,
+            `Cost: $${(settledUsd ?? ENROLLMENT_PRICE_USD).toFixed(4)} USDC`,
             ...(txHash ? [`Tx: ${txHash}`] : []),
             ``,
             `Use it: blockrun_video model:"bytedance/seedance-2.0" real_face_asset_id:"${assetId}" prompt:"…".`,
@@ -434,7 +546,7 @@ Privacy: BlockRun does not store face/liveness data — only the asset id, name,
               asset_id: assetId,
               group_id: data.group_id || group_id,
               name: data.name || name,
-              price_usd: ENROLLMENT_PRICE_USD,
+              price_usd: settledUsd ?? ENROLLMENT_PRICE_USD,
               ...(txHash ? { txHash } : {}),
             },
           };
@@ -445,10 +557,21 @@ Privacy: BlockRun does not store face/liveness data — only the asset id, name,
         const errMsg = err instanceof Error ? err.message : String(err);
         if (isPaymentRejectionError(errMsg)) {
           return {
-            content: [{ type: "text", text: `RealFace enrollment needs USDC — your wallet is out of funds. ${(await launchTopUp()).note}\nError: ${errMsg}` }],
+            content: [{ type: "text", text: isApiKeyMode()
+              ? `RealFace enrollment was refused for lack of credit on your BlockRun account — top it up at ${PORTAL_CREDITS_URL}.\nError: ${errMsg}`
+              : `RealFace enrollment needs USDC — your wallet is out of funds. ${(await launchTopUp()).note}\nError: ${errMsg}` }],
             isError: true,
           };
         }
+        // The request carrying the payment never answered. The gateway
+        // settles on its own clock, so this is not "no charge" — book it
+        // conservatively (the quote where one was seen, else the reserve) and
+        // say what is and is not known. Same trade-off video and music make:
+        // over-counting a request that settled nothing is recoverable,
+        // under-counting a real charge is not. `paid` is this call's own
+        // tracker, so another call's outstanding payment cannot land here.
+        const giveUp = settleGiveUp(paid, err, { budget, agentId: agent_id, estimateUsd: ENROLLMENT_PRICE_USD, what: `RealFace ${action}` });
+        if (giveUp) return { content: [{ type: "text", text: giveUp.text }], isError: true };
         return { content: [{ type: "text", text: formatError(`RealFace ${action} failed: ${errMsg}`) }], isError: true };
       } finally {
         gate?.release();
diff --git a/src/tools/rpc.ts b/src/tools/rpc.ts
index 92509ab..ff84456 100644
--- a/src/tools/rpc.ts
+++ b/src/tools/rpc.ts
@@ -15,13 +15,14 @@ import { confirmSpend } from "../utils/confirm-spend.js";
 import { withTxFee } from "../utils/tx-fee.js";
 import { coerceBody } from "../utils/body.js";
 import { getClient } from "../utils/wallet.js";
-import { type RawClient, rawPost } from "../utils/raw-call.js";
-import { formatError, extractErrorMessage } from "../utils/errors.js";
+import { ledgerFallback, rawPost, type RawClient } from "../utils/raw-call.js";
+import { formatError } from "../utils/errors.js";
+import { pathToolFailure } from "../utils/path-tool-catch.js";
 import { isValidNetworkSlug } from "../utils/path-safety.js";
 import type { BudgetState } from "../types.js";
 
 
-const RPC_PRICE_USD = 0.002;
+export const RPC_PRICE_USD = 0.002;
 
 export function registerRpcTool(server: McpServer, budget: BudgetState): void {
   server.registerTool(
@@ -51,6 +52,9 @@ Prefer blockrun_price (free quotes) or blockrun_dex (free DEX data) when they co
       },
     },
     async ({ network, method, params, body, agent_id }) => {
+      // The reserve of the paid request in flight, for the catch: 0 until the
+      // line before rawPost, so nothing thrown earlier can book a charge.
+      let sentUsd = 0;
       try {
         body = coerceBody(body);
         if (body === undefined) {
@@ -95,8 +99,9 @@ Prefer blockrun_price (free quotes) or blockrun_dex (free DEX data) when they co
           const confirm = await confirmSpend(server, { usd: estimatedCost, label: `rpc · ${cleanNetwork}` });
           if (!confirm.ok) return { content: [{ type: "text", text: confirm.reason ?? "Charge cancelled." }] };
           const client = getClient() as unknown as RawClient;
+          sentUsd = estimatedCost;
           const { data: result, paidUsd } = await rawPost(client, `/v1/rpc/${cleanNetwork}`, body);
-          recordActualSpend(budget, paidUsd, estimatedCost, agent_id);
+          recordActualSpend(budget, paidUsd, ledgerFallback(estimatedCost), agent_id);
           return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
             structuredContent: (typeof result === "object" && result !== null && !Array.isArray(result)
@@ -107,10 +112,9 @@ Prefer blockrun_price (free quotes) or blockrun_dex (free DEX data) when they co
           gate.release();
         }
       } catch (err) {
-        return {
-          content: [{ type: "text", text: formatError(extractErrorMessage(err)) }],
-          isError: true,
-        };
+        // Books the reserve when the payment went out and no origin answer came
+        // back (utils/path-tool-catch.ts).
+        return pathToolFailure(err, { budget, agentId: agent_id, sentUsd });
       }
     }
   );
diff --git a/src/tools/search.ts b/src/tools/search.ts
index 35ffcfc..9fe99ab 100644
--- a/src/tools/search.ts
+++ b/src/tools/search.ts
@@ -12,8 +12,9 @@ import { reserveBudget, recordSpending, recordActualSpend } from "../utils/budge
 import { confirmSpend } from "../utils/confirm-spend.js";
 import { asStructuredContent, coerceBody } from "../utils/body.js";
 import { getClient } from "../utils/wallet.js";
-import { type RawClient, rawPost } from "../utils/raw-call.js";
-import { formatError, extractErrorMessage } from "../utils/errors.js";
+import { ledgerFallback, rawPost, type RawClient } from "../utils/raw-call.js";
+import { formatError } from "../utils/errors.js";
+import { pathToolFailure } from "../utils/path-tool-catch.js";
 import { hasPathTraversal } from "../utils/path-safety.js";
 import type { BudgetState } from "../types.js";
 
@@ -62,16 +63,43 @@ export function estimateSearchCost(body: unknown): number {
   return reserve(max);
 }
 
+// The gateway's `sources` enum. X/Twitter was dropped upstream on 2026-07-05
+// (blockrun commit edefa8eb, `z.array(z.enum(["web","news"])).optional()
+// .default(["web"])`) and this tool went on advertising `["web","x","news"]`
+// as its Common shape for two months. Following it to the letter reserved
+// $0.2645, sat through the confirm dialog and came back as `API error: 400 /
+// Invalid request body` — the SDK strips the zod issues, so the field was
+// never named and the agent had no way to self-correct. Unpaid probe
+// 2026-09-13: `["web","x","news"]` 400s on both gateways, `["web","news"]`
+// quotes a 402. Only the NAMES are ours to check; a non-array `sources` is a
+// shape error the gateway reports unpaid.
+const SEARCH_SOURCES = ["web", "news"] as const;
+
+/** Exported for tests. The refusal for a `sources` entry the gateway no longer serves, or null. */
+export function unsupportedSearchSource(body: unknown): string | null {
+  if (!body || typeof body !== "object") return null;
+  const sources = (body as { sources?: unknown }).sources;
+  if (!Array.isArray(sources)) return null;
+  const bad = sources.filter((s) => !(SEARCH_SOURCES as readonly unknown[]).includes(s));
+  if (bad.length === 0) return null;
+  const xTwitter = bad.some((s) => typeof s === "string" && /^(x|twitter)$/i.test(s));
+  return `body.sources ${JSON.stringify(bad)} is not served: the gateway accepts only ["web","news"] (default ["web"]). ` +
+    (xTwitter
+      ? `The X/Twitter source was removed upstream on 2026-07-05 and there is no live X route in this server — do not retry with "x". `
+      : "") +
+    `Retry with sources: ["web","news"] or omit it. No payment was made.`;
+}
+
 export function registerSearchTool(server: McpServer, budget: BudgetState): void {
   server.registerTool(
     "blockrun_search",
     {
-      description: `Grok Live Search — real-time web + X/Twitter + news with AI-summarized results and citations. PRICED PER SOURCE and expensive by default: $0.025 × max_results, +5% gateway buffer — default max_results=10 settles ~$0.26 (max_results=50 → ~$1.31). Pass a smaller max_results to cap spend; for a plain fact, 3 sources (~$0.08) is usually enough.
+      description: `Grok Live Search — real-time web + news with AI-summarized results and citations. PRICED PER SOURCE and expensive by default: $0.025 × max_results, +5% gateway buffer — default max_results=10 settles ~$0.26 (max_results=50 → ~$1.31). Pass a smaller max_results to cap spend; for a plain fact, 3 sources (~$0.08) is usually enough.
 
 Common shape:
-- body: { query: "...", sources: ["web","x","news"], max_results: 10, from_date: "YYYY-MM-DD", to_date: "YYYY-MM-DD" }
+- body: { query: "...", sources: ["web","news"], max_results: 10, from_date: "YYYY-MM-DD", to_date: "YYYY-MM-DD" }
 
-\`sources\` accepts any subset of ["web","x","news"] (defaults to all three). For tweet-only searches, use ["x"]. \`max_results\` is 1–50 (default 10) and drives the price — pass a smaller value if you want to cap spend.
+\`sources\` accepts any subset of ["web","news"] (default ["web"] — pass both for news coverage). There is no X/Twitter source (removed upstream 2026-07-05; asking for it is refused before payment). \`max_results\` is 1–50 (default 10) and drives the price — pass a smaller value if you want to cap spend.
 
 Full request shape + worked examples in the \`search\` skill (\`skills/search/SKILL.md\`).`,
       annotations: TOOL_ANNOTATIONS.readOnlyOpenWorld,
@@ -82,12 +110,22 @@ Full request shape + worked examples in the \`search\` skill (\`skills/search/SK
       },
     },
     async ({ path, body, agent_id }) => {
+      // The reserve of the paid request in flight, for the catch: 0 until the
+      // line before rawPost, so nothing thrown earlier can book a charge.
+      let sentUsd = 0;
       try {
         body = coerceBody(body);
         const cleanPath = (path ?? "").replace(/^\/+/, "").replace(/^v1\/search\/?/, "");
         if (hasPathTraversal(cleanPath)) {
           return { content: [{ type: "text", text: formatError(`Invalid path '${path}'.`) }], isError: true };
         }
+        // Before the reserve and the confirm dialog: a source the gateway no
+        // longer serves would 400 unpaid anyway, but as an opaque "Invalid
+        // request body" — name the field and the live values instead.
+        const badSource = unsupportedSearchSource(body);
+        if (badSource) {
+          return { content: [{ type: "text", text: formatError(badSource) }], isError: true };
+        }
         const estimatedCost = estimateSearchCost(body);
         const gate = reserveBudget(budget, agent_id, estimatedCost);
         if (!gate.allowed) {
@@ -104,8 +142,9 @@ Full request shape + worked examples in the \`search\` skill (\`skills/search/SK
           if (!confirm.ok) return { content: [{ type: "text", text: confirm.reason ?? "Charge cancelled." }] };
           const client = getClient() as unknown as RawClient;
           const endpoint = cleanPath ? `/v1/search/${cleanPath}` : "/v1/search";
+          sentUsd = estimatedCost;
           const { data: result, paidUsd } = await rawPost(client, endpoint, body ?? {});
-          recordActualSpend(budget, paidUsd, estimatedCost, agent_id);
+          recordActualSpend(budget, paidUsd, ledgerFallback(estimatedCost), agent_id);
           return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
             structuredContent: asStructuredContent(result),
@@ -114,7 +153,10 @@ Full request shape + worked examples in the \`search\` skill (\`skills/search/SK
           gate.release();
         }
       } catch (err) {
-        return { content: [{ type: "text", text: formatError(extractErrorMessage(err)) }], isError: true };
+        // Books the reserve only when the payment went out and no ORIGIN answer
+        // came back (utils/path-tool-catch.ts). The search route calls Grok
+        // BEFORE it settles, so its bare 500 is pre-settle and books nothing.
+        return pathToolFailure(err, { budget, agentId: agent_id, sentUsd });
       }
     }
   );
diff --git a/src/tools/speech.ts b/src/tools/speech.ts
index 27b8a47..3b57c39 100644
--- a/src/tools/speech.ts
+++ b/src/tools/speech.ts
@@ -13,12 +13,13 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { TOOL_ANNOTATIONS } from "../tool-annotations.js";
 import { z } from "zod";
-import { amountToUsd, reserveBudget, recordActualSpend } from "../utils/budget.js";
+import { amountToUsd, assertQuoteNearEstimate, reserveBudget, recordActualSpend } from "../utils/budget.js";
 import { confirmSpend } from "../utils/confirm-spend.js";
 import { withTxFee } from "../utils/tx-fee.js";
 import { formatError, isPaymentRejectionError } from "../utils/errors.js";
 import { launchTopUp } from "../utils/onramp.js";
-import { fetchWithTimeout, isTimeoutError } from "../utils/http.js";
+import { fetchWithTimeout } from "../utils/http.js";
+import { sendPaid, settleGiveUp, trackPaidRequest } from "../utils/in-flight.js";
 import type { BudgetState } from "../types.js";
 import { getApiBase, getChain, getOrCreateWalletKey } from "../utils/wallet.js";
 import { apiAuthHeaders, isApiKeyMode } from "../utils/auth.js";
@@ -145,6 +146,29 @@ Returns a hosted audio URL — download immediately if you need to keep the file
       // Reserve the estimate up front so concurrent calls can't each pass a
       // stale budget; release in finally once the call settles or fails.
       let gate: ReturnType<typeof reserveBudget> | undefined;
+      // Hoisted for the catch: a timeout after the signature was sent has to be
+      // booked, and the booking needs the reserve when no quote was captured.
+      let reservedCost = 0;
+      // Armed only while a request carrying the payment is outstanding, on
+      // every rail. A timeout on the unpaid 402 probe charges nothing, and
+      // booking it would invent spend; a timeout after the signature (or the
+      // account Bearer) went out may well have settled. Per call, and settled
+      // only by a response — 0.50.0's boolean was cleared in a `.finally` the
+      // catch could never observe, and set on Base alone (audit round 3).
+      const paid = trackPaidRequest();
+      // The amount booked once settlement was OBSERVED, on any rail. Read by
+      // the catch: an error after this point — a body that aborted mid-read,
+      // a payload with no URL — is a real charge with an unusable result, and
+      // the message has to say the charge stands rather than "failed" with
+      // retry advice that pays again (the D13 shape video and music got in
+      // round 3; speech did not — audit round 4).
+      let bookedUsd: number | null = null;
+      // Hoisted with it: the receipt, so the charge-stands sentence can name it.
+      let txHash: string | null | undefined;
+      const book = (paidUsd: number | null, reserve: number) => {
+        recordActualSpend(budget, paidUsd, reserve, agent_id);
+        bookedUsd = paidUsd ?? reserve;
+      };
       try {
         if (action === "voices") {
           return await listVoices();
@@ -197,6 +221,7 @@ Returns a hosted audio URL — download immediately if you need to keep the file
           cost = speechCost(model, input);
         }
 
+        reservedCost = cost;
         gate = reserveBudget(budget, agent_id, cost);
         if (!gate.allowed) {
           return {
@@ -212,36 +237,57 @@ Returns a hosted audio URL — download immediately if you need to keep the file
 
         let data: { data?: Array<{ url: string; format?: string; characters?: number; duration_seconds?: number }>; model?: string };
         let billedUsd: number;
-        let txHash: string | null | undefined;
         let estimated = false;
 
         // ---- Rail 1: account API key. One POST, no quote, no signature. ----
         if (isApiKeyMode()) {
-          const r = await apiKeyPost(path, body, { timeoutMs: SPEECH_TIMEOUT });
+          // The Bearer IS the payment on this rail: a POST that never answers
+          // may still be billed, so it is armed like a signed one.
+          const r = await sendPaid(paid, () => apiKeyPost(path, body, { timeoutMs: SPEECH_TIMEOUT }));
           data = r.data as typeof data;
           // The settled figure when the rail reports one, the local estimate
           // otherwise — and `estimated` says which, so the two are never mixed up.
           billedUsd = r.paidUsd ?? cost;
           estimated = r.paidUsd === null;
           txHash = r.txHash;
-          recordActualSpend(budget, r.paidUsd, cost, agent_id);
+          book(r.paidUsd, cost);
         } else if (getChain() === "solana") {
           // ---- Rail 2: Solana wallet, via the shared manual-x402 helper. ----
           const { solanaPaidPost } = await import("../utils/solana-402.js");
+          // The quote, captured for the tracker: armed at the helper's
+          // onPaidRequest (the line before the signed POST leaves) and settled
+          // at onPaidResponse (any status), so the unpaid probe and the
+          // signing step are outside the window and an answered 5xx is never
+          // a maybe.
+          let solQuotedUsd: number | null = null;
           const r = await solanaPaidPost(path, body, SPEECH_TIMEOUT, {
-            onQuote: (quotedUsd) => {
-              // Re-check the REAL price against the budget before signing: the
-              // Solana gateway quotes independently of our local estimate.
-              if (quotedUsd === null || quotedUsd <= cost) return;
-              gate?.release();
-              gate = reserveBudget(budget, agent_id, quotedUsd);
-              if (!gate.allowed) throw new Error(`${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget. No charge was made.`);
+            onPaidRequest: () => paid.arm(solQuotedUsd),
+            onPaidResponse: () => paid.settle(),
+            onQuote: (quotedUsd, quoteDetails) => {
+              // WHAT was quoted, before how much. 350df27 put this guard on the
+              // Base rail only, so a substituted or repriced product on
+              // sol.blockrun.ai — the DEFAULT chain — was signed unseen while
+              // Base refused it (audit round 3). Refusing costs nothing: the
+              // helper has not signed yet.
+              assertQuoteNearEstimate(quotedUsd, cost, {
+                what: `${action === "sound_effect" ? "sound effect" : model} speech`,
+                quotedFor: quoteDetails?.resource?.description,
+                hint: `Retry on Base (blockrun_wallet action:"chain" chain:"base"), or report the quote.`,
+              });
+              // Then the cap, against the REAL price: the Solana gateway quotes
+              // independently of our local estimate.
+              if (quotedUsd !== null && quotedUsd > cost) {
+                gate?.release();
+                gate = reserveBudget(budget, agent_id, quotedUsd);
+                if (!gate.allowed) throw new Error(`${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget. No charge was made.`);
+              }
+              solQuotedUsd = quotedUsd;
             },
           });
           data = r.data as typeof data;
           billedUsd = r.paidUsd ?? cost;
           txHash = r.txHash;
-          recordActualSpend(budget, r.paidUsd, cost, agent_id);
+          book(r.paidUsd, cost);
         } else {
         // ---- Rail 3: Base wallet. The original EIP-3009 402 flow. ----
         const endpoint = `${getApiBase()}${path}`;
@@ -269,6 +315,24 @@ Returns a hosted audio URL — download immediately if you need to keep the file
         // server-side price change) over the local estimate for billing + display.
         billedUsd = amountToUsd(details.amount) ?? cost;
 
+        // WHAT was quoted, before how much. 0.49.0 added this to video (both
+        // rails) and image (Solana) and left the identical hand-rolled flows
+        // here unguarded — so a gateway that quotes a different product, the
+        // way sol.blockrun.ai quoted azure/sora-2 as Seedance at 2.7x, was
+        // signed unseen. Refusing costs nothing: nothing is signed yet.
+        assertQuoteNearEstimate(billedUsd, cost, {
+          what: `${model} speech`,
+          quotedFor: details.resource?.description,
+          hint: `Retry on Solana (blockrun_wallet action:"chain" chain:"solana"), or report the quote.`,
+        });
+        // And the cap, against the REAL price rather than the estimate.
+        const quotedUsd = amountToUsd(details.amount);
+        if (quotedUsd !== null && quotedUsd > cost) {
+          gate?.release();
+          gate = reserveBudget(budget, agent_id, quotedUsd);
+          if (!gate.allowed) throw new Error(`${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget. No charge was made.`);
+        }
+
         const paymentPayload = await createPaymentPayload(
           privateKey,
           account.address,
@@ -283,15 +347,17 @@ Returns a hosted audio URL — download immediately if you need to keep the file
           }
         );
 
-        // Step 2: synthesize with payment (settlement happens after generation)
-        const resp = await fetchWithTimeout(endpoint, {
+        // Step 2: synthesize with payment (settlement happens after generation).
+        // Armed for exactly this fetch: the signature is on it, and a response
+        // of any status settles the tracker before it is inspected.
+        const resp = await sendPaid(paid, () => fetchWithTimeout(endpoint, {
           method: "POST",
           headers: {
             "Content-Type": "application/json",
             "PAYMENT-SIGNATURE": paymentPayload,
           },
           body: JSON.stringify(body),
-        }, SPEECH_TIMEOUT);
+        }, SPEECH_TIMEOUT), quotedUsd);
 
         if (resp.status === 402) {
           throw new Error("Payment rejected. Check your wallet balance.");
@@ -306,7 +372,7 @@ Returns a hosted audio URL — download immediately if you need to keep the file
         // the charge NOW, before reading the body — a truncated/unreadable body
         // below must not un-record a spend that already left the wallet.
         txHash = resp.headers.get("X-Payment-Receipt") || resp.headers.get("x-payment-receipt");
-        recordActualSpend(budget, billedUsd, cost, agent_id);
+        book(billedUsd, cost);
 
         data = await resp.json() as {
           data: Array<{ url: string; format?: string; characters?: number; duration_seconds?: number }>;
@@ -347,20 +413,33 @@ Returns a hosted audio URL — download immediately if you need to keep the file
         };
       } catch (err) {
         const errMsg = err instanceof Error ? err.message : String(err);
-        // Account mode has no wallet to fund — apiKeyPost already returns the
-        // right remedy (top up credit at the portal), so don't overwrite it.
-        if (isPaymentRejectionError(errMsg) && !isApiKeyMode()) {
+        // 1. Settlement was observed and booked, then the result could not be
+        //    used. The charge stands; the one thing not to do is run the
+        //    tool again.
+        // (Widened: TS narrows a closure-assigned `let` to never here.)
+        const booked = bookedUsd as number | null;
+        if (booked !== null) {
+          const where = isApiKeyMode() ? "https://user.blockrun.ai/dashboard/activity" : `blockrun_wallet action:"report"`;
           return {
-            content: [{ type: "text", text: `Speech generation needs USDC — your wallet is out of funds. ${(await launchTopUp()).note}\nError: ${errMsg}` }],
+            content: [{ type: "text", text: `Speech generation settled and the charge stands — $${booked.toFixed(4)} was charged${txHash ? ` (tx ${txHash})` : ""} and is booked against your budget — but the result could not be used: ${errMsg}
+Check ${where} before doing anything else; re-running blockrun_speech would charge again.` }],
             isError: true,
           };
         }
-        if (isTimeoutError(err)) {
+        // Account mode has no wallet to fund — apiKeyPost already returns the
+        // right remedy (top up credit at the portal), so don't overwrite it.
+        if (isPaymentRejectionError(errMsg) && !isApiKeyMode()) {
           return {
-            content: [{ type: "text", text: `Speech generation timed out after ${SPEECH_TIMEOUT / 1000}s. The payment signature had already been sent, so a charge MAY have settled without returning audio — check blockrun_wallet action:"report" before retrying.\nError: ${errMsg}` }],
+            content: [{ type: "text", text: `Speech generation needs USDC — your wallet is out of funds. ${(await launchTopUp()).note}\nError: ${errMsg}` }],
             isError: true,
           };
         }
+        // A paid request that never answered on ANY rail: the gateway settles
+        // on its own clock, so this is booked (the quote where one was seen,
+        // else the reserve) and said out loud — the finally below releases the
+        // reservation, and a bare "failed" invites a retry that pays twice.
+        const giveUp = settleGiveUp(paid, err, { budget, agentId: agent_id, estimateUsd: reservedCost, what: "Speech generation" });
+        if (giveUp) return { content: [{ type: "text", text: giveUp.text }], isError: true };
         return {
           content: [{ type: "text", text: formatError(`Speech generation failed: ${errMsg}`) }],
           isError: true,
diff --git a/src/tools/video.ts b/src/tools/video.ts
index d24b26c..6130017 100644
--- a/src/tools/video.ts
+++ b/src/tools/video.ts
@@ -5,10 +5,11 @@ import { z } from "zod";
 import { amountToUsd, assertQuoteNearEstimate, reserveBudget, recordActualSpend } from "../utils/budget.js";
 import { confirmSpend } from "../utils/confirm-spend.js";
 import { withTxFee } from "../utils/tx-fee.js";
-import { formatError, isPaymentRejectionError } from "../utils/errors.js";
+import { formatError, hasLabelledServerStatus } from "../utils/errors.js";
 import { launchTopUp } from "../utils/onramp.js";
 import { fetchWithTimeout, isTimeoutError } from "../utils/http.js";
-import { pollTimeoutFor } from "../utils/poll.js";
+import { JobFailedError, pollTimeoutFor } from "../utils/poll.js";
+import { sendPaid, settleGiveUp, trackPaidRequest } from "../utils/in-flight.js";
 import type { BudgetState } from "../types.js";
 import { getApiBase, getChain, getOrCreateWalletKey, resolveGatewayUrl } from "../utils/wallet.js";
 import { isApiKeyMode } from "../utils/auth.js";
@@ -37,8 +38,13 @@ import {
 // Without that clamp the true worst case is budget + interval + poll timeout,
 // which at 540s/5s/90s lands 35s PAST a 600s authorization.
 export const VIDEO_TOTAL_BUDGET_MS = 540_000;
-const POLL_INTERVAL_MS = 5_000;
-export const VIDEO_POLL_TIMEOUT_MS = 90_000;
+export const POLL_INTERVAL_MS = 5_000;
+// The gateway's poll route declares `export const maxDuration = 60` (blockrun
+// src/app/api/v1/videos/generations/[id]/route.ts), so a poll that has not
+// answered in 60s never will — waiting 90 was 30s of the signed authorization's
+// window spent on a request the server had already abandoned. The Solana helper
+// already capped its poll at the route's own limit; this matches it.
+export const VIDEO_POLL_TIMEOUT_MS = 60_000;
 // Lifetime of the signed payment authorization, in seconds. Exported so the
 // margin above is asserted against the value the request actually sends,
 // rather than a literal restated in the test.
@@ -296,6 +302,24 @@ export function assertVideoQuoteSane(
   assertQuoteNearEstimate(quotedUsd, estimatedCost, { what: `${model} video`, quotedFor, hint });
 }
 
+/**
+ * The wallet refused to pay: a 402 that came back on a request CARRYING the
+ * signature. The SDK's PaymentError (and the helpers' own) set `name` to
+ * "PaymentError"; the Base rail below throws the same shape. Checked by name
+ * rather than `instanceof` so the module does not need a static import of the
+ * SDK class — every handler suite that mocks @blockrun/llm lists its exports
+ * by hand (chat-stream.ts classifies the same way).
+ *
+ * This replaces isPaymentRejectionError's substring match on "insufficient" /
+ * "balance" / "rejected": an upstream safety filter's "Your request was
+ * rejected …" arrived through the same catch and was reported as an empty
+ * wallet — with a Coinbase top-up page opened on Base — while the message
+ * itself said no payment was taken (audit round 3, C36).
+ */
+function isPaymentRefusal(err: unknown): boolean {
+  return err instanceof Error && err.name === "PaymentError";
+}
+
 export function registerVideoTool(server: McpServer, budget: BudgetState): void {
   server.registerTool(
     "blockrun_video",
@@ -305,7 +329,7 @@ export function registerVideoTool(server: McpServer, budget: BudgetState): void
 Turns a text prompt (and optional seed image) into a short MP4 clip. The tool submits the job, then polls until the video is ready (typical total wall-time 60-180s; 9 min Base / 15 min Solana hard cap). Payment is settled only when upstream returns a finished video — if the job fails you are not charged; if this client gives up while a paid poll is still in flight the gateway may still settle, and the error text says so.
 
 Models. Every rate below is what you are CHARGED (margin and transaction fee included), at the 720p baseline Seedance renders by default with synced audio:
-- azure/sora-2 (~$0.105/sec, 720p + synced audio, text-to-video) — OpenAI Sora 2 via Azure AI Foundry. duration_seconds must be 4, 8, or 12 (4s default -> ~$0.42/clip). No image_url / RealFace. Base only for now: the Solana gateway quotes it as Seedance 2.0 at $1.135 and the tool refuses that quote unsigned.
+- azure/sora-2 (~$0.105/sec, 720p + synced audio, text- or image-to-video) — OpenAI Sora 2 via Azure AI Foundry. duration_seconds must be 4, 8, or 12 (4s default -> ~$0.42/clip). image_url takes a NON-HUMAN reference image (faces are rejected upstream by moderation — use Seedance + RealFace for real people); same price as text-to-video. No RealFace, no last_frame_url. Base only for now: the Solana gateway quotes it as Seedance 2.0 at $1.135 and the tool refuses that quote unsigned.
 - xai/grok-imagine-video ($0.05/sec at 480p default, $0.07/sec at 720p; 8s default -> $0.401/clip, 1-15s) — stylized, fast. 480p/720p only.
 - bytedance/seedance-1.5-pro (~$0.071/sec, 4-12s, 5s default -> ~$0.35/clip) — cheapest Seedance, token-priced upstream
 - bytedance/seedance-2.0-mini (~$0.080/sec, 4-15s, 5s default) — 2.0-generation quality at roughly half the 2.0-fast rate; 720p ceiling; supports RealFace and first/last-frame
@@ -342,10 +366,28 @@ Returns a permanent blockrun-hosted MP4 URL (the gateway mirrors the asset to GC
       let estimatedCost = 0;
       let quotedUsd: number | null = null;
       let jobId: string | undefined;
-      // True while a Base poll carrying the payment header has been issued and
-      // has not answered. A poll that rejects leaves it true: that request may
-      // still be settling on the gateway, which does not stop on disconnect.
-      let paidPollInFlight = false;
+      // Whether a request carrying the payment is outstanding, per call (the
+      // MCP SDK dispatches tool calls concurrently). Armed the moment a signed
+      // request is about to leave — never around the unpaid quote — and
+      // settled on every answer; utils/in-flight.ts explains why the
+      // hand-rolled boolean this replaces was wrong on every rail.
+      const paid = trackPaidRequest();
+      // Set once a request carrying the payment has left at all, answered or
+      // not. formatError's afterPayment: a 5xx that came back on a signed
+      // request is an answer (the tracker settles), but it is not a verdict
+      // on the money — the gateway's catch-all 500 does not release the nonce.
+      let paidRequestSent = false;
+      // The amount booked as settled, once settlement was OBSERVED (a
+      // completed poll, an inline 200, the helper returning). Read by the
+      // catch: an error after this point — a payload with no URL — is a real
+      // charge with an unusable result, and the message has to say the charge
+      // stands and the job is claimable, not "failed" with model advice that
+      // invites paying again (audit round 3, D13).
+      let bookedUsd: number | null = null;
+      const book = (paidUsd: number | null) => {
+        recordActualSpend(budget, paidUsd, estimatedCost, agent_id);
+        bookedUsd = paidUsd ?? estimatedCost;
+      };
       try {
         const selectedModel = model || "xai/grok-imagine-video";
 
@@ -479,12 +521,18 @@ Returns a permanent blockrun-hosted MP4 URL (the gateway mirrors the asset to GC
 
         // ---- Rail 1: account API key. No quote, no signature, no expiry. ----
         if (isApiKeyMode()) {
+          // Not wrapped in sendPaid: this rail bills at SUBMIT and the helper
+          // already classifies every post-submit exit as a BilledJobError
+          // (certain or unknown). Arming the tracker here would make a
+          // not_charged terminal failure whose upstream text says "timeout"
+          // read as "may have settled" — the C13 shape on a third rail.
+          paidRequestSent = true;
           const { data, paidUsd, txHash } = await apiKeyAsyncPost("/v1/videos/generations", body, {
             pollBudgetMs: VIDEO_TOTAL_BUDGET_MS,
             pollIntervalMs: POLL_INTERVAL_MS,
             pollTimeoutMs: VIDEO_POLL_TIMEOUT_MS,
           });
-          recordActualSpend(budget, paidUsd, estimatedCost, agent_id);
+          book(paidUsd);
           const clip = (data as { data?: Array<{ url?: string; source_url?: string; duration_seconds?: number; request_id?: string; backed_up?: boolean }> }).data?.[0];
           if (!clip?.url) throw new Error("Completed video response missing video URL");
           const modelOut = (data as { model?: string }).model || selectedModel;
@@ -524,28 +572,53 @@ Returns a permanent blockrun-hosted MP4 URL (the gateway mirrors the asset to GC
           // installations never need to initialize SVM payment dependencies.
           const { solanaPaidAsyncPost } = await import("../utils/solana-402.js");
 
-          const { data, paidUsd, txHash } = await solanaPaidAsyncPost(
+          const { data, paidUsd, txHash, jobId: solJobId } = await solanaPaidAsyncPost(
             "/v1/videos/generations",
             body,
             {
               pollBudgetMs: SOLANA_VIDEO_TOTAL_BUDGET_MS,
-              onQuote: (quotedUsd, quoteDetails) => {
+              what: "Video generation",
+              tool: "blockrun_video",
+              onQuote: (solQuotedUsd, quoteDetails) => {
+                // Capture for the give-up path below: on Solana the quote is
+                // only ever seen inside the helper, and the catch needs it to
+                // book conservatively.
+                quotedUsd = solQuotedUsd;
                 // WHAT was quoted, before how much: a substituted or repriced
                 // model is refused here, unsigned (QuoteMismatchError).
-                assertVideoQuoteSane(quotedUsd, estimatedCost, selectedModel, "solana", quoteDetails?.resource?.description);
-                if (quotedUsd === null || quotedUsd <= estimatedCost) return;
-                gate?.release();
-                gate = reserveBudget(budget, agent_id, quotedUsd);
-                // Phrased so formatError's uncharged guard suppresses its
-                // "fund your wallet" footer — the remedy is the budget, not USDC.
-                if (!gate.allowed) throw new Error(`${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget. No charge was made.`);
+                assertVideoQuoteSane(solQuotedUsd, estimatedCost, selectedModel, "solana", quoteDetails?.resource?.description);
+                if (solQuotedUsd !== null && solQuotedUsd > estimatedCost) {
+                  gate?.release();
+                  gate = reserveBudget(budget, agent_id, solQuotedUsd);
+                  // Phrased so formatError's uncharged guard suppresses its
+                  // "fund your wallet" footer — the remedy is the budget, not USDC.
+                  if (!gate.allowed) throw new Error(`${gate.reason}. Use blockrun_wallet action:"report" to see usage or action:"delegate" to increase agent budget. No charge was made.`);
+                }
+                // Last: after the guard and the re-reserve, nothing can refuse
+                // the quote any more and the helper signs next. Armed here
+                // rather than at the paid request alone so a signing-time
+                // failure still books conservatively (the narrow residual
+                // window utils/in-flight.ts documents); the hooks below keep
+                // the tracker exact from the first signed request onwards.
+                paid.arm(solQuotedUsd);
               },
+              // The edges of every request carrying PAYMENT-SIGNATURE — the
+              // submit and each poll. A poll that drops leaves the tracker
+              // armed; a poll that answers "in_progress" settles it, so a
+              // deadline reached with nothing outstanding books nothing, the
+              // way Base's loop already behaved. Before these hooks the rail
+              // booked the estimate on ANY timeout, including the unpaid
+              // quote probe aborting (C32/C37).
+              onPaidRequest: () => { paidRequestSent = true; paid.arm(quotedUsd); },
+              onPaidResponse: () => paid.settle(),
             },
           );
+          paid.settle();
+          jobId = solJobId;
           // A terminal response means the gateway has already settled. Book it
           // before validating the payload so a malformed completed body cannot
           // make a real Solana charge disappear from the local ledger.
-          recordActualSpend(budget, paidUsd, estimatedCost, agent_id);
+          book(paidUsd);
           const clip = (data as { data?: Array<{ url?: string; source_url?: string; duration_seconds?: number; request_id?: string; backed_up?: boolean }>; model?: string }).data?.[0];
           if (!clip?.url) throw new Error("Completed Solana video response missing video URL");
           const billedUsd = paidUsd ?? estimatedCost;
@@ -657,18 +730,26 @@ Returns a permanent blockrun-hosted MP4 URL (the gateway mirrors the asset to GC
         );
 
         // Step 2: submit job with payment — server verifies (does not settle)
-        // and returns { id, poll_url, status: "queued" } in ~3-20s.
-        const submitResp = await fetchWithTimeout(submitUrl, {
+        // and returns { id, poll_url, status: "queued" } in ~3-20s. Armed for
+        // the round trip: the gateway does not settle on submit here, but it
+        // burns the nonce and enqueues, and a submit that never answers is
+        // still a signed request the gateway may have accepted.
+        paidRequestSent = true;
+        const submitResp = await sendPaid(paid, () => fetchWithTimeout(submitUrl, {
           method: "POST",
           headers: {
             "Content-Type": "application/json",
             "PAYMENT-SIGNATURE": paymentPayload,
           },
           body: JSON.stringify(body),
-        }, 30_000);
+        }, 30_000), settledUsd);
 
         if (submitResp.status === 402) {
-          throw new Error("Payment rejected. Check your wallet balance.");
+          // The one answer that IS a funding problem: the gateway refused the
+          // signed request. Named like the SDK's class so the catch classifies
+          // it by type, not by the words in it.
+          await submitResp.json().catch(() => ({}));
+          throw Object.assign(new Error("Payment rejected. Check your wallet balance."), { name: "PaymentError" });
         }
         if (!submitResp.ok && submitResp.status !== 202) {
           const errBody = await submitResp.json().catch(() => ({ error: "Submit failed" })) as Record<string, unknown>;
@@ -720,23 +801,21 @@ Returns a permanent blockrun-hosted MP4 URL (the gateway mirrors the asset to GC
           if (pollTimeoutMs === 0) break;
 
           let pollResp: Response;
-          paidPollInFlight = true;
           try {
-            pollResp = await fetchWithTimeout(pollAbsoluteUrl, {
+            pollResp = await sendPaid(paid, () => fetchWithTimeout(pollAbsoluteUrl, {
               method: "GET",
               headers: { "PAYMENT-SIGNATURE": paymentPayload },
-            }, pollTimeoutMs);
+            }, pollTimeoutMs), settledUsd);
           } catch {
             // Polling is idempotent and settlement has not been observed. A
             // transient disconnect is safe to retry inside the existing
             // deadline (the EIP-3009 nonce is single-use, so re-sending the
             // same header after a lost-in-flight settlement cannot settle
             // twice), and one reset must not abandon a nine-minute render.
-            // paidPollInFlight stays true: the request that never answered may
+            // The tracker stays armed: the request that never answered may
             // still be settling server-side.
             continue;
           }
-          paidPollInFlight = false;
 
           const pollData = await pollResp.json().catch(() => ({})) as {
             status?: string;
@@ -761,7 +840,7 @@ Returns a permanent blockrun-hosted MP4 URL (the gateway mirrors the asset to GC
           // finally released the reservation — a real charge the ledger never
           // saw, silently raising the cap by the lost amount.
           if (lastStatus === "completed" && !spendBooked) {
-            recordActualSpend(budget, settledUsd, estimatedCost, agent_id);
+            book(settledUsd);
             spendBooked = true;
           }
 
@@ -770,7 +849,11 @@ Returns a permanent blockrun-hosted MP4 URL (the gateway mirrors the asset to GC
           }
 
           if (lastStatus === "failed") {
-            throw new Error(`Upstream generation failed: ${pollData.error || "unknown"}. No payment taken.`);
+            // Typed: the upstream text rides along verbatim and can say
+            // anything — "rejected", "timeout" — none of which is a verdict
+            // on the money. The gateway's contract is that a failed job on
+            // this route is not charged.
+            throw new JobFailedError(`Upstream generation failed: ${pollData.error || "unknown"}. No payment taken.`, { jobId });
           }
 
           if (pollResp.ok && lastStatus === "completed") {
@@ -796,8 +879,8 @@ Returns a permanent blockrun-hosted MP4 URL (the gateway mirrors the asset to GC
         }
 
         if (!completed) {
-          // Whether money moved depends on paidPollInFlight, which the catch
-          // reads; the message here states only what was observed.
+          // Whether money moved depends on the tracker, which the catch reads;
+          // the message here states only what was observed.
           throw new Error(`Video generation did not complete within ${Math.round(VIDEO_TOTAL_BUDGET_MS / 1000)}s (last status: ${lastStatus}).`);
         }
 
@@ -817,7 +900,7 @@ Returns a permanent blockrun-hosted MP4 URL (the gateway mirrors the asset to GC
         ];
         // Backstop only — every reachable path here has already booked at the
         // poll site the moment "completed" was observed.
-        if (!spendBooked) recordActualSpend(budget, settledUsd, estimatedCost, agent_id);
+        if (!spendBooked) book(settledUsd);
 
         return {
           content: [{ type: "text", text: lines.join("\n") }],
@@ -834,54 +917,100 @@ Returns a permanent blockrun-hosted MP4 URL (the gateway mirrors the asset to GC
         };
       } catch (err) {
         const errMsg = err instanceof Error ? err.message : String(err);
-        // The account rail bills at SUBMIT. A failure after that — deadline,
-        // poll error, terminal failure — leaves a charge the ledger must carry
-        // (finally releases the reservation, so without this booking the cap
-        // silently rises by the clip price), and the one thing the caller must
-        // not do is "try again": that submits and bills a second job. Checked
-        // before isTimeoutError, which matches the deadline message and would
-        // glue retry advice onto a note saying the job was billed.
+        const reclaim = jobId ? ` The finished job stays claimable on the gateway for ~48h (job ${jobId}); re-running blockrun_video would start and charge a new job.` : "";
+        // The order below is the classification, and it is the same on all
+        // three rails. Each step is a fact the code observed — a booking, a
+        // typed error, the tracker — never a word in the message: the message
+        // carries upstream text verbatim, and "rejected", "timeout" and
+        // "balance" have all arrived in it for reasons that had nothing to do
+        // with the money (audit round 3, C13/C32/C36/C37).
+        //
+        // 1. Settlement was observed and booked, then the result could not be
+        //    used (no URL in a completed payload). The charge stands; the one
+        //    thing not to do is run the tool again, which pays for a second
+        //    render of a clip that is claimable for ~48h (D13).
+        if (bookedUsd !== null) {
+          return {
+            content: [{ type: "text", text: `Video generation completed and the charge stands — $${bookedUsd.toFixed(4)} was settled${jobId ? ` for job ${jobId}` : ""} and is booked against your budget — but the result could not be used: ${errMsg}${reclaim || " Re-running blockrun_video would start and charge a new job."}\nCheck blockrun_wallet action:"report" before doing anything else.` }],
+            isError: true,
+          };
+        }
+        // 2. The gateway billed the job at SUBMIT — the account rail always,
+        //    the Solana audio route (settled optimistically at POST) via the
+        //    shared helper — and the failure came after: deadline, poll
+        //    error, terminal failure, or a submit that never answered
+        //    ("unknown"). The ledger must carry it (finally releases the
+        //    reservation, so without this booking the cap silently rises by
+        //    the clip price), and the one thing the caller must not do is
+        //    "try again": that submits and bills a second job.
         if (err instanceof BilledJobError) {
           recordActualSpend(budget, err.paidUsd, estimatedCost, agent_id);
+          const account = isApiKeyMode();
+          const billedTo = account ? "the BlockRun account" : "the Solana wallet";
           const what = err.billing === "billed"
-            ? `Video generation did not return a clip, but the job was billed to the BlockRun account when the gateway accepted it${err.jobId ? ` (job ${err.jobId})` : ""}.`
-            : `Video generation got no answer to its submit, so the job MAY have been accepted and billed to the BlockRun account.`;
+            ? `Video generation did not return a clip, but the job was billed to ${billedTo} when the gateway accepted it${err.jobId ? ` (job ${err.jobId})` : ""}.`
+            : `Video generation got no answer to its submit, so the job MAY have been accepted and billed to ${billedTo}.`;
+          const where = account ? "https://user.blockrun.ai/dashboard/activity" : `blockrun_wallet action:"report" or the wallet's recent transactions`;
           return {
-            content: [{ type: "text", text: `${what} Check https://user.blockrun.ai/dashboard/activity before doing anything else — a new blockrun_video call starts and bills a second job.\nError: ${errMsg}` }],
+            content: [{ type: "text", text: `${what} Check ${where} before doing anything else — a new blockrun_video call starts and bills a second job.\nError: ${errMsg}` }],
             isError: true,
           };
         }
-        if (isPaymentRejectionError(errMsg)) {
+        // 3. The wallet refused to pay: a 402 that came back on the signed
+        //    request. The only branch that may say "out of funds" or open a
+        //    top-up page — and it is reached by type, never by the words in
+        //    an upstream failure (C36). The account rail's 402 is worded by
+        //    apiKeyAsyncPost itself ("out of credit"), so nothing to add.
+        if (isPaymentRefusal(err)) {
           return {
             content: [{ type: "text", text: `Video generation needs USDC — your wallet is out of funds. ${(await launchTopUp()).note}\nError: ${errMsg}` }],
             isError: true,
           };
         }
+        // 4. A request carrying the payment was outstanding and no answer was
+        //    observed — the last signed poll dropped, or the submit did. The
+        //    gateway's poll route settles a "completed" job whether or not we
+        //    are still connected, so this is booked (the quote where one was
+        //    seen, else the reserve) and said out loud. The tracker, not the
+        //    chain, decides: 0.50.0 booked on the Solana rail for ANY timeout,
+        //    including the unpaid quote probe aborting before anything was
+        //    signed (C32/C37).
+        const giveUp = settleGiveUp(paid, err, { budget, agentId: agent_id, estimateUsd: estimatedCost, what: "Video generation", note: reclaim.trim() || undefined });
+        if (giveUp) return { content: [{ type: "text", text: giveUp.text }], isError: true };
+        // 5. The gateway answered a poll with "failed" on a route that charges
+        //    on completion: nothing was charged, whatever the upstream text
+        //    says (MiniMax's is "The operation was aborted due to timeout" —
+        //    C13). No reclaim note: there is no finished job.
+        if (err instanceof JobFailedError) {
+          return {
+            content: [{ type: "text", text: formatError(`Video generation failed: ${errMsg}`, { altModels: "bytedance/seedance-2.0, azure/sora-2" }) }],
+            isError: true,
+          };
+        }
+        // 6. A labelled 5xx is an ANSWER, not a timeout, however its text
+        //    reads ("504 Gateway Timeout"). formatError says what a 5xx after
+        //    a signed request means for the money; a bare "timed out" here
+        //    would promise "no payment was taken" on a settled-at-submit route.
+        if (hasLabelledServerStatus(errMsg)) {
+          return {
+            content: [{ type: "text", text: formatError(`Video generation failed: ${errMsg}`, { altModels: "bytedance/seedance-2.0, azure/sora-2", afterPayment: paidRequestSent }) + reclaim }],
+            isError: true,
+          };
+        }
+        // 7. A timeout with nothing outstanding: the unpaid quote probe
+        //    aborted, signing failed before anything was sent, or the deadline
+        //    passed after the last poll was ANSWERED — on the wallet rails
+        //    settlement needs a signed poll to observe "completed", so nothing
+        //    settled. (On the account rail every post-submit exit is step 2.)
         if (isTimeoutError(err)) {
-          const reclaim = jobId ? ` The finished job stays claimable on the gateway for ~48h (job ${jobId}); re-running blockrun_video would start and charge a new job.` : "";
-          if (paidPollInFlight) {
-            // The gateway's poll route passes the request signal only to the
-            // upstream check; on "completed" it backs up the clip and settles
-            // regardless of whether we are still connected. Book the quote
-            // conservatively — over-counting a slow poll that settled nothing
-            // is the documented trade-off; under-counting a real charge is not.
-            recordActualSpend(budget, quotedUsd, estimatedCost, agent_id);
-            return {
-              content: [{ type: "text", text: `Video generation timed out while a poll carrying the payment signature was still in flight, so the gateway MAY have settled the charge after this client gave up — check blockrun_wallet action:"report" or the wallet's recent transactions before retrying.${reclaim}\nError: ${errMsg}` }],
-              isError: true,
-            };
-          }
-          // On Base, settlement happens only on a poll the gateway answers
-          // "completed"; the last one answered otherwise, so nothing settled.
-          // The Solana helper describes its own money state in errMsg.
-          const base = !isApiKeyMode() && getChain() !== "solana";
+          const base = !isApiKeyMode();
           return {
             content: [{ type: "text", text: `Video generation timed out.${base ? ` No payment was taken.${reclaim}` : ""}\nError: ${errMsg}` }],
             isError: true,
           };
         }
         return {
-          content: [{ type: "text", text: formatError(`Video generation failed: ${errMsg}`, { altModels: "bytedance/seedance-2.0, azure/sora-2" }) }],
+          content: [{ type: "text", text: formatError(`Video generation failed: ${errMsg}`, { altModels: "bytedance/seedance-2.0, azure/sora-2", afterPayment: paidRequestSent }) }],
           isError: true,
         };
       } finally {
diff --git a/src/tools/wallet.ts b/src/tools/wallet.ts
index dbdf1c9..3c5d153 100644
--- a/src/tools/wallet.ts
+++ b/src/tools/wallet.ts
@@ -8,10 +8,22 @@ import { describeBlock, formatCredit, getAccountCredit } from "../utils/account.
 import { generateQrPng, openQrInViewer } from "../utils/qr.js";
 import { launchTopUp } from "../utils/onramp.js";
 import { formatError } from "../utils/errors.js";
+import { delegateAgent, listRevokedAgents, revokeAgent, sealOperatorCeiling } from "../utils/budget.js";
 import { TOOL_ANNOTATIONS } from "../tool-annotations.js";
 import { appToolMeta } from "../apps.js";
 
 export function registerWalletTool(server: McpServer, budget: BudgetState): void {
+  // The limit this ledger was BORN with is the operator's BLOCKRUN_BUDGET_LIMIT
+  // (initializeMcpServer seeds it from the env and registers tools right
+  // after). It is sealed here, before the model can call anything, and the
+  // budget/delegate branches below treat it as a ceiling the session may
+  // lower but never clear or exceed — see budget.ts for the failure this
+  // prevents. Null means the server started unlimited and set/clear keep
+  // their original, unrestricted meaning.
+  const ceiling = sealOperatorCeiling(budget);
+  const ceilingStr = ceiling !== null ? `$${ceiling.toFixed(2)}` : null;
+  const restartHint = `Only a restart with a higher BLOCKRUN_BUDGET_LIMIT raises it.`;
+
   server.registerTool(
     "blockrun_wallet",
     {
@@ -46,11 +58,15 @@ Actions:
 
 Budget controls:
 - budget + budget_action:"set" + budget_amount:1.00 → Set global spend cap
-- budget + budget_action:"clear" → Remove global spend cap
+- budget + budget_action:"check" (the default) → Report the cap, spend and remaining
+- budget + budget_action:"clear" → Remove a cap set here
+If the operator started the server with BLOCKRUN_BUDGET_LIMIT, that value is a
+ceiling this tool can only lower: set above it is clamped, clear restores it,
+and agent_limit is clamped to it. Only a restart with a new env raises it.
 
 Multi-agent orchestration:
 - delegate + agent_id:"research" + agent_limit:2.00 → Allocate $2 to a child agent
-- revoke + agent_id:"research" → Remove a child agent's budget
+- revoke + agent_id:"research" → Remove a child agent's cap (its spend is kept; re-delegating the id carries it)
 - report → See per-agent spending breakdown
 
 Usage pattern for multi-agent systems:
@@ -65,7 +81,7 @@ Do NOT call this for actual AI queries — use blockrun_chat for that.`,
       inputSchema: {
         action: z.enum(["status", "deposit", "setup", "qr", "chain", "budget", "delegate", "revoke", "report"]).optional().default("status").describe("What to do"),
         chain: z.enum(["base", "solana"]).optional().describe("Target chain for action='chain'. Omit to view the current active chain."),
-        budget_action: z.enum(["set", "check", "clear"]).optional().describe("Budget action (for action='budget')"),
+        budget_action: z.enum(["set", "check", "clear"]).optional().describe("Budget action (for action='budget'). Defaults to 'check', which only reports."),
         budget_amount: z.number().optional().describe("Budget limit in USD (for budget_action='set')"),
         agent_id: z.string().optional().describe("Agent identifier for delegate/revoke/report actions"),
         agent_limit: z.number().optional().describe("Budget limit in USD for this agent (required for delegate action)"),
@@ -75,6 +91,13 @@ Do NOT call this for actual AI queries — use blockrun_chat for that.`,
       // Handle budget action
       if (action === "budget") {
         const budgetAct = budget_action || "check";
+        // What the call did, in the model's own terms. A clamp or a restored
+        // ceiling is NOT an error — the state changed, just not to what was
+        // asked — but the reason has to be in the text, because the next thing
+        // an agent does after "Set to $2.00" when it asked for $1000 is ask
+        // again.
+        let outcome = "";
+        let clamped = false;
 
         if (budgetAct === "set") {
           if (budget_amount === undefined || budget_amount <= 0) {
@@ -83,9 +106,24 @@ Do NOT call this for actual AI queries — use blockrun_chat for that.`,
               isError: true,
             };
           }
-          budget.limit = budget_amount;
+          if (ceiling !== null && budget_amount > ceiling) {
+            clamped = true;
+            budget.limit = ceiling;
+            outcome = ` | Requested $${budget_amount.toFixed(2)}, clamped to ${ceilingStr}: the operator set BLOCKRUN_BUDGET_LIMIT=${ceilingStr} as this process's ceiling and it cannot be raised from inside the session. ${restartHint}`;
+          } else {
+            budget.limit = budget_amount;
+            outcome = ` | Set to $${budget_amount.toFixed(2)}`;
+          }
         } else if (budgetAct === "clear") {
-          budget.limit = null;
+          if (ceiling !== null) {
+            budget.limit = ceiling;
+            outcome = ` | Restored to the operator ceiling ${ceilingStr} (BLOCKRUN_BUDGET_LIMIT); that cap cannot be removed from inside the session. ${restartHint}`;
+          } else {
+            budget.limit = null;
+            outcome = " | Limit removed";
+          }
+        } else if (ceiling !== null) {
+          outcome = ` | Ceiling: ${ceilingStr} (BLOCKRUN_BUDGET_LIMIT, operator-set; this tool can only lower it)`;
         }
 
         const remaining = budget.limit !== null ? budget.limit - budget.spent : null;
@@ -93,9 +131,11 @@ Do NOT call this for actual AI queries — use blockrun_chat for that.`,
         const remainingStr = remaining !== null ? `$${remaining.toFixed(4)}` : "N/A";
 
         return {
-          content: [{ type: "text", text: `Session Budget: ${limitStr} | Spent: $${budget.spent.toFixed(4)} | Calls: ${budget.calls} | Remaining: ${remainingStr}${budgetAct === "set" ? ` | Set to $${budget_amount?.toFixed(2)}` : ""}${budgetAct === "clear" ? " | Limit removed" : ""}` }],
+          content: [{ type: "text", text: `Session Budget: ${limitStr} | Spent: $${budget.spent.toFixed(4)} | Calls: ${budget.calls} | Remaining: ${remainingStr}${outcome}` }],
           structuredContent: {
             limit: budget.limit,
+            ceiling,
+            clamped,
             spent: budget.spent,
             calls: budget.calls,
             remaining,
@@ -111,20 +151,60 @@ Do NOT call this for actual AI queries — use blockrun_chat for that.`,
         if (!agent_limit || agent_limit <= 0) {
           return { content: [{ type: "text", text: formatError("agent_limit (USD > 0) required for delegate action") }], isError: true };
         }
-        budget.agents.set(agent_id, { limit: agent_limit, spent: 0, calls: 0 });
+        // A child's cap cannot exceed the operator's. The global cap would
+        // stop the spend anyway; what a $50 allocation under a $2 ceiling
+        // gets wrong is the REPORT — an agent told it has $48 remaining plans
+        // for $48.
+        const requested = agent_limit;
+        const limit = ceiling !== null && agent_limit > ceiling ? ceiling : agent_limit;
+        // Carry the LEDGER across a re-delegation (and across a revoke — see
+        // delegateAgent). This used to write `spent: 0` unconditionally, so an
+        // agent that had exhausted its cap could refill itself by calling
+        // delegate again with the same id — and delegate is a tool the model
+        // can call. A limit is a policy the operator may raise or lower at
+        // will; spend already happened and is not the operator's to erase.
+        // The entry is mutated in place rather than replaced: a paid call
+        // that reserved against it before this re-delegation must release
+        // against the same object afterwards, or the estimate is stranded on
+        // the ledger for the rest of the process.
+        const { entry, carried } = delegateAgent(budget, agent_id, limit);
+        const { spent, calls } = entry;
+        // USDC has six decimals, and float subtraction does not: 1 - 0.9 is
+        // 0.09999999999999998, which would surface verbatim in the report and
+        // in structuredContent. Round the DERIVED figure; `spent` stays exact.
+        const remaining = Math.round(Math.max(0, limit - spent) * 1e6) / 1e6;
+        const lines = [`Agent "${agent_id}" allocated $${limit.toFixed(2)} budget.`];
+        if (limit !== requested) {
+          lines.push(
+            `Requested $${requested.toFixed(2)}, clamped to ${ceilingStr}: the operator set BLOCKRUN_BUDGET_LIMIT=${ceilingStr} ` +
+            `as this process's ceiling and no agent can be allocated more than that. ${restartHint}`,
+          );
+        }
+        if (carried) {
+          lines.push(
+            `Carried over from the previous allocation: $${spent.toFixed(4)} spent across ${calls} call${calls === 1 ? "" : "s"} — ` +
+            `$${remaining.toFixed(4)} remains under the new limit.` +
+            (remaining === 0 ? ` This agent is already at its cap; raise agent_limit above $${spent.toFixed(4)} to give it room.` : ""),
+          );
+        }
+        if (budget.limit !== null && limit > budget.limit) {
+          lines.push(`Note: the session cap is $${budget.limit.toFixed(2)}, so this agent cannot actually spend more than that.`);
+        }
+        lines.push(`Pass agent_id: "${agent_id}" in any blockrun_* tool call to track and enforce this limit.`);
         return {
-          content: [{ type: "text", text: `Agent "${agent_id}" allocated $${agent_limit.toFixed(2)} budget.\nPass agent_id: "${agent_id}" in any blockrun_* tool call to track and enforce this limit.` }],
-          structuredContent: { agent_id, limit: agent_limit, spent: 0, calls: 0 },
+          content: [{ type: "text", text: lines.join("\n") }],
+          structuredContent: { agent_id, limit, spent, calls, remaining },
         };
       }
 
-      // Revoke: remove an agent's budget allocation
+      // Revoke: remove an agent's cap. The ledger is kept — revoke + delegate
+      // is two model-callable calls, and letting them reset `spent` would be
+      // the refill the carry-over above exists to prevent.
       if (action === "revoke") {
         if (!agent_id) {
           return { content: [{ type: "text", text: formatError("agent_id required for revoke action") }], isError: true };
         }
-        const existed = budget.agents.has(agent_id);
-        budget.agents.delete(agent_id);
+        const existed = revokeAgent(budget, agent_id);
         return {
           content: [{ type: "text", text: existed ? `Agent "${agent_id}" budget revoked.` : `Agent "${agent_id}" had no budget entry.` }],
           structuredContent: { agent_id, revoked: existed },
@@ -133,7 +213,7 @@ Do NOT call this for actual AI queries — use blockrun_chat for that.`,
 
       // Report: show spending breakdown by agent
       if (action === "report") {
-        const agentRows: Record<string, { limit: number; spent: number; calls: number; remaining: number }> = {};
+        const agentRows: Record<string, { limit: number | null; spent: number; calls: number; remaining: number | null; revoked?: true }> = {};
         for (const [id, ab] of budget.agents.entries()) {
           agentRows[id] = {
             limit: ab.limit,
@@ -142,18 +222,26 @@ Do NOT call this for actual AI queries — use blockrun_chat for that.`,
             remaining: Math.max(0, ab.limit - ab.spent),
           };
         }
+        // Revoked ids keep their ledger (the next delegate carries it); the
+        // report shows it, because "its spend is kept" is what the
+        // description promises and a tombstone nobody can read is not kept.
+        for (const [id, ab] of listRevokedAgents(budget)) {
+          if (!(id in agentRows)) agentRows[id] = { limit: null, spent: ab.spent, calls: ab.calls, remaining: null, revoked: true };
+        }
         const agentLines = Object.entries(agentRows).map(
-          ([id, ab]) => `  ${id}: $${ab.spent.toFixed(4)}/$${ab.limit.toFixed(2)} (${ab.calls} calls, $${ab.remaining.toFixed(4)} remaining)`
+          ([id, ab]) => ab.revoked
+            ? `  ${id}: $${ab.spent.toFixed(4)} (${ab.calls} calls, revoked — no cap; re-delegating carries this spend)`
+            : `  ${id}: $${ab.spent.toFixed(4)}/$${(ab.limit as number).toFixed(2)} (${ab.calls} calls, $${(ab.remaining as number).toFixed(4)} remaining)`
         );
         const lines = [
-          `Global: $${budget.spent.toFixed(4)} spent${budget.limit ? ` / $${budget.limit.toFixed(2)} limit` : " (no limit)"} — ${budget.calls} calls`,
+          `Global: $${budget.spent.toFixed(4)} spent${budget.limit ? ` / $${budget.limit.toFixed(2)} limit` : " (no limit)"} — ${budget.calls} calls${ceiling !== null ? ` (operator ceiling ${ceilingStr} via BLOCKRUN_BUDGET_LIMIT)` : ""}`,
           ``,
           `Per-agent budgets (${budget.agents.size} active):`,
           ...(agentLines.length > 0 ? agentLines : ["  (none delegated)"]),
         ];
         return {
           content: [{ type: "text", text: lines.join("\n") }],
-          structuredContent: { global: { limit: budget.limit, spent: budget.spent, calls: budget.calls }, agents: agentRows },
+          structuredContent: { global: { limit: budget.limit, ceiling, spent: budget.spent, calls: budget.calls }, agents: agentRows },
         };
       }
 
@@ -404,6 +492,12 @@ SECURITY: Private key stored at ~/.blockrun/.session by default (never leaves yo
       const envNote = envIgnored
         ? `\n\n⚠️  SOLANA_WALLET_KEY is set but the active chain is BASE — a stored chain preference outranks it. Run action:"chain" chain:"solana" to switch (that also clears the stored preference).`
         : "";
+      // The description promises "session spending" from status, and tells
+      // the model to check here before an expensive call. The balance alone
+      // answers "can the wallet pay?" — not "am I still inside my cap?", which
+      // is the question an agent on a $1 allotment is actually asking. Same
+      // line and fields as the api-key branch, so a client renders one shape.
+      const session = `$${budget.spent.toFixed(4)}${budget.limit ? ` / $${budget.limit.toFixed(2)} local cap` : ""} — ${budget.calls} calls`;
       const text = `Active chain: ${chain.toUpperCase()}   (switch with action:"chain" chain:"base"|"solana")
 
 ${mark("base")} Base:   ${both.base.address}
@@ -411,6 +505,7 @@ ${mark("base")} Base:   ${both.base.address}
 ${mark("solana")} Solana: ${both.solana.address}
             ${fmt(solBal)}${solBal !== null && solBal < 1 ? "  (low)" : ""}
 
+This session: ${session}
 Paying on ${chain} | View active: ${info.explorerUrl}${info.isNew ? "\nNEW WALLET on active chain — run action:'setup' for funding instructions" : ""}${envNote}`;
 
       return {
@@ -424,6 +519,9 @@ Paying on ${chain} | View active: ${info.explorerUrl}${info.isNew ? "\nNEW WALLE
           isNew: info.isNew,
           explorerUrl: info.explorerUrl,
           explorerLabel,
+          sessionSpend: budget.spent,
+          calls: budget.calls,
+          limit: budget.limit,
           wallets: {
             base: { address: both.base.address, balance: baseBal },
             solana: { address: both.solana.address, balance: solBal },
diff --git a/src/utils/api-key-call.ts b/src/utils/api-key-call.ts
index 710ff9f..d283b88 100644
--- a/src/utils/api-key-call.ts
+++ b/src/utils/api-key-call.ts
@@ -16,7 +16,7 @@
 // it needs its own module rather than a flag threaded through the 402 code.
 
 import { fetchWithTimeout } from "./http.js";
-import { pollTimeoutFor } from "./poll.js";
+import { JobFailedError, pollTimeoutFor } from "./poll.js";
 import { apiAuthHeaders } from "./auth.js";
 import { getApiBase, resolveGatewayUrl } from "./wallet.js";
 
@@ -181,8 +181,25 @@ function statusErrorMessage(response: Response, what: string, body: Record<strin
   return `API error ${response.status}: ${JSON.stringify(body)}`;
 }
 
+/**
+ * A non-OK answer from the account API, carrying its status the way the SDK's
+ * APIError does (`statusCode`). The path tools' shared catch
+ * (utils/path-tool-catch.ts) reads it through settlementOnThrow to tell an edge
+ * 502/504 — the origin may still be running and billing the call — from a
+ * refusal the gateway itself authored; a bare Error hid the status inside the
+ * message and every account-rail 5xx read as "nothing could have settled".
+ */
+export class AccountApiError extends Error {
+  readonly statusCode: number;
+  constructor(message: string, statusCode: number) {
+    super(message);
+    this.name = "AccountApiError";
+    this.statusCode = statusCode;
+  }
+}
+
 async function throwForStatus(response: Response, what: string): Promise<never> {
-  throw new Error(statusErrorMessage(response, what, await readJson(response)));
+  throw new AccountApiError(statusErrorMessage(response, what, await readJson(response)), response.status);
 }
 
 /** POST an endpoint that answers inline. `endpoint` is rooted, e.g. "/v1/audio/speech". */
@@ -293,7 +310,17 @@ export async function apiKeyAsyncPost(
     return { data: submitted, paidUsd: costFrom(submit), txHash: receiptFrom(submit), jobId };
   }
   if (!pollUrl) {
-    throw new Error(`Async submit missing poll_url: ${JSON.stringify(submitted)}`);
+    // A 202 IS the acceptance, and this rail bills on acceptance. A malformed
+    // envelope is a billed job this client cannot poll — typed as such, so the
+    // tool books it and names the job, instead of the plain Error that the
+    // callers' comments ("every post-submit exit is a BilledJobError") were
+    // wrong about until audit round 4.
+    throw new BilledJobError(
+      `Async submit answered 202 without a poll_url (${JSON.stringify(submitted)}), so the job cannot be polled from here. ` +
+        `It has already been billed to the account${jobId ? `; job id ${jobId}` : ""} — ` +
+        `check https://user.blockrun.ai/dashboard/activity before submitting again.`,
+      { paidUsd: submitCost, jobId, billing: "billed" },
+    );
   }
 
   const absolutePollUrl = resolveGatewayUrl(pollUrl);
@@ -339,7 +366,9 @@ export async function apiKeyAsyncPost(
       const note = typeof data.note === "string" ? data.note : undefined;
       const failed = `Upstream generation failed: ${String(data.error ?? "unknown")}.`;
       if (paymentStatus === "not_charged") {
-        throw new Error(`${failed} ${note ?? "No payment was taken."}`);
+        // Typed: the upstream text rides along verbatim and can say "timeout"
+        // or "aborted" — none of it is a verdict on the money. The type is.
+        throw new JobFailedError(`${failed} ${note ?? "No payment was taken."}`, { jobId });
       }
       // Anything short of an observed refund is bookable: an explicit charged
       // status is certain, an absent one is unknown — and unknown books too,
diff --git a/src/utils/budget.ts b/src/utils/budget.ts
index 617d920..e5196ed 100644
--- a/src/utils/budget.ts
+++ b/src/utils/budget.ts
@@ -1,5 +1,5 @@
 // src/utils/budget.ts
-import type { BudgetState } from "../types.js";
+import type { AgentBudget, BudgetState } from "../types.js";
 
 const EPSILON = 1e-9;
 
@@ -149,12 +149,17 @@ export function recordSpending(budget: BudgetState, cost: number, agentId?: stri
   budget.calls += 1;
 
   if (agentId) {
-    const agentBudget = budget.agents.get(agentId);
+    // The live entry, or the tombstone a revoke left behind: a call that
+    // settles while its id is revoked still spent that agent's money, and the
+    // next delegate of the id carries the ledger back. Until audit round 4
+    // this looked only at the live map, so revoke → settle → delegate forgot
+    // the call — a per-agent refill, one in-flight call at a time.
+    const agentBudget = budget.agents.get(agentId) ?? revokedLedgers.get(budget)?.get(agentId);
     if (agentBudget) {
       agentBudget.spent += cost;
       agentBudget.calls += 1;
     }
-    // If no budget entry for this agent, spending is tracked globally only
+    // If no entry for this agent anywhere, spending is tracked globally only
   }
 }
 
@@ -180,6 +185,17 @@ export function amountToUsd(amount: unknown): number | null {
  * real on-chain spend: the old path recorded a flat estimate, so a frontier
  * chat or high-resolution video could settle for orders of magnitude more than
  * was booked, silently blowing past the cap.
+ *
+ * ZERO IS A SETTLED FIGURE, NOT AN ABSENT ONE. The account rail writes
+ * `x-blockrun-cost-usd: 0.000000` for a charge that really resolved to nothing,
+ * and parseCostHeader preserves it as 0 for exactly this call; the wallet rails
+ * report a genuinely free model as a 0 counter delta. Until audit round 3 this
+ * treated 0 like null (`actualUsd > 0`) and booked the ESTIMATE for it, so a
+ * free-priced account call was recorded at the reserve and a $0.05 delegate
+ * was cut off after seven of them having spent nothing (D33/D40). "Unknown" is
+ * spelled null/undefined; NaN and a negative are estimator bugs and fall back
+ * the same way. Callers that cannot tell free from unknown must pass null —
+ * amountToUsd already does, mapping a missing or "0" x402 amount to null.
  */
 export function recordActualSpend(
   budget: BudgetState,
@@ -188,7 +204,7 @@ export function recordActualSpend(
   agentId?: string,
 ): void {
   const cost =
-    typeof actualUsd === "number" && Number.isFinite(actualUsd) && actualUsd > 0
+    typeof actualUsd === "number" && Number.isFinite(actualUsd) && actualUsd >= 0
       ? actualUsd
       : Math.max(0, estimate);
   recordSpending(budget, cost, agentId);
@@ -206,6 +222,123 @@ export function parseBudgetLimitEnv(raw: string | undefined): number | null {
   return Number.isFinite(n) && n > 0 ? n : null;
 }
 
+// ---------------------------------------------------------------------------
+// The operator's ceiling — the one number the session cannot raise
+// ---------------------------------------------------------------------------
+//
+// BLOCKRUN_BUDGET_LIMIT is documented as the hard stop for clients that cannot
+// render the spend dialog: on those, it is the ONLY guard. It used to seed the
+// same mutable `budget.limit` that blockrun_wallet action:"budget" writes, so
+// the agent it constrained could clear it (limit = null) or raise it (any
+// positive number) in one free, non-destructive, un-elicited tool call — and
+// the denial text it received at the cap pointed it at exactly that tool.
+//
+// The env value is therefore remembered separately, keyed by the ledger it
+// seeded, and the wallet tool treats it as a ceiling: `set` may lower the
+// session cap or raise it back UP TO the ceiling, `clear` restores the ceiling
+// rather than lifting it, and a delegated per-agent cap is clamped to it.
+// Without the env the ceiling is null and the tool keeps its old contract —
+// set/clear are then the operator's own session controls, and there is no one
+// to protect them from.
+//
+// A WeakMap rather than a field on BudgetState: the ledger is constructed in
+// one place and handed by reference to every tool, and the ceiling is a fact
+// about how that ledger was BORN, not state the tools update. Sealing happens
+// at wallet-tool registration, which initializeMcpServer runs right after the
+// env seed — so "the limit the server started with" and "the env value" are
+// the same number, and a cap the model sets later in the session is not
+// mistaken for one.
+const operatorCeilings = new WeakMap<BudgetState, number | null>();
+
+/**
+ * Record the current `budget.limit` as the operator ceiling for this ledger,
+ * once. Later calls return the sealed value and do not re-read `limit`, so a
+ * session `set` cannot become the ceiling by being sealed after the fact.
+ */
+export function sealOperatorCeiling(budget: BudgetState): number | null {
+  if (!operatorCeilings.has(budget)) operatorCeilings.set(budget, budget.limit);
+  return operatorCeilings.get(budget) ?? null;
+}
+
+/** The sealed operator ceiling, or null when the server started unlimited. */
+export function getOperatorCeiling(budget: BudgetState): number | null {
+  return operatorCeilings.get(budget) ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Per-agent allocations — the ledger follows the agent_id, not the Map entry
+// ---------------------------------------------------------------------------
+//
+// Two bugs shared a root: `delegate` REPLACED the Map entry and `revoke`
+// DELETED it, while the reservation closure in reserveBudget() holds the entry
+// object it was given. So a re-delegation two minutes into a $1 render carried
+// `spent` into a new object, the actual was booked on the new one and the
+// estimate released from the old — the agent was over-counted by the estimate
+// for the rest of the process. And revoke + delegate (two calls, both the
+// model's to make) started the id at zero, which is the refill 0.50.0 said it
+// had closed.
+//
+// So the entry object is never replaced: re-delegation mutates its `limit`,
+// and revoke moves the SAME object into a per-ledger tombstone map that the
+// next delegate of that id restores. A reservation taken before either
+// operation releases against the object that is live after it. Spend made
+// while an id is revoked is tracked globally only, as before — a revoked id
+// has no per-agent cap, and a cap it does not have cannot be charged against.
+const revokedLedgers = new WeakMap<BudgetState, Map<string, AgentBudget>>();
+
+/**
+ * Allocate (or re-allocate) a per-agent cap. Returns the live entry and
+ * whether it carried a prior ledger — from a live entry or a revoked one — so
+ * the caller can say so. Never resets `spent`/`calls`.
+ */
+export function delegateAgent(
+  budget: BudgetState,
+  agentId: string,
+  limit: number,
+): { entry: AgentBudget; carried: boolean } {
+  const live = budget.agents.get(agentId);
+  if (live) {
+    live.limit = limit;
+    return { entry: live, carried: true };
+  }
+  const tombs = revokedLedgers.get(budget);
+  const revoked = tombs?.get(agentId);
+  if (revoked) {
+    tombs!.delete(agentId);
+    revoked.limit = limit;
+    budget.agents.set(agentId, revoked);
+    return { entry: revoked, carried: true };
+  }
+  const entry: AgentBudget = { limit, spent: 0, calls: 0 };
+  budget.agents.set(agentId, entry);
+  return { entry, carried: false };
+}
+
+/**
+ * The ledgers revoke left behind, for action:"report": the tool description
+ * promises "its spend is kept", and kept spend nobody can read is not kept.
+ */
+export function listRevokedAgents(budget: BudgetState): Array<[string, AgentBudget]> {
+  return [...(revokedLedgers.get(budget)?.entries() ?? [])];
+}
+
+/**
+ * Remove an agent's cap. Its ledger is kept (tombstoned) so a later delegate
+ * of the same id carries the spend. Returns false when there was no entry.
+ */
+export function revokeAgent(budget: BudgetState, agentId: string): boolean {
+  const live = budget.agents.get(agentId);
+  if (!live) return false;
+  budget.agents.delete(agentId);
+  let tombs = revokedLedgers.get(budget);
+  if (!tombs) {
+    tombs = new Map();
+    revokedLedgers.set(budget, tombs);
+  }
+  tombs.set(agentId, live);
+  return true;
+}
+
 // ---------------------------------------------------------------------------
 // Quote sanity — pay what you were told, or nothing
 // ---------------------------------------------------------------------------
diff --git a/src/utils/chat-stream.ts b/src/utils/chat-stream.ts
index b1a2804..a6841b9 100644
--- a/src/utils/chat-stream.ts
+++ b/src/utils/chat-stream.ts
@@ -12,9 +12,21 @@
 //
 // The SDK's fetchWithTimeout clears its abort timer once response HEADERS
 // arrive, so reading the body has no client-side deadline — the idle guard
-// here (readWithIdleTimeout) is therefore the ONLY thing standing between a
-// stalled stream and hanging forever.
+// here (withIdleTimeout, around every read) is therefore the ONLY thing
+// standing between a stalled stream and hanging forever.
+//
+// Two clients, one assembler. LLMClient (Base wallet, and the account rail)
+// exposes chatCompletionStream() and hands back the raw Response — headers
+// included, which is where the account rail's `x-blockrun-cost-usd` lives.
+// SolanaLLMClient has no chatCompletionStream, but since @blockrun/llm 3.15.1
+// it ships stream(path, body), which pays the 402, records the settlement, and
+// yields each decoded SSE frame. Until audit round 3 the comment here said the
+// Solana client "cannot" stream, and every paid chat on the DEFAULT chain ran
+// the non-streaming path with the SDK's 60s Solana timeout — so a generation
+// over a minute was aborted client-side after the SPL payment was sent (C19).
+// Both shapes now feed the same accumulator (assembleChatFrames).
 import type { ApiClient } from "./wallet.js";
+import { parseCostHeader } from "./api-key-call.js";
 
 /** Chat message shape the gateway accepts (content may be multimodal parts). */
 export interface StreamChatMessage {
@@ -29,62 +41,162 @@ export interface StreamChatOptions {
   stop?: string[];
 }
 
-/** Narrow an ApiClient to one that can stream (SolanaLLMClient cannot). */
-export function supportsStreaming(
-  client: ApiClient,
-): client is ApiClient & { chatCompletionStream: (model: string, messages: unknown, options?: unknown) => Promise<Response> } {
+/** Token counts the gateway reports for the call, when it does. */
+export interface ChatUsage {
+  promptTokens: number;
+  completionTokens: number;
+}
+
+/**
+ * Everything a chat call comes back with that the caller has to act on — not
+ * just the text. `servedModel` is the id the GATEWAY says answered; constants.ts
+ * documents that retired ids are silently aliased onto a live model and that
+ * only this field tells you (D55). `finishReason` "length" means the reply was
+ * cut at max_tokens (D57). `settledUsd` is `x-blockrun-cost-usd` when the rail
+ * sent it — a settled zero included — and null when it did not.
+ */
+export interface ChatOutcome {
+  text: string;
+  servedModel: string | null;
+  finishReason: string | null;
+  usage: ChatUsage | null;
+  settledUsd: number | null;
+}
+
+/**
+ * A failure that arrived AFTER the gateway had answered 2xx: a mid-stream error
+ * event, an idle stall, an empty-length completion, an unreadable body. The
+ * distinction is money. On the wallet rails x402 settles on the 200, and on the
+ * account rail the request is billed once accepted — so this class is the
+ * evidence a caller needs to book the charge, where a pre-acceptance throw
+ * (a 4xx from the first response, a refused payment) books nothing.
+ *
+ * `partialText` is whatever had streamed before the failure. The caller paid
+ * for those tokens; discarding them turned "900 tokens then an error frame"
+ * into a bare error (D57).
+ */
+export class AcceptedThenFailedError extends Error {
+  readonly partialText: string;
+  constructor(message: string, partialText = "", options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "AcceptedThenFailedError";
+    this.partialText = partialText;
+  }
+}
+
+type StreamingClient = ApiClient & { chatCompletionStream: (model: string, messages: unknown, options?: unknown) => Promise<Response> };
+type FrameStreamingClient = ApiClient & { stream: (path: string, body: Record<string, unknown>) => AsyncGenerator<unknown, void, undefined> };
+
+/** Narrow an ApiClient to one whose stream call returns the raw Response (LLMClient). */
+export function supportsStreaming(client: ApiClient): client is StreamingClient {
   return typeof (client as { chatCompletionStream?: unknown }).chatCompletionStream === "function";
 }
 
-async function readWithIdleTimeout(
-  reader: ReadableStreamDefaultReader<Uint8Array>,
-  ms: number,
-): Promise<ReadableStreamReadResult<Uint8Array>> {
+/** Narrow an ApiClient to one whose stream call yields decoded frames (SolanaLLMClient). */
+export function supportsFrameStreaming(client: ApiClient): client is FrameStreamingClient {
+  return typeof (client as { stream?: unknown }).stream === "function";
+}
+
+/**
+ * The account rail's settled figure off a response, when it sent one. Absent
+ * is "unknown" (chat settles after the response by design), never "free"; an
+ * explicit 0.000000 is a settled zero. parseCostHeader draws that line.
+ */
+export function settledCostFromHeaders(headers: { get(name: string): string | null } | null | undefined): number | null {
+  return parseCostHeader(headers?.get("x-blockrun-cost-usd"));
+}
+
+function stallError(ms: number): AcceptedThenFailedError {
+  return new AcceptedThenFailedError(`stream stalled: no data from the gateway for ${Math.round(ms / 1000)}s`);
+}
+
+async function withIdleTimeout<T>(read: () => Promise<T>, ms: number): Promise<T> {
   let timer: NodeJS.Timeout | undefined;
   const stall = new Promise<never>((_, reject) => {
-    timer = setTimeout(
-      () => reject(new Error(`stream stalled: no data from the gateway for ${Math.round(ms / 1000)}s`)),
-      ms,
-    );
+    timer = setTimeout(() => reject(stallError(ms)), ms);
   });
   try {
-    return await Promise.race([reader.read(), stall]);
+    return await Promise.race([read(), stall]);
   } finally {
     clearTimeout(timer);
   }
 }
 
 /**
- * Assemble the complete reply from an OpenAI-compatible SSE body.
+ * One decoded OpenAI-compatible chunk folded into the running result.
  *
  * - Concatenates `choices[0].delta.content`; `reasoning_content` is collected
  *   separately and used only as a fallback when no content ever arrives, so a
  *   provider that splits reasoning out doesn't produce an empty answer.
  * - An `error` object mid-stream throws (the gateway reports upstream failures
- *   in-band once headers are already 200).
- * - A JSON parse failure on a single data line skips that line; SSE comment/
- *   keepalive lines (":…") and blank lines are ignored by the data: filter.
+ *   in-band once headers are already 200) — with the partial text attached.
+ * - `model` is taken from any chunk that carries it (every chunk does, on both
+ *   gateways); `usage` from the final choices-less chunk.
+ */
+class ChatAccumulator {
+  text = "";
+  reasoning = "";
+  finishReason: string | null = null;
+  servedModel: string | null = null;
+  usage: ChatUsage | null = null;
+
+  fold(event: unknown): void {
+    const ev = event as {
+      error?: { message?: string } | string;
+      model?: unknown;
+      usage?: { prompt_tokens?: unknown; completion_tokens?: unknown };
+      choices?: Array<{
+        delta?: { content?: unknown; reasoning_content?: unknown };
+        message?: { content?: unknown };
+        finish_reason?: string | null;
+      }>;
+    };
+    if (ev?.error) {
+      const msg = typeof ev.error === "string" ? ev.error : ev.error.message ?? JSON.stringify(ev.error);
+      throw new AcceptedThenFailedError(`upstream error mid-stream: ${msg}`, this.result().text);
+    }
+    if (typeof ev?.model === "string" && ev.model) this.servedModel = ev.model;
+    const u = ev?.usage;
+    if (u && typeof u.prompt_tokens === "number" && typeof u.completion_tokens === "number") {
+      this.usage = { promptTokens: u.prompt_tokens, completionTokens: u.completion_tokens };
+    }
+    const choice = ev?.choices?.[0];
+    // Some providers put the final text in `message` on the last chunk
+    // instead of a delta; treat both, delta first.
+    const content = choice?.delta?.content ?? choice?.message?.content;
+    if (typeof content === "string") this.text += content;
+    const rc = choice?.delta?.reasoning_content;
+    if (typeof rc === "string") this.reasoning += rc;
+    if (choice?.finish_reason) this.finishReason = choice.finish_reason;
+  }
+
+  result(): Omit<ChatOutcome, "settledUsd"> {
+    return { text: this.text || this.reasoning, finishReason: this.finishReason, servedModel: this.servedModel, usage: this.usage };
+  }
+}
+
+/**
+ * Assemble the complete reply from an OpenAI-compatible SSE body.
+ *
+ * A JSON parse failure on a single data line skips that line; SSE comment/
+ * keepalive lines (":…") and blank lines are ignored by the data: filter.
  *
  * Exported for tests.
  */
 export async function assembleSseChatStream(
   resp: { body: ReadableStream<Uint8Array> | null },
   idleTimeoutMs = 120_000,
-): Promise<{ text: string; finishReason: string | null }> {
-  if (!resp.body) throw new Error("streaming response had no body");
+): Promise<Omit<ChatOutcome, "settledUsd">> {
+  if (!resp.body) throw new AcceptedThenFailedError("streaming response had no body");
   const reader = resp.body.getReader();
   const decoder = new TextDecoder();
+  const acc = new ChatAccumulator();
   let buffer = "";
-  let text = "";
-  let reasoning = "";
-  let finishReason: string | null = null;
-
-  const finish = () => ({ text: text || reasoning, finishReason });
 
   try {
     for (;;) {
-      const chunk = await readWithIdleTimeout(reader, idleTimeoutMs);
-      if (chunk.done) return finish();
+      const chunk = await withIdleTimeout(() => reader.read(), idleTimeoutMs);
+      if (chunk.done) return acc.result();
       buffer += decoder.decode(chunk.value, { stream: true });
       let nl: number;
       while ((nl = buffer.indexOf("\n")) !== -1) {
@@ -92,33 +204,14 @@ export async function assembleSseChatStream(
         buffer = buffer.slice(nl + 1);
         if (!line.startsWith("data:")) continue;
         const payload = line.slice(5).trim();
-        if (payload === "[DONE]") return finish();
+        if (payload === "[DONE]") return acc.result();
         let event: unknown;
         try {
           event = JSON.parse(payload);
         } catch {
           continue; // malformed single line — never abandon the whole stream for it
         }
-        const ev = event as {
-          error?: { message?: string } | string;
-          choices?: Array<{
-            delta?: { content?: unknown; reasoning_content?: unknown };
-            message?: { content?: unknown };
-            finish_reason?: string | null;
-          }>;
-        };
-        if (ev?.error) {
-          const msg = typeof ev.error === "string" ? ev.error : ev.error.message ?? JSON.stringify(ev.error);
-          throw new Error(`upstream error mid-stream: ${msg}`);
-        }
-        const choice = ev?.choices?.[0];
-        // Some providers put the final text in `message` on the last chunk
-        // instead of a delta; treat both, delta first.
-        const content = choice?.delta?.content ?? choice?.message?.content;
-        if (typeof content === "string") text += content;
-        const rc = choice?.delta?.reasoning_content;
-        if (typeof rc === "string") reasoning += rc;
-        if (choice?.finish_reason) finishReason = choice.finish_reason;
+        acc.fold(event);
       }
     }
   } catch (err) {
@@ -129,37 +222,267 @@ export async function assembleSseChatStream(
 }
 
 /**
- * Streamed equivalent of `client.chat(...)` / `client.chatCompletion(...)`:
- * returns the assembled reply text. The caller decides WHEN to stream
- * (paid EVM paths); this decides HOW.
+ * The same assembly over already-decoded frames — what SolanaLLMClient.stream()
+ * yields. The SDK's generator has no idle guard of its own (its fetch deadline
+ * ends at the headers, like LLMClient's), so the stall timer wraps each next().
+ *
+ * Exported for tests.
+ */
+export async function assembleChatFrames(
+  frames: AsyncIterator<unknown> | AsyncIterable<unknown>,
+  idleTimeoutMs = 120_000,
+  acc = new ChatAccumulator(),
+): Promise<Omit<ChatOutcome, "settledUsd">> {
+  const it: AsyncIterator<unknown> = Symbol.asyncIterator in (frames as object)
+    ? (frames as AsyncIterable<unknown>)[Symbol.asyncIterator]()
+    : (frames as AsyncIterator<unknown>);
+  try {
+    for (;;) {
+      const next = await withIdleTimeout(() => it.next(), idleTimeoutMs);
+      if (next.done) return acc.result();
+      acc.fold(next.value);
+    }
+  } catch (err) {
+    // Ask the generator to finish so the SDK releases its reader lock. NOT
+    // awaited: a generator suspended inside `await reader.read()` (the stall
+    // case) only honours return() once that read resolves, which is never —
+    // awaiting it here would turn the stall guard back into a hang.
+    void it.return?.(undefined).catch(() => undefined);
+    throw err;
+  }
+}
+
+/**
+ * Reasoning models stream their hidden thinking as empty-content keepalive
+ * chunks, and those tokens COUNT toward max_tokens. A hard task with a small
+ * budget can burn the whole budget reasoning and emit zero visible text —
+ * finish_reason "length" with an empty answer (measured live: kimi-k3,
+ * 4000 max_tokens, 125s of keepalives, 0 chars). Returning "" would be
+ * indistinguishable from success; say what happened and what to change.
+ */
+function rejectEmptyLength(model: string, out: Omit<ChatOutcome, "settledUsd">): void {
+  if (!out.text && out.finishReason === "length") {
+    throw new AcceptedThenFailedError(
+      `${model} spent the entire max_tokens budget on internal reasoning and produced no visible answer. ` +
+      `Raise max_tokens (reasoning tokens count against it) or simplify the request.`,
+    );
+  }
+}
+
+/**
+ * Anything thrown once a 2xx is in hand is a post-acceptance failure, whatever
+ * its type: a body-read error, a JSON parse error on a non-SSE answer, the
+ * assembler's own throws. Wrap it so the caller can tell it from a refusal.
+ */
+async function afterAccept<T>(run: () => Promise<T>): Promise<T> {
+  try {
+    return await run();
+  } catch (err) {
+    if (err instanceof AcceptedThenFailedError) throw err;
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new AcceptedThenFailedError(msg, "", { cause: err });
+  }
+}
+
+/**
+ * Streamed equivalent of `client.chat(...)` / `client.chatCompletion(...)` over
+ * LLMClient: returns the assembled reply plus what the gateway said about it.
+ * The caller decides WHEN to stream; this decides HOW.
  */
 export async function streamChatText(
-  client: ApiClient & { chatCompletionStream: (model: string, messages: unknown, options?: unknown) => Promise<Response> },
+  client: StreamingClient,
   model: string,
   messages: StreamChatMessage[],
   options: StreamChatOptions,
-): Promise<string> {
+  idleTimeoutMs?: number,
+): Promise<ChatOutcome> {
+  // The SDK throws on any non-OK response before returning, so a Response here
+  // IS the acceptance — money has moved (wallet) or will be billed (account).
   const resp = await client.chatCompletionStream(model, messages, options);
-  // A provider/route that ignores `stream:true` answers with a plain JSON
-  // completion. Feeding that to the SSE parser would "succeed" with an empty
-  // string — the silent-truncation failure shape this module must never add.
-  const contentType = (resp.headers?.get?.("content-type") ?? "").toLowerCase();
-  if (!contentType.includes("text/event-stream")) {
-    const data = (await resp.json()) as { choices?: Array<{ message?: { content?: string } }> };
-    return data.choices?.[0]?.message?.content ?? "";
+  const settledUsd = settledCostFromHeaders(resp.headers);
+  return afterAccept(async () => {
+    // A provider/route that ignores `stream:true` answers with a plain JSON
+    // completion. Feeding that to the SSE parser would "succeed" with an empty
+    // string — the silent-truncation failure shape this module must never add.
+    const contentType = (resp.headers?.get?.("content-type") ?? "").toLowerCase();
+    if (!contentType.includes("text/event-stream")) {
+      const data = await resp.json();
+      const acc = new ChatAccumulator();
+      acc.fold(data);
+      const out = acc.result();
+      rejectEmptyLength(model, out);
+      return { ...out, settledUsd };
+    }
+    const out = await assembleSseChatStream(resp, idleTimeoutMs);
+    rejectEmptyLength(model, out);
+    return { ...out, settledUsd };
+  });
+}
+
+/**
+ * One chat call, whichever client this is, as a ChatOutcome.
+ *
+ * - LLMClient (Base wallet, account rail): chatCompletionStream when `stream`.
+ * - SolanaLLMClient: stream("/v1/chat/completions", { …, stream: true }) when
+ *   `stream` — settlement is recorded before the first frame, so the idle guard
+ *   and the post-acceptance class apply exactly as on Base.
+ * - Otherwise, or when `stream` is false (the free tier, whose short per-model
+ *   timeout the deadline loop depends on): the non-streaming chatCompletion,
+ *   whose parsed body still carries `model`, `finish_reason` and `usage`.
+ */
+export async function completeChat(
+  client: ApiClient,
+  model: string,
+  messages: StreamChatMessage[],
+  options: StreamChatOptions,
+  opts: { stream: boolean; idleTimeoutMs?: number },
+): Promise<ChatOutcome> {
+  if (opts.stream && supportsStreaming(client)) {
+    return streamChatText(client, model, messages, options, opts.idleTimeoutMs);
   }
-  const { text, finishReason } = await assembleSseChatStream(resp);
-  // Reasoning models stream their hidden thinking as empty-content keepalive
-  // chunks, and those tokens COUNT toward max_tokens. A hard task with a small
-  // budget can burn the whole budget reasoning and emit zero visible text —
-  // finish_reason "length" with an empty answer (measured live: kimi-k3,
-  // 4000 max_tokens, 125s of keepalives, 0 chars). Returning "" would be
-  // indistinguishable from success; say what happened and what to change.
-  if (!text && finishReason === "length") {
-    throw new Error(
-      `${model} spent the entire max_tokens budget on internal reasoning and produced no visible answer. ` +
-      `Raise max_tokens (reasoning tokens count against it) or simplify the request.`,
-    );
+  if (opts.stream && supportsFrameStreaming(client)) {
+    // The SDK does not inject stream:true ("silently rewriting a caller's body
+    // is how you end up debugging a request you did not send"); the body is
+    // the same shape LLMClient.chatCompletionStream builds.
+    const body: Record<string, unknown> = { model, messages, max_tokens: options.maxTokens ?? 1024, stream: true };
+    if (options.temperature !== undefined) body.temperature = options.temperature;
+    if (options.responseFormat !== undefined) body.response_format = options.responseFormat;
+    if (options.stop !== undefined) body.stop = options.stop;
+    const gen = client.stream("/v1/chat/completions", body);
+    // openPaidStream pays and records the settlement before the first frame is
+    // handed out, so the very first next() is where a pre-acceptance throw
+    // (unpaid 4xx, refused payment, the SDK's abort on the paid retry) surfaces
+    // — outside afterAccept, unwrapped, for settlementOnThrow to read. A STALL
+    // waiting for that first frame is the one case this module cannot place:
+    // the paid request may still be in flight (payment sent, no verdict) or
+    // the 200 may be in and the upstream silent. Either way the counter says
+    // what was recorded, so it is rethrown as a plain timeout — "unknown" to
+    // the classifier, which books the reserve — rather than as accepted.
+    const first = await withIdleTimeout(() => gen.next(), opts.idleTimeoutMs ?? 120_000).catch((err: unknown) => {
+      if (err instanceof AcceptedThenFailedError) throw new Error(`timeout: ${err.message}, before the first frame`, { cause: err });
+      throw err;
+    });
+    return afterAccept(async () => {
+      const acc = new ChatAccumulator();
+      if (!first.done) acc.fold(first.value);
+      const out = first.done ? acc.result() : await assembleChatFrames(gen, opts.idleTimeoutMs, acc);
+      rejectEmptyLength(model, out);
+      return { ...out, settledUsd: null };
+    });
   }
-  return text;
+  const r = await client.chatCompletion(model, messages as unknown as Parameters<ApiClient["chatCompletion"]>[1], options);
+  return afterAccept(async () => {
+    const acc = new ChatAccumulator();
+    acc.fold(r);
+    const out = acc.result();
+    rejectEmptyLength(model, out);
+    return { ...out, settledUsd: null };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Did money move? — classifying a chat call that THREW
+// ---------------------------------------------------------------------------
+
+/**
+ * "none":    nothing was accepted, so nothing was charged — book $0, and a
+ *            fallback loop may go on to the next model.
+ * "unknown": a payment was signed and sent (wallet) or the request reached
+ *            the gateway (account) and no verdict came back — a timeout on the
+ *            paid retry, an edge 502/504/52x, a reset mid-flight. The gateway
+ *            settles those after the client has given up. Book the reserve as a
+ *            precaution and never pay a second model for the same call.
+ * "settled": the gateway answered 2xx and the failure came after — the charge
+ *            is certain (AcceptedThenFailedError).
+ */
+export type SettlementVerdict = "none" | "unknown" | "settled";
+
+// Statuses an edge or a load balancer returns when the ORIGIN did not answer in
+// time — the origin may still be running the request and settle it afterwards
+// (the Cloud Run route documents that a client disconnect is never propagated
+// to a non-streaming handler). Everything else in the 4xx/5xx range is the
+// gateway itself answering, which it does before settlement starts.
+const ORIGIN_DID_NOT_ANSWER = new Set([408, 502, 504, 520, 521, 522, 523, 524, 525, 526, 527, 529, 530]);
+
+// A fetch rejection that proves the request never left this machine.
+const NEVER_CONNECTED = new Set(["ENOTFOUND", "EAI_AGAIN", "ECONNREFUSED", "ENETUNREACH", "EHOSTUNREACH", "EADDRNOTAVAIL"]);
+
+// Transport failures where the request may have been in flight when it died.
+const IN_FLIGHT_TRANSPORT = /aborted|timeout|timed out|fetch failed|socket hang up|ECONNRESET|ETIMEDOUT|EPIPE|terminated|network/i;
+
+function statusOf(error: unknown): number | undefined {
+  const e = error as { statusCode?: unknown; status?: unknown } | undefined;
+  if (typeof e?.statusCode === "number") return e.statusCode; // @blockrun/llm APIError
+  if (typeof e?.status === "number") return e.status; // @anthropic-ai/sdk APIError
+  return undefined;
+}
+
+function messageOf(error: unknown): string {
+  if (error instanceof Error) {
+    const cause = (error as { cause?: unknown }).cause;
+    const causeMsg = cause instanceof Error ? cause.message : typeof cause === "string" ? cause : "";
+    return `${error.message} ${causeMsg}`;
+  }
+  return String(error);
+}
+
+export function settlementOnThrow(
+  error: unknown,
+  opts: {
+    rail: "wallet" | "account";
+    estimateUsd: number;
+    /**
+     * The native claude-* path: @blockrun/llm's AnthropicClient pays the 402
+     * INSIDE its fetch, so the status the SDK surfaces is already the paid
+     * retry's — there is no "after payment" prefix to read. A 4xx there is the
+     * gateway's refusal before settlement (its /v1/messages route passes 4xx
+     * through and does not settle); anything the origin did not answer, or a
+     * 5xx, may have settled.
+     */
+    transparentPayment?: boolean;
+  },
+): SettlementVerdict {
+  // A $0 estimate is a free model: whatever happened, it cannot have cost
+  // anything, and mode:"free" must keep walking its candidates.
+  if (!(opts.estimateUsd > 0)) return "none";
+  if (error instanceof AcceptedThenFailedError) return "settled";
+
+  const name = (error as { name?: unknown } | undefined)?.name;
+  const msg = messageOf(error);
+  const lower = msg.toLowerCase();
+
+  // The wallet could not or would not pay: the SDK's PaymentError, or the same
+  // sentence surfaced through the Anthropic SDK's connection-error wrapper.
+  if (name === "PaymentError" || /payment was rejected|no payment requirements|insufficient|check your .*balance/i.test(msg)) return "none";
+  // Refused by this process before anything was sent.
+  if (name === "BudgetExceededError" || name === "QuoteMismatchError") return "none";
+
+  const cause = (error as { cause?: { code?: unknown } } | undefined)?.cause;
+  if (typeof cause?.code === "string" && NEVER_CONNECTED.has(cause.code)) return "none";
+
+  const status = statusOf(error);
+  if (status !== undefined) {
+    if (opts.rail === "wallet") {
+      // "API error: N" is the UNPAID first response — the gateway wants a
+      // payment it never got, or refused the request outright. No money.
+      // "API error after payment: N" is the paid retry: a 4xx there is the
+      // gateway's own refusal before settlement starts (its streaming route
+      // says so in as many words); an edge timeout may hide a settle.
+      if (!opts.transparentPayment && !lower.includes("after payment")) return "none";
+      return ORIGIN_DID_NOT_ANSWER.has(status) ? "unknown" : status >= 500 ? "unknown" : "none";
+    }
+    // Account rail: every non-OK first response throws with its status before
+    // any body exists — 400 unknown model, 401, 402 out of credit, 429 — and
+    // none of those is billed. Only an origin that did not answer is ambiguous.
+    return ORIGIN_DID_NOT_ANSWER.has(status) ? "unknown" : "none";
+  }
+
+  // No status: a transport failure. Before headers on a paid call the payment
+  // has already been signed and sent (the unpaid 402 comes back in
+  // milliseconds; the paid retry is the one that runs long), so an abort here
+  // is exactly the settle-after-disconnect shape. Anything else without a
+  // status — an SDK validation throw, a programming error — never reached
+  // the wire.
+  if (name === "AbortError" || IN_FLIGHT_TRANSPORT.test(msg)) return "unknown";
+  return "none";
 }
diff --git a/src/utils/constants.ts b/src/utils/constants.ts
index f4191c6..0e8551a 100644
--- a/src/utils/constants.ts
+++ b/src/utils/constants.ts
@@ -89,7 +89,9 @@ export const BASE_RPC_URLS = [
 //   nemotron-nano-12b-v2-vl (vision).
 //   Also live but UNLISTED (hidden from GET /v1/models, still served): gpt-oss-120b
 //   — the gateway's own free fallback — and gpt-oss-20b (both re-probed
-//   2026-08-12, ~0.6-2.5s, serving themselves).
+//   2026-08-12, ~0.6-2.5s, serving themselves). NO LONGER TRUE OF 120b: the
+//   2026-09-13 sweep saw it answer as nano-omni on Base and 3.5-lightning on
+//   Solana — see the free[] note; 20b still serves itself on both.
 //   DEAD SINCE THE JULY SWEEP, removed 2026-08-12: deepseek-v4-flash and
 //   seed-oss-36b now report `"model": "nvidia/gpt-oss-120b"` on BOTH chains —
 //   the aliasing trap from the note above, caught again. Keeping them routed
@@ -134,8 +136,11 @@ export const MODEL_TIERS = {
   // it is the single most load-bearing free model there is. Re-probed 2026-07-21
   // on BOTH chains with a realistic ~1.5K-token prompt: gpt-oss-120b 3.5s,
   // gpt-oss-20b 3.7s; re-confirmed 2026-08-12 (0.6-2.5s, serving themselves).
-  // Absence from the public catalogue is a listing decision, not a health
-  // signal — check the behaviour. But the 2026-08-12 sweep also showed the
+  // (Since 2026-09-13 gpt-oss-120b is on the OTHER side of that line — the
+  // alias target became an alias — which is why it left the tier. Its bare
+  // spelling stays in the tool description as the example free id; it is
+  // still $0.) Absence from the public catalogue is a listing decision, not a
+  // health signal — check the behaviour. But the 2026-08-12 sweep also showed the
   // CONVERSE playing out: two other delisted entries (deepseek-v4-flash,
   // seed-oss-36b) turned out to be alias-dead, not hidden-alive. Delisting
   // tells you NOTHING either way; only the response's `model` field does.
@@ -148,25 +153,44 @@ export const MODEL_TIERS = {
   // is the trap the gateway's own probe script added a --real mode for. Never
   // health-check a free model with a 16-token ping.
   //
-  // 2026-09-08 order, three bands, from the live catalogue (listing evidence
-  // only — see the NVIDIA note above for what was and was not probed):
-  //   1. gpt-oss-120b — hidden-alive, the gateway's own free fallback; and
-  //      nemotron-3-nano-omni — listed, available, served itself on 2026-08-12.
-  //   2. Listed billing_mode:"free" on BOTH chains and available: the two new
-  //      NVIDIA entries and the first two non-NVIDIA free models. Unprobed for
-  //      latency, so they sit behind the proven pair, not ahead of it.
-  //   3. The four delisted entries. Delisting tells you nothing either way;
-  //      each is bounded by FREE_MODEL_TIMEOUT_MS and the loop by
-  //      FREE_TIER_DEADLINE_MS, so a dead tail costs time, never money.
-  //      Remove them only on a POST probe that shows aliasing or a crawl.
-  // Skipped on purpose: nemotron-3.5-lightning (available:false on Base),
-  // muse-glimmer-30b and gemma-4-31b (Solana catalogue only) — routing has to
-  // hold on both chains. They are still in FREE_CHAT_MODELS, so an explicit
-  // call to one reserves $0 like any other free id.
+  // 2026-09-13 SWEEP — the realistic-prompt POST probe the 09-08 note asked
+  // for: ~3,000 characters, max_tokens 32, no payment header, both gateways,
+  // the response's `model` field read on every 200. It found the tier was
+  // mostly ALIASES: six of the eleven routed ids answered as another model on
+  // BOTH chains —
+  //     gpt-oss-120b          -> nemotron-3-nano-omni (Base, 6.4s) / nemotron-3.5-lightning (sol, 21.9s)
+  //     nemotron-3-ultra-550b -> nemotron-3-super-120b (Base) / nemotron-3.5-lightning (sol, 63.9s)
+  //     step-3.7-flash        -> nemotron-3-super-120b (Base) / no answer in 90s (sol)
+  //     mistral-nemotron      -> nemotron-3-nano-omni (Base) / nemotron-3-super-120b (sol)
+  //     nemotron-nano-12b-v2-vl, nemotron-nano-9b-v2 -> nano-omni on both
+  // — and the TARGET moves between probes (the 09-13 finder saw gpt-oss-120b
+  // land on nemotron-3-super-120b hours earlier). "The gateway's own free
+  // fallback serves itself", the premise free[0] rested on since July, is
+  // gone: the fallback now serves whatever has capacity. So the tier walked
+  // the same saturated backend under five names inside the 150s deadline and
+  // reported "did not answer" having tried ONE model. Removed, per this list's
+  // own rule (a POST probe that shows aliasing). They stay in FREE_CHAT_MODELS:
+  // still $0, and an explicit call must still reserve nothing.
+  //
+  // What is left is every id that echoed ITS OWN NAME on both chains, fastest
+  // first — distinct backends, which is the only thing a fallback rung is for:
+  //   gpt-oss-20b (0.7s sol / 1.7s Base), north-mini-code (1.0s / 3.0s),
+  //   nemotron-3-nano-omni (2.3s as "…-nim" on sol / 3.6s), then two that
+  //   served themselves on Solana and were merely unavailable on Base that day
+  //   (laguna-xs-2.1: 429 "capacity exhausted" on Base, 0.7s on sol;
+  //   llama-3.2-11b-vision: no answer in 90s on Base, 9.8s on sol) — last, so
+  //   a bad day on one chain costs the loop time at the tail, never at the head.
+  // Since audit round 3 the reply names the served model whenever it differs
+  // from the requested id (see chat.ts servedNotes), so the next alias is
+  // visible in the tool output instead of in a sweep months later.
+  //
+  // Skipped on purpose: nemotron-3.5-lightning (429 on Base, no answer on
+  // sol), muse-glimmer-30b and gemma-4-31b (400 "Unknown model" on Base;
+  // gemma crawled 79.8s on sol) — routing has to hold on both chains. They are
+  // still in FREE_CHAT_MODELS, so an explicit call to one reserves $0.
   free: [
-    "nvidia/gpt-oss-120b", "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning",
-    "nvidia/llama-3.2-11b-vision", "nvidia/nemotron-3-ultra-550b", "cohere/north-mini-code", "poolside/laguna-xs-2.1",
-    "nvidia/step-3.7-flash", "nvidia/mistral-nemotron", "nvidia/gpt-oss-20b", "nvidia/nemotron-nano-12b-v2-vl", "nvidia/nemotron-nano-9b-v2",
+    "nvidia/gpt-oss-20b", "cohere/north-mini-code", "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning",
+    "poolside/laguna-xs-2.1", "nvidia/llama-3.2-11b-vision",
   ],
   coding: ["anthropic/claude-opus-5", "openai/gpt-5.3-codex", "moonshot/kimi-k3", "xai/grok-build-0.1", "zai/glm-5.2", "qwen/qwen3.7-max", "anthropic/claude-sonnet-5"],
   glm: ["zai/glm-5", "zai/glm-5.2", "zai/glm-5.1", "zai/glm-5-turbo"],
@@ -189,7 +213,16 @@ export type RoutingMode = keyof typeof MODEL_TIERS;
  * The dangerous direction is the other one: a member that STARTS costing money
  * gets a $0 reserve for a paid call, which is the total gate bypass this file
  * spends so many words preventing. So `npm run verify:prices` checks every
- * member against the live catalogue and fails if one is priced. A Set needs no
+ * member the CATALOGUE REPORTS against its live price and fails if one is
+ * priced — including one marked unavailable, since "retired today" does not
+ * promise "still free when it returns".
+ *
+ * What that check cannot cover, and does not pretend to: a member the catalogue
+ * does not list at all. Six of these are in that state on both gateways today,
+ * and delisting is not death — gpt-oss-120b is the gateway's own free fallback
+ * and answers for itself while absent from GET /v1/models. The sweep names each
+ * one as UNVERIFIED rather than counting it as checked; the only way to settle
+ * one is a realistic POST, which costs a call and so is a human's decision. A Set needs no
  * hasOwn guard — there are no prototype keys to leak through `.has`.
  *
  * Not every member is routed: MODEL_TIERS.free wants a both-chain, latency-
@@ -197,10 +230,19 @@ export type RoutingMode = keyof typeof MODEL_TIERS;
  */
 export const FREE_CHAT_MODELS: ReadonlySet<string> = new Set<string>([
   ...MODEL_TIERS.free,
+  // Still $0 on both gateways (200 without a payment header, 2026-09-13) but
+  // answering as ANOTHER model — pulled from the routing tier, kept here so an
+  // explicit call reserves $0. See the free[] sweep note.
+  "nvidia/gpt-oss-120b",
+  "nvidia/nemotron-3-ultra-550b",
+  "nvidia/step-3.7-flash",
+  "nvidia/mistral-nemotron",
+  "nvidia/nemotron-nano-12b-v2-vl",
+  "nvidia/nemotron-nano-9b-v2",
   // Live billing_mode:"free" on 2026-09-08 but deliberately not routed.
-  "nvidia/nemotron-3.5-lightning", // available:false on Base that day
-  "nvidia/muse-glimmer-30b", // Solana catalogue only
-  "nvidia/gemma-4-31b", // Solana catalogue only
+  "nvidia/nemotron-3.5-lightning", // 429 capacity on Base, no answer on sol (09-13)
+  "nvidia/muse-glimmer-30b", // Solana catalogue only (400 on Base)
+  "nvidia/gemma-4-31b", // Solana catalogue only (400 on Base; 79.8s crawl on sol)
 ]);
 
 /**
@@ -255,6 +297,15 @@ export const CHAT_PRICE_PER_MTOKEN: Record<string, { input: number; output: numb
   "openai/gpt-6-astra": { input: 10, output: 50 },
   "anthropic/claude-fable-5.1": { input: 10, output: 50 },
   "anthropic/claude-fable-5": { input: 10, output: 50 },
+  // Hidden from every /v1/models listing but still SERVED, and the rails do
+  // not agree on what it costs: the account rail bills it from the public
+  // sheet at $15/$75 (blockrun.ai/api/pricing, hidden:true, available:true —
+  // the 2026-09-15 catalogue sweep caught it reserving the $5/$30 default),
+  // while both wallet gateways alias the request onto Opus 4.8 and quote
+  // $5/$25 (unpaid POST 2026-09-15: "Claude Opus 4.8 API call"). The reserve
+  // has to cover the dearer rail; the native ledger keys on the SERVED id
+  // (catalogueKeyForEcho), so the wallet rails still book the 4.8 rate.
+  "anthropic/claude-opus-4": { input: 15, output: 75 },
   // At or below the default — listed so the CHEAP tiers reserve their own real
   // rate instead of the $5/$30 worst case, which would price a qwen3.7-flash
   // call like a frontier one and lock small budgets out of the cheap path.
diff --git a/src/utils/errors.ts b/src/utils/errors.ts
index 9c6b2b1..5973aa9 100644
--- a/src/utils/errors.ts
+++ b/src/utils/errors.ts
@@ -1,4 +1,14 @@
 import { getChain } from "./wallet.js";
+import { isApiKeyMode } from "./auth.js";
+import { isExplicitlyUncharged } from "./uncharged.js";
+export { isExplicitlyUncharged };
+
+// Literals rather than PORTAL_CREDITS_URL / PORTAL_ACTIVITY_URL: every handler
+// test that mocks utils/auth.js lists its named exports by hand, and the one
+// name this module cannot do without is isApiKeyMode (in-flight.ts and
+// api-key-call.ts spell their URLs out for the same reason).
+const ACCOUNT_CREDITS_URL = "https://user.blockrun.ai/dashboard/credits";
+const ACCOUNT_ACTIVITY_URL = "https://user.blockrun.ai/dashboard/activity";
 
 /**
  * Pulls a useful message out of any thrown value. For SDK APIError, surfaces
@@ -55,6 +65,23 @@ export function isPaymentRejectionError(message: string): boolean {
   return m.includes("insufficient") || m.includes("balance") || m.includes("rejected");
 }
 
+/**
+ * Where a status code is allowed to END.
+ *
+ * End of string, or a character that is neither a digit nor a dot — that much
+ * is what keeps "$402.50" and "$1.4020" from reading as status codes, and it is
+ * load-bearing (both are pinned by tests).
+ *
+ * The third alternative is the fix for a real gap: the SDK's ACCOUNT client
+ * writes `BlockRun account API error: 502.` with a sentence-ending period
+ * (@blockrun/llm dist/index.js, `${response.status}.${hint}`), and a dot was
+ * excluded outright — so every account-rail 5xx fell through unclassified and
+ * the caller got no guidance at all, while the identical wallet-rail message
+ * ("API error: 502") got it. A dot NOT followed by a digit is punctuation; a
+ * dot followed by a digit is a decimal point and still disqualifies.
+ */
+const STATUS_END = "(?:$|[^0-9.]|\\.(?!\\d))";
+
 /**
  * True when `message` carries a 5xx that READS as an HTTP status. A bare
  * three-digit match is far too loose: LLM errors are full of incidental
@@ -69,7 +96,7 @@ export function hasLabelledServerStatus(message: string): boolean {
   const m = message.toLowerCase();
   // "payment" is a label too: the SDK's post-402 prefix is "API error after
   // payment: 502", where the word before the number is "payment", not "error".
-  return /(?:status(?:\s*code)?|http|error|payment)\s*[:=]?\s*5[0-9]{2}(?:$|[^0-9.])/.test(m) ||
+  return new RegExp(`(?:status(?:\\s*code)?|http|error|payment)\\s*[:=]?\\s*5[0-9]{2}${STATUS_END}`).test(m) ||
     /(?:^|[^0-9.])5[0-9]{2}:?\s+(?:internal|server error|bad gateway|service unavailable|gateway time)/.test(m);
 }
 
@@ -79,27 +106,43 @@ export function hasLabelledServerStatus(message: string): boolean {
  * payment/balance). `opts.altModels` lets a tool suggest a SAME-DOMAIN fallback
  * (e.g. video → "bytedance/seedance-2.0") instead of a generic, often-wrong
  * cross-domain one — omit it and no specific model is named.
+ *
+ * `opts.afterPayment` is the caller saying "a request carrying the payment
+ * (a signature, or the account Bearer) had already been sent when this was
+ * thrown". The formatter can read that from the SDK's "API error after
+ * payment" prefix, but an abort or a dropped socket arrives as a bare
+ * "This operation was aborted" / "fetch failed" with no such prefix, and the
+ * text alone cannot tell a paid retry from an unpaid quote probe. Pass it from
+ * a tracker (utils/in-flight.ts `paid.outstanding`) or from settlementOnThrow's
+ * "unknown" verdict; never guess it.
  */
-export function formatError(message: string, opts?: { altModels?: string }): string {
+export function formatError(message: string, opts?: { altModels?: string; afterPayment?: boolean }): string {
   const msgLower = message.toLowerCase();
 
   // Match HTTP status codes as standalone tokens, not substrings — "max 5000
   // characters", "$1.4020", or "$402.50" must not classify as 500/402 errors.
   // The trailing boundary excludes a following digit AND a following dot, so the
   // integer part of a decimal amount ($402.50) is not misread as a status code.
-  const hasStatus = (code: string) => new RegExp(`(^|[^0-9.])${code}($|[^0-9.])`).test(msgLower);
+  const hasStatus = (code: string) => new RegExp(`(^|[^0-9.])${code}${STATUS_END}`).test(msgLower);
 
   const isPostPaymentClientError = msgLower.includes("api error after payment") &&
     /(^|[^0-9.])4[0-9]{2}($|[^0-9.])/.test(msgLower);
-  const explicitlyUncharged =
-    msgLower.includes("no payment was made") ||
-    msgLower.includes("no charge was made") ||
-    msgLower.includes("not charged");
-  const isPaymentError = !isPostPaymentClientError && (
+  const explicitlyUncharged = isExplicitlyUncharged(message);
+  // …and it gates the WHOLE funding branch, not just the "payment" keyword.
+  // It used to gate only that sub-clause, so a message carrying a bare 402, the
+  // word "balance", or "insufficient" still earned "your wallet needs funding"
+  // while saying in the same breath that nothing was charged. Two of this
+  // repo's own messages did exactly that: the video tool's unreadable-quote
+  // refusal ("Refusing to sign a payment for an amount that could not be
+  // validated — no charge was made") matched the bare 402 and told a wallet
+  // holding $1,000 to top up, and RealFace's "No payment taken" was not even in
+  // the marker list. Telling someone to fund a wallet that was never debited is
+  // the same class of wrong as #132, pointed the other way.
+  const isPaymentError = !isPostPaymentClientError && !explicitlyUncharged && (
     hasStatus("402") ||
     msgLower.includes("balance") ||
     msgLower.includes("insufficient") ||
-    (msgLower.includes("payment") && !hasStatus("500") && !explicitlyUncharged)
+    (msgLower.includes("payment") && !hasStatus("500"))
   );
 
   // Upstream model/provider availability, e.g. token360 returns
@@ -133,10 +176,34 @@ export function formatError(message: string, opts?: { altModels?: string }): str
   // gateway settled and then upstream refused, and this formatter has no
   // endpoint context to know whether the nonce was released.
   const isNotServed =
-    /(?:status(?:\s*code)?|http|error|payment)\s*[:=]?\s*501(?:$|[^0-9.])/.test(msgLower) ||
+    new RegExp(`(?:status(?:\\s*code)?|http|error|payment)\\s*[:=]?\\s*501${STATUS_END}`).test(msgLower) ||
     /(?:^|[^0-9.])501:?\s+not implemented/.test(msgLower);
   const isNotServedPrePayment = isNotServed && !msgLower.includes("api error after payment");
 
+  // Had a request CARRYING THE PAYMENT already left the machine when this was
+  // thrown? On the wallet rails the SDK says so in the prefix of every failure
+  // on its paid retry. On the account rail the credential rides every request,
+  // so any answer from the gateway is "after payment" by construction — the
+  // 4xx refusals are excluded below because the gateway answers those before
+  // billing. A caller that watched the wire can also say so (`afterPayment`).
+  const afterPayment = opts?.afterPayment === true ||
+    msgLower.includes("api error after payment") ||
+    (isApiKeyMode() && has5xxStatus);
+  // No status, no prefix, no verdict: the request went out and nothing came
+  // back. Same shape settlementOnThrow (chat-stream.ts) classifies as "unknown"
+  // — an abort of the paid retry, an idle timeout, a socket reset mid-flight.
+  const isTransportFailure =
+    /aborted|timed out|timeout|fetch failed|socket hang up|econnreset|etimedout|epipe|terminated/.test(msgLower);
+  // The one sentence this branch exists for. The gateway's catch-all 500 does
+  // not release the payment nonce (settlement ran in the same try), a 504 after
+  // settlement carries no body at all, and a client that aborted the paid retry
+  // never sees the answer — in all three the USDC may be gone. Until audit
+  // round 3 this read as "temporary API issue, try again in a few minutes",
+  // the ledger booked nothing, and the retry paid again (C38). Only the
+  // gateway's own marker (`explicitlyUncharged`) is allowed to overrule it.
+  const mayHaveSettled = afterPayment && !explicitlyUncharged && !isPostPaymentClientError &&
+    (isServerError || (opts?.afterPayment === true && isTransportFailure));
+
   const altHint = opts?.altModels ? ` (e.g. ${opts.altModels})` : "";
   let errorText = `Error: ${message}`;
 
@@ -151,6 +218,22 @@ export function formatError(message: string, opts?: { altModels?: string }): str
       (isNotServedPrePayment
         ? `, and nothing was charged.`
         : `. Check blockrun_wallet action:"report" to see whether this call settled.`);
+  } else if (mayHaveSettled) {
+    // Tested BEFORE the generic outage branch: the retry advice there is the
+    // wrong advice for a call that may already have paid. Say what is known
+    // (the payment went out), what is not (whether it settled), and where to
+    // look — never "nothing was charged" and never "the charge stands".
+    const account = isApiKeyMode();
+    const carrying = account ? "the account key" : "the payment signature";
+    const failure = isServerError
+      ? `The gateway failed AFTER the request carrying ${carrying} was sent, and did not say whether this call was billed`
+      : `No response came back, and the request carrying ${carrying} had already been sent`;
+    const where = account
+      ? `check blockrun_wallet action:"report" and ${ACCOUNT_ACTIVITY_URL}`
+      : `check blockrun_wallet action:"report" and the wallet's recent transactions`;
+    errorText += `\n\n${failure} — the charge MAY have gone through (the gateway settles on its own clock and ` +
+      `does not stop because this client saw an error). Before retrying, ${where}: a retry pays again if it did.` +
+      (opts?.altModels ? ` If it did not, a different model${altHint} may be healthier.` : ``);
   } else if (isServerError) {
     errorText += `\n\nThis is a temporary API issue. The API may be experiencing problems.` +
       `\nTry again in a few minutes` +
@@ -167,12 +250,59 @@ export function formatError(message: string, opts?: { altModels?: string }): str
       errorText += `\nThe gateway reported that this call was not settled — nothing was charged.`;
     }
   } else if (isPaymentError) {
-    const chain = getChain();
-    const network = chain === "solana" ? "Solana" : "Base";
-    errorText += `\n\nThis error usually means your wallet needs funding.\n` +
-      `Run blockrun_wallet with action: "setup" to get funding instructions.\n\n` +
-      `Quick fix: Send USDC to your wallet on ${network} network.`;
+    // The rail decides what "payment required" means. On the account rail a
+    // 402 is the gateway saying the prepaid credit is gone; there is no wallet
+    // to fund, and telling the agent to run action:"setup" sends it to
+    // requireWalletMode ("unset BLOCKRUN_API_KEY …") — off the rail the user
+    // chose. Tested first so the branch never reaches getChain(), which on an
+    // account-only machine is a session-file/keychain probe for nothing (C28).
+    if (isApiKeyMode()) {
+      errorText += `\n\nYour BlockRun account is out of credit. Top up at ${ACCOUNT_CREDITS_URL} ` +
+        `(the API key stays the same).`;
+    } else {
+      const chain = getChain();
+      const network = chain === "solana" ? "Solana" : "Base";
+      errorText += `\n\nThis error usually means your wallet needs funding.\n` +
+        `Run blockrun_wallet with action: "setup" to get funding instructions.\n\n` +
+        `Quick fix: Send USDC to your wallet on ${network} network.`;
+    }
   }
 
   return errorText;
 }
+
+// The SDK's text for ANY post-payment 402, body discarded (@blockrun/llm
+// dist/index.js, handlePaymentAndRetryRaw). On the Base rail it has two causes
+// the tool cannot tell apart:
+//
+//   - the wallet really was refused (balance, allowance);
+//   - the upstream answered 5xx, the gateway route returned 502 "Payment was
+//     NOT charged" WITHOUT releasing the payment nonce (the pm route releases;
+//     the exa and defillama routes do not — blockrun src/app/api/v1/exa/
+//     [...path]/route.ts and defillama/[...path]/route.ts), the SDK slept 1s
+//     and re-sent the SAME PAYMENT-SIGNATURE, and rejectReplay answered 402
+//     {code: PAYMENT_REPLAY}. Nothing settled.
+//
+// formatError sees "balance" and prescribes funding, so a 30-second upstream
+// blip told a $50 wallet to top up. The Solana client has no 502 retry and the
+// account rail has no nonce, so the ambiguity is Base-only — and so is the
+// hedge: on Base the SDK's words stay (it MAY be a real rejection) with the
+// second reading added; elsewhere the sentence means what it says. The real
+// fix is upstream (release the nonce on 5xx, as pm does) or in the SDK
+// (surface the 402 `code`); this is the honest message until then. Shared so
+// exa and defi cannot drift apart on the wording.
+export const SDK_POST_PAYMENT_REJECTION = "Payment was rejected. Check your wallet balance.";
+
+/**
+ * The Base-only second reading of the SDK's post-payment rejection, or "" when
+ * the message is anything else, the rail is not Base, or the process bills an
+ * account. Append it AFTER formatError's output. `upstream` names the vendor
+ * behind the route ("Exa", "DefiLlama") so the sentence says who failed.
+ */
+export function basePaymentReplayHedge(message: string, upstream: string): string {
+  if (message.trim() !== SDK_POST_PAYMENT_REJECTION) return "";
+  if (isApiKeyMode() || getChain() !== "base") return "";
+  return `\n\nOn Base this exact rejection is also what the gateway returns when ${upstream} itself failed (5xx) and the SDK ` +
+    "re-sent the same payment header: in that case nothing was settled and the wallet was never the problem. " +
+    "Check blockrun_wallet action:\"status\" — if it shows funds, retry the call once before topping up.";
+}
diff --git a/src/utils/in-flight.ts b/src/utils/in-flight.ts
new file mode 100644
index 0000000..07709c2
--- /dev/null
+++ b/src/utils/in-flight.ts
@@ -0,0 +1,227 @@
+// src/utils/in-flight.ts
+//
+// One answer to the one question every paid tool's catch has to ask: when this
+// error was thrown, had a request CARRYING A PAYMENT already left the machine?
+//
+// The gateway settles on its own clock and does not stop because the client
+// disconnected. So a paid POST that never answered is not "no charge": the
+// signature (or the account Bearer) went out, the gateway may well have taken
+// the money and finished the render, and the tool's job is to book that
+// conservatively and say so — the natural next move after a bare "failed" is
+// to run the call again, which pays a second time.
+//
+// 0.50.0 tried to do this with a `paidRequestInFlight` boolean copied into
+// each tool by hand, and every copy was wrong in its own way (audit round 3):
+//
+//   - speech, realface and image cleared the flag in a `.finally()` chained on
+//     the very fetch they were guarding. Promise#finally runs its callback
+//     BEFORE the rejection reaches the awaiting catch, so the catch always
+//     read `false` and the booking branch was unreachable — dead code that
+//     the rail-parity matrix greenlit because the identifier existed;
+//   - speech set it on Base only; image's Base rail never set it;
+//   - realface's flag was module-global, so a concurrent call's outstanding
+//     payment made an unrelated failure book a phantom charge;
+//   - image's Solana branch armed it BEFORE the unpaid 402 probe, so a probe
+//     timeout — nothing signed, nothing sent with a signature — booked a
+//     full render against the cap.
+//
+// This module replaces the flag with a per-call tracker and two rules:
+//
+//   1. arm() only when something has been signed / the paid request is about
+//      to be sent — never around the unpaid quote probe. On Base and the
+//      account rail that is the line before the paid fetch; on Solana the
+//      helper (utils/solana-402.ts) owns the sequence and fires onPaidRequest
+//      the line before the signed request leaves, so tools arm there.
+//   2. settle() the moment a RESPONSE arrives — any status, before it is
+//      inspected. A 402/4xx/5xx that came back is an answer: the gateway told
+//      us what it did, and the catch must not turn it into "may have settled".
+//      A rejection leaves the tracker armed; that is the whole point.
+import type { BudgetState } from "../types.js";
+import { recordActualSpend } from "./budget.js";
+import { isTimeoutError } from "./http.js";
+import { isApiKeyMode } from "./auth.js";
+import { isExplicitlyUncharged } from "./uncharged.js";
+
+// Literal rather than PORTAL_ACTIVITY_URL: every handler test that mocks
+// utils/auth.js lists its named exports by hand, and the one name this module
+// cannot do without is isApiKeyMode. (api-key-call.ts spells the URL out for
+// the same reason.)
+const ACCOUNT_ACTIVITY_URL = "https://user.blockrun.ai/dashboard/activity";
+
+/**
+ * A per-call record of whether a request carrying a payment is outstanding.
+ * Create one per handler invocation (never at module scope — the MCP SDK
+ * dispatches tool calls concurrently) and hand it to whatever performs the
+ * paid request on the active rail.
+ */
+export interface PaidRequest {
+  /**
+   * The paid request is about to be sent (a signature exists, or the Bearer
+   * is on the request). `quotedUsd` is the authoritative 402 amount when the
+   * rail has one; a give-up books it in preference to the caller's estimate.
+   */
+  arm(quotedUsd?: number | null): void;
+  /** A response arrived — whatever its status. The outcome is now known. */
+  settle(): void;
+  /** True between arm() and settle(): the payment MAY have settled server-side. */
+  readonly outstanding: boolean;
+  /** The quote captured at arm() time, if any. */
+  readonly quotedUsd: number | null;
+  /**
+   * True when `err` was thrown while a paid request was outstanding AND the
+   * error is the kind that means "no response was observed" — a timeout, an
+   * abort, a socket that dropped mid-flight. A response that did arrive and
+   * was then rejected by the caller (a 402, an API error) is not this — nor an
+   * error that CARRIES the answer (a status, a typed job verdict, the
+   * gateway's uncharged marker; see isAnswer) — nor a connection that
+   * provably never opened (DNS failed, connection refused), because nothing
+   * could have reached the gateway.
+   */
+  mayHaveSettled(err: unknown): boolean;
+}
+
+/**
+ * Rejection causes that prove the request never left this machine. Mirrors
+ * the set utils/api-key-call.ts uses for the account rail's async submit; a
+ * request that was never accepted by a socket cannot have been billed.
+ */
+const NEVER_CONNECTED = new Set(["ENOTFOUND", "EAI_AGAIN", "ECONNREFUSED", "ENETUNREACH", "EHOSTUNREACH", "EADDRNOTAVAIL"]);
+
+/**
+ * The request went out and nothing came back. undici surfaces every transport
+ * failure as `TypeError: fetch failed` with the real reason in `cause`, so the
+ * cause code is what is classified; fetchWithTimeout's own abort arrives as a
+ * DOMException named AbortError, which isTimeoutError already recognises.
+ */
+function noResponseObserved(err: unknown): boolean {
+  if (isAnswer(err)) return false;
+  const cause = (err as { cause?: { code?: unknown } } | undefined)?.cause;
+  const code = typeof cause?.code === "string" ? cause.code : "";
+  if (NEVER_CONNECTED.has(code)) return false;
+  if (isTimeoutError(err)) return true;
+  if (err instanceof TypeError && /fetch failed/i.test(err.message)) return true;
+  return /^(ECONNRESET|EPIPE|ETIMEDOUT|UND_ERR_)/.test(code);
+}
+
+/**
+ * An error that IS the gateway's answer, thrown by a helper AFTER a response
+ * arrived — so settle() was never reached, but nothing is outstanding.
+ *
+ * sendPaid can only settle when the wrapped call resolves; a helper that
+ * inspects the response and throws on it (apiKeyPost's AccountApiError with
+ * the body text, apiKeyAsyncPost's not_charged terminal failure, the Solana
+ * helper's "API error N:") leaves the tracker armed with an answer in hand.
+ * Until audit round 4 the verdict then fell to isTimeoutError's substring
+ * match on the message, and a not_charged poll whose upstream text read "The
+ * operation was aborted due to timeout" booked a whole render on image's
+ * account rail and said "MAY have gone through" — the C13 shape, on the rail
+ * whose sibling tools had just documented why it must not happen. So the
+ * answer is read off the error, never its prose: a numeric status (the SDK's
+ * APIError.statusCode, AccountApiError, the Anthropic SDK's .status), a typed
+ * job verdict, or the gateway's own uncharged marker.
+ */
+function isAnswer(err: unknown): boolean {
+  const e = err as { statusCode?: unknown; status?: unknown; name?: unknown; message?: unknown } | undefined;
+  if (typeof e?.statusCode === "number" || typeof e?.status === "number") return true;
+  if (e?.name === "JobFailedError" || e?.name === "BilledJobError" || e?.name === "AccountApiError") return true;
+  return typeof e?.message === "string" && isExplicitlyUncharged(e.message);
+}
+
+export function trackPaidRequest(): PaidRequest {
+  let armed = false;
+  let quoted: number | null = null;
+  return {
+    arm(quotedUsd) {
+      armed = true;
+      if (typeof quotedUsd === "number" && Number.isFinite(quotedUsd) && quotedUsd > 0) quoted = quotedUsd;
+    },
+    settle() {
+      armed = false;
+    },
+    get outstanding() {
+      return armed;
+    },
+    get quotedUsd() {
+      return quoted;
+    },
+    mayHaveSettled(err) {
+      return armed && noResponseObserved(err);
+    },
+  };
+}
+
+/**
+ * Run the paid request with the tracker armed, and settle it only when a
+ * response comes back. A rejection propagates with the tracker still armed —
+ * the shape `await send().finally(() => settle())` must never come back,
+ * because finally runs before the rejection reaches the catch.
+ *
+ *   const resp = await sendPaid(paid, () => fetchWithTimeout(url, { headers: { "PAYMENT-SIGNATURE": sig } }, ms), quotedUsd);
+ *
+ * Use this on the rails where the caller issues the paid request itself
+ * (Base's signed resubmit, the account rail's Bearer POST, the SDK-owned
+ * ImageClient call). On Solana the sequence lives inside solanaPaidPost /
+ * solanaPaidAsyncPost, which offer `onPaidRequest` / `onPaidResponse` — the
+ * exact edges of every request carrying the signature — so arm() and
+ * settle() from those hooks and capture the quote in onQuote for arm() to
+ * book. (Round 3 armed at onQuote, one step early: a signing-time RPC
+ * failure read as "may have settled". Round 4 moved every tool to the hooks.)
+ *
+ * NOT for a helper that bills on its own and classifies its own exits
+ * (apiKeyAsyncPost: BilledJobError / JobFailedError). Wrapping one leaves
+ * the tracker armed across a verdict the helper already reached; video,
+ * music and image call it bare.
+ */
+export async function sendPaid<T>(paid: PaidRequest, send: () => Promise<T>, quotedUsd?: number | null): Promise<T> {
+  paid.arm(quotedUsd);
+  const out = await send();
+  paid.settle();
+  return out;
+}
+
+/**
+ * The catch-side half. When the tracker says a paid request was outstanding
+ * and `err` means no response was observed, book the charge (the captured
+ * quote, else the caller's reserve) and return the sentence the caller must
+ * show — one that says what is and is not known and where to check. Returns
+ * null when nothing could have settled, so the caller falls through to its
+ * usual error formatting.
+ *
+ * Booking here is the documented trade-off video and music already make:
+ * over-counting a request that settled nothing is recoverable (the report
+ * can be reconciled against the wallet), under-counting a real charge is not
+ * (the cap drifts permissive and the message invites a second payment).
+ */
+export function settleGiveUp(
+  paid: PaidRequest,
+  err: unknown,
+  opts: {
+    budget: BudgetState;
+    agentId?: string;
+    /** What was reserved at the gate — booked when no quote was captured. */
+    estimateUsd: number;
+    /** Sentence subject, e.g. "Speech generation" or "RealFace enroll". */
+    what: string;
+    /** Extra sentence appended before the error line (e.g. a reclaim note). */
+    note?: string;
+  },
+): { text: string; bookedUsd: number } | null {
+  if (!paid.mayHaveSettled(err)) return null;
+  const bookedUsd = paid.quotedUsd ?? Math.max(0, opts.estimateUsd);
+  recordActualSpend(opts.budget, paid.quotedUsd, opts.estimateUsd, opts.agentId);
+  const errMsg = err instanceof Error ? err.message : String(err);
+  const account = isApiKeyMode();
+  const carrying = account ? "the account key" : "the payment signature";
+  const where = account
+    ? `check blockrun_wallet action:"report" and ${ACCOUNT_ACTIVITY_URL}`
+    : `check blockrun_wallet action:"report" or the wallet's recent transactions`;
+  return {
+    bookedUsd,
+    text:
+      `${opts.what} got no answer while a request carrying ${carrying} was still in flight, so the charge MAY have gone through — ` +
+      `the gateway settles on its own clock and does not stop because this client gave up. ` +
+      `$${bookedUsd.toFixed(4)} has been booked against your budget; ${where} before retrying.` +
+      (opts.note ? ` ${opts.note}` : "") +
+      `\nError: ${errMsg}`,
+  };
+}
diff --git a/src/utils/keychain.ts b/src/utils/keychain.ts
index a04638c..a7185a8 100644
--- a/src/utils/keychain.ts
+++ b/src/utils/keychain.ts
@@ -29,6 +29,7 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
+import { privateKeyToAccount } from "viem/accounts";
 
 /** Keychain service name — one namespace for every BlockRun secret. */
 export const KEYCHAIN_SERVICE = "blockrun";
@@ -46,9 +47,24 @@ const TIMEOUT_MS = 5_000;
 
 /** macOS errSecItemNotFound. */
 const MACOS_ITEM_NOT_FOUND = 44;
-/** secret-tool lookup miss. */
+/**
+ * secret-tool lookup: exit 1 — for a MISS and for a FAULT alike. libsecret's
+ * tool/secret-tool.c returns 1 from the lookup action whether `value == NULL`
+ * or `error != NULL`; the only difference is that the fault path g_printerr()s
+ * its reason first ("Cannot autolaunch D-Bus without X11 $DISPLAY", "The
+ * unlock prompt was dismissed", a StartServiceByName timeout). So the status
+ * cannot decide, and until audit round 4 the Linux branch read every fault as
+ * "absent" — round 3's tri-state was macOS-only, and under strict mode both
+ * provisioners minted over a funded keychain wallet the process could not
+ * open. linuxLookupMissed() reads stderr as well.
+ */
 const LINUX_ITEM_NOT_FOUND = 1;
 
+/** A secret-tool exit 1 that printed nothing is a miss; one that said why is a fault. */
+function linuxLookupMissed(result: { status: number | null; stderr?: string | null }): boolean {
+  return result.status === LINUX_ITEM_NOT_FOUND && !(result.stderr ?? "").trim();
+}
+
 const warned = new Set<string>();
 
 function warnOnce(message: string): void {
@@ -187,10 +203,34 @@ export type KeychainRead =
   | { status: "absent" }
   | { status: "error"; detail: string };
 
+/**
+ * Did the helper binary fail to launch at all?
+ *
+ * spawnSync does NOT throw for a nonexistent path: it returns `{status: null,
+ * error: ENOENT}`. Before this was checked, the linux branch fell through its
+ * exit-code tests and reported `secret-tool exit timeout` as a keychain ERROR
+ * — and both provisioners rightly refuse to mint on "error", so a fresh
+ * Ubuntu/Debian/WSL/Docker install (libsecret-tools is not installed by
+ * default) could never create a wallet on either chain, with a message
+ * blaming BLOCKRUN_KEYCHAIN=strict on a machine that had never set it. A
+ * keychain that does not exist cannot be holding a funded key: a missing
+ * binary is "unavailable", never a fault, and the header above promises the
+ * MCP stays file-based there.
+ */
+function binaryMissing(result: { error?: NodeJS.ErrnoException }): boolean {
+  return result.error?.code === "ENOENT";
+}
+
 /**
  * Read a secret, preserving WHY a read came back empty.
  */
 export function keychainRead(account: string): KeychainRead {
+  // Without a keychain there is nothing to read and nothing to spawn. This is
+  // the same check persistKey() makes before writing; a reader that asked a
+  // narrower question than the writer is how the ENOENT above got classified
+  // as a fault.
+  if (!isKeychainAvailable()) return { status: "absent" };
+
   const platform = os.platform();
   try {
     if (platform === "darwin") {
@@ -204,6 +244,7 @@ export function keychainRead(account: string): KeychainRead {
         return value ? { status: "found", value } : { status: "absent" };
       }
       if (result.status === MACOS_ITEM_NOT_FOUND) return { status: "absent" };
+      if (binaryMissing(result)) return { status: "absent" };
       return { status: "error", detail: `security exit ${result.status ?? "timeout"}` };
     }
 
@@ -217,8 +258,10 @@ export function keychainRead(account: string): KeychainRead {
         const value = result.stdout.trim();
         return value ? { status: "found", value } : { status: "absent" };
       }
-      if (result.status === LINUX_ITEM_NOT_FOUND) return { status: "absent" };
-      return { status: "error", detail: `secret-tool exit ${result.status ?? "timeout"}` };
+      if (linuxLookupMissed(result)) return { status: "absent" };
+      if (binaryMissing(result)) return { status: "absent" };
+      const said = (result.stderr ?? "").trim().split("\n")[0];
+      return { status: "error", detail: `secret-tool exit ${result.status ?? "timeout"}${said ? `: ${said}` : ""}` };
     }
 
     return { status: "absent" };
@@ -231,10 +274,12 @@ export function keychainRead(account: string): KeychainRead {
  * Read a secret. Returns null when absent, unavailable, or unreadable.
  *
  * Convenience wrapper for callers where "absent" and "error" lead to the same
- * safe action. Anywhere the difference decides whether to CREATE a wallet, use
- * keychainRead() instead.
+ * safe action. Anywhere the difference decides whether to CREATE a wallet — or
+ * which chain to select — use keychainRead() instead.
  */
 export function keychainLoad(account: string): string | null {
+  if (!isKeychainAvailable()) return null;
+
   const platform = os.platform();
   try {
     if (platform === "darwin") {
@@ -248,7 +293,7 @@ export function keychainLoad(account: string): string | null {
       // a locked keychain returns a different code, and silently creating a
       // SECOND wallet because we could not read the first one is the worst
       // possible failure here — the user's funds appear to vanish.
-      if (result.status !== MACOS_ITEM_NOT_FOUND) {
+      if (result.status !== MACOS_ITEM_NOT_FOUND && !binaryMissing(result)) {
         warnOnce(
           `OS keychain read failed (security exit ${result.status}) — falling back to ~/.blockrun/.session.`,
         );
@@ -263,9 +308,10 @@ export function keychainLoad(account: string): string | null {
         { timeout: TIMEOUT_MS, encoding: "utf-8" },
       );
       if (result.status === 0) return result.stdout.trim() || null;
-      if (result.status !== LINUX_ITEM_NOT_FOUND) {
+      if (!linuxLookupMissed(result) && !binaryMissing(result)) {
+        const said = (result.stderr ?? "").trim().split("\n")[0];
         warnOnce(
-          `OS keychain read failed (secret-tool exit ${result.status}) — falling back to ~/.blockrun/.session.`,
+          `OS keychain read failed (secret-tool exit ${result.status}${said ? `: ${said}` : ""}) — falling back to ~/.blockrun/.session.`,
         );
       }
       return null;
@@ -278,7 +324,20 @@ export function keychainLoad(account: string): string | null {
   }
 }
 
-/** Delete a secret. Returns true when the entry is gone (including "was never there"). */
+/**
+ * Delete a secret. Returns true when the entry is gone, including when it was
+ * never there — callers care about the end state, not about who removed it.
+ *
+ * Both backends have to spell that out, and only the macOS branch used to.
+ * `secret-tool clear` is not consistent across versions about whether a miss
+ * exits 0 or 1, so accept LINUX_ITEM_NOT_FOUND alongside success; the entry is
+ * absent either way. Returning false there would tell a caller the key is
+ * still in the keychain when it is not — the exact direction that turns a
+ * cleanup into a retry loop or a refusal to re-provision.
+ *
+ * A platform with no keychain returns false: nothing was deleted and nothing
+ * can be, which keychainAvailable() already reports the same way.
+ */
 export function keychainDelete(account: string): boolean {
   const platform = os.platform();
   try {
@@ -297,7 +356,7 @@ export function keychainDelete(account: string): boolean {
         ["clear", "app", KEYCHAIN_SERVICE, "account", account],
         { timeout: TIMEOUT_MS, encoding: "utf-8" },
       );
-      return result.status === 0;
+      return result.status === 0 || result.status === LINUX_ITEM_NOT_FOUND;
     }
 
     return false;
@@ -350,6 +409,39 @@ const defaultOps: KeychainOps = {
   load: keychainLoad,
 };
 
+/**
+ * Does the plaintext file hold exactly `key`, as its loader would read it?
+ *
+ * The loaders trim and (for EVM) 0x-prefix the file, so `KEY\n` and the bare
+ * hex are the same key on disk. Missing or empty is "yes": there is nothing
+ * there to lose. Unreadable is "no": unverifiable is not verified.
+ */
+function fileHoldsKey(file: string, key: string): boolean {
+  let raw: string;
+  try {
+    if (!fs.existsSync(file)) return true;
+    raw = fs.readFileSync(file, "utf-8");
+  } catch {
+    return false;
+  }
+  const onDisk = raw.trim();
+  if (onDisk === "") return true;
+  if (onDisk === key) return true;
+  return key.startsWith("0x") && !onDisk.startsWith("0x") && `0x${onDisk}` === key;
+}
+
+/** The address behind a stored key, for the replace notice — never the key. */
+function describeKeyOwner(_account: string, key: string): string {
+  // By shape, not by account name: an EVM key is the only one whose address
+  // can be derived here without the SVM dependencies.
+  if (/^0x[0-9a-fA-F]{64}$/.test(key)) {
+    try {
+      return privateKeyToAccount(key as `0x${string}`).address;
+    } catch { /* fall through */ }
+  }
+  return "another wallet";
+}
+
 export function persistKey(
   account: string,
   key: string,
@@ -359,6 +451,21 @@ export function persistKey(
   const mode = getKeychainMode();
   if (mode === "off" || !ops.available()) return;
 
+  // The store is `-U`: it REPLACES whatever the keychain held. The file is
+  // the source of truth by design (rotation by replacing .session), so a
+  // different key is written — but never silently. Round 4 found three ways
+  // a key nobody meant to rotate reached this line (a mis-read Linux
+  // keychain, a lost first-run race, a stale legacy file); each is fixed at
+  // its source, and this line is what makes the next one visible the run it
+  // happens. The address, never the key, is printed.
+  const previous = ops.load(account);
+  if (previous && previous !== key) {
+    console.error(
+      `[blockrun] Replacing the ${account} entry in the OS keychain: it held the key for ${describeKeyOwner(account, previous)}, ` +
+        `the key file now holds a different one. If you did not rotate this wallet on purpose, stop and check ~/.blockrun before spending.`,
+    );
+  }
+
   if (!ops.store(account, key)) return;
 
   if (mode !== "strict" || !plaintextFile) return;
@@ -370,6 +477,22 @@ export function persistKey(
     return;
   }
 
+  // The read-back proved the KEYCHAIN holds `key`. It says nothing about the
+  // FILE, and the file is what gets deleted. Before this check, a key that
+  // arrived from BLOCKRUN_WALLET_KEY went through here: stored over the
+  // funded key with -U, read back as itself, and the .session still holding
+  // the funded key was removed — both copies of the wallet gone in one run,
+  // behind the success message below. The caller no longer persists env keys
+  // at all, but the delete must be safe on its own: remove the file only when
+  // it holds the very key we just verified, and never remove what we could
+  // not read. Empty is fine to remove — it holds nothing to lose.
+  if (!fileHoldsKey(plaintextFile, key)) {
+    warnOnce(
+      `BLOCKRUN_KEYCHAIN=strict: ${plaintextFile} holds a different key than the one verified in the keychain — keeping it.`,
+    );
+    return;
+  }
+
   try {
     if (fs.existsSync(plaintextFile)) {
       fs.rmSync(plaintextFile, { force: true });
diff --git a/src/utils/markets-validation.ts b/src/utils/markets-validation.ts
index d01ce1c..577a00e 100644
--- a/src/utils/markets-validation.ts
+++ b/src/utils/markets-validation.ts
@@ -62,8 +62,16 @@ function numberParam(params: Record<string, string>, key: string): number | unde
 /**
  * Catch the most expensive, repeatable Predexon request mistakes before an
  * x402 payment is created. This intentionally validates only endpoints whose
- * current contract has caused real paid failures; unknown paths still pass
- * through so the MCP remains forward-compatible with new Predexon routes.
+ * current contract has caused real failed round-trips; unknown paths still
+ * pass through so the MCP remains forward-compatible with new Predexon routes.
+ *
+ * ON MONEY: none of these rules guards a PAID failure. The gateway's pm route
+ * returns on any upstream !ok BEFORE settlePaymentWithRetry runs, and its 4xx
+ * bodies say "(payment NOT charged)"; a route the registry does not know 404s
+ * before the 402 is even built. What a rule saves is the unpaid round-trip and
+ * an opaque error — so relaxing one when Predexon adds a param risks nothing
+ * but a wasted turn. Earlier wording here ("returns 410 after settling",
+ * "a paid 400") said otherwise and was wrong about when money moves.
  */
 export function validateMarketRequest(
   rawPath: string,
@@ -73,13 +81,32 @@ export function validateMarketRequest(
   const path = normalizeMarketPath(rawPath);
   const query = params ?? {};
 
-  // Verified live 2026-07-29: this route settles a payment and THEN returns
-  // 410 Gone. The gateway still registers, prices, and advertises it
-  // (blockrun/src/lib/predexon.ts), which is what talked me out of this block in
-  // 0.33.0 — but the gateway only proxies, and Predexon has retired it upstream.
-  // The registry is not evidence that a route still serves.
+  // Retired upstream. It settled-then-410'd in July 2026 (verified live
+  // 2026-07-29); since 2026-08-04 the registry no longer routes it at all and
+  // it 404s BEFORE payment ("Unknown Predexon endpoint", re-probed
+  // unauthenticated 2026-09-13). The block stays for the steer, and it comes
+  // before the query-in-path refusal below because "this route is gone" is
+  // the more useful message when both apply.
   if (path === "markets/listings") {
-    return "Predexon has retired 'markets/listings' — it returns 410 Gone after settling payment. Use 'markets/search' to discover open venue markets, then resolve the selected Polymarket market with 'polymarket/markets/keyset'. No payment was made.";
+    return "Predexon removed 'markets/listings' upstream on 2026-08-04 — it now 404s before payment. Use 'markets/search' to discover open venue markets, then resolve the selected Polymarket market with 'polymarket/markets/keyset'. No payment was made.";
+  }
+
+  // A QUERY STRING IN `path` READS AS NO PARAMS AT ALL. The rules below take
+  // their query from `params`; the path is normalised (its `?…` stripped) only
+  // so a rule can match the slug. So `polymarket/markets?active=true` matched
+  // the Gamma-param rule's slug with an EMPTY query, passed, paid, and came
+  // back unfiltered (Predexon returns 200 + unfiltered data on an unknown
+  // param name — it never 400s); `polymarket/orderbooks?token_id=…&start_time=…`
+  // was refused as "missing" although it was complete; and on the account
+  // rail a path query plus `params` concatenated into `…?limit=5?status=open`.
+  // The tool's contract is already "pass query params via params" — hold the
+  // caller to it here, before any rule that reads `params` can be fooled.
+  // `#` too: fetch drops a fragment before sending, so it is a silent no-op
+  // that looks like a filter.
+  if (/[?#]/.test(rawPath)) {
+    return `Query strings are not accepted in 'path' (got ${JSON.stringify(rawPath)}). ` +
+      "Put the bare route in 'path' and every query value in 'params', e.g. path: 'polymarket/orderbooks', params: { token_id: '…', start_time: '…', end_time: '…' }. " +
+      "Values in the path are invisible to this tool's pre-payment checks and to the account rail's URL builder. No payment was made.";
   }
 
   if (path === "markets/search" && query.status === "active") {
@@ -101,18 +128,18 @@ export function validateMarketRequest(
     }
     // Reject only what is definitively malformed. Verified live: omitting
     // `interval` succeeds (the server has a default), `1440` succeeds, `1h`
-    // 422s — but `60` returns a paid 400 on a market where `1440` works. Which
-    // integer intervals a given market can serve is data-dependent, so a
-    // client-side whitelist of numeric values would block valid calls on some
-    // markets and still let paid failures through on others. Only the shape is
-    // ours to check.
+    // 422s — but `60` returns a 400 on a market where `1440` works (a 4xx
+    // round-trip the gateway does not settle). Which integer intervals a given
+    // market can serve is data-dependent, so a client-side whitelist of numeric
+    // values would block valid calls on some markets and still let failed
+    // round-trips through on others. Only the shape is ours to check.
     //
     // Honest limit: ONE market was probed. "Data-dependent" is an inference, not
     // a finding — "60 is simply unsupported" fits the same evidence. If that is
     // the true rule, letting integers through under-blocks every hourly request.
     // Re-probe a second market before treating this as settled.
     if (query.interval !== undefined && !/^\d+$/.test(query.interval)) {
-      return `Polymarket candlesticks interval '${query.interval}' is not a number. It is integer minutes. The minute-equivalent of '1h' is '60', but '60' was observed returning a paid 400 on a market where '1440' (daily) worked — so '1440' is the safer choice if daily resolution is acceptable, and note it is coarser than hourly. Which intervals a market serves varies. Optional start_time/end_time are Unix seconds. No payment was made.`;
+      return `Polymarket candlesticks interval '${query.interval}' is not a number. It is integer minutes. The minute-equivalent of '1h' is '60', but '60' was observed returning an (unpaid) 400 on a market where '1440' (daily) worked — so '1440' is the safer choice if daily resolution is acceptable, and note it is coarser than hourly. Which intervals a market serves varies. Optional start_time/end_time are Unix seconds. No payment was made.`;
     }
     if ("start" in query || "end" in query) {
       return "Polymarket candlesticks uses params.start_time and params.end_time in Unix seconds, not start/end. No payment was made.";
@@ -134,12 +161,12 @@ export function validateMarketRequest(
   // Requires a smart-wallet CRITERION, not merely any param. Verified live:
   // no params 400s, `{ window: "7d" }` alone ALSO 400s, `{ min_trades: "100" }`
   // alone succeeds. Treating `window` as a cohort filter (0.33.0 did) let a
-  // guaranteed paid 400 straight through.
+  // guaranteed (unpaid) 400 round-trip straight through.
   if (/^polymarket\/market\/[^/]+\/smart-money$/.test(path)) {
     // Presence is not enough: `{ min_trades: "" }` is the shape a model emits
-    // when it knows the param name but not a value, and it 400s upstream after
-    // settling exactly like the unfiltered call. The orderbooks rule above
-    // already tests usability this way.
+    // when it knows the param name but not a value, and it 400s upstream
+    // exactly like the unfiltered call (unsettled — see the note on money
+    // above). The orderbooks rule above already tests usability this way.
     const hasCriterion = SMART_MONEY_CRITERIA.some((key) => (query[key] ?? "").trim() !== "");
     if (!hasCriterion) {
       const why = "window" in query
@@ -164,9 +191,9 @@ export function validateMarketRequest(
 // anyone who knows the path, withheld from openapi.json and the x402 manifest,
 // and on an upstream 5xx it releases the payment nonce, so nothing settles.
 //
-// Not a pre-payment block like markets/listings above: that one is a 410 sunset
-// and settles before failing, this one is an upstream bug that may recover, and
-// the gateway is the authority on whether it has. What we own is the wording.
+// Not a pre-payment block like markets/listings above: that one is a removed
+// route (a 404 before the 402), this one is an upstream bug that may recover,
+// and the gateway is the authority on whether it has. What we own is the wording.
 // The SDK reduced the gateway's "(payment NOT charged)" body to
 // `API error after payment: 502`, which asserts a charge that did not happen.
 export const DEGRADED_SPORTS_SINCE = "2026-08-04";
diff --git a/src/utils/model-cache.ts b/src/utils/model-cache.ts
index b208ca2..b18da05 100644
--- a/src/utils/model-cache.ts
+++ b/src/utils/model-cache.ts
@@ -2,7 +2,13 @@
 import type { ImageModel, Model } from "@blockrun/llm";
 
 export type ModelEntry = Model | ImageModel;
-export type ModelCache = { models: ModelEntry[] | null };
+export type ModelCache = {
+  models: ModelEntry[] | null;
+  /** Which rail+chain the cached list came from — see loadModels. */
+  key?: string;
+  /** In-flight fetch, so concurrent callers share one request. */
+  inflight?: Promise<ModelEntry[]>;
+};
 
 type ModelLister = {
   listModels: () => Promise<Model[]>;
@@ -15,15 +21,45 @@ const CACHE_TTL_MS = 5 * 60 * 1000;
 // unref'd so it never keeps the stdio process alive after work is done. Both the
 // models tool and the models resource call through here so the fetch + TTL logic
 // lives in one place.
-export async function loadModels(llm: ModelLister, cache: ModelCache): Promise<ModelEntry[]> {
+export async function loadModels(
+  llm: ModelLister,
+  cache: ModelCache,
+  /**
+   * Which catalogue this list belongs to. The two gateways do NOT serve the
+   * same one (measured 2026-09-09: 78 chat models on Base, 83 on Solana), and
+   * the account rail is a third. Without a key, `blockrun_wallet action:"chain"`
+   * left the previous chain's catalogue in place for the rest of the 5-minute
+   * TTL, so blockrun_models answered for a gateway the user had just left.
+   * Callers pass the active rail+chain; a changed key re-fetches.
+   */
+  key = "default",
+): Promise<ModelEntry[]> {
   // Treat an empty array as "not loaded" too: `![]` is false, so a transient
   // empty upstream result would otherwise be pinned as a valid cache for the
   // whole TTL ("Models (0):") and never re-fetched even after recovery.
-  if (cache.models === null || cache.models.length === 0) {
-    cache.models = llm.listAllModels
-      ? await llm.listAllModels()
-      : await llm.listModels();
-    setTimeout(() => { cache.models = null; }, CACHE_TTL_MS).unref();
+  const stale = cache.models === null || cache.models.length === 0 || cache.key !== key;
+  if (!stale) return cache.models as ModelEntry[];
+
+  // Share one request between concurrent callers (the tool and the resource can
+  // both be answering at once). Keyed with the fetch so a chain switch mid-flight
+  // does not adopt the wrong catalogue.
+  if (!cache.inflight || cache.key !== key) {
+    cache.key = key;
+    cache.inflight = (llm.listAllModels ? llm.listAllModels() : llm.listModels())
+      .then((models) => {
+        // Only publish if nobody switched rails while we were waiting.
+        if (cache.key === key) {
+          cache.models = models;
+          setTimeout(() => { if (cache.key === key) cache.models = null; }, CACHE_TTL_MS).unref();
+        }
+        return models;
+      })
+      .finally(() => { if (cache.key === key) cache.inflight = undefined; });
   }
-  return cache.models;
+  return cache.inflight;
+}
+
+/** The catalogue key for the active rail+chain. */
+export function modelCacheKey(mode: string, chain: string): string {
+  return mode === "api-key" ? "account" : `wallet:${chain}`;
 }
diff --git a/src/utils/onramp.ts b/src/utils/onramp.ts
index 918d4ca..d0f6cf6 100644
--- a/src/utils/onramp.ts
+++ b/src/utils/onramp.ts
@@ -30,8 +30,9 @@ const ONRAMP_ENDPOINT = "https://blockrun.ai/api/v1/onramp/token";
 /**
  * Mint a one-time Coinbase Onramp URL for the given Base address (which MUST be
  * the active wallet — the gateway binds the link to the signing wallet). Runs
- * the standard two-step x402 flow at a $0 price. Throws on any gateway error or
- * if the returned URL isn't a Coinbase Onramp link.
+ * the standard two-step x402 flow at a $0 price — and REFUSES to sign if the
+ * 402 quotes anything but a literal zero. Throws on any gateway error or if
+ * the returned URL isn't a Coinbase Onramp link.
  */
 export async function mintOnrampUrl(address: string): Promise<string> {
   const privateKey = getOrCreateWalletKey();
@@ -53,6 +54,25 @@ export async function mintOnrampUrl(address: string): Promise<string> {
   if (!prHeader) throw new Error("no PAYMENT-REQUIRED header in 402 response");
   const details = extractPaymentDetails(parsePaymentRequired(prHeader));
 
+  // The $0 is a contract, and this is where it is enforced. Every media tool's
+  // out-of-funds catch lands here — including on wallets that DO hold USDC (a
+  // replayed nonce after an upstream 5xx reads as "rejected" too, see
+  // basePaymentReplayHedge) — and until audit round 3 the amount was signed
+  // as quoted, with the "free" living only in the comment above and the test
+  // fixture. A gateway regression or a hijacked route that quoted a real
+  // amount would have been signed against a funded wallet by the very path
+  // that runs when something has already gone wrong. Refuse anything that is
+  // not a literal zero: an absent or malformed amount is not "free", it is
+  // unknown (and `Number("")` is 0, so a numeric compare would wave an empty
+  // field through — the same trap api-key-call's parseCostHeader documents).
+  const amountStr = typeof details.amount === "string" ? details.amount.trim() : "";
+  if (!/^0+$/.test(amountStr)) {
+    throw new Error(
+      `the onramp quote was not free (the gateway asked for ${JSON.stringify(details.amount)} atomic USDC; ` +
+        `the link must cost $0) — refusing to sign it. Nothing was signed and no charge was made.`,
+    );
+  }
+
   // Sign the (free, $0) authorization — the gateway recovers the signer to prove
   // wallet ownership; nothing settles on-chain.
   const payload = await createPaymentPayload(
diff --git a/src/utils/path-safety.ts b/src/utils/path-safety.ts
index d676ee1..ef87fc6 100644
--- a/src/utils/path-safety.ts
+++ b/src/utils/path-safety.ts
@@ -15,11 +15,12 @@
  * that merely *contain* a dot (e.g. `coingecko:ethereum`, `base:0x...`) are
  * legitimate and NOT flagged — only an exact `.`/`..` segment is.
  *
- * Decode once and split on both `/` and `\` first: the WHATWG URL parser (which
- * runs on the concatenated endpoint before fetch) treats `%2e`/`%2E` as `.` and
- * `\` as `/`, so `%2e%2e/...`, `.%2e/...`, and `..\..\...` normalize into
- * traversal too. A single decode matches the parser (it does not double-decode
- * `%252e`); a malformed `%` is left as-is rather than throwing.
+ * Split on both `/` and `\` and decode each segment once: the WHATWG URL parser
+ * (which runs on the concatenated endpoint before fetch) treats `%2e`/`%2E` as
+ * `.` and `\` as `/`, so `%2e%2e/...`, `.%2e/...`, and `..\..\...` normalize
+ * into traversal too. A single decode matches the parser (it does not
+ * double-decode `%252e`); a malformed escape in the route part is REFUSED (see
+ * below for why the old "leave it as-is" fallback was the hole).
  *
  * STRIP TAB/LF/CR FIRST. Per the URL spec the parser *removes* every ASCII tab
  * (U+0009), newline (U+000A) and carriage return (U+000D) from its input before
@@ -50,13 +51,70 @@ export function hasPathTraversal(path: string): boolean {
   // /api/v1/phone/numbers/buy and quoted $5.001 against its $0.0095 reserve,
   // and escapes profile scoping on the way. Each transformation was tested
   // alone and passed; only the composition was broken.
-  const asSent = path.replace(/[\t\n\r]/g, "");
-  let decoded = asSent;
-  try { decoded = decodeURIComponent(asSent); } catch { /* malformed %: check as-sent */ }
-  // Strip again after decoding: an ENCODED %09 decodes to a literal tab, which
-  // the far side does not delete. Over-blocking is the safe direction here.
-  const asParsed = decoded.replace(/[\t\n\r]/g, "");
-  return asParsed.split(/[/\\]/).some((seg) => seg === ".." || seg === ".");
+  //
+  // DECODE PER SEGMENT, NEVER THE WHOLE STRING. Until 0.50.0 the strip above
+  // was followed by ONE decodeURIComponent over the entire caller string, with
+  // a catch that fell back to the raw string. So a single malformed `%`
+  // anywhere — trivially a lone `%` after `?` or `#`, which the parser assigns
+  // to the query/fragment and never decodes — threw, the fallback kept the
+  // literal segment `%2e%2e`, and the equality check below said "not `..`".
+  // The parser, meanwhile, resolves `%2e%2e` / `.%2e` / `%2e.` as dot-segments
+  // NATIVELY (no decode needed) and ends the path at `?`/`#`. Probed on the
+  // pure pipeline 2026-09-13:
+  //
+  //   blockrun_modal({ path: "%2e%2e/phone/numbers/buy#%" })
+  //     -> guard false, priced as a $0.003 modal op, POSTs /v1/phone/numbers/buy ($5.001)
+  //   blockrun_phone({ path: "phone/%2e%2e/modal/sandbox/create#%", body: { gpu: "H100", timeout: 86400 } })
+  //     -> guard false, passes the phone/ namespace pin, reserves $0.012, buys a $192 sandbox
+  //
+  // Same composition class as the tab-in-escape hole above: each transformation
+  // was tested alone and passed. So, in parser order: drop the query/fragment
+  // (the parser never routes on it; a `..` right before the `?` still counts),
+  // split on `/` and `\`, read `%2e` as `.` the way the parser does, then decode
+  // each segment ON ITS OWN so one bad escape cannot blind the check to another
+  // — and a malformed escape in the route part is refused outright rather than
+  // waved through: fetch sends it verbatim, the gateway's router cannot decode
+  // it and 4xxs before payment, so nothing legitimate is lost by refusing.
+  const asSent = cutQueryAndControls(path);
+  return asSent.split(/[/\\]/).some((seg) => {
+    if (isDotSegment(seg)) return true;
+    let decoded: string;
+    try { decoded = decodeURIComponent(seg); } catch { return true; /* malformed escape: refuse */ }
+    // Strip again after decoding: an ENCODED %09 decodes to a literal tab, which
+    // the far side does not delete. Over-blocking is the safe direction here.
+    // Split again too: `phone%2F..%2Fmodal` decodes to phone/../modal, and the
+    // gateway routes on the decoded form.
+    return decoded.replace(/[\t\n\r]/g, "").split(/[/\\]/).some(isDotSegment);
+  });
+}
+
+/**
+ * The parser's own dot-segment test: `.`, `..`, and the percent-encoded forms
+ * `%2e`, `.%2e`, `%2e.`, `%2e%2e` (any case) are all single/double-dot segments
+ * to the WHATWG path parser — no decode step is involved, which is why a guard
+ * that only looked after decodeURIComponent could be blinded.
+ */
+function isDotSegment(seg: string): boolean {
+  const dotted = seg.replace(/%2e/gi, ".");
+  return dotted === ".." || dotted === ".";
+}
+
+/**
+ * The two things fetch's URL parser does to a caller string BEFORE routing is
+ * decided, in the order it does them: delete every tab/LF/CR, then end the path
+ * at the first `?` or `#`. Shared by hasPathTraversal and normalizeClassifyPath
+ * so the two guards cannot drift apart again.
+ *
+ * `[\s\S]` and not `.`: JS `.` never matches LF, CR, U+2028 or U+2029, and `$`
+ * without the `m` flag is end-of-input only — so the old `[?#].*$` cut simply
+ * failed to match when a line terminator followed the `?`, and
+ * `phone/numbers/buy?\n` reached the price table as `phone/numbers/buy?`
+ * ($0.012 unknown) while the parser sent `/v1/phone/numbers/buy` ($5.001).
+ * Cutting after the control strip rather than before it is the same order
+ * discipline as everything else in this file.
+ */
+function cutQueryAndControls(path: string): string {
+  return path.replace(/[\t\n\r]/g, "").replace(/[?#][\s\S]*$/, "");
 }
 
 /**
@@ -100,7 +158,10 @@ export function normalizeClassifyPath(path: string): string {
   // reason as hasPathTraversal above: `phone/numbers/%<TAB>62uy` is sent as
   // `%62uy`, which the gateway decodes to `buy` ($5.001), while a decode-first
   // classifier throws on the split escape and prices it as the $0.012 unknown.
-  const asSent = path.replace(/[?#].*$/, "").replace(/[\t\n\r]/g, "");
+  // The query cut itself lives in cutQueryAndControls, with hasPathTraversal —
+  // its `[?#].*$` predecessor did not cross a line terminator, so
+  // `phone/numbers/buy?\n` kept its `?` and priced as the $0.012 unknown.
+  const asSent = cutQueryAndControls(path);
   let decoded = asSent;
   try { decoded = decodeURIComponent(asSent); } catch { /* malformed %: classify as-sent */ }
   return decoded
diff --git a/src/utils/path-tool-catch.ts b/src/utils/path-tool-catch.ts
new file mode 100644
index 0000000..8aac16b
--- /dev/null
+++ b/src/utils/path-tool-catch.ts
@@ -0,0 +1,127 @@
+// src/utils/path-tool-catch.ts
+//
+// The one catch block for the seven path-based tools (search, exa, markets,
+// rpc, defi, phone, modal). They let the SDK — or, on the account rail,
+// utils/api-key-call.ts — own the paid request, so by the time an error
+// reaches them the only evidence of what happened to the money is the error
+// itself. Until audit round 3 every one of them did
+// `formatError(extractErrorMessage(err))` and nothing else: a call that
+// settled and then failed booked $0 against the cap, and the text said "try
+// again in a few minutes" (C38).
+//
+// WHAT GETS BOOKED, AND WHY NOT MORE. The SDK throws "API error after payment"
+// before it records any spend, on both wallet rails, so a settled-then-failed
+// call never reaches the counter. But the same prefix covers two very
+// different 5xx: the gateway's catch-all 500 AFTER settlement (the pm route
+// awaits the upstream body inside the same try — money gone, no marker) and
+// the search route's Grok failure BEFORE settlement (also a bare 500 "Internal
+// server error" — no money moved). The client cannot tell those apart, and
+// booking both would re-create the invented spend 0.49.0 removed: a 30-second
+// Grok blip would book $0.26 of phantom search spend per call. So the rule is
+// narrower than settlementOnThrow's "unknown":
+//
+//   book when the payment was sent AND no response from the ORIGIN was seen —
+//   a transport failure (abort, timeout, reset) or an edge status that means
+//   the origin did not answer (502/504/52x) — AND the message carries no
+//   uncharged marker.
+//
+// A gateway-authored 5xx with a body (500, 503) after payment is NOT booked;
+// formatError still hedges it ("the charge MAY have gone through"), because
+// the text can afford to be uncertain where the ledger cannot afford to be
+// wrong in the permissive direction twice a minute.
+
+import type { BudgetState } from "../types.js";
+import { recordActualSpend } from "./budget.js";
+import { settlementOnThrow } from "./chat-stream.js";
+import { isApiKeyMode } from "./auth.js";
+import { ledgerFallback, RawCallSettledError } from "./raw-call.js";
+import { basePaymentReplayHedge, extractErrorMessage, formatError, isExplicitlyUncharged } from "./errors.js";
+
+// Statuses an edge or a load balancer returns when the ORIGIN did not answer
+// in time — the origin may still be running the request and settle it after
+// the client is gone. Mirrors ORIGIN_DID_NOT_ANSWER in utils/chat-stream.ts
+// (not exported there); keep the two in step.
+const ORIGIN_DID_NOT_ANSWER = new Set([408, 502, 504, 520, 521, 522, 523, 524, 525, 526, 527, 529, 530]);
+
+function statusOf(err: unknown): number | undefined {
+  const e = err as { statusCode?: unknown; status?: unknown } | undefined;
+  if (typeof e?.statusCode === "number") return e.statusCode; // @blockrun/llm APIError
+  if (typeof e?.status === "number") return e.status;
+  return undefined;
+}
+
+export interface PathToolFailureOpts {
+  budget: BudgetState;
+  agentId?: string;
+  /**
+   * The reserve of the paid request that was IN FLIGHT when `err` was thrown,
+   * or 0 when no paid request had been sent yet (validation, the budget gate,
+   * a declined confirmSpend, a client that could not be built). The caller
+   * sets it on the line before rawGet/rawPost — never earlier, or a keychain
+   * error whose text happens to say "timeout" books a render.
+   */
+  sentUsd: number;
+  /** Vendor name for the Base-only replay hedge (exa, defi), when the route has that ambiguity. */
+  replayUpstream?: string;
+  /**
+   * Route-specific rendering that REPLACES formatError's text when it returns
+   * a string (markets' degraded sports/* formatter). Booking is unaffected.
+   */
+  describe?: (message: string) => string | null;
+}
+
+// A type alias, not an interface: the MCP SDK's CallToolResult carries an
+// index signature, and an interface without one is not assignable to it.
+export type PathToolFailure = {
+  [key: string]: unknown;
+  content: Array<{ type: "text"; text: string }>;
+  isError: true;
+};
+
+/**
+ * Render a path tool's failure and book the charge when it may have settled.
+ * Returns the MCP error result the handler returns as-is.
+ */
+export function pathToolFailure(err: unknown, opts: PathToolFailureOpts): PathToolFailure {
+  // The SDK's counter moved before the throw: a CERTAIN charge at a known
+  // amount (see RawCallSettledError), not a maybe at the reserve.
+  if (err instanceof RawCallSettledError) {
+    recordActualSpend(opts.budget, err.settledUsd, opts.sentUsd, opts.agentId);
+    return {
+      content: [{
+        type: "text",
+        text: `Error: ${err.message}
+
+The payment settled before this failure, so the charge stands — $${err.settledUsd.toFixed(4)} is booked against your budget. ` +
+          `The gateway answered but the response could not be read; retrying pays again. Check blockrun_wallet action:"report" first.`,
+      }],
+      isError: true,
+    };
+  }
+  const message = extractErrorMessage(err);
+  const rail = isApiKeyMode() ? "account" : "wallet";
+  const verdict = settlementOnThrow(err, { rail, estimateUsd: opts.sentUsd });
+  const status = statusOf(err);
+  // "unknown" is the necessary condition (the payment went out, no verdict came
+  // back); the status test is the sufficient one — see the header comment.
+  const originSilent = status === undefined || ORIGIN_DID_NOT_ANSWER.has(status);
+  const mayHaveSettled = verdict === "unknown" && originSilent && !isExplicitlyUncharged(message);
+
+  let bookedUsd = 0;
+  if (mayHaveSettled) {
+    // Same conservative direction video/music/in-flight already take: over-
+    // counting a request that settled nothing is recoverable against the wallet;
+    // under-counting a real charge drifts the cap permissive and the message
+    // invites a second payment. paidUsd is null — nothing was observed.
+    bookedUsd = ledgerFallback(opts.sentUsd);
+    recordActualSpend(opts.budget, null, bookedUsd, opts.agentId);
+  }
+
+  const bespoke = opts.describe?.(message) ?? null;
+  let text = bespoke ?? formatError(message, { afterPayment: verdict === "unknown" });
+  if (mayHaveSettled) {
+    text += ` $${bookedUsd.toFixed(4)} has been booked against your budget as a precaution.`;
+  }
+  if (opts.replayUpstream) text += basePaymentReplayHedge(message, opts.replayUpstream);
+  return { content: [{ type: "text", text }], isError: true };
+}
diff --git a/src/utils/poll.ts b/src/utils/poll.ts
index cf1f31b..539b4e9 100644
--- a/src/utils/poll.ts
+++ b/src/utils/poll.ts
@@ -1,9 +1,37 @@
 // src/utils/poll.ts
-// Shared polling arithmetic for the async x402 tools (video, music).
+// Shared polling arithmetic and vocabulary for the async x402 tools (video,
+// music) and the helpers that poll on their behalf (utils/solana-402.ts).
 //
 // Deliberately NOT in http.ts: every async-tool test replaces that module
 // with a network sentinel, so a pure function living there would force each
-// of them to stub arithmetic just to import the tool under test.
+// of them to stub arithmetic just to import the tool under test. Nothing in
+// the test tree mocks this module, which is also why the typed error below
+// lives here and not in a tool file: video.ts cannot statically import from
+// solana-402.ts (Base-only installs must never load the SVM dependencies), and
+// a class that is one thing in src and another in a mock is worse than prose.
+
+/**
+ * The gateway answered a poll with a terminal job status, and the payment
+ * model of that route means nothing was charged (payment-on-completion: the
+ * charge only happens on a poll that observes "completed").
+ *
+ * Typed so a tool's catch can tell "the job failed, uncharged" from "we gave
+ * up" without reading the message. The message is not safe to classify: the
+ * gateway echoes the upstream failure text verbatim, and MiniMax's is Node's
+ * own "The operation was aborted due to timeout" — which isTimeoutError's
+ * substring fallback matched, so the Solana give-up branch booked a full
+ * render and told the user the charge MAY have gone through for a job the
+ * same message said was not charged (audit round 3, C13/C37).
+ */
+export class JobFailedError extends Error {
+  readonly jobId?: string;
+  constructor(message: string, opts: { jobId?: string } = {}) {
+    super(message);
+    this.name = "JobFailedError";
+    this.jobId = opts.jobId;
+  }
+}
+
 // How long the next poll may block, given the budget that is left.
 //
 // The async x402 tools (video, music) poll a job to completion while holding a
diff --git a/src/utils/polymarket/creds.ts b/src/utils/polymarket/creds.ts
index 3ff3a28..08037af 100644
--- a/src/utils/polymarket/creds.ts
+++ b/src/utils/polymarket/creds.ts
@@ -55,6 +55,15 @@ export interface PolymarketState {
    * while this is set and unresolved. Cleared on confirm/failure.
    */
   pendingWithdraw?: { transactionID: string; deadline: number };
+  /**
+   * A funding call whose gateway response was lost, 5xx, or success:false
+   * after the signed EIP-3009 authorization had already been POSTed. The
+   * authorization stays executable by the facilitator until `deadline` (unix
+   * seconds), so a fresh one signed before then can DOUBLE-SEND the full
+   * amount — fund refuses to sign while this is set and unexpired. Cleared on
+   * a confirmed submit or a definite 4xx rejection.
+   */
+  pendingFund?: { amountUsd: number; deadline: number };
 }
 
 function readJsonFile<T>(file: string): T | null {
diff --git a/src/utils/polymarket/fund.ts b/src/utils/polymarket/fund.ts
index 9a76c54..209383d 100644
--- a/src/utils/polymarket/fund.ts
+++ b/src/utils/polymarket/fund.ts
@@ -15,10 +15,40 @@ import { getPolymarketAccount } from "./client.js";
 import { BASE_CHAIN_ID, BRIDGE_API_HOST, getMaxFundUsd, getSigType } from "./constants.js";
 import { getFundsAddress } from "./positions.js";
 import { getPublicClient } from "./setup.js";
-import type { ToolResult } from "./orders.js";
+import { loadState, saveState } from "./creds.js";
+import { declinedResult, type SpendGate, type ToolResult } from "./transactions.js";
+import type { BudgetState } from "../../types.js";
+import { recordActualSpend, reserveBudget } from "../budget.js";
 
 const FUND_FEE_USD = 0.01;
 const USDC_DECIMALS = 6;
+/**
+ * How long the signed EIP-3009 authorization stays executable, in seconds.
+ * Passed to createPaymentPayload explicitly (its default is the same 300s) so
+ * the pendingFund deadline below and the signature's validBefore cannot drift.
+ * Exported for tests.
+ */
+export const FUND_AUTH_VALIDITY_SECS = 300;
+/** The facilitator can broadcast right at validBefore; don't race it. */
+const FUND_GUARD_GRACE_SECS = 60;
+
+const FUND_GUIDANCE =
+  "check your Base wallet's USDC balance (blockrun_wallet action:\"status\", or basescan) and the vault's pUSD " +
+  "with action:\"setup\" before ANY retry — a resubmitted funding call signs a SECOND full transfer and can double-send";
+
+/**
+ * True when a thrown gateway error PROVES the deposit authorization was never
+ * forwarded: a 4xx from @blockrun/llm's APIError (`statusCode`), or its
+ * PaymentError (the x402 FEE payment was refused before the request body was
+ * processed). A timeout, a dropped socket, a 5xx, or a success:false body all
+ * arrive after the gateway may have handed the authorization to the
+ * facilitator — outcome unknown.
+ */
+function isDefiniteFundRejection(err: unknown): boolean {
+  const e = err as { name?: string; statusCode?: unknown } | undefined;
+  if (e?.name === "PaymentError") return true;
+  return typeof e?.statusCode === "number" && e.statusCode >= 400 && e.statusCode < 500;
+}
 // The Polymarket bridge does NOT process Base-USDC deposits below this — a
 // smaller amount lands at the bridge address but is never wrapped/delivered to
 // the vault (verified live: a $0.10 deposit confirmed on Base but never reached
@@ -37,7 +67,20 @@ async function bridgeAddressFor(vault: string): Promise<string> {
   return evm;
 }
 
-export async function fundVault(input: { amount_usd?: number; confirm?: boolean }): Promise<ToolResult> {
+export async function fundVault(input: {
+  amount_usd?: number;
+  confirm?: boolean;
+  askUser?: SpendGate;
+  /**
+   * The x402 budget ledger. The DEPOSIT is the user's own USDC into a vault
+   * only the same key controls and stays outside the ledger, but the $0.01
+   * gateway fee is BlockRun API spend from the Base wallet — the thing the
+   * ledger meters. Absent (legacy wiring), the fee is neither reserved nor
+   * booked, as before.
+   */
+  budget?: BudgetState;
+  agent_id?: string;
+}): Promise<ToolResult> {
   if (input.amount_usd === undefined || input.amount_usd <= 0) {
     return { text: `Pass amount_usd — the USDC amount to move from your Base wallet into your Polymarket vault (e.g. amount_usd:5).`, isError: true };
   }
@@ -113,6 +156,16 @@ export async function fundVault(input: { amount_usd?: number; confirm?: boolean
 
     const bridge = await bridgeAddressFor(vault);
 
+    // An earlier funding call whose outcome is unknown: its authorization may
+    // still be executed by the facilitator until its deadline, and a second
+    // one signed on top of it double-sends the full amount. Refuse to sign
+    // until the window has passed (the balance reads then show what
+    // happened); the dry-run only warns. Mirrors withdraw's pendingWithdraw.
+    const pending = loadState().pendingFund;
+    const nowSec = Math.floor(Date.now() / 1000);
+    const pendingWaitSecs = pending ? pending.deadline + FUND_GUARD_GRACE_SECS - nowSec : 0;
+    if (pending && pendingWaitSecs <= 0) saveState({ pendingFund: undefined }); // expired — safe
+
     if (input.confirm !== true) {
       return {
         text: [
@@ -122,67 +175,151 @@ export async function fundVault(input: { amount_usd?: number; confirm?: boolean
           `  → bridge:         ${bridge}`,
           `  → wraps to pUSD in your vault: ${vault}`,
           `  fee: $${FUND_FEE_USD} (BlockRun pays the Base gas; you need no ETH)`,
+          ...(pending && pendingWaitSecs > 0
+            ? [
+                ``,
+                `⚠️ A previous funding call for $${pending.amountUsd.toFixed(2)} has an UNKNOWN outcome and its signed ` +
+                  `authorization may still execute for ~${pendingWaitSecs}s. confirm:true is refused until then — ${FUND_GUIDANCE}.`,
+              ]
+            : []),
           ``,
           `Re-call with confirm:true to sign and submit.`,
         ].join("\n"),
-        structured: { dryRun: true, amountUsd, agent, bridge, vault, feeUsd: FUND_FEE_USD },
+        structured: { dryRun: true, amountUsd, agent, bridge, vault, feeUsd: FUND_FEE_USD, ...(pending && pendingWaitSecs > 0 ? { pendingFund: pending } : {}) },
       };
     }
 
-    // Sign the EIP-3009 deposit authorization: Base USDC → bridge address.
-    const privateKey = getOrCreateWalletKey();
-    const amountMicro = String(Math.floor(amountUsd * 10 ** USDC_DECIMALS));
-    const depositAuthorization = await createPaymentPayload(
-      privateKey, agent, bridge, amountMicro, `eip155:${BASE_CHAIN_ID}`,
-    );
-
-    // Call the gateway fund endpoint — it charges $0.01 via x402 automatically
-    // and relays the deposit authorization to the CDP facilitator (pays gas).
-    const client = new BlockrunClient({ privateKey });
-    const result = (await client.post("/v1/polymarket/fund", {
-      depositWallet: vault,
-      recipient: bridge,
-      amountMicro,
-      depositAuthorization,
-    })) as {
-      success?: boolean;
-      funded?: boolean;
-      creditPending?: boolean;
-      deposit?: { txHash?: string; amountUsd?: number };
-      fee?: { txHash?: string };
-      error?: string;
-    };
+    if (pending && pendingWaitSecs > 0) {
+      return {
+        text: `Refusing to sign: a previous funding call for $${pending.amountUsd.toFixed(2)} has an UNKNOWN outcome — ` +
+          `its signed USDC authorization may still execute for up to ~${pendingWaitSecs}s more, and signing another ` +
+          `now could double-send. Nothing was signed. Re-run after that window; meanwhile ${FUND_GUIDANCE}.`,
+        isError: true,
+        structured: { refused: "pending_fund", pendingFund: pending },
+      };
+    }
 
-    if (!result?.success) {
-      return { text: `Funding failed: ${result?.error ?? JSON.stringify(result)}`, isError: true };
+    // Reserve the gateway fee against the x402 budget BEFORE the dialog and
+    // the signature, like every other paid tool: a cap the fee would cross
+    // refuses here, with nothing signed. Released in the finally below —
+    // recordActualSpend books the settled figure on the paths that paid.
+    const feeGate = input.budget ? reserveBudget(input.budget, input.agent_id, FUND_FEE_USD) : null;
+    if (feeGate && !feeGate.allowed) {
+      return {
+        text: `${feeGate.reason}. The $${FUND_FEE_USD} funding fee is BlockRun API spend and counts against the budget cap ` +
+          `(blockrun_wallet action:"report" / action:"delegate"). Nothing was signed.`,
+        isError: true,
+      };
     }
+    try {
+      // The user's word before the signature, when the operator asked for it
+      // (BLOCKRUN_CONFIRM_SPEND=on): the full amount plus the fee leaves the
+      // Base wallet on this signature.
+      if (input.askUser) {
+        const gate = await input.askUser(amountUsd + FUND_FEE_USD, `polymarket · fund vault ${vault} from ${agent}`);
+        if (!gate.ok) return declinedResult(`the $${amountUsd.toFixed(2)} funding authorization`);
+      }
 
-    // success:true = the deposit was SUBMITTED to the bridge + fee charged on
-    // Base. It does NOT mean the vault is funded: the Polymarket bridge credits
-    // pUSD on Polygon asynchronously (usually minutes, occasionally 30+),
-    // off-chain and un-pollable here — don't claim "Funded" (issue #226).
-    return {
-      text: [
-        `✅ Deposit of $${amountUsd.toFixed(2)} USDC submitted to the Polymarket bridge (gasless).`,
-        `  from Base wallet: ${agent}`,
-        ...(result.deposit?.txHash ? [`  deposit tx: https://basescan.org/tx/${result.deposit.txHash}`] : []),
-        `  ⏳ pUSD credit to your vault ${vault} is PENDING — the bridge settles on Polygon`,
-        `     asynchronously (usually minutes, occasionally 30+). Re-run action:"setup"`,
-        `     and watch for the pUSD balance; it is not instant.`,
-        `  Fee charged: $${FUND_FEE_USD}.`,
-      ].join("\n"),
-      structured: {
-        success: true,
-        funded: false,
-        creditPending: true,
-        amountUsd,
-        agent,
-        bridge,
-        vault,
-        deposit: result.deposit,
-        fee: result.fee,
-      },
-    };
+      // Sign the EIP-3009 deposit authorization: Base USDC → bridge address.
+      const privateKey = getOrCreateWalletKey();
+      const amountMicro = String(Math.floor(amountUsd * 10 ** USDC_DECIMALS));
+      const deadline = Math.floor(Date.now() / 1000) + FUND_AUTH_VALIDITY_SECS;
+      const depositAuthorization = await createPaymentPayload(
+        privateKey, agent, bridge, amountMicro, `eip155:${BASE_CHAIN_ID}`,
+        { maxTimeoutSeconds: FUND_AUTH_VALIDITY_SECS },
+      );
+
+      // Call the gateway fund endpoint — it charges $0.01 via x402 automatically
+      // and relays the deposit authorization to the CDP facilitator (pays gas).
+      // Arm the guard BEFORE the POST: a crash mid-request must leave it set.
+      saveState({ pendingFund: { amountUsd, deadline } });
+      const client = new BlockrunClient({ privateKey });
+      let result: {
+        success?: boolean;
+        funded?: boolean;
+        creditPending?: boolean;
+        deposit?: { txHash?: string; amountUsd?: number };
+        fee?: { txHash?: string };
+        error?: string;
+      };
+      // What "failed" means depends on WHEN it failed. A definite 4xx (or a
+      // refused fee payment) proves the authorization was never forwarded —
+      // plain failure, guard cleared. Anything else — timeout, dropped socket,
+      // 5xx, or a success:false body — arrives after the gateway may already
+      // have handed the authorization to the facilitator, and the old bare
+      // "Funding failed" invited the retry that signs a second $amount.
+      const outcomeUnknown = (detail: string): ToolResult => ({
+        text: `⚠️ Funding outcome UNKNOWN — the gateway did not confirm the $${amountUsd.toFixed(2)} deposit (${detail}). ` +
+          `The signed USDC authorization MAY already have been forwarded and broadcast on Base. Do NOT retry yet: ` +
+          `${FUND_GUIDANCE}. This tool refuses to re-sign for ~${FUND_AUTH_VALIDITY_SECS + FUND_GUARD_GRACE_SECS}s ` +
+          `(the authorization's validity window) so a retry cannot double-send.`,
+        isError: true,
+        structured: { outcome: "unknown", amountUsd, agent, bridge, vault, pendingFund: { amountUsd, deadline } },
+      });
+      try {
+        result = (await client.post("/v1/polymarket/fund", {
+          depositWallet: vault,
+          recipient: bridge,
+          amountMicro,
+          depositAuthorization,
+        })) as typeof result;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (isDefiniteFundRejection(err)) {
+          saveState({ pendingFund: undefined });
+          return { text: `Funding failed: ${msg}. The gateway rejected the request before forwarding it — nothing moved.`, isError: true };
+        }
+        // The fee payment left with the request; book the estimate rather than
+        // under-count a charge that may have settled (the same trade-off the
+        // other paid tools make on a lost response).
+        if (input.budget) recordActualSpend(input.budget, null, FUND_FEE_USD, input.agent_id);
+        return outcomeUnknown(msg);
+      }
+
+      // The SDK settles the 402 quote into its session spend on a 2xx — the fee
+      // the gateway actually charged, whatever the route is priced at today.
+      // getSpending throws in account mode, which cannot reach here (Polymarket
+      // is wallet-only) — guarded anyway so a booking never masks a success.
+      if (input.budget) {
+        let observed: number | null = null;
+        try { observed = client.getSpending().totalUsd; } catch { observed = null; }
+        recordActualSpend(input.budget, observed && observed > 0 ? observed : null, FUND_FEE_USD, input.agent_id);
+      }
+
+      if (!result?.success) {
+        return outcomeUnknown(`gateway said success:false — ${result?.error ?? JSON.stringify(result)}`);
+      }
+      saveState({ pendingFund: undefined });
+
+      // success:true = the deposit was SUBMITTED to the bridge + fee charged on
+      // Base. It does NOT mean the vault is funded: the Polymarket bridge credits
+      // pUSD on Polygon asynchronously (usually minutes, occasionally 30+),
+      // off-chain and un-pollable here — don't claim "Funded" (issue #226).
+      return {
+        text: [
+          `✅ Deposit of $${amountUsd.toFixed(2)} USDC submitted to the Polymarket bridge (gasless).`,
+          `  from Base wallet: ${agent}`,
+          ...(result.deposit?.txHash ? [`  deposit tx: https://basescan.org/tx/${result.deposit.txHash}`] : []),
+          `  ⏳ pUSD credit to your vault ${vault} is PENDING — the bridge settles on Polygon`,
+          `     asynchronously (usually minutes, occasionally 30+). Re-run action:"setup"`,
+          `     and watch for the pUSD balance; it is not instant.`,
+          `  Fee charged: $${FUND_FEE_USD}.`,
+        ].join("\n"),
+        structured: {
+          success: true,
+          funded: false,
+          creditPending: true,
+          amountUsd,
+          agent,
+          bridge,
+          vault,
+          deposit: result.deposit,
+          fee: result.fee,
+        },
+      };
+    } finally {
+      feeGate?.release();
+    }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { text: `Funding error: ${msg}`, isError: true };
diff --git a/src/utils/polymarket/l1-auth-1271.ts b/src/utils/polymarket/l1-auth-1271.ts
index 270bde8..2e54a94 100644
--- a/src/utils/polymarket/l1-auth-1271.ts
+++ b/src/utils/polymarket/l1-auth-1271.ts
@@ -1,24 +1,44 @@
 // src/utils/polymarket/l1-auth-1271.ts
 //
-// Workaround for https://github.com/Polymarket/clob-client-v2/issues/65
+// CLOB L1 authentication and API-credential derivation.
+//
+// READ THIS BEFORE DELETING ANYTHING HERE. The file is named for a hypothesis
+// that turned out to be wrong, and the function every Polymarket action
+// depends on now lives in it: deriveApiCreds(). Removing the module removes
+// credential derivation, and all trading stops.
+//
+// The hypothesis was https://github.com/Polymarket/clob-client-v2/issues/65
 // (open as of v1.0.8, 2026-07): the SDK's createApiKey()/createL1Headers()
 // signs the L1 ClobAuth attestation as a PLAIN EOA signature bound to the EOA
-// address, while POLY_1271 orders set order.signer = deposit wallet — so the
-// CLOB rejects every order with 400 "the order signer address has to be the
-// address of the API KEY". The SDK's ORDER signing does wrap correctly
-// (ExchangeOrderBuilderV2.buildOrderSignature); only L1 auth lacks the wrap.
+// address, while POLY_1271 orders set order.signer = deposit wallet, and the
+// CLOB rejects those orders with 400 "the order signer address has to be the
+// address of the API KEY". The obvious reading was that L1 auth needed the
+// same ERC-7739 wrap the SDK already applies to orders, and
+// buildWrapped1271Headers() below implements exactly that.
+//
+// It is not the fix. The CLOB rejects the wrapped envelope outright with
+// "Invalid L1 Request headers". L2 credentials are ALWAYS bound to the owner
+// EOA even in POLY_1271 mode, matching the reference Rust client
+// (rs-clob-client-v2 src/auth.rs): L1/L2 auth uses the owner's plain ECDSA
+// signature, and only the ORDER carries signer/maker = deposit wallet, checked
+// on-chain by that wallet's ERC-1271 isValidSignature. See the long note at
+// the buildClobClient() call site in client.ts.
 //
-// This module applies the SAME ERC-7739 TypedDataSign envelope the SDK uses
-// for orders to the L1 ClobAuth message, with POLY_ADDRESS = the deposit
-// wallet, so the derived API creds are bound to the deposit wallet:
+// So the live path is buildPlainL1Headers(), and both call sites
+// (client.ts, relayer.ts) pass sigType 0. The wrapped path below is kept as a
+// tested reference implementation of the ERC-7739 envelope for ClobAuth --
+// it is correct about the envelope and wrong about what the server wants --
+// and test/polymarket-l1-auth.test.ts pins its byte layout. Nothing calls it
+// with sigType 3.
 //
 //   contentsHash = hashStruct(ClobAuth message)              (app = ClobAuthDomain v1)
 //   innerSig     = eth_signTypedData(TypedDataSign{contents, DepositWallet domain})
-//   envelope     = innerSig ‖ appDomainSeparator ‖ contentsHash
-//                  ‖ typeString(ClobAuth) ‖ uint16(len(typeString))
+//   envelope     = innerSig | appDomainSeparator | contentsHash
+//                  | typeString(ClobAuth) | uint16(len(typeString))
 //
-// Re-check issue #65 when bumping @polymarket/clob-client-v2 — if fixed
-// upstream, delete this module and use client.createOrDeriveApiKey().
+// When bumping @polymarket/clob-client-v2, what to re-check is whether the SDK
+// can now derive creds itself (client.createOrDeriveApiKey()) -- not whether
+// issue #65 is closed, since its premise was already wrong.
 import axios from "axios";
 import {
   encodeAbiParameters,
@@ -177,10 +197,15 @@ async function buildPlainL1Headers(account: PrivateKeyAccount): Promise<L1Header
 }
 
 /**
- * Create-or-derive CLOB L2 API creds. sigType 3 binds them to the deposit
- * wallet via the wrapped headers; sigType 0 binds them to the EOA. Mirrors the
- * SDK's createOrDeriveApiKey flow (POST /auth/api-key, falling back to
- * GET /auth/derive-api-key when the key already exists).
+ * Create-or-derive CLOB L2 API creds. Mirrors the SDK's createOrDeriveApiKey
+ * flow (POST /auth/api-key, falling back to GET /auth/derive-api-key when the
+ * key already exists).
+ *
+ * Pass sigType 0. It binds the creds to the EOA, which is what the CLOB wants
+ * in POLY_1271 mode too, and it is what both call sites pass. sigType 3 sends
+ * the wrapped headers and the server answers "Invalid L1 Request headers" --
+ * it is reachable only to keep the envelope implementation honest, not because
+ * it is an option. The file header explains why.
  */
 export async function deriveApiCreds(
   account: PrivateKeyAccount,
diff --git a/src/utils/polymarket/orders.ts b/src/utils/polymarket/orders.ts
index b4f0fe4..c34549a 100644
--- a/src/utils/polymarket/orders.ts
+++ b/src/utils/polymarket/orders.ts
@@ -13,18 +13,25 @@ import { checkGeoblock, getClobClient, getPolymarketAccount, resetClobClient } f
 import { getMaxBetUsd, getMaxSessionUsd, getSigType } from "./constants.js";
 import { invalidateL2Creds, loadState } from "./creds.js";
 import { fetchWithTimeout } from "../http.js";
+import { declinedResult, isDefiniteRejection, type SpendGate, type ToolResult } from "./transactions.js";
 
 // --- Session bet ledger (in-memory; resets with the process) ---
 const ledger = {
   totalUsd: 0,
   count: 0,
+  // Submits whose response was lost or 5xx: the order MAY be live, so its
+  // notional stays inside totalUsd (a possibly-live order must count against
+  // the cap) but it is not a confirmed placement. Never decremented — the
+  // tool has no order id to reconcile against; a restart resets the ledger.
+  unconfirmed: 0,
   perAgent: new Map<string, number>(),
 };
 
-export function getSessionLedger(): { totalUsd: number; count: number; perAgent: Record<string, number> } {
+export function getSessionLedger(): { totalUsd: number; count: number; unconfirmed: number; perAgent: Record<string, number> } {
   return {
     totalUsd: ledger.totalUsd,
     count: ledger.count,
+    unconfirmed: ledger.unconfirmed,
     perAgent: Object.fromEntries(ledger.perAgent),
   };
 }
@@ -46,6 +53,26 @@ function commitBet(): void {
   ledger.count += 1;
 }
 
+// --- Previewed worst-fill bounds (in-memory; reset with the process) ---
+//
+// A market order's preview and its confirm are two tool calls, and the book
+// can move in between — against you exactly when it matters. The confirm
+// re-walks a fresh book, so "signed at the worst fill you saw" only held
+// within ONE call unless the caller carried `max_fill_price` forward, and the
+// documented agent flow (preview → quote the user → re-call with confirm:true)
+// never did. Only the MCP-Apps order card passed it. So the preview now
+// records the worst fill it showed, per (token, side), and a confirm that
+// carries no bound of its own is held to the LAST preview's figure: a worse
+// walk is refused unsigned with a re-preview instruction. A fresh preview
+// replaces the entry; an explicit max_fill_price overrides it either way.
+// Entries are never expired — a stale bound can only refuse (and say to
+// re-preview) or allow a better price, never sign a worse one.
+const previewedBounds = new Map<string, { worstFillPrice: number; at: number }>();
+
+function boundKey(tokenId: string, side: "buy" | "sell"): string {
+  return `${tokenId}:${side}`;
+}
+
 // --- Helpers ---
 
 /**
@@ -267,8 +294,22 @@ function isBalanceAllowanceError(err: unknown): boolean {
   return text.includes("not enough balance") || text.includes("insufficient") || text.includes("allowance");
 }
 
+/**
+ * Thrown by executeTrade when the submit's outcome is unknown. Carries the
+ * finished, agent-facing text so mapClobError passes it through untouched —
+ * none of its phrase branches ("closed", "tick", …) may reinterpret a
+ * transport message that happens to contain one of those words.
+ */
+export class OrderOutcomeUnknownError extends Error {
+  constructor(message: string, readonly cause: unknown) {
+    super(message);
+    this.name = "OrderOutcomeUnknownError";
+  }
+}
+
 /** Map CLOB errors to actionable guidance. Exported for unit tests. */
 export async function mapClobError(err: unknown): Promise<string> {
+  if (err instanceof OrderOutcomeUnknownError) return err.message;
   const e = err as { message?: string; status?: number; data?: unknown };
   const dataText = e?.data ? ` — ${typeof e.data === "string" ? e.data : JSON.stringify(e.data)}` : "";
   const message = `${e?.message ?? String(err)}${dataText}`;
@@ -355,13 +396,22 @@ export interface TradeInput {
   post_only?: boolean;
   confirm?: boolean;
   agent_id?: string;
+  /**
+   * The worst fill the CALLER accepts, overriding the previewed bound. Market
+   * orders are held to the worst fill the last preview for this (token, side)
+   * showed (see previewedBounds); pass this to widen or tighten that bound
+   * explicitly. A walk that comes out worse than the bound in force is REFUSED
+   * before anything is signed, never silently signed at the new number. With
+   * neither a preview in this process nor this field, the walk stands on its
+   * own.
+   */
+  max_fill_price?: number;
+  /** See SpendGate. Supplied by the tool handler; absent in direct/unit use. */
+  askUser?: SpendGate;
 }
 
-export interface ToolResult {
-  text: string;
-  structured?: Record<string, unknown>;
-  isError?: boolean;
-}
+export type { ToolResult, SpendGate } from "./transactions.js";
+
 
 export async function executeTrade(input: TradeInput): Promise<ToolResult> {
   const side = input.action === "buy" ? Side.BUY : Side.SELL;
@@ -438,6 +488,34 @@ export async function executeTrade(input: TradeInput): Promise<ToolResult> {
         ? roundToTick(walk.worstPrice ?? (quote as number), tickSize, input.action)
         : undefined;
 
+      // The bound in force at a confirm: an explicit max_fill_price, else the
+      // worst fill the last preview for this (token, side) showed. A dry-run
+      // is the preview — it records its own walk below and is never bounded.
+      // Enforced BEFORE anything is signed. Buy: a worse fill is a HIGHER
+      // price; sell: a worse fill is a LOWER one.
+      const previewed = !isLimit && input.confirm === true ? previewedBounds.get(boundKey(token.tokenId, input.action)) : undefined;
+      const bound = input.max_fill_price ?? previewed?.worstFillPrice;
+      const boundSource = input.max_fill_price !== undefined ? "max_fill_price" : previewed ? "preview" : undefined;
+      if (!isLimit && input.confirm === true && bound !== undefined && worstFillPrice !== undefined) {
+        const worse = input.action === "buy" ? worstFillPrice > bound : worstFillPrice < bound;
+        if (worse) {
+          const dir = input.action === "buy" ? "above" : "below";
+          const ago = previewed && boundSource === "preview" ? ` (previewed ${Math.max(1, Math.round((Date.now() - previewed.at) / 1000))}s ago)` : "";
+          return {
+            text:
+              `The book moved since that quote: this order would fill at ${worstFillPrice} (${(worstFillPrice * 100).toFixed(1)}¢), ` +
+              `${dir} the ${bound} (${(bound * 100).toFixed(1)}¢) you were shown${ago}. Nothing was signed and nothing was charged. ` +
+              `Re-preview (the same call without confirm, or blockrun_polymarket_read action:"preview") to see the current ` +
+              `price and confirm again at the new figure, or pass max_fill_price yourself to set the bound you will accept.`,
+            isError: true,
+            structured: { refused: "worse_than_quoted", worstFillPrice, maxFillPrice: bound, boundSource, action: input.action },
+          };
+        }
+      }
+      // Past the guard, the order is still signed at THIS call's worst fill
+      // (below) — never looser than the bound, and never looser than the
+      // summary this call prints, which is what the agent relays to the user.
+
       const notional = isLimit
         ? (price as number) * (size as number)
         : input.action === "buy"
@@ -508,10 +586,21 @@ export async function executeTrade(input: TradeInput): Promise<ToolResult> {
         `  Tick ${tickSize} · negRisk ${negRisk} · min size ${minSize || "n/a"} · fees are taker-only`,
       ].join("\n");
 
-      // Dry-run: no confirm → preview only, nothing is signed.
+      // Dry-run: no confirm → preview only, nothing is signed. A market
+      // preview is the quote the confirm is held to: record its worst fill and
+      // say so, so the agent quoting "at most X" to the user is telling the
+      // truth across the two calls.
       if (input.confirm !== true) {
+        const boundNote = worstFillPrice !== undefined
+          ? `\nThe worst fill ${input.action === "buy" ? "≤" : "≥"} ${worstFillPrice} above is the limit the confirm is held to: ` +
+            `if the book moves past it before you confirm, the confirm is refused unsigned and you re-preview. ` +
+            `Pass max_fill_price to set a different bound.`
+          : "";
+        if (worstFillPrice !== undefined) {
+          previewedBounds.set(boundKey(token.tokenId, input.action), { worstFillPrice, at: Date.now() });
+        }
         return {
-          text: `DRY RUN — no order placed.\n${summary}\n\nRe-call with confirm:true to sign and submit.`,
+          text: `DRY RUN — no order placed.\n${summary}${boundNote}\n\nRe-call with confirm:true to sign and submit.`,
           structured: {
             dryRun: true,
             action: input.action,
@@ -579,29 +668,76 @@ export async function executeTrade(input: TradeInput): Promise<ToolResult> {
               orderKind === "FAK" ? OrderType.FAK : OrderType.FOK,
             );
 
+      // The SDK signs and posts; a throw with no 4xx behind it (dropped socket,
+      // client timeout, relay 502/504) arrives AFTER the order may have been
+      // accepted. Releasing the reservation and rendering it as a plain error
+      // steered the agent straight into a second real order while the session
+      // cap saw one. Keep the notional booked, count it as unconfirmed, and
+      // say what is and is not known — the relayer withdraw path and the order
+      // card already treat this failure class this way.
+      const outcomeUnknown = (cause: unknown): OrderOutcomeUnknownError => {
+        const raw = cause instanceof Error ? cause.message : String(cause);
+        const status = (cause as { status?: unknown } | undefined)?.status;
+        const check = isLimit
+          ? `run action:"orders" and look for a ${input.action} of ${size} @ ${price}`
+          : `run action:"positions" (a filled ${orderKind} shows up as a position; a killed one leaves nothing)`;
+        return new OrderOutcomeUnknownError(
+          `⚠️ Order outcome UNKNOWN — the CLOB did not answer${typeof status === "number" ? ` (HTTP ${status})` : ""}: ${raw}. ` +
+          `The signed ${input.action} MAY have been accepted and be live at the exchange. Do NOT re-place it yet: ` +
+          `${check} before retrying. The $${notional.toFixed(2)} stays booked against the session cap as unconfirmed ` +
+          `(it is not released — restart the server to reset the ledger once you have confirmed it is absent).`,
+          cause,
+        );
+      };
+      const submitOrUnknown = async (): Promise<unknown> => {
+        try {
+          return await submitOrder();
+        } catch (err) {
+          throw isDefiniteRejection(err) ? err : outcomeUnknown(err);
+        }
+      };
+
+      // The last word before a signature is the user's, when the operator
+      // asked for one (BLOCKRUN_CONFIRM_SPEND=on). Every guard above has
+      // passed, nothing is reserved yet, so a decline leaves no residue.
+      if (input.askUser) {
+        const what = `${input.action} ${token.outcome ? `"${token.outcome}"` : `token ${token.tokenId.slice(0, 12)}…`}`;
+        const gate = await input.askUser(notional, `polymarket · ${what} · ${isLimit ? `limit ${orderKind}` : `market ${orderKind}`}`);
+        if (!gate.ok) return declinedResult(`the ${what} order`);
+      }
+
       // Reserve now (before the await) so a concurrent order sees this spend;
-      // roll back if the submit throws so a failed order doesn't consume budget.
+      // roll back if the submit is definitely rejected so a failed order
+      // doesn't consume budget.
       reserveBet(notional, input.agent_id);
       let response: unknown;
       try {
         try {
-          response = await submitOrder();
+          response = await submitOrUnknown();
         } catch (submitErr) {
           // Funded + approved on-chain, but the CLOB's server-side balance cache
           // can lag reality — setup's warm-up refresh is best-effort and freshly
           // bridged pUSD takes a moment to register — so the exchange rejects a
           // fully-funded wallet with "not enough balance/allowance". Refresh the
           // cache for the traded asset and retry the submit ONCE before giving up
-          // (COLLATERAL for buys, the specific outcome token for sells).
-          if (!isBalanceAllowanceError(submitErr)) throw submitErr;
+          // (COLLATERAL for buys, the specific outcome token for sells). Only a
+          // definite rejection may take the retry — an unknown outcome whose
+          // raw text happens to mention balance must never be re-submitted on
+          // top of a possibly-live order. The refresh call is not an order, so
+          // its own failure is a plain error, never unknown.
+          if (submitErr instanceof OrderOutcomeUnknownError || !isBalanceAllowanceError(submitErr)) throw submitErr;
           await clob.updateBalanceAllowance(
             input.action === "buy"
               ? { asset_type: AssetType.COLLATERAL }
               : { asset_type: AssetType.CONDITIONAL, token_id: token.tokenId },
           );
-          response = await submitOrder();
+          response = await submitOrUnknown();
         }
       } catch (submitErr) {
+        if (submitErr instanceof OrderOutcomeUnknownError) {
+          ledger.unconfirmed += 1;
+          throw submitErr;
+        }
         releaseBet(notional, input.agent_id);
         throw submitErr;
       }
@@ -636,7 +772,8 @@ export async function executeTrade(input: TradeInput): Promise<ToolResult> {
           `  status: ${r?.status ?? "submitted"}${filled ? "" : " (resting in the book until filled or cancelled)"}`,
           ...(r?.errorMsg ? [`  note: ${r.errorMsg}`] : []),
           ...(r?.transactionsHashes?.length ? [`  tx: ${r.transactionsHashes.join(", ")}`] : []),
-          `  Session bets so far: $${ledger.totalUsd.toFixed(2)} across ${ledger.count} order(s).`,
+          `  Session bets so far: $${ledger.totalUsd.toFixed(2)} across ${ledger.count} order(s)` +
+            (ledger.unconfirmed ? ` plus ${ledger.unconfirmed} unconfirmed (outcome unknown — see action:"orders"/"positions").` : "."),
         ].join("\n"),
         structured: {
           orderID: r?.orderID,
@@ -652,7 +789,10 @@ export async function executeTrade(input: TradeInput): Promise<ToolResult> {
       };
     });
   } catch (err) {
-    return { text: await mapClobError(err), isError: true };
+    const structured = err instanceof OrderOutcomeUnknownError
+      ? { outcome: "unknown", action: input.action, session: getSessionLedger() }
+      : undefined;
+    return { text: await mapClobError(err), isError: true, ...(structured ? { structured } : {}) };
   }
 }
 
diff --git a/src/utils/polymarket/relayer.ts b/src/utils/polymarket/relayer.ts
index b5f0ee5..1633963 100644
--- a/src/utils/polymarket/relayer.ts
+++ b/src/utils/polymarket/relayer.ts
@@ -15,15 +15,82 @@ import { BuilderConfig } from "@polymarket/builder-signing-sdk";
 import { ClobClient } from "@polymarket/clob-client-v2";
 import { createWalletClient, http, type Hex } from "viem";
 import { polygon } from "viem/chains";
-import { getPolymarketAccount } from "./client.js";
+import { getClobProxyAgent, getPolymarketAccount, installUnderscoreHeaderBridge } from "./client.js";
 import { CLOB_HOST, POLYGON_CHAIN_ID, POLYGON_WRITE_RPC_URL, RELAYER_URL } from "./constants.js";
 import { loadBuilderCreds, loadL2Creds, saveBuilderCreds, saveL2Creds, saveState } from "./creds.js";
 import { deriveApiCreds } from "./l1-auth-1271.js";
+import { isDefiniteRejection } from "./transactions.js";
 
 export type { DepositWalletCall };
 
 let _relayClient: RelayClient | null = null;
 
+// --- stdout discipline ---
+//
+// The relayer SDK console.logs progress ("Waiting for transaction …",
+// "Executing … transactions", "… timing out!") from pollUntilState and the
+// batch builders. In the stdio MCP server stdout IS the JSON-RPC channel, so
+// every deploy, approval, redeem and withdraw batch injected a non-JSON line
+// into the protocol stream, mid-money-operation. The TS SDK client survives
+// (it reports the bad line via onerror); a stricter client drops the
+// connection and the user never receives the result text — the tx hash or the
+// anti-retry guidance. Every SDK call below runs inside quietStdout, which
+// points console.log/info at stderr (the MCP log channel) for its duration.
+// Ref-counted: tool calls are dispatched concurrently, and two overlapping
+// batches must not leave a swapped console behind when the first finishes.
+let quietDepth = 0;
+let savedLog: typeof console.log | null = null;
+let savedInfo: typeof console.info | null = null;
+
+async function quietStdout<T>(fn: () => Promise<T>): Promise<T> {
+  if (quietDepth++ === 0) {
+    savedLog = console.log;
+    savedInfo = console.info;
+    console.log = (...args: unknown[]) => console.error(...args);
+    console.info = (...args: unknown[]) => console.error(...args);
+  }
+  try {
+    return await fn();
+  } finally {
+    if (--quietDepth === 0) {
+      if (savedLog) console.log = savedLog;
+      if (savedInfo) console.info = savedInfo;
+      savedLog = null;
+      savedInfo = null;
+    }
+  }
+}
+
+/**
+ * The relayer SDK builds its OWN axios instance (`httpClient.instance`,
+ * axios 0.27), so neither the underscore-header bridge nor the
+ * POLYMARKET_CLOB_PROXY agent installed on the hoisted axios in client.ts ever
+ * reached relayer traffic — while the 403 advice and deploy.sh told operators
+ * to point POLYMARKET_RELAYER_URL at the Caddy relay, whose /relayer/* route
+ * reconstructs POLY_BUILDER_* from the hyphenated copies the client never
+ * sent. Install both here, on that instance, right after construction. The
+ * bridge is harmless direct (Polymarket reads the underscore header and
+ * ignores the copy); the agent only applies when the operator set a proxy.
+ */
+function bridgeRelayerTransport(client: RelayClient): void {
+  const instance = (client as unknown as { httpClient?: { instance?: {
+    interceptors?: { request?: { use?: (fn: (config: unknown) => unknown) => void } };
+    defaults?: { httpsAgent?: unknown; proxy?: unknown };
+  } } }).httpClient?.instance;
+  if (!instance?.interceptors?.request?.use || !instance.defaults) {
+    // SDK shape drifted: say so on stderr rather than fail the money path —
+    // direct relayer traffic still works; only a relayed/proxied setup would not.
+    console.error("[BlockRun] relayer SDK exposes no axios instance — header bridge / POLYMARKET_CLOB_PROXY not applied to relayer traffic");
+    return;
+  }
+  installUnderscoreHeaderBridge(instance as never);
+  const agent = getClobProxyAgent();
+  if (agent) {
+    instance.defaults.httpsAgent = agent;
+    instance.defaults.proxy = false;
+  }
+}
+
 /**
  * Programmatically obtain Builder API credentials (key/secret/passphrase) for
  * the local wallet — created via the CLOB createBuilderApiKey() (L2-authed),
@@ -77,7 +144,9 @@ export async function getRelayClient(): Promise<RelayClient> {
   });
   const builderCreds = await getOrCreateBuilderCreds();
   const builderConfig = new BuilderConfig({ localBuilderCreds: builderCreds });
-  _relayClient = new RelayClient(RELAYER_URL, POLYGON_CHAIN_ID, walletClient, builderConfig);
+  const client = new RelayClient(RELAYER_URL, POLYGON_CHAIN_ID, walletClient, builderConfig);
+  bridgeRelayerTransport(client);
+  _relayClient = client;
   return _relayClient;
 }
 
@@ -97,8 +166,11 @@ export async function isDepositWalletDeployed(address: string): Promise<boolean>
  * relayer transaction id on failure/timeout so the user can re-run setup.
  */
 export async function deployDepositWallet(): Promise<{ transactionHash?: string }> {
-  const response = await (await getRelayClient()).deployDepositWallet();
-  const confirmed = await response.wait();
+  const relay = await getRelayClient();
+  const { response, confirmed } = await quietStdout(async () => {
+    const response = await relay.deployDepositWallet();
+    return { response, confirmed: await response.wait() };
+  });
   if (!confirmed) {
     throw new Error(
       `Deposit wallet deployment did not confirm (relayer tx ${response.transactionID}). ` +
@@ -117,7 +189,8 @@ const TERMINAL_FAILURE_STATES = ["STATE_FAILED", "STATE_INVALID"];
 /** Current relayer-side state of a submitted batch, or undefined if unreachable. */
 export async function getRelayerTransactionState(transactionID: string): Promise<string | undefined> {
   try {
-    const txns = await (await getRelayClient()).getTransaction(transactionID);
+    const relay = await getRelayClient();
+    const txns = await quietStdout(() => relay.getTransaction(transactionID));
     return txns?.[0]?.state;
   } catch {
     return undefined;
@@ -149,8 +222,15 @@ export async function sendWalletBatch(
 ): Promise<{ transactionHash?: string }> {
   const deadlineSec = Math.floor(Date.now() / 1000) + BATCH_DEADLINE_SECS;
   let response: Awaited<ReturnType<RelayClient["executeDepositWalletBatch"]>>;
+  // Getting the client is NOT part of the send. getRelayClient derives CLOB
+  // credentials and creates a builder key — real network calls that happen
+  // before the RelayClient exists, so they cannot have signed or posted the
+  // batch. Leaving them inside the try armed the double-send guard for a
+  // failure that provably moved nothing, wedging the user behind a deadline
+  // for a transfer that was never signed.
+  const relay = await getRelayClient();
   try {
-    response = await (await getRelayClient()).executeDepositWalletBatch(calls, depositWallet, String(deadlineSec));
+    response = await quietStdout(() => relay.executeDepositWalletBatch(calls, depositWallet, String(deadlineSec)));
   } catch (err) {
     // The SDK signs, THEN posts. A lost response (proxy 502/504, reset — the
     // SDK surfaces these as `{"error":"connection error"}` or a 5xx "request
@@ -164,8 +244,12 @@ export async function sendWalletBatch(
     // clear it (withdraw.ts). Untracked batches (approvals, wrap) are safe to
     // retry and rethrow as before.
     const message = err instanceof Error ? err.message : String(err);
-    const definitelyRejected = /"status":4\d\d/.test(message);
-    if (opts?.trackPendingWithdraw && !definitelyRejected) {
+    // The CLOB SDK's ApiError carries its code on a `.status` PROPERTY and
+    // leaves the message as the bare error string, so matching only the JSON
+    // shape missed every definite 4xx it raises — the guard armed on rejections
+    // that were unambiguous. isDefiniteRejection reads the property first,
+    // then the shapes that only appear in text (shared with the order submit).
+    if (opts?.trackPendingWithdraw && !isDefiniteRejection(err)) {
       saveState({ pendingWithdraw: { transactionID: "unknown", deadline: deadlineSec } });
       throw new Error(
         `${description}: the relayer returned no transaction id (${message}). It may still have ACCEPTED the ` +
@@ -179,7 +263,7 @@ export async function sendWalletBatch(
   if (opts?.trackPendingWithdraw) {
     saveState({ pendingWithdraw: { transactionID: response.transactionID, deadline: deadlineSec } });
   }
-  const confirmed = await response.wait();
+  const confirmed = await quietStdout(() => response.wait());
   if (!confirmed) {
     const state = await getRelayerTransactionState(response.transactionID);
     if (state && TERMINAL_FAILURE_STATES.includes(state)) {
diff --git a/src/utils/polymarket/setup.ts b/src/utils/polymarket/setup.ts
index 85630eb..2147f62 100644
--- a/src/utils/polymarket/setup.ts
+++ b/src/utils/polymarket/setup.ts
@@ -225,17 +225,40 @@ function approvalChecklist(items: ApprovalItem[]): string {
   return items.map((i) => `  ${i.granted ? "✅" : "❌"} ${i.label}`).join("\n");
 }
 
-async function geoblockLine(): Promise<string> {
+/**
+ * The region check, as a report line AND as a verdict. `ready` below has to
+ * see the verdict: a blocked egress used to print "❌ Region: order placement
+ * BLOCKED" and, two lines later, "🎯 Ready to trade" with structured
+ * ready:true — the fields an agent keys on before funding — so the user
+ * funded a vault it could not trade from. "unknown" is a best-effort probe
+ * that failed, not a blocker; it is reported as such.
+ */
+async function geoblockLine(): Promise<{ line: string; orderPlacement: "permitted" | "blocked" | "unknown" }> {
   const geo = await checkGeoblock();
   const where = geo.country ? ` (egress country: ${geo.country})` : "";
-  if (geo.orderPlacement === "permitted") return `✅ Region: order placement permitted from this egress${where}`;
+  if (geo.orderPlacement === "permitted") {
+    return { orderPlacement: "permitted", line: `✅ Region: order placement permitted from this egress${where}` };
+  }
   if (geo.orderPlacement === "blocked") {
-    return `❌ Region: order placement BLOCKED from this egress${where}. ` +
-      "Point POLYMARKET_CLOB_HOST + POLYMARKET_RELAYER_URL at a permitted-region relay " +
-      "(see deploy/finland-egress) or restore the default. A proxy alone (POLYMARKET_CLOB_PROXY / " +
-      "HTTPS_PROXY) only changes how the current egress is reached, not the Polymarket-facing IP.";
+    return {
+      orderPlacement: "blocked",
+      line: `❌ Region: order placement BLOCKED from this egress${where}. ` +
+        "Point POLYMARKET_CLOB_HOST + POLYMARKET_RELAYER_URL at a permitted-region relay " +
+        "(see deploy/finland-egress) or restore the default. A proxy alone (POLYMARKET_CLOB_PROXY / " +
+        "HTTPS_PROXY) only changes how the current egress is reached, not the Polymarket-facing IP.",
+    };
   }
-  return "ℹ️ Region: could not determine order-placement status (check re-runs on demand)";
+  return { orderPlacement: "unknown", line: "ℹ️ Region: could not determine order-placement status (check re-runs on demand)" };
+}
+
+/** The closing verdict line: green only when nothing blocks an order. */
+function readyLine(ready: boolean, orderPlacement: "permitted" | "blocked" | "unknown", readyText: string): string {
+  if (ready) return readyText;
+  if (orderPlacement === "blocked") {
+    return `⛔ NOT ready: order placement is blocked from this egress (see ❌ Region above). ` +
+      `Do not fund the wallet for trading until setup reports the region as permitted.`;
+  }
+  return `Re-run action:"setup" after completing the ❌ items.`;
 }
 
 const KEY_BACKUP_NOTE =
@@ -358,7 +381,8 @@ async function runSetupDepositWallet(opts: { confirm: boolean }): Promise<{ text
   }
 
   const geo = await geoblockLine();
-  const ready = deployed && balance > 0 && !approvalsPending && credsReady;
+  const boundedApprovalUsd = getBoundedApprovalsUsd();
+  const ready = deployed && balance > 0 && !approvalsPending && credsReady && geo.orderPlacement !== "blocked";
 
   const lines = [
     `Polymarket setup — deposit-wallet mode (POLY_1271)`,
@@ -383,7 +407,26 @@ async function runSetupDepositWallet(opts: { confirm: boolean }): Promise<{ text
           ``,
           `   ${missing.length} approval(s) needed. This authorizes Polymarket's exchange`,
           `   contracts to settle YOUR signed orders from the deposit wallet (gasless`,
-          `   batch via the relayer). Re-run action:"setup" with confirm:true to sign.`,
+          `   batch via the relayer).`,
+          // Say the SIZE of the grant, not only its purpose. The default is an
+          // unlimited pUSD allowance to four spenders plus all-or-nothing
+          // ERC-1155 operator rights to five — standard for Polymarket, and
+          // exactly the kind of thing to state BEFORE the signature rather than
+          // after. POLYMARKET_BOUNDED_APPROVALS has existed all along; nothing
+          // surfaced it at the moment of consent.
+          ...(boundedApprovalUsd === null
+            ? [
+                `   Amount: UNLIMITED pUSD allowance (the Polymarket default) to the four`,
+                `   collateral spenders, plus operator rights on your outcome tokens to five`,
+                `   contracts. Set POLYMARKET_BOUNDED_APPROVALS=<usd> to cap the pUSD side`,
+                `   instead (the ERC-1155 operator grant is all-or-nothing either way).`,
+              ]
+            : [
+                `   Amount: pUSD allowance capped at $${boundedApprovalUsd.toFixed(2)} per spender`,
+                `   (POLYMARKET_BOUNDED_APPROVALS), plus operator rights on your outcome`,
+                `   tokens, which are all-or-nothing.`,
+              ]),
+          `   Re-run action:"setup" with confirm:true to sign.`,
         ]
       : []),
     ...(approvalsUnverified
@@ -398,9 +441,9 @@ async function runSetupDepositWallet(opts: { confirm: boolean }): Promise<{ text
     ...(balanceCacheWarned
       ? [`   ⚠️ Balance cache not pre-warmed (${balanceCacheWarned}) — your first buy refreshes it automatically.`]
       : []),
-    geo,
+    geo.line,
     ``,
-    ready ? `🎯 Ready to trade. Discover markets with blockrun_markets, then action:"buy".` : `Re-run action:"setup" after completing the ❌ items.`,
+    readyLine(ready, geo.orderPlacement, `🎯 Ready to trade. Discover markets with blockrun_markets, then action:"buy".`),
     ``,
     KEY_BACKUP_NOTE,
   ];
@@ -418,6 +461,7 @@ async function runSetupDepositWallet(opts: { confirm: boolean }): Promise<{ text
       ...(approvalsTxHash ? { approvalsTxHash } : {}),
       ...(approvalsUnverified ? { approvalsUnverified: true } : {}),
       credsReady,
+      orderPlacement: geo.orderPlacement,
       ready,
     },
   };
@@ -497,7 +541,7 @@ async function runSetupEoa(opts: { confirm: boolean }): Promise<{ text: string;
   }
 
   const geo = await geoblockLine();
-  const ready = balance > 0 && !approvalsPending && credsReady;
+  const ready = balance > 0 && !approvalsPending && credsReady && geo.orderPlacement !== "blocked";
 
   const lines = [
     `Polymarket setup — plain EOA mode (POLYMARKET_SIG_TYPE=0)`,
@@ -522,12 +566,14 @@ async function runSetupEoa(opts: { confirm: boolean }): Promise<{ text: string;
         ]
       : []),
     `${credsReady ? "✅" : "❌"} CLOB API credentials${credsNote}`,
-    geo,
+    geo.line,
     ``,
-    ready
-      ? `🎯 Ready to trade. Note: the CLOB may reject plain-EOA makers on order placement — ` +
-        `the deposit wallet (unset POLYMARKET_SIG_TYPE) is the supported trading path.`
-      : `Re-run action:"setup" after completing the ❌ items.`,
+    readyLine(
+      ready,
+      geo.orderPlacement,
+      `🎯 Ready to trade. Note: the CLOB may reject plain-EOA makers on order placement — ` +
+        `the deposit wallet (unset POLYMARKET_SIG_TYPE) is the supported trading path.`,
+    ),
     ``,
     KEY_BACKUP_NOTE,
   ];
@@ -544,6 +590,7 @@ async function runSetupEoa(opts: { confirm: boolean }): Promise<{ text: string;
       ...(approvalTxHashes.length ? { approvalTxHashes } : {}),
       ...(approvalsUnverified ? { approvalsUnverified: true } : {}),
       credsReady,
+      orderPlacement: geo.orderPlacement,
       ready,
     },
   };
diff --git a/src/utils/polymarket/transactions.ts b/src/utils/polymarket/transactions.ts
index 3ee8c4e..dd247eb 100644
--- a/src/utils/polymarket/transactions.ts
+++ b/src/utils/polymarket/transactions.ts
@@ -32,3 +32,53 @@ export function assertTransactionSucceeded(
     );
   }
 }
+
+/**
+ * True when a thrown submit error PROVES the counterparty accepted nothing: a
+ * 4xx, read off the CLOB SDK's ApiError `.status` property first (its message
+ * is the bare error string), then off the JSON/HTTP shapes that only appear in
+ * text (the relayer SDK stringifies `{"error":"request error","status":4xx}`).
+ * Anything else — no status at all (socket hang up, ECONNRESET, a client-side
+ * timeout) or a 5xx (a relay 502/504 after the upstream POST landed) — is
+ * outcome-unknown: the signed order/batch may already be live. One answer for
+ * the CLOB submit (orders.ts) and the relayer batch (relayer.ts), so the two
+ * money paths cannot drift apart on the question again.
+ */
+export function isDefiniteRejection(err: unknown): boolean {
+  const status = (err as { status?: unknown } | undefined)?.status;
+  if (typeof status === "number") return status >= 400 && status < 500;
+  const message = err instanceof Error ? err.message : String(err);
+  return /"status":4\d\d/.test(message) || /\b(?:HTTP|status(?:\s*code)?)\s*[:=]?\s*4\d\d\b/i.test(message);
+}
+
+/** The shape every Polymarket action returns to the tool handler. */
+export interface ToolResult {
+  text: string;
+  structured?: Record<string, unknown>;
+  isError?: boolean;
+}
+
+/**
+ * The human-in-the-loop gate (utils/confirm-spend.ts confirmSpend, bound to
+ * the MCP server by the tool handler). `confirm:true` is a boolean the MODEL
+ * supplies; with BLOCKRUN_CONFIRM_SPEND=on the operator asked for a dialog
+ * before money moves, and a $0.004 rpc call got one while a $25 bet did not.
+ * Called once, after every pre-sign guard has passed and before anything is
+ * signed, with the notional and a label naming the action. Resolves
+ * { ok:false } only on an explicit decline; off/unsupported/cancel proceed.
+ */
+export type SpendGate = (usd: number, label: string) => Promise<{ ok: boolean; reason?: string }>;
+
+/**
+ * The result every money path returns when the user declines at the dialog.
+ * isError so the order card never renders it as "Order submitted"; the
+ * "nothing was charged" wording is what the card's re-arm predicate
+ * (apps/order-safety.ts) keys on to restore its pre-click state.
+ */
+export function declinedResult(what: string): ToolResult {
+  return {
+    text: `Declined at the confirmation prompt — ${what} was not signed. Nothing was signed and nothing was charged.`,
+    isError: true,
+    structured: { declined: true },
+  };
+}
diff --git a/src/utils/polymarket/withdraw.ts b/src/utils/polymarket/withdraw.ts
index cc74ea9..9a72cf7 100644
--- a/src/utils/polymarket/withdraw.ts
+++ b/src/utils/polymarket/withdraw.ts
@@ -36,7 +36,7 @@ import {
 } from "./constants.js";
 import { getPolymarketAccount } from "./client.js";
 import { assertTransactionSucceeded } from "./transactions.js";
-import type { ToolResult } from "./orders.js";
+import { declinedResult, type SpendGate, type ToolResult } from "./transactions.js";
 import { getFundsAddress } from "./positions.js";
 import { loadState, saveState } from "./creds.js";
 import { getRelayerTransactionState, sendWalletBatch } from "./relayer.js";
@@ -124,6 +124,8 @@ interface WithdrawInput {
   amount_usd?: number;
   to_address?: string;
   confirm?: boolean;
+  /** See orders.ts SpendGate. Supplied by the tool handler. */
+  askUser?: SpendGate;
 }
 
 export async function withdrawFunds(input: WithdrawInput): Promise<ToolResult> {
@@ -226,6 +228,15 @@ export async function withdrawFunds(input: WithdrawInput): Promise<ToolResult> {
       };
     }
 
+    // The user's word before anything is signed, when the operator asked for
+    // it (BLOCKRUN_CONFIRM_SPEND=on). The amount is the one that will move —
+    // the full balance when amount_usd was omitted — and the label carries the
+    // destination, since a custom to_address is the irreversible part.
+    if (input.askUser) {
+      const gate = await input.askUser(amountUsd, `polymarket · withdraw $${amountUsd.toFixed(2)} → ${recipient}${isCustom ? " (CUSTOM address)" : " (your agent wallet)"}`);
+      if (!gate.ok) return declinedResult(`the $${amountUsd.toFixed(2)} withdrawal`);
+    }
+
     // 0. Sweep legacy USDC.e → pUSD when the pUSD on hand can't cover the
     //    amount. Wrapping keeps funds in the SAME wallet (a re-run after a
     //    partial failure is safe), so this batch is not double-spend-tracked.
diff --git a/src/utils/raw-call.ts b/src/utils/raw-call.ts
index 67b73d8..d3d8a3d 100644
--- a/src/utils/raw-call.ts
+++ b/src/utils/raw-call.ts
@@ -1,7 +1,7 @@
 // src/utils/raw-call.ts
 //
-// One entry point for the path-based tools (search, exa, surf, markets, rpc,
-// defi, phone, modal), so each of them stops choosing a rail for itself.
+// One entry point for the path-based tools (search, exa, markets, rpc, defi,
+// phone, modal), so each of them stops choosing a rail for itself.
 //
 // WHY THIS EXISTS RATHER THAN "just call the SDK". On the account rail there is
 // no x402 to perform: no quote to read, nothing to sign, no retry-after-payment.
@@ -17,13 +17,57 @@
 
 import { isApiKeyMode } from "./auth.js";
 import { apiKeyGet, apiKeyPost } from "./api-key-call.js";
+import { getChain } from "./wallet.js";
+import { OBSERVED_GATEWAY_TX_FEE_USD, TRANSACTION_FEE_USD } from "./tx-fee.js";
 
 /** The two raw methods every path-based tool already depends on. */
 export type RawClient = {
   getWithPaymentRaw: (endpoint: string, params?: Record<string, string>) => Promise<unknown>;
   requestWithPaymentRaw: (endpoint: string, body: unknown) => Promise<unknown>;
+  /** The SDK's cumulative settlement counter (throws on the account rail). Optional for stubs. */
+  getSpending?: () => { totalUsd: number };
 };
 
+/**
+ * The SDK call threw AFTER its own counter recorded a settlement. Both wallet
+ * clients count on the paid retry's 2xx and only then read the body
+ * (SolanaLLMClient.requestWithPaymentRaw: assertPaid → recordSettlement →
+ * json()), so a non-JSON 200 surfaces as a bare SyntaxError — no status, no
+ * transport words, "none" to settlementOnThrow — for a call that was paid.
+ * The counter is the evidence, and this carries it to the tool's catch.
+ */
+export class RawCallSettledError extends Error {
+  readonly settledUsd: number;
+  constructor(message: string, settledUsd: number, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "RawCallSettledError";
+    this.settledUsd = settledUsd;
+  }
+}
+
+function counted(client: RawClient): number | undefined {
+  try {
+    const usd = client.getSpending?.().totalUsd;
+    return typeof usd === "number" && Number.isFinite(usd) ? usd : undefined;
+  } catch {
+    return undefined; // the account rail's client throws here; it never reaches this path
+  }
+}
+
+/** Run the SDK call; a throw after the counter moved is re-thrown as RawCallSettledError. */
+async function countedCall<T>(client: RawClient, run: () => Promise<T>): Promise<T> {
+  const before = counted(client);
+  try {
+    return await run();
+  } catch (err) {
+    const after = counted(client);
+    if (before !== undefined && after !== undefined && after - before > 0) {
+      throw new RawCallSettledError(err instanceof Error ? err.message : String(err), after - before, { cause: err });
+    }
+    throw err;
+  }
+}
+
 export interface RawCallResult {
   data: unknown;
   /**
@@ -48,7 +92,7 @@ export async function rawGet(
     const { data, paidUsd } = await apiKeyGet(endpoint, params);
     return { data, paidUsd };
   }
-  return { data: await client.getWithPaymentRaw(endpoint, params), paidUsd: null };
+  return { data: await countedCall(client, () => client.getWithPaymentRaw(endpoint, params)), paidUsd: null };
 }
 
 /** POST a rooted endpoint on whichever rail is active. */
@@ -61,5 +105,40 @@ export async function rawPost(
     const { data, paidUsd } = await apiKeyPost(endpoint, (body ?? {}) as Record<string, unknown>);
     return { data, paidUsd };
   }
-  return { data: await client.requestWithPaymentRaw(endpoint, body), paidUsd: null };
+  return { data: await countedCall(client, () => client.requestWithPaymentRaw(endpoint, body)), paidUsd: null };
+}
+
+/**
+ * What to BOOK when the rail reports no settled figure.
+ *
+ * The gate and the ledger are deliberately different numbers — tx-fee.ts says
+ * so at length — and until now exactly one file honoured it. Every path tool
+ * passed its RESERVE (base + TRANSACTION_FEE_USD, 0.002, rounded against us on
+ * purpose) as recordActualSpend's fallback, and on the wallet rail there is
+ * never a settled figure to override it, so the ledger booked the reserve.
+ *
+ * Measured with unauthenticated 402 probes on 2026-09-09, no payment header:
+ *
+ *   route                     reserved   Base charge   Solana charge
+ *   rpc/ethereum (single)     $0.0040    $0.0030       $0.0020
+ *   pm/*                      $0.0095    $0.0085       $0.0075
+ *   phone/lookup              $0.0120    $0.0110       $0.0100
+ *   search (max_results=10)   $0.2645    $0.2635       $0.2625
+ *
+ * On Solana — the default chain since 0.46.0 — that is $0.002 of invented spend
+ * per call: an agent capped at $1.00 making only rpc calls was cut off after 250
+ * of them having actually spent $0.50, and action:"report" showed $1.00. The
+ * account rail bills the base with no fee at all.
+ *
+ * Reserving high stays. This only converts a reserve into what the gateway is
+ * observed to charge, for the LEDGER.
+ */
+export function ledgerFallback(reservedUsd: number): number {
+  if (!(reservedUsd > 0)) return 0;
+  // withTxFee() adds exactly one fee, whatever the route's per-element maths.
+  const base = Math.max(0, reservedUsd - TRANSACTION_FEE_USD);
+  if (isApiKeyMode() || getChain() === "solana") return base;
+  // Never book more than was reserved. Structural, not incidental: a reserve
+  // smaller than one fee would otherwise book a fee with no base under it.
+  return Math.min(reservedUsd, base + OBSERVED_GATEWAY_TX_FEE_USD);
 }
diff --git a/src/utils/solana-402.ts b/src/utils/solana-402.ts
index 2213cac..50d67d9 100644
--- a/src/utils/solana-402.ts
+++ b/src/utils/solana-402.ts
@@ -1,11 +1,30 @@
 // src/utils/solana-402.ts
 // Manual x402 payment flow against the Solana gateway (sol.blockrun.ai) for
-// paid endpoints the SolanaLLMClient doesn't expose as public methods yet:
-// image generation (solanaPaidPost, synchronous optimistic settle) and video
-// (solanaPaidAsyncPost, payment-on-completion polling). Music and speech are
-// candidates once their Solana routes ship. Mirrors the music.ts manual-402
-// pattern on Base, but signs an SPL transfer via createSolanaPaymentPayload
-// instead of an EIP-3009 authorization.
+// paid endpoints the SolanaLLMClient doesn't expose as public methods:
+// solanaPaidPost for the routes that answer inline (image, speech, realface —
+// synchronous optimistic settle) and solanaPaidAsyncPost for the async ones
+// (video, music — submit + poll). Mirrors the manual-402 pattern the tools use
+// on Base, but signs an SPL transfer via createSolanaPaymentPayload instead of
+// an EIP-3009 authorization.
+//
+// Two settlement models share solanaPaidAsyncPost, and the gateway tells us
+// which one a route follows on the submit answer:
+//
+//   payment-on-completion (video)  the POST verifies and enqueues; the charge
+//                                  happens on the poll that observes
+//                                  "completed", with the signature it carries.
+//                                  A failed job is not charged.
+//   settled-at-submit (music)      the POST settles the transfer optimistically
+//                                  the moment it is accepted (202 with
+//                                  payment_status "settled_optimistic" and the
+//                                  X-Payment-Optimistic header; blockrun-sol
+//                                  audio/generations/route.ts). The polls are
+//                                  pure delivery, so a failed job, a deadline
+//                                  or a poll error is a CERTAIN charge.
+//
+// Until audit round 3 the helper assumed the first model for every route and
+// said "No payment was taken" for a failed music job the gateway had already
+// settled.
 import {
   SolanaLLMClient,
   PaymentError,
@@ -17,9 +36,10 @@ import {
   SOLANA_NETWORK,
 } from "@blockrun/llm";
 import { fetchWithTimeout } from "./http.js";
-import { pollTimeoutFor } from "./poll.js";
+import { JobFailedError, pollTimeoutFor } from "./poll.js";
 import { resolveSolanaKey } from "./wallet.js";
 import { amountToUsd } from "./budget.js";
+import { BilledJobError } from "./api-key-call.js";
 
 const QUOTE_TIMEOUT_MS = 15_000;
 
@@ -38,9 +58,12 @@ const QUOTE_TIMEOUT_MS = 15_000;
 // keeps the worst case near 40s. The poll GET itself is capped at the Solana
 // poll route's own maxDuration (60s) rather than Base's 90s: a stalled poll
 // is the one place the signature ages without a re-sign, and the gateway
-// can't answer past 60s anyway. Submit gets Base's 30s — the gateway verifies
-// and enqueues in 3-20s, and a 300s hold here was silently adding five
-// minutes to the "15 min hard cap" the tool description promises.
+// can't answer past 60s anyway. Submit gets Base's 30s — the VIDEO gateway
+// verifies and enqueues in 3-20s, and a 300s hold here was silently adding
+// five minutes to the "15 min hard cap" the tool description promises. It is
+// a default, not a rule: the audio route holds the paid POST inline for up to
+// 60s and settles at POST regardless, so a 30s abort there was a charged track
+// with no job id (C15) — music.ts passes its own submitTimeoutMs.
 export const SOLANA_ASYNC_DEFAULT_BUDGET_MS = 900_000;
 export const SOLANA_ASYNC_POLL_INTERVAL_MS = 5_000;
 export const SOLANA_ASYNC_SUBMIT_TIMEOUT_MS = 30_000;
@@ -52,12 +75,19 @@ export const SOLANA_ASYNC_RESIGN_RETRY_MS = 10_000;
 export const SOLANA_ASYNC_MAX_REACTIVE_RESIGNS = 3;
 
 // Settle-failure reasons the Solana gateway itself treats as permanent for the
-// presented authorization (mirrors PERMANENT_ERRORS in the gateway's
-// x402-solana.ts). Anything else on a poll 402 — stale blockhash, a concurrent
-// settle claim, a facilitator hiccup — is the gateway's documented "re-sign
-// and re-poll" path and must not be reported as a funding problem.
-const PERMANENT_SETTLE_PATTERNS = [
-  "insufficient",
+// presented authorization (together they mirror PERMANENT_ERRORS in the
+// gateway's x402-solana.ts). Anything else on a poll 402 — stale blockhash, a
+// concurrent settle claim, a facilitator hiccup — is the gateway's documented
+// "re-sign and re-poll" path and must not be reported as a funding problem.
+//
+// The permanent set is split by REMEDY. Only "insufficient" is the wallet; the
+// rest are the signature or the authorization, and a user whose payload was
+// malformed or whose authorization expired was being told to fund a wallet
+// that had plenty in it — and, on Base, handed a Coinbase top-up page — because
+// the one message said "rejected … balance" and every tool's catch keyed on
+// those words (audit round 3, D2).
+const FUNDING_SETTLE_PATTERNS = ["insufficient"];
+const INVALID_AUTH_SETTLE_PATTERNS = [
   "invalid signature",
   "invalid payment",
   "unauthorized",
@@ -65,10 +95,70 @@ const PERMANENT_SETTLE_PATTERNS = [
   "invalid_payload",
   "expired",
 ];
-function isPermanentSettleFailure(reason: string | undefined): boolean {
+function matches(reason: string | undefined, patterns: string[]): boolean {
   if (!reason) return false;
   const lower = reason.toLowerCase();
-  return PERMANENT_SETTLE_PATTERNS.some((p) => lower.includes(p));
+  return patterns.some((p) => lower.includes(p));
+}
+const isFundingFailure = (reason: string | undefined) => matches(reason, FUNDING_SETTLE_PATTERNS);
+const isInvalidAuthFailure = (reason: string | undefined) => matches(reason, INVALID_AUTH_SETTLE_PATTERNS);
+
+/**
+ * The error for a 402 that came back on a request CARRYING the signature. A
+ * funding reason (or no reason at all — the gateway's verification 402 does
+ * not always carry PAYMENT-RESPONSE) is a PaymentError, which the tools turn
+ * into "out of funds" plus the top-up note. An authorization reason is a plain
+ * Error whose text deliberately contains none of "rejected" / "balance" /
+ * "insufficient" — isPaymentRejectionError (utils/errors.ts) keys on exactly
+ * those — and does contain "no charge was made", which formatError honours.
+ */
+function paidRequestRefused(reason: string | undefined, where: string, tail = ""): Error {
+  if (reason && isInvalidAuthFailure(reason) && !isFundingFailure(reason)) {
+    return new Error(
+      `The Solana gateway refused the payment signature ${where} (reason: ${reason}) — a signing/authorization fault, not a funding problem. ` +
+        `No charge was made.${tail ? ` ${tail}` : ""}`,
+    );
+  }
+  // statusCode 402: the refusal is an ANSWER (realface maps it to its 402
+  // branch; the in-flight tracker reads it as settled), and only this one —
+  // the authorization fault above carries no status on purpose, so nothing
+  // downstream can read it as a funding problem.
+  return Object.assign(
+    new PaymentError(`Payment was rejected${reason ? ` (${reason})` : ""}. Check your Solana USDC balance.${tail ? ` ${tail}` : ""}`),
+    { statusCode: 402 },
+  );
+}
+
+/**
+ * The key, or the honest reason there is none. Two reasons, two remedies:
+ * a keychain that would not open is NOT a missing wallet — the wallet is very
+ * likely there and funded, and "run setup" invites a second one. 783cfb3
+ * taught buildSolanaClient (wallet.ts) that distinction and left the manual-402
+ * helpers saying the old thing (audit round 3, D3/D30). Neither is a
+ * PaymentError: image's catch turns one into "your wallet is out of funds".
+ *
+ * solanaKeyUnavailableReason is imported dynamically so the handler suites
+ * that mock utils/wallet.js by name (and predate it) keep linking — image.ts
+ * imports this module statically. Only the failure path pays for the import.
+ */
+async function requireSolanaKey(): Promise<string> {
+  // resolveSolanaKey, not the SDK's file-only loader: under
+  // BLOCKRUN_KEYCHAIN=strict the .solana-session file is retired once its key
+  // is in the OS keychain, and getChain() still reports "solana" for it.
+  const privateKey = resolveSolanaKey();
+  if (privateKey) return privateKey;
+  const { solanaKeyUnavailableReason } = await import("./wallet.js");
+  const locked = solanaKeyUnavailableReason?.();
+  if (locked) {
+    throw new Error(
+      `Cannot reach your Solana wallet key — ${locked}. Your existing wallet is most likely still in the keychain: ` +
+        `unlock it and retry, or set SOLANA_WALLET_KEY. Nothing was charged.`,
+    );
+  }
+  throw new Error(
+    `No Solana wallet on this machine yet. Run blockrun_wallet action:"setup" (or action:"chain" chain:"solana") to create one, ` +
+      `or set SOLANA_WALLET_KEY. Nothing was charged.`,
+  );
 }
 
 /** errorReason from a base64 x402 PAYMENT-RESPONSE header, when present and well-formed. */
@@ -93,7 +183,26 @@ export interface SolanaPaidPostResult {
   jobId?: string;
 }
 
-export interface SolanaPaidAsyncPostOptions {
+/**
+ * The two hooks that mark the edges of every request CARRYING the payment.
+ * Offered by both helpers so a tool's in-flight tracker (utils/in-flight.ts)
+ * can be armed at the true signing point and settled on every answer, instead
+ * of guessing from onQuote — which fires before the transfer is signed, so a
+ * signing-time RPC failure read as "may have settled".
+ */
+export interface PaidRequestHooks {
+  /**
+   * Invoked immediately before a request carrying PAYMENT-SIGNATURE is sent:
+   * the submit, and (async) every paid poll. Never around the unpaid quote or
+   * the unpaid re-sign challenge. A request that is sent and never answered
+   * leaves this as the last hook that fired — which is the point.
+   */
+  onPaidRequest?: () => void;
+  /** Invoked the moment such a request has an answer — any status, before it is inspected. */
+  onPaidResponse?: () => void;
+}
+
+export interface SolanaPaidAsyncPostOptions extends PaidRequestHooks {
   /**
    * Total wall time allowed for quote + submit + polling, measured from the
    * call's entry. Defaults to SOLANA_ASYNC_DEFAULT_BUDGET_MS (15 minutes).
@@ -101,8 +210,23 @@ export interface SolanaPaidAsyncPostOptions {
   pollBudgetMs?: number;
   /** Delay between idempotent poll GETs. Defaults to SOLANA_ASYNC_POLL_INTERVAL_MS. */
   pollIntervalMs?: number;
-  /** Timeout for the single paid submit POST. Defaults to SOLANA_ASYNC_SUBMIT_TIMEOUT_MS. */
+  /**
+   * Timeout for the single paid submit POST. Defaults to
+   * SOLANA_ASYNC_SUBMIT_TIMEOUT_MS, which is sized for the video route (verify
+   * + enqueue, always 202 in 3-20s). A route that holds the paid POST inline —
+   * the audio route races generation against a 60s window and settles at
+   * POST regardless — needs its own, larger value (music.ts).
+   */
   submitTimeoutMs?: number;
+  /**
+   * Sentence subject for every error this helper throws, e.g. "Music
+   * generation". Defaults to "Video generation", the helper's first caller —
+   * music surfaced "Video generation did not complete" and "re-running
+   * blockrun_video" verbatim until it passed its own (audit round 3, D1/D22).
+   */
+  what?: string;
+  /** The tool name the reclaim note warns about re-running. Defaults to "blockrun_video". */
+  tool?: string;
   /** Timeout for each poll GET (always clamped to the remaining budget). Defaults to SOLANA_ASYNC_POLL_TIMEOUT_MS. */
   pollTimeoutMs?: number;
   /** Re-sign the SVM transaction (fresh blockhash) this often. Defaults to SOLANA_ASYNC_RESIGN_INTERVAL_MS. */
@@ -131,7 +255,10 @@ async function readPaymentRequired(response: Response): Promise<string> {
       header = Buffer.from(JSON.stringify(body)).toString("base64");
     }
   }
-  if (!header) throw new PaymentError("402 response but no payment requirements found");
+  // A gateway fault, not a funding problem — plain Error, like every other
+  // refusal of a quote we could not validate. PaymentError is reserved for a
+  // 402 on a request that CARRIED the signature (the tools' "out of funds").
+  if (!header) throw new Error("402 response but no payment requirements found. No charge was made.");
   return header;
 }
 
@@ -139,10 +266,10 @@ function parseSolanaChallenge(paymentHeader: string): SolanaPaymentContext {
   const paymentRequired = parsePaymentRequired(paymentHeader);
   const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
   if (!details.network?.startsWith("solana:")) {
-    throw new PaymentError(`Expected a Solana payment quote, got network: ${details.network}. The endpoint may not support Solana settlement yet.`);
+    throw new Error(`Expected a Solana payment quote, got network: ${details.network}. The endpoint may not support Solana settlement yet. No charge was made.`);
   }
   const feePayer = (details.extra as { feePayer?: string } | undefined)?.feePayer;
-  if (!feePayer) throw new PaymentError("Missing feePayer in the 402 quote's extra field");
+  if (!feePayer) throw new Error("Missing feePayer in the 402 quote's extra field. No charge was made.");
   return { paymentRequired, details, paidUsd: amountToUsd(details.amount) };
 }
 
@@ -187,7 +314,7 @@ export async function solanaPaidPost(
   endpoint: string,
   body: Record<string, unknown>,
   paidTimeoutMs: number,
-  opts?: {
+  opts?: PaidRequestHooks & {
     /**
      * Invoked with the quoted USD (from the 402 `details.amount`) AFTER the quote
      * is parsed but BEFORE anything is signed or paid. Throw from here to abort
@@ -197,13 +324,7 @@ export async function solanaPaidPost(
     onQuote?: (quotedUsd: number | null, details: ReturnType<typeof extractPaymentDetails>) => void;
   },
 ): Promise<SolanaPaidPostResult> {
-  // resolveSolanaKey, not the SDK's file-only loader: under
-  // BLOCKRUN_KEYCHAIN=strict the .solana-session file is retired once its key
-  // is in the OS keychain, and getChain() still reports "solana" for it.
-  const privateKey = resolveSolanaKey();
-  if (!privateKey) {
-    throw new PaymentError('No Solana wallet found. Run blockrun_wallet with action:"setup" to provision one.');
-  }
+  const privateKey = await requireSolanaKey();
 
   const apiUrl = SolanaLLMClient.SOLANA_API_URL;
   const url = `${apiUrl}${endpoint}`;
@@ -235,21 +356,37 @@ export async function solanaPaidPost(
   // Step 2: paid request. The signed SPL transaction embeds a recent blockhash
   // (~60-90s validity); the gateway settles optimistically in parallel with
   // generation, so submitting right after signing keeps it inside the window.
+  opts?.onPaidRequest?.();
   const resp = await fetchWithTimeout(url, {
     method: "POST",
     headers: { "Content-Type": "application/json", "PAYMENT-SIGNATURE": paymentPayload },
     body: JSON.stringify(body),
   }, paidTimeoutMs);
+  opts?.onPaidResponse?.();
 
   if (resp.status === 402) {
-    throw new PaymentError("Payment was rejected. Check your Solana USDC balance.");
+    await resp.json().catch(() => ({}));
+    throw paidRequestRefused(settleFailureReason(resp), "on the paid request");
   }
   if (!resp.ok) {
     const errBody = await resp.json().catch(() => ({ error: "Request failed" })) as Record<string, unknown>;
-    throw new Error(`API error ${resp.status}: ${JSON.stringify(errBody)}`);
+    // `statusCode`, the SDK's APIError shape: the gateway ANSWERED, and a
+    // catch that reads the status off the error (realface's callers, the
+    // in-flight tracker's isAnswer) must not have to find it in the prose —
+    // realface's regex read any "402" in a quote fault's text as "out of
+    // funds", and a 504 whose body said "timeout" read as a dropped request
+    // (audit round 4).
+    throw Object.assign(new Error(`API error ${resp.status}: ${JSON.stringify(errBody)}`), { statusCode: resp.status });
   }
 
-  const data = await resp.json() as Record<string, unknown>;
+  // The 200 IS the settlement — the money moved before this body was read. An
+  // unguarded .json() on a truncated or aborted response threw here, and the
+  // caller's catch then reported a failure with nothing booked, which is the
+  // one direction that must never happen. Hand back what we know instead: the
+  // charge is real whether or not the payload parsed.
+  const data = await resp.json().catch(() => ({
+    error: "The paid response could not be parsed. The 200 means the payment settled — the charge stands.",
+  })) as Record<string, unknown>;
   return { data, paidUsd: context.paidUsd };
 }
 
@@ -281,15 +418,11 @@ export async function solanaPaidAsyncPost(
   const pollTimeoutMs = opts.pollTimeoutMs ?? SOLANA_ASYNC_POLL_TIMEOUT_MS;
   const resignIntervalMs = opts.resignIntervalMs ?? SOLANA_ASYNC_RESIGN_INTERVAL_MS;
   const maxReactiveResigns = opts.maxReactiveResigns ?? SOLANA_ASYNC_MAX_REACTIVE_RESIGNS;
+  const what = opts.what ?? "Video generation";
+  const tool = opts.tool ?? "blockrun_video";
   const deadline = startedAt + pollBudgetMs;
 
-  // resolveSolanaKey, not the SDK's file-only loader: under
-  // BLOCKRUN_KEYCHAIN=strict the .solana-session file is retired once its key
-  // is in the OS keychain, and getChain() still reports "solana" for it.
-  const privateKey = resolveSolanaKey();
-  if (!privateKey) {
-    throw new PaymentError('No Solana wallet found. Run blockrun_wallet with action:"setup" to provision one.');
-  }
+  const privateKey = await requireSolanaKey();
 
   const apiUrl = SolanaLLMClient.SOLANA_API_URL;
   const url = `${apiUrl}${endpoint}`;
@@ -301,8 +434,10 @@ export async function solanaPaidAsyncPost(
   if (quoteResp.status !== 402) {
     // Same as solanaPaidPost and the Base video path: a paid route that does
     // not quote is a fault, not a free render. Returning the body as a
-    // completed clip with paidUsd 0 made recordActualSpend book the full
-    // ESTIMATE (0 is "unknown" there) for a call that charged nothing.
+    // completed clip used to book it as a call — and since round 3 an
+    // explicit 0 is a SETTLED zero to recordActualSpend, so it would now be
+    // booked as a free success for a route that served no quote at all.
+    // Either way the honest answer is a throw.
     const data = await quoteResp.json().catch(() => ({})) as Record<string, unknown>;
     throw new Error(`Unexpected status ${quoteResp.status} (the endpoint did not return a quote): ${JSON.stringify(data)}`);
   }
@@ -310,7 +445,7 @@ export async function solanaPaidAsyncPost(
   const paymentHeader = await readPaymentRequired(quoteResp);
   const original = parseSolanaChallenge(paymentHeader);
   if (original.paidUsd === null) {
-    throw new PaymentError(`The gateway's Solana quote carried an unreadable amount (${JSON.stringify(original.details.amount)}); refusing to sign it. No charge was made.`);
+    throw new Error(`The gateway's Solana quote carried an unreadable amount (${JSON.stringify(original.details.amount)}); refusing to sign it. No charge was made.`);
   }
   opts.onQuote?.(original.paidUsd, original.details);
 
@@ -323,12 +458,17 @@ export async function solanaPaidAsyncPost(
   if (submitTimeout === 0) {
     throw new Error(`Budget of ${Math.round(pollBudgetMs / 1000)}s was spent before the job could be submitted. No charge was made.`);
   }
+  opts.onPaidRequest?.();
   const submitResp = await fetchWithTimeout(url, {
     method: "POST",
     headers: { "Content-Type": "application/json", "PAYMENT-SIGNATURE": paymentPayload },
     body: JSON.stringify(body),
   }, submitTimeout);
-  if (submitResp.status === 402) throw new PaymentError("Payment was rejected. Check your Solana USDC balance.");
+  opts.onPaidResponse?.();
+  if (submitResp.status === 402) {
+    await submitResp.json().catch(() => ({}));
+    throw paidRequestRefused(settleFailureReason(submitResp), "at submit");
+  }
 
   const submitData = await submitResp.json().catch(() => ({})) as Record<string, unknown>;
   const pollPath = typeof submitData.poll_url === "string" ? submitData.poll_url : "";
@@ -351,18 +491,58 @@ export async function solanaPaidAsyncPost(
   if (!pollPath) throw new Error(`Submit response missing poll_url: ${JSON.stringify(submitData)}`);
   const pollUrl = new URL(pollPath, apiUrl);
   if (pollUrl.origin !== new URL(apiUrl).origin) {
-    throw new PaymentError(`Refusing to send a payment signature to an off-gateway poll URL: ${pollUrl.origin}. No charge was made.`);
+    throw new Error(`Refusing to send a payment signature to an off-gateway poll URL: ${pollUrl.origin}. No charge was made.`);
   }
 
+  // Which settlement model this route follows (see the module comment). The
+  // gateway declares settled-at-submit on the wire — the header and the body
+  // field are both read because a proxy can strip either — and the helper
+  // never assumes it: an answer that says nothing is payment-on-completion.
+  const settledAtSubmit =
+    (submitResp.headers.get("x-payment-optimistic") || "").toLowerCase() === "true" ||
+    submitData.payment_status === "settled_optimistic";
+
   // The gateway keeps a finished job claimable for ~48h; every message that
   // gives up on one must say so, because re-running the tool submits (and
   // pays for) a brand-new job.
-  const reclaimNote = `The finished job stays claimable on the gateway for ~48h${jobId ? ` (job ${jobId})` : ""}; re-running blockrun_video would start and charge a new job.`;
+  const reclaimNote = `The finished job stays claimable on the gateway for ~48h${jobId ? ` (job ${jobId})` : ""}; re-running ${tool} would start and charge a new job.`;
+  const settledNote = `The gateway settled the payment at submit (payment_status settled_optimistic), so the charge stands${jobId ? ` (job ${jobId})` : ""}.`;
+  // Every give-up after the submit goes through here so the two models cannot
+  // drift apart: on a settled-at-submit route the money is gone whatever the
+  // failure was, and the tool has to book it and name the job — the same
+  // BilledJobError the account rail throws, for the same reason.
+  const giveUp = (core: string, uncharged: string): Error =>
+    settledAtSubmit
+      ? new BilledJobError(`${core} ${settledNote} ${reclaimNote}`, { paidUsd: original.paidUsd, jobId, billing: "billed" })
+      : new Error(`${core} ${uncharged} ${reclaimNote}`);
 
   let resignsLeft = maxReactiveResigns;
   let lastStatus = typeof submitData.status === "string" ? submitData.status : "queued";
   let lastSettleReason: string | undefined;
+  // True between a paid poll leaving and its answer arriving. Read at the
+  // deadline: a poll that was still in flight can settle server-side after
+  // this client gives up; one that was answered cannot.
+  let paidPollInFlight = false;
+
+  // EVERY escape from here on goes through one classifier, not only the ones
+  // enumerated below. Round 3 typed the failed-job, poll-error and deadline
+  // exits and left the reactive re-sign path throwing plain Errors — a
+  // mutated challenge ("No charge was made"), a challenge with no readable
+  // requirements, an RPC fault inside the re-sign — so on a settled-at-submit
+  // route music reported "failed"/"No payment was taken" with nothing booked
+  // for a track the gateway had settled at POST (audit round 4). On that
+  // model no throw after the submit can un-settle the transfer, so any throw
+  // that is not already a BilledJobError becomes one; payment-on-completion
+  // routes keep their plain refusals untouched.
+  try {
+    return await pollUntilDone();
+  } catch (err) {
+    if (!settledAtSubmit || err instanceof BilledJobError) throw err;
+    const msg = (err instanceof Error ? err.message : String(err)).replace(/\s*No charge was made\.?/i, "");
+    throw giveUp(`${what} could not be collected: ${msg}`, "");
+  }
 
+  async function pollUntilDone(): Promise<SolanaPaidPostResult> {
   while (Date.now() < deadline) {
     await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
 
@@ -387,6 +567,8 @@ export async function solanaPaidAsyncPost(
     if (pollTimeout === 0) break;
 
     let pollResp: Response;
+    paidPollInFlight = true;
+    opts.onPaidRequest?.();
     try {
       pollResp = await fetchWithTimeout(pollUrl.toString(), {
         method: "GET",
@@ -394,9 +576,13 @@ export async function solanaPaidAsyncPost(
       }, pollTimeout);
     } catch {
       // Polling is idempotent and settlement has not been observed. A transient
-      // disconnect is safe to retry inside the existing deadline.
+      // disconnect is safe to retry inside the existing deadline. The in-flight
+      // flag stays set (and the caller's tracker stays armed): the request
+      // that never answered may still be settling server-side.
       continue;
     }
+    paidPollInFlight = false;
+    opts.onPaidResponse?.();
 
     if (pollResp.status === 402) {
       // The gateway's settle-failure 402 carries PAYMENT-RESPONSE (the reason),
@@ -404,11 +590,24 @@ export async function solanaPaidAsyncPost(
       // Its body is informational only — consume it to release the socket.
       lastSettleReason = settleFailureReason(pollResp) ?? lastSettleReason;
       await pollResp.json().catch(() => ({}));
-      if (isPermanentSettleFailure(lastSettleReason)) {
-        throw new PaymentError(`Payment was rejected while settling the completed Solana video (${lastSettleReason}). Check your Solana USDC balance. ${reclaimNote}`);
+      if (isFundingFailure(lastSettleReason)) {
+        // On a settled-at-submit route the poll never settles, so a funding
+        // reason there is the delivery signature being refused — the charge
+        // already stands. Everywhere else it is the wallet.
+        if (settledAtSubmit) throw giveUp(`The Solana gateway refused the delivery signature (reason: ${lastSettleReason}).`, "");
+        throw new PaymentError(`Payment was rejected while settling the completed job (${lastSettleReason}). Check your Solana USDC balance. ${reclaimNote}`);
+      }
+      if (isInvalidAuthFailure(lastSettleReason)) {
+        throw giveUp(
+          `The Solana gateway refused the payment signature while settling the completed job (reason: ${lastSettleReason}) — a signing/authorization fault, not a funding problem.`,
+          "No charge was made.",
+        );
       }
       if (resignsLeft <= 0) {
-        throw new Error(`Solana settlement did not go through after ${maxReactiveResigns} re-signs${lastSettleReason ? ` (last gateway reason: ${lastSettleReason})` : ""}. The video finished upstream but this client observed no settlement receipt, so no charge was made. ${reclaimNote}`);
+        throw giveUp(
+          `Solana settlement did not go through after ${maxReactiveResigns} re-signs${lastSettleReason ? ` (last gateway reason: ${lastSettleReason})` : ""}.`,
+          "The job finished upstream but this client observed no settlement receipt, so no charge was made.",
+        );
       }
       resignsLeft--;
       let challenge: Response;
@@ -433,7 +632,7 @@ export async function solanaPaidAsyncPost(
         fresh.details.recipient !== original.details.recipient ||
         freshFeePayer !== originalFeePayer
       ) {
-        throw new PaymentError("The refreshed poll challenge changed the payment amount, recipient or fee payer; refusing to re-authorize it. No charge was made.");
+        throw giveUp("The refreshed poll challenge changed the payment amount, recipient or fee payer; refusing to re-authorize it.", "No charge was made.");
       }
       nextResignAt = Date.now() + resignIntervalMs;
       paymentPayload = await signSolanaChallenge(fresh, pollUrl.toString(), privateKey);
@@ -452,14 +651,36 @@ export async function solanaPaidAsyncPost(
     }
 
     if (lastStatus === "failed") {
-      throw new Error(`Video generation failed upstream: ${String(pollData.error || "unknown")}. No payment was taken.`);
+      // Typed on both models. The gateway echoes the upstream failure text
+      // verbatim, and MiniMax's is "The operation was aborted due to timeout";
+      // a tool that classified this by prose booked a render the gateway had
+      // just said was not charged (C13).
+      const failed = `${what} failed upstream: ${String(pollData.error || "unknown")}.`;
+      if (settledAtSubmit) {
+        throw new BilledJobError(`${failed} ${settledNote}`, { paidUsd: original.paidUsd, jobId, billing: "billed" });
+      }
+      throw new JobFailedError(`${failed} No payment was taken.`, { jobId });
     }
     if (pollResp.ok && lastStatus === "completed") {
       return { data: pollData, paidUsd: original.paidUsd, txHash: undefined, jobId };
     }
     if (pollResp.status === 202 || pollResp.status === 504 || pollResp.ok) continue;
-    throw new Error(`Video poll error ${pollResp.status}: ${JSON.stringify(pollData)}`);
+    const pollError = `${what} poll error ${pollResp.status}: ${JSON.stringify(pollData)}`;
+    if (settledAtSubmit) throw giveUp(pollError, "");
+    throw new Error(pollError);
   }
 
-  throw new Error(`Video generation did not complete within ${Math.round(pollBudgetMs / 1000)}s (last status: ${lastStatus}). No settlement receipt was observed by this client; a poll still in flight at the deadline can settle server-side, so check the wallet's recent transactions before retrying. ${reclaimNote}`);
+  // The deadline says what this helper KNOWS, and the hooks above let the
+  // caller's tracker know the same thing: a poll that was still in flight can
+  // settle server-side (the gateway does not stop because we hung up); a poll
+  // that was answered "in_progress" cannot, because on this model settlement
+  // needs a signed poll to observe "completed".
+  const deadlineCore = `${what} did not complete within ${Math.round(pollBudgetMs / 1000)}s (last status: ${lastStatus}).`;
+  if (settledAtSubmit) throw giveUp(deadlineCore, "");
+  throw new Error(
+    paidPollInFlight
+      ? `${deadlineCore} No settlement receipt was observed by this client, but a poll carrying the payment signature was still in flight at the deadline and can settle server-side, so check the wallet's recent transactions before retrying. ${reclaimNote}`
+      : `${deadlineCore} The last poll was answered and no request carrying the payment signature is outstanding, so no charge was made. ${reclaimNote}`,
+  );
+  }
 }
diff --git a/src/utils/uncharged.ts b/src/utils/uncharged.ts
new file mode 100644
index 0000000..91ffb97
--- /dev/null
+++ b/src/utils/uncharged.ts
@@ -0,0 +1,28 @@
+// src/utils/uncharged.ts
+//
+// A leaf module on purpose: no imports. errors.ts re-exports this, but
+// errors.ts imports wallet.js and auth.js, and every handler suite that mocks
+// utils/auth.js lists its named exports by hand — so a module that only needs
+// this one predicate (in-flight.ts) imports it from here and stays linkable
+// under those mocks.
+
+/**
+ * Every way this repo and the gateway say "the money did not move". The list
+ * is longer than it looks because the sentence is written in five places by
+ * four authors: the gateway ("payment NOT charged"), the SDK, the manual-402
+ * tools ("No payment taken", "no charge was made"), and the quote guard
+ * ("Refusing to sign it — no charge was made"). Exported because the path
+ * tools' catch (utils/path-tool-catch.ts) and the in-flight tracker
+ * (utils/in-flight.ts) must refuse to BOOK a charge the gateway says it never
+ * took, using the same evidence formatError uses to refuse to SAY it.
+ */
+export function isExplicitlyUncharged(message: string): boolean {
+  const m = message.toLowerCase();
+  return m.includes("no payment was made") ||
+    m.includes("no payment was taken") ||
+    m.includes("no payment taken") ||
+    m.includes("no charge was made") ||
+    m.includes("nothing was charged") ||
+    m.includes("not charged");
+}
+
diff --git a/src/utils/wallet.ts b/src/utils/wallet.ts
index a086a13..01bde15 100644
--- a/src/utils/wallet.ts
+++ b/src/utils/wallet.ts
@@ -8,9 +8,9 @@ import {
   PriceClient,
   SolanaLLMClient,
   AnthropicClient,
-  getOrCreateWallet,
+  createWallet,
+  loadWallet,
   createSolanaWallet,
-  saveSolanaWallet,
   solanaPublicKey,
   loadSolanaWallet,
   USDC_SOLANA,
@@ -26,7 +26,6 @@ import {
   EVM_KEY_ACCOUNT,
   SOLANA_KEY_ACCOUNT,
   getKeychainMode,
-  keychainLoad,
   keychainRead,
   persistKey,
 } from "./keychain.js";
@@ -93,27 +92,138 @@ function readChainPreference(): "base" | "solana" | null {
 // Memoized: getChain() is a hot path and this branch spawns a subprocess.
 // Only ever consulted after the file check misses, so the cost is paid at most
 // once per process, and only by users who have no Solana session file.
+//
+// Three answers, not two. These probes used keychainLoad(), which collapses a
+// read ERROR (locked keychain, the 5s unlock-dialog timeout, an ACL denial)
+// into the same null as "absent" — and the null was memoised for the life of
+// the process. Under BLOCKRUN_KEYCHAIN=strict the session files are gone, so
+// a funded Base-only user whose keychain was locked at the first paid call was
+// read as a fresh install and routed to Solana; unlocking and retrying in the
+// same process changed nothing, the "No Solana wallet yet — run setup" remedy
+// fired, and setup minted a Solana wallet that step 5 then selected on every
+// later start. ensureEvmWallet() refuses to act on the same "error" status;
+// the selector in front of it has to be at least as careful. So: "unknown" is
+// never memoised, and only definite answers are.
+type KeychainProbe = boolean | "unknown";
+
 let _keychainSolanaKeyPresent: boolean | undefined;
+let _keychainEvmKeyPresent: boolean | undefined;
+
+function probeKeychain(account: string): KeychainProbe {
+  const read = keychainRead(account);
+  if (read.status === "error") return "unknown";
+  return read.status === "found";
+}
 
-function hasKeychainSolanaKey(): boolean {
+function hasKeychainSolanaKey(): KeychainProbe {
   if (getKeychainMode() === "off") return false;
   if (_keychainSolanaKeyPresent === undefined) {
-    _keychainSolanaKeyPresent = keychainLoad(SOLANA_KEY_ACCOUNT) !== null;
+    const probe = probeKeychain(SOLANA_KEY_ACCOUNT);
+    if (probe === "unknown") return probe;
+    _keychainSolanaKeyPresent = probe;
   }
   return _keychainSolanaKeyPresent;
 }
 
 // Same memoization, for the mirror-image probe used by the Solana-first default.
-let _keychainEvmKeyPresent: boolean | undefined;
-
-function hasKeychainEvmKey(): boolean {
+function hasKeychainEvmKey(): KeychainProbe {
   if (getKeychainMode() === "off") return false;
   if (_keychainEvmKeyPresent === undefined) {
-    _keychainEvmKeyPresent = keychainLoad(EVM_KEY_ACCOUNT) !== null;
+    const probe = probeKeychain(EVM_KEY_ACCOUNT);
+    if (probe === "unknown") return probe;
+    _keychainEvmKeyPresent = probe;
   }
   return _keychainEvmKeyPresent;
 }
 
+/**
+ * The EVM key the environment supplies, normalised the way the SDK normalises
+ * it (trim, 0x-prefix) — or undefined.
+ *
+ * BOTH names, because the SDK loader behind every gate in this file honours
+ * `BLOCKRUN_WALLET_KEY || BASE_CHAIN_WALLET_KEY` (its README documents the
+ * latter as the canonical setup). Checking only the first meant a user on the
+ * SDK's configuration had the keychain read ahead of their env key — a stale
+ * entry from the previous wallet silently signing every payment, the exact
+ * shadowing the precedence comment in ensureEvmWallet says it prevents — and
+ * was read as "no Base wallet" by the Solana-first default.
+ */
+function envEvmKey(): `0x${string}` | undefined {
+  const raw = (process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY || "").trim();
+  if (!raw) return undefined;
+  return (raw.startsWith("0x") ? raw : `0x${raw}`) as `0x${string}`;
+}
+
+/**
+ * The EVM key the SDK would load from disk — ~/.blockrun/.session, then the
+ * legacy ~/.blockrun/wallet.key — or null when neither holds one. Asks the
+ * loader's own question rather than re-implementing half of it: a file the
+ * loader would honour must never be invisible to the gate in front of it.
+ *
+ * "unreadable" when a file exists but cannot be read: not evidence either
+ * way. See keyFileHasKey for why the gate then errs on the side of "present".
+ */
+function evmKeyOnDisk(): string | null | "unreadable" {
+  try {
+    return loadWallet();
+  } catch {
+    return "unreadable";
+  }
+}
+
+/**
+ * The key in ~/.blockrun/.session alone — the ROTATION seam, the one file
+ * that outranks the keychain — or null when that file holds nothing.
+ *
+ * Not the legacy wallet.key: strict mode retires .session once its key is in
+ * the keychain and never touches wallet.key (persistKey is only ever handed
+ * the .session path), so a loader that read both put a stale legacy file
+ * from an older install AHEAD of the keychain the moment .session was gone —
+ * and persisted its key over the funded one with -U (audit round 4). The
+ * legacy file is consulted only after the keychain says "absent".
+ *
+ * "unreadable" when .session exists but cannot be read, for the same reason
+ * as evmKeyOnDisk: the loader then fails loudly on it instead of a keychain
+ * entry shadowing it.
+ */
+function sessionKeyOnDisk(): string | null | "unreadable" {
+  if (!keyFileHasKey(WALLET_FILE_PATH)) return null;
+  return evmKeyOnDisk();
+}
+
+/**
+ * Does this key file actually HOLD a key?
+ *
+ * `existsSync` alone is the wrong question at a keychain gate. The loaders on
+ * the far side of that gate — the SDK's resolveFromFiles() and
+ * loadSolanaWallet() — both `.trim()` the file and treat whitespace as NO KEY.
+ * So a zero-byte session file reads as "present" to the gate and "absent" to
+ * the loader, and the two disagree in the one direction that costs money:
+ * the gate skips the keychain, the loader mints a BRAND NEW wallet, and the
+ * persistKey() call right after it overwrites the keychain entry that still
+ * held the funded key. Silent, unrecoverable, and reachable without anyone
+ * calling a delete — saveWallet() is a plain non-atomic writeFileSync, so an
+ * interrupted write, a full disk, a restore tool's placeholder or a stray
+ * shell redirect all leave exactly this file behind.
+ *
+ * getChain() already asks the question this way (twice, with comments saying
+ * why). The Solana gate below is the caller that did not; the EVM gate now
+ * asks the SDK loader itself (evmKeyOnDisk), which trims the same way.
+ *
+ * A file we cannot READ counts as present. We have no idea whether it holds a
+ * key, and consulting the keychain on that guess is how a stale entry shadows
+ * a live wallet; the loader then hits the same unreadable file and fails
+ * loudly, which is the outcome we want.
+ */
+function keyFileHasKey(file: string): boolean {
+  try {
+    if (!fs.existsSync(file)) return false;
+    return fs.readFileSync(file, "utf-8").trim() !== "";
+  } catch {
+    return true;
+  }
+}
+
 /**
  * Does this machine already hold a BASE wallet the user may have funded?
  *
@@ -125,13 +235,19 @@ function hasKeychainEvmKey(): boolean {
  * install and move them to a chain they have never funded.
  */
 function hasExistingBaseWallet(): boolean {
-  if (process.env.BLOCKRUN_WALLET_KEY) return true;
-  try {
-    if (fs.existsSync(WALLET_FILE_PATH) && fs.readFileSync(WALLET_FILE_PATH, "utf-8").trim()) {
-      return true;
-    }
-  } catch { /* an unreadable file is not evidence either way — fall through */ }
-  return hasKeychainEvmKey();
+  if (envEvmKey()) return true;
+  // Same files the SDK loader reads (.session, then the legacy wallet.key); an
+  // unreadable file is not evidence either way — fall through to the keychain.
+  // A file that exists but cannot be read counts as present, the way
+  // ensureEvmWallet treats it: migrating on "could not read" is the silent
+  // substitution this guard exists to stop, and the Base path then fails
+  // loudly on the same file.
+  if (evmKeyOnDisk() !== null) return true;
+  // A keychain we could not open may well hold the funded wallet. Migrating
+  // on that uncertainty is the silent substitution this guard exists to stop,
+  // so "unknown" answers "yes, stay on Base": the Base path then fails loudly
+  // with its unlock-the-keychain message, and nothing suggests minting.
+  return hasKeychainEvmKey() !== false;
 }
 
 /** Test seam — clears the memoized keychain probes. */
@@ -176,7 +292,13 @@ export function getChain(): "base" | "solana" {
   //    without this a Solana user with no explicit .chain would be silently
   //    flipped to Base by the hardening step itself — then met with
   //    "Base-only" refusals from a wallet they never funded.
-  if (hasKeychainSolanaKey()) return "solana";
+  //
+  //    "unknown" (the keychain would not open) is deliberately NOT a Solana
+  //    signal: it falls through to step 6, whose guard treats the same
+  //    uncertainty as "stay on Base" — the chain whose refusal message says
+  //    "unlock the keychain" rather than "run setup". Nothing is memoised on
+  //    the way, so the first successful read after an unlock is honoured.
+  if (hasKeychainSolanaKey() === true) return "solana";
 
   // 6. No Solana signal anywhere — but that is not the same as "new user".
   //
@@ -248,6 +370,13 @@ export async function ensureBothWallets(): Promise<{
   // already wins in getChain() and must not be overwritten.
   const chainBefore = readChainPreference() === null ? getChain() : null;
 
+  // Whether THIS call provisions, not whether the cached object still carries
+  // the isNew flag from an earlier one. Both caches freeze isNew for the life of
+  // the process, so a second ensureBothWallets() would otherwise look like a
+  // second mint — and the pin below is written off exactly that fact.
+  const evmWasCached = _evmWalletInfo !== null;
+  const solWasCached = _solanaWalletInfo !== null;
+
   const evm = ensureEvmWallet();
   // NOT the SDK's getOrCreateSolanaWallet(): that loader knows only the env var
   // and the file. Under BLOCKRUN_KEYCHAIN=strict the file is retired once the
@@ -258,12 +387,31 @@ export async function ensureBothWallets(): Promise<{
   // refuses to mint when the keychain could not be read (audit 2026-09-08).
   const sol = await ensureSolanaWallet();
 
-  if (chainBefore !== null && getChain() !== chainBefore) {
+  // Pin on the PROVISIONING FACT, not on a re-derived getChain().
+  //
+  // The old form asked getChain() again and wrote the pin only if the answer
+  // had moved. Under BLOCKRUN_KEYCHAIN=strict that question cannot be answered
+  // correctly at this point: minting the Solana wallet stores the key in the
+  // keychain and DELETES .solana-session, so getChain()'s file check misses and
+  // its keychain probe returns the value memoised before the mint. It answered
+  // "base" both times, no pin was written, and on the next start the probe
+  // re-ran, found the new key and moved a funded Base user onto an empty Solana
+  // wallet — the exact 0.32.3 failure CHAIN_AUTO_FILE exists to prevent.
+  //
+  // Minting the OTHER chain's wallet is the whole reason continuity is at risk,
+  // and that fact is local, cache-free and true on both platforms.
+  const solMinted = !solWasCached && sol.isNew;
+  const evmMinted = !evmWasCached && evm.isNew;
+  if (chainBefore !== null && ((solMinted && chainBefore === "base") || (evmMinted && chainBefore === "solana"))) {
     // writeAutoChain, NOT setChain: this is the machine preserving continuity,
     // not the user expressing a preference. The distinction is the whole fix —
     // see CHAIN_AUTO_FILE.
     writeAutoChain(chainBefore);
   }
+  // The probes were memoised before the mint, so at least one of them is now a
+  // lie for the rest of the process. The pin above already outranks them in
+  // getChain(); dropping them keeps a same-process reader honest anyway.
+  if (solMinted || evmMinted) resetKeychainProbeCache();
 
   return {
     base: { address: evm.address, isNew: evm.isNew },
@@ -363,15 +511,145 @@ export function isEvmPrivateKey(value: string): value is `0x${string}` {
   return /^0x[0-9a-fA-F]{64}$/.test(value);
 }
 
+/**
+ * Publish a freshly minted key to its session file — unless another process
+ * got there first, in which case return THEIR key and drop ours.
+ *
+ * The 0.50.0 single-flight covers overlapping callers inside one server; it
+ * cannot see a second server, and Claude Code, Cursor and Claude Desktop are
+ * commonly all configured with `-s user`. On a machine that has never held a
+ * key, two of them can both find every store empty, both mint, and both write.
+ * The SDK's saveWallet()/saveSolanaWallet() are plain writeFileSync, so the
+ * last writer won on disk (and in the keychain, via -U) while each process
+ * kept its own wallet cached for its lifetime and printed its OWN address with
+ * a funding QR. USDC sent to the loser's address was unrecoverable once that
+ * process exited: no store ever held the key.
+ *
+ * Exclusive publish, via hard link: the key is written to a private temp file
+ * and linked into place, so the session file either does not exist or holds a
+ * complete key — never a zero-byte file mid-write that a racing reader could
+ * mistake for "nothing here" and overwrite. link() fails with EEXIST when the
+ * other process won; we then read the file and adopt what it holds. On a
+ * filesystem without hard links, `wx` (O_EXCL) is the fallback, which closes
+ * the same race up to the microseconds between its create and its write.
+ *
+ * A pre-existing EMPTY file (an interrupted write, a restore placeholder —
+ * the round-3 scenario) loses the exclusive create but holds nothing to
+ * adopt. It is CLAIMED, not overwritten: the placeholder is renamed aside
+ * (exactly one process can rename a given name away) and the exclusive link
+ * is retried, so two processes that both lost to the same placeholder still
+ * publish exactly one key and the other adopts it — round 3 replaced the
+ * placeholder with a plain rename, which two losers could both do, the last
+ * one silently discarding the first one's published key (audit round 4).
+ * Whatever happened, the file is read back at the end and its contents are
+ * what this process signs with: the residual window is the read-to-return
+ * gap, not the whole publish. Mode 0600 throughout, as the SDK writes.
+ */
+function publishMintedKey(file: string, key: string): string {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(dir, `${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+  // Exclusive create, by hard link where the filesystem has them and by
+  // O_EXCL otherwise. true = ours is now the file; false = a file exists.
+  const tryPublish = (): boolean => {
+    try {
+      fs.linkSync(tmp, file);
+      return true;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "EEXIST") return false;
+      try {
+        fs.writeFileSync(file, key, { mode: 0o600, flag: "wx" });
+        return true;
+      } catch (err2) {
+        if ((err2 as NodeJS.ErrnoException).code === "EEXIST") return false;
+        throw err2;
+      }
+    }
+  };
+  try {
+    fs.writeFileSync(tmp, key, { mode: 0o600 });
+    for (let attempt = 0; attempt < 4; attempt++) {
+      if (tryPublish()) break;
+      // Someone published before us. Their key is the wallet every store
+      // will hold from here on; ours exists only in this heap and must not
+      // be shown.
+      let theirs = "";
+      try { theirs = fs.readFileSync(file, "utf-8").trim(); } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+        continue; // gone between the link and the read: try the link again
+      }
+      if (theirs) break;
+      // A stale empty placeholder. Claim it by renaming it away — the one
+      // process whose rename succeeds is the one that gets to publish; the
+      // others see ENOENT here, retry the link, lose to the claimant's key
+      // and adopt it on the next pass.
+      const aside = `${tmp}.placeholder`;
+      try { fs.renameSync(file, aside); } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+      }
+      fs.rmSync(aside, { force: true });
+    }
+    // What is on disk is the wallet, whoever put it there. (Four passes of
+    // link/read/claim without a file at the end is not a race any more, it
+    // is a filesystem that will not hold one; write plainly and say so.)
+    let published = "";
+    try { published = fs.readFileSync(file, "utf-8").trim(); } catch { /* fall through */ }
+    if (published) return published;
+    fs.writeFileSync(file, key, { mode: 0o600 });
+    return key;
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+}
+
+/**
+ * The refusal below has to describe the state it found, not a mode the user
+ * may never have set. The empty-file gate made it reachable in AUTO mode — an
+ * existing zero-byte .session consults the keychain — and the fixed wording
+ * ("no longer exists because BLOCKRUN_KEYCHAIN=strict retired it") sent that
+ * user hunting for a file that was right there, and never told them that
+ * restoring it from a backup is the fix.
+ */
+function explainMissingKeyFile(file: string, shown: string): string {
+  let exists = false;
+  try {
+    exists = fs.existsSync(file);
+  } catch { /* treat as missing */ }
+  if (exists) return `${shown} exists but holds no key (an interrupted write or a restore placeholder)`;
+  return getKeychainMode() === "strict"
+    ? `${shown} no longer exists (BLOCKRUN_KEYCHAIN=strict retires it once the key is in the keychain)`
+    : `there is no ${shown} to fall back to`;
+}
+
 function ensureEvmWallet() {
   if (_evmWalletInfo) return _evmWalletInfo;
 
-  // BLOCKRUN_WALLET_KEY outranks the keychain, matching the SDK's own
-  // precedence (env > ~/.blockrun/.session). An operator who exports a key
-  // must not be silently overridden by a stale keychain entry from an earlier
-  // wallet — that is the same failure the .chain-auto file exists to prevent,
-  // and here it would route payments through a wallet the user cannot see.
-  // ...and so does the key FILE, whenever it exists. Replacing
+  // The env key outranks everything, matching the SDK's own precedence
+  // (env > ~/.blockrun/.session > legacy wallet.key). An operator who exports
+  // a key must not be silently overridden by a stale keychain entry from an
+  // earlier wallet — that is the same failure the .chain-auto file exists to
+  // prevent, and here it would route payments through a wallet the user
+  // cannot see.
+  //
+  // And it is a SIGNER OVERRIDE, not a wallet this machine owns: it is never
+  // mirrored into the keychain and never retires the file. It used to be —
+  // persistKey stored it over the funded key with -U and, under strict, the
+  // read-back (keychain === env key, trivially) then deleted the .session
+  // still holding the funded key. One run with a different key in the
+  // environment and the funded wallet, also the Polymarket deposit signer,
+  // was in no store at all. The Solana rail never persisted SOLANA_WALLET_KEY;
+  // this is the parity fix.
+  const fromEnv = envEvmKey();
+  if (fromEnv) {
+    _evmWalletInfo = {
+      address: privateKeyToAccount(fromEnv).address,
+      privateKey: fromEnv,
+      isNew: false,
+    };
+    return _evmWalletInfo;
+  }
+
+  // ...and so does the key FILE, whenever it holds a key. Replacing
   // ~/.blockrun/.session is how a wallet gets rotated or restored from backup,
   // and reading the keychain ahead of an existing file would let a stale entry
   // from the previous wallet shadow the new key silently — every payment then
@@ -381,11 +659,14 @@ function ensureEvmWallet() {
   // exactly when the file is gone, which is what strict mode does. Reading it
   // first bought no security in auto mode anyway: the plaintext file is still
   // sitting there for the same attacker to read.
-  if (
-    !process.env.BLOCKRUN_WALLET_KEY &&
-    getKeychainMode() !== "off" &&
-    !fs.existsSync(WALLET_FILE_PATH)
-  ) {
+  //
+  // "Holds a key" is the loader's question, asked through the loader: an
+  // empty file is no key (see keyFileHasKey), and a file we cannot read
+  // counts as present so the loader fails loudly on it instead of a stale
+  // keychain entry shadowing it. Only .session ranks here — the legacy
+  // wallet.key is read AFTER the keychain (see sessionKeyOnDisk).
+  const onDisk = sessionKeyOnDisk();
+  if (onDisk === null && getKeychainMode() !== "off") {
     const read = keychainRead(EVM_KEY_ACCOUNT);
 
     if (read.status === "found" && isEvmPrivateKey(read.value)) {
@@ -397,18 +678,17 @@ function ensureEvmWallet() {
       return _evmWalletInfo;
     }
 
-    // A read that FAILED is not a read that found nothing. The file is already
-    // gone at this point (strict mode retired it), so falling through would
-    // hand getOrCreateWallet() an empty slate and mint a BRAND NEW wallet —
-    // orphaning a funded one that is very likely still sitting in a keychain we
-    // merely could not open (locked, ACL-denied, timed out). Stop instead: a
-    // loud error is recoverable, a silently replaced wallet is not.
+    // A read that FAILED is not a read that found nothing. No file holds a
+    // key at this point, so falling through would mint a BRAND NEW wallet —
+    // orphaning a funded one that is very likely still sitting in a keychain
+    // we merely could not open (locked, ACL-denied, timed out). Stop instead:
+    // a loud error is recoverable, a silently replaced wallet is not.
     if (read.status === "error") {
       throw new Error(
         `Could not read the wallet key from the OS keychain (${read.detail}), and ` +
-          `~/.blockrun/.session no longer exists because BLOCKRUN_KEYCHAIN=strict retired it. ` +
+          `${explainMissingKeyFile(WALLET_FILE_PATH, "~/.blockrun/.session")}. ` +
           `Refusing to create a new wallet — your existing one is most likely still in the keychain. ` +
-          `Unlock the keychain and retry, or set BLOCKRUN_WALLET_KEY to your key.`,
+          `Unlock the keychain and retry, restore the file from a backup, or set BLOCKRUN_WALLET_KEY to your key.`,
       );
     }
 
@@ -419,14 +699,36 @@ function ensureEvmWallet() {
     }
   }
 
-  _evmWalletInfo = getOrCreateWallet();
-  if (_evmWalletInfo.isNew) {
-    console.error(formatWalletCreatedMessage(_evmWalletInfo.address));
+  // .session held a key (or could not be read), or the keychain had nothing:
+  // the SDK loader's own answer — .session, then the legacy wallet.key. A
+  // file we cannot read is re-read here so it throws the real error rather
+  // than being papered over.
+  {
+    const privateKey = (onDisk !== null && onDisk !== "unreadable" ? onDisk : loadWallet()) as `0x${string}` | null;
+    if (privateKey) {
+      _evmWalletInfo = { address: privateKeyToAccount(privateKey).address, privateKey, isNew: false };
+      persistKey(EVM_KEY_ACCOUNT, privateKey, WALLET_FILE_PATH);
+      return _evmWalletInfo;
+    }
   }
+
+  // Every store says "absent": mint. The mint is what the SDK's
+  // getOrCreateWallet() would do, minus its plain-write save — see
+  // publishMintedKey for why the write has to be exclusive.
+  const minted = createWallet();
+  const published = publishMintedKey(WALLET_FILE_PATH, minted.privateKey);
+  // An adopted file is read raw; the SDK loader would 0x-prefix it, so do the same.
+  const privateKey = (published.startsWith("0x") ? published : `0x${published}`) as `0x${string}`;
+  _evmWalletInfo = {
+    address: privateKeyToAccount(privateKey).address,
+    privateKey,
+    isNew: true,
+  };
+  console.error(formatWalletCreatedMessage(_evmWalletInfo.address));
   // Mirror into the keychain so the next process reads it from there instead
   // of the plaintext file. No-op unless a keychain exists; only strict mode
   // then retires the file, and only after a verified read-back.
-  persistKey(EVM_KEY_ACCOUNT, _evmWalletInfo.privateKey, WALLET_FILE_PATH);
+  persistKey(EVM_KEY_ACCOUNT, privateKey, WALLET_FILE_PATH);
   return _evmWalletInfo;
 }
 
@@ -472,9 +774,10 @@ function resolveSolanaKeyDetailed(): SolanaKeyResolution {
   if (_solanaKey) return { key: _solanaKey };
 
   let keychainError: string | undefined;
-  // Same precedence correction as the EVM path: an existing .solana-session is
-  // the user's current intent, so it outranks whatever the keychain remembers.
-  if (getKeychainMode() !== "off" && !fs.existsSync(SOLANA_WALLET_FILE_PATH)) {
+  // Same precedence correction as the EVM path: a .solana-session that HOLDS a
+  // key is the user's current intent, so it outranks whatever the keychain
+  // remembers. An empty one holds no intent — see keyFileHasKey.
+  if (getKeychainMode() !== "off" && !keyFileHasKey(SOLANA_WALLET_FILE_PATH)) {
     const read = keychainRead(SOLANA_KEY_ACCOUNT);
     if (read.status === "found") {
       _solanaKey = read.value;
@@ -496,7 +799,25 @@ export function resolveSolanaKey(): string | undefined {
   return resolveSolanaKeyDetailed().key;
 }
 
+/**
+ * Why there is no key, when there is no key.
+ *
+ * resolveSolanaKey() collapses "absent" and "the keychain would not open" into
+ * undefined, and every caller then says "no Solana wallet yet — run setup",
+ * which for a locked keychain is both wrong and destructive advice: the wallet
+ * exists and is funded. ensureSolanaWallet already refuses to mint on that
+ * distinction; this exposes it so the sync callers can say the same thing.
+ */
+export function solanaKeyUnavailableReason(): string | undefined {
+  const { key, keychainError } = resolveSolanaKeyDetailed();
+  if (key) return undefined;
+  return keychainError === undefined
+    ? undefined
+    : `the OS keychain could not be read (${keychainError})`;
+}
+
 let _solanaWalletInfo: { address: string; privateKey: string; isNew: boolean } | null = null;
+let _solanaWalletPromise: Promise<{ address: string; privateKey: string; isNew: boolean }> | null = null;
 
 /**
  * The Solana twin of ensureEvmWallet(): return the existing wallet from
@@ -505,8 +826,31 @@ let _solanaWalletInfo: { address: string; privateKey: string; isNew: boolean } |
  * already gone in strict mode, so minting here would orphan a funded key that
  * is very likely still sitting in a keychain we merely could not open.
  */
-export async function ensureSolanaWallet(): Promise<{ address: string; privateKey: string; isNew: boolean }> {
+export async function ensureSolanaWallet(): Promise<SolanaWalletInfo> {
   if (_solanaWalletInfo) return _solanaWalletInfo;
+  // Single-flight. The cache is only assigned AFTER `await createSolanaWallet()`,
+  // so two overlapping callers both saw null and both minted — and 0.49.0 made
+  // that reachable from two entry points at once: the read-only
+  // blockrun://wallet resource and blockrun_wallet action:"setup". Last writer
+  // wins in the file and the keychain, so one caller walks away with a funding
+  // QR for an address whose key was discarded.
+  //
+  // A rejection is deliberately NOT cached: memoising the keychain-error throw
+  // below would leave a user who unlocks their keychain and retries broken until
+  // restart — the same poisoning 0.49.0 removed when it stopped memoising a MISS
+  // (see resolveSolanaKeyDetailed, and the tests that pin it).
+  if (!_solanaWalletPromise) {
+    _solanaWalletPromise = provisionSolanaWallet().catch((err) => {
+      _solanaWalletPromise = null;
+      throw err;
+    });
+  }
+  return _solanaWalletPromise;
+}
+
+type SolanaWalletInfo = { address: string; privateKey: string; isNew: boolean };
+
+async function provisionSolanaWallet(): Promise<SolanaWalletInfo> {
   const { key, keychainError } = resolveSolanaKeyDetailed();
   if (key) {
     _solanaWalletInfo = { address: await solanaPublicKey(key), privateKey: key, isNew: false };
@@ -515,19 +859,24 @@ export async function ensureSolanaWallet(): Promise<{ address: string; privateKe
   if (keychainError !== undefined) {
     throw new Error(
       `Could not read the Solana wallet key from the OS keychain (${keychainError}), and ` +
-        `~/.blockrun/.solana-session does not exist (BLOCKRUN_KEYCHAIN=strict retires it once the key is in the keychain). ` +
+        `${explainMissingKeyFile(SOLANA_WALLET_FILE_PATH, "~/.blockrun/.solana-session")}. ` +
         `Refusing to create a new Solana wallet — your existing one is most likely still in the keychain. ` +
-        `Unlock the keychain and retry, or set SOLANA_WALLET_KEY to your key. Nothing was charged.`,
+        `Unlock the keychain and retry, restore the file from a backup, or set SOLANA_WALLET_KEY to your key. Nothing was charged.`,
     );
   }
   const created = await createSolanaWallet();
-  saveSolanaWallet(created.privateKey);
+  // NOT the SDK's saveSolanaWallet(): that is a plain write, and the await
+  // above (a cold @solana/web3.js import) is a wide window for a second server
+  // process to mint too. Publish exclusively and adopt the winner's key if we
+  // lost — see publishMintedKey.
+  const privateKey = publishMintedKey(SOLANA_WALLET_FILE_PATH, created.privateKey);
+  const address = privateKey === created.privateKey ? created.address : await solanaPublicKey(privateKey);
   // Mirror into the keychain; strict mode then retires the file after a
   // verified read-back — the same sequence ensureEvmWallet() runs.
-  persistKey(SOLANA_KEY_ACCOUNT, created.privateKey, SOLANA_WALLET_FILE_PATH);
-  _solanaKey = created.privateKey;
-  _solanaWalletInfo = { address: created.address, privateKey: created.privateKey, isNew: true };
-  console.error(formatWalletCreatedMessage(created.address));
+  persistKey(SOLANA_KEY_ACCOUNT, privateKey, SOLANA_WALLET_FILE_PATH);
+  _solanaKey = privateKey;
+  _solanaWalletInfo = { address, privateKey, isNew: true };
+  console.error(formatWalletCreatedMessage(address));
   return _solanaWalletInfo;
 }
 
@@ -535,6 +884,7 @@ export async function ensureSolanaWallet(): Promise<{ address: string; privateKe
 export function resetSolanaKeyCache(): void {
   _solanaKey = undefined;
   _solanaWalletInfo = null;
+  _solanaWalletPromise = null;
 }
 
 /**
@@ -569,6 +919,15 @@ function buildSolanaClient(timeout?: number): SolanaLLMClient {
   }
   const privateKey = resolveSolanaKey();
   if (!privateKey) {
+    const locked = solanaKeyUnavailableReason();
+    if (locked) {
+      // NOT "no wallet yet": the wallet may well exist and be funded, and
+      // telling this user to run setup invites a second one.
+      throw new Error(
+        `Cannot reach your Solana wallet key — ${locked}. Your existing wallet is most likely still in the keychain: ` +
+          `unlock it and retry, or set SOLANA_WALLET_KEY. Nothing was charged.`,
+      );
+    }
     // The SDK constructor would throw "Private key required. Pass privateKey in
     // options or set SOLANA_WALLET_KEY" — true, and useless to someone on a
     // fresh install where Solana is the default chain and nothing has minted a
@@ -744,10 +1103,26 @@ const DEFAULT_SOLANA_RPC_URL = "https://sol.blockrun.ai/api/v1/solana/rpc";
  */
 async function getSolanaUsdcBalance(address: string): Promise<number | null> {
   const rpcUrl = process.env.SOLANA_RPC_URL || DEFAULT_SOLANA_RPC_URL;
+  // The SDK reads SOLANA_RPC_HEADERS alongside SOLANA_RPC_URL (resolveRpcConfig
+  // in @blockrun/llm), and taking the balance query off the SDK dropped it —
+  // so a private RPC that authenticates by header answered 401 and the balance
+  // read as "unavailable". Same parse, same failure mode on bad JSON: ignore it.
+  let rpcHeaders: Record<string, string> | undefined;
+  if (process.env.SOLANA_RPC_HEADERS) {
+    try {
+      const parsed = JSON.parse(process.env.SOLANA_RPC_HEADERS) as unknown;
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        rpcHeaders = Object.fromEntries(Object.entries(parsed as Record<string, unknown>).map(([k, v]) => [String(k), String(v)]));
+      }
+    } catch { /* malformed: fall through unauthenticated, as the SDK does */ }
+  } else if (process.env.SOLANA_RPC_API_KEY) {
+    // The SDK's other spelling (resolveRpcConfig): a keyed private RPC.
+    rpcHeaders = { "x-api-key": process.env.SOLANA_RPC_API_KEY };
+  }
   try {
     const response = await fetch(rpcUrl, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", ...(rpcHeaders ?? {}) },
       body: JSON.stringify({
         jsonrpc: "2.0",
         id: 1,
diff --git a/test/_setup.ts b/test/_setup.ts
new file mode 100644
index 0000000..535b653
--- /dev/null
+++ b/test/_setup.ts
@@ -0,0 +1,42 @@
+// Preloaded into EVERY test process by the `test` script in package.json:
+//
+//   tsx --experimental-test-module-mocks --import ./test/_setup.ts --test test/*.test.ts
+//
+// node's test runner hands its own execArgv to each child it spawns, so this
+// runs once per test file, before that file's first import. It is not a test
+// (the glob is *.test.ts) and it registers nothing; it pins the environment.
+//
+// WHY: the wallet, the chain preference and the account API key all live under
+// ~/.blockrun on the developer's machine, and utils/auth.ts, utils/wallet.ts
+// and utils/constants.ts capture os.homedir() at import time. A suite that
+// mocks fetch and the SDK clients but not auth.js still asks isApiKeyMode()
+// first — and on a machine with ~/.blockrun/.api-key the answer switched ten
+// mocked-handler suites onto the account rail, where the Base-rail assertions
+// they exist for were never exercised. Only image-cost.test.ts had pinned
+// itself. Pinning here means the verdict is the same on every machine and no
+// suite has to remember to do it; a suite that WANTS the account rail mocks
+// auth.js or sets BLOCKRUN_API_KEY itself, and restores it.
+//
+// The home is a fresh empty directory, not a nonexistent path: code under test
+// is allowed to mkdir ~/.blockrun and write a session into it, and a real
+// directory is what it would find on a first run. test/harness-pin.test.ts is
+// the assertion that this actually took effect.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const home = fs.mkdtempSync(path.join(os.tmpdir(), "blockrun-test-home-"));
+process.env.HOME = home;
+process.env.USERPROFILE = home;
+
+// Every variable that selects a rail, a chain, a key, a gateway or a price.
+// Wildcarded by prefix so a new BLOCKRUN_* knob cannot leak in unpinned.
+for (const key of Object.keys(process.env)) {
+  if (/^(BLOCKRUN_|SOLANA_|POLYMARKET_)/.test(key) || key === "BASE_CHAIN_WALLET_KEY" || key === "TRANSACTION_FEE_USD") {
+    delete process.env[key];
+  }
+}
+
+process.on("exit", () => {
+  fs.rmSync(home, { recursive: true, force: true });
+});
diff --git a/test/apps.test.ts b/test/apps.test.ts
index 0cd27a7..f5bd66b 100644
--- a/test/apps.test.ts
+++ b/test/apps.test.ts
@@ -98,3 +98,51 @@ test("the order card refuses to place a stale amount and shows the worst fill",
   assert.ok(order.includes("Re-quote first"), "order card: stale-amount guard text");
   assert.ok(order.includes("worstFillPrice"), "order card: renders the server's worst-fill bound");
 });
+
+// --- the card's post-failure logic, as logic (round 2) ---
+//
+// These two predicates decide whether the card may offer Place again. Grepping
+// a minified bundle cannot test that, and getting it wrong costs a duplicate
+// real-money order, so they live outside the DOM.
+test("a failure the server says signed nothing may re-arm; anything else may not", async () => {
+  const { outcomeIsUnknown } = await import("../apps/order-safety.js");
+
+  // The server knows, and says so, in the wording this repo standardised on.
+  for (const known of [
+    "Insufficient balance. No charge was made.",
+    "to_address must be a valid 0x… Base address. Nothing withdrawn.",
+    "The gateway quoted $1.14 … Refusing to sign it — no charge was made.",
+    "Predexon 500 … (payment NOT charged)",
+  ]) assert.equal(outcomeIsUnknown(known), false, known);
+
+  // Everything else is ambiguous: the order may be live at the CLOB.
+  for (const unknown of [
+    "MCP error -32001: Request timed out",
+    "fetch failed",
+    "socket hang up",
+    "Order submission failed",
+    "",
+  ]) assert.equal(outcomeIsUnknown(unknown), true, unknown);
+});
+
+test("only a declined consent prompt restores the card to its pre-click state", async () => {
+  const { declinedByUser } = await import("../apps/order-safety.js");
+  for (const declined of [
+    "User declined the request",
+    "Permission denied by the user",
+    "Request cancelled",
+    "rejected by user",
+  ]) assert.equal(declinedByUser(declined), true, declined);
+
+  for (const notDeclined of [
+    "MCP error -32001: Request timed out",
+    "fetch failed",
+    "CLOB rejected the order: insufficient allowance",
+  ]) assert.equal(declinedByUser(notDeclined), false, notDeclined);
+});
+
+test("the built card carries the duplicate-submit guards, not just the stale-amount one", () => {
+  const order = readAppHtml("orderPreview");
+  assert.ok(order.includes("MAY already be live at the exchange"), "ambiguous failure must warn, not re-arm");
+  assert.ok(order.includes("Outcome unknown"), "the disabled Place button explains itself");
+});
diff --git a/test/axios-scope.test.ts b/test/axios-scope.test.ts
new file mode 100644
index 0000000..b5309bf
--- /dev/null
+++ b/test/axios-scope.test.ts
@@ -0,0 +1,69 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// applyClobProxyOnce() sets axios.defaults.httpsAgent PROCESS-WIDE. That is
+// not a style choice: @polymarket/clob-client-v2 reaches for the hoisted axios
+// itself, so there is no instance to scope the agent to without forking it.
+//
+// The safety argument is entirely about WHO ELSE shares that axios. Today the
+// answer is "only Polymarket": every axios importer in src/ is under
+// utils/polymarket/, @blockrun/llm and the rest of the tools use fetch (which
+// ignores axios defaults), and the relayer carries its own axios 0.27 copy
+// that relayer.ts hands the agent to explicitly.
+//
+// That argument lives in a comment, which cannot fail. This can. The day a
+// non-Polymarket module imports axios, its traffic starts going through an
+// operator's POLYMARKET_CLOB_PROXY the moment a trade is placed -- a silent
+// egress change nobody asked for -- and this test goes red first.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SRC = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "src");
+const POLYMARKET_DIR = path.join("utils", "polymarket");
+
+function walk(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = path.join(dir, entry);
+    if (statSync(full).isDirectory()) out.push(...walk(full));
+    else if (entry.endsWith(".ts")) out.push(full);
+  }
+  return out;
+}
+
+test("only src/utils/polymarket may import axios", () => {
+  const offenders: string[] = [];
+  for (const file of walk(SRC)) {
+    const source = readFileSync(file, "utf-8");
+    if (!/(^|\n)\s*import[^;]*from\s+["']axios["']/.test(source) &&
+        !/require\(\s*["']axios["']\s*\)/.test(source)) continue;
+    const rel = path.relative(SRC, file);
+    if (!rel.startsWith(POLYMARKET_DIR)) offenders.push(rel);
+  }
+
+  assert.deepEqual(
+    offenders,
+    [],
+    "applyClobProxyOnce() mutates axios.defaults process-wide; a non-Polymarket " +
+      "axios caller would silently route through POLYMARKET_CLOB_PROXY. Use fetch, " +
+      "or give this module its own axios instance with an explicit agent.",
+  );
+});
+
+test("the proxy is only installed when the operator asks for one", async () => {
+  const saved = process.env.POLYMARKET_CLOB_PROXY;
+  delete process.env.POLYMARKET_CLOB_PROXY;
+  const { getClobProxy } = await import("../src/utils/polymarket/constants.js");
+
+  assert.equal(
+    getClobProxy(),
+    undefined,
+    "the Finland default is a HOST (POLYMARKET_CLOB_HOST), not a proxy — if a " +
+      "default ever lands here, axios.defaults gets mutated for every user",
+  );
+
+  if (saved === undefined) delete process.env.POLYMARKET_CLOB_PROXY;
+  else process.env.POLYMARKET_CLOB_PROXY = saved;
+});
diff --git a/test/brand-sync-script.test.ts b/test/brand-sync-script.test.ts
new file mode 100644
index 0000000..1e4dca5
--- /dev/null
+++ b/test/brand-sync-script.test.ts
@@ -0,0 +1,116 @@
+// Run with: npm test  (tsx --test)
+//
+// scripts/sync-brand-numbers.mjs is a vendored copy of blockrun's
+// brand/sync-brand-numbers.mjs, and blockrun's CI (`brand-script-sync`)
+// compares every consumer's copy byte-for-byte against that source. Its
+// printed remediation is "copy the source over the consumer's copy". This
+// repo's copy is AHEAD of the source: the markup-injection guard
+// (assertRenderable + escAttr, commit efb9e2e) exists only here, and a
+// resync PR that follows the remediation deletes it — which is what #84 and
+// #128 did to earlier local fixes. Nothing failed then, because nothing
+// exercised the behaviour.
+//
+// These tests run the script for real (a temp dir, no git, no network — only
+// --refresh fetches) and assert what it DOES with a hostile value. A resync
+// that drops the guard fails `npm test`, which is a required check on main,
+// so the guard cannot be quietly reverted; the header of the script says
+// which direction the resync has to go.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "scripts", "sync-brand-numbers.mjs");
+
+function fixture(numbers: unknown, readme: string) {
+  const dir = mkdtempSync(path.join(os.tmpdir(), "brand-sync-script-"));
+  // A string is written verbatim: JSON.stringify would turn the Infinity the
+  // non-finite case needs back into null before the script ever saw it.
+  writeFileSync(path.join(dir, "brand-numbers.json"), typeof numbers === "string" ? numbers : JSON.stringify(numbers, null, 2));
+  writeFileSync(path.join(dir, "README.md"), readme);
+  const run = (...args: string[]) => spawnSync("node", [SCRIPT, ...args], { cwd: dir, encoding: "utf8" });
+  return { dir, run, readme: () => readFileSync(path.join(dir, "README.md"), "utf8"), cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+const BADGE_README = 'Hero: <!-- br:mcp.tools@badge -->old<!-- /br:mcp.tools@badge -->\nPlain: <!-- br:mcp.tools -->18<!-- /br:mcp.tools --> tools\n';
+
+test("a value carrying a quote or an angle bracket is refused, and nothing is written", () => {
+  // What a compromised mirror would serve: closes the src="…" attribute and
+  // injects a tag into every consuming README.
+  const hostile = '19" onerror="alert(1)"><script>';
+  const f = fixture({ mcp: { tools: hostile } }, BADGE_README);
+  try {
+    const r = f.run();
+    assert.notEqual(r.status, 0, `the script must exit non-zero on a hostile value:\n${r.stdout}${r.stderr}`);
+    assert.match(r.stderr, /refusing to render mcp\.tools/);
+    assert.match(r.stderr, /pushed by the brand-sync bot/);
+    assert.equal(f.readme(), BADGE_README, "the README must be untouched — a refusal that already wrote is not a refusal");
+  } finally {
+    f.cleanup();
+  }
+});
+
+test("--check refuses the same value the same way, so PR CI fails too", () => {
+  const f = fixture({ mcp: { tools: "<img src=x>" } }, BADGE_README);
+  try {
+    const r = f.run("--check");
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /refusing to render/);
+  } finally {
+    f.cleanup();
+  }
+});
+
+test("an array or an object under a marker is refused rather than rendered as [object Object]", () => {
+  const f = fixture({ mcp: { tools: [19] } }, BADGE_README);
+  try {
+    const r = f.run();
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /expected a number or a string, got an array/);
+  } finally {
+    f.cleanup();
+  }
+});
+
+test("a plain number renders into both the badge and the prose, and the badge's attributes stay closed", () => {
+  const f = fixture({ mcp: { tools: 19 } }, BADGE_README);
+  try {
+    const r = f.run();
+    assert.equal(r.status, 0, r.stderr);
+    const out = f.readme();
+    assert.match(out, /<!-- br:mcp\.tools -->19<!-- \/br:mcp\.tools --> tools/);
+    assert.match(out, /<img src="https:\/\/img\.shields\.io\/badge\/tools-19-5B9BF6\?style=flat-square&labelColor=0B0A0F" alt="19 tools">/);
+  } finally {
+    f.cleanup();
+  }
+});
+
+test("a short plain label (a string value) is allowed, and ampersands in it are attribute-escaped", () => {
+  // The artifact legitimately carries labels ("Solana & Base" style). Belt to
+  // the braces: even an allowed character that is special in an attribute is
+  // escaped inside src/alt, so the tag cannot be mis-parsed.
+  const f = fixture({ mcp: { tools: "19+" } }, BADGE_README);
+  try {
+    const r = f.run();
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(f.readme(), /alt="19\+ tools"/);
+  } finally {
+    f.cleanup();
+  }
+});
+
+test("a non-finite number is refused", () => {
+  // JSON cannot carry NaN, but the mirror could carry 1e999 — which parses
+  // to Infinity and would render the word "Infinity" into the hero badge.
+  const f = fixture('{"mcp":{"tools":1e999}}', BADGE_README);
+  try {
+    const r = f.run();
+    assert.notEqual(r.status, 0);
+    assert.match(r.stderr, /not a finite number/);
+  } finally {
+    f.cleanup();
+  }
+});
diff --git a/test/budget-ceiling.test.ts b/test/budget-ceiling.test.ts
new file mode 100644
index 0000000..80ea734
--- /dev/null
+++ b/test/budget-ceiling.test.ts
@@ -0,0 +1,207 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// BLOCKRUN_BUDGET_LIMIT is sold as the operator's hard stop — the ONLY guard on
+// a client that cannot render the spend dialog. It seeded a plain mutable
+// `budget.limit`, and blockrun_wallet action:"budget" let the model write that
+// field: budget_action:"clear" set it to null, budget_action:"set" to any
+// positive number. The wallet tool is in every profile, annotated
+// non-destructive, and the budget action is free, so no client prompted. The
+// denial text an agent receives at the cap even points at the tool. One call,
+// and the cap the operator set was gone on all three rails.
+//
+// The rule now: an env-seeded limit is a CEILING the session can only lower.
+// `set` above it is clamped to it and says why; `clear` restores it rather
+// than lifting it; a delegated per-agent cap cannot exceed it. Without the
+// env, the tool behaves as before — set/clear are the operator's session
+// controls and there is nothing to protect them from.
+import { test, mock } from "node:test";
+import assert from "node:assert/strict";
+import type { BudgetState } from "../src/types.js";
+
+let apiKeyMode = false;
+let activeChain: "base" | "solana" = "solana";
+
+mock.module("../src/utils/onramp.js", {
+  namedExports: { launchTopUp: async () => ({ opened: false, url: "", note: "" }) },
+});
+mock.module("../src/utils/auth.js", {
+  namedExports: {
+    isApiKeyMode: () => apiKeyMode,
+    requireWalletMode: (c: string) => `${c} needs wallet mode`,
+    PORTAL_CREDITS_URL: "https://user.blockrun.ai/dashboard/credits",
+    PORTAL_ACTIVITY_URL: "https://user.blockrun.ai/dashboard/activity",
+  },
+});
+mock.module("../src/utils/account.js", {
+  namedExports: {
+    describeBlock: () => null,
+    formatCredit: () => "credit",
+    getAccountCredit: async () => ({ accountId: "acct", billingMode: "prepaid", grantedUsd: 10, spentUsd: 1, remainingUsd: 9, blocked: false, blockedReason: null }),
+  },
+});
+mock.module("../src/utils/wallet.js", {
+  namedExports: {
+    getApiBase: () => "https://blockrun.ai/api",
+    resolveGatewayUrl: (u: string) => u,
+    getWalletInfo: async () => ({ address: "0xTESTADDRESS", explorerUrl: "https://x", network: "base", chainId: 8453, isNew: false }),
+    getChain: () => activeChain,
+    getUsdcBalance: async () => 0,
+    setChain: () => {},
+    ensureBothWallets: async () => ({ base: { address: "0xTESTADDRESS" }, solana: { address: "SOL" } }),
+    getChainBalance: async () => 0,
+  },
+});
+const { registerWalletTool } = await import("../src/tools/wallet.js");
+const { reserveBudget } = await import("../src/utils/budget.js");
+
+// The ceiling is what initializeMcpServer seeded from the env before it
+// registered the tools: a BudgetState whose `limit` is already set at
+// registration time IS an env-capped server.
+function makeHarness(envLimit: number | null) {
+  let handler: ((a: Record<string, unknown>) => Promise<any>) | undefined;
+  const server = { registerTool: (_n: string, _c: unknown, h: any) => { handler = h; } } as any;
+  const budget: BudgetState = { limit: envLimit, spent: 0, calls: 0, agents: new Map() };
+  registerWalletTool(server, budget);
+  return { call: (a: Record<string, unknown>) => handler!(a), budget };
+}
+
+// The ledger is one object shared by every paid tool, so the rail only changes
+// which branch of the wallet tool the budget action runs in front of. All three
+// are exercised so a future "api-key mode returns early" refactor cannot
+// quietly reopen one of them.
+const RAILS: Array<{ name: string; apiKey: boolean; chain: "base" | "solana" }> = [
+  { name: "solana wallet", apiKey: false, chain: "solana" },
+  { name: "base wallet", apiKey: false, chain: "base" },
+  { name: "account api key", apiKey: true, chain: "base" },
+];
+
+for (const rail of RAILS) {
+  test(`[${rail.name}] budget clear cannot lift an env-seeded cap — it restores the ceiling and the next call is still refused`, async () => {
+    apiKeyMode = rail.apiKey;
+    activeChain = rail.chain;
+    const { call, budget } = makeHarness(2);
+    budget.spent = 1.5;
+
+    const res = await call({ action: "budget", budget_action: "clear" });
+    assert.equal(res.isError, undefined, "clear is not an error — it is answered with what it did");
+    assert.equal(budget.limit, 2, "the operator's $2 survives the clear");
+    assert.equal(res.structuredContent.limit, 2);
+    assert.equal(res.structuredContent.ceiling, 2);
+    assert.match(res.content[0].text, /BLOCKRUN_BUDGET_LIMIT/, "names the env the operator set");
+    assert.match(res.content[0].text, /cannot be removed|cannot be lifted|not removable/i, "says the cap stays");
+    assert.match(res.content[0].text, /restart/i, "and where the real control is");
+    assert.doesNotMatch(res.content[0].text, /Unlimited|Limit removed/);
+
+    const over = reserveBudget(budget, undefined, 0.6);
+    assert.equal(over.allowed, false, "$1.50 + $0.60 must still be refused under the $2 ceiling");
+  });
+
+  test(`[${rail.name}] budget set above the ceiling is clamped to it, with the reason`, async () => {
+    apiKeyMode = rail.apiKey;
+    activeChain = rail.chain;
+    const { call, budget } = makeHarness(2);
+
+    const res = await call({ action: "budget", budget_action: "set", budget_amount: 1000 });
+    assert.equal(budget.limit, 2, "the raise is clamped, not applied");
+    assert.equal(res.structuredContent.limit, 2);
+    assert.equal(res.structuredContent.clamped, true);
+    assert.match(res.content[0].text, /\$1000\.00/, "echoes what was asked for");
+    assert.match(res.content[0].text, /clamped/i);
+    assert.match(res.content[0].text, /BLOCKRUN_BUDGET_LIMIT/);
+    assert.match(res.content[0].text, /restart/i);
+    assert.doesNotMatch(res.content[0].text, /Set to \$1000/);
+
+    budget.spent = 1.99;
+    assert.equal(reserveBudget(budget, undefined, 0.05).allowed, false, "still capped at $2 after the attempted raise");
+  });
+}
+
+test("the session may LOWER an env cap, and raise it back — but only up to the ceiling", async () => {
+  apiKeyMode = false;
+  activeChain = "solana";
+  const { call, budget } = makeHarness(5);
+
+  const lower = await call({ action: "budget", budget_action: "set", budget_amount: 1 });
+  assert.equal(budget.limit, 1);
+  assert.equal(lower.structuredContent.clamped, false);
+  assert.match(lower.content[0].text, /Set to \$1\.00/);
+  assert.equal(reserveBudget(budget, undefined, 1.5).allowed, false, "the lowered cap bites");
+
+  const back = await call({ action: "budget", budget_action: "set", budget_amount: 5 });
+  assert.equal(budget.limit, 5, "raising back to exactly the ceiling is allowed");
+  assert.equal(back.structuredContent.clamped, false);
+
+  await call({ action: "budget", budget_action: "set", budget_amount: 1 });
+  const cleared = await call({ action: "budget", budget_action: "clear" });
+  assert.equal(budget.limit, 5, "clear after a lower means: back to the operator's number");
+  assert.match(cleared.content[0].text, /\$5\.00/);
+});
+
+test("budget check and report both name the ceiling so the model knows the cap is the operator's", async () => {
+  apiKeyMode = false;
+  activeChain = "base";
+  const { call } = makeHarness(3);
+  const res = await call({ action: "budget" });
+  assert.equal(res.structuredContent.ceiling, 3);
+  assert.match(res.content[0].text, /BLOCKRUN_BUDGET_LIMIT/);
+
+  const report = await call({ action: "report" });
+  assert.equal(report.structuredContent.global.ceiling, 3);
+  assert.match(report.content[0].text, /operator ceiling \$3\.00 via BLOCKRUN_BUDGET_LIMIT/);
+
+  const { call: free } = makeHarness(null);
+  const freeReport = await free({ action: "report" });
+  assert.equal(freeReport.structuredContent.global.ceiling, null);
+  assert.doesNotMatch(freeReport.content[0].text, /ceiling/);
+});
+
+test("a delegated per-agent cap cannot exceed the ceiling either", async () => {
+  apiKeyMode = false;
+  activeChain = "solana";
+  const { call, budget } = makeHarness(2);
+  const res = await call({ action: "delegate", agent_id: "greedy", agent_limit: 50 });
+  assert.equal(budget.agents.get("greedy")!.limit, 2, "clamped to the operator's $2");
+  assert.equal(res.structuredContent.limit, 2);
+  assert.equal(res.structuredContent.remaining, 2);
+  assert.match(res.content[0].text, /\$50\.00/, "echoes the request");
+  assert.match(res.content[0].text, /BLOCKRUN_BUDGET_LIMIT/);
+  assert.match(res.content[0].text, /clamped/i);
+
+  budget.agents.get("greedy")!.spent = 1.99;
+  assert.equal(reserveBudget(budget, "greedy", 0.05).allowed, false, "the agent cap bites at $2, not $50");
+});
+
+test("with no env cap the tool keeps its old contract: set anything, clear to unlimited", async () => {
+  apiKeyMode = false;
+  activeChain = "solana";
+  const { call, budget } = makeHarness(null);
+
+  const set = await call({ action: "budget", budget_action: "set", budget_amount: 1000 });
+  assert.equal(budget.limit, 1000);
+  assert.equal(set.structuredContent.ceiling, null);
+  assert.equal(set.structuredContent.clamped, false);
+  assert.match(set.content[0].text, /Set to \$1000\.00/);
+  assert.doesNotMatch(set.content[0].text, /BLOCKRUN_BUDGET_LIMIT/, "no env, no lecture about one");
+
+  const cleared = await call({ action: "budget", budget_action: "clear" });
+  assert.equal(budget.limit, null);
+  assert.match(cleared.content[0].text, /Unlimited/);
+  assert.match(cleared.content[0].text, /Limit removed/);
+  assert.equal(reserveBudget(budget, undefined, 999).allowed, true);
+
+  const big = await call({ action: "delegate", agent_id: "free", agent_limit: 50 });
+  assert.equal(big.structuredContent.limit, 50, "no ceiling to clamp a delegation against");
+  assert.doesNotMatch(big.content[0].text, /clamped/i);
+});
+
+test("the ceiling is what the server STARTED with — a cap set later in the session is not one", async () => {
+  // An operator with no env who sets $1 via the tool has set a session
+  // control, not a process ceiling: clearing it must still work, or the tool
+  // would lock the very person it is meant to serve out of their own change.
+  apiKeyMode = false;
+  activeChain = "base";
+  const { call, budget } = makeHarness(null);
+  await call({ action: "budget", budget_action: "set", budget_amount: 1 });
+  await call({ action: "budget", budget_action: "clear" });
+  assert.equal(budget.limit, null);
+});
diff --git a/test/budget.test.ts b/test/budget.test.ts
index cffdb45..ca49609 100644
--- a/test/budget.test.ts
+++ b/test/budget.test.ts
@@ -39,16 +39,33 @@ test("recordActualSpend books the real settled cost when known", () => {
   assert.equal(b.calls, 1);
 });
 
-test("recordActualSpend falls back to the estimate when actual is unavailable/zero/negative", () => {
+test("recordActualSpend falls back to the estimate when actual is unavailable (null/undefined/NaN/negative)", () => {
   const b = newBudget();
   recordActualSpend(b, null, 0.02, undefined);
-  recordActualSpend(b, 0, 0.02, undefined);
+  recordActualSpend(b, undefined, 0.02, undefined);
   recordActualSpend(b, -5, 0.02, undefined);
   recordActualSpend(b, NaN, 0.02, undefined);
   assert.equal(Math.round(b.spent * 1000) / 1000, 0.08, "4 × $0.02 estimate");
   assert.equal(b.calls, 4);
 });
 
+// ONE contract for a settled zero, shared with api-key-call.ts and raw-call.ts:
+// `x-blockrun-cost-usd: 0.000000` is the gateway saying "this resolved to
+// nothing", and parseCostHeader preserves it as 0 precisely so it can be booked
+// as 0. Until audit round 3 (D33/D40) this function treated 0 like null and
+// booked the ESTIMATE for it — a free-priced account call was recorded at the
+// reserve, so per-agent caps filled with spend the dashboard showed as $0. Null
+// (header absent, or a wallet call with no counter delta) still means "unknown,
+// use the estimate"; only an explicit finite zero is the truth.
+test("recordActualSpend books an explicit settled ZERO as zero, not as the estimate", () => {
+  const b = newBudget();
+  recordActualSpend(b, 0, 0.02, undefined);
+  assert.equal(b.spent, 0, "a settled $0 is $0");
+  assert.equal(b.calls, 1, "…but it was still a call");
+  recordActualSpend(b, null, 0.02, undefined);
+  assert.equal(Math.round(b.spent * 1000) / 1000, 0.02, "null still books the estimate");
+});
+
 test("budget cap holds once ACTUAL frontier cost is booked (the core fix)", () => {
   // A $1 cap. Each frontier call settles $0.50 on-chain.
   const b = newBudget(1);
diff --git a/test/chain-keychain-probe.test.ts b/test/chain-keychain-probe.test.ts
new file mode 100644
index 0000000..fb88f36
--- /dev/null
+++ b/test/chain-keychain-probe.test.ts
@@ -0,0 +1,138 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// getChain()'s two keychain probes (step 5: "is there a Solana key?", step 6:
+// "is there a Base wallet to strand?") went through keychainLoad(), which
+// collapses a read ERROR — locked keychain, the 5s unlock-dialog timeout, an
+// ACL denial — into the same null as "absent", and memoised that null for the
+// life of the process. Under BLOCKRUN_KEYCHAIN=strict the session files are
+// gone, so a Base-only user whose keychain was locked at the first paid call
+// was read as a fresh install and routed to Solana; unlocking and retrying in
+// the same process changed nothing (memo), the "No Solana wallet yet — run
+// setup" remedy fired, and setup minted a Solana wallet that step 5 selected
+// on every later start. ensureEvmWallet(), a few lines away, refuses to act on
+// the same "error" status. The chain selector has to be at least as careful as
+// the provisioner behind it.
+//
+// Rule: an unreadable keychain is UNKNOWN, never "absent". Unknown is not
+// memoised, and on unknown the selector stays on Base — the chain whose
+// refusal message says "unlock the keychain", rather than the one whose
+// remedy says "run setup".
+import { test, mock, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const home = fs.mkdtempSync(path.join(os.tmpdir(), "br-chain-probe-"));
+const blockrunDir = path.join(home, ".blockrun");
+fs.mkdirSync(blockrunDir, { recursive: true });
+const ENV_NAMES = ["HOME", "BLOCKRUN_HOME", "BLOCKRUN_KEYCHAIN", "BLOCKRUN_WALLET_KEY", "BASE_CHAIN_WALLET_KEY", "SOLANA_WALLET_KEY", "BLOCKRUN_API_KEY"] as const;
+const saved = Object.fromEntries(ENV_NAMES.map((k) => [k, process.env[k]]));
+process.env.HOME = home;
+for (const k of ENV_NAMES) if (k !== "HOME") delete process.env[k];
+
+const EVM_KEY = "0x" + "11".repeat(32);
+const SOL_KEY = "5KJvsngHeMpm884wtkJNzQGaCErckhHJBGFsvd3VyK5qMZXj3hS";
+
+// The keychain under test: `locked` makes every read fail; otherwise it serves
+// whatever `store` holds. Reads are counted so memoisation is observable.
+let locked = false;
+let reads: string[] = [];
+const store = new Map<string, string>();
+mock.module("../src/utils/keychain.js", {
+  namedExports: {
+    EVM_KEY_ACCOUNT: "evm-wallet-key",
+    SOLANA_KEY_ACCOUNT: "solana-wallet-key",
+    getKeychainMode: () => "strict",
+    keychainLoad: (a: string) => {
+      reads.push(a);
+      return locked ? null : store.get(a) ?? null;
+    },
+    keychainRead: (a: string) => {
+      reads.push(a);
+      if (locked) return { status: "error", detail: "security exit 36" };
+      return store.has(a) ? { status: "found", value: store.get(a) } : { status: "absent" };
+    },
+    persistKey: () => {},
+  },
+});
+
+const wallet = await import("../src/utils/wallet.js");
+
+process.on("exit", () => {
+  for (const [k, v] of Object.entries(saved)) {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+  fs.rmSync(home, { recursive: true, force: true });
+});
+
+beforeEach(() => {
+  for (const f of [".session", ".solana-session", "wallet.key", ".chain", ".chain-auto"]) {
+    fs.rmSync(path.join(blockrunDir, f), { force: true });
+  }
+  locked = false;
+  reads = [];
+  store.clear();
+  wallet.resetEvmWalletCache();
+  wallet.resetSolanaKeyCache();
+  wallet.resetKeychainProbeCache();
+});
+
+test("strict Base-only user, keychain locked at start: getChain() stays on Base and recovers after unlock", () => {
+  store.set("evm-wallet-key", EVM_KEY); // the funded wallet, in the keychain only
+  locked = true;
+
+  assert.equal(wallet.getChain(), "base", "an unreadable keychain must not be read as 'no Base wallet here'");
+
+  // The user unlocks the keychain and retries IN THE SAME PROCESS.
+  locked = false;
+  assert.equal(wallet.getChain(), "base");
+  assert.ok(reads.length >= 3, `the failed probes must not have been memoised (reads: ${reads.join(",")})`);
+});
+
+test("strict Solana-only user, keychain locked at start: no migration to a Base wallet either, and unlock is honoured", () => {
+  store.set("solana-wallet-key", SOL_KEY);
+  locked = true;
+
+  const during = wallet.getChain();
+  assert.equal(during, "base", "on uncertainty the selector stays where the refusal says 'unlock', not where the remedy says 'setup'");
+
+  locked = false;
+  assert.equal(wallet.getChain(), "solana", "the Solana key becomes visible as soon as the keychain opens — nothing was memoised");
+});
+
+test("a genuinely absent keychain entry IS memoised — the hot path stays cheap", () => {
+  assert.equal(wallet.getChain(), "solana", "fresh install");
+  const after = reads.length;
+  wallet.getChain();
+  wallet.getChain();
+  assert.equal(reads.length, after, "definite answers are cached for the process");
+});
+
+test("the locked-keychain answer never turns into a 'run setup' remedy on the Solana rail", () => {
+  // The destructive step of the original trace: after the selector said
+  // "solana", buildSolanaClient() reported "No Solana wallet on this machine
+  // yet — run setup". With the selector on Base, the Base path throws its
+  // unlock message instead, and nothing suggests minting.
+  store.set("evm-wallet-key", EVM_KEY);
+  locked = true;
+
+  assert.equal(wallet.getChain(), "base");
+  assert.throws(
+    () => wallet.getClient(),
+    (err: Error) => /Could not read the wallet key from the OS keychain/.test(err.message) && !/run blockrun_wallet action:"setup"/.test(err.message),
+  );
+});
+
+test("after unlock, a later successful probe replaces the earlier failure (no stale 'unknown' either)", () => {
+  store.set("evm-wallet-key", EVM_KEY);
+  locked = true;
+  assert.equal(wallet.getChain(), "base");
+
+  locked = false;
+  assert.equal(wallet.getChain(), "base");
+  const after = reads.length;
+  wallet.getChain();
+  assert.equal(reads.length, after, "once the keychain answered definitively, the answer is memoised");
+});
diff --git a/test/chat-account-rail.test.ts b/test/chat-account-rail.test.ts
new file mode 100644
index 0000000..dabfbec
--- /dev/null
+++ b/test/chat-account-rail.test.ts
@@ -0,0 +1,319 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// blockrun_chat on the ACCOUNT rail (BLOCKRUN_API_KEY): what gets booked, and
+// what the caller is told, for every way a call can end.
+//
+// The 0.50.0 fix for "a billed-then-dropped stream booked $0" made the account
+// branch of withSettledCost treat EVERY rejection as a billed call: a 400
+// (typo'd model), a 401, a 402 out-of-credit, a 60s free-tier timeout — all
+// booked the full gate reserve, all printed "the gateway had already accepted
+// and billed this request … retrying will incur a second charge", and all
+// broke the routing loop before a second candidate was tried. Five typos
+// exhausted a delegated cap with $0 actually billed, and mode:"free" was
+// single-shot on this rail (audit round 3: C5/C18/C23/C31).
+//
+// The account rail CAN tell these apart: the SDK's ApiKeyAuth.fetch throws an
+// APIError carrying the status of the first response, before any body exists —
+// nothing was accepted. Only a failure AFTER a 2xx is a billed call. And on
+// success the rail may carry `x-blockrun-cost-usd`; when it does, THAT is the
+// ledger entry (a settled zero included), and when it does not, the entry is a
+// ledger estimate at the served model's own rate — never the gate reserve,
+// which prices the worst member of the tier at full max_tokens plus a fee this
+// rail does not charge (C33/D53).
+//
+// No network, no key that works anywhere: the client is a fake LLMClient whose
+// chatCompletionStream() answers with a scripted Response or throws the same
+// error shapes the SDK does.
+import { test, mock } from "node:test";
+import assert from "node:assert/strict";
+import type { BudgetState } from "../src/types.js";
+import { CHAT_PRICE_PER_MTOKEN, MODEL_TIERS } from "../src/utils/constants.js";
+
+// Drive account mode through the env var rather than mocking auth.js: the mode
+// is derived from BLOCKRUN_API_KEY, and replacing that module wholesale drops
+// exports other modules import.
+process.env.BLOCKRUN_API_KEY = "brk_live_testkeyfortestsonly0000";
+
+type Attempt =
+  | { kind: "reject"; status: number }
+  | { kind: "abort" }
+  | { kind: "midstream"; partial: string }
+  | { kind: "ok"; text: string; costHeader?: string; usage?: { prompt: number; completion: number }; served?: string; finish?: string };
+
+let script: Map<string, Attempt>;
+let attempts: string[];
+const enc = new TextEncoder();
+
+function sse(frames: unknown[], headers: Record<string, string> = {}): Response {
+  const lines = frames.map((f) => `data: ${JSON.stringify(f)}\n\n`).concat("data: [DONE]\n\n");
+  return new Response(
+    new ReadableStream<Uint8Array>({ start(c) { for (const l of lines) c.enqueue(enc.encode(l)); c.close(); } }),
+    { status: 200, headers: { "content-type": "text/event-stream", ...headers } },
+  );
+}
+
+// The SDK's account transport: `throw new APIError("BlockRun account API error: 402. Top up at …", 402)`.
+function apiError(status: number): Error {
+  const hint = status === 402 ? " Top up at https://user.blockrun.ai/dashboard/credits." : "";
+  return Object.assign(new Error(`BlockRun account API error: ${status}.${hint}`), { name: "APIError", statusCode: status });
+}
+
+function makeFakeClient() {
+  return {
+    // The account rail has no settlement counter — the real SDK THROWS here.
+    getSpending: () => { throw new Error("Account usage is available at the dashboard; getSpending() tracks x402 settlements only."); },
+    // The free tier runs non-streaming on the short-timeout client; same script.
+    chatCompletion: async (model: string) => {
+      attempts.push(model);
+      const a = script.get(model) ?? { kind: "ok", text: `reply from ${model}` };
+      if (a.kind === "reject") throw apiError(a.status);
+      if (a.kind === "abort") throw Object.assign(new Error("This operation was aborted"), { name: "AbortError" });
+      if (a.kind === "midstream") throw new Error("not scripted for the non-streaming fake");
+      return { model: a.served ?? model, choices: [{ message: { content: a.text }, finish_reason: a.finish ?? "stop" }] };
+    },
+    chatCompletionStream: async (model: string) => {
+      attempts.push(model);
+      const a = script.get(model) ?? { kind: "ok", text: `reply from ${model}` };
+      if (a.kind === "reject") throw apiError(a.status);
+      if (a.kind === "abort") throw Object.assign(new Error("This operation was aborted"), { name: "AbortError" });
+      if (a.kind === "midstream") {
+        return sse([
+          { model, choices: [{ delta: { content: a.partial } }] },
+          { error: { message: "upstream exploded" } },
+        ]);
+      }
+      const served = a.served ?? model;
+      return sse([
+        { model: served, choices: [{ delta: { content: a.text }, finish_reason: null }] },
+        { model: served, choices: [{ delta: {}, finish_reason: a.finish ?? "stop" }] },
+        ...(a.usage ? [{ model: served, choices: [], usage: { prompt_tokens: a.usage.prompt, completion_tokens: a.usage.completion } }] : []),
+      ], a.costHeader !== undefined ? { "x-blockrun-cost-usd": a.costHeader } : {});
+    },
+  };
+}
+
+mock.module("../src/utils/wallet.js", {
+  namedExports: {
+    getApiBase: () => "https://api.blockrun.ai",
+    resolveGatewayUrl: (u: string) => u,
+    getChain: () => "solana", // the account rail must win over the chain
+    buildClient: () => makeFakeClient(),
+    buildClientWithTimeout: () => makeFakeClient(),
+    getOrCreateWalletKey: () => { throw new Error("account rail must not touch a wallet key"); },
+    getWalletInfo: async () => ({ address: "0xTEST" }),
+    getAnthropicClient: () => { throw new Error("not used"); },
+    baseOnlyMessage: () => null,
+  },
+});
+
+const { registerChatTool, estimateChatCost } = await import("../src/tools/chat.js");
+
+type Result = { content: Array<{ type: string; text: string }>; structuredContent?: Record<string, unknown>; isError?: boolean };
+function makeHarness(limit = 100) {
+  const budget: BudgetState = { spent: 0, calls: 0, limit, agents: new Map() };
+  let handler: (args: Record<string, unknown>) => Promise<Result>;
+  const server = {
+    registerTool: (_n: string, _c: unknown, h: typeof handler) => { handler = h; },
+  } as unknown as Parameters<typeof registerChatTool>[0];
+  registerChatTool(server, budget);
+  return { budget, call: (args: Record<string, unknown>) => handler!(args) };
+}
+
+const near = (a: number, b: number) => Math.abs(a - b) < 1e-9;
+// The ledger books whole micro-dollars, rounded up (the gateway bills that way).
+const micro = (usd: number) => Math.ceil(usd * 1e6 - 1e-6) / 1e6;
+
+test("account rail: a 402 out-of-credit refusal books $0 and is not reported as billed", async () => {
+  script = new Map([["openai/gpt-5.6-terra", { kind: "reject", status: 402 }]]);
+  attempts = [];
+  const { budget, call } = makeHarness();
+
+  const res = await call({ message: "hi", model: "openai/gpt-5.6-terra", max_tokens: 1024, temperature: 1 });
+
+  assert.equal(res.isError, true);
+  assert.equal(budget.spent, 0, `a refusal before any body settles nothing (booked ${budget.spent})`);
+  assert.match(res.content[0].text, /Top up/, res.content[0].text);
+  // The SDK threw from the first non-OK response: nothing was accepted, so the
+  // text must not claim a charge or warn the caller off a retry.
+  assert.doesNotMatch(res.content[0].text, /charge stands|has been billed|is billed|second charge|already accepted/i, res.content[0].text);
+});
+
+test("account rail: a 400 (typo'd model) books $0 — five typos must not exhaust a delegated cap", async () => {
+  script = new Map([["openai/gpt-5.6-tera", { kind: "reject", status: 400 }]]);
+  attempts = [];
+  const { budget, call } = makeHarness();
+  budget.agents.set("a1", { limit: 0.1, spent: 0, calls: 0 });
+
+  for (let i = 0; i < 5; i++) {
+    const res = await call({ message: "hi", model: "openai/gpt-5.6-tera", max_tokens: 1024, temperature: 1, agent_id: "a1" });
+    assert.equal(res.isError, true);
+    assert.doesNotMatch(res.content[0].text, /charge stands|billed|second charge/i, res.content[0].text);
+  }
+  assert.equal(budget.spent, 0);
+  assert.equal(budget.agents.get("a1")!.spent, 0, "phantom spend must not consume the agent's cap");
+  assert.equal(attempts.length, 5, "each call reached the gateway — the cap was never falsely tripped");
+});
+
+test("account rail: the routing loop falls through a pre-accept refusal to the next model", async () => {
+  script = new Map([
+    ["deepseek/deepseek-v4-pro", { kind: "reject", status: 429 }],
+    ["qwen/qwen3.7-flash", { kind: "ok", text: "qwen answers", usage: { prompt: 100, completion: 50 } }],
+  ]);
+  attempts = [];
+  const { budget, call } = makeHarness();
+
+  const res = await call({ message: "hi", mode: "cheap", max_tokens: 1024, temperature: 1 });
+
+  assert.equal(res.isError, undefined, res.content[0].text);
+  assert.deepEqual(attempts, ["deepseek/deepseek-v4-pro", "qwen/qwen3.7-flash"], "a 429 before any body must not end the loop");
+  // Booked at the SERVED model's own rate from the usage the stream reported,
+  // with no transaction fee — not the tier's worst member at full max_tokens.
+  const rate = CHAT_PRICE_PER_MTOKEN["qwen/qwen3.7-flash"];
+  const expected = micro((100 * rate.input + 50 * rate.output) / 1e6);
+  assert.ok(near(budget.spent, expected), `booked ${budget.spent}, expected the usage-based ${expected}`);
+  const reserve = estimateChatCost(1024, "cheap", undefined, undefined, 2);
+  assert.ok(budget.spent < reserve / 10, `the gate reserve (${reserve}) must not be what the ledger books`);
+});
+
+test("account rail: mode:\"free\" keeps falling through after a timeout and a refusal, and books $0", async () => {
+  const [first, second, third] = MODEL_TIERS.free;
+  script = new Map<string, Attempt>([
+    [first, { kind: "abort" }],
+    [second, { kind: "reject", status: 429 }],
+    [third, { kind: "ok", text: "free answer" }],
+  ]);
+  attempts = [];
+  const { budget, call } = makeHarness();
+
+  const res = await call({ message: "hi", mode: "free", max_tokens: 1024, temperature: 1 });
+
+  assert.equal(res.isError, undefined, res.content[0].text);
+  assert.deepEqual(attempts, [first, second, third], "a $0 tier can never have been billed — the loop must walk on");
+  assert.equal(budget.spent, 0);
+});
+
+test("account rail: a failure AFTER the 200 is billed — booked at the model's ledger rate, said plainly, partial text kept", async () => {
+  script = new Map([["openai/gpt-5.6-terra", { kind: "midstream", partial: "the first 900 tokens" }]]);
+  attempts = [];
+  const { budget, call } = makeHarness();
+
+  const res = await call({ message: "hi", model: "openai/gpt-5.6-terra", max_tokens: 1024, temperature: 1 });
+
+  assert.equal(res.isError, true);
+  // Accepted with a 200, so the account is billed at exact usage. No usage
+  // arrived, so the entry is the model's own rate over the prompt and the full
+  // max_tokens — no tier worst-case, no transaction fee.
+  const rate = CHAT_PRICE_PER_MTOKEN["openai/gpt-5.6-terra"];
+  const expected = micro((Math.ceil(2 / 2.08) * rate.input + 1024 * rate.output) / 1e6);
+  assert.ok(near(budget.spent, expected), `booked ${budget.spent}, expected ${expected}`);
+  assert.ok(budget.spent < estimateChatCost(1024, undefined, "openai/gpt-5.6-terra", undefined, 2), "must book below the gate reserve");
+  assert.match(res.content[0].text, /accepted/i, res.content[0].text);
+  assert.match(res.content[0].text, /billed/i, res.content[0].text);
+  assert.match(res.content[0].text, /second charge/i, res.content[0].text);
+  assert.doesNotMatch(res.content[0].text, /needs funding/, res.content[0].text);
+  // The 900 tokens the caller paid for are surfaced, not discarded.
+  assert.match(res.content[0].text, /the first 900 tokens/, res.content[0].text);
+  assert.equal(res.structuredContent?.partial_response, "the first 900 tokens");
+});
+
+test("account rail: a timeout with no response observed MAY have been billed — booked as a precaution, no fallback", async () => {
+  script = new Map([
+    ["deepseek/deepseek-v4-pro", { kind: "abort" }],
+    ["qwen/qwen3.7-flash", { kind: "ok", text: "never reached" }],
+  ]);
+  attempts = [];
+  const { budget, call } = makeHarness();
+
+  const res = await call({ message: "hi", mode: "cheap", max_tokens: 1024, temperature: 1 });
+
+  assert.equal(res.isError, true);
+  assert.deepEqual(attempts, ["deepseek/deepseek-v4-pro"], "a paid call that may have been billed must not be followed by a second paid model");
+  assert.ok(budget.spent > 0, "the precautionary booking must land");
+  assert.match(res.content[0].text, /may have been billed/i, res.content[0].text);
+  assert.doesNotMatch(res.content[0].text, /charge stands/, "no charge is certain here");
+});
+
+test("account rail: x-blockrun-cost-usd on the response is the ledger entry, exactly", async () => {
+  script = new Map([["openai/gpt-5.6-terra", { kind: "ok", text: "hello", costHeader: "0.003100", usage: { prompt: 5000, completion: 900 } }]]);
+  attempts = [];
+  const { budget, call } = makeHarness();
+
+  const res = await call({ message: "hi", model: "openai/gpt-5.6-terra", max_tokens: 1024, temperature: 1 });
+
+  assert.equal(res.isError, undefined, res.content[0].text);
+  assert.ok(near(budget.spent, 0.0031), `booked ${budget.spent}, header said 0.0031`);
+  assert.equal(res.structuredContent?.cost_usd, 0.0031);
+  assert.equal(res.structuredContent?.cost_is_estimate, false);
+  assert.doesNotMatch(res.content[0].text, /~\$/, "a settled figure is not printed as an estimate");
+});
+
+test("account rail: a settled ZERO in the header books $0, not the estimate", async () => {
+  script = new Map([["openai/gpt-5.6-terra", { kind: "ok", text: "hello", costHeader: "0.000000", usage: { prompt: 5000, completion: 900 } }]]);
+  attempts = [];
+  const { budget, call } = makeHarness();
+
+  await call({ message: "hi", model: "openai/gpt-5.6-terra", max_tokens: 1024, temperature: 1 });
+
+  assert.equal(budget.spent, 0, `the gateway priced this at zero; booked ${budget.spent}`);
+  assert.equal(budget.calls, 1);
+});
+
+test("account rail: without the header the ledger is the served model's rate over reported usage, labelled as an estimate", async () => {
+  script = new Map([["openai/gpt-5.6-terra", { kind: "ok", text: "hello", usage: { prompt: 100, completion: 50 } }]]);
+  attempts = [];
+  const { budget, call } = makeHarness();
+
+  const res = await call({ message: "hi", model: "openai/gpt-5.6-terra", max_tokens: 1024, temperature: 1 });
+
+  const rate = CHAT_PRICE_PER_MTOKEN["openai/gpt-5.6-terra"];
+  const expected = micro((100 * rate.input + 50 * rate.output) / 1e6);
+  assert.ok(near(budget.spent, expected), `booked ${budget.spent}, expected ${expected}`);
+  assert.equal(res.structuredContent?.cost_is_estimate, true);
+  assert.match(res.content[0].text, /~\$0\.0008/, res.content[0].text);
+  assert.match(res.content[0].text, /exact usage/i, res.content[0].text);
+});
+
+test("account rail: the multi-turn path books the same way", async () => {
+  script = new Map([["openai/gpt-5.6-terra", { kind: "ok", text: "and so on", usage: { prompt: 200, completion: 20 } }]]);
+  attempts = [];
+  const { budget, call } = makeHarness();
+
+  const res = await call({
+    message: "and then?",
+    model: "openai/gpt-5.6-terra",
+    messages: [{ role: "user", content: "hi" }, { role: "assistant", content: "hello" }],
+    max_tokens: 1024,
+    temperature: 1,
+  });
+
+  assert.equal(res.isError, undefined, res.content[0].text);
+  const rate = CHAT_PRICE_PER_MTOKEN["openai/gpt-5.6-terra"];
+  assert.ok(near(budget.spent, micro((200 * rate.input + 20 * rate.output) / 1e6)), `booked ${budget.spent}`);
+});
+
+test("account rail: a free request served under another (unpriced) id still books $0", async () => {
+  // The gateway's free fallback answers a free id from whatever has capacity;
+  // the alias target has no price row. Booking DEFAULT_CHAT_PRICE for that
+  // would charge the ledger $5/$30 for a call the gateway served free.
+  const [first] = MODEL_TIERS.free;
+  script = new Map<string, Attempt>([[first, { kind: "ok", text: "free", served: "nvidia/nemotron-3-super-120b", usage: { prompt: 900, completion: 40 } }]]);
+  attempts = [];
+  const { budget, call } = makeHarness();
+
+  const res = await call({ message: "hi", mode: "free", max_tokens: 1024, temperature: 1 });
+
+  assert.equal(res.isError, undefined, res.content[0].text);
+  assert.equal(budget.spent, 0, `booked ${budget.spent} for a free call`);
+  assert.equal(res.structuredContent?.served_model, "nvidia/nemotron-3-super-120b");
+});
+
+test("account rail: a paid request answered by a priced alias is booked at the alias's rate", async () => {
+  script = new Map<string, Attempt>([["moonshot/kimi-k2.6", { kind: "ok", text: "k3", served: "moonshot/kimi-k3", usage: { prompt: 1000, completion: 100 } }]]);
+  attempts = [];
+  const { budget, call } = makeHarness();
+
+  await call({ message: "hi", model: "moonshot/kimi-k2.6", max_tokens: 1024, temperature: 1 });
+
+  const rate = CHAT_PRICE_PER_MTOKEN["moonshot/kimi-k3"];
+  assert.ok(near(budget.spent, micro((1000 * rate.input + 100 * rate.output) / 1e6)), `booked ${budget.spent}`);
+});
diff --git a/test/chat-anthropic-account.test.ts b/test/chat-anthropic-account.test.ts
new file mode 100644
index 0000000..4dc0742
--- /dev/null
+++ b/test/chat-anthropic-account.test.ts
@@ -0,0 +1,101 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// The native claude-* path on the ACCOUNT rail. Mode is derived from
+// BLOCKRUN_API_KEY at first use and fixed for the process, so the account-rail
+// cases live here and the wallet-rail ones in chat-anthropic-settled.test.ts.
+//
+// Two things differ on this rail and both were wrong (audit round 3, C20/D58):
+// the ledger added the $0.001 x402 transaction fee that api.blockrun.ai never
+// charges, and it booked the x402 QUOTE formula (0.1 x max_tokens) on a rail
+// that bills exact usage. And a call the account accepted and then lost booked
+// $0 with no note at all.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import type Anthropic from "@anthropic-ai/sdk";
+import { handleAnthropicNative } from "../src/tools/chat-anthropic.js";
+import { CHAT_PRICE_PER_MTOKEN } from "../src/utils/constants.js";
+import type { BudgetState } from "../src/types.js";
+
+process.env.BLOCKRUN_API_KEY = "brk_live_testkeyfortestsonly0000";
+
+function newBudget(): BudgetState {
+  return { limit: 100, spent: 0, calls: 0, agents: new Map() };
+}
+function message(): Anthropic.Message {
+  return {
+    id: "msg_1", type: "message", role: "assistant", model: "claude-haiku-4-5-20251001",
+    content: [{ type: "text", text: "hello", citations: null }],
+    stop_reason: "end_turn", stop_sequence: null,
+    usage: { input_tokens: 100, output_tokens: 50, cache_creation_input_tokens: null, cache_read_input_tokens: null, server_tool_use: null, service_tier: null },
+  } as Anthropic.Message;
+}
+function fakeClient(s: { connect: boolean; events?: number; result: Anthropic.Message | Error; costHeader?: string }) {
+  return {
+    messages: {
+      stream: () => {
+        const listeners: Record<string, Array<(...a: unknown[]) => void>> = {};
+        const self = {
+          on(ev: string, cb: (...a: unknown[]) => void) { (listeners[ev] ??= []).push(cb); return self; },
+          off() { return self; },
+          abort() {},
+          response: s.costHeader === undefined ? null : new Response(null, { headers: { "x-blockrun-cost-usd": s.costHeader } }),
+          finalMessage: async () => {
+            await Promise.resolve();
+            if (s.connect) for (const cb of listeners.connect ?? []) cb();
+            for (let i = 0; i < (s.events ?? 0); i++) for (const cb of listeners.streamEvent ?? []) cb({ type: "content_block_delta" });
+            if (s.result instanceof Error) throw s.result;
+            return s.result;
+          },
+        };
+        return self;
+      },
+    },
+  };
+}
+const near = (a: number, b: number) => Math.abs(a - b) < 1e-9;
+const micro = (usd: number) => Math.ceil(usd * 1e6 - 1e-6) / 1e6;
+const baseArgs = { model: "anthropic/claude-haiku-4.5", message: "hi", maxTokens: 1024, estimatedCost: 0.05 };
+
+test("account rail: success books reported usage at the model's own rate — no transaction fee, no quote formula (D58)", async () => {
+  const budget = newBudget();
+  const res = await handleAnthropicNative({ client: fakeClient({ connect: true, events: 2, result: message() }) as never, ...baseArgs, budget });
+  assert.equal(res.isError, undefined, res.content[0].text);
+  const rate = CHAT_PRICE_PER_MTOKEN["anthropic/claude-haiku-4.5"];
+  // 100 in / 50 out at $1/$5 per M = $0.00035. The old ledger booked $0.002
+  // (the $0.001 quote floor plus a $0.001 fee this rail does not charge).
+  assert.ok(near(budget.spent, micro((100 * rate.input + 50 * rate.output) / 1e6)), `booked ${budget.spent}`);
+  assert.equal(res.structuredContent?.cost_is_estimate, true);
+  assert.match(res.content[0].text, /Cost: ~\$0\.000[34]/, res.content[0].text);
+  assert.match(res.content[0].text, /exact usage/, res.content[0].text);
+});
+
+test("account rail: x-blockrun-cost-usd on the stream response is the ledger entry", async () => {
+  const budget = newBudget();
+  await handleAnthropicNative({ client: fakeClient({ connect: true, events: 2, result: message(), costHeader: "0.001200" }) as never, ...baseArgs, budget });
+  assert.ok(near(budget.spent, 0.0012), `booked ${budget.spent}`);
+});
+
+test("account rail: a 402 out-of-credit before any stream books nothing and is not called billed", async () => {
+  const budget = newBudget();
+  const err = Object.assign(new Error("402 BlockRun account API error: 402. Top up at https://user.blockrun.ai/dashboard/credits."), { status: 402 });
+  const res = await handleAnthropicNative({ client: fakeClient({ connect: false, result: err }) as never, ...baseArgs, budget });
+  assert.equal(res.isError, true);
+  assert.equal(budget.spent, 0);
+  assert.doesNotMatch(res.content[0].text, /charge stands|has been billed|is billed|second charge/i, res.content[0].text);
+});
+
+test("account rail: a failure after the stream connected is billed at exact usage — booked at the model's rate over max_tokens, said plainly", async () => {
+  const budget = newBudget();
+  const err = Object.assign(new Error("Connection error."), { status: undefined, cause: new Error("terminated") });
+  const res = await handleAnthropicNative({ client: fakeClient({ connect: true, events: 3, result: err }) as never, ...baseArgs, budget });
+  assert.equal(res.isError, true);
+  const rate = CHAT_PRICE_PER_MTOKEN["anthropic/claude-haiku-4.5"];
+  // Prompt at the observed chars/token plus the gateway's ~20-token message
+  // envelope (the same fit anthropicCallCost uses), output at the full
+  // max_tokens — nothing was reported, so the conservative side — no fee.
+  const expected = micro(((Math.ceil(2 / 2.08) + 20) * rate.input + 1024 * rate.output) / 1e6);
+  assert.ok(near(budget.spent, expected), `booked ${budget.spent}, expected ${expected}`);
+  assert.match(res.content[0].text, /accepted/i, res.content[0].text);
+  assert.match(res.content[0].text, /billed/i, res.content[0].text);
+  assert.match(res.content[0].text, /second charge/i, res.content[0].text);
+});
diff --git a/test/chat-anthropic-settled.test.ts b/test/chat-anthropic-settled.test.ts
new file mode 100644
index 0000000..fb50d34
--- /dev/null
+++ b/test/chat-anthropic-settled.test.ts
@@ -0,0 +1,191 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// The native claude-* path (chat-anthropic.ts) and money.
+//
+// Until audit round 3 (C20) handleAnthropicNative caught every error from the
+// SDK and returned formatError with no booking and no note — the settled-then-
+// failed machinery 0.40.1/0.49.0/0.50.0 wired into the three OpenAI-compat
+// paths never reached this one. Worse, on the wallet rail @blockrun/llm builds
+// the official SDK at its default maxRetries=2 with a fetch that signs a FRESH
+// x402 payment on every 402 it sees, so a 5xx/524/timeout after settlement was
+// retried up to twice more — three settlements for one undelivered answer, none
+// in the ledger, and text that said "try again".
+//
+// Two more findings ride on the same call: D51 — a non-streaming request with
+// max_tokens above 21,333 (every thinking budget >= 20,310) never left the
+// process, because @anthropic-ai/sdk refuses it ("Streaming is required…") —
+// and D58, the $0.001 tx fee the ledger added on the account rail, which
+// charges none.
+//
+// The client here is a fake MessageStream; the last test uses the REAL SDK
+// against a canned fetch to prove the streaming route sidesteps the guard.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import Anthropic from "@anthropic-ai/sdk";
+import { handleAnthropicNative, anthropicCallCost } from "../src/tools/chat-anthropic.js";
+import type { BudgetState } from "../src/types.js";
+
+// Wallet rail throughout: no BLOCKRUN_API_KEY. The account-rail twin of these
+// cases lives in chat-anthropic-account.test.ts (mode is fixed per process).
+delete process.env.BLOCKRUN_API_KEY;
+
+function newBudget(): BudgetState {
+  return { limit: 100, spent: 0, calls: 0, agents: new Map() };
+}
+
+function message(over: Partial<Anthropic.Message> = {}): Anthropic.Message {
+  return {
+    id: "msg_1", type: "message", role: "assistant", model: "claude-haiku-4-5-20251001",
+    content: [{ type: "text", text: "hello", citations: null }],
+    stop_reason: "end_turn", stop_sequence: null,
+    usage: { input_tokens: 100, output_tokens: 50, cache_creation_input_tokens: null, cache_read_input_tokens: null, server_tool_use: null, service_tier: null },
+    ...over,
+  } as Anthropic.Message;
+}
+
+type FakeScript = { connect: boolean; events?: number; result: Anthropic.Message | Error };
+let lastOptions: Record<string, unknown> | undefined;
+let lastParams: Record<string, unknown> | undefined;
+
+// A stand-in for the SDK's MessageStream: `connect` fires once the 2xx is in,
+// `streamEvent` per frame, and finalMessage() resolves or rejects.
+function fakeClient(s: FakeScript) {
+  return {
+    messages: {
+      create: async () => { throw new Error("the native path must stream — create() must not be called"); },
+      stream: (params: Record<string, unknown>, options?: Record<string, unknown>) => {
+        lastParams = params;
+        lastOptions = options;
+        const listeners: Record<string, Array<(...a: unknown[]) => void>> = {};
+        const self = {
+          on(ev: string, cb: (...a: unknown[]) => void) { (listeners[ev] ??= []).push(cb); return self; },
+          off() { return self; },
+          abort() {},
+          response: null,
+          finalMessage: async () => {
+            await Promise.resolve();
+            if (s.connect) for (const cb of listeners.connect ?? []) cb();
+            for (let i = 0; i < (s.events ?? 0); i++) for (const cb of listeners.streamEvent ?? []) cb({ type: "content_block_delta" });
+            if (s.result instanceof Error) throw s.result;
+            return s.result;
+          },
+        };
+        return self;
+      },
+    },
+  };
+}
+
+function sdkError(status: number | undefined, msg: string, cause?: Error): Error {
+  return Object.assign(new Error(msg), { status, cause });
+}
+
+const near = (a: number, b: number) => Math.abs(a - b) < 1e-9;
+const baseArgs = { model: "anthropic/claude-haiku-4.5", message: "hi", maxTokens: 1024, estimatedCost: 0.05 };
+
+test("the native call is streamed with maxRetries: 0 — one payment, never re-signed by the SDK's retry loop", async () => {
+  const client = fakeClient({ connect: true, events: 3, result: message() });
+  const res = await handleAnthropicNative({ client: client as never, ...baseArgs, budget: newBudget() });
+  assert.equal(res.isError, undefined, res.content[0].text);
+  assert.equal(lastOptions?.maxRetries, 0, "the SDK must not retry (each retry pays a fresh 402)");
+  assert.equal(lastParams?.model, "anthropic/claude-haiku-4.5");
+});
+
+test("a 4xx before any stream connected books nothing and carries no charge note", async () => {
+  const budget = newBudget();
+  const client = fakeClient({ connect: false, result: sdkError(400, "400 max_tokens: invalid") });
+  const res = await handleAnthropicNative({ client: client as never, ...baseArgs, budget });
+  assert.equal(res.isError, true);
+  assert.equal(budget.spent, 0, `booked ${budget.spent}`);
+  assert.doesNotMatch(res.content[0].text, /charge stands|may have|billed/i, res.content[0].text);
+});
+
+test("a payment the wallet could not make is not money", async () => {
+  const budget = newBudget();
+  const client = fakeClient({ connect: false, result: sdkError(undefined, "Connection error.", new Error("Payment was rejected. Check your wallet balance.")) });
+  const res = await handleAnthropicNative({ client: client as never, ...baseArgs, budget });
+  assert.equal(res.isError, true);
+  assert.equal(budget.spent, 0);
+  assert.doesNotMatch(res.content[0].text, /charge stands|may have settled/i, res.content[0].text);
+});
+
+test("a 5xx/524 with no stream connected MAY have settled — booked at the reconstructed quote, said so, no retry advice", async () => {
+  const budget = newBudget();
+  const client = fakeClient({ connect: false, result: sdkError(524, "524 status code (no body)") });
+  const res = await handleAnthropicNative({ client: client as never, ...baseArgs, budget });
+  assert.equal(res.isError, true);
+  const expected = anthropicCallCost("anthropic/claude-haiku-4.5", 2, 1024)!;
+  assert.ok(near(budget.spent, expected), `booked ${budget.spent}, expected the quote ${expected}`);
+  assert.match(res.content[0].text, /may have (settled|been billed)|cannot tell whether/i, res.content[0].text);
+  assert.match(res.content[0].text, /second charge/i, res.content[0].text);
+  assert.doesNotMatch(res.content[0].text, /needs funding/, res.content[0].text);
+});
+
+test("a failure AFTER the stream connected is a settled call — booked, and said plainly", async () => {
+  const budget = newBudget();
+  const client = fakeClient({ connect: true, events: 2, result: sdkError(undefined, "Connection error.", new Error("terminated")) });
+  const res = await handleAnthropicNative({ client: client as never, ...baseArgs, budget });
+  assert.equal(res.isError, true);
+  assert.ok(budget.spent > 0, `booked ${budget.spent}`);
+  assert.match(res.content[0].text, /charge stands/, res.content[0].text);
+  assert.match(res.content[0].text, /second charge/i, res.content[0].text);
+});
+
+test("a thinking budget above the SDK's non-streaming ceiling is sent, not refused in-process (D51)", async () => {
+  const client = fakeClient({ connect: true, events: 1, result: message() });
+  const res = await handleAnthropicNative({
+    client: client as never, ...baseArgs, model: "anthropic/claude-opus-5", thinking: { type: "enabled", budget_tokens: 32_000 }, budget: newBudget(),
+  });
+  assert.equal(res.isError, undefined, res.content[0].text);
+  assert.equal(lastParams?.max_tokens, 33_024, "max_tokens auto-raised above the budget");
+});
+
+test("wallet rail: success books the reconstructed quote, fee included", async () => {
+  const budget = newBudget();
+  const client = fakeClient({ connect: true, events: 2, result: message() });
+  const res = await handleAnthropicNative({ client: client as never, ...baseArgs, budget });
+  assert.equal(res.isError, undefined, res.content[0].text);
+  assert.ok(near(budget.spent, anthropicCallCost("claude-haiku-4-5-20251001", 2, 1024)!), `booked ${budget.spent}`);
+  // The wallet quote formula still carries the observed fee and the floor.
+  assert.equal(anthropicCallCost("claude-haiku-4-5-20251001", 2, 1024), 0.002);
+});
+
+// The real SDK, no network: the fetch stub answers /v1/messages with a canned
+// SSE message. `create()` with max_tokens 33,024 must refuse before fetch
+// (that is the D51 failure); `stream()` must go through and assemble it.
+test("real @anthropic-ai/sdk: create() refuses 33k max_tokens non-streaming, stream() carries it (D51)", async () => {
+  let fetches = 0;
+  const enc = new TextEncoder();
+  const sse = [
+    { type: "message_start", message: { id: "msg_1", type: "message", role: "assistant", model: "claude-opus-5", content: [], stop_reason: null, stop_sequence: null, usage: { input_tokens: 3, output_tokens: 1 } } },
+    { type: "content_block_start", index: 0, content_block: { type: "thinking", thinking: "", signature: "" } },
+    { type: "content_block_delta", index: 0, delta: { type: "thinking_delta", thinking: "let me think" } },
+    { type: "content_block_delta", index: 0, delta: { type: "signature_delta", signature: "sig123" } },
+    { type: "content_block_stop", index: 0 },
+    { type: "content_block_start", index: 1, content_block: { type: "text", text: "" } },
+    { type: "content_block_delta", index: 1, delta: { type: "text_delta", text: "42" } },
+    { type: "content_block_stop", index: 1 },
+    { type: "message_delta", delta: { stop_reason: "end_turn", stop_sequence: null }, usage: { output_tokens: 7 } },
+    { type: "message_stop" },
+  ].map((e) => `event: ${e.type}\ndata: ${JSON.stringify(e)}\n\n`).join("");
+  const fetchStub = async () => {
+    fetches += 1;
+    return new Response(new ReadableStream<Uint8Array>({ start(c) { c.enqueue(enc.encode(sse)); c.close(); } }), {
+      status: 200, headers: { "content-type": "text/event-stream" },
+    });
+  };
+  const client = new Anthropic({ apiKey: "blockrun", baseURL: "https://gateway.invalid/api", fetch: fetchStub as unknown as typeof fetch, maxRetries: 0 });
+  const params = { model: "claude-opus-5", max_tokens: 33_024, messages: [{ role: "user" as const, content: "hi" }], thinking: { type: "enabled" as const, budget_tokens: 32_000 } };
+
+  // The guard fires synchronously, before the request is even built.
+  assert.throws(() => client.messages.create(params), /Streaming is required/);
+  assert.equal(fetches, 0, "the non-streaming refusal happens before any request");
+
+  const final = await client.messages.stream(params, { maxRetries: 0 }).finalMessage();
+  assert.equal(fetches, 1);
+  assert.equal(final.stop_reason, "end_turn");
+  const thinking = final.content.find((b) => b.type === "thinking") as Anthropic.ThinkingBlock | undefined;
+  assert.equal(thinking?.thinking, "let me think");
+  assert.equal(thinking?.signature, "sig123", "the signature survives streaming assembly");
+  assert.equal((final.content.find((b) => b.type === "text") as Anthropic.TextBlock).text, "42");
+});
diff --git a/test/chat-free-deadline.test.ts b/test/chat-free-deadline.test.ts
index 0812756..20ad158 100644
--- a/test/chat-free-deadline.test.ts
+++ b/test/chat-free-deadline.test.ts
@@ -30,19 +30,19 @@ const realDateNow = Date.now;
 
 function makeFakeClient(timeout?: number) {
   return {
-    chat: async (model: string) => {
+    chatCompletion: async (model: string) => {
       attempts.push(model);
       // Emulate the SDK's AbortController: a model slower than its timeout burns
       // the whole timeout and then rejects. Time passes on the virtual clock.
       const budgetMs = timeout ?? 600_000;
       if (modelLatencyMs >= budgetMs) {
         now += budgetMs;
-        throw new Error(`timeout after ${budgetMs}ms`);
+        throw Object.assign(new Error("This operation was aborted"), { name: "AbortError" });
       }
       now += modelLatencyMs;
-      return "hello from " + model;
+      return { model, choices: [{ message: { content: "hello from " + model }, finish_reason: "stop" }] };
     },
-    getSpending: () => 0,
+    getSpending: () => ({ totalUsd: 0 }),
   };
 }
 
diff --git a/test/chat-settled-on-error.test.ts b/test/chat-settled-on-error.test.ts
index 3eb422f..dda2400 100644
--- a/test/chat-settled-on-error.test.ts
+++ b/test/chat-settled-on-error.test.ts
@@ -18,6 +18,7 @@
 import { test, mock } from "node:test";
 import assert from "node:assert/strict";
 import type { BudgetState } from "../src/types.js";
+import { MODEL_TIERS } from "../src/utils/constants.js";
 
 const TEST_KEY = "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d";
 
@@ -163,10 +164,11 @@ test("the routing loop stops after a payment settles — one reservation, one ch
 test("the routing loop still falls through when nothing settled (the free tier's whole design)", async () => {
   // Free NVIDIA models settle $0. A failure there must NOT stop the fallback,
   // or mode:"free" loses the resilience it exists for.
+  const [first, second, third] = MODEL_TIERS.free;
   script = new Map([
-    ["nvidia/gpt-oss-120b", { settleUsd: 0, fail: true }],
-    ["nvidia/nemotron-3-nano-omni-30b-a3b-reasoning", { settleUsd: 0, fail: true }],
-    ["nvidia/step-3.7-flash", { settleUsd: 0, fail: false }],
+    [first, { settleUsd: 0, fail: true }],
+    [second, { settleUsd: 0, fail: true }],
+    [third, { settleUsd: 0, fail: false }],
   ]);
   attempts = [];
   const { budget, call } = makeHarness();
diff --git a/test/chat-stream.test.ts b/test/chat-stream.test.ts
index 26e61fb..4377d8a 100644
--- a/test/chat-stream.test.ts
+++ b/test/chat-stream.test.ts
@@ -110,11 +110,15 @@ test("a bodyless response throws loudly", async () => {
   await assert.rejects(assembleSseChatStream({ body: null }), /no body/);
 });
 
-// The Solana client has no chatCompletionStream — the capability check is what
-// keeps those callers on the old non-streaming path instead of crashing.
-test("supportsStreaming distinguishes streaming-capable clients", () => {
+// The Solana client has no chatCompletionStream (it streams frames through
+// stream() instead — see completeChat); the two capability checks are what
+// route each client to the right assembler instead of crashing.
+test("supportsStreaming / supportsFrameStreaming distinguish the two client shapes", async () => {
+  const { supportsFrameStreaming } = await import("../src/utils/chat-stream.js");
   assert.equal(supportsStreaming({ chatCompletionStream: async () => new Response() } as unknown as ApiClient), true);
   assert.equal(supportsStreaming({ chat: async () => "" } as unknown as ApiClient), false);
+  assert.equal(supportsFrameStreaming({ stream: async function* () { yield 1; } } as unknown as ApiClient), true);
+  assert.equal(supportsFrameStreaming({ chat: async () => "" } as unknown as ApiClient), false);
 });
 
 // A reasoning model can burn the whole max_tokens budget thinking and emit
@@ -138,3 +142,149 @@ test("empty text + finish_reason length throws a max_tokens diagnosis", async ()
     /entire max_tokens budget on internal reasoning/,
   );
 });
+
+// ── What the gateway SAYS answered, and how it stopped ──
+//
+// Every SSE chunk carries `model`, and the last one carries `usage`
+// ($0 probes on both gateways, 2026-09-13). The assembler used to read only
+// the deltas and finish_reason, so a retired id that the gateway aliased onto
+// another model was reported back under the requested name (D55), and a reply
+// cut at max_tokens came back looking complete (D57).
+test("the served model and the usage chunk are surfaced alongside the text", async () => {
+  const { text, finishReason, servedModel, usage } = await assembleSseChatStream(bodyFrom([
+    chunk({ model: "nvidia/nemotron-3-super-120b", choices: [{ delta: { content: "hi" } }] }),
+    chunk({ model: "nvidia/nemotron-3-super-120b", choices: [{ delta: {}, finish_reason: "length" }] }),
+    chunk({ model: "nvidia/nemotron-3-super-120b", choices: [], usage: { prompt_tokens: 74, completion_tokens: 24, total_tokens: 98 } }),
+    "data: [DONE]\n\n",
+  ]));
+  assert.equal(text, "hi");
+  assert.equal(finishReason, "length");
+  assert.equal(servedModel, "nvidia/nemotron-3-super-120b");
+  assert.deepEqual(usage, { promptTokens: 74, completionTokens: 24 });
+});
+
+test("a stream with no model or usage fields reports them as null, never as a guess", async () => {
+  const { servedModel, usage } = await assembleSseChatStream(bodyFrom([delta("x")]));
+  assert.equal(servedModel, null);
+  assert.equal(usage, null);
+});
+
+test("an in-band error after partial text carries the partial text on the error", async () => {
+  const { AcceptedThenFailedError } = await import("../src/utils/chat-stream.js");
+  await assert.rejects(
+    assembleSseChatStream(bodyFrom([delta("the first 900 tokens"), chunk({ error: { message: "upstream exploded" } })])),
+    (err: unknown) => err instanceof AcceptedThenFailedError && err.partialText === "the first 900 tokens",
+  );
+});
+
+test("the same assembler consumes decoded frames (the Solana client's stream()) with an idle guard", async () => {
+  const { assembleChatFrames } = await import("../src/utils/chat-stream.js");
+  async function* frames() {
+    yield { model: "openai/gpt-5.6-terra", choices: [{ delta: { content: "sol " } }] };
+    yield { model: "openai/gpt-5.6-terra", choices: [{ delta: { content: "stream" }, finish_reason: "stop" }] };
+    yield { choices: [], usage: { prompt_tokens: 3, completion_tokens: 2 } };
+  }
+  const out = await assembleChatFrames(frames());
+  assert.equal(out.text, "sol stream");
+  assert.equal(out.servedModel, "openai/gpt-5.6-terra");
+  assert.equal(out.finishReason, "stop");
+  assert.deepEqual(out.usage, { promptTokens: 3, completionTokens: 2 });
+
+  async function* stalls() {
+    yield { choices: [{ delta: { content: "start" } }] };
+    await new Promise(() => undefined); // never yields again
+  }
+  await assert.rejects(assembleChatFrames(stalls(), 50), /stream stalled/);
+});
+
+test("streamChatText reads x-blockrun-cost-usd off the response when the rail sends it", async () => {
+  const { streamChatText } = await import("../src/utils/chat-stream.js");
+  const body = (frames: string[]) => new ReadableStream<Uint8Array>({ start(c) { for (const s of frames) c.enqueue(enc.encode(s)); c.close(); } });
+  const mk = (headers: Record<string, string>) => ({
+    chatCompletionStream: async () => new Response(body([delta("ok"), "data: [DONE]\n\n"]), { headers: { "content-type": "text/event-stream", ...headers } }),
+  });
+  const withHeader = await streamChatText(mk({ "x-blockrun-cost-usd": "0.000000" }) as never, "m", [{ role: "user", content: "hi" }], {});
+  assert.equal(withHeader.settledUsd, 0, "an explicit zero is a settled zero");
+  const without = await streamChatText(mk({}) as never, "m", [{ role: "user", content: "hi" }], {});
+  assert.equal(without.settledUsd, null, "absent means unknown, not free");
+  const priced = await streamChatText(mk({ "x-blockrun-cost-usd": "0.003100" }) as never, "m", [{ role: "user", content: "hi" }], {});
+  assert.equal(priced.settledUsd, 0.0031);
+});
+
+// ── completeChat over the Solana client's stream(): where the payment is ──
+//
+// openPaidStream pays, records the settlement, and only then hands out frames.
+// A stall BEFORE the first frame cannot be placed by this module (the paid
+// request may still be in flight); it must NOT read as "accepted" — the
+// classifier treats a plain timeout as "unknown" and books the reserve. A
+// stall AFTER the first frame is post-acceptance.
+test("completeChat on a frame-streaming client: a first-frame stall is a timeout, a later stall is post-acceptance", async () => {
+  const { completeChat, AcceptedThenFailedError } = await import("../src/utils/chat-stream.js");
+  const never = () => new Promise<never>(() => undefined);
+  const beforeFirst = { getSpending: () => ({ totalUsd: 0 }), chatCompletion: async () => ({}), stream: async function* () { await never(); yield {}; } };
+  await assert.rejects(
+    completeChat(beforeFirst as never, "m", [{ role: "user", content: "hi" }], {}, { stream: true, idleTimeoutMs: 30 }),
+    (err: unknown) => err instanceof Error && !(err instanceof AcceptedThenFailedError) && /timeout/.test(err.message),
+  );
+  const afterFirst = { getSpending: () => ({ totalUsd: 0 }), chatCompletion: async () => ({}), stream: async function* () { yield { choices: [{ delta: { content: "a" } }] }; await never(); } };
+  await assert.rejects(
+    completeChat(afterFirst as never, "m", [{ role: "user", content: "hi" }], {}, { stream: true, idleTimeoutMs: 30 }),
+    (err: unknown) => err instanceof AcceptedThenFailedError && /stalled/.test(err.message),
+  );
+  // The SDK's own throw from the first next() (unpaid 4xx, refused payment,
+  // abort) passes through untouched.
+  const refused = { getSpending: () => ({ totalUsd: 0 }), chatCompletion: async () => ({}), stream: async function* () { throw Object.assign(new Error("API error: 400"), { name: "APIError", statusCode: 400 }); yield {}; } };
+  await assert.rejects(
+    completeChat(refused as never, "m", [{ role: "user", content: "hi" }], {}, { stream: true, idleTimeoutMs: 30 }),
+    (err: unknown) => (err as { name?: string }).name === "APIError" && !(err instanceof AcceptedThenFailedError),
+  );
+  // And the body the SDK builds carries stream:true with the caller's options.
+  let sent: Record<string, unknown> | undefined;
+  const ok = { getSpending: () => ({ totalUsd: 0 }), chatCompletion: async () => ({}), stream: async function* (_p: string, body: Record<string, unknown>) { sent = body; yield { model: "m", choices: [{ delta: { content: "done" }, finish_reason: "stop" }] }; } };
+  const out = await completeChat(ok as never, "m", [{ role: "user", content: "hi" }], { maxTokens: 77, temperature: 0.2, stop: ["x"] }, { stream: true });
+  assert.equal(out.text, "done");
+  assert.deepEqual(sent, { model: "m", messages: [{ role: "user", content: "hi" }], max_tokens: 77, stream: true, temperature: 0.2, stop: ["x"] });
+});
+
+// ── settlementOnThrow: the money verdict, rail by rail ──
+test("settlementOnThrow: the wallet rail reads the SDK's after-payment prefix and the status", async () => {
+  const { settlementOnThrow } = await import("../src/utils/chat-stream.js");
+  const api = (m: string, statusCode: number) => Object.assign(new Error(m), { name: "APIError", statusCode });
+  const w = (e: unknown) => settlementOnThrow(e, { rail: "wallet", estimateUsd: 0.01 });
+  assert.equal(w(api("API error: 400", 400)), "none");
+  assert.equal(w(api("API error: 503", 503)), "none", "an unpaid first response, whatever the status");
+  assert.equal(w(api("API error after payment: 400", 400)), "none", "the gateway's own refusal on the paid retry");
+  assert.equal(w(api("API error after payment: 429", 429)), "none");
+  assert.equal(w(api("API error after payment: 524", 524)), "unknown");
+  assert.equal(w(api("API error after payment: 502", 502)), "unknown");
+  assert.equal(w(api("API error after payment: 500", 500)), "unknown");
+  assert.equal(w(Object.assign(new Error("Payment was rejected. Check your wallet balance."), { name: "PaymentError" })), "none");
+  assert.equal(w(Object.assign(new Error("This operation was aborted"), { name: "AbortError" })), "unknown");
+  assert.equal(w(Object.assign(new TypeError("fetch failed"), { cause: { code: "ENOTFOUND" } })), "none", "never connected");
+  assert.equal(w(Object.assign(new TypeError("fetch failed"), { cause: { code: "ECONNRESET" } })), "unknown", "died in flight");
+  assert.equal(w(new Error("maxTokens must be an integer")), "none", "never left the process");
+  assert.equal(w(api("API error after payment: 524", 524)), "unknown");
+  assert.equal(settlementOnThrow(api("API error after payment: 524", 524), { rail: "wallet", estimateUsd: 0 }), "none", "a free model cannot have cost anything");
+});
+
+test("settlementOnThrow: the account rail bills nothing for a labelled refusal, and only an unanswered origin is ambiguous", async () => {
+  const { settlementOnThrow, AcceptedThenFailedError } = await import("../src/utils/chat-stream.js");
+  const api = (statusCode: number) => Object.assign(new Error(`BlockRun account API error: ${statusCode}.`), { name: "APIError", statusCode });
+  const a = (e: unknown) => settlementOnThrow(e, { rail: "account", estimateUsd: 0.01 });
+  for (const s of [400, 401, 402, 404, 413, 422, 429, 500, 503]) assert.equal(a(api(s)), "none", `status ${s}`);
+  for (const s of [408, 502, 504, 522, 524]) assert.equal(a(api(s)), "unknown", `status ${s}`);
+  assert.equal(a(Object.assign(new Error("This operation was aborted"), { name: "AbortError" })), "unknown");
+  assert.equal(a(new AcceptedThenFailedError("upstream error mid-stream: x")), "settled");
+});
+
+test("settlementOnThrow: the native path (payment inside fetch) judges the status alone", async () => {
+  const { settlementOnThrow } = await import("../src/utils/chat-stream.js");
+  const sdk = (status: number | undefined, message: string, cause?: Error) => Object.assign(new Error(message), { status, cause });
+  const n = (e: unknown) => settlementOnThrow(e, { rail: "wallet", estimateUsd: 0.01, transparentPayment: true });
+  assert.equal(n(sdk(400, "400 invalid_request_error")), "none");
+  assert.equal(n(sdk(429, "429 rate limited")), "none");
+  assert.equal(n(sdk(524, "524 status code (no body)")), "unknown");
+  assert.equal(n(sdk(500, "500 internal")), "unknown");
+  assert.equal(n(sdk(undefined, "Connection error.", new Error("Payment was rejected. Check your wallet balance."))), "none");
+  assert.equal(n(sdk(undefined, "Request timed out.")), "unknown");
+});
diff --git a/test/chat-wallet-after-payment.test.ts b/test/chat-wallet-after-payment.test.ts
new file mode 100644
index 0000000..279805e
--- /dev/null
+++ b/test/chat-wallet-after-payment.test.ts
@@ -0,0 +1,356 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// The wallet rails, for the failure the getSpending() delta cannot see.
+//
+// withSettledCost books a settled-then-failed call from the SDK's own spend
+// counter, which the SDK increments only AFTER the paid retry came back OK:
+// LLMClient.chatCompletionStream throws `API error after payment: <status>`
+// BEFORE `sessionTotalUsd += costUsd`, and SolanaLLMClient.handlePaymentAndRetry
+// runs assertPaid() before recordSettlement() — and fetchWithTimeout aborts the
+// paid retry with no counter movement at all (60s on Solana, the default chain).
+// So a 524 from the edge or a client-side abort on a slow generation arrived
+// with a signed payment already sent, the delta read 0, nothing was booked, the
+// text said "temporary API issue — try again", and the routing loop signed a
+// SECOND payment for the next model under the same reservation (audit round 3,
+// C19). The gateway settles those after the client has given up.
+//
+// This process cannot know whether such a payment settled. What it can do is
+// refuse to pay again, book the reserve as a precaution, and say so. That is
+// what these pin — on Solana (the default) and on Base alike — together with
+// the shapes that are NOT payments: an unpaid first-response 4xx, and a 4xx
+// after payment, which the gateway answers before settlement starts.
+//
+// Also pinned here, because they come off the same stream: the id the gateway
+// says answered (D55) and a reply cut at max_tokens (D57).
+import { test, mock } from "node:test";
+import assert from "node:assert/strict";
+import type { BudgetState } from "../src/types.js";
+
+type Fail = false | "unpaid-400" | "after-payment-524" | "after-payment-400" | "abort" | "midstream";
+type Attempt = { settleUsd: number; fail: Fail; served?: string; finish?: string; text?: string };
+let script: Map<string, Attempt>;
+let attempts: string[];
+let chain: "base" | "solana" = "solana";
+const enc = new TextEncoder();
+
+function apiError(message: string, statusCode: number): Error {
+  return Object.assign(new Error(message), { name: "APIError", statusCode });
+}
+function abortError(): Error {
+  return Object.assign(new Error("This operation was aborted"), { name: "AbortError" });
+}
+
+// What the paid retry does, before any body: the money moves (or not) HERE.
+function paidRetry(model: string, total: { usd: number }): { a: Attempt; frames: unknown[] } {
+  attempts.push(model);
+  const a = script.get(model) ?? { settleUsd: 0, fail: false };
+  if (a.fail === "unpaid-400") throw apiError("API error: 400", 400);
+  if (a.fail === "after-payment-400") throw apiError("API error after payment: 400", 400);
+  if (a.fail === "after-payment-524") throw apiError("API error after payment: 524", 524);
+  if (a.fail === "abort") throw abortError();
+  // A 200: the SDK counts the settlement before the body is read.
+  total.usd += a.settleUsd;
+  const served = a.served ?? model;
+  const frames: unknown[] = a.fail === "midstream"
+    ? [{ model: served, choices: [{ delta: { content: "partial " } }] }, { error: { message: "upstream exploded" } }]
+    : [
+        { model: served, choices: [{ delta: { content: a.text ?? `reply from ${model}` }, finish_reason: null }] },
+        { model: served, choices: [{ delta: {}, finish_reason: a.finish ?? "stop" }] },
+        { model: served, choices: [], usage: { prompt_tokens: 10, completion_tokens: 5 } },
+      ];
+  return { a, frames };
+}
+
+// SolanaLLMClient: no chatCompletionStream; `stream()` yields decoded frames
+// and records the settlement before the first one.
+function makeSolanaFake() {
+  const total = { usd: 0 };
+  return {
+    getSpending: () => ({ totalUsd: total.usd }),
+    chatCompletion: async (model: string) => {
+      const { frames } = paidRetry(model, total);
+      const text = frames.map((f) => (f as { choices?: Array<{ delta?: { content?: string } }> }).choices?.[0]?.delta?.content ?? "").join("");
+      return { model, choices: [{ message: { content: text }, finish_reason: "stop" }] };
+    },
+    stream: async function* (_path: string, body: Record<string, unknown>) {
+      const { frames } = paidRetry(String(body.model), total);
+      for (const f of frames) yield f;
+    },
+  };
+}
+
+// LLMClient on Base: chatCompletionStream returns the paid Response.
+function makeBaseFake() {
+  const total = { usd: 0 };
+  return {
+    getSpending: () => ({ totalUsd: total.usd }),
+    chatCompletion: async (model: string) => {
+      const { a } = paidRetry(model, total);
+      return { model: a.served ?? model, choices: [{ message: { content: a.text ?? `reply from ${model}` }, finish_reason: a.finish ?? "stop" }] };
+    },
+    chatCompletionStream: async (model: string) => {
+      const { frames } = paidRetry(model, total);
+      const lines = frames.map((f) => `data: ${JSON.stringify(f)}\n\n`).concat("data: [DONE]\n\n");
+      return new Response(
+        new ReadableStream<Uint8Array>({ start(c) { for (const l of lines) c.enqueue(enc.encode(l)); c.close(); } }),
+        { status: 200, headers: { "content-type": "text/event-stream" } },
+      );
+    },
+  };
+}
+
+mock.module("../src/utils/wallet.js", {
+  namedExports: {
+    getApiBase: () => "https://blockrun.ai/api",
+    resolveGatewayUrl: (u: string) => u,
+    getChain: () => chain,
+    buildClient: () => (chain === "solana" ? makeSolanaFake() : makeBaseFake()),
+    buildClientWithTimeout: () => (chain === "solana" ? makeSolanaFake() : makeBaseFake()),
+    getOrCreateWalletKey: () => "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d",
+    getWalletInfo: async () => ({ address: "0xTEST" }),
+    getAnthropicClient: () => { throw new Error("native AnthropicClient was built"); },
+    // The real one: a Solana wallet gets the refusal text, Base gets null.
+    baseOnlyMessage: (capability: string) => (chain === "solana"
+      ? `${capability} currently supports Base-chain payment only — your active chain is Solana. Switch with: blockrun_wallet action:"chain" chain:"base"`
+      : null),
+  },
+});
+
+const { registerChatTool, estimateChatCost } = await import("../src/tools/chat.js");
+
+type Result = { content: Array<{ type: string; text: string }>; structuredContent?: Record<string, unknown>; isError?: boolean };
+function makeHarness() {
+  const budget: BudgetState = { spent: 0, calls: 0, limit: 100, agents: new Map() };
+  let handler: (args: Record<string, unknown>) => Promise<Result>;
+  const server = {
+    registerTool: (_n: string, _c: unknown, h: typeof handler) => { handler = h; },
+  } as unknown as Parameters<typeof registerChatTool>[0];
+  registerChatTool(server, budget);
+  return { budget, call: (args: Record<string, unknown>) => handler!(args) };
+}
+const near = (a: number, b: number) => Math.abs(a - b) < 1e-9;
+
+for (const c of ["solana", "base"] as const) {
+  test(`${c}: a 524 after payment with no counter movement is booked as a precaution and ends the loop`, async () => {
+    chain = c;
+    script = new Map([
+      ["deepseek/deepseek-v4-pro", { settleUsd: 0, fail: "after-payment-524" }],
+      ["qwen/qwen3.7-flash", { settleUsd: 0.0031, fail: false }],
+    ]);
+    attempts = [];
+    const { budget, call } = makeHarness();
+
+    const res = await call({ message: "hi", mode: "cheap", max_tokens: 1024, temperature: 1 });
+
+    assert.equal(res.isError, true);
+    assert.deepEqual(attempts, ["deepseek/deepseek-v4-pro"], "a payment that may have settled must not be followed by a second signed payment");
+    const reserve = estimateChatCost(1024, "cheap", undefined, undefined, 2);
+    assert.ok(near(budget.spent, reserve), `the reserve (${reserve}) is booked as the precaution; got ${budget.spent}`);
+    assert.match(res.content[0].text, /may have settled|cannot tell whether/i, res.content[0].text);
+    assert.match(res.content[0].text, /second charge/i, res.content[0].text);
+    assert.doesNotMatch(res.content[0].text, /needs funding/, res.content[0].text);
+  });
+
+  test(`${c}: an abort on a paid explicit model books the reserve and says the payment may have settled`, async () => {
+    chain = c;
+    script = new Map([["openai/gpt-5.6-terra", { settleUsd: 0, fail: "abort" }]]);
+    attempts = [];
+    const { budget, call } = makeHarness();
+
+    const res = await call({ message: "hi", model: "openai/gpt-5.6-terra", max_tokens: 1024, temperature: 1 });
+
+    assert.equal(res.isError, true);
+    const reserve = estimateChatCost(1024, undefined, "openai/gpt-5.6-terra", undefined, 2);
+    assert.ok(near(budget.spent, reserve), `booked ${budget.spent}, reserve ${reserve}`);
+    assert.match(res.content[0].text, /may have settled|cannot tell whether/i, res.content[0].text);
+    assert.doesNotMatch(res.content[0].text, /charge stands/, "no charge is certain here");
+  });
+
+  test(`${c}: an unpaid first-response 400 books nothing and the loop falls through`, async () => {
+    chain = c;
+    script = new Map([
+      ["deepseek/deepseek-v4-pro", { settleUsd: 0, fail: "unpaid-400" }],
+      ["qwen/qwen3.7-flash", { settleUsd: 0.0031, fail: false }],
+    ]);
+    attempts = [];
+    const { budget, call } = makeHarness();
+
+    const res = await call({ message: "hi", mode: "cheap", max_tokens: 1024, temperature: 1 });
+
+    assert.equal(res.isError, undefined, res.content[0].text);
+    assert.deepEqual(attempts, ["deepseek/deepseek-v4-pro", "qwen/qwen3.7-flash"]);
+    assert.ok(near(budget.spent, 0.0031), `only the second model settled; booked ${budget.spent}`);
+  });
+
+  test(`${c}: a 4xx AFTER payment is refused before settlement — nothing booked, loop continues`, async () => {
+    // The gateway answers a 4xx on the paid retry from its own handler, before
+    // streamAIProvider has returned a stream handle — "settlement has not
+    // started" in its own words — so this is not money.
+    chain = c;
+    script = new Map([
+      ["deepseek/deepseek-v4-pro", { settleUsd: 0, fail: "after-payment-400" }],
+      ["qwen/qwen3.7-flash", { settleUsd: 0.0031, fail: false }],
+    ]);
+    attempts = [];
+    const { budget, call } = makeHarness();
+
+    const res = await call({ message: "hi", mode: "cheap", max_tokens: 1024, temperature: 1 });
+
+    assert.equal(res.isError, undefined, res.content[0].text);
+    assert.deepEqual(attempts, ["deepseek/deepseek-v4-pro", "qwen/qwen3.7-flash"]);
+    assert.ok(near(budget.spent, 0.0031), `booked ${budget.spent}`);
+  });
+
+  test(`${c}: a free model that aborts is never "may have settled" — the free tier walks on`, async () => {
+    chain = c;
+    const free = ["nvidia/gpt-oss-20b", "cohere/north-mini-code", "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning"];
+    script = new Map([[free[0], { settleUsd: 0, fail: "abort" }], [free[1], { settleUsd: 0, fail: "after-payment-524" }]]);
+    attempts = [];
+    const { budget, call } = makeHarness();
+
+    const res = await call({ message: "hi", mode: "free", max_tokens: 1024, temperature: 1 });
+
+    assert.equal(res.isError, undefined, res.content[0].text);
+    assert.ok(attempts.length >= 3, `expected the loop to reach a third free model, got ${attempts.join(", ")}`);
+    assert.equal(budget.spent, 0);
+  });
+
+  test(`${c}: a stream that settled and then died books the counter's delta and keeps the partial text`, async () => {
+    chain = c;
+    script = new Map([["openai/gpt-5.6-terra", { settleUsd: 0.0412, fail: "midstream" }]]);
+    attempts = [];
+    const { budget, call } = makeHarness();
+
+    const res = await call({ message: "hi", model: "openai/gpt-5.6-terra", max_tokens: 1024, temperature: 1 });
+
+    assert.equal(res.isError, true);
+    assert.ok(near(budget.spent, 0.0412), `booked ${budget.spent}`);
+    assert.match(res.content[0].text, /charge stands \(\$0\.041200\)/, res.content[0].text);
+    assert.match(res.content[0].text, /partial /, "the paid partial text must be surfaced");
+    assert.equal(res.structuredContent?.partial_response, "partial ");
+  });
+
+  test(`${c}: a paid call that streams to completion books the settled delta once and reports what served`, async () => {
+    chain = c;
+    script = new Map([["openai/gpt-5.6-terra", { settleUsd: 0.0217, fail: false, served: "openai/gpt-5.6-terra", text: "done" }]]);
+    attempts = [];
+    const { budget, call } = makeHarness();
+
+    const res = await call({ message: "hi", model: "openai/gpt-5.6-terra", max_tokens: 1024, temperature: 1 });
+
+    assert.equal(res.isError, undefined, res.content[0].text);
+    assert.deepEqual(attempts, ["openai/gpt-5.6-terra"]);
+    assert.ok(near(budget.spent, 0.0217), `booked ${budget.spent}`);
+    assert.equal(budget.calls, 1);
+    assert.match(res.content[0].text, /done/);
+    assert.equal(res.structuredContent?.served_model, "openai/gpt-5.6-terra");
+    assert.equal(res.structuredContent?.finish_reason, "stop");
+  });
+}
+
+test("D55: an aliased id is reported under the id that actually answered", async () => {
+  chain = "solana";
+  script = new Map([["moonshot/kimi-k2.6", { settleUsd: 0.0105, fail: false, served: "moonshot/kimi-k3", text: "kimi here" }]]);
+  attempts = [];
+  const { call } = makeHarness();
+
+  const res = await call({ message: "hi", model: "moonshot/kimi-k2.6", max_tokens: 1024, temperature: 1 });
+
+  assert.equal(res.isError, undefined, res.content[0].text);
+  assert.equal(res.structuredContent?.served_model, "moonshot/kimi-k3");
+  assert.equal(res.structuredContent?.model_used, "moonshot/kimi-k2.6", "what was asked for stays visible too");
+  assert.match(res.content[0].text, /served by moonshot\/kimi-k3/i, res.content[0].text);
+});
+
+test("D55: the routing loop's header names the served model when it differs", async () => {
+  chain = "base";
+  const free0 = "nvidia/gpt-oss-20b";
+  script = new Map([[free0, { settleUsd: 0, fail: false, served: "nvidia/nemotron-3-super-120b", text: "free reply" }]]);
+  attempts = [];
+  const { call } = makeHarness();
+
+  const res = await call({ message: "hi", mode: "free", max_tokens: 1024, temperature: 1 });
+
+  assert.equal(res.isError, undefined, res.content[0].text);
+  assert.equal(res.structuredContent?.served_model, "nvidia/nemotron-3-super-120b");
+  assert.match(res.content[0].text, /nemotron-3-super-120b/, res.content[0].text);
+});
+
+test("D57: a reply cut at max_tokens is flagged, on the explicit and the routed path", async () => {
+  chain = "base";
+  script = new Map([
+    ["openai/gpt-5.6-terra", { settleUsd: 0.01, fail: false, finish: "length", text: '{"partial": tru' }],
+    ["deepseek/deepseek-v4-pro", { settleUsd: 0.01, fail: false, finish: "length", text: "cut off mid" }],
+  ]);
+  attempts = [];
+  const { call } = makeHarness();
+
+  const explicit = await call({ message: "hi", model: "openai/gpt-5.6-terra", max_tokens: 200, temperature: 1 });
+  assert.equal(explicit.isError, undefined, explicit.content[0].text);
+  assert.match(explicit.content[0].text, /TRUNCATED OUTPUT/, explicit.content[0].text);
+  assert.match(explicit.content[0].text, /max_tokens=200/, explicit.content[0].text);
+  assert.equal(explicit.structuredContent?.truncated_output, true);
+  assert.equal(explicit.structuredContent?.finish_reason, "length");
+
+  const routed = await call({ message: "hi", mode: "cheap", max_tokens: 200, temperature: 1 });
+  assert.equal(routed.isError, undefined, routed.content[0].text);
+  assert.match(routed.content[0].text, /TRUNCATED OUTPUT/, routed.content[0].text);
+  assert.equal(routed.structuredContent?.truncated_output, true);
+});
+
+test("a complete reply carries no truncation note", async () => {
+  chain = "base";
+  script = new Map([["openai/gpt-5.6-terra", { settleUsd: 0.01, fail: false, finish: "stop", text: "whole" }]]);
+  attempts = [];
+  const { call } = makeHarness();
+  const res = await call({ message: "hi", model: "openai/gpt-5.6-terra", max_tokens: 200, temperature: 1 });
+  assert.doesNotMatch(res.content[0].text, /TRUNCATED/, res.content[0].text);
+  assert.equal(res.structuredContent?.truncated_output, undefined);
+});
+
+// ── D5: explicit claude-* on Solana ──
+//
+// sol.blockrun.ai serves anthropic/claude-* on /v1/chat/completions ($0 probe
+// 2026-09-13: 402 "Claude Sonnet 5 API call" / "Claude Opus 5 API call"), and
+// mode:"powerful" already sent those ids there. Only the native /v1/messages
+// client is EVM-only, and only `thinking` needs it.
+test("D5: on Solana an explicit claude-* id without thinking runs on the compat path, paid on Solana", async () => {
+  chain = "solana";
+  script = new Map([["anthropic/claude-sonnet-5", { settleUsd: 0.0103, fail: false, text: "sonnet on sol" }]]);
+  attempts = [];
+  const { budget, call } = makeHarness();
+
+  const res = await call({ message: "hi", model: "anthropic/claude-sonnet-5", max_tokens: 1024, temperature: 1 });
+
+  assert.equal(res.isError, undefined, res.content[0].text);
+  assert.deepEqual(attempts, ["anthropic/claude-sonnet-5"], "the SolanaLLMClient must carry the call");
+  assert.ok(near(budget.spent, 0.0103), `booked the Solana settlement; got ${budget.spent}`);
+  assert.match(res.content[0].text, /sonnet on sol/);
+});
+
+test("D5: on Solana, claude-* WITH thinking is still refused before anything is sent — thinking needs the native path", async () => {
+  chain = "solana";
+  script = new Map();
+  attempts = [];
+  const { budget, call } = makeHarness();
+
+  const res = await call({ message: "hi", model: "anthropic/claude-opus-5", max_tokens: 1024, temperature: 1, thinking: { type: "enabled", budget_tokens: 2048 } });
+
+  assert.equal(res.isError, true);
+  assert.match(res.content[0].text, /Base-chain payment only/, res.content[0].text);
+  assert.match(res.content[0].text, /thinking/, "the refusal names what needs Base");
+  assert.deepEqual(attempts, [], "nothing may be sent, let alone paid");
+  assert.equal(budget.spent, 0);
+});
+
+test("D5: on Base an explicit claude-* id still takes the native /v1/messages path", async () => {
+  chain = "base";
+  script = new Map();
+  attempts = [];
+  const { call } = makeHarness();
+
+  // The mock's AnthropicClient factory throws — proof the native branch was
+  // taken and the compat client was never asked.
+  await assert.rejects(call({ message: "hi", model: "anthropic/claude-sonnet-5", max_tokens: 1024, temperature: 1 }), /native AnthropicClient was built/);
+  assert.deepEqual(attempts, []);
+});
diff --git a/test/chat.test.ts b/test/chat.test.ts
index 9ce44b1..c51e8c3 100644
--- a/test/chat.test.ts
+++ b/test/chat.test.ts
@@ -112,9 +112,23 @@ function fakeNative() {
   };
 }
 
+// The native path STREAMS (see streamNativeMessage): the fake is the SDK's
+// MessageStream surface, capturing the params it was built with.
+function fakeStreamingClient(onParams: (p: any) => void) {
+  return {
+    messages: {
+      stream: (p: any) => {
+        onParams(p);
+        const self = { on: () => self, off: () => self, abort: () => undefined, response: null, finalMessage: async () => fakeNative() };
+        return self;
+      },
+    },
+  };
+}
+
 test("handleAnthropicNative folds json_object into the system prompt", async () => {
   let captured: any;
-  const client = { messages: { create: async (p: any) => { captured = p; return fakeNative(); } } };
+  const client = fakeStreamingClient((p) => { captured = p; });
   await handleAnthropicNative({
     client: client as any,
     model: "anthropic/claude-haiku-4.5",
@@ -128,7 +142,7 @@ test("handleAnthropicNative folds json_object into the system prompt", async ()
 
 test("handleAnthropicNative sends a data:image/jpg URI as a base64 image source", async () => {
   let captured: any;
-  const client = { messages: { create: async (p: any) => { captured = p; return fakeNative(); } } };
+  const client = fakeStreamingClient((p) => { captured = p; });
   await handleAnthropicNative({
     client: client as any,
     model: "anthropic/claude-haiku-4.5",
@@ -146,7 +160,7 @@ test("handleAnthropicNative sends a data:image/jpg URI as a base64 image source"
 
 test("handleAnthropicNative adds no JSON instruction for plain text", async () => {
   let captured: any;
-  const client = { messages: { create: async (p: any) => { captured = p; return fakeNative(); } } };
+  const client = fakeStreamingClient((p) => { captured = p; });
   await handleAnthropicNative({
     client: client as any,
     model: "anthropic/claude-haiku-4.5",
@@ -455,3 +469,31 @@ test("claude-sonnet-5 books at the gateway's $2/$10, not the old $3/$15", () =>
   // The old row booked $0.146827 for the same call.
   assert.ok(anthropicCallCost("claude-sonnet-5", 100_000, 1024)! < 0.146827 * 0.7);
 });
+
+// ── free[] must route ids that answer for THEMSELVES on both chains ──
+//
+// $0 POST probes with a realistic ~3,000-character prompt, both gateways,
+// 2026-09-13 (no payment header; free models answer 200). Six of the eleven
+// routed ids answered as ANOTHER model on both chains — gpt-oss-120b (free[0]
+// since July, "the gateway's own free fallback") as nemotron-3-nano-omni on
+// Base and nemotron-3.5-lightning on Solana; nemotron-3-ultra-550b, step-3.7-
+// flash, mistral-nemotron and both nemotron-nano-* as nemotron-3-super-120b /
+// nano-omni — so a saturated backend was retried under five names inside the
+// 150s deadline, and the loop reported "did not answer" having tried ONE
+// model. The alias TARGET moves between probes (the gateway serves whatever
+// has capacity), which is exactly why the tier keys on ids that echo their
+// own name: those are distinct backends. The pruned ids stay in
+// FREE_CHAT_MODELS so an explicit call still reserves $0 (D56).
+test("free[] is the self-serving, both-chain set from the 2026-09-13 probe, fastest first", () => {
+  assert.deepEqual([...MODEL_TIERS.free], [
+    "nvidia/gpt-oss-20b",                              // itself, 0.7s sol / 1.7s base
+    "cohere/north-mini-code",                          // itself, 1.0s / 3.0s
+    "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning",   // itself (…-nim on sol), 2.3s / 3.6s
+    "poolside/laguna-xs-2.1",                          // itself on sol 0.7s; 429 capacity on base that day
+    "nvidia/llama-3.2-11b-vision",                     // itself on sol 9.8s; no answer in 90s on base — last
+  ]);
+  for (const aliased of ["nvidia/gpt-oss-120b", "nvidia/nemotron-3-ultra-550b", "nvidia/step-3.7-flash", "nvidia/mistral-nemotron", "nvidia/nemotron-nano-12b-v2-vl", "nvidia/nemotron-nano-9b-v2"]) {
+    assert.ok(FREE_CHAT_MODELS.has(aliased), `${aliased} is still $0 — an explicit call must reserve nothing`);
+    assert.ok(!(MODEL_TIERS.free as readonly string[]).includes(aliased), `${aliased} answers as another model on both chains — not a fallback rung`);
+  }
+});
diff --git a/test/defi-replay-hedge.test.ts b/test/defi-replay-hedge.test.ts
new file mode 100644
index 0000000..5b90e9c
--- /dev/null
+++ b/test/defi-replay-hedge.test.ts
@@ -0,0 +1,133 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// The same Base-rail ambiguity exa-replay-hedge.test.ts pins, on the other
+// route that has it. The gateway's defillama/[...path] route, like exa's,
+// answers an upstream 5xx with 502 "Payment was NOT charged" WITHOUT releasing
+// the payment nonce; @blockrun/llm's handlePaymentAndRetryRaw sleeps 1s and
+// re-sends the SAME PAYMENT-SIGNATURE, rejectReplay answers 402
+// {code: PAYMENT_REPLAY}, and the SDK collapses every post-payment 402 into
+// PaymentError("Payment was rejected. Check your wallet balance."), body
+// discarded. formatError then sees "balance" and prescribes funding to a
+// wallet that was never the problem.
+//
+// exa.ts got the hedge in round 3; defi.ts did not (E-residual). The wording
+// is now one helper in utils/errors.ts so the two cannot drift.
+import { test, mock, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import type { BudgetState } from "../src/types.js";
+
+let apiKeyMode = false;
+let chain: "base" | "solana" = "base";
+let walletThrows: Error | null = null;
+let getCalls: string[] = [];
+const stubClient = {
+  getWithPaymentRaw: async (endpoint: string) => {
+    getCalls.push(endpoint);
+    if (walletThrows) throw walletThrows;
+    return { protocols: [] };
+  },
+  requestWithPaymentRaw: async () => { throw new Error("defi never POSTs"); },
+};
+mock.module("../src/utils/wallet.js", {
+  namedExports: {
+    getApiBase: () => "https://blockrun.ai/api",
+    resolveGatewayUrl: (u: string) => u,
+    getChain: () => chain,
+    getClient: () => stubClient,
+    buildClient: () => stubClient,
+    buildClientWithTimeout: () => stubClient,
+    // defi is Base-only on the wallet rails; the real helper returns null on
+    // Base and on the account rail. The Solana case here is the hedge's own
+    // rail check, reached by pretending the chain gate passed.
+    baseOnlyMessage: () => null,
+    getOrCreateWalletKey: () => { throw new Error("defi tests must not touch a wallet key"); },
+    getWalletInfo: async () => ({ address: "0xTEST" }),
+  },
+});
+mock.module("../src/utils/auth.js", {
+  namedExports: {
+    isApiKeyMode: () => apiKeyMode,
+    getApiKey: () => (apiKeyMode ? "brk_test_key" : undefined),
+    apiAuthHeaders: () => ({ Authorization: "Bearer brk_test_key" }),
+    getApiKeyBase: () => "https://api.blockrun.ai",
+    PORTAL_CREDITS_URL: "https://user.blockrun.ai/dashboard/credits",
+  },
+});
+let accountThrows: Error | null = null;
+mock.module("../src/utils/http.js", {
+  namedExports: {
+    fetchWithTimeout: async () => {
+      if (accountThrows) throw accountThrows;
+      return new Response(JSON.stringify({ protocols: [] }), { status: 200, headers: { "content-type": "application/json", "x-blockrun-cost-usd": "0.005" } });
+    },
+    isTimeoutError: () => false,
+  },
+});
+
+const { registerDefiTool } = await import("../src/tools/defi.js");
+
+// The SDK's exact text — the only signal the tool gets.
+const SDK_REJECTED = "Payment was rejected. Check your wallet balance.";
+
+type Handler = (args: Record<string, unknown>) => Promise<{ content: Array<{ type: string; text?: string }>; isError?: boolean }>;
+function harness() {
+  let handler: Handler | undefined;
+  const server = {
+    registerTool: (_n: string, _c: unknown, h: Handler) => { handler = h; },
+    server: { getClientCapabilities: () => ({}) },
+  };
+  const budget: BudgetState = { limit: null, spent: 0, calls: 0, agents: new Map() };
+  registerDefiTool(server as never, budget);
+  assert.ok(handler, "blockrun_defi did not register a handler");
+  return { call: (args: Record<string, unknown>) => handler!(args), budget };
+}
+const text = (res: { content: Array<{ text?: string }> }) => res.content.map((p) => p.text ?? "").join("\n");
+
+beforeEach(() => { apiKeyMode = false; chain = "base"; walletThrows = null; accountThrows = null; getCalls = []; });
+
+test("Base rail: the SDK's post-payment rejection is hedged — it may be a replay after a DefiLlama 5xx, not an empty wallet", async () => {
+  walletThrows = new Error(SDK_REJECTED);
+  const { call, budget } = harness();
+  const res = await call({ path: "protocols" });
+  const out = text(res);
+  assert.equal(res.isError, true);
+  assert.deepEqual(getCalls, ["/v1/defillama/protocols"]);
+  assert.match(out, /Payment was rejected/, "the SDK's own words stay — it MAY be a real rejection");
+  assert.match(out, /DefiLlama/, out);
+  assert.match(out, /nothing was settled/, out);
+  assert.match(out, /retry the call once/, out);
+  // Points at a wallet action that exists (blockrun_wallet has no "balance").
+  assert.match(out, /blockrun_wallet action:"status"/, out);
+  assert.equal(budget.spent, 0, "a rejected call books nothing");
+});
+
+test("Solana rail: no hedge — the Solana client does not retry a 502 with a burned nonce", async () => {
+  chain = "solana";
+  walletThrows = new Error(SDK_REJECTED);
+  const { call } = harness();
+  const res = await call({ path: "protocols" });
+  const out = text(res);
+  assert.equal(res.isError, true);
+  assert.match(out, /Payment was rejected/);
+  assert.doesNotMatch(out, /replay|re-sent|resent|DefiLlama itself failed/i, out);
+});
+
+test("account rail: no hedge — there is no nonce to replay", async () => {
+  apiKeyMode = true;
+  accountThrows = new Error(SDK_REJECTED);
+  const { call } = harness();
+  const res = await call({ path: "protocols" });
+  const out = text(res);
+  assert.equal(res.isError, true);
+  assert.equal(getCalls.length, 0, "the account rail never touches the SDK client");
+  assert.doesNotMatch(out, /replay|re-sent|resent|DefiLlama itself failed/i, out);
+});
+
+test("Base rail: any other error is untouched by the hedge", async () => {
+  for (const msg of ["API error after payment: 502", "API error: 402 Payment Required", `${SDK_REJECTED} (extra)`]) {
+    walletThrows = new Error(msg);
+    const { call } = harness();
+    const res = await call({ path: "protocols" });
+    assert.doesNotMatch(text(res), /replay|re-sent|resent|DefiLlama itself failed/i, msg);
+  }
+});
diff --git a/test/delegate-ledger.test.ts b/test/delegate-ledger.test.ts
new file mode 100644
index 0000000..e8b747b
--- /dev/null
+++ b/test/delegate-ledger.test.ts
@@ -0,0 +1,224 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// A per-agent cap the agent can refill is not a cap.
+//
+// `delegate` wrote `spent: 0` unconditionally, so an agent that had exhausted
+// its allocation could call blockrun_wallet action:"delegate" with its own
+// agent_id and start again — and delegate is a tool the MODEL can call. The
+// global BLOCKRUN_BUDGET_LIMIT was never bypassable this way (checkBudget
+// tests it separately), so the damage was bounded: the sub-cap simply meant
+// nothing once the agent noticed. A limit is the operator's to raise or lower;
+// spend already happened and is not theirs to erase.
+import { test, mock } from "node:test";
+import assert from "node:assert/strict";
+import type { BudgetState } from "../src/types.js";
+
+mock.module("../src/utils/onramp.js", {
+  namedExports: { launchTopUp: async () => ({ opened: false, url: "", note: "" }) },
+});
+mock.module("../src/utils/wallet.js", {
+  namedExports: {
+    getApiBase: () => "https://blockrun.ai/api",
+    resolveGatewayUrl: (u: string) => u,
+    getWalletInfo: async () => ({ address: "0xTESTADDRESS" }),
+    getChain: () => "base",
+    getUsdcBalance: async () => 0,
+    setChain: () => {},
+    ensureBothWallets: async () => ({ base: { address: "0xTESTADDRESS" }, solana: { address: "SOL" } }),
+    getChainBalance: async () => 0,
+  },
+});
+const { registerWalletTool } = await import("../src/tools/wallet.js");
+const { reserveBudget, recordActualSpend } = await import("../src/utils/budget.js");
+
+function makeHarness(limit: number | null = null) {
+  let handler: ((a: Record<string, unknown>) => Promise<any>) | undefined;
+  const server = { registerTool: (_n: string, _c: unknown, h: any) => { handler = h; } } as any;
+  const budget: BudgetState = { limit, spent: 0, calls: 0, agents: new Map() };
+  registerWalletTool(server, budget);
+  return { call: (a: Record<string, unknown>) => handler!(a), budget };
+}
+
+test("re-delegating the same agent_id carries the spend, it does not refill the cap", async () => {
+  const { call, budget } = makeHarness();
+  await call({ action: "delegate", agent_id: "worker-1", agent_limit: 1 });
+
+  // Spend it out through the real ledger, the way a paid tool does.
+  const gate = reserveBudget(budget, "worker-1", 0.9);
+  assert.equal(gate.allowed, true);
+  gate.release();
+  budget.agents.get("worker-1")!.spent = 0.9;
+
+  const blocked = reserveBudget(budget, "worker-1", 0.5);
+  assert.equal(blocked.allowed, false, "0.9 of a 1.0 cap leaves no room for 0.5");
+
+  // The refill attempt.
+  const res = await call({ action: "delegate", agent_id: "worker-1", agent_limit: 1 });
+  assert.equal(budget.agents.get("worker-1")!.spent, 0.9, "spend must survive a re-delegation");
+  assert.equal(res.structuredContent.spent, 0.9);
+  assert.equal(res.structuredContent.remaining, 0.1);
+  assert.match(res.content[0].text, /Carried over/);
+  assert.match(res.content[0].text, /\$0\.1000 remains/);
+
+  const stillBlocked = reserveBudget(budget, "worker-1", 0.5);
+  assert.equal(stillBlocked.allowed, false, "the cap must still bite after re-delegation");
+});
+
+test("raising the limit gives an exhausted agent room again — that is the operator's call", async () => {
+  const { call, budget } = makeHarness();
+  await call({ action: "delegate", agent_id: "worker-2", agent_limit: 1 });
+  budget.agents.get("worker-2")!.spent = 1;
+
+  const res = await call({ action: "delegate", agent_id: "worker-2", agent_limit: 5 });
+  assert.equal(budget.agents.get("worker-2")!.spent, 1, "still one dollar spent");
+  assert.equal(res.structuredContent.remaining, 4);
+  assert.doesNotMatch(res.content[0].text, /already at its cap/);
+  assert.equal(reserveBudget(budget, "worker-2", 3).allowed, true);
+});
+
+test("a first delegation reports no carry-over, and revoke removes the allocation", async () => {
+  const { call, budget } = makeHarness();
+  const first = await call({ action: "delegate", agent_id: "fresh", agent_limit: 2 });
+  assert.equal(first.structuredContent.spent, 0);
+  assert.doesNotMatch(first.content[0].text, /Carried over/);
+
+  const res = await call({ action: "revoke", agent_id: "fresh" });
+  assert.equal(budget.agents.has("fresh"), false, "revoke removes the allocation outright");
+  assert.equal(res.structuredContent.revoked, true);
+  assert.equal(reserveBudget(budget, "fresh", 100).allowed, true, "a revoked id has no per-agent cap — it is tracked globally only");
+});
+
+test("revoke + delegate is not a refill: the spend follows the agent_id back", async () => {
+  // The 0.50.0 fix carried `spent` across a re-delegation, but `revoke` deleted
+  // the entry and the next `delegate` started at zero — two calls instead of
+  // one, both of them the model's to make. The changelog said the cap could
+  // not refill itself; it could.
+  const { call, budget } = makeHarness();
+  await call({ action: "delegate", agent_id: "fresh", agent_limit: 2 });
+  budget.agents.get("fresh")!.spent = 2;
+  budget.agents.get("fresh")!.calls = 7;
+  await call({ action: "revoke", agent_id: "fresh" });
+
+  const again = await call({ action: "delegate", agent_id: "fresh", agent_limit: 2 });
+  assert.equal(again.structuredContent.spent, 2, "spend already happened; revoke does not erase it");
+  assert.equal(again.structuredContent.calls, 7);
+  assert.equal(again.structuredContent.remaining, 0);
+  assert.match(again.content[0].text, /Carried over/);
+  assert.match(again.content[0].text, /already at its cap/);
+  assert.equal(reserveBudget(budget, "fresh", 0.01).allowed, false, "still exhausted after the revoke/delegate dance");
+
+  // Raising the limit is the operator's call and still works.
+  const raised = await call({ action: "delegate", agent_id: "fresh", agent_limit: 3 });
+  assert.equal(raised.structuredContent.remaining, 1);
+  assert.equal(reserveBudget(budget, "fresh", 0.5).allowed, true);
+});
+
+test("a reservation taken BEFORE a re-delegation is released against the entry that is live AFTER it", async () => {
+  // Regression of 7f8d8f1: carrying `spent` into a brand-new object meant the
+  // reservation closure (which holds the OLD object) released the estimate
+  // from an orphan, so the live entry kept reservation + actual and the agent
+  // was over-counted for the rest of the process.
+  const { call, budget } = makeHarness();
+  await call({ action: "delegate", agent_id: "worker-1", agent_limit: 2 });
+
+  const gate = reserveBudget(budget, "worker-1", 1);
+  assert.equal(gate.allowed, true);
+  assert.equal(budget.agents.get("worker-1")!.spent, 1, "the estimate is held while the call is in flight");
+
+  // The operator raises the cap two minutes into the render.
+  const res = await call({ action: "delegate", agent_id: "worker-1", agent_limit: 3 });
+  assert.equal(res.structuredContent.spent, 1, "the in-flight reservation is still visible");
+  assert.equal(budget.agents.get("worker-1")!.limit, 3);
+
+  // The call settles at the estimate, then the gate is released — the order
+  // every paid tool follows.
+  recordActualSpend(budget, 1, 1, "worker-1");
+  gate.release();
+  assert.equal(budget.agents.get("worker-1")!.spent, 1, "actual only: the reservation was netted out of the LIVE entry");
+  assert.equal(budget.agents.get("worker-1")!.calls, 1);
+  assert.equal(budget.spent, 1, "the global ledger agrees");
+  assert.equal(reserveBudget(budget, "worker-1", 1.5).allowed, true, "$1 of $3 spent leaves room for $1.50");
+});
+
+test("the same holds across revoke → re-delegate while a call is in flight", async () => {
+  const { call, budget } = makeHarness();
+  await call({ action: "delegate", agent_id: "worker-2", agent_limit: 2 });
+  const gate = reserveBudget(budget, "worker-2", 0.5);
+  await call({ action: "revoke", agent_id: "worker-2" });
+  const back = await call({ action: "delegate", agent_id: "worker-2", agent_limit: 2 });
+  assert.equal(back.structuredContent.spent, 0.5, "the in-flight reservation came back with the id");
+  assert.equal(reserveBudget(budget, "worker-2", 1.6).allowed, false, "and it still counts against the cap");
+
+  recordActualSpend(budget, 0.5, 0.5, "worker-2");
+  gate.release();
+  assert.equal(budget.agents.get("worker-2")!.spent, 0.5);
+  assert.equal(budget.agents.get("worker-2")!.calls, 1);
+});
+
+test("an agent_limit above the session cap says so instead of implying it can be spent", async () => {
+  // A cap set through the tool mid-session (no BLOCKRUN_BUDGET_LIMIT) is not a
+  // ceiling — the delegation is honoured and the note says the session cap
+  // will stop it first. The env-ceiling case, where the allocation itself is
+  // clamped, lives in budget-ceiling.test.ts.
+  const { call, budget } = makeHarness();
+  await call({ action: "budget", budget_action: "set", budget_amount: 3 });
+  const res = await call({ action: "delegate", agent_id: "greedy", agent_limit: 50 });
+  assert.equal(budget.agents.get("greedy")!.limit, 50);
+  assert.match(res.content[0].text, /session cap is \$3\.00/);
+  assert.doesNotMatch(res.content[0].text, /clamped/i);
+});
+
+test("an agent whose spend has reached the limit is told so, not silently re-armed", async () => {
+  const { call, budget } = makeHarness();
+  await call({ action: "delegate", agent_id: "spent-out", agent_limit: 1 });
+  budget.agents.get("spent-out")!.spent = 1;
+
+  const res = await call({ action: "delegate", agent_id: "spent-out", agent_limit: 1 });
+  assert.equal(res.structuredContent.remaining, 0);
+  assert.match(res.content[0].text, /already at its cap/);
+  assert.match(res.content[0].text, /raise agent_limit above \$1\.0000/);
+  assert.equal(reserveBudget(budget, "spent-out", 0.01).allowed, false);
+});
+
+// Audit round 4: the case between the two above. The in-flight call SETTLES
+// while the id is revoked — recordSpending looked the id up in the live map,
+// found nothing, and credited the global ledger only; the release then netted
+// the reservation out of the tombstoned entry, and the next delegate carried
+// a ledger that had forgotten the call. revoke → (call settles) → delegate was
+// still a per-agent refill, one call at a time.
+test("a call that settles while its agent is revoked is still booked against that agent's ledger", async () => {
+  const { call, budget } = makeHarness();
+  await call({ action: "delegate", agent_id: "worker-3", agent_limit: 2 });
+  const gate = reserveBudget(budget, "worker-3", 1.5);
+  await call({ action: "revoke", agent_id: "worker-3" });
+
+  // Settles at the estimate while revoked, then releases — the order every
+  // paid tool follows.
+  recordActualSpend(budget, 1.5, 1.5, "worker-3");
+  gate.release();
+  assert.equal(budget.spent, 1.5, "the global ledger has it");
+
+  const back = await call({ action: "delegate", agent_id: "worker-3", agent_limit: 2 });
+  assert.equal(back.structuredContent.spent, 1.5, "so must the agent's ledger — revoke is not a refill");
+  assert.equal(back.structuredContent.calls, 1);
+  assert.equal(reserveBudget(budget, "worker-3", 0.6).allowed, false, "$1.50 of $2 spent leaves no room for $0.60");
+});
+
+test("action:\"report\" still shows a revoked agent's spend, marked as revoked", async () => {
+  // The description promises "its spend is kept" and "report to audit
+  // spending"; a tombstone nobody can read is not kept spend.
+  const { call, budget } = makeHarness();
+  await call({ action: "delegate", agent_id: "ghost", agent_limit: 2 });
+  budget.agents.get("ghost")!.spent = 0.75;
+  budget.agents.get("ghost")!.calls = 3;
+  await call({ action: "revoke", agent_id: "ghost" });
+
+  const report = await call({ action: "report" });
+  assert.match(report.content[0].text, /ghost.*\$0\.7500.*revoked/);
+  const row = report.structuredContent.agents.ghost;
+  assert.ok(row, "the revoked agent has a row");
+  assert.equal(row.spent, 0.75);
+  assert.equal(row.calls, 3);
+  assert.equal(row.revoked, true);
+  assert.equal(row.limit, null, "a revoked agent has no cap");
+});
diff --git a/test/doc-file-refs.test.ts b/test/doc-file-refs.test.ts
new file mode 100644
index 0000000..9fc3fa9
--- /dev/null
+++ b/test/doc-file-refs.test.ts
@@ -0,0 +1,121 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// CONTRIBUTING.md pointed contributors at `src/tools/surf.ts` four times —
+// as the starting template to copy, as the reference example of the
+// path-based pattern, and as the example of the sync payment call. That file
+// was deleted with the tool in 0.49.0. Step 1 of "Adding a new MCP tool" was
+// literally uncopyable, and nothing failed, because prose naming a path is
+// invisible to a compiler.
+//
+// So: every repo path our docs name has to exist. This is the cheap half of
+// the problem. The expensive half — whether the file still demonstrates what
+// the sentence claims — is not checkable here; see the raw-call assertion at
+// the bottom for the one case that costs money to get wrong.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+// Every tracked markdown file, not a hand-kept list of three. The list was
+// README, CONTRIBUTING and one doc — so the other four docs/*.md, all sixteen
+// skills, AGENTS.md and every `[…](docs/x.md)` link in the README were never
+// scanned, and a renamed docs/spend-confirmation.md would have 404'd on
+// GitHub and npm with this test green. Excluded: CHANGELOG.md names deleted
+// files on purpose (that is what a changelog is for), and docs/plans is
+// gitignored scratch.
+const DOCS = execFileSync("git", ["ls-files", "-z", "--", "*.md", "**/*.md"], { cwd: ROOT, encoding: "utf8" })
+  .split("\0")
+  .filter((f) => f && f !== "CHANGELOG.md" && !f.startsWith("docs/plans/"));
+
+// A backticked path into the repo's own source, skills or scripts. Deliberately
+// narrow: it must start at a directory we own, so prose like `blockrun_chat`
+// or a URL never matches. `ui/` is NOT here: it is the gitignored MCP Apps
+// build output, and `ui/open-link` in docs/mcp-apps.md is an MCP Apps host
+// method, not a path.
+const REPO_PATH = /`((?:src|test|skills|scripts|apps|assets|docs|\.github)\/[A-Za-z0-9_./-]+)`/g;
+
+// A markdown link target that is not a URL or an in-page anchor, resolved
+// relative to the file that carries it — which is how GitHub and npm resolve
+// it. An optional `"title"` after the target is tolerated.
+const MD_LINK = /\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+const NOT_A_FILE = /^(?:[a-z][a-z0-9+.-]*:|#)/i; // http:, https:, mailto:, ui:, data:, …, or an anchor
+
+test("the doc set is the whole tree, not a hand-kept list", () => {
+  // If this shrinks to a handful, `git ls-files` failed or the exclusions
+  // grew too wide — either way the sweep below would be silently vacuous.
+  assert.ok(DOCS.length >= 20, `only ${DOCS.length} markdown files found: ${DOCS.join(", ")}`);
+  for (const must of ["README.md", "CONTRIBUTING.md", "AGENTS.md", "docs/mcp-apps.md", "skills/blockrun/SKILL.md"]) {
+    assert.ok(DOCS.includes(must), `${must} must be in the scanned set`);
+  }
+  assert.ok(!DOCS.includes("CHANGELOG.md"));
+});
+
+test("every repo file path named in the docs exists", () => {
+  const missing: string[] = [];
+  for (const doc of DOCS) {
+    const text = readFileSync(path.join(ROOT, doc), "utf-8");
+    for (const [, rel] of text.matchAll(REPO_PATH)) {
+      // A trailing colon-line-number ("wallet.ts:24") points INTO a file.
+      const bare = rel.replace(/:\d+$/, "");
+      if (!existsSync(path.join(ROOT, bare))) missing.push(`${doc} → ${rel}`);
+    }
+  }
+  assert.deepEqual(
+    missing,
+    [],
+    "the docs name files that are not in the repo — a contributor told to copy one cannot",
+  );
+});
+
+test("every markdown link to a file in the repo resolves from the file that carries it", () => {
+  const dead: string[] = [];
+  let checked = 0;
+  for (const doc of DOCS) {
+    const text = readFileSync(path.join(ROOT, doc), "utf-8");
+    for (const [, target] of text.matchAll(MD_LINK)) {
+      if (NOT_A_FILE.test(target)) continue;
+      const clean = target.replace(/[#?].*$/, "");
+      if (!clean) continue; // `(#anchor)` on the same page
+      checked++;
+      const resolved = clean.startsWith("/") ? path.join(ROOT, clean) : path.join(ROOT, path.dirname(doc), clean);
+      if (!existsSync(resolved)) dead.push(`${doc} → ${target}`);
+    }
+  }
+  assert.ok(checked >= 10, `only ${checked} relative links found — the link regex stopped matching`);
+  assert.deepEqual(dead, [], "a relative link that does not resolve 404s on GitHub and on npm");
+});
+
+test("CONTRIBUTING sends new path-based tools through raw-call, not straight at the SDK", () => {
+  // Not pedantry about naming. There are three payment rails and the SDK knows
+  // two: on the account rail requestWithPaymentRaw degrades to a Bearer fetch
+  // and discards the x-blockrun-cost-usd header, so a tool written that way
+  // cannot say what it cost and books the wrong ledger figure. raw-call.ts is
+  // the single entry point that exists so no tool picks a rail for itself, and
+  // every rail-parity bug this repo has shipped came from one doing so.
+  const text = readFileSync(path.join(ROOT, "CONTRIBUTING.md"), "utf-8");
+  assert.match(text, /rawGet\(client, endpoint/, "the GET helper should be the documented one");
+  assert.match(text, /rawPost\(client, endpoint/, "the POST helper should be the documented one");
+  assert.match(
+    text,
+    /Do \*\*not\*\* reach for `client\.getWithPaymentRaw`/,
+    "the SDK-direct path must stay called out as the wrong one",
+  );
+});
+
+test("every path-based tool actually goes through raw-call", () => {
+  // The claim above is only worth documenting if it is true of the code.
+  const PATH_BASED = ["search", "exa", "markets", "rpc", "defi", "phone", "modal"];
+  const offenders: string[] = [];
+  for (const name of PATH_BASED) {
+    const file = path.join(ROOT, "src", "tools", `${name}.ts`);
+    assert.ok(existsSync(file), `src/tools/${name}.ts should exist — raw-call.ts names it`);
+    const source = readFileSync(file, "utf-8");
+    if (!/from "\.\.\/utils\/raw-call\.js"/.test(source)) offenders.push(`${name}.ts`);
+    if (/client\.(get|request)WithPaymentRaw\(/.test(source)) offenders.push(`${name}.ts (calls the SDK directly)`);
+  }
+  assert.deepEqual(offenders, [], "a path-based tool that skips raw-call.ts breaks the account rail");
+});
diff --git a/test/e2e-confirm.test.ts b/test/e2e-confirm.test.ts
new file mode 100644
index 0000000..20719de
--- /dev/null
+++ b/test/e2e-confirm.test.ts
@@ -0,0 +1,108 @@
+// Run with: npm test  (tsx --test)
+//
+// Three of the Polymarket e2e scripts move real funds the moment they run:
+// `e2e:polymarket:live` and `e2e:polymarket:withdraw` submit a $2 withdrawal
+// with confirm:true, `e2e:polymarket:approve` signs the unlimited operator
+// approval batch. smoke-speech got a --confirm gate under the rule "nothing in
+// scripts/ should spend money by being run"; these three were carved out of
+// that rule, so an agent checking a redeem path with `npm run
+// e2e:polymarket:live` burned a position, bridged $2 and signed approvals with
+// no way to say no. Same class as the $0.42 paid-handler incident.
+//
+// The gate is a pure function (argv and env in, refusal out) so it can be
+// proven here without running a script. The wiring assertions at the bottom
+// are static for the same reason scripts-spend-gate.test.ts's are: a test
+// that ran the script to prove the gate would spend the wallet the day the
+// gate regressed.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIRM_ENV, CONFIRM_FLAG, requireLiveConfirm } from "../scripts/e2e-confirm.js";
+
+const SCRIPTS = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "scripts");
+
+class Exit extends Error {
+  constructor(public code: number) { super(`exit ${code}`); }
+}
+
+function attempt(argv: string[], env: Record<string, string>) {
+  const lines: string[] = [];
+  let exited: number | undefined;
+  try {
+    requireLiveConfirm(["withdraw $2.00 USDC from the Polymarket deposit wallet", "sign the unlimited operator approval batch"], {
+      argv,
+      env,
+      stderr: (s) => lines.push(s),
+      exit: (code) => { exited = code; throw new Exit(code); },
+    });
+  } catch (e) {
+    if (!(e instanceof Exit)) throw e;
+  }
+  return { exited, out: lines.join("\n") };
+}
+
+test("a bare run refuses with exit 1 and prints exactly what would move", () => {
+  const { exited, out } = attempt([], {});
+  assert.equal(exited, 1);
+  assert.match(out, /withdraw \$2\.00 USDC from the Polymarket deposit wallet/);
+  assert.match(out, /sign the unlimited operator approval batch/);
+  assert.match(out, /REAL funds/i);
+  assert.match(out, new RegExp(CONFIRM_FLAG.replace(/-/g, "\\-")));
+  assert.match(out, new RegExp(`${CONFIRM_ENV}=1`));
+});
+
+test("--confirm authorises the run", () => {
+  const { exited } = attempt([CONFIRM_FLAG], {});
+  assert.equal(exited, undefined);
+});
+
+test("the env switch authorises the run, and only with the value 1", () => {
+  assert.equal(attempt([], { [CONFIRM_ENV]: "1" }).exited, undefined);
+  assert.equal(attempt([], { [CONFIRM_ENV]: "true" }).exited, 1, "a truthy-looking string is not the documented switch");
+  assert.equal(attempt([], { [CONFIRM_ENV]: "" }).exited, 1);
+});
+
+test("BLOCKRUN_SMOKE_CONFIRM (smoke-speech's switch) does NOT authorise a Polymarket script", () => {
+  // Different money, different switch: a shell that exported the speech one
+  // for a $0.06 smoke run must not have silently pre-authorised a $2 bridge.
+  assert.equal(attempt([], { BLOCKRUN_SMOKE_CONFIRM: "1" }).exited, 1);
+});
+
+test("the gate names the two switches it accepts", () => {
+  assert.equal(CONFIRM_FLAG, "--confirm");
+  assert.equal(CONFIRM_ENV, "POLYMARKET_E2E_CONFIRM");
+});
+
+// ---- wiring: every script that passes confirm:true gates before its first await ----
+
+const MONEY_MOVING = ["polymarket-e2e-live.ts", "polymarket-e2e-withdraw.ts", "polymarket-e2e-approve.ts"];
+
+test("the set of e2e scripts that pass confirm:true to a utils/ function is known", () => {
+  const found: string[] = [];
+  for (const name of ["polymarket-e2e-live.ts", "polymarket-e2e-withdraw.ts", "polymarket-e2e-approve.ts", "polymarket-e2e-readonly.ts", "polymarket-e2e-verify-approvals.ts"]) {
+    const source = readFileSync(path.join(SCRIPTS, name), "utf8");
+    // As an argument (`{ confirm: true }`), not as prose — readonly.ts's header
+    // says "Never supplies confirm:true" and must not count.
+    if (/confirm:\s*true\s*[,}]/.test(source)) found.push(name);
+  }
+  assert.deepEqual(found.sort(), [...MONEY_MOVING].sort(), "a new script passing confirm:true moves real funds — gate it with requireLiveConfirm");
+});
+
+test("every money-moving e2e script calls requireLiveConfirm before its first await", () => {
+  for (const name of MONEY_MOVING) {
+    const source = readFileSync(path.join(SCRIPTS, name), "utf8");
+    const gate = source.search(/requireLiveConfirm\(/);
+    const firstAwait = source.search(/\bawait\b/);
+    assert.ok(gate > -1, `${name} has no confirm gate — a bare \`npm run\` moves real funds`);
+    assert.ok(firstAwait === -1 || gate < firstAwait, `${name}: the gate must come before the first await, not after money has moved`);
+  }
+});
+
+test("the read-only scripts do not carry the gate — they must stay runnable as a preflight", () => {
+  for (const name of ["polymarket-e2e-readonly.ts", "polymarket-e2e-verify-approvals.ts"]) {
+    const source = readFileSync(path.join(SCRIPTS, name), "utf8");
+    assert.doesNotMatch(source, /requireLiveConfirm\(/, `${name} never supplies confirm:true; gating it teaches people to type --confirm reflexively`);
+  }
+});
diff --git a/test/errors-rails.test.ts b/test/errors-rails.test.ts
new file mode 100644
index 0000000..0c22300
--- /dev/null
+++ b/test/errors-rails.test.ts
@@ -0,0 +1,211 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// formatError's rail awareness (audit round 3, C28 + C38). The formatter is
+// the last word every tool without a bespoke formatter gets, so the two
+// sentences it appends about MONEY have to be true on all three rails:
+//
+//   C28 — a 402 on the ACCOUNT rail means "out of prepaid credit". Since the
+//         0.50.0 status-boundary change admitted the SDK's "account API error:
+//         402." shape, it earned the wallet footer ("Run blockrun_wallet
+//         action:setup … Send USDC on Solana") for a user with no wallet — and
+//         following it lands on requireWalletMode ("unset BLOCKRUN_API_KEY").
+//   C38 — an unmarked 5xx AFTER the payment header was sent said "temporary
+//         API issue, try again in a few minutes". The gateway's catch-all 500
+//         and a post-settle 504 carry no "NOT charged" marker, so the money
+//         MAY have moved; "try again" pays a second time.
+//
+// auth.js and wallet.js are mocked so the rail is chosen here, not by whatever
+// ~/.blockrun holds on the developer's machine.
+import { test, mock, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+
+let apiKeyMode = false;
+let chain: "base" | "solana" = "solana";
+let getChainCalls = 0;
+mock.module("../src/utils/auth.js", {
+  namedExports: { isApiKeyMode: () => apiKeyMode },
+});
+mock.module("../src/utils/wallet.js", {
+  namedExports: { getChain: () => { getChainCalls++; return chain; } },
+});
+
+const { formatError, basePaymentReplayHedge } = await import("../src/utils/errors.js");
+
+/** Everything after the echoed message — the formatter's OWN words. */
+function guidance(out: string): string {
+  const i = out.indexOf("\n\n");
+  return i === -1 ? "" : out.slice(i);
+}
+
+beforeEach(() => { apiKeyMode = false; chain = "solana"; getChainCalls = 0; });
+
+// ---------------------------------------------------------------- C28 ----
+
+const ACCOUNT_402 = "BlockRun account API error: 402. Top up at https://user.blockrun.ai/dashboard/credits.";
+
+test("account rail: the SDK's 402 is out-of-credit guidance, never a wallet to fund", () => {
+  apiKeyMode = true;
+  const out = formatError(ACCOUNT_402);
+  const g = guidance(out);
+  assert.match(g, /out of credit/i, out);
+  assert.match(g, /user\.blockrun\.ai\/dashboard\/credits/, out);
+  assert.doesNotMatch(g, /wallet needs funding|Send USDC|action: "setup"|Solana|Base network/, out);
+  assert.doesNotMatch(out, /temporary API issue/, out);
+});
+
+test("account rail: a plain 'Insufficient balance' gets the same credit remedy", () => {
+  apiKeyMode = true;
+  for (const msg of ["Insufficient balance", "API error 402: insufficient balance", "Payment rejected: insufficient balance"]) {
+    const g = guidance(formatError(msg));
+    assert.match(g, /out of credit/i, msg);
+    assert.match(g, /dashboard\/credits/, msg);
+    assert.doesNotMatch(g, /wallet needs funding|Send USDC|action: "setup"/, msg);
+  }
+});
+
+test("account rail: the funding branch never probes the chain (no wallet, no keychain prompt)", () => {
+  apiKeyMode = true;
+  formatError(ACCOUNT_402);
+  assert.equal(getChainCalls, 0);
+});
+
+test("wallet rails: a 402 still names the active chain's funding path", () => {
+  for (const c of ["base", "solana"] as const) {
+    chain = c;
+    const out = formatError("API error 402: insufficient balance");
+    assert.match(out, /needs funding/, c);
+    assert.match(out, new RegExp(`Send USDC to your wallet on ${c === "solana" ? "Solana" : "Base"} network`), out);
+    assert.doesNotMatch(out, /out of credit|dashboard\/credits/, c);
+  }
+});
+
+// ---------------------------------------------------------------- C38 ----
+
+const UNMARKED_AFTER_PAYMENT = [
+  "API error after payment: 500\nInternal server error",
+  "API error after payment: 504\nRequest failed",
+  "API error after payment: 502\nRequest failed",
+  "API error after payment: upstream provider unavailable",
+];
+
+test("wallet rails: an unmarked 5xx after the payment was sent says the charge MAY have gone through", () => {
+  for (const c of ["base", "solana"] as const) {
+    chain = c;
+    for (const msg of UNMARKED_AFTER_PAYMENT) {
+      const out = formatError(msg);
+      const g = guidance(out);
+      assert.match(g, /MAY have gone through/, `${c}: ${msg}\n${out}`);
+      assert.match(g, /blockrun_wallet action:"report"/, `${c}: ${msg}`);
+      assert.doesNotMatch(g, /Try again in a few minutes/, `${c}: ${msg} — a blind retry pays twice`);
+      // The formatter still never invents a settlement claim in either direction.
+      assert.doesNotMatch(g, /nothing was charged|not settled|charge stands/, `${c}: ${msg}`);
+      assert.doesNotMatch(g, /needs funding/, `${c}: ${msg}`);
+    }
+  }
+});
+
+test("wallet rails: the gateway's own 'NOT charged' marker keeps the retry advice and drops the hedge", () => {
+  const marked = "API error after payment: 502\nUpstream provider error\nPredexon 500: An unexpected error occurred (payment NOT charged)";
+  for (const c of ["base", "solana"] as const) {
+    chain = c;
+    const g = guidance(formatError(marked));
+    assert.match(g, /nothing was charged/, c);
+    assert.match(g, /temporary API issue/, c);
+    assert.match(g, /Try again in a few minutes/, c);
+    assert.doesNotMatch(g, /MAY have gone through/, c);
+  }
+});
+
+test("a 5xx BEFORE any payment is still a plain outage to retry", () => {
+  for (const msg of ["API error: 502\nBad Gateway", "error 500 occurred", "Request failed with status code 503"]) {
+    const g = guidance(formatError(msg));
+    assert.match(g, /temporary API issue/, msg);
+    assert.match(g, /Try again in a few minutes/, msg);
+    assert.doesNotMatch(g, /MAY have gone through/, msg);
+  }
+});
+
+test("account rail: an unmarked 5xx points at the account ledger instead of 'try again'", () => {
+  apiKeyMode = true;
+  for (const msg of [
+    "BlockRun account API error: 502.",
+    "BlockRun account API error: 500. Check https://user.blockrun.ai/dashboard/activity",
+    'API error 504: {"error":"upstream timeout"}',
+  ]) {
+    const g = guidance(formatError(msg));
+    assert.match(g, /MAY have/, msg);
+    assert.match(g, /user\.blockrun\.ai\/dashboard\/activity/, msg);
+    assert.doesNotMatch(g, /Try again in a few minutes/, msg);
+    // blockrun_wallet is the tool name on every rail (action:"report" is the
+    // ledger); what must not appear is a WALLET to fund or a signature.
+    assert.match(g, /account key/, msg);
+    assert.doesNotMatch(g, /payment signature|wallet's recent|your wallet|Send USDC|needs funding/, msg);
+    assert.doesNotMatch(g, /nothing was charged|not settled|charge stands/, msg);
+  }
+  assert.equal(getChainCalls, 0, "no chain probe on the account rail");
+});
+
+test("account rail: a 5xx the gateway marked as uncharged says so and may be retried", () => {
+  apiKeyMode = true;
+  const g = guidance(formatError("API error 502: Upstream provider error (payment NOT charged)"));
+  assert.match(g, /nothing was charged/);
+  assert.match(g, /Try again in a few minutes/);
+  assert.doesNotMatch(g, /MAY have/);
+});
+
+// The abort / dropped-socket shape carries no status and no "after payment"
+// prefix: the formatter cannot see from the text whether a payment was
+// attached, so the caller says so. Without the flag the text stays bare —
+// an abort of an unpaid quote probe must not be sold as a possible charge.
+const TRANSPORT = ["This operation was aborted", "fetch failed", "socket hang up", "Request timed out after 60000ms"];
+
+test("afterPayment: an abort or dropped socket on the paid request is hedged on every rail", () => {
+  for (const rail of ["base", "solana", "account"] as const) {
+    apiKeyMode = rail === "account";
+    if (rail !== "account") chain = rail;
+    for (const msg of TRANSPORT) {
+      const out = formatError(msg, { afterPayment: true });
+      const g = guidance(out);
+      assert.match(g, /MAY have gone through/, `${rail}: ${msg}\n${out}`);
+      assert.match(g, rail === "account" ? /dashboard\/activity/ : /action:"report"/, `${rail}: ${msg}`);
+      assert.doesNotMatch(g, /Try again in a few minutes|needs funding|nothing was charged/, `${rail}: ${msg}`);
+    }
+  }
+});
+
+test("without afterPayment a transport failure stays bare — the formatter never guesses", () => {
+  for (const msg of TRANSPORT) {
+    assert.equal(formatError(msg), `Error: ${msg}`, msg);
+  }
+});
+
+test("afterPayment does not override the gateway's uncharged marker or a client 4xx", () => {
+  const uncharged = formatError("API error after payment: 502\nPredexon 500: boom (payment NOT charged)", { afterPayment: true });
+  assert.match(guidance(uncharged), /nothing was charged/);
+  assert.doesNotMatch(guidance(uncharged), /MAY have gone through/);
+  const clientErr = formatError("API error after payment: 400\nBad Request", { afterPayment: true });
+  assert.equal(clientErr, "Error: API error after payment: 400\nBad Request");
+});
+
+// ------------------------------------------------ shared Base replay hedge ----
+//
+// exa.ts grew this for the SDK's exact post-payment 402 text; defi.ts hits the
+// same gateway behaviour (neither route releases the nonce on 5xx). One helper,
+// two callers, one wording.
+
+const SDK_REJECTED = "Payment was rejected. Check your wallet balance.";
+
+test("basePaymentReplayHedge: Base only, exact SDK text only, names the upstream", () => {
+  chain = "base";
+  const hedge = basePaymentReplayHedge(SDK_REJECTED, "DefiLlama");
+  assert.match(hedge, /DefiLlama/);
+  assert.match(hedge, /nothing was settled/);
+  assert.match(hedge, /retry the call once/);
+  assert.equal(basePaymentReplayHedge(`${SDK_REJECTED} extra`, "DefiLlama"), "");
+  assert.equal(basePaymentReplayHedge("API error after payment: 502", "DefiLlama"), "");
+  chain = "solana";
+  assert.equal(basePaymentReplayHedge(SDK_REJECTED, "DefiLlama"), "");
+  apiKeyMode = true;
+  chain = "base";
+  assert.equal(basePaymentReplayHedge(SDK_REJECTED, "DefiLlama"), "");
+});
diff --git a/test/errors.test.ts b/test/errors.test.ts
index c0a6abb..3ea562b 100644
--- a/test/errors.test.ts
+++ b/test/errors.test.ts
@@ -1,7 +1,7 @@
 // Run with: npm test  (tsx --test)
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { extractErrorMessage, formatError, isPaymentRejectionError } from "../src/utils/errors.js";
+import { extractErrorMessage, formatError, hasLabelledServerStatus, isPaymentRejectionError } from "../src/utils/errors.js";
 
 test("model-unavailable (token360) → steers to a sibling model, not a generic blip", () => {
   const msg = "Video generation failed: API error 500: token360 video submit failed: Model 'seedance-2.0-fast' not found or not active for requested provider";
@@ -55,17 +55,24 @@ test("a pre-payment validation error that says no payment was made is not fundin
   assert.doesNotMatch(out, /funding instructions/);
 });
 
-test("post-payment 5xx still reads as an outage even without a parseable status", () => {
+test("post-payment 5xx is never an empty wallet, even without a parseable status", () => {
+  // Since audit round 3 (C38) an UNMARKED post-payment 5xx is hedged ("the
+  // charge MAY have gone through") rather than sold as an outage to retry;
+  // the per-rail wording is pinned in errors-rails.test.ts. What this test
+  // guards is the older mistake: the "payment" keyword reading as "fund".
   for (const msg of [
     "API error after payment: 500 Internal Server Error",
     "API error after payment: 502 Bad Gateway",
     "API error after payment: upstream provider unavailable",
-    "Request failed with status code 503",
   ]) {
     const out = formatError(msg);
-    assert.match(out, /temporary API issue/, msg);
+    assert.match(out, /MAY have gone through/, msg);
     assert.doesNotMatch(out, /needs funding/, msg);
   }
+  // A 5xx with no payment attached is still the plain outage.
+  const out = formatError("Request failed with status code 503");
+  assert.match(out, /temporary API issue/);
+  assert.doesNotMatch(out, /needs funding|MAY have gone through/);
 });
 
 test("an incidental 5xx-shaped number is not sold to the user as an outage", () => {
@@ -147,17 +154,20 @@ test("extractErrorMessage surfaces the SDK's `detail` field (blockrun-llm-ts#39)
 });
 
 test("a post-payment 5xx WITHOUT the gateway's uncharged marker never claims nothing was charged", () => {
-  // The formatter must never invent a settlement claim: only the gateway's own
-  // marker in the message earns the "nothing was charged" line.
+  // The formatter must never invent a settlement claim in EITHER direction:
+  // only the gateway's own marker earns "nothing was charged", and the
+  // post-payment hedge says MAY, never "the charge stands".
   for (const msg of [
     "API error after payment: 502\nRequest failed",
     "API error after payment: 500 Internal Server Error",
-    "error 500 occurred",
   ]) {
     const out = formatError(msg);
-    assert.match(out, /temporary API issue/, msg);
-    assert.doesNotMatch(out, /nothing was charged|not settled/, msg);
+    assert.match(out, /MAY have gone through/, msg);
+    assert.doesNotMatch(out, /nothing was charged|not settled|charge stands|Try again in a few minutes/, msg);
   }
+  const out = formatError("error 500 occurred");
+  assert.match(out, /temporary API issue/);
+  assert.doesNotMatch(out, /nothing was charged|not settled/);
 });
 
 test("extractErrorMessage does not repeat a detail identical to the message", () => {
@@ -195,6 +205,106 @@ test("a post-payment 501 does not claim nothing was charged", () => {
 
 test("the SDK's post-payment prefix counts as a labelled status", () => {
   // "API error after payment: 502" — the word before the number is "payment".
+  // It classifies as a 5xx (hasLabelledServerStatus), and because the payment
+  // had been sent it is the hedged branch, not the plain outage and not
+  // funding advice.
+  assert.equal(hasLabelledServerStatus("API error after payment: 502\nRequest failed"), true);
   const out = formatError("API error after payment: 502\nRequest failed");
-  assert.match(out, /temporary API issue/);
+  assert.match(out, /MAY have gone through/);
+  assert.doesNotMatch(out, /needs funding/);
+});
+
+// --- the account rail's own error shape (audit round 2) ---
+//
+// @blockrun/llm's account client writes `BlockRun account API error: ${status}.${hint}`
+// — with a sentence-ending period. The status boundary excluded a dot outright
+// (so "$402.50" could not read as a status), which meant every account-rail
+// status fell through unclassified: the identical wallet-rail message got
+// guidance, the account one got none.
+
+test("an account-rail 5xx is classified like the wallet rail's", () => {
+  for (const msg of [
+    "BlockRun account API error: 502.",
+    "BlockRun account API error: 503. Retry-After: 30",
+    "BlockRun account API error: 500. Check https://user.blockrun.ai/dashboard/activity",
+  ]) {
+    const out = formatError(msg);
+    assert.match(out, /temporary API issue/, msg);
+    assert.doesNotMatch(out, /needs funding/, msg);
+  }
+});
+
+test("an account-rail 402 is classified as a payment problem, not an outage", () => {
+  // This file runs on whatever rail the machine is on; the rail-specific
+  // remedy (credit top-up vs wallet funding) is pinned under a mocked auth.js
+  // in errors-rails.test.ts. The earlier version of this test matched
+  // /Insufficient/, a word the echoed input already contains, so it could not
+  // fail either way (C28).
+  const out = formatError("BlockRun account API error: 402. Insufficient credit");
+  const guidance = out.slice(out.indexOf("\n\n"));
+  assert.match(guidance, /needs funding|out of credit/);
+  assert.doesNotMatch(out, /temporary API issue/);
+});
+
+test("an account-rail 501 is 'not served', and says nothing was charged", () => {
+  const out = formatError("BlockRun account API error: 501.");
+  assert.match(out, /does not serve this endpoint/);
+  assert.match(out, /nothing was charged/);
+});
+
+test("a decimal amount is STILL not a status code after the boundary change", () => {
+  // The whole reason a dot was excluded. A dot followed by a digit is a decimal
+  // point; a dot not followed by one is punctuation.
+  for (const msg of ["Charged $402.50 for this render", "cost was $1.4020 total", "price 500.25 usd"]) {
+    const out = formatError(msg);
+    assert.doesNotMatch(out, /temporary API issue/, msg);
+    assert.doesNotMatch(out, /does not serve this endpoint/, msg);
+    assert.doesNotMatch(out, /wallet needs funding/, msg);
+  }
+});
+
+test("hasLabelledServerStatus agrees with formatError on the dotted shape", () => {
+  assert.equal(hasLabelledServerStatus("BlockRun account API error: 502."), true);
+  assert.equal(hasLabelledServerStatus("error 500. something"), true);
+  assert.equal(hasLabelledServerStatus("charged $500.25"), false);
+  assert.equal(hasLabelledServerStatus("batch of 501 items"), false);
+});
+
+// --- "nothing was charged" must never carry "fund your wallet" (round 2) ---
+//
+// explicitlyUncharged gated only the `payment` keyword sub-clause, so a bare
+// 402, "balance" or "insufficient" still earned the funding footer. Two of this
+// repo's own messages did exactly that.
+
+test("the video tool's unreadable-quote refusal does not tell a funded wallet to top up", () => {
+  const out = formatError(
+    "The gateway's 402 quote carried an unreadable amount (\"garbage\"). Refusing to sign a payment " +
+    "for an amount that could not be validated — no charge was made. This is a gateway fault; retry, " +
+    "and report it if it persists.",
+  );
+  assert.doesNotMatch(out, /needs funding/);
+  assert.doesNotMatch(out, /Send USDC/);
+});
+
+test("RealFace's 'No payment taken' is recognised as uncharged", () => {
+  const out = formatError("Portrait rejected — the image did not pass the liveness check. No payment taken.");
+  assert.doesNotMatch(out, /needs funding/);
+});
+
+test("the quote guard's own refusal does not read as a funding problem", () => {
+  const out = formatError(
+    "The gateway quoted $1.1355 for azure/sora-2 video, but this tool expected about $0.4220 " +
+    "(2.7x the published rate). Refusing to sign it — no charge was made.",
+  );
+  assert.doesNotMatch(out, /needs funding/);
+});
+
+test("a genuine empty wallet STILL gets funding advice", () => {
+  for (const msg of [
+    "API error: 402 Payment Required",
+    "Payment rejected: insufficient balance",
+    "insufficient funds for this call",
+  ]) {
+    assert.match(formatError(msg), /needs funding|Send USDC/, msg);
+  }
 });
diff --git a/test/exa-replay-hedge.test.ts b/test/exa-replay-hedge.test.ts
new file mode 100644
index 0000000..bb84f66
--- /dev/null
+++ b/test/exa-replay-hedge.test.ts
@@ -0,0 +1,127 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// On the Base rail a transient Exa 5xx surfaces as "wallet needs funding".
+// Traced 2026-09-13 in @blockrun/llm 3.15.1 and the gateway:
+//
+//   1. MCP signs the 402, gateway proxies, Exa answers 5xx.
+//   2. Gateway exa route returns 502 "Payment was NOT charged" — but unlike the
+//      pm route it does NOT releasePaymentNonce, so the nonce stays claimed.
+//   3. handlePaymentAndRetryRaw (dist/index.js:5274-5286) sleeps 1s and
+//      re-sends the SAME PAYMENT-SIGNATURE; rejectReplay answers 402
+//      {code: PAYMENT_REPLAY}; the SDK turns any post-payment 402 into
+//      PaymentError("Payment was rejected. Check your wallet balance.") and
+//      drops the body.
+//   4. formatError sees "balance" and appends the funding footer.
+//
+// Nothing settled, the wallet may hold $50, and the agent is told to top up.
+// The Solana client has no 502 retry and the account rail has no nonce, so
+// this is Base-only. The tool cannot tell a replay from a real rejection (the
+// SDK discards the code), so it HEDGES on Base instead of prescribing funding
+// — and says nothing extra on the other two rails, where the sentence means
+// what it says.
+import { test, mock, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import type { BudgetState } from "../src/types.js";
+
+let apiKeyMode = false;
+let chain: "base" | "solana" = "base";
+let walletThrows: Error | null = null;
+const stubClient = {
+  getWithPaymentRaw: async () => { throw new Error("exa never GETs"); },
+  requestWithPaymentRaw: async () => { if (walletThrows) throw walletThrows; return { results: [] }; },
+};
+mock.module("../src/utils/wallet.js", {
+  namedExports: {
+    getApiBase: () => "https://blockrun.ai/api",
+    resolveGatewayUrl: (u: string) => u,
+    getChain: () => chain,
+    getClient: () => stubClient,
+    buildClient: () => stubClient,
+    buildClientWithTimeout: () => stubClient,
+    baseOnlyMessage: () => null,
+    getOrCreateWalletKey: () => { throw new Error("exa tests must not touch a wallet key"); },
+    getWalletInfo: async () => ({ address: "0xTEST" }),
+  },
+});
+mock.module("../src/utils/auth.js", {
+  namedExports: {
+    isApiKeyMode: () => apiKeyMode,
+    getApiKey: () => (apiKeyMode ? "br_test_key" : undefined),
+    apiAuthHeaders: () => ({ Authorization: "Bearer br_test_key" }),
+    getApiKeyBase: () => "https://api.blockrun.ai",
+    PORTAL_CREDITS_URL: "https://user.blockrun.ai/dashboard/credits",
+  },
+});
+let accountThrows: Error | null = null;
+mock.module("../src/utils/http.js", {
+  namedExports: {
+    fetchWithTimeout: async () => {
+      if (accountThrows) throw accountThrows;
+      return new Response(JSON.stringify({ results: [] }), { status: 200, headers: { "content-type": "application/json", "x-blockrun-cost-usd": "0.01" } });
+    },
+    isTimeoutError: () => false,
+  },
+});
+
+const { registerExaTool } = await import("../src/tools/exa.js");
+
+// The SDK's exact text — the only signal the tool gets.
+const SDK_REJECTED = "Payment was rejected. Check your wallet balance.";
+
+type Handler = (args: Record<string, unknown>) => Promise<{ content: Array<{ type: string; text?: string }>; isError?: boolean }>;
+function harness() {
+  let handler: Handler | undefined;
+  const server = {
+    registerTool: (_n: string, _c: unknown, h: Handler) => { handler = h; },
+    server: { getClientCapabilities: () => ({}) },
+  };
+  const budget: BudgetState = { limit: null, spent: 0, calls: 0, agents: new Map() };
+  registerExaTool(server as never, budget);
+  assert.ok(handler, "blockrun_exa did not register a handler");
+  return { call: (args: Record<string, unknown>) => handler!(args), budget };
+}
+
+beforeEach(() => { apiKeyMode = false; chain = "base"; walletThrows = null; accountThrows = null; });
+
+test("Base rail: the SDK's post-payment rejection is hedged — it may be a replay after an upstream Exa error, not an empty wallet", async () => {
+  walletThrows = new Error(SDK_REJECTED);
+  const { call, budget } = harness();
+  const res = await call({ path: "search", body: { query: "fed" } });
+  const text = res.content.map((p) => p.text ?? "").join("\n");
+  assert.equal(res.isError, true);
+  assert.match(text, /Payment was rejected/, "the SDK's own words stay — it MAY be a real rejection");
+  assert.match(text, /upstream|Exa/i, text);
+  assert.match(text, /nothing (was )?settled|not charged|no charge/i, text);
+  assert.match(text, /retry/i, text);
+  assert.match(text, /status|report/i, "point at a wallet action that exists (blockrun_wallet has no \"balance\")");
+  assert.equal(budget.spent, 0, "a rejected call books nothing");
+});
+
+test("Solana rail: no hedge — the Solana client does not retry a 502 with a burned nonce", async () => {
+  chain = "solana";
+  walletThrows = new Error(SDK_REJECTED);
+  const { call } = harness();
+  const res = await call({ path: "search", body: { query: "fed" } });
+  const text = res.content.map((p) => p.text ?? "").join("\n");
+  assert.equal(res.isError, true);
+  assert.match(text, /Payment was rejected/);
+  assert.doesNotMatch(text, /replay|re-sent|resent/i, text);
+});
+
+test("account rail: no hedge — there is no nonce to replay", async () => {
+  apiKeyMode = true;
+  accountThrows = new Error(SDK_REJECTED);
+  const { call } = harness();
+  const res = await call({ path: "search", body: { query: "fed" } });
+  const text = res.content.map((p) => p.text ?? "").join("\n");
+  assert.equal(res.isError, true);
+  assert.doesNotMatch(text, /replay|re-sent|resent/i, text);
+});
+
+test("Base rail: any other error is untouched by the hedge", async () => {
+  walletThrows = new Error("API error after payment: 502");
+  const { call } = harness();
+  const res = await call({ path: "search", body: { query: "fed" } });
+  const text = res.content.map((p) => p.text ?? "").join("\n");
+  assert.doesNotMatch(text, /replay|re-sent|resent/i, text);
+});
diff --git a/test/harness-pin.test.ts b/test/harness-pin.test.ts
new file mode 100644
index 0000000..38a1d84
--- /dev/null
+++ b/test/harness-pin.test.ts
@@ -0,0 +1,52 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// The suite's verdict must not depend on whose machine runs it. Ten mocked-
+// handler suites (chat-settled-on-error, chat-free-deadline, music-cost, video-
+// money-path, realface-money-path, phone, price-behaviour, dex, ...) never mock
+// utils/auth.js, and isApiKeyMode() reads BLOCKRUN_API_KEY or ~/.blockrun/.api-key
+// from the REAL home. A developer who set up account mode locally ran the Base-
+// rail assertions on the account rail: six chat tests went red with account-rail
+// text, and the obvious "fix" is to rewrite the expectations — quietly deleting
+// the Base assertion those tests exist for. image-cost.test.ts pinned itself
+// (temp HOME, no env key) in 0.49.0; nothing pinned the other nine.
+//
+// test/_setup.ts is preloaded into every test child by the `test` script
+// (`--import`), and it is what this file checks. Each assertion is about the
+// process this test runs in, not about the setup file's text: if the pin is
+// dropped from package.json, or the setup stops clearing a variable, the
+// corresponding assertion fails here for the right reason.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, readdirSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+test("the suite does not run in the developer's real home directory", () => {
+  // os.homedir() honours $HOME (POSIX) / %USERPROFILE% (Windows); os.userInfo()
+  // asks the passwd database, which no env var can move. They agree only when
+  // nothing pinned HOME.
+  let real: string | undefined;
+  try { real = os.userInfo().homedir; } catch { /* no passwd entry (some containers) */ }
+  const pinned = os.homedir();
+  assert.ok(pinned, "os.homedir() must resolve");
+  if (real) assert.notEqual(pinned, real, "HOME is the real home — ~/.blockrun/.api-key and .session leak into the suite");
+  assert.ok(existsSync(pinned), "the pinned HOME must exist, so code that writes ~/.blockrun can");
+  assert.deepEqual(readdirSync(pinned), [], "the pinned HOME must start empty — no key file, no session, no chain preference");
+});
+
+test("no BlockRun credential, chain or pricing override reaches the suite from the shell", () => {
+  // Every one of these selects a rail, a chain, a key or a price. A suite that
+  // wants one sets it itself and restores it; none may inherit it.
+  const leaked = Object.keys(process.env).filter((k) =>
+    /^(BLOCKRUN_|SOLANA_|POLYMARKET_)/.test(k) || k === "BASE_CHAIN_WALLET_KEY" || k === "TRANSACTION_FEE_USD",
+  );
+  assert.deepEqual(leaked, [], "these came from the developer's shell, not from a test");
+});
+
+test("the key file the account rail looks for is absent under the pinned home", async () => {
+  // auth.ts captures the key path from os.homedir() at import time, so this
+  // import must happen AFTER the pin — which the --import preload guarantees.
+  const { isApiKeyMode } = await import("../src/utils/auth.js");
+  assert.equal(existsSync(path.join(os.homedir(), ".blockrun", ".api-key")), false);
+  assert.equal(isApiKeyMode(), false, "the suite must start on the wallet rail; account-rail suites mock auth.js explicitly");
+});
diff --git a/test/image-account-cost.test.ts b/test/image-account-cost.test.ts
index 82ab364..8e9a5a6 100644
--- a/test/image-account-cost.test.ts
+++ b/test/image-account-cost.test.ts
@@ -17,37 +17,75 @@
 //                    "nothing settled at response time", never "free": booking
 //                    $0 against a call that was genuinely billed is the failure
 //                    this whole mechanism exists to prevent.
-import { test, mock } from "node:test";
+//
+// Audit round 3 added the shape of the WIRE: the account gateway answers 202 +
+// poll_url for any render past its 30s inline window (the default gpt-image-2,
+// every edit), and the single-POST helper this rail used until then handed
+// that envelope back as the image — "No image URL in response", job id and
+// poll_url dropped, the render orphaned, and the agent's retry submitting
+// another. So the real utils/api-key-call.ts runs here over a scripted
+// fetchWithTimeout, and the 202 path is driven end to end.
+import { test, mock, beforeEach } from "node:test";
 import assert from "node:assert/strict";
 import type { BudgetState } from "../src/types.js";
 
-let lastPostedEndpoint: string | undefined;
-let settledCost: number | null = 0.0525;
-
-// Drive account mode through the env var rather than mocking auth.js: the mode
-// is derived from BLOCKRUN_API_KEY, and replacing that module wholesale drops
-// exports other modules import (onramp.ts wants PORTAL_CREDITS_URL).
-process.env.BLOCKRUN_API_KEY = "brk_live_testkeyfortestsonly0000";
+function headers(map: Record<string, string> = {}) {
+  const lower = Object.fromEntries(Object.entries(map).map(([k, v]) => [k.toLowerCase(), v]));
+  return { get: (name: string) => lower[name.toLowerCase()] ?? null };
+}
 
-// The account rail helper the four hand-built tools already use. Standing in
-// for it keeps this test off the network while exercising the same seam.
-mock.module("../src/utils/api-key-call.js", {
+// Scripted wire: each fetch shifts one response; an empty script means the
+// test expected NO further network call. `requests` records what was sent.
+let script: Array<() => unknown> = [];
+const requests: Array<{ url: string; method: string }> = [];
+mock.module("../src/utils/http.js", {
   namedExports: {
-    apiKeyPost: async (endpoint: string) => {
-      lastPostedEndpoint = endpoint;
-      return {
-        data: { data: [{ url: "https://blockrun.ai/media/fake.png" }] },
-        paidUsd: settledCost,
-        txHash: "credit:test",
-      };
+    fetchWithTimeout: async (url: string, init: { method?: string }) => {
+      requests.push({ url, method: init.method ?? "GET" });
+      const next = script.shift();
+      if (!next) throw new Error("UNEXPECTED_NETWORK_CALL");
+      return next();
+    },
+    isTimeoutError: (err: unknown) => {
+      const name = err instanceof Error ? err.name : "";
+      if (name === "AbortError" || name === "TimeoutError") return true;
+      const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+      return msg.includes("abort") || msg.includes("timeout") || msg.includes("timed out") || msg.includes("did not complete within");
     },
   },
 });
+// A movable clock, so the poll deadline can pass without five minutes of
+// real time.
+const realNow = Date.now;
+let clockOffset = 0;
+mock.method(Date, "now", () => realNow() + clockOffset);
+
+const inline200 = (cost: number | null) => () => ({
+  status: 200, ok: true,
+  headers: headers(cost === null ? {} : { "x-blockrun-cost-usd": cost.toFixed(6), "x-payment-receipt": "credit:test" }),
+  json: async () => ({ data: [{ url: "https://blockrun.ai/media/fake.png" }] }),
+});
+const queued202 = () => ({
+  status: 202, ok: true,
+  headers: headers(),
+  json: async () => ({ id: "img_42", status: "queued", poll_url: "/api/v1/images/generations/img_42" }),
+});
+const poll = (status: number, body: unknown, extra: Record<string, string> = {}) => () => ({
+  status, ok: status >= 200 && status < 300, headers: headers(extra), json: async () => body,
+});
+const abortError = () => { const e = new Error("This operation was aborted"); e.name = "AbortError"; return e; };
+
+// Drive account mode through the env var rather than mocking auth.js: the mode
+// is derived from BLOCKRUN_API_KEY, and replacing that module wholesale drops
+// exports other modules import (onramp.ts wants PORTAL_CREDITS_URL).
+process.env.BLOCKRUN_API_KEY = "brk_live_testkeyfortestsonly0000";
 
 mock.module("../src/utils/wallet.js", {
   namedExports: {
     getApiBase: () => "https://api.blockrun.ai",
-    resolveGatewayUrl: (u: string) => (u.startsWith("http") ? u : `https://api.blockrun.ai${u}`),
+    // The real resolver's shape: the gateway hands back a root-relative
+    // /api/v1/... path and the account API serves /v1/... at its root.
+    resolveGatewayUrl: (u: string) => (u.startsWith("http") ? u : `https://api.blockrun.ai${u.startsWith("/api/") ? u.slice(4) : u}`),
     getChain: () => "solana", // account rail must win over this, not read a key
     getImageClient: () => {
       throw new Error("account rail must NOT go through the SDK ImageClient");
@@ -75,9 +113,11 @@ function makeHarness() {
   return { call: (args: Record<string, unknown>) => handler!(args), budget };
 }
 
+beforeEach(() => { script = []; requests.length = 0; clockOffset = 0; });
+
 test("account rail reports the SETTLED cost, not the estimate", async () => {
-  settledCost = 0.0525;
-  const { call } = makeHarness();
+  script = [inline200(0.0525)];
+  const { call, budget } = makeHarness();
   const res = await call({ prompt: "a red cube", model: "google/nano-banana" });
   const text = res.content.map((c: any) => c.text).join("\n");
 
@@ -87,22 +127,24 @@ test("account rail reports the SETTLED cost, not the estimate", async () => {
   assert.doesNotMatch(text, /estimated/);
   assert.equal(res.structuredContent.cost_usd, 0.0525);
   assert.equal(res.structuredContent.cost_is_estimate, false);
+  assert.equal(budget.spent, 0.0525, "the ledger books the header, once");
 });
 
 test("account rail does not go through the SDK or touch a wallet", async () => {
   // getImageClient and getOrCreateWalletKey both throw in this harness, so
   // reaching either fails the test rather than silently working.
-  settledCost = 0.0525;
+  script = [inline200(0.0525)];
   const { call } = makeHarness();
   const res = await call({ prompt: "a red cube", model: "google/nano-banana" });
   assert.equal(res.isError, undefined);
-  assert.ok(lastPostedEndpoint, "expected the account rail to POST directly");
+  assert.equal(requests.length, 1, "expected the account rail to POST directly");
+  assert.equal(requests[0].url, "https://api.blockrun.ai/v1/images/generations");
 });
 
 test("an absent settled cost falls back to the estimate and still says so", async () => {
   // paidUsd null means the rail settled nothing at response time. It must not
   // be booked as $0.
-  settledCost = null;
+  script = [inline200(null)];
   const { call, budget } = makeHarness();
   const res = await call({ prompt: "a red cube", model: "google/nano-banana" });
   const text = res.content.map((c: any) => c.text).join("\n");
@@ -112,3 +154,113 @@ test("an absent settled cost falls back to the estimate and still says so", asyn
   assert.ok(res.structuredContent.cost_usd > 0, "must not book a null as $0");
   assert.ok(budget.spent > 0, "the ledger must not record zero for a billed call");
 });
+
+test("a render past the inline window (202 + poll_url) is polled to completion and returned", async () => {
+  // The default gpt-image-2 routinely exceeds the gateway's 30s window. Until
+  // audit round 3 this rail took the 202 envelope as the image and returned
+  // "No image URL in response" with the job discarded.
+  script = [
+    queued202,
+    poll(202, { id: "img_42", status: "in_progress" }),
+    poll(200, { id: "img_42", status: "completed", data: [{ url: "https://blockrun.ai/media/img_42.png" }] }, { "x-blockrun-cost-usd": "0.063000" }),
+  ];
+  const { call, budget } = makeHarness();
+  const res = await call({ prompt: "a red cube", model: "openai/gpt-image-2", size: "1024x1024" });
+  const text = res.content.map((c: any) => c.text).join("\n");
+  assert.notEqual(res.isError, true, text);
+  assert.match(text, /Image: https:\/\/blockrun\.ai\/media\/img_42\.png/);
+  assert.doesNotMatch(text, /No image URL/);
+  assert.equal(res.structuredContent.url, "https://blockrun.ai/media/img_42.png");
+  // The poll went to the ACCOUNT API root (resolveGatewayUrl), not to a
+  // string-concatenated /api/v1 on the wallet gateway.
+  assert.equal(requests[1].url, "https://api.blockrun.ai/v1/images/generations/img_42");
+  assert.equal(requests[1].method, "GET");
+  assert.equal(budget.spent, 0.063, "booked from the completed poll's cost header, once");
+  assert.equal(script.length, 0);
+});
+
+test("a 202 render that never completes is booked, names the job, and does not invite a second submit", async () => {
+  script = [
+    queued202,
+    () => { clockOffset += 3_600_000; return poll(202, { id: "img_42", status: "in_progress" })(); },
+  ];
+  const { call, budget } = makeHarness();
+  const res = await call({ prompt: "a red cube", model: "openai/gpt-image-2", size: "1024x1024" });
+  const text = res.content.map((c: any) => c.text).join("\n");
+  assert.equal(res.isError, true, text);
+  assert.match(text, /job img_42/);
+  assert.match(text, /dashboard\/activity/);
+  assert.match(text, /bills a second render/);
+  assert.doesNotMatch(text, /No image URL/);
+  assert.doesNotMatch(text, /No payment was taken/);
+  // No cost header on the 202: the estimate is booked, never $0.
+  assert.equal(budget.spent, 0.065, `spent=${budget.spent}`);
+});
+
+test("a submit that never answers MAY have been accepted: booked and said so", async () => {
+  // 0.50.0 cleared the in-flight flag in a `.finally` on this rail, so an
+  // abort after the Bearer went out returned a plain "failed" with $0 booked.
+  script = [() => { throw abortError(); }];
+  const { call, budget } = makeHarness();
+  const res = await call({ prompt: "a red cube", model: "google/nano-banana" });
+  const text = res.content.map((c: any) => c.text).join("\n");
+  assert.equal(res.isError, true, text);
+  assert.match(text, /MAY have been accepted/);
+  assert.match(text, /dashboard\/activity/);
+  assert.doesNotMatch(text, /No payment was taken/);
+  assert.equal(budget.spent, 0.054501, "the estimate is booked conservatively");
+});
+
+test("an out-of-credit 402 on this rail is a funding answer, not a maybe, and books nothing", async () => {
+  script = [poll(402, { error: "insufficient credit" })];
+  const { call, budget } = makeHarness();
+  const res = await call({ prompt: "a red cube", model: "google/nano-banana" });
+  const text = res.content.map((c: any) => c.text).join("\n");
+  assert.equal(res.isError, true);
+  assert.match(text, /out of credit/);
+  assert.doesNotMatch(text, /MAY have/);
+  assert.equal(budget.spent, 0);
+});
+
+// Audit round 4: the account rail is NOT wrapped in the in-flight tracker —
+// apiKeyAsyncPost classifies every post-submit exit itself (BilledJobError,
+// JobFailedError), and arming the tracker around it made a not_charged
+// terminal failure whose upstream text said "timeout" read as "MAY have
+// settled": budget.spent += a whole render and the text told the user to
+// check the dashboard before retrying a job the gateway had just said cost
+// nothing. video and music documented exactly this; image did the opposite.
+test("a not_charged terminal failure whose text says 'timeout' books nothing and says so", async () => {
+  script = [
+    queued202,
+    poll(200, { status: "failed", error: "The operation was aborted due to timeout", payment_status: "not_charged", note: "No payment was taken." }),
+  ];
+  const { call, budget } = makeHarness();
+  const res = await call({ prompt: "a cube", model: "google/nano-banana", size: "1024x1024" });
+  assert.equal(res.isError, true);
+  assert.equal(budget.spent, 0, "the gateway said not_charged — nothing is booked");
+  assert.match(res.content[0].text, /No payment was taken/);
+  assert.doesNotMatch(res.content[0].text, /MAY have/);
+  assert.doesNotMatch(res.content[0].text, /booked against your budget/);
+});
+
+test("a 504 that ARRIVED on submit is an answer, not a maybe — nothing is booked as 'may have settled'", async () => {
+  script = [poll(504, { error: "Upstream timeout" })];
+  const { call, budget } = makeHarness();
+  const res = await call({ prompt: "a cube", model: "google/nano-banana", size: "1024x1024" });
+  assert.equal(res.isError, true);
+  assert.equal(budget.spent, 0);
+  // formatError's hedge for a 5xx after the key was sent is text only, by
+  // design; what must not happen is the in-flight BOOKING sentence.
+  assert.doesNotMatch(res.content[0].text, /booked against your budget/);
+  assert.doesNotMatch(res.content[0].text, /got no answer/);
+});
+
+test("a 202 whose body carries no poll_url is a BILLED job, not a plain error", async () => {
+  script = [() => ({ status: 202, ok: true, headers: headers({ "x-blockrun-cost-usd": "0.052500" }), json: async () => ({ id: "img_43", status: "queued" }) })];
+  const { call, budget } = makeHarness();
+  const res = await call({ prompt: "a cube", model: "google/nano-banana", size: "1024x1024" });
+  assert.equal(res.isError, true);
+  assert.equal(budget.spent, 0.0525, "the submit was accepted and billed; the ledger carries it");
+  assert.match(res.content[0].text, /img_43/);
+  assert.match(res.content[0].text, /bills a second render/);
+});
diff --git a/test/image-cost.test.ts b/test/image-cost.test.ts
index f1283bd..1294e00 100644
--- a/test/image-cost.test.ts
+++ b/test/image-cost.test.ts
@@ -59,7 +59,15 @@ let networkCalls = 0;
 mock.module("../src/utils/http.js", {
   namedExports: {
     fetchWithTimeout: async () => { networkCalls++; throw new Error("network call escaped the mocks"); },
-    isTimeoutError: () => false,
+    // The real predicate, restated. A `() => false` stub here (as this suite
+    // had until audit round 3) hides the timeout branch from every test in
+    // the file — which is how a dead in-flight booking stayed green.
+    isTimeoutError: (err: unknown) => {
+      const name = err instanceof Error ? err.name : "";
+      if (name === "AbortError" || name === "TimeoutError") return true;
+      const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+      return msg.includes("abort") || msg.includes("timeout") || msg.includes("timed out") || msg.includes("did not complete within");
+    },
   },
 });
 
@@ -85,16 +93,23 @@ function makeHarness() {
 }
 
 // The Cost footer and the ledger must report what the user is CHARGED, not the
-// catalog base. The gateway settles catalog x 1.05 + $0.002 (verified live:
-// cogview-4 base $0.015 -> charged $0.017751), so reporting the catalog figure
-// understated real spend in the footer, the confirmSpend prompt and the ledger.
-test("generate result includes a Cost line at the CHARGED price, not the catalog base", async () => {
-  const { call } = makeHarness();
+// catalog base and not the reserve. The gateway settles catalog x 1.05 + a
+// transaction fee; the RESERVE (estimateCost) carries that fee at $0.002, the
+// higher figure it has flip-flopped through, on purpose (see utils/tx-fee.ts).
+// What the Base gateway is OBSERVED to charge is $0.001 — an unpaid 402 probe
+// of /v1/images/generations on 2026-09-13 quoted cogview-4 at 16750 micro
+// ($0.016750 = 0.015 x 1.05 + $0.001) against a $0.017751 reserve — so the
+// footer and the ledger carry ledgerFallback(reserve): reserve - $0.002 +
+// $0.001, never more than the reserve. Booking the reserve verbatim tripped
+// caps one fee early on every Base image (audit round 3).
+test("generate result includes a Cost line at the CHARGED price, not the catalog base or the reserve", async () => {
+  const { call, budget } = makeHarness();
   const res = await call({ prompt: "a red cube", model: "openai/gpt-image-2", size: "1024x1024" });
   const text = res.content.map((c: any) => c.text).join("\n");
-  assert.match(text, /Cost: \$0\.0650/); // 0.06 catalog x 1.05 + $0.002
-  assert.equal(res.structuredContent.cost_usd, 0.065);
+  assert.match(text, /Cost: \$0\.0640/); // 0.06 catalog x 1.05 + $0.001 observed (reserve is $0.065)
+  assert.equal(res.structuredContent.cost_usd, 0.064);
   assert.equal(res.isError, undefined);
+  assert.equal(budget.spent, 0.064, "the ledger books the observed charge, not the $0.065 reserve");
   assert.equal(networkCalls, 0, "the mocked ImageClient must be the only rail this suite touches");
 });
 
@@ -102,24 +117,64 @@ test("large gpt-image-2 render is billed at the large-size CHARGED price", async
   const { call } = makeHarness();
   const res = await call({ prompt: "wide banner", model: "openai/gpt-image-2", size: "1536x1024" });
   const text = res.content.map((c: any) => c.text).join("\n");
-  assert.match(text, /Cost: \$0\.1280/);
-  assert.equal(res.structuredContent.cost_usd, 0.128);
+  assert.match(text, /Cost: \$0\.1270/); // reserve $0.128
+  assert.equal(res.structuredContent.cost_usd, 0.127);
 });
 
 test("cheapest model (cogview-4) shows its own price", async () => {
   const { call } = makeHarness();
   const res = await call({ prompt: "a cat", model: "zai/cogview-4" });
   const text = res.content.map((c: any) => c.text).join("\n");
-  assert.match(text, /Cost: \$0\.0178/);
+  assert.match(text, /Cost: \$0\.0168/); // the 2026-09-13 live quote: $0.016750 (booked as 0.016751, the reserve's ceil drift)
+});
+
+test("Base: the SDK call dropping mid-payment is booked and reported as a possible charge", async () => {
+  // The SDK signs and sends the payment inside generate(); an abort out of it
+  // is the paid retry (or its poll) that never answered. 0.50.0 never set the
+  // in-flight flag on this rail at all, so this returned a plain "failed" with
+  // $0 booked and the reservation released (audit round 3).
+  const abort = new Error("This operation was aborted");
+  abort.name = "AbortError";
+  const original = fakeImageClient.generate;
+  fakeImageClient.generate = async () => { throw abort; };
+  try {
+    const { call, budget } = makeHarness();
+    const res = await call({ prompt: "a red cube", model: "openai/gpt-image-2", size: "1024x1024" });
+    const text = res.content.map((c: any) => c.text).join("\n");
+    assert.equal(res.isError, true);
+    assert.match(text, /MAY have gone through/);
+    assert.match(text, /action:"report"/);
+    assert.doesNotMatch(text, /No payment was taken/);
+    assert.equal(budget.spent, 0.064, "the observed charge is booked, and the reservation is released on top");
+  } finally {
+    fakeImageClient.generate = original;
+  }
+});
+
+test("Base: an SDK API error (a response arrived) books nothing and is not a maybe", async () => {
+  const original = fakeImageClient.generate;
+  fakeImageClient.generate = async () => { throw new Error("API error 400: size not supported"); };
+  try {
+    const { call, budget } = makeHarness();
+    const res = await call({ prompt: "a red cube", model: "openai/gpt-image-2", size: "1024x1024" });
+    const text = res.content.map((c: any) => c.text).join("\n");
+    assert.equal(res.isError, true);
+    assert.doesNotMatch(text, /MAY have/);
+    assert.equal(budget.spent, 0);
+  } finally {
+    fakeImageClient.generate = original;
+  }
 });
 
 test("budget records the same amount that is reported to the user", async () => {
   const { call, budget } = makeHarness();
-  await call({ prompt: "a dog", model: "google/nano-banana" });
-  // The CHARGED price, not the $0.05 catalog base: 0.05 * 1.05 + $0.002, ceiled to
-  // micro-USDC exactly as the gateway does. Footer and ledger must agree on it —
-  // that is what this test is for.
-  assert.equal(budget.spent, 0.054501);
+  const res = await call({ prompt: "a dog", model: "google/nano-banana" });
+  // The CHARGED price, not the $0.05 catalog base and not the $0.054501
+  // reserve: 0.05 * 1.05 + the observed $0.001 fee, ceiled to micro-USDC
+  // exactly as the gateway does. Footer and ledger must agree on it — that is
+  // what this test is for.
+  assert.equal(budget.spent, 0.053501);
+  assert.equal(res.structuredContent.cost_usd, 0.053501);
 });
 
 // The large-size tier was a single >1024 rule for every model, which is wrong for
@@ -139,7 +194,7 @@ test("nano-banana-2 bills its flat 1024 price and is accepted for edits", async
   const { call } = makeHarness();
   const res = await call({ prompt: "a pear", model: "google/nano-banana-2" });
   const text = res.content.map((c: any) => c.text).join("\n");
-  assert.match(text, /Cost: \$0\.0965/); // 0.09 catalog x 1.05 + $0.002
+  assert.match(text, /Cost: \$0\.0955/); // 0.09 catalog x 1.05 + $0.001 observed (reserve is $0.0965)
   assert.equal(res.isError, undefined);
   // Edit support: the gateway's EDIT_SUPPORTED_MODELS includes nano-banana-2,
   // so the local gate must not reject it before the paid call.
diff --git a/test/image-materialize.test.ts b/test/image-materialize.test.ts
new file mode 100644
index 0000000..8c72d3d
--- /dev/null
+++ b/test/image-materialize.test.ts
@@ -0,0 +1,51 @@
+// Run with: npm test  (tsx --test)
+//
+// materializeImageUrl persists a data: URI the image2image routes ship verbatim
+// (google/nano-banana returns multi-megabyte base64) to a temp file and hands
+// back the path. The subtype it captures is UPSTREAM OUTPUT spliced into the
+// filename, which a round-4 finder read as a traversal: "the class admits `.`,
+// so `../` can escape tmpdir". It cannot — the capture is `[a-z0-9.+-]+`, which
+// admits neither `/` nor `\`, so the subtype is always the tail of ONE path
+// segment and path.join has nothing to normalise. Refuted, and pinned here so
+// that widening the class later (say, to accept `image/svg+xml;charset=…`)
+// cannot quietly reopen the question.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname } from "node:path";
+import { materializeImageUrl } from "../src/tools/image.js";
+
+const PNG_B64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M8AAAMBAQDJ/pLvAAAAAElFTkSuQmCC";
+const cleanup: string[] = [];
+process.on("exit", () => { for (const f of cleanup) rmSync(f, { force: true }); });
+
+test("a subtype carrying a path separator is not a data URI to this function — returned verbatim, nothing written", async () => {
+  for (const subtype of ["../../x", "png/../../x", "..\\..\\x", "png/../../../etc/passwd"]) {
+    const uri = `data:image/${subtype};base64,${PNG_B64}`;
+    assert.equal(await materializeImageUrl(uri), uri, subtype);
+  }
+});
+
+test("a separator-free subtype — dots included — lands as one segment inside tmpdir", async () => {
+  for (const subtype of [".", "..", "...", "png..", "a.b.c", "svg+xml", "PNG"]) {
+    const file = await materializeImageUrl(`data:image/${subtype};base64,${PNG_B64}`);
+    cleanup.push(file);
+    assert.equal(dirname(file), tmpdir(), `${subtype}: wrote to ${file}`);
+    assert.match(basename(file), /^blockrun-image-\d+-[0-9a-f]{8}\./, `${subtype}: ${file}`);
+    assert.ok(existsSync(file));
+  }
+});
+
+test("jpeg maps to .jpg; other subtypes keep their own lowercased extension", async () => {
+  for (const [subtype, ext] of [["jpeg", "jpg"], ["JPEG", "jpg"], ["png", "png"], ["WebP", "webp"]] as const) {
+    const file = await materializeImageUrl(`data:image/${subtype};base64,${PNG_B64}`);
+    cleanup.push(file);
+    assert.match(file, new RegExp(`\\.${ext}$`), `${subtype} -> ${file}`);
+  }
+});
+
+test("a non-data URL and an undecodable data URI pass through untouched", async () => {
+  assert.equal(await materializeImageUrl("https://blockrun.ai/media/x.png"), "https://blockrun.ai/media/x.png");
+  assert.equal(await materializeImageUrl("data:image/png,notbase64"), "data:image/png,notbase64");
+});
diff --git a/test/image-quality-default.test.ts b/test/image-quality-default.test.ts
new file mode 100644
index 0000000..7b6f691
--- /dev/null
+++ b/test/image-quality-default.test.ts
@@ -0,0 +1,152 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// blockrun_image generate was dead on the Base wallet rail for every model and
+// every prompt. The zod schema defaulted `quality` to "standard", the Base path
+// hands that to @blockrun/llm's ImageClient.generate, whose body builder is
+// `if (options?.quality) body.quality = options.quality` — "standard" is
+// truthy — and since gateway commit 397e5d1c (live 2026-09-11) blockrun.ai's
+// /v1/images/generations schema is `quality: z.enum(["low","medium","high",
+// "xhigh","max","auto"]).optional()` AND refuses ANY quality value for every
+// model this tool lists (only the two gpt-image-2.5 ids accept one). Unpaid
+// probe 2026-09-13 (no payment header — a 402 means the body is accepted):
+//
+//   {model:"openai/gpt-image-2", prompt, size, quality:"standard"} -> HTTP 400
+//       "Invalid option: expected one of low|medium|high|xhigh|max|auto"
+//   same body without quality                                      -> HTTP 402
+//   quality:"hd"                                                   -> HTTP 400 (same enum)
+//   quality:"high"                                                 -> HTTP 400
+//       "quality is not accepted for openai/gpt-image-2 ... Models that accept
+//        it: openai/gpt-image-2.5-flare, openai/gpt-image-2.5-sunburst"
+//
+// Nothing was charged — the 400 precedes the 402 — but the tool answered
+// "Image generation failed: API error: 400" with an altModels hint that fails
+// identically. Solana and the account rail only survived because
+// buildSolanaImageRequest drops "standard" on its own.
+//
+// The pin: there is NO quality parameter at all. Nothing the gateway accepts
+// for these models can be expressed by it, so the schema neither defaults it
+// nor declares it — a stale caller's value is stripped at the schema, the
+// handler never reads one, and no rail's body carries the key. These tests go
+// through the zod shape the way the MCP SDK does, because calling the handler
+// directly (as the other image suites do) skips the schema entirely and could
+// never have seen the original default.
+import { test, mock } from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { z } from "zod";
+import type { BudgetState } from "../src/types.js";
+
+// Wallet/Base rail pin, as in image-cost.test.ts: a temp HOME so no account
+// key on the developer's machine can switch the rail under the mocks.
+const home = fs.mkdtempSync(path.join(os.tmpdir(), "blockrun-image-quality-"));
+const realHome = process.env.HOME;
+const savedApiKey = process.env.BLOCKRUN_API_KEY;
+process.env.HOME = home;
+delete process.env.BLOCKRUN_API_KEY;
+process.on("exit", () => {
+  if (realHome === undefined) delete process.env.HOME; else process.env.HOME = realHome;
+  if (savedApiKey === undefined) delete process.env.BLOCKRUN_API_KEY; else process.env.BLOCKRUN_API_KEY = savedApiKey;
+  fs.rmSync(home, { recursive: true, force: true });
+});
+
+const generateCalls: Array<{ prompt: string; options: Record<string, unknown> }> = [];
+const fakeImageClient = {
+  generate: async (prompt: string, options: Record<string, unknown>) => {
+    generateCalls.push({ prompt, options });
+    return { data: [{ url: "https://blockrun.ai/media/fake.png" }] };
+  },
+  edit: async () => ({ data: [{ url: "https://blockrun.ai/media/fake-edit.png" }] }),
+};
+mock.module("../src/utils/wallet.js", {
+  namedExports: {
+    getApiBase: () => "https://blockrun.ai/api",
+    resolveGatewayUrl: (u: string) => u,
+    getChain: () => "base",
+    getImageClient: () => fakeImageClient,
+    getOrCreateWalletKey: () => "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d",
+    getWalletInfo: async () => ({ address: "0xTEST" }),
+    resolveSolanaKey: () => undefined,
+  },
+});
+let networkCalls = 0;
+mock.module("../src/utils/http.js", {
+  namedExports: {
+    fetchWithTimeout: async () => { networkCalls++; throw new Error("network call escaped the mocks"); },
+    isTimeoutError: () => false,
+  },
+});
+
+const { registerImageTool, buildSolanaImageRequest } = await import("../src/tools/image.js");
+
+function makeHarness() {
+  let handler: ((args: Record<string, unknown>) => Promise<any>) | undefined;
+  let shape: z.ZodRawShape | undefined;
+  const server = {
+    registerTool: (_name: string, cfg: { inputSchema: z.ZodRawShape }, h: any) => { handler = h; shape = cfg.inputSchema; },
+    server: { getClientCapabilities: () => ({}) },
+  } as any;
+  const budget: BudgetState = { limit: null, spent: 0, calls: 0, agents: new Map() };
+  registerImageTool(server, budget);
+  assert.ok(handler && shape, "blockrun_image did not register");
+  // What the MCP SDK hands the handler: the shape parsed with its defaults.
+  const parse = (args: Record<string, unknown>) => z.object(shape!).parse(args) as Record<string, unknown>;
+  return { call: (args: Record<string, unknown>) => handler!(args), parse, budget, shape: shape! };
+}
+
+test("the schema does not invent a quality: a call without one parses to quality undefined", () => {
+  const { parse } = makeHarness();
+  const parsed = parse({ prompt: "a cat" });
+  assert.equal(parsed.quality, undefined, `zod filled quality=${JSON.stringify(parsed.quality)} — the gateway 400s "standard"`);
+  // Defaults that DO exist still apply, so this is the right parse path.
+  assert.equal(parsed.action, "generate");
+  assert.equal(parsed.size, "1024x1024");
+});
+
+test("Base rail: the default generate call reaches the SDK with NO quality option (the SDK forwards any truthy value)", async () => {
+  const { call, parse } = makeHarness();
+  const res = await call(parse({ prompt: "a cat" }));
+  assert.equal(res.isError, undefined, res.content?.map((c: any) => c.text).join("\n"));
+  assert.equal(generateCalls.length, 1);
+  assert.equal(generateCalls[0].options.quality, undefined,
+    `the Base SDK path would send body.quality=${JSON.stringify(generateCalls[0].options.quality)}, which blockrun.ai rejects 400 for every listed model`);
+  assert.equal(generateCalls[0].options.model, "openai/gpt-image-2");
+  assert.equal(networkCalls, 0);
+});
+
+test("Solana and account rails: the body builder puts no quality on the wire for the default call", () => {
+  const { parse } = makeHarness();
+  const parsed = parse({ prompt: "a fox", model: "google/nano-banana" });
+  const { body } = buildSolanaImageRequest("generate", {
+    model: parsed.model as string,
+    prompt: parsed.prompt as string,
+    size: parsed.size as string,
+  });
+  assert.equal("quality" in body, false, `body carries quality=${JSON.stringify(body.quality)}`);
+  assert.deepEqual(body, { model: "google/nano-banana", prompt: "a fox", size: "1024x1024", n: 1 });
+});
+
+test("the schema declares no quality at all: a stale caller's value is stripped and never reaches the SDK", async () => {
+  // Every explicit value — "standard", "hd", "high" — is refused by the
+  // gateway before payment for every listed model, so keeping the parameter
+  // would only let a caller turn a paid call into a 400. It is gone from the
+  // schema (zod strips the unknown key) and from the handler.
+  const { call, parse, shape } = makeHarness();
+  assert.equal("quality" in shape, false, "blockrun_image still declares a quality parameter");
+  for (const quality of ["standard", "hd", "high"]) {
+    generateCalls.length = 0;
+    const parsed = parse({ prompt: "a cat", quality });
+    assert.equal("quality" in parsed, false, `zod let quality=${quality} through`);
+    const res = await call(parsed);
+    assert.equal(res.isError, undefined, res.content?.map((c: any) => c.text).join("\n"));
+    assert.equal(generateCalls.length, 1);
+    assert.equal("quality" in generateCalls[0].options, false, `the Base SDK path would send quality=${quality}`);
+  }
+  // And a handler called DIRECTLY with the key (no schema in front, as an
+  // in-process caller might) still forwards nothing.
+  generateCalls.length = 0;
+  const res = await call({ prompt: "a cat", quality: "hd" });
+  assert.equal(res.isError, undefined);
+  assert.equal("quality" in generateCalls[0].options, false, "the handler read a quality it does not declare");
+});
diff --git a/test/image.test.ts b/test/image.test.ts
index cace7dd..da6b9e7 100644
--- a/test/image.test.ts
+++ b/test/image.test.ts
@@ -55,25 +55,29 @@ test("toImageDataUri refuses to fetch a loopback/link-local URL (SSRF guard)", a
   await assert.rejects(() => toImageDataUri("http://10.0.0.5/internal.png"), /refusing to fetch/i);
 });
 
-test("buildSolanaImageRequest generate targets /v1/images/generations with quality omitted for standard", () => {
+test("buildSolanaImageRequest generate targets /v1/images/generations with exactly the accepted keys", () => {
   const { endpoint, body } = buildSolanaImageRequest("generate", {
     model: "openai/gpt-image-2",
     prompt: "a fox",
     size: "1024x1024",
-    quality: "standard",
   });
   assert.equal(endpoint, "/v1/images/generations");
   assert.deepEqual(body, { model: "openai/gpt-image-2", prompt: "a fox", size: "1024x1024", n: 1 });
 });
 
-test("buildSolanaImageRequest maps quality hd → high (the gateway's zod enum has no 'hd')", () => {
-  const { body } = buildSolanaImageRequest("generate", {
-    model: "openai/gpt-image-2",
-    prompt: "a fox",
-    size: "1024x1024",
-    quality: "hd",
-  });
-  assert.equal(body.quality, "high");
+test("buildSolanaImageRequest never puts a quality key on the wire, even when a stale caller passes one", () => {
+  // The gateway refuses every quality value for every listed model BEFORE the
+  // 402 (unpaid probes 2026-09-13: "standard", "hd", "high" all 400). The old
+  // hd→high mapping therefore only ever turned a paid call into a 400.
+  for (const quality of ["standard", "hd", "high"]) {
+    const { body } = buildSolanaImageRequest("generate", {
+      model: "openai/gpt-image-2",
+      prompt: "a fox",
+      size: "1024x1024",
+      ...({ quality } as Record<string, unknown>),
+    } as Parameters<typeof buildSolanaImageRequest>[1]);
+    assert.equal("quality" in body, false, `quality=${quality} leaked onto the wire`);
+  }
 });
 
 test("buildSolanaImageRequest edit targets /v1/images/image2image with image and optional mask", () => {
diff --git a/test/in-flight.test.ts b/test/in-flight.test.ts
new file mode 100644
index 0000000..4e33f46
--- /dev/null
+++ b/test/in-flight.test.ts
@@ -0,0 +1,181 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// utils/in-flight.ts: the per-call "was a request carrying the payment
+// outstanding when this threw?" tracker that replaced the hand-copied
+// paidRequestInFlight flags. The three properties pinned here are the three
+// the flags got wrong in 0.50.0: a rejection must leave the tracker ARMED
+// (the `.finally` shape cleared it before the catch could read it), a response
+// that arrived must settle it (a 402 that came back is an answer, not a
+// maybe), and an error that proves nothing left the machine must not book.
+import { test, mock } from "node:test";
+import assert from "node:assert/strict";
+import type { BudgetState } from "../src/types.js";
+
+let apiKeyMode = false;
+mock.module("../src/utils/auth.js", {
+  namedExports: { isApiKeyMode: () => apiKeyMode },
+});
+
+const { trackPaidRequest, sendPaid, settleGiveUp } = await import("../src/utils/in-flight.js");
+
+const abortError = () => { const e = new Error("This operation was aborted"); e.name = "AbortError"; return e; };
+const fetchFailed = (code: string) => { const e = new TypeError("fetch failed"); (e as Error & { cause: unknown }).cause = { code }; return e; };
+const budget = (): BudgetState => ({ limit: null, spent: 0, calls: 0, agents: new Map() });
+
+test("a rejection leaves the tracker armed — the catch can still see it", async () => {
+  const paid = trackPaidRequest();
+  await assert.rejects(sendPaid(paid, async () => { throw abortError(); }, 0.25));
+  assert.equal(paid.outstanding, true);
+  assert.equal(paid.quotedUsd, 0.25);
+  assert.equal(paid.mayHaveSettled(abortError()), true);
+});
+
+test("the `.finally` shape is exactly what must not come back: it clears before the catch runs", async () => {
+  // Documents the JS ordering the 0.50.0 flags tripped over, so nobody
+  // "simplifies" sendPaid back into it.
+  let flag = false;
+  try {
+    flag = true;
+    await Promise.reject(abortError()).finally(() => { flag = false; });
+  } catch {
+    assert.equal(flag, false, "finally ran before the catch — the flag is useless here");
+  }
+  const paid = trackPaidRequest();
+  try {
+    await sendPaid(paid, () => Promise.reject(abortError()));
+  } catch (err) {
+    assert.equal(paid.mayHaveSettled(err), true, "sendPaid keeps the tracker armed through the rejection");
+  }
+});
+
+test("a response that arrived settles the tracker, whatever the caller does with it next", async () => {
+  const paid = trackPaidRequest();
+  const resp = await sendPaid(paid, async () => ({ status: 402 }), 0.25);
+  assert.equal(resp.status, 402);
+  assert.equal(paid.outstanding, false);
+  // The caller now throws "Payment rejected" on that 402 — that is an answer,
+  // not a maybe, and must not be booked as a possible settlement.
+  assert.equal(paid.mayHaveSettled(new Error("Payment rejected. Check your wallet balance.")), false);
+});
+
+test("nothing is 'may have settled' before arm() — the unpaid 402 probe charges nothing", () => {
+  const paid = trackPaidRequest();
+  assert.equal(paid.mayHaveSettled(abortError()), false);
+  assert.equal(settleGiveUp(paid, abortError(), { budget: budget(), estimateUsd: 0.05, what: "X" }), null);
+});
+
+test("only a no-response error counts: an API error thrown after a response is not a maybe", () => {
+  const paid = trackPaidRequest();
+  paid.arm(0.1);
+  assert.equal(paid.mayHaveSettled(abortError()), true, "abort after send");
+  assert.equal(paid.mayHaveSettled(fetchFailed("ECONNRESET")), true, "socket dropped mid-flight");
+  assert.equal(paid.mayHaveSettled(fetchFailed("UND_ERR_HEADERS_TIMEOUT")), true, "undici header timeout");
+  assert.equal(paid.mayHaveSettled(new TypeError("fetch failed")), true, "undici transport failure with no cause");
+  assert.equal(paid.mayHaveSettled(fetchFailed("ECONNREFUSED")), false, "never connected");
+  assert.equal(paid.mayHaveSettled(fetchFailed("ENOTFOUND")), false, "DNS failed");
+  assert.equal(paid.mayHaveSettled(new Error("API error 500: {}")), false, "a status is an answer");
+  assert.equal(paid.mayHaveSettled(new Error("Budget exceeded. No charge was made.")), false);
+});
+
+test("settleGiveUp books the captured quote, else the reserve, and says where to look", () => {
+  const b = budget();
+  const paid = trackPaidRequest();
+  paid.arm(0.3);
+  const out = settleGiveUp(paid, abortError(), { budget: b, agentId: undefined, estimateUsd: 0.25, what: "Speech generation" });
+  assert.ok(out);
+  assert.equal(out.bookedUsd, 0.3, "the quote wins over the reserve");
+  assert.ok(Math.abs(b.spent - 0.3) < 1e-9);
+  assert.match(out.text, /^Speech generation got no answer/);
+  assert.match(out.text, /MAY have gone through/);
+  assert.match(out.text, /action:"report"/);
+  assert.match(out.text, /\$0\.3000 has been booked/);
+  assert.match(out.text, /Error: This operation was aborted$/);
+  assert.doesNotMatch(out.text, /No payment was taken/);
+
+  const b2 = budget();
+  const noQuote = trackPaidRequest();
+  noQuote.arm();
+  const out2 = settleGiveUp(noQuote, abortError(), { budget: b2, estimateUsd: 0.25, what: "X", note: "Job stays claimable." });
+  assert.ok(out2);
+  assert.equal(out2.bookedUsd, 0.25, "no quote: the reserve is booked");
+  assert.ok(Math.abs(b2.spent - 0.25) < 1e-9);
+  assert.match(out2.text, /Job stays claimable\.\nError:/);
+});
+
+test("on the account rail the sentence points at the account activity page, not a wallet", () => {
+  apiKeyMode = true;
+  try {
+    const paid = trackPaidRequest();
+    paid.arm();
+    const out = settleGiveUp(paid, abortError(), { budget: budget(), estimateUsd: 0.05, what: "Image generation" });
+    assert.ok(out);
+    assert.match(out.text, /carrying the account key/);
+    assert.match(out.text, /dashboard\/activity/);
+    assert.match(out.text, /action:"report"/);
+    assert.doesNotMatch(out.text, /wallet's recent transactions/);
+  } finally {
+    apiKeyMode = false;
+  }
+});
+
+test("a non-positive or unreadable quote is not captured — the reserve stays the fallback", () => {
+  const paid = trackPaidRequest();
+  paid.arm(null);
+  assert.equal(paid.quotedUsd, null);
+  paid.arm(0);
+  assert.equal(paid.quotedUsd, null);
+  paid.arm(NaN);
+  assert.equal(paid.quotedUsd, null);
+  const b = budget();
+  const out = settleGiveUp(paid, abortError(), { budget: b, estimateUsd: 0.012, what: "RealFace enroll" });
+  assert.equal(out?.bookedUsd, 0.012);
+  assert.ok(Math.abs(b.spent - 0.012) < 1e-9);
+});
+
+// Audit round 4: a helper wrapped in sendPaid can inspect the response and
+// THROW inside send(), so settle() is never reached although an answer
+// arrived — apiKeyPost's AccountApiError (a 4xx/5xx with its body text),
+// apiKeyAsyncPost's not_charged terminal failure, a Solana helper's
+// "API error N:". The tracker cannot know, so the verdict has to: an error
+// that carries a status, a typed job verdict, or the gateway's own uncharged
+// marker is an ANSWER, whatever its prose says. Before this, a not_charged
+// poll whose upstream text read "The operation was aborted due to timeout"
+// booked a whole render on image's account rail and said "MAY have gone
+// through" — the C13 shape, on the rail whose tools had just documented
+// why it must not happen.
+test("an error carrying a status is an answer, not a maybe — even when its body says 'timeout'", async () => {
+  const paid = trackPaidRequest();
+  const answered = Object.assign(new Error('API error 504: {"error":"Upstream timeout"}'), { statusCode: 504, name: "AccountApiError" });
+  await assert.rejects(sendPaid(paid, async () => { throw answered; }, 0.05));
+  assert.equal(paid.outstanding, true, "sendPaid itself cannot know a response arrived");
+  assert.equal(paid.mayHaveSettled(answered), false, "a statusCode proves the gateway answered");
+  const sdkShape = Object.assign(new Error("API error after payment: 502"), { statusCode: 502 });
+  assert.equal(paid.mayHaveSettled(sdkShape), false);
+  const anthropicShape = Object.assign(new Error("Request timed out"), { status: 408 });
+  assert.equal(paid.mayHaveSettled(anthropicShape), false);
+});
+
+test("the gateway's own not-charged verdict outranks a timeout in the upstream text", async () => {
+  const paid = trackPaidRequest();
+  const notCharged = new Error("Upstream generation failed: The operation was aborted due to timeout. No payment was taken.");
+  await assert.rejects(sendPaid(paid, async () => { throw notCharged; }, 0.05));
+  assert.equal(paid.mayHaveSettled(notCharged), false);
+  assert.equal(settleGiveUp(paid, notCharged, { budget: budget(), estimateUsd: 0.05, what: "Image generation" }), null);
+});
+
+test("a typed job verdict (JobFailedError / BilledJobError) is never a maybe", async () => {
+  const paid = trackPaidRequest();
+  for (const name of ["JobFailedError", "BilledJobError"]) {
+    const typed = Object.assign(new Error("Upstream generation failed: aborted due to timeout"), { name });
+    await assert.rejects(sendPaid(paid, async () => { throw typed; }, 0.05));
+    assert.equal(paid.mayHaveSettled(typed), false, name);
+  }
+});
+
+test("a bare abort while armed is still a maybe — the answered-error rule does not widen into 'never'", async () => {
+  const paid = trackPaidRequest();
+  await assert.rejects(sendPaid(paid, async () => { throw abortError(); }, 0.05));
+  assert.equal(paid.mayHaveSettled(abortError()), true);
+  assert.equal(paid.mayHaveSettled(fetchFailed("ECONNRESET")), true);
+  assert.equal(paid.mayHaveSettled(fetchFailed("ECONNREFUSED")), false);
+});
diff --git a/test/keychain-delete.test.ts b/test/keychain-delete.test.ts
new file mode 100644
index 0000000..e9dc83c
--- /dev/null
+++ b/test/keychain-delete.test.ts
@@ -0,0 +1,111 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// keychainDelete's contract, on both backends.
+//
+// It documents "true when the entry is gone, INCLUDING was never there", and
+// the macOS branch honoured that by accepting errSecItemNotFound. The Linux
+// branch accepted only exit 0, so `secret-tool clear` on a miss reported the
+// entry as still present — the one direction that misleads a caller, since it
+// says a key is in the keychain when it is not. LINUX_ITEM_NOT_FOUND was
+// already defined in the file and simply unused here.
+//
+// Nothing below spawns a real keychain helper: node:child_process is mocked,
+// so `security` and `secret-tool` are never invoked and the login keychain is
+// never touched.
+import { test, mock, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import realOs from "node:os";
+
+let platform = "darwin";
+let result: { status: number | null; stdout: string } = { status: 0, stdout: "" };
+let calls: Array<{ bin: string; args: string[] }> = [];
+
+mock.module("node:os", {
+  defaultExport: { ...realOs, platform: () => platform },
+});
+
+mock.module("node:child_process", {
+  namedExports: {
+    spawnSync: (bin: string, args: string[]) => {
+      calls.push({ bin, args });
+      return result;
+    },
+  },
+});
+
+const { keychainDelete, KEYCHAIN_SERVICE } = await import("../src/utils/keychain.js");
+
+beforeEach(() => {
+  calls = [];
+});
+
+test("macOS: a successful delete reports the entry gone", () => {
+  platform = "darwin";
+  result = { status: 0, stdout: "" };
+  assert.equal(keychainDelete("evm-wallet-key"), true);
+  assert.equal(calls[0].bin, "/usr/bin/security");
+  assert.deepEqual(calls[0].args, [
+    "delete-generic-password",
+    "-s",
+    KEYCHAIN_SERVICE,
+    "-a",
+    "evm-wallet-key",
+  ]);
+});
+
+test("macOS: 'was never there' (errSecItemNotFound) is also gone", () => {
+  platform = "darwin";
+  result = { status: 44, stdout: "" };
+  assert.equal(keychainDelete("evm-wallet-key"), true);
+});
+
+test("Linux: a successful clear reports the entry gone", () => {
+  platform = "linux";
+  result = { status: 0, stdout: "" };
+  assert.equal(keychainDelete("solana-wallet-key"), true);
+  assert.equal(calls[0].bin, "/usr/bin/secret-tool");
+  assert.deepEqual(calls[0].args, [
+    "clear",
+    "app",
+    KEYCHAIN_SERVICE,
+    "account",
+    "solana-wallet-key",
+  ]);
+});
+
+test("Linux: 'was never there' is gone too, matching macOS and the documented contract", () => {
+  platform = "linux";
+  result = { status: 1, stdout: "" };
+  assert.equal(
+    keychainDelete("solana-wallet-key"),
+    true,
+    "returning false here claims the key is still in the keychain when it is not",
+  );
+});
+
+test("a real failure stays false on both backends", () => {
+  platform = "darwin";
+  result = { status: 51, stdout: "" };
+  assert.equal(keychainDelete("evm-wallet-key"), false, "authorization denied is not a delete");
+
+  platform = "linux";
+  result = { status: 2, stdout: "" };
+  assert.equal(keychainDelete("solana-wallet-key"), false);
+});
+
+test("a timeout (status null) is never mistaken for a delete", () => {
+  platform = "darwin";
+  result = { status: null, stdout: "" };
+  assert.equal(keychainDelete("evm-wallet-key"), false);
+
+  platform = "linux";
+  result = { status: null, stdout: "" };
+  assert.equal(keychainDelete("solana-wallet-key"), false);
+});
+
+test("a platform with no keychain deletes nothing and says so", () => {
+  platform = "win32";
+  result = { status: 0, stdout: "" };
+  assert.equal(keychainDelete("evm-wallet-key"), false);
+  assert.equal(calls.length, 0, "no helper may be spawned on an unsupported platform");
+});
diff --git a/test/keychain-linux-exit1.test.ts b/test/keychain-linux-exit1.test.ts
new file mode 100644
index 0000000..ee2c72a
--- /dev/null
+++ b/test/keychain-linux-exit1.test.ts
@@ -0,0 +1,83 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// `secret-tool lookup` exits 1 for BOTH "no such item" and "an error
+// occurred" — libsecret's tool/secret-tool.c returns 1 from the lookup action
+// whether `value == NULL` or `error != NULL`; the difference is that the error
+// path g_printerr()s a message first. So on Linux, round 3's tri-state read
+// (found / absent / error) was macOS-only: a locked collection, a missing
+// D-Bus session ("Cannot autolaunch D-Bus without X11 $DISPLAY"), a dismissed
+// unlock prompt — every one read as ABSENT, and under BLOCKRUN_KEYCHAIN=strict
+// (session file retired) both provisioners then minted a fresh wallet over the
+// funded one in the keychain the process merely could not open.
+//
+// The tell is stderr: a miss prints nothing, a fault prints why. The status
+// alone cannot decide, and this file pins that the classifier no longer tries.
+import { test, mock, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import realFs from "node:fs";
+import realOs from "node:os";
+
+const SECRET_TOOL = "/usr/bin/secret-tool";
+let spawnResult: { status: number | null; stdout: string; stderr: string } = { status: 1, stdout: "", stderr: "" };
+
+const osMock = { ...realOs, platform: () => "linux" };
+mock.module("node:os", { defaultExport: osMock, namedExports: osMock });
+const fsMock = {
+  ...realFs,
+  accessSync: (p: string, mode?: number) => (p === SECRET_TOOL ? undefined : realFs.accessSync(p, mode)),
+};
+mock.module("node:fs", { defaultExport: fsMock, namedExports: fsMock });
+mock.module("node:child_process", {
+  namedExports: {
+    spawnSync: () => ({ ...spawnResult, signal: null, pid: 1, output: [] }),
+  },
+});
+
+const keychain = await import("../src/utils/keychain.js");
+
+beforeEach(() => {
+  keychain._resetKeychainWarnings();
+});
+
+test("exit 1 with nothing on stderr is a miss: absent", () => {
+  spawnResult = { status: 1, stdout: "", stderr: "" };
+  assert.deepEqual(keychain.keychainRead("evm-wallet-key"), { status: "absent" });
+  assert.equal(keychain.keychainLoad("evm-wallet-key"), null);
+});
+
+for (const [why, stderr] of [
+  ["no D-Bus session", "secret-tool: Cannot autolaunch D-Bus without X11 $DISPLAY\n"],
+  ["locked collection / dismissed prompt", "secret-tool: The unlock prompt was dismissed\n"],
+  ["service unavailable", "secret-tool: Error calling StartServiceByName for org.freedesktop.secrets: Timeout was reached\n"],
+] as const) {
+  test(`exit 1 with a message on stderr (${why}) is a FAULT: error, never absent`, () => {
+    spawnResult = { status: 1, stdout: "", stderr };
+    const read = keychain.keychainRead("evm-wallet-key");
+    assert.equal(read.status, "error", `${why}: ${JSON.stringify(read)}`);
+    assert.match((read as { detail: string }).detail, /secret-tool/);
+    assert.match((read as { detail: string }).detail, new RegExp(stderr.trim().slice(13, 30).replace(/[$()]/g, "\\$&")), "the detail carries the tool's own reason");
+  });
+}
+
+test("a timeout (status null, no ENOENT) is a fault on Linux too", () => {
+  spawnResult = { status: null, stdout: "", stderr: "" };
+  assert.equal(keychain.keychainRead("evm-wallet-key").status, "error");
+});
+
+test("keychainLoad warns on a fault and stays quiet on a miss", async () => {
+  const lines: string[] = [];
+  const original = console.error;
+  console.error = (...args: unknown[]) => lines.push(args.map(String).join(" "));
+  try {
+    spawnResult = { status: 1, stdout: "", stderr: "" };
+    assert.equal(keychain.keychainLoad("solana-wallet-key"), null);
+    assert.deepEqual(lines, [], "a miss is not worth a warning");
+    keychain._resetKeychainWarnings();
+    spawnResult = { status: 1, stdout: "", stderr: "secret-tool: Cannot autolaunch D-Bus without X11 $DISPLAY\n" };
+    assert.equal(keychain.keychainLoad("solana-wallet-key"), null);
+    assert.equal(lines.length, 1, "a fault is");
+    assert.match(lines[0], /keychain read failed/i);
+  } finally {
+    console.error = original;
+  }
+});
diff --git a/test/keychain-linux-no-secret-tool.test.ts b/test/keychain-linux-no-secret-tool.test.ts
new file mode 100644
index 0000000..33c8222
--- /dev/null
+++ b/test/keychain-linux-no-secret-tool.test.ts
@@ -0,0 +1,171 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// Linux without /usr/bin/secret-tool — Ubuntu and Debian desktops (libsecret-
+// tools is not installed by default), WSL, Docker, every cloud VM. The
+// keychain.ts header and the 0.41.0 CHANGELOG both promise that such a machine
+// "stays file-based". It did not: keychainRead() spawned the missing binary,
+// spawnSync reported it as {status: null, error: ENOENT} without throwing, and
+// the linux branch mapped that to {status: "error", detail: "secret-tool exit
+// timeout"}. Both provisioners treat "error" as "a funded wallet may be sitting
+// in a keychain we could not open — refuse to mint", so a fresh install could
+// never create a wallet on EITHER chain, and the refusal blamed
+// BLOCKRUN_KEYCHAIN=strict on a machine that had never set it.
+//
+// A keychain that does not exist cannot be holding a funded key. A missing
+// binary is "unavailable", never a fault.
+//
+// Nothing here spawns anything: node:child_process is mocked, and the
+// availability probe (fs.accessSync on the binary) is mocked so the result does
+// not depend on whether the developer's machine happens to have secret-tool.
+import { test, mock, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import realFs from "node:fs";
+import realOs from "node:os";
+import path from "node:path";
+
+const home = realFs.mkdtempSync(path.join(realOs.tmpdir(), "br-linux-nokc-"));
+const blockrunDir = path.join(home, ".blockrun");
+realFs.mkdirSync(blockrunDir, { recursive: true });
+const ENV_NAMES = ["HOME", "BLOCKRUN_HOME", "BLOCKRUN_KEYCHAIN", "BLOCKRUN_WALLET_KEY", "BASE_CHAIN_WALLET_KEY", "SOLANA_WALLET_KEY", "BLOCKRUN_API_KEY"] as const;
+const saved = Object.fromEntries(ENV_NAMES.map((k) => [k, process.env[k]]));
+process.env.HOME = home;
+for (const k of ENV_NAMES) if (k !== "HOME") delete process.env[k];
+
+const SECRET_TOOL = "/usr/bin/secret-tool";
+let binaryInstalled = false;
+let spawns: Array<{ bin: string; args: string[] }> = [];
+
+// Both the default and the named export surfaces: keychain.ts uses the default
+// import, the SDK and viem use named imports from "os"/"fs".
+const osMock = { ...realOs, platform: () => "linux" };
+mock.module("node:os", { defaultExport: osMock, namedExports: osMock });
+
+const fsMock = {
+  ...realFs,
+  accessSync: (p: string, mode?: number) => {
+    if (p === SECRET_TOOL && !binaryInstalled) {
+      const err = new Error(`ENOENT: no such file or directory, access '${p}'`) as NodeJS.ErrnoException;
+      err.code = "ENOENT";
+      throw err;
+    }
+    if (p === SECRET_TOOL) return undefined;
+    return realFs.accessSync(p, mode);
+  },
+};
+mock.module("node:fs", { defaultExport: fsMock, namedExports: fsMock });
+
+mock.module("node:child_process", {
+  namedExports: {
+    // What spawnSync really returns for a nonexistent absolute path: no throw,
+    // status null, and the ENOENT on `error`.
+    spawnSync: (bin: string, args: string[]) => {
+      spawns.push({ bin, args });
+      const error = new Error(`spawnSync ${bin} ENOENT`) as NodeJS.ErrnoException;
+      error.code = "ENOENT";
+      return { status: null, signal: null, stdout: "", stderr: "", error, pid: 0, output: [] };
+    },
+  },
+});
+
+const keychain = await import("../src/utils/keychain.js");
+const wallet = await import("../src/utils/wallet.js");
+
+process.on("exit", () => {
+  for (const [k, v] of Object.entries(saved)) {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+  realFs.rmSync(home, { recursive: true, force: true });
+});
+
+/** Capture stderr lines for the duration of `fn`. */
+async function captureStderr<T>(fn: () => T | Promise<T>): Promise<{ result: T; lines: string[] }> {
+  const lines: string[] = [];
+  const original = console.error;
+  console.error = (...args: unknown[]) => lines.push(args.map(String).join(" "));
+  try {
+    return { result: await fn(), lines };
+  } finally {
+    console.error = original;
+  }
+}
+
+beforeEach(() => {
+  for (const f of [".session", ".solana-session", "wallet.key", ".chain", ".chain-auto"]) {
+    realFs.rmSync(path.join(blockrunDir, f), { force: true });
+  }
+  delete process.env.BLOCKRUN_KEYCHAIN;
+  binaryInstalled = false;
+  spawns = [];
+  keychain._resetKeychainWarnings();
+  wallet.resetEvmWalletCache();
+  wallet.resetSolanaKeyCache();
+  wallet.resetKeychainProbeCache();
+});
+
+// --- keychain.ts: classification ------------------------------------------
+
+test("a missing secret-tool reads as ABSENT, not as a keychain error, and spawns nothing", async () => {
+  const { result, lines } = await captureStderr(() => keychain.keychainRead("evm-wallet-key"));
+
+  assert.deepEqual(result, { status: "absent" }, "no keychain means no key in it — never 'error'");
+  assert.deepEqual(spawns, [], "there is nothing to spawn");
+  assert.deepEqual(lines, [], "no 'OS keychain read failed' warning for a keychain that was never there");
+});
+
+test("keychainLoad on a missing secret-tool is a quiet null", async () => {
+  const { result, lines } = await captureStderr(() => keychain.keychainLoad("solana-wallet-key"));
+
+  assert.equal(result, null);
+  assert.deepEqual(lines, [], "getChain()'s probes printed two of these per process on every keychain-less Linux box");
+});
+
+test("ENOENT from the spawn itself (binary vanished after the availability check) is also absent", async () => {
+  binaryInstalled = true; // accessSync succeeds, spawnSync still reports ENOENT
+
+  const { result, lines } = await captureStderr(() => keychain.keychainRead("evm-wallet-key"));
+
+  assert.deepEqual(result, { status: "absent" });
+  assert.equal(spawns.length, 1, "the binary looked present, so the spawn was attempted");
+  assert.deepEqual(lines, []);
+  assert.equal(keychain.keychainLoad("evm-wallet-key"), null);
+});
+
+test("isKeychainAvailable is false without the binary and true with it", () => {
+  assert.equal(keychain.isKeychainAvailable(), false);
+  binaryInstalled = true;
+  assert.equal(keychain.isKeychainAvailable(), true);
+});
+
+// --- wallet.ts: a fresh install mints on both chains -----------------------
+
+test("fresh keychain-less Linux install: Solana (the default chain) provisions a wallet", async () => {
+  const { result: info, lines } = await captureStderr(() => wallet.ensureSolanaWallet());
+
+  assert.equal(info.isNew, true, "a fresh install must be allowed to mint");
+  assert.ok(realFs.existsSync(path.join(blockrunDir, ".solana-session")), "file storage is the fallback the header promises");
+  assert.ok(!lines.some((l) => /keychain read failed|strict/i.test(l)), `spurious keychain noise: ${JSON.stringify(lines)}`);
+});
+
+test("fresh keychain-less Linux install: Base provisions a wallet too", async () => {
+  const { result: key, lines } = await captureStderr(() => wallet.getOrCreateWalletKey());
+
+  assert.match(key, /^0x[0-9a-f]{64}$/);
+  assert.equal(realFs.readFileSync(path.join(blockrunDir, ".session"), "utf-8").trim(), key, "the key went to the file");
+  assert.ok(!lines.some((l) => /keychain read failed|strict/i.test(l)), `spurious keychain noise: ${JSON.stringify(lines)}`);
+});
+
+test("fresh keychain-less Linux install: ensureBothWallets (the blockrun_wallet status path) succeeds", async () => {
+  const both = await wallet.ensureBothWallets();
+  assert.equal(both.base.isNew, true);
+  assert.equal(both.solana.isNew, true);
+  assert.equal(wallet.getChain(), "solana", "and the fresh-install default still applies");
+});
+
+test("an existing file-based wallet keeps working, and is not mirrored anywhere", async () => {
+  const KEY = "0x" + "11".repeat(32);
+  realFs.writeFileSync(path.join(blockrunDir, ".session"), KEY, { mode: 0o600 });
+
+  assert.equal(wallet.getOrCreateWalletKey(), KEY);
+  assert.deepEqual(spawns.filter((s) => s.args[0] === "store"), [], "no keychain, no store attempt");
+});
diff --git a/test/keychain-precedence.test.ts b/test/keychain-precedence.test.ts
index f0d6457..89d777e 100644
--- a/test/keychain-precedence.test.ts
+++ b/test/keychain-precedence.test.ts
@@ -155,3 +155,209 @@ test("Solana: an existing session file outranks a stale keychain entry", async (
 
   readAnswer = { status: "found", value: KEYCHAIN_KEY };
 });
+
+// --- the empty-file gap (audit round 3) ---
+//
+// Both gates above asked `existsSync`. The loaders on the far side of them
+// (the SDK's resolveFromFiles / loadSolanaWallet) `.trim()` the file and treat
+// whitespace as no key. A zero-byte session file therefore read as PRESENT to
+// the gate and ABSENT to the loader: the keychain was skipped, a brand new
+// wallet was minted, and persistKey() then overwrote the keychain entry still
+// holding the funded key. saveWallet() is a plain non-atomic writeFileSync, so
+// an interrupted write or a full disk is enough to produce that file.
+
+test("EVM: an EMPTY session file does not shadow the funded key in the keychain", async () => {
+  const { resetEvmWalletCache } = await import("../src/utils/wallet.js");
+  resetEvmWalletCache();
+
+  const session = path.join(home, ".blockrun", ".session");
+  fs.writeFileSync(session, "   \n", { mode: 0o600 });
+  mode = "auto";
+  readAnswer = { status: "found", value: KEYCHAIN_KEY };
+
+  const resolved = getOrCreateWalletKey();
+
+  assert.equal(
+    resolved,
+    KEYCHAIN_KEY,
+    "a file holding no key must fall through to the keychain, not mint over it",
+  );
+  assert.equal(
+    fs.readFileSync(session, "utf-8").trim(),
+    "",
+    "nothing may be minted and saved while a funded key sits in the keychain",
+  );
+
+  fs.rmSync(session, { force: true });
+  resetEvmWalletCache();
+});
+
+test("Solana: an EMPTY session file does not shadow the funded key in the keychain", async () => {
+  const { createSolanaWallet, solanaPublicKey } = await import("@blockrun/llm");
+  const { ensureSolanaWallet, resetSolanaKeyCache } = await import("../src/utils/wallet.js");
+  const funded = await createSolanaWallet();
+
+  const session = path.join(home, ".blockrun", ".solana-session");
+  fs.writeFileSync(session, "\n", { mode: 0o600 });
+  resetSolanaKeyCache();
+  mode = "auto";
+  readAnswer = { status: "found", value: funded.privateKey };
+
+  const info = await ensureSolanaWallet();
+
+  assert.equal(info.isNew, false, "minting here orphans the key the keychain still holds");
+  assert.equal(info.privateKey, funded.privateKey);
+  assert.equal(info.address, await solanaPublicKey(funded.privateKey));
+
+  fs.rmSync(session, { force: true });
+  resetSolanaKeyCache();
+  readAnswer = { status: "found", value: KEYCHAIN_KEY };
+});
+
+// --- the refusal names the state it found, not a mode the user never set ---
+//
+// The empty-file gate above made the refusal reachable in AUTO mode: an
+// existing zero-byte .session consults the keychain, and if that read fails
+// the (correct) refusal said ".session no longer exists because
+// BLOCKRUN_KEYCHAIN=strict retired it" — neither half true. The user looks for
+// a file that is right there, never learns that restoring it from a backup is
+// the fix, and is told to unlock a keychain that may hold nothing.
+
+test("EVM: refusing over an EMPTY .session in auto mode says so, and does not blame strict mode", async () => {
+  const { resetEvmWalletCache } = await import("../src/utils/wallet.js");
+  resetEvmWalletCache();
+  const session = path.join(home, ".blockrun", ".session");
+  fs.writeFileSync(session, "", { mode: 0o600 });
+  mode = "auto";
+  readAnswer = { status: "error", detail: "security exit 36" };
+
+  assert.throws(
+    () => getOrCreateWalletKey(),
+    (err: Error) =>
+      /Refusing to create a new wallet/.test(err.message) &&
+      /\.session exists but holds no key/.test(err.message) &&
+      /backup/.test(err.message) &&
+      !/strict/.test(err.message),
+    "the diagnosis must match the facts: the file exists, it is empty, strict mode was never set",
+  );
+  assert.equal(fs.readFileSync(session, "utf-8"), "", "nothing minted, nothing written");
+
+  fs.rmSync(session, { force: true });
+  readAnswer = { status: "found", value: KEYCHAIN_KEY };
+  resetEvmWalletCache();
+});
+
+test("EVM: refusing with the file gone under strict still names strict mode as the reason it is gone", async () => {
+  const { resetEvmWalletCache } = await import("../src/utils/wallet.js");
+  resetEvmWalletCache();
+  fs.rmSync(path.join(home, ".blockrun", ".session"), { force: true });
+  mode = "strict";
+  readAnswer = { status: "error", detail: "security exit 36" };
+
+  assert.throws(
+    () => getOrCreateWalletKey(),
+    (err: Error) => /Refusing to create a new wallet/.test(err.message) && /BLOCKRUN_KEYCHAIN=strict/.test(err.message),
+  );
+
+  mode = "auto";
+  readAnswer = { status: "found", value: KEYCHAIN_KEY };
+  resetEvmWalletCache();
+});
+
+test("Solana: refusing over an EMPTY .solana-session in auto mode says so, and does not blame strict mode", async () => {
+  const { ensureSolanaWallet, resetSolanaKeyCache } = await import("../src/utils/wallet.js");
+  resetSolanaKeyCache();
+  const session = path.join(home, ".blockrun", ".solana-session");
+  fs.writeFileSync(session, "\n", { mode: 0o600 });
+  mode = "auto";
+  readAnswer = { status: "error", detail: "security exit 36" };
+
+  await assert.rejects(
+    ensureSolanaWallet(),
+    (err: Error) =>
+      /Refusing to create a new Solana wallet/.test(err.message) &&
+      /\.solana-session exists but holds no key/.test(err.message) &&
+      /backup/.test(err.message) &&
+      !/strict/.test(err.message),
+  );
+  assert.equal(fs.readFileSync(session, "utf-8"), "\n", "nothing minted, nothing written");
+
+  fs.rmSync(session, { force: true });
+  readAnswer = { status: "found", value: KEYCHAIN_KEY };
+  resetSolanaKeyCache();
+});
+
+test("a file that HOLDS a key still outranks the keychain (the empty-file fix did not invert precedence)", async () => {
+  const { resetEvmWalletCache } = await import("../src/utils/wallet.js");
+  resetEvmWalletCache();
+
+  const session = path.join(home, ".blockrun", ".session");
+  fs.writeFileSync(session, FILE_KEY + "\n", { mode: 0o600 });
+  mode = "auto";
+  readAnswer = { status: "found", value: KEYCHAIN_KEY };
+
+  assert.equal(getOrCreateWalletKey(), FILE_KEY, "rotation by replacing the file must keep working");
+
+  fs.rmSync(session, { force: true });
+  resetEvmWalletCache();
+});
+
+// --- audit round 4: the legacy file ranks BELOW the keychain ---------------
+//
+// evmKeyOnDisk() asks the SDK loader, and the loader reads ~/.blockrun/.session
+// THEN the legacy ~/.blockrun/wallet.key. Under strict mode the .session is
+// retired once its key is in the keychain — but wallet.key never is (persistKey
+// is only ever handed the .session path), so a stale legacy file from an older
+// install outranked the keychain the moment .session was gone, and its key was
+// stored over the funded one with -U. "The keychain becomes authoritative
+// exactly when the file is gone" was false on that branch. The .session is the
+// rotation seam and keeps outranking the keychain; the legacy file is a
+// fallback for a machine with no keychain entry, nothing more.
+test("EVM: a legacy wallet.key does NOT outrank the keychain once .session is retired (strict)", async () => {
+  const { resetEvmWalletCache } = await import("../src/utils/wallet.js");
+  resetEvmWalletCache();
+  const dir = path.join(home, ".blockrun");
+  fs.rmSync(path.join(dir, ".session"), { force: true });
+  const LEGACY_KEY = "0x" + "33".repeat(32);
+  fs.writeFileSync(path.join(dir, "wallet.key"), LEGACY_KEY, { mode: 0o600 });
+  mode = "strict";
+  readAnswer = { status: "found", value: KEYCHAIN_KEY };
+
+  assert.equal(getOrCreateWalletKey(), KEYCHAIN_KEY, "the funded keychain wallet wins over a stale legacy file");
+
+  fs.rmSync(path.join(dir, "wallet.key"), { force: true });
+  mode = "auto";
+  resetEvmWalletCache();
+});
+
+test("EVM: the legacy wallet.key is still honoured when the keychain has nothing", async () => {
+  const { resetEvmWalletCache } = await import("../src/utils/wallet.js");
+  resetEvmWalletCache();
+  const dir = path.join(home, ".blockrun");
+  fs.rmSync(path.join(dir, ".session"), { force: true });
+  const LEGACY_KEY = "0x" + "33".repeat(32);
+  fs.writeFileSync(path.join(dir, "wallet.key"), LEGACY_KEY, { mode: 0o600 });
+  mode = "auto";
+  readAnswer = { status: "absent" };
+
+  assert.equal(getOrCreateWalletKey(), LEGACY_KEY, "no keychain entry: the legacy file is the wallet, not a reason to mint");
+
+  fs.rmSync(path.join(dir, "wallet.key"), { force: true });
+  readAnswer = { status: "found", value: KEYCHAIN_KEY };
+  resetEvmWalletCache();
+});
+
+test("EVM: .session still outranks the keychain in strict mode (rotation by file)", async () => {
+  const { resetEvmWalletCache } = await import("../src/utils/wallet.js");
+  resetEvmWalletCache();
+  const session = path.join(home, ".blockrun", ".session");
+  fs.writeFileSync(session, FILE_KEY, { mode: 0o600 });
+  mode = "strict";
+  readAnswer = { status: "found", value: KEYCHAIN_KEY };
+
+  assert.equal(getOrCreateWalletKey(), FILE_KEY);
+
+  fs.rmSync(session, { force: true });
+  mode = "auto";
+  resetEvmWalletCache();
+});
diff --git a/test/keychain.test.ts b/test/keychain.test.ts
index bb8d2c4..e55c721 100644
--- a/test/keychain.test.ts
+++ b/test/keychain.test.ts
@@ -175,7 +175,65 @@ test("a failed store never reaches the delete branch", () => {
   persistKey("evm", KEY, file, ops);
 
   assert.ok(fs.existsSync(file));
-  assert.equal(calls.filter((c) => c.startsWith("load:")).length, 0);
+  // One load is the pre-store "am I replacing a different key?" check; the
+  // strict READ-BACK (the second load) must never run after a failed store.
+  assert.equal(calls.filter((c) => c.startsWith("load:")).length, 1);
+});
+
+// The read-back proved the KEYCHAIN holds `key`. It said nothing about the
+// FILE, which was deleted on `existsSync` alone. An env override (a different
+// key from BLOCKRUN_WALLET_KEY) reached this branch and the file holding the
+// funded wallet went with it. The caller no longer persists env keys, but the
+// last line of defence has to hold on its own.
+test("strict mode never deletes a plaintext file that holds a DIFFERENT key than the one verified", () => {
+  process.env.BLOCKRUN_KEYCHAIN = "strict";
+  const file = seedKeyFile("strict-other-key.key"); // holds KEY
+  const OTHER = "0x" + "ef".repeat(32);
+  const { ops, items } = fakeOps();
+
+  persistKey("evm", OTHER, file, ops);
+
+  assert.equal(items.get("evm"), OTHER, "the store itself is not the guard");
+  assert.ok(fs.existsSync(file), "a file holding a key we did not verify must never be removed");
+  assert.equal(fs.readFileSync(file, "utf-8"), KEY);
+});
+
+test("strict mode still retires a file whose key matches modulo whitespace and the 0x prefix", () => {
+  // The SDK loader trims and 0x-normalises the file, so these are the same key
+  // on disk as far as every reader is concerned; keeping them would leave the
+  // plaintext copy strict mode exists to remove.
+  process.env.BLOCKRUN_KEYCHAIN = "strict";
+  for (const onDisk of [`${KEY}\n`, `  ${KEY}  `, KEY.slice(2), `${KEY.slice(2)}\n`]) {
+    const file = path.join(tmp, `strict-normalised-${Math.random().toString(36).slice(2)}.key`);
+    fs.writeFileSync(file, onDisk, { mode: 0o600 });
+    const { ops } = fakeOps();
+
+    persistKey("evm", KEY, file, ops);
+
+    assert.equal(fs.existsSync(file), false, `must retire ${JSON.stringify(onDisk)}`);
+  }
+});
+
+test("strict mode retires an EMPTY placeholder file — it holds nothing to lose", () => {
+  process.env.BLOCKRUN_KEYCHAIN = "strict";
+  const file = path.join(tmp, "strict-empty.key");
+  fs.writeFileSync(file, "  \n", { mode: 0o600 });
+  const { ops } = fakeOps();
+
+  persistKey("evm", KEY, file, ops);
+
+  assert.equal(fs.existsSync(file), false);
+});
+
+test("strict mode keeps a plaintext file it cannot READ — unverifiable is not verified", () => {
+  process.env.BLOCKRUN_KEYCHAIN = "strict";
+  const dir = path.join(tmp, "unreadable.key"); // a directory: readFileSync throws EISDIR
+  fs.mkdirSync(dir);
+  const { ops } = fakeOps();
+
+  persistKey("evm", KEY, dir, ops);
+
+  assert.ok(fs.existsSync(dir), "must not remove what it could not compare");
 });
 
 test("strict mode with no plaintext path just stores", () => {
@@ -212,3 +270,45 @@ test("the escape helper still covers the characters it CAN quote", () => {
   assert.equal(escapeForSecurityInteractive('a"b'), 'a\\"b');
   assert.equal(escapeForSecurityInteractive("a\\b"), "a\\\\b");
 });
+
+// Audit round 4: replacing a DIFFERENT key in the keychain is the destructive
+// step behind three findings (a second launch on a mis-read Linux keychain, a
+// lost first-run race, a stale legacy file). The file-is-truth design means
+// the mirror does get rewritten on a deliberate rotation, so the store is not
+// refused — but it is never silent: the previous key's address is named on
+// stderr, so a rotation the user did not intend is visible the run it happens.
+test("replacing a different key in the keychain is announced, with the address being replaced", async () => {
+  const OTHER = "0x" + "5e".repeat(32);
+  const file = seedKeyFile("rotate.key");
+  const { ops, items } = fakeOps();
+  items.set("evm", OTHER);
+  const lines: string[] = [];
+  const original = console.error;
+  console.error = (...args: unknown[]) => lines.push(args.map(String).join(" "));
+  try {
+    persistKey("evm", KEY, file, ops);
+  } finally {
+    console.error = original;
+  }
+  assert.equal(items.get("evm"), KEY, "the file's key is the wallet; the mirror follows it");
+  assert.equal(lines.length, 1);
+  assert.match(lines[0], /replac/i);
+  assert.match(lines[0], /0x[0-9a-fA-F]{40}/, "names the address whose key is being replaced");
+  assert.doesNotMatch(lines[0], new RegExp(OTHER), "never prints the key itself");
+});
+
+test("mirroring the same key, or a first key, says nothing", () => {
+  const file = seedKeyFile("same.key");
+  const { ops, items } = fakeOps();
+  const lines: string[] = [];
+  const original = console.error;
+  console.error = (...args: unknown[]) => lines.push(args.map(String).join(" "));
+  try {
+    persistKey("evm", KEY, file, ops);
+    persistKey("evm", KEY, file, ops);
+  } finally {
+    console.error = original;
+  }
+  assert.equal(items.get("evm"), KEY);
+  assert.deepEqual(lines, []);
+});
diff --git a/test/markets-validation.test.ts b/test/markets-validation.test.ts
index 5a2a7f3..1f483ed 100644
--- a/test/markets-validation.test.ts
+++ b/test/markets-validation.test.ts
@@ -3,10 +3,78 @@ import assert from "node:assert/strict";
 import { describeDegradedSportsFailure, isDegradedSportsPath, validateMarketRequest } from "../src/utils/markets-validation.js";
 
 test("markets/listings is retired upstream and blocked before payment", () => {
-  // Verified live 2026-07-29: settles payment, THEN returns 410 Gone. The
-  // gateway still registers and prices it, but the gateway only proxies —
-  // registry presence is not evidence that a route still serves.
-  assert.match(validateMarketRequest("markets/listings", { venue: "polymarket" }, undefined) ?? "", /410 Gone/);
+  // It settled-then-410'd in July 2026; since 2026-08-04 the registry no
+  // longer routes it and it 404s BEFORE payment ("Unknown Predexon endpoint",
+  // re-probed unauthenticated 2026-09-13). The block stays — it saves the
+  // round-trip and carries the steer — but it must not claim a charge the
+  // gateway cannot make.
+  const msg = validateMarketRequest("markets/listings", { venue: "polymarket" }, undefined) ?? "";
+  assert.match(msg, /404/);
+  assert.match(msg, /before payment/i);
+  assert.match(msg, /markets\/search/);
+  assert.doesNotMatch(msg, /410|after settling/i, "the pm route settles only on an upstream 2xx");
+});
+
+// ── Money claims the gateway cannot make ──
+//
+// The pm route returns on any upstream !ok BEFORE settlePaymentWithRetry, and
+// its 4xx bodies say "(payment NOT charged)". So no rule here is guarding a
+// PAID 4xx; it is saving an unpaid round-trip and a confusing error. Wording
+// that says otherwise teaches the next maintainer that relaxing a rule risks
+// money, and gets a valid call blocked "to be safe".
+test("no validation message claims a 4xx that settles", () => {
+  const messages = [
+    validateMarketRequest("markets/listings", {}, undefined),
+    validateMarketRequest("polymarket/candlesticks/token/123", { interval: "1h" }, undefined),
+    validateMarketRequest("polymarket/orderbooks", {}, undefined),
+    validateMarketRequest("polymarket/market/0xabc/smart-money", {}, undefined),
+    validateMarketRequest("polymarket/markets", { active: "true" }, undefined),
+  ];
+  for (const m of messages) {
+    assert.ok(m, "precondition: every one of these is a rule hit");
+    assert.doesNotMatch(m, /paid 4\d\d|after settling|settles? (a |the )?payment/i, m);
+    assert.match(m, /No payment was made/, m);
+  }
+});
+
+// ── A query string in `path` bypassed every rule and false-blocked valid calls ──
+//
+// validateMarketRequest normalised the path (stripping `?…`) so the rule
+// MATCHED on the slug, but read the query from `params` alone. The gateway
+// forwards request.nextUrl.searchParams to Predexon, which returns 200 +
+// UNFILTERED data on an unknown param name (it never 400s), so:
+//   (a) "polymarket/markets?active=true" passed validation, paid, and came
+//       back unfiltered — the exact outcome the Gamma-param rule exists for;
+//   (b) "polymarket/orderbooks?token_id=1&start_time=1&end_time=2" was refused
+//       as "missing" although the request was complete;
+//   (c) on the account rail path-query + params concatenated into
+//       "…?limit=5?status=open", so `limit` became "5?status=open".
+// The tool's own contract is "Pass query params via 'params'", so a `?` or `#`
+// in the path is refused up front with that instruction. Pre-payment, every
+// rail, no exceptions — the first rule that reads params must never see one.
+test("a query string or fragment in `path` is refused with the params instruction, before any param rule", () => {
+  for (const path of [
+    "polymarket/markets?active=true&limit=5",
+    "polymarket/orderbooks?token_id=123&start_time=1700000000000&end_time=1700003600000",
+    "polymarket/market/0xabc/smart-money?min_trades=100",
+    "polymarket/markets/keyset?pagination_key=abc",
+    "polymarket/wallets/profiles?addresses=0xabc",
+    "markets/search?q=NBA",
+    "kalshi/markets#frag",
+    "polymarket/events?",
+  ]) {
+    const msg = validateMarketRequest(path, undefined, undefined) ?? "";
+    assert.match(msg, /params/, `${JSON.stringify(path)}: ${msg}`);
+    assert.match(msg, /No payment was made/, msg);
+    // Not the misleading "missing token_id" / "needs a criterion" — the
+    // caller DID supply them, in the wrong place.
+    assert.doesNotMatch(msg, /requires params\.token_id|smart-wallet criterion|Gamma-only/, msg);
+  }
+  // The same path with the query moved into params is the working call.
+  assert.equal(validateMarketRequest("polymarket/orderbooks", { token_id: "123", start_time: "1700000000000", end_time: "1700003600000" }, undefined), null);
+  assert.equal(validateMarketRequest("polymarket/market/0xabc/smart-money", { min_trades: "100" }, undefined), null);
+  // A retired route is still reported as retired first — the more specific steer.
+  assert.match(validateMarketRequest("markets/listings?venue=polymarket", {}, undefined) ?? "", /404/);
 });
 
 test("Gamma-only market discovery params are rejected before payment", () => {
@@ -95,17 +163,20 @@ test("a decorated path cannot step around a rule", () => {
     "markets/listings#x",
     "markets/listings\t",
     "/markets/listings/",
+    "markets/listings?\n",
   ]) {
     assert.match(
       validateMarketRequest(path, {}, undefined) ?? "",
-      /410 Gone/,
+      /404/,
       `${JSON.stringify(path)} must not bypass the retired-route block`,
     );
   }
 
+  // A query in the path is refused outright (see the `?`/`#` test above), so
+  // it cannot reach a param rule with an empty `query` either.
   assert.match(
     validateMarketRequest("polymarket/market/0xabc/smart-money?window=7d", {}, undefined) ?? "",
-    /smart-wallet criterion/,
+    /params/,
   );
   assert.match(
     validateMarketRequest("POLYMARKET/ORDERBOOKS", {}, undefined) ?? "",
diff --git a/test/modal-cost.test.ts b/test/modal-cost.test.ts
index 30bae4d..a4e054a 100644
--- a/test/modal-cost.test.ts
+++ b/test/modal-cost.test.ts
@@ -52,7 +52,10 @@ test("estimateModalCost never reserves the flat rate for an expensive sandbox",
   assert.ok(expensive > cheap * 1000, `24h H100 ($${expensive}) must dwarf a flat create ($${cheap})`);
 });
 
-test("estimateModalCost falls back to the CPU rate for an unknown gpu, like the gateway", () => {
+// The gateway does NOT price an unknown gpu — it 400s it before payment, and the
+// handler refuses it before the reserve (unsupportedModalGpu, see
+// modal-gpu-trim.test.ts). The estimator merely has to stay total and finite.
+test("estimateModalCost falls back to the CPU rate for an unknown gpu (the handler refuses it first)", () => {
   assert.equal(estimateModalCost("sandbox/create", { timeout: 300, gpu: "NOPE" }), 0.012);
   assert.equal(estimateModalCost("sandbox/create", { timeout: 3600, gpu: "NOPE" }), 0.102001);
 });
diff --git a/test/modal-gpu-trim.test.ts b/test/modal-gpu-trim.test.ts
new file mode 100644
index 0000000..13c6244
--- /dev/null
+++ b/test/modal-gpu-trim.test.ts
@@ -0,0 +1,183 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// modal sandbox/create is priced off the BODY, and the gateway's
+// CreateRequestSchema runs `gpu: z.string().trim()` BEFORE both its allow-list
+// check and getModalCreatePricing. So `" H100 "`, `"H100\n"`, an NBSP-padded
+// `"H100"` all pass upstream validation and are billed at the H100 rate —
+// while estimateModalCost looked the raw string up in a Map, missed, and fell
+// to the CPU rate. Unpaid 402 probe 2026-09-13 (no payment header, no money):
+//
+//   { timeout: 3600, gpu: " H100 " }  -> amount 8001000  ($8.001)   reserved $0.102
+//   { timeout: 3600, gpu: "H100\n" }  -> amount 8001000  ($8.001)   reserved $0.102
+//   { timeout: 3600, gpu: "h100" }    -> HTTP 400 "Unsupported GPU type: h100"
+//   { timeout: 3600, gpu: "NOPE" }    -> HTTP 400
+//
+// With timeout 86400 that is $2.402 reserved against a $192.002 non-refundable
+// charge: past any budget cap, past the confirm dialog (which quoted $2.40),
+// and — on the Base rail, where the SDK owns the 402 and reports no settled
+// figure — a ledger that booked $2.40 of a $192 spend.
+//
+// The gateway is case-SENSITIVE (lowercase 400s before payment) and refuses
+// every gpu string outside its five tiers, so the only values that diverge are
+// whitespace-padded valid names. Two properties are pinned here on both rails
+// that can reach Modal (Solana is refused up front by baseOnlyMessage):
+//
+//   1. the reserve for a padded gpu equals the reserve for the bare one;
+//   2. the body that leaves this process carries the TRIMMED gpu, so what was
+//      reserved is what is sent — no second normalisation on the far side;
+//   3. a gpu the gateway would 400 is refused here, before the reserve, so a
+//      hallucinated tier never costs a paid round-trip and the message names
+//      the five that exist.
+import { test, mock, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import type { BudgetState } from "../src/types.js";
+
+let apiKeyMode = false;
+const walletBodies: unknown[] = [];
+const stubClient = {
+  getWithPaymentRaw: async () => { throw new Error("modal never GETs"); },
+  requestWithPaymentRaw: async (_endpoint: string, body: unknown) => { walletBodies.push(body); return { sandbox_id: "sb-1" }; },
+};
+mock.module("../src/utils/wallet.js", {
+  namedExports: {
+    getApiBase: () => "https://blockrun.ai/api",
+    resolveGatewayUrl: (u: string) => u,
+    getChain: () => "base",
+    getClient: () => stubClient,
+    buildClient: () => stubClient,
+    buildClientWithTimeout: () => stubClient,
+    baseOnlyMessage: () => null,
+    getOrCreateWalletKey: () => { throw new Error("modal tests must not touch a wallet key"); },
+    getWalletInfo: async () => ({ address: "0xTEST" }),
+  },
+});
+mock.module("../src/utils/auth.js", {
+  namedExports: {
+    isApiKeyMode: () => apiKeyMode,
+    getApiKey: () => (apiKeyMode ? "br_test_key" : undefined),
+    apiAuthHeaders: () => ({ Authorization: "Bearer br_test_key" }),
+    getApiKeyBase: () => "https://api.blockrun.ai",
+    PORTAL_CREDITS_URL: "https://user.blockrun.ai/dashboard/credits",
+  },
+});
+const accountBodies: unknown[] = [];
+mock.module("../src/utils/http.js", {
+  namedExports: {
+    fetchWithTimeout: async (_url: string, init: { body?: string }) => {
+      accountBodies.push(JSON.parse(init.body ?? "{}"));
+      return new Response(JSON.stringify({ sandbox_id: "sb-1" }), {
+        status: 200,
+        headers: { "content-type": "application/json", "x-blockrun-cost-usd": "192.000000" },
+      });
+    },
+    isTimeoutError: () => false,
+  },
+});
+
+const { registerModalTool, estimateModalCost } = await import("../src/tools/modal.js");
+
+type Handler = (args: Record<string, unknown>) => Promise<{ content: Array<{ type: string; text?: string }>; isError?: boolean }>;
+function harness(limit: number | null = null) {
+  let handler: Handler | undefined;
+  const server = {
+    registerTool: (_n: string, _c: unknown, h: Handler) => { handler = h; },
+    server: { getClientCapabilities: () => ({}) },
+  };
+  const budget: BudgetState = { limit, spent: 0, calls: 0, agents: new Map() };
+  registerModalTool(server as never, budget);
+  assert.ok(handler, "blockrun_modal did not register a handler");
+  return { call: (args: Record<string, unknown>) => handler!(args), budget };
+}
+
+beforeEach(() => { apiKeyMode = false; walletBodies.length = 0; accountBodies.length = 0; });
+
+const PADDED = [" H100", "H100 ", " H100 ", "H100\n", "\tH100", " H100", "H100\r\n"];
+
+test("estimateModalCost prices a whitespace-padded gpu exactly like the bare tier (the gateway trims)", () => {
+  // The bare figures are the gateway's own quotes (see modal-cost.test.ts):
+  // 24h H100 $192.002, 1h H100 $8.001 charged / $8.002 reserved, flat H100 $0.402.
+  assert.equal(estimateModalCost("sandbox/create", { timeout: 86400, gpu: "H100" }), 192.002);
+  for (const timeout of [86400, 3600, 300]) {
+    const bare = estimateModalCost("sandbox/create", { timeout, gpu: "H100" });
+    assert.ok(bare >= (timeout > 300 ? 8 * (timeout / 3600) : 0.4), `precondition: bare H100 at ${timeout}s reserves the H100 rate`);
+    for (const gpu of PADDED) {
+      assert.equal(estimateModalCost("sandbox/create", { timeout, gpu }), bare, `${JSON.stringify(gpu)} at ${timeout}s`);
+    }
+  }
+  assert.equal(estimateModalCost("sandbox/create", { timeout: 86400, gpu: " A100 " }), estimateModalCost("sandbox/create", { timeout: 86400, gpu: "A100" }));
+});
+
+// A $5 cap admitted " H100" for 24h at the $2.402 CPU reserve. It must now be
+// refused at the gate exactly like the bare "H100" is.
+test("a $5 cap refuses a padded 24h H100 create the way it refuses the bare one (Base rail)", async () => {
+  const { call, budget } = harness(5);
+  const bare = await call({ path: "sandbox/create", body: { gpu: "H100", timeout: 86400 } });
+  assert.equal(bare.isError, true, "precondition: bare H100 is over a $5 cap");
+  for (const gpu of PADDED) {
+    const res = await call({ path: "sandbox/create", body: { gpu, timeout: 86400 } });
+    const text = res.content.map((p) => p.text ?? "").join("\n");
+    assert.equal(res.isError, true, `${JSON.stringify(gpu)} slipped past the $5 cap: ${text}`);
+    assert.match(text, /budget|limit/i, text);
+  }
+  assert.equal(walletBodies.length, 0, "nothing may reach the client under a refused reserve");
+  assert.equal(budget.spent, 0);
+});
+
+test("the body that leaves this process carries the TRIMMED gpu on the Base rail, and the ledger books the H100 figure", async () => {
+  const { call, budget } = harness();
+  const res = await call({ path: "sandbox/create", body: { gpu: " H100 ", timeout: 86400, image: "python:3.11" } });
+  assert.notEqual(res.isError, true, res.content.map((p) => p.text).join());
+  assert.equal(walletBodies.length, 1);
+  assert.deepEqual(walletBodies[0], { gpu: "H100", timeout: 86400, image: "python:3.11" });
+  // Wallet rail reports no settled figure, so the ledger books the reserve's
+  // ledgerFallback — of the H100 price, not the CPU one. 192.002 - 0.002 + 0.001.
+  assert.ok(budget.spent > 190, `ledger booked $${budget.spent}, not the H100 figure`);
+});
+
+test("the same on the account rail: trimmed body, and the reserve gate sees the H100 price", async () => {
+  apiKeyMode = true;
+  const capped = harness(5);
+  const refused = await capped.call({ path: "sandbox/create", body: { gpu: "H100\n", timeout: 86400 } });
+  assert.equal(refused.isError, true, "account rail: padded H100 must not clear a $5 cap");
+  assert.equal(accountBodies.length, 0);
+
+  const { call, budget } = harness();
+  const res = await call({ path: "sandbox/create", body: { gpu: " H100", timeout: 86400 } });
+  assert.notEqual(res.isError, true, res.content.map((p) => p.text).join());
+  assert.equal(accountBodies.length, 1);
+  assert.deepEqual(accountBodies[0], { gpu: "H100", timeout: 86400 });
+  assert.equal(walletBodies.length, 0, "an account call must not touch the wallet client");
+  assert.equal(budget.spent, 192, "account rail books the settled x-blockrun-cost-usd");
+});
+
+// The gateway 400s every gpu outside its five tiers BEFORE payment — including
+// lowercase — so refusing here loses nothing and saves the round-trip. The
+// message has to name the tiers: "Unsupported GPU type" alone sends the model
+// guessing again.
+test("a gpu the gateway would reject is refused before the reserve, on both rails, naming the five tiers", async () => {
+  for (const mode of [false, true]) {
+    apiKeyMode = mode;
+    const { call, budget } = harness();
+    for (const gpu of ["h100", "NOPE", "", "  ", "H-100", "toString"]) {
+      const res = await call({ path: "sandbox/create", body: { gpu, timeout: 3600 } });
+      const text = res.content.map((p) => p.text ?? "").join("\n");
+      assert.equal(res.isError, true, `${JSON.stringify(gpu)} (apiKey=${mode}) was not refused: ${text}`);
+      assert.match(text, /T4, L4, A10G, A100, H100/, text);
+      assert.match(text, /No payment was made/i, text);
+    }
+    assert.equal(walletBodies.length, 0);
+    assert.equal(accountBodies.length, 0);
+    assert.equal(budget.spent, 0);
+    assert.equal(budget.calls, 0);
+  }
+});
+
+test("a create with no gpu, or a non-create op, is untouched", async () => {
+  const { call } = harness();
+  const r1 = await call({ path: "sandbox/create", body: { timeout: 300 } });
+  assert.notEqual(r1.isError, true);
+  assert.deepEqual(walletBodies[0], { timeout: 300 });
+  const r2 = await call({ path: "sandbox/exec", body: { sandbox_id: "sb-1", command: ["echo"], gpu: "whatever" } });
+  assert.notEqual(r2.isError, true, "gpu is not a create field; exec must not be validated on it");
+  assert.deepEqual(walletBodies[1], { sandbox_id: "sb-1", command: ["echo"], gpu: "whatever" });
+});
diff --git a/test/music-cost.test.ts b/test/music-cost.test.ts
index b049169..94d8e87 100644
--- a/test/music-cost.test.ts
+++ b/test/music-cost.test.ts
@@ -223,7 +223,7 @@ test("a paid poll still in flight at the deadline MAY have settled: say so, book
   const res = await call({ prompt: "lofi beat" });
   const t = text(res);
   assert.equal(res.isError, true, t);
-  assert.match(t, /MAY have settled/);
+  assert.match(t, /MAY have gone through/);
   assert.match(t, /blockrun_wallet action:"report"/);
   assert.match(t, /claimable.*job trk_1/);
   assert.doesNotMatch(t, /please try again|peak load/);
@@ -254,7 +254,7 @@ test("a paid submit that aborts MAY have settled inline: say so and book conserv
   const res = await call({ prompt: "lofi beat" });
   const t = text(res);
   assert.equal(res.isError, true, t);
-  assert.match(t, /MAY have settled/);
+  assert.match(t, /MAY have gone through/);
   assert.doesNotMatch(t, /please try again|peak load/);
   assert.doesNotMatch(t, /No payment was taken/);
   assert.ok(Math.abs(budget.spent - 0.2) < 1e-9, `booked conservatively: spent=${budget.spent}`);
diff --git a/test/onramp.test.ts b/test/onramp.test.ts
index 9488d6b..5080c14 100644
--- a/test/onramp.test.ts
+++ b/test/onramp.test.ts
@@ -37,12 +37,17 @@ mock.module("../src/utils/wallet.js", {
     getWalletInfo: async () => ({ address: "0x34913A202138c83D0ed5FcA84E15da456d24402E" }),
   },
 });
+// What the 402 quotes. The onramp link is FREE by contract ($0 = the signature
+// is wallet authentication, nothing settles); a test flips this to prove the
+// client refuses to sign anything else.
+let quotedAmount: unknown = "0";
+let signCalls = 0;
 mock.module("@blockrun/llm", {
   namedExports: {
-    createPaymentPayload: async () => "0xpaymentpayloadmock",
+    createPaymentPayload: async () => { signCalls++; return "0xpaymentpayloadmock"; },
     parsePaymentRequired: () => ({}),
     extractPaymentDetails: () => ({
-      amount: "0", recipient: "0x0000000000000000000000000000000000000001",
+      amount: quotedAmount, recipient: "0x0000000000000000000000000000000000000001",
       network: "eip155:8453", resource: { url: "https://blockrun.ai/api/v1/onramp/token" },
       maxTimeoutSeconds: 300, extra: {},
     }),
@@ -51,6 +56,63 @@ mock.module("@blockrun/llm", {
 
 const { launchTopUp, mintOnrampUrl } = await import("../src/utils/onramp.js");
 
+const ADDRESS = "0x34913A202138c83D0ed5FcA84E15da456d24402E";
+
+// --- the "$0" promise is enforced, not assumed (audit round 3, critic) ---
+//
+// mintOnrampUrl is reached from every media tool's out-of-funds catch — on
+// wallets that DO hold USDC (a replayed nonce reads as "rejected" too). Until
+// now it signed whatever `details.amount` the 402 quoted; the $0 lived only in
+// a comment and this file's fixture. A gateway bug or a hijacked route that
+// quoted a real amount would have been signed against a funded wallet.
+
+test("a 402 that quotes a non-zero amount is refused before anything is signed", async () => {
+  fetchCall = 0; signCalls = 0; quotedAmount = "1000";
+  try {
+    await assert.rejects(
+      () => mintOnrampUrl(ADDRESS),
+      (e: unknown) => {
+        const msg = e instanceof Error ? e.message : String(e);
+        assert.match(msg, /not free/i, msg);
+        assert.match(msg, /1000/, msg);
+        assert.match(msg, /nothing was signed/i, msg);
+        return true;
+      },
+    );
+    assert.equal(signCalls, 0, "createPaymentPayload must not run for a priced quote");
+    assert.equal(fetchCall, 1, "no second (signed) POST");
+  } finally {
+    quotedAmount = "0";
+  }
+});
+
+test("an unreadable quoted amount is refused the same way — absence is not zero", async () => {
+  for (const bad of [undefined, "", "abc", null]) {
+    fetchCall = 0; signCalls = 0; quotedAmount = bad;
+    try {
+      await assert.rejects(() => mintOnrampUrl(ADDRESS), /not free|nothing was signed/i, String(bad));
+      assert.equal(signCalls, 0, `signed against amount ${String(bad)}`);
+    } finally {
+      quotedAmount = "0";
+    }
+  }
+});
+
+test("launchTopUp degrades a priced quote to the manual-funding note, still without signing", async () => {
+  fetchCall = 0; signCalls = 0; openCalls = []; quotedAmount = "1000";
+  try {
+    const r = await launchTopUp();
+    assert.equal(r.opened, false);
+    assert.equal(r.url, undefined);
+    assert.equal(signCalls, 0);
+    assert.equal(openCalls.length, 0);
+    assert.match(r.note, /not free/i, r.note);
+    assert.match(r.note, /Fund manually/, r.note);
+  } finally {
+    quotedAmount = "0";
+  }
+});
+
 test("mintOnrampUrl returns the Coinbase URL from the gateway", async () => {
   fetchCall = 0;
   const url = await mintOnrampUrl("0x34913A202138c83D0ed5FcA84E15da456d24402E");
diff --git a/test/order-preview-lock.test.ts b/test/order-preview-lock.test.ts
new file mode 100644
index 0000000..512db53
--- /dev/null
+++ b/test/order-preview-lock.test.ts
@@ -0,0 +1,47 @@
+// Run with: npm test  (tsx --test)
+//
+// The order card's outcome-unknown lock must outlive the card that set it
+// (audit round 3, D14). After a transport throw the card said "this card will
+// not re-submit it" and disabled Place — then re-enabled Re-quote, whose
+// handler rendered a brand-new card with a fresh `outcomeUnknown = false` and
+// Place enabled. One more click was a second real order on top of one that
+// may already be resting at the CLOB. The model was also never told: the
+// card called updateModelContext only on success.
+//
+// The card is DOM code inside a minified single-file bundle, so — like the
+// rest of apps.test.ts — this pins the strings and property names that only
+// exist if the module-scope lock and the model notification are wired in.
+// The predicates the lock keys on (outcomeIsUnknown / declinedByUser) are
+// tested as logic in apps.test.ts.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readAppHtml } from "../src/apps.js";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+test("the built card tells the model when an order's outcome is unknown", () => {
+  const order = readAppHtml("orderPreview");
+  assert.ok(order.includes("its outcome is UNKNOWN"), "model-context message on the unknown path");
+  assert.ok(order.includes('action:"orders"'), "…pointing at the order list");
+  assert.ok(order.includes('action:"positions"'), "…and at positions");
+  assert.ok(/outcome:["'`]unknown["'`]/.test(order), "structured outcome for the model");
+});
+
+test("the built card keeps the lock across Re-quote", () => {
+  const order = readAppHtml("orderPreview");
+  // The re-rendered-while-locked note only exists on the module-scope path.
+  assert.ok(order.includes("A previous submit of this order did not complete"), "a re-quoted card renders locked");
+});
+
+test("the source declares the lock at module scope, not inside renderPreview", () => {
+  const src = readFileSync(join(ROOT, "apps", "order-preview.ts"), "utf8");
+  const declaration = src.indexOf("const unknownOutcomes = new Map");
+  const renderPreview = src.indexOf("function renderPreview(");
+  assert.ok(declaration > -1, "unknownOutcomes map exists");
+  assert.ok(declaration < renderPreview, "the lock must be declared before (outside) renderPreview so Re-quote cannot reset it");
+  assert.ok(/let outcomeUnknown = unknownOutcomes\.has\(/.test(src), "renderPreview must initialise its flag from the module-scope lock");
+  assert.ok(!/let outcomeUnknown = false/.test(src), "the per-render `false` initialiser is the bug");
+});
diff --git a/test/path-safety.test.ts b/test/path-safety.test.ts
index 822016a..46b31e1 100644
--- a/test/path-safety.test.ts
+++ b/test/path-safety.test.ts
@@ -55,9 +55,82 @@ test("hasPathTraversal catches tab/newline-obfuscated traversal (URL parser stri
   }
 });
 
-test("hasPathTraversal tolerates a malformed percent and legit encoded chars", () => {
-  assert.equal(hasPathTraversal("foo%zzbar"), false); // malformed % must not throw
+test("hasPathTraversal tolerates legit encoded chars", () => {
   assert.equal(hasPathTraversal("search/web%20query"), false); // %20 → space, no traversal
+  assert.equal(hasPathTraversal("polymarket/wallet/0xabc%2Fdef"), false); // decodes to a slash, not a dot-segment
+});
+
+// ── ONE malformed escape ANYWHERE used to blind the whole check ──
+//
+// The guard decoded the entire caller string in one decodeURIComponent. A
+// single malformed `%` — trivially a lone `%` after `?` or `#`, which the URL
+// parser assigns to the query/fragment and never decodes — made the decode
+// throw, the catch kept the raw string, and the literal segment `%2e%2e` was
+// not `..` to the equality check. The parser, meanwhile, resolves `%2e%2e` /
+// `.%2e` / `%2e.` as dot-segments natively and ends the path at `?`/`#`, so the
+// request left this process already re-routed out of the tool's namespace:
+//
+//   blockrun_modal({ path: "%2e%2e/phone/numbers/buy#%" })
+//     -> guard false, classified as a $0.003 modal op, POSTs /v1/phone/numbers/buy ($5.001)
+//   blockrun_phone({ path: "phone/%2e%2e/modal/sandbox/create#%", body: { gpu: "H100", timeout: 86400 } })
+//     -> guard false, passes the phone/ namespace pin, reserves $0.012, buys a $192 sandbox
+//
+// The old test at this spot pinned `foo%zzbar` -> false, i.e. it pinned the
+// fallback that created the hole. Now: the query/fragment is dropped first (the
+// parser never routes on it), `%2e` is read as `.` the way the parser reads it,
+// each segment is decoded on its own so one bad escape cannot hide another, and
+// a malformed escape in the ROUTE part is refused outright — over-blocking is
+// the safe direction, and the gateway would 4xx such a path before payment.
+test("hasPathTraversal is not blinded by a malformed escape in the query or fragment", () => {
+  const BASE = "https://blockrun.ai/api/v1/exa/";
+  const escapes = (p: string) => !new URL(BASE + p).pathname.startsWith("/api/v1/exa/");
+  for (const p of [
+    "%2e%2e/phone/numbers/buy?%",
+    "%2e%2e/phone/numbers/buy#%",
+    "%2e%2e/phone/numbers/buy%",
+    ".%2e/phone/numbers/buy?%zz",
+    "%2e./phone/numbers/buy?%",
+    "%2E%2E/phone/numbers/buy#%",
+    "%2e%2e\\phone/numbers/buy?%",
+    "%\t2e%\t2e/phone/numbers/buy?%",
+  ]) {
+    assert.equal(escapes(p), true, `precondition: ${JSON.stringify(p)} must actually escape the namespace`);
+    assert.equal(hasPathTraversal(p), true, `${JSON.stringify(p)} reaches ${new URL(BASE + p).pathname} but was not blocked`);
+  }
+  // A namespace-internal hop with the same trick: the parser resolves it to
+  // /api/v1/exa/modal/sandbox/create, i.e. a different route than typed.
+  assert.equal(hasPathTraversal("phone/%2e%2e/modal/sandbox/create#%"), true);
+  assert.equal(hasPathTraversal("phone/%2e%2e/modal/sandbox/create?%"), true);
+});
+
+test("hasPathTraversal refuses a malformed escape in the route part", () => {
+  // fetch sends `foo%zzbar` verbatim; the gateway's router cannot decode it and
+  // 4xxs before payment. Refusing here costs nothing and closes the class.
+  assert.equal(hasPathTraversal("foo%zzbar"), true);
+  assert.equal(hasPathTraversal("phone/numbers/buy%"), true);
+  assert.equal(hasPathTraversal("%2e%2e%/phone/numbers/buy"), true);
+});
+
+test("hasPathTraversal ignores dot-segments the parser assigns to the query/fragment", () => {
+  // These never leave /api/v1/exa/ — the parser puts `../..` in the search
+  // string — so blocking them would refuse a harmless (if odd) call.
+  const BASE = "https://blockrun.ai/api/v1/exa/";
+  for (const p of ["search?next=../..", "search#..", "contents?u=%2e%2e"]) {
+    assert.equal(new URL(BASE + p).pathname.startsWith("/api/v1/exa/"), true, p);
+    assert.equal(hasPathTraversal(p), false, p);
+  }
+  // …but a `..` immediately BEFORE the `?` is still a route segment.
+  assert.equal(hasPathTraversal("../phone/numbers/buy?x=1"), true);
+  assert.equal(hasPathTraversal("..?x=1"), true);
+});
+
+test("hasPathTraversal still refuses an encoded slash that decodes into a dot-segment", () => {
+  // The gateway decodes %2F when routing; `phone%2F..%2Fmodal` becomes
+  // phone/../modal on the far side. Per-segment decoding must split AGAIN
+  // after decoding or this regresses (it was caught by the whole-string
+  // decode before).
+  assert.equal(hasPathTraversal("phone%2F..%2Fmodal/sandbox/create"), true);
+  assert.equal(hasPathTraversal("a/%2e%2e%2fb"), true);
 });
 
 test("hasPathTraversal allows legitimate passthrough paths", () => {
@@ -135,6 +208,36 @@ test("normalizeClassifyPath decodes once, as the gateway router does", () => {
   assert.equal(normalizeClassifyPath("phone/lookup%zz"), "phone/lookup%zz");
 });
 
+// ── `[?#].*$` did not cross a line terminator ──
+//
+// The query cut ran BEFORE the tab/LF/CR strip and used `.`, which in JS never
+// matches LF, CR, U+2028 or U+2029; `$` without the `m` flag is end-of-input
+// only. So the cut simply failed to match when a line terminator followed the
+// `?`/`#`, the later strip removed the LF, and `phone/numbers/buy?` reached the
+// exact-match price table — which priced it as the $0.012 unknown while fetch
+// deleted the same LF and the gateway served the $5.001 buy route. The
+// round-2 `?x=1` fix re-opened by one character; probed on the pure pipeline
+// (no handler run) 2026-09-13.
+test("normalizeClassifyPath cuts the query/fragment even when a line terminator follows it", () => {
+  const BASE = "https://blockrun.ai/api/v1/";
+  for (const raw of [
+    "phone/numbers/buy?\n",
+    "phone/numbers/buy#\r",
+    "phone/numbers/buy?x\ry",
+    "phone/numbers/buy?x\u2028y",
+    "phone/numbers/buy#\u2029",
+    "phone/numbers/buy?\n\n\n",
+    "phone/numbers/buy?a=1\nb=2",
+  ]) {
+    // The parser deletes LF/CR outright and percent-encodes U+2028 into the
+    // query; the PATH it sends is the full buy route every time.
+    assert.equal(new URL(BASE + raw).pathname, "/api/v1/phone/numbers/buy", JSON.stringify(raw));
+    assert.equal(normalizeClassifyPath(raw), "phone/numbers/buy", JSON.stringify(raw));
+  }
+  assert.equal(normalizeClassifyPath("contents?\n"), "contents");
+  assert.equal(normalizeClassifyPath("markets/listings?\n"), "markets/listings");
+});
+
 test("normalizeClassifyPath keeps the query string off the classified route", () => {
   // Order matters: the query is dropped from the RAW string before decoding, so
   // an encoded `?` inside a segment cannot truncate the path to a cheaper tier.
diff --git a/test/path-tools-settle-on-throw.test.ts b/test/path-tools-settle-on-throw.test.ts
new file mode 100644
index 0000000..74b0d11
--- /dev/null
+++ b/test/path-tools-settle-on-throw.test.ts
@@ -0,0 +1,275 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// C38 (audit round 3): the seven path tools let the SDK — or, on the account
+// rail, utils/api-key-call.ts — own the paid request, and their catch used to
+// do formatError(extractErrorMessage(err)) and nothing else. A call that was
+// paid for and then never answered booked $0 and said "try again in a few
+// minutes"; the retry paid again.
+//
+// One matrix, seven tools, three rails, five failure shapes:
+//
+//   settle-then-abort   the paid request went out, nothing came back
+//                       → books the reserve ONCE, says MAY, no blind retry
+//   edge 504            the origin did not answer (post-settle 504 has no body)
+//                       → books, says MAY
+//   marked NOT charged  the gateway said the nonce was released
+//                       → books nothing, keeps the retry advice
+//   pre-settle 500      a gateway-authored 5xx with a body after payment —
+//                       the search route's Grok failure is exactly this shape
+//                       → books NOTHING (would be phantom spend), text hedges
+//   pre-payment 4xx     the unpaid first response refused the call
+//                       → books nothing, no hedge
+//
+// The stub SDK client throws whatever the row says; on the account rail the
+// mocked fetchWithTimeout does. Money is asserted through budget.spent.
+import { test, mock, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import type { BudgetState } from "../src/types.js";
+
+type Rail = "base" | "solana" | "account";
+let rail: Rail = "base";
+let walletThrows: unknown = null;
+let accountFetch: (() => Promise<Response>) | null = null;
+let sdkCalls = 0;
+
+const stubClient = {
+  getWithPaymentRaw: async () => { sdkCalls++; if (walletThrows) throw walletThrows; return { ok: true }; },
+  requestWithPaymentRaw: async () => { sdkCalls++; if (walletThrows) throw walletThrows; return { ok: true }; },
+};
+mock.module("../src/utils/wallet.js", {
+  namedExports: {
+    getApiBase: () => "https://blockrun.ai/api",
+    resolveGatewayUrl: (u: string) => u,
+    getChain: () => (rail === "solana" ? "solana" : "base"),
+    getClient: () => stubClient,
+    buildClient: () => stubClient,
+    buildClientWithTimeout: () => stubClient,
+    baseOnlyMessage: () => null,
+    getOrCreateWalletKey: () => { throw new Error("path tools must not touch a wallet key"); },
+    getWalletInfo: async () => ({ address: "0xTEST" }),
+  },
+});
+mock.module("../src/utils/auth.js", {
+  namedExports: {
+    isApiKeyMode: () => rail === "account",
+    getApiKey: () => (rail === "account" ? "brk_test_key" : undefined),
+    apiAuthHeaders: () => ({ Authorization: "Bearer brk_test_key" }),
+    getApiKeyBase: () => "https://api.blockrun.ai",
+    PORTAL_CREDITS_URL: "https://user.blockrun.ai/dashboard/credits",
+  },
+});
+mock.module("../src/utils/http.js", {
+  namedExports: {
+    fetchWithTimeout: async () => {
+      if (accountFetch) return accountFetch();
+      return new Response(JSON.stringify({ ok: true }), { status: 200, headers: { "content-type": "application/json", "x-blockrun-cost-usd": "0.01" } });
+    },
+    isTimeoutError: (e: unknown) => (e as { name?: string } | undefined)?.name === "AbortError",
+  },
+});
+
+const { registerSearchTool } = await import("../src/tools/search.js");
+const { registerExaTool } = await import("../src/tools/exa.js");
+const { registerMarketsTool } = await import("../src/tools/markets.js");
+const { registerRpcTool, RPC_PRICE_USD } = await import("../src/tools/rpc.js");
+const { registerPhoneTool } = await import("../src/tools/phone.js");
+const { registerModalTool } = await import("../src/tools/modal.js");
+const { registerDefiTool } = await import("../src/tools/defi.js");
+const { ledgerFallback } = await import("../src/utils/raw-call.js");
+const { estimateSearchCost } = await import("../src/tools/search.js");
+const { estimateExaCost } = await import("../src/tools/exa.js");
+const { MARKETS_PRICE_USD } = await import("../src/tools/markets.js");
+const { estimatePhoneCost } = await import("../src/tools/phone.js");
+const { estimateModalCost } = await import("../src/tools/modal.js");
+const { withTxFee } = await import("../src/utils/tx-fee.js");
+
+type Handler = (args: Record<string, unknown>) => Promise<{ content: Array<{ type: string; text?: string }>; isError?: boolean }>;
+type Register = (server: never, budget: BudgetState) => void;
+
+function harness(register: Register) {
+  let handler: Handler | undefined;
+  const server = {
+    registerTool: (_n: string, _c: unknown, h: Handler) => { handler = h; },
+    server: { getClientCapabilities: () => ({}) },
+  };
+  const budget: BudgetState = { limit: null, spent: 0, calls: 0, agents: new Map() };
+  register(server as never, budget);
+  assert.ok(handler, "tool did not register a handler");
+  return { call: (args: Record<string, unknown>) => handler!(args), budget };
+}
+const textOf = (res: { content: Array<{ text?: string }> }) => res.content.map((p) => p.text ?? "").join("\n");
+
+// Every tool with a paid call and the reserve it makes for it. The estimate
+// functions are the tools' own, so a price-table change does not silently
+// turn a booked-vs-not assertion into a coincidence.
+const TOOLS: Array<{ name: string; register: Register; args: Record<string, unknown>; estimate: number }> = [
+  { name: "search", register: registerSearchTool as Register, args: { body: { query: "fed", max_results: 10 } }, estimate: estimateSearchCost({ query: "fed", max_results: 10 }) },
+  { name: "exa", register: registerExaTool as Register, args: { path: "search", body: { query: "fed" } }, estimate: estimateExaCost("search", { query: "fed" }) },
+  { name: "markets", register: registerMarketsTool as Register, args: { path: "polymarket/events", params: { search: "NBA" } }, estimate: MARKETS_PRICE_USD },
+  { name: "rpc", register: registerRpcTool as Register, args: { network: "ethereum", method: "eth_blockNumber" }, estimate: withTxFee(RPC_PRICE_USD) },
+  { name: "phone", register: registerPhoneTool as Register, args: { path: "phone/lookup", body: { number: "+14155551212" } }, estimate: estimatePhoneCost("phone/lookup", true) },
+  { name: "modal", register: registerModalTool as Register, args: { path: "sandbox/exec", body: { command: "ls" } }, estimate: estimateModalCost("sandbox/exec", { command: "ls" }) },
+  { name: "defi", register: registerDefiTool as Register, args: { path: "protocols" }, estimate: 0.007 },
+];
+
+// The SDK's APIError shape: message + statusCode + sanitized response body.
+class FakeAPIError extends Error {
+  constructor(message: string, public statusCode: number, public response: unknown) { super(message); this.name = "APIError"; }
+}
+const abortError = () => { const e = new Error("This operation was aborted"); e.name = "AbortError"; return e; };
+const jsonResponse = (status: number, body: unknown) =>
+  new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+
+type Row = {
+  shape: string;
+  wallet: () => unknown;
+  account: () => Promise<Response>;
+  books: boolean;
+  text: RegExp[];
+  notText: RegExp[];
+};
+const ROWS: Row[] = [
+  {
+    shape: "settle-then-abort",
+    wallet: abortError,
+    account: async () => { throw abortError(); },
+    books: true,
+    text: [/MAY have gone through/, /booked against your budget as a precaution/, /action:"report"/],
+    notText: [/Try again in a few minutes/, /needs funding|out of credit/, /nothing was charged/],
+  },
+  {
+    shape: "edge 504 after payment (origin did not answer)",
+    wallet: () => new FakeAPIError("API error after payment: 504", 504, { message: "Request failed" }),
+    account: async () => new Response("upstream request timeout", { status: 504, headers: { "content-type": "text/plain" } }),
+    books: true,
+    text: [/MAY have gone through/, /booked against your budget as a precaution/],
+    notText: [/Try again in a few minutes/, /needs funding|out of credit/, /nothing was charged/],
+  },
+  {
+    shape: "marked NOT charged",
+    wallet: () => new FakeAPIError("API error after payment: 502", 502, {
+      message: "Upstream provider error",
+      detail: "Predexon 500: An unexpected error occurred (payment NOT charged)",
+    }),
+    account: async () => jsonResponse(502, { error: "Upstream provider error", message: "Upstream returned an error. Payment was NOT charged." }),
+    books: false,
+    text: [/nothing was charged/, /Try again in a few minutes/],
+    notText: [/MAY have gone through/, /booked against your budget/, /needs funding|out of credit/],
+  },
+  {
+    shape: "pre-settle 500 with a body (search's Grok failure)",
+    wallet: () => new FakeAPIError("API error after payment: 500", 500, { message: "Internal server error" }),
+    account: async () => jsonResponse(500, { error: "Internal server error" }),
+    books: false,
+    // The text still hedges — the client cannot tell this from a post-settle
+    // catch-all 500 — but the ledger does not guess.
+    text: [/MAY have gone through/],
+    notText: [/booked against your budget/, /Try again in a few minutes/, /needs funding|out of credit/],
+  },
+  {
+    shape: "pre-payment 4xx",
+    wallet: () => new FakeAPIError("API error: 400", 400, { message: "Bad request: missing query" }),
+    account: async () => jsonResponse(400, { error: "Bad request: missing query" }),
+    books: false,
+    text: [/Bad request/],
+    notText: [/MAY have gone through/, /booked against your budget/, /Try again in a few minutes/, /needs funding|out of credit/],
+  },
+];
+
+beforeEach(() => { rail = "base"; walletThrows = null; accountFetch = null; sdkCalls = 0; });
+
+for (const r of ["base", "solana", "account"] as const) {
+  for (const row of ROWS) {
+    for (const tool of TOOLS) {
+      test(`${r} · ${tool.name} · ${row.shape} → ${row.books ? "books the reserve once" : "books nothing"}`, async () => {
+        rail = r;
+        if (r === "account") accountFetch = row.account; else walletThrows = row.wallet();
+        const { call, budget } = harness(tool.register);
+
+        const res = await call(tool.args);
+        const out = textOf(res);
+
+        assert.equal(res.isError, true, out);
+        if (r === "account") assert.equal(sdkCalls, 0, "the account rail never touches the SDK client");
+        const expected = row.books ? ledgerFallback(tool.estimate) : 0;
+        assert.ok(Math.abs(budget.spent - expected) < 1e-9, `spent ${budget.spent}, expected ${expected}\n${out}`);
+        if (row.books) {
+          assert.ok(expected > 0, "the row must book a real amount, or the assertion proves nothing");
+          assert.equal(budget.calls, 1, "booked once, not per retry");
+          assert.match(out, new RegExp(`\\$${expected.toFixed(4)}`), out);
+        }
+        for (const re of row.text) assert.match(out, re, out);
+        for (const re of row.notText) assert.doesNotMatch(out, re, out);
+      });
+    }
+  }
+}
+
+test("nothing thrown before the paid request can book: a declined budget gate is $0", async () => {
+  // sentUsd stays 0 until the line before rawGet/rawPost. Exhaust the cap so
+  // the gate refuses before anything is sent; an abort-shaped message here
+  // must not be read as a settled payment.
+  for (const tool of TOOLS) {
+    walletThrows = abortError();
+    const { call, budget } = harness(tool.register);
+    budget.limit = 0.000001;
+    const res = await call(tool.args);
+    assert.equal(res.isError, true);
+    assert.equal(budget.spent, 0, tool.name);
+    assert.doesNotMatch(textOf(res), /MAY have gone through|booked against/, tool.name);
+  }
+});
+
+test("a free phone poll (reserve $0) books $0 even when it is aborted", async () => {
+  walletThrows = abortError();
+  const { call, budget } = harness(registerPhoneTool as Register);
+  const res = await call({ path: "voice/call/abc123" });
+  assert.equal(res.isError, true);
+  assert.equal(budget.spent, 0);
+  assert.doesNotMatch(textOf(res), /booked against/);
+});
+
+// Audit round 4: the Solana client records the settlement BEFORE it parses
+// the paid body (requestWithPaymentRaw: assertPaid → recordSettlement →
+// retryResponse.json()), so a non-JSON 200 throws a bare SyntaxError with no
+// status and no transport words — "none" to settlementOnThrow — for a call
+// the SDK's own counter says was paid. The counter is the evidence: rawGet /
+// rawPost read it around the SDK call and hand the delta to the catch, which
+// books it as a CERTAIN charge.
+test("a throw after the SDK counted the settlement books the counted amount, on every wallet rail", async () => {
+  for (const r of ["base", "solana"] as const) {
+    rail = r;
+    let total = 0;
+    const settling = {
+      getSpending: () => ({ totalUsd: total }),
+      getWithPaymentRaw: async () => { total += 0.003; throw new SyntaxError("Unexpected token < in JSON at position 0"); },
+      requestWithPaymentRaw: async () => { total += 0.003; throw new SyntaxError("Unexpected token < in JSON at position 0"); },
+    };
+    const { rawGet, rawPost } = await import("../src/utils/raw-call.js");
+    for (const call of [() => rawGet(settling as never, "/v1/x"), () => rawPost(settling as never, "/v1/x", {})]) {
+      await assert.rejects(call, (err: Error & { settledUsd?: number }) => {
+        assert.equal(err.name, "RawCallSettledError", `${r}: ${err.message}`);
+        assert.ok(Math.abs((err.settledUsd ?? 0) - 0.003) < 1e-9, `${r}: settledUsd=${err.settledUsd}`);
+        assert.match(err.message, /Unexpected token/);
+        return true;
+      });
+    }
+  }
+});
+
+test("a path tool renders a settled-then-failed call as a charge that stands, booked at the counted amount", async () => {
+  rail = "solana";
+  const { rawPost } = await import("../src/utils/raw-call.js");
+  let total = 0;
+  const settling = { getSpending: () => ({ totalUsd: total }), requestWithPaymentRaw: async () => { total += 0.003; throw new SyntaxError("Unexpected token <"); } };
+  let thrown: unknown;
+  try { await rawPost(settling as never, "/v1/rpc/ethereum", {}); } catch (e) { thrown = e; }
+  const { pathToolFailure } = await import("../src/utils/path-tool-catch.js");
+  const budget: BudgetState = { limit: null, spent: 0, calls: 0, agents: new Map() };
+  const res = pathToolFailure(thrown, { budget, sentUsd: withTxFee(RPC_PRICE_USD) });
+  const t = textOf(res);
+  assert.ok(Math.abs(budget.spent - 0.003) < 1e-9, `spent=${budget.spent}`);
+  assert.match(t, /charge stands/);
+  assert.match(t, /\$0\.0030/);
+  assert.doesNotMatch(t, /MAY have gone through|Try again in a few minutes/);
+});
diff --git a/test/poll.test.ts b/test/poll.test.ts
index 98824cb..06b7763 100644
--- a/test/poll.test.ts
+++ b/test/poll.test.ts
@@ -36,3 +36,24 @@ test("pollTimeoutFor never lets a poll finish past the deadline", () => {
     );
   }
 });
+
+// JobFailedError is the typed "the gateway answered the poll with a terminal
+// status and nothing was charged" the three async loops (Base video, Base
+// music, the Solana helper) throw, so a tool's catch can recognise it without
+// reading prose. The prose mattered: MiniMax's own failure text is "The
+// operation was aborted due to timeout", which isTimeoutError's substring
+// fallback matched, and the Solana give-up branch then booked a full render
+// for a job the gateway had just said was not charged (audit round 3, C13).
+test("JobFailedError is a distinct class that carries the job id and stays a plain Error otherwise", async () => {
+  const { JobFailedError } = await import("../src/utils/poll.js");
+  const err = new JobFailedError("Video generation failed upstream: The operation was aborted due to timeout. No payment was taken.", { jobId: "vid_1" });
+  assert.ok(err instanceof Error);
+  assert.ok(err instanceof JobFailedError);
+  assert.equal(err.name, "JobFailedError");
+  assert.equal(err.jobId, "vid_1");
+  assert.match(err.message, /No payment was taken/);
+  // instanceof, not name: a plain Error whose message merely looks alike is
+  // not a gateway verdict.
+  assert.equal(new Error(err.message) instanceof JobFailedError, false);
+  assert.equal(new JobFailedError("x").jobId, undefined);
+});
diff --git a/test/polymarket-confirm-spend.test.ts b/test/polymarket-confirm-spend.test.ts
new file mode 100644
index 0000000..5e84f1f
--- /dev/null
+++ b/test/polymarket-confirm-spend.test.ts
@@ -0,0 +1,246 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// BLOCKRUN_CONFIRM_SPEND=on is the human-in-the-loop switch: the server asks
+// the user, via MCP elicitation, before money moves. It covered a $0.004 rpc
+// call and none of blockrun_polymarket's confirm:true actions — and
+// `confirm:true` is a model-supplied boolean, not a human's click. With the
+// flag on, fund / withdraw / buy / sell now go through the same confirmSpend
+// dialog (usd = the notional, label names the action and destination); a
+// decline signs nothing. With the flag off, confirm:true alone still places,
+// exactly as before (that path is what every other polymarket test runs).
+process.env.BLOCKRUN_CONFIRM_SPEND = "on";
+process.env.BLOCKRUN_CONFIRM_THRESHOLD = "0";
+
+import { test, mock } from "node:test";
+import assert from "node:assert/strict";
+import { outcomeIsUnknown } from "../apps/order-safety.js";
+import { USDCE_COLLATERAL } from "../src/utils/polymarket/constants.js";
+
+const VAULT = "0x5d3eaa66AE01F1a907c8e0970D1D021C6Ff8EB26";
+const AGENT = "0xCC8c44AD3dc2A58D841c3EB26131E49b22665EF8";
+const BRIDGE = "0x6a6827094a5809Df44b32adBEf26F233614F12c4";
+
+let orderSubmits = 0;
+let authorizationsSigned = 0;
+let fundPosts = 0;
+let bridgeWithdrawPosts = 0;
+let relayerBatches = 0;
+let stateFile: Record<string, unknown> = {};
+
+const fakeClob = {
+  getOrderBook: async () => ({
+    tick_size: "0.01", neg_risk: false, min_order_size: "5",
+    asks: [{ price: "0.40", size: "100" }], bids: [{ price: "0.39", size: "100" }],
+  }),
+  createAndPostOrder: async () => { orderSubmits++; return { success: true, orderID: "0xORDER", status: "live" }; },
+  createAndPostMarketOrder: async () => { orderSubmits++; return { success: true, orderID: "0xMKT", status: "matched" }; },
+};
+
+mock.module("../src/utils/polymarket/client.js", {
+  namedExports: {
+    getClobClient: async () => fakeClob,
+    checkGeoblock: async () => ({ orderPlacement: "permitted", country: "FI", ip: null, raw: {} }),
+    getPolymarketAccount: () => ({ address: AGENT }),
+    resetClobClient: () => {},
+    getClobProxyAgent: () => null,
+    installUnderscoreHeaderBridge: () => {},
+  },
+});
+mock.module("../src/utils/http.js", {
+  namedExports: { fetchWithTimeout: async () => ({ ok: false }), isTimeoutError: () => false },
+});
+mock.module("@blockrun/llm", {
+  namedExports: {
+    createPaymentPayload: async () => { authorizationsSigned++; return "BASE64"; },
+    BlockrunClient: class {
+      sessionTotalUsd = 0;
+      getSpending() { return { totalUsd: 0, calls: 0 }; }
+      async post() { fundPosts++; return { success: true, deposit: { txHash: "0xDEP" } }; }
+    },
+  },
+});
+mock.module("../src/utils/wallet.js", {
+  namedExports: {
+    getApiBase: () => "https://blockrun.ai/api",
+    resolveGatewayUrl: (u: string) => u,
+    getOrCreateWalletKey: () => "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
+    getChainBalance: async () => 100,
+    getChain: () => "base",
+  },
+});
+mock.module("../src/utils/polymarket/positions.js", {
+  namedExports: { getFundsAddress: () => VAULT, listPositions: async () => ({ text: "none", structured: { positions: [] } }) },
+});
+mock.module("../src/utils/polymarket/setup.js", {
+  namedExports: {
+    runSetup: async () => { throw new Error("setup not used (test)"); },
+    getPublicClient: () => ({
+      getCode: async () => "0x60006000",
+      // $7.50 pUSD, no legacy USDC.e — the withdraw-all amount is $7.50.
+      readContract: async ({ address }: { address: string }) =>
+        address.toLowerCase() === USDCE_COLLATERAL.toLowerCase() ? 0n : 7_500_000n,
+      waitForTransactionReceipt: async () => ({ status: "success" }),
+    }),
+    getPusdBalance: async () => 7.5,
+  },
+});
+mock.module("../src/utils/polymarket/redeem.js", {
+  namedExports: { redeemPosition: async () => { throw new Error("redeem not used (test)"); } },
+});
+mock.module("../src/utils/polymarket/creds.js", {
+  namedExports: {
+    loadState: () => ({ ...stateFile }),
+    saveState: (patch: Record<string, unknown>) => { stateFile = { ...stateFile, ...patch }; return stateFile; },
+    loadDepositWalletForSigner: () => VAULT,
+    loadL2Creds: () => null,
+    saveL2Creds: () => {},
+    invalidateL2Creds: () => {},
+    loadBuilderCreds: () => null,
+    saveBuilderCreds: () => {},
+  },
+});
+mock.module("../src/utils/polymarket/relayer.js", {
+  namedExports: {
+    sendWalletBatch: async () => { relayerBatches++; return { transactionHash: "0x" + "ab".repeat(32) }; },
+    getRelayerTransactionState: async () => undefined,
+    BATCH_DEADLINE_SECS: 300,
+  },
+});
+mock.module("axios", {
+  defaultExport: {
+    post: async (url: string) => {
+      if (url.endsWith("/withdraw")) bridgeWithdrawPosts++;
+      return { data: { address: { evm: BRIDGE } } };
+    },
+    get: async () => { throw new Error("unexpected GET (test)"); },
+  },
+});
+
+const { registerPolymarketTool } = await import("../src/tools/polymarket.js");
+const { resetSpendApproval } = await import("../src/utils/confirm-spend.js");
+
+type Handler = (args: Record<string, unknown>) => Promise<{ content: Array<{ type: string; text?: string }>; isError?: boolean }>;
+type Elicit = { message: string };
+
+function harness(answer: "decline" | "accept" | "cancel") {
+  let handler: Handler | undefined;
+  const prompts: Elicit[] = [];
+  const server = {
+    registerTool: (_n: string, _c: unknown, h: Handler) => { handler = h; },
+    server: {
+      getClientCapabilities: () => ({ elicitation: {} }),
+      elicitInput: async (p: Elicit) => { prompts.push(p); return { action: answer }; },
+    },
+  };
+  registerPolymarketTool(server as never);
+  assert.ok(handler, "tool did not register a handler");
+  return {
+    prompts,
+    call: async (args: Record<string, unknown>) => {
+      const r = await handler!(args);
+      return { ...r, text: r.content.map((c) => c.text ?? "").join("\n") };
+    },
+  };
+}
+
+function reset() {
+  orderSubmits = 0; authorizationsSigned = 0; fundPosts = 0; bridgeWithdrawPosts = 0; relayerBatches = 0;
+  stateFile = {};
+  resetSpendApproval();
+}
+
+test("buy confirm:true with the flag on asks the user; a decline signs nothing and releases the session ledger", async () => {
+  reset();
+  const { call, prompts } = harness("decline");
+  const res = await call({ action: "buy", token_id: "T1", amount_usd: 5, confirm: true });
+  assert.equal(prompts.length, 1, "exactly one elicitation");
+  assert.match(prompts[0].message, /\$5\.0000/, "the dialog states the notional");
+  assert.match(prompts[0].message, /polymarket/i);
+  assert.match(prompts[0].message, /buy/i);
+  assert.match(res.text, /declined/i, res.text);
+  assert.match(res.text, /nothing was signed/i);
+  assert.equal(orderSubmits, 0, "nothing may be signed after a decline");
+  // The order card must read this as "nothing moved" and re-arm, not lock.
+  assert.equal(outcomeIsUnknown(res.text), false, res.text);
+  assert.equal(res.isError, true, "the card branches on isError to avoid rendering 'Order submitted'");
+});
+
+test("a decline leaves no session-ledger residue", async () => {
+  reset();
+  const { getSessionLedger } = await import("../src/utils/polymarket/orders.js");
+  const before = getSessionLedger();
+  const { call } = harness("decline");
+  await call({ action: "buy", token_id: "T1", amount_usd: 5, confirm: true });
+  const after = getSessionLedger();
+  assert.equal(after.totalUsd, before.totalUsd);
+  assert.equal(after.count, before.count);
+});
+
+test("a dry-run (no confirm) never prompts — the dialog gates signatures, not previews", async () => {
+  reset();
+  const { call, prompts } = harness("decline");
+  const res = await call({ action: "buy", token_id: "T1", amount_usd: 5 });
+  assert.equal(res.isError, undefined, res.text);
+  assert.match(res.text, /DRY RUN/);
+  assert.equal(prompts.length, 0);
+});
+
+test("an accept places the order (confirm:true is still required underneath)", async () => {
+  reset();
+  const { call, prompts } = harness("accept");
+  const res = await call({ action: "buy", token_id: "T1", amount_usd: 5, confirm: true });
+  assert.equal(res.isError, undefined, res.text);
+  assert.match(res.text, /Order submitted/);
+  assert.equal(prompts.length, 1);
+  assert.equal(orderSubmits, 1);
+});
+
+test("fund confirm:true: a decline signs no EIP-3009 authorization and never POSTs", async () => {
+  reset();
+  const { call, prompts } = harness("decline");
+  const res = await call({ action: "fund", amount_usd: 5, confirm: true });
+  assert.equal(prompts.length, 1);
+  assert.match(prompts[0].message, /\$5\.01/, "amount + the $0.01 fee");
+  assert.match(prompts[0].message, /fund/i);
+  assert.match(res.text, /declined/i, res.text);
+  assert.equal(authorizationsSigned, 0, "the authorization must not be signed before the user answers");
+  assert.equal(fundPosts, 0);
+  assert.equal(stateFile.pendingFund, undefined, "no guard armed for a transfer that was never signed");
+});
+
+test("withdraw confirm:true (full balance): the dialog shows the real amount and destination; a decline moves nothing", async () => {
+  reset();
+  const { call, prompts } = harness("decline");
+  const res = await call({ action: "withdraw", confirm: true });
+  assert.equal(prompts.length, 1);
+  assert.match(prompts[0].message, /\$7\.5000/, "the amount is the full balance the withdraw would move, not a placeholder");
+  assert.match(prompts[0].message, new RegExp(`withdraw.*${AGENT.slice(0, 6)}`, "is"), "label names the destination");
+  assert.match(res.text, /declined/i, res.text);
+  assert.equal(bridgeWithdrawPosts, 0, "the bridge must not be asked for a withdrawal address");
+  assert.equal(relayerBatches, 0);
+});
+
+test("withdraw to a custom address puts THAT address in the dialog", async () => {
+  reset();
+  const custom = "0x000000000000000000000000000000000000dEaD";
+  const { call, prompts } = harness("decline");
+  await call({ action: "withdraw", amount_usd: 3, to_address: custom, confirm: true });
+  assert.equal(prompts.length, 1);
+  assert.match(prompts[0].message, /\$3\.0000/);
+  assert.match(prompts[0].message, /dEaD/);
+});
+
+test("a cancel/ESC is fail-open (the client's own permission prompt is the real gate) — the order proceeds", async () => {
+  reset();
+  const { call } = harness("cancel");
+  const res = await call({ action: "buy", token_id: "T1", amount_usd: 5, confirm: true });
+  assert.equal(res.isError, undefined, res.text);
+  assert.equal(orderSubmits, 1);
+});
+
+test("read-only/free actions never prompt", async () => {
+  reset();
+  const { call, prompts } = harness("decline");
+  await call({ action: "positions" });
+  assert.equal(prompts.length, 0);
+});
diff --git a/test/polymarket-e2e-readonly.test.ts b/test/polymarket-e2e-readonly.test.ts
new file mode 100644
index 0000000..ba94ed7
--- /dev/null
+++ b/test/polymarket-e2e-readonly.test.ts
@@ -0,0 +1,108 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// scripts/polymarket-e2e-readonly.ts is the preflight an operator runs before
+// a live redeem. listPositions() catches every failure and returns
+// `{ text, isError: true }` with no `structured`; the script read
+// `structured?.positions ?? []` and printed `positions: []` under a
+// success-shaped JSON with exit 0 — so a Data-API timeout looked like an
+// empty wallet, and "nothing to redeem" was the conclusion.
+//
+// The script is top-level await over two utils/ calls, so it is imported here
+// with both mocked (no wallet, no RPC, no network) and its stdout and exit
+// code are captured. The redacted-exit installer is real; process.exit is
+// intercepted so the test process survives the failure path.
+import { test, mock } from "node:test";
+import assert from "node:assert/strict";
+
+const WALLET = "0x" + "ab".repeat(20);
+
+type ToolResult = { text: string; isError?: boolean; structured?: Record<string, unknown> };
+let positionsResult: ToolResult;
+let withdrawalResult: ToolResult;
+
+mock.module("../src/utils/polymarket/positions.js", {
+  namedExports: { listPositions: async () => positionsResult },
+});
+mock.module("../src/utils/polymarket/withdraw.js", {
+  namedExports: { withdrawFunds: async () => withdrawalResult },
+});
+
+const logged: string[] = [];
+const realLog = console.log;
+const realExit = process.exit;
+class Exit extends Error {
+  constructor(public code: number) { super(`exit ${code}`); }
+}
+
+async function runScript(): Promise<{ out: Record<string, unknown>; exit: number }> {
+  logged.length = 0;
+  console.log = (s: string) => { logged.push(String(s)); };
+  process.exit = ((code?: number) => { throw new Exit(code ?? 0); }) as never;
+  let exit = 0;
+  try {
+    // A fresh module instance per case: the query string defeats the import
+    // cache, and the mocks above are consulted on every evaluation.
+    await import(`../scripts/polymarket-e2e-readonly.ts?case=${Date.now()}-${Math.random()}`);
+  } catch (e) {
+    if (!(e instanceof Exit)) throw e;
+    exit = e.code;
+  } finally {
+    console.log = realLog;
+    process.exit = realExit;
+  }
+  return { out: JSON.parse(logged.join("\n")) as Record<string, unknown>, exit };
+}
+
+const dryRun: ToolResult = {
+  text: "dry run",
+  structured: { dryRun: true, amountUsd: 12.5, pusdUsd: 10, usdceUsd: 2.5, wrapUsd: 0, toChainId: 8453 },
+};
+
+test("a positions error is printed AS an error, redacted, and the run exits 1", async () => {
+  positionsResult = { text: `Could not fetch positions from Polymarket's Data-API (timeout for ${WALLET}).`, isError: true };
+  withdrawalResult = dryRun;
+  const { out, exit } = await runScript();
+  assert.equal(exit, 1);
+  assert.equal(out.ok, false);
+  assert.notDeepEqual(out.positions, [], "an outage must not read as an empty wallet");
+  const positions = out.positions as { error?: string };
+  assert.match(positions.error ?? "", /Could not fetch positions/);
+  assert.equal(JSON.stringify(out).includes(WALLET), false, "the address must not reach stdout");
+  assert.match(positions.error ?? "", /<wallet>/);
+});
+
+test("a withdrawal-preview error still exits 1 even when positions loaded", async () => {
+  positionsResult = { text: "ok", structured: { positions: [] } };
+  withdrawalResult = { text: `Bridge did not return an address (got: ${WALLET}).`, isError: true };
+  const { out, exit } = await runScript();
+  assert.equal(exit, 1);
+  assert.equal(out.ok, false);
+  assert.deepEqual(out.positions, []);
+  assert.match(String(out.withdrawalPreview), /<wallet>/);
+});
+
+test("both sides healthy: ok:true, exit 0, positions abbreviated, condition id truncated", async () => {
+  positionsResult = {
+    text: "ok",
+    structured: {
+      positions: [{ title: "Will it rain?", outcome: "Yes", size: 3, currentValue: 0.0009, redeemable: true, negativeRisk: false, conditionId: "0x" + "12".repeat(32) }],
+    },
+  };
+  withdrawalResult = dryRun;
+  const { out, exit } = await runScript();
+  assert.equal(exit, 0);
+  assert.equal(out.ok, true);
+  const [p] = out.positions as Array<Record<string, unknown>>;
+  assert.equal(p!.title, "Will it rain?");
+  assert.equal(p!.condition, "0x12121212…");
+  assert.deepEqual(out.withdrawalPreview, { dryRun: true, amountUsd: 12.5, pusdUsd: 10, usdceUsd: 2.5, wrapUsd: 0, toChainId: 8453 });
+});
+
+test("an empty wallet is an empty list, distinguishable from an error", async () => {
+  positionsResult = { text: "No positions.", structured: { positions: [] } };
+  withdrawalResult = dryRun;
+  const { out, exit } = await runScript();
+  assert.equal(exit, 0);
+  assert.deepEqual(out.positions, []);
+  assert.equal(out.ok, true);
+});
diff --git a/test/polymarket-fund-fee.test.ts b/test/polymarket-fund-fee.test.ts
new file mode 100644
index 0000000..6c1dbd0
--- /dev/null
+++ b/test/polymarket-fund-fee.test.ts
@@ -0,0 +1,158 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// action:"fund" pays a REAL $0.01 x402 fee from the Base wallet on every call
+// (the gateway's /v1/polymarket/fund charge) — BlockRun API spend, the thing
+// the budget ledger meters — yet it never reserved or booked it (audit round
+// 3, D18): a delegated agent could call fund ten times and action:"report"
+// still showed $0.00, the cap never tripped, and a gateway re-price of the
+// route would be signed by the SDK with nothing in this repo recording it.
+// Now: reserve the fee at the gate (before the dialog, before signing), book
+// what the SDK observed on success, book the estimate when the outcome is
+// unknown (the fee payment went out with the request), book nothing on a
+// definite rejection.
+import { test, mock } from "node:test";
+import assert from "node:assert/strict";
+import type { BudgetState } from "../src/types.js";
+
+const VAULT = "0x5d3eaa66AE01F1a907c8e0970D1D021C6Ff8EB26";
+const AGENT = "0xCC8c44AD3dc2A58D841c3EB26131E49b22665EF8";
+const BRIDGE = "0x6a6827094a5809Df44b32adBEf26F233614F12c4";
+
+let signed = 0;
+let observedFeeUsd = 0.01; // what the SDK's 402 quote settled at
+let postBehaviour: () => Promise<unknown> = async () => ({ success: true, deposit: { txHash: "0xDEP" } });
+let stateFile: Record<string, unknown> = {};
+
+class APIError extends Error {
+  constructor(message: string, readonly statusCode: number) { super(message); this.name = "APIError"; }
+}
+
+mock.module("axios", { defaultExport: { post: async () => ({ data: { address: { evm: BRIDGE } } }) } });
+mock.module("@blockrun/llm", {
+  namedExports: {
+    createPaymentPayload: async () => { signed++; return "BASE64"; },
+    BlockrunClient: class {
+      sessionTotalUsd = 0;
+      getSpending() { return { totalUsd: this.sessionTotalUsd, calls: 1 }; }
+      async post() {
+        const out = await postBehaviour();
+        this.sessionTotalUsd += observedFeeUsd; // the SDK settles the quote on a 2xx
+        return out;
+      }
+    },
+  },
+});
+mock.module("../src/utils/wallet.js", {
+  namedExports: {
+    getApiBase: () => "https://blockrun.ai/api",
+    resolveGatewayUrl: (u: string) => u,
+    getOrCreateWalletKey: () => "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
+    getChainBalance: async () => 100,
+    getChain: () => "base",
+  },
+});
+mock.module("../src/utils/polymarket/client.js", { namedExports: { getPolymarketAccount: () => ({ address: AGENT }) } });
+mock.module("../src/utils/polymarket/positions.js", { namedExports: { getFundsAddress: () => VAULT } });
+mock.module("../src/utils/polymarket/setup.js", { namedExports: { getPublicClient: () => ({ getCode: async () => "0x60006000" }) } });
+mock.module("../src/utils/polymarket/creds.js", {
+  namedExports: {
+    loadState: () => ({ ...stateFile }),
+    saveState: (patch: Record<string, unknown>) => { stateFile = { ...stateFile, ...patch }; return stateFile; },
+  },
+});
+
+const { fundVault } = await import("../src/utils/polymarket/fund.js");
+
+function freshBudget(limit: number | null = null): BudgetState {
+  return { limit, spent: 0, calls: 0, agents: new Map() };
+}
+
+function reset() {
+  signed = 0;
+  observedFeeUsd = 0.01;
+  stateFile = {};
+  postBehaviour = async () => ({ success: true, deposit: { txHash: "0xDEP" } });
+}
+
+test("a confirmed funding call books the fee the gateway settled", async () => {
+  reset();
+  const budget = freshBudget();
+  const res = await fundVault({ amount_usd: 5, confirm: true, budget, agent_id: "bot" });
+  assert.equal(res.isError, undefined, res.text);
+  assert.ok(Math.abs(budget.spent - 0.01) < 1e-9, `spent ${budget.spent}`);
+  assert.equal(budget.calls, 1);
+});
+
+test("a re-priced route is booked at what the SDK observed, not the $0.01 constant", async () => {
+  reset();
+  observedFeeUsd = 0.03;
+  const budget = freshBudget();
+  await fundVault({ amount_usd: 5, confirm: true, budget });
+  assert.ok(Math.abs(budget.spent - 0.03) < 1e-9, `spent ${budget.spent}`);
+});
+
+test("a budget cap that the fee would cross refuses BEFORE signing the authorization", async () => {
+  reset();
+  const budget = freshBudget(0.005);
+  const res = await fundVault({ amount_usd: 5, confirm: true, budget });
+  assert.equal(res.isError, true);
+  assert.match(res.text, /budget|cap/i);
+  assert.equal(signed, 0, "no EIP-3009 authorization may be signed past the cap");
+  assert.equal(budget.spent, 0, "a refused gate leaves no reservation");
+});
+
+test("a delegated agent's own cap is enforced and its spend attributed", async () => {
+  reset();
+  const budget = freshBudget();
+  const { delegateAgent } = await import("../src/utils/budget.js");
+  delegateAgent(budget, "bot", 0.015);
+  const first = await fundVault({ amount_usd: 5, confirm: true, budget, agent_id: "bot" });
+  assert.equal(first.isError, undefined, first.text);
+  const second = await fundVault({ amount_usd: 5, confirm: true, budget, agent_id: "bot" });
+  assert.equal(second.isError, true, "the second $0.01 would take the agent to $0.02 > $0.015");
+  assert.equal(signed, 1);
+  assert.ok(Math.abs((budget.agents.get("bot")?.spent ?? 0) - 0.01) < 1e-9);
+});
+
+test("a definite 4xx books nothing — the gateway rejected before charging", async () => {
+  reset();
+  postBehaviour = async () => { throw new APIError("HTTP 400", 400); };
+  const budget = freshBudget();
+  const res = await fundVault({ amount_usd: 5, confirm: true, budget });
+  assert.equal(res.isError, true);
+  assert.equal(budget.spent, 0);
+});
+
+test("an unknown outcome books the fee estimate — the fee payment left with the request", async () => {
+  reset();
+  postBehaviour = async () => { throw Object.assign(new Error("aborted"), { name: "AbortError" }); };
+  const budget = freshBudget();
+  const res = await fundVault({ amount_usd: 5, confirm: true, budget });
+  assert.equal(res.isError, true);
+  assert.match(res.text, /outcome UNKNOWN/i);
+  assert.ok(Math.abs(budget.spent - 0.01) < 1e-9, `spent ${budget.spent}`);
+});
+
+test("a dry-run reserves and books nothing", async () => {
+  reset();
+  const budget = freshBudget(0.005); // even under a cap the fee would cross
+  const res = await fundVault({ amount_usd: 5, budget });
+  assert.equal(res.isError, undefined, res.text);
+  assert.match(res.text, /DRY RUN/);
+  assert.equal(budget.spent, 0);
+});
+
+test("without a budget (legacy wiring) behaviour is unchanged", async () => {
+  reset();
+  const res = await fundVault({ amount_usd: 5, confirm: true });
+  assert.equal(res.isError, undefined, res.text);
+  assert.equal(signed, 1);
+});
+
+// Audit round 4: the registrar accepted a ledger the handler never passed, so
+// the fee booking above existed only in this file. Pin the wiring itself.
+test("mcp-handler hands the budget ledger to the polymarket registrar", async () => {
+  const { readFileSync } = await import("node:fs");
+  const src = readFileSync(new URL("../src/mcp-handler.ts", import.meta.url), "utf8");
+  assert.match(src, /registerPolymarketTool\(server, budget\)/, "fund's fee is reserved and booked only when the ledger reaches the tool");
+});
diff --git a/test/polymarket-fund-unknown.test.ts b/test/polymarket-fund-unknown.test.ts
new file mode 100644
index 0000000..16f8d4e
--- /dev/null
+++ b/test/polymarket-fund-unknown.test.ts
@@ -0,0 +1,180 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// action:"fund" signs a 300s EIP-3009 authorization for the FULL amount, then
+// POSTs it to /v1/polymarket/fund, which forwards it to the CDP facilitator.
+// A timeout, a 5xx, or a success:false that arrives AFTER the gateway forwarded
+// it used to render as a bare "Funding failed" — an invitation to retry, and a
+// retry signs a SECOND full transfer while the first authorization is still
+// executable. withdraw.ts got exactly this guard in 0.49.0 (pendingWithdraw +
+// WITHDRAW_GUIDANCE); this is the same guard for fund (audit round 3,
+// CRITIC-fund): outcome-unknown wording, and a persisted pendingFund that
+// refuses a re-sign inside the authorization's validity window.
+import { test, mock } from "node:test";
+import assert from "node:assert/strict";
+import { outcomeIsUnknown } from "../apps/order-safety.js";
+
+const VAULT = "0x5d3eaa66AE01F1a907c8e0970D1D021C6Ff8EB26";
+const AGENT = "0xCC8c44AD3dc2A58D841c3EB26131E49b22665EF8";
+const BRIDGE = "0x6a6827094a5809Df44b32adBEf26F233614F12c4";
+
+let signed = 0;
+let postBehaviour: () => Promise<unknown> = async () => ({ success: true, deposit: { txHash: "0xDEPOSITTX" }, fee: { txHash: "0xFEETX" } });
+let stateFile: Record<string, unknown> = {};
+
+/** @blockrun/llm's APIError: `statusCode` property, bare message. */
+class APIError extends Error {
+  constructor(message: string, readonly statusCode: number, readonly response?: unknown) {
+    super(message);
+    this.name = "APIError";
+  }
+}
+class PaymentError extends Error {
+  constructor(message: string) { super(message); this.name = "PaymentError"; }
+}
+
+mock.module("axios", {
+  defaultExport: { post: async () => ({ data: { address: { evm: BRIDGE } } }) },
+});
+mock.module("@blockrun/llm", {
+  namedExports: {
+    createPaymentPayload: async () => { signed++; return "BASE64_DEPOSIT_PAYLOAD"; },
+    BlockrunClient: class {
+      sessionTotalUsd = 0;
+      getSpending() { return { totalUsd: 0, calls: 0 }; }
+      async post() { return postBehaviour(); }
+    },
+  },
+});
+mock.module("../src/utils/wallet.js", {
+  namedExports: {
+    getApiBase: () => "https://blockrun.ai/api",
+    resolveGatewayUrl: (u: string) => u,
+    getOrCreateWalletKey: () => "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
+    getChainBalance: async () => 100,
+  },
+});
+mock.module("../src/utils/polymarket/client.js", {
+  namedExports: { getPolymarketAccount: () => ({ address: AGENT }) },
+});
+mock.module("../src/utils/polymarket/positions.js", {
+  namedExports: { getFundsAddress: () => VAULT },
+});
+mock.module("../src/utils/polymarket/setup.js", {
+  namedExports: { getPublicClient: () => ({ getCode: async () => "0x60006000" }) },
+});
+mock.module("../src/utils/polymarket/creds.js", {
+  namedExports: {
+    loadState: () => ({ ...stateFile }),
+    saveState: (patch: Record<string, unknown>) => { stateFile = { ...stateFile, ...patch }; return stateFile; },
+  },
+});
+
+const { fundVault, FUND_AUTH_VALIDITY_SECS } = await import("../src/utils/polymarket/fund.js");
+
+function reset() {
+  signed = 0;
+  stateFile = {};
+  postBehaviour = async () => ({ success: true, deposit: { txHash: "0xDEPOSITTX" }, fee: { txHash: "0xFEETX" } });
+}
+
+function assertUnknown(text: string) {
+  assert.match(text, /outcome UNKNOWN|MAY (already )?have been (forwarded|broadcast|submitted)/i, text);
+  assert.match(text, /basescan|Base wallet balance|deposit-wallet balance|action:"setup"/i, "must say where to check");
+  assert.match(text, /before (any )?retry|Do NOT retry/i);
+  assert.doesNotMatch(text, /^Funding failed:/);
+  assert.equal(outcomeIsUnknown(text), true, `the order card would treat this as 'nothing moved': ${text}`);
+}
+
+test("a timeout after the POST left is outcome-unknown and arms pendingFund", async () => {
+  reset();
+  postBehaviour = async () => { throw Object.assign(new Error("The operation was aborted"), { name: "AbortError" }); };
+  const res = await fundVault({ amount_usd: 5, confirm: true });
+  assert.equal(res.isError, true);
+  assertUnknown(res.text);
+  assert.match(res.text, /\$5\.00/);
+  const pending = stateFile.pendingFund as { amountUsd: number; deadline: number } | undefined;
+  assert.ok(pending, "pendingFund must be persisted");
+  assert.equal(pending.amountUsd, 5);
+  const now = Math.floor(Date.now() / 1000);
+  assert.ok(pending.deadline >= now + FUND_AUTH_VALIDITY_SECS - 5 && pending.deadline <= now + FUND_AUTH_VALIDITY_SECS + 5, `deadline ${pending.deadline} vs now ${now}`);
+  assert.equal((res.structured as { outcome?: string }).outcome, "unknown");
+});
+
+test("a gateway 5xx after payment is outcome-unknown too", async () => {
+  reset();
+  postBehaviour = async () => { throw new APIError("POST /v1/polymarket/fund failed after payment: HTTP 502", 502, { error: "bad gateway" }); };
+  const res = await fundVault({ amount_usd: 5, confirm: true });
+  assert.equal(res.isError, true);
+  assertUnknown(res.text);
+  assert.match(res.text, /502/);
+  assert.ok(stateFile.pendingFund);
+});
+
+test("success:false with HTTP 200 is outcome-unknown — the gateway may have forwarded before failing", async () => {
+  reset();
+  postBehaviour = async () => ({ success: false, error: "facilitator timeout" });
+  const res = await fundVault({ amount_usd: 5, confirm: true });
+  assert.equal(res.isError, true);
+  assertUnknown(res.text);
+  assert.match(res.text, /facilitator timeout/);
+  assert.ok(stateFile.pendingFund);
+});
+
+test("inside the validity window a second confirm refuses to sign — no second authorization", async () => {
+  reset();
+  postBehaviour = async () => { throw new APIError("HTTP 504", 504); };
+  await fundVault({ amount_usd: 5, confirm: true });
+  assert.equal(signed, 1);
+  postBehaviour = async () => ({ success: true, deposit: { txHash: "0xSECOND" } });
+  const res = await fundVault({ amount_usd: 5, confirm: true });
+  assert.equal(res.isError, true);
+  assert.match(res.text, /previous funding|may still (execute|be executed|land)/i);
+  assert.match(res.text, /refus/i);
+  assert.equal(signed, 1, "the guard must fire BEFORE createPaymentPayload");
+  assert.ok(stateFile.pendingFund, "the guard stays armed");
+});
+
+test("the guard never blocks a dry-run", async () => {
+  reset();
+  stateFile = { pendingFund: { amountUsd: 5, deadline: Math.floor(Date.now() / 1000) + 200 } };
+  const res = await fundVault({ amount_usd: 5 });
+  assert.equal(res.isError, undefined, res.text);
+  assert.match(res.text, /DRY RUN/);
+  assert.match(res.text, /previous funding|outcome unknown|pending/i, "the dry-run still warns about the unresolved one");
+  assert.equal(signed, 0);
+});
+
+test("past the deadline (plus grace) the guard clears and funding proceeds", async () => {
+  reset();
+  stateFile = { pendingFund: { amountUsd: 5, deadline: Math.floor(Date.now() / 1000) - 120 } };
+  const res = await fundVault({ amount_usd: 5, confirm: true });
+  assert.equal(res.isError, undefined, res.text);
+  assert.equal(signed, 1);
+  assert.equal(stateFile.pendingFund, undefined, "cleared after a confirmed submit");
+});
+
+test("a definite 4xx from the gateway proves nothing was forwarded: plain failure, guard cleared", async () => {
+  reset();
+  postBehaviour = async () => { throw new APIError("POST /v1/polymarket/fund failed after payment: HTTP 400", 400, { error: "invalid authorization" }); };
+  const res = await fundVault({ amount_usd: 5, confirm: true });
+  assert.equal(res.isError, true);
+  assert.match(res.text, /Funding (failed|error)/);
+  assert.doesNotMatch(res.text, /outcome UNKNOWN/i);
+  assert.equal(stateFile.pendingFund, undefined, "a rejected submit must not wedge the next call");
+});
+
+test("a rejected x402 fee payment (PaymentError) never reached the fund logic: plain failure", async () => {
+  reset();
+  postBehaviour = async () => { throw new PaymentError("Payment was rejected. Check your wallet balance."); };
+  const res = await fundVault({ amount_usd: 5, confirm: true });
+  assert.equal(res.isError, true);
+  assert.doesNotMatch(res.text, /outcome UNKNOWN/i);
+  assert.equal(stateFile.pendingFund, undefined);
+});
+
+test("a confirmed submit clears the guard", async () => {
+  reset();
+  const res = await fundVault({ amount_usd: 5, confirm: true });
+  assert.equal(res.isError, undefined, res.text);
+  assert.equal(stateFile.pendingFund, undefined);
+});
diff --git a/test/polymarket-fund.test.ts b/test/polymarket-fund.test.ts
index 7b7e71f..96bf363 100644
--- a/test/polymarket-fund.test.ts
+++ b/test/polymarket-fund.test.ts
@@ -46,6 +46,15 @@ mock.module("../src/utils/polymarket/positions.js", {
 mock.module("../src/utils/polymarket/setup.js", {
   namedExports: { getPublicClient: () => ({ getCode: async () => vaultCode }) },
 });
+// fund consults the pendingFund guard (test/polymarket-fund-unknown.test.ts);
+// keep it off the real ~/.blockrun/.polymarket.json.
+let stateFile: Record<string, unknown> = {};
+mock.module("../src/utils/polymarket/creds.js", {
+  namedExports: {
+    loadState: () => ({ ...stateFile }),
+    saveState: (patch: Record<string, unknown>) => { stateFile = { ...stateFile, ...patch }; return stateFile; },
+  },
+});
 
 const { fundVault } = await import("../src/utils/polymarket/fund.js");
 
diff --git a/test/polymarket-preview-bound.test.ts b/test/polymarket-preview-bound.test.ts
new file mode 100644
index 0000000..8d1abf4
--- /dev/null
+++ b/test/polymarket-preview-bound.test.ts
@@ -0,0 +1,164 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// The previewed worst fill is the DEFAULT bound at confirm (audit round 3,
+// C39). Before this, the cross-call bound existed only as an opt-in
+// `max_fill_price`, and the documented agent flow — preview through
+// blockrun_polymarket_read, quote the user "at most 40¢", re-call
+// blockrun_polymarket with confirm:true — never passed it: the confirm
+// re-walked a fresh book and signed at whatever it found, the price the user
+// had explicitly not consented to. Only the MCP-Apps order card carried the
+// bound. Now the preview records its worst fill per (token, side) and a bare
+// confirm is held to it; a moved book refuses and says to re-preview.
+import { test, mock } from "node:test";
+import assert from "node:assert/strict";
+
+type Call = { kind: "limit" | "market"; order: Record<string, unknown> };
+const calls: Call[] = [];
+let asks: Array<{ price: string; size: string }> = [{ price: "0.40", size: "100" }];
+let bids: Array<{ price: string; size: string }> = [{ price: "0.39", size: "100" }];
+
+const fakeClob = {
+  getOrderBook: async () => ({ tick_size: "0.01", neg_risk: false, min_order_size: "5", asks, bids }),
+  createAndPostOrder: async (order: Record<string, unknown>) => {
+    calls.push({ kind: "limit", order });
+    return { success: true, orderID: "0xORDER", status: "matched" };
+  },
+  createAndPostMarketOrder: async (order: Record<string, unknown>) => {
+    calls.push({ kind: "market", order });
+    return { success: true, orderID: "0xMKT", status: "matched" };
+  },
+};
+
+mock.module("../src/utils/polymarket/client.js", {
+  namedExports: {
+    getClobClient: async () => fakeClob,
+    checkGeoblock: async () => ({ orderPlacement: "permitted", country: "FI", ip: null, raw: {} }),
+    getPolymarketAccount: () => ({ address: "0xEOA0000000000000000000000000000000000000" }),
+    resetClobClient: () => {},
+  },
+});
+// Gamma metadata lookup for a bare token_id — keep it off the network.
+mock.module("../src/utils/http.js", {
+  namedExports: { fetchWithTimeout: async () => ({ ok: false }), isTimeoutError: () => false },
+});
+
+const { executeTrade } = await import("../src/utils/polymarket/orders.js");
+
+function lastOrder(): Record<string, unknown> {
+  return calls[calls.length - 1].order;
+}
+
+test("a bare confirm after a preview is refused when the book moved past the previewed worst fill", async () => {
+  asks = [{ price: "0.40", size: "100" }];
+  const preview = await executeTrade({ action: "buy", token_id: "T1", amount_usd: 5 });
+  assert.equal(preview.isError, undefined, preview.text);
+  assert.equal((preview.structured as { worstFillPrice: number }).worstFillPrice, 0.4);
+  // The preview itself tells the agent the bound is the confirm's limit.
+  assert.match(preview.text, /0\.4\b.*limit|limit.*0\.4\b/s);
+
+  asks = [{ price: "0.55", size: "100" }]; // the cheap level is lifted before the confirm
+  const before = calls.length;
+  // Exactly what the skill prescribes: the same call plus confirm:true, no max_fill_price.
+  const res = await executeTrade({ action: "buy", token_id: "T1", amount_usd: 5, order_type: "FOK", confirm: true });
+  assert.equal(res.isError, true, res.text);
+  assert.match(res.text, /book moved/i);
+  assert.match(res.text, /0\.55/);
+  assert.match(res.text, /0\.4\b/);
+  assert.match(res.text, /nothing was charged/i);
+  assert.match(res.text, /re-?preview|preview again|confirm:false/i, "the refusal must say how to get a fresh quote");
+  assert.equal((res.structured as { refused?: string }).refused, "worse_than_quoted");
+  assert.equal((res.structured as { boundSource?: string }).boundSource, "preview");
+  assert.equal(calls.length, before, "nothing may be signed");
+});
+
+test("a bare confirm on an unmoved book signs at the previewed worst fill", async () => {
+  asks = [{ price: "0.40", size: "100" }];
+  await executeTrade({ action: "buy", token_id: "T2", amount_usd: 5 });
+  const before = calls.length;
+  const res = await executeTrade({ action: "buy", token_id: "T2", amount_usd: 5, confirm: true });
+  assert.equal(res.isError, undefined, res.text);
+  assert.equal(calls.length, before + 1);
+  assert.equal(lastOrder().price, 0.4);
+});
+
+test("a book that moved in the user's favour places, signed no worse than the previewed bound", async () => {
+  asks = [{ price: "0.40", size: "100" }];
+  await executeTrade({ action: "buy", token_id: "T3", amount_usd: 5 });
+  asks = [{ price: "0.30", size: "100" }];
+  const before = calls.length;
+  const res = await executeTrade({ action: "buy", token_id: "T3", amount_usd: 5, confirm: true });
+  assert.equal(res.isError, undefined, res.text);
+  assert.equal(calls.length, before + 1);
+  const signed = lastOrder().price as number;
+  assert.ok(signed <= 0.4, `signed ${signed} must not exceed the previewed 0.4`);
+});
+
+test("a fresh preview replaces the bound — re-preview then confirm goes through at the new figure", async () => {
+  asks = [{ price: "0.40", size: "100" }];
+  await executeTrade({ action: "buy", token_id: "T4", amount_usd: 5 });
+  asks = [{ price: "0.55", size: "100" }];
+  const refused = await executeTrade({ action: "buy", token_id: "T4", amount_usd: 5, confirm: true });
+  assert.equal(refused.isError, true);
+  const again = await executeTrade({ action: "buy", token_id: "T4", amount_usd: 5 });
+  assert.equal((again.structured as { worstFillPrice: number }).worstFillPrice, 0.55);
+  const before = calls.length;
+  const res = await executeTrade({ action: "buy", token_id: "T4", amount_usd: 5, confirm: true });
+  assert.equal(res.isError, undefined, res.text);
+  assert.equal(calls.length, before + 1);
+  assert.equal(lastOrder().price, 0.55);
+});
+
+test("an explicit max_fill_price overrides the previewed bound in both directions", async () => {
+  asks = [{ price: "0.40", size: "100" }];
+  await executeTrade({ action: "buy", token_id: "T5", amount_usd: 5 });
+  asks = [{ price: "0.55", size: "100" }];
+  const before = calls.length;
+  // The caller widens the bound on purpose: the walk at 0.55 is within 0.60.
+  const ok = await executeTrade({ action: "buy", token_id: "T5", amount_usd: 5, confirm: true, max_fill_price: 0.6 });
+  assert.equal(ok.isError, undefined, ok.text);
+  assert.equal(calls.length, before + 1);
+  // …and tightens it: 0.55 is worse than 0.50 even though the preview is stale.
+  const refused = await executeTrade({ action: "buy", token_id: "T5", amount_usd: 5, confirm: true, max_fill_price: 0.5 });
+  assert.equal(refused.isError, true);
+  assert.equal((refused.structured as { boundSource?: string }).boundSource, "max_fill_price");
+  assert.equal(calls.length, before + 1);
+});
+
+test("the bound is per (token, side): a sell preview does not bound a buy, and a sell is bounded as a floor", async () => {
+  asks = [{ price: "0.60", size: "100" }];
+  bids = [{ price: "0.45", size: "100" }];
+  const preview = await executeTrade({ action: "sell", token_id: "T6", size: 10 });
+  assert.equal((preview.structured as { worstFillPrice: number }).worstFillPrice, 0.45);
+  bids = [{ price: "0.35", size: "100" }]; // bids dropped: a LOWER fill is the worse one
+  const before = calls.length;
+  const refused = await executeTrade({ action: "sell", token_id: "T6", size: 10, confirm: true });
+  assert.equal(refused.isError, true, refused.text);
+  assert.match(refused.text, /below/);
+  assert.equal(calls.length, before);
+  // The buy side of the same token was never previewed: no bound, the walk stands.
+  const buy = await executeTrade({ action: "buy", token_id: "T6", amount_usd: 5, confirm: true });
+  assert.equal(buy.isError, undefined, buy.text);
+  assert.equal(calls.length, before + 1);
+  bids = [{ price: "0.39", size: "100" }];
+});
+
+test("a confirm with no preview in this process and no max_fill_price stands on its own walk", async () => {
+  asks = [{ price: "0.55", size: "100" }];
+  const before = calls.length;
+  const res = await executeTrade({ action: "buy", token_id: "T7", amount_usd: 5, confirm: true });
+  assert.equal(res.isError, undefined, res.text);
+  assert.equal(calls.length, before + 1);
+  assert.equal(lastOrder().price, 0.55);
+});
+
+test("limit orders are untouched by the bound — the price is the user's own limit", async () => {
+  asks = [{ price: "0.40", size: "100" }];
+  await executeTrade({ action: "buy", token_id: "T8", amount_usd: 5 }); // a market preview on the same token/side
+  asks = [{ price: "0.55", size: "100" }];
+  const before = calls.length;
+  const res = await executeTrade({ action: "buy", token_id: "T8", price: 0.5, size: 10, confirm: true });
+  assert.equal(res.isError, undefined, res.text);
+  assert.equal(calls.length, before + 1);
+  assert.equal(calls[calls.length - 1].kind, "limit");
+  assert.equal(lastOrder().price, 0.5);
+});
diff --git a/test/polymarket-relayer-batch.test.ts b/test/polymarket-relayer-batch.test.ts
index 01f0355..d5095a0 100644
--- a/test/polymarket-relayer-batch.test.ts
+++ b/test/polymarket-relayer-batch.test.ts
@@ -14,11 +14,13 @@ let getTransactionThrows = false;
 // lost response is `{"error":"connection error"}`, for a rejection
 // `{"error":"request error","status":4xx,...}` (http-helpers/index.js).
 let submitThrows: string | undefined;
+let submitThrowsError: Error | undefined;
 let stateFile: Record<string, unknown> = {};
 const saveStateCalls: Array<Record<string, unknown>> = [];
 
 class FakeRelayClient {
   async executeDepositWalletBatch() {
+    if (submitThrowsError) throw submitThrowsError;
     if (submitThrows) throw new Error(submitThrows);
     return {
       transactionID: "batch-1",
@@ -72,6 +74,7 @@ function reset() {
   txnState = undefined;
   getTransactionThrows = false;
   submitThrows = undefined;
+  submitThrowsError = undefined;
   stateFile = {};
   saveStateCalls.length = 0;
 }
@@ -180,3 +183,35 @@ test("an untracked batch (approvals/wrap) that loses its submit response writes
   assert.equal(saveStateCalls.length, 0, "only withdrawals are double-send-tracked");
   assert.equal(stateFile.pendingWithdraw, undefined);
 });
+
+// --- the double-send guard must arm ONLY when the outcome is unknown (round 2) ---
+
+test("a CLOB ApiError carries its 4xx on a PROPERTY — that is still a definite rejection", async () => {
+  // The SDK sets `.status` and leaves the message bare, so a matcher that only
+  // read the JSON shape armed the lock on an unambiguous refusal and wedged the
+  // user behind a 5-minute deadline for a transfer nothing had signed.
+  reset();
+  submitThrowsError = Object.assign(new Error("request rejected"), { status: 403 });
+  await assert.rejects(
+    sendWalletBatch(CALLS, DEPOSIT, "Withdraw", { trackPendingWithdraw: true }),
+    (err: Error) => {
+      assert.match(err.message, /request rejected/);
+      assert.doesNotMatch(err.message, /Do NOT retry/);
+      return true;
+    },
+  );
+  assert.equal(stateFile.pendingWithdraw, undefined, "a definite 4xx signed nothing");
+});
+
+test("a bare HTTP 403 in the message is a definite rejection too", async () => {
+  reset();
+  submitThrows = "CLOB credential derivation failed: HTTP 403 (forbidden)";
+  await assert.rejects(
+    sendWalletBatch(CALLS, DEPOSIT, "Withdraw", { trackPendingWithdraw: true }),
+    (err: Error) => {
+      assert.doesNotMatch(err.message, /Do NOT retry/);
+      return true;
+    },
+  );
+  assert.equal(stateFile.pendingWithdraw, undefined);
+});
diff --git a/test/polymarket-relayer-transport.test.ts b/test/polymarket-relayer-transport.test.ts
new file mode 100644
index 0000000..2e63d76
--- /dev/null
+++ b/test/polymarket-relayer-transport.test.ts
@@ -0,0 +1,151 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// Two transport-level facts about the relayer client (audit round 3, D15/D16):
+//
+//  D16 — @polymarket/builder-relayer-client's pollUntilState (what `wait()`
+//        runs) console.logs "Waiting for transaction …" to STDOUT. In the
+//        stdio MCP server stdout IS the JSON-RPC channel, so every deploy,
+//        approval, redeem and withdraw batch injected a non-JSON line into the
+//        protocol stream mid-money-operation. Everything the SDK prints must
+//        reach stderr instead, and console.log must be restored afterwards.
+//
+//  D15 — the SDK builds its own axios instance (`httpClient.instance`), so the
+//        underscore-header bridge and POLYMARKET_CLOB_PROXY agent installed on
+//        the hoisted axios never reached relayer traffic, while client.ts's
+//        comment claimed relayer.ts injected them. getRelayClient must install
+//        both on that instance.
+import { test, mock } from "node:test";
+import assert from "node:assert/strict";
+import axios from "axios";
+
+const AGENT_SENTINEL = { sentinel: "https-proxy-agent" };
+let proxyAgent: unknown = null;
+const bridgedInstances: unknown[] = [];
+let waitResult: { transactionHash?: string } | undefined = { transactionHash: "0x" + "ab".repeat(32) };
+
+class FakeRelayClient {
+  httpClient = { instance: axios.create() };
+  async executeDepositWalletBatch() {
+    console.log("Executing deposit wallet batch (sdk chatter)");
+    return {
+      transactionID: "batch-1",
+      wait: async () => {
+        console.log("Waiting for transaction batch-1 matching states: STATE_MINED,STATE_CONFIRMED...");
+        console.info("Client side request creation took: 0.1 seconds");
+        return waitResult;
+      },
+    };
+  }
+  async deployDepositWallet() {
+    return {
+      transactionID: "deploy-1",
+      wait: async () => { console.log("Waiting for transaction deploy-1 …"); return { transactionHash: "0x" + "cd".repeat(32) }; },
+    };
+  }
+  async getTransaction() {
+    console.log("Transaction not found or not in given states, timing out!");
+    return [{ state: "STATE_NEW" }];
+  }
+}
+
+mock.module("@polymarket/builder-relayer-client", {
+  namedExports: { RelayClient: FakeRelayClient },
+});
+mock.module("../src/utils/polymarket/client.js", {
+  namedExports: {
+    getPolymarketAccount: () => ({ address: "0xCC8c44AD3dc2A58D841c3EB26131E49b22665EF8" }),
+    checkGeoblock: async () => ({ orderPlacement: "permitted", country: "FI", ip: null, raw: {} }),
+    getClobClient: async () => { throw new Error("not used"); },
+    resetClobClient: () => {},
+    getClobProxyAgent: () => proxyAgent,
+    installUnderscoreHeaderBridge: (inst: unknown) => { bridgedInstances.push(inst); },
+  },
+});
+mock.module("../src/utils/polymarket/creds.js", {
+  namedExports: {
+    loadBuilderCreds: () => ({ key: "k", secret: "s", passphrase: "p", createdAt: "" }),
+    saveBuilderCreds: () => {},
+    loadL2Creds: () => null,
+    saveL2Creds: () => {},
+    invalidateL2Creds: () => {},
+    loadDepositWalletForSigner: () => undefined,
+    loadState: () => ({}),
+    saveState: () => ({}),
+  },
+});
+
+proxyAgent = AGENT_SENTINEL; // set before the client is first built (it is cached)
+const { sendWalletBatch, deployDepositWallet, getRelayClient, getRelayerTransactionState } = await import("../src/utils/polymarket/relayer.js");
+const DEPOSIT = "0x5d3eaa66AE01F1a907c8e0970D1D021C6Ff8EB26";
+const CALLS = [{ target: DEPOSIT, value: "0", data: "0x" }] as never;
+
+/** Capture stdout/stderr writes for the duration of `fn`. */
+async function captureStreams<T>(fn: () => Promise<T>): Promise<{ out: string[]; err: string[]; result: T }> {
+  const out: string[] = [];
+  const err: string[] = [];
+  const stdout = mock.method(process.stdout, "write", ((chunk: unknown) => { out.push(String(chunk)); return true; }) as never);
+  const stderr = mock.method(process.stderr, "write", ((chunk: unknown) => { err.push(String(chunk)); return true; }) as never);
+  try {
+    const result = await fn();
+    return { out, err, result };
+  } finally {
+    stdout.mock.restore();
+    stderr.mock.restore();
+  }
+}
+
+test("D16: nothing the SDK prints during a batch reaches stdout — it goes to stderr, and console.log is restored", async () => {
+  const originalLog = console.log;
+  const originalInfo = console.info;
+  waitResult = { transactionHash: "0x" + "ab".repeat(32) };
+  const { out, err, result } = await captureStreams(() => sendWalletBatch(CALLS, DEPOSIT, "Approval batch"));
+  assert.equal(result.transactionHash, "0x" + "ab".repeat(32));
+  assert.deepEqual(out, [], `stdout is the JSON-RPC channel; got: ${JSON.stringify(out)}`);
+  assert.ok(err.some((l) => l.includes("Waiting for transaction batch-1")), `SDK chatter must land on stderr: ${JSON.stringify(err)}`);
+  assert.ok(err.some((l) => l.includes("Executing deposit wallet batch")), "the submit's own log line too");
+  assert.ok(err.some((l) => l.includes("request creation took")), "console.info as well");
+  assert.equal(console.log, originalLog, "console.log must be restored after the batch");
+  assert.equal(console.info, originalInfo, "console.info must be restored after the batch");
+});
+
+test("D16: the poll-timeout path (wait() undefined → getTransaction) is quiet on stdout too", async () => {
+  waitResult = undefined;
+  const { out, err } = await captureStreams(() => sendWalletBatch(CALLS, DEPOSIT, "Redeem").catch((e: Error) => e));
+  assert.deepEqual(out, []);
+  assert.ok(err.some((l) => l.includes("timing out")));
+});
+
+test("D16: deploy and the standalone state lookup are quiet on stdout", async () => {
+  const deploy = await captureStreams(() => deployDepositWallet());
+  assert.equal(deploy.result.transactionHash, "0x" + "cd".repeat(32));
+  assert.deepEqual(deploy.out, []);
+  const state = await captureStreams(() => getRelayerTransactionState("batch-1"));
+  assert.equal(state.result, "STATE_NEW");
+  assert.deepEqual(state.out, []);
+});
+
+test("D16: the redirect is scoped — console.log outside a relayer call is untouched", async () => {
+  const originalLog = console.log;
+  await sendWalletBatch(CALLS, DEPOSIT, "Approval batch").catch(() => undefined);
+  assert.equal(console.log, originalLog);
+  // Two overlapping batches must not leave a swapped console behind when the
+  // first finishes before the second (ref-counted, not last-writer-wins).
+  waitResult = { transactionHash: "0x" + "ab".repeat(32) };
+  await Promise.all([
+    sendWalletBatch(CALLS, DEPOSIT, "A"),
+    sendWalletBatch(CALLS, DEPOSIT, "B"),
+  ]);
+  assert.equal(console.log, originalLog);
+});
+
+test("D15: the relayer's own axios instance gets the underscore-header bridge and the CLOB proxy agent", async () => {
+  const client = (await getRelayClient()) as unknown as FakeRelayClient;
+  const inst = client.httpClient.instance;
+  assert.ok(bridgedInstances.includes(inst), "installUnderscoreHeaderBridge must be called with the relayer's axios instance");
+  assert.equal(inst.defaults.httpsAgent, AGENT_SENTINEL, "POLYMARKET_CLOB_PROXY must apply to relayer traffic");
+  assert.equal(inst.defaults.proxy, false, "axios env-proxy resolution must be off when an explicit agent is set (same as client.ts)");
+  // Idempotent: a second getRelayClient returns the cached client and installs nothing twice.
+  const before = bridgedInstances.length;
+  await getRelayClient();
+  assert.equal(bridgedInstances.length, before);
+});
diff --git a/test/polymarket-setup-ready.test.ts b/test/polymarket-setup-ready.test.ts
new file mode 100644
index 0000000..35e2f66
--- /dev/null
+++ b/test/polymarket-setup-ready.test.ts
@@ -0,0 +1,120 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// setup's `ready` verdict used to ignore the geoblock probe (audit round 3,
+// D17): a blocked egress printed "❌ Region: order placement BLOCKED …"
+// followed by "🎯 Ready to trade" and structured.ready:true — the two fields
+// an agent keys on before funding. It would fund $50 into the vault and only
+// learn the truth from the first buy's 403, with the money now behind a
+// withdraw. ready must be false when any blocking check fails; "unknown" is
+// not a failure (the probe is best-effort) but is reported as such.
+//
+// Same harness as polymarket-setup-rotation.test.ts: relayer, creds, CLOB and
+// viem's public client are all doubles; no network.
+import { test, mock } from "node:test";
+import assert from "node:assert/strict";
+import * as viem from "viem";
+
+const SIGNER = "0xCC8c44AD3dc2A58D841c3EB26131E49b22665EF8";
+const VAULT = "0x5d3eaa66AE01F1a907c8e0970D1D021C6Ff8EB26";
+
+let orderPlacement: "permitted" | "blocked" | "unknown" = "permitted";
+let stateFile: Record<string, unknown> = { depositWallet: VAULT, signer: SIGNER, deployed: true, approvalsDone: true };
+
+mock.module("viem", {
+  namedExports: {
+    ...viem,
+    createPublicClient: () => ({
+      readContract: async ({ functionName }: { functionName: string }) => {
+        if (functionName === "balanceOf") return 25_000_000n; // $25 pUSD
+        if (functionName === "allowance") return viem.maxUint256;
+        if (functionName === "isApprovedForAll") return true;
+        throw new Error(`unexpected readContract ${functionName} (test)`);
+      },
+      getCode: async () => "0x60006000",
+      getBalance: async () => 10n ** 18n, // 1 POL (EOA mode only)
+    }),
+  },
+});
+mock.module("../src/utils/polymarket/client.js", {
+  namedExports: {
+    getPolymarketAccount: () => ({ address: SIGNER }),
+    checkGeoblock: async () => ({ orderPlacement, country: orderPlacement === "blocked" ? "US" : "FI", ip: null, raw: {} }),
+    getClobClient: async () => ({ updateBalanceAllowance: async () => ({}) }),
+    resetClobClient: () => {},
+    getClobProxyAgent: () => null,
+    installUnderscoreHeaderBridge: () => {},
+  },
+});
+mock.module("../src/utils/polymarket/creds.js", {
+  namedExports: {
+    loadState: () => ({ ...stateFile }),
+    saveState: (patch: Record<string, unknown>) => { stateFile = { ...stateFile, ...patch }; return stateFile; },
+    loadDepositWalletForSigner: () => VAULT,
+    loadL2Creds: () => null,
+    saveL2Creds: () => {},
+    invalidateL2Creds: () => {},
+    loadBuilderCreds: () => null,
+    saveBuilderCreds: () => {},
+  },
+});
+mock.module("../src/utils/polymarket/relayer.js", {
+  namedExports: {
+    deriveDepositWallet: async () => VAULT,
+    isDepositWalletDeployed: async () => true,
+    deployDepositWallet: async () => { throw new Error("deploy not expected (test)"); },
+    sendWalletBatch: async () => { throw new Error("sendWalletBatch not expected (test)"); },
+    getRelayerTransactionState: async () => undefined,
+    getRelayClient: async () => { throw new Error("not used"); },
+    BATCH_DEADLINE_SECS: 300,
+  },
+});
+
+const { runSetup } = await import("../src/utils/polymarket/setup.js");
+
+test("everything green and the egress permitted → ready", async () => {
+  orderPlacement = "permitted";
+  const res = await runSetup({ confirm: false });
+  assert.match(res.text, /✅ Region: order placement permitted/);
+  assert.match(res.text, /🎯 Ready to trade/);
+  assert.equal(res.structured.ready, true);
+  assert.equal(res.structured.orderPlacement, "permitted");
+});
+
+test("everything green but the egress BLOCKED → NOT ready, and the report says why", async () => {
+  orderPlacement = "blocked";
+  const res = await runSetup({ confirm: false });
+  assert.match(res.text, /❌ Region: order placement BLOCKED/);
+  assert.doesNotMatch(res.text, /🎯 Ready to trade/, "a blocked egress must not print the green headline");
+  assert.match(res.text, /not ready|blocked/i);
+  assert.equal(res.structured.ready, false, "agents branch on structured.ready before funding");
+  assert.equal(res.structured.orderPlacement, "blocked");
+  // The other checks still read green — the region is the one blocker.
+  assert.equal(res.structured.deployed, true);
+  assert.equal(res.structured.approvalsPending, false);
+  assert.equal(res.structured.credsReady, true);
+});
+
+test("an undeterminable region is not a blocker, but is exposed so an agent can see it", async () => {
+  orderPlacement = "unknown";
+  const res = await runSetup({ confirm: false });
+  assert.match(res.text, /could not determine/);
+  assert.equal(res.structured.ready, true);
+  assert.equal(res.structured.orderPlacement, "unknown");
+});
+
+test("EOA mode applies the same rule", async () => {
+  process.env.POLYMARKET_SIG_TYPE = "0";
+  try {
+    orderPlacement = "blocked";
+    const blocked = await runSetup({ confirm: false });
+    assert.match(blocked.text, /plain EOA mode/);
+    assert.doesNotMatch(blocked.text, /🎯 Ready to trade/);
+    assert.equal(blocked.structured.ready, false);
+    assert.equal(blocked.structured.orderPlacement, "blocked");
+    orderPlacement = "permitted";
+    const ok = await runSetup({ confirm: false });
+    assert.equal(ok.structured.ready, true);
+  } finally {
+    delete process.env.POLYMARKET_SIG_TYPE;
+  }
+});
diff --git a/test/polymarket-setup-rotation.test.ts b/test/polymarket-setup-rotation.test.ts
index e290437..0debaa8 100644
--- a/test/polymarket-setup-rotation.test.ts
+++ b/test/polymarket-setup-rotation.test.ts
@@ -134,3 +134,38 @@ test("same signer, same vault: the persisted flag is still trusted (no extra rel
   assert.ok(!saveStateCalls.some((p) => p.deployed === false), "the flag must not be reset for the same vault");
   assert.equal(stateFile.deployed, true);
 });
+
+// --- the size of the grant is stated before the signature, not after ---
+//
+// The prompt said what the approvals are FOR ("settle YOUR signed orders") and
+// never what they are WORTH: the default is an unlimited pUSD allowance to four
+// spenders. POLYMARKET_BOUNDED_APPROVALS could always cap it; nothing surfaced
+// that at the moment of consent.
+
+test("the pending-approval prompt states the allowance amount and how to bound it", async () => {
+  const { getBoundedApprovalsUsd } = await import("../src/utils/polymarket/constants.js");
+  const saved = process.env.POLYMARKET_BOUNDED_APPROVALS;
+  try {
+    delete process.env.POLYMARKET_BOUNDED_APPROVALS;
+    assert.equal(getBoundedApprovalsUsd(), null, "unset means unlimited — the default this text must disclose");
+
+    process.env.POLYMARKET_BOUNDED_APPROVALS = "250";
+    assert.equal(getBoundedApprovalsUsd(), 250);
+
+    // Garbage must not silently read as a bound the prompt would then claim.
+    for (const bad of ["0", "-5", "abc", ""]) {
+      process.env.POLYMARKET_BOUNDED_APPROVALS = bad;
+      assert.equal(getBoundedApprovalsUsd(), null, `"${bad}" must fall back to unlimited`);
+    }
+  } finally {
+    if (saved === undefined) delete process.env.POLYMARKET_BOUNDED_APPROVALS;
+    else process.env.POLYMARKET_BOUNDED_APPROVALS = saved;
+  }
+
+  // The disclosure itself lives in the setup report; pin both branches' wording
+  // so a future edit cannot quietly drop the amount again.
+  const src = await import("node:fs").then(fs => fs.readFileSync(new URL("../src/utils/polymarket/setup.ts", import.meta.url), "utf8"));
+  assert.match(src, /UNLIMITED pUSD allowance/, "the unlimited branch must name it");
+  assert.match(src, /POLYMARKET_BOUNDED_APPROVALS=<usd> to cap/, "and point at the bound");
+  assert.match(src, /capped at \$\$\{boundedApprovalUsd\.toFixed\(2\)\} per spender/, "the bounded branch must state the cap");
+});
diff --git a/test/polymarket-submit-unknown.test.ts b/test/polymarket-submit-unknown.test.ts
new file mode 100644
index 0000000..2dd93a9
--- /dev/null
+++ b/test/polymarket-submit-unknown.test.ts
@@ -0,0 +1,184 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// A lost or 5xx submit response is NOT a rejection (audit round 3, C40). The
+// CLOB SDK signs the order, posts it, and throws on a dropped socket or a
+// relay 502/504 — shapes that happen AFTER the exchange may have accepted the
+// order (the default egress is a Cloud Run relay in front of the CLOB). The
+// old catch released the session-cap reservation and rendered a bare
+// "Polymarket CLOB error: socket hang up", and the skill tells the agent the
+// message says exactly what to do next — so the agent re-placed, doubling real
+// exposure while the cap saw one order. The relayer withdraw path
+// (sendWalletBatch) and the order card (apps/order-safety.ts) already treated
+// this class as outcome-unknown; the order path was the odd one out.
+import { test, mock } from "node:test";
+import assert from "node:assert/strict";
+import { outcomeIsUnknown } from "../apps/order-safety.js";
+
+type Call = { kind: "limit" | "market" };
+const calls: Call[] = [];
+let limitBehaviour: () => Promise<unknown> = async () => ({ success: true, orderID: "0xORDER", status: "live" });
+let marketBehaviour: () => Promise<unknown> = async () => ({ success: true, orderID: "0xMKT", status: "matched" });
+let refreshBehaviour: () => Promise<unknown> = async () => ({});
+const refreshCalls: unknown[] = [];
+
+/** The CLOB SDK's ApiError: bare message, code on a `.status` PROPERTY, body on `.data`. */
+class ApiError extends Error {
+  status?: number;
+  data?: unknown;
+  constructor(message: string, status?: number, data?: unknown) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.data = data;
+  }
+}
+
+const fakeClob = {
+  getOrderBook: async () => ({
+    tick_size: "0.01", neg_risk: false, min_order_size: "5",
+    asks: [{ price: "0.45", size: "100" }], bids: [{ price: "0.44", size: "100" }],
+  }),
+  createAndPostOrder: async () => { calls.push({ kind: "limit" }); return limitBehaviour(); },
+  createAndPostMarketOrder: async () => { calls.push({ kind: "market" }); return marketBehaviour(); },
+  updateBalanceAllowance: async (args: unknown) => { refreshCalls.push(args); return refreshBehaviour(); },
+};
+
+mock.module("../src/utils/polymarket/client.js", {
+  namedExports: {
+    getClobClient: async () => fakeClob,
+    checkGeoblock: async () => ({ orderPlacement: "permitted", country: "FI", ip: null, raw: {} }),
+    getPolymarketAccount: () => ({ address: "0xEOA0000000000000000000000000000000000000" }),
+    resetClobClient: () => {},
+  },
+});
+mock.module("../src/utils/http.js", {
+  namedExports: { fetchWithTimeout: async () => ({ ok: false }), isTimeoutError: () => false },
+});
+
+const { executeTrade, getSessionLedger } = await import("../src/utils/polymarket/orders.js");
+
+function reset() {
+  calls.length = 0;
+  refreshCalls.length = 0;
+  limitBehaviour = async () => ({ success: true, orderID: "0xORDER", status: "live" });
+  marketBehaviour = async () => ({ success: true, orderID: "0xMKT", status: "matched" });
+  refreshBehaviour = async () => ({});
+}
+
+const LIMIT = { action: "buy" as const, token_id: "L1", price: 0.45, size: 20, confirm: true, agent_id: "bot" }; // $9.00
+const MARKET = { action: "buy" as const, token_id: "M1", amount_usd: 5, confirm: true };
+
+function assertOutcomeUnknownText(text: string, kind: "limit" | "market") {
+  assert.match(text, /MAY (have been accepted|be live|already be live)/i, text);
+  assert.match(text, kind === "limit" ? /action:"orders"/ : /action:"positions"/, text);
+  assert.match(text, /before (you )?(re-?plac|retry)/i, "must steer the agent to check before re-placing");
+  assert.doesNotMatch(text, /^Polymarket CLOB error:/, "not the bare fallthrough");
+  // The order card's re-arm predicate must read this as ambiguous, never as
+  // "nothing was signed" — the same wording rules apps/order-safety.ts pins.
+  assert.equal(outcomeIsUnknown(text), true, `the card would re-arm on: ${text}`);
+}
+
+test("a lost response (no status) on a limit order keeps the reservation and says the order MAY be live", async () => {
+  reset();
+  const before = getSessionLedger();
+  limitBehaviour = async () => { throw new ApiError("socket hang up", undefined, { error: "socket hang up" }); };
+  const res = await executeTrade(LIMIT);
+  assert.equal(res.isError, true);
+  assertOutcomeUnknownText(res.text, "limit");
+  const after = getSessionLedger();
+  assert.equal(after.totalUsd, before.totalUsd + 9, "the possibly-live $9 stays booked against the session cap");
+  assert.equal(after.perAgent.bot ?? 0, (before.perAgent.bot ?? 0) + 9, "…and against the agent");
+  assert.equal(after.count, before.count, "not counted as a confirmed placement");
+  assert.equal(after.unconfirmed, (before.unconfirmed ?? 0) + 1, "counted as unconfirmed");
+  assert.equal((res.structured as { outcome?: string }).outcome, "unknown");
+  assert.equal(calls.length, 1, "no SDK-level retry");
+});
+
+test("a relay 504 on a market order is outcome-unknown too, pointing at positions", async () => {
+  reset();
+  const before = getSessionLedger();
+  marketBehaviour = async () => { throw new ApiError("<html>upstream request timeout</html>", 504, { error: "<html>", status: 504 }); };
+  const res = await executeTrade(MARKET);
+  assert.equal(res.isError, true);
+  assertOutcomeUnknownText(res.text, "market");
+  assert.match(res.text, /504/);
+  const after = getSessionLedger();
+  assert.equal(after.totalUsd, before.totalUsd + 5);
+  assert.equal(after.count, before.count);
+  assert.equal(after.unconfirmed, (before.unconfirmed ?? 0) + 1);
+});
+
+test("a definite 4xx rejection releases the reservation and reads as a plain rejection", async () => {
+  reset();
+  const before = getSessionLedger();
+  limitBehaviour = async () => { throw new ApiError("invalid order payload", 400, { error: "invalid order payload", status: 400 }); };
+  const res = await executeTrade(LIMIT);
+  assert.equal(res.isError, true);
+  assert.doesNotMatch(res.text, /MAY (have been accepted|be live)/i);
+  assert.match(res.text, /invalid order payload/);
+  const after = getSessionLedger();
+  assert.equal(after.totalUsd, before.totalUsd, "a rejected order must not consume session budget");
+  assert.equal(after.unconfirmed ?? 0, before.unconfirmed ?? 0);
+});
+
+test("a 4xx that only appears in the message text is still a definite rejection", async () => {
+  reset();
+  const before = getSessionLedger();
+  limitBehaviour = async () => { throw new Error('{"error":"request error","status":422,"data":"bad tick"}'); };
+  const res = await executeTrade(LIMIT);
+  assert.equal(res.isError, true);
+  assert.doesNotMatch(res.text, /MAY (have been accepted|be live)/i);
+  assert.equal(getSessionLedger().totalUsd, before.totalUsd);
+});
+
+test("an explicit success:false response is a rejection: released, not outcome-unknown", async () => {
+  reset();
+  const before = getSessionLedger();
+  limitBehaviour = async () => ({ success: false, errorMsg: "order rejected by risk" });
+  const res = await executeTrade(LIMIT);
+  assert.equal(res.isError, true);
+  assert.match(res.text, /order rejected by risk/);
+  assert.doesNotMatch(res.text, /MAY (have been accepted|be live)/i);
+  assert.equal(getSessionLedger().totalUsd, before.totalUsd);
+});
+
+test("balance-cache retry: a lost response on the SECOND submit is outcome-unknown", async () => {
+  reset();
+  const before = getSessionLedger();
+  let n = 0;
+  limitBehaviour = async () => {
+    n++;
+    if (n === 1) throw new ApiError("not enough balance / allowance", 400, { error: "not enough balance / allowance", status: 400 });
+    throw new ApiError("ECONNRESET", undefined, { error: "ECONNRESET" });
+  };
+  const res = await executeTrade(LIMIT);
+  assert.equal(res.isError, true);
+  assertOutcomeUnknownText(res.text, "limit");
+  assert.equal(refreshCalls.length, 1, "the cache refresh ran once");
+  assert.equal(calls.length, 2);
+  assert.equal(getSessionLedger().totalUsd, before.totalUsd + 9);
+});
+
+test("balance-cache retry: the refresh itself failing is NOT an unknown order — nothing was re-submitted", async () => {
+  reset();
+  const before = getSessionLedger();
+  limitBehaviour = async () => { throw new ApiError("not enough balance / allowance", 400, { error: "not enough balance / allowance", status: 400 }); };
+  refreshBehaviour = async () => { throw new Error("socket hang up"); };
+  const res = await executeTrade(LIMIT);
+  assert.equal(res.isError, true);
+  assert.doesNotMatch(res.text, /MAY (have been accepted|be live)/i);
+  assert.equal(calls.length, 1, "the second submit never ran");
+  assert.equal(getSessionLedger().totalUsd, before.totalUsd, "released — the one submit was definitely rejected");
+});
+
+test("the unconfirmed booking is visible in the session ledger the success text prints", async () => {
+  reset();
+  const ledgerBefore = getSessionLedger();
+  limitBehaviour = async () => { throw new ApiError("socket hang up"); };
+  await executeTrade(LIMIT);
+  limitBehaviour = async () => ({ success: true, orderID: "0xORDER2", status: "live" });
+  const res = await executeTrade({ ...LIMIT, token_id: "L2" });
+  assert.equal(res.isError, undefined, res.text);
+  assert.match(res.text, /unconfirmed/i, "a later success must keep showing the unresolved order");
+  assert.equal(getSessionLedger().unconfirmed, (ledgerBefore.unconfirmed ?? 0) + 1);
+});
diff --git a/test/polymarket-trade-gating.test.ts b/test/polymarket-trade-gating.test.ts
index 7feccb2..f6f79ba 100644
--- a/test/polymarket-trade-gating.test.ts
+++ b/test/polymarket-trade-gating.test.ts
@@ -137,19 +137,38 @@ test("session cap blocks the order that would cross it", async () => {
   }
 });
 
-test("a failed submit rolls back the reservation (no phantom session spend)", async () => {
+// Round 3 (C40): this used to throw a bare "network blip" and assert the
+// reservation was rolled back — pinning the defect. A throw with no 4xx behind
+// it is a LOST response, and the order may be live; only a definite rejection
+// releases (test/polymarket-submit-unknown.test.ts covers the unknown class).
+test("a REJECTED submit rolls back the reservation (no phantom session spend)", async () => {
   const before = getSessionLedger();
-  const failClob = {
-    ...fakeClob,
-    createAndPostMarketOrder: async () => { throw new Error("network blip"); },
-  };
-  mock.method(fakeClob, "createAndPostMarketOrder", failClob.createAndPostMarketOrder);
+  const rejected = Object.assign(new Error("invalid order"), { status: 400, data: { error: "invalid order", status: 400 } });
+  mock.method(fakeClob, "createAndPostMarketOrder", async () => { throw rejected; });
   try {
     const res = await executeTrade({ action: "buy", token_id: "111", amount_usd: 5, confirm: true });
     assert.equal(res.isError, true);
+    assert.doesNotMatch(res.text, /MAY (have been accepted|be live)/i);
     const after = getSessionLedger();
-    assert.equal(after.totalUsd, before.totalUsd, "failed order must not consume session budget");
-    assert.equal(after.count, before.count, "failed order must not increment the order count");
+    assert.equal(after.totalUsd, before.totalUsd, "rejected order must not consume session budget");
+    assert.equal(after.count, before.count, "rejected order must not increment the order count");
+  } finally {
+    mock.restoreAll();
+  }
+});
+
+test("a submit whose response is LOST keeps the reservation — the order may be live", async () => {
+  const before = getSessionLedger();
+  mock.method(fakeClob, "createAndPostMarketOrder", async () => { throw new Error("network blip"); });
+  try {
+    const res = await executeTrade({ action: "buy", token_id: "111", amount_usd: 5, confirm: true });
+    assert.equal(res.isError, true);
+    assert.match(res.text, /MAY have been accepted/);
+    assert.match(res.text, /action:"positions"/);
+    const after = getSessionLedger();
+    assert.equal(after.totalUsd, before.totalUsd + 5, "a possibly-live order must count against the cap");
+    assert.equal(after.count, before.count, "…but is not a confirmed placement");
+    assert.equal(after.unconfirmed, before.unconfirmed + 1);
   } finally {
     mock.restoreAll();
   }
@@ -334,3 +353,92 @@ test("a FOK market sell the bid book cannot absorb is refused pre-sign, like the
     mock.restoreAll();
   }
 });
+
+// --- the previewed bound, enforced across the preview→confirm boundary ---
+//
+// "Signed at the worst fill you saw" held within ONE call: the walk that
+// produced the preview also set the signed limit. The preview and the confirm
+// are two calls, and the confirm re-walks a fresh book — so a book that moved
+// in between was signed at a price the card never displayed. It moves against
+// you exactly when it matters.
+
+test("a book that moved against the quote is refused, unsigned, when the bound is carried", async () => {
+  mock.method(fakeClob, "getOrderBook", async () => ({
+    tick_size: "0.01", neg_risk: false, min_order_size: "5",
+    asks: [{ price: "0.40", size: "25" }], bids: [{ price: "0.39", size: "100" }],
+  }));
+  const preview = await executeTrade({ action: "buy", token_id: "111", amount_usd: 5 });
+  const quoted = (preview.structured as { worstFillPrice: number }).worstFillPrice;
+  assert.equal(quoted, 0.4);
+
+  // The cheap level is gone by the time the user clicks Confirm.
+  mock.method(fakeClob, "getOrderBook", async () => ({
+    tick_size: "0.01", neg_risk: false, min_order_size: "5",
+    asks: [{ price: "0.55", size: "25" }], bids: [{ price: "0.39", size: "100" }],
+  }));
+  const before = calls.length;
+  const res = await executeTrade({ action: "buy", token_id: "111", amount_usd: 5, confirm: true, max_fill_price: quoted });
+  assert.equal(res.isError, true, res.text);
+  assert.match(res.text, /book moved/);
+  assert.match(res.text, /nothing was charged/i);
+  assert.equal((res.structured as { refused?: string }).refused, "worse_than_quoted");
+  assert.equal(calls.length, before, "nothing may be signed");
+});
+
+test("a book that moved in the user's FAVOUR still places", async () => {
+  mock.method(fakeClob, "getOrderBook", async () => ({
+    tick_size: "0.01", neg_risk: false, min_order_size: "5",
+    asks: [{ price: "0.30", size: "25" }], bids: [{ price: "0.29", size: "100" }],
+  }));
+  const before = calls.length;
+  const res = await executeTrade({ action: "buy", token_id: "111", amount_usd: 5, confirm: true, max_fill_price: 0.4 });
+  assert.equal(res.isError, undefined, res.text);
+  assert.equal(calls.length, before + 1, "a better price is not a reason to refuse");
+});
+
+test("a sell is bounded the other way — a LOWER fill is the worse one", async () => {
+  mock.method(fakeClob, "getOrderBook", async () => ({
+    tick_size: "0.01", neg_risk: false, min_order_size: "5",
+    asks: [{ price: "0.60", size: "100" }], bids: [{ price: "0.45", size: "100" }],
+  }));
+  const before = calls.length;
+  const worse = await executeTrade({ action: "sell", token_id: "111", size: 10, confirm: true, max_fill_price: 0.5 });
+  assert.equal(worse.isError, true, worse.text);
+  assert.match(worse.text, /book moved/);
+  assert.equal(calls.length, before, "nothing signed on a sell below the floor");
+
+  const ok = await executeTrade({ action: "sell", token_id: "111", size: 10, confirm: true, max_fill_price: 0.4 });
+  assert.equal(ok.isError, undefined, ok.text);
+  assert.equal(calls.length, before + 1);
+});
+
+// Round 3 (C39): the bound is no longer opt-in. The documented agent flow —
+// preview, quote the user, re-call with confirm:true and nothing else — never
+// passed max_fill_price, so a moved book was signed at a price the user never
+// consented to. The preview's worst fill is now the default bound at confirm
+// (test/polymarket-preview-bound.test.ts); only a token/side that was never
+// previewed in this process stands on its own walk.
+test("without max_fill_price, the LAST PREVIEW for that token/side is the bound", async () => {
+  mock.method(fakeClob, "getOrderBook", async () => ({
+    tick_size: "0.01", neg_risk: false, min_order_size: "5",
+    asks: [{ price: "0.55", size: "25" }], bids: [{ price: "0.39", size: "100" }],
+  }));
+  const before = calls.length;
+  // Token 111 was previewed at worst fill 0.40 earlier in this file.
+  const res = await executeTrade({ action: "buy", token_id: "111", amount_usd: 5, confirm: true });
+  assert.equal(res.isError, true, res.text);
+  assert.match(res.text, /book moved/);
+  assert.equal(calls.length, before, "a bare confirm past the previewed bound signs nothing");
+});
+
+test("a token/side never previewed in this process stands on its own walk", async () => {
+  mock.method(fakeClob, "getOrderBook", async () => ({
+    tick_size: "0.01", neg_risk: false, min_order_size: "5",
+    asks: [{ price: "0.55", size: "25" }], bids: [{ price: "0.39", size: "100" }],
+  }));
+  const before = calls.length;
+  const res = await executeTrade({ action: "buy", token_id: "999", amount_usd: 5, confirm: true });
+  assert.equal(res.isError, undefined, res.text);
+  assert.equal(calls.length, before + 1);
+  assert.equal(calls[calls.length - 1].order.price, 0.55);
+});
diff --git a/test/quote-guard.test.ts b/test/quote-guard.test.ts
index 6dc47d4..b9413f7 100644
--- a/test/quote-guard.test.ts
+++ b/test/quote-guard.test.ts
@@ -58,3 +58,35 @@ test("the video wrapper adds the Sora/Solana explanation only where it applies",
   assert.throws(() => assertVideoQuoteSane(3, 1, "bytedance/seedance-2.0", "base"), /Retry on Solana/);
   assert.doesNotThrow(() => assertVideoQuoteSane(0.421001, 0.422001, "azure/sora-2", "base"));
 });
+
+// --- blockrun_image's quote guard, which nothing exercised (round 2) ---
+//
+// The guard was added to image.ts in 0.49.0 and deleting it left every test
+// green. These pin the two things the Solana onQuote hook must do — refuse a
+// quote far above the published rate, and let a real one through — using the
+// same figures the gateway quotes.
+test("the image quote guard refuses a substituted product and passes a real one", async () => {
+  const { assertQuoteNearEstimate, QuoteMismatchError } = await import("../src/utils/budget.js");
+  // nano-banana at 1024: $0.01675 estimate. A 2.7x substitution is refused.
+  assert.throws(
+    () => assertQuoteNearEstimate(0.0452, 0.01675, { what: "google/nano-banana image", quotedFor: "Seedance 2.0 Pro video generation (5s)" }),
+    (err: unknown) => {
+      assert.ok(err instanceof QuoteMismatchError);
+      assert.match((err as Error).message, /google\/nano-banana image/);
+      assert.match((err as Error).message, /no charge was made/);
+      return true;
+    },
+  );
+  // A real size-tier difference stays inside the tolerance.
+  assert.doesNotThrow(() => assertQuoteNearEstimate(0.0177, 0.01675, { what: "google/nano-banana image" }));
+  // And the floor keeps a cheap image from reading as a multiple.
+  assert.doesNotThrow(() => assertQuoteNearEstimate(0.03, 0.01675, { what: "x" }));
+});
+
+test("image.ts actually calls the guard on the rail that has a quote", async () => {
+  const { readFileSync } = await import("node:fs");
+  const src = readFileSync(new URL("../src/tools/image.ts", import.meta.url), "utf8");
+  // The Solana helper is the only image rail that surfaces a 402 amount.
+  assert.match(src, /solanaPaidPost\([\s\S]{0,900}onQuote:/, "image must guard the Solana quote");
+  assert.match(src, /assertQuoteNearEstimate\(/, "image must call the shared guard");
+});
diff --git a/test/rail-parity.test.ts b/test/rail-parity.test.ts
new file mode 100644
index 0000000..9a568af
--- /dev/null
+++ b/test/rail-parity.test.ts
@@ -0,0 +1,561 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// THE RAIL-PARITY MATRIX.
+//
+// Round 1 of the 0.49.0 audit was fixed by six agents working in parallel, one
+// per area, and round 2's regressions had a single fingerprint: each agent
+// hardened the rail it was looking at and left its siblings alone. The quote
+// guard landed on video and image but not music and speech; the in-flight
+// booking on Base and the account rail but not Solana, the default chain;
+// music's Solana call passed no onQuote at all, so the guard hook fired against
+// nobody. Every one of those was a real money path, and every one passed CI.
+//
+// Round 3 found the next fingerprint: the first version of this file was a
+// STATIC check — "the source mentions paidRequestInFlight" — and 0.50.0
+// shipped that identifier as dead code in three tools (cleared in a `.finally`
+// before the catch could read it, set on one rail out of three, module-global
+// in realface, armed before the unpaid probe in image). The matrix was green
+// throughout, because a grep cannot tell a guard from its name.
+//
+// So the money cells are now BEHAVIOURAL. For every manual-402 tool and every
+// rail it serves, the HTTP layer is scripted to resolve the 402 / payment step
+// and then reject the request that carries the payment, and the assertions
+// are on what a user would see: the ledger (budget.spent) and the sentence
+// the tool returns. Identifier presence proves nothing here. A handful of
+// static cells remain for the things that ARE structural — the shapes that
+// can never work, and the deliberate division between the tools that see a
+// quote and the seven that let the SDK own the 402.
+import { test, mock, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { BudgetState } from "../src/types.js";
+
+const TOOLS = join(dirname(fileURLToPath(import.meta.url)), "..", "src", "tools");
+const src = (f: string) => readFileSync(join(TOOLS, f), "utf8");
+
+/** A paid tool that performs its OWN 402 (reads the quote, signs the payment). */
+const MANUAL_402 = ["video.ts", "music.ts", "speech.ts", "image.ts", "realface.ts"] as const;
+
+/** Paid tools that hand the whole 402 to the SDK or the account helper. */
+const DELEGATED_402 = ["markets.ts", "exa.ts", "defi.ts", "rpc.ts", "search.ts", "phone.ts", "modal.ts"] as const;
+
+// ---------------------------------------------------------------------------
+// Harness: one process, every rail, switched by two variables. The real
+// utils/solana-402.ts and utils/api-key-call.ts run underneath — only the
+// wire (fetchWithTimeout), the wallet, the auth mode and the SDK's signing
+// primitives are replaced — so a "settle-then-abort" here is the same
+// sequence of fetches the tool issues in production.
+// ---------------------------------------------------------------------------
+type Rail = "base" | "solana" | "account";
+let rail: Rail = "base";
+const TEST_KEY = "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d";
+const SOL_PUBKEY = "So1anaPubkey1111111111111111111111111111111";
+
+function headers(map: Record<string, string> = {}) {
+  const lower = Object.fromEntries(Object.entries(map).map(([k, v]) => [k.toLowerCase(), v]));
+  return { get: (name: string) => lower[name.toLowerCase()] ?? null };
+}
+
+let script: Array<() => unknown> = [];
+let fetchCalls = 0;
+mock.module("../src/utils/http.js", {
+  namedExports: {
+    fetchWithTimeout: async () => {
+      fetchCalls++;
+      const next = script.shift();
+      if (!next) throw new Error("UNEXPECTED_NETWORK_CALL");
+      return next();
+    },
+    // The real predicate, restated: the deadline cases depend on the
+    // "did not complete within" message being classified as a timeout.
+    isTimeoutError: (err: unknown) => {
+      const name = err instanceof Error ? err.name : "";
+      if (name === "AbortError" || name === "TimeoutError") return true;
+      const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+      return msg.includes("abort") || msg.includes("timeout") || msg.includes("timed out") || msg.includes("did not complete within");
+    },
+  },
+});
+// A movable clock: the Base video/music poll loops give up on a deadline, and
+// jumping the clock from inside a scripted poll ends them on the next check
+// instead of after nine minutes of real time.
+const realNow = Date.now;
+let clockOffset = 0;
+mock.method(Date, "now", () => realNow() + clockOffset);
+
+// The Base ImageClient stand-in: the SDK owns that 402, so the only seam is
+// the call itself. `imageSdk` decides whether it answers or drops.
+let imageSdk: () => Promise<{ data: Array<{ url: string }> }> = async () => ({ data: [{ url: "https://blockrun.ai/media/x.png" }] });
+mock.module("../src/utils/wallet.js", {
+  namedExports: {
+    getApiBase: () => (rail === "account" ? "https://api.blockrun.ai" : rail === "solana" ? "https://sol.blockrun.ai/api" : "https://blockrun.ai/api"),
+    resolveGatewayUrl: (u: string) => (u.startsWith("http") ? u : `https://blockrun.ai/api${u.startsWith("/api/") ? u.slice(4) : u}`),
+    getChain: () => (rail === "solana" ? "solana" : "base"),
+    getOrCreateWalletKey: () => {
+      if (rail !== "base") throw new Error(`the EVM wallet must not be touched on the ${rail} rail`);
+      return TEST_KEY;
+    },
+    getWalletInfo: async () => ({ address: rail === "solana" ? SOL_PUBKEY : "0xTEST" }),
+    getImageClient: () => {
+      if (rail !== "base") throw new Error(`the SDK ImageClient must not be used on the ${rail} rail`);
+      return { generate: () => imageSdk(), edit: () => imageSdk() };
+    },
+    resolveSolanaKey: () => (rail === "solana" ? "solana-secret-key" : undefined),
+    solanaKeyUnavailableReason: () => undefined,
+  },
+});
+mock.module("../src/utils/auth.js", {
+  namedExports: {
+    DEFAULT_API_KEY_BASE: "https://api.blockrun.ai",
+    PORTAL_URL: "https://user.blockrun.ai",
+    PORTAL_KEYS_URL: "https://user.blockrun.ai/dashboard/keys",
+    PORTAL_CREDITS_URL: "https://user.blockrun.ai/dashboard/credits",
+    PORTAL_ACTIVITY_URL: "https://user.blockrun.ai/dashboard/activity",
+    getApiKey: () => (rail === "account" ? "brk_live_test" : undefined),
+    getAuthMode: () => (rail === "account" ? "api-key" : "wallet"),
+    isApiKeyMode: () => rail === "account",
+    getApiKeyBase: () => "https://api.blockrun.ai",
+    apiAuthHeaders: () => (rail === "account" ? { Authorization: "Bearer brk_live_test" } : {}),
+    requireWalletMode: (c: string) => (rail === "account" ? `${c} needs wallet mode` : null),
+    resetAuthCache: () => {},
+  },
+});
+mock.module("../src/utils/ssrf.js", {
+  namedExports: { isBlockedFetchHostResolved: async () => false, isBlockedFetchHost: () => false },
+});
+
+// The quote every 402 carries, in micro-USDC, set per tool so it sits inside
+// the quote guard's tolerance — a refused quote would prove nothing about the
+// in-flight booking. `paymentsSigned` is the tripwire for "nothing signed".
+let quotedAmount = "0";
+let paymentsSigned = 0;
+class FakePaymentError extends Error { constructor(m: string) { super(m); this.name = "PaymentError"; } }
+mock.module("@blockrun/llm", {
+  namedExports: {
+    PaymentError: FakePaymentError,
+    SOLANA_NETWORK: "solana:mainnet",
+    SolanaLLMClient: { SOLANA_API_URL: "https://sol.blockrun.ai/api" },
+    createPaymentPayload: async () => { paymentsSigned++; return "0xpaymentpayloadmock"; },
+    createSolanaPaymentPayload: async () => { paymentsSigned++; return "solana-payment-payload"; },
+    solanaKeyToBytes: async () => new Uint8Array(64),
+    solanaPublicKey: async () => SOL_PUBKEY,
+    parsePaymentRequired: () => ({}),
+    extractPaymentDetails: () => ({
+      amount: quotedAmount,
+      recipient: rail === "solana" ? "Recipient111111111111111111111111111111111" : "0x0000000000000000000000000000000000000001",
+      network: rail === "solana" ? "solana:mainnet" : "eip155:8453",
+      resource: { url: "https://blockrun.ai/api/v1/x", description: "BlockRun media" },
+      maxTimeoutSeconds: 600,
+      extra: rail === "solana" ? { feePayer: "FeePayer1111111111111111111111111111111111" } : {},
+    }),
+  },
+});
+
+const { registerVideoTool, estimateVideoCost } = await import("../src/tools/video.js");
+const { registerMusicTool } = await import("../src/tools/music.js");
+const { registerSpeechTool, speechCost } = await import("../src/tools/speech.js");
+const { registerImageTool, estimateCost: estimateImageCost } = await import("../src/tools/image.js");
+const { registerRealfaceTool } = await import("../src/tools/realface.js");
+const { withTxFee } = await import("../src/utils/tx-fee.js");
+const { ledgerFallback } = await import("../src/utils/raw-call.js");
+
+type Register = (server: any, budget: BudgetState) => void;
+function harness(register: Register) {
+  let handler: ((args: Record<string, unknown>) => Promise<any>) | undefined;
+  const server = {
+    registerTool: (_n: string, _c: unknown, h: any) => { handler = h; },
+    server: { getClientCapabilities: () => ({}) },
+  } as any;
+  const budget: BudgetState = { limit: null, spent: 0, calls: 0, agents: new Map() };
+  register(server, budget);
+  return { call: (args: Record<string, unknown>) => handler!(args), budget };
+}
+const text = (res: any) => res.content.map((c: any) => c.text).join("\n");
+const abortError = () => { const e = new Error("This operation was aborted"); e.name = "AbortError"; return e; };
+const resp402 = () => ({ status: 402, ok: false, headers: headers({ "payment-required": "x402 ..." }), json: async () => ({}) });
+const respSubmit202 = (id: string) => () => ({ status: 202, ok: false, headers: headers(), json: async () => ({ id, poll_url: `/api/v1/poll/${id}`, status: "queued" }) });
+const micro = (usd: number) => String(Math.round(usd * 1e6));
+const near = (a: number, b: number) => Math.abs(a - b) < 1e-9;
+
+/**
+ * One row per tool: how to register it, what to call it with, what the gate
+ * reserves, and the scripted wire for "the 402 resolved and then the request
+ * carrying the payment never answered" on each rail. `expect` is what the
+ * ledger must show afterwards, per rail — the quote where one was captured,
+ * the reserve where the rail has none.
+ */
+const ROWS: Array<{
+  name: string;
+  register: Register;
+  args: Record<string, unknown>;
+  reserve: number;
+  /** The Base wire after the paid request has been sent and dropped. */
+  base: () => Array<() => unknown>;
+  /** What Base books on that give-up. */
+  baseBooks: number;
+  /** Text the Base give-up must carry. */
+  baseSays: RegExp;
+}> = [
+  {
+    name: "video",
+    register: registerVideoTool,
+    args: { prompt: "a cube", model: "bytedance/seedance-2.0", duration_seconds: 5 },
+    reserve: estimateVideoCost("bytedance/seedance-2.0", 5),
+    // Base video settles on a completed poll; the paid request that can be
+    // outstanding is the poll. Submit answers, the poll drops, the deadline
+    // passes.
+    base: () => [resp402, respSubmit202("vid_1"), () => { clockOffset += 3_600_000; throw abortError(); }],
+    baseBooks: estimateVideoCost("bytedance/seedance-2.0", 5),
+    baseSays: /MAY have gone through/,
+  },
+  {
+    name: "music",
+    register: registerMusicTool,
+    args: { prompt: "lofi beat", instrumental: true, model: "minimax/music-2.5+" },
+    reserve: withTxFee(0.1575),
+    // Music can settle inline on the submit itself, so a dropped submit is
+    // the outstanding paid request.
+    base: () => [resp402, () => { throw abortError(); }],
+    baseBooks: withTxFee(0.1575),
+    baseSays: /MAY have gone through/,
+  },
+  {
+    name: "speech",
+    register: registerSpeechTool,
+    args: { action: "speak", input: "x".repeat(1000), model: "elevenlabs/flash-v2.5", response_format: "mp3" },
+    reserve: speechCost("elevenlabs/flash-v2.5", "x".repeat(1000)),
+    base: () => [resp402, () => { throw abortError(); }],
+    baseBooks: speechCost("elevenlabs/flash-v2.5", "x".repeat(1000)),
+    baseSays: /MAY have gone through/,
+  },
+  {
+    name: "image",
+    register: registerImageTool,
+    args: { prompt: "a red cube", model: "zai/cogview-4", size: "1024x1024" },
+    reserve: estimateImageCost("zai/cogview-4", "1024x1024"),
+    // The SDK owns Base's 402: the only wire is the SDK call, scripted via
+    // imageSdk below. No fetch is expected.
+    base: () => [],
+    // No quote is visible on this rail, so the give-up books what the ledger
+    // would have booked on success: the observed charge, not the reserve.
+    baseBooks: 0.016751,
+    baseSays: /MAY have gone through/,
+  },
+  {
+    name: "realface",
+    register: registerRealfaceTool,
+    args: { action: "portrait", name: "Ada", image_url: "https://ok.example.com/ada.png" },
+    reserve: withTxFee(0.01),
+    base: () => [resp402, () => { throw abortError(); }],
+    baseBooks: withTxFee(0.01),
+    baseSays: /MAY have gone through/,
+  },
+];
+
+beforeEach(() => {
+  script = []; fetchCalls = 0; paymentsSigned = 0; clockOffset = 0;
+  imageSdk = async () => ({ data: [{ url: "https://blockrun.ai/media/x.png" }] });
+});
+
+// The sentence every give-up must carry, and the one it must not: the
+// charge may stand, here is where to check, and nothing about it being free.
+function assertBooked(res: any, budget: BudgetState, expectUsd: number, says: RegExp, label: string) {
+  const t = text(res);
+  assert.equal(res.isError, true, `${label}: ${t}`);
+  assert.match(t, says, `${label}: the give-up must say the charge may stand — got: ${t}`);
+  assert.match(t, /action:"report"|dashboard\/activity/, `${label}: must say where to check — got: ${t}`);
+  assert.doesNotMatch(t, /No payment was taken|no charge was made/i, `${label}: a dropped paid request cannot promise that`);
+  assert.ok(near(budget.spent, expectUsd), `${label}: expected the ledger to carry $${expectUsd}, got $${budget.spent}`);
+}
+
+// ---------------------------------------------------------------------------
+// Cell 1: settle-then-abort on every rail books the charge and says so.
+// ---------------------------------------------------------------------------
+for (const row of ROWS) {
+  test(`${row.name} on Base: the paid request drops after the signature went out → booked, "may have settled"`, async () => {
+    rail = "base";
+    quotedAmount = micro(row.reserve);
+    script = row.base();
+    if (row.name === "image") imageSdk = async () => { throw abortError(); };
+    const { call, budget } = harness(row.register);
+    const res = await call(row.args);
+    assertBooked(res, budget, row.baseBooks, row.baseSays, `${row.name}/base`);
+    assert.equal(script.length, 0, "every scripted response was consumed");
+  });
+
+  test(`${row.name} on Solana: the paid request drops after the SPL transfer was signed → booked, "may have settled"`, async () => {
+    rail = "solana";
+    // The Solana gateway prices carry a small markup: a distinct figure proves
+    // the QUOTE is booked, not the reserve.
+    const solQuote = row.reserve + 0.0005;
+    quotedAmount = micro(solQuote);
+    script = [resp402, () => { throw abortError(); }];
+    const { call, budget } = harness(row.register);
+    const res = await call(row.args);
+    assert.equal(paymentsSigned, 1, `${row.name}/solana: exactly one transfer signed`);
+    assertBooked(res, budget, solQuote, /MAY have (gone through|settled)/, `${row.name}/solana`);
+    assert.equal(script.length, 0, "every scripted response was consumed");
+  });
+
+  test(`${row.name} on the account rail: the Bearer request drops → booked, "may have been billed"`, async () => {
+    rail = "account";
+    script = [() => { throw abortError(); }];
+    const { call, budget } = harness(row.register);
+    const res = await call(row.args);
+    assert.equal(paymentsSigned, 0, "nothing is signed on the account rail");
+    assertBooked(res, budget, row.reserve, /MAY have (gone through|settled|been accepted)/, `${row.name}/account`);
+    assert.equal(script.length, 0, "every scripted response was consumed");
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Cell 2: a timeout on the UNPAID 402 probe books nothing. Nothing was signed
+// and nothing carried a payment; booking it would invent spend and a "may
+// have settled" here sends the user to check a charge that cannot exist.
+// ---------------------------------------------------------------------------
+for (const row of ROWS) {
+  // The SDK owns Base's 402 for image, and the only seam is the whole call:
+  // a probe timeout inside the SDK is indistinguishable from a paid-retry
+  // timeout, so that rail deliberately books (the conservative direction).
+  if (row.name !== "image") {
+    test(`${row.name} on Base: the unpaid 402 probe times out → nothing booked, nothing signed`, async () => {
+      rail = "base";
+      quotedAmount = micro(row.reserve);
+      script = [() => { throw abortError(); }];
+      const { call, budget } = harness(row.register);
+      const res = await call(row.args);
+      assert.equal(res.isError, true);
+      assert.equal(paymentsSigned, 0, "nothing to sign yet");
+      assert.doesNotMatch(text(res), /MAY have/, `${row.name}/base: a probe timeout is not a maybe — got: ${text(res)}`);
+      assert.equal(budget.spent, 0, `${row.name}/base: probe timeout must not book — spent=${budget.spent}`);
+    });
+  }
+
+  // video and music used to branch on `getChain() === "solana" &&
+  // isTimeoutError` with no in-flight state at all, so they booked the
+  // estimate for a probe that never produced a signature (audit round 3,
+  // D20/C32). They now arm the tracker in onQuote and at the helper's
+  // onPaidRequest hook, so this cell is a real assertion for every row.
+  test(
+    `${row.name} on Solana: the unpaid 402 probe times out → nothing booked, nothing signed`,
+    async () => {
+      rail = "solana";
+      quotedAmount = micro(row.reserve);
+      script = [() => { throw abortError(); }];
+      const { call, budget } = harness(row.register);
+      const res = await call(row.args);
+      assert.equal(res.isError, true);
+      assert.equal(paymentsSigned, 0, "the quote never arrived, so nothing was signed");
+      assert.doesNotMatch(text(res), /MAY have/, `${row.name}/solana: a probe timeout is not a maybe — got: ${text(res)}`);
+      assert.equal(budget.spent, 0, `${row.name}/solana: probe timeout must not book — spent=${budget.spent}`);
+    },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Cell 2b: an ANSWER is never a maybe, whatever its words. The paid request
+// comes back 5xx with a body that says "timeout" — the gateway answered, so
+// nothing is outstanding and nothing is booked as "may have settled". Audit
+// round 4: image's account rail and speech's account rail wrapped a helper
+// that inspects the response and THROWS on it inside sendPaid, so settle()
+// was never reached and the catch classified the error by its prose —
+// isTimeoutError's substring match — and booked a whole render for a
+// not_charged job whose upstream text read "aborted due to timeout". The
+// verdict now comes off the error (a status, a typed job verdict, the
+// gateway's uncharged marker), never its message.
+// ---------------------------------------------------------------------------
+const answered5xx = () => ({ status: 504, ok: false, headers: headers(), json: async () => ({ error: "The operation was aborted due to timeout" }) });
+for (const row of ROWS) {
+  // video's Solana submit answering 5xx is the helper's own "poll error" shape
+  // after a 202; a 5xx ON the submit is covered the same way in the helper.
+  test(`${row.name} on Solana: the paid request is ANSWERED 5xx with "timeout" in the body → nothing booked as a maybe`, async () => {
+    rail = "solana";
+    quotedAmount = micro(row.reserve);
+    script = [resp402, answered5xx];
+    const { call, budget } = harness(row.register);
+    const res = await call(row.args);
+    const t = text(res);
+    assert.equal(res.isError, true, `${row.name}/solana: ${t}`);
+    assert.doesNotMatch(t, /got no answer|booked against your budget as a precaution|has been booked against your budget/, `${row.name}/solana: an answered 5xx is not "no answer" — got: ${t}`);
+    assert.equal(budget.spent, 0, `${row.name}/solana: an answered 5xx books nothing — spent=${budget.spent}`);
+  });
+
+  test(`${row.name} on the account rail: the Bearer request is ANSWERED 5xx with "timeout" in the body → nothing booked as a maybe`, async () => {
+    rail = "account";
+    script = [answered5xx];
+    const { call, budget } = harness(row.register);
+    const res = await call(row.args);
+    const t = text(res);
+    assert.equal(res.isError, true, `${row.name}/account: ${t}`);
+    assert.doesNotMatch(t, /got no answer|booked against your budget/, `${row.name}/account: an answered 5xx is not "no answer" — got: ${t}`);
+    assert.equal(budget.spent, 0, `${row.name}/account: an answered 5xx books nothing — spent=${budget.spent}`);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Cell 3: a Solana quote far above the estimate is refused BEFORE signing, on
+// every manual-402 tool — the 2026-09-08 shape (sol.blockrun.ai quoting a
+// different product at 2.7x). The first matrix checked this per FILE, and
+// speech's Base guard covered for a Solana hook that had none.
+// ---------------------------------------------------------------------------
+for (const row of ROWS) {
+  test(`${row.name} on Solana: a 2.7x quote is refused unsigned — no charge, no booking`, async () => {
+    rail = "solana";
+    quotedAmount = micro(row.reserve * 2.7);
+    script = [resp402];
+    const { call, budget } = harness(row.register);
+    const res = await call(row.args);
+    const t = text(res);
+    assert.equal(res.isError, true, `${row.name}/solana: ${t}`);
+    assert.match(t, /Refusing to sign it|no charge was made/i, `${row.name}/solana: must refuse the quote — got: ${t}`);
+    assert.equal(paymentsSigned, 0, `${row.name}/solana: a refused quote must not be signed`);
+    assert.equal(budget.spent, 0, `${row.name}/solana: a refused quote settles nothing`);
+    assert.equal(script.length, 0, "the paid POST was never issued");
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Cell 4: the happy path books exactly the settled amount, once, on every
+// rail — so the give-up bookings above cannot be "passing" by double-booking.
+// ---------------------------------------------------------------------------
+const HAPPY: Record<string, { body: unknown; account: unknown }> = {
+  video: { body: null, account: null }, // async on every rail; covered by video-money-path / video-solana / api-key-call tests
+  music: { body: { model: "minimax/music-2.5+", data: [{ url: "https://blockrun.ai/media/t.mp3", duration_seconds: 30 }] }, account: null },
+  speech: { body: { model: "elevenlabs/flash-v2.5", data: [{ url: "https://blockrun.ai/media/s.mp3", format: "mp3" }] }, account: null },
+  image: { body: { data: [{ url: "https://blockrun.ai/media/i.png" }] }, account: null },
+  realface: { body: { asset_id: "ta_abc", name: "Ada" }, account: null },
+};
+for (const row of ROWS) {
+  const happy = HAPPY[row.name];
+  if (!happy.body) continue;
+  test(`${row.name} on Solana: a settled 200 books the quote exactly once`, async () => {
+    rail = "solana";
+    const solQuote = row.reserve + 0.0005;
+    quotedAmount = micro(solQuote);
+    script = [resp402, () => ({ status: 200, ok: true, headers: headers({ "x-payment-receipt": "sol-tx" }), json: async () => happy.body })];
+    const { call, budget } = harness(row.register);
+    const res = await call(row.args);
+    assert.notEqual(res.isError, true, text(res));
+    assert.ok(near(budget.spent, solQuote), `${row.name}/solana: spent=${budget.spent}, quote=${solQuote}`);
+  });
+  test(`${row.name} on the account rail: a settled 200 books the cost header exactly once`, async () => {
+    rail = "account";
+    const settled = row.reserve - 0.001; // the account rail bills the base, no tx fee
+    script = [() => ({ status: 200, ok: true, headers: headers({ "x-blockrun-cost-usd": settled.toFixed(6), "x-payment-receipt": "credit:1" }), json: async () => happy.body })];
+    const { call, budget } = harness(row.register);
+    const res = await call(row.args);
+    assert.notEqual(res.isError, true, text(res));
+    assert.ok(near(budget.spent, Number(settled.toFixed(6))), `${row.name}/account: spent=${budget.spent}, header=${settled.toFixed(6)}`);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Static cells. These are structural claims a grep CAN make honestly.
+// ---------------------------------------------------------------------------
+test("no tool clears its in-flight state in a `.finally` on the awaited paid request", () => {
+  // Promise#finally runs its callback BEFORE the rejection reaches the
+  // awaiting catch, so a flag cleared there is always false by the time the
+  // catch reads it. 0.50.0 shipped exactly this in speech, realface and image.
+  for (const f of MANUAL_402) {
+    assert.doesNotMatch(src(f), /\.finally\(\(\) => \{\s*paid\w*InFlight\s*=\s*false/, `${f}: clears the in-flight flag before the catch can see it`);
+    assert.doesNotMatch(src(f), /\.finally\(\(\) => \w+\.settle\(\)\)/, `${f}: settles the tracker before the catch can see it`);
+  }
+});
+
+test("no tool keeps in-flight state at module scope", () => {
+  // The MCP SDK dispatches tool calls concurrently; a shared flag makes one
+  // call's outstanding payment book against another call's failure.
+  for (const f of MANUAL_402) {
+    assert.doesNotMatch(src(f), /^(let|var)\s+paid\w*InFlight\b/m, `${f}: module-global in-flight flag`);
+    assert.doesNotMatch(src(f), /^(let|var|const)\s+\w+\s*=\s*trackPaidRequest\(\)/m, `${f}: module-global paid-request tracker`);
+  }
+});
+
+test("every Solana onQuote hook checks WHAT was quoted, not only how much", () => {
+  // The helper's onQuote is the last stop before the SPL transfer is signed.
+  // Checked per HOOK, not per file: speech's Base branch had the guard and
+  // its Solana hook did not, and the per-file grep could not tell.
+  for (const f of MANUAL_402) {
+    const s = src(f);
+    const hooks = [...s.matchAll(/onQuote:\s*\([^)]*\)\s*=>\s*\{/g)];
+    if (!/solanaPaid(Post|AsyncPost)\(/.test(s)) continue;
+    assert.ok(hooks.length > 0, `${f}: calls the Solana helper without an onQuote guard`);
+    for (const h of hooks) {
+      const body = s.slice(h.index!, h.index! + 1200);
+      if (/onQuote\?\.\(/.test(body)) {
+        // The hook delegates to a caller-supplied callback (realface's shared
+        // payAndPostJson): every such callback must carry the guard instead.
+        const callers = [...s.matchAll(/payAndPostJson\(/g)].filter((m) => !/async function payAndPostJson/.test(s.slice(m.index! - 20, m.index! + 20)));
+        assert.ok(callers.length > 0, `${f}: delegating onQuote hook with no callers to carry the guard`);
+        for (const c of callers) {
+          assert.match(s.slice(c.index!, c.index! + 1200), /assertQuoteNearEstimate\(|assertVideoQuoteSane\(/, `${f}: a payAndPostJson caller supplies an onQuote without checking what was quoted`);
+        }
+        continue;
+      }
+      assert.match(body, /assertQuoteNearEstimate\(|assertVideoQuoteSane\(/, `${f}: an onQuote hook re-reserves without checking what was quoted`);
+    }
+  }
+});
+
+test("no delegated-402 tool pretends to check a quote it cannot see", () => {
+  // The SDK owns their 402 and does not surface the amount, so a guard there
+  // would be theatre. This asserts the DIVISION is deliberate: if one of these
+  // ever grows a quote check, it has moved rails and this table must say so.
+  for (const f of DELEGATED_402) {
+    const s = src(f);
+    assert.doesNotMatch(s, /assertQuoteNearEstimate|assertVideoQuoteSane/, `${f}: grew a quote guard — update the matrix`);
+    assert.doesNotMatch(s, /trackPaidRequest\(/, `${f}: grew in-flight tracking it cannot arm honestly (the SDK owns the paid request) — update the matrix`);
+  }
+});
+
+test("every delegated-402 tool books the observed charge, not its reserve", () => {
+  // The reserve rounds against us on purpose ($0.002 fee where the gateway
+  // charges $0.001 on Base and nothing on Solana). Booking it inflates recorded
+  // spend on every call and trips caps early — up to 2x on the default chain.
+  for (const f of DELEGATED_402) {
+    assert.match(src(f), /ledgerFallback\(/, `${f}: books its reserve as settled spend`);
+  }
+});
+
+test("image's SDK-owned Base rail books the observed charge too", () => {
+  // Live 402 probe of /v1/images/generations on 2026-09-13: cogview-4 quotes
+  // 16750 micro ($0.01675 = base x 1.05 + $0.001) against a $0.017751
+  // reserve. The reserve stays high on purpose; the LEDGER books what is
+  // charged — which is what ledgerFallback reconstructs on every rail.
+  rail = "base";
+  assert.ok(near(ledgerFallback(0.017751), 0.016751), `ledgerFallback(0.017751)=${ledgerFallback(0.017751)}`);
+  assert.match(src("image.ts"), /ledgerFallback\(/, "image.ts Base rail books the reserve");
+});
+
+test("the matrix covers every paid tool in the directory", () => {
+  // The point of a table is that nothing is missing from it. A new paid tool
+  // must be classified, not silently skipped.
+  const classified = new Set<string>([...MANUAL_402, ...DELEGATED_402]);
+  const unclassified: string[] = [];
+  for (const f of readdirSync(TOOLS).filter((n) => n.endsWith(".ts"))) {
+    if (classified.has(f)) continue;
+    const s = src(f);
+    // Free tools and the wallet/chat tools are out of scope by construction:
+    // chat settles per token through the SDK and has its own settled-cost
+    // wrapper; wallet, models, dex and polymarket_read take no payment here.
+    if (!/reserveBudget\(budget/.test(s)) continue;
+    if (["chat.ts", "chat-anthropic.ts", "polymarket.ts", "wallet.ts"].includes(f)) continue;
+    // price.ts reserves but cannot currently pay: the equity route has
+    // answered 501 since 2026-09-05 and the tool short-circuits BEFORE the
+    // reservation (price-behaviour.test.ts pins that). The day the route
+    // returns, its paid path pays through the SDK's PriceClient and books
+    // the reserve — classify it as DELEGATED_402 and route it through
+    // raw-call's ledgerFallback then. The assertion below ties the
+    // exclusion to the reason it is safe: an SDK-direct paid call that has
+    // no quote guard must not be reachable.
+    if (f === "price.ts") {
+      assert.match(s, /501/, "price.ts no longer mentions the 501 short-circuit — classify it in the matrix");
+      assert.doesNotMatch(s, /assertQuoteNearEstimate|trackPaidRequest/, "price.ts grew paid-path treatments — classify it in the matrix");
+      continue;
+    }
+    unclassified.push(f);
+  }
+  assert.deepEqual(unclassified, [], `paid tools missing from the rail-parity matrix: ${unclassified.join(", ")}`);
+});
diff --git a/test/raw-call.test.ts b/test/raw-call.test.ts
new file mode 100644
index 0000000..a3f4772
--- /dev/null
+++ b/test/raw-call.test.ts
@@ -0,0 +1,225 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// raw-call.ts is the rail switch for EIGHT path-based tools (search, exa,
+// markets, rpc, defi, phone, modal, and formerly surf) and it had no test on
+// either rail. It decides two things that are easy to get silently wrong:
+//
+//   1. WHICH rail runs — the SDK's 402 dance, or the account API's Bearer fetch.
+//      Pick wrong and the call is billed to the other payer.
+//   2. What `paidUsd` means — the settled figure on the account rail, and null
+//      (never 0) on a wallet call, because recordActualSpend books the caller's
+//      estimate for null and would book a real charge as FREE for 0.
+//
+// Both rails are mocked here; nothing reaches the network or a wallet.
+import { test, mock, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+
+let apiKeyMode = false;
+let chain: "base" | "solana" = "base";
+mock.module("../src/utils/wallet.js", {
+  namedExports: {
+    getChain: () => chain,
+    getApiBase: () => "https://blockrun.ai/api",
+    resolveGatewayUrl: (u: string) => u,
+  },
+});
+mock.module("../src/utils/auth.js", {
+  namedExports: {
+    isApiKeyMode: () => apiKeyMode,
+    getApiKey: () => (apiKeyMode ? "br_test_key" : undefined),
+    apiAuthHeaders: () => ({ Authorization: "Bearer br_test_key" }),
+    getApiKeyBase: () => "https://api.blockrun.ai",
+    PORTAL_CREDITS_URL: "https://user.blockrun.ai/dashboard/credits",
+  },
+});
+
+const accountCalls: Array<{ verb: string; endpoint: string; arg: unknown }> = [];
+let accountResult: { data: unknown; paidUsd: number | null } = { data: { ok: "account" }, paidUsd: 0.0085 };
+let accountThrows: Error | null = null;
+mock.module("../src/utils/api-key-call.js", {
+  namedExports: {
+    apiKeyGet: async (endpoint: string, params?: Record<string, string>) => {
+      accountCalls.push({ verb: "GET", endpoint, arg: params });
+      if (accountThrows) throw accountThrows;
+      return accountResult;
+    },
+    apiKeyPost: async (endpoint: string, body: Record<string, unknown>) => {
+      accountCalls.push({ verb: "POST", endpoint, arg: body });
+      if (accountThrows) throw accountThrows;
+      return accountResult;
+    },
+  },
+});
+
+const { rawGet, rawPost } = await import("../src/utils/raw-call.js");
+
+const walletCalls: Array<{ verb: string; endpoint: string; arg: unknown }> = [];
+let walletThrows: Error | null = null;
+const walletClient = {
+  getWithPaymentRaw: async (endpoint: string, params?: Record<string, string>) => {
+    walletCalls.push({ verb: "GET", endpoint, arg: params });
+    if (walletThrows) throw walletThrows;
+    return { ok: "wallet" };
+  },
+  requestWithPaymentRaw: async (endpoint: string, body: unknown) => {
+    walletCalls.push({ verb: "POST", endpoint, arg: body });
+    if (walletThrows) throw walletThrows;
+    return { ok: "wallet" };
+  },
+};
+
+beforeEach(() => {
+  apiKeyMode = false;
+  accountCalls.length = 0;
+  walletCalls.length = 0;
+  accountThrows = null;
+  walletThrows = null;
+  accountResult = { data: { ok: "account" }, paidUsd: 0.0085 };
+  chain = "base";
+});
+
+test("wallet mode goes through the SDK and NEVER touches the account API", async () => {
+  const got = await rawGet(walletClient, "/v1/pm/polymarket/markets", { limit: "1" });
+  const posted = await rawPost(walletClient, "/v1/exa/search", { query: "fed" });
+
+  assert.deepEqual(got.data, { ok: "wallet" });
+  assert.deepEqual(posted.data, { ok: "wallet" });
+  assert.equal(accountCalls.length, 0, "the account rail must not be consulted without a key");
+  assert.deepEqual(walletCalls.map(c => c.verb + " " + c.endpoint), [
+    "GET /v1/pm/polymarket/markets",
+    "POST /v1/exa/search",
+  ]);
+  assert.deepEqual(walletCalls[0].arg, { limit: "1" });
+  assert.deepEqual(walletCalls[1].arg, { query: "fed" });
+});
+
+test("a wallet call reports paidUsd null, never 0 — 0 would book a real charge as free", async () => {
+  const got = await rawGet(walletClient, "/v1/defillama/protocols");
+  const posted = await rawPost(walletClient, "/v1/search", { query: "x" });
+  assert.equal(got.paidUsd, null);
+  assert.equal(posted.paidUsd, null);
+  // The distinction recordActualSpend depends on: null means "unknown, use the
+  // estimate", 0 means "this was free" and is BOOKED as $0 — budget.test.ts
+  // pins that side of the contract ("books an explicit settled ZERO as zero").
+  assert.notEqual(got.paidUsd, 0);
+});
+
+test("account mode goes through api-key-call and NEVER touches the SDK client", async () => {
+  apiKeyMode = true;
+  const got = await rawGet(walletClient, "/v1/pm/kalshi/markets", { status: "open" });
+  const posted = await rawPost(walletClient, "/v1/modal/sandbox/exec", { command: ["echo"] });
+
+  assert.deepEqual(got.data, { ok: "account" });
+  assert.deepEqual(posted.data, { ok: "account" });
+  assert.equal(walletCalls.length, 0, "the wallet must not be asked to sign in account mode");
+  assert.deepEqual(accountCalls.map(c => c.verb + " " + c.endpoint), [
+    "GET /v1/pm/kalshi/markets",
+    "POST /v1/modal/sandbox/exec",
+  ]);
+  assert.deepEqual(accountCalls[0].arg, { status: "open" });
+});
+
+test("account mode surfaces the settled cost the header carried", async () => {
+  apiKeyMode = true;
+  accountResult = { data: { ok: "account" }, paidUsd: 0.012 };
+  assert.equal((await rawGet(walletClient, "/v1/phone/lookup")).paidUsd, 0.012);
+
+  // A gateway that priced nothing at response time hands back null, and null
+  // must survive: the caller then books its estimate rather than zero.
+  accountResult = { data: { ok: "account" }, paidUsd: null };
+  assert.equal((await rawPost(walletClient, "/v1/search", { query: "x" })).paidUsd, null);
+
+  // A genuinely free account route reports 0, and 0 must survive too.
+  accountResult = { data: { ok: "account" }, paidUsd: 0 };
+  assert.equal((await rawPost(walletClient, "/v1/phone/numbers/release", {})).paidUsd, 0);
+});
+
+test("an undefined POST body reaches the account rail as {}, not as undefined", async () => {
+  // apiKeyPost types its body as an object; passing undefined through would
+  // JSON.stringify to "undefined" and 400 at the gateway.
+  apiKeyMode = true;
+  await rawPost(walletClient, "/v1/pm/markets/search", undefined);
+  assert.deepEqual(accountCalls[0].arg, {});
+});
+
+test("an undefined POST body is passed through UNCHANGED on the wallet rail", async () => {
+  // The SDK distinguishes an absent body from an empty one; only the account
+  // rail needs the {} coercion, and coercing both would change wallet behaviour.
+  await rawPost(walletClient, "/v1/pm/markets/search", undefined);
+  assert.equal(walletCalls[0].arg, undefined);
+});
+
+test("each rail's failure propagates from that rail alone", async () => {
+  walletThrows = new Error("API error: 502");
+  await assert.rejects(() => rawGet(walletClient, "/v1/exa/search"), /502/);
+  assert.equal(accountCalls.length, 0);
+
+  apiKeyMode = true;
+  walletThrows = null;
+  accountThrows = new Error("BlockRun account API error: 402.");
+  await assert.rejects(() => rawGet(walletClient, "/v1/exa/search"), /402/);
+  assert.equal(walletCalls.length, 1, "only the wallet call from the first half");
+});
+
+test("the rail is decided per call, so switching mid-process routes the next call correctly", async () => {
+  await rawGet(walletClient, "/v1/defillama/protocols");
+  apiKeyMode = true;
+  await rawGet(walletClient, "/v1/defillama/protocols");
+  assert.equal(walletCalls.length, 1);
+  assert.equal(accountCalls.length, 1);
+});
+
+// --- the ledger books the observed charge, not the reserve (round 2) ---
+//
+// tx-fee.ts states the rule at length and one file honoured it. Every path tool
+// passed its RESERVE (base + $0.002, rounded against us on purpose) as
+// recordActualSpend's fallback, and on the wallet rail there is never a settled
+// figure to override it — so the ledger booked the reserve. On Solana, where
+// the gateway charges no fee at all, that is $0.002 of invented spend per call.
+
+test("a Solana wallet call books the BASE, not the reserve", async () => {
+  const { ledgerFallback } = await import("../src/utils/raw-call.js");
+  apiKeyMode = false;
+  chain = "solana";
+  // rpc single: reserve $0.004, Solana charges $0.002.
+  assert.ok(Math.abs(ledgerFallback(0.004) - 0.002) < 1e-9);
+  // pm/*: reserve $0.0095, Solana charges $0.0075.
+  assert.ok(Math.abs(ledgerFallback(0.0095) - 0.0075) < 1e-9);
+});
+
+test("a Base wallet call books the base plus the fee the gateway actually charges", async () => {
+  const { ledgerFallback } = await import("../src/utils/raw-call.js");
+  apiKeyMode = false;
+  chain = "base";
+  assert.ok(Math.abs(ledgerFallback(0.004) - 0.003) < 1e-9, "rpc single: $0.003 on Base");
+  assert.ok(Math.abs(ledgerFallback(0.0095) - 0.0085) < 1e-9, "pm/*: $0.0085 on Base");
+});
+
+test("the account rail books the base — it charges no transaction fee", async () => {
+  const { ledgerFallback } = await import("../src/utils/raw-call.js");
+  apiKeyMode = true;
+  assert.ok(Math.abs(ledgerFallback(0.012) - 0.010) < 1e-9, "phone/lookup: $0.010 on the account rail");
+});
+
+test("free stays free, and the reserve is never converted into a negative", async () => {
+  const { ledgerFallback } = await import("../src/utils/raw-call.js");
+  assert.equal(ledgerFallback(0), 0);
+  assert.equal(ledgerFallback(-1), 0);
+  // A reserve smaller than one fee has no base under it; the result floors at
+  // zero and is clamped to the reserve, never below zero and never above it.
+  chain = "solana";
+  assert.equal(ledgerFallback(0.001), 0);
+  chain = "base";
+  assert.equal(ledgerFallback(0.001), 0.001);
+});
+
+test("the ledger figure is never ABOVE the reserve — the gate stays the conservative one", async () => {
+  const { ledgerFallback } = await import("../src/utils/raw-call.js");
+  for (const chainUnderTest of ["base", "solana"] as const) {
+    chain = chainUnderTest;
+    apiKeyMode = false;
+    for (const reserve of [0.003, 0.004, 0.0095, 0.012, 0.2645, 192.002]) {
+      assert.ok(ledgerFallback(reserve) <= reserve, `${chainUnderTest} ${reserve}`);
+    }
+  }
+});
diff --git a/test/realface-money-path.test.ts b/test/realface-money-path.test.ts
index 80de612..c1bb9af 100644
--- a/test/realface-money-path.test.ts
+++ b/test/realface-money-path.test.ts
@@ -8,11 +8,38 @@
 // asset_id one line BEFORE recordActualSpend; the catch formatted a failure and
 // finally released the reservation, so the ledger netted to $0 for money that
 // had moved. video.ts, speech.ts and music.ts each fixed this ordering already.
+//
+// Audit round 3 extended this to the other two rails and to the give-up
+// path: the in-flight booking 776b4a7 added was cleared in a `.finally` before
+// the catch could read it (dead on every rail), the flag behind it was
+// module-global (a concurrent call's payment booked against an unrelated
+// failure), the account rail discarded the settled cost header, and
+// action:"list" asked the Solana gateway for an EVM address (400 on the
+// default chain, minting an EVM key on the way). Each has a case below.
 import { test, mock, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 import type { BudgetState } from "../src/types.js";
 
+// Pin the auth rail: auth.ts reads ~/.blockrun/.api-key from os.homedir() at
+// import time, so a developer machine set up for account billing would run
+// every wallet case below in account mode. Temp HOME, no env key; the account
+// cases set the env key themselves and reset the memo.
+const home = fs.mkdtempSync(path.join(os.tmpdir(), "blockrun-realface-"));
+const realHome = process.env.HOME;
+const savedApiKey = process.env.BLOCKRUN_API_KEY;
+process.env.HOME = home;
+delete process.env.BLOCKRUN_API_KEY;
+process.on("exit", () => {
+  if (realHome === undefined) delete process.env.HOME; else process.env.HOME = realHome;
+  if (savedApiKey === undefined) delete process.env.BLOCKRUN_API_KEY; else process.env.BLOCKRUN_API_KEY = savedApiKey;
+  fs.rmSync(home, { recursive: true, force: true });
+});
+
 const TEST_KEY = "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d";
+const SOL_PUBKEY = "So1anaPubkey1111111111111111111111111111111";
 
 function headers(map: Record<string, string> = {}) {
   const lower = Object.fromEntries(Object.entries(map).map(([k, v]) => [k.toLowerCase(), v]));
@@ -21,41 +48,64 @@ function headers(map: Record<string, string> = {}) {
 
 let script: Array<() => unknown> = [];
 let paymentsSigned = 0;
+let chain: "base" | "solana" = "base";
+let solanaKey: string | undefined = "solana-secret-key";
+let evmKeyReads = 0;
+const requests: Array<{ url: string; method: string }> = [];
 mock.module("../src/utils/http.js", {
   namedExports: {
-    fetchWithTimeout: async () => {
+    fetchWithTimeout: async (url: string, init: { method?: string }) => {
+      requests.push({ url, method: init.method ?? "GET" });
       const next = script.shift();
       if (!next) throw new Error("UNEXPECTED_NETWORK_CALL");
       return next();
     },
-    isTimeoutError: () => false,
+    // The real predicate, restated. This suite stubbed it to `() => false`
+    // until audit round 3, which hid the give-up branch from every case.
+    isTimeoutError: (err: unknown) => {
+      const name = err instanceof Error ? err.name : "";
+      if (name === "AbortError" || name === "TimeoutError") return true;
+      const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+      return msg.includes("abort") || msg.includes("timeout") || msg.includes("timed out") || msg.includes("did not complete within");
+    },
   },
 });
 mock.module("../src/utils/wallet.js", {
   namedExports: {
-    getApiBase: () => "https://blockrun.ai/api",
-    getChain: () => "base",
-    getOrCreateWalletKey: () => TEST_KEY,
+    getApiBase: () => (chain === "solana" ? "https://sol.blockrun.ai/api" : "https://blockrun.ai/api"),
+    resolveGatewayUrl: (u: string) => u,
+    getChain: () => chain,
+    getOrCreateWalletKey: () => { evmKeyReads++; return TEST_KEY; },
     getWalletInfo: async () => ({ address: "0xTEST" }),
+    resolveSolanaKey: () => solanaKey,
+    solanaKeyUnavailableReason: () => undefined,
   },
 });
+class FakePaymentError extends Error { constructor(m: string) { super(m); this.name = "PaymentError"; } }
 mock.module("@blockrun/llm", {
   namedExports: {
+    PaymentError: FakePaymentError,
+    SOLANA_NETWORK: "solana:mainnet",
+    SolanaLLMClient: { SOLANA_API_URL: "https://sol.blockrun.ai/api" },
     createPaymentPayload: async () => { paymentsSigned++; return "0xpaymentpayloadmock"; },
+    createSolanaPaymentPayload: async () => { paymentsSigned++; return "solana-payment-payload"; },
+    solanaKeyToBytes: async () => new Uint8Array(64),
+    solanaPublicKey: async () => SOL_PUBKEY,
     parsePaymentRequired: () => ({}),
     // 12000 micro-USDC = $0.012: the gateway's $0.01 base plus the $0.002 fee.
     extractPaymentDetails: () => ({
       amount: "12000",
-      recipient: "0x0000000000000000000000000000000000000001",
-      network: "eip155:8453",
+      recipient: chain === "solana" ? "Recipient111111111111111111111111111111111" : "0x0000000000000000000000000000000000000001",
+      network: chain === "solana" ? "solana:mainnet" : "eip155:8453",
       resource: { url: "https://blockrun.ai/api/v1/portrait/enroll", description: "BlockRun Virtual Portrait enrollment" },
       maxTimeoutSeconds: 120,
-      extra: {},
+      extra: chain === "solana" ? { feePayer: "FeePayer1111111111111111111111111111111111" } : {},
     }),
   },
 });
 
 const { registerRealfaceTool } = await import("../src/tools/realface.js");
+const { resetAuthCache, isApiKeyMode } = await import("../src/utils/auth.js");
 
 function makeHarness() {
   let handler: ((args: Record<string, unknown>) => Promise<any>) | undefined;
@@ -72,9 +122,20 @@ const text = (res: any) => res.content.map((c: any) => c.text).join("\n");
 const resp402 = () => ({ status: 402, ok: false, headers: headers({ "payment-required": "x402 base ..." }), json: async () => ({}) });
 const paid = (status: number, body: unknown) => () => ({ status, ok: status >= 200 && status < 300, headers: headers(), json: async () => body });
 
-beforeEach(() => { script = []; paymentsSigned = 0; });
+const abortError = () => { const e = new Error("This operation was aborted"); e.name = "AbortError"; return e; };
+const near = (a: number, b: number) => Math.abs(a - b) < 1e-9;
+function accountMode(on: boolean) {
+  if (on) process.env.BLOCKRUN_API_KEY = "brk_live_testkeyfortestsonly0000"; else delete process.env.BLOCKRUN_API_KEY;
+  resetAuthCache();
+}
+
+beforeEach(() => { script = []; paymentsSigned = 0; chain = "base"; solanaKey = "solana-secret-key"; evmKeyReads = 0; requests.length = 0; accountMode(false); });
 afterEach(() => { assert.equal(script.length, 0, "unconsumed scripted responses"); });
 
+test("the suite runs on the wallet rail whatever the developer's account setup", () => {
+  assert.equal(isApiKeyMode(), false);
+});
+
 const PORTRAIT = { action: "portrait", name: "Ada", image_url: "https://ok.example.com/ada.png" };
 const ENROLL = { action: "enroll", name: "Ada", image_url: "https://ok.example.com/ada.png", group_id: "legacy_rf_1" };
 
@@ -111,3 +172,192 @@ for (const [label, args, missing] of [
     assert.equal(budget.spent, 0, "reservation must be fully released");
   });
 }
+
+// ---------------------------------------------------------------------------
+// Give-up booking, per rail. The paid request goes out (402 answered, transfer
+// signed — or the Bearer on the request) and never answers.
+// ---------------------------------------------------------------------------
+test("Base: the signed POST dropping is booked at the quote and reported as a possible charge", async () => {
+  script = [resp402, () => { throw abortError(); }];
+  const { call, budget } = makeHarness();
+  const res = await call(PORTRAIT);
+  const t = text(res);
+  assert.equal(res.isError, true, t);
+  assert.equal(paymentsSigned, 1);
+  assert.match(t, /RealFace portrait got no answer/);
+  assert.match(t, /MAY have gone through/);
+  assert.match(t, /action:"report"/);
+  assert.doesNotMatch(t, /No payment taken|no charge was made/i);
+  assert.ok(near(budget.spent, 0.012), `the quote is booked: spent=${budget.spent}`);
+});
+
+test("Base: the unpaid 402 probe dropping books nothing — nothing was signed", async () => {
+  script = [() => { throw abortError(); }];
+  const { call, budget } = makeHarness();
+  const res = await call(PORTRAIT);
+  assert.equal(res.isError, true);
+  assert.equal(paymentsSigned, 0);
+  assert.doesNotMatch(text(res), /MAY have/);
+  assert.equal(budget.spent, 0);
+});
+
+test("Solana: the paid POST dropping after the SPL transfer was signed is booked at the quote", async () => {
+  chain = "solana";
+  script = [resp402, () => { throw abortError(); }];
+  const { call, budget } = makeHarness();
+  const res = await call(ENROLL);
+  const t = text(res);
+  assert.equal(res.isError, true, t);
+  assert.equal(paymentsSigned, 1, "one SPL transfer signed");
+  assert.equal(evmKeyReads, 0, "the EVM wallet is never touched on Solana");
+  assert.match(t, /RealFace enroll got no answer/);
+  assert.match(t, /MAY have gone through/);
+  assert.ok(near(budget.spent, 0.012), `spent=${budget.spent}`);
+});
+
+test("Solana: the unpaid quote probe dropping books nothing — the tracker is armed only from onQuote", async () => {
+  chain = "solana";
+  script = [() => { throw abortError(); }];
+  const { call, budget } = makeHarness();
+  const res = await call(ENROLL);
+  assert.equal(res.isError, true);
+  assert.equal(paymentsSigned, 0);
+  assert.doesNotMatch(text(res), /MAY have/);
+  assert.equal(budget.spent, 0);
+});
+
+test("Solana: a 422 that came back is 'rejected, not charged' — a response is an answer, never a maybe", async () => {
+  chain = "solana";
+  script = [resp402, paid(422, { hint: "use a clearer photo" })];
+  const { call, budget } = makeHarness();
+  const res = await call(ENROLL);
+  assert.equal(res.isError, true);
+  assert.match(text(res), /No payment taken/);
+  assert.doesNotMatch(text(res), /MAY have/);
+  assert.equal(budget.spent, 0);
+});
+
+test("account rail: the Bearer POST dropping is booked at the reserve and points at the account activity page", async () => {
+  accountMode(true);
+  script = [() => { throw abortError(); }];
+  const { call, budget } = makeHarness();
+  const res = await call(PORTRAIT);
+  const t = text(res);
+  assert.equal(res.isError, true, t);
+  assert.equal(paymentsSigned, 0, "nothing is signed on the account rail");
+  assert.match(t, /carrying the account key/);
+  assert.match(t, /MAY have gone through/);
+  assert.match(t, /dashboard\/activity/);
+  assert.ok(near(budget.spent, 0.012), `the reserve is booked: spent=${budget.spent}`);
+});
+
+test("account rail: the settled cost header is booked and shown instead of the fee-inclusive estimate", async () => {
+  // The account API bills the $0.010 base with no transaction fee and says so
+  // in x-blockrun-cost-usd (since 2026-09-05). realface hand-rolled its fetch
+  // and threw the header away under a comment claiming there was none, so the
+  // ledger carried $0.012 for a $0.010 charge on every enrolment.
+  accountMode(true);
+  script = [() => ({ status: 200, ok: true, headers: headers({ "x-blockrun-cost-usd": "0.010000" }), json: async () => ({ asset_id: "ta_acc", name: "Ada" }) })];
+  const { call, budget } = makeHarness();
+  const res = await call(PORTRAIT);
+  assert.notEqual(res.isError, true, text(res));
+  assert.ok(near(budget.spent, 0.01), `spent=${budget.spent}`);
+  assert.match(text(res), /Cost: \$0\.0100/);
+  assert.equal(res.structuredContent.price_usd, 0.01);
+  assert.match(requests[0].url, /\/v1\/portrait\/enroll$/);
+});
+
+test("account rail: an absent cost header still books the estimate, never $0", async () => {
+  accountMode(true);
+  script = [() => ({ status: 200, ok: true, headers: headers(), json: async () => ({ asset_id: "ta_acc", name: "Ada" }) })];
+  const { call, budget } = makeHarness();
+  const res = await call(PORTRAIT);
+  assert.notEqual(res.isError, true, text(res));
+  assert.ok(near(budget.spent, 0.012), `spent=${budget.spent}`);
+});
+
+// ---------------------------------------------------------------------------
+// Per-call state. Two calls interleave; only the one whose paid request is
+// outstanding may book — the module-global flag booked $0.012 against the
+// OTHER call's refused-unsigned quote and told it a charge may have settled.
+// ---------------------------------------------------------------------------
+test("a concurrent call's outstanding payment never books against another call's failure", async () => {
+  chain = "solana";
+  let releaseA: (() => void) | undefined;
+  const aPaidPostReached = new Promise<void>((resolve) => {
+    // Call A: 402 answered, transfer signed, paid POST hangs until released,
+    // then drops.
+    script = [
+      resp402,
+      () => new Promise((_, reject) => { resolve(); releaseA = () => reject(abortError()); }),
+    ];
+  });
+  const { call, budget } = makeHarness();
+  const a = call(ENROLL);
+  await aPaidPostReached;
+  assert.equal(paymentsSigned, 1, "A has signed and its paid POST is outstanding");
+
+  // Call B, while A is in flight: its quote probe drops before anything is
+  // quoted or signed. B must book nothing and say nothing about a charge.
+  const heldByA = budget.spent;
+  assert.ok(near(heldByA, 0.012), "A's reservation is what the ledger holds mid-flight");
+  script = [() => { throw abortError(); }];
+  const b = await call(PORTRAIT);
+  assert.equal(b.isError, true);
+  assert.doesNotMatch(text(b), /MAY have/, `B borrowed A's state: ${text(b)}`);
+  assert.ok(near(budget.spent, heldByA), `B booked nothing (its own reservation released): spent=${budget.spent}`);
+  assert.equal(paymentsSigned, 1, "B signed nothing");
+
+  releaseA!();
+  const resA = await a;
+  assert.match(text(resA), /MAY have gone through/);
+  assert.ok(near(budget.spent, 0.012), `A books its own charge exactly once: spent=${budget.spent}`);
+});
+
+// ---------------------------------------------------------------------------
+// action:"list" on the default chain.
+// ---------------------------------------------------------------------------
+test("list on Solana asks the Solana gateway for the Solana payer, and mints nothing", async () => {
+  chain = "solana";
+  script = [
+    () => ({ status: 200, ok: true, headers: headers(), json: async () => ({ realfaces: [{ assetId: "ta_sol", name: "Ada" }], count: 1 }) }),
+    () => ({ status: 200, ok: true, headers: headers(), json: async () => ({ portraits: [] }) }),
+  ];
+  const { call, budget } = makeHarness();
+  const res = await call({ action: "list" });
+  const t = text(res);
+  assert.notEqual(res.isError, true, t);
+  assert.equal(requests[0].url, `https://sol.blockrun.ai/api/v1/wallet/${SOL_PUBKEY}/realfaces`);
+  assert.equal(requests[1].url, `https://sol.blockrun.ai/api/v1/wallet/${SOL_PUBKEY}/portraits`);
+  assert.equal(evmKeyReads, 0, "a free listing on Solana must not read (or mint) the EVM wallet");
+  assert.match(t, /ta_sol/);
+  assert.match(t, /on Solana/);
+  assert.equal(res.structuredContent.chain, "solana");
+  assert.equal(res.structuredContent.wallet, SOL_PUBKEY);
+  assert.equal(budget.spent, 0);
+});
+
+test("list on Solana with no Solana wallet refuses without provisioning one", async () => {
+  chain = "solana";
+  solanaKey = undefined;
+  const { call } = makeHarness();
+  const res = await call({ action: "list" });
+  assert.equal(res.isError, true);
+  assert.match(text(res), /No Solana wallet yet/);
+  assert.match(text(res), /action:"setup"/);
+  assert.equal(requests.length, 0, "nothing asked of the gateway");
+  assert.equal(evmKeyReads, 0);
+});
+
+test("list on Base still asks the Base gateway for the EVM address", async () => {
+  script = [
+    () => ({ status: 200, ok: true, headers: headers(), json: async () => ({ realfaces: [], count: 0 }) }),
+    () => ({ status: 200, ok: true, headers: headers(), json: async () => ({ portraits: [] }) }),
+  ];
+  const { call } = makeHarness();
+  const res = await call({ action: "list" });
+  assert.notEqual(res.isError, true, text(res));
+  assert.match(requests[0].url, /^https:\/\/blockrun\.ai\/api\/v1\/wallet\/0x[0-9a-fA-F]{40}\/realfaces$/);
+  assert.match(text(res), /Base wallet/);
+  assert.equal(res.structuredContent.chain, "base");
+});
diff --git a/test/redact-exit.test.ts b/test/redact-exit.test.ts
new file mode 100644
index 0000000..54522b0
--- /dev/null
+++ b/test/redact-exit.test.ts
@@ -0,0 +1,72 @@
+// Run with: npm test  (tsx --test)
+//
+// Round 3 (commit 4e357af) found that only the isError branch of the live
+// e2e scripts was redacted — a thrown viem/RPC error, whose message
+// interpolates `sender: 0x…` and the funds address, bypassed it and Node
+// printed the raw message and stack. -live.ts got process-level handlers;
+// -approve.ts and -withdraw.ts got try/catch. -readonly.ts, whose header says
+// it "never emits a wallet address", and -verify-approvals.ts got neither:
+// `withdrawFunds({})`, `listPositions()` and `runSetup({confirm:false})` all
+// reach a Polygon RPC, and an unhandled rejection from any of them printed the
+// address in full.
+//
+// One installer, every script. The behaviour test spawns a child that
+// installs it and then dies both ways — a rejection and a throw — carrying a
+// wallet address and a tx hash, and asserts what reached stderr.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+const SCRIPTS = path.join(ROOT, "scripts");
+const TSX = path.join(ROOT, "node_modules", ".bin", "tsx");
+
+const WALLET = "0x" + "ab".repeat(20);
+const TX = "0x" + "cd".repeat(32);
+
+function dieWith(kind: "reject" | "throw") {
+  const program = [
+    `import { installRedactedExit } from "${path.join(SCRIPTS, "redact.ts")}";`,
+    "installRedactedExit();",
+    kind === "reject"
+      ? `void Promise.reject(new Error("ContractFunctionExecutionError: sender: ${WALLET} tx ${TX}"));`
+      : `setTimeout(() => { throw new Error("RPC 401 for ${WALLET}"); }, 0);`,
+    // Keep the loop alive long enough for the rejection to surface.
+    "setTimeout(() => {}, 200);",
+  ].join("\n");
+  return spawnSync(TSX, ["--eval", program], { encoding: "utf8", cwd: ROOT });
+}
+
+test("an unhandled rejection exits 1 with the address and hash redacted", () => {
+  const r = dieWith("reject");
+  assert.equal(r.status, 1, `expected exit 1, got ${r.status}\nstdout: ${r.stdout}\nstderr: ${r.stderr}`);
+  assert.equal(r.stderr.includes(WALLET), false, `the wallet address reached stderr:\n${r.stderr}`);
+  assert.equal(r.stderr.includes(TX), false, `the tx hash reached stderr:\n${r.stderr}`);
+  assert.match(r.stderr, /<wallet>/);
+  assert.match(r.stderr, /<tx>/);
+  assert.match(r.stderr, /"failed":\s*true/);
+});
+
+test("an uncaught exception exits 1 with the address redacted", () => {
+  const r = dieWith("throw");
+  assert.equal(r.status, 1, `expected exit 1, got ${r.status}\nstdout: ${r.stdout}\nstderr: ${r.stderr}`);
+  assert.equal(r.stderr.includes(WALLET), false, `the wallet address reached stderr:\n${r.stderr}`);
+  assert.match(r.stderr, /RPC 401 for <wallet>/);
+});
+
+test("every Polymarket e2e script installs the redacted exit before its first await", () => {
+  // Static, like scripts-redaction.test.ts's regex sweep: running a live
+  // script to prove its error path would need a wallet and a failing RPC.
+  const missing: string[] = [];
+  for (const name of readdirSync(SCRIPTS)) {
+    if (!name.startsWith("polymarket-e2e-")) continue;
+    const source = readFileSync(path.join(SCRIPTS, name), "utf8");
+    const install = source.search(/installRedactedExit\(\)/);
+    const firstAwait = source.search(/\bawait\b/);
+    if (install === -1 || (firstAwait > -1 && install > firstAwait)) missing.push(name);
+  }
+  assert.deepEqual(missing, [], "a script without the installer prints the wallet address on the first RPC failure");
+});
diff --git a/test/repo-hygiene.test.ts b/test/repo-hygiene.test.ts
new file mode 100644
index 0000000..ac1355a
--- /dev/null
+++ b/test/repo-hygiene.test.ts
@@ -0,0 +1,49 @@
+// Run with: npm test  (tsx --test)
+//
+// Commit 7f8d8f1 (round 3) tracked a SYMLINK named node_modules pointing at
+// ../blockrun-mcp/node_modules — itself. `.gitignore` said `node_modules/`,
+// and a trailing slash matches only a directory, so `git add -A` took the
+// link. A clone named blockrun-mcp then had a self-loop (ELOOP on readdir,
+// `npm install` cannot create the directory); CONTRIBUTING's `git clone … &&
+// cd blockrun-mcp && npm install` failed at step one, and CI never saw it
+// because `npm ci` deletes the path first.
+//
+// Both halves are asked of git itself, not of the .gitignore text.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { copyFileSync, mkdtempSync, rmSync, symlinkSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+test("git tracks nothing under node_modules — not a directory, not a symlink", () => {
+  const tracked = execFileSync("git", ["ls-files", "-z", "--", "node_modules"], { cwd: ROOT, encoding: "utf8" })
+    .split("\0")
+    .filter(Boolean);
+  assert.deepEqual(tracked, [], "`git rm --cached node_modules` — a tracked node_modules ships in every clone");
+});
+
+test(".gitignore ignores a node_modules SYMLINK, not only a node_modules directory", () => {
+  // Asked of git in a scratch repo carrying THIS .gitignore and a dangling
+  // symlink named node_modules: `git status` must not list it as untracked.
+  // (check-ignore on the real tree would consult the real node_modules
+  // directory and pass on the directory-only pattern too.)
+  const dir = mkdtempSync(path.join(os.tmpdir(), "gitignore-symlink-"));
+  try {
+    const git = (...args: string[]) => execFileSync("git", args, { cwd: dir, encoding: "utf8" });
+    git("init", "-q");
+    copyFileSync(path.join(ROOT, ".gitignore"), path.join(dir, ".gitignore"));
+    symlinkSync("../somewhere-else/node_modules", path.join(dir, "node_modules"));
+    const untracked = git("status", "--porcelain", "--untracked-files=all")
+      .split("\n")
+      .filter((l) => l.startsWith("??"))
+      .map((l) => l.slice(3));
+    assert.ok(!untracked.includes("node_modules"), "a node_modules symlink is untracked, not ignored — the pattern must be `node_modules`, without the trailing slash");
+    assert.ok(untracked.includes(".gitignore"), "sanity: the scratch repo does see untracked files");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
diff --git a/test/schema-tokens.test.ts b/test/schema-tokens.test.ts
index ad39247..a5caa97 100644
--- a/test/schema-tokens.test.ts
+++ b/test/schema-tokens.test.ts
@@ -28,6 +28,13 @@ import { initializeMcpServer } from "../src/mcp-handler.js";
 import { measure, asK, listTools } from "../scripts/measure-tool-schema.mjs";
 
 const README = readFileSync(new URL("../README.md", import.meta.url), "utf8");
+// docs/mcp-schema-overhead.md carries a SECOND copy of the profile-cost table.
+// Only the README copy was pinned, so the doc could sit at a stale number
+// indefinitely while the README stayed correct.
+const OVERHEAD_DOC = readFileSync(
+  new URL("../docs/mcp-schema-overhead.md", import.meta.url),
+  "utf8",
+);
 const PREFIX = "mcp__blockrun__";
 
 /** Same projection the CLI harness measures, over an in-process handshake. */
@@ -80,9 +87,24 @@ test("the profile table states each profile's measured cost", async () => {
     );
     assert.match(README, row,
       `README row for ${profile} should read ${tools} tools / ${total.toLocaleString()} tokens`);
+    assert.match(OVERHEAD_DOC, row,
+      `docs/mcp-schema-overhead.md row for ${profile} should read ${tools} tools / ${total.toLocaleString()} tokens`);
   }
 });
 
+test("every profile in src/profiles.ts is measured, not just the five in the table", async () => {
+  // measure-tool-schema.mjs hardcodes its profile list and this file hardcodes
+  // the same one. A profile added to src/profiles.ts would be measured by
+  // neither and pinned by neither, so it could ship advertising nothing.
+  const { PROFILES } = await import("../src/profiles.js");
+  assert.deepEqual(
+    Object.keys(PROFILES).sort(),
+    ["chat", "full", "media", "research", "trading"],
+    "a new profile needs a row in the README table, in docs/mcp-schema-overhead.md, " +
+      "and in PROFILES in scripts/measure-tool-schema.mjs",
+  );
+});
+
 test("the advertised profile saving is the one measured", async () => {
   const full = await measureProfile("full");
   const trading = await measureProfile("trading");
diff --git a/test/scripts-redaction.test.ts b/test/scripts-redaction.test.ts
new file mode 100644
index 0000000..13c6243
--- /dev/null
+++ b/test/scripts-redaction.test.ts
@@ -0,0 +1,75 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// The live Polymarket e2e scripts run against a real funded wallet, and their
+// output goes into terminals, CI logs and issue comments. Three of them state
+// in their own doc comment that wallet addresses and transaction ids are never
+// printed. Each had implemented that promise with a DIFFERENT regex, and the
+// one used by the two scripts that actually move money matched `{64}` only —
+// so a 40-hex address printed in full, and withdraw.ts really does interpolate
+// a bridge response carrying an address into its error text.
+//
+// Nothing here runs a script. The first tests exercise the shared helper; the
+// last reads the scripts as text and fails if one grows its own regex again.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { redactChainValues } from "../scripts/redact.js";
+
+const SCRIPTS = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "scripts");
+
+const WALLET = "0x" + "ab".repeat(20);
+const TX = "0x" + "cd".repeat(32);
+
+test("a wallet address is redacted, not just a transaction hash", () => {
+  const out = redactChainValues(`Bridge did not return an address (got: ${WALLET}).`);
+  assert.equal(out.includes(WALLET), false, "the address must not survive");
+  assert.match(out, /<wallet>/);
+});
+
+test("a transaction hash is labelled as one and never half-eaten by the address rule", () => {
+  const out = redactChainValues(`submitted ${TX}`);
+  assert.equal(out, "submitted <tx>");
+  assert.equal(out.includes("cd"), false, "no tail of the hash may leak past a 40-char match");
+});
+
+test("both in one string, in either order", () => {
+  assert.equal(
+    redactChainValues(`from ${WALLET} tx ${TX} back to ${WALLET}`),
+    "from <wallet> tx <tx> back to <wallet>",
+  );
+  assert.equal(redactChainValues(`${TX} ${WALLET}`), "<tx> <wallet>");
+});
+
+test("a 32-byte private key comes out redacted (mislabelled is fine, printed is not)", () => {
+  const key = "0x" + "11".repeat(32);
+  assert.equal(redactChainValues(`key=${key}`).includes("11"), false);
+});
+
+test("anything else long and hex is redacted rather than passed through", () => {
+  const odd = "0x" + "ef".repeat(25);
+  const out = redactChainValues(`blob ${odd}`);
+  assert.equal(out.includes(odd), false);
+  assert.match(out, /<redacted>/);
+});
+
+test("short hex is left alone — a token id or a selector is not a secret", () => {
+  assert.equal(redactChainValues("selector 0xdeadbeef"), "selector 0xdeadbeef");
+});
+
+test("no e2e script carries its own address/hash regex", () => {
+  const offenders: string[] = [];
+  for (const name of readdirSync(SCRIPTS)) {
+    if (!name.startsWith("polymarket-e2e-")) continue;
+    const source = readFileSync(path.join(SCRIPTS, name), "utf-8");
+    if (/0x\[a-fA-F0-9\]\{/.test(source)) offenders.push(name);
+  }
+  assert.deepEqual(
+    offenders,
+    [],
+    "redact via scripts/redact.ts — four hand-rolled regexes is how the {64}-only " +
+      "one shipped in the two scripts that move real money",
+  );
+});
diff --git a/test/scripts-spend-gate.test.ts b/test/scripts-spend-gate.test.ts
new file mode 100644
index 0000000..83657cc
--- /dev/null
+++ b/test/scripts-spend-gate.test.ts
@@ -0,0 +1,69 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// A script that registers a real tool handler spends real USDC from the
+// machine-global wallet the moment it is run. scripts/smoke-speech.ts did
+// exactly that on a bare `npx tsx scripts/smoke-speech.ts`, with `limit: null`
+// so nothing capped it, under a header advertising "real $0.001 speak" while
+// the run ends with a $0.0525 sound effect. This repo has already lost $0.42
+// to a paid handler that was run because it looked like a read.
+//
+// These assertions are STATIC on purpose. A test that proved the gate by
+// running the script would charge the wallet the day the gate regressed,
+// which is the failure it is supposed to catch.
+//
+// The polymarket e2e scripts are deliberately not covered: they reach paid
+// paths through utils/, not through a tool handler, they are exposed only as
+// explicitly named `npm run e2e:polymarket:live`-style targets, and each
+// carries its own bound ($2 withdrawal cap, redeem restricted to a position
+// worth <= $0.001).
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCRIPTS = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "scripts");
+
+function scriptsRegisteringTools(): Array<{ name: string; source: string }> {
+  const found: Array<{ name: string; source: string }> = [];
+  for (const name of readdirSync(SCRIPTS)) {
+    if (!name.endsWith(".ts")) continue;
+    const source = readFileSync(path.join(SCRIPTS, name), "utf-8");
+    // Importing a pure estimator from src/tools is free — verify-prices.ts does
+    // exactly that. Calling register…Tool() is what wires up a handler that pays.
+    if (/register[A-Za-z]*Tool\s*\(/.test(source)) found.push({ name, source });
+  }
+  return found;
+}
+
+test("the set of scripts that register a paid tool handler is known", () => {
+  assert.deepEqual(
+    scriptsRegisteringTools().map((s) => s.name).sort(),
+    ["smoke-speech.ts"],
+    "a new script here spends real USDC when run — give it a confirm gate and a budget cap",
+  );
+});
+
+test("every such script refuses to spend without an explicit confirmation", () => {
+  for (const { name, source } of scriptsRegisteringTools()) {
+    assert.match(
+      source,
+      /--confirm|BLOCKRUN_SMOKE_CONFIRM/,
+      `${name} charges a real wallet on a bare run with no way to say no`,
+    );
+    const gate = source.search(/process\.exit\(1\)/);
+    const firstCall = source.search(/await run\(|await handler/);
+    assert.ok(gate > -1 && (firstCall === -1 || gate < firstCall), `${name}: the gate must come before the first paid call`);
+  }
+});
+
+test("every such script caps its own spend", () => {
+  for (const { name, source } of scriptsRegisteringTools()) {
+    assert.equal(
+      /limit:\s*null/.test(source),
+      false,
+      `${name} runs with an uncapped budget — a moved price or a retry drains the wallet`,
+    );
+    assert.match(source, /limit:\s*[A-Z_]+|limit:\s*0\.\d+/, `${name} must set a numeric budget limit`);
+  }
+});
diff --git a/test/search-sources.test.ts b/test/search-sources.test.ts
new file mode 100644
index 0000000..bdcdf3f
--- /dev/null
+++ b/test/search-sources.test.ts
@@ -0,0 +1,150 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// blockrun_search kept selling the X/Twitter source after the gateway removed
+// it (blockrun commit edefa8eb, 2026-07-05: `sources: z.array(z.enum(["web",
+// "news"])).optional().default(["web"])`). The description's own "Common
+// shape" was `sources: ["web","x","news"]`, so an agent following it to the
+// letter reserved $0.2645, sat through the confirm dialog, and got back
+// `API error: 400 / Invalid request body` with the zod issues stripped by the
+// SDK — no field named, nothing charged, no way to self-correct. Unpaid probe
+// 2026-09-13 on both gateways (no payment header):
+//
+//   {sources:["web","x","news"]} -> 400 {"path":["sources",1],"message":"Invalid option: expected one of \"web\"|\"news\""}
+//   {sources:["x"]}              -> 400 (sol.blockrun.ai, same body)
+//   {sources:["web","news"]}     -> 402 (the normal quote)
+//
+// Pinned: an unknown source is refused BEFORE the reserve, on every rail, with
+// a message that names the field and the two values that exist; the
+// description no longer advertises "x"; valid sources still pass through.
+import { test, mock, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import type { BudgetState } from "../src/types.js";
+
+let apiKeyMode = false;
+let chain: "base" | "solana" = "base";
+const walletCalls: Array<{ endpoint: string; body: unknown }> = [];
+const stubClient = {
+  getWithPaymentRaw: async () => { throw new Error("search never GETs"); },
+  requestWithPaymentRaw: async (endpoint: string, body: unknown) => { walletCalls.push({ endpoint, body }); return { results: [] }; },
+};
+mock.module("../src/utils/wallet.js", {
+  namedExports: {
+    getApiBase: () => "https://blockrun.ai/api",
+    resolveGatewayUrl: (u: string) => u,
+    getChain: () => chain,
+    getClient: () => stubClient,
+    buildClient: () => stubClient,
+    buildClientWithTimeout: () => stubClient,
+    baseOnlyMessage: () => null,
+    getOrCreateWalletKey: () => { throw new Error("search tests must not touch a wallet key"); },
+    getWalletInfo: async () => ({ address: "0xTEST" }),
+  },
+});
+mock.module("../src/utils/auth.js", {
+  namedExports: {
+    isApiKeyMode: () => apiKeyMode,
+    getApiKey: () => (apiKeyMode ? "br_test_key" : undefined),
+    apiAuthHeaders: () => ({ Authorization: "Bearer br_test_key" }),
+    getApiKeyBase: () => "https://api.blockrun.ai",
+    PORTAL_CREDITS_URL: "https://user.blockrun.ai/dashboard/credits",
+  },
+});
+const accountCalls: Array<{ url: string; body: unknown }> = [];
+mock.module("../src/utils/http.js", {
+  namedExports: {
+    fetchWithTimeout: async (url: string, init: { body?: string }) => {
+      accountCalls.push({ url, body: JSON.parse(init.body ?? "{}") });
+      return new Response(JSON.stringify({ results: [] }), {
+        status: 200,
+        headers: { "content-type": "application/json", "x-blockrun-cost-usd": "0.2625" },
+      });
+    },
+    isTimeoutError: () => false,
+  },
+});
+
+const { registerSearchTool } = await import("../src/tools/search.js");
+
+type Handler = (args: Record<string, unknown>) => Promise<{ content: Array<{ type: string; text?: string }>; isError?: boolean }>;
+function harness() {
+  let handler: Handler | undefined;
+  let description = "";
+  const server = {
+    registerTool: (_n: string, cfg: { description: string }, h: Handler) => { handler = h; description = cfg.description; },
+    server: { getClientCapabilities: () => ({}) },
+  };
+  const budget: BudgetState = { limit: null, spent: 0, calls: 0, agents: new Map() };
+  registerSearchTool(server as never, budget);
+  assert.ok(handler, "blockrun_search did not register a handler");
+  return { call: (args: Record<string, unknown>) => handler!(args), budget, description };
+}
+
+const RAILS: Array<{ name: string; apiKey: boolean; chain: "base" | "solana" }> = [
+  { name: "base wallet", apiKey: false, chain: "base" },
+  { name: "solana wallet", apiKey: false, chain: "solana" },
+  { name: "account key", apiKey: true, chain: "solana" },
+];
+
+beforeEach(() => { apiKeyMode = false; chain = "base"; walletCalls.length = 0; accountCalls.length = 0; });
+
+for (const rail of RAILS) {
+  test(`[${rail.name}] a source the gateway removed is refused before the reserve, naming the field and the live values`, async () => {
+    apiKeyMode = rail.apiKey; chain = rail.chain;
+    const { call, budget } = harness();
+    for (const sources of [["web", "x", "news"], ["x"], ["twitter"], ["web", "X"], ["news", "rss"]]) {
+      const res = await call({ body: { query: "Solana outage today", sources, max_results: 10 } });
+      const text = res.content.map((p) => p.text ?? "").join("\n");
+      assert.equal(res.isError, true, `${JSON.stringify(sources)} was not refused: ${text}`);
+      assert.match(text, /sources/, text);
+      assert.match(text, /"web"|'web'|web/, text);
+      assert.match(text, /news/, text);
+      assert.match(text, /No payment was made/i, text);
+      assert.doesNotMatch(text, /API error: 400/, "the refusal must be ours, not the gateway's opaque 400");
+    }
+    assert.equal(walletCalls.length, 0, "nothing may reach the wallet client");
+    assert.equal(accountCalls.length, 0, "nothing may reach the account API");
+    assert.equal(budget.spent, 0);
+    assert.equal(budget.calls, 0);
+  });
+
+  test(`[${rail.name}] the X/Twitter refusal says the source is gone, so the agent does not retry it`, async () => {
+    apiKeyMode = rail.apiKey; chain = rail.chain;
+    const { call } = harness();
+    const res = await call({ body: { query: "CT sentiment", sources: ["x"] } });
+    const text = res.content.map((p) => p.text ?? "").join("\n");
+    assert.match(text, /X\/Twitter/i, text);
+    assert.match(text, /removed|no longer|retired/i, text);
+  });
+
+  test(`[${rail.name}] valid sources, and no sources at all, still go through`, async () => {
+    apiKeyMode = rail.apiKey; chain = rail.chain;
+    const { call, budget } = harness();
+    const r1 = await call({ body: { query: "fed rate decision", sources: ["web", "news"], max_results: 3 } });
+    assert.notEqual(r1.isError, true, r1.content.map((p) => p.text).join());
+    const r2 = await call({ body: { query: "fed rate decision", max_results: 3 } });
+    assert.notEqual(r2.isError, true, r2.content.map((p) => p.text).join());
+    const sent = rail.apiKey ? accountCalls.map((c) => c.body) : walletCalls.map((c) => c.body);
+    assert.equal(sent.length, 2);
+    assert.deepEqual(sent[0], { query: "fed rate decision", sources: ["web", "news"], max_results: 3 });
+    assert.deepEqual(sent[1], { query: "fed rate decision", max_results: 3 }, "no sources is forwarded as-is (the gateway defaults to web)");
+    assert.equal(budget.calls, 2);
+  });
+}
+
+test("the description no longer advertises the X source, and states the gateway's real default", () => {
+  const { description } = harness();
+  assert.doesNotMatch(description, /"x"/, "the Common shape must not list \"x\"");
+  assert.doesNotMatch(description, /\["web","x","news"\]/);
+  assert.doesNotMatch(description, /tweet-only/i);
+  assert.doesNotMatch(description, /defaults to all three/i);
+  assert.match(description, /\["web","news"\]|\["web", "news"\]/);
+  assert.match(description, /default.*web/i);
+});
+
+test("a non-array sources value is left for the gateway's own 400 (unpaid) rather than guessed at", async () => {
+  // Only the SOURCE NAMES are ours to know; shape errors are the schema's.
+  const { call } = harness();
+  const res = await call({ body: { query: "x", sources: "web" } });
+  assert.notEqual(res.isError, true);
+  assert.equal(walletCalls.length, 1);
+});
diff --git a/test/smoke-speech-plan.test.ts b/test/smoke-speech-plan.test.ts
new file mode 100644
index 0000000..649ef85
--- /dev/null
+++ b/test/smoke-speech-plan.test.ts
@@ -0,0 +1,57 @@
+// Run with: npm test  (tsx --test)
+//
+// scripts/smoke-speech.ts asks the operator to authorise a charge, and the
+// figure it quoted was typed by hand: "$0.001 speak", "$0.054 total". The
+// estimator the tool actually reserves with says $0.004678 and $0.059179.
+// The gate message is now computed from that estimator via smoke-speech-plan.ts;
+// this pins the plan to the estimator and keeps hand-typed dollar figures out
+// of the script.
+//
+// smoke-speech.ts itself is never imported here: importing it runs the paid
+// calls. The plan module is pure.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { SOUND_EFFECT_USD, SPEAK_INPUT, SPEAK_MODEL, smokeSpeechPlan, usd } from "../scripts/smoke-speech-plan.js";
+import { speechCost } from "../src/tools/speech.js";
+
+test("the speak figure is what speechCost reserves for the exact input the script sends", () => {
+  const plan = smokeSpeechPlan();
+  assert.equal(plan.speakUsd, speechCost(SPEAK_MODEL, SPEAK_INPUT));
+  // 51 chars @ $0.05/1k x 1.05 = $0.0026775 base, + $0.002 fee, ceiled.
+  assert.equal(SPEAK_INPUT.length, 51);
+  assert.equal(plan.speakUsd, 0.004678);
+});
+
+test("the sound-effect figure is the live-verified 54501 micro, not the $0.0525 base", () => {
+  // speech-cost.test.ts pins the same number through the tool's own path.
+  assert.equal(SOUND_EFFECT_USD, 0.054501);
+  assert.equal(smokeSpeechPlan().soundEffectUsd, 0.054501);
+});
+
+test("the total is the sum, to the micro", () => {
+  const plan = smokeSpeechPlan();
+  assert.equal(plan.totalUsd, 0.059179);
+  assert.equal(plan.totalUsd, Math.round((plan.speakUsd + plan.soundEffectUsd) * 1e6) / 1e6);
+});
+
+test("usd() prints a readable figure without trailing zeros", () => {
+  assert.equal(usd(0.004678), "$0.004678");
+  assert.equal(usd(0.05), "$0.05");
+  assert.equal(usd(0.1), "$0.1");
+});
+
+test("smoke-speech.ts carries no hand-typed dollar figure and sends the inputs the plan priced", () => {
+  const source = readFileSync(new URL("../scripts/smoke-speech.ts", import.meta.url), "utf8");
+  // The one dollar figure allowed is the spend cap; everything shown to the
+  // operator must come from the plan. A literal like "$0.001" in the gate
+  // message or a run label is the bug this test exists for.
+  // Comments may recount the old wrong figures; code may not carry any.
+  const code = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+  const literals = [...code.matchAll(/\$0\.\d+/g)].map((m) => m[0]);
+  assert.deepEqual(literals, [], `hand-typed dollar figures in smoke-speech.ts: ${literals.join(", ")} — print smokeSpeechPlan() instead`);
+  assert.match(source, /smokeSpeechPlan\(\)/, "the gate message must be computed from the estimator");
+  assert.match(source, /input: SPEAK_INPUT/, "the speak call must send the input the plan priced");
+  assert.match(source, /input: SOUND_EFFECT_INPUT/);
+  assert.match(source, /model: SPEAK_MODEL/);
+});
diff --git a/test/solana-402-async.test.ts b/test/solana-402-async.test.ts
index 590792a..84b3717 100644
--- a/test/solana-402-async.test.ts
+++ b/test/solana-402-async.test.ts
@@ -35,8 +35,16 @@ mock.module("../src/utils/http.js", {
 // The helper reads the key through the keychain-aware resolver, never the
 // SDK's file-only loader (strict keychain mode retires the session file).
 let walletKey: string | undefined = "test-solana-key";
+// What solanaKeyUnavailableReason() answers when there is no key: undefined
+// means "no wallet anywhere", a string means "the keychain would not open".
+let keyUnavailableReason: string | undefined;
 mock.module("../src/utils/wallet.js", {
-  namedExports: { resolveSolanaKey: () => walletKey, getApiBase: () => "https://blockrun.ai/api", resolveGatewayUrl: (u: string) => (u.startsWith("http") ? u : `https://blockrun.ai/api${u.startsWith("/api/") ? u.slice(4) : u}`), },
+  namedExports: {
+    resolveSolanaKey: () => walletKey,
+    solanaKeyUnavailableReason: () => (walletKey ? undefined : keyUnavailableReason),
+    getApiBase: () => "https://blockrun.ai/api",
+    resolveGatewayUrl: (u: string) => (u.startsWith("http") ? u : `https://blockrun.ai/api${u.startsWith("/api/") ? u.slice(4) : u}`),
+  },
 });
 
 const baseDetails = () => ({
@@ -47,10 +55,11 @@ const baseDetails = () => ({
   resource: { url: "https://sol.blockrun.ai/api/v1/videos/generations" },
 });
 let details: Record<string, unknown> = baseDetails();
+class FakePaymentError extends Error { constructor(m: string) { super(m); this.name = "PaymentError"; } }
 mock.module("@blockrun/llm", {
   namedExports: {
     SolanaLLMClient: { SOLANA_API_URL: "https://sol.blockrun.ai/api" },
-    PaymentError: class PaymentError extends Error {},
+    PaymentError: FakePaymentError,
     SOLANA_NETWORK: "solana:mainnet",
     solanaPublicKey: async () => "payer",
     solanaKeyToBytes: async () => new Uint8Array(64),
@@ -66,11 +75,13 @@ mock.module("@blockrun/llm", {
   },
 });
 
-const { solanaPaidAsyncPost } = await import("../src/utils/solana-402.js");
+const { solanaPaidAsyncPost, solanaPaidPost } = await import("../src/utils/solana-402.js");
+const { JobFailedError } = await import("../src/utils/poll.js");
+const { BilledJobError } = await import("../src/utils/api-key-call.js");
 
 beforeEach(() => {
   script = []; requests = []; signaturesCreated = 0; signOptions = []; timeouts = [];
-  failSignOnCall = null; signCalls = 0; walletKey = "test-solana-key"; details = baseDetails();
+  failSignOnCall = null; signCalls = 0; walletKey = "test-solana-key"; keyUnavailableReason = undefined; details = baseDetails();
 });
 // Unconsumed scripted responses fail the test that owns them, not the next one.
 afterEach(() => { assert.equal(script.length, 0, "unconsumed scripted responses"); });
@@ -155,11 +166,43 @@ test("an unreadable quote amount is never signed", async () => {
   assert.equal(signaturesCreated, 0);
 });
 
-test("a missing Solana wallet is a PaymentError with the setup hint", async () => {
-  walletKey = undefined;
-  await assert.rejects(solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, fast), /No Solana wallet found/);
-  assert.equal(requests.length, 0);
-});
+// D3/D30: 783cfb3 taught buildSolanaClient that "the keychain would not open"
+// is not "no wallet" — telling that user to run setup invites a second wallet
+// — and left the two manual-402 helpers saying the old thing. Both helpers
+// now say what buildSolanaClient says, and neither is a funding error: image's
+// catch turns a PaymentError into "out of funds", which is wrong twice over.
+for (const [label, run] of [
+  ["solanaPaidAsyncPost", () => solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, fast)],
+  ["solanaPaidPost", () => solanaPaidPost("/v1/images/generations", { prompt: "t" }, 1_000)],
+] as const) {
+  test(`${label}: a locked keychain is 'unlock and retry', never 'run setup', and not a funding error`, async () => {
+    walletKey = undefined;
+    keyUnavailableReason = "the OS keychain could not be read (security exit 51)";
+    await assert.rejects(run(), (err: Error) => {
+      assert.match(err.message, /Cannot reach your Solana wallet key/);
+      assert.match(err.message, /security exit 51/);
+      assert.match(err.message, /unlock it and retry/);
+      assert.match(err.message, /Nothing was charged/);
+      assert.doesNotMatch(err.message, /action:"setup"|No Solana wallet/, "must not invite a second wallet");
+      assert.notEqual(err.name, "PaymentError", "a locked keychain is not an empty wallet");
+      return true;
+    });
+    assert.equal(requests.length, 0);
+  });
+
+  test(`${label}: no wallet anywhere names setup as the remedy and is not a funding error`, async () => {
+    walletKey = undefined;
+    keyUnavailableReason = undefined;
+    await assert.rejects(run(), (err: Error) => {
+      assert.match(err.message, /No Solana wallet on this machine yet/);
+      assert.match(err.message, /action:"setup"/);
+      assert.match(err.message, /Nothing was charged/);
+      assert.notEqual(err.name, "PaymentError");
+      return true;
+    });
+    assert.equal(requests.length, 0);
+  });
+}
 
 test("a paid route that answers 2xx instead of a quote is a fault, not a free render", async () => {
   script = [() => ({ status: 200, ok: true, headers: headers(), json: async () => ({ data: [{ url: "u" }] }) })];
@@ -169,7 +212,11 @@ test("a paid route that answers 2xx instead of a quote is a fault, not a free re
 
 test("a rejected paid submit is a PaymentError and issues no polls", async () => {
   script = [quote, quote];
-  await assert.rejects(solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, fast), /Payment was rejected/);
+  await assert.rejects(solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, fast), (err: Error) => {
+    assert.match(err.message, /Payment was rejected/);
+    assert.ok(err instanceof FakePaymentError, "a 402 on the paid submit with no reason is a funding problem");
+    return true;
+  });
   assert.equal(gets().length, 0);
 });
 
@@ -280,12 +327,19 @@ test("a completed body without a receipt is still returned, with no txHash", asy
 
 test("a completed status on a non-2xx poll is not trusted", async () => {
   script = [quote, () => submit(), () => ({ status: 500, ok: false, headers: headers(), json: async () => ({ status: "completed", data: [{ url: "u" }] }) })];
-  await assert.rejects(solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, fast), /Video poll error 500/);
+  await assert.rejects(solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, fast), /Video generation poll error 500/);
 });
 
 test("a failed job rejects without a receipt and a 504 is retried", async () => {
   script = [quote, () => submit(), () => ({ status: 504, ok: false, headers: headers(), json: async () => ({}) }), () => poll("failed", { error: "render exploded" })];
-  await assert.rejects(solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, fast), /render exploded.*No payment was taken/);
+  await assert.rejects(solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, fast), (err: Error) => {
+    assert.match(err.message, /render exploded.*No payment was taken/);
+    // Typed, so a tool can recognise the verdict when the upstream text says
+    // "aborted due to timeout" (C13) — the prose is the gateway's, not ours.
+    assert.ok(err instanceof JobFailedError, `expected JobFailedError, got ${err.name}`);
+    assert.equal((err as InstanceType<typeof JobFailedError>).jobId, "vid_1");
+    return true;
+  });
   assert.equal(gets().length, 2);
 });
 
@@ -305,3 +359,340 @@ test("every request is clamped to the remaining budget (no request may outlive t
   for (const t of timeouts) assert.ok(t > 0 && t <= 5_000, `timeout ${t} exceeds the 5s budget`);
   assert.ok(timeouts[1] <= 5_000 && timeouts[2] <= 5_000, "submit and poll were both clamped below their 30s/60s defaults");
 });
+
+// ---------------------------------------------------------------------------
+// Round-3 additions: the paid-request hooks, the 402 classification, the
+// caller labels, settled-at-submit routes, and the deadline wording.
+// ---------------------------------------------------------------------------
+
+test("onPaidRequest fires immediately before every request carrying PAYMENT-SIGNATURE and onPaidResponse after each answer", async () => {
+  const events: string[] = [];
+  script = [
+    () => { events.push("quote"); return quote(); },
+    () => { events.push("submit"); return submit(); },
+    () => { events.push("poll1"); throw new TypeError("transient disconnect"); },
+    () => { events.push("poll2"); return poll("in_progress"); },
+    () => { events.push("poll3"); return poll("completed", { data: [{ url: "u" }] }); },
+  ];
+  await solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, {
+    ...fast,
+    onQuote: () => events.push("onQuote"),
+    onPaidRequest: () => events.push("armed"),
+    onPaidResponse: () => events.push("settled"),
+  });
+  // Nothing is armed around the unpaid quote; every signed request is armed
+  // before it leaves and settled only when an answer arrives — the dropped
+  // poll leaves the tracker armed, which is the whole point.
+  assert.deepEqual(events, ["quote", "onQuote", "armed", "submit", "settled", "armed", "poll1", "armed", "poll2", "settled", "armed", "poll3", "settled"]);
+});
+
+test("the unpaid re-sign challenge GET is not a paid request and fires neither hook", async () => {
+  const events: string[] = [];
+  script = [quote, () => submit(), settleFail402, () => { events.push("challenge"); return challenge402(); }, () => poll("completed", { data: [{ url: "u" }] })];
+  await solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, {
+    ...fast,
+    onPaidRequest: () => events.push("armed"),
+    onPaidResponse: () => events.push("settled"),
+  });
+  assert.deepEqual(events, ["armed", "settled", "armed", "settled", "challenge", "armed", "settled"]);
+});
+
+test("solanaPaidPost arms before the paid POST only, and settles on its answer", async () => {
+  const events: string[] = [];
+  script = [
+    () => { events.push("quote"); return quote(); },
+    () => { events.push("paid"); return { status: 200, ok: true, headers: headers({ "x-payment-receipt": "tx" }), json: async () => ({ data: [{ url: "u" }] }) }; },
+  ];
+  const r = await solanaPaidPost("/v1/images/generations", { prompt: "t" }, 1_000, {
+    onQuote: () => events.push("onQuote"),
+    onPaidRequest: () => events.push("armed"),
+    onPaidResponse: () => events.push("settled"),
+  });
+  assert.equal(r.paidUsd, 0.5);
+  assert.deepEqual(events, ["quote", "onQuote", "armed", "paid", "settled"]);
+});
+
+test("a signing failure after onQuote never reaches onPaidRequest — nothing carrying a payment left the machine", async () => {
+  let armed = 0;
+  failSignOnCall = 1;
+  script = [quote];
+  await assert.rejects(solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, { ...fast, onPaidRequest: () => { armed++; } }), /rpc blip/);
+  assert.equal(armed, 0);
+  assert.equal(posts().length, 1, "only the unpaid quote went out");
+});
+
+// D2: the gateway's PAYMENT-RESPONSE reason splits into two very different
+// remedies. "insufficient" is the wallet; everything else on the permanent
+// list is the signature or the authorization — sending that user to a
+// Coinbase top-up page is the wrong door, and isPaymentRejectionError's
+// substring match ("rejected", "balance") is exactly what routed it there.
+const INVALID_AUTH_REASONS = ["invalid signature", "invalid payment", "unauthorized", "forbidden", "invalid_payload", "expired"];
+for (const reason of INVALID_AUTH_REASONS) {
+  test(`a paid submit 402 whose reason is '${reason}' is a signing/authorization fault, not a funding error`, async () => {
+    script = [quote, () => ({ status: 402, ok: false, headers: headers({ "payment-response": paymentResponse(`verify failed: ${reason}`) }), json: async () => ({ error: "Payment verification failed" }) })];
+    await assert.rejects(solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, fast), (err: Error) => {
+      assert.notEqual(err.name, "PaymentError");
+      assert.match(err.message, /refused the payment signature/);
+      assert.match(err.message, /signing\/authorization fault, not a funding problem/);
+      assert.match(err.message, new RegExp(reason.replace("_", "_")));
+      assert.match(err.message, /no charge was made/i);
+      assert.doesNotMatch(err.message, /rejected|balance|insufficient/i, "must not route to the top-up branch");
+      return true;
+    });
+    assert.equal(gets().length, 0);
+  });
+
+  test(`a settle-time poll 402 whose reason is '${reason}' names the claimable job and is not a funding error`, async () => {
+    script = [quote, () => submit(), () => settleFail402(`settle failed: ${reason}`)];
+    await assert.rejects(solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, fast), (err: Error) => {
+      assert.notEqual(err.name, "PaymentError");
+      assert.match(err.message, /refused the payment signature while settling the completed job/);
+      assert.match(err.message, /not a funding problem/);
+      assert.match(err.message, /no charge was made/i);
+      assert.match(err.message, /claimable.*job vid_1/);
+      assert.doesNotMatch(err.message, /rejected|balance|insufficient/i);
+      return true;
+    });
+    assert.equal(signaturesCreated, 1, "no re-sign against a signature the gateway refused outright");
+  });
+}
+
+test("a paid submit 402 whose reason says 'insufficient' stays a PaymentError, with the reason", async () => {
+  script = [quote, () => ({ status: 402, ok: false, headers: headers({ "payment-response": paymentResponse("insufficient funds for transfer") }), json: async () => ({}) })];
+  await assert.rejects(solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, fast), (err: Error) => {
+    assert.ok(err instanceof FakePaymentError);
+    assert.match(err.message, /Payment was rejected.*insufficient funds/);
+    return true;
+  });
+});
+
+test("solanaPaidPost classifies its paid-POST 402 the same way", async () => {
+  script = [quote, () => ({ status: 402, ok: false, headers: headers({ "payment-response": paymentResponse("invalid signature") }), json: async () => ({}) })];
+  await assert.rejects(solanaPaidPost("/v1/images/generations", { prompt: "t" }, 1_000), (err: Error) => {
+    assert.notEqual(err.name, "PaymentError");
+    assert.match(err.message, /signing\/authorization fault/);
+    assert.match(err.message, /no charge was made/i);
+    assert.doesNotMatch(err.message, /rejected|balance|insufficient/i);
+    return true;
+  });
+  script = [quote, () => ({ status: 402, ok: false, headers: headers(), json: async () => ({}) })];
+  await assert.rejects(solanaPaidPost("/v1/images/generations", { prompt: "t" }, 1_000), (err: Error) => err instanceof FakePaymentError);
+});
+
+test("quote-validation refusals are gateway faults, not funding errors", async () => {
+  // Every one of these says "no charge was made" and none is the wallet's
+  // fault; image.ts turns a PaymentError into "out of funds" plus a top-up note.
+  const cases: Array<[string, () => void, Array<() => unknown>, RegExp]> = [
+    ["non-Solana network", () => { details = { ...baseDetails(), network: "eip155:8453" }; }, [quote], /Expected a Solana payment quote/],
+    ["missing feePayer", () => { details = { ...baseDetails(), extra: {} }; }, [quote], /Missing feePayer/],
+    ["unreadable amount", () => { details = { ...baseDetails(), amount: "x" }; }, [quote], /unreadable amount/],
+    ["off-gateway poll", () => {}, [quote, () => submit("https://evil.example/poll")], /off-gateway poll URL/],
+    ["mutated challenge", () => {}, [quote, () => submit(), settleFail402, () => { details = { ...baseDetails(), amount: "900000" }; return challenge402(); }], /changed the payment amount/],
+  ];
+  for (const [label, arrange, wire, expect] of cases) {
+    details = baseDetails(); arrange(); script = wire;
+    await assert.rejects(solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, fast), (err: Error) => {
+      assert.match(err.message, expect, label);
+      assert.notEqual(err.name, "PaymentError", `${label}: not a funding error`);
+      return true;
+    });
+    details = baseDetails(); requests = []; signaturesCreated = 0;
+  }
+});
+
+// D1/D22: music routes its Solana rail through this helper and every give-up
+// said "Video generation" and "re-running blockrun_video".
+test("the caller's labels reach every message; the defaults are video's", async () => {
+  const music = { ...fast, what: "Music generation", tool: "blockrun_music" };
+  script = [quote, () => submit(), () => poll("failed", { error: "boom" })];
+  await assert.rejects(solanaPaidAsyncPost("/v1/audio/generations", { prompt: "t" }, music), (err: Error) => {
+    assert.match(err.message, /^Music generation failed upstream: boom/);
+    assert.doesNotMatch(err.message, /video/i);
+    return true;
+  });
+  script = [quote, () => submit(), ...Array.from({ length: 200 }, () => () => poll("in_progress"))];
+  await assert.rejects(solanaPaidAsyncPost("/v1/audio/generations", { prompt: "t" }, { ...music, pollBudgetMs: 30 }), (err: Error) => {
+    assert.match(err.message, /^Music generation did not complete within/);
+    assert.match(err.message, /re-running blockrun_music would start and charge a new job/);
+    assert.doesNotMatch(err.message, /video/i);
+    return true;
+  });
+  script = [];
+  script = [quote, () => submit(), () => ({ status: 500, ok: false, headers: headers(), json: async () => ({}) })];
+  await assert.rejects(solanaPaidAsyncPost("/v1/audio/generations", { prompt: "t" }, music), /Music generation poll error 500/);
+  script = [quote, () => submit(), ...Array.from({ length: 200 }, () => () => poll("in_progress"))];
+  await assert.rejects(solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, { ...fast, pollBudgetMs: 30 }), /Video generation did not complete within.*re-running blockrun_video/);
+  script = [];
+});
+
+// The deadline message says what the helper KNOWS. With the hooks it knows
+// whether a signed poll was outstanding when the budget ran out; before, it
+// always said "a poll still in flight can settle" and the tools booked on it.
+test("deadline with the last poll answered: no request is outstanding, so no charge was made", async () => {
+  script = [quote, () => submit(), ...Array.from({ length: 200 }, () => () => poll("in_progress"))];
+  await assert.rejects(solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, { ...fast, pollBudgetMs: 30 }), (err: Error) => {
+    assert.match(err.message, /last poll was answered/);
+    assert.match(err.message, /no charge was made/i);
+    assert.doesNotMatch(err.message, /still in flight/);
+    return true;
+  });
+  script = [];
+});
+
+test("deadline with the last poll dropped: a signed poll is still in flight and can settle server-side", async () => {
+  let n = 0;
+  script = [quote, () => submit(), ...Array.from({ length: 200 }, () => () => { n++; throw new TypeError("fetch failed"); })];
+  await assert.rejects(solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, { ...fast, pollBudgetMs: 30 }), (err: Error) => {
+    assert.match(err.message, /still in flight at the deadline/);
+    assert.match(err.message, /can settle server-side/);
+    assert.doesNotMatch(err.message, /no charge was made/i);
+    return true;
+  });
+  assert.ok(n >= 1);
+  script = [];
+});
+
+// Settled-at-submit routes. sol.blockrun.ai's audio route (blockrun_music)
+// settles the SPL transfer OPTIMISTICALLY when the POST is accepted — the
+// 202 says payment_status "settled_optimistic" and carries X-Payment-Optimistic
+// — and the poll GET is pure delivery. So on that route a failed job, a
+// deadline or a poll error is a CERTAIN charge, not "no payment was taken",
+// and the helper hands the tool the same BilledJobError the account rail uses.
+const optimistic202 = () => ({
+  status: 202, ok: true, headers: headers({ "x-payment-optimistic": "true" }),
+  json: async () => ({ id: "aud_1", status: "queued", poll_url: "/api/v1/audio/generations/aud_1", payment_status: "settled_optimistic" }),
+});
+const bodyOnly202 = () => ({
+  status: 202, ok: true, headers: headers(),
+  json: async () => ({ id: "aud_1", status: "queued", poll_url: "/api/v1/audio/generations/aud_1", payment_status: "settled_optimistic" }),
+});
+const music = { ...fast, what: "Music generation", tool: "blockrun_music" };
+
+test("settled-at-submit: a failed job is a BilledJobError carrying the quote and the job — the charge stands", async () => {
+  for (const submitted of [optimistic202, bodyOnly202]) {
+    script = [quote, submitted, () => ({ status: 200, ok: true, headers: headers(), json: async () => ({ status: "failed", error: "The operation was aborted due to timeout", note: "Payment was settled optimistically at POST" }) })];
+    await assert.rejects(solanaPaidAsyncPost("/v1/audio/generations", { prompt: "t" }, music), (err: Error) => {
+      assert.ok(err instanceof BilledJobError, `expected BilledJobError, got ${err.name}: ${err.message}`);
+      const billed = err as InstanceType<typeof BilledJobError>;
+      assert.equal(billed.billing, "billed");
+      assert.equal(billed.paidUsd, 0.5);
+      assert.equal(billed.jobId, "aud_1");
+      assert.match(err.message, /^Music generation failed upstream: The operation was aborted due to timeout/);
+      assert.match(err.message, /settled .*at submit/i);
+      assert.match(err.message, /charge stands/);
+      assert.doesNotMatch(err.message, /No payment was taken|no charge was made/i);
+      return true;
+    });
+    requests = []; signaturesCreated = 0;
+  }
+});
+
+test("settled-at-submit: the deadline and a poll error are BilledJobErrors that name the claimable job", async () => {
+  script = [quote, optimistic202, ...Array.from({ length: 200 }, () => () => poll("in_progress"))];
+  await assert.rejects(solanaPaidAsyncPost("/v1/audio/generations", { prompt: "t" }, { ...music, pollBudgetMs: 30 }), (err: Error) => {
+    assert.ok(err instanceof BilledJobError);
+    assert.match(err.message, /did not complete within/);
+    assert.match(err.message, /charge stands/);
+    assert.match(err.message, /claimable.*job aud_1.*re-running blockrun_music/);
+    assert.doesNotMatch(err.message, /no charge was made|can settle server-side/i);
+    return true;
+  });
+  script = [];
+  script = [quote, optimistic202, () => ({ status: 500, ok: false, headers: headers(), json: async () => ({ error: "boom" }) })];
+  await assert.rejects(solanaPaidAsyncPost("/v1/audio/generations", { prompt: "t" }, music), (err: Error) => {
+    assert.ok(err instanceof BilledJobError);
+    assert.match(err.message, /poll error 500/);
+    assert.match(err.message, /charge stands/);
+    return true;
+  });
+});
+
+test("settled-at-submit: a completed poll with no receipt header still returns the quote as paid", async () => {
+  script = [quote, optimistic202, () => ({ status: 200, ok: true, headers: headers(), json: async () => ({ status: "completed", data: [{ url: "https://blockrun.ai/media/t.mp3" }], payment: { status: "settled_at_post" } }) })];
+  const r = await solanaPaidAsyncPost("/v1/audio/generations", { prompt: "t" }, music);
+  assert.equal(r.paidUsd, 0.5);
+  assert.equal(r.jobId, "aud_1");
+  assert.equal(r.txHash, undefined);
+});
+
+// Audit round 4: every escape from the post-submit loop, not just the ones
+// the round-3 branch enumerated. The reactive re-sign path could still throw
+// a plain "No charge was made" (a mutated challenge, a quote it could not
+// parse) or a bare RPC error from the re-sign, and music then reported
+// "failed"/"No payment was taken" with nothing booked — for a track the
+// gateway had settled at POST.
+test("settled-at-submit: every post-submit escape is a BilledJobError — re-sign refusals and RPC faults included", async () => {
+  // A re-priced challenge on a settled route: the refusal stands, but the
+  // charge does too.
+  script = [quote, optimistic202, settleFail402, () => { details = { ...baseDetails(), amount: "900000" }; return challenge402(); }];
+  await assert.rejects(solanaPaidAsyncPost("/v1/audio/generations", { prompt: "t" }, music), (err: Error) => {
+    assert.ok(err instanceof BilledJobError, `expected BilledJobError, got ${err.name}: ${err.message}`);
+    assert.match(err.message, /changed the payment amount/);
+    assert.match(err.message, /charge stands/);
+    assert.doesNotMatch(err.message, /no charge was made/i);
+    assert.equal((err as InstanceType<typeof BilledJobError>).paidUsd, 0.5);
+    return true;
+  });
+  details = baseDetails(); requests = []; signaturesCreated = 0;
+
+  // A fresh challenge with no readable requirements.
+  script = [quote, optimistic202, settleFail402, () => ({ status: 402, ok: false, headers: headers(), json: async () => ({}) })];
+  await assert.rejects(solanaPaidAsyncPost("/v1/audio/generations", { prompt: "t" }, music), (err: Error) => {
+    assert.ok(err instanceof BilledJobError, `expected BilledJobError, got ${err.name}: ${err.message}`);
+    assert.match(err.message, /no payment requirements/);
+    assert.match(err.message, /charge stands/);
+    assert.doesNotMatch(err.message, /no charge was made/i);
+    return true;
+  });
+  requests = []; signaturesCreated = 0;
+
+  // The re-sign itself fails (RPC) on the reactive path.
+  script = [quote, optimistic202, settleFail402, challenge402];
+  signCalls = 0; failSignOnCall = 2;
+  await assert.rejects(solanaPaidAsyncPost("/v1/audio/generations", { prompt: "t" }, music), (err: Error) => {
+    assert.ok(err instanceof BilledJobError, `expected BilledJobError, got ${err.name}: ${err.message}`);
+    assert.match(err.message, /rpc blip/);
+    assert.match(err.message, /charge stands/);
+    return true;
+  });
+  requests = []; signaturesCreated = 0; failSignOnCall = null; signCalls = 0;
+
+  // Re-sign exhaustion on a settled route is a charge, not "no charge".
+  script = [quote, optimistic202, settleFail402, challenge402, settleFail402];
+  await assert.rejects(solanaPaidAsyncPost("/v1/audio/generations", { prompt: "t" }, { ...music, maxReactiveResigns: 1 }), (err: Error) => {
+    assert.ok(err instanceof BilledJobError, `expected BilledJobError, got ${err.name}: ${err.message}`);
+    assert.match(err.message, /did not go through after 1 re-signs/);
+    assert.match(err.message, /charge stands/);
+    assert.doesNotMatch(err.message, /no charge was made/i);
+    return true;
+  });
+});
+
+test("payment-on-completion routes keep their plain refusals: a re-priced challenge is not a billed job", async () => {
+  script = [quote, () => submit(), settleFail402, () => { details = { ...baseDetails(), amount: "900000" }; return challenge402(); }];
+  await assert.rejects(solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, fast), (err: Error) => {
+    assert.equal(err instanceof BilledJobError, false);
+    assert.match(err.message, /No charge was made/);
+    return true;
+  });
+  details = baseDetails();
+});
+
+test("payment-on-completion routes (video) are untouched by the settled-at-submit branch", async () => {
+  script = [quote, () => submit(), () => poll("failed", { error: "boom", payment_status: "not_charged" })];
+  await assert.rejects(solanaPaidAsyncPost("/v1/videos/generations", { prompt: "t" }, fast), (err: Error) => {
+    assert.ok(err instanceof JobFailedError);
+    assert.equal(err instanceof BilledJobError, false);
+    return true;
+  });
+});
+
+// C15: the Solana audio route holds the paid POST inline for up to 60s and
+// settles at POST regardless; the helper's 30s default was sized for the
+// always-202 video route. The submit timeout is per-route, and the caller's
+// value must reach the wire.
+test("submitTimeoutMs is honoured on the paid submit", async () => {
+  script = [quote, optimistic202, () => poll("completed", { data: [{ url: "u" }] }, false)];
+  await solanaPaidAsyncPost("/v1/audio/generations", { prompt: "t" }, { ...music, submitTimeoutMs: 95_000, pollBudgetMs: 240_000 });
+  assert.equal(timeouts[1], 95_000, `paid submit timeout was ${timeouts[1]}`);
+});
diff --git a/test/solana-provisioning-regressions.test.ts b/test/solana-provisioning-regressions.test.ts
new file mode 100644
index 0000000..277c592
--- /dev/null
+++ b/test/solana-provisioning-regressions.test.ts
@@ -0,0 +1,152 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// Two regressions the 0.49.0 keychain-aware Solana provisioning introduced,
+// found by the round-2 audit. Both are about a FUNDED wallet.
+//
+//  1. Under BLOCKRUN_KEYCHAIN=strict the mint stores the key and deletes
+//     .solana-session, so the post-provision getChain() sees neither the file
+//     nor a fresh keychain probe (it was memoised before the mint) and answers
+//     "base" twice. No .chain-auto pin was written, and the NEXT start found the
+//     stored key and moved a funded Base user onto an empty Solana wallet — the
+//     0.32.3 failure CHAIN_AUTO_FILE exists to prevent.
+//
+//  2. The wallet cache is assigned after `await createSolanaWallet()`, so two
+//     overlapping callers both minted. 0.49.0 made that reachable from two
+//     entry points at once (the blockrun://wallet resource and action:"setup"),
+//     and last-writer-wins means one caller is handed a funding address whose
+//     key was thrown away.
+import { test, mock, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const home = fs.mkdtempSync(path.join(os.tmpdir(), "br-sol-prov-"));
+const blockrunDir = path.join(home, ".blockrun");
+fs.mkdirSync(blockrunDir, { recursive: true });
+const saved = { HOME: process.env.HOME, KC: process.env.BLOCKRUN_KEYCHAIN, SOL: process.env.SOLANA_WALLET_KEY, EVM: process.env.BLOCKRUN_WALLET_KEY, API: process.env.BLOCKRUN_API_KEY };
+process.env.HOME = home;
+delete process.env.SOLANA_WALLET_KEY;
+delete process.env.BLOCKRUN_API_KEY;
+
+// A keychain that behaves like the real one in strict mode: persistKey stores
+// the secret AND deletes the plaintext file, which is the step that blinds
+// getChain() to the wallet that was just created.
+let mode = "strict";
+let readFails = false;
+const store = new Map<string, string>();
+mock.module("../src/utils/keychain.js", {
+  namedExports: {
+    EVM_KEY_ACCOUNT: "evm-wallet-key",
+    SOLANA_KEY_ACCOUNT: "solana-wallet-key",
+    getKeychainMode: () => mode,
+    keychainLoad: (a: string) => store.get(a) ?? null,
+    keychainRead: (a: string) =>
+      readFails
+        ? { status: "error", detail: "security exit 51" }
+        : store.has(a)
+          ? { status: "found", value: store.get(a) }
+          : { status: "absent" },
+    persistKey: (account: string, key: string, file?: string) => {
+      store.set(account, key);
+      if (mode === "strict" && file && fs.existsSync(file)) fs.rmSync(file, { force: true });
+    },
+  },
+});
+
+const wallet = await import("../src/utils/wallet.js");
+
+process.on("exit", () => {
+  for (const [k, v] of Object.entries({ HOME: saved.HOME, BLOCKRUN_KEYCHAIN: saved.KC, SOLANA_WALLET_KEY: saved.SOL, BLOCKRUN_WALLET_KEY: saved.EVM, BLOCKRUN_API_KEY: saved.API })) {
+    if (v === undefined) delete process.env[k]; else process.env[k] = v;
+  }
+  fs.rmSync(home, { recursive: true, force: true });
+});
+
+beforeEach(() => {
+  for (const f of [".chain", ".chain-auto", ".solana-session", ".session"]) fs.rmSync(path.join(blockrunDir, f), { force: true });
+  store.clear();
+  mode = "strict";
+  readFails = false;
+  wallet.resetSolanaKeyCache();
+  wallet.resetEvmWalletCache();
+  wallet.resetKeychainProbeCache();
+});
+
+test("strict mode: provisioning Solana for a Base user writes the continuity pin", async () => {
+  // An existing Base-only user: a key file on disk, no chain preference.
+  fs.writeFileSync(path.join(blockrunDir, ".session"), "0x" + "11".repeat(32), { mode: 0o600 });
+  assert.equal(wallet.getChain(), "base", "precondition: this user is on Base");
+
+  const both = await wallet.ensureBothWallets();
+  assert.equal(both.solana.isNew, true, "precondition: the Solana wallet was minted here");
+
+  // The mint stored the key and (strict) deleted the file, so a later probe
+  // would see a Solana key and move the user. The pin has to outrank it.
+  assert.equal(fs.existsSync(path.join(blockrunDir, ".chain-auto")), true, "continuity pin must be written");
+  wallet.resetKeychainProbeCache();
+  wallet.resetSolanaKeyCache();
+  assert.equal(wallet.getChain(), "base", "a funded Base user must NOT be moved by provisioning");
+});
+
+test("a fresh install keeps its Solana default against the Base wallet it just minted", async () => {
+  // Both wallets are new. getChain() answered "solana" (the fresh-install
+  // default) BEFORE provisioning, and minting the EVM wallet is exactly what
+  // would flip it to "base" on the next start, so the pin belongs here too —
+  // the direction is just reversed.
+  const both = await wallet.ensureBothWallets();
+  assert.equal(both.base.isNew, true);
+  assert.equal(both.solana.isNew, true);
+  assert.equal(fs.readFileSync(path.join(blockrunDir, ".chain-auto"), "utf-8").trim(), "solana");
+
+  wallet.resetKeychainProbeCache();
+  wallet.resetSolanaKeyCache();
+  wallet.resetEvmWalletCache();
+  assert.equal(wallet.getChain(), "solana", "the default the user started on must survive provisioning");
+});
+
+test("no pin when nothing was minted — a second run does not rewrite it", async () => {
+  fs.writeFileSync(path.join(blockrunDir, ".session"), "0x" + "11".repeat(32), { mode: 0o600 });
+  await wallet.ensureBothWallets();
+  fs.rmSync(path.join(blockrunDir, ".chain-auto"), { force: true });
+
+  // Everything already exists now, so the second call mints nothing and must
+  // not write a pin off a stale probe.
+  await wallet.ensureBothWallets();
+  assert.equal(fs.existsSync(path.join(blockrunDir, ".chain-auto")), false, "nothing minted, nothing to preserve");
+});
+
+test("an explicit chain preference is never overwritten by provisioning", async () => {
+  fs.writeFileSync(path.join(blockrunDir, ".chain"), "solana");
+  await wallet.ensureBothWallets();
+  assert.equal(fs.existsSync(path.join(blockrunDir, ".chain-auto")), false, "an explicit .chain already wins");
+  assert.equal(wallet.getChain(), "solana");
+});
+
+test("concurrent callers mint ONE Solana wallet, not one each", async () => {
+  const [a, b, c] = await Promise.all([
+    wallet.ensureSolanaWallet(),
+    wallet.ensureSolanaWallet(),
+    wallet.ensureSolanaWallet(),
+  ]);
+  assert.equal(a.address, b.address);
+  assert.equal(b.address, c.address);
+  // And the address every caller was handed is the key the machine kept.
+  assert.equal(store.get("solana-wallet-key"), a.privateKey, "the stored key must be the one callers were shown");
+  assert.equal(wallet.resolveSolanaKey(), a.privateKey);
+});
+
+test("a failed provisioning is NOT cached — unlocking the keychain and retrying works", async () => {
+  // Strict mode with an unreadable keychain and no file: refuse to mint, which
+  // is 0.49.0's rule. The rejection must not be memoised by the single-flight
+  // promise, or a user who unlocks and retries stays broken until restart.
+  readFails = true;
+  await assert.rejects(wallet.ensureSolanaWallet(), /Refusing to create a new Solana wallet/);
+  await assert.rejects(wallet.ensureSolanaWallet(), /Refusing to create a new Solana wallet/);
+
+  // Unlock it: the very next call in the SAME process must succeed.
+  readFails = false;
+  const info = await wallet.ensureSolanaWallet();
+  assert.equal(info.isNew, true);
+  assert.equal(store.get("solana-wallet-key"), info.privateKey);
+});
diff --git a/test/solana-rail-parity.test.ts b/test/solana-rail-parity.test.ts
new file mode 100644
index 0000000..022043a
--- /dev/null
+++ b/test/solana-rail-parity.test.ts
@@ -0,0 +1,210 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// 0.49.0 taught the media tools two things and taught them per-rail, which is
+// how the DEFAULT chain ended up with neither:
+//
+//   1. A quote guard before signing (video both rails, image on Solana) — music
+//      and speech kept signing whatever the 402 said.
+//   2. Conservative booking when we give up while a paid request may still be
+//      in flight (Base via paidPollInFlight, account rail via BilledJobError) —
+//      the Solana rail booked nothing, so a settled render moved no budget at
+//      all and the caller was invited to pay for it twice.
+//
+// Solana has been the default chain since 0.46.0.
+//
+// Round 3 found this file promised parity across "the media tools" and drove
+// blockrun_music alone, and that its first test counted helper invocations
+// rather than whether an onQuote was passed. It now runs every manual-402
+// tool through the same four cases at the HELPER seam (solanaPaidPost /
+// solanaPaidAsyncPost mocked); rail-parity.test.ts drives the same tools over
+// a scripted wire with the real helper underneath.
+import { test, mock, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import type { BudgetState } from "../src/types.js";
+
+let quoteUsd: number | null = 0.5;
+let giveUp = false;
+let onQuoteWasFunction: boolean | null = null;
+let paidPostsIssued = 0;
+let happyBody: unknown = {};
+const abortError = () => { const e = new Error("This operation was aborted"); e.name = "AbortError"; return e; };
+
+mock.module("../src/utils/wallet.js", {
+  namedExports: {
+    getApiBase: () => "https://sol.blockrun.ai/api",
+    resolveGatewayUrl: (u: string) => u,
+    getChain: () => "solana",
+    getOrCreateWalletKey: () => { throw new Error("Base wallet must not be touched on the Solana rail"); },
+    getImageClient: () => { throw new Error("the SDK ImageClient must not be used on the Solana rail"); },
+    getWalletInfo: async () => ({ address: "So1anaTest" }),
+    resolveSolanaKey: () => "solana-secret-key",
+    solanaKeyUnavailableReason: () => undefined,
+  },
+});
+mock.module("../src/utils/auth.js", {
+  namedExports: {
+    DEFAULT_API_KEY_BASE: "https://api.blockrun.ai",
+    PORTAL_URL: "https://user.blockrun.ai",
+    PORTAL_KEYS_URL: "https://user.blockrun.ai/dashboard/keys",
+    PORTAL_CREDITS_URL: "https://user.blockrun.ai/dashboard/credits",
+    PORTAL_ACTIVITY_URL: "https://user.blockrun.ai/dashboard/activity",
+    getApiKey: () => undefined,
+    getAuthMode: () => "wallet",
+    isApiKeyMode: () => false,
+    getApiKeyBase: () => "https://api.blockrun.ai",
+    apiAuthHeaders: () => ({}),
+    requireWalletMode: () => null,
+    resetAuthCache: () => {},
+  },
+});
+mock.module("../src/utils/solana-402.js", {
+  namedExports: {
+    // The async helper (video, music): hands the caller the authoritative
+    // quote BEFORE signing, then either finishes or gives up on its deadline
+    // with the helper's own "a poll still in flight can settle" wording.
+    solanaPaidAsyncPost: async (_e: string, _b: unknown, opts: { onQuote?: (usd: number | null, d?: unknown) => void }) => {
+      onQuoteWasFunction = typeof opts.onQuote === "function";
+      opts.onQuote?.(quoteUsd, { resource: { description: "Seedance 2.0 Pro video generation (5s)" } });
+      paidPostsIssued++;
+      if (giveUp) {
+        throw new Error(
+          "Generation did not complete within 900s (last status: processing). No settlement receipt was " +
+          "observed by this client; a poll still in flight at the deadline can settle server-side, so check the " +
+          "wallet's recent transactions before retrying.",
+        );
+      }
+      return { data: happyBody, paidUsd: quoteUsd, txHash: "sol-tx" };
+    },
+    // The synchronous helper (speech, image, realface): same hook, and on a
+    // give-up the paid POST itself aborts after the transfer was signed. The
+    // real helper fires onPaidRequest the line before the signed POST leaves
+    // and onPaidResponse when any answer arrives — the seam the tools arm
+    // and settle their tracker at since audit round 4 — so this stand-in
+    // honours the same contract: a give-up is a request that LEFT and never
+    // answered.
+    solanaPaidPost: async (_e: string, _b: unknown, _t: number, opts?: { onQuote?: (usd: number | null, d?: unknown) => void; onPaidRequest?: () => void; onPaidResponse?: () => void }) => {
+      onQuoteWasFunction = typeof opts?.onQuote === "function";
+      opts?.onQuote?.(quoteUsd, { resource: { description: "Seedance 2.0 Pro video generation (5s)" } });
+      opts?.onPaidRequest?.();
+      paidPostsIssued++;
+      if (giveUp) throw abortError();
+      opts?.onPaidResponse?.();
+      return { data: happyBody, paidUsd: quoteUsd, txHash: "sol-tx" };
+    },
+  },
+});
+mock.module("../src/utils/http.js", {
+  namedExports: {
+    fetchWithTimeout: async () => { throw new Error("the Base HTTP route must not be reached"); },
+    isTimeoutError: (err: unknown) => {
+      const name = err instanceof Error ? err.name : "";
+      if (name === "AbortError" || name === "TimeoutError") return true;
+      const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+      return msg.includes("abort") || msg.includes("timeout") || msg.includes("timed out") || msg.includes("did not complete within");
+    },
+  },
+});
+mock.module("../src/utils/ssrf.js", {
+  namedExports: { isBlockedFetchHostResolved: async () => false, isBlockedFetchHost: () => false },
+});
+class FakePaymentError extends Error { constructor(m: string) { super(m); this.name = "PaymentError"; } }
+mock.module("@blockrun/llm", {
+  namedExports: {
+    PaymentError: FakePaymentError,
+    createPaymentPayload: async () => { throw new Error("nothing is signed on Base in this suite"); },
+    parsePaymentRequired: () => ({}),
+    extractPaymentDetails: () => ({}),
+    solanaPublicKey: async () => "So1anaTest",
+  },
+});
+
+const { registerVideoTool, estimateVideoCost } = await import("../src/tools/video.js");
+const { registerMusicTool } = await import("../src/tools/music.js");
+const { registerSpeechTool, speechCost } = await import("../src/tools/speech.js");
+const { registerImageTool, estimateCost: estimateImageCost } = await import("../src/tools/image.js");
+const { registerRealfaceTool } = await import("../src/tools/realface.js");
+const { withTxFee } = await import("../src/utils/tx-fee.js");
+
+type Register = (server: any, budget: BudgetState) => void;
+function makeHarness(register: Register, limit: number | null = null) {
+  let handler: ((a: Record<string, unknown>) => Promise<any>) | undefined;
+  const server = { registerTool: (_n: string, _c: unknown, h: any) => { handler = h; }, server: { getClientCapabilities: () => ({}) } } as any;
+  const budget: BudgetState = { limit, spent: 0, calls: 0, agents: new Map() };
+  register(server, budget);
+  return { call: (a: Record<string, unknown>) => handler!(a), budget };
+}
+const text = (res: any) => res.content.map((c: any) => c.text).join("\n");
+const near = (a: number, b: number) => Math.abs(a - b) < 1e-9;
+
+const INPUT = "x".repeat(1000);
+const TOOLS: Array<{ name: string; register: Register; args: Record<string, unknown>; estimate: number; happy: unknown }> = [
+  { name: "video", register: registerVideoTool, args: { prompt: "a cube", model: "bytedance/seedance-2.0", duration_seconds: 5 }, estimate: estimateVideoCost("bytedance/seedance-2.0", 5), happy: { status: "completed", data: [{ url: "https://blockrun.ai/media/v.mp4", duration_seconds: 5 }] } },
+  { name: "music", register: registerMusicTool, args: { prompt: "lofi", instrumental: true, model: "minimax/music-2.5+" }, estimate: withTxFee(0.1575), happy: { data: [{ url: "https://blockrun.ai/media/x.mp3", duration_seconds: 30 }] } },
+  { name: "speech", register: registerSpeechTool, args: { action: "speak", input: INPUT, model: "elevenlabs/flash-v2.5", response_format: "mp3" }, estimate: speechCost("elevenlabs/flash-v2.5", INPUT), happy: { data: [{ url: "https://blockrun.ai/media/s.mp3", format: "mp3" }] } },
+  { name: "image", register: registerImageTool, args: { prompt: "a red cube", model: "zai/cogview-4", size: "1024x1024" }, estimate: estimateImageCost("zai/cogview-4", "1024x1024"), happy: { data: [{ url: "https://blockrun.ai/media/i.png" }] } },
+  { name: "realface", register: registerRealfaceTool, args: { action: "portrait", name: "Ada", image_url: "https://ok.example.com/ada.png" }, estimate: withTxFee(0.01), happy: { asset_id: "ta_abc", name: "Ada" } },
+];
+
+beforeEach(() => { quoteUsd = 0.5; giveUp = false; onQuoteWasFunction = null; paidPostsIssued = 0; happyBody = {}; });
+
+for (const t of TOOLS) {
+  test(`${t.name} on Solana hands the helper an onQuote — the guard cannot fire against nobody`, async () => {
+    // Asserted on the OPTION, not on the helper being called: the first
+    // version counted invocations, which removing onQuote left unchanged.
+    quoteUsd = t.estimate;
+    happyBody = t.happy;
+    const { call } = makeHarness(t.register);
+    await call(t.args);
+    assert.equal(onQuoteWasFunction, true, `${t.name}: no onQuote passed to the Solana helper`);
+  });
+
+  test(`${t.name}: a Solana quote far above the published rate is refused BEFORE the transfer is signed`, async () => {
+    // The exact 2026-09-08 shape: sol.blockrun.ai quoting a different product
+    // at 2.7x. Refused inside onQuote, so the helper never reaches its paid POST.
+    quoteUsd = Number((t.estimate * 2.7).toFixed(6));
+    const { call, budget } = makeHarness(t.register);
+    const res = await call(t.args);
+    const txt = text(res);
+    assert.equal(res.isError, true, txt);
+    assert.match(txt, new RegExp(`quoted \\$${quoteUsd.toFixed(4)}`), txt);
+    assert.match(txt, /Seedance 2\.0 Pro video generation/, "names what the gateway said it was quoting");
+    assert.match(txt, /no charge was made/i);
+    assert.doesNotMatch(txt, /needs funding|out of funds/i, "a refused quote is not a funding problem");
+    assert.equal(paidPostsIssued, 0, `${t.name}: the paid POST must never be issued for a refused quote`);
+    assert.equal(budget.spent, 0, "a refused quote settles nothing");
+  });
+
+  test(`${t.name}: a quote inside the tolerance still re-reserves against the cap before signing`, async () => {
+    quoteUsd = Number((t.estimate * 1.25).toFixed(6)); // real markup, allowed by the guard
+    const { call, budget } = makeHarness(t.register, t.estimate * 1.1); // the estimate fits; the quote does not
+    const res = await call(t.args);
+    const txt = text(res);
+    assert.equal(res.isError, true, txt);
+    assert.match(txt, /budget|limit/i, txt);
+    assert.match(txt, /No charge was made/i);
+    assert.equal(paidPostsIssued, 0, `${t.name}: the paid POST must not go out past the cap`);
+    assert.equal(budget.spent, 0);
+  });
+
+  test(`${t.name}: giving up on Solana books the QUOTE conservatively instead of reporting a free failure`, async () => {
+    quoteUsd = Number((t.estimate * 1.2).toFixed(6));
+    giveUp = true;
+    const { call, budget } = makeHarness(t.register);
+    const res = await call(t.args);
+    const txt = text(res);
+    assert.equal(res.isError, true, txt);
+    assert.match(txt, /MAY have gone through/, txt);
+    assert.match(txt, /action:"report"/);
+    assert.doesNotMatch(txt, /No payment was taken/, "Solana cannot promise that");
+    assert.ok(near(budget.spent, quoteUsd), `${t.name}: the quote must be booked: spent=${budget.spent}, quote=${quoteUsd}`);
+  });
+
+  test(`${t.name}: the happy path books exactly the settled amount, once`, async () => {
+    quoteUsd = Number((t.estimate * 1.02).toFixed(6));
+    happyBody = t.happy;
+    const { call, budget } = makeHarness(t.register);
+    const res = await call(t.args);
+    assert.notEqual(res.isError, true, text(res));
+    assert.ok(near(budget.spent, quoteUsd), `${t.name}: spent=${budget.spent}, quote=${quoteUsd}`);
+  });
+}
diff --git a/test/speech-money-path.test.ts b/test/speech-money-path.test.ts
new file mode 100644
index 0000000..4f341f6
--- /dev/null
+++ b/test/speech-money-path.test.ts
@@ -0,0 +1,233 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// blockrun_speech's money path, driven through the registered handler on
+// every rail with the wire scripted. Until audit round 3 speech had NO handler
+// test at all (speech-cost.test.ts is the estimator only), which is how it
+// shipped with a quote guard on Base alone and an in-flight booking that was
+// dead on Base and absent on Solana and the account rail. The give-up cells
+// live in rail-parity.test.ts; this file pins the rest of the ledger: what a
+// settled call books, what a refused quote does, and that an answered 402 is
+// a funding problem rather than a "maybe".
+import { test, mock, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import type { BudgetState } from "../src/types.js";
+
+const TEST_KEY = "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d";
+
+function headers(map: Record<string, string> = {}) {
+  const lower = Object.fromEntries(Object.entries(map).map(([k, v]) => [k.toLowerCase(), v]));
+  return { get: (name: string) => lower[name.toLowerCase()] ?? null };
+}
+
+type Rail = "base" | "solana" | "account";
+let rail: Rail = "base";
+let script: Array<() => unknown> = [];
+let quotedAmount = "54500";
+let paymentsSigned = 0;
+mock.module("../src/utils/http.js", {
+  namedExports: {
+    fetchWithTimeout: async () => {
+      const next = script.shift();
+      if (!next) throw new Error("UNEXPECTED_NETWORK_CALL");
+      return next();
+    },
+    isTimeoutError: (err: unknown) => {
+      const name = err instanceof Error ? err.name : "";
+      if (name === "AbortError" || name === "TimeoutError") return true;
+      const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+      return msg.includes("abort") || msg.includes("timeout") || msg.includes("timed out") || msg.includes("did not complete within");
+    },
+  },
+});
+mock.module("../src/utils/wallet.js", {
+  namedExports: {
+    getApiBase: () => (rail === "account" ? "https://api.blockrun.ai" : rail === "solana" ? "https://sol.blockrun.ai/api" : "https://blockrun.ai/api"),
+    resolveGatewayUrl: (u: string) => u,
+    getChain: () => (rail === "solana" ? "solana" : "base"),
+    getOrCreateWalletKey: () => {
+      if (rail !== "base") throw new Error(`the EVM wallet must not be touched on the ${rail} rail`);
+      return TEST_KEY;
+    },
+    getWalletInfo: async () => ({ address: "0xTEST" }),
+    resolveSolanaKey: () => (rail === "solana" ? "solana-secret-key" : undefined),
+  },
+});
+mock.module("../src/utils/auth.js", {
+  namedExports: {
+    DEFAULT_API_KEY_BASE: "https://api.blockrun.ai",
+    PORTAL_URL: "https://user.blockrun.ai",
+    PORTAL_KEYS_URL: "https://user.blockrun.ai/dashboard/keys",
+    PORTAL_CREDITS_URL: "https://user.blockrun.ai/dashboard/credits",
+    PORTAL_ACTIVITY_URL: "https://user.blockrun.ai/dashboard/activity",
+    getApiKey: () => (rail === "account" ? "brk_live_test" : undefined),
+    getAuthMode: () => (rail === "account" ? "api-key" : "wallet"),
+    isApiKeyMode: () => rail === "account",
+    getApiKeyBase: () => "https://api.blockrun.ai",
+    apiAuthHeaders: () => (rail === "account" ? { Authorization: "Bearer brk_live_test" } : {}),
+    requireWalletMode: () => null,
+    resetAuthCache: () => {},
+  },
+});
+class FakePaymentError extends Error { constructor(m: string) { super(m); this.name = "PaymentError"; } }
+mock.module("@blockrun/llm", {
+  namedExports: {
+    PaymentError: FakePaymentError,
+    SOLANA_NETWORK: "solana:mainnet",
+    SolanaLLMClient: { SOLANA_API_URL: "https://sol.blockrun.ai/api" },
+    createPaymentPayload: async () => { paymentsSigned++; return "0xpaymentpayloadmock"; },
+    createSolanaPaymentPayload: async () => { paymentsSigned++; return "solana-payment-payload"; },
+    solanaKeyToBytes: async () => new Uint8Array(64),
+    solanaPublicKey: async () => "So1anaPubkey1111111111111111111111111111111",
+    parsePaymentRequired: () => ({}),
+    extractPaymentDetails: () => ({
+      amount: quotedAmount,
+      recipient: rail === "solana" ? "Recipient111111111111111111111111111111111" : "0x0000000000000000000000000000000000000001",
+      network: rail === "solana" ? "solana:mainnet" : "eip155:8453",
+      resource: { url: "https://blockrun.ai/api/v1/audio/speech", description: "ElevenLabs Flash v2.5 speech" },
+      maxTimeoutSeconds: 300,
+      extra: rail === "solana" ? { feePayer: "FeePayer1111111111111111111111111111111111" } : {},
+    }),
+  },
+});
+
+const { registerSpeechTool, speechCost } = await import("../src/tools/speech.js");
+
+function makeHarness(limit: number | null = null) {
+  let handler: ((args: Record<string, unknown>) => Promise<any>) | undefined;
+  const server = {
+    registerTool: (_n: string, _c: unknown, h: any) => { handler = h; },
+    server: { getClientCapabilities: () => ({}) },
+  } as any;
+  const budget: BudgetState = { limit, spent: 0, calls: 0, agents: new Map() };
+  registerSpeechTool(server, budget);
+  return { call: (args: Record<string, unknown>) => handler!(args), budget };
+}
+const text = (res: any) => res.content.map((c: any) => c.text).join("\n");
+const near = (a: number, b: number) => Math.abs(a - b) < 1e-9;
+const resp402 = () => ({ status: 402, ok: false, headers: headers({ "payment-required": "x402 ..." }), json: async () => ({}) });
+const clip = (extra: Record<string, string> = {}) => () => ({
+  status: 200, ok: true, headers: headers({ "x-payment-receipt": "0xtx", ...extra }),
+  json: async () => ({ model: "elevenlabs/flash-v2.5", data: [{ url: "https://blockrun.ai/media/s.mp3", format: "mp3", characters: 1000 }] }),
+});
+const INPUT = "x".repeat(1000);
+const SPEAK = { action: "speak", input: INPUT, model: "elevenlabs/flash-v2.5", response_format: "mp3" };
+const ESTIMATE = speechCost("elevenlabs/flash-v2.5", INPUT); // $0.0545
+
+beforeEach(() => { script = []; paymentsSigned = 0; rail = "base"; quotedAmount = "54500"; });
+afterEach(() => { assert.equal(script.length, 0, "unconsumed scripted responses"); });
+
+test("Base: a settled 200 books the 402 quote exactly once and prints it", async () => {
+  quotedAmount = "55000"; // the gateway's figure wins over the local estimate
+  script = [resp402, clip()];
+  const { call, budget } = makeHarness();
+  const res = await call(SPEAK);
+  assert.notEqual(res.isError, true, text(res));
+  assert.equal(paymentsSigned, 1);
+  assert.match(text(res), /Cost: \$0\.0550/);
+  assert.match(text(res), /Tx: 0xtx/);
+  assert.ok(near(budget.spent, 0.055), `spent=${budget.spent}`);
+});
+
+test("Base: a 402 answered on the PAID request is a funding problem, not a maybe, and books nothing", async () => {
+  script = [resp402, () => ({ status: 402, ok: false, headers: headers(), json: async () => ({}) })];
+  const { call, budget } = makeHarness();
+  const res = await call(SPEAK);
+  const t = text(res);
+  assert.equal(res.isError, true);
+  assert.match(t, /out of funds/);
+  assert.doesNotMatch(t, /MAY have/);
+  assert.equal(budget.spent, 0);
+});
+
+test("Base: an API error that came back after the signature books nothing and is not a maybe", async () => {
+  script = [resp402, () => ({ status: 500, ok: false, headers: headers(), json: async () => ({ error: "upstream" }) })];
+  const { call, budget } = makeHarness();
+  const res = await call(SPEAK);
+  assert.equal(res.isError, true);
+  assert.doesNotMatch(text(res), /MAY have/);
+  assert.equal(budget.spent, 0);
+});
+
+test("Solana: a quote inside the tolerance is re-reserved against the cap before signing", async () => {
+  rail = "solana";
+  quotedAmount = "70000"; // $0.07 vs $0.0545 estimate: 1.28x, honest markup
+  script = [resp402];
+  const { call, budget } = makeHarness(0.06); // the estimate fits, the quote does not
+  const res = await call(SPEAK);
+  const t = text(res);
+  assert.equal(res.isError, true, t);
+  assert.match(t, /budget|limit/i);
+  assert.match(t, /No charge was made/);
+  assert.equal(paymentsSigned, 0, "refused before signing");
+  assert.equal(budget.spent, 0);
+});
+
+test("Solana: a sound-effect quote far above the flat rate is refused unsigned, labelled as such", async () => {
+  rail = "solana";
+  quotedAmount = "500000"; // $0.50 against $0.0545: the 9x shape
+  script = [resp402];
+  const { call, budget } = makeHarness();
+  const res = await call({ action: "sound_effect", input: "rain on a tin roof", response_format: "mp3" });
+  const t = text(res);
+  assert.equal(res.isError, true, t);
+  assert.match(t, /quoted \$0\.5000 for sound effect speech/);
+  assert.match(t, /ElevenLabs Flash v2\.5 speech/, "names what the gateway said it was quoting");
+  assert.match(t, /Refusing to sign it/);
+  assert.match(t, /chain:"base"/, "points at the other rail");
+  assert.equal(paymentsSigned, 0);
+  assert.equal(budget.spent, 0);
+});
+
+test("Solana: a settled 200 books the quote exactly once", async () => {
+  rail = "solana";
+  quotedAmount = "56000";
+  script = [resp402, clip()];
+  const { call, budget } = makeHarness();
+  const res = await call(SPEAK);
+  assert.notEqual(res.isError, true, text(res));
+  assert.equal(paymentsSigned, 1);
+  assert.ok(near(budget.spent, 0.056), `spent=${budget.spent}`);
+});
+
+test("account rail: the settled cost header is booked, and its absence books the estimate", async () => {
+  rail = "account";
+  script = [clip({ "x-blockrun-cost-usd": "0.052500" })];
+  const withHeader = makeHarness();
+  const res = await withHeader.call(SPEAK);
+  assert.notEqual(res.isError, true, text(res));
+  assert.equal(paymentsSigned, 0);
+  assert.ok(near(withHeader.budget.spent, 0.0525), `spent=${withHeader.budget.spent}`);
+  assert.match(text(res), /Cost: \$0\.0525/);
+  assert.doesNotMatch(text(res), /estimated/);
+
+  script = [clip()];
+  const noHeader = makeHarness();
+  const res2 = await noHeader.call(SPEAK);
+  assert.notEqual(res2.isError, true, text(res2));
+  assert.ok(near(noHeader.budget.spent, ESTIMATE), `spent=${noHeader.budget.spent}`);
+  assert.match(text(res2), /estimated/);
+});
+
+// Audit round 4 (the D13 shape video and music got in round 3, and speech did
+// not): settlement was OBSERVED and booked, then the result could not be used
+// — the body aborted mid-read, or carried no URL. The charge stands; the
+// message has to say so and must not invite a second payment. Before this a
+// Base body abort after the booking returned "Speech generation failed" plus
+// formatError's "temporary API issue, try again" — for a call that had paid.
+for (const [name, setup, expectUsd] of [
+  ["Base", () => { rail = "base"; quotedAmount = "55000"; script = [resp402, () => ({ status: 200, ok: true, headers: headers({ "x-payment-receipt": "0xtx" }), json: async () => { throw new Error("aborted"); } })]; }, 0.055],
+  ["Solana", () => { rail = "solana"; quotedAmount = "56000"; script = [resp402, () => ({ status: 200, ok: true, headers: headers({ "x-payment-receipt": "sol-tx" }), json: async () => ({ model: "elevenlabs/flash-v2.5", data: [{}] }) })]; }, 0.056],
+  ["account", () => { rail = "account"; script = [() => ({ status: 200, ok: true, headers: headers({ "x-blockrun-cost-usd": "0.052500" }), json: async () => ({ data: [] }) })]; }, 0.0525],
+] as const) {
+  test(`${name}: a settled 200 whose body is unusable says the charge stands, once, and does not invite a retry`, async () => {
+    setup();
+    const { call, budget } = makeHarness();
+    const res = await call(SPEAK);
+    const t = text(res);
+    assert.equal(res.isError, true, t);
+    assert.ok(near(budget.spent, expectUsd), `${name}: spent=${budget.spent}, expected ${expectUsd}`);
+    assert.match(t, /charge stands/, `${name}: ${t}`);
+    assert.match(t, /action:"report"|dashboard\/activity/, `${name}: must say where to check — ${t}`);
+    assert.doesNotMatch(t, /try again|No payment was taken|out of funds/i, `${name}: ${t}`);
+  });
+}
diff --git a/test/verify-prices-verdict.test.ts b/test/verify-prices-verdict.test.ts
new file mode 100644
index 0000000..b63164b
--- /dev/null
+++ b/test/verify-prices-verdict.test.ts
@@ -0,0 +1,86 @@
+// Run with: npm test  (tsx --test)
+//
+// `npm run verify:prices` is the release gate against silent gateway repricing.
+// Until this existed it exited 0 whenever every probe was UNREACHABLE: a
+// renamed 402 field, DNS failing, a proxy answering 200 pages — all sixty rows
+// print `?`, both catalogues print `?`, and the summary reads "0 under-
+// reserving … N unreachable" with exit 0. The release ritual and every agent
+// read that as pass, on a run that verified nothing.
+//
+// The verdict is a pure function of the tallies so it can be pinned here
+// without touching the network. Exit codes are distinct on purpose: 1 is a
+// CONFIRMED under-reserve (fix the estimator), 2 is "could not verify" (fix the
+// probe, or the network, and run again). A caller must be able to tell them
+// apart, and neither may read as success.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { UNREACHABLE_FRACTION, verdict, type Tally } from "../scripts/verify-prices-verdict.js";
+
+const clean: Tally = {
+  probes: 60, short: 0, solShort: 0, unreachable: 0,
+  catalogueGaps: 0, catalogues: 3, catalogueUnreachable: 0,
+};
+
+test("a fully reachable, fully covered run passes", () => {
+  const v = verdict(clean);
+  assert.equal(v.code, 0);
+  assert.deepEqual(v.lines, []);
+});
+
+test("every probe unreachable is a failure, not a pass with a warning", () => {
+  const v = verdict({ ...clean, unreachable: 60 });
+  assert.equal(v.code, 2);
+  assert.match(v.lines.join("\n"), /60 of 60 routes could not be verified/);
+  assert.match(v.lines.join("\n"), /NOT verified/);
+});
+
+test("unreachable above the fraction fails; at or below it only warns", () => {
+  const limit = Math.floor(60 * UNREACHABLE_FRACTION);
+  assert.equal(verdict({ ...clean, unreachable: limit }).code, 0, "at the threshold a transient miss is tolerated");
+  const over = verdict({ ...clean, unreachable: limit + 1 });
+  assert.equal(over.code, 2);
+  assert.match(over.lines.join("\n"), new RegExp(`${limit + 1} of 60 routes could not be verified`));
+});
+
+test("a few unreachable rows still print the 'treat as unknown' line without failing", () => {
+  const v = verdict({ ...clean, unreachable: 2 });
+  assert.equal(v.code, 0);
+  assert.match(v.lines.join("\n"), /2 unreachable route/);
+  assert.match(v.lines.join("\n"), /treat them as unknown, not as passing/);
+});
+
+test("a catalogue that could not be read fails the run — the sweep is the only check that sees a NEW model", () => {
+  const v = verdict({ ...clean, catalogueUnreachable: 1 });
+  assert.equal(v.code, 2);
+  assert.match(v.lines.join("\n"), /1 of 3 price catalogues could not be read/);
+});
+
+test("a confirmed under-reserve is exit 1 even when the run was also partly unreachable", () => {
+  // Both are true; the one that costs money wins the exit code, and the
+  // unverified rows are still named so nobody reads a partial run as complete.
+  const v = verdict({ ...clean, short: 1, unreachable: 59 });
+  assert.equal(v.code, 1);
+  const out = v.lines.join("\n");
+  assert.match(out, /FAIL: an estimator reserves less than the gateway charges/);
+  assert.match(out, /59 of 60 routes could not be verified/);
+});
+
+test("a Solana-side under-reserve names the chain", () => {
+  const v = verdict({ ...clean, solShort: 2 });
+  assert.equal(v.code, 1);
+  assert.match(v.lines.join("\n"), /\(on Solana\)/);
+});
+
+test("a catalogue gap is exit 1 and counts its models", () => {
+  const one = verdict({ ...clean, catalogueGaps: 1 });
+  assert.equal(one.code, 1);
+  assert.match(one.lines.join("\n"), /1 live chat model disagrees with the price table/);
+  const two = verdict({ ...clean, catalogueGaps: 2 });
+  assert.match(two.lines.join("\n"), /2 live chat models disagree with the price table/);
+});
+
+test("zero probes is not a pass — a probe list that filtered itself empty verified nothing", () => {
+  const v = verdict({ ...clean, probes: 0 });
+  assert.equal(v.code, 2);
+  assert.match(v.lines.join("\n"), /0 of 0 routes could not be verified|no routes were probed/);
+});
diff --git a/test/version-file.test.ts b/test/version-file.test.ts
new file mode 100644
index 0000000..32b30e5
--- /dev/null
+++ b/test/version-file.test.ts
@@ -0,0 +1,30 @@
+// Run with: npm test  (tsx --test)
+//
+// `VERSION` is read by nothing in this repo — publish.yml, stamp-server-json
+// and the CLI all take the version from package.json — but external release
+// tooling (/ship) computes the NEXT version from it. 0.40.1 found it eight
+// minors behind and fixed it by hand; nine minors later it was 0.41.1 against
+// a package.json at 0.50.0, because nothing pinned the two together. Off a
+// stale VERSION the tooling proposes a number that is either already on npm
+// (the publish 403s, red release job) or LOWER than npm `latest` (it publishes
+// and becomes `latest` — see the semver guard in publish.yml).
+//
+// So: the two files must agree, and both move in the release ritual.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+
+const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string };
+const versionFile = readFileSync(new URL("../VERSION", import.meta.url), "utf8");
+
+test("VERSION carries exactly the package.json version", () => {
+  assert.equal(
+    versionFile.trim(),
+    pkg.version,
+    "VERSION and package.json disagree — release tooling computes the next version from VERSION, so bump both",
+  );
+});
+
+test("VERSION is a bare semver line, nothing the tooling would have to parse around", () => {
+  assert.match(versionFile, /^\d+\.\d+\.\d+\n?$/, "VERSION must be one X.Y.Z line");
+});
diff --git a/test/version-gate.test.ts b/test/version-gate.test.ts
new file mode 100644
index 0000000..9394327
--- /dev/null
+++ b/test/version-gate.test.ts
@@ -0,0 +1,68 @@
+// Run with: npm test  (tsx --test)
+//
+// publish.yml's npm guard was inequality only: `pkg != npm`. npm publish does
+// not compare semver and tags whatever it publishes as `latest` unless told
+// otherwise, so a release PR that typed 0.5.1 for 0.51.0 would have published
+// and every fresh `npx -y @blockrun/mcp@latest` would have installed a build
+// with 0.5-era estimators. VERSION drifting behind package.json (see
+// version-file.test.ts) is exactly how such a number gets proposed.
+//
+// The gate is a plain-Node script (it runs BEFORE `npm ci`, so no semver
+// package) and this pins the comparison it makes.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+// @ts-expect-error — plain .mjs helper, no types
+import { compareSemver, gate } from "../scripts/version-gate.mjs";
+
+test("compareSemver orders numerically, not lexically", () => {
+  assert.equal(compareSemver("0.51.0", "0.5.1"), 1, "0.51.0 is newer than 0.5.1 — a string compare says otherwise");
+  assert.equal(compareSemver("0.50.0", "0.50.0"), 0);
+  assert.equal(compareSemver("0.9.9", "0.10.0"), -1);
+  assert.equal(compareSemver("1.0.0", "0.99.99"), 1);
+});
+
+test("a package version below npm latest is refused with the downgrade named", () => {
+  const r = gate({ pkg: "0.5.1", npm: "0.50.0" });
+  assert.equal(r.ok, false);
+  assert.match(r.reason, /0\.5\.1 is LOWER than npm latest 0\.50\.0/);
+  assert.match(r.reason, /would become `latest`/);
+});
+
+test("equal is allowed — that is the 'already published, skip npm' re-run", () => {
+  assert.equal(gate({ pkg: "0.50.0", npm: "0.50.0" }).ok, true);
+});
+
+test("higher is allowed, and 'none' (nothing on npm yet) is allowed", () => {
+  assert.equal(gate({ pkg: "0.51.0", npm: "0.50.0" }).ok, true);
+  assert.equal(gate({ pkg: "0.1.0", npm: "none" }).ok, true);
+});
+
+test("a version that is not X.Y.Z is refused rather than compared as zero", () => {
+  const r = gate({ pkg: "0.51", npm: "0.50.0" });
+  assert.equal(r.ok, false);
+  assert.match(r.reason, /not a bare X\.Y\.Z version/);
+  const t = gate({ pkg: "0.51.0-rc.1", npm: "0.50.0" });
+  assert.equal(t.ok, false, "prereleases are refused: publish.yml has no dist-tag path for them");
+});
+
+test("the CLI exits non-zero on a downgrade and zero on a release", () => {
+  const script = new URL("../scripts/version-gate.mjs", import.meta.url).pathname;
+  assert.throws(
+    () => execFileSync("node", [script, "0.5.1", "0.50.0"], { stdio: "pipe" }),
+    (err: unknown) => (err as { status?: number }).status === 1,
+  );
+  const out = execFileSync("node", [script, "0.51.0", "0.50.0"], { encoding: "utf8" });
+  assert.match(out, /0\.51\.0 > npm latest 0\.50\.0/);
+});
+
+// Audit round 4: "none" must mean "npm answered E404", never "npm did not
+// answer". The workflow used to spell every `npm view` failure as "none", so a
+// transient registry error on a run whose package.json was BELOW latest — the
+// exact case the gate exists for — passed the gate and the npm step alike.
+test("'unknown' (npm could not be read) is refused — a gate that cannot look does not pass", () => {
+  const r = gate({ pkg: "0.51.0", npm: "unknown" });
+  assert.equal(r.ok, false);
+  assert.match(r.reason, /could not be read|unknown/i);
+  assert.match(r.reason, /re-run/i);
+});
diff --git a/test/video-models.test.ts b/test/video-models.test.ts
index 32d3a84..d6c5d9a 100644
--- a/test/video-models.test.ts
+++ b/test/video-models.test.ts
@@ -52,6 +52,7 @@ const {
   SEEDANCE_RESOLUTIONS,
   VIDEO_TOTAL_BUDGET_MS,
   VIDEO_POLL_TIMEOUT_MS,
+  POLL_INTERVAL_MS,
   VIDEO_PAYMENT_AUTH_SECONDS,
 } = await import("../src/tools/video.js");
 
@@ -352,9 +353,14 @@ test("video polling allows slow 30s jobs while staying inside payment authorizat
   );
 
   // The clamp is load-bearing, not cosmetic: unclamped, the real worst case is
-  // budget + interval + poll timeout, which overruns the authorization.
+  // budget + interval + poll timeout, which overruns the authorization. Stated
+  // with the interval included, because that is the actual worst case — a poll
+  // is ENTERED after the sleep, so the sleep is part of the overrun. (Written
+  // as > authMs against a 90s poll timeout, where the timeout alone cleared it;
+  // at the gateway route's own 60s cap it is the interval that carries the
+  // margin, which is exactly why the clamp cannot be dropped.)
   assert.ok(
-    VIDEO_TOTAL_BUDGET_MS + VIDEO_POLL_TIMEOUT_MS > authMs,
+    VIDEO_TOTAL_BUDGET_MS + POLL_INTERVAL_MS + VIDEO_POLL_TIMEOUT_MS > authMs,
     "unclamped worst case would overrun the authorization — do not remove pollTimeoutFor",
   );
 });
diff --git a/test/video-money-path.test.ts b/test/video-money-path.test.ts
index 3743317..857b9ae 100644
--- a/test/video-money-path.test.ts
+++ b/test/video-money-path.test.ts
@@ -243,7 +243,7 @@ test("a paid poll still in flight at the deadline MAY have settled: say so, book
   const res = await call({ prompt: "a cube", model: "xai/grok-imagine-video" });
   const text = res.content.map((c: any) => c.text).join("\n");
   assert.equal(res.isError, true, text);
-  assert.match(text, /MAY have settled/);
+  assert.match(text, /MAY have gone through/);
   assert.match(text, /blockrun_wallet action:"report"/);
   assert.match(text, /claimable.*job vid_1/);
   assert.doesNotMatch(text, /please try again/);
diff --git a/test/wallet-env-key.test.ts b/test/wallet-env-key.test.ts
new file mode 100644
index 0000000..ad6d4b0
--- /dev/null
+++ b/test/wallet-env-key.test.ts
@@ -0,0 +1,228 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// An env-provided key is a SIGNER OVERRIDE, not a wallet the machine owns.
+//
+// The README, the debug skill and the SDK's own migration notice all present
+// BLOCKRUN_WALLET_KEY as reversible: "for a single run without changing
+// anything", "unset the override". ensureEvmWallet() nevertheless fed whatever
+// getOrCreateWallet() returned into persistKey(), which stores with `-U` —
+// overwriting the keychain entry that held the funded wallet — and, under
+// BLOCKRUN_KEYCHAIN=strict, deleted ~/.blockrun/.session on the strength of a
+// read-back that only proved the keychain held the ENV key. One run with a
+// different key in the environment and the funded wallet (also the Polymarket
+// deposit signer) was in no store at all, behind a "moved the wallet key into
+// the OS keychain" success message. The Solana rail already returned before
+// persisting SOLANA_WALLET_KEY; Base did not. Rail parity, in the direction
+// that destroys money.
+//
+// Second gap, same root: the SDK loader honours BLOCKRUN_WALLET_KEY OR
+// BASE_CHAIN_WALLET_KEY and falls back to the legacy ~/.blockrun/wallet.key,
+// but the two questions the MCP asks in front of it (the keychain gate and the
+// Solana-first migration guard) knew only BLOCKRUN_WALLET_KEY and .session. A
+// user configured the SDK-documented way had a stale keychain entry win over
+// the key they had just rotated to, and was read as "no Base wallet" by
+// getChain().
+import { test, mock, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { privateKeyToAccount } from "viem/accounts";
+
+const ENV_KEY = "0x" + "aa".repeat(32);
+const STALE_KEYCHAIN_KEY = "0x" + "bb".repeat(32);
+const LEGACY_KEY = "0x" + "cc".repeat(32);
+
+const home = fs.mkdtempSync(path.join(os.tmpdir(), "br-env-key-"));
+const blockrunDir = path.join(home, ".blockrun");
+fs.mkdirSync(blockrunDir, { recursive: true });
+const ENV_NAMES = ["HOME", "BLOCKRUN_HOME", "BLOCKRUN_KEYCHAIN", "BLOCKRUN_WALLET_KEY", "BASE_CHAIN_WALLET_KEY", "SOLANA_WALLET_KEY", "BLOCKRUN_API_KEY"] as const;
+const saved = Object.fromEntries(ENV_NAMES.map((k) => [k, process.env[k]]));
+process.env.HOME = home;
+for (const k of ENV_NAMES) if (k !== "HOME") delete process.env[k];
+
+// A keychain that already holds a DIFFERENT funded key on both rails. Any test
+// that resolves to it proves the env override was ignored; any persistKey call
+// proves the override was about to be written over it.
+let mode = "auto";
+const store = new Map<string, string>([["evm-wallet-key", STALE_KEYCHAIN_KEY]]);
+const persisted: Array<{ account: string; key: string; file?: string }> = [];
+mock.module("../src/utils/keychain.js", {
+  namedExports: {
+    EVM_KEY_ACCOUNT: "evm-wallet-key",
+    SOLANA_KEY_ACCOUNT: "solana-wallet-key",
+    getKeychainMode: () => mode,
+    keychainLoad: (a: string) => store.get(a) ?? null,
+    keychainRead: (a: string) => (store.has(a) ? { status: "found", value: store.get(a) } : { status: "absent" }),
+    persistKey: (account: string, key: string, file?: string) => {
+      persisted.push({ account, key, file });
+    },
+  },
+});
+
+const wallet = await import("../src/utils/wallet.js");
+const { createSolanaWallet, solanaPublicKey } = await import("@blockrun/llm");
+
+process.on("exit", () => {
+  for (const [k, v] of Object.entries(saved)) {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+  fs.rmSync(home, { recursive: true, force: true });
+});
+
+beforeEach(() => {
+  for (const f of [".session", ".solana-session", "wallet.key", ".chain", ".chain-auto"]) {
+    fs.rmSync(path.join(blockrunDir, f), { force: true });
+  }
+  for (const k of ["BLOCKRUN_WALLET_KEY", "BASE_CHAIN_WALLET_KEY", "SOLANA_WALLET_KEY"]) delete process.env[k];
+  mode = "auto";
+  persisted.length = 0;
+  store.clear();
+  store.set("evm-wallet-key", STALE_KEYCHAIN_KEY);
+  wallet.resetEvmWalletCache();
+  wallet.resetSolanaKeyCache();
+  wallet.resetKeychainProbeCache();
+});
+
+// --- C1: an env key is never persisted ------------------------------------
+
+test("BLOCKRUN_WALLET_KEY is used for signing but never written to the keychain", () => {
+  process.env.BLOCKRUN_WALLET_KEY = ENV_KEY;
+
+  assert.equal(wallet.getOrCreateWalletKey(), ENV_KEY, "the env override must be the signer");
+  assert.deepEqual(persisted, [], "an env override must not overwrite the keychain's funded key with -U");
+  assert.equal(store.get("evm-wallet-key"), STALE_KEYCHAIN_KEY, "the funded key survives the run");
+});
+
+test("strict mode with an env override never retires the .session that holds the funded key", () => {
+  // The first strict run: keychain W1, file W1, env W2. persistKey would have
+  // stored W2 over W1 and — read-back W2 === W2 — deleted the file holding W1.
+  mode = "strict";
+  const session = path.join(blockrunDir, ".session");
+  fs.writeFileSync(session, STALE_KEYCHAIN_KEY, { mode: 0o600 });
+  process.env.BLOCKRUN_WALLET_KEY = ENV_KEY;
+
+  assert.equal(wallet.getOrCreateWalletKey(), ENV_KEY);
+  assert.deepEqual(persisted, [], "nothing may be persisted from an env override, in any mode");
+  assert.equal(fs.readFileSync(session, "utf-8"), STALE_KEYCHAIN_KEY, "the file holding the funded key must survive");
+});
+
+test("unsetting the override brings the previous wallet back — the override was reversible", () => {
+  process.env.BLOCKRUN_WALLET_KEY = ENV_KEY;
+  assert.equal(wallet.getOrCreateWalletKey(), ENV_KEY);
+
+  delete process.env.BLOCKRUN_WALLET_KEY;
+  wallet.resetEvmWalletCache();
+  assert.equal(wallet.getOrCreateWalletKey(), STALE_KEYCHAIN_KEY, "the keychain still holds the wallet the user had before the override");
+});
+
+// --- C34: the gate asks the loader's question -----------------------------
+
+test("BASE_CHAIN_WALLET_KEY (the SDK's alias) outranks a stale keychain entry and is not persisted", () => {
+  process.env.BASE_CHAIN_WALLET_KEY = ENV_KEY;
+
+  const resolved = wallet.getOrCreateWalletKey();
+  assert.equal(resolved, ENV_KEY, "the SDK resolves this variable; the MCP's gate must not read the keychain ahead of it");
+  assert.notEqual(
+    privateKeyToAccount(resolved).address,
+    privateKeyToAccount(STALE_KEYCHAIN_KEY as `0x${string}`).address,
+    "signing with the keychain's key here is the stale-entry shadowing the precedence comment says it prevents",
+  );
+  assert.deepEqual(persisted, []);
+});
+
+test("a rotated BASE_CHAIN_WALLET_KEY takes effect on the next run instead of the keychain's mirror", () => {
+  // The self-perpetuating form: the first run mirrored W1; the user rotates to
+  // W2; the gate must not hand W1 back from the keychain.
+  process.env.BASE_CHAIN_WALLET_KEY = STALE_KEYCHAIN_KEY;
+  assert.equal(wallet.getOrCreateWalletKey(), STALE_KEYCHAIN_KEY);
+
+  process.env.BASE_CHAIN_WALLET_KEY = ENV_KEY;
+  wallet.resetEvmWalletCache();
+  assert.equal(wallet.getOrCreateWalletKey(), ENV_KEY, "rotation must not be silently undone");
+});
+
+test("an env key without the 0x prefix is normalised the way the SDK normalises it", () => {
+  process.env.BLOCKRUN_WALLET_KEY = ENV_KEY.slice(2);
+  assert.equal(wallet.getOrCreateWalletKey(), ENV_KEY);
+});
+
+test("the legacy ~/.blockrun/wallet.key ranks BELOW the keychain, and above a mint", () => {
+  // Round 3 pinned the opposite ("exactly as the SDK loader ranks it") and
+  // that was the P1 round 4 found: strict mode retires .session and never
+  // wallet.key, so a stale legacy file outranked the funded keychain entry
+  // the moment .session was gone, and persistKey stored it over the funded
+  // key with -U. The keychain entry only ever exists because this server
+  // mirrored a key there, so it can never be staler than a file that
+  // predates the mirror. .session stays the rotation seam (see
+  // keychain-precedence.test.ts); wallet.key is a fallback for a machine
+  // whose keychain holds nothing.
+  fs.writeFileSync(path.join(blockrunDir, "wallet.key"), LEGACY_KEY + "\n", { mode: 0o600 });
+  assert.equal(wallet.getOrCreateWalletKey(), STALE_KEYCHAIN_KEY, "the keychain's funded key wins over a legacy file");
+  assert.deepEqual(persisted, [], "and nothing is written over it");
+
+  wallet.resetEvmWalletCache();
+  store.delete("evm-wallet-key");
+  assert.equal(wallet.getOrCreateWalletKey(), LEGACY_KEY, "with no keychain entry the legacy file is the wallet, not a reason to mint");
+  store.set("evm-wallet-key", STALE_KEYCHAIN_KEY);
+});
+
+test("getChain() recognises a Base wallet configured through BASE_CHAIN_WALLET_KEY or wallet.key", () => {
+  // Keychain off: the probe must not rescue the guard here, because on Windows,
+  // keychain-less Linux and the very first run there is no mirror to find.
+  mode = "off";
+
+  process.env.BASE_CHAIN_WALLET_KEY = ENV_KEY;
+  assert.equal(wallet.getChain(), "base", "a configured Base key is not a fresh install");
+  delete process.env.BASE_CHAIN_WALLET_KEY;
+
+  fs.writeFileSync(path.join(blockrunDir, "wallet.key"), LEGACY_KEY, { mode: 0o600 });
+  assert.equal(wallet.getChain(), "base", "a legacy key file is a funded Base wallet the default must not strand");
+});
+
+// --- rail parity: every env override is treated the same way --------------
+
+test("rail parity: no env override is ever persisted, on either wallet rail", async () => {
+  const solana = await createSolanaWallet();
+  const rows: Array<{ rail: string; env: string; key: string; resolve: () => Promise<string> }> = [
+    { rail: "base", env: "BLOCKRUN_WALLET_KEY", key: ENV_KEY, resolve: async () => wallet.getOrCreateWalletKey() },
+    { rail: "base", env: "BASE_CHAIN_WALLET_KEY", key: ENV_KEY, resolve: async () => wallet.getOrCreateWalletKey() },
+    { rail: "solana", env: "SOLANA_WALLET_KEY", key: solana.privateKey, resolve: async () => (await wallet.ensureSolanaWallet()).privateKey },
+  ];
+
+  for (const row of rows) {
+    for (const rowMode of ["auto", "strict"]) {
+      mode = rowMode;
+      persisted.length = 0;
+      wallet.resetEvmWalletCache();
+      wallet.resetSolanaKeyCache();
+      process.env[row.env] = row.key;
+
+      assert.equal(await row.resolve(), row.key, `${row.rail}/${row.env}/${rowMode}: the override must be the signer`);
+      assert.deepEqual(persisted, [], `${row.rail}/${row.env}/${rowMode}: an override must never reach the keychain`);
+
+      delete process.env[row.env];
+    }
+  }
+
+  // And the Solana address the override maps to is the one reported.
+  process.env.SOLANA_WALLET_KEY = solana.privateKey;
+  wallet.resetSolanaKeyCache();
+  assert.equal((await wallet.ensureSolanaWallet()).address, await solanaPublicKey(solana.privateKey));
+});
+
+test("rail parity: a key that came from a FILE is still mirrored on both rails (the fix did not disable auto mode)", async () => {
+  const solana = await createSolanaWallet();
+  fs.writeFileSync(path.join(blockrunDir, ".session"), ENV_KEY, { mode: 0o600 });
+  fs.writeFileSync(path.join(blockrunDir, ".solana-session"), solana.privateKey, { mode: 0o600 });
+
+  wallet.getOrCreateWalletKey();
+  await wallet.ensureSolanaWallet();
+
+  assert.deepEqual(
+    persisted.map((p) => p.account).sort(),
+    ["evm-wallet-key", "solana-wallet-key"],
+    "file-sourced keys are the ones auto mode exists to mirror",
+  );
+});
diff --git a/test/wallet-first-run-race.test.ts b/test/wallet-first-run-race.test.ts
new file mode 100644
index 0000000..2303d0d
--- /dev/null
+++ b/test/wallet-first-run-race.test.ts
@@ -0,0 +1,181 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// The cross-PROCESS first-run race. 0.50.0's single-flight covers overlapping
+// callers inside one server; it cannot see a second server. Claude Code,
+// Cursor and Claude Desktop are commonly all configured with `-s user`, and on
+// a machine that has never held a key two of them can both find every store
+// empty, both mint, and both write: saveSolanaWallet()/saveWallet() were plain
+// writeFileSync (no exclusive flag, no re-read) and persistKey stores with -U.
+// Last writer wins on disk and in the keychain, but each process keeps its own
+// cached wallet for its lifetime and prints its OWN address with a funding QR.
+// USDC sent to the loser's address is unrecoverable once that process exits —
+// no store ever held the key.
+//
+// The fix is at the write: publish the freshly minted key with an exclusive
+// create, and when that loses, adopt the key the OTHER process published
+// instead of the one just generated. Both processes then advertise the same
+// wallet, which is the one every store holds.
+//
+// Two "processes" are simulated by interleaving: the SDK's key generator is
+// wrapped so that, inside process A's mint window (after A's empty-store check,
+// before A's write), process B's key lands in the session file. That is the
+// exact ordering that lost money.
+import { test, mock, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { privateKeyToAccount } from "viem/accounts";
+
+const home = fs.mkdtempSync(path.join(os.tmpdir(), "br-first-run-race-"));
+const blockrunDir = path.join(home, ".blockrun");
+fs.mkdirSync(blockrunDir, { recursive: true });
+const ENV_NAMES = ["HOME", "BLOCKRUN_HOME", "BLOCKRUN_KEYCHAIN", "BLOCKRUN_WALLET_KEY", "BASE_CHAIN_WALLET_KEY", "SOLANA_WALLET_KEY", "BLOCKRUN_API_KEY"] as const;
+const saved = Object.fromEntries(ENV_NAMES.map((k) => [k, process.env[k]]));
+process.env.HOME = home;
+for (const k of ENV_NAMES) if (k !== "HOME") delete process.env[k];
+
+const realLlm = await import("@blockrun/llm");
+const SESSION = path.join(blockrunDir, ".session");
+const SOLANA_SESSION = path.join(blockrunDir, ".solana-session");
+
+// What "process B" does inside A's mint window. Reset per test.
+let duringSolanaMint: (() => Promise<void>) | null = null;
+let duringEvmMint: (() => void) | null = null;
+
+// The namespace object carries a `default` binding that mock.module cannot
+// re-export under that name; everything else passes through untouched.
+const { default: _unusedDefault, ...realNamed } = realLlm as Record<string, unknown> & { default?: unknown };
+void _unusedDefault;
+mock.module("@blockrun/llm", {
+  namedExports: {
+    ...realNamed,
+    createSolanaWallet: async () => {
+      const created = await realLlm.createSolanaWallet();
+      if (duringSolanaMint) await duringSolanaMint();
+      return created;
+    },
+    createWallet: () => {
+      const created = realLlm.createWallet();
+      if (duringEvmMint) duringEvmMint();
+      return created;
+    },
+  },
+});
+
+// The keychain both processes share. `-U` semantics: last store wins.
+const store = new Map<string, string>();
+mock.module("../src/utils/keychain.js", {
+  namedExports: {
+    EVM_KEY_ACCOUNT: "evm-wallet-key",
+    SOLANA_KEY_ACCOUNT: "solana-wallet-key",
+    getKeychainMode: () => "auto",
+    keychainLoad: (a: string) => store.get(a) ?? null,
+    keychainRead: (a: string) => (store.has(a) ? { status: "found", value: store.get(a) } : { status: "absent" }),
+    persistKey: (account: string, key: string) => {
+      store.set(account, key);
+    },
+  },
+});
+
+const wallet = await import("../src/utils/wallet.js");
+
+process.on("exit", () => {
+  for (const [k, v] of Object.entries(saved)) {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+  fs.rmSync(home, { recursive: true, force: true });
+});
+
+beforeEach(() => {
+  for (const f of fs.readdirSync(blockrunDir)) fs.rmSync(path.join(blockrunDir, f), { force: true, recursive: true });
+  store.clear();
+  duringSolanaMint = null;
+  duringEvmMint = null;
+  wallet.resetEvmWalletCache();
+  wallet.resetSolanaKeyCache();
+  wallet.resetKeychainProbeCache();
+});
+
+test("Solana: when another process publishes first, this process adopts THAT key instead of its own", async () => {
+  const processB = await realLlm.createSolanaWallet();
+  let generatedByA: string | undefined;
+  duringSolanaMint = async () => {
+    // Process B wins the race: its key is on disk before A writes.
+    fs.writeFileSync(SOLANA_SESSION, processB.privateKey, { mode: 0o600 });
+    store.set("solana-wallet-key", processB.privateKey);
+  };
+
+  const info = await wallet.ensureSolanaWallet();
+  generatedByA = info.privateKey;
+
+  assert.equal(info.privateKey, processB.privateKey, "A must hand back the key every store holds, not one only its heap holds");
+  assert.equal(info.address, processB.address, "the address shown with the funding QR must be the winner's");
+  assert.equal(fs.readFileSync(SOLANA_SESSION, "utf-8").trim(), processB.privateKey, "B's file was not overwritten");
+  assert.equal(store.get("solana-wallet-key"), processB.privateKey, "and the keychain still holds B's key");
+  assert.equal(wallet.resolveSolanaKey(), processB.privateKey);
+  assert.equal((await wallet.ensureSolanaWallet()).address, processB.address, "the cache agrees with the stores");
+  assert.equal(generatedByA, processB.privateKey);
+});
+
+test("Base: when another process publishes first, this process adopts THAT key instead of its own", () => {
+  const processB = realLlm.createWallet();
+  duringEvmMint = () => {
+    fs.writeFileSync(SESSION, processB.privateKey, { mode: 0o600 });
+    store.set("evm-wallet-key", processB.privateKey);
+  };
+
+  const key = wallet.getOrCreateWalletKey();
+
+  assert.equal(key, processB.privateKey, "A must sign with the key every store holds");
+  assert.equal(fs.readFileSync(SESSION, "utf-8").trim(), processB.privateKey, "B's file was not overwritten");
+  assert.equal(store.get("evm-wallet-key"), processB.privateKey);
+  assert.equal(privateKeyToAccount(key).address, processB.address);
+});
+
+test("the address a process reports after losing the race is fundable — its key is in the file", async () => {
+  const processB = await realLlm.createSolanaWallet();
+  duringSolanaMint = async () => {
+    fs.writeFileSync(SOLANA_SESSION, processB.privateKey, { mode: 0o600 });
+  };
+
+  const info = await wallet.getWalletInfo();
+  assert.equal(info.network, "Solana");
+  assert.equal(info.address, processB.address);
+  // Simulate the loser restarting: a fresh process resolves the same address.
+  wallet.resetSolanaKeyCache();
+  assert.equal((await wallet.ensureSolanaWallet()).address, info.address, "after restart the same wallet is found — no funds stranded");
+});
+
+test("no race: a fresh mint still writes the file and reports isNew on both chains", async () => {
+  const sol = await wallet.ensureSolanaWallet();
+  assert.equal(sol.isNew, true);
+  assert.equal(fs.readFileSync(SOLANA_SESSION, "utf-8").trim(), sol.privateKey);
+
+  const evm = wallet.getOrCreateWalletKey();
+  assert.equal(fs.readFileSync(SESSION, "utf-8").trim(), evm);
+  assert.deepEqual(fs.readdirSync(blockrunDir).sort(), [".session", ".solana-session"], "no temp files left behind");
+});
+
+test("a pre-existing EMPTY session file is replaced by the mint, not adopted as a key", async () => {
+  // The round-3 scenario: an interrupted write left a zero-byte file. The
+  // exclusive create loses to it, but there is nothing to adopt.
+  fs.writeFileSync(SOLANA_SESSION, "", { mode: 0o600 });
+  fs.writeFileSync(SESSION, "  \n", { mode: 0o600 });
+
+  const sol = await wallet.ensureSolanaWallet();
+  assert.equal(sol.isNew, true);
+  assert.equal(fs.readFileSync(SOLANA_SESSION, "utf-8").trim(), sol.privateKey);
+
+  const evm = wallet.getOrCreateWalletKey();
+  assert.equal(fs.readFileSync(SESSION, "utf-8").trim(), evm);
+});
+
+test("the session files are created mode 0600", async () => {
+  await wallet.ensureSolanaWallet();
+  wallet.getOrCreateWalletKey();
+  for (const f of [SESSION, SOLANA_SESSION]) {
+    assert.equal(fs.statSync(f).mode & 0o777, 0o600, f);
+  }
+});
diff --git a/test/wallet-solana-rpc-headers.test.ts b/test/wallet-solana-rpc-headers.test.ts
new file mode 100644
index 0000000..26cdadf
--- /dev/null
+++ b/test/wallet-solana-rpc-headers.test.ts
@@ -0,0 +1,119 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// 0.50.0 "around the edges": `SOLANA_RPC_HEADERS` is honoured again by the
+// Solana USDC balance read. The SDK reads it alongside SOLANA_RPC_URL, and
+// taking the balance query off the SDK (so the status screen shows the
+// balance of the address it displays, not of the client's own key) dropped
+// it — a private RPC that authenticates by header answered 401 and every
+// balance read "unavailable". Fixed, and never pinned: a refactor that drops
+// the merge again ships with the suite green.
+//
+// getSolanaUsdcBalance() uses global fetch directly (not utils/http.ts), so
+// the request it sends is captured by replacing fetch. No RPC is reached.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { getChainBalance } from "../src/utils/wallet.js";
+
+const ADDRESS = "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU";
+const USDC_SOLANA_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+
+type Captured = { url: string; headers: Record<string, string>; body: Record<string, unknown> };
+
+async function balanceWith(env: { SOLANA_RPC_HEADERS?: string; SOLANA_RPC_URL?: string; SOLANA_RPC_API_KEY?: string }, reply: unknown): Promise<{ captured: Captured; balance: number | null }> {
+  const saved = { headers: process.env.SOLANA_RPC_HEADERS, url: process.env.SOLANA_RPC_URL, apiKey: process.env.SOLANA_RPC_API_KEY };
+  if (env.SOLANA_RPC_HEADERS === undefined) delete process.env.SOLANA_RPC_HEADERS; else process.env.SOLANA_RPC_HEADERS = env.SOLANA_RPC_HEADERS;
+  if (env.SOLANA_RPC_URL === undefined) delete process.env.SOLANA_RPC_URL; else process.env.SOLANA_RPC_URL = env.SOLANA_RPC_URL;
+  if (env.SOLANA_RPC_API_KEY === undefined) delete process.env.SOLANA_RPC_API_KEY; else process.env.SOLANA_RPC_API_KEY = env.SOLANA_RPC_API_KEY;
+  const realFetch = globalThis.fetch;
+  let captured: Captured | undefined;
+  globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const headers = new Headers(init?.headers);
+    captured = {
+      url: String(input),
+      headers: Object.fromEntries([...headers.entries()]),
+      body: JSON.parse(String(init?.body)) as Record<string, unknown>,
+    };
+    return new Response(JSON.stringify(reply), { status: 200, headers: { "content-type": "application/json" } });
+  }) as typeof fetch;
+  try {
+    const balance = await getChainBalance("solana", ADDRESS);
+    assert.ok(captured, "the balance read must issue exactly one RPC request");
+    return { captured: captured!, balance };
+  } finally {
+    globalThis.fetch = realFetch;
+    if (saved.headers === undefined) delete process.env.SOLANA_RPC_HEADERS; else process.env.SOLANA_RPC_HEADERS = saved.headers;
+    if (saved.url === undefined) delete process.env.SOLANA_RPC_URL; else process.env.SOLANA_RPC_URL = saved.url;
+    if (saved.apiKey === undefined) delete process.env.SOLANA_RPC_API_KEY; else process.env.SOLANA_RPC_API_KEY = saved.apiKey;
+  }
+}
+
+const tokenAccounts = (uiAmounts: number[]) => ({
+  jsonrpc: "2.0",
+  id: 1,
+  result: { value: uiAmounts.map((uiAmount) => ({ account: { data: { parsed: { info: { tokenAmount: { uiAmount } } } } } })) },
+});
+
+test("SOLANA_RPC_HEADERS is sent on the balance request, alongside the JSON content type", async () => {
+  const { captured, balance } = await balanceWith(
+    { SOLANA_RPC_HEADERS: '{"x-api-key":"k-123","Authorization":"Bearer t"}', SOLANA_RPC_URL: "https://private.rpc.example/solana" },
+    tokenAccounts([4.5, 0.5]),
+  );
+  assert.equal(captured.url, "https://private.rpc.example/solana", "SOLANA_RPC_URL selects the endpoint");
+  assert.equal(captured.headers["x-api-key"], "k-123", "the authenticating header must reach the private RPC — without it the RPC answers 401 and the balance reads 'unavailable'");
+  assert.equal(captured.headers["authorization"], "Bearer t");
+  assert.equal(captured.headers["content-type"], "application/json", "merging the extra headers must not drop the content type");
+  assert.equal(captured.body.method, "getTokenAccountsByOwner");
+  assert.deepEqual((captured.body.params as unknown[])[0], ADDRESS, "the balance is keyed on the address DISPLAYED, not the client's own key");
+  assert.deepEqual((captured.body.params as unknown[])[1], { mint: USDC_SOLANA_MINT });
+  assert.equal(balance, 5, "token accounts are summed");
+});
+
+test("without SOLANA_RPC_HEADERS the request carries only the content type, on the default gateway RPC", async () => {
+  const { captured, balance } = await balanceWith({}, tokenAccounts([1.25]));
+  assert.deepEqual(Object.keys(captured.headers), ["content-type"]);
+  assert.equal(captured.url, "https://sol.blockrun.ai/api/v1/solana/rpc");
+  assert.equal(balance, 1.25);
+});
+
+test("a malformed SOLANA_RPC_HEADERS falls through unauthenticated, as the SDK does, rather than failing the read", async () => {
+  const { captured, balance } = await balanceWith({ SOLANA_RPC_HEADERS: "{not json" }, tokenAccounts([2]));
+  assert.deepEqual(Object.keys(captured.headers), ["content-type"]);
+  assert.equal(balance, 2);
+});
+
+test("a non-object SOLANA_RPC_HEADERS (an array, a string) is ignored, not spread into the request", async () => {
+  const arr = await balanceWith({ SOLANA_RPC_HEADERS: '["x-api-key","k"]' }, tokenAccounts([1]));
+  assert.deepEqual(Object.keys(arr.captured.headers), ["content-type"]);
+  const str = await balanceWith({ SOLANA_RPC_HEADERS: '"x-api-key: k"' }, tokenAccounts([1]));
+  assert.deepEqual(Object.keys(str.captured.headers), ["content-type"]);
+});
+
+test("an RPC error answers null (unavailable), never 0 beside a funded address", async () => {
+  const { balance } = await balanceWith(
+    { SOLANA_RPC_HEADERS: '{"x-api-key":"k"}' },
+    { jsonrpc: "2.0", id: 1, error: { code: -32600, message: "unauthorized" } },
+  );
+  assert.equal(balance, null);
+});
+
+// Audit round 4: the SDK's resolveRpcConfig honours SOLANA_RPC_API_KEY as an
+// `x-api-key` header when SOLANA_RPC_HEADERS is unset — the documented way to
+// point at a keyed private RPC — and the balance read knew only the JSON
+// form, so that configuration still answered 401 and "unavailable".
+test("SOLANA_RPC_API_KEY is sent as x-api-key, the way the SDK sends it", async () => {
+  const { captured, balance } = await balanceWith(
+    { SOLANA_RPC_API_KEY: "k-456", SOLANA_RPC_URL: "https://private.rpc.example/solana" },
+    tokenAccounts([2]),
+  );
+  assert.equal(captured.headers["x-api-key"], "k-456");
+  assert.equal(balance, 2);
+});
+
+test("SOLANA_RPC_HEADERS outranks SOLANA_RPC_API_KEY, the SDK's precedence", async () => {
+  const { captured } = await balanceWith(
+    { SOLANA_RPC_HEADERS: '{"Authorization":"Bearer t"}', SOLANA_RPC_API_KEY: "k-456" },
+    tokenAccounts([2]),
+  );
+  assert.equal(captured.headers["authorization"], "Bearer t");
+  assert.equal(captured.headers["x-api-key"], undefined, "the JSON form replaces, it does not merge");
+});
diff --git a/test/wallet-status-session-spend.test.ts b/test/wallet-status-session-spend.test.ts
new file mode 100644
index 0000000..d8450b2
--- /dev/null
+++ b/test/wallet-status-session-spend.test.ts
@@ -0,0 +1,85 @@
+// Run with: npm test  (tsx --experimental-test-module-mocks --test)
+//
+// The blockrun_wallet description promises that action:"status" (the default)
+// shows "session spending", and tells the model to call it before expensive
+// operations. The api-key branch did; the wallet branch printed addresses,
+// balances and the active chain and nothing about what this process has
+// spent, so an agent that checked status before a $0.40 render saw $12 of USDC
+// and no hint that its $1 allotment was nearly gone. Both wallet chains carry
+// the same session line and structuredContent fields the api-key branch does.
+import { test, mock } from "node:test";
+import assert from "node:assert/strict";
+import type { BudgetState } from "../src/types.js";
+
+let activeChain: "base" | "solana" = "solana";
+
+mock.module("../src/utils/onramp.js", {
+  namedExports: { launchTopUp: async () => ({ opened: false, url: "", note: "" }) },
+});
+mock.module("../src/utils/auth.js", {
+  namedExports: {
+    isApiKeyMode: () => false,
+    requireWalletMode: (c: string) => `${c} needs wallet mode`,
+    PORTAL_CREDITS_URL: "https://user.blockrun.ai/dashboard/credits",
+    PORTAL_ACTIVITY_URL: "https://user.blockrun.ai/dashboard/activity",
+  },
+});
+mock.module("../src/utils/account.js", {
+  namedExports: {
+    describeBlock: () => null,
+    formatCredit: () => "credit",
+    getAccountCredit: async () => { throw new Error("wallet mode: not called"); },
+  },
+});
+mock.module("../src/utils/wallet.js", {
+  namedExports: {
+    getApiBase: () => "https://blockrun.ai/api",
+    resolveGatewayUrl: (u: string) => u,
+    getWalletInfo: async () => ({ address: "0xTESTADDRESS", explorerUrl: "https://explorer/x", network: "base", chainId: 8453, isNew: false }),
+    getChain: () => activeChain,
+    getUsdcBalance: async () => 12,
+    setChain: () => {},
+    ensureBothWallets: async () => ({ base: { address: "0xTESTADDRESS" }, solana: { address: "SOLADDR" } }),
+    getChainBalance: async () => 12,
+  },
+});
+const { registerWalletTool } = await import("../src/tools/wallet.js");
+
+function makeHarness(limit: number | null) {
+  let handler: ((a: Record<string, unknown>) => Promise<any>) | undefined;
+  const server = { registerTool: (_n: string, _c: unknown, h: any) => { handler = h; } } as any;
+  const budget: BudgetState = { limit, spent: 0, calls: 0, agents: new Map() };
+  registerWalletTool(server, budget);
+  return { call: (a: Record<string, unknown>) => handler!(a), budget };
+}
+
+for (const chain of ["solana", "base"] as const) {
+  test(`[${chain}] wallet-mode status reports the session ledger next to the balance`, async () => {
+    activeChain = chain;
+    const { call, budget } = makeHarness(1);
+    budget.spent = 0.7325;
+    budget.calls = 3;
+
+    const res = await call({ action: "status" });
+    const text: string = res.content[0].text;
+    assert.match(text, /\$12\.000000 USDC/, "the balance is still there");
+    assert.match(text, /This session: \$0\.7325 \/ \$1\.00 local cap — 3 calls/, "the same line the api-key branch prints");
+    assert.equal(res.structuredContent.sessionSpend, 0.7325);
+    assert.equal(res.structuredContent.calls, 3);
+    assert.equal(res.structuredContent.limit, 1);
+    assert.equal(res.structuredContent.activeChain, chain);
+  });
+
+  test(`[${chain}] wallet-mode status with no cap says so rather than omitting the figure`, async () => {
+    activeChain = chain;
+    const { call, budget } = makeHarness(null);
+    budget.spent = 0.01;
+    budget.calls = 1;
+
+    const res = await call({ action: "status" });
+    assert.match(res.content[0].text, /This session: \$0\.0100 — 1 call/);
+    assert.doesNotMatch(res.content[0].text, /local cap/);
+    assert.equal(res.structuredContent.sessionSpend, 0.01);
+    assert.equal(res.structuredContent.limit, null);
+  });
+}
diff --git a/test/workflows.test.ts b/test/workflows.test.ts
new file mode 100644
index 0000000..c6c5c76
--- /dev/null
+++ b/test/workflows.test.ts
@@ -0,0 +1,204 @@
+// Run with: npm test  (tsx --test)
+//
+// The two release-side workflows cannot run locally, but their shell CAN, and
+// their gates can be read. Both have reported success while doing nothing:
+//
+//   brand-sync.yml  — main is protected and Actions may not open PRs here, so
+//                     the push failed, the PR fallback failed, `|| echo` ate
+//                     it, and the run went green with a stale README (#123 sat
+//                     26 days; #141 was the manual PR that finally landed it).
+//   publish.yml     — the tag/release step was gated on `pkg != npm`, which is
+//                     false once npm has published, so a job that went red
+//                     AFTER npm could never repair the missing tag on re-run:
+//                     the re-run skipped the step and went green.
+//
+// The brand-sync test executes the workflow's real `run:` block against shimmed
+// `git`/`gh` binaries that behave the way this org does (push to main
+// rejected, PR creation forbidden). The publish tests parse the YAML and
+// inspect the gates — the only honest check available for an `if:` expression
+// GitHub evaluates.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync, spawnSync } from "node:child_process";
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "yaml";
+
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+type Step = { name?: string; id?: string; if?: string; run?: string };
+type Workflow = { jobs: Record<string, { steps: Step[] }> };
+
+function load(file: string): Workflow {
+  return parse(readFileSync(path.join(ROOT, ".github", "workflows", file), "utf8")) as Workflow;
+}
+
+function step(wf: Workflow, job: string, name: string): Step {
+  const s = wf.jobs[job]?.steps.find((x) => x.name === name);
+  assert.ok(s, `${job} has no step named "${name}"`);
+  return s!;
+}
+
+// ---- brand-sync.yml: the fallback must not report success it did not earn ----
+
+/**
+ * A scratch git repo with one committed file, a drift in the working tree, and
+ * `git`/`gh` shims first on PATH. The shim delegates every git subcommand to
+ * the real binary except `push`, which mirrors this org: a push to main is
+ * rejected (protected branch), any other ref is accepted. `gh` always fails
+ * the way it does for GITHUB_TOKEN here ("not permitted to create or approve
+ * pull requests").
+ */
+function landingFixture(opts: { ghSucceeds: boolean }) {
+  const dir = mkdtempSync(path.join(os.tmpdir(), "brand-sync-run-"));
+  const repo = path.join(dir, "repo");
+  const bin = path.join(dir, "bin");
+  const log = path.join(dir, "calls.log");
+  mkdirSync(repo);
+  mkdirSync(bin);
+  const realGit = execFileSync("sh", ["-c", "command -v git"], { encoding: "utf8" }).trim();
+  writeFileSync(
+    path.join(bin, "git"),
+    `#!/bin/sh
+echo "git $*" >> "${log}"
+if [ "$1" = "push" ]; then
+  case "$*" in
+    *HEAD:main*) echo "remote: error: GH006: Protected branch update failed for refs/heads/main." >&2; exit 1 ;;
+    *) exit 0 ;;
+  esac
+fi
+exec "${realGit}" "$@"
+`,
+  );
+  writeFileSync(
+    path.join(bin, "gh"),
+    `#!/bin/sh
+echo "gh $*" >> "${log}"
+${opts.ghSucceeds ? 'echo "https://github.com/BlockRunAI/blockrun-mcp/pull/999"; exit 0' : 'echo "pull request create failed: GraphQL: GitHub Actions is not permitted to create or approve pull requests (createPullRequest)" >&2; exit 1'}
+`,
+  );
+  chmodSync(path.join(bin, "git"), 0o755);
+  chmodSync(path.join(bin, "gh"), 0o755);
+  const git = (...args: string[]) => execFileSync(realGit, args, { cwd: repo, stdio: "pipe" });
+  git("init", "-q", "-b", "main");
+  git("config", "user.email", "t@example.com");
+  git("config", "user.name", "t");
+  writeFileSync(path.join(repo, "README.md"), "<!-- br:mcp.tools -->19<!-- /br:mcp.tools --> tools\n");
+  git("add", "-A");
+  git("commit", "-q", "-m", "init");
+  // The drift the sync script would have written.
+  writeFileSync(path.join(repo, "README.md"), "<!-- br:mcp.tools -->20<!-- /br:mcp.tools --> tools\n");
+  return {
+    repo,
+    log,
+    env: { ...process.env, PATH: `${bin}:${process.env.PATH}`, GITHUB_REF_NAME: "main", GH_TOKEN: "ghs_fake" },
+    calls: () => readFileSync(log, "utf8"),
+    cleanup: () => rmSync(dir, { recursive: true, force: true }),
+  };
+}
+
+function runLandStep(fixture: ReturnType<typeof landingFixture>) {
+  const script = step(load("brand-sync.yml"), "sync", "Land the rewrite").run;
+  assert.ok(script, "the landing step must be a run: block");
+  return spawnSync("bash", ["-e", "-c", script!], { cwd: fixture.repo, env: fixture.env, encoding: "utf8" });
+}
+
+test("brand-sync: push rejected AND PR creation forbidden is a red run that names the branch", () => {
+  const f = landingFixture({ ghSucceeds: false });
+  try {
+    const r = runLandStep(f);
+    assert.notEqual(r.status, 0, `the step exited ${r.status} having landed nothing:\n${r.stdout}${r.stderr}`);
+    const out = r.stdout + r.stderr;
+    assert.match(out, /brand-sync/, "the pushed branch must be named so a human can open the PR");
+    assert.match(out, /manual PR|needs a human|open the PR/i);
+    // The branch was still pushed — the rewrite is not lost, only unlanded.
+    assert.match(f.calls(), /git push -f origin HEAD:brand-sync/);
+  } finally {
+    f.cleanup();
+  }
+});
+
+test("brand-sync: the fallback branch name is fixed, not dated — one branch, force-pushed, not one per Monday", () => {
+  const f = landingFixture({ ghSucceeds: false });
+  try {
+    runLandStep(f);
+    const pushes = f.calls().split("\n").filter((l) => l.startsWith("git push"));
+    assert.ok(pushes.some((l) => /HEAD:brand-sync$/.test(l)), `expected a push to refs/heads/brand-sync, got:\n${pushes.join("\n")}`);
+    assert.ok(!pushes.some((l) => /brand-sync\/\d{8}/.test(l)), "a dated branch per run is how origin grew brand-sync/20260831, /20260905, /20260907");
+  } finally {
+    f.cleanup();
+  }
+});
+
+test("brand-sync: when the PR does open, the run is green", () => {
+  const f = landingFixture({ ghSucceeds: true });
+  try {
+    const r = runLandStep(f);
+    assert.equal(r.status, 0, r.stdout + r.stderr);
+    assert.match(f.calls(), /gh pr create --head brand-sync/);
+  } finally {
+    f.cleanup();
+  }
+});
+
+test("brand-sync: nothing to land is a quiet green, no push at all", () => {
+  const f = landingFixture({ ghSucceeds: false });
+  try {
+    // Undo the drift: the tree matches HEAD.
+    writeFileSync(path.join(f.repo, "README.md"), "<!-- br:mcp.tools -->19<!-- /br:mcp.tools --> tools\n");
+    const r = runLandStep(f);
+    assert.equal(r.status, 0);
+    assert.match(r.stdout, /already in sync/);
+    assert.doesNotMatch(f.calls(), /git push/);
+  } finally {
+    f.cleanup();
+  }
+});
+
+// ---- publish.yml: three targets, three INDEPENDENT guards ----
+
+test("publish: a version below npm latest is refused before anything installs or publishes", () => {
+  const wf = load("publish.yml");
+  const steps = wf.jobs.publish.steps;
+  const gate = steps.findIndex((s) => /version-gate\.mjs/.test(s.run ?? ""));
+  assert.ok(gate > -1, "publish.yml must call scripts/version-gate.mjs — `pkg != npm` is inequality, not order");
+  const install = steps.findIndex((s) => /npm ci/.test(s.run ?? ""));
+  const publish = steps.findIndex((s) => /npm publish/.test(s.run ?? ""));
+  assert.ok(gate < install && gate < publish, "the gate must run before npm ci and before npm publish");
+  const call = steps[gate]!.run!;
+  assert.match(call, /steps\.v\.outputs\.pkg/);
+  assert.match(call, /steps\.v\.outputs\.npm/);
+});
+
+test("publish: the tag/release step is gated on the tag being ABSENT, not on npm still being behind", () => {
+  const wf = load("publish.yml");
+  const resolve = step(wf, "publish", "Resolve versions");
+  assert.match(resolve.run ?? "", /git ls-remote --exit-code --tags origin "refs\/tags\/v\$\{PKG\}"/, "the tag must be resolved against origin up front");
+  assert.match(resolve.run ?? "", /tag_missing=\$TAG_MISSING/);
+
+  const release = step(wf, "publish", "Tag + GitHub release");
+  const cond = (release.if ?? "").replace(/\s+/g, " ");
+  assert.match(cond, /steps\.v\.outputs\.tag_missing == 'true'/, "the release step's own guard is the tag");
+  assert.doesNotMatch(
+    cond,
+    /^\s*steps\.v\.outputs\.pkg != steps\.v\.outputs\.npm\s*$/,
+    "gated on `pkg != npm` alone, a re-run after npm published skips the step and the tag is never repaired",
+  );
+  // It must still be able to run past a registry failure (the failure that
+  // left 0.32.3 untagged was AFTER npm), and must not run when npm failed.
+  assert.match(cond, /!cancelled\(\)/, "without !cancelled() a registry-step failure skips this step");
+  assert.match(cond, /steps\.npm\.outcome == 'success' \|\| steps\.v\.outputs\.pkg == steps\.v\.outputs\.npm/, "tag only when npm carries the version — published now, or already there");
+  assert.match(cond, /steps\.build\.outcome == 'success'/, "never tag a build that did not pass");
+  assert.equal(step(wf, "publish", "Publish to npm").id, "npm", "the npm step needs an id for its outcome to be referenced");
+  assert.equal(step(wf, "publish", "Build, typecheck, test").id, "build");
+});
+
+test("publish: an npm registry failure is 'unknown' and refused, only an E404 is 'none'", () => {
+  const wf = load("publish.yml");
+  const resolve = step(wf, "publish", "Resolve versions").run ?? "";
+  assert.doesNotMatch(resolve, /npm view @blockrun\/mcp version 2>\/dev\/null \|\| echo "none"/, "every failure spelled as 'none' lets a downgrade through on a registry blip");
+  assert.match(resolve, /E404/, "the not-yet-published case is recognised by npm's own error code");
+  assert.match(resolve, /NPM=unknown|NPM="unknown"/, "anything else is unknown, which the gate refuses");
+});
diff --git a/tsconfig.json b/tsconfig.json
index 6aa671a..a45cf2f 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -13,7 +13,8 @@
   "include": [
     "src/**/*",
     "test/**/*",
-    "apps/**/*"
+    "apps/**/*",
+    "scripts/**/*"
   ],
   "exclude": [
     "node_modules",