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

package/dist/x402-buyer/refund-actions.js

@@ -0,0 +1,351 @@
+/**
+ * The buyer's own close + reclaim of an x402 stream, through the seller's
+ * gasless refund relay. ONE implementation behind `metrik refund`,
+ * `metrik pay --close-after`, the MCP `x402_pay` tool's `closeAfter` and
+ * {@link closeAfterPayment} (`@absol-labs/agent/x402-buyer`).
+ *
+ * Nothing here is an automatic refund: it runs only when the buyer asks for
+ * it, and it is the buyer's own client that signs the Close and asks the
+ * relay to send the permissionless reclaim. The relay pays the gas; the
+ * opener always sends the reclaim to the payer.
+ *
+ * The waits are bounded and the relay's own: `RefundClient.status()` waits
+ * out a `503 chain-lagging` (honouring `Retry-After`), and
+ * `RefundClient.reclaim()` retries, bounded by the client's `maxAttempts` /
+ * `maxDelayMs`, while the relay says the checkpoint covering the close is not
+ * posted yet.
+ */
+/**
+ * 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.
+ */
+export const POST_ACTION_READS = 6;
+export const POST_ACTION_INTERVAL_MS = 1_500;
+/**
+ * A close or reclaim that did not complete. `closed` says whether the stream
+ * is known to be closed (by this run or before it), so the caller can name the
+ * exact command that finishes the job. `cause` is the SDK's error, unchanged.
+ */
+export class RefundActionsError extends Error {
+    stage;
+    closed;
+    closeResult;
+    constructor(context) {
+        super(`the ${context.stage} did not finish: ${context.cause instanceof Error ? context.cause.message : String(context.cause)}`, { cause: context.cause });
+        this.name = "RefundActionsError";
+        this.stage = context.stage;
+        this.closed = context.closed;
+        this.closeResult = context.closeResult;
+    }
+}
+/**
+ * Close and/or reclaim one x402 stream through its refund relay, then read
+ * the state AFTER those actions. Finished states (already closed, already
+ * reclaimed, nothing to reclaim) are reported, not thrown. Anything else that
+ * fails is a {@link RefundActionsError} carrying the SDK's error as `cause`.
+ */
+export async function runRefundActions(input) {
+    const { refunds } = input;
+    let closeResult = null;
+    let closeSkipped = null;
+    // Set when the relay itself says there is nothing left: the stream was
+    // already reclaimed, or the verified delivery covers the whole deposit.
+    // Those are FINISHED recoveries, not failures — a second close + reclaim on
+    // a done stream must succeed and never point the payer at a gas-spending
+    // on-chain recovery that cannot recover a cent.
+    let finishedByRelay = null;
+    if (input.close) {
+        try {
+            // Ask first: a stream that is already closed (or already finished)
+            // needs no Close, so there is nothing to sign and no wallet is needed.
+            const before = await refunds.status();
+            const finishedBefore = finishedReason(before);
+            if (finishedBefore !== null || before.status === "closed") {
+                closeSkipped = finishedBefore ?? "already-closed";
+                finishedByRelay = finishedBefore;
+                input.note?.(finishedBefore === null
+                    ? "stream is already closed — no Close to sign."
+                    : `stream is already closed and ${finishedBefore === "reclaimed" ? "reclaimed" : "has nothing left to reclaim"} — no Close to sign.`);
+            }
+            else {
+                const signer = await input.closeSigner();
+                try {
+                    closeResult = await refunds.close({ signer });
+                    input.note?.(`close relayed in ${closeResult.transaction}${closeResult.verified ? " (receipt verified on-chain)" : ""}`);
+                }
+                catch (error) {
+                    // The status read above said "active", but the stream closed in the
+                    // meantime (it reached expiresAt, or another close landed): the
+                    // state the payer asked for. Anything else is a real failure.
+                    if (relayCode(error) !== "already-closed")
+                        throw error;
+                    closeSkipped = "already-closed";
+                    input.note?.("stream was already closed — no Close was needed.");
+                }
+            }
+        }
+        catch (error) {
+            throw new RefundActionsError({
+                stage: "close",
+                closed: false,
+                closeResult: null,
+                cause: error,
+            });
+        }
+    }
+    let reclaimResult = null;
+    let reclaimSkipped = null;
+    if (input.reclaim) {
+        if (finishedByRelay !== null) {
+            reclaimSkipped = finishedByRelay;
+        }
+        else {
+            if (input.reclaimActivity !== undefined) {
+                input.setActivity?.(input.reclaimActivity);
+            }
+            try {
+                reclaimResult = await refunds.reclaim();
+            }
+            catch (error) {
+                const finished = finishedFromRelayCode(relayCode(error));
+                if (finished === null) {
+                    throw new RefundActionsError({
+                        stage: "reclaim",
+                        closed: closeResult !== null || closeSkipped !== null,
+                        closeResult,
+                        cause: error,
+                    });
+                }
+                reclaimSkipped = finished;
+                finishedByRelay = finished;
+            }
+            finally {
+                input.setActivity?.(null);
+            }
+        }
+    }
+    // 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: input.payer,
+        opener: input.opener,
+        streamId: input.streamId,
+        sleep: input.sleep,
+    });
+    // A reclaim THIS run performed is reported as a reclaim, not as "already
+    // finished".
+    const finished = reclaimResult === null ? (finishedReason(status) ?? finishedByRelay) : null;
+    return {
+        close: closeResult,
+        closeSkipped,
+        reclaim: reclaimResult,
+        reclaimSkipped,
+        status,
+        finished,
+    };
+}
+/**
+ * Right after a paid response, at the BUYER's request: close the stream the
+ * payment opened (the payer signs the Close, the relay pays the gas), wait for
+ * the checkpoint covering the close, and reclaim the unearned remainder to the
+ * payer. Never throws for a close/reclaim failure: the payment already
+ * succeeded, so the outcome says what did not finish instead.
+ *
+ * An upfront-only payment (no stream) has nothing to close: the outcome is
+ * `nothing-to-close` and nothing is requested, signed or sent.
+ */
+export async function closeAfterPayment(input) {
+    const { payment } = input;
+    const empty = {
+        close: null,
+        closeSkipped: null,
+        reclaim: null,
+        reclaimSkipped: null,
+        refundedUsdc: null,
+        finished: null,
+        status: null,
+    };
+    if (payment.streamId === null || /^0x0{64}$/i.test(payment.streamId)) {
+        return {
+            ...empty,
+            outcome: "nothing-to-close",
+            streamId: null,
+            incomplete: null,
+        };
+    }
+    const streamId = payment.streamId;
+    if (payment.refundUrl === null) {
+        return {
+            ...empty,
+            outcome: "incomplete",
+            streamId,
+            incomplete: {
+                stage: "no-relay",
+                closed: false,
+                reason: "the seller advertised no refund relay, so there is no gasless close; the stream accrues only for verified seconds until it expires, and anyone can reclaim the unearned remainder to the payer after that",
+                error: null,
+            },
+        };
+    }
+    let refunds;
+    try {
+        refunds = await input.openRefunds();
+    }
+    catch (error) {
+        return {
+            ...empty,
+            outcome: "incomplete",
+            streamId,
+            incomplete: {
+                stage: "close",
+                closed: false,
+                reason: errorMessage(error),
+                error,
+            },
+        };
+    }
+    try {
+        const result = await runRefundActions({
+            ...input,
+            refunds,
+            streamId,
+            opener: payment.opener,
+            close: true,
+            reclaim: true,
+        });
+        return {
+            outcome: "completed",
+            streamId,
+            close: result.close,
+            closeSkipped: result.closeSkipped,
+            reclaim: result.reclaim,
+            reclaimSkipped: result.reclaimSkipped,
+            refundedUsdc: result.reclaim !== null && result.reclaim.verified
+                ? result.reclaim.amount
+                : null,
+            finished: result.finished,
+            status: result.status,
+            incomplete: null,
+        };
+    }
+    catch (error) {
+        if (!(error instanceof RefundActionsError))
+            throw error;
+        return {
+            ...empty,
+            outcome: "incomplete",
+            streamId,
+            close: error.closeResult,
+            incomplete: {
+                stage: error.stage,
+                closed: error.closed,
+                reason: errorMessage(error.cause),
+                error: error.cause,
+            },
+        };
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * 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.
+ */
+export async function statusAfterActions(refunds, done) {
+    const reclaimed = done.reclaim !== null;
+    if (!done.closed && !reclaimed)
+        return await refunds.status();
+    const reflects = (status) => (!done.closed || status.status === "closed" || status.reclaimed) &&
+        (!reclaimed || status.reclaimed);
+    let last = 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, done) {
+    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 },
+    };
+}
+/**
+ * Whether the relay's status says nothing is left to recover. `reclaimed` is
+ * the chain's one-reclaim-per-stream flag; `next: none` with `reclaimable: 0`
+ * is the relay's "the verified delivery covers the whole deposit".
+ */
+export function finishedReason(status) {
+    if (status.reclaimed)
+        return "reclaimed";
+    if (status.next.action === "none" && status.reclaimable === 0n) {
+        return "nothing-to-reclaim";
+    }
+    return null;
+}
+/** The relay's 409 codes that mean "finished", not "failed". */
+function finishedFromRelayCode(code) {
+    if (code === "already-reclaimed")
+        return "reclaimed";
+    if (code === "nothing-to-reclaim")
+        return "nothing-to-reclaim";
+    return null;
+}
+/** The relay's refusal code, looked up through a few `cause` links. */
+export function relayCode(error) {
+    for (let current = error, depth = 0; depth < 4; depth++) {
+        if (!(current instanceof Error))
+            return null;
+        const code = current.code;
+        if (current.name === "RefundRelayError" && typeof code === "string") {
+            return code;
+        }
+        current = current.cause;
+    }
+    return null;
+}
+//# sourceMappingURL=refund-actions.js.map

package/dist/x402-buyer/refund-actions.js.map

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

package/docs/cli.md

@@ -605,9 +605,10 @@ everyone who ran it. It is left out until that constraint lifts.
 
 ```bash
 metrik pay https://x402.example/transform --json '{"text":"# hi"}' --max-amount 0.1
+metrik pay https://x402.example/transform --json '{"text":"# hi"}' --max-amount 0.1 --close-after
 metrik pay <url> [--json <body> | --data <body>] [--method POST] [--header "K: V"] \
   --max-amount <usdc> [--max-rate <usdc/s>] [--max-upfront <usdc>] [--max-duration <s>] \
-  [--min-duration <s>] [--operator <address>] [--units atomic]
+  [--min-duration <s>] [--operator <address>] [--close-after] [--units atomic]
 ```
 
 Pays any **x402 v2 `exact`** endpoint through `@absol-labs/sdk/x402`'s `payWithX402`,
@@ -679,11 +680,41 @@ facilitator's `PAYMENT-RESPONSE` header (relayed by the seller) carries the sett
 transaction hash, it is printed as `settlement tx` and returned as
 `settlementTransaction` with `settlementTransactionSource: "PAYMENT-RESPONSE"`: the
 facilitator's relayer broadcast it, not the payer, and the CLI reports it as given.
-**Refunds are not automatic** — see `metrik refund`.
-
-Exit codes: `2` usage (including no ceiling), `3` refused by the mandate or the SDK
-(nothing signed, including an upfront part above `--max-upfront`), `4` the settlement failed after signing (the error says whether the
-authorization was used and how to cancel it; see [x402.md](./x402.md)).
+**Refunds are not automatic** — see `metrik refund`, or ask for the close up front with
+`--close-after`.
+
+**Close right after the response (`--close-after`).** The metered part of a payment pays
+per verified second of the seller's uptime, not per call: a one-shot caller who never
+closes lets the seller earn the whole metered part for a single response. With
+`--close-after`, once the paid response is in (the request settled), the CLI does what
+`metrik refund <streamId> --refund-url <url> --close --reclaim` does, in the same run and
+with the same code: it signs the payer's `Close` (the payer key, no gas), the seller's
+refund relay sends it and pays the gas, the CLI waits for the checkpoint covering the close
+(bounded: up to 5 relay attempts, at most 60 s each, honouring `Retry-After`; a relay that
+lags the chain is waited out the same way), then asks the relay to reclaim the unearned
+part to the payer. This is your client acting on your request — the escrow does not
+return anything by itself, and nothing is sent unless you pass the flag. It then prints
+what came back, from the verified receipt: `close tx`, `reclaim tx`, `refunded to payer`,
+`seller earned` (verified seconds) and `payment cost` (price minus refund: the upfront
+part plus what was earned). JSON adds `closeAfter` (`outcome`, `close`, `reclaim`,
+`refunded`, `kept`, `earned`, `finishCommand`, `sentBy: "buyer"`, `refundIsAutomatic:
+false`). An upfront-only payment has nothing to close: it says so and exits `0` with
+`closeAfter.outcome: "nothing-to-close"`. A request that did not settle (nothing paid)
+closes nothing (`closeAfter.outcome: "not-paid"`).
+
+If the close or the reclaim does not finish (the relay is down, the checkpoint is late,
+the seller advertised no relay), the payment and the response still stand and nothing is
+lost — the unearned part stays in the escrow for the payer. `pay` then exits **`5`**,
+keeps the full result on stdout (`closeAfter.outcome: "incomplete"`, with the `stage` that
+did not finish), and prints the exact command that finishes it, for example
+`metrik refund <streamId> --refund-url <url> --reclaim` when the stream is already closed.
+
+Exit codes: `0` paid (or nothing to pay), `2` usage (including no ceiling), `3` refused by
+the mandate or the SDK (nothing signed, including an upfront part above `--max-upfront`),
+`4` the settlement failed after signing (the error says whether the authorization was used
+and how to cancel it; see [x402.md](./x402.md)), `5` paid and answered, but the
+`--close-after` close/reclaim did not finish (the hint names the command that finishes
+it).
 
 ### `metrik refund`
 
@@ -906,7 +937,8 @@ done
 ```
 
 Exit codes: `0` success, `2` usage error, `3` refused configuration (wrong chain, no
-wallet, mandate denied), `4` the operation failed.
+wallet, mandate denied), `4` the operation failed, `5` (`metrik pay --close-after` only)
+paid and answered, but the close/reclaim did not finish.
 
 **Nothing waits silently.** Every RPC call carries a 15s budget with two bounded retries,
 and the oracle fetch — an HTTP call the RPC transport does not cover — has its own 20s

package/docs/mcp-reference.md

@@ -193,6 +193,29 @@ the stream record carries `nonRefundableUsdc`. An **upfront-only** payment
 reservation) is recorded — only a non-stream charge that keeps counting against
 `maxTotalUsdc` and shows in `list_streams` as such — and the payment is final.
 
+**`closeAfter: true` — close right after the response.** The metered part pays per
+verified second of the seller's uptime, not per call, so a one-shot call that is never
+closed lets the seller earn the whole metered part for one response. With `closeAfter`,
+once the paid response is in, this server does what `refund` with `close: true` does, in
+the same call and with the same code as `metrik refund`: it signs the payer's `Close`
+(the relay sends it and pays the gas), waits — bounded, honouring `Retry-After` — for the
+checkpoint covering the close, and asks the relay to reclaim the unearned part to the
+payer. It is this server acting on the model's request; the escrow does not return
+anything by itself, and nothing is sent unless `closeAfter` is set. The wait runs after
+the owner's spend queue is released, and can add a minute or two to the call. The result
+adds `closeAfter` (`outcome` `completed` / `nothing-to-close` / `incomplete`, `close`,
+`reclaim` with `amountUsdc` and `verified`, `refundedUsdc`, `incomplete.stage`,
+`sentBy: "buyer"`, `refundIsAutomatic: false`) and `countedSpendUsdc`.
+
+_Spend accounting:_ only what the payment finally kept counts against the mandate. A
+reclaim whose mined receipt is verified (`ReclaimForwarded` to the payer) is recorded on
+the stream as `reclaimedUsdc`, and cumulative spend counts `budgetUsdc - reclaimedUsdc`
+for it (persisted by the file registry, shown by `list_streams`). A relay-reported amount
+that nothing verified is reported but never credited back. If the close or the reclaim
+does not finish, the tool still succeeds (the payment and the response stand), counts the
+full price, and the text says which `refund` call finishes it. An upfront-only payment has
+nothing to close: `closeAfter.outcome` is `nothing-to-close` and no relay is contacted.
+
 ### `refund_status` / `refund`
 
 Arguments: `streamId`, optional `refundUrl` (not needed for a stream this server

package/docs/x402.md

@@ -652,8 +652,9 @@ chain and before anything is signed — and the caps are also passed to the SDK
 (`X402MandateDeniedError` reason `not-an-opener-quote`).
 
 For an upfront quote the mandate counts the WHOLE price, upfront part included,
-as spend (`budgetUsdc = price`); that part is non-recoverable and nothing a
-refund returns is credited back. Its size is also capped separately before
+as spend (`budgetUsdc = price`); that part is non-recoverable, and a refund is
+credited back only in the one case below (an MCP `closeAfter` reclaim proven by
+its receipt). Its size is also capped separately before
 signing by `maxUpfrontAmount` (`metrik pay --max-upfront`, MCP
 `maxUpfrontAmountUsdc`; default 0.10 USDC, `0` refuses any upfront charge). The
 split is shown before signing and in the result. An upfront-only payment
@@ -665,13 +666,52 @@ non-stream charge that still counts against the mandate.
 ```bash
 metrik pay https://x402.137.23.50.249.sslip.io/transform --json '{"text":"# hi"}' --max-amount 0.1
 metrik refund <streamId> --refund-url <url printed above> --close --reclaim
+
+# one-shot call: close and reclaim in the same run
+metrik pay https://x402.137.23.50.249.sslip.io/transform --json '{"text":"# hi"}' \
+  --max-amount 0.1 --max-upfront 0.02 --close-after
 ```
 
 The MCP server offers the same as `x402_pay`, `refund_status` and `refund`
 (see [mcp-reference.md](./mcp-reference.md)); `x402_pay` shares the server
 mandate and cumulative spend with `hire_verified_service`. Refunds are still
 **requested, never pushed**: `metrik refund` / `refund` call the relay; nothing
-calls it for you.
+calls it for you unless you ask for it.
+
+### Closing right after the response (`--close-after`, `closeAfter`)
+
+The metered part of a payment pays per verified second of the seller's uptime,
+not per call. A one-shot caller that never closes lets the seller earn the whole
+metered part for a single response (testers measured never closing at 4x the
+cost of closing quickly); a caller that closes immediately gets back everything
+unearned. So the buyer can ask for the close up front:
+
+- `metrik pay … --close-after`
+- MCP `x402_pay` with `closeAfter: true`
+- `payX402WithMandate({ …, closeAfter: true | { verifyWith, maxAttempts, maxDelayMs } })`,
+  or `closeAfterPayment(…)` on an existing payment (`@absol-labs/agent/x402-buyer`)
+
+After a successful paid response, the buyer's own client runs exactly what
+`metrik refund --close --reclaim` runs (one shared implementation): the payer
+signs the opener's `Close`, the seller's refund relay sends it and pays the gas,
+the client waits — bounded, honouring the relay's `Retry-After` — for the
+checkpoint covering the close, then asks the relay for the permissionless
+reclaim, which the opener always pays to the payer. This is not an automatic
+refund: it is the buyer's client sending the buyer's close and reclaim, because
+the buyer asked; without the option nothing is sent. The payer still broadcasts
+nothing and needs no gas.
+
+What came back is reported from the verified receipt (`ReclaimForwarded` to the
+payer): the refund, what the seller earned, and what the payment finally cost
+(`price - refund` = the upfront part plus the earned seconds). An upfront-only
+payment has nothing to close (exit 0 / `nothing-to-close`); a request that never
+settled closes nothing. If the close or the reclaim does not finish, the payment
+and the response stand and nothing is lost — the unearned part stays escrowed for
+the payer: `metrik pay` exits `5` and prints the exact `metrik refund …` command
+that finishes it; the MCP tool still succeeds and names the `refund` call; the
+programmatic outcome is `incomplete` with the `stage`. In MCP, a verified reclaim
+is recorded as the stream's `reclaimedUsdc`, so only what the payment kept counts
+against the spend mandate.
 
 The facilitator's `PAYMENT-RESPONSE` `extra.metrikStreamOpener.expiresAt` is a
 JSON **number** (it was a decimal string before metrik-agent#121, which the SDK's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absol-labs/agent",
-  "version": "0.12.0-rc.3",
+  "version": "0.12.0-rc.4",
   "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",

package/src/cli/commands/claim.ts

@@ -68,42 +68,53 @@ export const claimCommand: CommandSpec = {
       );
     }
 
-    const plan = await planClaim(
-      read,
-      streamId,
-      stream,
-      escrowGenerationFor(config.chainId, config.escrow),
-    );
-    if (plan.kind === "nothing") throw plan.error;
-
     const write = deps.createWriteClient(
       config,
       account,
       writeClientOptions(wallet),
     );
-    const action = {
-      streamId,
-      // `null` for a policy-enforced wallet — see `../spend-policy.ts`.
-      signedMandate: isPolicyEnforced(wallet)
-        ? null
-        : await signClaimMandate(account, config.chainId),
-      spentSoFarUsdc: 0n,
-      nowSeconds: deps.nowSeconds(),
-    };
+    const generation = escrowGenerationFor(config.chainId, config.escrow);
+    // The oracle can post (or the escrow retain) a newer checkpoint between
+    // this plan and the transaction, so a proof read moments ago can revert
+    // `InvalidProof`. Nothing was spent on a reverted simulation: re-plan from
+    // fresh chain and proof state and try again, a bounded number of times.
+    let plan: Extract<ClaimPlan, { kind: "claimWithProof" | "claimProven" }>;
     let result: { readonly txHash: `0x${string}` };
-    if (plan.kind === "claimWithProof") {
-      result = await write.claimStream(action);
-    } else {
-      if (write.claimProvenStream === undefined) {
-        throw new CliError(
-          "this write client cannot send claimProven, which is the only way to collect this stream's proven value",
-          {
-            exitCode: 3,
-            hint: "no current checkpoint proof pays it, so a proof claim would revert NothingToClaim",
-          },
-        );
+    for (let attempt = 1; ; attempt += 1) {
+      const planned = await planClaim(read, streamId, stream, generation);
+      if (planned.kind === "nothing") throw planned.error;
+      plan = planned;
+      const action = {
+        streamId,
+        // `null` for a policy-enforced wallet — see `../spend-policy.ts`.
+        signedMandate: isPolicyEnforced(wallet)
+          ? null
+          : await signClaimMandate(account, config.chainId),
+        spentSoFarUsdc: 0n,
+        nowSeconds: deps.nowSeconds(),
+      };
+      try {
+        if (plan.kind === "claimWithProof") {
+          result = await write.claimStream(action);
+        } else {
+          if (write.claimProvenStream === undefined) {
+            throw new CliError(
+              "this write client cannot send claimProven, which is the only way to collect this stream's proven value",
+              {
+                exitCode: 3,
+                hint: "no current checkpoint proof pays it, so a proof claim would revert NothingToClaim",
+              },
+            );
+          }
+          result = await write.claimProvenStream(action);
+        }
+        break;
+      } catch (error) {
+        if (attempt >= CLAIM_REPLAN_ATTEMPTS || !isStaleProofError(error)) {
+          throw error;
+        }
+        await deps.sleep(CLAIM_REPLAN_DELAY_MS);
       }
-      result = await write.claimProvenStream(action);
     }
 
     out.result({
@@ -131,6 +142,21 @@ export const claimCommand: CommandSpec = {
   },
 };
 
+/** How many plan-then-send rounds `metrik claim` makes before giving up. */
+const CLAIM_REPLAN_ATTEMPTS = 3;
+/** Pause between rounds, so a just-posted checkpoint can settle on the RPC. */
+const CLAIM_REPLAN_DELAY_MS = 3_000;
+
+/**
+ * A claim reverted because its proof no longer matches a root the escrow
+ * accepts (a checkpoint rotated, or a lagging node served a not-yet-visible
+ * root). Re-planning reads a fresh proof, so it is worth one more round.
+ */
+export function isStaleProofError(error: unknown): boolean {
+  const text = describeError(error);
+  return /InvalidProof|fresh checkpoint proof/.test(text);
+}
+
 /**
  * Which claim, if any, `metrik claim` would send. Reads only, so it is
  * testable (and checkable against a live stream) without a key.