@absol-labs/agent 0.11.0 → 0.12.0-rc.1

package/src/cli/commands/reclaim.ts

@@ -1,4 +1,9 @@
-import { SettlementWindowOpenError } from "@absol-labs/sdk";
+import {
+  CheckpointNotReadyError,
+  ReclaimFailedError,
+  SettlementWindowOpenError,
+  StreamNotInCheckpointError,
+} from "@absol-labs/sdk";
 
 import { booleanFlag, integerFlag } from "../args.js";
 import { formatUsdc } from "../amounts.js";
@@ -12,6 +17,12 @@ import {
 import { signRecoveryMandate } from "../mandate.js";
 import { assertCanPayGas } from "../preflight.js";
 import { writeClientOptions } from "../deps.js";
+import {
+  describeAwaitingCheckpoint,
+  describeTerminalBlocker,
+  readReclaimBlocker,
+  type ReclaimBlocker,
+} from "../reclaimability.js";
 import { isPolicyEnforced, resolveCliWallet } from "../wallet.js";
 import type { CommandContext, CommandSpec } from "../context.js";
 import type { CliReadClient, CliWriteClient } from "../deps.js";
@@ -20,6 +31,9 @@ import type {
   StreamProofTransactionResult,
 } from "../../sdk/client.js";
 import type { StreamV2 } from "@absol-labs/sdk";
+import { streamEscrowV2Abi } from "@absol-labs/shared";
+import { parseEventLogs, type Log } from "viem";
+import { escrowGenerationFor } from "../../escrow-generation.js";
 
 /**
  * How long to keep retrying a reclaim that is blocked only by an open
@@ -56,7 +70,24 @@ export const reclaimCommand: CommandSpec = {
     const { account } = wallet;
     const read = deps.createReadClient(config);
     await assertTestnetRpc(config, () => read.getChainId());
-    await assertCanPayGas(read, account.address);
+
+    // Name the condition from chain state BEFORE anything is built or spent.
+    // The public endpoint's revert data is not dependable enough to tell
+    // "already reclaimed" from "still running" from "not checkpointed yet", and
+    // those three have nothing in common but the word "reverted". See
+    // `../reclaimability.ts`.
+    const blocker = await readReclaimBlocker(read, streamId, deps.nowSeconds());
+    // `--close-first` exists precisely to clear a running stream, so it is the
+    // one caller allowed past that refusal. Nothing gets past "already
+    // reclaimed": there is no money left to take, with or without a close.
+    if (blocker !== null && !(closeFirst && blocker.kind === "running")) {
+      throwIfTerminal(blocker, streamId);
+      if (blocker.kind === "awaiting-checkpoint") {
+        out.note(describeAwaitingCheckpoint(blocker));
+      }
+    }
+
+    await assertCanPayGas(read, account.address, config.network);
 
     const write = deps.createWriteClient(
       config,
@@ -106,6 +137,19 @@ export const reclaimCommand: CommandSpec = {
             `closed in ${closeResult.txHash} — waiting for it to land …`,
           );
           await awaitClosed(read, streamId, deps.sleep, closeResult.txHash);
+          // A stream closed before any checkpoint covers its stop time is the
+          // ORDINARY outcome of a short trial run, not an exotic one — and it
+          // is the state `--close-first` leaves behind by construction. Say
+          // what is being waited for, so the retries below read as the
+          // advertised wait rather than as a command that has stalled.
+          const afterClose = await readReclaimBlocker(
+            read,
+            streamId,
+            deps.nowSeconds(),
+          );
+          if (afterClose?.kind === "awaiting-checkpoint") {
+            out.note(describeAwaitingCheckpoint(afterClose));
+          }
         }
       }
     }
@@ -122,6 +166,15 @@ export const reclaimCommand: CommandSpec = {
         attempts,
         intervalMs: interval * 1_000,
         sleep: deps.sleep,
+        isRetryable: async (error) =>
+          await isWaitingForCheckpoint(
+            error,
+            read,
+            streamId,
+            deps.nowSeconds(),
+          ),
+        explainFailure: async (error) =>
+          await explainReclaimFailure(error, read, streamId, deps.nowSeconds()),
         onRetry: (attempt, reason) =>
           out.note(
             `reclaim blocked: no checkpoint covers the stream's stop time yet (attempt ${attempt}/${attempts}) — ${reason}`,
@@ -131,18 +184,31 @@ export const reclaimCommand: CommandSpec = {
         // give-up message names the path that needs no proof, and says whether
         // it is open yet.
         exhaustedHint: async () =>
-          await describeLastResort(read, streamId, deps.nowSeconds()),
+          await describeLastResort(
+            read,
+            streamId,
+            deps.nowSeconds(),
+            escrowGenerationFor(config.chainId, config.escrow),
+          ),
       },
     );
 
     // Read the settled figure back only once the node we are reading from has
-    // actually applied the reclaim. `sepolia.base.org` is load-balanced, so an
+    // actually applied the reclaim. The public RPC is load-balanced, so an
     // immediate read can land on a lagged node and report `settledCumulative: 0`
     // for a stream that just settled a non-zero amount — printing "settled to
     // operator 0 USDC" when it was not zero. Poll for `reclaimed` (which the
     // transaction we just landed sets) so the number beside it is from the same
     // post-reclaim state. Bounded, and falls back to the last value read.
     const stream = await readSettledStream(read, streamId, deps.sleep);
+    // The refund comes from the reclaim's own BuyerReclaimed event, never from
+    // a post-reclaim read: reclaim overwrites `deposit` with the operator's
+    // entitlement, so deposit − settled reads 0 after every reclaim.
+    const refunded = refundFromReceipt(
+      result.reclaimResult.receipt,
+      config.escrow,
+      streamId,
+    );
     out.result({
       streamId,
       txHash: result.reclaimResult.txHash,
@@ -152,6 +218,14 @@ export const reclaimCommand: CommandSpec = {
       // asked for".
       closeSkippedAlreadyClosed: closeFirst ? alreadyClosed : null,
       settledCumulative: stream?.settledCumulative ?? null,
+      // What the reclaim sent back: everything not settled to the operator.
+      // Only reported once the read reflects the reclaim, so a lagged node can
+      // never print a refund figure computed from pre-reclaim state.
+      refundedAmount: refunded,
+      // For an x402 stream the refund goes to the opener's payer, whoever sent
+      // the (permissionless) reclaim.
+      opener: stream?.opener ?? null,
+      refundedTo: stream === null ? null : (stream.payer ?? stream.buyer),
     });
     out.print("Reclaimed.");
     out.table([
@@ -166,6 +240,22 @@ export const reclaimCommand: CommandSpec = {
         ? []
         : ([
             ["settled to operator", formatUsdc(stream.settledCumulative)],
+            ...(refunded === null
+              ? []
+              : ([
+                  [
+                    (stream.opener ?? null) === null
+                      ? "returned to buyer"
+                      : "returned to payer",
+                    formatUsdc(refunded),
+                  ],
+                ] as const)),
+            ...((stream.opener ?? null) === null
+              ? []
+              : ([
+                  ["via opener", stream.opener as string],
+                  ["refunded to payer", stream.payer],
+                ] as const)),
           ] as const)),
     ]);
   },
@@ -207,7 +297,7 @@ function isAlreadyClosed(error: unknown): boolean {
  * Block until the node we read from reports the stream as closed.
  *
  * The close transaction's own receipt is awaited inside the SDK, but
- * `sepolia.base.org` is load-balanced: the receipt can come back from one node
+ * the public RPC is load-balanced: the receipt can come back from one node
  * while the very next `simulateContract` lands on another that has not imported
  * the block yet. That node simulates `reclaim` against PRE-close state and
  * reverts `StreamNotReclaimable()`. Confirming the close through the same read
@@ -243,8 +333,16 @@ export async function awaitClosed(
  * time. That is not an error condition — it is the normal ordering of a
  * checkpoint rail, and it happens on the FIRST attempt essentially every time.
  * A CLI that surfaced the raw revert would teach every user that reclaim is
- * broken, so the wait is built in and narrated. Any other failure is rethrown
- * immediately: only an open settlement window is retried.
+ * broken, so the wait is built in and narrated.
+ *
+ * What counts as "wait for the next checkpoint" is decided by `isRetryable`,
+ * NOT by this function. It used to be `instanceof SettlementWindowOpenError`
+ * alone, which missed the two ways the wait actually shows up in practice: the
+ * ORACLE refusing a proof for a stream it has not checkpointed yet (the SDK
+ * fetches the proof before it ever simulates, so the escrow's revert never
+ * happens), and the endpoint returning revert data the ABI cannot decode. Both
+ * killed the advertised retry on its first attempt — the second one right
+ * after `--close-first` had already spent the buyer's close.
  */
 export async function reclaimWithBoundedRetry(
   write: CliWriteClient,
@@ -253,6 +351,10 @@ export async function reclaimWithBoundedRetry(
     readonly attempts: number;
     readonly intervalMs: number;
     readonly sleep: (ms: number) => Promise<void>;
+    /** True when this failure is the checkpoint wait and will clear on its own. */
+    readonly isRetryable: (error: unknown) => Promise<boolean>;
+    /** Turn a failure that will NOT clear into something worth reading. */
+    readonly explainFailure: (error: unknown) => Promise<unknown>;
     readonly onRetry: (attempt: number, reason: string) => void;
     /** What to tell the buyer once the budget is spent. See `describeLastResort`. */
     readonly exhaustedHint?: () => Promise<string>;
@@ -263,7 +365,8 @@ export async function reclaimWithBoundedRetry(
     try {
       return await write.reclaimStream(await buildInput());
     } catch (error) {
-      if (!isSettlementWindowOpen(error)) throw explainReclaimFailure(error);
+      if (!(await options.isRetryable(error)))
+        throw await options.explainFailure(error);
       lastError = error;
       if (attempt === options.attempts) break;
       options.onRetry(attempt, describeError(error));
@@ -299,25 +402,123 @@ async function describeLastResort(
   read: CliReadClient,
   streamId: `0x${string}`,
   fallbackNowSeconds: number,
+  generation: string,
 ): Promise<string> {
   const [stream, grace] = await Promise.all([
     read.getStreamV2(streamId),
     read.escapeGraceSeconds(),
   ]);
   const now = await readChainNow(read, fallbackNowSeconds);
-  const window = escapeHatchWindow(stream, grace, now.seconds);
+  const window = escapeHatchWindow(stream, grace, now.seconds, generation);
   const escapeCommand = `metrik reclaim-unverified ${streamId} --forfeit-unclaimed`;
   return window.ready
     ? `the funds are not lost. The no-proof escape hatch is OPEN (${describeEscapeHatch(window)}): \`${escapeCommand}\` takes them back without the oracle — at the cost of forfeiting whatever the operator earned but has not yet claimed. Retrying this command only helps if the oracle comes back.`
     : `the funds are not lost, but retrying only helps if the oracle comes back — this path needs a proof from it. The no-proof escape hatch ${describeEscapeHatch(window)}; from then on \`${escapeCommand}\` takes them back without the oracle, forfeiting whatever the operator earned but has not yet claimed.`;
 }
 
+/** Raise a blocker that will not clear on its own as a named CliError. */
+function throwIfTerminal(
+  blocker: ReclaimBlocker,
+  streamId: `0x${string}`,
+  cause?: unknown,
+): void {
+  const terminal = describeTerminalBlocker(blocker, streamId);
+  if (terminal === null) return;
+  throw new CliError(terminal.message, {
+    exitCode: 4,
+    hint: terminal.hint,
+    ...(cause === undefined ? {} : { cause }),
+  });
+}
+
+/**
+ * Is this failure the checkpoint wait, i.e. will it clear on its own?
+ *
+ * Three shapes, in increasing order of how little the endpoint told us:
+ *
+ *  1. `SettlementWindowOpenError` — the escrow said so and the ABI decoded it.
+ *  2. `StreamNotInCheckpointError` / `CheckpointNotReadyError` — the ORACLE has
+ *     no proof for this stream yet, so the SDK never reached the escrow at all.
+ *     This is the state `--close-first` creates by construction on a stream
+ *     closed before its first covering checkpoint, and treating it as fatal is
+ *     what stranded a buyer's deposit in escrow for three minutes of manual
+ *     retries while the CLI's own help promised it would wait.
+ *  3. A reclaim revert the ABI could not decode. Nothing in the error names the
+ *     condition, so ask the chain instead — the state is authoritative and the
+ *     answer is the same one the pre-flight computes.
+ *
+ * Case 3 is deliberately narrowed to `ReclaimFailedError`: an unrelated failure
+ * (no gas, a dead RPC) must still fail on its first attempt rather than burn
+ * twelve of them.
+ */
+async function isWaitingForCheckpoint(
+  error: unknown,
+  read: Pick<
+    CliReadClient,
+    "getStreamV2" | "latestCheckpointCheckedAt" | "latestBlockTimestamp"
+  >,
+  streamId: `0x${string}`,
+  nowSeconds: number,
+): Promise<boolean> {
+  if (isSettlementWindowOpen(error)) return true;
+  if (hasNoCheckpointProofYet(error)) return true;
+  if (!isReclaimRevert(error)) return false;
+  const blocker = await readReclaimBlocker(read, streamId, nowSeconds).catch(
+    () => null,
+  );
+  return blocker?.kind === "awaiting-checkpoint";
+}
+
 /**
- * `StreamNotReclaimable()` means exactly one thing: the stream is neither closed
- * nor past its expiry. Say that, and say which command fixes it, instead of
- * handing the reader a selector.
+ * The oracle could not supply a proof yet: it has no leaf for this stream in
+ * the latest checkpoint (404), or no internally consistent checkpoint is ready
+ * (503). Both resolve when the next checkpoint lands, ~15-22s apart.
  */
-function explainReclaimFailure(error: unknown): unknown {
+function hasNoCheckpointProofYet(error: unknown): boolean {
+  for (let current: unknown = error, depth = 0; depth < 8; depth++) {
+    if (
+      current instanceof StreamNotInCheckpointError ||
+      current instanceof CheckpointNotReadyError
+    ) {
+      return true;
+    }
+    if (!(current instanceof Error) || current.cause === undefined)
+      return false;
+    current = current.cause;
+  }
+  return false;
+}
+
+/** True when the escrow rejected the reclaim, whatever the reason decoded to. */
+function isReclaimRevert(error: unknown): boolean {
+  for (let current: unknown = error, depth = 0; depth < 8; depth++) {
+    if (current instanceof ReclaimFailedError) return true;
+    if (!(current instanceof Error) || current.cause === undefined)
+      return false;
+    current = current.cause;
+  }
+  return false;
+}
+
+/**
+ * Name a failure that will not clear.
+ *
+ * `StreamNotReclaimable()` means exactly one thing when the ABI decodes it: the
+ * stream is neither closed nor past its expiry. When it does NOT decode — the
+ * live failure mode on the public endpoint — the chain is asked the same
+ * question, so "already reclaimed" and "still running" are still told apart and
+ * still say which command fixes them. The raw error is kept as the `cause`
+ * either way.
+ */
+async function explainReclaimFailure(
+  error: unknown,
+  read: Pick<
+    CliReadClient,
+    "getStreamV2" | "latestCheckpointCheckedAt" | "latestBlockTimestamp"
+  >,
+  streamId: `0x${string}`,
+  nowSeconds: number,
+): Promise<unknown> {
   if (!(error instanceof Error)) return error;
   for (let current: unknown = error, depth = 0; depth < 8; depth++) {
     if (!(current instanceof Error)) break;
@@ -326,7 +527,7 @@ function explainReclaimFailure(error: unknown): unknown {
         "the stream is still running, so there is nothing to reclaim yet",
         {
           exitCode: 4,
-          hint: "stop the clock first — `metrik close <streamId>`, or re-run this command with --close-first — or wait for the stream to expire.",
+          hint: `stop the clock first — \`metrik close ${streamId}\`, or re-run this command with --close-first — or wait for the stream to expire.`,
           cause: error,
         },
       );
@@ -334,6 +535,18 @@ function explainReclaimFailure(error: unknown): unknown {
     if (current.cause === undefined) break;
     current = current.cause;
   }
+  if (isReclaimRevert(error)) {
+    const blocker = await readReclaimBlocker(read, streamId, nowSeconds).catch(
+      () => null,
+    );
+    if (blocker !== null) {
+      try {
+        throwIfTerminal(blocker, streamId, error);
+      } catch (named) {
+        return named;
+      }
+    }
+  }
   return error;
 }
 
@@ -359,6 +572,31 @@ const SETTLED_READ_ATTEMPTS = 5;
 // `--interval`), so the two waits are tellable apart in tests and in logs.
 const SETTLED_READ_INTERVAL_MS = 500;
 
+/**
+ * The amount the reclaim returned, decoded from its BuyerReclaimed event (same
+ * signature on V2 and V3). Null when the receipt carries no matching log, so
+ * the CLI prints nothing rather than a guessed figure.
+ */
+export function refundFromReceipt(
+  receipt: { logs?: readonly Log[] } | undefined,
+  escrow: string,
+  streamId: `0x${string}`,
+): bigint | null {
+  const logs = receipt?.logs;
+  if (!Array.isArray(logs)) return null;
+  const events = parseEventLogs({
+    abi: streamEscrowV2Abi,
+    eventName: "BuyerReclaimed",
+    logs: logs.filter(
+      (log) => log.address?.toLowerCase() === escrow.toLowerCase(),
+    ),
+  });
+  const match = events.find(
+    (event) => event.args.streamId.toLowerCase() === streamId.toLowerCase(),
+  );
+  return match === undefined ? null : match.args.amount;
+}
+
 async function readSettledStream(
   read: { getStreamV2(streamId: `0x${string}`): Promise<StreamV2> },
   streamId: `0x${string}`,

package/src/cli/commands/refund.ts

@@ -0,0 +1,277 @@
+import type {
+  RefundClient,
+  RefundRelayResult,
+  RefundStatus,
+  X402PayerSigner,
+} from "@absol-labs/sdk/x402";
+
+import { verifyMandateOwnerSignature } from "../../mandates/mandate.js";
+import { booleanFlag, integerFlag, stringFlag } from "../args.js";
+import { formatUsdc } from "../amounts.js";
+import { assertTestnetRpc, parseBytes32 } from "../config.js";
+import type { CliX402 } from "../deps.js";
+import { CliError, configError, usageError } from "../errors.js";
+import { signRecoveryMandate } from "../mandate.js";
+import { isPrivyWalletSource, resolveCliWallet } from "../wallet.js";
+import type { CommandContext, CommandSpec } from "../context.js";
+
+/** Environment fallback for `--refund-url`. */
+export const REFUND_URL_ENV = "METRIK_AGENT_REFUND_URL";
+
+const DEFAULT_ATTEMPTS = 5;
+const DEFAULT_MAX_WAIT_SECONDS = 60;
+
+export const refundCommand: CommandSpec = {
+  name: "refund",
+  summary:
+    "Recover the unearned part of an x402 payment through the gasless refund relay",
+  usage:
+    "metrik refund <streamId> --refund-url <url> [--close] [--reclaim] [--attempts 5] [--max-wait 60]",
+  flags: ["refund-url", "close", "reclaim", "attempts", "max-wait"],
+  // `--close` signs the payer's EIP-712 Close (off-chain); the RELAY broadcasts
+  // and pays the gas. `--reclaim` needs no wallet at all: `opener.reclaim` is
+  // permissionless and always pays `payerOf(streamId)`.
+  signs: false,
+  requiresKey: false,
+  async run(context: CommandContext): Promise<void> {
+    const { args, config, env, out, deps } = context;
+    if (deps.x402 === undefined) {
+      throw new CliError(
+        "this CLI build has no x402 dependency wired (CliDependencies.x402)",
+        { exitCode: 4 },
+      );
+    }
+    const x402: CliX402 = deps.x402;
+    const [streamIdArg] = args.positionals;
+    if (streamIdArg === undefined) {
+      throw usageError("metrik refund requires a <streamId>");
+    }
+    const streamId = parseBytes32(streamIdArg, "<streamId>");
+    const refundUrl = resolveRefundUrl(
+      stringFlag(args, "refund-url") ?? env[REFUND_URL_ENV],
+      streamId,
+    );
+    const doClose = booleanFlag(args, "close");
+    const doReclaim = booleanFlag(args, "reclaim");
+    const attempts = integerFlag(args, "attempts") ?? DEFAULT_ATTEMPTS;
+    const maxWait = integerFlag(args, "max-wait") ?? DEFAULT_MAX_WAIT_SECONDS;
+    if (attempts < 1) throw usageError("--attempts must be at least 1");
+
+    const read = deps.createReadClient(config);
+    await assertTestnetRpc(config, () => read.getChainId());
+    // Bind the relay to the stream AS THE CHAIN SEES IT: the opener comes from
+    // `factory.isOpener(buyer)` on-chain, never from the relay's answer.
+    const stream = await read.getStreamV2(streamId);
+    const opener = stream.opener ?? null;
+    if (opener === null) {
+      throw configError(
+        `stream ${streamId} was not opened by an x402 opener, so the refund relay does not serve it`,
+        `the buyer is ${stream.buyer}, an ordinary wallet: use \`metrik close ${streamId}\` and \`metrik reclaim ${streamId}\` with that wallet.`,
+      );
+    }
+
+    const refunds = await x402.refundClient(config, {
+      refundUrl,
+      streamId,
+      opener,
+      maxAttempts: attempts,
+      maxDelayMs: maxWait * 1_000,
+    });
+
+    let closeResult: RefundRelayResult | null = null;
+    if (doClose) {
+      const wallet = await resolveCliWallet(env, {
+        purpose: "capability",
+        note: out.note,
+        rpcUrl: config.rpcUrl,
+      });
+      if (isPrivyWalletSource(wallet.source)) {
+        throw configError(
+          "metrik refund --close cannot sign with a Privy wallet",
+          "the payer signs the opener's EIP-712 Close, which the Privy broker's typed-data policy does not allow. Use the key that paid.",
+        );
+      }
+      // Buyer recovery: authorized on the mandate OWNER's signature alone, like
+      // `metrik close` — never on caps or expiry, so nothing can strand the
+      // payer's own money. The SDK then refuses a signer that is not
+      // `payerOf(streamId)` before anything is signed for the relay.
+      const mandate = await signRecoveryMandate(wallet.account, config.chainId);
+      const decision = await verifyMandateOwnerSignature(mandate);
+      if (!decision.allowed) {
+        throw new CliError(`mandate denied: ${decision.reason}`, {
+          exitCode: 3,
+        });
+      }
+      closeResult = await relay(() =>
+        refunds.close({
+          signer: wallet.account as unknown as X402PayerSigner,
+        }),
+      );
+      out.note(
+        `close relayed in ${closeResult.transaction}${closeResult.verified ? " (receipt verified on-chain)" : ""}`,
+      );
+    }
+
+    let reclaimResult: RefundRelayResult | null = null;
+    if (doReclaim) {
+      reclaimResult = await relay(() => refunds.reclaim());
+    }
+
+    const status = await relay(() => refunds.status());
+    out.result({
+      streamId,
+      opener,
+      payer: status.payer,
+      status: status.status,
+      reclaimed: status.reclaimed,
+      reclaimable: status.reclaimable,
+      next: status.next,
+      close:
+        closeResult === null
+          ? null
+          : {
+              transaction: closeResult.transaction,
+              verified: closeResult.verified,
+            },
+      reclaim:
+        reclaimResult === null
+          ? null
+          : {
+              transaction: reclaimResult.transaction,
+              amount: reclaimResult.amount,
+              verified: reclaimResult.verified,
+            },
+      refundIsAutomatic: false,
+    });
+    out.print(`x402 stream ${streamId}`);
+    out.table(statusRows(status, closeResult, reclaimResult));
+    out.print("");
+    out.print(nextStep(status, streamId, refundUrl));
+  },
+};
+
+/**
+ * Accepts the relay's full stream URL, a `{streamId}` template, or the relay's
+ * base origin (`https://relay.example` -> `https://relay.example/streams/<id>`).
+ */
+export function resolveRefundUrl(
+  raw: string | undefined,
+  streamId: `0x${string}`,
+): string {
+  if (raw === undefined || raw.trim().length === 0) {
+    throw usageError(
+      `metrik refund needs the seller's refund relay: pass --refund-url (printed by \`metrik pay\`) or set ${REFUND_URL_ENV}`,
+    );
+  }
+  const value = raw.trim();
+  if (value.includes("{streamId}")) return value;
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw usageError(
+      `--refund-url must be an absolute http(s) URL (got "${value}")`,
+    );
+  }
+  if (/\/streams\/0x[0-9a-fA-F]{64}\/?$/.test(url.pathname)) return value;
+  url.pathname = `${url.pathname.replace(/\/+$/, "")}/streams/${streamId}`;
+  return url.toString();
+}
+
+async function relay<T>(task: () => Promise<T>): Promise<T> {
+  try {
+    return await task();
+  } catch (error) {
+    throw explainRefundFailure(error);
+  }
+}
+
+export function explainRefundFailure(error: unknown): unknown {
+  if (!(error instanceof Error)) return error;
+  switch (error.name) {
+    case "RefundNotReadyError": {
+      const retryAt = (error as { retryAt?: number | null }).retryAt;
+      return new CliError(error.message, {
+        exitCode: 3,
+        hint:
+          retryAt === undefined || retryAt === null
+            ? "the relay is not ready to reclaim yet (the settlement window is open). Re-run later with --reclaim."
+            : `the relay can reclaim from ${new Date(retryAt * 1000).toISOString()}. Re-run then with --reclaim (or raise --max-wait to wait here).`,
+        cause: error,
+      });
+    }
+    case "RefundRelayError":
+      return new CliError(error.message, {
+        exitCode: 3,
+        hint: `relay refusal${(error as { code?: string }).code === undefined ? "" : ` (${(error as { code?: string }).code})`}. The payer can always recover on-chain without the relay: \`metrik close\` (as the payer, needs gas) and \`metrik reclaim\` (anyone).`,
+        cause: error,
+      });
+    case "NotStreamPayerError":
+      return new CliError(error.message, {
+        exitCode: 3,
+        hint: "only the address that paid (payerOf(streamId)) can sign the close. Nothing was signed.",
+        cause: error,
+      });
+    default:
+      return error;
+  }
+}
+
+function statusRows(
+  status: RefundStatus,
+  closeResult: RefundRelayResult | null,
+  reclaimResult: RefundRelayResult | null,
+): (readonly [string, string])[] {
+  const rows: (readonly [string, string])[] = [
+    [
+      "status",
+      status.reclaimed ? `${status.status} (reclaimed)` : status.status,
+    ],
+    ["payer", status.payer],
+    ["opener", status.opener],
+    [
+      "reclaimable",
+      status.reclaimable === null ? "-" : formatUsdc(status.reclaimable),
+    ],
+    ["next", status.next.action],
+  ];
+  if (closeResult !== null) {
+    rows.push([
+      "close tx",
+      `${closeResult.transaction}${closeResult.verified ? " (verified)" : " (relay-reported)"}`,
+    ]);
+  }
+  if (reclaimResult !== null) {
+    rows.push([
+      "reclaim tx",
+      `${reclaimResult.transaction}${reclaimResult.verified ? " (verified)" : " (relay-reported)"}`,
+    ]);
+    if (reclaimResult.amount !== null) {
+      rows.push(["refunded to payer", formatUsdc(reclaimResult.amount)]);
+    }
+  }
+  return rows;
+}
+
+function nextStep(
+  status: RefundStatus,
+  streamId: `0x${string}`,
+  refundUrl: string,
+): string {
+  if (status.reclaimed) {
+    return "Reclaimed: the unearned remainder was returned to the payer.";
+  }
+  const base = `metrik refund ${streamId} --refund-url ${refundUrl}`;
+  switch (status.next.action) {
+    case "close":
+      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`;
+    case "wait":
+      return `Refunds are NOT automatic, and the settlement window is still open${status.next.retryAt === undefined ? "" : ` until ${new Date(status.next.retryAt * 1000).toISOString()}`}. Then run  ${base} --reclaim`;
+    default:
+      return `Refunds are NOT automatic. The relay says: ${status.next.message ?? status.next.action}.`;
+  }
+}
+
+export type { RefundClient };