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

package/src/cli/config.ts

@@ -1,76 +1,97 @@
-import {
-  BASE_SEPOLIA_ESCROW_V2,
-  BASE_SEPOLIA_USDC,
-  DEFAULT_ORACLE_BASE_URL,
-  DEFAULT_PUBLIC_REGISTRY_URL,
-} from "@absol-labs/sdk";
-import { isAddress, getAddress } from "viem";
-import { baseSepolia } from "viem/chains";
+import type { MetrikNetwork } from "@absol-labs/sdk";
+import { isAddress, getAddress, type Chain } from "viem";
 
+import {
+  allowedNetworks,
+  describeAllowedNetworks,
+  registeredDeployment,
+  METRIK_NETWORK_ENV,
+  resolveAgentNetwork,
+  UnsupportedNetworkError,
+} from "../network.js";
 import { CliError, configError, usageError } from "./errors.js";
 import { stringFlag, integerFlag, type ParsedArgs } from "./args.js";
 
 /**
- * TESTNET ONLY — the single allowlist this CLI will settle against.
+ * TESTNET ONLY — the CLI settles only on registered networks the SDK registry
+ * marks `testnet: true`.
  *
  * Metrik's escrow moves real USDC the moment it is pointed at a mainnet chain,
  * and this CLI signs with a raw private key read from the environment. So the
- * chain is an allowlist, not a default: any other chain id is refused outright,
- * with no override flag. There is deliberately no `--allow-mainnet` — an escape
- * hatch that re-enables real funds would defeat the guarantee, and a mainnet
- * deployment is not something a flag can conjure (there is none).
+ * chain is an allowlist, not a default: a chain the registry does not know, or
+ * one it knows as a mainnet, is refused outright, with no override flag. There
+ * is deliberately no `--allow-mainnet` — an escape hatch that re-enables real
+ * funds would defeat the guarantee.
  *
- * The allowlist is enforced TWICE: once against the configured/declared chain
- * id, and again against the chain id the RPC endpoint actually reports before
- * any fund-moving command signs anything (see `assertTestnetRpc`). The second
- * check is what stops `--chain-id 84532 --rpc-url <a mainnet RPC>`.
+ * The allowlist is enforced TWICE: once against the configured/declared network,
+ * and again against the chain id the RPC endpoint actually reports before any
+ * fund-moving command signs anything (see `assertTestnetRpc`). The second check
+ * is what stops a testnet `--chain-id` paired with a mainnet `--rpc-url`.
  */
-export const TESTNET_CHAIN_IDS: readonly number[] = [baseSepolia.id];
+export const CLI_NETWORK_POLICY = { testnetOnly: true } as const;
+
+/** Chain ids of every registered testnet this CLI will settle against. */
+export function testnetChainIds(): number[] {
+  return allowedNetworks(CLI_NETWORK_POLICY).map((network) => network.chain.id);
+}
 
 /**
- * The block `BASE_SEPOLIA_ESCROW_V2` was deployed at — the anchor of every
- * escrow log scan, because the contract has no history before it.
- *
- * Verified against Base Sepolia on 2026-09-17: `eth_getLogs` for this single
- * block returns 6 escrow logs (the deployment's own events). History is
- * immutable, so that is a stable known answer forever, which is what lets the
- * same block serve as the log-retention canary in `metrik streams`.
- *
- * It is tied to that ONE address. A run pointed at a different `--escrow` has
- * no anchor and must be given `--from-block`, rather than silently scanning
- * from a block that means nothing for it.
+ * @deprecated Snapshot of {@link testnetChainIds} at import time. A network
+ * registered later is not in it; call `testnetChainIds()` instead.
  */
-export const BASE_SEPOLIA_ESCROW_V2_DEPLOY_BLOCK = 45_892_018n;
+export const TESTNET_CHAIN_IDS: readonly number[] = testnetChainIds();
 
 export interface CliConfig {
-  readonly chain: typeof baseSepolia;
+  /** The registered network this run settles on (from the SDK registry). */
+  readonly network: MetrikNetwork;
+  readonly chain: Chain;
   readonly chainId: number;
   readonly rpcUrl: string;
   readonly escrow: `0x${string}`;
   readonly usdc: `0x${string}`;
   readonly oracleBaseUrl: string;
   readonly registryUrl: string;
+  /**
+   * Set ONLY for an `--escrow` the registry does not record, from the explicit
+   * `--escrow-generation`: the SDK then opts out of its code-hash pin
+   * (`allowUnregisteredEscrow`). A registered escrow's generation comes from
+   * the registry.
+   */
+  readonly unregisteredEscrowGeneration?: "v2" | "v3";
+}
+
+/**
+ * The block the configured escrow was deployed at — the anchor of every escrow
+ * log scan — or `undefined` when the escrow is not the network's registered
+ * escrow (a run pointed at a different `--escrow` has no anchor and must be
+ * given `--from-block`, rather than silently scanning from a block that means
+ * nothing for it).
+ */
+export function escrowDeployBlock(config: CliConfig): bigint | undefined {
+  return registeredDeployment(config.network, config.escrow)?.escrow
+    .deployBlock;
 }
 
 /**
- * Resolves settlement configuration from flags, then env, then the baked-in
- * Base Sepolia defaults — so `metrik discover` works with nothing configured at
+ * Resolves settlement configuration from flags, then env, then the network's
+ * registry defaults — so `metrik discover` works with nothing configured at
  * all, while every value stays overridable.
+ *
+ * The network is selected by `--network` / `METRIK_NETWORK` (registry id,
+ * chain id or CAIP-2 id) or by `--chain-id` / `METRIK_AGENT_CHAIN_ID`; giving
+ * both is allowed only when they agree.
  */
 export function resolveConfig(
   args: ParsedArgs,
   env: NodeJS.ProcessEnv,
 ): CliConfig {
-  const chainId =
-    integerFlag(args, "chain-id") ??
-    parseEnvChainId(env.METRIK_AGENT_CHAIN_ID) ??
-    baseSepolia.id;
-  assertTestnetChainId(chainId, "the configured chain id");
+  const network = resolveCliNetwork(args, env);
+  const chainId = network.chain.id;
 
   const rpcUrl =
     stringFlag(args, "rpc-url") ??
     env.METRIK_AGENT_RPC_URL ??
-    baseSepolia.rpcUrls.default.http[0];
+    network.rpcUrls[0];
   if (rpcUrl === undefined || !isHttpUrl(rpcUrl)) {
     throw configError(
       `RPC URL must be an http(s) URL (got "${rpcUrl ?? "undefined"}")`,
@@ -78,35 +99,101 @@ export function resolveConfig(
     );
   }
 
+  const escrow = resolveAddress(
+    stringFlag(args, "escrow") ?? env.METRIK_AGENT_ESCROW,
+    network.escrow.address,
+    "escrow",
+  );
+  const declared = (
+    stringFlag(args, "escrow-generation") ?? env.METRIK_AGENT_ESCROW_GENERATION
+  )
+    ?.trim()
+    .toLowerCase();
+  if (declared !== undefined && declared !== "v2" && declared !== "v3") {
+    throw configError(
+      `--escrow-generation must be "v2" or "v3" (got "${declared}")`,
+    );
+  }
+  const deployment = registeredDeployment(network, escrow);
+  if (deployment === undefined && declared === undefined) {
+    throw configError(
+      `escrow ${escrow} is not a registered deployment of ${network.name}`,
+      `the SDK pins registered escrows by code hash; for your own deployment pass --escrow-generation v2|v3 (it then only checks the interface, which any contract can fake). Registered: ${[network.escrow, ...network.legacy.map((d) => d.escrow)].map((e) => `${e.address} (${e.generation})`).join(", ")}.`,
+    );
+  }
+  if (
+    deployment !== undefined &&
+    declared !== undefined &&
+    declared !== deployment.escrow.generation
+  ) {
+    throw configError(
+      `--escrow-generation ${declared} contradicts the registry: ${escrow} is the ${deployment.escrow.generation} escrow`,
+    );
+  }
+
   return {
-    chain: baseSepolia,
+    network,
+    chain: network.chain,
     chainId,
     rpcUrl,
-    escrow: resolveAddress(
-      stringFlag(args, "escrow") ?? env.METRIK_AGENT_ESCROW,
-      BASE_SEPOLIA_ESCROW_V2,
-      "escrow",
-    ),
+    escrow,
+    ...(deployment === undefined
+      ? { unregisteredEscrowGeneration: declared as "v2" | "v3" }
+      : {}),
     usdc: resolveAddress(
       stringFlag(args, "usdc") ?? env.METRIK_AGENT_USDC,
-      BASE_SEPOLIA_USDC,
+      network.usdc.address,
       "usdc",
     ),
     oracleBaseUrl: resolveHttpUrl(
       stringFlag(args, "oracle-url") ?? env.METRIK_AGENT_ORACLE_URL,
-      DEFAULT_ORACLE_BASE_URL,
+      network.oracleBaseUrl,
       "oracle-url",
     ),
     registryUrl: resolveHttpUrl(
       stringFlag(args, "registry-url") ?? env.METRIK_AGENT_REGISTRY_URL,
-      DEFAULT_PUBLIC_REGISTRY_URL,
+      network.publicRegistryUrl ?? `${network.oracleBaseUrl}/listings`,
       "registry-url",
     ),
   };
 }
 
+function resolveCliNetwork(
+  args: ParsedArgs,
+  env: NodeJS.ProcessEnv,
+): MetrikNetwork {
+  const chainId =
+    integerFlag(args, "chain-id") ?? parseEnvChainId(env.METRIK_AGENT_CHAIN_ID);
+  const selector = stringFlag(args, "network") ?? env[METRIK_NETWORK_ENV];
+  if (chainId !== undefined)
+    assertTestnetChainId(chainId, "the configured chain id");
+  let network: MetrikNetwork;
+  try {
+    network = resolveAgentNetwork(
+      selector !== undefined && selector.trim().length > 0 ? selector : chainId,
+      CLI_NETWORK_POLICY,
+    );
+  } catch (error) {
+    if (error instanceof UnsupportedNetworkError) {
+      throw configError(
+        `refusing to run against network "${error.selector}": it is not a supported testnet`,
+        `${error.message}. There is no override flag.`,
+      );
+    }
+    throw error;
+  }
+  if (chainId !== undefined && chainId !== network.chain.id) {
+    throw configError(
+      `--chain-id ${chainId} does not match --network ${network.id} (chain ${network.chain.id})`,
+      "give one of them, or make them agree.",
+    );
+  }
+  return network;
+}
 /** Flags every command accepts for settlement configuration. */
 export const CONFIG_FLAGS: readonly string[] = [
+  "network",
+  "escrow-generation",
   "chain-id",
   "rpc-url",
   "escrow",
@@ -119,12 +206,12 @@ export const CONFIG_FLAGS: readonly string[] = [
 export const GLOBAL_FLAGS: readonly string[] = ["json", "help"];
 
 export function assertTestnetChainId(chainId: number, source: string): void {
-  if (TESTNET_CHAIN_IDS.includes(chainId)) return;
+  if (testnetChainIds().includes(chainId)) return;
   throw configError(
     `refusing to run against chain ${chainId}: ${source} is not a supported testnet`,
-    `this CLI signs with a raw private key and settles real value, so it is testnet-only. Supported: ${TESTNET_CHAIN_IDS.join(
-      ", ",
-    )} (Base Sepolia). There is no override flag.`,
+    `this CLI signs with a raw private key and settles real value, so it is testnet-only. Supported (registered testnets): ${describeAllowedNetworks(
+      CLI_NETWORK_POLICY,
+    )}. There is no override flag.`,
   );
 }
 

package/src/cli/context.ts

@@ -2,6 +2,7 @@ import type { ParsedArgs } from "./args.js";
 import type { CliConfig } from "./config.js";
 import type { CliDependencies } from "./deps.js";
 import type { Printer } from "./output.js";
+import type { ProgressActivity } from "./progress.js";
 
 /** Everything a command needs, assembled once by the runner. */
 export interface CommandContext {
@@ -10,6 +11,12 @@ export interface CommandContext {
   readonly env: NodeJS.ProcessEnv;
   readonly out: Printer;
   readonly deps: CliDependencies;
+  /**
+   * The runner's heartbeat. A command in a deliberate, announced retry or poll
+   * names it here so the heartbeat says what it is waiting for. Optional so a
+   * command can be driven without the runner (tests); absent means no-op.
+   */
+  readonly progress?: ProgressActivity;
 }
 
 export interface CommandSpec {
@@ -26,5 +33,14 @@ export interface CommandSpec {
    * `signs`, since everything that broadcasts obviously needs a key.
    */
   readonly requiresKey?: boolean;
+  /**
+   * Replaces the generic wallet paragraph of `--help` (and the tag in the
+   * command list) when "Broadcasts a transaction" / "needs a key" would be
+   * false for this command — e.g. `pay`, whose payer signs an EIP-3009
+   * authorization and broadcasts nothing, and cannot use a Privy wallet.
+   */
+  readonly walletHelp?: { readonly tag: string; readonly text: string };
+  /** How a flag is shown in `--help`, when `--<name>` alone would mislead. */
+  readonly flagHelp?: Readonly<Record<string, string>>;
   readonly run: (context: CommandContext) => Promise<void>;
 }

package/src/cli/deps.ts

@@ -31,6 +31,11 @@ import {
   type ReclaimVerifiedStreamResult,
 } from "../sdk/client.js";
 import type { SignedSpendMandate } from "../mandates/mandate.js";
+import type {
+  PayX402WithMandateInput,
+  PayX402WithMandateResult,
+} from "../x402-buyer/pay.js";
+import type { RefundClient } from "@absol-labs/sdk/x402";
 
 import type { CliConfig } from "./config.js";
 import type { CliSignerAccount } from "./wallet.js";
@@ -65,6 +70,19 @@ export interface CliReadClient {
   ): Promise<bigint>;
   /** Live protocol fee, read from the escrow rather than hardcoded. */
   protocolFeeBps(): Promise<number>;
+  /**
+   * StreamEscrowV3 only: the stream's on-chain proven high-water
+   * (`provenCumulativeOf`). Both V3 buyer exits settle the operator at no less
+   * than this, and the operator can redeem it with `claimProven` — so it is the
+   * part of the operator's verified earnings the no-proof escape hatch can NOT
+   * take. Never called against a V2 escrow, which has no such view.
+   *
+   * Optional so an embedder's existing read client keeps compiling; a client
+   * without it is treated as "proven high-water unknown", which the CLI reports
+   * as worst case (nothing protected), never as protected.
+   */
+  provenCumulativeOf?(streamId: `0x${string}`): Promise<bigint>;
+
   /**
    * `StreamEscrowV2.escapeGraceSeconds` (public immutable). The buyer's no-proof
    * escape hatch unlocks at `expiresAt + escapeGraceSeconds`, so this is half of
@@ -197,6 +215,16 @@ export interface CliWriteClient {
   claimStream(
     input: CliStreamActionInput,
   ): Promise<StreamProofTransactionResult>;
+  /**
+   * Operator-only, StreamEscrowV3 only: redeem the stream's on-chain proven
+   * high-water (`claimProven`) WITHOUT a fresh Merkle proof — the only way to
+   * collect proven value whose checkpoint root has rotated out of the retained
+   * set. Optional so an embedder's existing write client keeps compiling; the
+   * CLI refuses, rather than falls back to a proof claim, when it is absent.
+   */
+  claimProvenStream?(
+    input: CliStreamActionInput,
+  ): Promise<StreamProofTransactionResult>;
 }
 
 /**
@@ -212,6 +240,32 @@ export interface CreateWriteClientOptions {
   readonly transport?: Transport;
 }
 
+/**
+ * The buyer side of x402 (`metrik pay` / `metrik refund`). Behind the injectable
+ * surface like every other side effect, and loaded lazily by default so a CLI
+ * run that never pays over x402 never imports `@x402/*`.
+ */
+export interface CliX402 {
+  /** Mandate-gated `payWithX402` (see `../x402-buyer/pay.ts`). */
+  readonly pay: (
+    input: PayX402WithMandateInput,
+  ) => Promise<PayX402WithMandateResult>;
+  /**
+   * The SDK's `refundClient`, bound to ONE stream and verifying every relay
+   * "success" against the chain this CLI is configured for.
+   */
+  readonly refundClient: (
+    config: CliConfig,
+    target: {
+      readonly refundUrl: string;
+      readonly streamId: `0x${string}`;
+      readonly opener?: `0x${string}`;
+      readonly maxAttempts?: number;
+      readonly maxDelayMs?: number;
+    },
+  ) => Promise<RefundClient>;
+}
+
 export interface CliDependencies {
   readonly createReadClient: (config: CliConfig) => CliReadClient;
   /**
@@ -236,6 +290,8 @@ export interface CliDependencies {
   readonly createInvokeStreamReader: (config: CliConfig) => InvokeStreamReader;
   readonly nowSeconds: () => number;
   readonly sleep: (ms: number) => Promise<void>;
+  /** Optional so an embedder's existing dependency object keeps compiling. */
+  readonly x402?: CliX402;
 }
 
 /**
@@ -256,13 +312,29 @@ const STREAM_OPENED_EVENT = getAbiItem({
  * with nothing on screen. Bounding it here bounds every read and every
  * simulation the SDK performs, in one place.
  */
-function rpcTransport(config: CliConfig) {
+export function rpcTransport(config: CliConfig) {
   return http(config.rpcUrl, {
     timeout: RPC_TIMEOUT_MS,
     retryCount: RPC_RETRY_COUNT,
   });
 }
 
+/**
+ * An `--escrow` the registry does not record was declared with
+ * `--escrow-generation`: the only case the SDK may skip its code-hash pin.
+ */
+function unregisteredEscrowOptions(config: CliConfig): {
+  readonly allowUnregisteredEscrow?: true;
+  readonly escrowGeneration?: "v2" | "v3";
+} {
+  return config.unregisteredEscrowGeneration === undefined
+    ? {}
+    : {
+        allowUnregisteredEscrow: true,
+        escrowGeneration: config.unregisteredEscrowGeneration,
+      };
+}
+
 /** Shared `MetrikClient` construction: one escrow, declared as V2 on both keys. */
 function createMetrikClient(
   config: CliConfig,
@@ -281,6 +353,7 @@ function createMetrikClient(
     usdc: config.usdc,
     oracleBaseUrl: config.oracleBaseUrl,
     settlementTarget: { chainId: config.chainId, escrow: config.escrow },
+    ...unregisteredEscrowOptions(config),
     ...(account === undefined ? {} : { account }),
   });
 }
@@ -309,6 +382,11 @@ export const defaultCliDependencies: CliDependencies = {
       async reclaimableForV2(streamId, cumulativeAmount) {
         return await metrik.reclaimableForV2(streamId, cumulativeAmount);
       },
+      async provenCumulativeOf(streamId) {
+        // The SDK refuses this (before any RPC) on a client whose escrow is not
+        // V3, so a V2 escrow can never be read through the V3 ABI here.
+        return await metrik.provenCumulativeOf(streamId);
+      },
       async nativeBalance(address) {
         return await metrik.publicClient.getBalance({ address });
       },
@@ -416,6 +494,7 @@ export const defaultCliDependencies: CliDependencies = {
       usdc: config.usdc,
       oracleBaseUrl: config.oracleBaseUrl,
       settlementTarget: { chainId: config.chainId, escrow: config.escrow },
+      ...unregisteredEscrowOptions(config),
       ...(account === null ? {} : { account }),
     };
     // The mandate-gated agent client owns every fund-moving call; the raw SDK
@@ -480,6 +559,15 @@ export const defaultCliDependencies: CliDependencies = {
         if (signedMandate === null) return await metrik.claim(input.streamId);
         return await agentClient.claimStream({ ...input, signedMandate });
       },
+      async claimProvenStream({ signedMandate, ...input }) {
+        if (signedMandate === null) {
+          return await metrik.claimProven(input.streamId);
+        }
+        return await agentClient.claimProvenStream({
+          ...input,
+          signedMandate,
+        });
+      },
     };
   },
   async discover(options) {
@@ -506,6 +594,28 @@ export const defaultCliDependencies: CliDependencies = {
   nowSeconds() {
     return Math.floor(Date.now() / 1000);
   },
+  x402: {
+    async pay(input) {
+      const { payX402WithMandate } = await import("../x402-buyer/pay.js");
+      return await payX402WithMandate(input);
+    },
+    async refundClient(config, target) {
+      const { refundClient } = await import("@absol-labs/sdk/x402");
+      return refundClient(target.refundUrl, {
+        streamId: target.streamId,
+        ...(target.opener === undefined ? {} : { opener: target.opener }),
+        // Every relay "success" is checked against the receipt on THIS chain.
+        verifyWith: createMetrikClient(config),
+        expectedChainId: config.chainId,
+        ...(target.maxAttempts === undefined
+          ? {}
+          : { maxAttempts: target.maxAttempts }),
+        ...(target.maxDelayMs === undefined
+          ? {}
+          : { maxDelayMs: target.maxDelayMs }),
+      });
+    },
+  },
   async sleep(ms) {
     await new Promise((resolve) => setTimeout(resolve, ms));
   },

package/src/cli/errors.ts

@@ -76,6 +76,28 @@ function namesTheRevert(line: string): boolean {
   );
 }
 
+/**
+ * Links that state the OUTCOME rather than open a sentence the next link
+ * completes — so the trailing "…and it reverted" carries nothing.
+ *
+ * `metrik status <a stream id that does not exist>` used to print
+ *
+ *   stream 0x…: does not exist on the escrow: The contract function
+ *   "getStream" reverted.
+ *
+ * The first link is the whole answer; the tail is viem restating that a revert
+ * is how the escrow says so. Contrast "reclaim simulation failed", which is a
+ * PREFIX — dropping the boilerplate after it would leave a failure with no
+ * stated reason at all, which is why the one-boilerplate rule exists.
+ */
+const STATES_THE_OUTCOME: readonly RegExp[] = [
+  /\bdoes not exist on the escrow\b/,
+];
+
+function statesTheOutcome(line: string): boolean {
+  return STATES_THE_OUTCOME.some((pattern) => pattern.test(line));
+}
+
 function isBoilerplate(line: string): boolean {
   return VIEM_BOILERPLATE.some((pattern) => pattern.test(line));
 }
@@ -108,7 +130,8 @@ export function stripRedundantBoilerplate(
   chain: readonly string[],
 ): readonly string[] {
   const decoded = chain.some(
-    (line) => namesTheRevert(line) && !isBoilerplate(line),
+    (line) =>
+      (namesTheRevert(line) || statesTheOutcome(line)) && !isBoilerplate(line),
   );
   let keptBoilerplate = false;
   const kept = chain.filter((line, index) => {

package/src/cli/escape-hatch.ts

@@ -1,5 +1,7 @@
 import type { StreamV2 } from "@absol-labs/sdk";
 
+import { escapeHatchReadyAtFormula } from "../escrow-generation.js";
+
 import { formatDuration } from "./amounts.js";
 import type { CliReadClient } from "./deps.js";
 
@@ -17,9 +19,11 @@ import type { CliReadClient } from "./deps.js";
  * — and `escapeGraceSeconds` is a public immutable on the escrow, so readiness
  * is fully computable before a single wei of gas is spent.
  *
- * Note which timestamp the escrow uses: `expiresAt`, NEVER `closedAt`. Closing a
- * stream early does not bring the escape hatch forward, and the CLI must not
- * imply that it does.
+ * Note which timestamp the escrow uses, which depends on its GENERATION (the
+ * SDK registry's `escrow.generation`; see `../escrow-generation.ts`): V2 uses
+ * `expiresAt`, NEVER `closedAt` — closing early does not bring the hatch
+ * forward, and the CLI must not imply that it does. V3 opens it at
+ * `min(expiresAt, closedAt) + escapeGraceSeconds`.
  */
 export interface EscapeHatchWindow {
   /** `escapeGraceSeconds` as read from the escrow. */
@@ -32,11 +36,21 @@ export interface EscapeHatchWindow {
 }
 
 export function escapeHatchWindow(
-  stream: Pick<StreamV2, "expiresAt">,
+  stream: Pick<StreamV2, "expiresAt"> & Partial<Pick<StreamV2, "closedAt">>,
   graceSeconds: number,
   nowSeconds: number,
+  generation = "v2",
 ): EscapeHatchWindow {
-  const readyAt = stream.expiresAt + graceSeconds;
+  const readyAt = Number(
+    escapeHatchReadyAtFormula(
+      generation,
+      {
+        expiresAt: BigInt(stream.expiresAt),
+        closedAt: BigInt(stream.closedAt ?? 0),
+      },
+      BigInt(graceSeconds),
+    ),
+  );
   const secondsRemaining = readyAt - nowSeconds;
   return {
     graceSeconds,

package/src/cli/listings.ts

@@ -18,6 +18,30 @@ export async function resolveListing(
   serviceRef: `0x${string}`,
   options: { readonly required: boolean },
 ): Promise<ServiceListing | null> {
+  return (await resolveListingRecord(context, serviceRef, options)).listing;
+}
+
+/**
+ * What {@link resolveListing} found, including the verified signed record of a
+ * matching row even when that row is not usable as a listing (no signed
+ * invocation URL) — `open` still has to read the operator-signed rate band off
+ * it — and whether the registry was unreachable (the only case in which a
+ * signed band may exist and be unknown).
+ */
+export interface ListingRecordResolution {
+  readonly listing: ServiceListing | null;
+  readonly record: {
+    readonly serviceRef: string;
+    readonly signed: ServiceListing["signed"];
+  } | null;
+  readonly registryUnreachable: boolean;
+}
+
+export async function resolveListingRecord(
+  context: CommandContext,
+  serviceRef: `0x${string}`,
+  options: { readonly required: boolean },
+): Promise<ListingRecordResolution> {
   const { config, out, deps } = context;
   let services;
   try {
@@ -32,7 +56,7 @@ export async function resolveListing(
       out.note(
         `warning: the registry at ${config.registryUrl} is unreachable; continuing without a verified listing.`,
       );
-      return null;
+      return { listing: null, record: null, registryUnreachable: true };
     }
     throw new CliError(
       `the service registry at ${config.registryUrl} could not be read`,
@@ -45,7 +69,9 @@ export async function resolveListing(
     (service) => service.serviceRef.toLowerCase() === wanted,
   );
   if (match === undefined) {
-    if (!options.required) return null;
+    if (!options.required) {
+      return { listing: null, record: null, registryUnreachable: false };
+    }
     throw new CliError(
       `no verified listing in the registry matches serviceRef ${serviceRef}`,
       {
@@ -54,8 +80,11 @@ export async function resolveListing(
       },
     );
   }
+  const record = { serviceRef: match.serviceRef, signed: match.signed };
   if (match.accessUrl === null) {
-    if (!options.required) return null;
+    if (!options.required) {
+      return { listing: null, record, registryUnreachable: false };
+    }
     throw new CliError(
       `listing ${serviceRef} carries no signed invocation URL`,
       {
@@ -66,12 +95,16 @@ export async function resolveListing(
   }
 
   return {
-    serviceRef: match.serviceRef,
-    operator: match.operator,
-    publicUrl: match.publicUrl,
-    access: match.access,
-    accessUrl: match.accessUrl,
-    signed: match.signed,
-    category: match.category,
+    listing: {
+      serviceRef: match.serviceRef,
+      operator: match.operator,
+      publicUrl: match.publicUrl,
+      access: match.access,
+      accessUrl: match.accessUrl,
+      signed: match.signed,
+      category: match.category,
+    },
+    record,
+    registryUnreachable: false,
   };
 }