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

package/src/cli/commands/status.ts

@@ -7,6 +7,7 @@ import {
   streamReportRows,
 } from "../status.js";
 import type { CommandContext, CommandSpec } from "../context.js";
+import { escrowGenerationFor } from "../../escrow-generation.js";
 
 export const statusCommand: CommandSpec = {
   name: "status",
@@ -28,7 +29,12 @@ export const statusCommand: CommandSpec = {
     // diverge from index 5 onward, so a wrong-chain read does not revert — it
     // silently decodes something else into fields with the right names.
     await assertTestnetRpc(config, () => read.getChainId());
-    const report = await readStreamReport(read, streamId, deps.nowSeconds());
+    const report = await readStreamReport(
+      read,
+      streamId,
+      deps.nowSeconds(),
+      escrowGenerationFor(config.chainId, config.escrow),
+    );
 
     out.result(streamReportJson(report));
     // Who attests, before the numbers. Printed on stderr so it survives `--json`
@@ -40,6 +46,16 @@ export const statusCommand: CommandSpec = {
     if (disclosure !== null) out.note(disclosure);
     out.print(`Stream ${streamId}`);
     out.table(streamReportRows(report));
+    const opener = report.stream.opener ?? null;
+    if (opener !== null) {
+      out.print("");
+      out.print(
+        `Bought over x402: the escrow accepts close/reclaim only from the opener ${opener}. ` +
+          `\`metrik close ${streamId}\` (signed by the payer ${report.stream.payer}) routes through it; ` +
+          `\`metrik reclaim ${streamId}\` sends the permissionless opener.reclaim, and the refund always goes to the payer. ` +
+          "A payer with no gas can use the seller's relay instead: `metrik refund <streamId> --refund-url <url> --close --reclaim`. Nothing refunds automatically.",
+      );
+    }
     if (report.settlement.pending) {
       out.print("");
       out.print(

package/src/cli/commands/streams.ts

@@ -1,11 +1,11 @@
-import { BASE_SEPOLIA_ESCROW_V2 } from "@absol-labs/sdk";
 import { getAddress, isAddress } from "viem";
 
 import { integerFlag, stringFlag } from "../args.js";
 import { formatUsdc } from "../amounts.js";
 import {
-  BASE_SEPOLIA_ESCROW_V2_DEPLOY_BLOCK,
   assertTestnetRpc,
+  escrowDeployBlock,
+  type CliConfig,
 } from "../config.js";
 import { CliError, configError, usageError } from "../errors.js";
 import { escrowScanRange } from "../scan-range.js";
@@ -32,7 +32,7 @@ const SCAN_CONCURRENCY = 6;
 /**
  * Attempts per window before it is reported as unscanned. A public RPC answers
  * a burst of `eth_getLogs` with an occasional 429 — measured against
- * `sepolia.base.org`, 2 of 212 windows on a full-history scan — and a transient
+ * the network's public RPC, 2 of 212 windows on a full-history scan — and a transient
  * rate-limit is NOT a window that cannot be scanned. Declaring it one would
  * make the "this scan is incomplete" warning routine, and a warning that fires
  * on every healthy run is a warning nobody reads on the run that matters.
@@ -71,7 +71,7 @@ export const streamsCommand: CommandSpec = {
     // else into fields with the right names.
     await assertTestnetRpc(config, () => read.getChainId());
 
-    const anchor = resolveAnchorBlock(args, config.escrow);
+    const anchor = resolveAnchorBlock(args, config);
     const head = await read.blockNumber();
     const range = escrowScanRange(head, anchor.block);
 
@@ -251,25 +251,21 @@ async function resolveScanAddress(
  */
 function resolveAnchorBlock(
   args: CommandContext["args"],
-  escrow: `0x${string}`,
+  config: CliConfig,
 ): { readonly block: bigint; readonly canary: bigint | null } {
   const override = integerFlag(args, "from-block");
-  const isKnownEscrow =
-    escrow.toLowerCase() === BASE_SEPOLIA_ESCROW_V2.toLowerCase();
+  const deployBlock = escrowDeployBlock(config);
 
   if (override !== undefined) {
     return { block: BigInt(override), canary: null };
   }
-  if (!isKnownEscrow) {
+  if (deployBlock === undefined) {
     throw configError(
-      `no scan anchor is known for escrow ${escrow}`,
-      "the scan is anchored at the escrow's deploy block, and this CLI only ships that block for its default Base Sepolia escrow. Pass --from-block <deploy block> for a different escrow.",
+      `no scan anchor is known for escrow ${config.escrow}`,
+      `the scan is anchored at the escrow's deploy block, and the network registry only records it for ${config.network.name}'s registered escrow (${config.network.escrow.address}). Pass --from-block <deploy block> for a different escrow.`,
     );
   }
-  return {
-    block: BASE_SEPOLIA_ESCROW_V2_DEPLOY_BLOCK,
-    canary: BASE_SEPOLIA_ESCROW_V2_DEPLOY_BLOCK,
-  };
+  return { block: deployBlock, canary: deployBlock };
 }
 
 /**

package/src/cli/commands/watch.ts

@@ -7,6 +7,7 @@ import {
   streamReportRows,
 } from "../status.js";
 import type { CommandContext, CommandSpec } from "../context.js";
+import { escrowGenerationFor } from "../../escrow-generation.js";
 
 const DEFAULT_INTERVAL_SECONDS = 15;
 
@@ -43,7 +44,12 @@ export const watchCommand: CommandSpec = {
 
       let report;
       try {
-        report = await readStreamReport(read, streamId, deps.nowSeconds());
+        report = await readStreamReport(
+          read,
+          streamId,
+          deps.nowSeconds(),
+          escrowGenerationFor(config.chainId, config.escrow),
+        );
       } catch (error) {
         // A transient RPC blip must not end a long watch.
         out.note(`read failed, retrying: ${describeError(error)}`);

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/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";
@@ -212,6 +217,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 +267,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 +289,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 +330,7 @@ function createMetrikClient(
     usdc: config.usdc,
     oracleBaseUrl: config.oracleBaseUrl,
     settlementTarget: { chainId: config.chainId, escrow: config.escrow },
+    ...unregisteredEscrowOptions(config),
     ...(account === undefined ? {} : { account }),
   });
 }
@@ -416,6 +466,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
@@ -506,6 +557,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,