agentic-wallet-mcp 0.14.0 → 0.14.2

package/dist/server-bundle.cjs

@@ -2982,7 +2982,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve.call(this, root, ref);
+      let _sch = resolve2.call(this, root, ref);
       if (_sch === void 0) {
         const schema = (_a3 = root.localRefs) === null || _a3 === void 0 ? void 0 : _a3[ref];
         const { schemaId } = this.opts;
@@ -3009,7 +3009,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve(root, ref) {
+    function resolve2(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -3640,7 +3640,7 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve(baseURI, relativeURI, options) {
+    function resolve2(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const resolved = resolveComponent(parse3(baseURI, schemelessOptions), parse3(relativeURI, schemelessOptions), schemelessOptions, true);
       schemelessOptions.skipEscape = true;
@@ -3898,7 +3898,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize: normalize3,
-      resolve,
+      resolve: resolve2,
       resolveComponent,
       equal,
       serialize,
@@ -7030,7 +7030,7 @@ var require_aspromise = __commonJS({
       var params = new Array(arguments.length - 1), offset = 0, index = 2, pending = true;
       while (index < arguments.length)
         params[offset++] = arguments[index++];
-      return new Promise(function executor(resolve, reject) {
+      return new Promise(function executor(resolve2, reject) {
         params[offset] = function callback(err) {
           if (pending) {
             pending = false;
@@ -7040,7 +7040,7 @@ var require_aspromise = __commonJS({
               var params2 = new Array(arguments.length - 1), offset2 = 0;
               while (offset2 < params2.length)
                 params2[offset2++] = arguments[offset2];
-              resolve.apply(null, params2);
+              resolve2.apply(null, params2);
             }
           }
         };
@@ -8568,7 +8568,7 @@ var require_path = __commonJS({
         return prefix + parts.join("/");
       }
     );
-    path.resolve = function resolve(originPath, includePath, alreadyNormalized) {
+    path.resolve = function resolve2(originPath, includePath, alreadyNormalized) {
       if (!alreadyNormalized)
         includePath = normalize3(includePath);
       if (isAbsolute(includePath))
@@ -8848,7 +8848,7 @@ var require_field = __commonJS({
         keepComments ? this.comment : void 0
       ]);
     };
-    Field.prototype.resolve = function resolve() {
+    Field.prototype.resolve = function resolve2() {
       if (this.resolved)
         return this;
       if ((this.typeDefault = types.defaults[this.type]) === void 0) {
@@ -9252,7 +9252,7 @@ var require_mapfield = __commonJS({
         keepComments ? this.comment : void 0
       ]);
     };
-    MapField.prototype.resolve = function resolve() {
+    MapField.prototype.resolve = function resolve2() {
       if (this.resolved)
         return this;
       if (types.mapKey[this.keyType] === void 0)
@@ -9329,7 +9329,7 @@ var require_method = __commonJS({
         this.parsedOptions
       ]);
     };
-    Method.prototype.resolve = function resolve() {
+    Method.prototype.resolve = function resolve2() {
       if (this.resolved)
         return this;
       this.resolvedRequestType = this.parent.lookupType(this.requestType);
@@ -10610,7 +10610,7 @@ var require_object = __commonJS({
       this.parent = null;
       this.resolved = false;
     };
-    ReflectionObject.prototype.resolve = function resolve() {
+    ReflectionObject.prototype.resolve = function resolve2() {
       if (this.resolved)
         return this;
       if (this.root instanceof Root)
@@ -20049,7 +20049,7 @@ var require_sha3 = __commonJS({
     function _interopRequireDefault(obj) {
       return obj && obj.__esModule ? obj : { "default": obj };
     }
-    var createHash10 = function createHash11(_ref) {
+    var createHash12 = function createHash13(_ref) {
       var allowedSizes = _ref.allowedSizes, defaultSize = _ref.defaultSize, padding = _ref.padding;
       return function Hash() {
         var _this = this;
@@ -20088,11 +20088,11 @@ var require_sha3 = __commonJS({
         return this;
       };
     };
-    var Keccak = createHash10({ allowedSizes: [224, 256, 384, 512], defaultSize: 512, padding: 1 });
+    var Keccak = createHash12({ allowedSizes: [224, 256, 384, 512], defaultSize: 512, padding: 1 });
     exports2.Keccak = Keccak;
-    var SHA3 = createHash10({ allowedSizes: [224, 256, 384, 512], defaultSize: 512, padding: 6 });
+    var SHA3 = createHash12({ allowedSizes: [224, 256, 384, 512], defaultSize: 512, padding: 6 });
     exports2.SHA3 = SHA3;
-    var SHAKE = createHash10({ allowedSizes: [128, 256], defaultSize: 256, padding: 31 });
+    var SHAKE = createHash12({ allowedSizes: [128, 256], defaultSize: 256, padding: 31 });
     exports2.SHAKE = SHAKE;
     var SHA3Hash = Keccak;
     exports2.SHA3Hash = SHA3Hash;
@@ -31382,16 +31382,16 @@ __export(index_exports, {
   describeAssetAmount: () => describeAssetAmount
 });
 module.exports = __toCommonJS(index_exports);
-var import_node_crypto10 = require("node:crypto");
+var import_node_crypto13 = require("node:crypto");
 var import_node_fs = require("node:fs");
-var import_promises7 = require("node:fs/promises");
+var import_promises10 = require("node:fs/promises");
 var import_node_os2 = require("node:os");
-var import_node_path8 = require("node:path");
+var import_node_path10 = require("node:path");
 
 // package.json
 var package_default = {
   name: "agentic-wallet-mcp",
-  version: "0.14.0",
+  version: "0.14.2",
   description: "Agent-facing MCP wallet for Zetrix \u2014 orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   keywords: [
     "mcp",
@@ -38773,7 +38773,7 @@ var Protocol = class {
           return;
         }
         const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1e3;
-        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
         options?.signal?.throwIfAborted();
       }
     } catch (error2) {
@@ -38790,7 +38790,7 @@ var Protocol = class {
    */
   request(request, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       const earlyReject = (error2) => {
         reject(error2);
       };
@@ -38868,7 +38868,7 @@ var Protocol = class {
           if (!parseResult.success) {
             reject(parseResult.error);
           } else {
-            resolve(parseResult.data);
+            resolve2(parseResult.data);
           }
         } catch (error2) {
           reject(error2);
@@ -39129,12 +39129,12 @@ var Protocol = class {
       }
     } catch {
     }
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       if (signal.aborted) {
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
         return;
       }
-      const timeoutId = setTimeout(resolve, interval);
+      const timeoutId = setTimeout(resolve2, interval);
       signal.addEventListener("abort", () => {
         clearTimeout(timeoutId);
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
@@ -40004,12 +40004,12 @@ var StdioServerTransport = class {
     this.onclose?.();
   }
   send(message) {
-    return new Promise((resolve) => {
+    return new Promise((resolve2) => {
       const json = serializeMessage(message);
       if (this._stdout.write(json)) {
-        resolve();
+        resolve2();
       } else {
-        this._stdout.once("drain", resolve);
+        this._stdout.once("drain", resolve2);
       }
     });
   }
@@ -40860,10 +40860,10 @@ async function fetchTemplateFields(templateId, registryAddress, nodeBaseUrl, que
 var WalletBeError = class extends Error {
   errorCode;
   cause;
-  constructor(message, errorCode, cause) {
+  constructor(message, errorCode2, cause) {
     super(message);
     this.name = "WalletBeError";
-    this.errorCode = errorCode;
+    this.errorCode = errorCode2;
     this.cause = cause;
   }
 };
@@ -41305,6 +41305,15 @@ async function resolveIssuerProofKeys(vc, resolver) {
   return { bbsPublicKey, ed25519PublicKey };
 }
 
+// src/orchestrator/birthcert-choice.ts
+function aiBirthcertChoice(kind, opts = {}) {
+  const note = `AI Birthcert comes in two kinds. BASIC: self-declared by the agent, with no check of the owner's identity; it is quick, shows only the agent's username, and does not mean the owner was verified. VERIFIED: the owner's identity is confirmed through MyDigital ID; the fee is paid up front, the owner completes a check in the MyID app, and the agent name must be unique (the name is only checked after payment, so a name that turns out to be taken is refused late, and whether the fee was spent cannot be confirmed). Each kind has its own price, read from the check for that kind: never assume Basic is free. This result is for the ${kind === "basic" ? "BASIC" : "VERIFIED"} one. If the user has not said which kind they want (they did not say "verified" or "basic", and did not mention MyDigital ID or owner verification), do not start either: run this check for both kinds (it is free) to see what the wallet already holds, tell the user the difference in plain words, offer only the kind or kinds they do not already hold, and ask which they prefer. If they want both, issue them one after the other, Basic first, and finish and show the first before starting the second; each has its own price and needs its own yes, so "both" is not a yes to either payment. Holding one kind never blocks the other, and replacing one that is held is its own explicit choice.`;
+  return opts.unavailable ? note + " The Verified kind is not available on this wallet or network: say so, and offer the Basic one only." : note;
+}
+
+// src/mcp-tools.ts
+var import_promises4 = require("node:fs/promises");
+
 // src/orchestrator/prove.ts
 async function proveIdentity(wallet, proofRequestHeader, holderDid) {
   const pr = await wallet.respondToChallenge(proofRequestHeader, holderDid);
@@ -41615,7 +41624,7 @@ var RECOVERY_MAX_POLLS = 5;
 var RECOVERY_POLL_DELAY_MS = 2e3;
 async function pollSettlementOutcome(deps, paymentId) {
   if (!deps.mbi.getStatus) return void 0;
-  const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const sleep = deps.sleep ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms)));
   let last;
   for (let polls = 1; polls <= RECOVERY_MAX_POLLS; polls++) {
     let status;
@@ -42236,7 +42245,7 @@ var TEMPLATE_ALIASES = [
     deriveAttributes: { id: "agentUsername" },
     validateAttributes: { dob: validateDob, countryOfOrigin: validateCountryOfOrigin },
     passDesignId: {
-      testnet: "did:zid:992e1e18985ba36a09ba0fbfeb601ddeb449f5e4e882ed69d0d620085f399818",
+      testnet: "did:zid:bb7202482ef6053be6d46ad8e2190b0ba1e3b2024d24ce7f37bc4c3747e2378f",
       mainnet: "did:zid:915955cb71c6fd2a256d04344f57381084903cb6a85a1c9ddb71c746f08932ab"
     }
   }
@@ -42301,6 +42310,8 @@ async function credentialPreflight(deps, input) {
   const blockers = [];
   const notChecked = [];
   const isVerified = input.credential === VERIFIED_AI_BIRTHCERT;
+  const kind = isVerified ? "verified" : deps.isBasicAiBirthcert?.(input.credential) ? "basic" : void 0;
+  const choice = kind ? { choice: aiBirthcertChoice(kind) } : {};
   let alreadyHeld;
   if (deps.findHeld) {
     try {
@@ -42318,7 +42329,8 @@ async function credentialPreflight(deps, input) {
             blockers: [
               `This wallet already holds a valid ${found.label}${until}${found.vcId ? `, ${found.vcId}` : ""}. Tell the user, and do not start another: a new one would REPLACE it (the wallet keeps one per template) and costs the fee. Only if the user explicitly says they want a replacement, run this check again with replacing: true.`
             ],
-            notChecked: []
+            notChecked: [],
+            ...choice
           };
         }
       } else {
@@ -42344,7 +42356,8 @@ async function credentialPreflight(deps, input) {
       ...alreadyHeld ? { alreadyHeld } : {},
       ...schema ? { schema } : {},
       blockers: [`Could not price this credential: ${why}`],
-      notChecked: [...notChecked, ...uncheckable(isVerified)]
+      notChecked: [...notChecked, ...uncheckable(isVerified)],
+      ...choice
     };
   }
   const asset = String(quote.asset ?? "");
@@ -42360,12 +42373,21 @@ async function credentialPreflight(deps, input) {
   } else if (!isFree && BigInt(feeBalance.balance) < BigInt(requiredRaw)) {
     blockers.push(`Not enough ${feeBalance.token}: the fee is ${renderAmount(requiredRaw, feeBalance)}, the balance is ${feeBalance.display}.`);
   }
+  const gasNotes = [];
   if (selfPaysGas && asset !== NATIVE) {
     const gas = balances[1];
     if (gas && "error" in gas) {
-      blockers.push(`Could not read the ZTX balance (${gas.error}) \u2014 ZTX pays network gas and is separate from the fee.`);
+      const msg = `Could not read the ZTX balance (${gas.error}) \u2014 ZTX pays network gas and is separate from the fee.`;
+      if (isFree) gasNotes.push(`${msg} Issuance is free right now, so none is needed unless it becomes chargeable.`);
+      else blockers.push(msg);
     } else if (gas && BigInt(gas.balance) === 0n) {
-      blockers.push(`No ZTX for network gas. ZTX is separate from the ${feeBalance.token ?? asset} fee and is needed for every transaction.`);
+      if (isFree) {
+        gasNotes.push(
+          "This wallet holds no ZTX. Issuance is free right now, so no payment is made and no gas is needed; if it becomes chargeable and this wallet pays its own gas, it will need ZTX."
+        );
+      } else {
+        blockers.push(`No ZTX for network gas. ZTX is separate from the ${feeBalance.token ?? asset} fee and is needed for every transaction.`);
+      }
     }
   }
   const cap = deps.policyGoverns && await deps.policyGoverns(asset) ? describePolicyGovernedCap(asset) : describePaymentCap(asset, requiredRaw, deps.caps);
@@ -42386,7 +42408,8 @@ async function credentialPreflight(deps, input) {
     ...alreadyHeld ? { alreadyHeld } : {},
     ...schema ? { schema } : {},
     blockers,
-    notChecked: [...notChecked, ...uncheckable(isVerified, isFree)]
+    notChecked: [...notChecked, ...gasNotes, ...uncheckable(isVerified, isFree)],
+    ...choice
   };
 }
 function renderAmount(raw, balance) {
@@ -42416,7 +42439,7 @@ function uncheckable(isVerified, isFree = false) {
   }
   if (isFree) {
     items.unshift(
-      "Whether issuance is still free at apply time \u2014 `paymentRequired` is a service-wide MBI setting and can change between this quote and issuance."
+      "Whether issuance is still free at apply time \u2014 whether the service charges is a service-wide setting and can change between this quote and issuance."
     );
   }
   return items;
@@ -43962,7 +43985,7 @@ async function attachAttributeMeanings(result, readVocabulary) {
 }
 
 // src/orchestrator/write-policy.ts
-var import_node_crypto6 = require("node:crypto");
+var import_node_crypto7 = require("node:crypto");
 
 // src/clients/policy-write-receipt-store.ts
 var import_node_crypto5 = require("node:crypto");
@@ -44052,6 +44075,12 @@ function parseGasPayer(value) {
   if (value === "self" || value === "sponsored") return { ok: true, gasPayer: value };
   return { ok: false };
 }
+function parseMaxGasRaw(value) {
+  if (value === void 0 || value === null || value === "") return { ok: true };
+  if (typeof value === "number" && Number.isSafeInteger(value) && value > 0) return { ok: true, maxGasRaw: String(value) };
+  if (typeof value === "string" && /^[1-9]\d{0,17}$/.test(value)) return { ok: true, maxGasRaw: value };
+  return { ok: false };
+}
 var UINT = /^\d+$/;
 var RESERVE_DIVISOR = 5n;
 var MAX_REASON = 200;
@@ -44124,6 +44153,7 @@ async function assessSelfPay(deps, call) {
 }
 
 // src/orchestrator/policy-self-pay.ts
+var import_node_crypto6 = require("node:crypto");
 var SCALAR_OF = {
   STRING: "STRING",
   NUMBER: "NUMBER",
@@ -44132,6 +44162,7 @@ var SCALAR_OF = {
   NUMBER_LIST: "NUMBER",
   ADDRESS_LIST: "ADDRESS"
 };
+var SELF_PAY_CEIL_LEDGERS = 60;
 var MAX_ATTRIBUTES = 64;
 var MAX_LIST_ENTRIES = 500;
 function parseList2(text) {
@@ -44225,6 +44256,9 @@ function createSelfPay(chain) {
     },
     queryNativeBalance: chain.queryNativeBalance,
     ...chain.getTransaction ? { lookupTransaction: chain.getTransaction } : {},
+    pendingSend: (policyKey) => chain.markers.get(chain.ownerAddress, policyKey),
+    clearSend: (policyKey, txHash) => chain.markers.remove(chain.ownerAddress, policyKey, txHash),
+    currentLedger: chain.currentLedger,
     async execute(call, limit) {
       const built = buildPolicyCall(call);
       if (!built.ok) return { kind: "rejected", reason: built.reason };
@@ -44250,9 +44284,17 @@ function createSelfPay(chain) {
           reason: `the node now estimates a fee of ${fee.feeLimit}, above the ${limit.maxFeeRaw} this wallet checked its balance against`
         };
       }
+      let ceil;
+      try {
+        const ledger = await chain.currentLedger();
+        if (typeof ledger !== "string" || !/^\d{1,18}$/.test(ledger)) throw new Error("the ledger number is not available");
+        ceil = (BigInt(ledger) + BigInt(SELF_PAY_CEIL_LEDGERS)).toString();
+      } catch (e) {
+        return { kind: "rejected", reason: `the ledger number could not be read, so the transaction could not be given an expiry: ${boundedReason(e)}` };
+      }
       let blob;
       try {
-        blob = chain.buildBlob({ sourceAddress: chain.ownerAddress, nonce, gasPrice: fee.gasPrice, feeLimit: ceiling.toString(), operations: [operation] }).blob;
+        blob = chain.buildBlob({ sourceAddress: chain.ownerAddress, nonce, gasPrice: fee.gasPrice, feeLimit: ceiling.toString(), ceilLedgerSeq: ceil, operations: [operation] }).blob;
       } catch (e) {
         return { kind: "rejected", reason: `the transaction could not be built: ${boundedReason(e)}` };
       }
@@ -44264,12 +44306,37 @@ function createSelfPay(chain) {
         if (refusal) return { kind: "refused", refusal };
         return { kind: "sign_failed", reason: boundedReason(e) };
       }
+      const txHash = (0, import_node_crypto6.createHash)("sha256").update(Buffer.from(blob, "hex")).digest("hex");
+      const marker = {
+        policyKey: call.policyKey,
+        ownerAddress: chain.ownerAddress,
+        operation: call.operation,
+        nonce,
+        txHash,
+        ceilLedgerSeq: ceil,
+        submittedAt: (chain.now?.() ?? /* @__PURE__ */ new Date()).toISOString()
+      };
+      try {
+        await chain.markers.set(marker);
+      } catch (e) {
+        try {
+          await chain.markers.remove(chain.ownerAddress, call.policyKey, txHash);
+        } catch {
+        }
+        return { kind: "rejected", reason: `the send could not be recorded, so nothing was sent: ${boundedReason(e)}` };
+      }
       try {
         const { hash } = await chain.submit({ blob, signBlob: signed.signBlob, publicKey: signed.publicKey });
-        return { kind: "submitted", txHash: hash, nonce, feeLimit: ceiling.toString() };
+        return { kind: "submitted", txHash: hash, nonce, feeLimit: ceiling.toString(), ceilLedgerSeq: ceil };
       } catch (e) {
-        if (isSubmitRejection(e)) return { kind: "rejected", reason: `the node rejected the transaction: ${boundedReason(e)}` };
-        return { kind: "unknown", reason: boundedReason(e), nonce };
+        if (isSubmitRejection(e)) {
+          try {
+            await chain.markers.remove(chain.ownerAddress, call.policyKey, txHash);
+          } catch {
+          }
+          return { kind: "rejected", reason: `the node rejected the transaction: ${boundedReason(e)}` };
+        }
+        return { kind: "unknown", reason: boundedReason(e), nonce, txHash, ceilLedgerSeq: ceil };
       }
     }
   };
@@ -44530,6 +44597,8 @@ function isDryRun(value) {
 async function writePolicy(deps, input) {
   const gas = parseGasPayer(input?.gasPayer);
   if (!gas.ok) return refusedGasPayer(input?.policyKey);
+  const maxGas = parseMaxGasRaw(input?.maxGasRaw);
+  if (!maxGas.ok) return refusedMaxGas(input?.policyKey);
   if (!deps.client && gas.gasPayer !== "self" && !(gas.gasPayer === void 0 && deps.selfPay)) {
     return unavailable(
       `No policy write service is configured for ${deps.network ?? "this network"}, so nothing was attempted and nothing was paid.`
@@ -44561,7 +44630,7 @@ async function writePolicy(deps, input) {
     ...input.validToBlock !== void 0 ? { validToBlock: input.validToBlock } : {},
     // A sha256 hex string: the service's column is 128 characters, and the old `${owner}-${policyKey}-${ISO}` overflowed it
     // for a policy key longer than about 65. Still unique per owner, key and moment.
-    requestKey: input.requestKey ?? (0, import_node_crypto6.createHash)("sha256").update(`${deps.ownerAddress}-${input.policyKey}-${(deps.now?.() ?? /* @__PURE__ */ new Date()).toISOString()}`).digest("hex")
+    requestKey: input.requestKey ?? (0, import_node_crypto7.createHash)("sha256").update(`${deps.ownerAddress}-${input.policyKey}-${(deps.now?.() ?? /* @__PURE__ */ new Date()).toISOString()}`).digest("hex")
   };
   const supplied = input.templateContractAddress;
   const omitted = supplied === void 0 || supplied === null || typeof supplied === "string" && supplied.trim() === "";
@@ -44616,7 +44685,8 @@ async function writePolicy(deps, input) {
       pollBudgetMs: input.pollBudgetMs ?? DEFAULT_BUDGET_MS,
       tool: "write_policy",
       verb: "write",
-      ...selfUnavailable ? { unavailable: selfUnavailable } : {}
+      ...selfUnavailable ? { unavailable: selfUnavailable } : {},
+      ...maxGas.maxGasRaw ? { maxGasRaw: maxGas.maxGasRaw } : {}
     });
   }
   if (!deps.client) {
@@ -44681,7 +44751,7 @@ async function writePolicy(deps, input) {
     ...gas.gasPayer ? { gasPayer: gas.gasPayer } : {}
   });
 }
-async function recoverInFlight(deps, client, a) {
+async function recoverInFlightLocked(deps, client, a) {
   const { pre } = a;
   const known = await deps.receipts.get(pre.blobId);
   const receipt = {
@@ -44712,6 +44782,8 @@ async function recoverInFlight(deps, client, a) {
       message: `${a.dryRun ? "DRY RUN" : "NOT CONFIRMED"} \u2014 nothing was collected. A write under "${a.policyKey}" has ALREADY BEEN PAID FOR and is waiting to be collected; the service said: "${clip2(pre.detail)}". Pass the receipt below to check_policy_write to finish it. Do not pay again.`
     };
   }
+  const heldCollect = await holdForSelfPaySend(deps, a.policyKey, COLLECT_HELD);
+  if (heldCollect) return { ...heldCollect, paid: true, paymentReceipt: pre.blobId, policyKey: a.policyKey, interpretation: a.interpretation };
   const stored = known ? operationOf(known) : void 0;
   if (stored !== void 0 && pre.operation !== void 0 && pre.operation !== stored) {
     return {
@@ -44771,6 +44843,13 @@ async function describeQuote(deps, accept) {
   }
   return { asset, amount, extra, amountHuman, affordability };
 }
+function refusedMaxGas(policyKey) {
+  return {
+    state: "refused",
+    ...typeof policyKey === "string" ? { policyKey } : {},
+    message: "maxGasRaw must be a positive whole number of raw units (micro-ZTX): the requiredRaw of the self option the user was shown, or be left out. NOTHING WAS PAID."
+  };
+}
 function refusedGasPayer(policyKey) {
   return {
     state: "refused",
@@ -44799,7 +44878,7 @@ function selfPayNotAvailable(a) {
 function selfPayWords(self2) {
   const gas = self2.gas;
   if (self2.status === "enough") {
-    return `Costs no fee, only about ${gas.estimatedHuman} of network gas (the wallet asks to hold ${gas.requiredHuman}); it holds ${self2.balance?.human}, enough.`;
+    return `Costs no fee, only about ${gas.estimatedHuman} of network gas (the wallet asks to hold ${gas.requiredHuman}, the estimate plus a fifth, and that is the figure to confirm); it holds ${self2.balance?.human}, enough.`;
   }
   return `Costs no fee, only network gas in ZTX${gas.estimatedHuman ? ` (about ${gas.estimatedHuman})` : ""}. ${self2.status === "short" ? "The wallet could NOT pay it right now" : "Whether the wallet can pay it is not known"}: ${clip2(self2.problems.join(" "), 400)}`;
 }
@@ -44844,7 +44923,7 @@ async function offerGasChoice(deps, a, accept) {
       } : {},
       ...self2 ? { self: { fee: "none", ...self2 } } : {}
     },
-    message: `CHOICE NEEDED \u2014 nothing was paid and nothing was written. ` + (both ? `There are two ways to pay to ${a.verb} this policy; ask the user which they want. ` : `Only ${quote ? "sponsored" : "self"} is available to ${a.verb} this policy right now; tell the user that and ask whether to go ahead that way. `) + `${sponsoredText} ${selfText} Say plainly what the wallet can pay right now. After the user has seen what the policy means (interpretation) and chosen, call ${a.tool} again with gasPayer ${both ? '"sponsored" or "self"' : only} and confirm: true. Never choose for the user and never pass confirm on your own judgement.`
+    message: `CHOICE NEEDED \u2014 nothing was paid and nothing was written. ` + (both ? `There are two ways to pay to ${a.verb} this policy; ask the user which they want. ` : `Only ${quote ? "sponsored" : "self"} is available to ${a.verb} this policy right now; tell the user that and ask whether to go ahead that way. `) + `${sponsoredText} ${selfText} Say plainly what the wallet can pay right now. After the user has seen what the policy means (interpretation) and chosen, call ${a.tool} again with gasPayer ${both ? '"sponsored" or "self"' : only} and confirm: true${self2 && self2.gas.requiredRaw ? `; for "self" also pass maxGasRaw "${self2.gas.requiredRaw}", the gas figure shown above, the most the user agrees to` : ""}. Never choose for the user and never pass confirm on your own judgement.`
   };
 }
 function chainMatchesCall(record2, call) {
@@ -44906,7 +44985,144 @@ async function confirmSelfWrite(deps, call, budgetMs, txHash) {
     waited += wait;
   }
 }
+var selfPayLocks = /* @__PURE__ */ new Map();
+var SELF_PAY_LOCK_WAIT_MS = 15e3;
+async function withSelfPayLock(key, waitMs, fn) {
+  const before = (selfPayLocks.get(key) ?? Promise.resolve()).catch(() => void 0);
+  let release;
+  const mine = new Promise((resolve2) => {
+    release = resolve2;
+  });
+  const tail = Promise.all([before, mine]);
+  selfPayLocks.set(key, tail);
+  let timer;
+  const acquired = await Promise.race([
+    before.then(() => true),
+    new Promise((resolve2) => {
+      timer = setTimeout(() => resolve2(false), waitMs);
+    })
+  ]);
+  clearTimeout(timer);
+  const done = () => {
+    release();
+    void tail.then(() => {
+      if (selfPayLocks.get(key) === tail) selfPayLocks.delete(key);
+    });
+  };
+  if (!acquired) {
+    done();
+    return { kind: "busy" };
+  }
+  try {
+    return { kind: "ran", value: await fn() };
+  } finally {
+    done();
+  }
+}
+var lockWaitMs = (deps) => deps.lockWaitMs ?? SELF_PAY_LOCK_WAIT_MS;
+var busyMessage = (policyKey, nothing) => `Another write, collect or removal for "${policyKey}" is in progress in this wallet, so ${nothing}. Ask again shortly.`;
+async function holdForSelfPaySend(deps, policyKey, nothing) {
+  const inFlight = await resolveInFlight(deps, policyKey);
+  if (inFlight.kind === "none") return void 0;
+  if (inFlight.kind === "unreadable") {
+    return {
+      state: "unavailable",
+      message: `Whether an earlier self-paid write for "${policyKey}" is still in flight could not be checked (${inFlight.detail ?? "the record of it could not be read"}), so ${nothing}. A transaction that is still in flight could overwrite this.`
+    };
+  }
+  const m = inFlight.marker;
+  return {
+    state: "refused",
+    txHash: m.txHash,
+    message: `A self-paid ${m.operation === "UPDATE" ? "update" : "write"} for "${policyKey}" was sent at ${m.submittedAt} (transaction ${m.txHash}, nonce ${m.nonce}) and its outcome is not known yet. It can still be included until ledger ${m.ceilLedgerSeq}${inFlight.ledger ? ` (the ledger is now ${inFlight.ledger})` : ""}, and it would replace the whole policy, so ${nothing}. Read the policy with get_my_policy to see whether it landed, or ask again after ledger ${m.ceilLedgerSeq}, when it can no longer land.`
+  };
+}
+async function resolveInFlight(deps, policyKey, mayClear = true) {
+  const sp = deps.selfPay;
+  if (!sp?.pendingSend) return { kind: "none" };
+  let marker;
+  try {
+    marker = await bounded(deps, () => sp.pendingSend(policyKey));
+  } catch (e) {
+    return { kind: "unreadable", detail: clip2(e instanceof Error ? e.message : String(e), 1200) };
+  }
+  if (!marker) return { kind: "none" };
+  const settled = marker;
+  const clear = async () => {
+    if (!mayClear) return;
+    try {
+      await sp.clearSend?.(policyKey, settled.txHash);
+    } catch {
+    }
+  };
+  if (sp.lookupTransaction) {
+    try {
+      const lookup = sp.lookupTransaction;
+      const hash = marker.txHash;
+      const tx = await bounded(deps, () => lookup(hash));
+      if (tx.status === "success" || tx.status === "failed") {
+        await clear();
+        return { kind: "none" };
+      }
+    } catch {
+    }
+  }
+  let ledger;
+  if (sp.currentLedger) {
+    try {
+      const read2 = sp.currentLedger;
+      ledger = await bounded(deps, () => read2());
+    } catch {
+      ledger = void 0;
+    }
+  }
+  if (typeof ledger === "string" && /^\d{1,18}$/.test(ledger) && BigInt(ledger) > BigInt(marker.ceilLedgerSeq)) {
+    await clear();
+    return { kind: "none" };
+  }
+  return { kind: "blocked", marker, ...typeof ledger === "string" && /^\d{1,18}$/.test(ledger) ? { ledger } : {} };
+}
+var selfPayLockKey = (deps, policyKey) => `${deps.ownerAddress}
+${policyKey}`;
 async function runSelfPay(deps, a) {
+  if (!a.canWrite) return runSelfPayLocked(deps, a);
+  const r = await withSelfPayLock(selfPayLockKey(deps, a.call.policyKey), lockWaitMs(deps), () => runSelfPayLocked(deps, a));
+  if (r.kind === "ran") return r.value;
+  return { state: "refused", paid: false, policyKey: a.call.policyKey, interpretation: a.interpretation, message: busyMessage(a.call.policyKey, "NOTHING WAS SENT") };
+}
+async function recoverInFlight(deps, client, a) {
+  if (!a.canWrite) return recoverInFlightLocked(deps, client, a);
+  const r = await withSelfPayLock(selfPayLockKey(deps, a.policyKey), lockWaitMs(deps), () => recoverInFlightLocked(deps, client, a));
+  if (r.kind === "ran") return r.value;
+  return {
+    state: "refused",
+    paid: true,
+    paymentReceipt: a.pre.blobId,
+    policyKey: a.policyKey,
+    interpretation: a.interpretation,
+    message: busyMessage(a.policyKey, COLLECT_HELD)
+  };
+}
+async function runPaidFlow(deps, client, a) {
+  const choosing = a.gasPayer === void 0 && deps.selfPay !== void 0;
+  if (!a.canWrite || choosing) return runPaidFlowLocked(deps, client, a);
+  const r = await withSelfPayLock(selfPayLockKey(deps, a.policyKey), lockWaitMs(deps), () => runPaidFlowLocked(deps, client, a));
+  if (r.kind === "ran") return r.value;
+  return { state: "refused", paid: false, policyKey: a.policyKey, interpretation: a.interpretation, message: busyMessage(a.policyKey, "NOTHING WAS PAID") };
+}
+var COLLECT_HELD = "NOTHING WAS COLLECTED (the earlier payment is not lost: do not pay again, ask again later)";
+async function collectUnlessSelfPayHeld(deps, receipt, budgetMs) {
+  const r = await withSelfPayLock(selfPayLockKey(deps, receipt.policyKey), lockWaitMs(deps), async () => {
+    const applied = await checkChainFirst(deps, receipt);
+    if (applied) return applied;
+    const held = await holdForSelfPaySend(deps, receipt.policyKey, COLLECT_HELD);
+    if (held) return { ...held, paid: true, paymentReceipt: receipt.blobId, policyKey: receipt.policyKey };
+    return pollCollect(deps, deps.client, receipt, budgetMs);
+  });
+  if (r.kind === "ran") return r.value;
+  return { state: "refused", paid: true, paymentReceipt: receipt.blobId, policyKey: receipt.policyKey, message: busyMessage(receipt.policyKey, COLLECT_HELD) };
+}
+async function runSelfPayLocked(deps, a) {
   const { call, interpretation } = a;
   const policyKey = call.policyKey;
   const done = a.verb === "write" ? "written" : "updated";
@@ -44934,6 +45150,22 @@ async function runSelfPay(deps, a) {
       message: `A paid write for "${policyKey}" is still waiting to be finished (receipt ${waiting.blobId}), and a self-paid write now could be overwritten by its collect, or overwrite it. Finish it first with check_policy_write, then ask again. NOTHING WAS SENT.`
     };
   }
+  const inFlight = await resolveInFlight(deps, policyKey, a.canWrite);
+  if (inFlight.kind === "unreadable") {
+    return unavailable(
+      'Whether an earlier self-paid write for "' + policyKey + '" is still in flight could not be checked (' + (inFlight.detail ?? "the record of it could not be read") + "), so NOTHING WAS SENT."
+    );
+  }
+  if (inFlight.kind === "blocked") {
+    const m = inFlight.marker;
+    return {
+      state: "unknown",
+      policyKey,
+      txHash: m.txHash,
+      interpretation,
+      message: `A self-paid ${m.operation === "UPDATE" ? "update" : "write"} for "${policyKey}" was sent at ${m.submittedAt} (transaction ${m.txHash}, nonce ${m.nonce}) and its outcome is not known yet. It can still be included until ledger ${m.ceilLedgerSeq}${inFlight.ledger ? ` (the ledger is now ${inFlight.ledger})` : ""}, so NOTHING WAS SENT this time: a second transaction could land on top of it. Read the policy with get_my_policy to see whether it landed, or ask again after ledger ${m.ceilLedgerSeq}, when it can no longer land.`
+    };
+  }
   let current;
   try {
     current = await readBounded(deps, policyKey);
@@ -44975,7 +45207,7 @@ async function runSelfPay(deps, a) {
       policyKey,
       interpretation,
       gasOptions: { self: self2 },
-      message: `QUOTE ONLY \u2014 nothing was sent and nothing was written. Paying the gas yourself: ${selfPayWords(assessment)} ` + (!a.dryRun && !a.confirmed ? `A policy is a spending limit, so a person must agree to it first: show the user what it means (interpretation) and the cost, and only after they say yes call ${a.tool} again with gasPayer "self" and confirm: true. Never pass confirm on your own judgement.` : assessment.status === "enough" ? `Ask again without dryRun to ${a.verb} it.` : "Fix that, then ask again without dryRun.")
+      message: `QUOTE ONLY \u2014 nothing was sent and nothing was written. Paying the gas yourself: ${selfPayWords(assessment)} ` + (!a.dryRun && !a.confirmed ? `A policy is a spending limit, so a person must agree to it first: show the user what it means (interpretation) and the cost, and only after they say yes call ${a.tool} again with gasPayer "self"${assessment.gas.requiredRaw ? `, maxGasRaw "${assessment.gas.requiredRaw}" (the gas figure above)` : ""} and confirm: true. Never pass confirm on your own judgement.` : assessment.status === "enough" ? `Ask again without dryRun to ${a.verb} it, with gasPayer "self" and maxGasRaw "${assessment.gas.requiredRaw}".` : "Fix that, then ask again without dryRun.")
     };
   }
   if (assessment.status !== "enough") {
@@ -44988,7 +45220,28 @@ async function runSelfPay(deps, a) {
       message: `NOTHING WAS SENT: the wallet cannot confirm it can pay the gas. ${clip2(assessment.problems.join(" "), 500)} ` + (assessment.status === "short" ? 'Top up ZTX or use gasPayer "sponsored".' : 'Fix the cause above and ask again, or use gasPayer "sponsored".')
     };
   }
-  const sent = await deps.selfPay.execute(call, { maxFeeRaw: assessment.gas.requiredRaw });
+  const requiredRaw = assessment.gas.requiredRaw;
+  if (a.maxGasRaw === void 0) {
+    return {
+      state: "refused",
+      paid: false,
+      policyKey,
+      interpretation,
+      gasOptions: { self: self2 },
+      message: `NOTHING WAS SENT: a self-paid write needs maxGasRaw, the most gas the user agreed to, so it can never cost more than they were shown. The gas the wallet asks to hold for this write is now ${assessment.gas.requiredHuman} (${requiredRaw} raw: the estimate plus a fifth). Show the user that figure and, if they agree, call ${a.tool} again with gasPayer "self", maxGasRaw "${requiredRaw}" and confirm: true.`
+    };
+  }
+  if (BigInt(requiredRaw) > BigInt(a.maxGasRaw)) {
+    return {
+      state: "refused",
+      paid: false,
+      policyKey,
+      interpretation,
+      gasOptions: { self: self2 },
+      message: `NOTHING WAS SENT: the gas the wallet asks to hold for this write is now ${assessment.gas.requiredHuman} (${requiredRaw} raw: the estimate plus a fifth), more than the ${a.maxGasRaw} raw the user agreed to. Show the user the new figure and, if they agree, call ${a.tool} again with gasPayer "self", maxGasRaw "${requiredRaw}" and confirm: true.`
+    };
+  }
+  const sent = await deps.selfPay.execute(call, { maxFeeRaw: requiredRaw });
   switch (sent.kind) {
     case "rejected":
       return { state: "refused", paid: false, policyKey, interpretation, message: `NOTHING WAS SENT and no gas was spent: ${sent.reason}. Fix the cause and ask again.` };
@@ -45018,11 +45271,18 @@ async function runSelfPay(deps, a) {
       return {
         state: "unknown",
         policyKey,
+        txHash: sent.txHash,
         interpretation,
-        message: `The transaction was sent but the node's answer never arrived (${sent.reason}), so it MAY be on chain and the gas MAY be spent. Do NOT send it again. Read the policy with get_my_policy to see whether it took effect (sent with nonce ${sent.nonce}).`
+        message: `The transaction was sent but the node's answer never arrived (${sent.reason}), so it MAY be on chain and the gas MAY be spent. Do NOT send it again. Read the policy with get_my_policy to see whether it took effect (transaction ${sent.txHash}, nonce ${sent.nonce}). It can be included only until ledger ${sent.ceilLedgerSeq}; this wallet remembers it and will not send another for this key until it has landed or can no longer land.`
       };
     case "submitted": {
       const landed = await confirmSelfWrite(deps, call, a.pollBudgetMs, sent.txHash);
+      if (landed.kind !== "not_yet") {
+        try {
+          await deps.selfPay.clearSend?.(policyKey, sent.txHash);
+        } catch {
+        }
+      }
       if (landed.kind === "failed") {
         return {
           state: "write_failed",
@@ -45054,7 +45314,7 @@ async function runSelfPay(deps, a) {
     }
   }
 }
-async function runPaidFlow(deps, client, a) {
+async function runPaidFlowLocked(deps, client, a) {
   const { policyKey, interpretation, dryRun, confirmed, canWrite } = a;
   const accepts = a.challenge.accepts ?? [];
   const offersChoice = a.gasPayer === void 0 && deps.selfPay !== void 0;
@@ -45088,6 +45348,8 @@ async function runPaidFlow(deps, client, a) {
       message: `QUOTE ONLY \u2014 nothing was paid and nothing was written. The service asked for ${amountHuman ?? `${amount} of ${asset}`} to ${a.verb} this policy. That is what it asked for just now: it can change, and it is not a promise the payment will be allowed, because ` + (worded ? `balances can change and the payment cap is enforced again when paying. ${worded} ` : `the wallet's payment cap is applied only when paying. `) + (!dryRun && !confirmed ? `A policy is a spending limit, so a person must agree to it first: show the user what it means (interpretation) and the price, and only after they say yes call ${a.tool} again with confirm: true. Never pass confirm on your own judgement.` + (affordability?.verdict === "not_affordable" ? " Fix the affordability problem above first." : "") : affordability?.verdict === "not_affordable" ? "Fix that, then ask again without dryRun to deploy." : "Ask again without dryRun to deploy.")
     };
   }
+  const held = await holdForSelfPaySend(deps, policyKey, "NOTHING WAS PAID");
+  if (held) return { ...held, paid: false, policyKey, interpretation };
   let paymentHeader;
   try {
     paymentHeader = await deps.pay(accept);
@@ -45161,14 +45423,14 @@ async function checkPolicyWrite(deps, input = {}) {
     }
     if (pending.length > 1) {
       const others = pending.slice(1).map((r) => `${r.policyKey} (${r.blobId})`).join(", ");
-      const result = await checkChainFirst(deps, receipt) ?? await pollCollect(deps, deps.client, receipt, input.pollBudgetMs ?? DEFAULT_BUDGET_MS);
+      const result = await collectUnlessSelfPayHeld(deps, receipt, input.pollBudgetMs ?? DEFAULT_BUDGET_MS);
       return {
         ...result,
         message: `${result.message} NOTE: ${pending.length} paid-for writes are on file and this checked the most recent one only. The others are: ${others}. Check each by passing its receipt.`
       };
     }
   }
-  return await checkChainFirst(deps, receipt) ?? pollCollect(deps, deps.client, receipt, input.pollBudgetMs ?? DEFAULT_BUDGET_MS);
+  return collectUnlessSelfPayHeld(deps, receipt, input.pollBudgetMs ?? DEFAULT_BUDGET_MS);
 }
 async function checkChainFirst(deps, receipt) {
   const shows = await chainShows(deps, receipt);
@@ -45189,6 +45451,8 @@ function blockString(value) {
 async function updatePolicy(deps, input) {
   const gas = parseGasPayer(input?.gasPayer);
   if (!gas.ok) return refusedGasPayer(input?.policyKey);
+  const maxGas = parseMaxGasRaw(input?.maxGasRaw);
+  if (!maxGas.ok) return refusedMaxGas(input?.policyKey);
   const client = deps.client;
   if (!client && gas.gasPayer !== "self" && !(gas.gasPayer === void 0 && deps.selfPay)) {
     return unavailable(
@@ -45338,7 +45602,8 @@ async function updatePolicy(deps, input) {
       pollBudgetMs: input.pollBudgetMs ?? DEFAULT_BUDGET_MS,
       tool: "update_policy",
       verb: "update",
-      ...blocker ? { unavailable: blocker } : {}
+      ...blocker ? { unavailable: blocker } : {},
+      ...maxGas.maxGasRaw ? { maxGasRaw: maxGas.maxGasRaw } : {}
     });
   }
   const selfUnavailable = blocker ?? (!selfCall ? NO_WINDOW_REASON : void 0);
@@ -45422,6 +45687,12 @@ var REMOVE_CONSEQUENCE = "Removing a policy removes every limit it set, and Wall
 var NEVER_TWICE = "Calling remove_policy again is expected to be safe: the service is expected not to submit a second removal for a policy that is already being removed.";
 var IN_PROGRESS_MESSAGE = (detail) => `A write for this policy has ALREADY BEEN PAID FOR and is still being completed by the service (${detail}). Do not pay again, and nothing was paid by this call. If this wallet holds its receipt, check_policy_write finishes it; otherwise wait and read the policy back later with get_my_policy to see whether it took effect.`;
 async function removePolicy(deps, input) {
+  if (!(input?.confirm === true && typeof input.policyKey === "string" && input.policyKey !== "")) return removePolicyLocked(deps, input);
+  const r = await withSelfPayLock(selfPayLockKey(deps, input.policyKey), lockWaitMs(deps), () => removePolicyLocked(deps, input));
+  if (r.kind === "ran") return r.value;
+  return { state: "refused", policyKey: input.policyKey, message: busyMessage(input.policyKey, "NOTHING WAS REMOVED") };
+}
+async function removePolicyLocked(deps, input) {
   const client = deps.client;
   if (!client) {
     return {
@@ -45457,6 +45728,8 @@ async function removePolicy(deps, input) {
       message: `NOTHING WAS REMOVED. ${REMOVE_CONSEQUENCE} Show the user what the policy "${input.policyKey}" currently limits${attributes ? " (currentAttributes)" : ""} and what removing it means, and only if they clearly agree call remove_policy again with confirm: true. Never pass confirm on your own judgement.`
     };
   }
+  const heldRemove = await holdForSelfPaySend(deps, input.policyKey, "NOTHING WAS REMOVED");
+  if (heldRemove) return { state: heldRemove.state, policyKey: input.policyKey, message: heldRemove.message };
   const result = await client.remove(deps.ownerAddress, input.policyKey, deps.hsmPassword);
   switch (result.kind) {
     case "not_found":
@@ -45513,11 +45786,11 @@ async function removePolicy(deps, input) {
   const started = (deps.now?.() ?? /* @__PURE__ */ new Date()).getTime();
   let polls = 0;
   let waited = 0;
-  let unreadable = false;
+  let unreadable2 = false;
   for (; ; ) {
     const read2 = await deps.readPolicy(input.policyKey);
     if ("error" in read2) {
-      unreadable = true;
+      unreadable2 = true;
     } else if (read2.found === false) {
       return {
         state: "removed",
@@ -45526,7 +45799,7 @@ async function removePolicy(deps, input) {
         message: `The policy "${input.policyKey}" is removed: the chain no longer holds it. Its limits no longer apply.`
       };
     } else {
-      unreadable = false;
+      unreadable2 = false;
     }
     const elapsed = Math.max((deps.now?.() ?? /* @__PURE__ */ new Date()).getTime() - started, waited);
     if (++polls >= MAX_POLLS || elapsed + wait >= budget) break;
@@ -45534,7 +45807,7 @@ async function removePolicy(deps, input) {
     waited += wait;
   }
   return submittedMessage(
-    unreadable ? "the chain could not be read to confirm it." : "the chain still shows the policy, so the block has not confirmed the removal yet."
+    unreadable2 ? "the chain could not be read to confirm it." : "the chain still shows the policy, so the block has not confirmed the removal yet."
   );
 }
 
@@ -45759,6 +46032,17 @@ async function transferToken(deps, opts) {
 var DEFAULT_EXPIRY_MINUTES = 5;
 var MAX_EXPIRY_MINUTES = 60;
 var MAX_REVEAL_PATHS = 50;
+function qrGuidance(qrCodePath, hasQrImage) {
+  const fallback = "If you cannot attach an image in this chat, give the user the link and say plainly that you could not send the QR code.";
+  const never2 = "Never send any other image as the QR code, and never call another image a QR code: the credential's pass design is not one.";
+  if (qrCodePath !== void 0) {
+    return `Send the user the QR code by attaching the file at ${qrCodePath} (the same image is also returned with this result, as its first image; any other image is not the QR code). ${never2} ${fallback} Also give them the link.`;
+  }
+  if (hasQrImage) {
+    return `There is no QR image file this time, so give the user the link. The QR code is the first image returned with this result; any other image is not the QR code. ${never2} If your channel cannot show images, say plainly that you could not send the QR code.`;
+  }
+  return `No QR code could be made this time, so give the user the link and say plainly that you could not send a QR code. Any image returned with this result is not the QR code. ${never2}`;
+}
 function buildVerificationLink(template, referenceId) {
   const problem = checkVerifyLinkTemplate(template);
   if (problem) throw new Error(problem);
@@ -45852,8 +46136,20 @@ async function createVerificationLink(input, deps) {
   const expiresAt = new Date(startedAt + expiryMinutes * 6e4).toISOString();
   let qrCodePngBase64;
   let qrError;
+  let qrCodePath;
+  let qrFileError;
   try {
-    qrCodePngBase64 = (await deps.renderQr(link)).toString("base64");
+    const png = await deps.renderQr(link);
+    if (png.length === 0) throw new Error("the QR renderer returned nothing");
+    qrCodePngBase64 = png.toString("base64");
+    if (deps.saveQr) {
+      try {
+        qrCodePath = await deps.saveQr(png, referenceId, startedAt + expiryMinutes * 6e4);
+      } catch (e) {
+        const code = e?.code;
+        qrFileError = typeof code === "string" && /^[A-Z0-9_]{1,32}$/.test(code) ? `could not write the QR file (${code})` : "could not write the QR file";
+      }
+    }
   } catch (e) {
     qrError = messageOf(e);
   }
@@ -45866,7 +46162,9 @@ async function createVerificationLink(input, deps) {
     revealed: revealed.revealed,
     ...qrCodePngBase64 !== void 0 ? { qrCodePngBase64 } : {},
     ...qrError !== void 0 ? { qrError } : {},
-    message: `Show the user the QR code and the link, and tell them to open it in the MyID app (they need MyID installed first). It stops working at about ${expiresAt}, ${expiryMinutes} minute${expiryMinutes === 1 ? "" : "s"} after it was created \u2014 if it lapses, create a new one. This ${revealed.revealed === "all" ? "reveals the whole credential" : `reveals: ${revealed.revealed.map((p) => JSON.stringify(p)).join(", ")}`}. Show it only to the user: whoever holds the link can open what it reveals until then.`
+    ...qrCodePath !== void 0 ? { qrCodePath } : {},
+    ...qrFileError !== void 0 ? { qrFileError } : {},
+    message: `${qrGuidance(qrCodePath, qrCodePngBase64 !== void 0)} Tell them to open the link in the MyID app (they need MyID installed first). It stops working at about ${expiresAt}, ${expiryMinutes} minute${expiryMinutes === 1 ? "" : "s"} after it was created \u2014 if it lapses, create a new one. This ${revealed.revealed === "all" ? "reveals the whole credential" : `reveals: ${revealed.revealed.map((p) => JSON.stringify(p)).join(", ")}`}. Show it only to the user: whoever holds the link can open what it reveals until then.`
   };
 }
 
@@ -45941,6 +46239,7 @@ function createTools(deps) {
       let vc = input.vc;
       let credentialUsed = "the credential you supplied";
       let kind;
+      let savedPassImages;
       const wantsDefault = (input.revealAttribute === void 0 || input.revealAttribute.length === 0) && input.revealAll !== true;
       const verifiedId = deps.config.aiBirthcertVerifiedTemplateId;
       const basicId = resolveTemplateAlias("ai birthcert", deps.config.network);
@@ -45956,11 +46255,13 @@ function createTools(deps) {
           };
         }
         vc = chosen.vc;
+        savedPassImages = chosen.vcPassImagePaths;
         credentialUsed = verified ? "Verified AI Birthcert" : "Basic AI Birthcert";
         kind = verified ? "verified" : "basic";
       } else if (wantsDefault && typeof vc === "object" && vc !== null && !Array.isArray(vc)) {
         const id = vc.id;
         const match = typeof id === "string" ? (await loadValidCachedCredentials(deps.cache)).find((e) => e.vc?.id === id) : void 0;
+        savedPassImages = match?.vcPassImagePaths;
         if (match && verifiedId && match.templateId === verifiedId) kind = "verified";
         else if (match && basicId && match.templateId === basicId) kind = "basic";
       }
@@ -45996,12 +46297,16 @@ function createTools(deps) {
         expiryMinutes: input.expiryMinutes
       });
       if (!result.created) return result;
+      const passImages = savedPassImages ? await existingFiles(savedPassImages) : [];
       const basicNote = kind === "basic" ? " This is a Basic AI Birthcert: it shows the agent's registered username only and does not mean the owner was verified, so do not describe the agent as owner-verified." : "";
+      const passNote = passImages.length > 0 ? " The credential's pass design image is also returned (vcPassImagePaths): if the user wants to see it, send it as its own picture, captioned as the credential's pass design. It is not the QR code." : "";
+      const extra = basicNote + passNote;
       return {
         ...result,
         credentialUsed,
         ...revealedByDefault ? { revealedByDefault: true } : {},
-        ...basicNote ? { message: result.message + basicNote } : {}
+        ...passImages.length > 0 ? { vcPassImagePaths: passImages } : {},
+        ...extra ? { message: result.message + extra } : {}
       };
     },
     pay_and_fetch(input) {
@@ -46090,7 +46395,14 @@ function createTools(deps) {
      */
     async credential_preflight(input) {
       if (input.credential === VERIFIED_AI_BIRTHCERT && !deps.verifyAiBirthcert) {
-        return { credential: input.credential, ready: false, balances: [], blockers: [AI_BIRTHCERT_NOT_CONFIGURED_ERROR], notChecked: [] };
+        return {
+          credential: input.credential,
+          ready: false,
+          balances: [],
+          blockers: [AI_BIRTHCERT_NOT_CONFIGURED_ERROR],
+          notChecked: [],
+          choice: aiBirthcertChoice("verified", { unavailable: true })
+        };
       }
       if (!deps.queryTokenBalance) {
         return {
@@ -46101,8 +46413,11 @@ function createTools(deps) {
           notChecked: []
         };
       }
+      const basicId = resolveTemplateAlias("ai birthcert", deps.config.network);
+      const isBasicAiBirthcert = (credential) => basicId !== void 0 && (credential === basicId || resolveTemplateAlias(credential, deps.config.network) === basicId);
       return credentialPreflight(
         {
+          isBasicAiBirthcert,
           quoteVerified: (q) => deps.verifyAiBirthcert.request(q),
           quoteTemplate: async (templateId) => {
             const resolved = resolveTemplateAlias(templateId, deps.config.network) ?? templateId;
@@ -46365,6 +46680,17 @@ async function priceTemplate(deps, tools, templateId) {
     ...schema ? { schema } : {}
   };
 }
+async function existingFiles(paths) {
+  const found = [];
+  for (const path of paths) {
+    try {
+      await (0, import_promises4.access)(path);
+      found.push(path);
+    } catch {
+    }
+  }
+  return found;
+}
 
 // src/held-credential.ts
 function createHeldCredentialFinder(deps) {
@@ -47097,6 +47423,57 @@ async function renderQrPng(text) {
   ]);
 }
 
+// src/qr-file-store.ts
+var import_node_crypto8 = require("node:crypto");
+var import_promises5 = require("node:fs/promises");
+var import_node_path5 = require("node:path");
+var PREFIX = "verification-qr-";
+var OWN_FILE = /^verification-qr-[a-z0-9]{1,8}-(\d+)-[a-f0-9]{6}\.png$/;
+function tagFor(referenceId) {
+  const tag = referenceId.toLowerCase().replace(/^v2-/, "").replace(/[^a-z0-9]/g, "").slice(0, 8);
+  return tag === "" ? "qr" : tag;
+}
+function createFsQrFileStore(dir, opts = {}) {
+  const now = opts.now ?? Date.now;
+  const randomSuffix = opts.randomSuffix ?? (() => (0, import_node_crypto8.randomBytes)(3).toString("hex"));
+  const root = (0, import_node_path5.resolve)(dir);
+  async function removeExpired() {
+    let names;
+    try {
+      names = await (0, import_promises5.readdir)(root);
+    } catch {
+      return;
+    }
+    const at = now();
+    for (const name of names) {
+      const m = OWN_FILE.exec(name);
+      if (!m) continue;
+      if (Number(m[1]) > at) continue;
+      try {
+        await (0, import_promises5.unlink)((0, import_node_path5.join)(root, name));
+      } catch {
+      }
+    }
+  }
+  return {
+    async save(png, referenceId, expiresAtMs) {
+      await (0, import_promises5.mkdir)(root, { recursive: true, mode: 448 });
+      await removeExpired();
+      for (let attempt = 0; ; attempt++) {
+        const name = `${PREFIX}${tagFor(referenceId)}-${Math.floor(expiresAtMs)}-${randomSuffix()}.png`;
+        const path = (0, import_node_path5.join)(root, name);
+        try {
+          await (0, import_promises5.writeFile)(path, png, { mode: 384, flag: "wx" });
+          return path;
+        } catch (e) {
+          if (e.code !== "EEXIST" || attempt >= 4) throw e;
+        }
+      }
+    },
+    sweep: removeExpired
+  };
+}
+
 // src/policy-cap-bypass.ts
 var NATIVE2 = "ZTX";
 var RAW_AMOUNT2 = /^\d{1,77}$/;
@@ -47163,8 +47540,8 @@ function createPolicyGovernsCheck(options) {
     const pending = inFlight;
     pending.catch(() => void 0);
     let timer;
-    const timedOut = new Promise((resolve) => {
-      timer = setTimeout(() => resolve(TIMED_OUT), timeoutMs);
+    const timedOut = new Promise((resolve2) => {
+      timer = setTimeout(() => resolve2(TIMED_OUT), timeoutMs);
     });
     try {
       const result = await Promise.race([pending, timedOut]);
@@ -47262,12 +47639,12 @@ function configPathFrom(argv) {
   if (!path || path.startsWith("--")) throw new Error("agentic-wallet-mcp: --config requires a file path");
   return path;
 }
-function loadConfigFileEnv(argv, readFile7) {
+function loadConfigFileEnv(argv, readFile8) {
   const path = configPathFrom(argv);
   if (path === null) return {};
   let raw;
   try {
-    raw = readFile7(path);
+    raw = readFile8(path);
   } catch (e) {
     throw new Error(`agentic-wallet-mcp: cannot read config file ${path}: ${e.message}`);
   }
@@ -47299,9 +47676,9 @@ function loadConfigFileEnv(argv, readFile7) {
 }
 
 // src/hsm-password.ts
-var import_node_crypto7 = require("node:crypto");
+var import_node_crypto9 = require("node:crypto");
 function generateHsmPassword() {
-  return (0, import_node_crypto7.randomBytes)(24).toString("base64url");
+  return (0, import_node_crypto9.randomBytes)(24).toString("base64url");
 }
 
 // src/export-credentials.ts
@@ -47338,8 +47715,8 @@ permanently inaccessible.
 }
 
 // src/clients/account-store.ts
-var import_promises4 = require("node:fs/promises");
-var import_node_path5 = require("node:path");
+var import_promises6 = require("node:fs/promises");
+var import_node_path6 = require("node:path");
 function isStoredAccountShape(value) {
   return typeof value === "object" && value !== null && typeof value.zetrixAddress === "string" && typeof value.holderDid === "string" && typeof value.hsmPassword === "string";
 }
@@ -47347,7 +47724,7 @@ function createFsAccountStore(filePath) {
   return {
     async get() {
       try {
-        const raw = await (0, import_promises4.readFile)(filePath, "utf8");
+        const raw = await (0, import_promises6.readFile)(filePath, "utf8");
         const parsed = JSON.parse(raw);
         return isStoredAccountShape(parsed) ? parsed : null;
       } catch {
@@ -47355,8 +47732,8 @@ function createFsAccountStore(filePath) {
       }
     },
     async set(account) {
-      await (0, import_promises4.mkdir)((0, import_node_path5.dirname)(filePath), { recursive: true, mode: 448 });
-      await (0, import_promises4.writeFile)(filePath, JSON.stringify(account, null, 2), { encoding: "utf8", mode: 384 });
+      await (0, import_promises6.mkdir)((0, import_node_path6.dirname)(filePath), { recursive: true, mode: 448 });
+      await (0, import_promises6.writeFile)(filePath, JSON.stringify(account, null, 2), { encoding: "utf8", mode: 384 });
     }
   };
 }
@@ -47374,13 +47751,13 @@ function splitQrCode(result) {
   if (typeof qrCodePngBase64 !== "string" || qrCodePngBase64 === "") return { text: result };
   return { text: rest, qrCodePngBase64 };
 }
-async function buildToolContent(result, readFile7) {
+async function buildToolContent(result, readFile8) {
   const { text, qrCodePngBase64 } = splitQrCode(result);
   const blocks = [{ type: "text", text: JSON.stringify(text) }];
   if (qrCodePngBase64 !== void 0) blocks.push({ type: "image", data: qrCodePngBase64, mimeType: "image/png" });
   for (const path of extractVcPassImagePaths(result)) {
     try {
-      const data = await readFile7(path);
+      const data = await readFile8(path);
       blocks.push({ type: "image", data: data.toString("base64"), mimeType: "image/png" });
     } catch {
     }
@@ -47529,8 +47906,8 @@ var SsivcClient = class {
 };
 
 // src/clients/ssivc-session-store.ts
-var import_promises5 = require("node:fs/promises");
-var import_node_path6 = require("node:path");
+var import_promises7 = require("node:fs/promises");
+var import_node_path7 = require("node:path");
 var isAbsentOrString = (v) => v === void 0 || typeof v === "string";
 function isStoredSessionShape(value) {
   if (typeof value !== "object" || value === null) return false;
@@ -47541,7 +47918,7 @@ function createFsSsivcSessionStore(filePath) {
   return {
     async get() {
       try {
-        const raw = await (0, import_promises5.readFile)(filePath, "utf8");
+        const raw = await (0, import_promises7.readFile)(filePath, "utf8");
         const parsed = JSON.parse(raw);
         return isStoredSessionShape(parsed) ? parsed : null;
       } catch (err) {
@@ -47551,23 +47928,23 @@ function createFsSsivcSessionStore(filePath) {
       }
     },
     async set(session) {
-      await (0, import_promises5.mkdir)((0, import_node_path6.dirname)(filePath), { recursive: true, mode: 448 });
+      await (0, import_promises7.mkdir)((0, import_node_path7.dirname)(filePath), { recursive: true, mode: 448 });
       const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
-      await (0, import_promises5.writeFile)(tmpPath, JSON.stringify(session, null, 2), { encoding: "utf8", mode: 384 });
-      await (0, import_promises5.rename)(tmpPath, filePath);
+      await (0, import_promises7.writeFile)(tmpPath, JSON.stringify(session, null, 2), { encoding: "utf8", mode: 384 });
+      await (0, import_promises7.rename)(tmpPath, filePath);
     },
     async clear() {
-      await (0, import_promises5.rm)(filePath, { force: true });
+      await (0, import_promises7.rm)(filePath, { force: true });
     }
   };
 }
 
 // src/clients/ssivc-download-quarantine-store.ts
-var import_node_crypto8 = require("node:crypto");
-var import_promises6 = require("node:fs/promises");
-var import_node_path7 = require("node:path");
+var import_node_crypto10 = require("node:crypto");
+var import_promises8 = require("node:fs/promises");
+var import_node_path8 = require("node:path");
 function quarantineFileName(vcId) {
-  return `${(0, import_node_crypto8.createHash)("sha256").update(vcId).digest("hex")}.json`;
+  return `${(0, import_node_crypto10.createHash)("sha256").update(vcId).digest("hex")}.json`;
 }
 function isQuarantinedDownloadShape(value) {
   if (typeof value !== "object" || value === null) return false;
@@ -47575,7 +47952,7 @@ function isQuarantinedDownloadShape(value) {
   return typeof v.vcId === "string" && "entries" in v && typeof v.downloadedAt === "string";
 }
 function createFsDownloadQuarantineStore(baseDir) {
-  const pathFor = (vcId) => (0, import_node_path7.join)(baseDir, quarantineFileName(vcId));
+  const pathFor = (vcId) => (0, import_node_path8.join)(baseDir, quarantineFileName(vcId));
   const locks = /* @__PURE__ */ new Map();
   return {
     filePathFor: pathFor,
@@ -47590,7 +47967,7 @@ function createFsDownloadQuarantineStore(baseDir) {
     },
     async get(vcId) {
       try {
-        const raw = await (0, import_promises6.readFile)(pathFor(vcId), "utf8");
+        const raw = await (0, import_promises8.readFile)(pathFor(vcId), "utf8");
         const parsed = JSON.parse(raw);
         return isQuarantinedDownloadShape(parsed) ? parsed : null;
       } catch {
@@ -47598,17 +47975,17 @@ function createFsDownloadQuarantineStore(baseDir) {
       }
     },
     async set(entry) {
-      await (0, import_promises6.mkdir)(baseDir, { recursive: true, mode: 448 });
+      await (0, import_promises8.mkdir)(baseDir, { recursive: true, mode: 448 });
       const filePath = pathFor(entry.vcId);
       const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
-      await (0, import_promises6.writeFile)(tmpPath, JSON.stringify(entry, null, 2), { encoding: "utf8", mode: 384 });
-      await (0, import_promises6.rename)(tmpPath, filePath);
+      await (0, import_promises8.writeFile)(tmpPath, JSON.stringify(entry, null, 2), { encoding: "utf8", mode: 384 });
+      await (0, import_promises8.rename)(tmpPath, filePath);
     }
   };
 }
 
 // src/orchestrator/verify-ai-birthcert.ts
-var import_node_crypto9 = require("node:crypto");
+var import_node_crypto11 = require("node:crypto");
 
 // src/canonical-json.ts
 function canonicalizeJson(value) {
@@ -47734,7 +48111,7 @@ function retryDelayMs(retryAfterSeconds) {
   if (!Number.isFinite(retryAfterSeconds) || retryAfterSeconds <= 0) return FALLBACK_RETRY_DELAY_MS;
   return Math.min(retryAfterSeconds * 1e3, MAX_RETRY_DELAY_MS);
 }
-var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var defaultSleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
 var SettlementStillQueuedError = class extends Error {
   constructor(message, paymentReceipt) {
     super(message);
@@ -48001,7 +48378,7 @@ async function buildSessionBody(deps, agentName, input) {
     ownerReference: deps.holderDid
   };
   Object.assign(fields, optionalRequestFields(input));
-  const digestHex = (0, import_node_crypto9.createHash)("sha256").update(canonicalizeJson(fields), "utf8").digest("hex");
+  const digestHex = (0, import_node_crypto11.createHash)("sha256").update(canonicalizeJson(fields), "utf8").digest("hex");
   const { signBlob: signedData } = await deps.signHexBlob(digestHex);
   return { ...fields, signedData };
 }
@@ -48945,6 +49322,100 @@ function clip3(text, max = 200) {
   return text.length > max ? `${text.slice(0, max - 1)}\u2026` : text;
 }
 
+// src/clients/self-pay-marker-store.ts
+var import_node_crypto12 = require("node:crypto");
+var import_promises9 = require("node:fs/promises");
+var import_node_path9 = require("node:path");
+function markerFileName(ownerAddress, policyKey) {
+  return `${(0, import_node_crypto12.createHash)("sha256").update(`${ownerAddress}
+${policyKey}`).digest("hex")}.json`;
+}
+var DIGITS = /^\d{1,18}$/;
+var HEX64 = /^[0-9a-fA-F]{64}$/;
+var ISO_8601 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+function isRealDate(iso) {
+  const t = Date.parse(iso);
+  return !Number.isNaN(t) && new Date(t).toISOString().slice(0, 10) === iso.slice(0, 10);
+}
+function isMarkerShape(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return typeof v.policyKey === "string" && v.policyKey !== "" && typeof v.ownerAddress === "string" && v.ownerAddress !== "" && (v.operation === "CREATE" || v.operation === "UPDATE") && typeof v.nonce === "string" && DIGITS.test(v.nonce) && typeof v.txHash === "string" && HEX64.test(v.txHash) && typeof v.ceilLedgerSeq === "string" && DIGITS.test(v.ceilLedgerSeq) && typeof v.submittedAt === "string" && ISO_8601.test(v.submittedAt) && isRealDate(v.submittedAt);
+}
+var DIRECTORY_FSYNC_UNSUPPORTED = /* @__PURE__ */ new Set(["EISDIR", "EPERM", "EACCES", "EINVAL", "ENOTSUP", "ENOSYS", "EBADF"]);
+var errorCode = (e) => typeof e === "object" && e !== null ? e.code : void 0;
+function unreadable(file, why) {
+  return new Error(
+    `the note of an earlier self-paid send (${file}) cannot be trusted: ${why}. A send can still land for 60 ledgers: delete that file only once at least 15 minutes have passed since it was last changed and the chain is producing ledgers, or once get_my_policy shows the write`
+  );
+}
+function createFsSelfPayMarkerStore(baseDir) {
+  const pathFor = (owner, key) => (0, import_node_path9.join)(baseDir, markerFileName(owner, key));
+  async function read2(ownerAddress, policyKey) {
+    const file = pathFor(ownerAddress, policyKey);
+    let raw;
+    try {
+      raw = await (0, import_promises9.readFile)(file, "utf8");
+    } catch (e) {
+      if (errorCode(e) === "ENOENT") return null;
+      throw unreadable(file, `it could not be read (${errorCode(e) ?? "unknown error"})`);
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw unreadable(file, raw === "" ? "it is empty" : "it is not valid JSON");
+    }
+    if (!isMarkerShape(parsed) || parsed.ownerAddress !== ownerAddress || parsed.policyKey !== policyKey) {
+      throw unreadable(file, "it is not a valid note for this owner and key");
+    }
+    return parsed;
+  }
+  return {
+    get: read2,
+    async set(marker) {
+      if (!isMarkerShape(marker)) throw new Error("refusing to save a malformed self-pay marker");
+      await (0, import_promises9.mkdir)(baseDir, { recursive: true, mode: 448 });
+      const filePath = pathFor(marker.ownerAddress, marker.policyKey);
+      const tmpPath = `${filePath}.tmp-${(0, import_node_crypto12.randomUUID)()}`;
+      try {
+        const handle = await (0, import_promises9.open)(tmpPath, "w", 384);
+        try {
+          await handle.writeFile(JSON.stringify(marker, null, 2), "utf8");
+          await handle.sync();
+        } finally {
+          await handle.close();
+        }
+        await (0, import_promises9.rename)(tmpPath, filePath);
+      } catch (e) {
+        await (0, import_promises9.unlink)(tmpPath).catch(() => void 0);
+        throw e;
+      }
+      try {
+        const dir = await (0, import_promises9.open)(baseDir, "r");
+        try {
+          await dir.sync();
+        } finally {
+          await dir.close();
+        }
+      } catch (e) {
+        if (!DIRECTORY_FSYNC_UNSUPPORTED.has(errorCode(e) ?? "")) throw e;
+      }
+    },
+    async remove(ownerAddress, policyKey, expectedTxHash) {
+      if (expectedTxHash !== void 0) {
+        const current = await read2(ownerAddress, policyKey);
+        if (current === null || current.txHash !== expectedTxHash) return;
+      }
+      try {
+        await (0, import_promises9.unlink)(pathFor(ownerAddress, policyKey));
+      } catch (e) {
+        if (errorCode(e) !== "ENOENT") throw e;
+      }
+    }
+  };
+}
+
 // src/orchestrator/policy-affordability.ts
 var NATIVE3 = "ZTX";
 var MAX_DETAIL = 160;
@@ -49039,6 +49510,7 @@ async function checkAffordability(deps, accept) {
 
 // src/index.ts
 var packageVersion = package_default.version;
+var POLICY_HTTP_TIMEOUT_MS = 6e4;
 function buildToolList() {
   return [
     {
@@ -49055,12 +49527,12 @@ function buildToolList() {
     },
     {
       name: "prove_identity",
-      description: "Answer an x401 PROOF-REQUEST and return the PROOF-RESPONSE header to replay to the resource server.",
+      description: "Answer an x401 PROOF-REQUEST and return the PROOF-RESPONSE header to replay to the resource server. If the wallet holds several credentials, pass vc: use the one the request or the verifier's challenge names, and if it names none, prefer the Verified AI Birthcert over the Basic one and say which one you presented.",
       inputSchema: {
         type: "object",
         properties: {
           proofRequest: { type: "string", description: "The PROOF-REQUEST header value from the 401 challenge." },
-          vc: { type: "object", description: "The VerifiableCredential to present. Omit to use the wallet's single locally-cached credential, if there is exactly one \u2014 the call fails with a clear error if none or several are cached." },
+          vc: { type: "object", description: "The VerifiableCredential to present. Omit to use the wallet's single locally-cached credential, if there is exactly one \u2014 the call fails with a clear error if none or several are cached, so with several, pass it." },
           revealAttribute: { type: "array", items: { type: "string" }, description: "Dotted disclosure paths to reveal. Omit to reveal exactly the claims the challenge (DCQL) requests; a challenge naming no claims reveals all." },
           issuerKeys: {
             type: "object",
@@ -49076,7 +49548,7 @@ function buildToolList() {
     },
     {
       name: "create_verification_qr",
-      description: "Create a link and a QR code that open this wallet's credential in the MyID app, so a human can see the identity behind the agent. Use it when the user asks whether the agent is verified, or asks to verify the agent in MyID. With no vc, it presents the Verified AI Birthcert if it holds one, otherwise the Basic AI Birthcert, and if it holds neither it returns created: false and says to create one first. By default it reveals only a standard minimal set (for the Verified AI Birthcert: agentName, evidenceProvider and ownerVerified; for the Basic AI Birthcert: agentUsername); pass revealAttribute to reveal other specific attributes the user asks for, and revealAll: true only when the user explicitly asks to reveal everything. A Basic AI Birthcert does not mean the owner was verified, so say so if that is what was presented. The wallet presents the credential to MBI and returns the link, the QR code image and the time the link stops working (5 minutes by default); the link holds only a reference id, and that reference id grants access to the revealed attributes until it expires. Show the link and QR code only to the human user, never pass them to another service, and tell the user to open the link in MyID (they need the app installed). If it returns created: false, relay the reason and do not invent a link.",
+      description: "Create a link and a QR code that open this wallet's credential in the MyID app, so a human can see the identity behind the agent. Use it when the user asks whether the agent is verified, or asks to verify the agent in MyID. With no vc, it presents the Verified AI Birthcert if it holds one, otherwise the Basic AI Birthcert, and if it holds neither it returns created: false and says to create one first. By default it reveals only a standard minimal set (for the Verified AI Birthcert: agentName, evidenceProvider and ownerVerified; for the Basic AI Birthcert: agentUsername); pass revealAttribute to reveal other specific attributes the user asks for, and revealAll: true only when the user explicitly asks to reveal everything. A Basic AI Birthcert does not mean the owner was verified, so say so if that is what was presented. The wallet presents the credential to MBI and returns the link, the QR code (as an image and as a PNG file at qrCodePath) and the time the link stops working (5 minutes by default); the link holds only a reference id, and that reference id grants access to the revealed attributes until it expires. Show the link and QR code only to the human user, never pass them to another service, and tell the user to open the link in MyID (they need the app installed). In a chat channel such as WhatsApp, send the QR code by attaching the file at qrCodePath; never send any other image as the QR code, because the credential's pass design is not one, and if you cannot attach an image, give the link and say plainly that you could not send the QR code. When the credential has a saved pass design, the result also carries vcPassImagePaths: if the user wants to see the credential itself, send that image too, as its own picture captioned as the credential's pass design and never as the QR code. If it returns created: false, relay the reason and do not invent a link.",
       inputSchema: {
         type: "object",
         properties: {
@@ -49181,7 +49653,7 @@ function buildToolList() {
     },
     {
       name: "write_policy",
-      description: 'Deploy a spending policy on chain. THIS PAYS A REAL FEE. Run policy_preflight first and show the user its `interpretation`, because a policy that is valid can still mean something other than what they asked for, and this tool cannot take that back once it is written. It only pays and writes with confirm: true, which the user must have given after seeing the interpretation and the price: without it you get the price back (state "quoted", needsConfirmation: true) and nothing is paid. Never pass confirm on your own judgement. Amounts (perTransactionMax, cumulativeMax, velocityCap) are RAW base units: 1 of a 6-decimal token is 0.000001 of it. Send the SAME attributes and the SAME amountUnit you preflighted with, and never substitute convertedAmounts for the values \u2014 that converts them twice. "whole" gives whole-token amounts the wallet converts before anything is paid; "base" confirms a raw value under one whole token is intended; without it such a value is refused. For any amount attribute you may give valueHuman (whole tokens, "100" for 100 JMYR) instead of value: the wallet converts it with the token\'s own decimals, shows both forms, and never sends valueHuman on. Never put convertedAmounts in valueHuman: those are raw base units and would be scaled again. maxTransactionCount is a count of transactions, not an amount, so give it as value and never scale it. The flow is three steps and the middle one is where care is needed: a free pre-check, a payment that writes NOTHING, and a collect that finishes the write once the payment settles. Between the payment and the settlement A PAYMENT HAS BEEN MADE and no policy exists \u2014 that window is normal, not a failure. On the sponsored path, if `state` is "settling" or "submitted", A PAYMENT HAS BEEN MADE: never call this tool again for the same policy, never tell the user it failed, and pass `paymentReceipt` to check_policy_write instead. "submitted" means the transaction is on chain but the block has not confirmed it \u2014 do NOT report the policy as created, even though a txHash is present. "written" is the only state that means the policy exists. "already_exists" and "refused" both mean nothing was paid: they come from the FREE pre-check, or, for "refused" with `policyDenied`, from Wallet BE refusing to sign. When `policyDenied` is true a spending policy refused the fee before it was signed: a decision, so do not retry, and no policy was written. When `policyCheckUnavailable` is true (state "unavailable") the spending policy check could not be completed, nothing was paid and no policy was written; trying again shortly is right. "payment_refused" is different: a payment was presented and the service rejected it, and that says nothing either way about whether the fee was taken \u2014 never tell the user they were not charged, and never tell them they were. "receipt_void" is the one state where paying again is correct \u2014 the settlement failed and the receipt bought nothing; `payFresh` is set to say so. On the sponsored path, "write_failed" and "unknown" both mean money moved and paying again would NOT help: quote `paymentReceipt` to support rather than retrying. To find a templateId, call get_policy_template_schema with no arguments \u2014 it lists the templates with their ids. Never invent one. The template contract address is never the user\'s to supply, so leave it out rather than asking. Who pays the gas is the USER\'s choice: if this returns "needs_choice", show the user both options (sponsored: a JMYR fee; self: ZTX for network gas, no fee), let them pick, and call again with gasPayer and confirm: true. Never choose for them. With gasPayer "self" there is no paymentReceipt and check_policy_write does not apply. A self-paid "submitted" means the network gas is spent: do NOT send it again, check get_my_policy, and quote the txHash to support. A self-paid "unknown" means it may be on chain: do NOT send it again, check get_my_policy, and quote the nonce. A self-paid "write_failed" means the transaction was included and rejected: the gas is spent and nothing was written. Self-paid gas is spent even when the write fails on chain. To learn the price BEFORE paying, pass dryRun: it runs every free check and returns the service\'s quote, paying nothing and writing no policy. "quoted" means that \u2014 no payment was made. It also reports `affordability`: whether this wallet currently holds the quoted amount of the fee asset (plus some ZTX for gas when the payer needs it) and whether the payment cap would refuse it \u2014 each shortfall named separately, and "unknown" when a balance could not be read, which is not a yes. Tell the user what it says before they decide to pay. A quote is what the service asked for just now; it can change, and it is not a promise the payment will be allowed \u2014 balances move and the cap is enforced again when paying. Never ask the user for their HSM password \u2014 this tool does not take one.',
+      description: 'Deploy a spending policy on chain. THIS PAYS A REAL FEE. Run policy_preflight first and show the user its `interpretation`, because a policy that is valid can still mean something other than what they asked for, and this tool cannot take that back once it is written. It only pays and writes with confirm: true, which the user must have given after seeing the interpretation and the price: without it you get the price back (state "quoted", needsConfirmation: true) and nothing is paid. Never pass confirm on your own judgement. Amounts (perTransactionMax, cumulativeMax, velocityCap) are RAW base units: 1 of a 6-decimal token is 0.000001 of it. Send the SAME attributes and the SAME amountUnit you preflighted with, and never substitute convertedAmounts for the values \u2014 that converts them twice. "whole" gives whole-token amounts the wallet converts before anything is paid; "base" confirms a raw value under one whole token is intended; without it such a value is refused. For any amount attribute you may give valueHuman (whole tokens, "100" for 100 JMYR) instead of value: the wallet converts it with the token\'s own decimals, shows both forms, and never sends valueHuman on. Never put convertedAmounts in valueHuman: those are raw base units and would be scaled again. maxTransactionCount is a count of transactions, not an amount, so give it as value and never scale it. The flow is three steps and the middle one is where care is needed: a free pre-check, a payment that writes NOTHING, and a collect that finishes the write once the payment settles. Between the payment and the settlement A PAYMENT HAS BEEN MADE and no policy exists \u2014 that window is normal, not a failure. On the sponsored path, if `state` is "settling" or "submitted", A PAYMENT HAS BEEN MADE: never call this tool again for the same policy, never tell the user it failed, and pass `paymentReceipt` to check_policy_write instead. "submitted" means the transaction is on chain but the block has not confirmed it \u2014 do NOT report the policy as created, even though a txHash is present. "written" is the only state that means the policy exists. "already_exists" and "refused" both mean nothing was paid: they come from the FREE pre-check, or, for "refused" with `policyDenied`, from Wallet BE refusing to sign. When `policyDenied` is true a spending policy refused the fee before it was signed: a decision, so do not retry, and no policy was written. When `policyCheckUnavailable` is true (state "unavailable") the spending policy check could not be completed, nothing was paid and no policy was written; trying again shortly is right. "payment_refused" is different: a payment was presented and the service rejected it, and that says nothing either way about whether the fee was taken \u2014 never tell the user they were not charged, and never tell them they were. "receipt_void" is the one state where paying again is correct \u2014 the settlement failed and the receipt bought nothing; `payFresh` is set to say so. On the sponsored path, "write_failed" and "unknown" both mean money moved and paying again would NOT help: quote `paymentReceipt` to support rather than retrying. To find a templateId, call get_policy_template_schema with no arguments \u2014 it lists the templates with their ids. Never invent one. The template contract address is never the user\'s to supply, so leave it out rather than asking. Who pays the gas is the USER\'s choice: if this returns "needs_choice", show the user both options (sponsored: a JMYR fee; self: ZTX for network gas, no fee), let them pick, and call again with gasPayer and confirm: true. Never choose for them. With gasPayer "self" there is no paymentReceipt and check_policy_write does not apply. A self-paid "submitted" means the network gas is spent: do NOT send it again, check get_my_policy, and quote the txHash to support. A self-paid "unknown" means it may be on chain: do NOT send it again, check get_my_policy, and quote the nonce. The wallet remembers it and refuses another send, a sponsored write, a collect and a removal for that key until it has landed or can no longer land, and says when. A self-paid "write_failed" means the transaction was included and rejected: the gas is spent and nothing was written. To send a self-paid write pass maxGasRaw: the requiredRaw of the self option you showed the user. It is the most gas they agreed to, and the wallet refuses, free, if the gas now costs more, so show the user any new figure and ask again. Self-paid gas is spent even when the write fails on chain. To learn the price BEFORE paying, pass dryRun: it runs every free check and returns the service\'s quote, paying nothing and writing no policy. "quoted" means that \u2014 no payment was made. It also reports `affordability`: whether this wallet currently holds the quoted amount of the fee asset (plus some ZTX for gas when the payer needs it) and whether the payment cap would refuse it \u2014 each shortfall named separately, and "unknown" when a balance could not be read, which is not a yes. Tell the user what it says before they decide to pay. A quote is what the service asked for just now; it can change, and it is not a promise the payment will be allowed \u2014 balances move and the cap is enforced again when paying. Never ask the user for their HSM password \u2014 this tool does not take one.',
       inputSchema: {
         type: "object",
         properties: {
@@ -49241,6 +49713,10 @@ function buildToolList() {
             type: "string",
             enum: ["sponsored", "self"],
             description: 'Who pays the gas to write. "sponsored": the fee is paid in JMYR and the network gas is covered, so no ZTX is needed. "self": no fee, only the network gas in ZTX. Leave it out unless the user has chosen: when the wallet can pay the gas itself, a call without it returns state "needs_choice" with both options and what each would cost, and the user decides. Never choose for the user.'
+          },
+          maxGasRaw: {
+            type: "string",
+            description: 'Self-pay only. The most gas, in raw units (micro-ZTX), the user agreed to pay to write: the "requiredRaw" of the self option (gasOptions.self.gas.requiredRaw) that you showed them. A self-paid send needs it and is refused, free, without it or when the gas now costs more than this, so it can never cost more than the user was shown.'
           }
         },
         required: ["policyKey", "attributes", "templateId"]
@@ -49248,7 +49724,7 @@ function buildToolList() {
     },
     {
       name: "update_policy",
-      description: 'Replace a deployed spending policy\'s attributes and validity window. THIS PAYS A REAL FEE. Read the policy first with get_my_policy and pass its `forUpdate.expectedUpdatedAtBlock` as expectedUpdatedAtBlock: if the policy has changed since, the update is refused before anything is paid. attributes is the FULL replacement set, not a patch \u2014 anything you leave out is dropped \u2014 so start from the policy\'s current attributes and change only what the user asked for. Do not pass a templateId: the policy keeps the template it already references. The validity window is kept as it is unless you pass validFromBlock or validToBlock. Run policy_preflight first and show the user its `interpretation`, because a policy that is valid can still mean something other than what they asked for, and an update cannot be taken back once it is written. It only pays and writes with confirm: true, which the user must have given after seeing the interpretation and the price: without it you get the price back (state "quoted", needsConfirmation: true) and nothing is paid. Never pass confirm on your own judgement. Amounts (perTransactionMax, cumulativeMax, velocityCap) are RAW base units, exactly as in write_policy: send the SAME attributes and the SAME amountUnit you preflighted with, and never substitute convertedAmounts for the values. For any amount attribute you may give valueHuman (whole tokens, "100" for 100 JMYR) instead of value, as in write_policy; maxTransactionCount is a count, not an amount, so give it as value and never scale it. The flow is the same three steps as write_policy: a free pre-check, a payment that changes NOTHING, and a collect that applies the update once the payment settles. Between the payment and the settlement A PAYMENT HAS BEEN MADE and the policy is still unchanged \u2014 that window is normal, not a failure. On the sponsored path, if `state` is "settling" or "submitted", A PAYMENT HAS BEEN MADE: never call this tool again for the same policy, never tell the user it failed, and pass `paymentReceipt` to check_policy_write instead. "submitted" means the transaction is on chain but the block has not confirmed it \u2014 do NOT report the policy as updated, even though a txHash is present. "written" is the only state that means the policy was updated. "not_found", "modified", "template_unavailable" and "refused" all come from the free checks, before any payment, and say so. For "modified", read the policy again with get_my_policy, show the user what it holds now, and update from that; never retry with the old expectedUpdatedAtBlock. When `policyDenied` is true a spending policy refused the fee before it was signed: a decision, so do not retry. "payment_refused" is different: a payment was presented and the service rejected it, and that says nothing either way about whether the fee was taken \u2014 never tell the user they were not charged, and never tell them they were. "receipt_void" is the one state where paying again is correct \u2014 the settlement failed and the receipt bought nothing; `payFresh` is set to say so. On the sponsored path, "write_failed" means the update was NOT applied and the policy is unchanged, but a payment may have been taken: paying again would not help, so quote `paymentReceipt` to support rather than retrying. On the sponsored path "unknown" also means money moved without a verdict: do the same. Who pays the gas is the USER\'s choice: if this returns "needs_choice", show the user both options (sponsored: a JMYR fee; self: ZTX for network gas, no fee), let them pick, and call again with gasPayer and confirm: true. Never choose for them. With gasPayer "self" there is no paymentReceipt and check_policy_write does not apply. A self-paid "submitted" means the network gas is spent: do NOT send it again, check get_my_policy, and quote the txHash to support. A self-paid "unknown" means it may be on chain: do NOT send it again, check get_my_policy, and quote the nonce. A self-paid "write_failed" means the transaction was included and rejected: the gas is spent and nothing was written. Self-paid gas is spent even when the write fails on chain. To learn the price BEFORE paying, pass dryRun: it runs every free check and returns the service\'s quote, paying nothing and changing no policy. Tell the user what it says before they decide to pay. To lift a policy\'s limits entirely, that is remove_policy, not an update with no attributes. Never ask the user for their HSM password \u2014 this tool does not take one.',
+      description: 'Replace a deployed spending policy\'s attributes and validity window. THIS PAYS A REAL FEE. Read the policy first with get_my_policy and pass its `forUpdate.expectedUpdatedAtBlock` as expectedUpdatedAtBlock: if the policy has changed since, the update is refused before anything is paid. attributes is the FULL replacement set, not a patch \u2014 anything you leave out is dropped \u2014 so start from the policy\'s current attributes and change only what the user asked for. Do not pass a templateId: the policy keeps the template it already references. The validity window is kept as it is unless you pass validFromBlock or validToBlock. Run policy_preflight first and show the user its `interpretation`, because a policy that is valid can still mean something other than what they asked for, and an update cannot be taken back once it is written. It only pays and writes with confirm: true, which the user must have given after seeing the interpretation and the price: without it you get the price back (state "quoted", needsConfirmation: true) and nothing is paid. Never pass confirm on your own judgement. Amounts (perTransactionMax, cumulativeMax, velocityCap) are RAW base units, exactly as in write_policy: send the SAME attributes and the SAME amountUnit you preflighted with, and never substitute convertedAmounts for the values. For any amount attribute you may give valueHuman (whole tokens, "100" for 100 JMYR) instead of value, as in write_policy; maxTransactionCount is a count, not an amount, so give it as value and never scale it. The flow is the same three steps as write_policy: a free pre-check, a payment that changes NOTHING, and a collect that applies the update once the payment settles. Between the payment and the settlement A PAYMENT HAS BEEN MADE and the policy is still unchanged \u2014 that window is normal, not a failure. On the sponsored path, if `state` is "settling" or "submitted", A PAYMENT HAS BEEN MADE: never call this tool again for the same policy, never tell the user it failed, and pass `paymentReceipt` to check_policy_write instead. "submitted" means the transaction is on chain but the block has not confirmed it \u2014 do NOT report the policy as updated, even though a txHash is present. "written" is the only state that means the policy was updated. "not_found", "modified", "template_unavailable" and "refused" all come from the free checks, before any payment, and say so. For "modified", read the policy again with get_my_policy, show the user what it holds now, and update from that; never retry with the old expectedUpdatedAtBlock. When `policyDenied` is true a spending policy refused the fee before it was signed: a decision, so do not retry. "payment_refused" is different: a payment was presented and the service rejected it, and that says nothing either way about whether the fee was taken \u2014 never tell the user they were not charged, and never tell them they were. "receipt_void" is the one state where paying again is correct \u2014 the settlement failed and the receipt bought nothing; `payFresh` is set to say so. On the sponsored path, "write_failed" means the update was NOT applied and the policy is unchanged, but a payment may have been taken: paying again would not help, so quote `paymentReceipt` to support rather than retrying. On the sponsored path "unknown" also means money moved without a verdict: do the same. Who pays the gas is the USER\'s choice: if this returns "needs_choice", show the user both options (sponsored: a JMYR fee; self: ZTX for network gas, no fee), let them pick, and call again with gasPayer and confirm: true. Never choose for them. With gasPayer "self" there is no paymentReceipt and check_policy_write does not apply. A self-paid "submitted" means the network gas is spent: do NOT send it again, check get_my_policy, and quote the txHash to support. A self-paid "unknown" means it may be on chain: do NOT send it again, check get_my_policy, and quote the nonce. The wallet remembers it and refuses another send, a sponsored write, a collect and a removal for that key until it has landed or can no longer land, and says when. A self-paid "write_failed" means the transaction was included and rejected: the gas is spent and nothing was written. To send a self-paid write pass maxGasRaw: the requiredRaw of the self option you showed the user. It is the most gas they agreed to, and the wallet refuses, free, if the gas now costs more, so show the user any new figure and ask again. Self-paid gas is spent even when the write fails on chain. To learn the price BEFORE paying, pass dryRun: it runs every free check and returns the service\'s quote, paying nothing and changing no policy. Tell the user what it says before they decide to pay. To lift a policy\'s limits entirely, that is remove_policy, not an update with no attributes. Never ask the user for their HSM password \u2014 this tool does not take one.',
       inputSchema: {
         type: "object",
         properties: {
@@ -49297,6 +49773,10 @@ function buildToolList() {
             enum: ["sponsored", "self"],
             description: 'Who pays the gas to update. "sponsored": the fee is paid in JMYR and the network gas is covered, so no ZTX is needed. "self": no fee, only the network gas in ZTX. Leave it out unless the user has chosen: when the wallet can pay the gas itself, a call without it returns state "needs_choice" with both options and what each would cost, and the user decides. Never choose for the user.'
           },
+          maxGasRaw: {
+            type: "string",
+            description: 'Self-pay only. The most gas, in raw units (micro-ZTX), the user agreed to pay to update: the "requiredRaw" of the self option (gasOptions.self.gas.requiredRaw) that you showed them. A self-paid send needs it and is refused, free, without it or when the gas now costs more than this, so it can never cost more than the user was shown.'
+          },
           pollBudgetMs: {
             type: "number",
             description: "How long to wait for the settlement before handing back the receipt. The default is about a minute; settlement usually takes around twenty seconds."
@@ -49307,7 +49787,7 @@ function buildToolList() {
     },
     {
       name: "remove_policy",
-      description: `Remove a deployed spending policy. REMOVING A POLICY REMOVES EVERY LIMIT IT SET: once it is gone, Wallet BE signs spends of that asset without any limit. Removing is free, but it needs the user's clear agreement. Without confirm: true nothing is sent and you get state "needs_confirmation" with what the policy currently limits: show the user that and what removing it means, and only if they clearly agree call again with confirm: true. Never pass confirm on your own judgement. "removed" is the only state that means the policy is gone: it is reported only when the chain no longer holds it. "submitted" means the removal is on its way but not confirmed \u2014 do NOT tell the user it is removed; check with get_my_policy (found: false means it is gone). Calling remove_policy again is free, and the service is expected not to submit a second removal. "not_found" means there was nothing to remove, or it is already gone \u2014 confirm with get_my_policy before saying which. "in_progress" means a paid write for this policy is still being completed: if this wallet holds its receipt, check_policy_write finishes it, otherwise wait and ask again later. To change a policy rather than remove it, use update_policy. Never ask the user for their HSM password \u2014 this tool does not take one.`,
+      description: `Remove a deployed spending policy. REMOVING A POLICY REMOVES EVERY LIMIT IT SET: once it is gone, Wallet BE signs spends of that asset without any limit. Removing is free, but it needs the user's clear agreement. Without confirm: true nothing is sent and you get state "needs_confirmation" with what the policy currently limits: show the user that and what removing it means, and only if they clearly agree call again with confirm: true. Never pass confirm on your own judgement. "removed" is the only state that means the policy is gone: it is reported only when the chain no longer holds it. "submitted" means the removal is on its way but not confirmed \u2014 do NOT tell the user it is removed; check with get_my_policy (found: false means it is gone). Calling remove_policy again is free, and the service is expected not to submit a second removal. "not_found" means there was nothing to remove, or it is already gone \u2014 confirm with get_my_policy before saying which. "in_progress" means a paid write for this policy is still being completed: if this wallet holds its receipt, check_policy_write finishes it, otherwise wait and ask again later. "refused" naming a self-paid transaction means an earlier self-paid update may still land and would bring the old policy back: NOTHING WAS REMOVED; wait until the ledger it names, or read the policy with get_my_policy, then ask again. "refused" saying another write is in progress in this wallet, or "unavailable" saying a record could not be read, also means NOTHING WAS REMOVED: ask again shortly. To change a policy rather than remove it, use update_policy. Never ask the user for their HSM password \u2014 this tool does not take one.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -49329,7 +49809,7 @@ function buildToolList() {
     },
     {
       name: "check_policy_write",
-      description: 'Finish a policy write that has already been PAID FOR. FREE \u2014 this tool never pays, on any path, which is why it is the right answer to "did my policy get created?" and calling write_policy again is not. Call it with the `paymentReceipt` from a "settling" or "submitted" result, or with no arguments to resume the most recent pending write. The states mean the same as in write_policy: "written" is the only one where the policy exists, "settling" and "submitted" mean keep waiting, and "unknown" means the outcome could not be determined \u2014 none of which is a reason to pay again. A paid update_policy is finished the same way: its receipt is collected on the update route, and "written" then means the policy was updated. If this wallet holds no record of the receipt, that does NOT mean the write failed: the service completes a paid write on its own, and asking to write the same policyKey again will report the truth for free before any payment.',
+      description: 'Finish a policy write that has already been PAID FOR. FREE \u2014 this tool never pays, on any path, which is why it is the right answer to "did my policy get created?" and calling write_policy again is not. Call it with the `paymentReceipt` from a "settling" or "submitted" result, or with no arguments to resume the most recent pending write. The states mean the same as in write_policy: "written" is the only one where the policy exists, "settling" and "submitted" mean keep waiting, and "unknown" means the outcome could not be determined \u2014 none of which is a reason to pay again. A paid update_policy is finished the same way: its receipt is collected on the update route, and "written" then means the policy was updated. "refused" or "unavailable" saying NOTHING WAS COLLECTED means a self-paid write for this policy may still land, or another write for it is in progress in this wallet: the payment is not lost, so do not pay again; ask again shortly. If this wallet holds no record of the receipt, that does NOT mean the write failed: the service completes a paid write on its own, and asking to write the same policyKey again will report the truth for free before any payment.',
       inputSchema: {
         type: "object",
         properties: {
@@ -49418,7 +49898,7 @@ function buildToolList() {
     },
     {
       name: "subscribe_and_issue",
-      description: "Obtain a VC from MBI: build the signed payload, pay x402, and return the issued credential. If a spending policy refuses the fee, the result has `policyDenied: true` (a decision: do not retry) or `policyCheckUnavailable: true` (transient: trying again shortly is right); either way nothing was paid and no credential was issued. If a still-valid credential for this templateId is already cached locally, it is returned directly with no payment (fromCache: true). Setting forceReissue:true alone does NOT pay again \u2014 it only asks to be shown that existing credential first: you get back { issued: false, vcId, vc, fromCache: true, reason } instead, and nothing is paid. Show that existing credential to the user and ask whether they actually want to replace it; only call this tool again, with BOTH forceReissue:true and confirmReplaceExistingVc set to exactly the vcId you were shown, if they explicitly say yes. Never pass confirmReplaceExistingVc on your own judgement. When nothing valid is cached, forceReissue has no effect either way \u2014 that case has always paid and issued fresh. When a call DOES render a full credential to the user (a fresh issuance, a plain cache hit, or a confirmed replace), show every claim under vc.credentialSubject as a table \u2014 not a cherry-picked subset \u2014 labelling each key by title-casing it (the exact claim set varies by template; use schema.required/optional to know what to expect), plus vcId and validUntil if present. If vcPassImagePaths is also present, the credential's own pass-design image(s) came back attached to this result \u2014 tell the user their credential's official pass design is shown below and display the image(s); do not silently drop them from your summary just because they are not text. Payment is asset-agnostic \u2014 MBI's 402 challenge may quote the native ZETRIX token or a ZTP20 token (e.g. JMYR); pass dryRun:true first to see the quoted asset/amount for free before committing to pay. What a call actually cost is reported precisely: paidAsset/amountPaid are set ONLY when this call paid, a cache hit reports the earlier charge under originalPayment instead (never as amountPaid, so summing spend cannot double-count), and any failure after the payment has settled on chain reports paymentAttempted: { asset, amount, paymentId }. Two such failures exist and mean different things: MBI 4006 is a definitive facilitator rejection, while 4012 (HTTP 502) means the outcome is INDETERMINATE \u2014 the payment may well have landed. On 4012 the wallet automatically polls MBI's recovery endpoint and reports recovery: { status, txHash?, vcId?, polls }, where status is ISSUED (the credential exists after all \u2014 fetch it by vcId, since recovery returns no VC body), FAILED, or REQUIRED/SETTLED (still unresolved) / UNKNOWN (recovery itself unreachable). NEVER retry a payment after either failure: the funds may already be gone, and a retry charges the full amount again \u2014 look the paymentId up instead. Every response also includes { schema: { required, optional } } whenever the template schema could be read from chain \u2014 the template's full declared attribute list, so you see the complete field list, not just what went wrong. For the AI Birthcert specifically: this issues the BASIC one \u2014 self-declared by the agent, agent-paid via x402, owner identity NOT identity-verified. If the user asked for a \"verified\" AI birthcert (owner identity confirmed via MyDigital ID), use request_ai_birthcert_verification instead \u2014 this tool cannot produce that credential.",
+      description: "Obtain a VC from MBI: build the signed payload, pay x402, and return the issued credential. If a spending policy refuses the fee, the result has `policyDenied: true` (a decision: do not retry) or `policyCheckUnavailable: true` (transient: trying again shortly is right); either way nothing was paid and no credential was issued. If a still-valid credential for this templateId is already cached locally, it is returned directly with no payment (fromCache: true). Setting forceReissue:true alone does NOT pay again \u2014 it only asks to be shown that existing credential first: you get back { issued: false, vcId, vc, fromCache: true, reason } instead, and nothing is paid. Show that existing credential to the user and ask whether they actually want to replace it; only call this tool again, with BOTH forceReissue:true and confirmReplaceExistingVc set to exactly the vcId you were shown, if they explicitly say yes. Never pass confirmReplaceExistingVc on your own judgement. When nothing valid is cached, forceReissue has no effect either way \u2014 that case has always paid and issued fresh. When a call DOES render a full credential to the user (a fresh issuance, a plain cache hit, or a confirmed replace), show every claim under vc.credentialSubject as a table \u2014 not a cherry-picked subset \u2014 labelling each key by title-casing it (the exact claim set varies by template; use schema.required/optional to know what to expect), plus vcId and validUntil if present. If vcPassImagePaths is also present, the credential's own pass-design image(s) came back attached to this result \u2014 tell the user their credential's official pass design is shown below and display the image(s); do not silently drop them from your summary just because they are not text. Payment is asset-agnostic \u2014 MBI's 402 challenge may quote the native ZETRIX token or a ZTP20 token (e.g. JMYR); pass dryRun:true first to see the quoted asset/amount for free before committing to pay. What a call actually cost is reported precisely: paidAsset/amountPaid are set ONLY when this call paid, a cache hit reports the earlier charge under originalPayment instead (never as amountPaid, so summing spend cannot double-count), and any failure after the payment has settled on chain reports paymentAttempted: { asset, amount, paymentId }. Two such failures exist and mean different things: MBI 4006 is a definitive facilitator rejection, while 4012 (HTTP 502) means the outcome is INDETERMINATE \u2014 the payment may well have landed. On 4012 the wallet automatically polls MBI's recovery endpoint and reports recovery: { status, txHash?, vcId?, polls }, where status is ISSUED (the credential exists after all \u2014 fetch it by vcId, since recovery returns no VC body), FAILED, or REQUIRED/SETTLED (still unresolved) / UNKNOWN (recovery itself unreachable). NEVER retry a payment after either failure: the funds may already be gone, and a retry charges the full amount again \u2014 look the paymentId up instead. Every response also includes { schema: { required, optional } } whenever the template schema could be read from chain \u2014 the template's full declared attribute list, so you see the complete field list, not just what went wrong. For the AI Birthcert specifically: this issues the BASIC one \u2014 self-declared by the agent, agent-paid via x402, owner identity NOT identity-verified. If the user asked for a \"verified\" AI birthcert (owner identity confirmed via MyDigital ID), use request_ai_birthcert_verification instead \u2014 this tool cannot produce that credential. If the user did not say which kind, ask first: see the `choice` note in credential_preflight.",
       inputSchema: {
         type: "object",
         properties: {
@@ -49428,12 +49908,12 @@ function buildToolList() {
           },
           attributes: {
             type: "object",
-            description: `Claim values for the credential (schema varies by template \u2014 check what the issuer requires before guessing). ALWAYS ask the human owner directly for any name/identifier-type value (e.g. an agentUsername or similar field) \u2014 NEVER invent, guess, or silently reuse one of your own choosing; if the template requires one, get it from the user first. "agentDid" is the one exception: it does not need to be supplied, since it is auto-filled with this wallet's own holder DID (the credential's self-referential subject) unless you explicitly override it.`
+            description: `Claim values for the credential (schema varies by template \u2014 check what the issuer requires before guessing). ALWAYS ask the human owner directly for any name/identifier-type value (e.g. an agentUsername or similar field) \u2014 NEVER invent, guess, or silently reuse one of your own choosing; if the template requires one, get it from the user first. When the user answers with a name \u2014 even a short phrase, even one that repeats words from your question \u2014 that IS the name: use it as given and do not ask for it again, unless it was refused (for example already in use). Tidying it (spaces or capitals, say) is optional and never needed; if you do want to suggest a tidier form, ask and WAIT for their answer, and use the tidied form only after a yes. Never go ahead on a name, or on a payment, that the user has not agreed to. Any example you give is only an example of the format, not a suggestion to use. "agentDid" is the one exception: it does not need to be supplied, since it is auto-filled with this wallet's own holder DID (the credential's self-referential subject) unless you explicitly override it.`
           },
           expirationDate: { type: "string" },
           dryRun: {
             type: "boolean",
-            description: "Price the credential without paying, signing, or issuing anything. Returns { quote: { asset, maxAmountRequired, payTo, gasModel, paymentRequired? }, schema: { required, optional } }. Priced via MBI's /quote endpoint, which cannot issue \u2014 so this is safe even on a template that issues for free (such a template mints synchronously on the real path, which is why pricing never goes through it). Never writes the VC cache, so it cannot displace a credential you already hold. `quote.paymentRequired` is the authoritative free-vs-paid answer: false means issuance is currently free and `maxAmountRequired` will not be charged. When the field is ABSENT the MBI predates it and the amount is unconfirmed \u2014 report it as a possible charge, never as certainly free. Still validates required attributes locally first \u2014 a missing one blocks before any MBI call."
+            description: "Price the credential without paying, signing, or issuing anything. Returns { quote: { asset, maxAmountRequired, payTo, gasModel, paymentRequired? }, schema: { required, optional } }. Priced via MBI's /quote endpoint, which cannot issue \u2014 so this is safe even on a template that issues for free (such a template mints synchronously on the real path, which is why pricing never goes through it). Never writes the VC cache, so it cannot displace a credential you already hold. `quote.paymentRequired` is the authoritative free-vs-paid answer: false means issuance is currently free and `maxAmountRequired` will not be charged. When the field is ABSENT the MBI predates it and the amount is unconfirmed \u2014 report it as a possible charge, never as certainly free. Tell the user in plain words that it is free or chargeable; never quote JSON field names such as paymentRequired to them. Still validates required attributes locally first \u2014 a missing one blocks before any MBI call."
           },
           forceReissue: {
             type: "boolean",
@@ -49449,13 +49929,13 @@ function buildToolList() {
     },
     {
       name: "request_ai_birthcert_verification",
-      description: 'Start a Verified AI Birthcert issuance session with myid (MyDigital ID owner verification). ALWAYS run credential_preflight for "verified_ai_birthcert" immediately before calling this, even if you checked earlier in the conversation \u2014 preflight is free, this tool spends real funds, and a balance the user topped up a minute ago is not the balance you read before that. If a spending policy refuses the session fee, the result is { error } with `policyDenied: true` (a decision: do not retry) or `policyCheckUnavailable: true` (transient: trying again shortly is right); either way nothing was paid and no session was created. Returns { sessionId, verificationUrl, expiresAt, expiresIn, expiresInSeconds, message } \u2014 show verificationUrl to the human owner and ask them to open it and complete MyDigital ID verification (typically finishes in seconds). Tell them how long the link is good for by quoting `expiresIn` exactly as given: the wallet works it out from its own clock, so never calculate the time remaining yourself from `expiresAt` \u2014 your clock and timezone may differ from the server\'s. `message` here contains a "Tell the user:" sentence about following up \u2014 relay it rather than composing your own reassurance. Once they confirm they are done, call check_ai_birthcert_verification to see whether the credential was issued. Nothing keeps running after this call returns \u2014 there is no background polling, webhook, or timer, so you can only check status when the user sends you a new message. NEVER tell the user you have "set up an automation" or that you will "alert them" when it completes \u2014 you cannot act on your own between messages, and promising that leaves them waiting for a notification that will never come. Instead, tell them how long the link is good for and ask them to message you back once done (or after a few minutes) so you can check_ai_birthcert_verification again. ALWAYS ask the human owner directly what agentName they want to use for a NEW session \u2014 NEVER invent, guess, or silently choose one yourself. (Calling again with the SAME name to resume an already-pending session, as described below, is not "inventing" one \u2014 that is reusing the exact name the owner already gave.) IMPORTANT: agentName must be unique \u2014 if this exact name has already been used to request a Verified AI Birthcert, issuance will fail. Before calling, ask the human owner whether they want to supply any of the optional fields \u2014 agentPurpose, evidenceAssuranceLevel, ownerType, ownerVerified \u2014 do not silently omit them; they only need to say no. Calling this again with the SAME agentName while a prior session is still pending returns that same session unchanged \u2014 no new session is started and nothing is paid again. This tool spends real funds: it self-pays an x402 challenge, subject to the same credential-issuance payment cap as subscribe_and_issue, which by default allows exactly 1 JMYR per call. Set MAX_PAYMENT_AMOUNT to override it; a spending policy that governs the asset replaces the default cap. It can return { error: "..." } instead of a session. Read `message` before deciding what to tell the user or whether retrying is safe \u2014 it does NOT always mean nothing was paid. For insufficient funds or a payment-cap block specifically, nothing is created and nothing was paid, so once the underlying problem is fixed (e.g. the user tops up), calling this tool again is the right next step. Several OTHER { error } shapes mean the opposite: a payment may already have been sent on a prior or even this call (blob_already_settled, a receipt that could not be saved locally, RECEIPT VOID, OUTCOME UNKNOWN) \u2014 for any of those, calling this tool again pays the fee AGAIN, so do NOT retry without explicit agreement from the user, exactly as `message` itself will say. It can also return { settlementPending: true, paymentReceipt, message } instead \u2014 a payment WAS SENT and no session exists yet. That is NOT a failure and NOT an error, but do NOT pay again and do NOT call this tool again to retry it \u2014 call check_ai_birthcert_verification to follow it through instead. It covers three different situations, told apart by the `issuerRejected` and `paymentInvalid` fields. With neither set, do NOT assume the payment is known to have succeeded \u2014 this shape covers TWO different states that look identical from these fields alone: usually the settlement is genuinely still clearing (the message says "still being processed"), but sometimes the outcome could not be determined at all yet (the message says "has not been confirmed yet" and does not say "still being processed") \u2014 an indeterminate state, not a confirmed one, even though neither flag is set. Either way the receipt is saved and you must not pay again, so report it as "payment sent, still settling" without promising the user it definitely succeeded. When the message contains a "Tell the user:" sentence, relay that sentence rather than composing your own reassurance, and if asked what the service said, quote only what the message says it answered. With issuerRejected: true the credential service was reached and refused the request \u2014 the settlement is NOT what failed, but do NOT describe this as the payment having succeeded either: `message` quotes its reason, and you must relay that reason rather than describing it as still settling or as a success. With paymentInvalid: true the service has specifically ruled the payment or receipt invalid \u2014 do NOT say "the settlement is not what failed" for this one, since this verdict IS about the payment; relay what it said instead, and do NOT describe it as a success either. Neither this case nor issuerRejected tells you whether the fee was taken, in either direction \u2014 never tell the user they were not charged, and just as much, never tell them they WERE charged either. That no-claim rule covers issuerRejected and paymentInvalid specifically. The plain no-flag case above is different again, and NOT simply "known to have succeeded" either \u2014 see the note on it above: it is two states, only one of which is confirmed, so read `message` there too rather than assuming success from the shape alone. If the user did NOT ask for a "verified" credential specifically, they most likely want the self-declared, non-verified Basic AI Birthcert instead \u2014 use subscribe_and_issue for that. BEFORE this pays or starts a session, it checks whether this holder already has a Verified AI Birthcert \u2014 found in the local cache, or (if the cache has not seen it yet) resolved from a previously-issued session. If one exists and is STILL VALID, nothing is paid and no session is started \u2014 you get back { existingVerifiedVc: { vcId, validUntil }, message } instead. Show that existing credential to the user and ask whether they actually want to replace it; only call this tool again, with confirmReplaceExistingVc set to exactly existingVerifiedVc.vcId, if they explicitly say yes. Never pass confirmReplaceExistingVc on your own judgement. If the existing VC has already EXPIRED, this proceeds automatically \u2014 no confirmation needed \u2014 and the result carries replacedExpiredVc: { vcId, validUntil } naming the one it replaced. That field can appear on a settled session, on a payment still settling, or on an EARLIER call\'s still-pending session simply being returned unchanged \u2014 so treat it only as "the holder\'s old VC had expired", never as proof that THIS call itself just spent money; read the rest of the result (an error, a settled session, or settlementPending) to know what this call actually did. It can also return { error } specifically because an already-issued VC exists but could not be confirmed as valid or expired (a resolution problem, not a payment problem) \u2014 nothing is paid on that path either; relay `error` as given, since it names the concrete next step (retry check_ai_birthcert_verification, or as a last resort clear_stuck_payment_receipt with the user\'s explicit agreement).',
+      description: 'Start a Verified AI Birthcert issuance session with myid (MyDigital ID owner verification). ALWAYS run credential_preflight for "verified_ai_birthcert" immediately before calling this, even if you checked earlier in the conversation \u2014 preflight is free, this tool spends real funds, and a balance the user topped up a minute ago is not the balance you read before that. If a spending policy refuses the session fee, the result is { error } with `policyDenied: true` (a decision: do not retry) or `policyCheckUnavailable: true` (transient: trying again shortly is right); either way nothing was paid and no session was created. Returns { sessionId, verificationUrl, expiresAt, expiresIn, expiresInSeconds, message } \u2014 show verificationUrl to the human owner and ask them to open it and complete MyDigital ID verification (typically finishes in seconds). Tell them how long the link is good for by quoting `expiresIn` exactly as given: the wallet works it out from its own clock, so never calculate the time remaining yourself from `expiresAt` \u2014 your clock and timezone may differ from the server\'s. `message` here contains a "Tell the user:" sentence about following up \u2014 relay it rather than composing your own reassurance. Once they confirm they are done, call check_ai_birthcert_verification to see whether the credential was issued. Nothing keeps running after this call returns \u2014 there is no background polling, webhook, or timer, so you can only check status when the user sends you a new message. NEVER tell the user you have "set up an automation" or that you will "alert them" when it completes \u2014 you cannot act on your own between messages, and promising that leaves them waiting for a notification that will never come. Instead, tell them how long the link is good for and ask them to message you back once done (or after a few minutes) so you can check_ai_birthcert_verification again. ALWAYS ask the human owner directly what agentName they want to use for a NEW session \u2014 NEVER invent, guess, or silently choose one yourself. (Calling again with the SAME name to resume an already-pending session, as described below, is not "inventing" one \u2014 that is reusing the exact name the owner already gave.) IMPORTANT: agentName must be unique \u2014 if this exact name has already been used to request a Verified AI Birthcert, issuance will fail. Before calling, ask the human owner whether they want to supply any of the optional fields \u2014 agentPurpose, evidenceAssuranceLevel, ownerType, ownerVerified \u2014 do not silently omit them; they only need to say no. Calling this again with the SAME agentName while a prior session is still pending returns that same session unchanged \u2014 no new session is started and nothing is paid again. This tool spends real funds: it self-pays an x402 challenge, subject to the same credential-issuance payment cap as subscribe_and_issue, which by default allows exactly 1 JMYR per call. Set MAX_PAYMENT_AMOUNT to override it; a spending policy that governs the asset replaces the default cap. It can return { error: "..." } instead of a session. Read `message` before deciding what to tell the user or whether retrying is safe \u2014 it does NOT always mean nothing was paid. For insufficient funds or a payment-cap block specifically, nothing is created and nothing was paid, so once the underlying problem is fixed (e.g. the user tops up), calling this tool again is the right next step. Several OTHER { error } shapes mean the opposite: a payment may already have been sent on a prior or even this call (blob_already_settled, a receipt that could not be saved locally, RECEIPT VOID, OUTCOME UNKNOWN) \u2014 for any of those, calling this tool again pays the fee AGAIN, so do NOT retry without explicit agreement from the user, exactly as `message` itself will say. It can also return { settlementPending: true, paymentReceipt, message } instead \u2014 a payment WAS SENT and no session exists yet. That is NOT a failure and NOT an error, but do NOT pay again and do NOT call this tool again to retry it \u2014 call check_ai_birthcert_verification to follow it through instead. It covers three different situations, told apart by the `issuerRejected` and `paymentInvalid` fields. With neither set, do NOT assume the payment is known to have succeeded \u2014 this shape covers TWO different states that look identical from these fields alone: usually the settlement is genuinely still clearing (the message says "still being processed"), but sometimes the outcome could not be determined at all yet (the message says "has not been confirmed yet" and does not say "still being processed") \u2014 an indeterminate state, not a confirmed one, even though neither flag is set. Either way the receipt is saved and you must not pay again, so report it as "payment sent, still settling" without promising the user it definitely succeeded. When the message contains a "Tell the user:" sentence, relay that sentence rather than composing your own reassurance, and if asked what the service said, quote only what the message says it answered. With issuerRejected: true the credential service was reached and refused the request \u2014 the settlement is NOT what failed, but do NOT describe this as the payment having succeeded either: `message` quotes its reason, and you must relay that reason rather than describing it as still settling or as a success. With paymentInvalid: true the service has specifically ruled the payment or receipt invalid \u2014 do NOT say "the settlement is not what failed" for this one, since this verdict IS about the payment; relay what it said instead, and do NOT describe it as a success either. Neither this case nor issuerRejected tells you whether the fee was taken, in either direction \u2014 never tell the user they were not charged, and just as much, never tell them they WERE charged either. That no-claim rule covers issuerRejected and paymentInvalid specifically. The plain no-flag case above is different again, and NOT simply "known to have succeeded" either \u2014 see the note on it above: it is two states, only one of which is confirmed, so read `message` there too rather than assuming success from the shape alone. If the request does not say which kind of AI Birthcert the user wants, do not start this: run credential_preflight for both kinds and ask which they prefer (see its `choice` note), and use this tool only for the Verified kind; if they want the self-declared, non-verified Basic one, use subscribe_and_issue for that. BEFORE this pays or starts a session, it checks whether this holder already has a Verified AI Birthcert \u2014 found in the local cache, or (if the cache has not seen it yet) resolved from a previously-issued session. If one exists and is STILL VALID, nothing is paid and no session is started \u2014 you get back { existingVerifiedVc: { vcId, validUntil }, message } instead. Show that existing credential to the user and ask whether they actually want to replace it; only call this tool again, with confirmReplaceExistingVc set to exactly existingVerifiedVc.vcId, if they explicitly say yes. Never pass confirmReplaceExistingVc on your own judgement. If the existing VC has already EXPIRED, this proceeds automatically \u2014 no confirmation needed \u2014 and the result carries replacedExpiredVc: { vcId, validUntil } naming the one it replaced. That field can appear on a settled session, on a payment still settling, or on an EARLIER call\'s still-pending session simply being returned unchanged \u2014 so treat it only as "the holder\'s old VC had expired", never as proof that THIS call itself just spent money; read the rest of the result (an error, a settled session, or settlementPending) to know what this call actually did. It can also return { error } specifically because an already-issued VC exists but could not be confirmed as valid or expired (a resolution problem, not a payment problem) \u2014 nothing is paid on that path either; relay `error` as given, since it names the concrete next step (retry check_ai_birthcert_verification, or as a last resort clear_stuck_payment_receipt with the user\'s explicit agreement).',
       inputSchema: {
         type: "object",
         properties: {
           agentName: {
             type: "string",
-            description: "A unique, human-readable name for this agent. Must not already be in use for a Verified AI Birthcert, or issuance will fail. ALWAYS ask the human owner directly which name to use for a new session \u2014 NEVER invent, guess, or silently choose one yourself."
+            description: "A unique, human-readable name for this agent. Must not already be in use for a Verified AI Birthcert, or issuance will fail. ALWAYS ask the human owner directly which name to use for a new session \u2014 NEVER invent, guess, or silently choose one yourself. When the user answers with a name \u2014 even a short phrase, even one that repeats words from your question \u2014 that IS the name: use it as given and do not ask for it again, unless it was refused (for example already in use). Tidying it (spaces or capitals, say) is optional and never needed; if you do want to suggest a tidier form, ask and WAIT for their answer, and use the tidied form only after a yes. Never go ahead on a name, or on a payment, that the user has not agreed to. Any example you give is only an example of the format, not a suggestion to use."
           },
           agentPurpose: { type: "string", description: 'Optional \u2014 what this agent does, e.g. "Negotiate and settle supplier invoices".' },
           evidenceAssuranceLevel: { type: "string", description: 'Optional \u2014 assurance level of the identity evidence, e.g. "high".' },
@@ -49484,13 +49964,13 @@ function buildToolList() {
     },
     {
       name: "credential_preflight",
-      description: "FREE readiness check \u2014 call this FIRST, before collecting ANY application detail from the user, whenever they ask for a credential. Spends nothing, signs no transaction, creates no session. Returns { ready, fee, balances, cap, schema?, alreadyHeld?, blockers, notChecked }: the live fee and which side pays gas, the balances that matter, whether the spending limit permits it, and \u2014 for a template credential \u2014 the attributes it requires. `blockers` lists EVERY reason it is not ready at once (a low balance and a too-low spending limit are different problems and both appear together), so one round of fixes is enough rather than discovering them one failed payment at a time. ALWAYS relay `notChecked` too: a clean result is not a guarantee. In particular it does NOT check whether an agent name is free \u2014 myid decides that at issuance, after payment. Report `fee.display` and each balance's `display` to the user, never the raw base-unit numbers. `fee.paymentRequired: false` means issuance is currently FREE \u2014 `fee.display` is then only what it WOULD cost if payment were switched back on, so do not ask the user to fund it and do not present that amount as a charge. Gas is separate and can still block a free credential. When the field is ABSENT the cost is unknown (an older MBI), and it is treated as chargeable \u2014 never report absent as free. If the result has `alreadyHeld`, this wallet already holds a valid copy of that credential: tell the user so, name it, and stop \u2014 do not ask for an agent name or any other detail, and do not begin an issuance. A new one would replace it. Only when the user has explicitly said they want a replacement, run this check with replacing: true.",
+      description: "FREE readiness check \u2014 call this FIRST, before collecting ANY application detail from the user, whenever they ask for a credential. Spends nothing, signs no transaction, creates no session. Returns { ready, fee, balances, cap, schema?, alreadyHeld?, blockers, notChecked }: the live fee and which side pays gas, the balances that matter, whether the spending limit permits it, and \u2014 for a template credential \u2014 the attributes it requires. `blockers` lists EVERY reason it is not ready at once (a low balance and a too-low spending limit are different problems and both appear together), so one round of fixes is enough rather than discovering them one failed payment at a time. ALWAYS relay `notChecked` too: a clean result is not a guarantee. In particular it does NOT check whether an agent name is free \u2014 myid decides that at issuance, after payment. Report `fee.display` and each balance's `display` to the user, never the raw base-unit numbers. `fee.paymentRequired: false` means issuance is currently FREE \u2014 `fee.display` is then only what it WOULD cost if payment were switched back on, so do not ask the user to fund it and do not present that amount as a charge. Tell the user in plain words that it is free or chargeable; never quote JSON field names such as paymentRequired to them. A free credential sends no transaction, so no gas is spent and a missing ZTX balance is not a blocker on it: never ask the user to fund ZTX for a free credential, and if notChecked mentions ZTX, pass it on as a note only. When the field is ABSENT the cost is unknown (an older MBI), and it is treated as chargeable \u2014 never report absent as free. If the result has `alreadyHeld`, this wallet already holds a valid copy of that credential: tell the user so, name it, and stop \u2014 do not ask for an agent name or any other detail, and do not begin an issuance. A new one would replace it. That stop applies to that credential only: the `choice` note still applies to the other kind. Only when the user has explicitly said they want a replacement, run this check with replacing: true. When a user asks for an AI Birthcert and the request does not say which kind they want (Basic, which is self-declared, or Verified, through MyDigital ID), do not pick one: follow the `choice` note in the result, which is to run this check for both kinds, tell the user the difference in plain words, and ask which they prefer.",
       inputSchema: {
         type: "object",
         properties: {
           credential: {
             type: "string",
-            description: 'Which credential to price: "verified_ai_birthcert" for the MyDigital-ID-verified AI Birthcert, or a template id (did:zid:...) / known template name (e.g. "AI Birthcert") for a template-issued one.'
+            description: 'Which credential to price: "verified_ai_birthcert" for the VERIFIED (MyDigital-ID-verified) AI Birthcert, or a template id (did:zid:...) / known template name for a template-issued one \u2014 "AI Birthcert" is the BASIC, self-declared one. For the Verified one use exactly "verified_ai_birthcert": any name containing "birthcert" is priced as the Basic one.'
           },
           agentName: {
             type: "string",
@@ -49566,10 +50046,10 @@ function buildPolicyWriteDeps(input) {
   const templateContract = input.policyTemplateAddress;
   return {
     policyWriteDeps: {
-      ...input.policyWriteUrl ? { client: new PolicyWriteClient(input.policyWriteUrl, (url, init) => fetch(url, init)) } : {},
+      ...input.policyWriteUrl ? { client: new PolicyWriteClient(input.policyWriteUrl, (url, init) => fetch(url, { ...init, signal: AbortSignal.timeout(POLICY_HTTP_TIMEOUT_MS) })) } : {},
       // A self-paid write has no service to catch what the attribute vocabulary would have, so it needs a vocabulary to check against.
       hasVocabularySource: Boolean(input.readVocabulary),
-      receipts: createFsPolicyWriteReceiptStore((0, import_node_path8.join)(input.stateDir, "policy-write-receipts")),
+      receipts: createFsPolicyWriteReceiptStore((0, import_node_path10.join)(input.stateDir, "policy-write-receipts")),
       // The one narrowing left, and it is here rather than at the call site so the call site
       // cannot pass something else entirely. The orchestrator describes an accept as an opaque
       // record because it never reads one; the payer wants the SDK's type.
@@ -49590,7 +50070,10 @@ function buildPolicyWriteDeps(input) {
         selfPay: createSelfPay({
           registryAddress: input.policyRegistryAddress,
           ownerAddress: input.ownerAddress,
-          ...input.selfPayChain
+          ...input.selfPayChain,
+          // One note per (owner, policy key), written before a send and kept until its outcome is settled.
+          // Scoped by network: the same key gives the same address on testnet and mainnet, and a testnet note must not block a mainnet write.
+          markers: createFsSelfPayMarkerStore((0, import_node_path10.join)(input.stateDir, "self-pay-markers", input.network.replace(/[^A-Za-z0-9_-]/g, "-")))
         })
       } : {},
       checkAffordability: (accept) => checkAffordability({ queryBalance: input.queryBalance, caps: input.caps, policyGoverns: input.policyGoverns }, accept),
@@ -49712,8 +50195,8 @@ function asPayRequest(accept) {
 }
 async function main() {
   const fileEnv = loadConfigFileEnv(process.argv, (p) => (0, import_node_fs.readFileSync)(p, "utf8"));
-  const stateDir = (process.env.ZETRIX_WALLET_STATE_DIR ?? fileEnv.ZETRIX_WALLET_STATE_DIR ?? (0, import_node_path8.join)((0, import_node_os2.homedir)(), ".agentic-wallet-mcp")).replace(/\/+$/, "");
-  const accountStore = createFsAccountStore((0, import_node_path8.join)(stateDir, "account.json"));
+  const stateDir = (process.env.ZETRIX_WALLET_STATE_DIR ?? fileEnv.ZETRIX_WALLET_STATE_DIR ?? (0, import_node_path10.join)((0, import_node_os2.homedir)(), ".agentic-wallet-mcp")).replace(/\/+$/, "");
+  const accountStore = createFsAccountStore((0, import_node_path10.join)(stateDir, "account.json"));
   if (process.argv[2] === "export-credentials") {
     const { exitCode } = await exportCredentials({
       getAccount: () => accountStore.get(),
@@ -49733,7 +50216,7 @@ async function main() {
   const config2 = loadConfig(env);
   const hsmPassword = config2.hsmPassword;
   const be = new WalletBeClient(config2.walletBeUrl);
-  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  const sleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
   const { zetrixAddress, holderDid, publicKeyHex, created, didMismatch, activated } = await resolveHolder(
     {
       createAccount: (password) => be.createAccount(password),
@@ -49786,8 +50269,8 @@ async function main() {
   const nodeBaseUrl = `https://${config2.nodeHost}${config2.nodePort ? `:${config2.nodePort}` : ""}`;
   const nodeMetaQuery = (url) => fetch(url, { headers: { Accept: "application/json" } }).then((r) => r.json());
   const resolveTemplateFields = (templateId) => fetchTemplateFields(templateId, config2.templateRegistryAddress, nodeBaseUrl, nodeMetaQuery);
-  const cacheScope = (0, import_node_crypto10.createHash)("sha256").update(`${config2.network}:${zetrixAddress}`).digest("hex");
-  const vcCache = createFsVcCache((0, import_node_path8.join)(config2.stateDir, "vc-cache", cacheScope));
+  const cacheScope = (0, import_node_crypto13.createHash)("sha256").update(`${config2.network}:${zetrixAddress}`).digest("hex");
+  const vcCache = createFsVcCache((0, import_node_path10.join)(config2.stateDir, "vc-cache", cacheScope));
   const mbi = new MbiClient(config2.mbiBaseUrl);
   const messageSigner = (message) => be.signMessage(message, zetrixAddress, hsmPassword);
   const formatAssetAmount = (asset, raw) => describeAssetAmount(asset, raw, contractQuery);
@@ -49839,10 +50322,12 @@ async function main() {
     }
   };
   const { pay, payForCredential, payForPolicyWrite, preflightCaps, policyWriteCaps } = buildPayers(config2, makePay);
-  const downloadQuarantine = createFsDownloadQuarantineStore((0, import_node_path8.join)(config2.stateDir, "ssivc-download-quarantine"));
-  const passImagesDir = (0, import_node_path8.join)(config2.stateDir, "vc-pass-images");
+  const downloadQuarantine = createFsDownloadQuarantineStore((0, import_node_path10.join)(config2.stateDir, "ssivc-download-quarantine"));
+  const passImagesDir = (0, import_node_path10.join)(config2.stateDir, "vc-pass-images");
+  const verificationQrFiles = createFsQrFileStore((0, import_node_path10.join)(config2.stateDir, "verification-qr"));
+  void verificationQrFiles.sweep().catch(() => void 0);
   const verifyAiBirthcert = config2.ssivcBaseUrl ? (() => {
-    const ssivcSessionStore = createFsSsivcSessionStore((0, import_node_path8.join)(config2.stateDir, "ssivc-session.json"));
+    const ssivcSessionStore = createFsSsivcSessionStore((0, import_node_path10.join)(config2.stateDir, "ssivc-session.json"));
     const ssivc = new SsivcClient(config2.ssivcBaseUrl);
     const verifyAiBirthcertDeps = {
       ssivc,
@@ -49979,6 +50464,16 @@ async function main() {
         // The same submit wrapper transfer_token uses, so a node refusal is told apart from an answer that never came.
         submit: transferDeps.submit,
         queryNativeBalance: () => queryTokenBalance2("ZTX"),
+        // The current ledger, so a self-paid transaction can carry an expiry. `undefined` when it cannot be read.
+        currentLedger: async () => {
+          try {
+            const r = await sdk.block.getNumber();
+            const n = r.errorCode === 0 ? r.result?.header?.blockNumber : void 0;
+            return n === void 0 ? void 0 : String(n);
+          } catch {
+            return void 0;
+          }
+        },
         // What became of a submitted transaction, so one that was included and then rejected by the contract (the gas is still spent)
         // is reported as that.
         getTransaction: buildTransactionLookup((hash) => sdk.transaction.getInfo(hash))
@@ -50006,7 +50501,9 @@ async function main() {
       signHexBlob: walletBeSignerFn,
       signMessage: messageSigner,
       linkTemplate: config2.myidVerifyLinkTemplate,
-      renderQr: renderQrPng
+      renderQr: renderQrPng,
+      // A chat channel (WhatsApp) sends files, not MCP image blocks: without a file the agent has no QR to attach.
+      saveQr: (png, referenceId, expiresAtMs) => verificationQrFiles.save(png, referenceId, expiresAtMs)
     }),
     verifyAiBirthcert,
     // So credential_preflight can say "you already have one" before the agent asks the user for anything.
@@ -50025,7 +50522,7 @@ async function main() {
     if (!fn) throw new Error(`Unknown tool: ${name}`);
     try {
       const result = await fn(args ?? {});
-      return { content: await buildToolContent(result, (p) => (0, import_promises7.readFile)(p)) };
+      return { content: await buildToolContent(result, (p) => (0, import_promises10.readFile)(p)) };
     } catch (err) {
       const chain = [];
       let e = err;