@haven_ai/signer 0.3.0-alpha.0 → 0.5.0-alpha.1

package/dist/index.js

@@ -1,144 +1,17 @@
 import { randomUUID, createHash } from 'crypto';
 import { recoverTypedDataAddress, hashTypedData, hashMessage } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
-import { exact } from 'x402/schemes';
-import { addressFromKey, HavenSigningError, buildSweepTypedData, selectStandardPaymentOption, HavenApiError, toStandardPaymentRequirements, decodeBase64Json, encodeBase64Json, x402V2PaymentEnvelope, buildSweepAuthorizationMessage, verifySignature, x402AuthorizationAmount, SignerRefusalCode, connectorRerunCommand, SIGNER_UPDATE_FALLBACK, HavenUnsupportedSignerVersionError, buildX402ExpectedMessage, HavenError, AgentPaymentFailureCode, AgentPaymentNextAction, isSupportedNodeVersion, unsupportedNodeVersionMessage, signHash } from '@haven_ai/sdk';
-import { readFile, stat, mkdir, appendFile, writeFile } from 'fs/promises';
+import { createNextStepBuilder, addressFromKey, HavenSigningError, buildSweepTypedData, selectStandardPaymentOption, HavenApiError, toStandardPaymentRequirements, decodeBase64Json, encodeBase64Json, x402V2PaymentEnvelope, isSettlementChildTypedData, chainIdForNetwork, assertOwnSettlementChild, isPackedUserOperationTypedData, assertUserOpTypedDataBinding, assertBoundDirectPaymentUserOp, assertFundingLegPaysDelegate, HavenTypedDataRefusedError, buildSweepAuthorizationMessage, verifySignature, x402AuthorizationAmount, SignerRefusalCode, connectorRerunCommand, SIGNER_UPDATE_FALLBACK, HavenUnsupportedSignerVersionError, buildX402ExpectedMessage, DIRECT_SIGN_CONTEXT_VERSION, AgentPaymentNextAction, HavenError, AgentPaymentFailureCode, havenClientIdentity, isSupportedNodeVersion, unsupportedNodeVersionMessage, HavenUserOpBindingError, readClientUpdate, HAVEN_CLIENT_HEADER } from '@haven_ai/sdk/edge';
+export { deriveDelegateAccountAddress } from '@haven_ai/sdk/edge';
+import { stat, lstat, chmod, readFile, mkdir, rename, appendFile, writeFile } from 'fs/promises';
+import { resolve, dirname, join } from 'path';
+import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { homedir } from 'os';
-import { resolve, dirname, join } from 'path';
-import { z } from 'zod/v3';
+import { z as z$1 } from 'zod/v3';
 
 // src/core.ts
-var DELEGATION_MANAGER = "0xdb9B1e94B5b69Df7e401DDbedE43491141047dB3";
-var CAVEAT_ENFORCERS = {
-  erc20TransferAmount: "0xf100b0819427117EcF76Ed94B358B1A5b5C6D2Fc",
-  allowedCalldata: "0xc2b0d624c1c4319760C96503BA27C347F3260f55",
-  timestamp: "0x1046bb45C8d673d4ea75321280DB34899413c069"};
-var MAX_SETTLEMENT_WINDOW_SECONDS = 600;
-function isSettlementChildTypedData(value) {
-  const td = value;
-  return !!td && td.primaryType === "Delegation" && typeof td.domain?.verifyingContract === "string" && Array.isArray(td.message?.caveats);
-}
-function same(a, b) {
-  return !!a && !!b && a.toLowerCase() === b.toLowerCase();
-}
-function hex(value) {
-  return value.startsWith("0x") ? value.slice(2).toLowerCase() : value.toLowerCase();
-}
-function slice(terms, start, end) {
-  const body = hex(terms);
-  return end === void 0 ? body.slice(start * 2) : body.slice(start * 2, end * 2);
-}
-function findCaveat(caveats, enforcer) {
-  return caveats.find((c) => same(c.enforcer, enforcer));
-}
-function refuse(what, detail) {
-  throw new HavenSigningError(
-    `Refusing to sign the x402 settlement child: ${what}. ${detail} The signature on this child is what lets a merchant pull from the treasury, so it is verified locally against the Haven-signed expected context rather than trusted.`
-  );
-}
-function chainIdForNetwork(network) {
-  if (!network) return void 0;
-  const caip = /^eip155:(\d+)$/.exec(network);
-  if (caip) return Number(caip[1]);
-  if (network === "base") return 8453;
-  if (network === "base-sepolia") return 84532;
-  return void 0;
-}
-function verifySettlementChild(typedData, expected, now = Date.now()) {
-  if (typedData.primaryType !== "Delegation") {
-    refuse("it is not a Delegation payload", `primaryType was '${typedData.primaryType}'.`);
-  }
-  if (!same(typedData.domain?.verifyingContract, DELEGATION_MANAGER)) {
-    refuse(
-      "the EIP-712 domain names an unknown DelegationManager",
-      `Expected ${DELEGATION_MANAGER}, got ${typedData.domain?.verifyingContract}.`
-    );
-  }
-  const domainChain = Number(typedData.domain?.chainId);
-  if (!Number.isFinite(domainChain) || domainChain !== expected.chainId) {
-    refuse(
-      "it is scoped to the wrong chain",
-      `The expected context says chain ${expected.chainId}; the child says ${typedData.domain?.chainId}.`
-    );
-  }
-  const caveats = typedData.message?.caveats ?? [];
-  if (caveats.length === 0) {
-    refuse("it carries no caveats at all", "An unconstrained delegation is not a payment.");
-  }
-  const transfer = findCaveat(caveats, CAVEAT_ENFORCERS.erc20TransferAmount);
-  if (!transfer) {
-    refuse(
-      "it has no ERC-20 transfer-amount caveat",
-      "Without it the delegation is not bounded to an amount."
-    );
-  }
-  const token = `0x${slice(transfer.terms, 0, 20)}`;
-  if (!same(token, expected.asset)) {
-    refuse("it spends a different token", `Expected ${expected.asset}, child pins ${token}.`);
-  }
-  const amount = BigInt(`0x${slice(transfer.terms, 20, 52)}`);
-  if (amount !== BigInt(expected.amount)) {
-    refuse(
-      "the amount does not match",
-      `The expected context says ${expected.amount}; the child allows ${amount.toString()}.`
-    );
-  }
-  const calldata = findCaveat(caveats, CAVEAT_ENFORCERS.allowedCalldata);
-  if (!calldata) {
-    refuse(
-      "it has no payee pin",
-      "Without an allowed-calldata caveat the merchant could redeem it to any address."
-    );
-  }
-  const startIndex = BigInt(`0x${slice(calldata.terms, 0, 32)}`);
-  if (startIndex !== 4n) {
-    refuse(
-      "the payee pin points at the wrong calldata offset",
-      `Expected offset 4 (the transfer's \`to\` word), got ${startIndex.toString()}.`
-    );
-  }
-  const paddedPayee = slice(calldata.terms, 32, 64);
-  if (paddedPayee.slice(0, 24) !== "0".repeat(24)) {
-    refuse("the pinned payee is not a plain address", "Its 32-byte word is not a padded address.");
-  }
-  const payee = `0x${paddedPayee.slice(24)}`;
-  if (!same(payee, expected.merchantTo)) {
-    refuse(
-      "it pays a different address than Haven declared",
-      `The expected context says ${expected.merchantTo}; the child pins ${payee}.`
-    );
-  }
-  const timestamp = findCaveat(caveats, CAVEAT_ENFORCERS.timestamp);
-  if (!timestamp) {
-    refuse("it never expires", "A settlement child without a timestamp caveat is open-ended.");
-  }
-  const beforeThreshold = Number(BigInt(`0x${slice(timestamp.terms, 16, 32)}`));
-  if (beforeThreshold <= 0) {
-    refuse("its expiry is unset", "The timestamp caveat has no upper bound.");
-  }
-  const nowSec = Math.floor(now / 1e3);
-  if (beforeThreshold <= nowSec) {
-    refuse("it has already expired", `Expiry ${beforeThreshold} is not in the future.`);
-  }
-  if (beforeThreshold > nowSec + MAX_SETTLEMENT_WINDOW_SECONDS) {
-    refuse(
-      "its window is longer than a settlement may live",
-      `Expiry is ${beforeThreshold - nowSec}s out; the ceiling is ${MAX_SETTLEMENT_WINDOW_SECONDS}s.`
-    );
-  }
-  if (expected.expiresAt) {
-    const declared = Math.floor(Date.parse(expected.expiresAt) / 1e3);
-    if (Number.isFinite(declared) && beforeThreshold > declared) {
-      refuse(
-        "it outlives the payment window Haven declared",
-        `The expected context expires at ${expected.expiresAt}; the child lives to ${beforeThreshold}.`
-      );
-    }
-  }
-}
 function createEdgeSigner(delegateKey, options = {}) {
   let delegateAddress;
   try {
@@ -158,41 +31,28 @@ function createEdgeSigner(delegateKey, options = {}) {
       if (!oldest.done) retiredX402Bindings.delete(oldest.value);
     }
   }
-  function signAndVerify(hash) {
-    const signature = signHash(delegateKey, hash);
-    if (!verifySignature(hash, signature, delegateAddress)) {
-      throw new HavenSigningError(
-        "Local signature verification failed \u2014 recovered address does not match the delegate key."
-      );
-    }
-    return signature;
-  }
   return {
     delegateAddress,
-    signPaymentHash(hash) {
-      return signAndVerify(hash);
-    },
     async signDelegationTypedData(typedData) {
       const account = privateKeyToAccount(delegateKey);
       return account.signTypedData(typedData);
     },
-    signX402FundingHash(hash, expected) {
-      assertExpectedBinding(hash, expected, options.x402BindingSigner, "hash");
-      assertPayerMatchesDelegate(expected, delegateAddress, options.agentId);
-      const signature = signAndVerify(hash);
-      const x402Binding = randomUUID();
-      x402Bindings.set(x402Binding, { ...expected });
-      return { signature, x402Binding };
-    },
     async signX402FundingTypedData(typedData, expected) {
-      assertExpectedBinding(expected.payloadHash, expected, options.x402BindingSigner, "typed-data");
-      assertPayerMatchesDelegate(expected, delegateAddress, options.agentId);
-      const digest = hashTypedData(typedData);
-      if (digest.toLowerCase() !== expected.typedDataHash?.toLowerCase()) {
+      if (expected?.auth) {
+        assertSupportedBindingVersion(
+          expected.auth.version,
+          SUPPORTED_X402_EXPECTED_VERSIONS,
+          "x402 expected context"
+        );
+      }
+      if (!typedData) {
         throw new HavenSigningError(
-          "x402 typed data does not match the digest Haven committed to in the expected context. Refusing to sign \u2014 the payload was altered in transit or Haven declared a different one. The most common cause is the typed data being truncated or reshaped while being copied between tool calls (#1255): re-run the hosted quote and pass its typed_data_b64 string through UNCHANGED instead of re-emitting the nested JSON."
+          "This x402 funding intent is on the delegation rail: it commits to EIP-712 typed data, which was not supplied. Pass typed_data_b64 from haven_pay_mcp_tool / haven_pay_x402_quote through unchanged (or typed_data verbatim) \u2014 a bare payload_hash is not what the account validates."
         );
       }
+      const digest = hashTypedData(typedData);
+      assertExpectedBinding(digest, expected, options.x402BindingSigner);
+      assertPayerMatchesDelegate(expected, delegateAddress, options.agentId);
       if (isSettlementChildTypedData(typedData)) {
         const settlementChainId = chainIdForNetwork(expected.network);
         if (settlementChainId === void 0) {
@@ -200,7 +60,7 @@ function createEdgeSigner(delegateKey, options = {}) {
             `Refusing to sign the x402 settlement child: this signer cannot map the network '${expected.network}' to a chain id, so it cannot check which chain the child is scoped to. Update @haven_ai/signer.`
           );
         }
-        verifySettlementChild(typedData, {
+        assertOwnSettlementChild(typedData, {
           merchantTo: expected.merchantTo,
           amount: expected.amount,
           asset: expected.asset,
@@ -210,7 +70,21 @@ function createEdgeSigner(delegateKey, options = {}) {
           // signed another" class this file exists to catch (#1455 review).
           chainId: settlementChainId,
           expiresAt: expected.expiresAt
+        }, delegateAddress);
+      } else if (isPackedUserOperationTypedData(typedData)) {
+        assertUserOpTypedDataBinding(typedData, expected.payloadHash);
+        assertBoundDirectPaymentUserOp(typedData, delegateAddress);
+        assertFundingLegPaysDelegate(typedData, {
+          delegateAddress,
+          asset: expected.asset,
+          amount: expected.amount
         });
+      } else {
+        throw new HavenTypedDataRefusedError(
+          `This signer's x402 arm signs only a funding-leg PackedUserOperation or an erc7710 settlement Delegation; this typed data is '${String(
+            typedData.primaryType
+          )}'. Refusing, even though its digest is bound by the expected context.`
+        );
       }
       const account = privateKeyToAccount(delegateKey);
       const signature = await account.signTypedData(
@@ -235,16 +109,19 @@ function createEdgeSigner(delegateKey, options = {}) {
           );
         }
         throw new HavenSigningError(
-          "x402 funding binding is required before signing a merchant header. Sign the hosted funding hash with x402_expected first (haven_sign returns a binding this tool can use). A binding is also lost when the signer process restarts, since bindings live in memory only \u2014 re-sign to mint a fresh one."
+          "x402 funding binding is required before signing a merchant header. Sign the hosted funding payload with x402_expected first (haven_sign returns a binding this tool can use). A binding is also lost when the signer process restarts, since bindings live in memory only \u2014 re-sign to mint a fresh one."
         );
       }
-      try {
-        assertX402PaymentWindowOpen(expected);
-      } catch (err) {
-        x402Bindings.delete(x402Binding);
-        retireX402Binding(x402Binding, "window_expired");
-        throw err;
-      }
+      const assertWindowOpenOrRetire = () => {
+        try {
+          assertX402PaymentWindowOpen(expected);
+        } catch (err) {
+          x402Bindings.delete(x402Binding);
+          retireX402Binding(x402Binding, "window_expired");
+          throw err;
+        }
+      };
+      assertWindowOpenOrRetire();
       const option = selectStandardPaymentOption(paymentRequired.accepts);
       if (!option) {
         throw new HavenApiError(
@@ -255,6 +132,8 @@ function createEdgeSigner(delegateKey, options = {}) {
       assertX402MatchesExpected(paymentRequired, option, expected);
       const account = privateKeyToAccount(delegateKey);
       const requirements = toStandardPaymentRequirements(paymentRequired, option);
+      const { exact } = await loadX402Schemes();
+      assertWindowOpenOrRetire();
       const header = await exact.evm.createPaymentHeader(
         account,
         paymentRequired.x402Version,
@@ -289,7 +168,7 @@ function createEdgeSigner(delegateKey, options = {}) {
       }
       if (expectedSafe && !sameAddress(authorization.to, expectedSafe)) {
         throw new HavenSigningError(
-          "Sweep authorization `to` does not match the Safe in the local credential."
+          "Sweep authorization `to` does not match the agent's account (Haven wallet) in the local credential."
         );
       }
       const typedData = buildSweepTypedData(authorization);
@@ -368,7 +247,7 @@ function assertExpectedShape(expected) {
     throw new HavenSigningError("x402 expected funding context is required before signing a merchant header.");
   }
 }
-var SUPPORTED_X402_EXPECTED_VERSIONS = [1, 2, 3];
+var SUPPORTED_X402_EXPECTED_VERSIONS = [2, 3];
 var SUPPORTED_SWEEP_BINDING_VERSIONS = [1];
 function assertSupportedBindingVersion(received, supported, context) {
   if (supported.includes(received)) return;
@@ -385,11 +264,11 @@ function assertSupportedBindingVersion(received, supported, context) {
     fallback
   );
 }
-function assertExpectedBinding(payloadHash, expected, trustedSigner, mode = "hash") {
+function assertExpectedBinding(typedDataDigest, expected, trustedSigner) {
   assertExpectedShape(expected);
   if (!trustedSigner) {
     throw new HavenSigningError(
-      "x402 expected-context verifier is not configured. Set HAVEN_X402_BINDING_SIGNER before signing x402 funding hashes."
+      "x402 expected-context verifier is not configured. Set HAVEN_X402_BINDING_SIGNER before signing x402 funding payloads."
     );
   }
   if (expected.auth) {
@@ -399,17 +278,14 @@ function assertExpectedBinding(payloadHash, expected, trustedSigner, mode = "has
       "x402 expected context"
     );
   }
-  if (expected.payloadHash.toLowerCase() !== payloadHash.toLowerCase()) {
-    throw new HavenSigningError("x402 expected context does not match the funding hash being signed.");
-  }
-  if (mode === "hash" && expected.typedDataHash) {
+  if (!expected.typedDataHash) {
     throw new HavenSigningError(
-      "This x402 funding intent commits to EIP-712 typed data, so its bare hash must not be raw-signed \u2014 the account would reject that signature on-chain. Sign sign_data.typed_data instead."
+      "Refusing to sign typed data under an expected context that does not commit to it. Haven must return a v2/v3 x402 expected context (with typedDataHash) for a delegation-rail intent."
     );
   }
-  if (mode === "typed-data" && !expected.typedDataHash) {
+  if (expected.typedDataHash.toLowerCase() !== typedDataDigest.toLowerCase()) {
     throw new HavenSigningError(
-      "Refusing to sign typed data under an expected context that does not commit to it. Haven must return a v2 x402 expected context (with typedDataHash) for a delegation-rail intent."
+      "x402 typed data does not match the digest Haven committed to in the expected context. Refusing to sign \u2014 the payload was altered in transit or Haven declared a different one. The most common cause is the typed data being truncated or reshaped while being copied between tool calls (#1255): re-run the hosted quote and pass its typed_data_b64 string through UNCHANGED instead of re-emitting the nested JSON."
     );
   }
   const message = buildX402ExpectedMessage({
@@ -425,7 +301,7 @@ function assertExpectedBinding(payloadHash, expected, trustedSigner, mode = "has
     payerDelegate: expected.payerDelegate,
     payerAgentId: expected.payerAgentId
   });
-  const expectedVersion = expected.payerDelegate ? 3 : expected.typedDataHash ? 2 : 1;
+  const expectedVersion = expected.payerDelegate ? 3 : 2;
   if (expected.auth?.version !== expectedVersion || expected.auth.message !== message) {
     throw new HavenSigningError("x402 expected context authentication message is invalid.");
   }
@@ -445,6 +321,15 @@ function assertPayerMatchesDelegate(expected, delegateAddress, localAgentId) {
     `This quote belongs to a DIFFERENT agent: the quote was created for agent ${quoteAgent} (delegate ${expected.payerDelegate}), but this signer holds agent ${localAgent} (delegate ${delegateAddress}). A long-lived host is holding stale credentials \u2014 its session authenticates as the old agent while the signer on disk belongs to the new one. Nothing was signed. Restart the host so it re-reads its wiring, then re-quote.`
   );
 }
+async function loadX402Schemes() {
+  try {
+    return await import('x402/schemes');
+  } catch (err) {
+    throw new HavenSigningError(
+      `The x402 scheme module could not be loaded, so no merchant header was built (nothing was sent to the merchant): ${err instanceof Error ? err.message : String(err)}. The signer's runtime install is incomplete \u2014 run: npx @haven_ai/connect --doctor`
+    );
+  }
+}
 function assertX402PaymentWindowOpen(expected) {
   if (!expected.expiresAt) return;
   const expiresAtMs = Date.parse(expected.expiresAt);
@@ -463,11 +348,317 @@ function assertX402PaymentWindowOpen(expected) {
 function sameAddress(a, b) {
   return a.toLowerCase() === b.toLowerCase();
 }
+var SIGNER_HOSTED_HANDOFF_SHAPES = {
+  haven_get_payment_status: { payment_id: z.string().min(1) }
+};
+function target(shape) {
+  const schema = z.object(shape).strict();
+  return {
+    role: "hosted",
+    validate: (input) => {
+      const r = schema.safeParse(input ?? {});
+      return r.success ? null : r.error.errors.map((e) => `${e.path.join(".") || "(root)"}: ${e.message}`).join("; ");
+    }
+  };
+}
+var SIGNER_NEXT_STEP_TARGETS = {
+  haven_get_payment_status: target(SIGNER_HOSTED_HANDOFF_SHAPES.haven_get_payment_status)
+};
+var nextStep = createNextStepBuilder(SIGNER_NEXT_STEP_TARGETS);
+function signerRefusalStep(input) {
+  return nextStep({ ...input, safeToContinue: false, reason: "" });
+}
+function nextStepWireFields(step) {
+  return {
+    ...step.next_tool ? { next_tool: step.next_tool } : {},
+    ...step.next_tool_server ? { next_tool_server: step.next_tool_server } : {},
+    ...step.next_tool_name ? { next_tool_name: step.next_tool_name } : {},
+    ...step.next_tool_server_role ? { next_tool_server_role: step.next_tool_server_role } : {},
+    ...step.next_arguments ? { next_arguments: step.next_arguments } : {},
+    ...step.next_tool_omitted_reason ? { next_tool_omitted_reason: step.next_tool_omitted_reason } : {}
+  };
+}
+
+// src/sign-context.ts
+var DIRECT_RELAY_FALLBACK = "call haven_sign with payload_hash and typed_data_b64 from the haven_send / haven_pay result, passed through unchanged";
+var HavenSignContextError = class extends HavenSigningError {
+  /**
+   * #3001 / #3010 review: the recovery path, when signing OTHER bytes is
+   * actually a remedy — a transport failure (timeout, unreachable) or a
+   * body this signer could not read. `typed_data_b64` is NOT in the default
+   * quote result since #1272: obtain it by re-running the SAME quote tool
+   * with the SAME idempotency_key plus `include_signing_payload: true`.
+   * Absent on a backend REFUSAL (an expired, executed or unsignable intent
+   * cannot be rescued by re-signing its bytes) — with one #3271 exception: a
+   * 404 from the DIRECT fetch (an older backend with no direct route), where
+   * the `haven_send` / `haven_pay` result's relay fields still work.
+   */
+  fallback;
+  /**
+   * #3001: `AgentPaymentNextAction` values the signer already emits — the
+   * version-mismatch refusal's `stop_and_tell_user` for the classes where
+   * retrying the same call cannot help, and `payment_window_expired` (with
+   * `retry_with_new_quote`) for the x402 fetch's 410 / `expired`, exactly as
+   * the plain `HavenError` branch already does for that code. On the direct
+   * fetch (#3271) only `error_code: 'expired'` means an expired window, with
+   * no `retry_with_new_quote`; a bare 410 there is a retired-rail tombstone.
+   */
+  next_action;
+  /**
+   * #3103 (epic #3105, decisions 1 and 3): the typed next step beside the
+   * action. A refusal Haven made (`SIGN_CONTEXT_REFUSED`, not expired) names
+   * the hosted status read with the payment id — except a 404 from the direct
+   * fetch (#3271), which names none and points at the `typed_data_b64`
+   * relay; a transport failure or a
+   * malformed body names no tool — the remedy is re-running the SAME quote
+   * tool with `include_signing_payload: true` (x402), or the payment
+   * result's `typed_data_b64` relay (direct, #3271) — and an expired window names
+   * none either (which quote tool depends on the flow). Never null: a step
+   * with no tool carries `next_tool_omitted_reason`. Additive: the class is
+   * not exported from the package index — the published surface is the
+   * `ToolFailure` envelope `tools.ts` builds from these fields — and every
+   * constructor call site is in this file.
+   */
+  next_tool;
+  next_tool_server;
+  next_tool_name;
+  next_tool_server_role;
+  next_arguments;
+  next_tool_omitted_reason;
+  retry_with_new_quote;
+  /** Present only for `SIGN_CONTEXT_REFUSED` (the backend's HTTP status). */
+  http_status;
+  /** Present only for `SIGN_CONTEXT_REFUSED`: the backend's own `error_code`. */
+  backend_error_code;
+  /**
+   * #3303: on a 426 `client_outdated` refusal, the backend's update hint —
+   * this signer is below the minimum the deployment set, and
+   * `client_update.upgrade_command` is what updates it.
+   */
+  client_update;
+  constructor(message, code, refusal, paymentId, flow = "x402") {
+    super(message);
+    this.code = code;
+    this.name = "HavenSignContextError";
+    let step;
+    if (code === "SIGN_CONTEXT_REFUSED") {
+      this.http_status = refusal?.httpStatus;
+      this.backend_error_code = refusal?.errorCode;
+      if (refusal?.errorCode === "client_outdated") {
+        this.client_update = refusal.clientUpdate;
+        this.next_action = AgentPaymentNextAction.StopAndTellUser;
+        step = signerRefusalStep({
+          nextAction: AgentPaymentNextAction.StopAndTellUser,
+          nextTool: null,
+          nextToolOmittedReason: `this signer is below the minimum version Haven accepts \u2014 tell the user to run ${refusal.clientUpdate?.upgrade_command ?? "the connector again"}, restart the agent runtime, then retry the same haven_sign / haven_sign_x402 call`
+        });
+      } else if (flow === "direct" && refusal?.httpStatus === 404) {
+        this.fallback = "typed_data_b64";
+        this.next_action = AgentPaymentNextAction.StopAndTellUser;
+        step = signerRefusalStep({
+          nextAction: AgentPaymentNextAction.StopAndTellUser,
+          nextTool: null,
+          nextToolOmittedReason: DIRECT_RELAY_FALLBACK
+        });
+      } else if (flow === "direct" && refusal?.errorCode === "expired") {
+        this.next_action = AgentPaymentNextAction.PaymentWindowExpired;
+        step = signerRefusalStep({
+          nextAction: AgentPaymentNextAction.PaymentWindowExpired,
+          nextTool: null,
+          nextToolOmittedReason: "call haven_send / haven_pay again with the same idempotency_key \u2014 the expired payment frees it"
+        });
+      } else if (flow === "x402" && (refusal?.httpStatus === 410 || refusal?.errorCode === "expired")) {
+        this.next_action = AgentPaymentNextAction.PaymentWindowExpired;
+        this.retry_with_new_quote = true;
+        step = signerRefusalStep({
+          nextAction: AgentPaymentNextAction.PaymentWindowExpired,
+          nextTool: null,
+          nextToolOmittedReason: "re-run the hosted quote tool you called with the same idempotency_key; which one depends on the flow"
+        });
+      } else {
+        this.next_action = AgentPaymentNextAction.StopAndTellUser;
+        step = signerRefusalStep({
+          nextAction: AgentPaymentNextAction.StopAndTellUser,
+          nextTool: "haven_get_payment_status",
+          nextArguments: { payment_id: paymentId }
+        });
+      }
+    } else {
+      this.fallback = "typed_data_b64";
+      this.next_action = AgentPaymentNextAction.StopAndTellUser;
+      step = signerRefusalStep({
+        nextAction: AgentPaymentNextAction.StopAndTellUser,
+        nextTool: null,
+        nextToolOmittedReason: flow === "direct" ? DIRECT_RELAY_FALLBACK : "re-run the SAME hosted quote tool with the same idempotency_key and include_signing_payload: true, then pass its typed_data_b64 to this signer"
+      });
+    }
+    Object.assign(this, nextStepWireFields(step));
+  }
+};
+async function loadHavenIdentity(credentialsPath) {
+  if (!credentialsPath) return null;
+  try {
+    const raw = JSON.parse(
+      await readFile(join(dirname(credentialsPath), "identity.json"), "utf8")
+    );
+    const apiKey = typeof raw.api_key === "string" ? raw.api_key : void 0;
+    const apiUrl = typeof raw.api_url === "string" ? raw.api_url : void 0;
+    if (!apiKey || !apiUrl) return null;
+    return { apiKey, apiUrl: apiUrl.replace(/\/+$/, "") };
+  } catch {
+    return null;
+  }
+}
+var SIGN_CONTEXT_TIMEOUT_MS = 15e3;
+function signContextHeaders(identity, clientIdentity) {
+  return {
+    Authorization: `Bearer ${identity.apiKey}`,
+    ...clientIdentity ? { [HAVEN_CLIENT_HEADER]: clientIdentity } : {}
+  };
+}
+function refusalOf(status, body) {
+  return {
+    httpStatus: status,
+    errorCode: typeof body.error_code === "string" ? body.error_code : void 0,
+    clientUpdate: readClientUpdate(body.client_update)
+  };
+}
+async function fetchX402SignContext(identity, paymentId, fetchImpl = fetch, timeoutMs = SIGN_CONTEXT_TIMEOUT_MS, clientIdentity) {
+  let response;
+  try {
+    response = await fetchImpl(
+      `${identity.apiUrl}/x402/${encodeURIComponent(paymentId)}/sign-context`,
+      {
+        headers: signContextHeaders(identity, clientIdentity),
+        signal: AbortSignal.timeout(timeoutMs)
+      }
+    );
+  } catch (err) {
+    const timedOut = err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
+    throw new HavenSignContextError(
+      timedOut ? `Haven did not answer the signing-context fetch for ${paymentId} within ${timeoutMs} ms. Retry, or pass typed_data_b64 from the quote result instead.` : `Could not reach Haven to fetch the signing context for ${paymentId}: ${err instanceof Error ? err.message : String(err)}. Retry, or pass typed_data_b64 from the quote result instead.`,
+      timedOut ? "SIGN_CONTEXT_TIMEOUT" : "SIGN_CONTEXT_UNREACHABLE",
+      void 0,
+      paymentId
+    );
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch (err) {
+    if (err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError")) {
+      throw new HavenSignContextError(
+        `Haven did not finish sending the signing context for ${paymentId} within ${timeoutMs} ms. Retry, or pass typed_data_b64 from the quote result instead.`,
+        "SIGN_CONTEXT_TIMEOUT",
+        void 0,
+        paymentId
+      );
+    }
+    body = {};
+  }
+  if (!response.ok) {
+    const detail = typeof body.error === "string" ? body.error : `HTTP ${response.status}`;
+    throw new HavenSignContextError(
+      `Haven refused the signing-context fetch for ${paymentId}: ${detail}` + (response.status === 404 ? " \u2014 check the payment_id came from this agent\u2019s own quote." : response.status === 410 ? " Re-run the quote with the same idempotency key, then sign the fresh payment_id." : ""),
+      "SIGN_CONTEXT_REFUSED",
+      refusalOf(response.status, body),
+      paymentId
+    );
+  }
+  const signData = body.sign_data;
+  const x402Expected = body.x402_expected;
+  if (!signData || typeof signData.hash !== "string" || !signData.typed_data || typeof signData.typed_data !== "object" || !x402Expected) {
+    throw new HavenSignContextError(
+      "The Haven sign-context response is missing sign_data.typed_data or x402_expected \u2014 the backend may predate #1263. Pass typed_data_b64 from the quote result instead.",
+      "SIGN_CONTEXT_MALFORMED",
+      void 0,
+      paymentId
+    );
+  }
+  const paymentRequired = body.payment_required;
+  return {
+    paymentId: String(body.payment_id ?? paymentId),
+    payloadHash: signData.hash,
+    typedData: signData.typed_data,
+    x402Expected,
+    paymentRequired: paymentRequired && typeof paymentRequired === "object" && !Array.isArray(paymentRequired) ? paymentRequired : null,
+    clientUpdate: readClientUpdate(body.client_update)
+  };
+}
+var SUPPORTED_DIRECT_SIGN_CONTEXT_VERSIONS = [DIRECT_SIGN_CONTEXT_VERSION];
+async function fetchDirectSignContext(identity, paymentId, fetchImpl = fetch, timeoutMs = SIGN_CONTEXT_TIMEOUT_MS, clientIdentity) {
+  let response;
+  try {
+    response = await fetchImpl(
+      `${identity.apiUrl}/payments/${encodeURIComponent(paymentId)}/sign-context`,
+      {
+        headers: signContextHeaders(identity, clientIdentity),
+        signal: AbortSignal.timeout(timeoutMs)
+      }
+    );
+  } catch (err) {
+    const timedOut = err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
+    throw new HavenSignContextError(
+      timedOut ? `Haven did not answer the direct-payment signing-context fetch for ${paymentId} within ${timeoutMs} ms. Retry, or pass typed_data_b64 from the payment result instead.` : `Could not reach Haven to fetch the direct-payment signing context for ${paymentId}: ${err instanceof Error ? err.message : String(err)}. Retry, or pass typed_data_b64 from the payment result instead.`,
+      timedOut ? "SIGN_CONTEXT_TIMEOUT" : "SIGN_CONTEXT_UNREACHABLE",
+      void 0,
+      paymentId,
+      "direct"
+    );
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch (err) {
+    if (err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError")) {
+      throw new HavenSignContextError(
+        `Haven did not finish sending the direct-payment signing context for ${paymentId} within ${timeoutMs} ms. Retry, or pass typed_data_b64 from the payment result instead.`,
+        "SIGN_CONTEXT_TIMEOUT",
+        void 0,
+        paymentId,
+        "direct"
+      );
+    }
+    body = {};
+  }
+  if (!response.ok) {
+    const detail = typeof body.error === "string" ? body.error : `HTTP ${response.status}`;
+    throw new HavenSignContextError(
+      `Haven refused the direct-payment signing-context fetch for ${paymentId}: ${detail}` + (response.status === 404 ? " \u2014 either the payment_id is not from this agent\u2019s own POST /payments call, or this Haven backend predates #3271. Pass payload_hash and typed_data_b64 from the haven_send / haven_pay result, unchanged, instead." : body.error_code === "expired" ? " The payment window has expired; call haven_send / haven_pay again with the same idempotency_key." : ""),
+      "SIGN_CONTEXT_REFUSED",
+      refusalOf(response.status, body),
+      paymentId,
+      "direct"
+    );
+  }
+  const signData = body.sign_data;
+  const version = body.direct_sign_context_version;
+  if (!signData || typeof signData.hash !== "string" || !signData.typed_data || typeof signData.typed_data !== "object" || signData.signature_scheme !== "eip712_userop" || typeof version !== "number" || !SUPPORTED_DIRECT_SIGN_CONTEXT_VERSIONS.includes(version)) {
+    throw new HavenSignContextError(
+      typeof version === "number" && !SUPPORTED_DIRECT_SIGN_CONTEXT_VERSIONS.includes(version) ? `The Haven direct-payment sign-context response is version ${version}, which this signer does not support (supported: ${SUPPORTED_DIRECT_SIGN_CONTEXT_VERSIONS.join(", ")}). Update @haven_ai/signer.` : "The Haven direct-payment sign-context response is missing sign_data.typed_data, or its signature_scheme is not 'eip712_userop' \u2014 the backend may predate #3271. Pass typed_data_b64 from the payment result instead.",
+      "SIGN_CONTEXT_MALFORMED",
+      void 0,
+      paymentId,
+      "direct"
+    );
+  }
+  return {
+    paymentId: String(body.payment_id ?? paymentId),
+    payloadHash: signData.hash,
+    typedData: signData.typed_data,
+    status: typeof body.status === "string" ? body.status : "pending_signature",
+    expiresAt: typeof body.expires_at === "string" ? body.expires_at : void 0,
+    clientUpdate: readClientUpdate(body.client_update)
+  };
+}
+
+// src/capabilities.ts
 var SIGNER_CAPABILITY_KEY = "haven/signer-compatibility";
 function signerCompatibility() {
   return {
     x402_expected_context_versions: [...SUPPORTED_X402_EXPECTED_VERSIONS],
-    sweep_binding_versions: [...SUPPORTED_SWEEP_BINDING_VERSIONS]
+    sweep_binding_versions: [...SUPPORTED_SWEEP_BINDING_VERSIONS],
+    direct_sign_context_versions: [...SUPPORTED_DIRECT_SIGN_CONTEXT_VERSIONS]
   };
 }
 function signerCapabilityAdvertisement() {
@@ -478,12 +669,14 @@ function signerInstructions() {
   return [
     "Haven edge signer: sign-only tools bound to the local delegate key. It never emits the",
     "key. Its one network capability is an authenticated READ of a signing context from",
-    "Haven by payment_id \u2014 pass payment_id to haven_sign / haven_sign_x402 (preferred for",
-    "delegation-rail x402) instead of relaying bulky typed-data payloads yourself.",
+    "Haven by payment_id \u2014 pass payment_id to haven_sign (preferred for both a direct payment,",
+    "#3271, and delegation-rail x402) or haven_sign_x402 (x402 only) instead of relaying bulky",
+    "typed-data payloads yourself.",
     "",
     "Version compatibility (check this BEFORE signing, not after):",
     `- x402 expected-context versions supported: ${compatibility.x402_expected_context_versions.join(", ")}`,
     `- sweep authorization binding versions supported: ${compatibility.sweep_binding_versions.join(", ")}`,
+    `- direct-payment (haven_send / haven_pay) sign-context versions supported: ${compatibility.direct_sign_context_versions.join(", ")} \u2014 pass payment_id alone to haven_sign; this signer fetches the exact bytes`,
     "",
     "Haven quote and prepare results report the expected-context version they will emit",
     "(signer_compatibility.x402_expected_context_version). If that version is not in the list",
@@ -494,9 +687,68 @@ function signerInstructions() {
     "",
     "A version-mismatch refusal from haven_sign / haven_sign_x402 / haven_sign_sweep_delegate is",
     "machine-readable, not just prose: it carries code, supported_versions, received_version, and",
-    "fallback fields alongside the message, so you can branch on it directly."
+    "fallback fields alongside the message, so you can branch on it directly. Every signer",
+    "refusal also carries the next-step family: next_tool_name + next_tool_server_role when a",
+    "hosted tool follows (resolve the role against your own server names), else",
+    "next_tool_omitted_reason saying why not."
   ].join("\n");
 }
+var OWNER_ONLY_MODE = 384;
+var defaultLog = (message) => process.stderr.write(`${message}
+`);
+async function permissiveMode(path, platform = process.platform, stats, follow = "nofollow") {
+  if (platform === "win32") return null;
+  let info;
+  try {
+    info = stats ?? (follow === "follow" ? await stat(path) : await lstat(path));
+  } catch {
+    return null;
+  }
+  if ((info.mode & 63) === 0) return null;
+  return { octal: (info.mode & 511).toString(8).padStart(4, "0"), regular: info.isFile() };
+}
+async function warnIfFilePermissive(kind, path, log = defaultLog, platform = process.platform) {
+  const found = await permissiveMode(path, platform, void 0, "follow");
+  if (found === null) return;
+  log(
+    `haven-signer: warning: ${kind} at ${path} is readable beyond the owner (mode ${found.octal}). Run: chmod 600 ${path}`
+  );
+}
+async function tightenIfFilePermissive(kind, path, log = defaultLog, platform = process.platform, stats) {
+  if (platform === "win32") return "skipped";
+  let info = stats ?? null;
+  if (!info) {
+    try {
+      info = await lstat(path);
+    } catch {
+      return "owner-only";
+    }
+  }
+  if (!info.isFile()) {
+    log(
+      `haven-signer: warning: ${kind} at ${path} is not a regular file (a symlink or similar); audit rows are being written through it and it was not tightened. Remove it: rm ${path}`
+    );
+    return "warned";
+  }
+  const found = await permissiveMode(path, platform, info);
+  if (found === null) return "owner-only";
+  {
+    try {
+      await chmod(path, OWNER_ONLY_MODE);
+      log(
+        `haven-signer: ${kind} at ${path} was readable beyond the owner (mode ${found.octal}); tightened to 0600.`
+      );
+      return "tightened";
+    } catch {
+    }
+  }
+  log(
+    `haven-signer: warning: ${kind} at ${path} is readable beyond the owner (mode ${found.octal}) and could not be tightened. Run: chmod 600 ${path}`
+  );
+  return "warned";
+}
+
+// src/credentials.ts
 async function loadSignerCredentials(path = process.env.HAVEN_CREDENTIALS) {
   if (path) return loadFromFile(path);
   const envKey = stringField(process.env.HAVEN_DELEGATE_KEY);
@@ -593,28 +845,26 @@ function invalidChainIdError(label) {
 }
 async function warnIfCredentialFilePermissive(path, log = (message) => process.stderr.write(`${message}
 `), platform = process.platform) {
-  if (platform === "win32") return;
-  let mode;
-  try {
-    mode = (await stat(path)).mode;
-  } catch {
-    return;
-  }
-  if ((mode & 63) !== 0) {
-    const octal = (mode & 511).toString(8).padStart(4, "0");
-    log(
-      `haven-signer: warning: credential file at ${path} is readable beyond the owner (mode ${octal}). Run: chmod 600 ${path}`
-    );
-  }
+  await warnIfFilePermissive("credential file", path, log, platform);
 }
+var AUDIT_ROTATE_BYTES = 8 * 1024 * 1024;
 function defaultSigningAuditPath(credentialsPath) {
   if (credentialsPath) return resolve(`${credentialsPath}.signer-audit.jsonl`);
   return resolve(homedir(), ".haven", "signer-audit.jsonl");
 }
-async function appendSigningAuditEntry(entry, path) {
+async function appendSigningAuditEntry(entry, path, options = {}) {
   await mkdir(dirname(path), { recursive: true });
+  const rotateAt = options.rotateAtBytes ?? AUDIT_ROTATE_BYTES;
+  const existing = await lstat(path).catch(() => null);
+  if (existing) {
+    await tightenIfFilePermissive("audit sidecar", path, options.log, options.platform, existing);
+    if (existing.size >= rotateAt) {
+      await rename(path, `${path}.1`).catch(() => {
+      });
+    }
+  }
   await appendFile(path, `${JSON.stringify(entry)}
-`, "utf8");
+`, { encoding: "utf8", mode: OWNER_ONLY_MODE });
 }
 function createSigningAuditEntry(tool, payloadHash, context, now = /* @__PURE__ */ new Date()) {
   const entry = {
@@ -640,168 +890,112 @@ function stableStringify(value) {
   const object = value;
   return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(object[key])}`).join(",")}}`;
 }
-var HavenSignContextError = class extends HavenSigningError {
-  /**
-   * #3001 / #3010 review: the recovery path, when signing OTHER bytes is
-   * actually a remedy — a transport failure (timeout, unreachable) or a
-   * body this signer could not read. `typed_data_b64` is NOT in the default
-   * quote result since #1272: obtain it by re-running the SAME quote tool
-   * with the SAME idempotency_key plus `include_signing_payload: true`.
-   * Absent on a backend REFUSAL: an expired, executed or unsignable intent
-   * cannot be rescued by re-signing its bytes.
-   */
-  fallback;
-  /**
-   * #3001: `AgentPaymentNextAction` values the signer already emits — the
-   * version-mismatch refusal's `stop_and_tell_user` for the classes where
-   * retrying the same call cannot help, and `payment_window_expired` (with
-   * `retry_with_new_quote`) for the backend's 410 `expired`, exactly as the
-   * plain `HavenError` branch already does for that code.
-   */
-  next_action;
-  retry_with_new_quote;
-  /** Present only for `SIGN_CONTEXT_REFUSED` (the backend's HTTP status). */
-  http_status;
-  /** Present only for `SIGN_CONTEXT_REFUSED`: the backend's own `error_code`. */
-  backend_error_code;
-  constructor(message, code, refusal) {
-    super(message);
-    this.code = code;
-    this.name = "HavenSignContextError";
-    if (code === "SIGN_CONTEXT_REFUSED") {
-      this.http_status = refusal?.httpStatus;
-      this.backend_error_code = refusal?.errorCode;
-      if (refusal?.httpStatus === 410 || refusal?.errorCode === "expired") {
-        this.next_action = AgentPaymentNextAction.PaymentWindowExpired;
-        this.retry_with_new_quote = true;
-      } else {
-        this.next_action = AgentPaymentNextAction.StopAndTellUser;
-      }
-    } else {
-      this.fallback = "typed_data_b64";
-      this.next_action = AgentPaymentNextAction.StopAndTellUser;
-    }
+var BARE_HASH_REFUSED = "BARE_HASH_REFUSED";
+var HavenBareHashRefusedError = class extends HavenSigningError {
+  next_action = AgentPaymentNextAction.StopAndTellUser;
+  step;
+  constructor() {
+    super(
+      "Refusing to sign a bare payload_hash. A hash carries no shape, amount, merchant or binding, so this signer cannot tell a Haven payment from a transfer out of the delegate wallet or a delegation of its authority \u2014 and the only rail that ever validated a raw hash signature is retired. Call this tool with { payment_id } (the signer fetches and verifies the Haven-signed context itself), or with typed_data / typed_data_b64 (the account validates that EIP-712 payload), or with x402_expected for an x402 funding leg."
+    );
+    this.code = BARE_HASH_REFUSED;
+    this.name = "HavenBareHashRefusedError";
+    this.step = signerRefusalStep({
+      nextAction: AgentPaymentNextAction.StopAndTellUser,
+      nextTool: null,
+      nextToolOmittedReason: "call haven_sign again with payment_id (preferred), typed_data / typed_data_b64, or x402_expected \u2014 a bare payload_hash is never signed"
+    });
   }
 };
-async function loadHavenIdentity(credentialsPath) {
-  if (!credentialsPath) return null;
-  try {
-    const raw = JSON.parse(
-      await readFile(join(dirname(credentialsPath), "identity.json"), "utf8")
-    );
-    const apiKey = typeof raw.api_key === "string" ? raw.api_key : void 0;
-    const apiUrl = typeof raw.api_url === "string" ? raw.api_url : void 0;
-    if (!apiKey || !apiUrl) return null;
-    return { apiKey, apiUrl: apiUrl.replace(/\/+$/, "") };
-  } catch {
-    return null;
+
+// src/tools.ts
+var USEROP_BINDING_MISMATCH = "USEROP_BINDING_MISMATCH";
+var HavenUserOpBindingRefusedError = class extends HavenSigningError {
+  next_action = AgentPaymentNextAction.StopAndTellUser;
+  step;
+  /** `message`: the SDK's `HavenUserOpBindingError.message` verbatim — it already names the mismatch and the remedy. */
+  constructor(message) {
+    super(message);
+    this.code = USEROP_BINDING_MISMATCH;
+    this.name = "HavenUserOpBindingRefusedError";
+    this.step = signerRefusalStep({
+      nextAction: AgentPaymentNextAction.StopAndTellUser,
+      nextTool: null,
+      nextToolOmittedReason: "call haven_sign again with payment_id alone (preferred), or with typed_data copied unchanged from the payment result"
+    });
   }
-}
-var SIGN_CONTEXT_TIMEOUT_MS = 15e3;
-async function fetchX402SignContext(identity, paymentId, fetchImpl = fetch, timeoutMs = SIGN_CONTEXT_TIMEOUT_MS) {
-  let response;
-  try {
-    response = await fetchImpl(
-      `${identity.apiUrl}/x402/${encodeURIComponent(paymentId)}/sign-context`,
-      {
-        headers: { Authorization: `Bearer ${identity.apiKey}` },
-        signal: AbortSignal.timeout(timeoutMs)
-      }
-    );
-  } catch (err) {
-    const timedOut = err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
-    throw new HavenSignContextError(
-      timedOut ? `Haven did not answer the signing-context fetch for ${paymentId} within ${timeoutMs} ms. Retry, or pass typed_data_b64 from the quote result instead.` : `Could not reach Haven to fetch the signing context for ${paymentId}: ${err instanceof Error ? err.message : String(err)}. Retry, or pass typed_data_b64 from the quote result instead.`,
-      timedOut ? "SIGN_CONTEXT_TIMEOUT" : "SIGN_CONTEXT_UNREACHABLE"
-    );
+};
+var HavenTypedDataNotAllowedError = class extends HavenTypedDataRefusedError {
+  next_action = AgentPaymentNextAction.StopAndTellUser;
+  step;
+  constructor(message) {
+    super(message);
+    this.name = "HavenTypedDataNotAllowedError";
+    this.step = signerRefusalStep({
+      nextAction: AgentPaymentNextAction.StopAndTellUser,
+      nextTool: null,
+      nextToolOmittedReason: "sign only Haven-prepared payloads: call haven_sign with payment_id (preferred), or pass typed_data / typed_data_b64 copied unchanged from a haven_send / haven_pay result, or x402_expected from a Haven quote"
+    });
   }
-  let body;
+};
+function assertBoundDirectPaymentUserOp2(typedData, delegateAddress) {
   try {
-    body = await response.json();
+    assertBoundDirectPaymentUserOp(typedData, delegateAddress);
   } catch (err) {
-    if (err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError")) {
-      throw new HavenSignContextError(
-        `Haven did not finish sending the signing context for ${paymentId} within ${timeoutMs} ms. Retry, or pass typed_data_b64 from the quote result instead.`,
-        "SIGN_CONTEXT_TIMEOUT"
-      );
+    if (err instanceof HavenTypedDataRefusedError && !(err instanceof HavenTypedDataNotAllowedError)) {
+      throw new HavenTypedDataNotAllowedError(err.message);
     }
-    body = {};
+    throw err;
   }
-  if (!response.ok) {
-    const detail = typeof body.error === "string" ? body.error : `HTTP ${response.status}`;
-    throw new HavenSignContextError(
-      `Haven refused the signing-context fetch for ${paymentId}: ${detail}` + (response.status === 404 ? " \u2014 check the payment_id came from this agent\u2019s own quote." : response.status === 410 ? " Re-run the quote with the same idempotency key, then sign the fresh payment_id." : ""),
-      "SIGN_CONTEXT_REFUSED",
-      { httpStatus: response.status, errorCode: typeof body.error_code === "string" ? body.error_code : void 0 }
-    );
-  }
-  const signData = body.sign_data;
-  const x402Expected = body.x402_expected;
-  if (!signData || typeof signData.hash !== "string" || !signData.typed_data || typeof signData.typed_data !== "object" || !x402Expected) {
-    throw new HavenSignContextError(
-      "The Haven sign-context response is missing sign_data.typed_data or x402_expected \u2014 the backend may predate #1263. Pass typed_data_b64 from the quote result instead.",
-      "SIGN_CONTEXT_MALFORMED"
-    );
-  }
-  const paymentRequired = body.payment_required;
-  return {
-    paymentId: String(body.payment_id ?? paymentId),
-    payloadHash: signData.hash,
-    typedData: signData.typed_data,
-    x402Expected,
-    paymentRequired: paymentRequired && typeof paymentRequired === "object" && !Array.isArray(paymentRequired) ? paymentRequired : null
-  };
 }
-
-// src/tools.ts
-var sweepAuthorizationSchema = z.object({
-  from: z.string().regex(/^0x[0-9a-fA-F]{40}$/, "from must be a 0x address"),
-  to: z.string().regex(/^0x[0-9a-fA-F]{40}$/, "to must be a 0x address"),
-  value: z.string().regex(/^[0-9]+$/, "value must be a decimal atomic amount"),
-  validAfter: z.string().regex(/^[0-9]+$/, "validAfter must be a decimal unix time"),
-  validBefore: z.string().regex(/^[0-9]+$/, "validBefore must be a decimal unix time"),
-  nonce: z.string().regex(/^0x[0-9a-fA-F]{64}$/, "nonce must be a 0x-prefixed 32-byte hex string"),
-  token: z.string().regex(/^0x[0-9a-fA-F]{40}$/, "token must be a 0x address"),
-  chainId: z.number().int().positive()
+var sweepAuthorizationSchema = z$1.object({
+  from: z$1.string().regex(/^0x[0-9a-fA-F]{40}$/, "from must be a 0x address"),
+  to: z$1.string().regex(/^0x[0-9a-fA-F]{40}$/, "to must be a 0x address"),
+  value: z$1.string().regex(/^[0-9]+$/, "value must be a decimal atomic amount"),
+  validAfter: z$1.string().regex(/^[0-9]+$/, "validAfter must be a decimal unix time"),
+  validBefore: z$1.string().regex(/^[0-9]+$/, "validBefore must be a decimal unix time"),
+  nonce: z$1.string().regex(/^0x[0-9a-fA-F]{64}$/, "nonce must be a 0x-prefixed 32-byte hex string"),
+  token: z$1.string().regex(/^0x[0-9a-fA-F]{40}$/, "token must be a 0x address"),
+  chainId: z$1.number().int().positive()
 });
-var bindingVersionSchema = z.number().int().positive();
-var sweepExpectedAuthSchema = z.object({
+var bindingVersionSchema = z$1.number().int().positive();
+var sweepExpectedAuthSchema = z$1.object({
   version: bindingVersionSchema,
-  message: z.string().min(1),
-  signature: z.string().regex(/^0x[0-9a-fA-F]+$/, "signature must be a 0x-prefixed hex string"),
-  signer: z.string().regex(/^0x[0-9a-fA-F]{40}$/, "signer must be a 0x address")
+  message: z$1.string().min(1),
+  signature: z$1.string().regex(/^0x[0-9a-fA-F]+$/, "signature must be a 0x-prefixed hex string"),
+  signer: z$1.string().regex(/^0x[0-9a-fA-F]{40}$/, "signer must be a 0x address")
 });
 var x402ExpectedShape = {
-  payment_id: z.string().min(1),
-  payload_hash: z.string().regex(/^0x[0-9a-fA-F]+$/, "payload_hash must be a 0x-prefixed hex string"),
-  resource_url: z.string().url(),
-  merchant_to: z.string().min(1),
-  amount: z.string().min(1),
-  asset: z.string().min(1),
-  network: z.string().min(1),
+  payment_id: z$1.string().min(1),
+  payload_hash: z$1.string().regex(/^0x[0-9a-fA-F]{64}$/, "payload_hash must be a 0x-prefixed 32-byte hex string"),
+  resource_url: z$1.string().url(),
+  merchant_to: z$1.string().min(1),
+  amount: z$1.string().min(1),
+  asset: z$1.string().min(1),
+  network: z$1.string().min(1),
   // Required: expires_at is folded into the Haven-signed binding message, so the
   // signer must receive the exact same value to reconstruct a matching message.
   // Omitting it used to fail downstream with a cryptic "authentication message is
   // invalid" — making it required surfaces a clear INVALID_INPUT at the boundary.
-  expires_at: z.string().min(1),
+  expires_at: z$1.string().min(1),
   // #1138: present on a delegation-rail (v2) context. It commits to the EIP-712
   // typed data the account validates; the signer refuses to raw-sign the bare
   // hash when it is present, and refuses to sign typed data when it is absent.
-  typed_data_hash: z.string().regex(/^0x[0-9a-fA-F]+$/, "typed_data_hash must be a 0x-prefixed hex string").optional(),
+  typed_data_hash: z$1.string().regex(/^0x[0-9a-fA-F]{64}$/, "typed_data_hash must be a 0x-prefixed 32-byte hex string").optional(),
   // #1690: present on a v3 context. The delegate this quote was created FOR —
   // the signer refuses to sign when it is not its own. Inside the Haven-signed
   // message, so stripping it here would only break the binding signature.
-  payer_delegate: z.string().regex(/^0x[0-9a-fA-F]{40}$/, "payer_delegate must be a 0x-prefixed address").optional(),
-  payer_agent_id: z.string().min(1).optional(),
-  auth: z.object({
+  payer_delegate: z$1.string().regex(/^0x[0-9a-fA-F]{40}$/, "payer_delegate must be a 0x-prefixed address").optional(),
+  payer_agent_id: z$1.string().min(1).optional(),
+  auth: z$1.object({
     // Open at the boundary, enforced in the signer — see bindingVersionSchema.
     version: bindingVersionSchema,
-    message: z.string().min(1),
-    signature: z.string().regex(/^0x[0-9a-fA-F]+$/, "signature must be a 0x-prefixed hex string"),
-    signer: z.string().min(1)
+    message: z$1.string().min(1),
+    signature: z$1.string().regex(/^0x[0-9a-fA-F]+$/, "signature must be a 0x-prefixed hex string"),
+    signer: z$1.string().min(1)
   })
 };
-var x402ExpectedSchema = z.object(x402ExpectedShape);
+var x402ExpectedSchema = z$1.object(x402ExpectedShape);
 var toolSchemas = {
   haven_sign_sweep_delegate: {
     // The authorization fields prepared by Haven's POST /sweep/prepare. Passed
@@ -816,17 +1010,17 @@ var toolSchemas = {
     // payload + expected context from Haven itself (authenticated with the
     // locally-stored agent credential), so no bulky bytes ever cross the
     // model. Pass payment_id ALONE for a delegation-rail x402 funding intent.
-    payment_id: z.string().min(1).optional(),
+    payment_id: z$1.string().min(1).optional(),
     // The unsigned hash from haven_pay / haven_pay_x402_quote (payload_hash).
     // Optional when payment_id is supplied (the fetch carries it).
-    payload_hash: z.string().regex(/^0x[0-9a-fA-F]+$/, "payload_hash must be a 0x-prefixed hex string").optional(),
+    payload_hash: z$1.string().regex(/^0x[0-9a-fA-F]{64}$/, "payload_hash must be a 0x-prefixed 32-byte hex string").optional(),
     // Pass x402.expected from hosted haven_pay_x402_quote when this hash funds
     // a standard x402 merchant retry. The signer records it locally and returns
     // an opaque x402_binding for the later header-signing step.
     x402_expected: x402ExpectedSchema.optional(),
     // #1138: delegation-rail intents sign THIS, not payload_hash. Object-typed
     // (not z.unknown()) so MCP clients embed it as JSON rather than a string.
-    typed_data: z.record(z.string(), z.unknown()).optional(),
+    typed_data: z$1.record(z$1.string(), z$1.unknown()).optional(),
     // #1255: the same payload as ONE opaque base64 string, exactly as returned
     // by the hosted tools. Preferred over typed_data when both are present —
     // an agent re-emitting multi-KB nested JSON between tool calls is the
@@ -835,48 +1029,57 @@ var toolSchemas = {
     // Bounded: a realistic redemption payload is ~10KB encoded; 256KB is
     // generous headroom while keeping the offline signer from materializing
     // arbitrarily large caller input.
-    typed_data_b64: z.string().min(1).max(262144).optional()
+    typed_data_b64: z$1.string().min(1).max(262144).optional()
   },
   haven_x402_sign_header: {
     // The parsed HTTP 402 PaymentRequired from the merchant. Typed as an object
     // (not z.unknown(), which becomes empty JSON Schema `{}`) so MCP clients
     // embed it as JSON rather than serialising the object to a string.
-    payment_required: z.record(z.string(), z.unknown()),
+    payment_required: z$1.record(z$1.string(), z$1.unknown()),
     // Opaque binding returned by haven_sign when x402_expected was supplied.
-    x402_binding: z.string().min(1)
+    x402_binding: z$1.string().min(1)
   },
   haven_sign_x402: {
     // #1263: preferred — pass payment_id (plus payment_required) and the
     // signer fetches the exact signing payload + expected context itself.
-    payment_id: z.string().min(1).optional(),
+    payment_id: z$1.string().min(1).optional(),
     // One-shot x402 signing: funding hash + merchant header in one local call.
     // Both optional when payment_id is supplied (the fetch carries them).
-    payload_hash: z.string().regex(/^0x[0-9a-fA-F]+$/, "payload_hash must be a 0x-prefixed hex string").optional(),
+    payload_hash: z$1.string().regex(/^0x[0-9a-fA-F]{64}$/, "payload_hash must be a 0x-prefixed 32-byte hex string").optional(),
     x402_expected: x402ExpectedSchema.optional(),
     // #1355: optional when payment_id is supplied — the signer's context fetch
     // carries the stored 402 PaymentRequired, so `{ payment_id }` alone is the
     // preferred call. Still required (via the runtime check in the handler)
     // for the quote-based fallback path without a payment_id.
-    payment_required: z.record(z.string(), z.unknown()).optional(),
+    payment_required: z$1.record(z$1.string(), z$1.unknown()).optional(),
     // #1138: delegation-rail intents sign THIS, not payload_hash. Object-typed
     // (not z.unknown()) so MCP clients embed it as JSON rather than a string.
-    typed_data: z.record(z.string(), z.unknown()).optional(),
+    typed_data: z$1.record(z$1.string(), z$1.unknown()).optional(),
     // #1255: see haven_sign.typed_data_b64 — the copy-through-safe form.
-    typed_data_b64: z.string().min(1).max(262144).optional()
+    typed_data_b64: z$1.string().min(1).max(262144).optional()
   }
+  // #3101: keys survive on the type (see the hosted server's contracts.ts).
 };
 var SIGN_DESCRIPTION = [
-  "Sign an unsigned Haven payment hash with the local delegate key. The delegate key never leaves",
-  "this process. Pass the payload_hash returned by haven_pay or haven_pay_x402_quote.",
+  "Sign an unsigned Haven payment with the local delegate key. The delegate key never leaves",
+  "this process. Pass payment_id (preferred), or the payload_hash from haven_pay / haven_pay_x402_quote",
+  "TOGETHER WITH typed_data / typed_data_b64 or x402_expected \u2014 never a payload_hash alone.",
   "For x402, also pass x402_expected from haven_pay_x402_quote; the signer records it locally",
   "and returns { signature, x402_binding }. x402_expected includes expires_at; sign before that",
   "window closes. DELEGATION-RAIL x402 accounts (#1263): pass payment_id ALONE (preferred) \u2014 this",
   "signer fetches the exact signing payload and expected context from Haven itself, so nothing",
-  "bulky ever crosses your context. Fallback: pass typed_data_b64 through UNCHANGED (never re-type",
-  "the nested typed_data JSON); the account validates that EIP-712 payload, not payload_hash.",
+  "bulky ever crosses your context. DIRECT payments (#3271, haven_send / haven_pay): payment_id",
+  "ALONE also works here \u2014 the signer fetches the exact PackedUserOperation typed data and its",
+  "payload_hash from Haven and checks them against each other before signing, so a payload corrupted",
+  "in transit is refused (USEROP_BINDING_MISMATCH) instead of producing a bad signature. Fallback for",
+  "either flow: pass typed_data_b64 through UNCHANGED (never re-type the nested typed_data JSON); the",
+  "account validates that EIP-712 payload, not payload_hash. On a direct payment the same binding",
+  "check runs on the relayed payload too. This tool signs ONLY Haven-prepared payloads (#3272): a",
+  "direct-payment UserOp from your own account that redeems a delegation granted to it, or an x402",
+  "intent against a Haven-signed context \u2014 never an arbitrary typed_data payload, however it is shaped.",
   "Next: call mcp__haven__haven_submit with signature, then pass x402_binding",
-  "to mcp__haven-signer__haven_x402_sign_header. For plain SafeTransfer payments, just pass payload_hash and",
-  "relay the returned signature via mcp__haven__haven_submit."
+  "to mcp__haven-signer__haven_x402_sign_header. A bare payload_hash with no payment_id, typed_data",
+  "or x402_expected is REFUSED (BARE_HASH_REFUSED): a hash carries nothing this signer can verify."
 ].join(" ");
 var X402_SIGN_HEADER_DESCRIPTION = [
   "Build and sign the EIP-3009 merchant payment header for the merchant leg of an x402 payment.",
@@ -894,7 +1097,7 @@ var X402_SIGN_HEADER_DESCRIPTION = [
   "the funding tx has a confirmed status). Next for paid MCP tools: call mcp__haven__haven_complete_mcp_tool."
 ].join(" ");
 var SIGN_X402_DESCRIPTION = [
-  "One-shot x402 signing for the fast 3-call flow: sign the funding hash AND build the EIP-3009",
+  "One-shot x402 signing for the fast 3-call flow: sign the funding payload AND build the EIP-3009",
   "merchant payment header in a single local call (equivalent to haven_sign followed by",
   "haven_x402_sign_header). The delegate key never leaves this process. From the haven_pay_mcp_tool",
   "result pass JUST payment_id \u2014 PREFERRED (#1263, #1355): this signer fetches the exact signing",
@@ -920,12 +1123,13 @@ var SIGN_X402_DESCRIPTION = [
 ].join(" ");
 var SIGN_SWEEP_DELEGATE_DESCRIPTION = [
   "Sign a Haven-prepared gasless USDC sweep that recovers stranded funds from the delegate",
-  "wallet back to your Haven wallet. The delegate key never leaves this process and this tool",
-  "never broadcasts \u2014 it returns only an EIP-3009 signature that Haven's relayer submits and",
+  "wallet back to the agent's account (Haven wallet). The delegate key never leaves this process and this",
+  "tool never broadcasts \u2014 it returns only an EIP-3009 signature that Haven's relayer submits and",
   "pays gas for. Pass the authorization and expected_auth returned by the hosted",
-  "haven_sweep_delegate tool. The signer verifies Haven authored the authorization and that it",
-  "pays out to your own Safe before signing, then returns { signature } to hand back to",
-  "mcp__haven__haven_sweep_delegate to complete recovery."
+  "haven_sweep_delegate tool. The signer verifies Haven authored the authorization; the",
+  "destination is checked against the agent's account (Haven wallet) from the local credential",
+  "when the credential carries one, and otherwise rests on Haven's binding signature. Then it",
+  "returns { signature } to hand back to mcp__haven__haven_sweep_delegate to complete recovery."
 ].join(" ");
 var toolDescriptions = {
   haven_sign: SIGN_DESCRIPTION,
@@ -933,16 +1137,18 @@ var toolDescriptions = {
   haven_sign_x402: SIGN_X402_DESCRIPTION,
   haven_sign_sweep_delegate: SIGN_SWEEP_DELEGATE_DESCRIPTION
 };
-async function signFundingLeg(signer, expected, payloadHash, typedData) {
-  if (!expected.typedDataHash) {
-    return signer.signX402FundingHash(payloadHash, expected);
-  }
-  if (!typedData) {
-    throw new HavenSigningError(
-      "This x402 funding intent is on the delegation rail: it commits to EIP-712 typed data, which was not supplied. Pass typed_data_b64 from haven_pay_mcp_tool / haven_pay_x402_quote through unchanged (or typed_data verbatim) \u2014 the bare payload_hash is not what the account validates."
-    );
+async function signFundingLeg(signer, expected, typedData) {
+  try {
+    return await signer.signX402FundingTypedData(typedData, expected);
+  } catch (err) {
+    if (err instanceof HavenTypedDataRefusedError && !(err instanceof HavenTypedDataNotAllowedError)) {
+      throw new HavenTypedDataNotAllowedError(err.message);
+    }
+    if (err instanceof HavenUserOpBindingError) {
+      throw new HavenUserOpBindingRefusedError(err.message);
+    }
+    throw err;
   }
-  return signer.signX402FundingTypedData(typedData, expected);
 }
 function toExpectedX402(raw) {
   return {
@@ -961,7 +1167,7 @@ function toExpectedX402(raw) {
   };
 }
 function parseFetchedExpected(fetched) {
-  const parsed = z.object(x402ExpectedShape).safeParse(fetched.x402Expected);
+  const parsed = z$1.object(x402ExpectedShape).safeParse(fetched.x402Expected);
   if (!parsed.success) {
     throw new HavenSigningError(
       `The Haven sign-context response carried a malformed x402_expected \u2014 the backend may predate #1263. Pass payload_hash + x402_expected from the quote result instead. Underlying: ${parsed.error.issues[0]?.message ?? "schema mismatch"}`
@@ -969,6 +1175,9 @@ function parseFetchedExpected(fetched) {
   }
   return parsed.data;
 }
+function clientUpdateField(resolved) {
+  return resolved?.ctx.clientUpdate ? { client_update: resolved.ctx.clientUpdate } : {};
+}
 function resolveTypedData(args) {
   if (!args.typed_data_b64) return args.typed_data;
   try {
@@ -986,7 +1195,14 @@ function resolveTypedData(args) {
   }
 }
 function createToolHandlers(signer, options = {}) {
-  async function resolveSignContext(args) {
+  function checkPayloadHashMatch(suppliedHash, fetchedHash, paymentId) {
+    if (suppliedHash && suppliedHash.toLowerCase() !== fetchedHash.toLowerCase()) {
+      throw new HavenSigningError(
+        `The supplied payload_hash does not match the signing context Haven serves for payment ${paymentId}. Pass payment_id alone, or check which quote the hash came from.`
+      );
+    }
+  }
+  async function resolveSignContext(args, opts) {
     if (!args.payment_id) return null;
     const identity = await options.signContext?.loadIdentity() ?? null;
     if (!identity) {
@@ -994,32 +1210,53 @@ function createToolHandlers(signer, options = {}) {
         `payment_id signing needs the agent identity (identity.json next to the signer credentials), which this signer could not load. Re-run \`${connectorRerunCommand()}\` to restore it, or pass typed_data_b64 from the quote result instead.`
       );
     }
-    const ctx = await fetchX402SignContext(
-      identity,
-      args.payment_id,
-      options.signContext?.fetchImpl
-    );
-    if (args.payload_hash && args.payload_hash.toLowerCase() !== ctx.payloadHash.toLowerCase()) {
-      throw new HavenSigningError(
-        `The supplied payload_hash does not match the signing context Haven serves for payment ${args.payment_id}. Pass payment_id alone, or check which quote the hash came from.`
+    try {
+      const ctx = await fetchX402SignContext(
+        identity,
+        args.payment_id,
+        options.signContext?.fetchImpl,
+        void 0,
+        options.signContext?.clientIdentity
       );
+      checkPayloadHashMatch(args.payload_hash, ctx.payloadHash, args.payment_id);
+      return { kind: "x402", ctx };
+    } catch (err) {
+      if (opts.allowDirectFallback && err instanceof HavenSignContextError && err.http_status === 409 && err.backend_error_code === "sign_context_unavailable") {
+        let ctx;
+        try {
+          ctx = await fetchDirectSignContext(
+            identity,
+            args.payment_id,
+            options.signContext?.fetchImpl,
+            void 0,
+            options.signContext?.clientIdentity
+          );
+        } catch (directErr) {
+          if (directErr instanceof HavenSignContextError && directErr.http_status === 409 && directErr.backend_error_code === "sign_context_unavailable") {
+            throw err;
+          }
+          throw directErr;
+        }
+        checkPayloadHashMatch(args.payload_hash, ctx.payloadHash, args.payment_id);
+        return { kind: "direct", ctx };
+      }
+      throw err;
     }
-    return ctx;
   }
   return {
     haven_sign: async (input) => runTool(async () => {
       const args = parse("haven_sign", coerceX402Expected(input));
-      const fetched = await resolveSignContext(args);
-      const typedData = fetched?.typedData ?? resolveTypedData(args);
-      const payloadHash = fetched?.payloadHash ?? args.payload_hash;
+      const resolved = await resolveSignContext(args, { allowDirectFallback: true });
+      const typedData = resolved?.ctx.typedData ?? resolveTypedData(args);
+      const payloadHash = resolved?.ctx.payloadHash ?? args.payload_hash;
       if (!payloadHash) {
         throw new HavenSigningError(
-          "Pass payment_id (preferred for delegation-rail x402) or payload_hash."
+          "Pass payment_id (preferred for delegation-rail x402 or direct payments) or payload_hash."
         );
       }
-      const expectedRaw = fetched ? parseFetchedExpected(fetched) : args.x402_expected;
+      const expectedRaw = resolved?.kind === "x402" ? parseFetchedExpected(resolved.ctx) : resolved?.kind === "direct" ? null : args.x402_expected;
       const x402Expected = expectedRaw ? toExpectedX402(expectedRaw) : null;
-      const result = x402Expected ? await signFundingLeg(signer, x402Expected, payloadHash, typedData) : null;
+      const result = x402Expected ? await signFundingLeg(signer, x402Expected, typedData) : null;
       if (!result) {
         if (typedData) {
           if (isSettlementChildTypedData(typedData)) {
@@ -1027,16 +1264,28 @@ function createToolHandlers(signer, options = {}) {
               "Refusing to sign a delegation payload with no expected context. This typed data is a DELEGATION \u2014 signing it grants a third party authority to move funds \u2014 so it is only ever signed against a Haven-signed context that the caveats are verified against. Call this tool with { payment_id } instead (the signer then fetches and verifies the context itself), or use haven_sign_x402."
             );
           }
-          const signature2 = await signer.signDelegationTypedData(typedData);
-          await auditSigning("haven_sign", payloadHash);
-          return { signature: signature2 };
+          if (resolved?.kind !== "direct" && !isPackedUserOperationTypedData(typedData)) {
+            throw new HavenTypedDataNotAllowedError(
+              "This signer signs only Haven-prepared payloads: a direct-payment PackedUserOperation from your own account that redeems a delegation granted to it, or a Haven-signed x402 context. Call haven_sign with payment_id (preferred), or pass x402_expected for an x402 funding leg."
+            );
+          }
+          try {
+            assertUserOpTypedDataBinding(typedData, payloadHash);
+          } catch (err) {
+            if (err instanceof HavenUserOpBindingError) {
+              throw new HavenUserOpBindingRefusedError(err.message);
+            }
+            throw err;
+          }
+          assertBoundDirectPaymentUserOp2(typedData, signer.delegateAddress);
+          const signature = await signer.signDelegationTypedData(typedData);
+          await auditSigning("haven_sign", hashTypedData(typedData));
+          return { signature, ...clientUpdateField(resolved) };
         }
-        const signature = signer.signPaymentHash(payloadHash);
-        await auditSigning("haven_sign", payloadHash);
-        return { signature };
+        throw new HavenBareHashRefusedError();
       }
-      await auditSigning("haven_sign", payloadHash);
-      return { signature: result.signature, x402_binding: result.x402Binding };
+      await auditSigning("haven_sign", hashTypedData(typedData));
+      return { signature: result.signature, x402_binding: result.x402Binding, ...clientUpdateField(resolved) };
     }),
     haven_x402_sign_header: async (input) => runTool(async () => {
       const args = parse("haven_x402_sign_header", coercePaymentRequired(input));
@@ -1052,7 +1301,8 @@ function createToolHandlers(signer, options = {}) {
     }),
     haven_sign_x402: async (input) => runTool(async () => {
       const args = parse("haven_sign_x402", coerceX402Expected(coercePaymentRequired(input)));
-      const fetched = await resolveSignContext(args);
+      const resolved = await resolveSignContext(args, { allowDirectFallback: false });
+      const fetched = resolved?.kind === "x402" ? resolved.ctx : void 0;
       const payloadHash = fetched?.payloadHash ?? args.payload_hash;
       const expectedRaw = fetched ? parseFetchedExpected(fetched) : args.x402_expected;
       if (!payloadHash || !expectedRaw) {
@@ -1060,12 +1310,8 @@ function createToolHandlers(signer, options = {}) {
           "Pass payment_id (preferred \u2014 the signer fetches the signing context itself) or payload_hash + x402_expected from the quote result."
         );
       }
-      const funding = await signFundingLeg(
-        signer,
-        toExpectedX402(expectedRaw),
-        payloadHash,
-        fetched?.typedData ?? resolveTypedData(args)
-      );
+      const fundingTypedData = fetched?.typedData ?? resolveTypedData(args);
+      const funding = await signFundingLeg(signer, toExpectedX402(expectedRaw), fundingTypedData);
       const paymentRequired = fetched?.paymentRequired ?? args.payment_required;
       if (!paymentRequired) {
         throw new HavenSigningError(
@@ -1076,13 +1322,17 @@ function createToolHandlers(signer, options = {}) {
         paymentRequired,
         funding.x402Binding
       );
-      await auditSigning("haven_sign_x402", payloadHash);
+      await auditSigning(
+        "haven_sign_x402",
+        hashTypedData(fundingTypedData)
+      );
       await auditSigning("haven_sign_x402", hashPayloadForAudit(paymentRequired));
       return {
         signature: funding.signature,
         x402_binding: funding.x402Binding,
         payment_header: header.paymentHeader,
-        accepted: header.accepted
+        accepted: header.accepted,
+        ...clientUpdateField(resolved)
       };
     }),
     haven_sign_sweep_delegate: async (input) => runTool(async () => {
@@ -1090,7 +1340,8 @@ function createToolHandlers(signer, options = {}) {
       const result = await signer.signSweepAuthorization({
         authorization: args.authorization,
         expectedAuth: args.expected_auth,
-        // Cross-check `to` against the Safe in the local credential when present.
+        // Cross-check `to` against the agent's account (Haven wallet) from the
+        // local credential, when the credential carries one.
         expectedSafe: options.audit?.accountAddress
       });
       await auditSigning(
@@ -1103,17 +1354,23 @@ function createToolHandlers(signer, options = {}) {
   async function auditSigning(tool, payloadHash) {
     if (!options.audit) return;
     const { auditPath, ...context } = options.audit;
-    await appendSigningAuditEntry(
-      createSigningAuditEntry(tool, payloadHash, {
-        ...context,
-        delegateAddress: signer.delegateAddress
-      }),
-      auditPath
-    );
+    try {
+      await appendSigningAuditEntry(
+        createSigningAuditEntry(tool, payloadHash, {
+          ...context,
+          delegateAddress: signer.delegateAddress
+        }),
+        auditPath
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`haven-signer: warning: audit entry for ${tool} could not be written to ${auditPath}: ${message}
+`);
+    }
   }
 }
 function parse(name, input) {
-  return z.object(toolSchemas[name]).parse(input ?? {});
+  return z$1.object(toolSchemas[name]).parse(input ?? {});
 }
 function coerceX402Expected(input) {
   if (!input || typeof input !== "object") return input;
@@ -1152,7 +1409,7 @@ async function runTool(fn) {
   }
 }
 function normalizeError(err) {
-  if (err instanceof z.ZodError) {
+  if (err instanceof z$1.ZodError) {
     return {
       success: false,
       code: "INVALID_INPUT",
@@ -1168,7 +1425,40 @@ function normalizeError(err) {
       supported_versions: [...err.supportedVersions],
       received_version: err.receivedVersion,
       fallback: err.fallback,
-      next_action: AgentPaymentNextAction.StopAndTellUser
+      next_action: AgentPaymentNextAction.StopAndTellUser,
+      // #3103: no tool can fix a version skew from inside the call.
+      ...nextStepWireFields(signerRefusalStep({
+        nextAction: AgentPaymentNextAction.StopAndTellUser,
+        nextTool: null,
+        nextToolOmittedReason: "update @haven_ai/signer by re-running the connector, then repeat the same call"
+      }))
+    };
+  }
+  if (err instanceof HavenBareHashRefusedError) {
+    return {
+      success: false,
+      code: err.code,
+      message: err.message,
+      next_action: err.next_action,
+      ...nextStepWireFields(err.step)
+    };
+  }
+  if (err instanceof HavenUserOpBindingRefusedError) {
+    return {
+      success: false,
+      code: err.code,
+      message: err.message,
+      next_action: err.next_action,
+      ...nextStepWireFields(err.step)
+    };
+  }
+  if (err instanceof HavenTypedDataNotAllowedError) {
+    return {
+      success: false,
+      code: err.code,
+      message: err.message,
+      next_action: err.next_action,
+      ...nextStepWireFields(err.step)
     };
   }
   if (err instanceof HavenSignContextError) {
@@ -1180,7 +1470,15 @@ function normalizeError(err) {
       ...err.fallback !== void 0 ? { fallback: err.fallback } : {},
       ...err.retry_with_new_quote ? { retry_with_new_quote: true } : {},
       ...err.http_status !== void 0 ? { http_status: err.http_status } : {},
-      ...err.backend_error_code !== void 0 ? { backend_error_code: err.backend_error_code } : {}
+      ...err.backend_error_code !== void 0 ? { backend_error_code: err.backend_error_code } : {},
+      ...err.client_update ? { client_update: err.client_update } : {},
+      // #3103: the typed step the error decided beside its action.
+      ...err.next_tool ? { next_tool: err.next_tool } : {},
+      ...err.next_tool_server ? { next_tool_server: err.next_tool_server } : {},
+      ...err.next_tool_name ? { next_tool_name: err.next_tool_name } : {},
+      ...err.next_tool_server_role ? { next_tool_server_role: err.next_tool_server_role } : {},
+      ...err.next_arguments ? { next_arguments: err.next_arguments } : {},
+      ...err.next_tool_omitted_reason ? { next_tool_omitted_reason: err.next_tool_omitted_reason } : {}
     };
   }
   if (err instanceof HavenSigningError) {
@@ -1199,7 +1497,13 @@ function normalizeError(err) {
       ...err.code === AgentPaymentFailureCode.PaymentWindowExpired ? {
         next_action: AgentPaymentNextAction.PaymentWindowExpired,
         retry_with_new_quote: true,
-        suggested_tool: "haven_pay_mcp_tool"
+        suggested_tool: "haven_pay_mcp_tool",
+        // #3103: same omission as the hosted window-expired helper.
+        ...nextStepWireFields(signerRefusalStep({
+          nextAction: AgentPaymentNextAction.PaymentWindowExpired,
+          nextTool: null,
+          nextToolOmittedReason: "re-run the hosted quote tool you called with the same idempotency_key; which one depends on the flow (suggested_tool names the MCP one)"
+        }))
       } : {}
     };
   }
@@ -1211,6 +1515,17 @@ function normalizeError(err) {
 }
 
 // src/consent.ts
+var toolSummaries = {
+  haven_sign: "signs one Haven-prepared payment (a direct-payment UserOp from your own account whose only call redeems a delegation made to it, or an x402 funding intent against a Haven-signed context)",
+  haven_x402_sign_header: "builds and signs the EIP-3009 merchant payment header for an x402 payment",
+  haven_sign_x402: "the two above in one call: funding payload + merchant header",
+  haven_sign_sweep_delegate: "signs a Haven-prepared gasless sweep of stranded funds back to your own account"
+};
+var CONNECTOR_DOCTOR_HINT = [
+  "Wired by the Haven connector (Claude Desktop, Codex, ...)? Diagnose and repair with: npx @haven_ai/connect --doctor",
+  "  (the doctor shows this as a failed 'Signer stdio handshake' check; the connector's setup outcome reports it as",
+  "  local_signer_ack_required; the repair is the connector's --ack-local-tools)."
+].join("\n");
 var SIGNER_ACK_ENV = "HAVEN_SIGNER_ACK";
 var SIGNER_CONSENT_SURFACE_VERSION = 2;
 function computeSignerConsentHash(input) {
@@ -1246,13 +1561,13 @@ function renderSignerConsentBlock(input, hash) {
   lines.push("payload from Haven, authenticated with the agent credential stored next to");
   lines.push("this signer's key file - it never sends the key, a signature, or anything");
   lines.push("else outbound, and it cannot show a live allowance summary.");
-  lines.push("On-chain Safe rules remain the real spend gate, and the wallet owner can");
-  lines.push("pause or revoke agent authority outside this signer.");
+  lines.push("The agent's signed budget delegation is the real spend gate, and the wallet");
+  lines.push("owner can pause or revoke agent authority outside this signer.");
   lines.push("");
-  lines.push("Tools this signer will expose to your agent runtime:");
+  lines.push("Tools this signer will expose to your agent runtime (one line each; the");
+  lines.push("full agent-facing descriptions are what the runtime sees):");
   for (const name of input.toolNames) {
-    lines.push(`  - ${name}`);
-    lines.push(`      ${toolDescriptions[name]}`);
+    lines.push(`  - ${name}: ${toolSummaries[name]}`);
   }
   lines.push("");
   lines.push("A local audit entry is appended for every signing operation. Audit entries");
@@ -1266,6 +1581,8 @@ function renderSignerConsentBlock(input, hash) {
   lines.push("  - re-run with --ack to write the acknowledgement next to your");
   lines.push("    credential file (sidecar <credentials>.signer-ack.json).");
   lines.push("");
+  lines.push(CONNECTOR_DOCTOR_HINT);
+  lines.push("");
   lines.push("------------------------------------------------------------");
   lines.push("");
   return lines.join("\n");
@@ -1329,7 +1646,7 @@ async function writeAckFile(path, hash) {
   );
 }
 var SIGNER_NAME = "@haven_ai/signer";
-var SIGNER_VERSION = "0.3.0-alpha.0";
+var SIGNER_VERSION = "0.5.0-alpha.1";
 async function resolveEdgeSigner(options = {}) {
   const { signer } = await resolveSignerRuntime(options);
   return signer;
@@ -1371,13 +1688,17 @@ function buildSignerMcpServer(signer, options = {}) {
       accountAddress: options.credentials?.accountAddress,
       chainId: options.credentials?.chainId
     },
-    // #1263: the payment_id signing path — the ONLY network call this server
-    // can make, an authenticated read of a signing context from Haven, using
+    // #1263: the payment_id signing path — the ONLY network path this server
+    // has: up to two authenticated reads of a signing context from Haven (x402,
+    // then direct for haven_sign, #3271), using
     // the agent identity the connector stores next to the signer credential.
     // The signer CORE stays network-free; fetched bytes still pass the same
     // binding verification + digest re-derivation as tool-argument bytes.
     signContext: {
-      loadIdentity: () => loadHavenIdentity(credentialsPath)
+      loadIdentity: () => loadHavenIdentity(credentialsPath),
+      // #3303: the backend refuses a signer below a minimum it has set, at
+      // sign-context — the one place this signer meets it.
+      clientIdentity: havenClientIdentity(SIGNER_NAME, SIGNER_VERSION)
     }
   });
   const registerTool = server.tool.bind(server);
@@ -1405,7 +1726,7 @@ async function runSignerStdioServer(options = {}) {
     const decision = await runSignerConsentGate(signer, credentials, options);
     if (!decision.ok) {
       const err = new Error(
-        decision.reason === "env_var_mismatch" ? "Haven edge signer consent acknowledgement does not match the current configuration." : "Haven edge signer requires a one-time consent acknowledgement before starting."
+        (decision.reason === "env_var_mismatch" ? "Haven edge signer consent acknowledgement does not match the current configuration." : "Haven edge signer requires a one-time consent acknowledgement before starting.") + " See the consent block above; if the Haven connector wired this signer, run: npx @haven_ai/connect --doctor"
       );
       err.code = "HAVEN_SIGNER_NO_CONSENT";
       throw err;
@@ -1439,6 +1760,6 @@ function toMcpResult(payload) {
   };
 }
 
-export { SIGNER_ACK_ENV, SIGNER_CAPABILITY_KEY, SIGNER_NAME, SIGNER_VERSION, SUPPORTED_SWEEP_BINDING_VERSIONS, SUPPORTED_X402_EXPECTED_VERSIONS, appendSigningAuditEntry, assertSupportedBindingVersion, assertSupportedNodeVersion, assertX402MatchesExpected, buildSignerMcpServer, computeSignerConsentHash, createEdgeSigner, createSigningAuditEntry, createToolHandlers, defaultSigningAuditPath, ensureSignerConsent, hashPayloadForAudit, loadSignerCredentials, readAccountAddressEnv, readAccountAddressField, renderSignerConsentBlock, resolveEdgeSigner, resolveSignerRuntime, runSignerConsentGate, runSignerStdioServer, signerCapabilityAdvertisement, signerCompatibility, signerInstructions, toolDescriptions, toolSchemas, warnIfCredentialFilePermissive };
+export { AUDIT_ROTATE_BYTES, OWNER_ONLY_MODE, SIGNER_ACK_ENV, SIGNER_CAPABILITY_KEY, SIGNER_HOSTED_HANDOFF_SHAPES, SIGNER_NAME, SIGNER_VERSION, SUPPORTED_SWEEP_BINDING_VERSIONS, SUPPORTED_X402_EXPECTED_VERSIONS, appendSigningAuditEntry, assertSupportedBindingVersion, assertSupportedNodeVersion, assertX402MatchesExpected, buildSignerMcpServer, computeSignerConsentHash, createEdgeSigner, createSigningAuditEntry, createToolHandlers, defaultSigningAuditPath, ensureSignerConsent, hashPayloadForAudit, loadSignerCredentials, permissiveMode, readAccountAddressEnv, readAccountAddressField, renderSignerConsentBlock, resolveEdgeSigner, resolveSignerRuntime, runSignerConsentGate, runSignerStdioServer, signerCapabilityAdvertisement, signerCompatibility, signerInstructions, tightenIfFilePermissive, toolDescriptions, toolSchemas, warnIfCredentialFilePermissive, warnIfFilePermissive };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map