@haven_ai/sdk 0.10.0-alpha.0 → 0.12.0-alpha.0

package/dist/index.js

@@ -1,9 +1,9 @@
-import { decodeBase64Json, selectStandardPaymentOption, buildX402IdempotencyKey, x402AuthorizationAmount, assertBoundDirectPaymentUserOp, assertFundingLegPaysDelegate, HavenTypedDataRefusedError, assertOwnSettlementChild, parsePaymentRequiredResponse, x402PaymentHeaderNamesSent, SDK_CLIENT_IDENTITY, readClientUpdate, HAVEN_CLIENT_HEADER, isSweepableChain, sweepUsdcAddress, x402PaymentHeaderNamesFor, X402_PAYMENT_HEADER_NAMES, toStandardPaymentRequirements, deriveX402PaymentNonce, encodeBase64Json, x402V2PaymentEnvelope, isErc7710Option, buildSignedTaxDeclaration, encodeTaxDeclarationHeader, selectX402SettlementScheme, selectErc7710PaymentOption, x402AssetTransferMethod, resolveTokenFromAddress, normalizePaymentRequired, X_TAX_DECLARATION_HEADER } from './chunk-MLUWABVT.js';
-export { DEFAULT_NEXT_TOOL_BY_ACTION, ERC7710_ASSET_TRANSFER_METHOD, HAVEN_CLIENT_HEADER, HAVEN_MINIMUM_NODE_VERSION, HavenTypedDataRefusedError, MAX_TASK_BUDGET_TTL_SECONDS, NEXT_TOOL_SERVER_NAMES, NEXT_TOOL_SERVER_ROLES, SDK_CLIENT_IDENTITY, SDK_VERSION, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, TRANSFER_WITH_AUTHORIZATION_TYPES, TYPED_DATA_NOT_ALLOWED, X402PaymentHeaderValidationError, X402_LEGACY_PAYMENT_HEADER_NAME, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_PAYMENT_HEADER_NAME, X402_PAYMENT_HEADER_NAMES_SENT, X402_PAYMENT_NONCE_TAG, X402_PAYMENT_REQUIRED_HEADER_NAME, X402_PAYMENT_RESPONSE_HEADER_NAME, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, assertBoundDirectPaymentUserOp, assertOwnTaskBudgetCloseUserOp, assertOwnTaskChild, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, createNextStepBuilder, decodeBase64Json, decodeBase64Utf8, defaultNextToolFor, deriveX402PaymentNonce, encodeBase64Json, encodeBase64Utf8, encodePaymentProof, hashDelegation, havenClientIdentity, isErc7710Option, isSupportedNodeVersion, isSweepableChain, isTaskChildTypedData, normalizePaymentRequired, parseNextTool, parsePaymentRequired, parsePaymentRequiredResponse, readClientUpdate, renderNextTool, resolveTokenBySymbol, resolveTokenFromAddress, selectErc7710PaymentOption, selectPaymentOption, selectStandardPaymentOption, selectX402SettlementScheme, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, unsupportedNodeVersionMessage, validateStandardX402PaymentHeader, x402AssetTransferMethod, x402AuthorizationAmount, x402FacilitatorAddresses, x402PaymentHeaderNamesFor, x402RetryHeadersFor, x402V2PaymentEnvelope } from './chunk-MLUWABVT.js';
-import { verifyPaymentReceipt } from './chunk-EWTHDEIW.js';
-export { RECEIPT_VERSION, verifyPaymentReceipt } from './chunk-EWTHDEIW.js';
-import { HavenSigningError, HavenError, DEFAULT_CONFIRMATION_TIMEOUT_MS, HavenApiError, assertUserOpTypedDataBinding, AgentPaymentRail, AgentPaymentPhase, HavenTimeoutError, X402TaskBudgetMismatchError, X402UnexpectedStatusError, X402AlreadySettledError, MerchantTimeoutError, AgentPaymentWarningCode, AgentPaymentNextAction, HavenPaymentStateError, HavenZeroSettlementHashError, X402Erc7710AlreadySettledError, chainIdForNetwork } from './chunk-TD2PHUYP.js';
-export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, AgentPaymentWarningCode, CONNECTOR_PACKAGE_NAME, DEFAULT_CONFIRMATION_TIMEOUT_MS, DIRECT_SIGN_CONTEXT_VERSION, ENTRY_POINT_V07, HAVEN_CONNECTOR_CHANNEL, HYBRID_DELEGATOR_DOMAIN_NAME, HYBRID_DELEGATOR_DOMAIN_VERSION, HavenApiError, HavenError, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, HavenUnsupportedSignerVersionError, HavenUserOpBindingError, HavenZeroSettlementHashError, MerchantTimeoutError, PACKED_USER_OPERATION_FIELDS, ROOT_AUTHORITY, SIGNER_UPDATE_FALLBACK, SignerRefusalCode, TASK_SIGN_CONTEXT_VERSION, X402AlreadySettledError, X402Erc7710AlreadySettledError, X402TaskBudgetMismatchError, X402UnexpectedStatusError, assertUserOpTypedDataBinding, connectorRerunCommand, connectorSpec, connectorUpgradeCommand, deriveDelegateAccountAddress, isConnectorChannel, isPackedUserOperationTypedData, packedUserOperationHash, resolveConnectorChannel, signerUpdateFallback, verifySettlementChild } from './chunk-TD2PHUYP.js';
+import { decodeBase64Json, selectStandardPaymentOption, buildX402IdempotencyKey, x402AuthorizationAmount, assertBoundDirectPaymentUserOp, assertFundingLegPaysDelegate, HavenTypedDataRefusedError, assertOwnSettlementChild, parsePaymentRequiredResponse, x402PaymentHeaderNamesSent, SDK_CLIENT_IDENTITY, readClientUpdate, HAVEN_CLIENT_HEADER, isSweepableChain, sweepUsdcAddress, x402PaymentHeaderNamesFor, X402_PAYMENT_HEADER_NAMES, toStandardPaymentRequirements, deriveX402PaymentNonce, encodeBase64Json, x402V2PaymentEnvelope, isErc7710Option, buildSignedTaxDeclaration, encodeTaxDeclarationHeader, selectX402SettlementScheme, selectErc7710PaymentOption, x402AssetTransferMethod, resolveTokenFromAddress, normalizePaymentRequired, X_TAX_DECLARATION_HEADER } from './chunk-7M3CIW7W.js';
+export { DEFAULT_NEXT_TOOL_BY_ACTION, ERC7710_ASSET_TRANSFER_METHOD, HAVEN_CLIENT_HEADER, HAVEN_MINIMUM_NODE_VERSION, HavenTypedDataRefusedError, MAX_TASK_BUDGET_TTL_SECONDS, NEXT_TOOL_SERVER_NAMES, NEXT_TOOL_SERVER_ROLES, SDK_CLIENT_IDENTITY, SDK_VERSION, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, TRANSFER_WITH_AUTHORIZATION_TYPES, TYPED_DATA_NOT_ALLOWED, X402PaymentHeaderValidationError, X402_LEGACY_PAYMENT_HEADER_NAME, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_PAYMENT_HEADER_NAME, X402_PAYMENT_HEADER_NAMES_SENT, X402_PAYMENT_NONCE_TAG, X402_PAYMENT_REQUIRED_HEADER_NAME, X402_PAYMENT_RESPONSE_HEADER_NAME, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, assertBoundDirectPaymentUserOp, assertOwnTaskBudgetCloseUserOp, assertOwnTaskChild, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, createNextStepBuilder, decodeBase64Json, decodeBase64Utf8, defaultNextToolFor, deriveX402PaymentNonce, encodeBase64Json, encodeBase64Utf8, encodePaymentProof, hashDelegation, havenClientIdentity, isErc7710Option, isSupportedNodeVersion, isSweepableChain, isTaskChildTypedData, normalizePaymentRequired, parseNextTool, parsePaymentRequired, parsePaymentRequiredResponse, readClientUpdate, renderNextTool, resolveTokenBySymbol, resolveTokenFromAddress, selectErc7710PaymentOption, selectPaymentOption, selectStandardPaymentOption, selectX402SettlementScheme, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, unsupportedNodeVersionMessage, validateStandardX402PaymentHeader, x402AssetTransferMethod, x402AuthorizationAmount, x402FacilitatorAddresses, x402PaymentHeaderNamesFor, x402RetryHeadersFor, x402V2PaymentEnvelope } from './chunk-7M3CIW7W.js';
+import { verifyPaymentReceipt } from './chunk-WFTGZS24.js';
+export { RECEIPT_VERSION, verifyPaymentReceipt } from './chunk-WFTGZS24.js';
+import { HavenSigningError, HavenError, DEFAULT_CONFIRMATION_TIMEOUT_MS, HavenApiError, assertUserOpTypedDataBinding, AgentPaymentRail, AgentPaymentPhase, HavenTimeoutError, X402TaskBudgetMismatchError, X402UnexpectedStatusError, X402AlreadySettledError, MerchantTimeoutError, AgentPaymentWarningCode, AgentPaymentNextAction, FundingConfirmationUnknownError, FundingRevertedError, HavenPaymentStateError, HavenZeroSettlementHashError, X402Erc7710AlreadySettledError, chainIdForNetwork } from './chunk-UPEDQLAL.js';
+export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, AgentPaymentWarningCode, CONNECTOR_PACKAGE_NAME, DEFAULT_CONFIRMATION_TIMEOUT_MS, DIRECT_SIGN_CONTEXT_VERSION, ENTRY_POINT_V07, FundingConfirmationUnknownError, FundingRevertedError, HAVEN_CONNECTOR_CHANNEL, HYBRID_DELEGATOR_DOMAIN_NAME, HYBRID_DELEGATOR_DOMAIN_VERSION, HavenApiError, HavenError, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, HavenUnsupportedSignerVersionError, HavenUserOpBindingError, HavenZeroSettlementHashError, MerchantTimeoutError, PACKED_USER_OPERATION_FIELDS, ROOT_AUTHORITY, SIGNER_UPDATE_FALLBACK, SignerRefusalCode, TASK_SIGN_CONTEXT_VERSION, X402AlreadySettledError, X402Erc7710AlreadySettledError, X402TaskBudgetMismatchError, X402UnexpectedStatusError, assertUserOpTypedDataBinding, connectorRerunCommand, connectorSpec, connectorUpgradeCommand, deriveDelegateAccountAddress, isConnectorChannel, isPackedUserOperationTypedData, packedUserOperationHash, resolveConnectorChannel, signerUpdateFallback, verifySettlementChild } from './chunk-UPEDQLAL.js';
 import { hashTypedData } from 'viem';
 import { ethers } from 'ethers';
 import { AsyncLocalStorage } from 'async_hooks';
@@ -143,12 +143,16 @@ var HavenApiTransport = class {
       return data;
     } catch (err) {
       if (err instanceof HavenApiError) throw err;
+      const failureCause = { kind: "no_answer", method };
       if (err instanceof Error && err.name === "AbortError") {
-        throw new HavenApiError(`Request to ${path} timed out`, 408);
+        throw new HavenApiError(`Request to ${path} timed out`, 408, void 0, void 0, failureCause);
       }
       throw new HavenApiError(
         `Request to ${path} failed: ${err instanceof Error ? err.message : String(err)}`,
-        0
+        0,
+        void 0,
+        void 0,
+        failureCause
       );
     } finally {
       clearTimeout(timeout);
@@ -354,6 +358,24 @@ function mapPaymentReceipt(raw) {
   if ("approval_request_id" in raw) {
     receipt.approvalRequestId = raw.approval_request_id ?? null;
   }
+  if ("settlement_scheme" in raw) {
+    receipt.settlementScheme = raw.settlement_scheme ?? null;
+  }
+  if ("budget_delegation_hash" in raw) {
+    receipt.budgetDelegationHash = raw.budget_delegation_hash ?? null;
+  }
+  if ("delivery_quality" in raw) {
+    receipt.deliveryQuality = raw.delivery_quality ?? null;
+  }
+  if ("delivery_note" in raw) {
+    receipt.deliveryNote = raw.delivery_note ?? null;
+  }
+  if ("delivery_reported_at" in raw) {
+    receipt.deliveryReportedAt = raw.delivery_reported_at ?? null;
+  }
+  if ("delivery_reference" in raw) {
+    receipt.deliveryReference = raw.delivery_reference ?? null;
+  }
   return receipt;
 }
 
@@ -473,7 +495,7 @@ function throwPaymentStateError(label, raw) {
     throw new HavenPaymentStateError(state.message, statusCode, state, raw);
   }
   if (raw.status === "pending_approval") {
-    throw new HavenApiError(
+    throw HavenApiError.deterministic(
       `${label} exceeds the agent's on-chain budget and was declined; no approval is pending and none will arrive (payment_id: ${raw.payment_id}).`,
       statusCode,
       raw
@@ -488,6 +510,7 @@ function throwPaymentStateError(label, raw) {
   }
   const paymentId = raw.payment_id ? ` (payment_id: ${raw.payment_id})` : "";
   const message = raw.error ?? `${label} ${raw.status}${paymentId}`;
+  if (statusCode >= 500) throw HavenApiError.deterministic(message, statusCode, raw);
   throw new HavenApiError(message, statusCode, raw);
 }
 
@@ -542,12 +565,30 @@ var MerchantEgressRefusedError = class extends HavenError {
   url;
   refusal;
   beforeRequest;
-  constructor(message, url, refusal, beforeRequest) {
-    super(message, MERCHANT_EGRESS_REFUSED_CODE, 400);
+  /** #4257: the redirect status that was not followed, when a redirect was refused. */
+  redirectStatus;
+  /**
+   * #4257: set only when `url` IS the redirect target (a cross-origin body
+   * re-send, a spent hop budget, a hop `assertUrl` refused). A refusal that
+   * stopped at the answering URL itself (a non-GET redirect, a missing or
+   * unresolvable Location) leaves it unset, and `url` is that answering URL.
+   */
+  redirectTarget;
+  /**
+   * #4257: set when the refusal interrupted a PAID delivery and the local
+   * completion has re-thrown it with the payment it belongs to — the funded,
+   * undelivered state, never "nothing happened".
+   */
+  settlementScheme;
+  constructor(message, url, refusal, beforeRequest, extra = {}) {
+    super(message, MERCHANT_EGRESS_REFUSED_CODE, 400, extra.paymentId);
     this.name = "MerchantEgressRefusedError";
     this.url = url;
     this.refusal = refusal;
     this.beforeRequest = beforeRequest;
+    this.redirectStatus = extra.redirectStatus;
+    this.redirectTarget = extra.redirectTarget;
+    this.settlementScheme = extra.settlementScheme;
   }
 };
 var MERCHANT_EGRESS_RESPONSE_CAP_CODE = "MERCHANT_EGRESS_RESPONSE_CAP";
@@ -662,6 +703,29 @@ var MCP_X402_PAYMENT_META_KEY = "x402/payment";
 var MCP_X402_PAYMENT_RESPONSE_META_KEY = "x402/payment-response";
 var X402_RETRY_REJECTED_STATUS = 402;
 var SESSION_NOT_FOUND_NEXT_ACTION = "reinitialize_then_retry_same_payment_header";
+var CROSS_ORIGIN_REDIRECT_HEADERS = /* @__PURE__ */ new Set([
+  "accept",
+  "accept-language",
+  "user-agent",
+  "x402-wallet"
+]);
+function crossOriginRedirectHeaders(headers) {
+  const kept = new Headers();
+  for (const [name, value] of new Headers(headers)) {
+    if (CROSS_ORIGIN_REDIRECT_HEADERS.has(name)) kept.set(name, value);
+  }
+  return kept;
+}
+var NO_POLICY_MAX_REDIRECTS = 20;
+var REQUEST_BODY_HEADERS = ["content-encoding", "content-language", "content-location", "content-type", "content-length"];
+function redirectedInit(init, status) {
+  const method = (init.method ?? "GET").toUpperCase();
+  const toGet = (status === 301 || status === 302) && method === "POST" || status === 303 && method !== "GET" && method !== "HEAD";
+  if (!toGet) return init;
+  const headers = new Headers(init.headers);
+  for (const name of REQUEST_BODY_HEADERS) headers.delete(name);
+  return { ...init, method: "GET", body: null, headers };
+}
 var McpMerchantTransport = class {
   merchantTimeout;
   fetchImpl;
@@ -692,11 +756,24 @@ var McpMerchantTransport = class {
   }
   /** Fetch a merchant with a settlement-sized timeout and caller cancellation. */
   async fetch(url, init = {}, timeoutMs = this.merchantTimeout, maxBytes) {
+    return this.send(url, init, timeoutMs, maxBytes, false);
+  }
+  /**
+   * `fetch`, plus whether this request is the paid delivery (#4257). A paid
+   * delivery, or any body carrying an x402 payment in `_meta`, is never
+   * re-sent to another origin by a redirect that keeps the body; without a policy every other
+   * request follows that redirect as the platform would, headers reduced.
+   */
+  async send(url, init, timeoutMs, maxBytes, paidDelivery) {
+    const carriesPayment = paidDelivery || bodyCarriesX402Payment(init.body);
     if (!this.egress) {
       const timeoutSignal = AbortSignal.timeout(timeoutMs);
       const signal = init.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;
       try {
-        return await this.fetchImpl(url, { ...init, signal });
+        if (init.redirect === "manual" || init.redirect === "error") {
+          return await this.fetchImpl(url, { ...init, signal });
+        }
+        return await this.followRedirects(url, init, signal, void 0, carriesPayment);
       } catch (err) {
         if (timeoutSignal.aborted) {
           throw new MerchantTimeoutError(`Merchant request timed out after ${timeoutMs}ms: ${url}`);
@@ -704,87 +781,144 @@ var McpMerchantTransport = class {
         throw err;
       }
     }
-    return this.fetchUnderPolicy(url, init, timeoutMs, maxBytes);
+    return this.fetchUnderPolicy(url, init, timeoutMs, maxBytes, carriesPayment);
   }
   /**
    * #3747: the policy path. Every URL — the initial request and each redirect
    * hop — is `assertUrl`-checked BEFORE it connects; redirects run `manual`
    * so nothing is ever followed un-checked; GET redirects are followed up to
-   * `maxGetRedirects` (a redirect on any other method is refused); response
-   * bodies are capped WHILE being read, not after buffering. The timeout
+   * `maxGetRedirects` (a redirect on any other method is refused); a hop to
+   * another origin carries only `CROSS_ORIGIN_REDIRECT_HEADERS` (#4244);
+   * response bodies are capped WHILE being read, not after buffering. The timeout
    * signal spans the WHOLE redirect chain, and `MerchantTimeoutError`
    * classification is preserved.
    */
-  async fetchUnderPolicy(url, init, timeoutMs, maxBytes) {
+  async fetchUnderPolicy(url, init, timeoutMs, maxBytes, carriesPayment) {
     const egress = this.egress;
     try {
       egress.assertUrl(url);
     } catch (err) {
       throw asRefusal(err, url, true);
     }
-    const method = (init.method ?? "GET").toUpperCase();
     const timeoutSignal = AbortSignal.timeout(timeoutMs);
     const signal = init.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;
-    const maxRedirects = egress.maxGetRedirects ?? 0;
+    let finalUrl = url;
+    try {
+      const response = await this.followRedirects(url, init, signal, egress, carriesPayment, (hopUrl) => {
+        finalUrl = hopUrl;
+      });
+      return this.capResponse(response, finalUrl, maxBytes);
+    } catch (err) {
+      if (timeoutSignal.aborted) {
+        throw new MerchantTimeoutError(`Merchant request timed out after ${timeoutMs}ms: ${finalUrl}`);
+      }
+      throw err;
+    }
+  }
+  /**
+   * The redirect follower both paths share (#3747, #4244, #4257). Redirects
+   * run `manual` and every hop is decided here:
+   *
+   * - Under a `policy`, every hop is `assertUrl`-checked before it connects,
+   *   only GET redirects are followed (any other method is refused), up to
+   *   `maxGetRedirects`; a missing or unresolvable Location is refused.
+   * - Without one, the platform's rules are kept: up to
+   *   `NO_POLICY_MAX_REDIRECTS` hops, the Fetch spec's method/body rewrite,
+   *   and a 3xx with no Location returned as the answer.
+   * - On both, a hop to another origin carries only
+   *   `CROSS_ORIGIN_REDIRECT_HEADERS`, never restored on a later hop.
+   * - A hop that would re-send a request body to another origin is refused
+   *   under a policy (which follows GET alone, so this is unreachable there),
+   *   and without one only when `carriesPayment`: the paid delivery, or a body
+   *   carrying an x402 payment in `_meta` (#4257). Any other body-keeping redirect is
+   *   followed with its body, as the platform did, headers reduced.
+   *
+   * `onHop` sees every URL a request goes to, so the caller can name the hop
+   * it was on when the chain stops.
+   */
+  async followRedirects(url, init, signal, policy, carriesPayment, onHop) {
+    const maxRedirects = policy ? policy.maxGetRedirects ?? 0 : NO_POLICY_MAX_REDIRECTS;
     let currentUrl = url;
+    let hopInit = init;
     let hops = 0;
-    try {
-      while (true) {
-        const response = await this.fetchImpl(currentUrl, {
-          ...init,
-          redirect: init.redirect === "error" ? "error" : "manual",
-          signal
-        });
-        if (!isRedirectStatus(response.status)) return this.capResponse(response, currentUrl, maxBytes);
-        if (method !== "GET") {
-          throw new MerchantEgressRefusedError(
-            `Hosted egress policy refuses the ${response.status} redirect from ${currentUrl}: redirects are followed for GET requests only, and this was a ${method}. The request itself was already sent to the checked URL; nothing was sent to the redirect target.`,
-            currentUrl,
-            "redirect_on_non_get",
-            false
-          );
-        }
-        const location = response.headers.get("location");
-        if (!location) {
-          throw new MerchantEgressRefusedError(
-            `Hosted egress policy refuses the ${response.status} redirect from ${currentUrl}: it carries no Location header, so there is no checked target to follow.`,
-            currentUrl,
-            "redirect_missing_location",
-            false
-          );
-        }
-        let next;
+    while (true) {
+      onHop?.(currentUrl);
+      const response = await this.fetchImpl(currentUrl, {
+        ...hopInit,
+        redirect: init.redirect === "error" ? "error" : "manual",
+        signal
+      });
+      if (!isRedirectStatus(response.status)) return response;
+      const method = (hopInit.method ?? "GET").toUpperCase();
+      if (policy && method !== "GET") {
+        throw new MerchantEgressRefusedError(
+          `Hosted egress policy refuses the ${response.status} redirect from ${currentUrl}: redirects are followed for GET requests only, and this was a ${method}. The request itself was already sent to the checked URL; nothing was sent to the redirect target.`,
+          currentUrl,
+          "redirect_on_non_get",
+          false,
+          { redirectStatus: response.status }
+        );
+      }
+      const location = response.headers.get("location");
+      if (!location) {
+        if (!policy) return response;
+        throw new MerchantEgressRefusedError(
+          `Hosted egress policy refuses the ${response.status} redirect from ${currentUrl}: it carries no Location header, so there is no checked target to follow.`,
+          currentUrl,
+          "redirect_missing_location",
+          false,
+          { redirectStatus: response.status }
+        );
+      }
+      let next;
+      try {
+        next = new URL(location, currentUrl).toString();
+      } catch {
+        if (!policy) throw new TypeError(`fetch failed: the redirect from ${currentUrl} has an unresolvable Location header`);
+        throw new MerchantEgressRefusedError(
+          `Hosted egress policy refuses the redirect from ${currentUrl}: its Location header is not a resolvable URL.`,
+          currentUrl,
+          "redirect_invalid_location",
+          false,
+          { redirectStatus: response.status }
+        );
+      }
+      if (!policy && !/^https?:$/.test(new URL(next).protocol)) {
+        throw new TypeError(`fetch failed: the redirect from ${currentUrl} names a non-HTTP(S) URL`);
+      }
+      if (hops >= maxRedirects) {
+        if (!policy) throw new TypeError(`fetch failed: redirect count exceeded (${maxRedirects}) at ${currentUrl}`);
+        throw new MerchantEgressRefusedError(
+          `Hosted egress policy refuses the redirect from ${currentUrl} to ${next}: the ${maxRedirects}-redirect budget for this request is spent.`,
+          next,
+          "redirect_budget_exceeded",
+          false,
+          { redirectStatus: response.status, redirectTarget: next }
+        );
+      }
+      if (policy) {
         try {
-          next = new URL(location, currentUrl).toString();
-        } catch {
-          throw new MerchantEgressRefusedError(
-            `Hosted egress policy refuses the redirect from ${currentUrl}: its Location header is not a resolvable URL.`,
-            currentUrl,
-            "redirect_invalid_location",
-            false
-          );
+          policy.assertUrl(next);
+        } catch (err) {
+          throw asRefusal(err, next, false, { redirectStatus: response.status, redirectTarget: next });
         }
-        if (hops >= maxRedirects) {
+      }
+      hopInit = redirectedInit(hopInit, response.status);
+      if (new URL(next).origin !== new URL(currentUrl).origin) {
+        if (hopInit.body != null && (policy || carriesPayment)) {
           throw new MerchantEgressRefusedError(
-            `Hosted egress policy refuses the redirect from ${currentUrl} to ${next}: the ${maxRedirects}-redirect budget for this request is spent.`,
+            carriesPayment ? `The ${response.status} redirect of a paid request from ${currentUrl} to ${next} was not followed: following it would re-send the paid request to a different origin. The paid request, payment header and body included, was already delivered to ${currentUrl}; nothing was sent to ${next}.` : `Refusing the ${response.status} redirect from ${currentUrl} to ${next}: it would re-send the request body to a different origin. The request was already sent to the first URL; nothing was sent to the redirect target.`,
             next,
-            "redirect_budget_exceeded",
-            false
+            "redirect_cross_origin_body",
+            false,
+            { redirectStatus: response.status, redirectTarget: next }
           );
         }
-        try {
-          egress.assertUrl(next);
-        } catch (err) {
-          throw asRefusal(err, next, false);
-        }
-        hops++;
-        currentUrl = next;
-      }
-    } catch (err) {
-      if (timeoutSignal.aborted) {
-        throw new MerchantTimeoutError(`Merchant request timed out after ${timeoutMs}ms: ${currentUrl}`);
+        hopInit = { ...hopInit, headers: crossOriginRedirectHeaders(hopInit.headers) };
       }
-      throw err;
+      await response.body?.cancel().catch(() => void 0);
+      hops++;
+      currentUrl = next;
     }
   }
   /**
@@ -962,7 +1096,7 @@ var McpMerchantTransport = class {
       if (send.includes(name)) headers.set(name, paymentHeader);
       else headers.delete(name);
     }
-    return this.fetch(url, withMcpPaymentMeta({ ...init, headers }, paymentHeader), this.budgetFor("delivery"), this.capFor("delivery"));
+    return this.send(url, withMcpPaymentMeta({ ...init, headers }, paymentHeader), this.budgetFor("delivery"), this.capFor("delivery"), true);
   }
   /**
    * #3171: deliver the payment; if the merchant answers its unknown-session
@@ -1099,6 +1233,27 @@ function withMcpPaymentMeta(init, paymentHeader) {
 function encodeMcpSettlementReceipt(settlement) {
   return encodeBase64Json(settlement);
 }
+function bodyCarriesX402Payment(body) {
+  let text;
+  if (typeof body === "string") text = body;
+  else if (body instanceof Uint8Array || body instanceof ArrayBuffer) {
+    try {
+      text = new TextDecoder("utf-8", { fatal: true }).decode(body);
+    } catch {
+      return false;
+    }
+  } else return false;
+  let request;
+  try {
+    request = JSON.parse(text);
+  } catch {
+    return false;
+  }
+  return Array.isArray(request) ? request.some(messageCarriesX402Payment) : messageCarriesX402Payment(request);
+}
+function messageCarriesX402Payment(message) {
+  return isRecord(message) && isRecord(message.params) && isRecord(message.params._meta) && message.params._meta[MCP_X402_PAYMENT_META_KEY] !== void 0;
+}
 function parseJsonRpcToolsCall(body) {
   if (typeof body !== "string") return void 0;
   let request;
@@ -1137,10 +1292,10 @@ function isRecord(value) {
 function isRedirectStatus(status) {
   return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
 }
-function asRefusal(err, url, beforeRequest) {
+function asRefusal(err, url, beforeRequest, redirect) {
   if (!(err instanceof MerchantEgressRefusedError)) return err;
-  if (err.beforeRequest === beforeRequest) return err;
-  return new MerchantEgressRefusedError(err.message, url, err.refusal, beforeRequest);
+  if (err.beforeRequest === beforeRequest && !redirect) return err;
+  return new MerchantEgressRefusedError(err.message, url, err.refusal, beforeRequest, redirect);
 }
 async function captureMerchantResponse(response) {
   const merchant_body = await response.text().catch((err) => {
@@ -1214,6 +1369,17 @@ function deriveReadiness(status, allowances) {
   if (status !== "active") return "revoked";
   return allowances.some((allowance) => safeBigInt(allowance.remainingAtomic) > 0n) ? "ready" : "needs_approval";
 }
+function deriveBudgetRefillsAt(readiness, allowances) {
+  if (readiness !== "needs_approval" || allowances.length === 0) return null;
+  const times = allowances.map((allowance) => allowance.nextRefillAt).filter((at) => at !== null && !Number.isNaN(Date.parse(at)));
+  if (times.length === 0) return null;
+  return times.reduce((earliest, at) => Date.parse(at) < Date.parse(earliest) ? at : earliest);
+}
+function deriveBudgetEndedAt(readiness, allowances, budgetEndedAt) {
+  if (readiness !== "needs_approval" || allowances.length > 0) return null;
+  if (!budgetEndedAt || Number.isNaN(Date.parse(budgetEndedAt))) return null;
+  return budgetEndedAt;
+}
 function formatRemainingDisplay(tokenAddress, tokenSymbol, remainingAtomic) {
   const token = resolveTokenFromAddress(tokenAddress);
   return token ? `${formatAtomicAmount(safeBigInt(remainingAtomic), token.decimals)} ${tokenSymbol}` : `${remainingAtomic} ${tokenSymbol} (atomic; unknown decimals)`;
@@ -1260,6 +1426,7 @@ function mapTaskBudget(raw) {
     status: raw.status,
     expiresAt: raw.expires_at,
     isExpired: raw.is_expired,
+    ...raw.is_live === void 0 ? {} : { isLive: raw.is_live },
     createdAt: raw.created_at,
     openedAt: raw.opened_at,
     closedAt: raw.closed_at,
@@ -1381,11 +1548,23 @@ var AccountReads = class {
         isResetPending: allowance.onchain.isResetPending,
         // #3731: same provenance as the detailed read's field — the compact
         // row is a projection of the same allowance, never a second source.
-        fundsCoverRemaining: allowance.fundsCoverRemaining
+        fundsCoverRemaining: allowance.fundsCoverRemaining,
+        nextRefillAt: allowance.nextRefillAt
       };
     });
     const readiness = deriveReadiness(agent.status, allowances);
-    return { ...agent, readiness, spend_authority_readiness: readiness, allowances, taskBudgets, pendingSubBudgetSignatures };
+    const budgetRefillsAt = deriveBudgetRefillsAt(readiness, allowances);
+    const budgetEndedAt = deriveBudgetEndedAt(readiness, allowances, allowanceSummary.budgetEndedAt);
+    return {
+      ...agent,
+      readiness,
+      spend_authority_readiness: readiness,
+      budgetRefillsAt,
+      budgetEndedAt,
+      allowances,
+      taskBudgets,
+      pendingSubBudgetSignatures
+    };
   }
   /**
    * #3329: `GET /task-budgets?status=open`, mapped to the condensed summary
@@ -1413,7 +1592,8 @@ var AccountReads = class {
    * an agent can still act on, and read-by-id (`haven_get_task_budget`) is
    * the any-status surface for everything else:
    *
-   * - `closing` ALWAYS stays visible, expired or not — the close submit is
+   * - `closing` stays visible until its expiry (#3773; an expired `closing`
+   *   row drops, #3923) — the close submit is
    *   in flight and the signer's close refusal tells the caller to re-check
    *   exactly this row's status;
    * - `closed` rows drop (terminal — `closed_at` names what happened, and
@@ -1422,10 +1602,14 @@ var AccountReads = class {
    *   budget reserves nothing and pays nothing);
    * - unexpired `pending` and `open` rows stay.
    *
-   * The same filter also runs here, client-side: it is what keeps the list
-   * bounded against a backend that predates `status=live`, which refuses the
-   * value with a 400 — that refusal (and only that) falls back to
-   * `status=all`. A row whose wire carries
+   * A filter also runs here, client-side. A row carrying the backend's
+   * `is_live` (#3922) is kept exactly when it is true — the server's own
+   * `status=live` verdict. A row without it (an older backend) is derived by
+   * the same rule: `closing` stays until its expiry, then drops (#3923), as
+   * the backend does since #3773. That is
+   * what keeps the list bounded against a backend that predates `status=live`,
+   * which refuses the value with a 400 — that refusal (and only that) falls
+   * back to `status=all`. A row whose wire carries
    * no `is_expired` is treated as unexpired — the degraded read errs toward
    * KEEPING rows, never toward hiding one the agent could still act on.
    */
@@ -1439,7 +1623,9 @@ var AccountReads = class {
       });
       const rows = raw?.task_budgets;
       if (!Array.isArray(rows)) return [];
-      return rows.map((row) => mapTaskBudget(row)).filter((tb) => tb.status === "closing" || !tb.isExpired && tb.status !== "closed").map((tb) => summarizeTaskBudget(tb));
+      return rows.map((row) => mapTaskBudget(row)).filter(
+        (tb) => tb.isLive !== void 0 ? tb.isLive : !tb.isExpired && tb.status !== "closed"
+      ).map((tb) => summarizeTaskBudget(tb));
     } catch {
       return [];
     }
@@ -1474,6 +1660,9 @@ var AccountReads = class {
       accountAddress: raw.account_address,
       delegateAddress: raw.delegate_address,
       chainId: raw.chain_id,
+      // #4352: a non-empty parseable date → itself; anything else (absent on
+      // an older backend, null when no budget has ended) → null.
+      budgetEndedAt: typeof raw.budget_ended_at === "string" && !Number.isNaN(Date.parse(raw.budget_ended_at)) ? raw.budget_ended_at : null,
       supersededBy: mapSupersession(raw.superseded_by),
       allowances: raw.allowances.map((allowance) => ({
         id: allowance.id,
@@ -1492,6 +1681,9 @@ var AccountReads = class {
         // "unverifiable", not a missing key. The key is absent on the wire
         // when the remaining is 0; that maps to null here too.
         fundsCoverRemaining: allowance.funds_cover_remaining === true || allowance.funds_cover_remaining === false ? allowance.funds_cover_remaining : null,
+        // #4355: a non-empty string → itself; anything else (absent on an
+        // older backend, null when the budget never refills) → null.
+        nextRefillAt: typeof allowance.next_refill_at === "string" && allowance.next_refill_at !== "" ? allowance.next_refill_at : null,
         remainingDisplay: formatRemainingDisplay(allowance.token_address, allowance.token_symbol, allowance.onchain.remaining),
         onchain: {
           amount: allowance.onchain.amount,
@@ -2117,7 +2309,7 @@ var X402FundingLeg = class {
     }
     this.assertSignableAuthorizationState("x402 payment", raw);
     if (!raw.sign_data?.hash) {
-      throw new HavenApiError("No sign_hash returned from x402/authorize", 500, raw);
+      throw HavenApiError.deterministic("No sign_hash returned from x402/authorize", 500, raw);
     }
     const sig = await this.signForData(raw.sign_data, {
       asset: option.asset,
@@ -2239,20 +2431,27 @@ var X402FundingLeg = class {
    * Skipped when `chainRpcs` does not include the chain; in that case Haven's
    * backend has already confirmed on-chain submission and callers accept the
    * small propagation window as a trade-off for not configuring an RPC URL.
+   *
+   * #4470: the two outcomes are typed apart. ethers 6 `waitForTransaction`
+   * REJECTS on its timeout (and on an RPC failure) rather than resolving
+   * null, so that path is `FundingConfirmationUnknownError` — funding may
+   * have moved. A mined receipt with `status !== 1` is `FundingRevertedError`.
    */
   async waitForFundingTx(txHash, chainId, timeoutMs = 3e4) {
     if (!txHash || !chainId) return;
     const rpcUrl = this.chainRpcs[chainId];
     if (!rpcUrl) return;
     const provider = createJsonRpcProvider(rpcUrl);
-    const onChainReceipt = await provider.waitForTransaction(txHash, 1, timeoutMs);
-    if (!onChainReceipt || onChainReceipt.status !== 1) {
-      throw new HavenApiError(
-        "Funding tx did not confirm on-chain within the timeout window.",
-        500,
-        { txHash, chainId }
-      );
+    let onChainReceipt;
+    try {
+      onChainReceipt = await provider.waitForTransaction(txHash, 1, timeoutMs);
+    } catch (err) {
+      throw new FundingConfirmationUnknownError(txHash, chainId, err instanceof Error ? err.message : String(err));
     }
+    if (!onChainReceipt) {
+      throw new FundingConfirmationUnknownError(txHash, chainId, "no receipt within the timeout window");
+    }
+    if (onChainReceipt.status !== 1) throw new FundingRevertedError(txHash, chainId);
   }
   /**
    * Can the delegate EOA still fund an authorization for `amountAtomic`?
@@ -2434,7 +2633,7 @@ var X402Erc7710 = class {
       ...options.subBudgetId ? { subBudgetId: options.subBudgetId } : {}
     });
     if (!raw.payment_id) {
-      throw new HavenApiError("No payment_id returned from x402/authorize", 500, raw);
+      throw HavenApiError.deterministic("No payment_id returned from x402/authorize", 500, raw);
     }
     if (raw.status === "confirmed" && raw.tx_hash) {
       const requestedUrl = options.resourceUrl ?? paymentRequired.resource?.url;
@@ -2451,7 +2650,7 @@ var X402Erc7710 = class {
     }
     const signData = raw.sign_data;
     if (signData?.signature_scheme !== "eip712_delegation" || !signData.typed_data) {
-      throw new HavenApiError(
+      throw HavenApiError.deterministic(
         `x402/authorize did not return an erc7710 settlement child (signature_scheme was ${JSON.stringify(signData?.signature_scheme)}). Refusing to sign a payload this path did not ask for.`,
         500,
         raw
@@ -2494,7 +2693,7 @@ var X402Erc7710 = class {
       throw err;
     }
     if (!settled.payment_header) {
-      throw new HavenApiError(
+      throw HavenApiError.deterministic(
         "x402 settle returned no payment_header \u2014 the merchant cannot be retried.",
         500,
         settled
@@ -2615,6 +2814,26 @@ function toolError(err) {
   };
 }
 
+// src/merchant-answer.ts
+function decidePostFundingMerchantAnswer(input) {
+  const inBandChallenge = input.toolResult ? extractMcpPaymentRequired(input.toolResult) : void 0;
+  const headerReceipt = input.paymentResponseHeader;
+  const protocolReceiptHeaderName = headerReceipt ? "PAYMENT-RESPONSE" : input.metaSettlement ? `_meta.${MCP_X402_PAYMENT_RESPONSE_META_KEY}` : void 0;
+  const protocolReceiptHeader = headerReceipt ?? (input.metaSettlement ? encodeMcpSettlementReceipt(input.metaSettlement) : void 0);
+  const settlement = parseMerchantSettlement(headerReceipt ?? null);
+  const settlementTxHash = settlement.settlementTxHash ?? (typeof input.metaSettlement?.transaction === "string" ? input.metaSettlement.transaction : void 0);
+  const plainToolErrorAfterFunding = input.toolResult?.isError === true && inBandChallenge === void 0 && !settlementTxHash;
+  const inBandRejection = inBandChallenge !== void 0 || input.metaSettlement?.success === false || plainToolErrorAfterFunding;
+  return {
+    accepted: input.httpOk && !inBandRejection,
+    inBandRejection,
+    plainToolErrorAfterFunding,
+    settlementTxHash,
+    protocolReceiptHeader,
+    protocolReceiptHeaderName
+  };
+}
+
 // src/merchant-completion.ts
 var MERCHANT_BODY_SNIPPET_LIMIT = 1e3;
 var EVIDENCE_RETRY_DELAYS_MS = [1e3, 2e3, 4e3];
@@ -2645,10 +2864,10 @@ var MerchantCompletion = class {
   }
   async retryRequest(url, initialInit, paymentRequired, receipt) {
     if (!receipt.accepted) {
-      throw new HavenApiError("No accepted x402 option was recorded for payment retry", 500);
+      throw HavenApiError.deterministic("No accepted x402 option was recorded for payment retry", 500);
     }
     if (!receipt.paymentHeader) {
-      throw new HavenApiError("No x402 payment header was returned for payment retry", 500);
+      throw HavenApiError.deterministic("No x402 payment header was returned for payment retry", 500);
     }
     let retryInit = initialInit;
     if (this.getTaxDeclarationHeader && this.delegateKey) {
@@ -2664,16 +2883,31 @@ var MerchantCompletion = class {
         retryInit = withTaxDeclarationHeader(initialInit, void 0);
       }
     }
-    const retryResponse = await this.merchantTransport.deliverPaymentRecoveringSession(
-      url,
-      retryInit,
-      receipt.paymentHeader,
-      () => this.merchantTransport.initialize(url, initialInit)
-    );
+    let retryResponse;
+    try {
+      retryResponse = await this.merchantTransport.deliverPaymentRecoveringSession(
+        url,
+        retryInit,
+        receipt.paymentHeader,
+        () => this.merchantTransport.initialize(url, initialInit)
+      );
+    } catch (err) {
+      if (err instanceof MerchantEgressRefusedError && !err.beforeRequest) {
+        throw await this.paidDeliveryInterrupted(err, url, receipt, receipt.paymentHeader, retryInit?.body != null);
+      }
+      throw err;
+    }
     const toolResult = retryResponse.ok ? await this.merchantTransport.readToolResult(retryResponse) : void 0;
-    const inBandChallenge = toolResult ? extractMcpPaymentRequired(toolResult) : void 0;
     const metaSettlement = toolResult ? mcpSettlementFromToolResult(toolResult) : void 0;
-    const inBandRejection = inBandChallenge !== void 0 || metaSettlement?.success === false;
+    const headerReceipt = retryResponse.headers.get("PAYMENT-RESPONSE");
+    const answer = decidePostFundingMerchantAnswer({
+      toolResult,
+      httpOk: retryResponse.ok,
+      paymentResponseHeader: headerReceipt ?? void 0,
+      metaSettlement
+    });
+    const reportedSettlementTxHash = answer.settlementTxHash;
+    const inBandRejection = answer.inBandRejection;
     if (!retryResponse.ok || inBandRejection) {
       const merchant = await captureMerchantResponse(retryResponse);
       await this.recordRetryRejected({
@@ -2688,7 +2922,7 @@ var MerchantCompletion = class {
         }
       });
       throw new HavenApiError(
-        "x402 retry failed after Haven funded the delegate wallet; reconciliation may be required.",
+        "x402 retry failed after Haven funded the delegate wallet; reconciliation may be required. The merchant may still settle late: check the payment status before sweeping the delegate.",
         inBandRejection ? X402_RETRY_REJECTED_STATUS : merchant.merchant_status,
         {
           marker: "x402_retry_rejected_after_funding",
@@ -2701,10 +2935,10 @@ var MerchantCompletion = class {
         }
       );
     }
-    const headerReceipt = retryResponse.headers.get("PAYMENT-RESPONSE");
-    const protocolReceiptHeader = headerReceipt ?? (metaSettlement ? encodeMcpSettlementReceipt(metaSettlement) : void 0);
-    const protocolReceiptHeaderName = headerReceipt ? "PAYMENT-RESPONSE" : metaSettlement ? `_meta.${MCP_X402_PAYMENT_RESPONSE_META_KEY}` : void 0;
-    const merchantSettlement = parseMerchantSettlement(protocolReceiptHeader ?? null);
+    const { protocolReceiptHeader, protocolReceiptHeaderName } = answer;
+    const merchantSettlement = {
+      settlementTxHash: reportedSettlementTxHash ?? null
+    };
     if (receipt.merchant && merchantSettlement.settlementTxHash) {
       receipt.merchant.settlementTxHash = merchantSettlement.settlementTxHash;
       receipt.merchant.settlementExplorerUrl = buildExplorerUrl(receipt.chainId, merchantSettlement.settlementTxHash) || null;
@@ -2724,7 +2958,12 @@ var MerchantCompletion = class {
     });
     const settlementCandidate = merchantSettlement.settlementTxHash;
     if (settlementCandidate && isWellFormedSettlementTxHash(settlementCandidate) && !isZeroSettlementTxHash(settlementCandidate) && settlementCandidate.toLowerCase() !== receipt.txHash.toLowerCase()) {
-      await this.reportSettlementEvidenceOnce(receipt.paymentId, settlementCandidate);
+      await this.reportEvidence({
+        paymentId: receipt.paymentId,
+        rail: "x402",
+        txHash: settlementCandidate,
+        ...settlementProofFields(receipt.paymentHeader)
+      });
     }
     await this.reportMerchantReceipt(receipt.paymentId, retryResponse);
     return retryResponse;
@@ -2827,6 +3066,51 @@ var MerchantCompletion = class {
   // and MACHINE-PAYMENT-CHALLENGE was never produced by any other Haven
   // surface. Use the x402 flow (authorizeX402 / fetch / quoteX402 / payX402Quote)
   // for agent-to-merchant payments.
+  /**
+   * #4257: record a paid delivery that a refused redirect interrupted, and
+   * return the refusal re-thrown with its payment and an accurate account:
+   * the payment header (and the body, when there is one) reached `url`, the
+   * merchant answered with a redirect Haven did not follow, and the merchant
+   * may still settle. The record is the same
+   * `merchant_retry_rejected_after_payment` event a non-2xx answer writes: its
+   * `retry_status` is the redirect status, `retry_body` is null, and `details`
+   * carry `refusal` plus `redirect_location` when the refusal names a redirect
+   * target, or `refused_url` (the URL that answered) otherwise. The payment
+   * reads as funded and undelivered.
+   */
+  async paidDeliveryInterrupted(err, url, receipt, paymentHeader, hasBody) {
+    const scheme = x402PaymentHeaderNamesFor(paymentHeader).length > 1 ? "eip3009" : "erc7710";
+    const status = err.redirectStatus ?? 0;
+    await this.recordRetryRejected({
+      rail: "x402",
+      paymentId: receipt.paymentId,
+      txHash: receipt.txHash,
+      resourceUrl: receipt.resourceUrl,
+      merchant: {
+        merchant_status: status,
+        merchant_status_text: "redirect not followed",
+        merchant_headers: {},
+        merchant_body: ""
+      },
+      details: {
+        merchant_to: receipt.merchantTo,
+        delegate_to: receipt.to,
+        refusal: err.refusal,
+        // The refusal's url is the redirect target only when it carries one;
+        // otherwise it is the URL that answered (a non-GET redirect, a missing
+        // or unresolvable Location), recorded under a neutral key.
+        ...err.redirectTarget ? { redirect_location: err.redirectTarget } : { refused_url: err.url }
+      }
+    });
+    const what = `The paid request was delivered to ${url}, ${hasBody ? "payment header and body" : "payment header"} included, and the merchant answered ${status ? `HTTP ${status} ` : ""}with a redirect${unfollowedRedirect(err)} Do not pay again: `;
+    const next = scheme === "erc7710" ? "erc7710 has no funding leg, so there is no delegate balance to strand or sweep. The merchant may still redeem the settlement authorization within its window: check haven_get_payment_status after that window and re-quote only if it shows no settlement." : "the funding leg is confirmed on-chain and the merchant may still settle late. Check haven_get_payment_status before anything else, and sweep the delegate only if no settlement appears.";
+    return new MerchantEgressRefusedError(what + next, err.url, err.refusal, false, {
+      redirectStatus: err.redirectStatus,
+      redirectTarget: err.redirectTarget,
+      paymentId: receipt.paymentId,
+      settlementScheme: scheme
+    });
+  }
   async recordRetryRejected(input) {
     try {
       await this.post("/machine-payments/reconciliation-events", {
@@ -2969,17 +3253,19 @@ var MerchantCompletion = class {
     };
     for (let attempt = 0; ; attempt += 1) {
       const result = await this.postEvidenceOnce(body);
-      if (result.outcome !== "retryable" || attempt >= EVIDENCE_RETRY_DELAYS_MS.length) {
+      if (result.outcome !== "retryable" || result.statusCode !== EVIDENCE_RETRYABLE_STATUS || attempt >= EVIDENCE_RETRY_DELAYS_MS.length) {
         return result;
       }
       await this.sleep(EVIDENCE_RETRY_DELAYS_MS[attempt]);
     }
   }
   /**
-   * ONE evidence attempt — the body of `reportEvidence`'s loop above, and the
-   * whole of the #3764 settlement report below. A 503 answers `retryable`
-   * immediately; the caller decides whether to sleep and re-attempt
-   * (`reportEvidence`) or hand the outcome to its consumer (#3764 D2).
+   * ONE evidence attempt — the body of `reportEvidence`'s loop above. A 503,
+   * or no verdict at all (a non-answer or a 408, #4470), answers `retryable`
+   * immediately; the caller decides whether to sleep and
+   * re-attempt (`reportEvidence`, and — #4215 — the local settlement report
+   * in `retryRequest`) or hand the outcome to its consumer (#3764 D2, the
+   * hosted settlement report).
    */
   async postEvidenceOnce(body) {
     try {
@@ -2987,12 +3273,15 @@ var MerchantCompletion = class {
       return { outcome: "confirmed" };
     } catch (err) {
       const statusCode = err instanceof HavenApiError ? err.statusCode : void 0;
-      if (statusCode !== EVIDENCE_RETRYABLE_STATUS) {
+      const noVerdict = statusCode === 408 || err instanceof HavenApiError && err.failureCause?.kind === "no_answer";
+      if (statusCode !== EVIDENCE_RETRYABLE_STATUS && !noVerdict) {
         const reason = refusalReasonFromBody(err);
+        const errorCode = refusalErrorCodeFromBody(err);
         return {
           outcome: "refused",
           statusCode: statusCode ?? 0,
-          ...reason ? { reason } : {}
+          ...reason ? { reason } : {},
+          ...errorCode ? { errorCode } : {}
         };
       }
       return { outcome: "retryable", statusCode };
@@ -3029,39 +3318,64 @@ var MerchantCompletion = class {
    * gate uses, so a caller cannot "fix" a missing hash by reporting the demo
    * merchant's own marker and getting a different verdict than the settle
    * path already gave it.
+   *
+   * #4061: `options.paymentHeader` is the payment header the caller sent to
+   * the merchant on its paid retry. On eip3009 it is REQUIRED for the record
+   * (#3925): its signed authorization proves the nonce the settlement burned
+   * is this payment's, and a report without it is refused with
+   * `errorCode: 'settlement_proof_header_missing'`. It is forwarded exactly
+   * as the funding report forwards it (`paymentProofHeader` plus the names
+   * `x402PaymentHeaderNamesSent` derives from the same payload). erc7710
+   * needs none — Haven assembled that header itself.
    */
-  async reportSettlementEvidence(paymentId, settlementTxHash) {
+  async reportSettlementEvidence(paymentId, settlementTxHash, options = {}) {
     if (isZeroSettlementTxHash(settlementTxHash)) {
       throw new HavenZeroSettlementHashError(paymentId);
     }
     return this.reportEvidence({
       paymentId,
       rail: "x402",
-      txHash: settlementTxHash
+      txHash: settlementTxHash,
+      ...settlementProofFields(options.paymentHeader)
     });
   }
   /**
    * #3764: report the merchant's OWN EIP-3009 settlement transaction right
-   * after a completed purchase — the second leg of a payment that already has
-   * a funding-evidence row. Same endpoint and payload shape as
+   * after a completed hosted purchase — the second leg of a payment that
+   * already has a funding-evidence row. Same endpoint and payload shape as
    * `reportSettlementEvidence` above, but with #3764's D2 budget: exactly ONE
    * attempt, no `EVIDENCE_RETRY_DELAYS_MS` backoff. The resource is already
    * paid for and delivered, so a retryable answer must not stretch the
    * completed purchase — the HOSTED tools hand the outcome to the agent
-   * (`settlementEvidenceOutcome` → `haven_report_settlement_evidence`), and
-   * the local caller swallows it by design (D1). Callers validate the hash
-   * before this call (well-formed, non-zero, different from the funding hash
+   * (`settlementEvidenceOutcome` → `haven_report_settlement_evidence`). Since
+   * #4215 this ONE-attempt form serves the HOSTED path only
+   * (`completeX402MerchantCall`); the local `retryRequest` posts the same
+   * report through `reportEvidence`, whose bounded loop re-attempts while
+   * Haven answers `retryable`. Callers validate the hash before this call
+   * (well-formed, non-zero, different from the funding hash
    * case-insensitively), so there is no client-side refusal here — the
    * backend verifies on-chain and is the only judge.
+   *
+   * #4061: `paymentHeader` is the header the paid retry sent — the #3925
+   * nonce proof, forwarded as `reportSettlementEvidence` forwards it. Both
+   * callers hold it; without it the backend refuses the record.
    */
-  async reportSettlementEvidenceOnce(paymentId, settlementTxHash) {
+  async reportSettlementEvidenceOnce(paymentId, settlementTxHash, paymentHeader) {
     return this.postEvidenceOnce({
       paymentId,
       rail: "x402",
-      txHash: settlementTxHash
+      txHash: settlementTxHash,
+      ...settlementProofFields(paymentHeader)
     });
   }
 };
+function settlementProofFields(paymentHeader) {
+  if (!paymentHeader || !paymentHeader.trim()) return {};
+  return {
+    paymentProofHeaderName: x402PaymentHeaderNamesSent(paymentHeader),
+    paymentProofHeader: paymentHeader
+  };
+}
 function refusalReasonFromBody(err) {
   if (!(err instanceof HavenApiError)) return void 0;
   const body = err.body;
@@ -3069,6 +3383,13 @@ function refusalReasonFromBody(err) {
   const reason = body.reason;
   return typeof reason === "string" && reason.length > 0 ? reason : void 0;
 }
+function refusalErrorCodeFromBody(err) {
+  if (!(err instanceof HavenApiError)) return void 0;
+  const body = err.body;
+  if (body === null || typeof body !== "object" || Array.isArray(body)) return void 0;
+  const code = body.error_code;
+  return typeof code === "string" && code.length > 0 ? code : void 0;
+}
 function isZeroSettlementTxHash(hash) {
   return typeof hash === "string" && /^0x0+$/i.test(hash);
 }
@@ -3089,6 +3410,25 @@ function parseProtocolReceiptHeader(value) {
     }
   }
 }
+function unfollowedRedirect(err) {
+  const target = err.redirectTarget ?? err.url;
+  switch (err.refusal) {
+    case "redirect_cross_origin_body":
+      return ` to a different origin (${target}). Haven did not follow it, so the payment was not re-sent there.`;
+    case "redirect_on_non_get":
+      return ". Under the egress policy only GET redirects are followed, so Haven did not follow it and nothing was sent to the redirect target.";
+    case "redirect_missing_location":
+      return " that named no target (no Location header). Haven did not follow it.";
+    case "redirect_invalid_location":
+      return " whose Location header is not a resolvable URL. Haven did not follow it.";
+    case "redirect_budget_exceeded":
+      return ` past the redirect budget. The chain stopped before ${target}, and nothing was sent there.`;
+    case "url_not_allowed":
+      return ` to a URL the egress policy does not allow (${target}). Haven did not follow it, so nothing was sent there.`;
+    default:
+      return ". Haven did not follow it.";
+  }
+}
 
 // src/client.ts
 var DEFAULT_POLLING_INTERVAL = 3e3;
@@ -3355,7 +3695,7 @@ var HavenClient = class {
     }
     const fundingTo = options.delegateAddress ?? (await this.getAgent()).delegateAddress;
     if (!fundingTo) {
-      throw new HavenApiError("Authenticated agent has no delegate address registered.", 502);
+      throw HavenApiError.deterministic("Authenticated agent has no delegate address registered.", 502);
     }
     const idempotencyKey = options.idempotencyKey ?? buildX402IdempotencyKey(paymentRequired, option);
     const raw = await this.post("/x402", {
@@ -3393,7 +3733,7 @@ var HavenClient = class {
       throwPaymentStateError("x402 payment", raw);
     }
     if (!raw.sign_data?.hash) {
-      throw new HavenApiError("No sign_hash returned from x402/authorize", 500, raw);
+      throw HavenApiError.deterministic("No sign_hash returned from x402/authorize", 500, raw);
     }
     if (raw.sign_data.signature_scheme !== void 0 && !raw.sign_data.typed_data) {
       throw new HavenSigningError(
@@ -3401,7 +3741,7 @@ var HavenClient = class {
       );
     }
     if (!raw.x402_expected_auth) {
-      throw new HavenApiError("No x402 expected-context binding returned from x402/authorize", 500, raw);
+      throw HavenApiError.deterministic("No x402 expected-context binding returned from x402/authorize", 500, raw);
     }
     return {
       paymentId: raw.payment_id,
@@ -3631,6 +3971,12 @@ var HavenClient = class {
    * degrade-to-warning path and the ledger row would still land while the
    * purchase proceeded.
    *
+   * #4458: an agent whose only budget for the token has ENDED is refused the
+   * same way with `error_code: 'delegation_expired'` and `budget_ended_at`
+   * (ISO 8601) — also thrown, also recorded (`source: 'hosted_prepare'`).
+   * The remedy differs: the owner sets a NEW budget, waiting for a period to
+   * reset cannot help.
+   *
    * #3518: without `merchantTo`, an agent whose budgets for the token are all
    * merchant-locked gets 409 `budget_requires_recipient` (thrown, nothing
    * recorded) naming the pins in `budget_recipient_addresses` — repeat the
@@ -3648,18 +3994,20 @@ var HavenClient = class {
       amountAtomic: input.amountAtomic,
       ...input.merchantTo !== void 0 ? { merchantTo: input.merchantTo } : {},
       ...input.resourceUrl !== void 0 ? { resourceUrl: input.resourceUrl } : {},
-      ...input.idempotencyKey !== void 0 ? { idempotencyKey: input.idempotencyKey } : {}
+      ...input.idempotencyKey !== void 0 ? { idempotencyKey: input.idempotencyKey } : {},
+      ...input.recordRefusal !== void 0 ? { recordRefusal: input.recordRefusal } : {}
     });
   }
   /**
    * Post-purchase allowance/budget summary for a settled payment (#1310).
    *
-   * Reuses the EXACT rail-aware read path {@link getAllowances} / #1306's
-   * catalog-purchase preflight `allowance` block use — `GET
-   * /machine-payments/allowances`, with delegation-rail values coming from
-   * the #1090 `deriveDelegationBudgets`-backed enforcer read, never
+   * Reuses the EXACT rail-aware read path {@link getAllowances} uses —
+   * `GET /machine-payments/allowances`, with delegation-rail values coming
+   * from the #1090 `deriveDelegationBudgets`-backed enforcer read, never
    * `agent_allowances` — so this can never disagree with
-   * {@link getAllowances} for the same fixture. The settled token is
+   * {@link getAllowances} for the same fixture. (#1306's catalog-purchase
+   * preflight read the same path until #3054; it now calls
+   * `POST /machine-payments/budget-precheck` instead.) The settled token is
    * resolved from {@link getPaymentStatus} so callers pass only
    * `paymentId`, never a second haven_get_agent-style round trip.
    *
@@ -3755,10 +4103,10 @@ var HavenClient = class {
     return this.get(`/catalog/submit/${encodeURIComponent(id)}`);
   }
   /**
-   * Fetch one curated catalog entry by id (#1306).
+   * Fetch one catalog entry by id (#1306).
    *
    * Chain-scoped for free by the backend's SQL when the client is
-   * agent-authenticated (#1299): an unknown id and an id curated for a
+   * agent-authenticated (#1299): an unknown id and an id listed for a
    * DIFFERENT chain than this agent's both 404 identically — this method does
    * not (and must not) re-filter by chain in JS. Read-only, like
    * {@link discoverTools}.
@@ -3914,9 +4262,10 @@ var HavenClient = class {
     return this.accountReads.listPendingSubBudgetSignatures();
   }
   /**
-   * Close a sub-budget row (delegating agent only). A `pending` or expired row
-   * closes immediately; a live child returns `signData` for the on-chain
-   * revocation — sign it (`haven_sign` with `sub_budget_id`) and call
+   * Close a sub-budget row (delegating agent only). A `pending` row, or an
+   * `open` one already expired, closes immediately; otherwise (a live child, or
+   * any `closing` row — its disable is still owed, #3923) it returns `signData`
+   * for the on-chain revocation — sign it (`haven_sign` with `sub_budget_id`) and call
    * `submitSubBudget`.
    */
   async closeSubBudget(id) {
@@ -4342,13 +4691,15 @@ var HavenClient = class {
       body = text;
     }
     const toolResult = mcpToolResultOf(body);
-    const inBandChallenge = toolResult ? extractMcpPaymentRequired(toolResult) : void 0;
     const metaSettlement = toolResult ? mcpSettlementFromToolResult(toolResult) : void 0;
     const headerReceipt = surfaced.headers.get("PAYMENT-RESPONSE") ?? void 0;
-    const protocolReceiptHeaderName = headerReceipt ? "PAYMENT-RESPONSE" : metaSettlement ? `_meta.${MCP_X402_PAYMENT_RESPONSE_META_KEY}` : void 0;
-    const protocolReceiptHeader = headerReceipt ?? (metaSettlement ? encodeMcpSettlementReceipt(metaSettlement) : void 0);
-    const settlement = parseMerchantSettlement(protocolReceiptHeader ?? null);
-    const merchantAccepted = surfaced.ok && inBandChallenge === void 0 && metaSettlement?.success !== false;
+    const answer = decidePostFundingMerchantAnswer({
+      toolResult,
+      httpOk: surfaced.ok,
+      paymentResponseHeader: headerReceipt,
+      metaSettlement
+    });
+    const merchantAccepted = answer.accepted;
     let evidenceOutcome;
     let settlementEvidenceOutcome;
     if (!merchantAccepted) {
@@ -4370,7 +4721,7 @@ var HavenClient = class {
         });
       }
     } else {
-      const rawEvidenceTxHash = input.noFundingLeg ? settlement.settlementTxHash ?? void 0 : fundingTxHash ?? void 0;
+      const rawEvidenceTxHash = input.noFundingLeg ? answer.settlementTxHash ?? void 0 : fundingTxHash ?? void 0;
       const evidenceTxHash = rawEvidenceTxHash && !isZeroSettlementTxHash(rawEvidenceTxHash) ? rawEvidenceTxHash : void 0;
       if (evidenceTxHash) {
         evidenceOutcome = await this.merchantCompletion.reportEvidence({
@@ -4381,19 +4732,20 @@ var HavenClient = class {
           merchantStatus: surfaced.status,
           paymentProofHeaderName: x402PaymentHeaderNamesSent(input.paymentHeader),
           paymentProofHeader: input.paymentHeader,
-          protocolReceiptHeaderName,
-          protocolReceiptHeader,
+          protocolReceiptHeaderName: answer.protocolReceiptHeaderName,
+          protocolReceiptHeader: answer.protocolReceiptHeader,
           // #3778: the delivery pointer rides the accepted arm's evidence
           // report — a rejection delivered nothing to point at.
           ...input.deliveryReference ? { deliveryReference: input.deliveryReference } : {}
         });
       }
       if (!input.noFundingLeg) {
-        const settlementCandidate = settlement.settlementTxHash;
+        const settlementCandidate = answer.settlementTxHash;
         if (settlementCandidate && isWellFormedSettlementTxHash(settlementCandidate) && !isZeroSettlementTxHash(settlementCandidate) && fundingTxHash && settlementCandidate.toLowerCase() !== fundingTxHash.toLowerCase()) {
           settlementEvidenceOutcome = await this.merchantCompletion.reportSettlementEvidenceOnce(
             evidenceContext.paymentId,
-            settlementCandidate
+            settlementCandidate,
+            input.paymentHeader
           );
         }
       }
@@ -4404,7 +4756,7 @@ var HavenClient = class {
       ok: merchantAccepted,
       body,
       // #3155 review S3: a transaction beside a rejection is not a settlement.
-      settlementTxHash: merchantAccepted ? settlement.settlementTxHash ?? void 0 : void 0,
+      settlementTxHash: merchantAccepted ? answer.settlementTxHash ?? void 0 : void 0,
       evidenceOutcome,
       settlementEvidenceOutcome
     };
@@ -4437,9 +4789,15 @@ var HavenClient = class {
    * Haven verifies the delegate → merchant transfer on-chain
    * (`observeEip3009MerchantSettlement`) and records it beside the funding
    * hash, so receipts name the merchant's settlement.
+   *
+   * #4061: on eip3009 pass `options.paymentHeader` — the payment header you
+   * sent the merchant on your paid retry. Since #3925 it is the proof the
+   * settlement is recorded against; without it the report is `refused` with
+   * `errorCode: 'settlement_proof_header_missing'`, and repeating it WITH the
+   * header can succeed.
    */
-  async reportSettlementEvidence(paymentId, settlementTxHash) {
-    return await this.merchantCompletion.reportSettlementEvidence(paymentId, settlementTxHash);
+  async reportSettlementEvidence(paymentId, settlementTxHash, options = {}) {
+    return await this.merchantCompletion.reportSettlementEvidence(paymentId, settlementTxHash, options);
   }
   /**
    * #3770: record the agent's evidence-only delivery verdict on a settled
@@ -4674,7 +5032,7 @@ var toolDescriptions = {
   getAgent: {
     summary: "Return the authenticated agent identity AND its live spend authority in one call: Haven wallet, delegate, chain, raw status, spend_authority_readiness, per-token remaining allowance (atomic + human-readable). The recommended first call in a new session.",
     selectionGuidance: "Use this as the session bootstrap, or to confirm identity together with whether the agent has spend authority right now. For per-token detail (configured vs spent vs reset window) use haven_get_allowances.",
-    behavior: `Reads identity plus the live spend-authority snapshot \u2014 the active on-chain budget delegation. spend_authority_readiness (readiness is a deprecated alias, same value) is "ready" when at least one token has remaining spend authority, "needs_approval" when the agent is active but has none, and "revoked" when the credential is not active. Readiness is AUTHORITY: it says a budget is live, not that the account holds funds. Each allowances[] row carries fundsCoverRemaining: false when the account's balance cannot back that row's whole remaining budget \u2014 a heads-up to mention to the user, not a refusal (budgets above the balance are a normal setup; an owner may top up weekly) \u2014 and null when the coverage read failed or the remaining figure was not read live; the key is absent when the remaining is 0, and rows for one token are compared alone. It covers hosted identity + on-chain spend authority ONLY \u2014 the hosted server cannot see the LOCAL signer, so "ready" does not mean the signer can start; verify the signer with a signer tool call or connect --doctor. An over-budget payment is declined before any money moves; there is no approval queue \u2014 ask the owner to grant or raise the budget in Haven. allowances[] carries id, tokenAddress, remainingAtomic, remainingDisplay per token. taskBudgets[] rows carry maxAtomic/maxDisplay plus spentAtomic/remainingAtomic/remainingDisplay \u2014 what the chain still allows that budget \u2014 and remainingIsFromChain: false marks a failed read (figures null, never the full cap); only live rows are listed (closed and expired omitted), each with its status (pending | open | closing) and isExpired, so a closing budget stays visible. pendingSubBudgetSignatures[] lists sub-budget rows awaiting YOUR signature, each with its haven_sign next step. Identity fields: id, name, status, accountAddress, delegateAddress, chainId.`,
+    behavior: `Reads identity plus the live spend-authority snapshot \u2014 the active on-chain budget delegation. spend_authority_readiness (readiness is a deprecated alias, same value) is "ready" when at least one token has remaining spend authority, "needs_approval" when the agent is active but has none, and "revoked" when the credential is not active. needs_approval with no allowances[] rows and budgetEndedAt set: the budget ENDED on that date \u2014 ask the owner to set a new one, waiting will not help; with no rows and no budgetEndedAt: nothing approved yet; with rows: spent for this period, refilling at budgetRefillsAt (null: it ends first). Readiness is AUTHORITY \u2014 a budget is live, not that funds are held. Each allowances[] row carries fundsCoverRemaining: false when the account's balance cannot back that row's whole remaining budget \u2014 a heads-up to mention, not a refusal (budgets above the balance are normal; an owner may top up weekly) \u2014 and null when the coverage read failed or the remaining was not read live; the key is absent at remaining 0, and rows for one token are compared alone. Covers hosted identity + on-chain spend authority ONLY \u2014 the hosted server cannot see the LOCAL signer, so "ready" does not mean the signer can start; verify it with a signer tool call or connect --doctor. An over-budget payment is declined before any money moves; there is no approval queue \u2014 ask the owner to grant or raise the budget. allowances[] carries id, tokenAddress, remainingAtomic, remainingDisplay, nextRefillAt per token. taskBudgets[] rows carry maxAtomic/maxDisplay plus spentAtomic/remainingAtomic/remainingDisplay \u2014 what the chain still allows that budget \u2014 and remainingIsFromChain: false marks a failed read (figures null, never the cap); only live rows are listed, each with its status (pending | open | closing) and isExpired. pendingSubBudgetSignatures[] lists sub-budget rows awaiting YOUR signature, with the haven_sign step. Identity fields: id, name, status, accountAddress, delegateAddress, chainId.`,
     nextActionGuidance: ""
   },
   getAllowances: {
@@ -4688,7 +5046,7 @@ var toolDescriptions = {
   checkFunds: {
     summary: "Check whether the agent's account actually holds at least the given amount of a token \u2014 funds held, not spend permitted.",
     selectionGuidance: "Use this before attempting a payment when it matters whether the money is really there: allowance answers say what you are PERMITTED to spend, never whether the account HOLDS it. For allowance, budget, spend-limit, remaining-budget, reset-period, or what-can-I-spend questions use the allowance lookup tool instead.",
-    behavior: "Returns covered: true (the account holds at least the checked amount), false (a live chain read reports less \u2014 the budget is backed by an empty account; stop and tell the user funds are missing), or null (the chain read failed \u2014 unverifiable, never treat it as absence; coverageError says why). The account balance itself is deliberately not returned: this is a sufficiency signal, not a balance read. budget_remaining_atomic is the permitted figure from the allowance lookup (the SDK spells it budgetRemainingAtomic), named so it can never be confused with holdings.",
+    behavior: "Returns covered: true (the account holds at least the checked amount), false (a live chain read reports the account holds less than the checked amount; stop and tell the user it is short), or null (the chain read failed \u2014 unverifiable, never treat it as absence; coverageError says why). The account balance itself is deliberately not returned: this is a sufficiency signal, not a balance read. budget_remaining_atomic is the permitted figure from the allowance lookup (the SDK spells it budgetRemainingAtomic), named so it can never be confused with holdings.",
     nextActionGuidance: "On covered=false, do not attempt the payment \u2014 tell the user the account is short and let them fund it; on covered=null, retry the check shortly or proceed knowing the payment may fail on-chain."
   },
   listReceipts: {
@@ -4716,9 +5074,9 @@ var toolDescriptions = {
     nextActionGuidance: "On a decline, report the reason to the user and ask them to raise the budget in Haven \u2014 there is no approval queue to wait on. This tool retries the merchant itself while it runs, so do not wait on a signal mid-call. If the process crashes after payment, a later haven_get_payment_status call may report nextAction=retry_original_x402_request \u2014 resume via haven_resume_x402_payment instead of paying again."
   },
   discoverTools: {
-    summary: "Step 1 of a purchase: discover payable services from Haven's curated merchant catalog \u2014 names, prices, the next call.",
-    selectionGuidance: "Use this when the user asks what the agent can buy, pay for, or which paid services exist \u2014 or when you need a resource URL for a service the user described. Use verified=verified for entries Haven watched pass a live quote probe (operator-curated or self-submitted) \u2014 domain_verified is the only ownership claim; never treat these badges as proof of merchant honesty, quality, or reliability. Do NOT use for balance, budget, or spend-limit questions \u2014 use haven_get_allowances. Do NOT use to pay \u2014 each returned entry names the next tool to call.",
-    behavior: "Use each entry's suggested_tool + suggested_arguments first; an entry without them says why. Read-only lookup against Haven's curated catalog; entries are periodically re-verified against the live merchant and degraded entries are flagged. Use category for a case-insensitive category filter (for example, VPN or vpn), or search for a product name, category, or description term. Returns name, description, price, rail, resource URL, tool_name, tool_arguments, the hint, and the provenance badges source/domain_verified/verified_payable. " + FUNDING_LEG_DISCOVERY_GUIDANCE + " The catalog price (price_display/price_atomic, marked price_is_indicative) is a last-verified hint, NOT authoritative \u2014 the real price comes from the merchant's live 402 at pay time. Never creates a payment, signature, or approval.",
+    summary: "Step 1 of a purchase: discover payable services from Haven's merchant catalog \u2014 names, prices, the next call.",
+    selectionGuidance: "Use this when the user asks what the agent can buy, pay for, or which paid services exist \u2014 or when you need a resource URL for a service the user described. Use verified=verified for entries Haven watched pass a live quote probe (any source; bazaar seller-asserted) \u2014 domain_verified is the only ownership claim; never treat these badges as proof of merchant honesty, quality, or reliability. Do NOT use for balance, budget, or spend-limit questions \u2014 use haven_get_allowances. Do NOT use to pay \u2014 each returned entry names the next tool to call.",
+    behavior: "Use each entry's suggested_tool + suggested_arguments first; an entry without them says why. Read-only lookup against Haven's catalog; entries are periodically re-verified against the live merchant and degraded entries are flagged. Use category for a case-insensitive category filter (for example, VPN or vpn), or search for a product name, category, or description term. Returns name, description, price, rail, resource URL, tool_name, tool_arguments, the hint, and the provenance badges source/domain_verified/verified_payable. " + FUNDING_LEG_DISCOVERY_GUIDANCE + " The catalog price (price_display/price_atomic, marked price_is_indicative) is a last-verified hint, NOT authoritative \u2014 the real price comes from the merchant's live 402 at pay time. Never creates a payment, signature, or approval.",
     nextActionGuidance: `Call suggested_tool with suggested_arguments VERBATIM (no hint: read suggested_tool_omitted_reason). Confirm the price from the live quote or pay result, not the catalog; if the next tool takes a cap, pass the user's cap as max_amount_human in whole tokens ("no more than 1 USDC" \u2192 max_amount_human: "1"), never atomic units by hand.`
   },
   submitCatalogEntry: {
@@ -4741,8 +5099,8 @@ var toolDescriptions = {
   },
   reportSettlementEvidence: {
     summary: "Report a payment's real merchant settlement transaction hash so Haven can verify it on-chain and record it.",
-    behavior: "Pass payment_id and, when you hold one, settlement_tx_hash (0x + 64 hex chars) \u2014 from PAYMENT-RESPONSE or a prior settlement_tx_hash. Omitting settlement_tx_hash succeeds as a no-op \u2014 nothing is checked or recorded, and no network call is made. Haven verifies on-chain before recording a hash; a zero, mismatched, or reverted hash is refused. Your own payments only.",
-    nextActionGuidance: "code SETTLEMENT_NOT_RECORDED (refusal_reason present): the payment's funding is confirmed and this hash was not accepted for it \u2014 do not retry it; refusal_reason carries why, verbatim. code DELIVERED_UNSETTLED: not verified, do not retry \u2014 poll haven_get_payment_status. code SETTLEMENT_PENDING (retryable:true): not mined or RPC unreachable \u2014 report the same hash again shortly."
+    behavior: "Pass payment_id and, when you hold one, settlement_tx_hash (0x + 64 hex chars) \u2014 from PAYMENT-RESPONSE or a prior settlement_tx_hash. On EIP-3009 also pass payment_header (the header you retried the merchant with) or the report is refused. Omitting settlement_tx_hash succeeds as a no-op \u2014 nothing is checked or recorded, and no network call is made. Haven verifies on-chain before recording a hash; a zero, mismatched, or reverted hash is refused. Your own payments only.",
+    nextActionGuidance: "code SETTLEMENT_PROOF_HEADER_MISSING: call again adding payment_header. code SETTLEMENT_NOT_RECORDED (refusal_reason present): the payment's funding is confirmed and this hash was not accepted for it \u2014 do not retry it; refusal_reason carries why, verbatim. code DELIVERED_UNSETTLED: not verified, do not retry \u2014 poll haven_get_payment_status. code SETTLEMENT_PENDING (retryable:true): not mined or RPC unreachable \u2014 report the same hash again shortly."
   }
 };
 
@@ -4996,13 +5354,13 @@ You are an AI agent whose user has no Haven account yet, or has one but has not
 
 ## What Haven is, in three sentences
 
-Your user gives you a **budget on their own account** \u2014 not their wallet, and not a key to their funds. The budget is a delegation they sign, enforced on-chain: a payment over it, to the wrong recipient, or past its expiry is refused at execution time, not by a dashboard promise. Haven constructs and relays the payments; you get an agent credential and a signing key made on your machine, and your user can revoke the budget without you and without Haven.
+Your user gives you a **budget on their own account** \u2014 not their wallet, and not a key to their funds. The budget is a delegation they sign, enforced on-chain: a payment over it, to the wrong recipient, or past its expiry is refused at execution time, not by a dashboard promise. The budget also ENDS on a date your user chooses \u2014 30, 90 (default), 180 or 365 days out \u2014 and that day is enforced on-chain too. When the budget ends, your authority to pay ends with it; ask your user to renew it (a new approval on the agent's page, or a new \`budget grant\`). Haven constructs and relays the payments; you get an agent credential and a signing key made on your machine, and your user can revoke the budget without you and without Haven.
 
 ## The sequence
 
 Four of the six steps are your user's \u2014 each needs a human signature or a human decision. The rest is yours. If they already have a funded account, start at step 3.
 
-1. **HUMAN \u2014 create the account.** Name, email, password, then a passkey (Face ID / Touch ID) or a wallet. Never offer to enter any of it: you must not have their password, and the passkey is bound to their device. With a terminal, \`<packages.cli.one_liner> login --api <api-url>\` afterwards gets you a scoped session for steps 3-4 (that flag or \`HAVEN_API_URL\`, on the first command \u2014 the session then remembers the backend; **the CLI's built-in default is Haven's hosted production backend**, so on any other deployment an omitted flag connects you somewhere real and wrong rather than failing) \u2014 they approve a code in the browser, you never hold their password. That command is the manifest's \`packages.cli.one_liner\` (\`/.well-known/haven.json\`) \u2014 run it as given: \`packages.cli.channel\` serves the full spec. Do not hold the process open while you wait: under \`--json\`, pass \`--no-wait\` to get the link object back at once, then poll it with \`haven login --poll <device_code>\` \u2014 one round per invocation, exit 3 while it is still pending, 0 once approved. It can set up agents and read the account; it cannot sign, approve a budget, move funds, or rotate any agent's keys.
+1. **HUMAN \u2014 create the account.** Name, email, password, then a passkey or a wallet. Never offer to enter any of it: you must not have their password, and the passkey is bound to their device. With a terminal, \`<packages.cli.one_liner> login --api <api-url>\` afterwards gets you a scoped session for steps 3-4 (that flag or \`HAVEN_API_URL\`, on the first command \u2014 the session then remembers the backend; **the CLI's built-in default is Haven's hosted production backend**, so on any other deployment an omitted flag connects you somewhere real and wrong rather than failing) \u2014 they approve a code in the browser, you never hold their password. That command is the manifest's \`packages.cli.one_liner\` (\`/.well-known/haven.json\`) \u2014 run it as given: \`packages.cli.channel\` serves the full spec. Do not hold the process open while you wait: under \`--json\`, pass \`--no-wait\` to get the link object back at once, then poll it with \`haven login --poll <device_code>\` \u2014 one round per invocation, exit 3 while it is still pending, 0 once approved. It can set up agents and read the account; it cannot sign, approve a budget, move funds, or rotate any agent's keys.
 2. **HUMAN \u2014 fund it.** USDC only, no ETH: Haven sponsors the gas. \`/.well-known/haven.json\` names \`chains.default\` as the deployment's expected chain, but after login \`haven wallets funding\` prints the address, the amount and which chain in one place; confirm that chain before you message your user. Without a CLI session, the dashboard's funding card shows the address and amount and its Receive-funds screen names the chain; never assume one: a testnet deployment and production both call themselves Haven. Before you write that message, read the manifest: \`environment\` says whether this deployment is \`production\`, and each \`chains.supported\` entry says whether that chain is a \`testnet\`. Real money is at stake only on a non-testnet chain of a \`production\` deployment \u2014 tell your user which case theirs is.
 3. **HUMAN \u2014 create the agent, set its budget**, and paste you the **setup prompt** it hands back. With a CLI session (step 1) you can do this step yourself: \`haven agents connect --name <n> --budget <amount> --token USDC --period <minutes>\` prints the same connector command and approval link; add \`--run\` to do step 4 too.
 4. **YOU \u2014 run the connector command** in that prompt (see What you run). It makes your signing key locally, registering only the public address.
@@ -5026,7 +5384,7 @@ Send these as your own message, \`<host>\` replaced by the host you fetched this
 
 **Before signup** (step 1):
 
-> I can do everything except the parts that need your signature. Please open \`<host>/signup?next=/agents&via=agent\` \u2014 name, email, password, then a passkey (Face ID / Touch ID) or a wallet. That is your account's key: I should not have it, and I will never ask for your password. Already have one? \`<host>/login?next=/agents\`.
+> I can do everything except the parts that need your signature. Please open \`<host>/signup?next=/agents&via=agent\` \u2014 name, email, password, then a passkey or a wallet. That is your account's key: I should not have it, and I will never ask for your password. Already have one? \`<host>/login?next=/agents\`.
 
 **At the passkey step:**
 
@@ -5069,7 +5427,7 @@ If the approval wait times out, nothing is lost \u2014 your agent is registered
 Call \`haven_get_agent\`, one of the Haven MCP tools the connector wires into your runtime in step 4. It returns identity plus \`spend_authority_readiness\`:
 
 - \`ready\` \u2014 a budget is live: you have the authority to pay. It does not say the account holds funds \u2014 the \`allowances[]\` rows carry \`funds_cover_remaining\`, and \`false\` there is a heads-up to mention to your user, not a refusal.
-- \`needs_approval\` \u2014 the connector finished, nobody approved yet. Ask your user again, in their Haven tab; there is no queue to wait in.
+- \`needs_approval\` \u2014 no budget can pay. \`allowances[]\` empty with \`budgetEndedAt\` set: your budget ENDED on that date; waiting will not help \u2014 ask your user to set a new one in their Haven tab. \`allowances[]\` empty with \`budgetEndedAt\` null: nobody approved one yet; ask your user again \u2014 there is no queue. Rows, all spent: it refills at \`budgetRefillsAt\`; tell your user, then wait or ask them to raise it (\`null\`: it ends first; ask them to renew it).
 - \`revoked\` \u2014 the credential is not active; ask your user to create a new agent.
 
 \`ready\` covers hosted identity and the budget only, not your local signer. Check that with \`npx -y @haven_ai/connect@<channel> --doctor\`, the same tag your prompt named \u2014 a separate command, so the command-modification rule does not bind it.
@@ -5105,7 +5463,7 @@ Then:
 1. Run \`<packages.cli.one_liner> login\`. That command is the manifest's \`packages.cli.one_liner\` (\`/.well-known/haven.json\`) \u2014 run it as given: \`packages.cli.channel\` serves the full spec. It prints a link and a code and does not need my password \u2014 it must never ask for it. Give me the link straight away and wait for me to approve it in my browser.
 2. Once I have approved, run \`haven agents connect --name <a name you choose> --budget <amount> --token USDC --period <minutes>\` with the budget I tell you. If I have not given you one, ask me before running it. Add \`--run\` to complete the connection in the same step.
 3. ${AGENT_APPROVAL_RELAY_JSON_SENTENCE}
-4. Once I have approved the budget, verify with the \`haven_get_agent\` tool: \`ready\` means I have given you the authority to pay \u2014 it does not confirm the account holds funds, so if its allowances rows carry \`funds_cover_remaining: false\`, tell me and still try the payment; \`needs_approval\` means my approval has not landed yet.
+4. Once I have approved the budget, verify with the \`haven_get_agent\` tool: \`ready\` means I have given you the authority to pay \u2014 it does not confirm the account holds funds, so if its allowances rows carry \`funds_cover_remaining: false\`, tell me and still try the payment; \`needs_approval\` with no allowances rows and \`budgetEndedAt\` set means my budget ended on that date \u2014 tell me, and I will set a new one; with no rows and no \`budgetEndedAt\`, my approval has not landed yet; with rows, the budget is spent \u2014 it refills at \`budgetRefillsAt\` (\`null\`: it ends first), so tell me, and I can raise or renew it.
 
 Two things only I can do: approving that budget with my passkey, and funding the account with USDC \u2014 no ETH, Haven sponsors the gas. Tell me if either is missing rather than working around it.
 
@@ -5225,8 +5583,10 @@ Do not guess the wallet address, network, or budget.
 
 For instant orientation at the start of a session, read the non-secret
 \`agent.json\` the connector wrote to your Haven credential directory (typically
-\`~/.haven/agents/<agent-id>/agent.json\` \u2014 if you don't know the agent id, list
-\`~/.haven/agents/\` to find the folder). It
+\`~/.haven/agents/<slug>/agent.json\`, where \`<slug>\` is the wiring name of the
+\`haven-<slug>\` pair \u2014 only a \`--bare\` run, or a \`--replace\` without \`--name\`,
+names the directory by the agent id instead; if you don't know the folder, list
+\`~/.haven/agents/\` to find it). It
 holds your agent id, Haven wallet address, network, and *configured* per-token
 budget, and contains no keys \u2014 the fastest way to answer "who am I and what may
 I spend" with no round trip. If that file is absent (some setups don't write
@@ -5247,7 +5607,13 @@ spending:
   the user, not a refusal \u2014 a budget above the balance is a normal setup, so
   still try the payment; \`null\` means the coverage read failed or the remaining
   figure was not read live; the key is absent when the remaining is 0. Rows for
-  one token are compared alone.
+  one token are compared alone. \`needs_approval\` with no \`allowances[]\`
+  rows and \`budgetEndedAt\` set means the budget ENDED on that date \u2014 waiting
+  will not help, ask the owner to set a new one; with no rows and no
+  \`budgetEndedAt\`, nobody approved a budget yet; with rows (all at remaining 0) the
+  budget is spent for this period, and \`budgetRefillsAt\` says when it refills
+  (\`null\`: it ends before it refills) \u2014 tell the user, then wait or ask them
+  to raise it.
 - \`mcp__haven__haven_get_allowances\` \u2014 detailed per-token breakdown
   (configured, spent, reset window) when you need more than the summary.
 - \`mcp__haven__haven_check_funds\` \u2014 whether the account actually HOLDS at
@@ -5394,10 +5760,13 @@ request, this is the only way it can learn the purchase failed \u2014 without it
 failed purchase reads as complete for fifteen minutes. If the merchant's
 \`PAYMENT-RESPONSE\` header names a \`transaction\`, pass that raw header as
 \`payment_response\` on the SAME \`mcp__haven__haven_report_x402_outcome\`
-call: Haven decodes it, verifies the settlement on-chain, and the receipt then
-shows the merchant's settlement, not only the funding transaction. Call
+call, together with \`payment_header\`: the exact header you retried the
+merchant with. Haven records a reported settlement only with that header,
+which proves the settlement is this payment's. It decodes the response,
+verifies the settlement on-chain, and the receipt then shows the merchant's
+settlement, not only the funding transaction. Call
 \`mcp__haven__haven_report_settlement_evidence\` only when the outcome answer
-names it as the next step. On the **erc7710** scheme (the pay result says
+names it as the next step, and pass the same \`payment_header\` there too. On the **erc7710** scheme (the pay result says
 \`settlement_scheme: "erc7710"\`), sign with \`mcp__haven-signer__haven_sign\`,
 then \`mcp__haven__haven_submit\` with \`settlement_scheme: "erc7710"\`
 returns the \`payment_header\`; retry the merchant yourself with it as
@@ -5427,7 +5796,9 @@ for example, an invoice carrying an \`x402_payment_url\` to POST with its
 \`invoice_id\`, beside a raw deposit address and a web payment link.
 - **Quote the exact request:** \`mcp__haven__haven_quote_x402\` with \`url\`,
   \`method\`, \`headers\` and \`body\`, exactly as the merchant described it.
-  \`body\` is a JSON **string**, not an object. On a JSON POST always pass
+  \`body\` is a JSON **string**, not an object. When the price is stated up
+  front (an invoice total, say), also pass \`expected_amount\` \u2014 the price you
+  expect, in whole tokens (\`"0.10"\`). On a JSON POST always pass
   \`headers: {"Content-Type": "application/json"}\` \u2014 the tool does not infer
   it, and a merchant may answer a request without it with a generic challenge
   Haven cannot pay (for example, only the \`upto\` scheme).
@@ -5456,6 +5827,18 @@ for example, an invoice carrying an \`x402_payment_url\` to POST with its
   report it, the merchant's settlement evidence. (A deposit transfer is bound
   to its payee and amount on-chain too; the difference is the record, not
   the binding.)
+- **If the quote says stop, stop.** The hosted quote checks the agent's
+  remaining budget at quote time, and it can check a price you state
+  (\`expected_amount\`). On the local runtime (\`@haven_ai/mcp\`) the quote
+  checks only a price you state; the budget is checked when you pay.
+  When it returns \`safe_to_continue: false\` \u2014 the amount exceeds the budget, or
+  the price does not match what you expected \u2014 it prefills no cap and names no
+  next tool: stop and tell the user. If the x402 challenge itself is wrong (a
+  price wildly off the invoice) and NOTHING has been paid via x402, the
+  invoice's own deposit address MAY be an alternative, but only with the
+  user's explicit go-ahead \u2014 never automatically. Once an x402 payment has
+  been attempted or refused, never pay the deposit address: it can pay the
+  invoice twice.
 - **Pay exactly one route, and never fall back silently.** If the x402 route
   is refused or fails, do not then pay the deposit address \u2014 that pays the
   invoice twice. Follow the result's guidance fields instead: on EIP-3009, a
@@ -5592,8 +5975,8 @@ only part of it was usable), and an optional \`note\` (max 2000 characters)
 saying what was wrong. It is evidence only: it moves no money, never changes
 \`settled\` or any money field, and works only on your own settled
 payments \u2014 another agent's payment is refused. A re-report replaces your
-earlier verdict; the receipt then carries it beside the payment, so the
-owner does not read a junk delivery as a success.
+earlier verdict; the receipt then carries it beside the payment, so a junk
+delivery does not read as a success.
 ### Relay a delivered code or credential to the owner \u2014 immediately, verbatim
 
 If a merchant response carries what the user PAID FOR \u2014 a redemption code, gift