@blockrun/llm 3.19.1 → 3.20.1

package/dist/index.js

@@ -1,4 +1,19 @@
 // src/types.ts
+var RETRY_DISPOSITION = /* @__PURE__ */ Symbol.for("@blockrun/llm/retry-disposition/v1");
+function retryDisposition(err) {
+  if (!err || typeof err !== "object" && typeof err !== "function") return void 0;
+  const value = err[RETRY_DISPOSITION];
+  return value === "unpaid" || value === "paid-or-in-doubt" ? value : void 0;
+}
+function withDisposition(err, disposition) {
+  if (!err || typeof err !== "object") return err;
+  if (retryDisposition(err) === "paid-or-in-doubt") return err;
+  try {
+    Object.defineProperty(err, RETRY_DISPOSITION, { value: disposition, configurable: true, writable: true, enumerable: false });
+  } catch {
+  }
+  return err;
+}
 var BlockrunError = class extends Error {
   constructor(message) {
     super(message);
@@ -190,6 +205,15 @@ function resolveApiKeyAuth(options) {
   const base = options.apiUrl ?? (typeof process !== "undefined" ? process.env?.BLOCKRUN_API_BASE_URL : void 0) ?? API_KEY_URL;
   return new ApiKeyAuth(key.trim(), base);
 }
+function accountErrorDisposition(err) {
+  if (!(err instanceof APIError)) return "paid-or-in-doubt";
+  if (err.statusCode >= 400 && err.statusCode < 500) return "unpaid";
+  if (err.statusCode >= 500 && hasGatewayErrorEnvelope(err.response)) return "unpaid";
+  return "paid-or-in-doubt";
+}
+function hasGatewayErrorEnvelope(response) {
+  return !!response && typeof response === "object" && typeof response.message === "string" && response.message.length > 0;
+}
 function requireWallet(value) {
   if (value === void 0) throw new Error("This operation requires a wallet; the client uses API key account billing.");
   return value;
@@ -4056,6 +4080,7 @@ var AUTO_ROUTING_PROFILES = {
 var BASE_MINIMUM_PAYMENT_USD = 2e-3;
 var SOLANA_MINIMUM_PAYMENT_USD = 1e-3;
 function isTransientError(err) {
+  if (retryDisposition(err) !== "unpaid") return false;
   if (err instanceof PaymentError) return false;
   if (err instanceof APIError) {
     return [429, 502, 503, 504, 522, 524].includes(err.statusCode);
@@ -4539,7 +4564,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.19.1";
+var SDK_VERSION = "3.20.1";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -4811,10 +4836,13 @@ var LLMClient = class _LLMClient {
    * Full chat completion interface (OpenAI-compatible).
    *
    * When `fallbackModels` is set, transient failures (timeouts, network
-   * errors, 5xx) on the primary model trigger a retry against the next
-   * model in the list before raising. 4xx errors and PaymentError
-   * propagate immediately — those aren't "swap upstream and retry"
-   * situations. Each fallback hop logs one stderr line.
+   * errors, 429, 5xx) on the primary model trigger a retry against the next
+   * model in the list before raising, but only while no payment has been
+   * sent for it (the error's {@link RetryDisposition} is `"unpaid"`). Once a
+   * payment was sent, any failure propagates: the next model would be a
+   * second charge. 4xx errors and PaymentError also propagate immediately —
+   * those aren't "swap upstream and retry" situations. Each fallback hop
+   * logs one stderr line.
    *
    * @param model - Primary model ID
    * @param messages - Array of messages with role and content
@@ -4917,21 +4945,25 @@ var LLMClient = class _LLMClient {
   }
   /**
    * Make a request with automatic x402 payment handling.
+   *
+   * Every error it throws carries a {@link RetryDisposition}, which is what
+   * {@link LLMClient.chatCompletion}'s fallback walk honours: errors of the
+   * unpaid first request (and its one 502/503 retry), of the 402 challenge
+   * and of signing are `"unpaid"`; anything after the signed payment was sent
+   * is `"paid-or-in-doubt"`. With an API key the request itself is billed, so
+   * only the account API's explicit 4xx refusal is `"unpaid"`.
    */
   async requestWithPayment(endpoint, body) {
     const url = `${this.apiUrl}${endpoint}`;
-    const response = await this.fetchWithTimeout(url, {
+    const unpaid = {
       method: "POST",
       headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
       body: JSON.stringify(body)
-    });
+    };
+    const response = await this.sendUnpaid(url, unpaid);
     if (response.status === 502 || response.status === 503) {
       await new Promise((r) => setTimeout(r, 1e3));
-      const retryResp = await this.fetchWithTimeout(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
-        body: JSON.stringify(body)
-      });
+      const retryResp = await this.sendUnpaid(url, unpaid);
       if (retryResp.status !== 502 && retryResp.status !== 503) {
         if (retryResp.status === 402) return this.handlePaymentAndRetry(url, body, retryResp);
         if (!retryResp.ok) {
@@ -4941,9 +4973,12 @@ var LLMClient = class _LLMClient {
           } catch {
             errorBody = { error: "Request failed" };
           }
-          throw new APIError(`API error: ${retryResp.status}`, retryResp.status, sanitizeErrorResponse(errorBody));
+          throw withDisposition(
+            new APIError(`API error: ${retryResp.status}`, retryResp.status, sanitizeErrorResponse(errorBody)),
+            "unpaid"
+          );
         }
-        return this.parseChatResponse(retryResp);
+        return this.parseUnpaidChatResponse(retryResp);
       }
     }
     if (response.status === 402) {
@@ -4956,18 +4991,61 @@ var LLMClient = class _LLMClient {
       } catch {
         errorBody = { error: "Request failed" };
       }
-      throw new APIError(
-        `API error: ${response.status}`,
-        response.status,
-        sanitizeErrorResponse(errorBody)
+      throw withDisposition(
+        new APIError(
+          `API error: ${response.status}`,
+          response.status,
+          sanitizeErrorResponse(errorBody)
+        ),
+        "unpaid"
       );
     }
-    return this.parseChatResponse(response);
+    return this.parseUnpaidChatResponse(response);
+  }
+  /**
+   * Send a request that carries no payment, marking what it throws with its
+   * {@link RetryDisposition}: `"unpaid"` with a wallet; with an API key, see
+   * {@link accountErrorDisposition} (the request itself is billed).
+   */
+  async sendUnpaid(url, init) {
+    try {
+      return await this.fetchWithTimeout(url, init);
+    } catch (err) {
+      throw withDisposition(err, this.apiAuth ? accountErrorDisposition(err) : "unpaid");
+    }
+  }
+  /**
+   * Parse a response to a request that carried no payment: the free tier,
+   * or, with an API key, the billed request itself.
+   */
+  async parseUnpaidChatResponse(response) {
+    try {
+      return await this.parseChatResponse(response);
+    } catch (err) {
+      throw withDisposition(err, this.apiAuth ? "paid-or-in-doubt" : "unpaid");
+    }
   }
   /**
    * Handle 402 response: parse requirements, sign payment, retry.
+   *
+   * Anything thrown before the signed payment is sent is `"unpaid"`; anything
+   * after it, `"paid-or-in-doubt"` (see {@link RetryDisposition}).
    */
   async handlePaymentAndRetry(url, body, response) {
+    let signed;
+    try {
+      signed = await this.signFrom402(url, response);
+    } catch (err) {
+      throw withDisposition(err, "unpaid");
+    }
+    try {
+      return await this.sendPaid(url, body, signed.paymentPayload, signed.details);
+    } catch (err) {
+      throw withDisposition(err, "paid-or-in-doubt");
+    }
+  }
+  /** Read a 402's requirements and sign the exact payment for them. Sends nothing. */
+  async signFrom402(url, response) {
     let paymentHeader = response.headers.get("payment-required");
     if (!paymentHeader) {
       try {
@@ -5003,6 +5081,10 @@ var LLMClient = class _LLMClient {
         extensions
       }
     );
+    return { paymentPayload, details };
+  }
+  /** Send the signed payment and read the answer. The payment may settle from here on. */
+  async sendPaid(url, body, paymentPayload, details) {
     const retryResponse = await this.fetchWithTimeout(url, {
       method: "POST",
       headers: {
@@ -5139,25 +5221,46 @@ var LLMClient = class _LLMClient {
     const cached = this.preAuthCache.get(cacheKey2);
     const now = Date.now();
     if (cached && now - cached.cachedAt < _LLMClient.PRE_AUTH_TTL_MS) {
+      let signed;
       try {
-        const { paymentPayload: paymentPayload2, costUsd: costUsd2 } = await this.signPayment(cached.paymentHeader);
-        const preAuthResp = await this.fetchWithTimeout(url, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            "User-Agent": USER_AGENT,
-            "PAYMENT-SIGNATURE": paymentPayload2
-          },
-          body: JSON.stringify(body)
-        });
-        if (preAuthResp.status !== 402 && preAuthResp.ok) {
+        signed = await this.signPayment(cached.paymentHeader);
+      } catch {
+        this.preAuthCache.delete(cacheKey2);
+      }
+      if (signed) {
+        let preAuthResp;
+        try {
+          preAuthResp = await this.fetchWithTimeout(url, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              "User-Agent": USER_AGENT,
+              "PAYMENT-SIGNATURE": signed.paymentPayload
+            },
+            body: JSON.stringify(body)
+          });
+        } catch (err) {
+          this.preAuthCache.delete(cacheKey2);
+          throw withDisposition(err, "paid-or-in-doubt");
+        }
+        if (preAuthResp.ok) {
           this.sessionCalls += 1;
-          this.sessionTotalUsd += costUsd2;
+          this.sessionTotalUsd += signed.costUsd;
           return preAuthResp;
         }
         this.preAuthCache.delete(cacheKey2);
-      } catch {
-        this.preAuthCache.delete(cacheKey2);
+        if (preAuthResp.status !== 402) {
+          let errorBody;
+          try {
+            errorBody = await preAuthResp.json();
+          } catch {
+            errorBody = { error: "Request failed" };
+          }
+          throw withDisposition(
+            new APIError(`API error after payment: ${preAuthResp.status}`, preAuthResp.status, sanitizeErrorResponse(errorBody)),
+            "paid-or-in-doubt"
+          );
+        }
       }
     }
     const firstResp = await this.fetchWithTimeout(url, {
@@ -9226,11 +9329,11 @@ var WALLET_DIR = path4.join(os3.homedir(), ".blockrun");
 var SOLANA_WALLET_FILE = path4.join(WALLET_DIR, ".solana-session");
 async function createSolanaWallet() {
   const { Keypair } = await loadSolanaWeb3("Solana wallet operations");
-  const bs58 = await import("bs58");
+  const bs582 = await import("bs58");
   const keypair = Keypair.generate();
   return {
     address: keypair.publicKey.toBase58(),
-    privateKey: (bs58.default ?? bs58).encode(keypair.secretKey)
+    privateKey: (bs582.default ?? bs582).encode(keypair.secretKey)
   };
 }
 async function solanaKeyToBytes(privateKey) {
@@ -9268,8 +9371,8 @@ async function solanaKeyToBytes(privateKey) {
     return bytes;
   }
   try {
-    const bs58 = await import("bs58");
-    const bytes = (bs58.default ?? bs58).decode(key);
+    const bs582 = await import("bs58");
+    const bytes = (bs582.default ?? bs582).decode(key);
     if (bytes.length !== 64) {
       throw new Error(`Invalid Solana key length: expected 64 bytes, got ${bytes.length}`);
     }
@@ -9449,10 +9552,59 @@ async function getOrCreateSolanaWallet() {
 }
 
 // src/solana-batch.ts
+import { AsyncLocalStorage } from "async_hooks";
+import { randomUUID } from "crypto";
 import * as fs6 from "fs";
 import * as path5 from "path";
+import bs58 from "bs58";
 var BATCH_SCHEME = "batch-settlement";
 var BLOCKRUN_SOL_OPERATOR = "5YKPQUFjw5WQqhSUkEGKNNfYYVqnRRNbpYyL71qQ1vm3";
+var DEFAULT_BATCH_RATE_LIMIT = { maxAttempts: 3, maxWaitMs: 6e4 };
+var BatchPaymentUnresolvedError = class extends PaymentError {
+  /** The {@link SolanaBatchEvent.reason} of the `unresolved` event reported with it. */
+  reason;
+  /** The paying wallet's address. */
+  wallet;
+  /** The request id of the payment that may have been charged. */
+  requestId;
+  /** The channel it paid into. */
+  channelId;
+  /** What it carried. */
+  payloadKind;
+  /** HTTP status of the gateway's last answer to it, when there was one. */
+  status;
+  /** Whether it carried a deposit, which is now in doubt as well. */
+  depositInDoubt;
+  constructor(init) {
+    super(
+      `batch-settlement payment ${init.requestId ?? "<unknown>"} from wallet ${init.wallet} may have been charged and is not paid again${init.detail ? `: ${init.detail}` : ""}`
+    );
+    this.name = "BatchPaymentUnresolvedError";
+    withDisposition(this, "paid-or-in-doubt");
+    this.reason = init.reason;
+    this.wallet = init.wallet;
+    this.requestId = init.requestId;
+    this.channelId = init.channelId;
+    this.payloadKind = init.payloadKind;
+    this.status = init.status;
+    this.depositInDoubt = init.payloadKind === "open" || init.payloadKind === "top-up";
+    if (init.cause !== void 0) this.cause = init.cause;
+  }
+};
+var BatchCloseDeferredError = class extends BlockrunError {
+  reason;
+  /** The paying wallet's address. */
+  wallet;
+  /** The channels whose deposit is in doubt (`deposit_in_doubt`). */
+  channelIds;
+  constructor(init) {
+    super(`batch-settlement channel close deferred for wallet ${init.wallet}: ${init.detail}`);
+    this.name = "BatchCloseDeferredError";
+    this.reason = init.reason;
+    this.wallet = init.wallet;
+    this.channelIds = init.channelIds ?? [];
+  }
+};
 var INSTALL_HINT2 = "npm install @x402/core@~2.28.0 @x402/svm@~2.28.0 @solana/kit";
 async function load(pkg, importer) {
   try {
@@ -9502,6 +9654,10 @@ var FileChannelStorage = class {
     delete all[key];
     this.write(all);
   }
+  /** The keys of every stored channel. */
+  async keys() {
+    return Object.keys(this.read());
+  }
   /** Forget every channel in this file. */
   clear() {
     try {
@@ -9511,6 +9667,192 @@ var FileChannelStorage = class {
     }
   }
 };
+var MemoryChannelStorage = class {
+  records = /* @__PURE__ */ new Map();
+  async get(key) {
+    const raw = this.records.get(key);
+    return raw === void 0 ? void 0 : JSON.parse(raw);
+  }
+  async set(key, record) {
+    this.records.set(key, JSON.stringify(record));
+  }
+  async delete(key) {
+    this.records.delete(key);
+  }
+  async keys() {
+    return [...this.records.keys()];
+  }
+  clear() {
+    this.records.clear();
+  }
+};
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function intentProblem(key, intent) {
+  const atomic = (value) => typeof value === "string" && /^\d+$/.test(value);
+  if (!isPlainObject(intent)) return "not an object";
+  if (intent.key !== key || !key) return "key does not match its entry";
+  if (typeof intent.channelId !== "string" || !intent.channelId) return "channelId missing";
+  if (!isPlainObject(intent.channelConfig)) return "channelConfig missing";
+  if (intent.kind !== "open" && intent.kind !== "top-up") return "kind is neither open nor top-up";
+  if (!atomic(intent.cumulative)) return "cumulative is not an atomic amount";
+  if (!atomic(intent.expectDeposit)) return "expectDeposit is not an atomic amount";
+  if (intent.knownDeposit !== void 0 && !atomic(intent.knownDeposit)) return "knownDeposit is not an atomic amount";
+  if (intent.requestId !== void 0 && typeof intent.requestId !== "string") return "requestId is not a string";
+  if (intent.anchorHeight !== void 0 && (!Number.isSafeInteger(intent.anchorHeight) || intent.anchorHeight < 0)) {
+    return "anchorHeight is not a block height";
+  }
+  if (typeof intent.at !== "number" || !Number.isFinite(intent.at)) return "at is not a time";
+  return void 0;
+}
+function fsyncDirectory(dir) {
+  let fd;
+  try {
+    fd = fs6.openSync(dir, "r");
+    fs6.fsyncSync(fd);
+  } catch (err) {
+    const code = err.code;
+    if (!["EISDIR", "EPERM", "EACCES", "EINVAL", "ENOTSUP", "EBADF"].includes(code ?? "")) throw err;
+  } finally {
+    if (fd !== void 0) fs6.closeSync(fd);
+  }
+}
+var FileIntentJournal = class _FileIntentJournal {
+  constructor(file) {
+    this.file = file;
+  }
+  file;
+  durable = true;
+  /** The journal file for a channel store file: its full path plus `.deposit-intents`, one per store. */
+  static beside(channelFile) {
+    return new _FileIntentJournal(`${channelFile}.deposit-intents`);
+  }
+  /**
+   * Where earlier builds kept a store's journal: the store's name without
+   * `.json`, plus `.deposit-intents.json`. Two stores could share it
+   * (`/x/channels` and `/x/channels.json`), so its intents are moved by payer
+   * ({@link adoptLegacy}). No current journal path ever ends in `.json`, so
+   * this never names one.
+   */
+  static legacyBeside(channelFile) {
+    const base = path5.basename(channelFile).replace(/\.json$/i, "");
+    return path5.join(path5.dirname(channelFile), `${base}.deposit-intents.json`);
+  }
+  /**
+   * Move `payer`'s intents from a journal an earlier build wrote at
+   * `legacyFile` into this one, before this one is used: written here first
+   * (durably), then removed there (the file goes once empty). Intents of other
+   * payers are left where they are, for the store they belong to. An intent
+   * already here is kept (a migration interrupted between the two writes).
+   *
+   * @throws when the old journal cannot be read or is not valid, or holds an
+   *   intent naming no payer: the wallet then keeps batch off, as for an
+   *   unreadable journal, and nothing is dropped.
+   */
+  adoptLegacy(legacyFile, payer) {
+    if (legacyFile === this.file) return;
+    const legacy = new _FileIntentJournal(legacyFile);
+    const found = legacy.read();
+    const mine = [];
+    const others = {};
+    for (const [key, intent] of Object.entries(found)) {
+      const owner = intent.channelConfig.payer;
+      if (typeof owner !== "string") {
+        throw new Error(`deposit-intent journal ${legacyFile} holds an intent naming no payer (${JSON.stringify(key)}); move it by hand`);
+      }
+      if (owner === payer) mine.push(intent);
+      else others[key] = intent;
+    }
+    if (mine.length === 0) return;
+    const intents = this.read();
+    for (const intent of mine) intents[intent.key] ??= intent;
+    this.write(intents);
+    legacy.write(others);
+  }
+  /**
+   * The journaled intents. Only a missing file is an empty journal: anything
+   * else that is not a version-1 journal of well-formed intents throws, so a
+   * deposit in doubt is never lost to a damaged or unknown file (the wallet
+   * then keeps batch off, `deposit_journal_unreadable`).
+   */
+  read() {
+    let text;
+    try {
+      text = fs6.readFileSync(this.file, "utf8");
+    } catch (err) {
+      if (err.code === "ENOENT") return {};
+      throw err;
+    }
+    const invalid = (why) => new Error(`deposit-intent journal ${this.file} is not valid (${why})`);
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch (err) {
+      throw invalid(err instanceof Error ? err.message : String(err));
+    }
+    if (!isPlainObject(parsed)) throw invalid("not a JSON object");
+    if (parsed.version !== 1) throw invalid(`unsupported version ${JSON.stringify(parsed.version)}`);
+    const { intents } = parsed;
+    if (!isPlainObject(intents)) throw invalid("intents is not an object");
+    for (const [key, intent] of Object.entries(intents)) {
+      const why = intentProblem(key, intent);
+      if (why) throw invalid(`intent ${JSON.stringify(key)}: ${why}`);
+    }
+    return intents;
+  }
+  write(intents) {
+    const dir = path5.dirname(this.file);
+    fs6.mkdirSync(dir, { recursive: true, mode: 448 });
+    if (Object.keys(intents).length === 0) {
+      try {
+        fs6.unlinkSync(this.file);
+      } catch (err) {
+        if (err.code !== "ENOENT") throw err;
+        return;
+      }
+      fsyncDirectory(dir);
+      return;
+    }
+    const tmp = `${this.file}.${process.pid}.${randomUUID()}.tmp`;
+    const fd = fs6.openSync(tmp, "w", 384);
+    try {
+      fs6.writeSync(fd, JSON.stringify({ version: 1, intents }, null, 2));
+      fs6.fsyncSync(fd);
+    } finally {
+      fs6.closeSync(fd);
+    }
+    fs6.renameSync(tmp, this.file);
+    fsyncDirectory(dir);
+  }
+  list() {
+    return Object.values(this.read());
+  }
+  put(intent) {
+    const intents = this.read();
+    intents[intent.key] = intent;
+    this.write(intents);
+  }
+  remove(key) {
+    const intents = this.read();
+    if (!(key in intents)) return;
+    delete intents[key];
+    this.write(intents);
+  }
+};
+var MemoryIntentJournal = class {
+  durable = false;
+  intents = /* @__PURE__ */ new Map();
+  list() {
+    return [...this.intents.values()];
+  }
+  put(intent) {
+    this.intents.set(intent.key, { ...intent });
+  }
+  remove(key) {
+    this.intents.delete(key);
+  }
+};
 function processAlive(pid) {
   try {
     process.kill(pid, 0);
@@ -9519,71 +9861,438 @@ function processAlive(pid) {
     return err.code === "EPERM";
   }
 }
-var heldLocks = /* @__PURE__ */ new Set();
-var exitHookInstalled = false;
+var BATCH_REGISTRY = /* @__PURE__ */ Symbol.for("@blockrun/llm/batch-registry/v1");
+var registryHost = globalThis;
+var registry2 = registryHost[BATCH_REGISTRY] ??= {
+  wallets: /* @__PURE__ */ new Map(),
+  locks: /* @__PURE__ */ new Map(),
+  exitHook: false
+};
+var lockIds = registry2.lockIds ??= /* @__PURE__ */ new Map();
+function fileIdentity(file) {
+  try {
+    const stat = fs6.statSync(file);
+    return `${stat.dev}:${stat.ino}:${stat.mtimeMs}`;
+  } catch {
+    return void 0;
+  }
+}
+function lockPredatesProcess(lock) {
+  try {
+    return fs6.statSync(lock).mtimeMs < performance.timeOrigin;
+  } catch {
+    return false;
+  }
+}
+function holdsChannelFile(file) {
+  const token = registry2.locks.get(file);
+  if (!token) return false;
+  const lock = `${file}.lock`;
+  if (!ownsLock(lock, token)) return false;
+  const id = lockIds.get(file);
+  return id === void 0 || fileIdentity(lock) === id;
+}
+function lockTokenFile(lock) {
+  return `${lock}.owner`;
+}
+function readLockOwner(lock) {
+  let raw;
+  try {
+    raw = fs6.readFileSync(lock, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return void 0;
+    throw err;
+  }
+  let pid = Number(raw.trim());
+  if (!Number.isInteger(pid)) {
+    try {
+      const parsed = JSON.parse(raw);
+      pid = parsed && typeof parsed === "object" && Number.isInteger(parsed.pid) ? parsed.pid : 0;
+    } catch {
+      pid = 0;
+    }
+  }
+  return { pid, raw };
+}
+function readLockToken(lock) {
+  try {
+    const parsed = JSON.parse(fs6.readFileSync(lockTokenFile(lock), "utf8"));
+    return parsed && typeof parsed === "object" && typeof parsed.token === "string" ? parsed.token : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function ownsLock(lock, token) {
+  return readLockOwner(lock)?.pid === process.pid && readLockToken(lock) === token;
+}
+function releaseHeldLocks() {
+  for (const [file, token] of registry2.locks) {
+    const lock = `${file}.lock`;
+    try {
+      if (!ownsLock(lock, token)) continue;
+      fs6.unlinkSync(lockTokenFile(lock));
+      fs6.unlinkSync(lock);
+    } catch {
+    }
+  }
+}
 function lockChannelFile(file) {
-  if (heldLocks.has(file)) return void 0;
+  if (registry2.locks.has(file)) return void 0;
   const lock = `${file}.lock`;
   fs6.mkdirSync(path5.dirname(lock), { recursive: true, mode: 448 });
+  const token = randomUUID();
   for (let attempt = 0; attempt < 2; attempt += 1) {
+    const tmp = `${lock}.${process.pid}.${token}.tmp`;
     try {
-      fs6.writeFileSync(lock, String(process.pid), { flag: "wx", mode: 384 });
-      heldLocks.add(file);
-      if (!exitHookInstalled) {
-        exitHookInstalled = true;
-        process.once("exit", () => {
-          for (const held of heldLocks) {
-            try {
-              fs6.unlinkSync(`${held}.lock`);
-            } catch {
-            }
-          }
-        });
+      fs6.writeFileSync(tmp, String(process.pid), { mode: 384 });
+      try {
+        fs6.linkSync(tmp, lock);
+      } catch (err) {
+        const code = err.code;
+        if (code !== "EPERM" && code !== "ENOTSUP" && code !== "EXDEV" && code !== "EOPNOTSUPP") throw err;
+        fs6.writeFileSync(lock, String(process.pid), { flag: "wx", mode: 384 });
+      }
+      try {
+        writeLockToken(lock, token);
+      } catch (err) {
+        try {
+          fs6.unlinkSync(lock);
+        } catch {
+        }
+        throw err;
+      }
+      registry2.locks.set(file, token);
+      const id = fileIdentity(lock);
+      if (id) lockIds.set(file, id);
+      else lockIds.delete(file);
+      if (!registry2.exitHook) {
+        registry2.exitHook = true;
+        process.once("exit", releaseHeldLocks);
       }
       return void 0;
     } catch (err) {
       if (err.code !== "EEXIST") throw err;
+    } finally {
+      try {
+        fs6.unlinkSync(tmp);
+      } catch {
+      }
+    }
+    const owner = readLockOwner(lock);
+    if (!owner) continue;
+    if (owner.pid === process.pid) {
+      if (!lockPredatesProcess(lock)) return process.pid;
+    } else if (owner.pid > 0 && processAlive(owner.pid)) {
+      return owner.pid;
     }
-    const owner = Number(fs6.readFileSync(lock, "utf8").trim());
-    if (Number.isInteger(owner) && owner > 0 && owner !== process.pid && processAlive(owner)) return owner;
     try {
-      fs6.unlinkSync(lock);
+      if (readLockOwner(lock)?.raw === owner.raw) fs6.unlinkSync(lock);
     } catch {
     }
   }
   return -1;
 }
+function writeLockToken(lock, token) {
+  const sidecar = lockTokenFile(lock);
+  const tmp = `${sidecar}.${process.pid}.${token}.tmp`;
+  try {
+    fs6.writeFileSync(tmp, JSON.stringify({ pid: process.pid, token }), { mode: 384 });
+    fs6.renameSync(tmp, sidecar);
+  } finally {
+    try {
+      fs6.unlinkSync(tmp);
+    } catch {
+    }
+  }
+}
 function pendingDeposit(pending) {
   const entries = Array.isArray(pending) ? pending : [pending];
   return entries.some(
     (entry) => entry?.payment?.payload?.type === "deposit"
   );
 }
-function dropOrphanedPending(storage) {
-  return {
-    get: async (key) => {
-      const record = await storage.get(key);
-      if (!record?.pending || record.channelConfig?.voucherSigner !== "server") return record;
-      if (!record.hasConfirmedState || pendingDeposit(record.pending)) {
-        await storage.delete(key);
-        return void 0;
-      }
+var ChannelResyncRequiredError = class extends Error {
+  constructor(channelId) {
+    super(`batch-settlement channel ${channelId ?? "<unknown>"} needs a chain re-read before it is used`);
+    this.channelId = channelId;
+    this.name = "ChannelResyncRequiredError";
+  }
+  channelId;
+};
+function isResyncRequired(err) {
+  return err instanceof Error && err.name === "ChannelResyncRequiredError";
+}
+function parseAtomic(value) {
+  return typeof value === "string" && /^\d+$/.test(value) ? BigInt(value) : 0n;
+}
+function confirmedCumulative(record, channelId) {
+  if (!record || record.channelId !== channelId) return 0n;
+  return record.pending === void 0 || record.hasConfirmedState ? parseAtomic(record.chargedCumulativeAmount) : 0n;
+}
+var ChannelBook = class {
+  constructor(base, onUnverified = () => {
+  }) {
+    this.base = base;
+    this.onUnverified = onUnverified;
+  }
+  base;
+  onUnverified;
+  seen = /* @__PURE__ */ new Map();
+  async get(key) {
+    const record = await this.base.get(key);
+    if (record) this.seen.set(key, record);
+    if (!record?.pending || record.channelConfig?.voucherSigner !== "server") return record;
+    if (record.hasConfirmedState && !pendingDeposit(record.pending)) {
       const { pending: _pending, hasConfirmedState: _confirmed, ...confirmed } = record;
-      await storage.set(key, confirmed);
+      await this.set(key, confirmed);
       return confirmed;
-    },
-    set: (key, record) => storage.set(key, record),
-    delete: (key) => storage.delete(key)
+    }
+    if (typeof record.channelId === "string") {
+      const pendingEntries = Array.isArray(record.pending) ? record.pending : [record.pending];
+      const inDoubt = pendingEntries.find((entry) => entry?.payment?.payload?.type === "deposit");
+      this.onUnverified({
+        key,
+        channelId: record.channelId,
+        channelConfig: record.channelConfig,
+        cumulative: record.hasConfirmedState ? parseAtomic(record.chargedCumulativeAmount) : 0n,
+        ...record.hasConfirmedState ? { knownDeposit: parseAtomic(record.deposit) } : {},
+        ...inDoubt ? { expectDeposit: parseAtomic(inDoubt.deposit) } : {},
+        reason: "orphaned_deposit"
+      });
+    }
+    throw new ChannelResyncRequiredError(record.channelId);
+  }
+  /**
+   * Store a record, and only once it is stored remember it as the last one
+   * seen. If storing fails (say, while the scheme saves a reconciled
+   * receipt), the scheme reports the receipt unreconciled, and the SDK must
+   * still see the state from before it: `distrust()` adds that call's charge
+   * to it, and a remembered post-receipt cumulative would count it twice.
+   */
+  async set(key, record) {
+    await this.base.set(key, record);
+    this.seen.set(key, record);
+  }
+  async delete(key) {
+    await this.base.delete(key);
+  }
+  /** The keys of every stored channel. */
+  async keys() {
+    return await this.base.keys?.() ?? [];
+  }
+  /** The last record seen for a channel, even one the scheme has deleted since. */
+  find(channelId) {
+    for (const [key, record] of this.seen) {
+      if (record.channelId === channelId) return { key, record };
+    }
+    return void 0;
+  }
+  clear() {
+    this.seen.clear();
+    this.base.clear?.();
+  }
+  /** Forget one channel: its stored record and the last record seen for it. An emptied store is removed. */
+  async forget(key) {
+    this.seen.delete(key);
+    await this.base.delete(key);
+    if ((await this.keys()).length === 0) this.clear();
+  }
+};
+var PAYMENT_CHANNELS_PROGRAM_ID = "CHNLxYvVA28MJP9PrFuDXccuoGXAx7jBacfLEkahyGsX";
+var CHANNEL = {
+  size: 256,
+  rentPayer: 216,
+  discriminator: 1,
+  status: 3,
+  deposit: 12,
+  settled: 20,
+  closureStartedAt: 36,
+  payer: 88,
+  authorizedSigner: 152,
+  mint: 184
+};
+function decodeChannelAccount(owner, data) {
+  if (owner !== PAYMENT_CHANNELS_PROGRAM_ID || data.length < CHANNEL.size || data[0] !== CHANNEL.discriminator) {
+    return void 0;
+  }
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const key = (offset) => bs58.encode(data.subarray(offset, offset + 32));
+  return {
+    deposit: view.getBigUint64(CHANNEL.deposit, true),
+    settled: view.getBigUint64(CHANNEL.settled, true),
+    open: data[CHANNEL.status] === 0 && view.getBigInt64(CHANNEL.closureStartedAt, true) === 0n,
+    payer: key(CHANNEL.payer),
+    authorizedSigner: key(CHANNEL.authorizedSigner),
+    mint: key(CHANNEL.mint)
+  };
+}
+var ChannelUnreadableError = class extends Error {
+  constructor(channelId, why) {
+    super(`account ${channelId} is on chain but is not a readable payment channel (${why})`);
+    this.name = "ChannelUnreadableError";
+  }
+};
+var ChannelLayoutError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "ChannelLayoutError";
+  }
+};
+async function readChannelAccount(rpcUrl, channelId, rpcHeaders, options = {}) {
+  await checkChannelLayout();
+  const config = { encoding: "base64", commitment: "finalized" };
+  if (options.minContextSlot !== void 0) config.minContextSlot = options.minContextSlot;
+  const response = await fetch(rpcUrl, {
+    method: "POST",
+    headers: { ...rpcHeaders, "Content-Type": "application/json" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "getAccountInfo", params: [channelId, config] }),
+    signal: AbortSignal.timeout(15e3),
+    // rpcHeaders may carry an API key: never let a redirect take it elsewhere.
+    redirect: "error"
+  });
+  if (!response.ok) throw new Error(`getAccountInfo answered HTTP ${response.status}`);
+  const body = await response.json();
+  if (body.error) throw new Error(`getAccountInfo failed: ${body.error.message ?? JSON.stringify(body.error)}`);
+  if (!body.result || typeof body.result !== "object" || !("value" in body.result)) {
+    throw new Error("getAccountInfo returned no result");
+  }
+  const value = body.result.value;
+  if (value === null) return void 0;
+  if (!value || typeof value !== "object") throw new ChannelUnreadableError(channelId, "malformed account value");
+  if (!Array.isArray(value.data) || typeof value.data[0] !== "string" || value.data[1] !== "base64") {
+    throw new ChannelUnreadableError(channelId, "unsupported data encoding");
+  }
+  const channel = decodeChannelAccount(value.owner, Buffer.from(value.data[0], "base64"));
+  if (!channel) throw new ChannelUnreadableError(channelId, "wrong owner or layout");
+  return channel;
+}
+async function rpcRequest(rpcUrl, method, params, rpcHeaders) {
+  const response = await fetch(rpcUrl, {
+    method: "POST",
+    headers: { ...rpcHeaders, "Content-Type": "application/json" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+    signal: AbortSignal.timeout(15e3),
+    // rpcHeaders may carry an API key: never let a redirect take it elsewhere.
+    redirect: "error"
+  });
+  if (!response.ok) throw new Error(`${method} answered HTTP ${response.status}`);
+  const body = await response.json();
+  if (body.error) throw new Error(`${method} failed: ${body.error.message ?? JSON.stringify(body.error)}`);
+  if (body.result === void 0 || body.result === null) throw new Error(`${method} returned no result`);
+  return body.result;
+}
+function rpcInteger(value, what) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(`${what} is not a block height or slot`);
+  return value;
+}
+var layoutChecked;
+function checkChannelLayout() {
+  layoutChecked ??= (async () => {
+    const svm = await load("@x402/svm", () => import("@x402/svm")).catch((err) => {
+      throw new ChannelLayoutError(
+        `cannot check the payment-channel account layout: ${err instanceof Error ? err.message : String(err)}`,
+        { cause: err }
+      );
+    });
+    if (svm.CHANNEL_ACCOUNT_SIZE !== BigInt(CHANNEL.size) || svm.CHANNEL_RENT_PAYER_OFFSET !== BigInt(CHANNEL.rentPayer)) {
+      throw new ChannelLayoutError("@x402/svm changed the payment-channel account layout; this SDK cannot read channels from it");
+    }
+  })();
+  layoutChecked.catch(() => {
+    layoutChecked = void 0;
+  });
+  return layoutChecked;
+}
+var LANDING_MARGIN_BLOCKS = 300;
+function maxOf(a, b) {
+  if (a === void 0) return b;
+  if (b === void 0) return a;
+  return a > b ? a : b;
+}
+var ResyncError = class extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.reason = reason;
+    this.name = "ResyncError";
+  }
+  reason;
+};
+function payloadChannelId(payload) {
+  return payload.payload?.authorization?.channelId ?? payload.payload?.voucher?.channelId;
+}
+function clientSignedBatch(accept) {
+  return accept.scheme === BATCH_SCHEME && accept.extra?.voucherSigner !== "server";
+}
+function batchUnavailable(paymentRequired) {
+  const batch = (paymentRequired.accepts ?? []).filter((accept) => accept.scheme === BATCH_SCHEME);
+  if (batch.length === 0) return { reason: "not_offered" };
+  if (!batch.every(clientSignedBatch)) return void 0;
+  return {
+    reason: "client_signed_not_supported",
+    detail: "the 402 offers only client-signed batch-settlement accepts; this SDK pays batch only into server-signed (operator) channels"
   };
 }
-function offersBatch(paymentRequired) {
-  return (paymentRequired.accepts ?? []).some((accept) => accept.scheme === BATCH_SCHEME);
+function withoutClientSignedBatch(paymentRequired) {
+  const accepts = paymentRequired.accepts ?? [];
+  return accepts.some(clientSignedBatch) ? { ...paymentRequired, accepts: accepts.filter((accept) => !clientSignedBatch(accept)) } : paymentRequired;
+}
+function trustedBatchAccepts(paymentRequired, operators) {
+  return (paymentRequired.accepts ?? []).filter((candidate) => {
+    const extra = candidate.extra;
+    return candidate.scheme === BATCH_SCHEME && extra?.voucherSigner === "server" && operators.includes(extra.operator);
+  });
+}
+function trustedBatchAccept(paymentRequired, operators) {
+  return trustedBatchAccepts(paymentRequired, operators)[0];
 }
 function atomicToUsd(amount) {
-  return amount !== void 0 && /^\d+$/.test(amount) ? Number(amount) / 1e6 : void 0;
+  return typeof amount === "string" && /^\d+$/.test(amount) ? Number(amount) / 1e6 : void 0;
 }
-async function isBatchRefusal(response) {
-  if (response.status === 402) return "payment_required";
+function chargedUsd(getReceipt) {
+  let receipt;
+  try {
+    receipt = getReceipt();
+  } catch {
+    return 0;
+  }
+  return atomicToUsd(receipt?.extra?.chargedAmount) ?? atomicToUsd(receipt?.amount) ?? 0;
+}
+function rebuiltCharge(settled, payload) {
+  if (settled?.success !== true) return 0n;
+  const charged = parseAtomic(typeof settled.extra?.chargedAmount === "string" ? settled.extra.chargedAmount : settled.amount);
+  const ceiling = parseAtomic(payload.accepted?.amount);
+  return charged > ceiling ? ceiling : charged;
+}
+function confirmedState(record) {
+  if (!record || !(record.pending === void 0 || record.hasConfirmedState)) return void 0;
+  return { cumulative: parseAtomic(record.chargedCumulativeAmount), deposit: parseAtomic(record.deposit) };
+}
+function recordAdvanced(before, after, payload, receipt) {
+  const deposited = payload.payload?.type === "deposit" ? parseAtomic(payload.payload.deposit?.amount) : 0n;
+  const charged = rebuiltCharge(receipt, payload);
+  if (deposited === 0n && charged === 0n) return true;
+  if (!after) return false;
+  const prior = before ?? { cumulative: 0n, deposit: 0n };
+  return after.deposit >= prior.deposit + deposited && after.cumulative >= prior.cumulative + charged;
+}
+var BATCH_REFUSALS = /* @__PURE__ */ new Set([
+  "batch_payer_not_allowed",
+  "batch_payer_not_admitted",
+  "batch_admission_paused",
+  "batch_server_signed_only",
+  "batch_unavailable",
+  "batch_channel_limit",
+  "PAYMENT_VERIFICATION_UNAVAILABLE"
+]);
+var PRE_REQUEST_REFUSALS = /* @__PURE__ */ new Set([
+  "batch_payer_not_allowed",
+  "batch_payer_not_admitted",
+  "batch_admission_paused",
+  "batch_server_signed_only",
+  "batch_unavailable",
+  "batch_channel_limit"
+]);
+async function batchRefusal(response) {
   if (![400, 403, 409, 503].includes(response.status)) return void 0;
   let body;
   try {
@@ -9592,20 +10301,254 @@ async function isBatchRefusal(response) {
     return void 0;
   }
   const { error, code } = body ?? {};
-  if (code === "PAYMENT_VERIFICATION_UNAVAILABLE") return code;
-  return typeof error === "string" && error.startsWith("batch_") ? error : void 0;
+  for (const value of [code, error]) {
+    if (typeof value === "string" && BATCH_REFUSALS.has(value)) return value;
+  }
+  return void 0;
 }
-var wallets = /* @__PURE__ */ new Map();
-var SolanaBatchPayer = class {
-  constructor(init) {
-    this.init = init;
-    const { operators } = init.options;
-    if (!Array.isArray(operators) || operators.length === 0 || operators.some((o) => typeof o !== "string" || !o)) {
-      throw new Error("batch.operators must list at least one base58 operator public key");
+async function duplicateAnswer(response) {
+  const codes = [];
+  try {
+    const body = await response.clone().json();
+    if (body && typeof body === "object") codes.push(body.error, body.code, body.reason, body.invalidReason);
+  } catch {
+  }
+  const header = response.headers.get("PAYMENT-REQUIRED");
+  if (header) {
+    try {
+      const challenge = parsePaymentRequired(header);
+      codes.push(challenge.error, challenge.invalidReason);
+    } catch {
+    }
+  }
+  for (const code of codes) {
+    if (typeof code === "string" && /duplicate/i.test(code)) return code;
+  }
+  return void 0;
+}
+function cleanRefusalReceipt(receipt) {
+  if (receipt === void 0) return true;
+  return receipt.success === false && !receipt.transaction && receipt.errorReason !== "settlement_pending";
+}
+async function afterPaymentError(response) {
+  let body;
+  try {
+    body = await response.clone().json();
+  } catch {
+    body = { error: "Request failed" };
+  }
+  return withDisposition(
+    new APIError(`API error after payment: ${response.status}`, response.status, sanitizeErrorResponse(body)),
+    "paid-or-in-doubt"
+  );
+}
+function cancelledReceipt(receipt) {
+  return receipt?.success === false && receipt.errorReason === "batch_cancelled" && !receipt.transaction;
+}
+async function cancelledError(response) {
+  let body;
+  try {
+    body = await response.clone().json();
+  } catch {
+    body = { error: "Request failed" };
+  }
+  return withDisposition(new APIError(`API error: ${response.status}`, response.status, sanitizeErrorResponse(body)), "unpaid");
+}
+function describeReceipt(receipt) {
+  if (!receipt) return "no receipt";
+  const parts = [`success=${String(receipt.success)}`];
+  if (receipt.errorReason) parts.push(`errorReason=${receipt.errorReason}`);
+  if (receipt.transaction) parts.push(`transaction=${receipt.transaction}`);
+  return `receipt ${parts.join(" ")}`;
+}
+var MAX_RETRY_AFTER_MS = 24 * 60 * 60 * 1e3;
+function parseRetryAfter(value, now = Date.now()) {
+  const text = value?.trim();
+  if (!text) return void 0;
+  let ms;
+  if (/^\d+(\.\d+)?$/.test(text)) {
+    ms = Math.round(Number(text) * 1e3);
+  } else {
+    const at = Date.parse(text);
+    if (Number.isNaN(at)) return void 0;
+    ms = Math.max(0, at - now);
+  }
+  return Number.isFinite(ms) && ms <= MAX_RETRY_AFTER_MS ? ms : void 0;
+}
+var NOT_BROADCAST_429 = /* @__PURE__ */ new Set([
+  "batch_account_channel_capacity_exhausted",
+  "batch_channel_capacity_exhausted",
+  "batch_deposit_rate_limited"
+]);
+function provesNothingBroadcast(receipt) {
+  return receipt?.success === false && !receipt.transaction && typeof receipt.errorReason === "string" && NOT_BROADCAST_429.has(receipt.errorReason);
+}
+function backoffDelay(attempt) {
+  const base = 1e3 * 2 ** Math.max(0, attempt - 1);
+  return Math.round(base * (0.75 + Math.random() * 0.5));
+}
+async function rateLimitReason(response, settled) {
+  let body;
+  try {
+    body = await response.clone().json();
+  } catch {
+    body = void 0;
+  }
+  const fields = body ?? {};
+  for (const value of [fields.errorReason, fields.error, fields.code, fields.reason, settled?.errorReason]) {
+    if (typeof value === "string" && value) return value;
+  }
+  return void 0;
+}
+function creationFailure(err) {
+  const detail = err instanceof Error ? err.message : String(err);
+  if (err instanceof Error && err.name === "UntrustedOperatorError") return { reason: "untrusted_operator", detail };
+  if (detail.includes("serverSignedChannelsPolicy maxDeposit")) return { reason: "deposit_over_cap", detail };
+  if (detail.includes("has a pending request")) return { reason: "channel_pending", detail };
+  if (detail.includes("requires the optional peer dependency")) return { reason: "peer_dependency_missing", detail };
+  return { reason: "payment_creation_failed", detail };
+}
+function logValue(value) {
+  const text = String(value);
+  return /^[\w.:/@+-]+$/.test(text) ? text : JSON.stringify(text);
+}
+function formatEvent(event) {
+  const fields = [
+    ["event", event.type],
+    ["reason", event.reason],
+    ["status", event.status],
+    ["errorReason", event.errorReason],
+    ["retryAfterMs", event.retryAfterMs],
+    ["attempt", event.attempt],
+    ["wallet", event.wallet],
+    ["next", event.type === "fallback" ? "exact" : event.type === "backoff" ? "retry" : event.type === "unresolved" ? "raise" : void 0],
+    ["detail", event.detail]
+  ];
+  const parts = fields.filter(([, v]) => v !== void 0 && v !== "").map(([k, v]) => `${k}=${logValue(v)}`);
+  return `[@blockrun/llm] batch-settlement ${parts.join(" ")}`;
+}
+var realSleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+var sleep2 = realSleep;
+var warnedNoSizer = false;
+function channelKeyOf(requirements) {
+  const accept = requirements;
+  const extra = accept?.extra ?? {};
+  if (typeof extra.feePayer !== "string" || typeof extra.withdrawDelay !== "number") return void 0;
+  return [
+    accept.network,
+    accept.asset,
+    accept.payTo,
+    extra.feePayer,
+    extra.withdrawDelay,
+    extra.receiverAuthorizer ?? "",
+    extra.voucherSigner ?? "client",
+    extra.operator ?? ""
+  ].join(":");
+}
+function capOutstandingEscrow(scheme, wallet) {
+  const target = scheme;
+  const original = target.resolveDepositAmount;
+  if (typeof original !== "function") {
+    if (!warnedNoSizer) {
+      warnedNoSizer = true;
+      console.error(
+        "[@blockrun/llm] batch-settlement: this @x402/svm does not expose resolveDepositAmount; maxDeposit caps lifetime deposits"
+      );
+    }
+    return;
+  }
+  target.resolveDepositAmount = function(requirements, requestAmount, needed, context, trust, existingDeposit) {
+    const topUp = wallet.topUp;
+    const widened = topUp && existingDeposit > 0n && existingDeposit === topUp.deposit && channelKeyOf(requirements) === topUp.key && typeof trust?.maxDeposit === "bigint" ? { ...trust, maxDeposit: trust.maxDeposit + topUp.settled } : trust;
+    return original.call(this, requirements, requestAmount, needed, context, widened, existingDeposit);
+  };
+}
+var RPC_SCOPE_STORE = /* @__PURE__ */ Symbol.for("@blockrun/llm/batch-rpc-scope/v1");
+var RPC_HEADER_HOOK = /* @__PURE__ */ Symbol.for("@blockrun/llm/batch-rpc-headers/v1");
+var sharedGlobal = globalThis;
+var rpcScope = sharedGlobal[RPC_SCOPE_STORE] ??= new AsyncLocalStorage();
+function requestUrl(input) {
+  return typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+}
+function installRpcHeaderHook() {
+  const current = globalThis.fetch;
+  if (current[RPC_HEADER_HOOK]) return;
+  const hooked = (input, init) => {
+    const scope = rpcScope.getStore();
+    if (!scope || requestUrl(input) !== scope.url) return current(input, init);
+    const headers = new Headers(input instanceof Request ? input.headers : void 0);
+    new Headers(scope.headers).forEach((value, name) => headers.set(name, value));
+    new Headers(init?.headers).forEach((value, name) => headers.set(name, value));
+    return current(input, { ...init, headers, redirect: "error" });
+  };
+  hooked[RPC_HEADER_HOOK] = true;
+  globalThis.fetch = hooked;
+}
+function addResyncTarget(wallet, target) {
+  const existing = wallet.resyncs.get(target.key);
+  if (!existing) {
+    wallet.resyncs.set(target.key, target);
+    return;
+  }
+  wallet.resyncs.set(target.key, {
+    ...existing,
+    channelConfig: target.channelConfig,
+    cumulative: maxOf(existing.cumulative, target.cumulative) ?? 0n,
+    expectDeposit: maxOf(existing.expectDeposit, target.expectDeposit),
+    knownDeposit: maxOf(existing.knownDeposit, target.knownDeposit),
+    anchorHeight: existing.anchorHeight === void 0 || target.anchorHeight === void 0 ? existing.anchorHeight ?? target.anchorHeight : Math.max(existing.anchorHeight, target.anchorHeight)
+  });
+}
+function intentTarget(intent) {
+  return {
+    key: intent.key,
+    channelId: intent.channelId,
+    channelConfig: intent.channelConfig,
+    cumulative: parseAtomic(intent.cumulative),
+    expectDeposit: parseAtomic(intent.expectDeposit),
+    ...intent.knownDeposit !== void 0 ? { knownDeposit: parseAtomic(intent.knownDeposit) } : {},
+    ...intent.anchorHeight !== void 0 ? { anchorHeight: intent.anchorHeight } : {},
+    reason: "orphaned_deposit"
+  };
+}
+var SolanaBatchPayer = class {
+  constructor(init) {
+    this.init = init;
+    const { operators, rateLimit } = init.options;
+    if (!Array.isArray(operators) || operators.length === 0 || operators.some((o) => typeof o !== "string" || !o)) {
+      throw new Error("batch.operators must list at least one base58 operator public key");
+    }
+    this.maxAttempts = rateLimit?.maxAttempts ?? DEFAULT_BATCH_RATE_LIMIT.maxAttempts;
+    this.maxWaitMs = rateLimit?.maxWaitMs ?? DEFAULT_BATCH_RATE_LIMIT.maxWaitMs;
+    if (!Number.isInteger(this.maxAttempts) || this.maxAttempts < 1) {
+      throw new Error("batch.rateLimit.maxAttempts must be an integer >= 1");
+    }
+    if (!Number.isFinite(this.maxWaitMs) || this.maxWaitMs < 0) {
+      throw new Error("batch.rateLimit.maxWaitMs must be a finite number of ms >= 0");
     }
   }
   init;
   state;
+  maxAttempts;
+  maxWaitMs;
+  counters = {
+    fallbacks: 0,
+    fallbacksByReason: {},
+    backoffs: 0,
+    retries: 0,
+    recoveries: 0,
+    resyncs: 0,
+    unresolved: 0,
+    unresolvedByReason: {}
+  };
+  /** A copy of this client's batch counters. */
+  stats() {
+    return {
+      ...this.counters,
+      fallbacksByReason: { ...this.counters.fallbacksByReason },
+      unresolvedByReason: { ...this.counters.unresolvedByReason }
+    };
+  }
   async storeFile() {
     const { channelStore } = this.init.options;
     if (channelStore === false) return void 0;
@@ -9621,20 +10564,63 @@ var SolanaBatchPayer = class {
       const address = await this.init.address();
       const file = await this.storeFile();
       const { operators, maxDeposit } = this.init.options;
-      const config = JSON.stringify([[...operators].sort(), String(maxDeposit ?? ""), file ?? null, this.init.rpcUrl]);
-      const existing = wallets.get(address);
+      const headers = Object.entries(this.init.rpcHeaders ?? {}).sort(([a], [b]) => a.localeCompare(b));
+      const config = JSON.stringify([[...operators].sort(), String(maxDeposit ?? ""), file ?? null, this.init.rpcUrl, headers]);
+      const existing = registry2.wallets.get(address);
       if (existing) {
-        return existing.config === config ? existing : "another client in this process uses this wallet with different batch options";
+        return existing.config === config ? existing : {
+          reason: "wallet_config_conflict",
+          detail: "another client in this process uses this wallet with different batch options"
+        };
       }
       if (file) {
         const owner = lockChannelFile(file);
-        if (owner !== void 0) return `channel store ${file} is in use by process ${owner}`;
+        if (owner !== void 0) {
+          return {
+            reason: "channel_store_locked",
+            detail: owner === process.pid ? `channel store ${file} is in use by another copy of @blockrun/llm in this process (or by a process that had this pid and died: remove ${file}.lock if nothing uses it)` : `channel store ${file} is in use by process ${owner}`
+          };
+        }
       }
-      const created = { config, busy: false, warned: /* @__PURE__ */ new Set() };
-      wallets.set(address, created);
+      const resyncs = /* @__PURE__ */ new Map();
+      const base = file ? new FileChannelStorage(file) : new MemoryChannelStorage();
+      const book = new ChannelBook(base, (target) => addResyncTarget(created, target));
+      const intents = file ? FileIntentJournal.beside(file) : new MemoryIntentJournal();
+      let journaled;
+      try {
+        if (file) intents.adoptLegacy(FileIntentJournal.legacyBeside(file), address);
+        journaled = intents.list();
+      } catch (err) {
+        return {
+          reason: "deposit_journal_unreadable",
+          detail: `cannot read ${intents.file}: ${err instanceof Error ? err.message : String(err)}`
+        };
+      }
+      const created = {
+        config,
+        busy: false,
+        cooldownUntil: 0,
+        active: 0,
+        ...file ? { file } : {},
+        book,
+        resyncs,
+        intents,
+        closes: 0
+      };
+      for (const intent of journaled) addResyncTarget(created, intentTarget(intent));
+      registry2.wallets.set(address, created);
       return created;
     })();
-    return this.state;
+    const state = this.state;
+    state.then(
+      (result) => {
+        if ("reason" in result && result.reason !== "wallet_config_conflict" && this.state === state) this.state = void 0;
+      },
+      () => {
+        if (this.state === state) this.state = void 0;
+      }
+    );
+    return state;
   }
   build(wallet) {
     wallet.client ??= (async () => {
@@ -9644,21 +10630,33 @@ var SolanaBatchPayer = class {
         load("@solana/kit", () => import("@solana/kit"))
       ]);
       const signer = await kit.createKeyPairSignerFromBytes(await this.init.secretKey());
-      const file = await this.storeFile();
-      const storage = file ? dropOrphanedPending(new FileChannelStorage(file)) : void 0;
       const scheme = new svm.BatchSvmScheme(signer, {
         rpcUrl: this.init.rpcUrl,
         serverSignedChannelsPolicy: {
           allowedOperators: this.init.options.operators,
           maxDeposit: this.init.options.maxDeposit ?? svm.DEFAULT_SERVER_SIGNED_MAX_DEPOSIT
         },
-        ...storage ? { channelStorage: storage } : {}
+        // Always a store, memory included: a record the SDK repairs from the
+        // chain survives the scheme being rebuilt to pick it up.
+        channelStorage: wallet.book
       });
+      capOutstandingEscrow(scheme, wallet);
       const client = new core.x402Client().register("solana:*", scheme).registerPolicy(scheme.paymentPolicy);
       client.setSpendControls({ maxAmountPerPayment: false });
+      const raw = new core.x402HTTPClient(client);
+      const http = {
+        getPaymentSettleResponse: (getHeader) => raw.getPaymentSettleResponse(getHeader),
+        createPaymentPayload: (paymentRequired) => this.withRpcHeaders(() => raw.createPaymentPayload(paymentRequired)),
+        encodePaymentSignatureHeader: (payload) => raw.encodePaymentSignatureHeader(payload),
+        processPaymentResult: (payload, getHeader, status2) => this.withRpcHeaders(() => raw.processPaymentResult(payload, getHeader, status2))
+      };
+      const loader = scheme.loadChannel;
       return {
-        http: new core.x402HTTPClient(client),
-        refund: (url) => scheme.refund(url)
+        http,
+        refund: (url, requirements) => this.withRpcHeaders(() => scheme.refund(url, { requirements })),
+        load: async (key) => {
+          if (typeof loader === "function") await loader.call(scheme, key);
+        }
       };
     })();
     wallet.client.catch(() => {
@@ -9666,73 +10664,863 @@ var SolanaBatchPayer = class {
     });
     return wallet.client;
   }
+  /** Run a scheme call so its RPC requests carry this client's `rpcHeaders`. */
+  withRpcHeaders(call) {
+    const headers = this.init.rpcHeaders;
+    if (!headers || Object.keys(headers).length === 0) return call();
+    installRpcHeaderHook();
+    return rpcScope.run({ url: this.init.rpcUrl, headers }, call);
+  }
   /**
-   * Drop everything this wallet knows about its channel, on disk and in
-   * memory. The next call rebuilds the scheme, which reads the channel's real
-   * state (deposit, open or closed) from the chain.
+   * Drop everything this wallet knows about one channel, on disk and in
+   * memory, leaving its other channels' records alone. The scheme is rebuilt
+   * on the next call, without the closed channel in its memory.
    */
-  async forget(wallet) {
+  async forget(wallet, key) {
     wallet.client = void 0;
-    const file = await this.storeFile();
-    if (file) new FileChannelStorage(file).clear();
+    wallet.resyncs.delete(key);
+    await wallet.book.forget(key);
+    this.forgetIntent(wallet, key);
   }
-  warn(wallet, reason) {
-    if (wallet?.warned.has(reason)) return;
-    wallet?.warned.add(reason);
-    console.error(`[@blockrun/llm] batch-settlement unavailable (${reason}); paying with exact`);
+  /**
+   * Stop trusting the record of the channel a payload paid into: the next
+   * payment re-reads that channel from the chain first. The scheme has
+   * already restored (or, for an open, dropped) its record; the book still
+   * knows the channel and the cumulative it last confirmed.
+   */
+  distrust(wallet, sent, reason, charged = 0n) {
+    const { payload } = sent;
+    const channelId = payloadChannelId(payload);
+    const known = channelId ? wallet.book.find(channelId) : void 0;
+    if (!channelId || !known) {
+      wallet.client = void 0;
+      let intent;
+      try {
+        intent = sent.key ? wallet.intents.list().find((candidate) => candidate.key === sent.key) : void 0;
+      } catch {
+        intent = void 0;
+      }
+      if (intent) addResyncTarget(wallet, { ...intentTarget(intent), reason });
+      return;
+    }
+    const { key, record } = known;
+    const hasConfirmed = record.pending === void 0 || record.hasConfirmedState;
+    const confirmed = hasConfirmed ? parseAtomic(record.chargedCumulativeAmount) : 0n;
+    const expectDeposit = sent.expectDeposit ?? this.depositExpectation(wallet, payload).expectDeposit;
+    addResyncTarget(wallet, {
+      key,
+      channelId,
+      channelConfig: record.channelConfig,
+      cumulative: confirmed + charged,
+      ...hasConfirmed ? { knownDeposit: parseAtomic(record.deposit) } : {},
+      ...expectDeposit !== void 0 ? { expectDeposit } : {},
+      reason
+    });
+  }
+  /**
+   * The channel's total deposit if a deposit payload landed: the confirmed
+   * deposit plus this one (for an open, nothing plus this one). Undefined for
+   * a payment without a deposit, or a channel the SDK has no record of.
+   */
+  depositExpectation(wallet, payload) {
+    if (payload.payload?.type !== "deposit") return {};
+    const channelId = payloadChannelId(payload);
+    const record = channelId ? wallet.book.find(channelId)?.record : void 0;
+    if (!record) return {};
+    const hasConfirmed = record.pending === void 0 || record.hasConfirmedState;
+    return { expectDeposit: (hasConfirmed ? parseAtomic(record.deposit) : 0n) + parseAtomic(payload.payload.deposit?.amount) };
+  }
+  /**
+   * Re-read every distrusted channel from the chain, at `finalized`
+   * commitment, and rewrite its record: the on-chain deposit, and the highest
+   * of the cumulative the SDK can vouch for, the cumulative the stored record
+   * already confirmed, and the on-chain settled amount. A closing or closed
+   * channel is dropped. The scheme is rebuilt to load the repaired record.
+   *
+   * The stored cumulative is never moved backwards. A deposit's intent can
+   * outlive the receipt that reconciled it (the process died, or the journal
+   * could not be cleared, after the scheme saved the new state), so its
+   * cumulative may predate vouchers the scheme has since confirmed; and
+   * vouchers are redeemed on-chain asynchronously, so `settled` can lag too.
+   * Rewriting the record with either would leave every later voucher
+   * unreconcilable.
+   *
+   * A deposit in doubt is settled by the chain alone:
+   * - landed: the finalized channel holds at least the deposit it would
+   *   bring (and at least what the record already claimed);
+   * - never landed: the finalized chain is {@link LANDING_MARGIN_BLOCKS}
+   *   past the target's anchor height, and a read at least that recent still
+   *   does not show it. An open's record is then dropped; a top-up's channel
+   *   is rewritten with the deposit it really has.
+   * Until one of those holds, it is pending. This settles only the deposit:
+   * whether the gateway charged the payment that carried it is never read
+   * from the chain.
+   *
+   * @throws ResyncError when the chain cannot be read, or a deposit may still
+   *   land: the caller pays exact and the re-read is tried again next call.
+   *   Nothing opens or tops up a channel while any re-read is pending.
+   */
+  async resync(wallet) {
+    for (const target of [...wallet.resyncs.values()]) {
+      const failed = (err) => err instanceof ResyncError ? err : err instanceof ChannelUnreadableError ? new ResyncError("channel_unreadable", err.message) : err instanceof ChannelLayoutError ? new ResyncError("channel_unreadable", `channel ${target.channelId}: ${err.message}`) : new ResyncError(
+        "channel_resync_failed",
+        `could not read channel ${target.channelId} from the chain: ${err instanceof Error ? err.message : String(err)}`
+      );
+      let channel;
+      let expired = false;
+      let stored;
+      try {
+        channel = await this.readOwnChannel(target);
+        const required = maxOf(target.expectDeposit, target.knownDeposit) ?? 0n;
+        if (channel === void 0 || channel.open && channel.deposit < required) {
+          if (target.anchorHeight === void 0) {
+            target.anchorHeight = rpcInteger(
+              await rpcRequest(this.init.rpcUrl, "getBlockHeight", [{ commitment: "confirmed" }], this.init.rpcHeaders),
+              "getBlockHeight"
+            );
+            try {
+              const intent = wallet.intents.list().find((candidate) => candidate.key === target.key);
+              if (intent) wallet.intents.put({ ...intent, anchorHeight: target.anchorHeight });
+            } catch {
+            }
+          }
+          const epoch = await rpcRequest(this.init.rpcUrl, "getEpochInfo", [{ commitment: "finalized" }], this.init.rpcHeaders);
+          const finalizedHeight = rpcInteger(epoch.blockHeight, "getEpochInfo blockHeight");
+          const finalizedSlot = rpcInteger(epoch.absoluteSlot, "getEpochInfo absoluteSlot");
+          if (finalizedHeight <= target.anchorHeight + LANDING_MARGIN_BLOCKS) {
+            throw new ResyncError(
+              "channel_resync_pending",
+              channel === void 0 ? `channel ${target.channelId} is not finalized on chain, and its deposit may still land` : `channel ${target.channelId} holds ${channel.deposit} finalized, short of the ${required} it should hold, and a deposit may still land`
+            );
+          }
+          channel = await this.readOwnChannel(target, finalizedSlot);
+          expired = true;
+        }
+        stored = await wallet.book.base.get(target.key);
+      } catch (err) {
+        throw failed(err);
+      }
+      let outcome;
+      if (typeof stored?.channelId === "string" && stored.channelId !== target.channelId) {
+        outcome = `the record under its key now names channel ${stored.channelId}; left untouched`;
+      } else if (channel === void 0) {
+        await wallet.book.delete(target.key);
+        outcome = "no such channel at finalized commitment, past its deposit's last valid block; record dropped";
+      } else if (!channel.open) {
+        await wallet.book.delete(target.key);
+        outcome = "channel is closing or closed; record dropped";
+      } else {
+        const cumulative = maxOf(maxOf(target.cumulative, channel.settled), confirmedCumulative(stored, target.channelId)) ?? 0n;
+        await wallet.book.set(target.key, {
+          channelConfig: target.channelConfig,
+          channelId: target.channelId,
+          chargedCumulativeAmount: cumulative.toString(),
+          deposit: channel.deposit.toString()
+        });
+        outcome = `record rewritten from finalized chain: deposit=${channel.deposit} settled=${channel.settled} cumulative=${cumulative}` + (expired ? " (the deposit in doubt never landed)" : "");
+      }
+      wallet.resyncs.delete(target.key);
+      this.forgetIntent(wallet, target.key);
+      wallet.client = void 0;
+      await this.report({ type: "resync", reason: target.reason, detail: `channel ${target.channelId}: ${outcome}` });
+    }
+  }
+  /**
+   * A distrusted channel's account at `finalized` commitment, checked to be
+   * this wallet's channel for the record's operator and mint.
+   *
+   * @throws ResyncError (`channel_unreadable`) for any other payment channel.
+   */
+  async readOwnChannel(target, minContextSlot) {
+    const channel = await readChannelAccount(this.init.rpcUrl, target.channelId, this.init.rpcHeaders, { minContextSlot });
+    if (channel !== void 0 && (channel.payer !== await this.init.address() || channel.authorizedSigner !== target.channelConfig.payerAuthorizer || channel.mint !== target.channelConfig.token)) {
+      throw new ResyncError("channel_unreadable", `account ${target.channelId} is a payment channel for another payer, operator or mint`);
+    }
+    return channel;
+  }
+  /**
+   * Make one event observable three ways: a stderr line (every time, never
+   * deduplicated), this client's counters, and the caller's `onEvent`.
+   */
+  async report(event) {
+    let wallet;
+    try {
+      wallet = await this.init.address();
+    } catch {
+      wallet = "unknown";
+    }
+    const full = { ...event, wallet, at: Date.now() };
+    if (full.type === "fallback") {
+      this.counters.fallbacks += 1;
+      this.counters.fallbacksByReason[full.reason] = (this.counters.fallbacksByReason[full.reason] ?? 0) + 1;
+    } else if (full.type === "backoff") {
+      this.counters.backoffs += 1;
+    } else if (full.type === "recovered") {
+      this.counters.recoveries += 1;
+    } else if (full.type === "unresolved") {
+      this.counters.unresolved += 1;
+      this.counters.unresolvedByReason[full.reason] = (this.counters.unresolvedByReason[full.reason] ?? 0) + 1;
+    } else {
+      this.counters.resyncs += 1;
+    }
+    console.error(formatEvent(full));
+    const failed = (err) => console.error(
+      `[@blockrun/llm] batch-settlement onEvent callback threw: ${JSON.stringify(err instanceof Error ? err.message : String(err))}`
+    );
+    try {
+      const result = this.init.options.onEvent?.(full);
+      if (result && typeof result.then === "function") {
+        result.then(void 0, failed);
+      }
+    } catch (err) {
+      failed(err);
+    }
+  }
+  /** Report a fallback and tell the caller to pay exact. */
+  async fallback(event) {
+    await this.report({ type: "fallback", ...event });
+    return { kind: "fallback", reason: event.reason };
   }
   /**
    * Pay one 402 with batch-settlement, or say why the caller should use exact.
    *
-   * `send` replays the original request with the payment headers. The
-   * returned response is 2xx; any other answer either becomes a fallback (the
-   * gateway charged nothing) or is returned to the caller's own error path.
+   * `send` replays the original request with the payment headers. Every send
+   * goes through {@link sendOnce}, the one place an answer is classified as
+   * charged, not charged, or in doubt:
+   *
+   * - charged: the 2xx is returned (`paid`);
+   * - not charged (the gateway's explicit answer to a first send): a 429
+   *   whose receipt proves nothing was broadcast is backed off
+   *   (`Retry-After`, else 1s, 2s, 4s with jitter) and paid again with a new
+   *   payment built from a fresh 402 (`rechallenge`: the original's
+   *   `recentBlockhash` / `recentSlot` can be stale by then), within
+   *   `rateLimit.maxAttempts` / `maxWaitMs`, then with exact; any other is
+   *   paid with exact (`fallback`). A fresh challenge served with a 2xx is
+   *   the call's result (`served`, nothing paid); one that fails otherwise
+   *   is the call's error (`failed`, `"unpaid"`), never an exact payment
+   *   against the stale challenge;
+   * - in doubt: ends only with a definitive success receipt from the one
+   *   replay a receipt-less 429 is allowed ({@link resolveInDoubt}), or a
+   *   thrown {@link BatchPaymentUnresolvedError}. No new authorization, no
+   *   new deposit, no exact payment and no fallback model is ever paid for a
+   *   call in doubt.
+   *
+   * The wallet stays in cooldown after a 429, so its other calls wait
+   * instead of sending opens of their own.
+   *
+   * @param closesAtStart - {@link closeFence}, taken before the call's first
+   *   (unpaid) request. If a close completed since, the call pays exact
+   *   (`closed_during_call`): it started before the close, so it must not
+   *   open a channel the caller believes is closed.
    */
-  async pay(paymentRequired, send) {
-    if (!offersBatch(paymentRequired)) return { kind: "fallback", reason: "not_offered" };
-    const wallet = await this.wallet();
-    if (typeof wallet === "string") {
-      this.warn(void 0, wallet);
-      return { kind: "fallback", reason: wallet };
+  async pay(paymentRequired, send, rechallenge, closesAtStart) {
+    const unavailable = batchUnavailable(paymentRequired);
+    if (unavailable) return this.fallback(unavailable);
+    let wallet;
+    try {
+      wallet = await this.wallet();
+    } catch (err) {
+      return this.fallback(creationFailure(err));
     }
-    if (wallet.busy) return { kind: "fallback", reason: "channel_busy" };
-    wallet.busy = true;
+    if ("reason" in wallet) return this.fallback({ reason: wallet.reason, detail: wallet.detail });
+    if (closesAtStart !== void 0 && wallet.closes !== closesAtStart) {
+      return this.fallback({
+        reason: "closed_during_call",
+        detail: "closeBatchChannel() closed this wallet's channel after this call started; it opens no channel"
+      });
+    }
+    wallet.active += 1;
     try {
-      let http;
-      let payload;
-      try {
-        http = (await this.build(wallet)).http;
-        payload = await http.createPaymentPayload(paymentRequired);
-      } catch (err) {
-        const reason = err instanceof Error ? err.message : String(err);
-        this.warn(wallet, reason);
-        return { kind: "fallback", reason };
+      return await this.payWith(wallet, paymentRequired, send, rechallenge, closesAtStart ?? wallet.closes);
+    } finally {
+      wallet.active -= 1;
+    }
+  }
+  /**
+   * The close fence for a call about to send its first request: how many
+   * closes this wallet has completed so far, to hand to {@link pay}.
+   * `close()` refuses while a call is inside `pay()`, but a call still
+   * waiting for its 402 is not there yet; the fence covers that window.
+   * Undefined when the wallet cannot be named (no fence then; `pay()`
+   * reports why batch is unavailable).
+   */
+  async closeFence() {
+    try {
+      return registry2.wallets.get(await this.init.address())?.closes ?? 0;
+    } catch {
+      return void 0;
+    }
+  }
+  /** {@link pay}, for a wallet this client may use. */
+  async payWith(wallet, paymentRequired, send, rechallenge, fence) {
+    let current = paymentRequired;
+    const fallback = async (event) => {
+      const result = await this.fallback(event);
+      return current === paymentRequired ? result : { ...result, paymentRequired: current };
+    };
+    const budget = { attempt: 1, waited: 0 };
+    let waitedUntil = 0;
+    let backedOff;
+    let holding = false;
+    let sent;
+    const release = () => {
+      if (holding) wallet.busy = false;
+      holding = false;
+    };
+    try {
+      for (; ; ) {
+        const now = Date.now();
+        if (wallet.cooldownUntil > now && wallet.cooldownUntil !== waitedUntil) {
+          const wait = wallet.cooldownUntil - now;
+          if (budget.waited + wait > this.maxWaitMs) {
+            return fallback({
+              reason: "rate_limited",
+              retryAfterMs: wait,
+              attempt: budget.attempt,
+              detail: "wallet is in a 429 cooldown longer than batch.rateLimit.maxWaitMs allows"
+            });
+          }
+          await this.report({ type: "backoff", reason: "cooldown", retryAfterMs: wait, attempt: budget.attempt });
+          backedOff ??= "cooldown";
+          waitedUntil = wallet.cooldownUntil;
+          budget.waited += wait;
+          await sleep2(wait);
+          continue;
+        }
+        if (budget.attempt > 1 || budget.waited > 0) {
+          let fresh;
+          try {
+            fresh = await rechallenge();
+          } catch (err) {
+            return { kind: "failed", error: withDisposition(err instanceof Error ? err : new Error(String(err)), "unpaid") };
+          }
+          if (fresh.kind === "served") {
+            await this.report({
+              type: "recovered",
+              reason: "served_unpaid_on_rechallenge",
+              status: fresh.response.status,
+              attempt: budget.attempt,
+              detail: "the fresh challenge after the wait was served without a payment; nothing was paid"
+            });
+            return { kind: "served", response: fresh.response };
+          }
+          current = fresh.paymentRequired;
+          const unavailable = batchUnavailable(current);
+          if (unavailable) return fallback({ ...unavailable, attempt: budget.attempt });
+        }
+        if (wallet.closes !== fence) {
+          return fallback({
+            reason: "closed_during_call",
+            attempt: budget.attempt,
+            detail: "closeBatchChannel() closed this wallet's channel after this call started; it opens no channel"
+          });
+        }
+        if (wallet.busy) return fallback({ reason: "channel_busy", attempt: budget.attempt });
+        if (wallet.file && !holdsChannelFile(wallet.file)) {
+          return fallback({
+            reason: "channel_store_locked",
+            attempt: budget.attempt,
+            detail: `this process no longer holds the lock on ${wallet.file}; another owner may be paying into its channels`
+          });
+        }
+        wallet.busy = true;
+        holding = true;
+        let built;
+        try {
+          built = await this.buildPayment(wallet, current);
+        } catch (err) {
+          release();
+          if (err instanceof ResyncError) return fallback({ reason: err.reason, detail: err.message, attempt: budget.attempt });
+          return fallback({ ...creationFailure(err), attempt: budget.attempt });
+        }
+        if (built.kind !== "authorization") {
+          try {
+            this.journalDeposit(wallet, built);
+          } catch (err) {
+            await this.settle(built.http, built.payload, () => null, 0);
+            release();
+            return fallback({
+              reason: "deposit_journal_failed",
+              attempt: budget.attempt,
+              detail: err instanceof Error ? err.message : String(err)
+            });
+          }
+        }
+        sent = built;
+        const outcome = await this.sendOnce(wallet, built, send, backedOff === "rate_limited", false);
+        if (outcome.kind === "charged") {
+          if (built.kind !== "authorization" && !(built.key && wallet.resyncs.has(built.key))) this.forgetIntent(wallet, built.key);
+          sent = void 0;
+          release();
+          if (backedOff) await this.report({ type: "recovered", reason: backedOff, attempt: budget.attempt });
+          return { kind: "paid", response: outcome.response, chargedUsd: outcome.chargedUsd };
+        }
+        if (outcome.kind === "not_charged") {
+          if (built.kind !== "authorization") {
+            if (outcome.depositSafe) this.forgetIntent(wallet, built.key);
+            else this.distrust(wallet, built, "deposit_refused");
+          }
+          sent = void 0;
+          release();
+          if (!outcome.rateLimited) {
+            const { kind: _kind, rateLimited: _limited, depositSafe: _safe, ...event } = outcome;
+            return fallback({ ...event, attempt: budget.attempt });
+          }
+          const wait = this.coolDown(wallet, outcome.rateLimited.retryAfterMs ?? backoffDelay(budget.attempt));
+          if (budget.attempt >= this.maxAttempts || budget.waited + wait > this.maxWaitMs) {
+            return fallback({
+              reason: "rate_limited",
+              status: 429,
+              errorReason: outcome.errorReason,
+              retryAfterMs: wait,
+              attempt: budget.attempt,
+              detail: budget.attempt >= this.maxAttempts ? "batch.rateLimit.maxAttempts reached" : "Retry-After exceeds what is left of batch.rateLimit.maxWaitMs"
+            });
+          }
+          await this.report({
+            type: "backoff",
+            reason: "rate_limited",
+            status: 429,
+            errorReason: outcome.errorReason,
+            retryAfterMs: wait,
+            attempt: budget.attempt
+          });
+          backedOff = "rate_limited";
+          waitedUntil = wallet.cooldownUntil;
+          budget.waited += wait;
+          await sleep2(wait);
+          budget.attempt += 1;
+          continue;
+        }
+        if (outcome.kind === "cancelled") {
+          sent = void 0;
+          release();
+          await this.report({
+            type: "recovered",
+            reason: "batch_cancelled",
+            status: outcome.status,
+            errorReason: "batch_cancelled",
+            attempt: budget.attempt,
+            detail: "the gateway cancelled the payment: nothing was charged, and its error is raised unpaid"
+          });
+          return { kind: "failed", error: outcome.error };
+        }
+        const resolved = await this.resolveInDoubt(wallet, built, outcome, send, budget);
+        if (resolved.kind === "charged") {
+          if (built.kind !== "authorization" && !(built.key && wallet.resyncs.has(built.key))) this.forgetIntent(wallet, built.key);
+          sent = void 0;
+          release();
+          await this.report({ type: "recovered", reason: "rate_limited", attempt: budget.attempt });
+          return { kind: "paid", response: resolved.response, chargedUsd: resolved.chargedUsd };
+        }
+        return await this.raiseUnresolved(wallet, built, resolved, budget.attempt);
+      }
+    } catch (err) {
+      if (err instanceof Error && err.name === "BatchPaymentUnresolvedError") throw err;
+      if (sent) {
+        try {
+          return await this.raiseUnresolved(
+            wallet,
+            sent,
+            {
+              kind: "in_doubt",
+              reason: "outcome_unknown",
+              replayable: false,
+              settled: false,
+              detail: `an error after the payment was sent: ${err instanceof Error ? err.message : String(err)}`,
+              cause: err
+            },
+            budget.attempt
+          );
+        } catch (raised) {
+          throw withDisposition(raised, "paid-or-in-doubt");
+        }
+      }
+      return fallback({ ...creationFailure(err), attempt: budget.attempt });
+    } finally {
+      release();
+    }
+  }
+  /**
+   * Put the wallet in a 429 cooldown for `delay` ms (`Retry-After`, or the
+   * default backoff), and return how long this call would have to wait.
+   *
+   * The shared cooldown is capped at `rateLimit.maxWaitMs`, so one header,
+   * however long, never keeps the wallet's calls off batch for longer than
+   * the retry budget. This call still weighs the full delay: one it cannot
+   * wait out within its budget is not waited at all, and the caller pays
+   * exact (or raises a payment in doubt) at once.
+   */
+  coolDown(wallet, delay) {
+    const limitedAt = Date.now();
+    wallet.cooldownUntil = Math.max(wallet.cooldownUntil, limitedAt + Math.min(delay, this.maxWaitMs));
+    return Math.max(delay, wallet.cooldownUntil - limitedAt);
+  }
+  /**
+   * Try to end a payment in doubt with the gateway's own word.
+   *
+   * The one source of evidence this SDK accepts today is a definitive
+   * success receipt on the single byte-identical replay a 429 without a
+   * receipt is allowed, after its backoff (the owner's bounded safety
+   * attempt). Any other answer to it (a 402 or `duplicate_settlement`, which
+   * mean the original reached the gateway; another 429; a 5xx; a timeout)
+   * leaves it in doubt. Every other in-doubt outcome is never replayed.
+   *
+   * Chain state is not evidence here: it can settle a deposit (see
+   * `resync`), never whether the gateway charged. Gateway-side evidence (a
+   * receipt on every response, a request-status endpoint with a fence)
+   * plugs in here, before the caller raises.
+   *
+   * @returns the charged replay, or the doubt to raise.
+   */
+  async resolveInDoubt(wallet, sent, doubt, send, budget) {
+    if (!doubt.replayable) return doubt;
+    const wait = this.coolDown(wallet, doubt.retryAfterMs ?? backoffDelay(budget.attempt));
+    if (budget.attempt >= this.maxAttempts || budget.waited + wait > this.maxWaitMs) {
+      return {
+        ...doubt,
+        detail: `${doubt.detail}; batch.rateLimit leaves no room for its one replay`
+      };
+    }
+    await this.report({
+      type: "backoff",
+      reason: "rate_limited",
+      status: 429,
+      errorReason: doubt.errorReason,
+      retryAfterMs: wait,
+      attempt: budget.attempt
+    });
+    budget.waited += wait;
+    await sleep2(wait);
+    budget.attempt += 1;
+    const replayed = await this.sendOnce(wallet, sent, send, true, true);
+    if (replayed.kind === "charged") return replayed;
+    return replayed.kind === "in_doubt" ? replayed : { kind: "in_doubt", reason: "replay_unresolved", replayable: false, settled: true, detail: "the replay was refused" };
+  }
+  /**
+   * Raise a payment in doubt: release the scheme's hold on it (the channel
+   * goes back to its confirmed state), put a deposit's channel in doubt so
+   * it is re-read from the chain before anything pays into it again, report
+   * the `unresolved` event, and throw {@link BatchPaymentUnresolvedError}.
+   */
+  async raiseUnresolved(wallet, sent, doubt, attempt) {
+    if (!doubt.settled) await this.settle(sent.http, sent.payload, () => null, 0);
+    if (sent.kind !== "authorization") {
+      this.distrust(
+        wallet,
+        sent,
+        doubt.reason === "no_response" ? "deposit_unanswered" : doubt.reason === "replay_unresolved" ? "deposit_rate_limited" : "deposit_failed"
+      );
+    }
+    await this.report({
+      type: "unresolved",
+      reason: doubt.reason,
+      status: doubt.status,
+      errorReason: doubt.errorReason,
+      attempt,
+      detail: `${doubt.detail}; it may have been charged, so it is not paid again`
+    });
+    throw new BatchPaymentUnresolvedError({
+      reason: doubt.reason,
+      wallet: await this.init.address(),
+      requestId: sent.payload.payload?.authorization?.requestId,
+      channelId: payloadChannelId(sent.payload),
+      payloadKind: sent.kind,
+      status: doubt.status,
+      detail: doubt.detail,
+      cause: doubt.cause
+    });
+  }
+  /** Build a new batch payment for a 402: the payload, its headers and its kind. */
+  async buildPayment(wallet, paymentRequired) {
+    const { http, payload } = await this.createPayload(wallet, paymentRequired);
+    const headers = http.encodePaymentSignatureHeader(payload);
+    const channelId = payloadChannelId(payload);
+    const known = channelId ? wallet.book.find(channelId) : void 0;
+    let kind = "authorization";
+    if (payload.payload?.type === "deposit") {
+      const record = known?.record;
+      kind = record && (record.pending === void 0 || record.hasConfirmedState) ? "top-up" : "open";
+    }
+    return { http, payload, headers, kind, key: known?.key, sentAt: Date.now(), sends: 0 };
+  }
+  /**
+   * Write a deposit's intent to the wallet's journal before it is sent
+   * (with the file store: the file and its directory fsynced).
+   *
+   * @throws when it cannot be recorded; the deposit must then not be sent.
+   */
+  journalDeposit(wallet, sent) {
+    const channelId = payloadChannelId(sent.payload);
+    const record = channelId ? wallet.book.find(channelId)?.record : void 0;
+    const { expectDeposit } = this.depositExpectation(wallet, sent.payload);
+    if (!sent.key || !channelId || !record || expectDeposit === void 0 || sent.kind === "authorization") {
+      throw new Error("the deposit's channel record is missing");
+    }
+    const hasConfirmed = record.pending === void 0 || record.hasConfirmedState;
+    sent.expectDeposit = expectDeposit;
+    wallet.intents.put({
+      key: sent.key,
+      channelId,
+      channelConfig: record.channelConfig,
+      requestId: sent.payload.payload?.authorization?.requestId,
+      kind: sent.kind,
+      cumulative: hasConfirmed ? String(parseAtomic(record.chargedCumulativeAmount)) : "0",
+      expectDeposit: expectDeposit.toString(),
+      ...hasConfirmed ? { knownDeposit: String(parseAtomic(record.deposit)) } : {},
+      at: Date.now()
+    });
+  }
+  /**
+   * Remove a deposit's intent once it is reconciled. A failure is logged,
+   * not thrown: the intent then outlives its deposit, and after a restart
+   * the chain re-read settles it again.
+   */
+  forgetIntent(wallet, key) {
+    if (!key) return;
+    try {
+      wallet.intents.remove(key);
+    } catch (err) {
+      console.error(
+        `[@blockrun/llm] batch-settlement could not clear a deposit intent: ${JSON.stringify(err instanceof Error ? err.message : String(err))}`
+      );
+    }
+  }
+  /**
+   * THE choke point: send a batch payment once and classify the answer.
+   *
+   * The only caller of `send` for a batch payment, and the only place its
+   * outcome is decided (see {@link SendOutcome}). Every exception once the
+   * send has started is `in_doubt`, whatever its type or `cause.code`: the
+   * request may have reached the gateway. "Not charged" is only ever minted
+   * here, and only for a first send.
+   *
+   * @param retry - count this send in `retries` (it follows this call's own 429).
+   * @param replay - this is the one replay of a receipt-less 429: only a 2xx
+   *   with a success receipt counts, everything else stays in doubt.
+   */
+  async sendOnce(wallet, sent, send, retry, replay) {
+    if (retry) this.counters.retries += 1;
+    sent.sends += 1;
+    let response;
+    try {
+      response = await send(sent.headers);
+    } catch (err) {
+      return {
+        kind: "in_doubt",
+        reason: replay ? "replay_unresolved" : "no_response",
+        replayable: false,
+        settled: false,
+        detail: `${replay ? "the replay" : "the payment"} got no answer (${err instanceof Error ? `${err.name}: ${err.message}` : String(err)})`,
+        cause: err
+      };
+    }
+    try {
+      return await this.classify(wallet, sent, response, replay);
+    } catch (err) {
+      return {
+        kind: "in_doubt",
+        reason: replay ? "replay_unresolved" : "outcome_unknown",
+        replayable: false,
+        settled: false,
+        status: response.status,
+        detail: `the answer could not be classified (${err instanceof Error ? err.message : String(err)})`,
+        cause: err
+      };
+    }
+  }
+  /** {@link sendOnce}'s classifier, for an HTTP answer. */
+  async classify(wallet, sent, response, replay) {
+    const { http, payload } = sent;
+    const getHeader = (name) => response.headers.get(name);
+    const receipted = Boolean(getHeader("PAYMENT-RESPONSE") || getHeader("X-PAYMENT-RESPONSE"));
+    const status2 = response.status;
+    if (status2 === 429 && !receipted) {
+      return {
+        kind: "in_doubt",
+        reason: "replay_unresolved",
+        replayable: !replay,
+        settled: false,
+        status: status2,
+        retryAfterMs: parseRetryAfter(getHeader("retry-after")),
+        errorReason: await rateLimitReason(response, void 0),
+        detail: replay ? "the replay was answered 429 without a receipt" : "a 429 without a receipt"
+      };
+    }
+    const channelId = payloadChannelId(payload);
+    const before = channelId ? confirmedState(wallet.book.find(channelId)?.record) : void 0;
+    const reconciled = await this.settle(http, payload, getHeader, status2);
+    const receipt = reconciled.settleResponse;
+    const definitive = receipt?.success === true && reconciled.ok && recordAdvanced(before, channelId ? confirmedState(wallet.book.find(channelId)?.record) : void 0, payload, receipt);
+    if (!response.ok && !replay && sent.kind === "authorization" && cancelledReceipt(receipt)) {
+      return { kind: "cancelled", status: status2, error: await cancelledError(response) };
+    }
+    if (response.ok && (!replay || definitive)) {
+      if (!definitive) {
+        this.distrust(wallet, sent, receipt ? "receipt_unreconciled" : "receipt_missing", rebuiltCharge(receipt, payload));
       }
-      const deposit = payload.payload?.type === "deposit";
-      let response;
+      return { kind: "charged", response, chargedUsd: chargedUsd(() => http.getPaymentSettleResponse(getHeader)) };
+    }
+    if (replay) {
+      return {
+        kind: "in_doubt",
+        reason: "replay_unresolved",
+        replayable: false,
+        settled: true,
+        status: status2,
+        errorReason: status2 === 429 ? await rateLimitReason(response, receipt) : receipt?.errorReason,
+        detail: `the replay was answered ${status2} with ${describeReceipt(receipt)}`,
+        cause: await afterPaymentError(response)
+      };
+    }
+    if (status2 === 429) {
+      if (provesNothingBroadcast(receipt)) {
+        return {
+          kind: "not_charged",
+          reason: "rate_limited",
+          status: status2,
+          errorReason: await rateLimitReason(response, receipt),
+          rateLimited: { retryAfterMs: parseRetryAfter(getHeader("retry-after")) },
+          // The facilitator's explicit failed receipt names no transaction: the
+          // deposit was never broadcast (see provesNothingBroadcast).
+          depositSafe: true
+        };
+      }
+      return {
+        kind: "in_doubt",
+        reason: "ambiguous_rate_limit",
+        replayable: false,
+        settled: true,
+        status: status2,
+        errorReason: await rateLimitReason(response, receipt),
+        detail: `a 429 whose ${describeReceipt(receipt)} does not prove nothing was broadcast`,
+        cause: await afterPaymentError(response)
+      };
+    }
+    if (cleanRefusalReceipt(receipt)) {
+      if (status2 === 402) {
+        const duplicate = await duplicateAnswer(response);
+        if (duplicate) {
+          return {
+            kind: "in_doubt",
+            reason: "duplicate_settlement",
+            replayable: false,
+            settled: true,
+            status: status2,
+            errorReason: duplicate,
+            detail: `the payment was answered 402 ${duplicate}: another copy of this request reached the gateway`,
+            cause: await afterPaymentError(response)
+          };
+        }
+        return { kind: "not_charged", reason: "payment_required", status: status2, errorReason: receipt?.errorReason, depositSafe: provesNothingBroadcast(receipt) };
+      }
+      const refusal = await batchRefusal(response);
+      if (refusal) {
+        return { kind: "not_charged", reason: refusal, status: status2, errorReason: refusal, depositSafe: PRE_REQUEST_REFUSALS.has(refusal) };
+      }
+    }
+    return {
+      kind: "in_doubt",
+      reason: "outcome_unknown",
+      replayable: false,
+      settled: true,
+      status: status2,
+      errorReason: receipt?.errorReason,
+      detail: `the payment was answered ${status2} with ${describeReceipt(receipt)}`,
+      cause: await afterPaymentError(response)
+    };
+  }
+  /**
+   * Build the payment payload, re-reading any distrusted channel from the
+   * chain first. A stored record the book refuses to hand over (a deposit a
+   * dead process never heard back about), or one a top-up's read found
+   * unusable ({@link prepareTopUp}), is re-read and the payload rebuilt
+   * once.
+   */
+  async createPayload(wallet, paymentRequired) {
+    for (let pass = 0; ; pass += 1) {
+      await this.resync(wallet);
+      const http = (await this.build(wallet)).http;
       try {
-        response = await send(http.encodePaymentSignatureHeader(payload));
+        await this.prepareTopUp(wallet, paymentRequired);
+        return { http, payload: await http.createPaymentPayload(withoutClientSignedBatch(paymentRequired)) };
       } catch (err) {
-        if (deposit) await this.forget(wallet);
-        else await this.settle(http, payload, () => null, 0);
-        throw err;
+        if (pass > 0 || !isResyncRequired(err) || wallet.resyncs.size === 0) throw err;
+      } finally {
+        wallet.topUp = void 0;
       }
-      const getHeader = (name) => response.headers.get(name);
-      const settled = await this.settle(http, payload, getHeader, response.status);
-      if (deposit && !(response.ok && settled?.success === true)) await this.forget(wallet);
-      if (response.ok) {
-        const charged = atomicToUsd(settled?.amount) ?? atomicToUsd(payload.accepted?.amount) ?? 0;
-        return { kind: "paid", response, chargedUsd: charged };
+    }
+  }
+  /**
+   * When this payment will top up the wallet's channel, read how much of its
+   * deposit is already settled on-chain (at `finalized` commitment, so never
+   * more than will stay settled), so `maxDeposit` caps the escrow still at
+   * stake rather than every deposit the channel ever took.
+   *
+   * Only a top-up costs this read (a channel's balance decides it, from the
+   * stored record). If the read fails, nothing settled is assumed, which is
+   * the stricter, lifetime cap. If the chain shows a larger deposit than the
+   * record, the record is behind (a deposit it never heard about landed):
+   * sizing a top-up from it could exceed `maxDeposit`, so this call pays
+   * exact and the channel is re-read before the next payment. If
+   * `@x402/svm`'s channel layout is not the one this SDK decodes, or the
+   * account at the channel's address cannot be read as a channel, the call
+   * pays exact (`channel_unreadable`), record kept. If
+   * the finalized channel is closing or closed, or is not this wallet's for
+   * the record's operator and mint, no top-up is sized from the record: it
+   * is re-read at once (`channel_unusable`), see {@link createPayload}.
+   */
+  async prepareTopUp(wallet, paymentRequired) {
+    wallet.topUp = void 0;
+    const accept = trustedBatchAccept(paymentRequired, this.init.options.operators);
+    if (!accept) return;
+    const key = channelKeyOf(accept);
+    const record = key ? await wallet.book.get(key) : void 0;
+    if (!key || !record || record.pending || typeof record.channelId !== "string") return;
+    const deposit = parseAtomic(record.deposit);
+    if (parseAtomic(record.chargedCumulativeAmount) + parseAtomic(accept.amount) <= deposit) return;
+    let channel;
+    try {
+      channel = await readChannelAccount(this.init.rpcUrl, record.channelId, this.init.rpcHeaders);
+    } catch (err) {
+      if (err instanceof ChannelLayoutError) {
+        throw new ResyncError("channel_unreadable", `channel ${record.channelId}: ${err.message}; no top-up is sized from it`);
       }
-      const refusal = await isBatchRefusal(response);
-      if (refusal) {
-        this.warn(wallet, refusal);
-        return { kind: "fallback", reason: refusal };
+      if (err instanceof ChannelUnreadableError) {
+        throw new ResyncError("channel_unreadable", `${err.message}; no top-up is signed into it`);
       }
-      return { kind: "failed", response };
-    } finally {
-      wallet.busy = false;
+      throw new ResyncError(
+        "channel_resync_failed",
+        `could not read channel ${record.channelId} before topping it up: ${err instanceof Error ? err.message : String(err)}`
+      );
     }
+    if (channel === void 0) return;
+    if (!channel.open || channel.payer !== await this.init.address() || channel.authorizedSigner !== record.channelConfig.payerAuthorizer || channel.mint !== record.channelConfig.token) {
+      addResyncTarget(wallet, {
+        key,
+        channelId: record.channelId,
+        channelConfig: record.channelConfig,
+        cumulative: parseAtomic(record.chargedCumulativeAmount),
+        knownDeposit: deposit,
+        reason: "channel_unusable"
+      });
+      throw new ChannelResyncRequiredError(record.channelId);
+    }
+    if (channel.deposit > deposit) {
+      addResyncTarget(wallet, {
+        key,
+        channelId: record.channelId,
+        channelConfig: record.channelConfig,
+        cumulative: parseAtomic(record.chargedCumulativeAmount),
+        knownDeposit: channel.deposit,
+        reason: "deposit_unrecorded"
+      });
+      throw new ResyncError(
+        "channel_resync_pending",
+        `channel ${record.channelId} holds ${channel.deposit} on chain, more than the ${deposit} its record knows; it is re-read before any top-up`
+      );
+    }
+    wallet.topUp = { key, deposit, settled: channel.settled };
   }
   /**
    * Hand the gateway's answer to the scheme, which verifies the operator's
@@ -9743,36 +11531,143 @@ var SolanaBatchPayer = class {
    */
   async settle(http, payload, getHeader, status2) {
     try {
-      return (await http.processPaymentResult(payload, getHeader, status2)).settleResponse;
+      return { settleResponse: (await http.processPaymentResult(payload, getHeader, status2)).settleResponse, ok: true };
     } catch (err) {
       console.error(
-        `[@blockrun/llm] batch-settlement receipt not reconciled: ${err instanceof Error ? err.message : String(err)}`
+        `[@blockrun/llm] batch-settlement receipt not reconciled: ${JSON.stringify(err instanceof Error ? err.message : String(err))}`
       );
-      return void 0;
+      let settleResponse;
+      try {
+        settleResponse = http.getPaymentSettleResponse(getHeader);
+      } catch {
+        settleResponse = void 0;
+      }
+      return { settleResponse, ok: false };
     }
   }
   /**
-   * Close the channel and return its unused escrow to the wallet.
+   * Close the channel the gateway's current challenge names and return its
+   * unused escrow to the wallet.
    *
    * The scheme keeps a closed channel in its records, and would go on paying
-   * into it, so a successful close forgets the channel. The next batch call
-   * finds no open channel on-chain and opens a new one.
+   * into it, so a successful close forgets that channel. The next batch call
+   * finds no open channel on-chain and opens a new one. Any other channel
+   * (say, one opened with an operator key that is being rotated out) keeps
+   * its record, so it can still be closed without an on-chain scan. A
+   * client-signed channel an earlier SDK version opened is closed too, once
+   * the trusted server-signed one has no record (see {@link refundTarget}).
    *
    * @param url - any batch-enabled route on the gateway the channel was opened with.
+   * @throws BatchCloseDeferredError while a batch call for the wallet is in
+   *   flight, or while any of its deposits is in doubt (until a finalized
+   *   chain read settles it). Nothing is refunded or forgotten then.
    */
   async close(url) {
     const wallet = await this.wallet();
-    if (typeof wallet === "string") throw new Error(`batch-settlement unavailable: ${wallet}`);
-    if (wallet.busy) throw new Error("batch-settlement channel has a request in flight; close it when the call returns");
+    if ("reason" in wallet) throw new Error(`batch-settlement unavailable: ${wallet.detail}`);
+    if (wallet.busy || wallet.active > 0) {
+      throw new BatchCloseDeferredError({
+        reason: "call_in_flight",
+        wallet: await this.init.address(),
+        detail: "a batch call is in flight (it may be waiting out a 429); close the channel when it returns"
+      });
+    }
     wallet.busy = true;
     try {
-      const result = await (await this.build(wallet)).refund(url);
-      await this.forget(wallet);
+      await this.settleDoubtsForClose(wallet);
+      const { accept, key } = await this.refundTarget(wallet, url);
+      const result = await (await this.prepareClose(wallet, key)).refund(url, accept);
+      wallet.closes += 1;
+      await this.forget(wallet, key);
       return result;
     } finally {
       wallet.busy = false;
     }
   }
+  /**
+   * Re-read every distrusted channel before a close. A deposit still in
+   * doubt defers the close: refunding (or forgetting) a channel a deposit
+   * may yet land on could strand that deposit, and after a restart nothing
+   * would remember it. A record re-read that only failed for another reason
+   * (an RPC error on a channel with no deposit in doubt) does not.
+   */
+  async settleDoubtsForClose(wallet) {
+    try {
+      await this.resync(wallet);
+    } catch (err) {
+      if (!(err instanceof ResyncError)) throw err;
+      const inDoubt = [...wallet.resyncs.values()].filter((target) => target.expectDeposit !== void 0);
+      if (inDoubt.length > 0) {
+        throw new BatchCloseDeferredError({
+          reason: "deposit_in_doubt",
+          wallet: await this.init.address(),
+          channelIds: inDoubt.map((target) => target.channelId),
+          detail: `a deposit on channel ${inDoubt.map((target) => target.channelId).join(", ")} is in doubt (${err.message}); close once a finalized chain read settles it`
+        });
+      }
+    }
+  }
+  /**
+   * The channel a close targets: the one the gateway's refund challenge
+   * names, by the scheme's storage key for its trusted server-signed accept
+   * (network, asset, receiver, fee payer, withdraw delay, receiver
+   * authorizer, operator). Probed with an unpaid GET, as `@x402/svm`'s own
+   * refund probes; that accept is then handed to the refund, so upstream
+   * does not probe again and pick another accept.
+   *
+   * A legacy client-signed channel (opened by an earlier SDK version, which
+   * could pay a client-signed accept; this one never opens one) must stay
+   * refundable. When the trusted server-signed accept has no stored record,
+   * or there is none, a client-signed accept in the challenge whose storage
+   * key names a stored client-signed record is the target instead, and the
+   * refund runs through `@x402/svm`'s client-signed path (a refund voucher
+   * signed by the payer at its confirmed cumulative). The signer modes match:
+   * a server-signed record is never refunded under a client-signed accept.
+   */
+  async refundTarget(wallet, url) {
+    const probe = await fetch(url, { method: "GET" });
+    const header = probe.status === 402 ? probe.headers.get("PAYMENT-REQUIRED") : null;
+    if (!header) throw new Error(`refund probe expected a 402 with PAYMENT-REQUIRED from ${url}, got HTTP ${probe.status}`);
+    const paymentRequired = parsePaymentRequired(header);
+    const trustedAccepts = trustedBatchAccepts(paymentRequired, this.init.options.operators).map((accept) => ({ accept, key: channelKeyOf(accept) })).filter((candidate) => !!candidate.key);
+    for (const candidate of trustedAccepts) {
+      if (await wallet.book.base.get(candidate.key)) return candidate;
+    }
+    for (const accept of (paymentRequired.accepts ?? []).filter(clientSignedBatch)) {
+      const key = channelKeyOf(accept);
+      const record = key ? await wallet.book.base.get(key) : void 0;
+      if (key && record && (record.channelConfig?.voucherSigner ?? "client") === "client") return { accept, key };
+    }
+    const first = trustedAccepts[0];
+    if (!first) throw new Error(`${url} offers no batch-settlement accept with a trusted operator to close against`);
+    return first;
+  }
+  /**
+   * Get the stored channel `key` ready to refund.
+   *
+   * `@x402/svm` refunds a server-signed channel only from the scheme's memory,
+   * or after an on-chain scan that many RPCs refuse; it never reads the
+   * stored record. So the target channel is loaded into a freshly built
+   * scheme, and only that one: upstream's refund falls back to the first
+   * channel in memory for the same receiver and asset, whatever its operator.
+   * A record in doubt (a deposit this process never confirmed, or a pending
+   * deposit left by a process that died) is re-read from the chain before it
+   * is loaded. If a re-read cannot settle a record, the refund is still
+   * attempted and may find the channel by its scan.
+   */
+  async prepareClose(wallet, key) {
+    for (let pass = 0; ; pass += 1) {
+      await this.settleDoubtsForClose(wallet);
+      wallet.client = void 0;
+      const built = await this.build(wallet);
+      try {
+        await built.load(key);
+        return built;
+      } catch (err) {
+        if (pass > 0 || !isResyncRequired(err)) return built;
+      }
+    }
+  }
 };
 
 // src/solana-client.ts
@@ -9841,6 +11736,18 @@ async function waitForStaleRetry(attempt) {
     (resolve2) => setTimeout(resolve2, STALE_BLOCKHASH_RETRY_BACKOFFS_MS[attempt])
   );
 }
+async function unpaidApiError(response) {
+  let errorBody;
+  try {
+    errorBody = await response.json();
+  } catch {
+    errorBody = { error: "Request failed" };
+  }
+  return withDisposition(
+    new APIError(`API error: ${response.status}`, response.status, sanitizeErrorResponse(errorBody)),
+    "unpaid"
+  );
+}
 var DEFAULT_SOLANA_RPC_URL = "https://sol.blockrun.ai/api/v1/solana/rpc";
 function resolveRpcConfig(rpcUrl, rpcHeaders) {
   const env = typeof process !== "undefined" && process.env ? process.env : {};
@@ -9907,21 +11814,42 @@ var SolanaLLMClient = class {
         options: options.batch,
         secretKey: () => solanaKeyToBytes(this.privateKey),
         address: () => this.getWalletAddress(),
-        rpcUrl: this.rpcUrl
+        rpcUrl: this.rpcUrl,
+        rpcHeaders: this.rpcHeaders
       });
     }
   }
   /**
    * Close this wallet's batch-settlement channel and return its unused escrow.
    *
-   * The gateway closes it cooperatively when it can; otherwise this starts a
-   * payer-forced close and the escrow comes back after the channel's grace
-   * period. Only meaningful with the `batch` option.
+   * Closes the channel for the operator the gateway's current 402 names; a
+   * channel opened with another trusted operator key (during a key rotation)
+   * keeps its record. The gateway closes it cooperatively when it can;
+   * otherwise this starts a payer-forced close and the escrow comes back
+   * after the channel's grace period. Only meaningful with the `batch`
+   * option.
+   *
+   * @throws BatchCloseDeferredError, closing nothing, while a chat call for
+   *   this wallet is still in flight (including one waiting out a 429, so a
+   *   retry can never reopen a channel you just closed), or while one of its
+   *   deposits is in doubt (until a `finalized` chain read shows it landed or
+   *   that it no longer can, usually a few minutes after it was sent). Call
+   *   it again later.
    */
   async closeBatchChannel() {
     if (!this.batchPayer) throw new Error("closeBatchChannel() requires the `batch` option in wallet mode");
     return this.batchPayer.close(`${this.apiUrl}/v1/chat/completions`);
   }
+  /**
+   * This client's batch-settlement counters: calls that fell back to `exact`
+   * (in total and by reason), 429 backoffs, batch retries, and recoveries.
+   * Every one of those is also logged to stderr and passed to `batch.onEvent`.
+   * Only meaningful with the `batch` option.
+   */
+  getBatchStats() {
+    if (!this.batchPayer) throw new Error("getBatchStats() requires the `batch` option in wallet mode");
+    return this.batchPayer.stats();
+  }
   /** Get Solana wallet address (public key in base58). */
   async getWalletAddress() {
     if (!this.addressCache) {
@@ -10445,17 +12373,34 @@ var SolanaLLMClient = class {
   isSolana() {
     return this.apiUrl.includes("sol.blockrun.ai");
   }
+  /**
+   * Chat request with automatic x402 payment.
+   *
+   * Every error it throws carries a {@link RetryDisposition}, which is what
+   * {@link SolanaLLMClient.chatCompletion}'s fallback walk honours: errors of
+   * the unpaid first request, its 402 challenge and the signing step are
+   * `"unpaid"`; anything after a payment was sent (exact or batch) is
+   * `"paid-or-in-doubt"`, and so is any error with an API key once the billed
+   * request was sent, except the account API's explicit 4xx refusal.
+   */
   async requestWithPayment(endpoint, body) {
     const url = `${this.apiUrl}${endpoint}`;
+    const closesAtStart = await this.batchPayer?.closeFence();
     for (let staleRetries = 0; ; ) {
-      const response = await this.fetchWithTimeout(url, {
+      const response = await this.sendUnpaid(url, {
         method: "POST",
         headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
         body: JSON.stringify(body)
       });
       if (response.status === 402) {
         try {
-          const paymentRequired = await this.readPaymentRequired(response);
+          let paymentRequired;
+          try {
+            paymentRequired = await this.readPaymentRequired(response);
+          } catch (error) {
+            throw withDisposition(error, "unpaid");
+          }
+          let exactRequired = paymentRequired;
           if (this.batchPayer && staleRetries === 0) {
             const batch = await this.batchPayer.pay(
               paymentRequired,
@@ -10463,39 +12408,75 @@ var SolanaLLMClient = class {
                 method: "POST",
                 headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT, ...paymentHeaders },
                 body: JSON.stringify(body)
-              })
+              }),
+              // A fresh, unpaid challenge after a 429 wait: the request itself,
+              // sent again without a payment. Every error it throws is unpaid.
+              async () => {
+                const challenge = await this.sendUnpaid(url, {
+                  method: "POST",
+                  headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
+                  body: JSON.stringify(body)
+                });
+                if (challenge.status === 402) {
+                  try {
+                    return { kind: "challenge", paymentRequired: await this.readPaymentRequired(challenge) };
+                  } catch (error) {
+                    throw withDisposition(error, "unpaid");
+                  }
+                }
+                if (challenge.ok) return { kind: "served", response: challenge };
+                throw await unpaidApiError(challenge);
+              },
+              closesAtStart
             );
             if (batch.kind === "paid") {
               this.recordSettlement(batch.chargedUsd);
-              return batch.response.json();
-            }
-            if (batch.kind === "failed") {
-              let errorBody;
-              try {
-                errorBody = await batch.response.json();
-              } catch {
-                errorBody = { error: "Request failed" };
-              }
-              throw new APIError(`API error after payment: ${batch.response.status}`, batch.response.status, sanitizeErrorResponse(errorBody));
+              return await this.readPaidJson(batch.response);
             }
+            if (batch.kind === "served") return await this.readUnpaidJson(batch.response);
+            if (batch.kind === "failed") throw batch.error;
+            exactRequired = batch.paymentRequired ?? paymentRequired;
           }
-          return await this.handlePaymentAndRetry(url, body, paymentRequired, staleRetries > 0);
+          return await this.handlePaymentAndRetry(url, body, exactRequired, staleRetries > 0);
         } catch (error) {
           if (!(error instanceof SafeStaleBlockhashError) || staleRetries >= STALE_BLOCKHASH_RETRY_BACKOFFS_MS.length) throw error;
           await waitForStaleRetry(staleRetries++);
           continue;
         }
       }
-      if (!response.ok) {
-        let errorBody;
-        try {
-          errorBody = await response.json();
-        } catch {
-          errorBody = { error: "Request failed" };
-        }
-        throw new APIError(`API error: ${response.status}`, response.status, sanitizeErrorResponse(errorBody));
-      }
-      return response.json();
+      if (!response.ok) throw await unpaidApiError(response);
+      return await this.readUnpaidJson(response);
+    }
+  }
+  /**
+   * Read the JSON body of a 2xx served without a payment: the free tier, or
+   * with an API key, where this very request was the billed one.
+   */
+  async readUnpaidJson(response) {
+    try {
+      return await response.json();
+    } catch (error) {
+      throw withDisposition(error, this.apiAuth ? "paid-or-in-doubt" : "unpaid");
+    }
+  }
+  /**
+   * Send a request that carries no payment, marking what it throws with its
+   * {@link RetryDisposition}: `"unpaid"` with a wallet; with an API key, see
+   * {@link accountErrorDisposition} (the request itself is billed).
+   */
+  async sendUnpaid(url, init) {
+    try {
+      return await this.fetchWithTimeout(url, init);
+    } catch (error) {
+      throw withDisposition(error, this.apiAuth ? accountErrorDisposition(error) : "unpaid");
+    }
+  }
+  /** Read a paid 2xx response's JSON body. The call was charged, so a failure here is never retried. */
+  async readPaidJson(response) {
+    try {
+      return await response.json();
+    } catch (error) {
+      throw withDisposition(error, "paid-or-in-doubt");
     }
   }
   /**
@@ -10663,24 +12644,30 @@ var SolanaLLMClient = class {
     return { paymentPayload, costUsd: parseFloat(details.amount) / 1e6 };
   }
   async handlePaymentAndRetry(url, body, paymentRequired, forceFreshBlockhash = false) {
-    const { paymentPayload, costUsd } = await this.signExactPayment(
-      url,
-      paymentRequired,
-      forceFreshBlockhash,
-      `${this.apiUrl}/v1/chat/completions`
-    );
-    const retryResponse = await this.fetchWithTimeout(url, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "User-Agent": USER_AGENT,
-        "PAYMENT-SIGNATURE": paymentPayload
-      },
-      body: JSON.stringify(body)
-    });
+    let signed;
+    try {
+      signed = await this.signExactPayment(url, paymentRequired, forceFreshBlockhash, `${this.apiUrl}/v1/chat/completions`);
+    } catch (error) {
+      throw withDisposition(error, "unpaid");
+    }
+    const { paymentPayload, costUsd } = signed;
+    let retryResponse;
+    try {
+      retryResponse = await this.fetchWithTimeout(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "User-Agent": USER_AGENT,
+          "PAYMENT-SIGNATURE": paymentPayload
+        },
+        body: JSON.stringify(body)
+      });
+    } catch (error) {
+      throw withDisposition(error, "paid-or-in-doubt");
+    }
     await this.assertPaid(retryResponse);
     this.recordSettlement(costUsd);
-    return retryResponse.json();
+    return this.readPaidJson(retryResponse);
   }
   async requestWithPaymentRaw(endpoint, body) {
     const url = `${this.apiUrl}${endpoint}`;
@@ -10787,14 +12774,15 @@ var SolanaLLMClient = class {
    * lives.
    * @param response - the reply to the paid request.
    * @throws SafeStaleBlockhashError when the caller should re-sign, PaymentError
-   *   when it should not, APIError for any other failure.
+   *   when it should not, APIError for any other failure. Every one but the
+   *   first is marked `"paid-or-in-doubt"`: the payment may have settled.
    */
   async assertPaid(response) {
     if (response.status === 402) {
       if (await isSafeStaleBlockhashResponse(response)) {
-        throw new SafeStaleBlockhashError();
+        throw withDisposition(new SafeStaleBlockhashError(), "unpaid");
       }
-      throw new PaymentError("Payment was rejected. Check your Solana USDC balance.");
+      throw withDisposition(new PaymentError("Payment was rejected. Check your Solana USDC balance."), "paid-or-in-doubt");
     }
     if (!response.ok) {
       let errorBody;
@@ -10803,7 +12791,11 @@ var SolanaLLMClient = class {
       } catch {
         errorBody = { error: "Request failed" };
       }
-      throw new APIError(`API error after payment: ${response.status}`, response.status, sanitizeErrorResponse(errorBody));
+      const unverified = response.status === 503 && errorBody?.code === "PAYMENT_VERIFICATION_UNAVAILABLE";
+      throw withDisposition(
+        new APIError(`API error after payment: ${response.status}`, response.status, sanitizeErrorResponse(errorBody)),
+        unverified ? "unpaid" : "paid-or-in-doubt"
+      );
     }
   }
   /** Count one settled x402 payment against the session total. */
@@ -11274,8 +13266,12 @@ var AnthropicClient = class {
         baseURL: this._apiUrl,
         apiKey: "blockrun",
         fetch: this._x402Fetch.bind(this),
-        // Account POSTs may already be billed when an upstream error arrives.
-        ...this.apiAuth ? { maxRetries: 0 } : {}
+        // Never let the Anthropic SDK retry. It retries 408/409/429/5xx and
+        // connection errors by calling this fetch again, which in wallet mode
+        // runs the whole x402 flow and signs a NEW payment each time (three
+        // payments for one call at the default maxRetries of 2); in account
+        // mode the POST itself may already be billed.
+        maxRetries: 0
       });
       return this._client;
     })();
@@ -11369,8 +13365,11 @@ export {
   AnthropicClient,
   BASE_CHAIN_ID,
   BLOCKRUN_SOL_OPERATOR,
+  BatchCloseDeferredError,
+  BatchPaymentUnresolvedError,
   BlockrunClient,
   BlockrunError,
+  DEFAULT_BATCH_RATE_LIMIT,
   EVM_NETWORKS,
   ImageClient,
   KNOWN_PROVIDERS,
@@ -11433,6 +13432,7 @@ export {
   loadWallet,
   logCost,
   parsePaymentRequired,
+  retryDisposition,
   saveSolanaWallet,
   saveToCache,
   saveWallet,