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

package/src/cli/status.ts

@@ -75,6 +75,155 @@ export function settlementCoverage(
   };
 }
 
+/**
+ * How much of the operator's verified, unclaimed accrual the buyer's no-proof
+ * escape hatch (`reclaimUnverified`) could take. All amounts are GROSS
+ * cumulative USDC base units (before the protocol fee), the unit the escrow
+ * settles in; the operator receives a claimed amount net of the fee.
+ *
+ * The rule depends on the escrow's generation:
+ *
+ * - **V2**: the hatch settles the operator at `claimedCumulative`, so every
+ *   verified-but-unclaimed unit is exposed.
+ * - **V3**: the hatch settles the operator at
+ *   `max(claimedCumulative, provenCumulative)` — the on-chain proven high-water
+ *   the oracle's `recordProven` keeper (or any claim / reclaim with a proof)
+ *   writes, and which the operator can redeem with `claimProven`. Only verified
+ *   value NOBODY has proven on-chain is exposed.
+ */
+export interface OperatorHatchExposure {
+  /** Verified cumulative from the oracle proof, capped at the deposit (gross). */
+  readonly verifiedCumulative: bigint;
+  /** What the hatch would still settle to the operator (gross). */
+  readonly protectedCumulative: bigint;
+  /** `max(0, verifiedCumulative − protectedCumulative)` (gross). */
+  readonly atRiskCumulative: bigint;
+  /**
+   * V3 only: whether `provenCumulative` was read. `false` means it was assumed
+   * to be zero (worst case for the operator), never assumed to be protective.
+   * Always `true` on V2, which has no such view.
+   */
+  readonly provenCumulativeKnown: boolean;
+}
+
+/**
+ * The exposure for a stream that has NOT been reclaimed and has a verified
+ * proof. Pure, so the per-generation rule is testable without an RPC. Returns
+ * `null` when there is nothing to reason about (no proof, or already reclaimed:
+ * a reclaimed stream has no hatch left to open).
+ */
+export function operatorHatchExposure(
+  stream: Pick<StreamV2, "deposit" | "claimedCumulative" | "reclaimed">,
+  verifiedCumulative: bigint | null,
+  generation: string,
+  provenCumulative: bigint | null,
+): OperatorHatchExposure | null {
+  if (stream.reclaimed || verifiedCumulative === null) return null;
+  const verified =
+    verifiedCumulative > stream.deposit ? stream.deposit : verifiedCumulative;
+  let protectedCumulative = stream.claimedCumulative;
+  let provenCumulativeKnown = true;
+  if (generation === "v3") {
+    if (provenCumulative === null) {
+      provenCumulativeKnown = false;
+    } else if (provenCumulative > protectedCumulative) {
+      protectedCumulative = provenCumulative;
+    }
+  }
+  const atRiskCumulative =
+    verified > protectedCumulative ? verified - protectedCumulative : 0n;
+  return {
+    verifiedCumulative: verified,
+    protectedCumulative,
+    atRiskCumulative,
+    provenCumulativeKnown,
+  };
+}
+
+/**
+ * A stream whose buyer side is over, read from chain state. All amounts gross.
+ *
+ * Two ways to get here:
+ *
+ * - `reclaimed`: the buyer reclaimed. Read from the stream tuple, which reclaim
+ *   WRITES, unlike during the stream's active life. The buyer's refund is
+ *   deliberately absent: reclaim overwrites `deposit` with the operator's
+ *   entitlement, so `deposit − settled` is NOT the refund, and the true figure
+ *   lives only in the reclaim's `BuyerReclaimed` event, which this screen does
+ *   not scan for (the reclaim block is unknown, so the lookup is not bounded).
+ * - `deposit-exhausted`: the stream has stopped (closed, or past expiry) and the
+ *   operator's floor already covers the whole deposit, so there is nothing to
+ *   reclaim and the buyer never will. Both buyer exits settle the operator at no
+ *   less than `max(claimedCumulative, provenCumulative)` (V2:
+ *   `claimedCumulative`) and revert `NothingToReclaim` when `deposit − floor` is
+ *   zero, so `reclaimed` stays `false` forever on such a stream.
+ */
+export interface FinalSettlement {
+  readonly finishedBy: "reclaimed" | "deposit-exhausted";
+  /**
+   * The operator's entitlement: `settledCumulative` (fixed at reclaim), or the
+   * whole `deposit` when it was exhausted.
+   */
+  readonly settledToOperator: bigint;
+  /** `claimedCumulative`: what the operator has redeemed so far. */
+  readonly operatorClaimed: bigint;
+  /** `settledToOperator − operatorClaimed`, still escrowed for the operator. */
+  readonly operatorUnclaimed: bigint;
+}
+
+/**
+ * Whether the buyer side of a stream is finished, and what the operator holds.
+ * Pure, so the rule is testable without an RPC.
+ *
+ * `stopped` is the escrow's own reclaim gate (closed, or `now >= expiresAt`).
+ * `provenCumulative` counts only on V3, and only when it was READ: an
+ * unreadable high-water is treated as zero, so it can never make a stream look
+ * finished that is not.
+ */
+export function finalSettlement(
+  stream: Pick<
+    StreamV2,
+    "reclaimed" | "settledCumulative" | "claimedCumulative" | "deposit"
+  >,
+  exhaustion?: {
+    readonly stopped: boolean;
+    readonly generation: string;
+    readonly provenCumulative: bigint | null;
+  },
+): FinalSettlement | null {
+  if (stream.reclaimed) {
+    return settled("reclaimed", stream.settledCumulative, stream);
+  }
+  if (exhaustion === undefined || !exhaustion.stopped) return null;
+  if (stream.deposit <= 0n) return null;
+  let operatorFloor = stream.claimedCumulative;
+  if (
+    exhaustion.generation === "v3" &&
+    exhaustion.provenCumulative !== null &&
+    exhaustion.provenCumulative > operatorFloor
+  ) {
+    operatorFloor = exhaustion.provenCumulative;
+  }
+  if (operatorFloor < stream.deposit) return null;
+  return settled("deposit-exhausted", stream.deposit, stream);
+}
+
+function settled(
+  finishedBy: FinalSettlement["finishedBy"],
+  settledToOperator: bigint,
+  stream: Pick<StreamV2, "claimedCumulative">,
+): FinalSettlement {
+  return {
+    finishedBy,
+    settledToOperator,
+    operatorClaimed: stream.claimedCumulative,
+    operatorUnclaimed:
+      settledToOperator > stream.claimedCumulative
+        ? settledToOperator - stream.claimedCumulative
+        : 0n,
+  };
+}
+
 /**
  * A stream as the CLI reports it.
  *
@@ -92,6 +241,12 @@ export interface StreamReport {
   /** Why there is no proof yet, when applicable. */
   readonly proofUnavailable: string | null;
   readonly claimable: bigint | null;
+  /**
+   * What {@link claimable} was computed against: the oracle's current proof,
+   * or — V3, when the latest checkpoint no longer contains the stream — the
+   * on-chain proven high-water, which `claimProven` redeems without a proof.
+   */
+  readonly claimableSource: "checkpoint-proof" | "proven-on-chain" | null;
   readonly reclaimable: bigint | null;
   readonly protocolFeeBps: number | null;
   /**
@@ -120,6 +275,22 @@ export interface StreamReport {
    * "no overlap".
    */
   readonly attesters: AttesterSet;
+  /** The escrow generation this report was read against (`v2` / `v3`). */
+  readonly escrowGeneration: string;
+  /**
+   * V3 only: the on-chain proven high-water (`provenCumulativeOf`). `null` on
+   * V2, or when the read failed — see {@link provenUnavailable}.
+   */
+  readonly provenCumulative: bigint | null;
+  /** Why a V3 proven high-water could not be read, when applicable. */
+  readonly provenUnavailable: string | null;
+  /** See {@link operatorHatchExposure}. `null` when not applicable. */
+  readonly operatorExposure: OperatorHatchExposure | null;
+  /**
+   * See {@link finalSettlement}. Non-null exactly when the buyer side is over:
+   * reclaimed, or stopped with the whole deposit already the operator's.
+   */
+  readonly finalSettlement: FinalSettlement | null;
 }
 
 export async function readStreamReport(
@@ -144,13 +315,38 @@ export async function readStreamReport(
     proofUnavailable = describeError(error);
   }
 
+  let provenCumulative: bigint | null = null;
+  let provenUnavailable: string | null = null;
+  if (escrowGeneration === "v3") {
+    if (read.provenCumulativeOf === undefined) {
+      provenUnavailable = "this read client cannot read provenCumulativeOf";
+    } else {
+      try {
+        provenCumulative = await read.provenCumulativeOf(streamId);
+      } catch (error) {
+        provenUnavailable = describeError(error);
+      }
+    }
+  }
+
   let claimable: bigint | null = null;
+  let claimableSource: StreamReport["claimableSource"] = null;
   let reclaimable: bigint | null = null;
   if (proof !== null) {
     [claimable, reclaimable] = await Promise.all([
       read.claimableForV2(streamId, proof.cumulativeAmount),
       read.reclaimableForV2(streamId, proof.cumulativeAmount),
     ]);
+    claimableSource = "checkpoint-proof";
+  } else if (
+    provenCumulative !== null &&
+    provenCumulative > stream.claimedCumulative
+  ) {
+    // The latest checkpoint no longer lists the stream, but a value proven
+    // against a signed root is recorded on-chain. `claimableFor` at that value
+    // is exactly what `claimProven` pays (same `_payableCumulative` and fee).
+    claimable = await read.claimableForV2(streamId, provenCumulative);
+    claimableSource = "proven-on-chain";
   }
 
   let protocolFeeBps: number | null = null;
@@ -179,11 +375,19 @@ export async function readStreamReport(
     latestCheckpointCheckedAt = null;
   }
 
-  const settlement = settlementCoverage(
+  const coverage = settlementCoverage(
     stream,
     latestCheckpointCheckedAt,
     now.seconds,
   );
+  const final = finalSettlement(stream, {
+    stopped: coverage.stopAt !== null,
+    generation: escrowGeneration,
+    provenCumulative,
+  });
+  // A finished stream is settled: there is no checkpoint left to wait for.
+  const settlement: SettlementCoverage =
+    final !== null ? { ...coverage, pending: false } : coverage;
   const attesters = await readAttesterSet(read);
 
   return {
@@ -192,6 +396,7 @@ export async function readStreamReport(
     proof,
     proofUnavailable,
     claimable,
+    claimableSource,
     reclaimable,
     protocolFeeBps,
     escapeHatch,
@@ -200,6 +405,20 @@ export async function readStreamReport(
     clockSource: now.source,
     settlement,
     attesters,
+    escrowGeneration,
+    provenCumulative,
+    provenUnavailable,
+    // A finished stream has no hatch left that could take anything.
+    operatorExposure:
+      final !== null
+        ? null
+        : operatorHatchExposure(
+            stream,
+            proof === null ? null : proof.cumulativeAmount,
+            escrowGeneration,
+            provenCumulative,
+          ),
+    finalSettlement: final,
   };
 }
 
@@ -242,8 +461,21 @@ export function streamReportJson(report: StreamReport): unknown {
     // settled-looking number derived from a checkpoint that predates the
     // stream's stop time. The superseded figure is still available, explicitly
     // labelled, under `settlement.provisionalReclaimable`.
-    claimable: report.claimable,
-    reclaimable: report.settlement.pending ? null : report.reclaimable,
+    // A finished stream with nothing left for the operator has nothing
+    // claimable, even when no proof was fetched.
+    claimable:
+      report.claimable ??
+      (report.finalSettlement?.operatorUnclaimed === 0n ? 0n : null),
+    // `checkpoint-proof`, `proven-on-chain` (V3: what `claimProven` pays), or
+    // `null` when `claimable` is.
+    claimableSource: report.claimableSource,
+    // Nothing is reclaimable from a stream whose buyer side is finished.
+    reclaimable:
+      report.finalSettlement !== null
+        ? 0n
+        : report.settlement.pending
+          ? null
+          : report.reclaimable,
     settlement: {
       pending: report.settlement.pending,
       stopAt: report.settlement.stopAt,
@@ -271,6 +503,39 @@ export function streamReportJson(report: StreamReport): unknown {
             ready: report.escapeHatch.ready,
             secondsUntilReady: report.escapeHatch.secondsRemaining,
           },
+    escrowGeneration: report.escrowGeneration,
+    // V3 only; `null` on V2 or when unreadable (`provenCumulativeUnavailable`).
+    provenCumulative: report.provenCumulative,
+    provenCumulativeUnavailable: report.provenUnavailable,
+    // True once nothing more is owed to, or can be reclaimed by, the buyer —
+    // reclaimed, or stopped with the whole deposit already the operator's —
+    // and the escape hatch no longer applies.
+    buyerSideFinished: report.finalSettlement !== null,
+    // Non-null exactly when `buyerSideFinished`. Gross base units. The buyer's
+    // refund is not included: see `FinalSettlement`.
+    finalSettlement:
+      report.finalSettlement === null
+        ? null
+        : {
+            finishedBy: report.finalSettlement.finishedBy,
+            settledToOperator: report.finalSettlement.settledToOperator,
+            operatorClaimed: report.finalSettlement.operatorClaimed,
+            operatorUnclaimed: report.finalSettlement.operatorUnclaimed,
+          },
+    // What the buyer's no-proof escape hatch could take from the operator.
+    // `null` once reclaimed or before any proof. Gross base units.
+    operatorHatchExposure:
+      report.operatorExposure === null
+        ? null
+        : {
+            units: "gross",
+            verifiedCumulative: report.operatorExposure.verifiedCumulative,
+            protectedCumulative: report.operatorExposure.protectedCumulative,
+            atRiskCumulative: report.operatorExposure.atRiskCumulative,
+            protectedOnChain: report.operatorExposure.atRiskCumulative === 0n,
+            provenCumulativeKnown:
+              report.operatorExposure.provenCumulativeKnown,
+          },
   };
 }
 
@@ -279,10 +544,7 @@ export function streamReportRows(
 ): (readonly [string, string])[] {
   const { stream, proof } = report;
   const rows: (readonly [string, string])[] = [
-    [
-      "status",
-      stream.reclaimed ? `${stream.status} (reclaimed)` : stream.status,
-    ],
+    ["status", describeStatus(report)],
     ...(stream.opener === null || stream.opener === undefined
       ? ([["buyer", stream.buyer]] as const)
       : ([
@@ -291,7 +553,15 @@ export function streamReportRows(
         ] as const)),
     ["operator", stream.operator],
     ["serviceRef", stream.serviceRef],
-    ["deposit", formatUsdc(stream.deposit)],
+    // Reclaim OVERWRITES `deposit` with the operator's entitlement, so after a
+    // reclaim the field is what is still escrowed for the operator — not what
+    // the buyer put in. Printing it bare would read as "the buyer deposited 0".
+    [
+      "deposit",
+      stream.reclaimed
+        ? `${formatUsdc(stream.deposit)} still escrowed for the operator (reclaim replaces the original deposit with the operator's entitlement)`
+        : formatUsdc(stream.deposit),
+    ],
     ["rate", `${formatUsdc(stream.ratePerSecond)} / second`],
     ["opened", formatTimestamp(stream.openedAt)],
     ["expires", describeDeadline(stream.expiresAt, report.nowSeconds)],
@@ -299,12 +569,12 @@ export function streamReportRows(
   if (stream.closedAt > 0) {
     rows.push(["closed", formatTimestamp(stream.closedAt)]);
   }
-  rows.push([
-    "verified accrual",
-    proof === null
-      ? `not checkpointed yet (${report.proofUnavailable ?? "no proof"})`
-      : `${formatUsdc(proof.cumulativeAmount)} @ checkpoint ${proof.checkpointId} (${formatTimestamp(Number(proof.checkedAt))})`,
-  ]);
+  if (report.finalSettlement !== null) {
+    rows.push(...finalSettlementRows(report, report.finalSettlement));
+    pushTrailingRows(rows, report);
+    return rows;
+  }
+  rows.push(["verified accrual", describeVerifiedAccrual(report)]);
   // `claim` accepts ANY retained root, so the operator's balance is obtainable
   // now — it is merely not FINAL until the covering checkpoint lands, and it
   // can only grow. `reclaim` requires the LATEST root to reach the stop time,
@@ -314,9 +584,11 @@ export function streamReportRows(
     "operator claimable",
     report.claimable === null
       ? "-"
-      : report.settlement.pending
-        ? `${formatUsdc(report.claimable)} so far — not final until the checkpoint covering the stop time lands`
-        : formatUsdc(report.claimable),
+      : report.claimableSource === "proven-on-chain"
+        ? `${formatUsdc(report.claimable)} (net of the protocol fee) — from the on-chain proven high-water; \`metrik claim\` redeems it with claimProven, no fresh proof needed`
+        : report.settlement.pending
+          ? `${formatUsdc(report.claimable)} so far (net of the protocol fee) — not final until the checkpoint covering the stop time lands`
+          : `${formatUsdc(report.claimable)} (net of the protocol fee)`,
   ]);
   rows.push([
     "buyer reclaimable",
@@ -326,48 +598,173 @@ export function streamReportRows(
         ? "-"
         : formatUsdc(report.reclaimable),
   ]);
+  if (report.escrowGeneration === "v3") {
+    rows.push([
+      "proven on-chain",
+      report.provenCumulative === null
+        ? `unknown (${report.provenUnavailable ?? "not read"})`
+        : `${formatUsdc(report.provenCumulative)} gross (the escrow's proven high-water; the escape hatch cannot take it)`,
+    ]);
+  }
   rows.push(["fees paid", formatUsdc(stream.feesPaid)]);
-  rows.push([
-    "oracle checkpoint",
-    report.latestCheckpointCheckedAt === null
-      ? "-"
-      : report.latestCheckpointCheckedAt <= 0
-        ? "none posted yet"
-        : `latest covers up to ${formatTimestamp(report.latestCheckpointCheckedAt)}`,
-  ]);
-  // The no-proof path. Printed for every stream, not only blocked ones: a buyer
-  // should learn that this exists before they need it.
+  rows.push(oracleCheckpointRow(report));
+  // The no-proof path. Printed for every live stream, not only blocked ones: a
+  // buyer should learn that this exists before they need it.
   rows.push([
     "escape hatch",
     report.escapeHatch === null
       ? "-"
-      : `${describeEscapeHatch(report.escapeHatch)} — no-proof reclaim, forfeits the operator's unclaimed earnings`,
+      : `${describeEscapeHatch(report.escapeHatch)} — ${
+          report.escrowGeneration === "v3"
+            ? "no-proof reclaim, refunds only value not proven on-chain; the operator keeps max(claimed, proven high-water)"
+            : "no-proof reclaim, forfeits the operator's unclaimed earnings"
+        }`,
   ]);
-  // The same row, read from the seller's side. `reclaimUnverified` pays the
-  // buyer the WHOLE remaining deposit with no proof, so an operator who has
-  // earned but not claimed loses it the moment that window opens. The window is
-  // `expiresAt + escapeGraceSeconds` and the grace is immutable on the live
-  // escrow, so the only thing an operator can do about it is claim in time —
-  // which they cannot do if nothing tells them the deadline exists.
-  if (
-    report.escapeHatch !== null &&
-    report.claimable !== null &&
-    report.claimable > 0n
-  ) {
-    rows.push([
+  const operatorRow = operatorExposureRow(report);
+  if (operatorRow !== null) rows.push(operatorRow);
+  pushTrailingRows(rows, report);
+  return rows;
+}
+
+/**
+ * The same escape-hatch row, read from the seller's side.
+ *
+ * V2: `reclaimUnverified` settles the operator at `claimedCumulative`, so an
+ * operator who has earned but not claimed loses all of it the moment the
+ * window opens. The window is fixed and the grace immutable, so the only thing
+ * an operator can do about it is claim in time — which they cannot do if
+ * nothing tells them the deadline exists.
+ *
+ * V3: the hatch settles the operator at `max(claimed, provenCumulative)`, so
+ * only verified value nobody proved on-chain is exposed. Warning about the
+ * WHOLE unclaimed balance there would be false — and would push an operator to
+ * spend gas racing a deadline that cannot hurt them.
+ */
+function operatorExposureRow(
+  report: StreamReport,
+): readonly [string, string] | null {
+  const hatch = report.escapeHatch;
+  if (hatch === null || report.claimable === null || report.claimable <= 0n) {
+    return null;
+  }
+  if (report.escrowGeneration !== "v3") {
+    return [
       "operator deadline",
-      report.escapeHatch.ready
+      hatch.ready
         ? `${formatUsdc(report.claimable)} is unclaimed and the buyer's no-proof reclaim is ALREADY open — it would take this amount from the operator`
-        : `${formatUsdc(report.claimable)} is unclaimed; \`metrik claim\` it before ${formatTimestamp(report.escapeHatch.readyAt)}, after which a buyer's no-proof reclaim can take it`,
+        : `${formatUsdc(report.claimable)} is unclaimed; \`metrik claim\` it before ${formatTimestamp(hatch.readyAt)}, after which a buyer's no-proof reclaim can take it`,
+    ];
+  }
+  const exposure = report.operatorExposure;
+  if (exposure === null) return null;
+  const units = `(gross: before the protocol fee; \`metrik claim\` pays the operator net of it — ${formatUsdc(report.claimable)} net unclaimed)`;
+  if (exposure.atRiskCumulative === 0n) {
+    return [
+      "operator earnings",
+      `${formatUsdc(exposure.verifiedCumulative)} gross verified, all protected on-chain by the proven high-water — a buyer's no-proof reclaim cannot take it, so it can be claimed at any time with \`metrik claim\` ${units}`,
+    ];
+  }
+  const protectedPart = exposure.provenCumulativeKnown
+    ? `${formatUsdc(exposure.protectedCumulative)} gross is protected on-chain (claimed or proven high-water)`
+    : "the on-chain proven high-water could not be read, so this assumes none of the unclaimed balance is protected";
+  return [
+    "operator deadline",
+    hatch.ready
+      ? `${formatUsdc(exposure.atRiskCumulative)} gross of verified accrual is not proven on-chain and the buyer's no-proof reclaim is ALREADY open — it would refund that part to the buyer. ${protectedPart}. ${units}`
+      : `${formatUsdc(exposure.atRiskCumulative)} gross of verified accrual is not proven on-chain; \`metrik claim\` it before ${formatTimestamp(hatch.readyAt)}, after which a buyer's no-proof reclaim refunds that part to the buyer. ${protectedPart}. ${units}`,
+  ];
+}
+
+/**
+ * A reclaimed stream, from the state reclaim WROTE. The buyer side is over:
+ * no checkpoint to wait for, nothing reclaimable, and no escape hatch left to
+ * open (`reclaimUnverified` reverts `AlreadyReclaimed`). So none of those are
+ * printed as live items — only what the operator is still owed.
+ */
+function finalSettlementRows(
+  report: StreamReport,
+  settlement: FinalSettlement,
+): (readonly [string, string])[] {
+  const refundTo = report.stream.payer ?? report.stream.buyer;
+  const exhausted = settlement.finishedBy === "deposit-exhausted";
+  const rows: (readonly [string, string])[] = [
+    [
+      "buyer side",
+      exhausted
+        ? `finished — the operator's claimed${report.escrowGeneration === "v3" ? " or proven" : ""} amount already covers the whole deposit, so there is nothing to reclaim (the escrow would revert NothingToReclaim) and the buyer never reclaimed. Nothing more is owed to, or reclaimable by, the buyer.`
+        : `finished — the buyer has reclaimed, and the refund was paid to ${refundTo}. Nothing more is owed to, or reclaimable by, the buyer.`,
+    ],
+    [
+      "settled to operator",
+      `${formatUsdc(settlement.settledToOperator)} gross (${exhausted ? "the whole deposit" : "fixed at reclaim"})`,
+    ],
+    ["operator claimed", `${formatUsdc(settlement.operatorClaimed)} gross`],
+    [
+      "operator unclaimed",
+      settlement.operatorUnclaimed === 0n
+        ? "none — fully settled"
+        : `${formatUsdc(settlement.operatorUnclaimed)} gross, reserved for the operator — the buyer side is finished, so nothing can take it; \`metrik claim\` it at any time (paid net of the protocol fee)`,
+    ],
+  ];
+  if (exhausted && report.provenCumulative !== null) {
+    rows.push([
+      "proven on-chain",
+      `${formatUsdc(report.provenCumulative)} gross (the escrow's proven high-water)`,
     ]);
   }
+  rows.push(["fees paid", formatUsdc(report.stream.feesPaid)]);
+  return rows;
+}
+
+function describeStatus(report: StreamReport): string {
+  const { stream } = report;
+  const final = report.finalSettlement;
+  if (final === null) return stream.status;
+  if (final.finishedBy === "reclaimed") return `${stream.status} (reclaimed)`;
+  const stop = stream.closedAt > 0 ? "closed" : "expired";
+  return final.operatorUnclaimed === 0n
+    ? `${stream.status} (${stop}, fully settled)`
+    : `${stream.status} (${stop}, buyer side finished)`;
+}
+
+/**
+ * The verified-accrual row. With no current proof on V3, a non-zero proven
+ * high-water IS verified accrual — proven against a signed checkpoint root and
+ * recorded on-chain — so it is stated rather than "not checkpointed yet", which
+ * reads as "nothing verified".
+ */
+function describeVerifiedAccrual(report: StreamReport): string {
+  const { proof } = report;
+  if (proof !== null) {
+    return `${formatUsdc(proof.cumulativeAmount)} gross @ checkpoint ${proof.checkpointId} (${formatTimestamp(Number(proof.checkedAt))})`;
+  }
+  if (report.provenCumulative !== null && report.provenCumulative > 0n) {
+    return `${formatUsdc(report.provenCumulative)} gross proven on-chain (provenCumulativeOf) — the latest checkpoint does not contain this stream (${report.proofUnavailable ?? "no proof"}), so this is read from the escrow`;
+  }
+  return `not checkpointed yet (${report.proofUnavailable ?? "no proof"})`;
+}
+
+function oracleCheckpointRow(report: StreamReport): readonly [string, string] {
+  return [
+    "oracle checkpoint",
+    report.latestCheckpointCheckedAt === null
+      ? "-"
+      : report.latestCheckpointCheckedAt <= 0
+        ? "none posted yet"
+        : `latest covers up to ${formatTimestamp(report.latestCheckpointCheckedAt)}`,
+  ];
+}
+
+function pushTrailingRows(
+  rows: (readonly [string, string])[],
+  report: StreamReport,
+): void {
   if (report.protocolFeeBps !== null) {
     rows.push([
       "protocol fee",
       `${report.protocolFeeBps} bps (read from the escrow)`,
     ]);
   }
-  return rows;
 }
 
 /**

package/src/cli/wallet.ts

@@ -76,12 +76,25 @@ export {
  * signs an EIP-712 invocation capability and broadcasts NOTHING; telling its
  * caller "this command signs a transaction" was simply false.
  */
-export type KeyPurpose = "transaction" | "capability";
+export type KeyPurpose =
+  | "transaction"
+  | "capability"
+  | "payer-close"
+  | "x402-payment";
 
 const PURPOSE_TEXT: Record<KeyPurpose, string> = {
   transaction: "signs a transaction",
   capability:
     "signs an off-chain EIP-712 invocation capability (no transaction is broadcast)",
+  // `metrik refund --close`: the x402 payer signs the opener's EIP-712 `Close`
+  // message and the relay broadcasts it, paying the gas. It is NOT an
+  // invocation capability, and the key needs no funds at all.
+  "payer-close":
+    "signs the payer's off-chain EIP-712 Close message (the refund relay broadcasts it and pays the gas)",
+  // `metrik pay`: the payer signs an EIP-3009 TransferWithAuthorization and the
+  // seller's facilitator settles it. The payer broadcasts nothing.
+  "x402-payment":
+    "signs an EIP-3009 USDC authorization that the seller's facilitator settles (the payer broadcasts no transaction and needs no gas)",
 };
 
 /** Which environment configured the signer, for output and for error text. */
@@ -122,10 +135,33 @@ export interface CliWallet {
   readonly readSpendPolicy?: () => Promise<PrivySpendPolicy>;
 }
 
-const WALLET_HINT =
-  `export ${PRIVATE_KEY_ENV}=0x… (a funded testnet key), configure a Coinbase CDP wallet with ` +
-  `${CDP_ENV_VARS.join(", ")}, or configure a Privy wallet with ${PRIVY_WALLET_KEY_ENV} (agent-owned) or ` +
-  `${PRIVY_SESSION_ENV_VARS.join(", ")} (broker session). All are read from the environment only — never pass a credential as a command-line flag.`;
+const ENV_ONLY =
+  "All are read from the environment only — never pass a credential as a command-line flag.";
+
+/**
+ * How to configure the wallet a purpose needs. "Funded" is said only where a
+ * transaction is broadcast: an off-chain signature costs nothing, and telling
+ * someone to fund a key for one sends them to a faucet for no reason.
+ */
+function walletHint(purpose: KeyPurpose): string {
+  if (purpose === "x402-payment") {
+    return (
+      `export ${PRIVATE_KEY_ENV}=0x… (a testnet key holding USDC; no ETH needed), or configure a Coinbase CDP wallet with ` +
+      `${CDP_ENV_VARS.join(", ")}. A Privy wallet cannot pay x402: its broker does not sign EIP-3009. ${ENV_ONLY}`
+    );
+  }
+  if (purpose === "payer-close") {
+    return (
+      `export ${PRIVATE_KEY_ENV}=0x… (the key that paid; it needs no ETH or USDC), or configure the paying Coinbase CDP wallet with ` +
+      `${CDP_ENV_VARS.join(", ")}. A Privy wallet cannot sign the Close. ${ENV_ONLY}`
+    );
+  }
+  return (
+    `export ${PRIVATE_KEY_ENV}=0x… (${purpose === "transaction" ? "a funded testnet key" : "a testnet key; it needs no funds for this"}), configure a Coinbase CDP wallet with ` +
+    `${CDP_ENV_VARS.join(", ")}, or configure a Privy wallet with ${PRIVY_WALLET_KEY_ENV} (agent-owned) or ` +
+    `${PRIVY_SESSION_ENV_VARS.join(", ")} (broker session). ${ENV_ONLY}`
+  );
+}
 
 export interface ResolveCliWalletOptions {
   readonly purpose?: KeyPurpose;
@@ -159,9 +195,10 @@ export async function resolveCliWallet(
 ): Promise<CliWallet> {
   const wallet = await optionalCliWallet(env, options);
   if (wallet === null) {
+    const purpose = options.purpose ?? "transaction";
     throw configError(
-      `this command ${PURPOSE_TEXT[options.purpose ?? "transaction"]} and needs a wallet: none of ${PRIVATE_KEY_ENV}, the CDP variables or the Privy variables are set`,
-      WALLET_HINT,
+      `this command ${PURPOSE_TEXT[purpose]} and needs a wallet: none of ${PRIVATE_KEY_ENV}, the CDP variables or the Privy variables are set`,
+      walletHint(purpose),
     );
   }
   return wallet;