@absol-labs/agent 0.12.0-rc.2 → 0.12.0-rc.3

package/docs/x402.md

@@ -145,9 +145,14 @@ instance, ever**:
   the mined outcome; it receives the one success only if none was delivered
   before.
 - The gateway enforces the same rule on its side: a `PAYMENT-SIGNATURE` whose
-  authorization is in flight or already settled gets `409
-x402-payment-already-used` **without** an upstream call; a retry after
-  `settlement_pending` is let through so it can reconcile.
+  authorization is in flight or already settled is refused **without** a
+  verify, an upstream call or a settlement. The refusal has the x402 v2 shape:
+  `402` with a fresh `PAYMENT-REQUIRED` whose `error` is
+  `x402-payment-already-used` (body `{"authorized": false, "reason":
+"x402-payment-already-used", …}`), so a stock client can sign a NEW payment
+  or report the reason. (It was a bare `409` before; the strictness is
+  unchanged.) A retry after `settlement_pending` is let through so it can
+  reconcile.
 - Relayer submissions (simulate + broadcast) are serialized, so concurrent
   payers never collide on the relayer's account nonce.
 
@@ -362,6 +367,56 @@ no proof that matches the escrow's on-chain latest root is available (with an
 shape), `wait` (with `retryAt` / `retryAfterSeconds`), `reclaim`,
 `reclaim-unverified` (with `typedData`), or `none`.
 
+How to read the fields:
+
+- `status` is the escrow's own on-chain status, verbatim (`active` / `closed`).
+  A stream past `expiresAt` that nobody closed is still `active` on-chain;
+  `state` says what it means now: `active` (running), `expired` (past
+  `expiresAt`, accrues nothing more, needs no close) or `closed`.
+  `onChainStatus` repeats the raw value.
+- `maxRefund` is a **ceiling**: the most this payment could ever refund (the
+  escrowed deposit), whatever was delivered. `reclaimable` is what a reclaim
+  returns **now**, given the latest verified delivery: `0` with `maxRefund:
+45000` means the verified delivery covers the whole deposit, not an error.
+  `maxRefundMeaning` and `reclaimableMeaning` say this in the response itself.
+
+**Right after paying.** Every answer is read at one block, and never below the
+block of a transaction the facilitator saw mined for that stream (its
+settlement, or a close/reclaim the relay sent), so a load-balanced RPC whose
+nodes lag each other cannot make a just-opened stream look unknown or a
+just-closed one look active. The relay waits, bounded (8 s by default), for the
+RPC to reach that block, then answers `503 chain-lagging` with `Retry-After`
+rather than a wrong answer. A miss for a stream it has no such block for
+(e.g. after a restart) is re-read once, a second later, before it is `404`. A
+client should still treat `404 not-found` and `503` right after paying as
+"retry shortly", and guard the body before reading `next`:
+
+```ts
+// `opened` is PAYMENT-RESPONSE extra.metrikStreamOpener.
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+async function relayStatus(refundUrl: string) {
+  for (let attempt = 0; attempt < 6; attempt++) {
+    const res = await fetch(refundUrl);
+    const body = await res.json().catch(() => undefined);
+    if (res.ok && body?.next !== undefined) return body;
+    // Just settled: the relay's RPC may not have caught up yet.
+    if (res.status === 404 || res.status === 503 || res.status === 429) {
+      await sleep(Number(res.headers.get("retry-after") ?? "2") * 1000);
+      continue;
+    }
+    throw new Error(`refund relay ${res.status}: ${body?.error ?? "no body"}`);
+  }
+  throw new Error("refund relay did not serve the stream; retry later");
+}
+const status = await relayStatus(opened.refundUrl);
+if (status.next?.action === "close") {
+  // sign status.next.typedData (with your deadline) and POST it to `${refundUrl}/close`
+}
+```
+
+`@absol-labs/sdk`'s `refundClient` (≤ 0.10.0-rc.3) does not retry a status
+read; `metrik refund` re-reads it itself after acting (see `docs/cli.md`).
+
 A successful relayed transaction answers `200` only from its **mined** receipt:
 
 ```json
@@ -375,18 +430,19 @@ A successful relayed transaction answers `200` only from its **mined** receipt:
 `{"ok": false, "error": "<code>", "message": "…", …}`, with `Retry-After`
 where a retry makes sense:
 
-| Status | `error`                                                                                         | Meaning                                                                                     |
-| ------ | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| 400    | `invalid-stream-id`, `invalid-request`, `invalid-json`                                          | Malformed input                                                                             |
-| 403    | `invalid-signature`, `signature-expired`                                                        | Not the payer's EIP-712 signature for this opener, stream and nonce; or deadline too near   |
-| 404    | `not-found`                                                                                     | Unknown stream, or its buyer is not an opener of the configured factory                     |
-| 409    | `already-closed`, `stream-expired`, `already-reclaimed`, `nothing-to-reclaim`, `nonce-mismatch` | Would have no effect; nothing sent                                                          |
-| 409    | `not-reclaimable-yet`, `settlement-window-open`, `proof-unavailable`, `escape-hatch-not-ready`  | Not yet; `retryAt` (unix s) says when at the latest                                         |
-| 409    | `simulation-failed`, `in-progress`, `blocked`                                                   | The simulation reverted; a relayed tx is in flight; an earlier tx had an unexpected outcome |
-| 202    | `pending`                                                                                       | Sent, not mined yet (`transaction`); repeat the same request — it is never re-sent          |
-| 429    | `rate-limited`                                                                                  | Per-IP, per-stream or global budget exhausted                                               |
-| 502    | `transaction-reverted`, `unexpected-receipt`, `submission-failed`                               | Never a success without the expected mined receipt                                          |
-| 503    | `chain-unavailable`, `oracle-unavailable`, `opener-domain-mismatch`                             | Fail closed                                                                                 |
+| Status | `error`                                                                                         | Meaning                                                                                      |
+| ------ | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| 400    | `invalid-stream-id`, `invalid-request`, `invalid-json`                                          | Malformed input                                                                              |
+| 403    | `invalid-signature`, `signature-expired`                                                        | Not the payer's EIP-712 signature for this opener, stream and nonce; or deadline too near    |
+| 404    | `not-found`                                                                                     | Unknown stream, or its buyer is not an opener of the configured factory (confirmed on-chain) |
+| 409    | `already-closed`, `stream-expired`, `already-reclaimed`, `nothing-to-reclaim`, `nonce-mismatch` | Would have no effect; nothing sent                                                           |
+| 409    | `not-reclaimable-yet`, `settlement-window-open`, `proof-unavailable`, `escape-hatch-not-ready`  | Not yet; `retryAt` (unix s) says when at the latest                                          |
+| 409    | `simulation-failed`, `in-progress`, `blocked`                                                   | The simulation reverted; a relayed tx is in flight; an earlier tx had an unexpected outcome  |
+| 202    | `pending`                                                                                       | Sent, not mined yet (`transaction`); repeat the same request — it is never re-sent           |
+| 429    | `rate-limited`                                                                                  | Per-IP, per-stream or global budget exhausted                                                |
+| 502    | `transaction-reverted`, `unexpected-receipt`, `submission-failed`                               | Never a success without the expected mined receipt                                           |
+| 503    | `chain-unavailable`, `oracle-unavailable`, `opener-domain-mismatch`                             | Fail closed                                                                                  |
+| 503    | `chain-lagging`                                                                                 | The RPC is still below a block the stream changed in (`minBlock`); retry after `Retry-After` |
 
 ### Bounded against gas abuse
 
@@ -556,17 +612,18 @@ informational http(s) links on top of the terms, never uses them for
 settlement, and still refuses any other key. "Verified" here means verified
 delivery, not verified output.
 
-| Request carries                                            | Result                                                                                |
-| ---------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| nothing                                                    | `402`, `PAYMENT-REQUIRED` quoting the opener `payTo` and the price                    |
-| `PAYMENT-SIGNATURE`                                        | verified → upstream → settled if upstream `< 400` → `200` + body + `PAYMENT-RESPONSE` |
-| `PAYMENT-SIGNATURE`, upstream `>= 400`                     | upstream response, nothing settled                                                    |
-| `PAYMENT-SIGNATURE`, settle fails                          | `402` + `PAYMENT-RESPONSE`, no upstream body                                          |
-| `x-metrik-capability`                                      | the capability path, unchanged                                                        |
-| capability **and** `PAYMENT-SIGNATURE`                     | `400 ambiguous-capability-and-payment`                                                |
-| probe capability **and** `PAYMENT-SIGNATURE`               | `400 ambiguous-probe-mode`                                                            |
-| any request while the facilitator marker cannot be proven  | `503 x402-facilitator-unavailable`                                                    |
-| a `PAYMENT-SIGNATURE` already in flight or already settled | `409 x402-payment-already-used`, no upstream call                                     |
+| Request carries                                                       | Result                                                                                                                                  |
+| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| nothing                                                               | `402`, `PAYMENT-REQUIRED` quoting the opener `payTo` and the price                                                                      |
+| `PAYMENT-SIGNATURE`                                                   | verified → upstream → settled if upstream `< 400` → `200` + body + `PAYMENT-RESPONSE`                                                   |
+| `PAYMENT-SIGNATURE`, upstream `>= 400`                                | upstream response, nothing settled                                                                                                      |
+| `PAYMENT-SIGNATURE`, verify refuses it (e.g. `validBefore` too short) | `402`, fresh `PAYMENT-REQUIRED` whose `error` is the reason; body `{"authorized": false, "reason": "x402-payment-invalid", "error": …}` |
+| `PAYMENT-SIGNATURE`, settle fails                                     | `402` + `PAYMENT-RESPONSE` (`success: false`, `errorReason`), no upstream body; body `{"reason": "x402-settlement-failed", "error": …}` |
+| `x-metrik-capability`                                                 | the capability path, unchanged                                                                                                          |
+| capability **and** `PAYMENT-SIGNATURE`                                | `400 ambiguous-capability-and-payment`                                                                                                  |
+| probe capability **and** `PAYMENT-SIGNATURE`                          | `400 ambiguous-probe-mode`                                                                                                              |
+| any request while the facilitator marker cannot be proven             | `503 x402-facilitator-unavailable`                                                                                                      |
+| a `PAYMENT-SIGNATURE` already in flight or already settled            | `402`, fresh `PAYMENT-REQUIRED` with `error: "x402-payment-already-used"`; no verify, upstream call or settle                           |
 
 With `METRIK_GATEWAY_X402V2_OPENER` unset the gateway is byte for byte the
 capability-only gateway (`test/gateway-http-baseline.test.ts`), and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absol-labs/agent",
-  "version": "0.12.0-rc.2",
+  "version": "0.12.0-rc.3",
   "description": "Metrik agent layer: verified-streaming USDC payments metered by delivery, an MCP server, framework tools, and spend mandates so AI agents can hire and pay verified services safely.",
   "license": "MIT",
   "author": "Absol Labs",
@@ -85,7 +85,7 @@
     "pnpm": "9.15.x"
   },
   "dependencies": {
-    "@absol-labs/sdk": "0.10.0-rc.3",
+    "@absol-labs/sdk": "0.10.0-rc.4",
     "@absol-labs/shared": "0.14.0-rc.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "1.3.0",

package/src/cli/commands/claim.ts

@@ -63,7 +63,7 @@ export const claimCommand: CommandSpec = {
         `wallet ${account.address} is not the operator of this stream`,
         {
           exitCode: 3,
-          hint: `only ${stream.operator} can claim it — the escrow enforces this, so no other wallet can. Set ${PRIVATE_KEY_ENV} to the operator's key. (The buyer's side of this stream is \`metrik reclaim ${streamId}\`.)`,
+          hint: `only ${stream.operator} can claim it — the escrow enforces this, so no other wallet can. Set ${PRIVATE_KEY_ENV} to the operator's key. (The buyer's side of this stream is \`${buyerSideCommand(stream, streamId, deps.nowSeconds())}\`.)`,
         },
       );
     }
@@ -259,3 +259,19 @@ export async function planClaim(
     }),
   };
 }
+
+/**
+ * The buyer's recovery command for a stream. A reclaim needs the clock
+ * stopped (closed, or past expiresAt), so a still-running stream gets
+ * `--close-first`; the plain form only once it has stopped.
+ */
+export function buyerSideCommand(
+  stream: { readonly status: string; readonly expiresAt: number },
+  streamId: string,
+  nowSeconds: number,
+): string {
+  const stopped = stream.status === "closed" || nowSeconds >= stream.expiresAt;
+  return stopped
+    ? `metrik reclaim ${streamId}`
+    : `metrik reclaim ${streamId} --close-first`;
+}

package/src/cli/commands/refund.ts

@@ -25,6 +25,15 @@ export const REFUND_URL_ENV = "METRIK_AGENT_REFUND_URL";
 
 const DEFAULT_ATTEMPTS = 5;
 const DEFAULT_MAX_WAIT_SECONDS = 60;
+/**
+ * After a close/reclaim, how many times the summary re-reads the relay until
+ * it reflects the transaction just mined (a load-balanced RPC behind the relay
+ * can answer from a node that has not seen it yet), and how long it waits
+ * between reads. Bounded: past it the summary is derived from the verified
+ * receipts instead.
+ */
+const POST_ACTION_READS = 6;
+const POST_ACTION_INTERVAL_MS = 1_500;
 
 export const refundCommand: CommandSpec = {
   name: "refund",
@@ -186,7 +195,17 @@ export const refundCommand: CommandSpec = {
       }
     }
 
-    const status = await relay(() => refunds.status());
+    // The summary describes the state AFTER what this run did: re-read until
+    // the relay reflects the close/reclaim just mined (bounded), else derive
+    // it from the verified receipts. Never the pre-action state.
+    const status = await statusAfterActions(refunds, {
+      closed: closeResult !== null,
+      reclaim: reclaimResult,
+      payer: stream.payer ?? null,
+      opener,
+      streamId,
+      sleep: deps.sleep,
+    });
     // A reclaim THIS run performed is reported as a reclaim, not as "already
     // finished".
     const finished =
@@ -197,7 +216,10 @@ export const refundCommand: CommandSpec = {
       streamId,
       opener,
       payer: status.payer,
+      // The escrow's own on-chain status, verbatim.
       status: status.status,
+      // What it means now: an Active stream past expiresAt is "expired".
+      state: stateOf(status),
       reclaimed: status.reclaimed,
       reclaimable: status.reclaimable,
       next: status.next,
@@ -233,13 +255,115 @@ export const refundCommand: CommandSpec = {
     );
     out.print("");
     out.print(
-      finished === null
-        ? nextStep(status, streamId, refundUrl)
-        : describeFinished(finished),
+      reclaimResult !== null
+        ? describeReclaimed(reclaimResult)
+        : finished === null
+          ? nextStep(status, streamId, refundUrl)
+          : describeFinished(finished),
     );
   },
 };
 
+/**
+ * The relay's view of a stream AFTER this run's actions. Reads until it
+ * reflects them (closed after a close, reclaimed after a reclaim), bounded;
+ * if the relay still lags, the state those verified transactions imply is
+ * reported instead, marked as derived. With no action, one plain read.
+ */
+async function statusAfterActions(
+  refunds: RefundClient,
+  done: {
+    readonly closed: boolean;
+    readonly reclaim: RefundRelayResult | null;
+    readonly payer: `0x${string}` | null;
+    readonly opener: `0x${string}`;
+    readonly streamId: `0x${string}`;
+    readonly sleep: (ms: number) => Promise<void>;
+  },
+): Promise<RefundStatus> {
+  const reclaimed = done.reclaim !== null;
+  if (!done.closed && !reclaimed) return await relay(() => refunds.status());
+  const reflects = (status: RefundStatus): boolean =>
+    (!done.closed || status.status === "closed" || status.reclaimed) &&
+    (!reclaimed || status.reclaimed);
+  let last: RefundStatus | null = null;
+  for (let attempt = 1; attempt <= POST_ACTION_READS; attempt++) {
+    try {
+      const status = await refunds.status();
+      if (reflects(status)) return status;
+      last = status;
+    } catch {
+      // A lagging relay (503 chain-lagging, a stale not-found, a blip): the
+      // transactions already happened, so keep going and derive if need be.
+    }
+    if (attempt < POST_ACTION_READS) await done.sleep(POST_ACTION_INTERVAL_MS);
+  }
+  return derivedStatus(last, done);
+}
+
+/** The state this run's verified close/reclaim imply, when the relay lags. */
+function derivedStatus(
+  last: RefundStatus | null,
+  done: {
+    readonly closed: boolean;
+    readonly reclaim: RefundRelayResult | null;
+    readonly payer: `0x${string}` | null;
+    readonly opener: `0x${string}`;
+    readonly streamId: `0x${string}`;
+  },
+): RefundStatus {
+  const reclaimed = done.reclaim !== null;
+  const note =
+    "derived from this run's transaction receipts; the refund relay had not caught up with them yet";
+  return {
+    streamId: done.streamId,
+    chainId: last?.chainId ?? 0,
+    opener: last?.opener ?? done.opener,
+    payer: last?.payer ?? done.payer ?? done.opener,
+    status: "closed",
+    reclaimed: reclaimed || (last?.reclaimed ?? false),
+    chainTime: last?.chainTime ?? null,
+    reclaimable: null,
+    // Both legs this run verified are on-chain facts: the stream is closed.
+    state: "closed",
+    onChainStatus: "closed",
+    maxRefund: last?.maxRefund ?? null,
+    maxRefundMeaning: last?.maxRefundMeaning ?? null,
+    reclaimableMeaning: last?.reclaimableMeaning ?? null,
+    next: reclaimed
+      ? {
+          action: "none",
+          message:
+            "Reclaimed: the unearned remainder was returned to the payer. Nothing further to do.",
+        }
+      : {
+          action: "reclaim",
+          message:
+            "Closed. Reclaim the unearned remainder once a checkpoint covering the close is posted (usually within a minute).",
+        },
+    raw: { derived: true, note },
+  } satisfies RefundStatus;
+}
+
+/** `closed`, `expired` (Active on-chain but past expiresAt) or `active`. */
+export function stateOf(status: RefundStatus): "active" | "expired" | "closed" {
+  if (status.status === "closed" || status.reclaimed) return "closed";
+  const raw = status.raw as { state?: unknown; expiresAt?: unknown };
+  if (raw.state === "expired") return "expired";
+  if (
+    typeof raw.expiresAt === "number" &&
+    status.chainTime !== null &&
+    status.chainTime >= raw.expiresAt
+  ) {
+    return "expired";
+  }
+  return "active";
+}
+
+function describeReclaimed(result: RefundRelayResult): string {
+  return `Reclaimed: ${result.amount === null ? "the unearned remainder" : formatUsdc(result.amount)} was returned to the payer${result.verified ? " (receipt verified on-chain)" : ""}. Nothing further to do for this stream.`;
+}
+
 /** Why a recovery is over. */
 export type FinishedReason = "reclaimed" | "nothing-to-reclaim";
 /** Why a requested `--close` / `--reclaim` sent nothing. */
@@ -414,10 +538,19 @@ function statusRows(
   closeSkipped: SkipReason | null,
   finished: FinishedReason | null,
 ): (readonly [string, string])[] {
+  const state = stateOf(status);
+  const derived = (status.raw as { derived?: unknown }).derived === true;
   const rows: (readonly [string, string])[] = [
     [
       "status",
-      status.reclaimed ? `${status.status} (reclaimed)` : status.status,
+      (status.reclaimed
+        ? `${state} (reclaimed)`
+        : state === status.status
+          ? state
+          : `${state} (on-chain: ${status.status}; past expiresAt, accrues nothing more)`) +
+        (derived
+          ? " — from this run's receipts; the relay is still catching up"
+          : ""),
     ],
     ...(finished === null
       ? []
@@ -425,10 +558,14 @@ function statusRows(
     ["payer", status.payer],
     ["opener", status.opener],
     [
-      "reclaimable",
-      status.reclaimable === null ? "-" : formatUsdc(status.reclaimable),
+      "reclaimable now",
+      reclaimResult !== null || status.reclaimed
+        ? "- (already reclaimed)"
+        : status.reclaimable === null
+          ? "-"
+          : formatUsdc(status.reclaimable),
     ],
-    ["next", status.next.action],
+    ["next", reclaimResult !== null ? "none" : status.next.action],
   ];
   if (closeResult === null && closeSkipped !== null) {
     rows.push(["close", "skipped — already closed"]);
@@ -462,6 +599,10 @@ function nextStep(
   const base = `metrik refund ${streamId} --refund-url ${refundUrl}`;
   switch (status.next.action) {
     case "close":
+      if (status.status === "closed") {
+        // Never "still running" for a stream the chain shows closed.
+        return `Refunds are NOT automatic. The stream is closed: reclaim the unearned remainder with  ${base} --reclaim`;
+      }
       return `Refunds are NOT automatic. The stream is still running: stop it with  ${base} --close --reclaim`;
     case "reclaim":
       return `Refunds are NOT automatic. Reclaim the unearned remainder with  ${base} --reclaim`;

package/src/cli/status.ts

@@ -564,7 +564,7 @@ export function streamReportRows(
     ],
     ["rate", `${formatUsdc(stream.ratePerSecond)} / second`],
     ["opened", formatTimestamp(stream.openedAt)],
-    ["expires", describeDeadline(stream.expiresAt, report.nowSeconds)],
+    describeDeadline(stream, report.nowSeconds),
   ];
   if (stream.closedAt > 0) {
     rows.push(["closed", formatTimestamp(stream.closedAt)]);
@@ -781,11 +781,32 @@ function describePendingSettlement(settlement: SettlementCoverage): string {
   return `pending final checkpoint — the stream stopped at ${stopAt}, the oracle has published only to ${covered}. Reclaim reverts until a checkpoint reaches the stop time (~15-22s apart).`;
 }
 
-function describeDeadline(expiresAt: number, nowSeconds: number): string {
+/**
+ * The expiry row. A stream that was closed before its expiry never reaches
+ * it, so it never reads as a countdown ("in 57m") — that looked like a stream
+ * still running. Exported for tests.
+ */
+export function describeDeadline(
+  stream: Pick<StreamV2, "expiresAt" | "closedAt">,
+  nowSeconds: number,
+): readonly [string, string] {
+  const { expiresAt } = stream;
+  const closedEarly = stream.closedAt > 0 && stream.closedAt < expiresAt;
+  if (closedEarly) {
+    return [
+      "would have expired",
+      `${formatTimestamp(expiresAt)} — not reached: closed early at ${formatTimestamp(stream.closedAt)}, so it accrues nothing more`,
+    ];
+  }
   const remaining = expiresAt - nowSeconds;
-  const suffix =
-    remaining > 0
-      ? `in ${formatDuration(remaining)}`
-      : `${formatDuration(-remaining)} ago`;
-  return `${formatTimestamp(expiresAt)} — ${suffix}`;
+  if (remaining > 0) {
+    return [
+      "expires",
+      `${formatTimestamp(expiresAt)} — in ${formatDuration(remaining)}`,
+    ];
+  }
+  return [
+    "expired",
+    `${formatTimestamp(expiresAt)} — ${formatDuration(-remaining)} ago`,
+  ];
 }

package/src/gateway/x402-opener-mode.ts

@@ -14,7 +14,11 @@ import {
   type SettleResultContext,
 } from "@x402/core/server";
 import type { Network } from "@x402/core/types";
-import { decodePaymentSignatureHeader } from "@x402/core/http";
+import {
+  decodePaymentRequiredHeader,
+  decodePaymentSignatureHeader,
+  encodePaymentRequiredHeader,
+} from "@x402/core/http";
 import { ExactEvmScheme } from "@x402/evm/exact/server";
 import {
   createPublicClient,
@@ -1029,7 +1033,16 @@ async function handleX402GatewayRequest(
     claim !== undefined &&
     !mode.authorizations.claim(claim.key, claim.validBefore)
   ) {
-    io.writeJson(409, "x402-payment-already-used");
+    // Refused exactly as strictly as before (no verify, no upstream, no
+    // settle), but in the x402 v2 shape: a 402 with a FRESH PAYMENT-REQUIRED
+    // whose `error` says why, so a stock client can pay again or report it.
+    await writePaymentRejected(
+      mode,
+      io,
+      context,
+      "x402-payment-already-used",
+      "this PAYMENT-SIGNATURE's authorization was already used (or is being settled) for another request; each authorization buys at most one response. Sign a new payment to call again.",
+    );
     return;
   }
   const release = () => {
@@ -1054,7 +1067,10 @@ async function handleX402GatewayRequest(
   }
   if (result.type === "payment-error") {
     release();
-    writeInstructions(io, result.response);
+    // The stock 402: a fresh PAYMENT-REQUIRED whose `error` is the verifier's
+    // reason (e.g. an authorization whose validBefore is too short). The body
+    // is made readable too, instead of `{}`.
+    writeInstructions(io, result.response, "x402-payment-invalid");
     return;
   }
 
@@ -1133,8 +1149,14 @@ async function handleX402GatewayRequest(
         release();
       }
     }
-    // No upstream body on a failed settlement.
-    writeInstructions(io, settled.response);
+    // No upstream body on a failed settlement. The stock settlement-failure
+    // 402 carries PAYMENT-RESPONSE (success false, errorReason).
+    writeInstructions(
+      io,
+      settled.response,
+      "x402-settlement-failed",
+      settled.errorReason,
+    );
     return;
   }
   if (claim !== undefined) {
@@ -1159,6 +1181,8 @@ async function handleX402GatewayRequest(
 function writeInstructions(
   io: X402GatewayRequestIO,
   response: HTTPResponseInstructions,
+  reason?: "x402-payment-invalid" | "x402-settlement-failed",
+  settlementError?: string,
 ): void {
   const headers: Record<string, string> = { ...response.headers };
   if (response.isHtml === true) {
@@ -1167,5 +1191,106 @@ function writeInstructions(
     return;
   }
   headers["Content-Type"] = "application/json";
-  io.write(response.status, headers, JSON.stringify(response.body ?? {}));
+  let body = response.body ?? {};
+  if (
+    reason !== undefined &&
+    typeof body === "object" &&
+    body !== null &&
+    Object.keys(body).length === 0
+  ) {
+    // Same JSON shape as the gateway's other refusals, plus the x402 error.
+    const error = settlementError ?? paymentRequiredError(headers);
+    body = {
+      authorized: false,
+      reason,
+      ...(error === undefined ? {} : { error }),
+    };
+  }
+  io.write(response.status, headers, JSON.stringify(body));
+}
+
+/** The `error` carried in a response's PAYMENT-REQUIRED header, if any. */
+function paymentRequiredError(
+  headers: Record<string, string>,
+): string | undefined {
+  const value = headerValue(headers, "payment-required");
+  if (value === undefined) return undefined;
+  try {
+    const decoded = decodePaymentRequiredHeader(value);
+    return typeof decoded.error === "string" ? decoded.error : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function headerValue(
+  headers: Record<string, string>,
+  name: string,
+): string | undefined {
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === name) return value;
+  }
+  return undefined;
+}
+
+/**
+ * A spec-shaped x402 v2 refusal of a payment the gateway will not accept: a
+ * `402` with a fresh `PAYMENT-REQUIRED` (built by the same resource server
+ * that quotes every 402, with no payment attached, so nothing is verified or
+ * settled) whose `error` is `reason`, and a JSON body naming it.
+ */
+async function writePaymentRejected(
+  mode: GatewayX402OpenerMode,
+  io: X402GatewayRequestIO,
+  context: HTTPRequestContext,
+  reason: "x402-payment-already-used",
+  message: string,
+): Promise<void> {
+  const body = JSON.stringify({
+    authorized: false,
+    reason,
+    error: reason,
+    message,
+  });
+  let headers: Record<string, string> = {};
+  try {
+    const { paymentHeader: _omitted, ...unpaid } = context;
+    const challenge = await mode.httpServer.processHTTPRequest({
+      ...unpaid,
+      adapter: {
+        ...context.adapter,
+        // The core reads the payment from the adapter's headers: hide it, so
+        // this builds a quote only and NOTHING is verified or settled.
+        getHeader: (name: string) =>
+          ["payment-signature", "x-payment"].includes(name.toLowerCase())
+            ? undefined
+            : context.adapter.getHeader(name),
+        // Always the machine-readable 402, never the browser paywall.
+        getAcceptHeader: () => "application/json",
+      },
+    });
+    if (challenge.type === "payment-error") {
+      for (const [key, value] of Object.entries(challenge.response.headers)) {
+        if (key.toLowerCase() === "content-type") continue;
+        headers[key] = value;
+      }
+      const required = headerValue(headers, "payment-required");
+      if (required !== undefined) {
+        const decoded = decodePaymentRequiredHeader(required);
+        for (const key of Object.keys(headers)) {
+          if (key.toLowerCase() === "payment-required") delete headers[key];
+        }
+        headers["PAYMENT-REQUIRED"] = encodePaymentRequiredHeader({
+          ...decoded,
+          error: reason,
+        });
+      }
+    }
+  } catch (error) {
+    // Still a 402 refusal (never served, never settled); just without a quote.
+    io.logError("x402 fresh PAYMENT-REQUIRED failed", error);
+    headers = {};
+  }
+  headers["Content-Type"] = "application/json";
+  io.write(402, headers, body);
 }