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

package/dist/cli.cjs

@@ -1,26 +1,141 @@
 #!/usr/bin/env node
 'use strict';
 
-var mcp_js = require('@modelcontextprotocol/sdk/server/mcp.js');
-var stdio_js = require('@modelcontextprotocol/sdk/server/stdio.js');
 var crypto = require('crypto');
 var promises = require('fs/promises');
-var os = require('os');
 var path = require('path');
-var sdk = require('@haven_ai/sdk');
+var edge = require('@haven_ai/sdk/edge');
 var viem = require('viem');
-var accounts = require('viem/accounts');
-var schemes = require('x402/schemes');
 var v3 = require('zod/v3');
+var zod = require('zod');
+var os = require('os');
+var mcp_js = require('@modelcontextprotocol/sdk/server/mcp.js');
+var stdio_js = require('@modelcontextprotocol/sdk/server/stdio.js');
+var accounts = require('viem/accounts');
+
+var SIGNER_HOSTED_HANDOFF_SHAPES = {
+  haven_get_payment_status: { payment_id: zod.z.string().min(1) }
+};
+function target(shape) {
+  const schema = zod.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 = edge.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/bare-hash.ts
+var BARE_HASH_REFUSED = "BARE_HASH_REFUSED";
+var HavenBareHashRefusedError = class extends edge.HavenSigningError {
+  next_action = edge.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: edge.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"
+    });
+  }
+};
+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 promises.stat(path) : await promises.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 promises.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 promises.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/audit.ts
+var AUDIT_ROTATE_BYTES = 8 * 1024 * 1024;
 function defaultSigningAuditPath(credentialsPath) {
   if (credentialsPath) return path.resolve(`${credentialsPath}.signer-audit.jsonl`);
   return path.resolve(os.homedir(), ".haven", "signer-audit.jsonl");
 }
-async function appendSigningAuditEntry(entry, path$1) {
+async function appendSigningAuditEntry(entry, path$1, options = {}) {
   await promises.mkdir(path.dirname(path$1), { recursive: true });
+  const rotateAt = options.rotateAtBytes ?? AUDIT_ROTATE_BYTES;
+  const existing = await promises.lstat(path$1).catch(() => null);
+  if (existing) {
+    await tightenIfFilePermissive("audit sidecar", path$1, options.log, options.platform, existing);
+    if (existing.size >= rotateAt) {
+      await promises.rename(path$1, `${path$1}.1`).catch(() => {
+      });
+    }
+  }
   await promises.appendFile(path$1, `${JSON.stringify(entry)}
-`, "utf8");
+`, { encoding: "utf8", mode: OWNER_ONLY_MODE });
 }
 function createSigningAuditEntry(tool, payloadHash, context, now = /* @__PURE__ */ new Date()) {
   const entry = {
@@ -46,1181 +161,1452 @@ function stableStringify(value) {
   const object = value;
   return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(object[key])}`).join(",")}}`;
 }
-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);
+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 edge.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 = edge.AgentPaymentNextAction.StopAndTellUser;
+        step = signerRefusalStep({
+          nextAction: edge.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 = edge.AgentPaymentNextAction.StopAndTellUser;
+        step = signerRefusalStep({
+          nextAction: edge.AgentPaymentNextAction.StopAndTellUser,
+          nextTool: null,
+          nextToolOmittedReason: DIRECT_RELAY_FALLBACK
+        });
+      } else if (flow === "direct" && refusal?.errorCode === "expired") {
+        this.next_action = edge.AgentPaymentNextAction.PaymentWindowExpired;
+        step = signerRefusalStep({
+          nextAction: edge.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 = edge.AgentPaymentNextAction.PaymentWindowExpired;
+        this.retry_with_new_quote = true;
+        step = signerRefusalStep({
+          nextAction: edge.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 = edge.AgentPaymentNextAction.StopAndTellUser;
+        step = signerRefusalStep({
+          nextAction: edge.AgentPaymentNextAction.StopAndTellUser,
+          nextTool: "haven_get_payment_status",
+          nextArguments: { payment_id: paymentId }
+        });
+      }
+    } else {
+      this.fallback = "typed_data_b64";
+      this.next_action = edge.AgentPaymentNextAction.StopAndTellUser;
+      step = signerRefusalStep({
+        nextAction: edge.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 promises.readFile(path.join(path.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;
+  }
 }
-function findCaveat(caveats, enforcer) {
-  return caveats.find((c) => same(c.enforcer, enforcer));
+var SIGN_CONTEXT_TIMEOUT_MS = 15e3;
+function signContextHeaders(identity, clientIdentity) {
+  return {
+    Authorization: `Bearer ${identity.apiKey}`,
+    ...clientIdentity ? { [edge.HAVEN_CLIENT_HEADER]: clientIdentity } : {}
+  };
 }
-function refuse(what, detail) {
-  throw new sdk.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 refusalOf(status, body) {
+  return {
+    httpStatus: status,
+    errorCode: typeof body.error_code === "string" ? body.error_code : void 0,
+    clientUpdate: edge.readClientUpdate(body.client_update)
+  };
 }
-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}.`
+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)
+      }
     );
-  }
-  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}.`
+  } 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
     );
   }
-  const caveats = typedData.message?.caveats ?? [];
-  if (caveats.length === 0) {
-    refuse("it carries no caveats at all", "An unconstrained delegation is not a payment.");
+  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 = {};
   }
-  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."
+  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 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 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 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 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: edge.readClientUpdate(body.client_update)
+  };
+}
+var SUPPORTED_DIRECT_SIGN_CONTEXT_VERSIONS = [edge.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)
+      }
     );
-  }
-  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()}.`
+  } 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"
     );
   }
-  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.");
+  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 = {};
   }
-  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}.`
+  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 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.`
+  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"
     );
   }
-  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}.`
-      );
-    }
-  }
+  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: edge.readClientUpdate(body.client_update)
+  };
 }
-function createEdgeSigner(delegateKey, options = {}) {
-  let delegateAddress;
-  try {
-    delegateAddress = sdk.addressFromKey(delegateKey);
-  } catch (err) {
-    throw new sdk.HavenSigningError(
-      `Invalid delegate key: ${err instanceof Error ? err.message : String(err)}`
-    );
+
+// src/tools.ts
+var USEROP_BINDING_MISMATCH = "USEROP_BINDING_MISMATCH";
+var HavenUserOpBindingRefusedError = class extends edge.HavenSigningError {
+  next_action = edge.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: edge.AgentPaymentNextAction.StopAndTellUser,
+      nextTool: null,
+      nextToolOmittedReason: "call haven_sign again with payment_id alone (preferred), or with typed_data copied unchanged from the payment result"
+    });
   }
-  const x402Bindings = /* @__PURE__ */ new Map();
-  const retiredX402Bindings = /* @__PURE__ */ new Map();
-  const RETIRED_BINDING_MEMORY = 64;
-  function retireX402Binding(id, reason) {
-    retiredX402Bindings.set(id, reason);
-    if (retiredX402Bindings.size > RETIRED_BINDING_MEMORY) {
-      const oldest = retiredX402Bindings.keys().next();
-      if (!oldest.done) retiredX402Bindings.delete(oldest.value);
-    }
+};
+var HavenTypedDataNotAllowedError = class extends edge.HavenTypedDataRefusedError {
+  next_action = edge.AgentPaymentNextAction.StopAndTellUser;
+  step;
+  constructor(message) {
+    super(message);
+    this.name = "HavenTypedDataNotAllowedError";
+    this.step = signerRefusalStep({
+      nextAction: edge.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"
+    });
   }
-  function signAndVerify(hash) {
-    const signature = sdk.signHash(delegateKey, hash);
-    if (!sdk.verifySignature(hash, signature, delegateAddress)) {
-      throw new sdk.HavenSigningError(
-        "Local signature verification failed \u2014 recovered address does not match the delegate key."
-      );
+};
+function assertBoundDirectPaymentUserOp(typedData, delegateAddress) {
+  try {
+    edge.assertBoundDirectPaymentUserOp(typedData, delegateAddress);
+  } catch (err) {
+    if (err instanceof edge.HavenTypedDataRefusedError && !(err instanceof HavenTypedDataNotAllowedError)) {
+      throw new HavenTypedDataNotAllowedError(err.message);
     }
-    return signature;
+    throw err;
   }
-  return {
-    delegateAddress,
-    signPaymentHash(hash) {
-      return signAndVerify(hash);
-    },
-    async signDelegationTypedData(typedData) {
-      const account = accounts.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 = crypto.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 = viem.hashTypedData(typedData);
-      if (digest.toLowerCase() !== expected.typedDataHash?.toLowerCase()) {
-        throw new sdk.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."
-        );
-      }
-      if (isSettlementChildTypedData(typedData)) {
-        const settlementChainId = chainIdForNetwork(expected.network);
-        if (settlementChainId === void 0) {
-          throw new sdk.HavenSigningError(
-            `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, {
-          merchantTo: expected.merchantTo,
-          amount: expected.amount,
-          asset: expected.asset,
-          // From the SIGNED network, not the payload's own claim. Passing
-          // Number(typedData.domain.chainId) here made the check compare a
-          // value to itself — vacuous, and precisely the "declared one thing,
-          // signed another" class this file exists to catch (#1455 review).
-          chainId: settlementChainId,
-          expiresAt: expected.expiresAt
-        });
-      }
-      const account = accounts.privateKeyToAccount(delegateKey);
-      const signature = await account.signTypedData(
-        typedData
-      );
-      const x402Binding = crypto.randomUUID();
-      x402Bindings.set(x402Binding, { ...expected });
-      return { signature, x402Binding };
-    },
-    async buildX402PaymentHeader(paymentRequired, x402Binding) {
-      const expected = x402Bindings.get(x402Binding);
-      if (!expected) {
-        const retired = retiredX402Bindings.get(x402Binding);
-        if (retired === "header_built") {
-          throw new sdk.HavenSigningError(
-            "This x402 binding was already used to build a merchant header. Bindings are single-use. If you called haven_sign_x402, it already returned the payment_header \u2014 retry the merchant with THAT header instead of building another; haven_x402_sign_header is the follow-up to haven_sign, not to haven_sign_x402. If you no longer have the header, re-run the quote tool with the same idempotency_key."
-          );
-        }
-        if (retired === "window_expired") {
-          throw new sdk.HavenSigningError(
-            "This x402 binding was retired because its payment window closed before a merchant header could be built \u2014 no header exists to retry with. Re-run the quote tool with the same idempotency_key to get a fresh window, then sign again."
+}
+var sweepAuthorizationSchema = v3.z.object({
+  from: v3.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "from must be a 0x address"),
+  to: v3.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "to must be a 0x address"),
+  value: v3.z.string().regex(/^[0-9]+$/, "value must be a decimal atomic amount"),
+  validAfter: v3.z.string().regex(/^[0-9]+$/, "validAfter must be a decimal unix time"),
+  validBefore: v3.z.string().regex(/^[0-9]+$/, "validBefore must be a decimal unix time"),
+  nonce: v3.z.string().regex(/^0x[0-9a-fA-F]{64}$/, "nonce must be a 0x-prefixed 32-byte hex string"),
+  token: v3.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "token must be a 0x address"),
+  chainId: v3.z.number().int().positive()
+});
+var bindingVersionSchema = v3.z.number().int().positive();
+var sweepExpectedAuthSchema = v3.z.object({
+  version: bindingVersionSchema,
+  message: v3.z.string().min(1),
+  signature: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "signature must be a 0x-prefixed hex string"),
+  signer: v3.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "signer must be a 0x address")
+});
+var x402ExpectedShape = {
+  payment_id: v3.z.string().min(1),
+  payload_hash: v3.z.string().regex(/^0x[0-9a-fA-F]{64}$/, "payload_hash must be a 0x-prefixed 32-byte hex string"),
+  resource_url: v3.z.string().url(),
+  merchant_to: v3.z.string().min(1),
+  amount: v3.z.string().min(1),
+  asset: v3.z.string().min(1),
+  network: v3.z.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: v3.z.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: v3.z.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: v3.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "payer_delegate must be a 0x-prefixed address").optional(),
+  payer_agent_id: v3.z.string().min(1).optional(),
+  auth: v3.z.object({
+    // Open at the boundary, enforced in the signer — see bindingVersionSchema.
+    version: bindingVersionSchema,
+    message: v3.z.string().min(1),
+    signature: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "signature must be a 0x-prefixed hex string"),
+    signer: v3.z.string().min(1)
+  })
+};
+var x402ExpectedSchema = v3.z.object(x402ExpectedShape);
+var toolSchemas = {
+  haven_sign_sweep_delegate: {
+    // The authorization fields prepared by Haven's POST /sweep/prepare. Passed
+    // through verbatim from the hosted haven_sweep_delegate tool — the signer
+    // re-derives the binding message from these exact values.
+    authorization: sweepAuthorizationSchema,
+    // Haven's signature over the authorization context (the binding).
+    expected_auth: sweepExpectedAuthSchema
+  },
+  haven_sign: {
+    // #1263: THE preferred x402 input — the signer fetches the exact signing
+    // 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: v3.z.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: v3.z.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: v3.z.record(v3.z.string(), v3.z.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
+    // failure mode this field removes (a truncated/reshaped payload fails the
+    // digest check and the payment refuses, correctly but pointlessly).
+    // 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: v3.z.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: v3.z.record(v3.z.string(), v3.z.unknown()),
+    // Opaque binding returned by haven_sign when x402_expected was supplied.
+    x402_binding: v3.z.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: v3.z.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: v3.z.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: v3.z.record(v3.z.string(), v3.z.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: v3.z.record(v3.z.string(), v3.z.unknown()).optional(),
+    // #1255: see haven_sign.typed_data_b64 — the copy-through-safe form.
+    typed_data_b64: v3.z.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 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. 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. 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.",
+  "The delegate key stays local \u2014 only the signed header crosses any boundary.",
+  "Pass the payment_required from the original merchant 402 response and the x402_binding",
+  "returned by haven_sign. It must be haven_sign \u2014 NOT haven_sign_x402, which is a",
+  "one-shot that builds the header itself and spends its own binding doing so. If you called",
+  "haven_sign_x402, its result already carries payment_header; retry the merchant with that and",
+  "do not call this tool. The signer validates the merchant, amount, resource, asset, and",
+  "network against the recorded funding context before signing, checks expires_at when present,",
+  "and rejects mismatches or expired payment windows.",
+  "Returns { payment_header, accepted }. On your retry set BOTH PAYMENT-SIGNATURE (x402 v2) and",
+  "X-PAYMENT (v1) to <payment_header>; a strict v2 merchant reads only the first.",
+  "Only call after haven_submit has confirmed the funding step (nextAction=none or",
+  "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 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",
+  "payload, expected context, and merchant payment_required from Haven itself, so nothing bulky",
+  "crosses your context. If the signer reports the context carried no payment_required (older",
+  "backend), re-call with payment_id plus payment_required verbatim from the pay result.",
+  "Fallback for older backends: pass payload_hash, x402_expected (the nested x402.expected object \u2014",
+  "passing the whole x402 object is also accepted and unwrapped for you), and typed_data_b64",
+  "through UNCHANGED; the signer",
+  "signs the typed data instead of payload_hash and refuses the bare hash when the context commits to typed data.",
+  "Returns",
+  "{ signature, x402_binding, payment_header, accepted }; hand signature + payment_header to",
+  "mcp__haven__haven_settle_mcp_tool to fund and settle in one hosted call. The header is built now (before",
+  "funding confirms), so its short validity window starts here \u2014 call mcp__haven__haven_settle_mcp_tool promptly,",
+  "and re-run mcp__haven__haven_pay_mcp_tool with the same idempotency_key if a tool returns PAYMENT_WINDOW_EXPIRED.",
+  "The returned x402_binding is ALREADY SPENT \u2014 this tool consumed it building payment_header \u2014",
+  "so never pass it to mcp__haven-signer__haven_x402_sign_header; that tool is the follow-up to",
+  "haven_sign, not to this one. payment_header IS the header to use.",
+  "Next: for a paid MCP tool, call mcp__haven__haven_settle_mcp_tool. For a direct plain-HTTP x402",
+  "merchant (the haven_pay_x402_quote path), relay signature via mcp__haven__haven_submit and then",
+  "retry the original merchant URL YOURSELF, setting BOTH PAYMENT-SIGNATURE (x402 v2) and",
+  "X-PAYMENT (v1) to payment_header \u2014 Haven never contacts that merchant."
+].join(" ");
+var SIGN_SWEEP_DELEGATE_DESCRIPTION = [
+  "Sign a Haven-prepared gasless USDC sweep that recovers stranded funds from the delegate",
+  "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; 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,
+  haven_x402_sign_header: X402_SIGN_HEADER_DESCRIPTION,
+  haven_sign_x402: SIGN_X402_DESCRIPTION,
+  haven_sign_sweep_delegate: SIGN_SWEEP_DELEGATE_DESCRIPTION
+};
+async function signFundingLeg(signer, expected, typedData) {
+  try {
+    return await signer.signX402FundingTypedData(typedData, expected);
+  } catch (err) {
+    if (err instanceof edge.HavenTypedDataRefusedError && !(err instanceof HavenTypedDataNotAllowedError)) {
+      throw new HavenTypedDataNotAllowedError(err.message);
+    }
+    if (err instanceof edge.HavenUserOpBindingError) {
+      throw new HavenUserOpBindingRefusedError(err.message);
+    }
+    throw err;
+  }
+}
+function toExpectedX402(raw) {
+  return {
+    paymentId: raw.payment_id,
+    payloadHash: raw.payload_hash,
+    typedDataHash: raw.typed_data_hash,
+    payerDelegate: raw.payer_delegate,
+    payerAgentId: raw.payer_agent_id,
+    resourceUrl: raw.resource_url,
+    merchantTo: raw.merchant_to,
+    amount: raw.amount,
+    asset: raw.asset,
+    network: raw.network,
+    expiresAt: raw.expires_at,
+    auth: raw.auth
+  };
+}
+function parseFetchedExpected(fetched) {
+  const parsed = v3.z.object(x402ExpectedShape).safeParse(fetched.x402Expected);
+  if (!parsed.success) {
+    throw new edge.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"}`
+    );
+  }
+  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 {
+    const decoded = JSON.parse(
+      Buffer.from(args.typed_data_b64, "base64").toString("utf8")
+    );
+    if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) {
+      throw new Error("decoded value is not an object");
+    }
+    return decoded;
+  } catch (err) {
+    throw new edge.HavenSigningError(
+      `typed_data_b64 did not decode to a JSON object. Pass the exact string returned by the hosted Haven tool, unchanged \u2014 do not re-encode, trim, or reformat it. Underlying error: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function createToolHandlers(signer, options = {}) {
+  function checkPayloadHashMatch(suppliedHash, fetchedHash, paymentId) {
+    if (suppliedHash && suppliedHash.toLowerCase() !== fetchedHash.toLowerCase()) {
+      throw new edge.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) {
+      throw new edge.HavenSigningError(
+        `payment_id signing needs the agent identity (identity.json next to the signer credentials), which this signer could not load. Re-run \`${edge.connectorRerunCommand()}\` to restore it, or pass typed_data_b64 from the quote result instead.`
+      );
+    }
+    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;
         }
-        throw new sdk.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."
-        );
-      }
-      try {
-        assertX402PaymentWindowOpen(expected);
-      } catch (err) {
-        x402Bindings.delete(x402Binding);
-        retireX402Binding(x402Binding, "window_expired");
-        throw err;
+        checkPayloadHashMatch(args.payload_hash, ctx.payloadHash, args.payment_id);
+        return { kind: "direct", ctx };
       }
-      const option = sdk.selectStandardPaymentOption(paymentRequired.accepts);
-      if (!option) {
-        throw new sdk.HavenApiError(
-          "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC.",
-          400
+      throw err;
+    }
+  }
+  return {
+    haven_sign: async (input) => runTool(async () => {
+      const args = parse("haven_sign", coerceX402Expected(input));
+      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 edge.HavenSigningError(
+          "Pass payment_id (preferred for delegation-rail x402 or direct payments) or payload_hash."
         );
       }
-      assertX402MatchesExpected(paymentRequired, option, expected);
-      const account = accounts.privateKeyToAccount(delegateKey);
-      const requirements = sdk.toStandardPaymentRequirements(paymentRequired, option);
-      const header = await schemes.exact.evm.createPaymentHeader(
-        account,
-        paymentRequired.x402Version,
-        requirements
-      );
-      if (paymentRequired.x402Version < 2) {
-        x402Bindings.delete(x402Binding);
-        retireX402Binding(x402Binding, "header_built");
-        return { paymentHeader: header, accepted: option };
-      }
-      try {
-        const payment = sdk.decodeBase64Json(header);
-        const wrapped = sdk.encodeBase64Json(
-          sdk.x402V2PaymentEnvelope(paymentRequired, option, payment.payload)
-        );
-        return { paymentHeader: wrapped, accepted: option };
-      } finally {
-        x402Bindings.delete(x402Binding);
-        retireX402Binding(x402Binding, "header_built");
+      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, typedData) : null;
+      if (!result) {
+        if (typedData) {
+          if (edge.isSettlementChildTypedData(typedData)) {
+            throw new edge.HavenSigningError(
+              "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."
+            );
+          }
+          if (resolved?.kind !== "direct" && !edge.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 {
+            edge.assertUserOpTypedDataBinding(typedData, payloadHash);
+          } catch (err) {
+            if (err instanceof edge.HavenUserOpBindingError) {
+              throw new HavenUserOpBindingRefusedError(err.message);
+            }
+            throw err;
+          }
+          assertBoundDirectPaymentUserOp(typedData, signer.delegateAddress);
+          const signature = await signer.signDelegationTypedData(typedData);
+          await auditSigning("haven_sign", viem.hashTypedData(typedData));
+          return { signature, ...clientUpdateField(resolved) };
+        }
+        throw new HavenBareHashRefusedError();
       }
-    },
-    async signSweepAuthorization({
-      authorization,
-      expectedAuth,
-      expectedSafe
-    }) {
-      assertSweepBinding(authorization, expectedAuth, options.x402BindingSigner);
-      if (!sameAddress(authorization.from, delegateAddress)) {
-        throw new sdk.HavenSigningError(
-          "Sweep authorization `from` does not match this delegate address."
+      await auditSigning("haven_sign", viem.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));
+      const result = await signer.buildX402PaymentHeader(
+        args.payment_required,
+        args.x402_binding
+      );
+      await auditSigning(
+        "haven_x402_sign_header",
+        hashPayloadForAudit(args.payment_required)
+      );
+      return { payment_header: result.paymentHeader, accepted: result.accepted };
+    }),
+    haven_sign_x402: async (input) => runTool(async () => {
+      const args = parse("haven_sign_x402", coerceX402Expected(coercePaymentRequired(input)));
+      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) {
+        throw new edge.HavenSigningError(
+          "Pass payment_id (preferred \u2014 the signer fetches the signing context itself) or payload_hash + x402_expected from the quote result."
         );
       }
-      if (expectedSafe && !sameAddress(authorization.to, expectedSafe)) {
-        throw new sdk.HavenSigningError(
-          "Sweep authorization `to` does not match the Safe in the local credential."
+      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 edge.HavenSigningError(
+          fetched ? "The Haven sign-context for this payment_id carried no payment_required (backend predates #1355). Pass payment_required from the pay result explicitly, verbatim." : "payment_required is required on the quote-based path (no payment_id to fetch it by). Pass it verbatim from the quote result."
         );
       }
-      const typedData = sdk.buildSweepTypedData(authorization);
-      const viemTypedData = {
-        domain: {
-          ...typedData.domain,
-          verifyingContract: typedData.domain.verifyingContract
-        },
-        types: typedData.types,
-        primaryType: typedData.primaryType,
-        message: {
-          ...typedData.message,
-          from: typedData.message.from,
-          to: typedData.message.to,
-          nonce: typedData.message.nonce
-        }
+      const header = await signer.buildX402PaymentHeader(
+        paymentRequired,
+        funding.x402Binding
+      );
+      await auditSigning(
+        "haven_sign_x402",
+        viem.hashTypedData(fundingTypedData)
+      );
+      await auditSigning("haven_sign_x402", hashPayloadForAudit(paymentRequired));
+      return {
+        signature: funding.signature,
+        x402_binding: funding.x402Binding,
+        payment_header: header.paymentHeader,
+        accepted: header.accepted,
+        ...clientUpdateField(resolved)
       };
-      const account = accounts.privateKeyToAccount(delegateKey);
-      const signature = await account.signTypedData(viemTypedData);
-      const recovered = await viem.recoverTypedDataAddress({ ...viemTypedData, signature });
-      if (!sameAddress(recovered, delegateAddress)) {
-        throw new sdk.HavenSigningError(
-          "Local sweep signature verification failed \u2014 recovered address does not match the delegate key."
-        );
-      }
-      return { signature };
-    }
+    }),
+    haven_sign_sweep_delegate: async (input) => runTool(async () => {
+      const args = parse("haven_sign_sweep_delegate", input);
+      const result = await signer.signSweepAuthorization({
+        authorization: args.authorization,
+        expectedAuth: args.expected_auth,
+        // 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(
+        "haven_sign_sweep_delegate",
+        hashPayloadForAudit(args.authorization)
+      );
+      return { signature: result.signature };
+    })
   };
-}
-function assertSweepBinding(authorization, expectedAuth, trustedSigner) {
-  if (!expectedAuth || typeof expectedAuth !== "object") {
-    throw new sdk.HavenSigningError("Sweep authorization binding is required before signing.");
-  }
-  if (!trustedSigner) {
-    throw new sdk.HavenSigningError(
-      "Sweep binding verifier is not configured. Set HAVEN_X402_BINDING_SIGNER before signing sweep authorizations."
-    );
-  }
-  assertSupportedBindingVersion(
-    expectedAuth.version,
-    SUPPORTED_SWEEP_BINDING_VERSIONS,
-    "sweep authorization binding"
-  );
-  const message = sdk.buildSweepAuthorizationMessage(authorization);
-  if (expectedAuth.message !== message) {
-    throw new sdk.HavenSigningError("Sweep authorization binding does not match the authorization being signed.");
-  }
-  if (!sameAddress(expectedAuth.signer, trustedSigner)) {
-    throw new sdk.HavenSigningError("Sweep authorization binding was not signed by the configured Haven signer.");
-  }
-  if (!sdk.verifySignature(viem.hashMessage(message), expectedAuth.signature, trustedSigner)) {
-    throw new sdk.HavenSigningError("Sweep authorization binding signature could not be verified.");
+  async function auditSigning(tool, payloadHash) {
+    if (!options.audit) return;
+    const { auditPath, ...context } = options.audit;
+    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 assertX402MatchesExpected(paymentRequired, option, expected) {
-  assertExpectedShape(expected);
-  const headerResource = option.resource ?? paymentRequired.resource.url;
-  if (headerResource !== expected.resourceUrl) {
-    throw new sdk.HavenSigningError("x402 payment_required resource does not match the funded intent.");
-  }
-  if (!sameAddress(option.payTo, expected.merchantTo)) {
-    throw new sdk.HavenSigningError("x402 merchant recipient does not match the funded intent.");
-  }
-  if (sdk.x402AuthorizationAmount(option) !== expected.amount) {
-    throw new sdk.HavenSigningError("x402 amount does not match the funded intent.");
-  }
-  if (!sameAddress(option.asset, expected.asset)) {
-    throw new sdk.HavenSigningError("x402 asset does not match the funded intent.");
+function parse(name, input) {
+  return v3.z.object(toolSchemas[name]).parse(input ?? {});
+}
+function coerceX402Expected(input) {
+  if (!input || typeof input !== "object") return input;
+  const record = input;
+  let value = record.x402_expected;
+  if (typeof value === "string") {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return input;
+    }
   }
-  if (option.network !== expected.network) {
-    throw new sdk.HavenSigningError("x402 network does not match the funded intent.");
+  if (!value || typeof value !== "object") return input;
+  const obj = value;
+  if (obj.auth === void 0 && obj.expected && typeof obj.expected === "object") {
+    return { ...record, x402_expected: obj.expected };
   }
+  if (value !== record.x402_expected) return { ...record, x402_expected: value };
+  return input;
 }
-function assertExpectedShape(expected) {
-  if (!expected || typeof expected !== "object") {
-    throw new sdk.HavenSigningError("x402 expected funding context is required before signing a merchant header.");
+function coercePaymentRequired(input) {
+  if (!input || typeof input !== "object") return input;
+  const record = input;
+  if (typeof record.payment_required !== "string") return input;
+  try {
+    return { ...record, payment_required: JSON.parse(record.payment_required) };
+  } catch {
+    return input;
   }
 }
-var SUPPORTED_X402_EXPECTED_VERSIONS = [1, 2, 3];
-var SUPPORTED_SWEEP_BINDING_VERSIONS = [1];
-function assertSupportedBindingVersion(received, supported, context) {
-  if (supported.includes(received)) return;
-  const highest = Math.max(...supported);
-  const outOfDate = received > highest;
-  const code = context === "x402 expected context" ? sdk.SignerRefusalCode.UnsupportedExpectedContextVersion : sdk.SignerRefusalCode.UnsupportedSweepBindingVersion;
-  const ceiling = outOfDate ? `This signer is out of date: it supports ${context} versions up to ${highest}, and Haven sent version ${received}. Update @haven_ai/signer \u2014 rerun the Haven connector (\`${sdk.connectorRerunCommand()}\`), which reinstalls the pinned MCP runtime.` : `Unsupported ${context} version ${received}: this signer supports ${supported.join(", ")}.`;
-  const fallback = outOfDate ? sdk.SIGNER_UPDATE_FALLBACK : `This ${context} version (${received}) is older than what this signer enforces (${supported.join(", ")}) \u2014 updating @haven_ai/signer will not restore it. Nothing was signed or spent; stop and tell the user rather than retrying.`;
-  throw new sdk.HavenUnsupportedSignerVersionError(
-    `${ceiling} Nothing was signed. Do not rewrite the version field to a supported value: it is part of the Haven-signed binding message, so changing it invalidates the signature and would misrepresent what Haven declared.`,
-    code,
-    supported,
-    received,
-    fallback
-  );
-}
-function assertExpectedBinding(payloadHash, expected, trustedSigner, mode = "hash") {
-  assertExpectedShape(expected);
-  if (!trustedSigner) {
-    throw new sdk.HavenSigningError(
-      "x402 expected-context verifier is not configured. Set HAVEN_X402_BINDING_SIGNER before signing x402 funding hashes."
-    );
+async function runTool(fn) {
+  try {
+    return { success: true, data: await fn() };
+  } catch (err) {
+    return normalizeError(err);
   }
-  if (expected.auth) {
-    assertSupportedBindingVersion(
-      expected.auth.version,
-      SUPPORTED_X402_EXPECTED_VERSIONS,
-      "x402 expected context"
-    );
+}
+function normalizeError(err) {
+  if (err instanceof v3.z.ZodError) {
+    return {
+      success: false,
+      code: "INVALID_INPUT",
+      message: err.errors.map((e) => `${e.path.join(".") || "(root)"}: ${e.message}`).join("; "),
+      statusCode: 400
+    };
   }
-  if (expected.payloadHash.toLowerCase() !== payloadHash.toLowerCase()) {
-    throw new sdk.HavenSigningError("x402 expected context does not match the funding hash being signed.");
+  if (err instanceof edge.HavenUnsupportedSignerVersionError) {
+    return {
+      success: false,
+      code: err.code,
+      message: err.message,
+      supported_versions: [...err.supportedVersions],
+      received_version: err.receivedVersion,
+      fallback: err.fallback,
+      next_action: edge.AgentPaymentNextAction.StopAndTellUser,
+      // #3103: no tool can fix a version skew from inside the call.
+      ...nextStepWireFields(signerRefusalStep({
+        nextAction: edge.AgentPaymentNextAction.StopAndTellUser,
+        nextTool: null,
+        nextToolOmittedReason: "update @haven_ai/signer by re-running the connector, then repeat the same call"
+      }))
+    };
   }
-  if (mode === "hash" && expected.typedDataHash) {
-    throw new sdk.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."
-    );
+  if (err instanceof HavenBareHashRefusedError) {
+    return {
+      success: false,
+      code: err.code,
+      message: err.message,
+      next_action: err.next_action,
+      ...nextStepWireFields(err.step)
+    };
   }
-  if (mode === "typed-data" && !expected.typedDataHash) {
-    throw new sdk.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."
-    );
+  if (err instanceof HavenUserOpBindingRefusedError) {
+    return {
+      success: false,
+      code: err.code,
+      message: err.message,
+      next_action: err.next_action,
+      ...nextStepWireFields(err.step)
+    };
   }
-  const message = sdk.buildX402ExpectedMessage({
-    paymentId: expected.paymentId,
-    payloadHash: expected.payloadHash,
-    resourceUrl: expected.resourceUrl,
-    merchantTo: expected.merchantTo,
-    amount: expected.amount,
-    asset: expected.asset,
-    network: expected.network,
-    expiresAt: expected.expiresAt,
-    typedDataHash: expected.typedDataHash,
-    payerDelegate: expected.payerDelegate,
-    payerAgentId: expected.payerAgentId
-  });
-  const expectedVersion = expected.payerDelegate ? 3 : expected.typedDataHash ? 2 : 1;
-  if (expected.auth?.version !== expectedVersion || expected.auth.message !== message) {
-    throw new sdk.HavenSigningError("x402 expected context authentication message is invalid.");
+  if (err instanceof HavenTypedDataNotAllowedError) {
+    return {
+      success: false,
+      code: err.code,
+      message: err.message,
+      next_action: err.next_action,
+      ...nextStepWireFields(err.step)
+    };
   }
-  if (!sameAddress(expected.auth.signer, trustedSigner)) {
-    throw new sdk.HavenSigningError("x402 expected context was not signed by the configured Haven signer.");
+  if (err instanceof HavenSignContextError) {
+    return {
+      success: false,
+      code: err.code,
+      message: err.message,
+      next_action: err.next_action,
+      ...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.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 (!sdk.verifySignature(viem.hashMessage(message), expected.auth.signature, trustedSigner)) {
-    throw new sdk.HavenSigningError("x402 expected context signature could not be verified.");
+  if (err instanceof edge.HavenSigningError) {
+    return { success: false, code: err.code, message: err.message };
   }
-}
-function assertPayerMatchesDelegate(expected, delegateAddress, localAgentId) {
-  if (!expected.payerDelegate) return;
-  if (sameAddress(expected.payerDelegate, delegateAddress)) return;
-  const quoteAgent = expected.payerAgentId ?? "unknown";
-  const localAgent = localAgentId ?? "unknown";
-  throw new sdk.HavenSigningError(
-    `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.`
-  );
-}
-function assertX402PaymentWindowOpen(expected) {
-  if (!expected.expiresAt) return;
-  const expiresAtMs = Date.parse(expected.expiresAt);
-  if (Number.isNaN(expiresAtMs)) {
-    throw new sdk.HavenSigningError("x402 expected context expiresAt is not a valid ISO timestamp.");
+  if (err instanceof edge.HavenApiError) {
+    return { success: false, code: err.code, message: err.message, statusCode: err.statusCode };
   }
-  if (expiresAtMs <= Date.now()) {
-    throw new sdk.HavenError(
-      "The x402 payment window expired before the merchant header could be signed. Re-quote with haven_pay_mcp_tool using the same idempotency_key before trying again.",
-      sdk.AgentPaymentFailureCode.PaymentWindowExpired,
-      410,
-      expected.paymentId
-    );
+  if (err instanceof edge.HavenError) {
+    return {
+      success: false,
+      code: err.code,
+      message: err.message,
+      statusCode: err.statusCode,
+      paymentId: err.paymentId,
+      ...err.code === edge.AgentPaymentFailureCode.PaymentWindowExpired ? {
+        next_action: edge.AgentPaymentNextAction.PaymentWindowExpired,
+        retry_with_new_quote: true,
+        suggested_tool: "haven_pay_mcp_tool",
+        // #3103: same omission as the hosted window-expired helper.
+        ...nextStepWireFields(signerRefusalStep({
+          nextAction: edge.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)"
+        }))
+      } : {}
+    };
   }
-}
-function sameAddress(a, b) {
-  return a.toLowerCase() === b.toLowerCase();
-}
-
-// 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]
+    success: false,
+    code: "UNKNOWN_ERROR",
+    message: err instanceof Error ? err.message : String(err)
   };
 }
-function signerCapabilityAdvertisement() {
-  return { experimental: { [SIGNER_CAPABILITY_KEY]: signerCompatibility() } };
+
+// 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) {
+  const identity = [
+    input.delegateAddress.toLowerCase(),
+    (input.accountAddress ?? "").toLowerCase(),
+    input.agentId ?? "",
+    input.chainId ?? "",
+    input.network ?? ""
+  ].join("|");
+  const toolCanonical = [...input.toolNames].sort().join(",");
+  return crypto.createHash("sha256").update(`${identity}
+${toolCanonical}
+surface:v${SIGNER_CONSENT_SURFACE_VERSION}`).digest("hex").slice(0, 16);
 }
-function signerInstructions() {
-  const compatibility = signerCompatibility();
-  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.",
-    "",
-    "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(", ")}`,
+function renderSignerConsentBlock(input, hash) {
+  const lines = [
     "",
-    "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",
-    "above, this signer is out of date: STOP before signing, and tell the user to update",
-    `@haven_ai/signer by rerunning \`${sdk.connectorRerunCommand()}\`, which reinstalls the pinned`,
-    "MCP runtime. Do not edit the version field to a supported value \u2014 it is part of the",
-    "Haven-signed binding message, so changing it invalidates the signature.",
+    "------------------------------------------------------------",
+    "Haven edge signer - first-launch consent",
+    "------------------------------------------------------------",
     "",
-    "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."
-  ].join("\n");
-}
-var HavenSignContextError = class extends sdk.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 = sdk.AgentPaymentNextAction.PaymentWindowExpired;
-        this.retry_with_new_quote = true;
-      } else {
-        this.next_action = sdk.AgentPaymentNextAction.StopAndTellUser;
-      }
-    } else {
-      this.fallback = "typed_data_b64";
-      this.next_action = sdk.AgentPaymentNextAction.StopAndTellUser;
-    }
-  }
-};
-async function loadHavenIdentity(credentialsPath) {
-  if (!credentialsPath) return null;
-  try {
-    const raw = JSON.parse(
-      await promises.readFile(path.join(path.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;
+    `Delegate address: ${input.delegateAddress}`
+  ];
+  lines.push(`Haven wallet:     ${input.accountAddress ?? "not provided to this signer"}`);
+  if (input.agentId) lines.push(`Agent ID:         ${input.agentId}`);
+  if (typeof input.chainId === "number") lines.push(`Chain ID:         ${input.chainId}`);
+  if (input.network) lines.push(`Network:          ${input.network}`);
+  lines.push("");
+  lines.push("This local signer holds the delegate key on this machine and signs");
+  lines.push("payment payloads or x402 merchant headers for the delegate address above.");
+  lines.push("Its one network use is a read-only fetch of a pending payment's signing");
+  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("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 (one line each; the");
+  lines.push("full agent-facing descriptions are what the runtime sees):");
+  for (const name of input.toolNames) {
+    lines.push(`  - ${name}: ${toolSummaries[name]}`);
   }
+  lines.push("");
+  lines.push("A local audit entry is appended for every signing operation. Audit entries");
+  lines.push("record timestamp, tool, payload hash, and delegate address; never the key,");
+  lines.push("signature, or x402 payment header.");
+  lines.push("");
+  lines.push(`Consent hash: ${hash}`);
+  lines.push("");
+  lines.push("To acknowledge, EITHER:");
+  lines.push(`  - set ${SIGNER_ACK_ENV}=${hash} in this process's environment, OR`);
+  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");
 }
-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"
-    );
-  }
-  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"
-      );
-    }
-    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",
-      { httpStatus: response.status, errorCode: typeof body.error_code === "string" ? body.error_code : void 0 }
+async function ensureSignerConsent(input, options = {}) {
+  const env = options.env ?? process.env;
+  const out = options.out ?? process.stderr;
+  const hash = computeSignerConsentHash(input);
+  const envAck = env[SIGNER_ACK_ENV];
+  if (typeof envAck === "string" && envAck.length > 0) {
+    if (envAck === hash) return { ok: true, hash, reason: "env_var_match" };
+    out.write(renderSignerConsentBlock(input, hash));
+    out.write(
+      `${SIGNER_ACK_ENV} was set but did not match the current signer consent hash.
+Expected: ${hash}
+Got:      ${envAck}
+Re-acknowledge with the new hash above, or run with --ack.
+
+`
     );
+    return { ok: false, hash, reason: "env_var_mismatch" };
   }
-  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 ackPath = sidecarPath(options.credentialsPath);
+  if (ackPath) {
+    const stored = await readAckFile(ackPath);
+    if (stored?.ack === hash) return { ok: true, hash, reason: "ack_file_match" };
   }
-  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
-  };
-}
+  if (options.writeAck && ackPath) {
+    out.write(renderSignerConsentBlock(input, hash));
+    await writeAckFile(ackPath, hash);
+    out.write(`Wrote acknowledgement to ${ackPath}
 
-// src/tools.ts
-var sweepAuthorizationSchema = v3.z.object({
-  from: v3.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "from must be a 0x address"),
-  to: v3.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "to must be a 0x address"),
-  value: v3.z.string().regex(/^[0-9]+$/, "value must be a decimal atomic amount"),
-  validAfter: v3.z.string().regex(/^[0-9]+$/, "validAfter must be a decimal unix time"),
-  validBefore: v3.z.string().regex(/^[0-9]+$/, "validBefore must be a decimal unix time"),
-  nonce: v3.z.string().regex(/^0x[0-9a-fA-F]{64}$/, "nonce must be a 0x-prefixed 32-byte hex string"),
-  token: v3.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "token must be a 0x address"),
-  chainId: v3.z.number().int().positive()
-});
-var bindingVersionSchema = v3.z.number().int().positive();
-var sweepExpectedAuthSchema = v3.z.object({
-  version: bindingVersionSchema,
-  message: v3.z.string().min(1),
-  signature: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "signature must be a 0x-prefixed hex string"),
-  signer: v3.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "signer must be a 0x address")
-});
-var x402ExpectedShape = {
-  payment_id: v3.z.string().min(1),
-  payload_hash: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "payload_hash must be a 0x-prefixed hex string"),
-  resource_url: v3.z.string().url(),
-  merchant_to: v3.z.string().min(1),
-  amount: v3.z.string().min(1),
-  asset: v3.z.string().min(1),
-  network: v3.z.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: v3.z.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: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "typed_data_hash must be a 0x-prefixed 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: v3.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "payer_delegate must be a 0x-prefixed address").optional(),
-  payer_agent_id: v3.z.string().min(1).optional(),
-  auth: v3.z.object({
-    // Open at the boundary, enforced in the signer — see bindingVersionSchema.
-    version: bindingVersionSchema,
-    message: v3.z.string().min(1),
-    signature: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "signature must be a 0x-prefixed hex string"),
-    signer: v3.z.string().min(1)
-  })
-};
-var x402ExpectedSchema = v3.z.object(x402ExpectedShape);
-var toolSchemas = {
-  haven_sign_sweep_delegate: {
-    // The authorization fields prepared by Haven's POST /sweep/prepare. Passed
-    // through verbatim from the hosted haven_sweep_delegate tool — the signer
-    // re-derives the binding message from these exact values.
-    authorization: sweepAuthorizationSchema,
-    // Haven's signature over the authorization context (the binding).
-    expected_auth: sweepExpectedAuthSchema
-  },
-  haven_sign: {
-    // #1263: THE preferred x402 input — the signer fetches the exact signing
-    // 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: v3.z.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: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "payload_hash must be a 0x-prefixed 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: v3.z.record(v3.z.string(), v3.z.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
-    // failure mode this field removes (a truncated/reshaped payload fails the
-    // digest check and the payment refuses, correctly but pointlessly).
-    // 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: v3.z.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: v3.z.record(v3.z.string(), v3.z.unknown()),
-    // Opaque binding returned by haven_sign when x402_expected was supplied.
-    x402_binding: v3.z.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: v3.z.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: v3.z.string().regex(/^0x[0-9a-fA-F]+$/, "payload_hash must be a 0x-prefixed 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: v3.z.record(v3.z.string(), v3.z.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: v3.z.record(v3.z.string(), v3.z.unknown()).optional(),
-    // #1255: see haven_sign.typed_data_b64 — the copy-through-safe form.
-    typed_data_b64: v3.z.string().min(1).max(262144).optional()
-  }
-};
-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.",
-  "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.",
-  "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."
-].join(" ");
-var X402_SIGN_HEADER_DESCRIPTION = [
-  "Build and sign the EIP-3009 merchant payment header for the merchant leg of an x402 payment.",
-  "The delegate key stays local \u2014 only the signed header crosses any boundary.",
-  "Pass the payment_required from the original merchant 402 response and the x402_binding",
-  "returned by haven_sign. It must be haven_sign \u2014 NOT haven_sign_x402, which is a",
-  "one-shot that builds the header itself and spends its own binding doing so. If you called",
-  "haven_sign_x402, its result already carries payment_header; retry the merchant with that and",
-  "do not call this tool. The signer validates the merchant, amount, resource, asset, and",
-  "network against the recorded funding context before signing, checks expires_at when present,",
-  "and rejects mismatches or expired payment windows.",
-  "Returns { payment_header, accepted }. On your retry set BOTH PAYMENT-SIGNATURE (x402 v2) and",
-  "X-PAYMENT (v1) to <payment_header>; a strict v2 merchant reads only the first.",
-  "Only call after haven_submit has confirmed the funding step (nextAction=none or",
-  "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",
-  "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",
-  "payload, expected context, and merchant payment_required from Haven itself, so nothing bulky",
-  "crosses your context. If the signer reports the context carried no payment_required (older",
-  "backend), re-call with payment_id plus payment_required verbatim from the pay result.",
-  "Fallback for older backends: pass payload_hash, x402_expected (the nested x402.expected object \u2014",
-  "passing the whole x402 object is also accepted and unwrapped for you), and typed_data_b64",
-  "through UNCHANGED; the signer",
-  "signs the typed data instead of payload_hash and refuses the bare hash when the context commits to typed data.",
-  "Returns",
-  "{ signature, x402_binding, payment_header, accepted }; hand signature + payment_header to",
-  "mcp__haven__haven_settle_mcp_tool to fund and settle in one hosted call. The header is built now (before",
-  "funding confirms), so its short validity window starts here \u2014 call mcp__haven__haven_settle_mcp_tool promptly,",
-  "and re-run mcp__haven__haven_pay_mcp_tool with the same idempotency_key if a tool returns PAYMENT_WINDOW_EXPIRED.",
-  "The returned x402_binding is ALREADY SPENT \u2014 this tool consumed it building payment_header \u2014",
-  "so never pass it to mcp__haven-signer__haven_x402_sign_header; that tool is the follow-up to",
-  "haven_sign, not to this one. payment_header IS the header to use.",
-  "Next: for a paid MCP tool, call mcp__haven__haven_settle_mcp_tool. For a direct plain-HTTP x402",
-  "merchant (the haven_pay_x402_quote path), relay signature via mcp__haven__haven_submit and then",
-  "retry the original merchant URL YOURSELF, setting BOTH PAYMENT-SIGNATURE (x402 v2) and",
-  "X-PAYMENT (v1) to payment_header \u2014 Haven never contacts that merchant."
-].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",
-  "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."
-].join(" ");
-var toolDescriptions = {
-  haven_sign: SIGN_DESCRIPTION,
-  haven_x402_sign_header: X402_SIGN_HEADER_DESCRIPTION,
-  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);
+`);
+    return { ok: true, hash, reason: "wrote_ack_file" };
   }
-  if (!typedData) {
-    throw new sdk.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."
-    );
+  out.write(renderSignerConsentBlock(input, hash));
+  return { ok: false, hash, reason: "no_acknowledgement" };
+}
+function registeredSignerToolNames() {
+  return Object.keys(toolSchemas);
+}
+function sidecarPath(credentialsPath) {
+  if (!credentialsPath) return null;
+  return path.resolve(`${credentialsPath}.signer-ack.json`);
+}
+async function readAckFile(path) {
+  try {
+    const raw = await promises.readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    return { ack: typeof parsed.ack === "string" ? parsed.ack : void 0 };
+  } catch {
+    return null;
   }
-  return signer.signX402FundingTypedData(typedData, expected);
 }
-function toExpectedX402(raw) {
-  return {
-    paymentId: raw.payment_id,
-    payloadHash: raw.payload_hash,
-    typedDataHash: raw.typed_data_hash,
-    payerDelegate: raw.payer_delegate,
-    payerAgentId: raw.payer_agent_id,
-    resourceUrl: raw.resource_url,
-    merchantTo: raw.merchant_to,
-    amount: raw.amount,
-    asset: raw.asset,
-    network: raw.network,
-    expiresAt: raw.expires_at,
-    auth: raw.auth
-  };
+async function writeAckFile(path$1, hash) {
+  await promises.mkdir(path.dirname(path$1), { recursive: true });
+  await promises.writeFile(
+    path$1,
+    JSON.stringify({ ack: hash, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2),
+    "utf8"
+  );
 }
-function parseFetchedExpected(fetched) {
-  const parsed = v3.z.object(x402ExpectedShape).safeParse(fetched.x402Expected);
-  if (!parsed.success) {
-    throw new sdk.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"}`
-    );
+
+// src/cli-args.ts
+var CONNECTOR_DOCTOR_COMMAND = "npx @haven_ai/connect --doctor";
+function parseSignerArgs(argv) {
+  const options = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--credentials" || arg === "--credentials-path") {
+      options.credentialsPath = argv[i + 1];
+      i += 1;
+    } else if (arg === "--ack") {
+      options.writeAck = true;
+    } else if (arg === "--help" || arg === "-h") {
+      return { kind: "help", text: helpText() };
+    } else {
+      return {
+        kind: "unknown-option",
+        option: arg,
+        text: `haven-signer: unknown option ${arg}. Run with --help for the options this signer takes` + (arg === "--ack-local-tools" ? ` \u2014 --ack-local-tools belongs to the connector (${CONNECTOR_DOCTOR_COMMAND}), not the signer.` : ".")
+      };
+    }
   }
-  return parsed.data;
+  return { kind: "run", options };
+}
+function helpText() {
+  const tools = registeredSignerToolNames();
+  return [
+    "Haven edge signer (local, holds the delegate key)",
+    "",
+    "Runs a local stdio MCP server exposing sign-only tools:",
+    ...tools.map((name) => `  - ${name}`),
+    "Pair it with the hosted, keyless Haven MCP server: the hosted server",
+    "constructs and relays, this one signs.",
+    "",
+    "Usage:",
+    "  npx @haven_ai/signer --credentials /path/to/agent.json",
+    "",
+    "Options:",
+    "  --credentials <path>   Haven credential JSON (delegate_key is read from it).",
+    "                         Alias: --credentials-path. Also supported: HAVEN_CREDENTIALS,",
+    "                         or HAVEN_DELEGATE_KEY.",
+    "  --ack                  Acknowledge the first-launch consent block and write",
+    "                         a signer sidecar acknowledgement next to the credential.",
+    "  --help, -h             This text. Any other option is refused (exit 2).",
+    "",
+    "Consent:",
+    "  On first launch the signer prints the sign-only tool list and delegate",
+    "  address, then refuses to start unless acknowledged. Its only Haven API call",
+    "  is a read-only fetch of the signing payload for one pending payment, so it",
+    "  cannot show a live allowance summary.",
+    "  Acknowledge with EITHER --ack OR HAVEN_SIGNER_ACK=<hash> in your environment.",
+    "",
+    "Connector-wired (the usual case)?",
+    `  Diagnose and repair with: ${CONNECTOR_DOCTOR_COMMAND}`,
+    "  (an unacknowledged signer shows there as a failed 'Signer stdio handshake'",
+    "  check, and in the connector's setup outcome as local_signer_ack_required;",
+    "  the repair is the connector's --ack-local-tools, not a signer flag).",
+    ""
+  ].join("\n");
 }
-function resolveTypedData(args) {
-  if (!args.typed_data_b64) return args.typed_data;
+function createEdgeSigner(delegateKey, options = {}) {
+  let delegateAddress;
   try {
-    const decoded = JSON.parse(
-      Buffer.from(args.typed_data_b64, "base64").toString("utf8")
-    );
-    if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) {
-      throw new Error("decoded value is not an object");
-    }
-    return decoded;
+    delegateAddress = edge.addressFromKey(delegateKey);
   } catch (err) {
-    throw new sdk.HavenSigningError(
-      `typed_data_b64 did not decode to a JSON object. Pass the exact string returned by the hosted Haven tool, unchanged \u2014 do not re-encode, trim, or reformat it. Underlying error: ${err instanceof Error ? err.message : String(err)}`
+    throw new edge.HavenSigningError(
+      `Invalid delegate key: ${err instanceof Error ? err.message : String(err)}`
     );
   }
-}
-function createToolHandlers(signer, options = {}) {
-  async function resolveSignContext(args) {
-    if (!args.payment_id) return null;
-    const identity = await options.signContext?.loadIdentity() ?? null;
-    if (!identity) {
-      throw new sdk.HavenSigningError(
-        `payment_id signing needs the agent identity (identity.json next to the signer credentials), which this signer could not load. Re-run \`${sdk.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 sdk.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.`
-      );
+  const x402Bindings = /* @__PURE__ */ new Map();
+  const retiredX402Bindings = /* @__PURE__ */ new Map();
+  const RETIRED_BINDING_MEMORY = 64;
+  function retireX402Binding(id, reason) {
+    retiredX402Bindings.set(id, reason);
+    if (retiredX402Bindings.size > RETIRED_BINDING_MEMORY) {
+      const oldest = retiredX402Bindings.keys().next();
+      if (!oldest.done) retiredX402Bindings.delete(oldest.value);
     }
-    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;
-      if (!payloadHash) {
-        throw new sdk.HavenSigningError(
-          "Pass payment_id (preferred for delegation-rail x402) or payload_hash."
+    delegateAddress,
+    async signDelegationTypedData(typedData) {
+      const account = accounts.privateKeyToAccount(delegateKey);
+      return account.signTypedData(typedData);
+    },
+    async signX402FundingTypedData(typedData, expected) {
+      if (expected?.auth) {
+        assertSupportedBindingVersion(
+          expected.auth.version,
+          SUPPORTED_X402_EXPECTED_VERSIONS,
+          "x402 expected context"
         );
       }
-      const expectedRaw = fetched ? parseFetchedExpected(fetched) : args.x402_expected;
-      const x402Expected = expectedRaw ? toExpectedX402(expectedRaw) : null;
-      const result = x402Expected ? await signFundingLeg(signer, x402Expected, payloadHash, typedData) : null;
-      if (!result) {
-        if (typedData) {
-          if (isSettlementChildTypedData(typedData)) {
-            throw new sdk.HavenSigningError(
-              "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 (!typedData) {
+        throw new edge.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 a bare payload_hash is not what the account validates."
+        );
+      }
+      const digest = viem.hashTypedData(typedData);
+      assertExpectedBinding(digest, expected, options.x402BindingSigner);
+      assertPayerMatchesDelegate(expected, delegateAddress, options.agentId);
+      if (edge.isSettlementChildTypedData(typedData)) {
+        const settlementChainId = edge.chainIdForNetwork(expected.network);
+        if (settlementChainId === void 0) {
+          throw new edge.HavenSigningError(
+            `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.`
+          );
         }
-        const signature = signer.signPaymentHash(payloadHash);
-        await auditSigning("haven_sign", payloadHash);
-        return { signature };
+        edge.assertOwnSettlementChild(typedData, {
+          merchantTo: expected.merchantTo,
+          amount: expected.amount,
+          asset: expected.asset,
+          // From the SIGNED network, not the payload's own claim. Passing
+          // Number(typedData.domain.chainId) here made the check compare a
+          // value to itself — vacuous, and precisely the "declared one thing,
+          // signed another" class this file exists to catch (#1455 review).
+          chainId: settlementChainId,
+          expiresAt: expected.expiresAt
+        }, delegateAddress);
+      } else if (edge.isPackedUserOperationTypedData(typedData)) {
+        edge.assertUserOpTypedDataBinding(typedData, expected.payloadHash);
+        edge.assertBoundDirectPaymentUserOp(typedData, delegateAddress);
+        edge.assertFundingLegPaysDelegate(typedData, {
+          delegateAddress,
+          asset: expected.asset,
+          amount: expected.amount
+        });
+      } else {
+        throw new edge.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.`
+        );
       }
-      await auditSigning("haven_sign", payloadHash);
-      return { signature: result.signature, x402_binding: result.x402Binding };
-    }),
-    haven_x402_sign_header: async (input) => runTool(async () => {
-      const args = parse("haven_x402_sign_header", coercePaymentRequired(input));
-      const result = await signer.buildX402PaymentHeader(
-        args.payment_required,
-        args.x402_binding
-      );
-      await auditSigning(
-        "haven_x402_sign_header",
-        hashPayloadForAudit(args.payment_required)
+      const account = accounts.privateKeyToAccount(delegateKey);
+      const signature = await account.signTypedData(
+        typedData
       );
-      return { payment_header: result.paymentHeader, accepted: result.accepted };
-    }),
-    haven_sign_x402: async (input) => runTool(async () => {
-      const args = parse("haven_sign_x402", coerceX402Expected(coercePaymentRequired(input)));
-      const fetched = await resolveSignContext(args);
-      const payloadHash = fetched?.payloadHash ?? args.payload_hash;
-      const expectedRaw = fetched ? parseFetchedExpected(fetched) : args.x402_expected;
-      if (!payloadHash || !expectedRaw) {
-        throw new sdk.HavenSigningError(
-          "Pass payment_id (preferred \u2014 the signer fetches the signing context itself) or payload_hash + x402_expected from the quote result."
+      const x402Binding = crypto.randomUUID();
+      x402Bindings.set(x402Binding, { ...expected });
+      return { signature, x402Binding };
+    },
+    async buildX402PaymentHeader(paymentRequired, x402Binding) {
+      const expected = x402Bindings.get(x402Binding);
+      if (!expected) {
+        const retired = retiredX402Bindings.get(x402Binding);
+        if (retired === "header_built") {
+          throw new edge.HavenSigningError(
+            "This x402 binding was already used to build a merchant header. Bindings are single-use. If you called haven_sign_x402, it already returned the payment_header \u2014 retry the merchant with THAT header instead of building another; haven_x402_sign_header is the follow-up to haven_sign, not to haven_sign_x402. If you no longer have the header, re-run the quote tool with the same idempotency_key."
+          );
+        }
+        if (retired === "window_expired") {
+          throw new edge.HavenSigningError(
+            "This x402 binding was retired because its payment window closed before a merchant header could be built \u2014 no header exists to retry with. Re-run the quote tool with the same idempotency_key to get a fresh window, then sign again."
+          );
+        }
+        throw new edge.HavenSigningError(
+          "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."
         );
       }
-      const funding = await signFundingLeg(
-        signer,
-        toExpectedX402(expectedRaw),
-        payloadHash,
-        fetched?.typedData ?? resolveTypedData(args)
-      );
-      const paymentRequired = fetched?.paymentRequired ?? args.payment_required;
-      if (!paymentRequired) {
-        throw new sdk.HavenSigningError(
-          fetched ? "The Haven sign-context for this payment_id carried no payment_required (backend predates #1355). Pass payment_required from the pay result explicitly, verbatim." : "payment_required is required on the quote-based path (no payment_id to fetch it by). Pass it verbatim from the quote result."
+      const assertWindowOpenOrRetire = () => {
+        try {
+          assertX402PaymentWindowOpen(expected);
+        } catch (err) {
+          x402Bindings.delete(x402Binding);
+          retireX402Binding(x402Binding, "window_expired");
+          throw err;
+        }
+      };
+      assertWindowOpenOrRetire();
+      const option = edge.selectStandardPaymentOption(paymentRequired.accepts);
+      if (!option) {
+        throw new edge.HavenApiError(
+          "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC.",
+          400
         );
       }
-      const header = await signer.buildX402PaymentHeader(
-        paymentRequired,
-        funding.x402Binding
+      assertX402MatchesExpected(paymentRequired, option, expected);
+      const account = accounts.privateKeyToAccount(delegateKey);
+      const requirements = edge.toStandardPaymentRequirements(paymentRequired, option);
+      const { exact } = await loadX402Schemes();
+      assertWindowOpenOrRetire();
+      const header = await exact.evm.createPaymentHeader(
+        account,
+        paymentRequired.x402Version,
+        requirements
       );
-      await auditSigning("haven_sign_x402", payloadHash);
-      await auditSigning("haven_sign_x402", hashPayloadForAudit(paymentRequired));
-      return {
-        signature: funding.signature,
-        x402_binding: funding.x402Binding,
-        payment_header: header.paymentHeader,
-        accepted: header.accepted
+      if (paymentRequired.x402Version < 2) {
+        x402Bindings.delete(x402Binding);
+        retireX402Binding(x402Binding, "header_built");
+        return { paymentHeader: header, accepted: option };
+      }
+      try {
+        const payment = edge.decodeBase64Json(header);
+        const wrapped = edge.encodeBase64Json(
+          edge.x402V2PaymentEnvelope(paymentRequired, option, payment.payload)
+        );
+        return { paymentHeader: wrapped, accepted: option };
+      } finally {
+        x402Bindings.delete(x402Binding);
+        retireX402Binding(x402Binding, "header_built");
+      }
+    },
+    async signSweepAuthorization({
+      authorization,
+      expectedAuth,
+      expectedSafe
+    }) {
+      assertSweepBinding(authorization, expectedAuth, options.x402BindingSigner);
+      if (!sameAddress(authorization.from, delegateAddress)) {
+        throw new edge.HavenSigningError(
+          "Sweep authorization `from` does not match this delegate address."
+        );
+      }
+      if (expectedSafe && !sameAddress(authorization.to, expectedSafe)) {
+        throw new edge.HavenSigningError(
+          "Sweep authorization `to` does not match the agent's account (Haven wallet) in the local credential."
+        );
+      }
+      const typedData = edge.buildSweepTypedData(authorization);
+      const viemTypedData = {
+        domain: {
+          ...typedData.domain,
+          verifyingContract: typedData.domain.verifyingContract
+        },
+        types: typedData.types,
+        primaryType: typedData.primaryType,
+        message: {
+          ...typedData.message,
+          from: typedData.message.from,
+          to: typedData.message.to,
+          nonce: typedData.message.nonce
+        }
       };
-    }),
-    haven_sign_sweep_delegate: async (input) => runTool(async () => {
-      const args = parse("haven_sign_sweep_delegate", input);
-      const result = await signer.signSweepAuthorization({
-        authorization: args.authorization,
-        expectedAuth: args.expected_auth,
-        // Cross-check `to` against the Safe in the local credential when present.
-        expectedSafe: options.audit?.accountAddress
-      });
-      await auditSigning(
-        "haven_sign_sweep_delegate",
-        hashPayloadForAudit(args.authorization)
-      );
-      return { signature: result.signature };
-    })
+      const account = accounts.privateKeyToAccount(delegateKey);
+      const signature = await account.signTypedData(viemTypedData);
+      const recovered = await viem.recoverTypedDataAddress({ ...viemTypedData, signature });
+      if (!sameAddress(recovered, delegateAddress)) {
+        throw new edge.HavenSigningError(
+          "Local sweep signature verification failed \u2014 recovered address does not match the delegate key."
+        );
+      }
+      return { signature };
+    }
   };
-  async function auditSigning(tool, payloadHash) {
-    if (!options.audit) return;
-    const { auditPath, ...context } = options.audit;
-    await appendSigningAuditEntry(
-      createSigningAuditEntry(tool, payloadHash, {
-        ...context,
-        delegateAddress: signer.delegateAddress
-      }),
-      auditPath
+}
+function assertSweepBinding(authorization, expectedAuth, trustedSigner) {
+  if (!expectedAuth || typeof expectedAuth !== "object") {
+    throw new edge.HavenSigningError("Sweep authorization binding is required before signing.");
+  }
+  if (!trustedSigner) {
+    throw new edge.HavenSigningError(
+      "Sweep binding verifier is not configured. Set HAVEN_X402_BINDING_SIGNER before signing sweep authorizations."
     );
   }
-}
-function parse(name, input) {
-  return v3.z.object(toolSchemas[name]).parse(input ?? {});
-}
-function coerceX402Expected(input) {
-  if (!input || typeof input !== "object") return input;
-  const record = input;
-  let value = record.x402_expected;
-  if (typeof value === "string") {
-    try {
-      value = JSON.parse(value);
-    } catch {
-      return input;
-    }
+  assertSupportedBindingVersion(
+    expectedAuth.version,
+    SUPPORTED_SWEEP_BINDING_VERSIONS,
+    "sweep authorization binding"
+  );
+  const message = edge.buildSweepAuthorizationMessage(authorization);
+  if (expectedAuth.message !== message) {
+    throw new edge.HavenSigningError("Sweep authorization binding does not match the authorization being signed.");
   }
-  if (!value || typeof value !== "object") return input;
-  const obj = value;
-  if (obj.auth === void 0 && obj.expected && typeof obj.expected === "object") {
-    return { ...record, x402_expected: obj.expected };
+  if (!sameAddress(expectedAuth.signer, trustedSigner)) {
+    throw new edge.HavenSigningError("Sweep authorization binding was not signed by the configured Haven signer.");
+  }
+  if (!edge.verifySignature(viem.hashMessage(message), expectedAuth.signature, trustedSigner)) {
+    throw new edge.HavenSigningError("Sweep authorization binding signature could not be verified.");
   }
-  if (value !== record.x402_expected) return { ...record, x402_expected: value };
-  return input;
 }
-function coercePaymentRequired(input) {
-  if (!input || typeof input !== "object") return input;
-  const record = input;
-  if (typeof record.payment_required !== "string") return input;
-  try {
-    return { ...record, payment_required: JSON.parse(record.payment_required) };
-  } catch {
-    return input;
+function assertX402MatchesExpected(paymentRequired, option, expected) {
+  assertExpectedShape(expected);
+  const headerResource = option.resource ?? paymentRequired.resource.url;
+  if (headerResource !== expected.resourceUrl) {
+    throw new edge.HavenSigningError("x402 payment_required resource does not match the funded intent.");
+  }
+  if (!sameAddress(option.payTo, expected.merchantTo)) {
+    throw new edge.HavenSigningError("x402 merchant recipient does not match the funded intent.");
+  }
+  if (edge.x402AuthorizationAmount(option) !== expected.amount) {
+    throw new edge.HavenSigningError("x402 amount does not match the funded intent.");
+  }
+  if (!sameAddress(option.asset, expected.asset)) {
+    throw new edge.HavenSigningError("x402 asset does not match the funded intent.");
+  }
+  if (option.network !== expected.network) {
+    throw new edge.HavenSigningError("x402 network does not match the funded intent.");
   }
 }
-async function runTool(fn) {
-  try {
-    return { success: true, data: await fn() };
-  } catch (err) {
-    return normalizeError(err);
+function assertExpectedShape(expected) {
+  if (!expected || typeof expected !== "object") {
+    throw new edge.HavenSigningError("x402 expected funding context is required before signing a merchant header.");
   }
 }
-function normalizeError(err) {
-  if (err instanceof v3.z.ZodError) {
-    return {
-      success: false,
-      code: "INVALID_INPUT",
-      message: err.errors.map((e) => `${e.path.join(".") || "(root)"}: ${e.message}`).join("; "),
-      statusCode: 400
-    };
+var SUPPORTED_X402_EXPECTED_VERSIONS = [2, 3];
+var SUPPORTED_SWEEP_BINDING_VERSIONS = [1];
+function assertSupportedBindingVersion(received, supported, context) {
+  if (supported.includes(received)) return;
+  const highest = Math.max(...supported);
+  const outOfDate = received > highest;
+  const code = context === "x402 expected context" ? edge.SignerRefusalCode.UnsupportedExpectedContextVersion : edge.SignerRefusalCode.UnsupportedSweepBindingVersion;
+  const ceiling = outOfDate ? `This signer is out of date: it supports ${context} versions up to ${highest}, and Haven sent version ${received}. Update @haven_ai/signer \u2014 rerun the Haven connector (\`${edge.connectorRerunCommand()}\`), which reinstalls the pinned MCP runtime.` : `Unsupported ${context} version ${received}: this signer supports ${supported.join(", ")}.`;
+  const fallback = outOfDate ? edge.SIGNER_UPDATE_FALLBACK : `This ${context} version (${received}) is older than what this signer enforces (${supported.join(", ")}) \u2014 updating @haven_ai/signer will not restore it. Nothing was signed or spent; stop and tell the user rather than retrying.`;
+  throw new edge.HavenUnsupportedSignerVersionError(
+    `${ceiling} Nothing was signed. Do not rewrite the version field to a supported value: it is part of the Haven-signed binding message, so changing it invalidates the signature and would misrepresent what Haven declared.`,
+    code,
+    supported,
+    received,
+    fallback
+  );
+}
+function assertExpectedBinding(typedDataDigest, expected, trustedSigner) {
+  assertExpectedShape(expected);
+  if (!trustedSigner) {
+    throw new edge.HavenSigningError(
+      "x402 expected-context verifier is not configured. Set HAVEN_X402_BINDING_SIGNER before signing x402 funding payloads."
+    );
   }
-  if (err instanceof sdk.HavenUnsupportedSignerVersionError) {
-    return {
-      success: false,
-      code: err.code,
-      message: err.message,
-      supported_versions: [...err.supportedVersions],
-      received_version: err.receivedVersion,
-      fallback: err.fallback,
-      next_action: sdk.AgentPaymentNextAction.StopAndTellUser
-    };
+  if (expected.auth) {
+    assertSupportedBindingVersion(
+      expected.auth.version,
+      SUPPORTED_X402_EXPECTED_VERSIONS,
+      "x402 expected context"
+    );
   }
-  if (err instanceof HavenSignContextError) {
-    return {
-      success: false,
-      code: err.code,
-      message: err.message,
-      next_action: err.next_action,
-      ...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 } : {}
-    };
+  if (!expected.typedDataHash) {
+    throw new edge.HavenSigningError(
+      "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 (err instanceof sdk.HavenSigningError) {
-    return { success: false, code: err.code, message: err.message };
+  if (expected.typedDataHash.toLowerCase() !== typedDataDigest.toLowerCase()) {
+    throw new edge.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."
+    );
   }
-  if (err instanceof sdk.HavenApiError) {
-    return { success: false, code: err.code, message: err.message, statusCode: err.statusCode };
+  const message = edge.buildX402ExpectedMessage({
+    paymentId: expected.paymentId,
+    payloadHash: expected.payloadHash,
+    resourceUrl: expected.resourceUrl,
+    merchantTo: expected.merchantTo,
+    amount: expected.amount,
+    asset: expected.asset,
+    network: expected.network,
+    expiresAt: expected.expiresAt,
+    typedDataHash: expected.typedDataHash,
+    payerDelegate: expected.payerDelegate,
+    payerAgentId: expected.payerAgentId
+  });
+  const expectedVersion = expected.payerDelegate ? 3 : 2;
+  if (expected.auth?.version !== expectedVersion || expected.auth.message !== message) {
+    throw new edge.HavenSigningError("x402 expected context authentication message is invalid.");
   }
-  if (err instanceof sdk.HavenError) {
-    return {
-      success: false,
-      code: err.code,
-      message: err.message,
-      statusCode: err.statusCode,
-      paymentId: err.paymentId,
-      ...err.code === sdk.AgentPaymentFailureCode.PaymentWindowExpired ? {
-        next_action: sdk.AgentPaymentNextAction.PaymentWindowExpired,
-        retry_with_new_quote: true,
-        suggested_tool: "haven_pay_mcp_tool"
-      } : {}
-    };
+  if (!sameAddress(expected.auth.signer, trustedSigner)) {
+    throw new edge.HavenSigningError("x402 expected context was not signed by the configured Haven signer.");
   }
-  return {
-    success: false,
-    code: "UNKNOWN_ERROR",
-    message: err instanceof Error ? err.message : String(err)
-  };
-}
-
-// src/consent.ts
-var SIGNER_ACK_ENV = "HAVEN_SIGNER_ACK";
-var SIGNER_CONSENT_SURFACE_VERSION = 2;
-function computeSignerConsentHash(input) {
-  const identity = [
-    input.delegateAddress.toLowerCase(),
-    (input.accountAddress ?? "").toLowerCase(),
-    input.agentId ?? "",
-    input.chainId ?? "",
-    input.network ?? ""
-  ].join("|");
-  const toolCanonical = [...input.toolNames].sort().join(",");
-  return crypto.createHash("sha256").update(`${identity}
-${toolCanonical}
-surface:v${SIGNER_CONSENT_SURFACE_VERSION}`).digest("hex").slice(0, 16);
-}
-function renderSignerConsentBlock(input, hash) {
-  const lines = [
-    "",
-    "------------------------------------------------------------",
-    "Haven edge signer - first-launch consent",
-    "------------------------------------------------------------",
-    "",
-    `Delegate address: ${input.delegateAddress}`
-  ];
-  lines.push(`Haven wallet:     ${input.accountAddress ?? "not provided to this signer"}`);
-  if (input.agentId) lines.push(`Agent ID:         ${input.agentId}`);
-  if (typeof input.chainId === "number") lines.push(`Chain ID:         ${input.chainId}`);
-  if (input.network) lines.push(`Network:          ${input.network}`);
-  lines.push("");
-  lines.push("This local signer holds the delegate key on this machine and signs");
-  lines.push("payment payloads or x402 merchant headers for the delegate address above.");
-  lines.push("Its one network use is a read-only fetch of a pending payment's signing");
-  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("");
-  lines.push("Tools this signer will expose to your agent runtime:");
-  for (const name of input.toolNames) {
-    lines.push(`  - ${name}`);
-    lines.push(`      ${toolDescriptions[name]}`);
+  if (!edge.verifySignature(viem.hashMessage(message), expected.auth.signature, trustedSigner)) {
+    throw new edge.HavenSigningError("x402 expected context signature could not be verified.");
   }
-  lines.push("");
-  lines.push("A local audit entry is appended for every signing operation. Audit entries");
-  lines.push("record timestamp, tool, payload hash, and delegate address; never the key,");
-  lines.push("signature, or x402 payment header.");
-  lines.push("");
-  lines.push(`Consent hash: ${hash}`);
-  lines.push("");
-  lines.push("To acknowledge, EITHER:");
-  lines.push(`  - set ${SIGNER_ACK_ENV}=${hash} in this process's environment, OR`);
-  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("------------------------------------------------------------");
-  lines.push("");
-  return lines.join("\n");
 }
-async function ensureSignerConsent(input, options = {}) {
-  const env = options.env ?? process.env;
-  const out = options.out ?? process.stderr;
-  const hash = computeSignerConsentHash(input);
-  const envAck = env[SIGNER_ACK_ENV];
-  if (typeof envAck === "string" && envAck.length > 0) {
-    if (envAck === hash) return { ok: true, hash, reason: "env_var_match" };
-    out.write(renderSignerConsentBlock(input, hash));
-    out.write(
-      `${SIGNER_ACK_ENV} was set but did not match the current signer consent hash.
-Expected: ${hash}
-Got:      ${envAck}
-Re-acknowledge with the new hash above, or run with --ack.
-
-`
+function assertPayerMatchesDelegate(expected, delegateAddress, localAgentId) {
+  if (!expected.payerDelegate) return;
+  if (sameAddress(expected.payerDelegate, delegateAddress)) return;
+  const quoteAgent = expected.payerAgentId ?? "unknown";
+  const localAgent = localAgentId ?? "unknown";
+  throw new edge.HavenSigningError(
+    `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 edge.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`
     );
-    return { ok: false, hash, reason: "env_var_mismatch" };
   }
-  const ackPath = sidecarPath(options.credentialsPath);
-  if (ackPath) {
-    const stored = await readAckFile(ackPath);
-    if (stored?.ack === hash) return { ok: true, hash, reason: "ack_file_match" };
+}
+function assertX402PaymentWindowOpen(expected) {
+  if (!expected.expiresAt) return;
+  const expiresAtMs = Date.parse(expected.expiresAt);
+  if (Number.isNaN(expiresAtMs)) {
+    throw new edge.HavenSigningError("x402 expected context expiresAt is not a valid ISO timestamp.");
   }
-  if (options.writeAck && ackPath) {
-    out.write(renderSignerConsentBlock(input, hash));
-    await writeAckFile(ackPath, hash);
-    out.write(`Wrote acknowledgement to ${ackPath}
-
-`);
-    return { ok: true, hash, reason: "wrote_ack_file" };
+  if (expiresAtMs <= Date.now()) {
+    throw new edge.HavenError(
+      "The x402 payment window expired before the merchant header could be signed. Re-quote with haven_pay_mcp_tool using the same idempotency_key before trying again.",
+      edge.AgentPaymentFailureCode.PaymentWindowExpired,
+      410,
+      expected.paymentId
+    );
   }
-  out.write(renderSignerConsentBlock(input, hash));
-  return { ok: false, hash, reason: "no_acknowledgement" };
 }
-function registeredSignerToolNames() {
-  return Object.keys(toolSchemas);
+function sameAddress(a, b) {
+  return a.toLowerCase() === b.toLowerCase();
 }
-function sidecarPath(credentialsPath) {
-  if (!credentialsPath) return null;
-  return path.resolve(`${credentialsPath}.signer-ack.json`);
+
+// 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],
+    direct_sign_context_versions: [...SUPPORTED_DIRECT_SIGN_CONTEXT_VERSIONS]
+  };
 }
-async function readAckFile(path) {
-  try {
-    const raw = await promises.readFile(path, "utf8");
-    const parsed = JSON.parse(raw);
-    return { ack: typeof parsed.ack === "string" ? parsed.ack : void 0 };
-  } catch {
-    return null;
-  }
+function signerCapabilityAdvertisement() {
+  return { experimental: { [SIGNER_CAPABILITY_KEY]: signerCompatibility() } };
 }
-async function writeAckFile(path$1, hash) {
-  await promises.mkdir(path.dirname(path$1), { recursive: true });
-  await promises.writeFile(
-    path$1,
-    JSON.stringify({ ack: hash, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2),
-    "utf8"
-  );
+function signerInstructions() {
+  const compatibility = signerCompatibility();
+  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 (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",
+    "above, this signer is out of date: STOP before signing, and tell the user to update",
+    `@haven_ai/signer by rerunning \`${edge.connectorRerunCommand()}\`, which reinstalls the pinned`,
+    "MCP runtime. Do not edit the version field to a supported value \u2014 it is part of the",
+    "Haven-signed binding message, so changing it invalidates the signature.",
+    "",
+    "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. 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");
 }
 async function loadSignerCredentials(path = process.env.HAVEN_CREDENTIALS) {
   if (path) return loadFromFile(path);
@@ -1318,24 +1704,12 @@ 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 promises.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);
 }
 
 // src/server.ts
 var SIGNER_NAME = "@haven_ai/signer";
-var SIGNER_VERSION = "0.3.0-alpha.0";
+var SIGNER_VERSION = "0.5.0-alpha.1";
 async function resolveSignerRuntime(options = {}) {
   assertSupportedNodeVersion(options.nodeVersion);
   if (options.delegateKey) {
@@ -1373,13 +1747,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: edge.havenClientIdentity(SIGNER_NAME, SIGNER_VERSION)
     }
   });
   const registerTool = server.tool.bind(server);
@@ -1394,9 +1772,9 @@ function buildSignerMcpServer(signer, options = {}) {
   return server;
 }
 function assertSupportedNodeVersion(nodeVersion = process.versions.node) {
-  if (sdk.isSupportedNodeVersion(nodeVersion)) return;
+  if (edge.isSupportedNodeVersion(nodeVersion)) return;
   const err = new Error(
-    sdk.unsupportedNodeVersionMessage({ subject: "The Haven signer", nodeVersion })
+    edge.unsupportedNodeVersionMessage({ subject: "The Haven signer", nodeVersion })
   );
   err.code = "HAVEN_SIGNER_UNSUPPORTED_NODE";
   throw err;
@@ -1407,7 +1785,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;
@@ -1442,49 +1820,18 @@ function toMcpResult(payload) {
 }
 
 // src/cli.ts
-function parseArgs(argv) {
-  const options = {};
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === "--credentials" || arg === "--credentials-path") {
-      options.credentialsPath = argv[i + 1];
-      i += 1;
-    } else if (arg === "--ack") {
-      options.writeAck = true;
-    } else if (arg === "--help" || arg === "-h") {
-      process.stdout.write(
-        [
-          "Haven edge signer (local, holds the delegate key)",
-          "",
-          "Runs a local stdio MCP server exposing sign-only tools (haven_sign,",
-          "haven_x402_sign_header). Pair it with the hosted, keyless Haven MCP",
-          "server: the hosted server constructs and relays, this one signs.",
-          "",
-          "Usage:",
-          "  npx @haven_ai/signer --credentials /path/to/agent.json",
-          "",
-          "Options:",
-          "  --credentials <path>   Haven credential JSON (delegate_key is read from it).",
-          "                         Also supported: HAVEN_CREDENTIALS, or HAVEN_DELEGATE_KEY.",
-          "  --ack                  Acknowledge the first-launch consent block and write",
-          "                         a signer sidecar acknowledgement next to the credential.",
-          "",
-          "Consent:",
-          "  On first launch the signer prints the sign-only tool list and delegate",
-          "  address, then refuses to start unless acknowledged. Its only Haven API call",
-          "  is a read-only fetch of the signing payload for one pending payment, so it",
-          "  cannot show a live allowance summary.",
-          "  Acknowledge with EITHER --ack OR HAVEN_SIGNER_ACK=<hash> in your environment.",
-          ""
-        ].join("\n")
-      );
-      process.exit(0);
-    }
-  }
-  return options;
-}
 async function main() {
-  await runSignerStdioServer(parseArgs(process.argv.slice(2)));
+  const decision = parseSignerArgs(process.argv.slice(2));
+  if (decision.kind === "help") {
+    process.stdout.write(decision.text);
+    process.exit(0);
+  }
+  if (decision.kind === "unknown-option") {
+    process.stderr.write(`${decision.text}
+`);
+    process.exit(2);
+  }
+  await runSignerStdioServer(decision.options);
 }
 main().catch((err) => {
   process.stderr.write(`${err instanceof Error ? err.message : String(err)}