agentic-wallet-mcp 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -8,6 +8,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > Entries for 0.5.0 and earlier were reconstructed from commit history when this file was
 > introduced in 0.6.0, so they summarise each release rather than being exhaustive.
 
+## [0.12.0] — 22 September 2026
+
+### Added
+
+- **Three free policy read tools**: `get_policy_template_schema` (which spending rules a template
+  allows), `get_my_policy` (the policies this owner has deployed on chain) and `policy_preflight`
+  (is a draft policy valid, and does it MEAN what the user thinks). All read-only: they sign
+  nothing, spend nothing and deploy nothing. Each reports a three-state result, so "this network has
+  no policy system" is never reported as "you have no policy".
+- **`clear_stuck_payment_receipt`**: the supported way to discard a Verified AI Birthcert payment
+  receipt the wallet is holding and refusing to pay past — previously only possible by deleting a
+  file on the server, which a hosted subscriber cannot do. Two steps by construction: the first call
+  clears nothing and returns the receipt id, and clearing requires echoing that exact id back.
+- **`request_ai_birthcert_verification` gains `discardStuckReceiptAndPayFresh`**: discard a stuck
+  receipt and pay again in one call. Takes the receipt id, never a boolean, so a receipt cannot be
+  discarded that was not first shown to the user. Refuses a mismatched id, a receipt belonging to a
+  live session, and combination with `dryRun` — spending nothing in each case.
+- **`SETTLEMENT_STUCK_AFTER_MS`** (default `86400000`, 24h): how long an unconfirmed settlement may
+  stay unresolved before the wallet stops calling it "still settling" and calls it permanently stuck.
+
+### Changed
+
+- **`check_ai_birthcert_verification` now advances a queued settlement** instead of only reporting
+  it. It replays the saved receipt — never a new payment — and returns the live session once it
+  settles, so "check back in a few minutes" genuinely progresses the flow.
+- **A queued settlement no longer blocks the tool call for ~20 minutes.** It returns within a bounded
+  wall-clock budget (`SETTLEMENT_WAIT_BUDGET_MS`, default 90s) as
+  `{ settlementPending: true, paymentReceipt, message }` — the payment succeeded and is in flight,
+  which is not an error.
+- **Settlement messages lead with their verdict** (`PAYMENT SENT` / `OUTCOME UNKNOWN` / `RECEIPT VOID`)
+  and carry `paymentReceipt` as its own field, so an assistant summarising the result cannot turn
+  "we do not know yet" into "it failed".
+- **The three settlement verdicts are now told apart.** A receipt the service declares finished is
+  terminal and reported as `status: "receipt_void"`; an unresolved one is judged by the receipt's own
+  age — recent means "still settling, check back", older than `SETTLEMENT_STUCK_AFTER_MS` means
+  "this is not coming back". None of them claims the fee was refunded: a settlement can expire after
+  the money has already moved, so the receipt id is always handed back for support.
+
+### Fixed
+
+- A stuck receipt no longer dead-ends. The wallet still refuses to buy a new credential while one is
+  held — that refusal is what prevents a second charge — but it now names the way out and states
+  plainly that starting over costs the fee a second time.
+
 ## [0.11.0] — 17 September 2026
 
 ### Added

package/README.md

@@ -28,8 +28,9 @@ VC issuance → identity proof → pay-per-use).
 | `create_holder_account` | Onboarding: mint an HSM account (the MCP already auto-creates one at startup if `ZETRIX_ADDRESS` is omitted — see Environment below). Always checks for an existing account first — if one is active for this session, returns `{ alreadyExists: true, existing }` without creating anything; pass `confirmNew: true` (after asking the user) to mint a new one anyway | `{ password, label?, purpose?, confirmNew? }` | `{ created, alreadyExists, existing?, zetrixAddress?, holderDid?, publicKeyHex?, message }` |
 | `get_template_schema` | **Free** read of a VC template's declared attribute schema. Call before `subscribe_and_issue` to learn which attributes it requires | `{ templateId }` | `{ templateId, schema: { required, optional } }` or `{ templateId, error }` |
 | `query_contract` | Read-only query against any Zetrix contract — call an arbitrary method and return its raw result. No signing, no state change | `{ contractAddress, method, params? }` | `{ ok: true, result }` or `{ ok: false, error }` |
-| `request_ai_birthcert_verification` | Start a **Verified** AI Birthcert issuance session with myid (MyDigital ID owner verification) — distinct from `subscribe_and_issue`'s self-declared Basic AI Birthcert. Optional `gasPayer` (`"sponsored"` \| `"self"`) overrides the gas payer for this call only — precedence is per-call `gasPayer` > `GAS_PREFERENCE` config > `sponsored` hardcoded default. If a sponsored quote is refused before any money moved, the wallet automatically falls back to paying gas itself; it never falls back once payment is merely pending/indeterminate. `dryRun: true` quotes instead of paying: it stops after the 402 challenge, pays nothing, creates no session, and returns `{ quote }` — the asset, the amount and which side pays gas. Quote and paid request send byte-identical signed bodies | `{ agentName, agentPurpose?, evidenceAssuranceLevel?, ownerType?, ownerVerified?, gasPayer?, dryRun? }` | `{ sessionId, verificationUrl, expiresAt }` or `{ quote: { asset, maxAmountRequired, payTo?, gasModel } }` |
-| `check_ai_birthcert_verification` | **Free.** Poll the most recently requested Verified AI Birthcert session; on `status: "issued"`, also fetches, verifies, and caches the credential. While the session is still open it replays the stored `verificationUrl` alongside SSIVC's live `expiresAt` — SSIVC issues the link only once, at creation, so this store is the only place it survives. That makes *"where is my link?"* answerable without touching the paid tool. No link is returned once `status` is `"issued"`: the link is spent | (none) | `{ status: "pending" \| "issued" \| "no_session", verificationUrl?, expiresAt?, vcId?, vc?, cacheError? }` |
+| `request_ai_birthcert_verification` | Start a **Verified** AI Birthcert issuance session with myid (MyDigital ID owner verification) — distinct from `subscribe_and_issue`'s self-declared Basic AI Birthcert. Optional `gasPayer` (`"sponsored"` \| `"self"`) overrides the gas payer for this call only — precedence is per-call `gasPayer` > `GAS_PREFERENCE` config > `sponsored` hardcoded default. If a sponsored quote is refused before any money moved, the wallet automatically falls back to paying gas itself; it never falls back once payment is merely pending/indeterminate. `dryRun: true` quotes instead of paying: it stops after the 402 challenge, pays nothing, creates no session, and returns `{ quote }` — the asset, the amount and which side pays gas. Quote and paid request send byte-identical signed bodies | `{ agentName, agentPurpose?, evidenceAssuranceLevel?, ownerType?, ownerVerified?, gasPayer?, dryRun?, discardStuckReceiptAndPayFresh? }` | `{ sessionId, verificationUrl, expiresAt }`, `{ quote: { asset, maxAmountRequired, payTo?, gasModel } }`, or — when the sponsored settlement is still clearing after ~90s — `{ settlementPending: true, paymentReceipt, message }`, which means the payment SUCCEEDED and is in progress, not that it failed. While a stuck receipt is held this tool can only REPLAY it — it never buys a new credential, which is what stops a second charge. `discardStuckReceiptAndPayFresh: "<exact receipt id>"` is the way to start over: it throws that payment away and pays the fee again, refuses a mismatched id (discarding and paying nothing), refuses a receipt that belongs to a live session, and returns `discardedPaymentReceipt` so the lost payment stays traceable |
+| `check_ai_birthcert_verification` | **Free** (never pays). Poll the most recently requested Verified AI Birthcert session; on `status: "issued"`, also fetches, verifies, and caches the credential. While the session is still open it replays the stored `verificationUrl` alongside SSIVC's live `expiresAt` — SSIVC issues the link only once, at creation, so this store is the only place it survives. That makes *"where is my link?"* answerable without touching the paid tool. No link is returned once `status` is `"issued"`: the link is spent. If a prior payment is still clearing this tool **advances** it — it replays the saved receipt (never a new payment) and returns the live session once it settles, so "check back in a few minutes" genuinely progresses the flow | (none) | `{ status: "pending" \| "issued" \| "no_session" \| "settlement_pending" | "receipt_void", verificationUrl?, expiresAt?, vcId?, vc?, cacheError?, paymentReceipt?, outcomeUnknown?, message? }` — `settlement_pending` means a payment was made and is being followed: without `outcomeUnknown` it is queued and progressing (check again shortly); with `outcomeUnknown: true` the outcome could not be determined at all and has been unresolved longer than `SETTLEMENT_STUCK_AFTER_MS` (24h default), so it is not coming back on its own — `stuckFor` says how long, the fee was most likely already taken, and quoting `paymentReceipt` to support is the way forward. Starting over via `clear_stuck_payment_receipt` costs a second fee. `receipt_void` is terminal and different: SSIVC has ruled the receipt finished (status_code 67 expired / 68 failed), so checking again cannot help — it does NOT mean the fee was refunded, and buying the credential means paying again |
+| `clear_stuck_payment_receipt` | **Free, last resort, destructive.** Discard a stuck Verified AI Birthcert payment receipt the wallet is holding and refusing to pay past — the supported replacement for deleting `<stateDir>/ssivc-session.json` by hand, which a hosted subscriber cannot do. Two steps by construction: with no argument it clears nothing and returns the receipt id plus a warning; clearing requires echoing that exact id back as `confirmReceiptId`, and a mismatch clears nothing. If the settlement completed in between — which is what happens when you follow the advice to call `check_ai_birthcert_verification` first — the receipt now belongs to a **live, paid-for session**, and the id alone no longer clears it: the tool hands back `sessionId` and `verificationUrl` instead, and only `confirmDiscardLiveSession: true` will discard them. The discarded payment is unrecoverable | `{ confirmReceiptId?, confirmDiscardLiveSession? }` | `{ cleared, paymentReceipt?, requiresConfirmation?, sessionId?, verificationUrl?, message?, error? }` |
 
 > **VCs are cached locally**, keyed by `templateId`, under `~/.agentic-wallet-mcp/vc-cache/`
 > (scoped per network + holder — different identities or networks never share a cache).
@@ -183,6 +184,8 @@ Node ≥ 18 required (built-in `fetch`).
 | `AI_BIRTHCERT_VERIFIED_TEMPLATE_ID` | no | The Verified AI Birthcert's on-chain `did:zid:...` template id. Auto-derived per network by default — **the mainnet default is unverified**, so override this explicitly once the mainnet template id is confirmed |
 | `GAS_PREFERENCE` | no | `sponsored` or `self` — the default gas payer for the Verified AI Birthcert flow (`request_ai_birthcert_verification`). **Defaults to `sponsored`; any unrecognised value also falls back to `sponsored`** rather than throwing. Sponsorship only actually engages when the resource server's x402 quote offers a sponsored option (`extra.gasModel: "facilitator"`) — a server that only quotes self-pay behaves unchanged. **Sponsorship is testnet-only today**; override per-call with the tool's `gasPayer` parameter |
 | `MAX_SETTLEMENT_ATTEMPTS` | no | Cap on retry attempts while polling a sponsored payment for settlement after SSIVC returns `202 Accepted` (queued). **Defaults to `20`; a non-positive or unparseable value also falls back to `20`** |
+| `SETTLEMENT_WAIT_BUDGET_MS` | no | Total time `request_ai_birthcert_verification` **and** `check_ai_birthcert_verification` will each wait for a queued settlement before returning `{ settlementPending: true }` / `{ status: "settlement_pending" }` — `check_` advances the settlement too, so it can block for this long. The attempt cap alone cannot bound this, because the delay between attempts is server-supplied. At least one poll always happens, even if the budget is shorter than the first retry delay. Not capped at the top end — raising it *and* `MAX_SETTLEMENT_ATTEMPTS` together can reinstate the long blocking call this budget exists to prevent, so raise it deliberately and temporarily. **Defaults to `90000` (90s); a non-positive or unparseable value also falls back to `90000`** |
+| `SETTLEMENT_STUCK_AFTER_MS` | no | How long a settlement SSIVC cannot confirm may stay unresolved before `check_ai_birthcert_verification` stops calling it "still settling" and calls it permanently stuck. SSIVC returns the same `status_code 69` for a settlement two minutes old and one three weeks old, so the receipt's own age is what separates *"payment sent, check back shortly"* from *"this is not coming back, the fee was most likely already taken, and starting over costs a second fee"*. This changes **only the wording**: either side of the line the wallet never pays again and never discards the receipt by itself. **Defaults to `86400000` (24h); a non-positive or unparseable value also falls back to `86400000`** |
 
 \* sensitive — never logged, never returned in a tool result, and never a tool parameter.
 

package/dist/server-bundle.cjs

@@ -12539,6 +12539,7 @@ var index_exports = {};
 __export(index_exports, {
   asPayRequest: () => asPayRequest,
   buildPayers: () => buildPayers,
+  buildSettlementWiring: () => buildSettlementWiring,
   buildToolList: () => buildToolList
 });
 module.exports = __toCommonJS(index_exports);
@@ -12551,7 +12552,7 @@ var import_node_path7 = require("node:path");
 // package.json
 var package_default = {
   name: "agentic-wallet-mcp",
-  version: "0.11.0",
+  version: "0.12.0",
   description: "Agent-facing MCP wallet for Zetrix \u2014 orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   keywords: [
     "mcp",
@@ -12589,7 +12590,8 @@ var package_default = {
     build: "tsc --noEmit && esbuild src/index.ts --bundle --platform=node --target=node18 --format=cjs --external:zetrix-sdk-nodejs --outfile=dist/server-bundle.cjs",
     test: "vitest run",
     "test:watch": "vitest",
-    typecheck: "tsc --noEmit"
+    typecheck: "tsc --noEmit",
+    "typecheck:tests": "tsc --noEmit -p tsconfig.test.json"
   },
   dependencies: {
     "@modelcontextprotocol/sdk": "^1.0.0",
@@ -21615,6 +21617,12 @@ function deriveMbiBaseUrl(network) {
 function deriveTemplateRegistryAddress(network) {
   return network.includes("testnet") ? "ZTX3JszqPgRUx743SAp7q7zURfjvkWuH2FMEz" : "ZTX3GqJM1U6ifMPonwD4fGvrgoTKJua7b2cKX";
 }
+function derivePolicyRegistryAddress(network) {
+  return isTestnet(network) ? "ZTX3Z2Fgsssx5fVq5v8EnhTBh6mqxJ8FQFqnk" : void 0;
+}
+function derivePolicyTemplateAddress(network) {
+  return isTestnet(network) ? "ZTX3WfTbuZwsLQDWe4f7mzrfULiNdDU84BLJ5" : void 0;
+}
 function deriveSsivcBaseUrl(network) {
   return network.includes("testnet") ? "https://ssivc-api-uat.myegdev.com/api" : void 0;
 }
@@ -21633,6 +21641,7 @@ function defaultCredentialIssuanceCaps(network) {
   return jmyr ? { [jmyr]: "1000000", "*": "0" } : { "*": "0" };
 }
 var KNOWN_NETWORKS = ["zetrix:testnet", "zetrix:mainnet"];
+var SETTLEMENT_WAIT_BUDGET_WARN_MS = 6e5;
 function isTestnet(network) {
   return network.includes("testnet");
 }
@@ -21679,6 +21688,8 @@ function loadConfig(env) {
     nodePort: opt("ZETRIX_NODE_PORT") ?? "",
     templateRegistryAddress: opt("ZETRIX_TEMPLATE_REGISTRY_ADDRESS") ?? deriveTemplateRegistryAddress(network),
     zidResolverBaseUrl: stripTrailingSlash(opt("ZID_RESOLVER_BASE_URL") ?? deriveZidResolverBaseUrl(network)),
+    policyRegistryAddress: opt("POLICY_REGISTRY_ADDRESS") ?? derivePolicyRegistryAddress(network),
+    policyTemplateAddress: opt("POLICY_TEMPLATE_ADDRESS") ?? derivePolicyTemplateAddress(network),
     // Fail closed: an unset cap means "spend nothing", not "spend anything". A wallet that starts
     // with no configuration at all must not be able to auto-pay a hostile x402 challenge. Raising
     // it is a deliberate act.
@@ -21698,6 +21709,33 @@ function loadConfig(env) {
     maxSettlementAttempts: (() => {
       const attempts = Number(env.MAX_SETTLEMENT_ATTEMPTS);
       return Number.isInteger(attempts) && attempts > 0 ? attempts : 20;
+    })(),
+    // APP-L02: deliberately NOT clamped to a ceiling. This is the ops escape hatch for a slow
+    // paymaster, and a hard cap turns a tuning knob into a wall with no way around it. Setting it
+    // very high cannot restore worse-than-before behaviour on its own either: maxSettlementAttempts
+    // still bounds the loop independently, so the old ~20-minute block needs BOTH knobs
+    // raised, deliberately.
+    //
+    // It IS warned about, though, on the same stderr channel parsePaymentCaps already uses above —
+    // an earlier version of this comment claimed no logging channel existed, which was simply wrong.
+    settlementWaitBudgetMs: (() => {
+      const ms = Number(env.SETTLEMENT_WAIT_BUDGET_MS);
+      const budget = Number.isInteger(ms) && ms > 0 ? ms : 9e4;
+      if (budget > SETTLEMENT_WAIT_BUDGET_WARN_MS) {
+        process.stderr.write(
+          `agentic-wallet-mcp: SETTLEMENT_WAIT_BUDGET_MS is ${budget}ms \u2014 request_ai_birthcert_verification and check_ai_birthcert_verification can each block a caller for that long (the budget bounds both). Above ~${SETTLEMENT_WAIT_BUDGET_WARN_MS}ms this reinstates the long blocking call the 90s default exists to prevent. Intended for temporary debugging only.
+`
+        );
+      }
+      return budget;
+    })(),
+    // Not clamped and not warned about: unlike the wait budget, nothing blocks on this —
+    // it only decides which of two true statements the user is told about a receipt SSIVC will not
+    // resolve. Setting it very low makes the wallet give up on the wording early (it still never
+    // pays again or discards anything on its own); very high just means it keeps saying "check back".
+    settlementStuckAfterMs: (() => {
+      const ms = Number(env.SETTLEMENT_STUCK_AFTER_MS);
+      return Number.isInteger(ms) && ms > 0 ? ms : 864e5;
     })()
   };
 }
@@ -23205,6 +23243,317 @@ function uncheckable(isVerified, isFree = false) {
   return items;
 }
 
+// src/clients/policy-read-client.ts
+async function queryPolicy(contractAddress, method, params, query) {
+  let response;
+  try {
+    response = await query({
+      contractAddress,
+      input: JSON.stringify({ method, params }),
+      optType: 2
+    });
+  } catch (e) {
+    return { ok: false, detail: `${method}: RPC call failed \u2014 ${e.message}` };
+  }
+  if (response?.errorCode !== 0) {
+    return { ok: false, detail: `${method}: contract call failed with errorCode ${response?.errorCode}` };
+  }
+  const entries = response.result?.query_rets;
+  if (!entries || entries.length === 0) {
+    return { ok: false, detail: `${method}: no query_rets returned` };
+  }
+  const raw = entries[entries.length - 1]?.result?.value;
+  if (raw === void 0) {
+    return { ok: false, detail: `${method}: no result value in the final query_rets entry` };
+  }
+  try {
+    return { ok: true, value: JSON.parse(raw) };
+  } catch {
+    return { ok: false, detail: `${method}: result was not JSON \u2014 ${raw}` };
+  }
+}
+async function getPolicyContract(owner, registryAddress, query) {
+  if (typeof owner !== "string" || owner.trim() === "") {
+    return {
+      error: "query_failed",
+      detail: "owner is required: the Registry answers an absent owner with {found:false}, which cannot be told apart from an owner who genuinely has no policy"
+    };
+  }
+  const raw = await queryPolicy(registryAddress, "getPolicyContract", { owner }, query);
+  if (!raw.ok) return { error: "query_failed", detail: raw.detail };
+  const value = raw.value;
+  if (!value || value.found !== true) return { found: false };
+  if (typeof value.address !== "string" || value.address === "") {
+    return { error: "query_failed", detail: "getPolicyContract: found:true without a usable address" };
+  }
+  return { found: true, value: value.address };
+}
+function toTemplateRead(raw) {
+  if (!raw.ok) return { error: "query_failed", detail: raw.detail };
+  const value = raw.value;
+  if (!value || value.found !== true) return { found: false };
+  return { found: true, value };
+}
+async function getTemplateViaRegistry(publisher, policyKey, registryAddress, query) {
+  return toTemplateRead(await queryPolicy(registryAddress, "getTemplate", { publisher, policyKey }, query));
+}
+async function getTemplateById(templateId, templateAddress, query) {
+  return toTemplateRead(await queryPolicy(templateAddress, "getTemplateById", { templateId }, query));
+}
+function declaredVocabulary(template) {
+  const vocab = /* @__PURE__ */ new Map();
+  for (const entry of template.attributes ?? []) {
+    if (typeof entry?.attributeName === "string" && entry.attributeName !== "") {
+      vocab.set(entry.attributeName, typeof entry.attributeType === "string" ? entry.attributeType : "");
+    }
+  }
+  return vocab;
+}
+var KEY_COUNT_WARNING_THRESHOLD = 50;
+async function listPolicyKeys(policyAddress, query) {
+  const raw = await queryPolicy(policyAddress, "listPolicyKeys", {}, query);
+  if (!raw.ok) return { error: "query_failed", detail: raw.detail };
+  if (!Array.isArray(raw.value)) {
+    return { error: "query_failed", detail: "listPolicyKeys: expected an array of key strings" };
+  }
+  return { found: true, value: raw.value.filter((k) => typeof k === "string") };
+}
+async function getPolicyByKey(policyAddress, policyKey, query) {
+  const raw = await queryPolicy(policyAddress, "getPolicy", { policyKey }, query);
+  if (!raw.ok) return { error: "query_failed", detail: raw.detail };
+  const value = raw.value;
+  if (!value || value.found !== true) return { found: false };
+  return { found: true, value };
+}
+async function readOwnerPolicies(owner, registryAddress, query) {
+  const contract = await getPolicyContract(owner, registryAddress, query);
+  if (!("found" in contract) || contract.found !== true) {
+    return { contract, keys: null, policies: [] };
+  }
+  const keys = await listPolicyKeys(contract.value, query);
+  if (!("found" in keys) || keys.found !== true) {
+    return { contract, keys, policies: [] };
+  }
+  const policies = [];
+  for (const policyKey of keys.value) {
+    policies.push({ policyKey, result: await getPolicyByKey(contract.value, policyKey, query) });
+  }
+  const warning = keys.value.length > KEY_COUNT_WARNING_THRESHOLD ? `This owner has ${keys.value.length} policy keys; reading them all costs ${keys.value.length + 2} chain calls.` : void 0;
+  return { contract, keys, policies, ...warning ? { warning } : {} };
+}
+
+// src/policy-window-rules.ts
+var WINDOW_RULES = [
+  {
+    cap: "cumulativeMax",
+    window: "cumulativeWindow",
+    outcome: "lifetime",
+    withoutWindowMeans: 'a cap for the entire lifetime of this policy, not per period \u2014 "RM500 a month" written this way silently means "RM500 ever"'
+  },
+  {
+    cap: "velocityCap",
+    window: "velocityWindow",
+    outcome: "denied",
+    withoutWindowMeans: "rejected outright as VALUE_INVALID \u2014 a rate limit with no period is meaningless, so unlike a cumulative cap it is not quietly treated as lifetime"
+  },
+  {
+    cap: "maxTransactionCount",
+    window: "countWindow",
+    outcome: "not-requested",
+    withoutWindowMeans: "not a limit at all \u2014 without its window this dimension was not asked for, which is NOT the same as an unlimited-period count"
+  }
+];
+function windowRuleFor(attributeName) {
+  return WINDOW_RULES.find((rule) => rule.cap === attributeName);
+}
+var INFORMATIONAL_ATTRIBUTES = /* @__PURE__ */ new Set(["approvalPolicy", "settlementChannel"]);
+var QUALIFIER_ATTRIBUTES = /* @__PURE__ */ new Set([
+  "assetScope",
+  "unknownAttributePolicy",
+  ...WINDOW_RULES.map((rule) => rule.window)
+]);
+function isListAttribute(attributeName) {
+  return /_list$/i.test(attributeName) || /[a-z0-9]List$/.test(attributeName);
+}
+
+// src/orchestrator/policy-preflight.ts
+var NUMERIC_TYPES = /* @__PURE__ */ new Set(["uint", "uint256", "int", "number"]);
+var BOOLEAN_TYPES = /* @__PURE__ */ new Set(["bool", "boolean"]);
+function isNumericString(value) {
+  return typeof value === "string" && /^\d+$/.test(value);
+}
+function isEmptyList(value) {
+  const trimmed = value.trim();
+  if (trimmed === "" || trimmed === "[]") return true;
+  try {
+    const parsed = JSON.parse(trimmed);
+    return Array.isArray(parsed) && parsed.length === 0;
+  } catch {
+    return false;
+  }
+}
+function baseNotChecked(network) {
+  const items = [
+    "Whether the policy will actually be ENFORCED. Nothing outside the policy registry currently consults the decision service, so a valid policy may gate nothing today.",
+    "Whether the write will be accepted, and what it will cost \u2014 the deploy path is not built yet.",
+    "Whether a decision would currently be ALLOW, STEP_UP or DENY \u2014 that needs off-chain spend state this wallet cannot read. A clean preflight is not permission to spend."
+  ];
+  if (network && !network.includes("testnet")) {
+    items.push(
+      `On ${network} none of this is deployed \u2014 there is no policy registry to read, so nothing here has been checked against a real contract.`
+    );
+  }
+  return items;
+}
+function unavailableResult(policyKey, reason, network) {
+  return {
+    policyKey,
+    ready: false,
+    blockers: [reason],
+    interpretation: [],
+    notChecked: baseNotChecked(network)
+  };
+}
+function structuralBlockers(draft) {
+  const blockers = [];
+  if (typeof draft?.policyKey !== "string" || draft.policyKey === "") {
+    blockers.push("policyKey is required \u2014 it is the key this policy would be stored under.");
+  }
+  if (!Array.isArray(draft?.attributes)) {
+    blockers.push("attributes must be an array of { attributeName, attributeType, value } rules.");
+  } else if (draft.attributes.some(
+    (a) => !a || typeof a !== "object" || typeof a.attributeName !== "string"
+  )) {
+    blockers.push("every entry in attributes must be an object with a string attributeName.");
+  }
+  return blockers;
+}
+function checkAttribute(attribute, vocabulary, present) {
+  const blockers = [];
+  const interpretation = [];
+  const notChecked = [];
+  const { attributeName: name, value } = attribute;
+  if (vocabulary && !vocabulary.has(name)) {
+    blockers.push(
+      `"${name}" is not declared by this template, so it would deploy and then enforce nothing. Declared attributes are: ${[...vocabulary.keys()].join(", ")}.`
+    );
+    return { blockers, interpretation, notChecked };
+  }
+  if (INFORMATIONAL_ATTRIBUTES.has(name)) {
+    interpretation.push(
+      `"${name}" is informational only and is never enforced \u2014 it records an intention and restricts nothing. Do not rely on it as a control.`
+    );
+  }
+  const rule = windowRuleFor(name);
+  if (rule && !present.has(rule.window)) {
+    if (rule.outcome === "denied") {
+      blockers.push(
+        `"${name}" has no "${rule.window}", so the chain rejects it as VALUE_INVALID: ${rule.withoutWindowMeans}.`
+      );
+    } else {
+      interpretation.push(`"${name}" has no "${rule.window}", so it means ${rule.withoutWindowMeans}.`);
+    }
+  } else if (rule) {
+    interpretation.push(`"${name}" is measured over each "${rule.window}" period, not over the policy's lifetime.`);
+  }
+  if (isListAttribute(name)) {
+    if (isEmptyList(value)) {
+      blockers.push(
+        `"${name}" is an empty list, which denies EVERYTHING \u2014 an empty list contains no one, so every recipient fails the check. This is stored and enforced exactly as written.`
+      );
+    } else {
+      interpretation.push(`"${name}" allows ONLY the entries listed; everything absent from it is denied.`);
+    }
+    return { blockers, interpretation, notChecked };
+  }
+  const type = vocabulary?.get(name) ?? attribute.attributeType;
+  if (NUMERIC_TYPES.has(type) && !isNumericString(value)) {
+    blockers.push(`"${name}" is declared ${type} but its value "${value}" is not a whole number.`);
+  } else if (BOOLEAN_TYPES.has(type) && value !== "true" && value !== "false") {
+    blockers.push(`"${name}" is declared ${type} but its value "${value}" is not true or false.`);
+  } else if (!NUMERIC_TYPES.has(type) && !BOOLEAN_TYPES.has(type)) {
+    notChecked.push(
+      `Whether "${name}"'s value suits its declared type "${type}" \u2014 that type is not one this wallet knows how to check.`
+    );
+  } else if (vocabulary && !INFORMATIONAL_ATTRIBUTES.has(name) && !rule) {
+    interpretation.push(`"${name}" is limited to ${value}.`);
+  }
+  return { blockers, interpretation, notChecked };
+}
+function checkBlockRange(draft) {
+  const blockers = [];
+  if (!isNumericString(draft.validFromBlock)) {
+    blockers.push(`validFromBlock must be a whole number written as a string, got "${draft.validFromBlock}".`);
+  }
+  if (!isNumericString(draft.validToBlock)) {
+    blockers.push(`validToBlock must be a whole number written as a string, got "${draft.validToBlock}".`);
+  }
+  if (isNumericString(draft.validFromBlock) && isNumericString(draft.validToBlock) && // "0" means no end date, so from > to is not an inversion here.
+  BigInt(draft.validToBlock) !== 0n && BigInt(draft.validFromBlock) > BigInt(draft.validToBlock)) {
+    blockers.push(
+      `validFromBlock (${draft.validFromBlock}) is after validToBlock (${draft.validToBlock}), so this policy would never be in force.`
+    );
+  }
+  return blockers;
+}
+async function policyPreflight(deps, draft) {
+  const notChecked = baseNotChecked(deps.network);
+  const structural = structuralBlockers(draft);
+  if (structural.length > 0) {
+    return {
+      policyKey: typeof draft?.policyKey === "string" ? draft.policyKey : "",
+      ready: false,
+      blockers: structural,
+      interpretation: [],
+      notChecked
+    };
+  }
+  const blockers = [];
+  const interpretation = [];
+  const template = await deps.readTemplate(draft);
+  if ("error" in template) {
+    blockers.push(`Could not read the template (${template.detail}) \u2014 retry before deploying.`);
+  } else if (template.found === false) {
+    blockers.push(
+      `No template found for this policy. A policy whose template does not exist declares no vocabulary, so nothing in it can be enforced.`
+    );
+  }
+  const vocabulary = "found" in template && template.found === true ? declaredVocabulary(template.value) : null;
+  const declared = vocabulary ? [...vocabulary.keys()] : void 0;
+  if (!vocabulary) {
+    interpretation.push(
+      "The template could not be read, so what these rules actually mean cannot be confirmed. Treat nothing below as verified until the template resolves."
+    );
+  }
+  if (draft.attributes.length === 0) {
+    blockers.push("This policy has no attributes \u2014 it would deploy successfully and restrict nothing.");
+  }
+  const present = new Set(draft.attributes.map((attribute) => attribute.attributeName));
+  for (const attribute of draft.attributes) {
+    const found = checkAttribute(attribute, vocabulary, present);
+    blockers.push(...found.blockers);
+    interpretation.push(...found.interpretation);
+    notChecked.push(...found.notChecked);
+  }
+  const enforceable = draft.attributes.filter(
+    (attribute) => !QUALIFIER_ATTRIBUTES.has(attribute.attributeName) && !INFORMATIONAL_ATTRIBUTES.has(attribute.attributeName)
+  );
+  if (draft.attributes.length > 0 && enforceable.length === 0) {
+    blockers.push(
+      `This policy has no enforceable constraint \u2014 only qualifiers and informational values. It answers NO_ENFORCEABLE_CONSTRAINTS, which is a DENY, so the agent could spend nothing at all.`
+    );
+  }
+  blockers.push(...checkBlockRange(draft));
+  return {
+    policyKey: draft.policyKey,
+    ready: blockers.length === 0,
+    ...declared ? { declared } : {},
+    blockers,
+    interpretation,
+    notChecked
+  };
+}
+
 // src/mcp-tools.ts
 async function loadValidCachedCredentials(cache) {
   if (!cache) return [];
@@ -23363,11 +23712,86 @@ function createTools(deps) {
         input
       );
     },
+    /**
+     * Free vocabulary lookup. Prefers the Registry proxy when given publisher+policyKey, because
+     * the Registry holds the Template address it trusts and the proxied reply also carries
+     * templateAttributeIds. Falls back to a direct Template call for an id-only lookup, which the
+     * Registry does not proxy.
+     */
+    async get_policy_template_schema(input = {}) {
+      const registry2 = deps.config.policyRegistryAddress;
+      const templateContract = deps.config.policyTemplateAddress;
+      const hasPair = Boolean(input.publisher && input.policyKey);
+      if (!registry2 && !templateContract) {
+        return { error: `Policy contracts are not deployed on ${deps.config.network}.` };
+      }
+      if (!hasPair && !input.templateId) {
+        return { error: "Provide either { publisher, policyKey } or { templateId }." };
+      }
+      const read = input.templateId ? templateContract ? await getTemplateById(input.templateId, templateContract, deps.chainQuery) : null : registry2 ? await getTemplateViaRegistry(input.publisher, input.policyKey, registry2, deps.chainQuery) : null;
+      if (!read) {
+        return {
+          error: input.templateId ? `A templateId lookup needs the policy template contract, which is not configured on ${deps.config.network}.` : `A publisher + policyKey lookup needs the policy registry, which is not configured on ${deps.config.network}.`
+        };
+      }
+      if ("error" in read) return { error: read.detail };
+      if (read.found === false) return { found: false };
+      return {
+        found: true,
+        declared: [...declaredVocabulary(read.value).entries()].map(([name, type]) => ({ name, type })),
+        // Present only on the Registry route; the id-only read does not return them. Carried
+        // through rather than dropped, since it is the stated reason to prefer that route and the
+        // write path needs it (APP-M06).
+        ...read.value.templateAttributeIds ? { templateAttributeIds: read.value.templateAttributeIds } : {}
+      };
+    },
+    /** The owner's deployed policies. 2 + N chain calls; warns above 50 keys. */
+    async get_my_policy(input = {}) {
+      const registry2 = deps.config.policyRegistryAddress;
+      if (!registry2) return { error: `The policy registry is not deployed on ${deps.config.network}.` };
+      const owner = input.owner ?? deps.config.zetrixAddress;
+      if (!owner) return { error: "No owner address \u2014 pass one, or configure ZETRIX_ADDRESS." };
+      return readOwnerPolicies(owner, registry2, deps.chainQuery);
+    },
+    /** Validate a draft policy before anything signs or pays for it. Free, signs nothing. */
+    async policy_preflight(input) {
+      const registry2 = deps.config.policyRegistryAddress;
+      const templateContract = deps.config.policyTemplateAddress;
+      const network = deps.config.network;
+      if (!registry2 && !templateContract) {
+        return unavailableResult(
+          typeof input?.policyKey === "string" ? input.policyKey : "",
+          `Policy contracts are not deployed on ${network}, so this draft could not be checked against a template.`,
+          network
+        );
+      }
+      return policyPreflight(
+        {
+          network,
+          readTemplate: async (draft) => (
+            // An explicit templateId wins. `draft.policyKey` is the key this policy would be
+            // STORED under, which is not necessarily the template's key — preferring the pair
+            // made an explicitly supplied templateId unreachable (APP-M04).
+            draft.templateId && templateContract ? getTemplateById(draft.templateId, templateContract, deps.chainQuery) : draft.publisher && draft.policyKey && registry2 ? getTemplateViaRegistry(draft.publisher, draft.policyKey, registry2, deps.chainQuery) : {
+              error: "query_failed",
+              detail: "no template identifier supplied \u2014 pass templateId, or publisher with policyKey"
+            }
+          )
+        },
+        input
+      );
+    },
     check_ai_birthcert_verification() {
       if (!deps.verifyAiBirthcert) {
         return { error: AI_BIRTHCERT_NOT_CONFIGURED_ERROR };
       }
       return deps.verifyAiBirthcert.check();
+    },
+    clear_stuck_payment_receipt(input = {}) {
+      if (!deps.verifyAiBirthcert) {
+        return { error: AI_BIRTHCERT_NOT_CONFIGURED_ERROR };
+      }
+      return deps.verifyAiBirthcert.clearStuckReceipt(input);
     }
   };
   return tools;
@@ -23586,6 +24010,9 @@ async function buildToolContent(result, readFile6) {
 }
 
 // src/clients/ssivc-client.ts
+var SETTLEMENT_UNCONFIRMED_STATUS_CODE = "69";
+var SETTLEMENT_EXPIRED_STATUS_CODE = "67";
+var SETTLEMENT_FAILED_STATUS_CODE = "68";
 var SsivcError = class extends Error {
   httpStatus;
   /** SSIVC's own `status_code` string (distinct from the HTTP status) — e.g. "50" signature invalid, "55" expired timestamp, "23" not found. */
@@ -23679,6 +24106,10 @@ var SsivcClient = class {
       msg = j.errors?.length ? j.errors.join("; ") : j.message ?? j.error ?? text;
       if (res.status === 402 && j.error === "payment_invalid") kind = "payment_invalid";
       else if (res.status === 503 && j.error === "facilitator_unavailable") kind = "facilitator_unavailable";
+      else if (res.status === 400 && statusCode === SETTLEMENT_UNCONFIRMED_STATUS_CODE) kind = "settlement_unconfirmed";
+      else if (res.status === 400 && (statusCode === SETTLEMENT_EXPIRED_STATUS_CODE || statusCode === SETTLEMENT_FAILED_STATUS_CODE)) {
+        kind = "settlement_void";
+      }
     } catch {
     }
     const prefix = context ? `${context} \u2014 ` : "";
@@ -23689,10 +24120,11 @@ var SsivcClient = class {
 // src/clients/ssivc-session-store.ts
 var import_promises4 = require("node:fs/promises");
 var import_node_path5 = require("node:path");
+var isAbsentOrString = (v) => v === void 0 || typeof v === "string";
 function isStoredSessionShape(value) {
   if (typeof value !== "object" || value === null) return false;
   const v = value;
-  return typeof v.sessionId === "string" && typeof v.agentName === "string" && typeof v.createdAt === "string" && typeof v.verificationUrl === "string" && typeof v.paymentReceipt === "string";
+  return typeof v.sessionId === "string" && typeof v.agentName === "string" && typeof v.createdAt === "string" && typeof v.verificationUrl === "string" && typeof v.paymentReceipt === "string" && isAbsentOrString(v.agentPurpose) && isAbsentOrString(v.evidenceAssuranceLevel) && isAbsentOrString(v.ownerType) && isAbsentOrString(v.ownerVerified);
 }
 function createFsSsivcSessionStore(filePath) {
   return {
@@ -23710,6 +24142,9 @@ function createFsSsivcSessionStore(filePath) {
       const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
       await (0, import_promises4.writeFile)(tmpPath, JSON.stringify(session, null, 2), { encoding: "utf8", mode: 384 });
       await (0, import_promises4.rename)(tmpPath, filePath);
+    },
+    async clear() {
+      await (0, import_promises4.rm)(filePath, { force: true });
     }
   };
 }
@@ -23803,10 +24238,10 @@ async function getConfirmedStatus(deps, sessionId) {
 async function decidePriorSession(deps, agentName) {
   const stored = await deps.sessionStore.get();
   if (!stored) return { kind: "pay_fresh" };
-  if (stored.sessionId === "") return { kind: "replay_receipt", receipt: stored.paymentReceipt };
+  if (stored.sessionId === "") return { kind: "replay_receipt", receipt: stored.paymentReceipt, stored };
   if (stored.agentName !== agentName) {
     const otherStatus = await getConfirmedStatus(deps, stored.sessionId);
-    if (otherStatus === "gone") return { kind: "replay_receipt", receipt: stored.paymentReceipt };
+    if (otherStatus === "gone") return { kind: "replay_receipt", receipt: stored.paymentReceipt, stored };
     if (otherStatus.status === "pending") {
       return {
         kind: "blocked",
@@ -23814,10 +24249,10 @@ async function decidePriorSession(deps, agentName) {
       };
     }
     if (otherStatus.status === "issued") return { kind: "pay_fresh" };
-    return { kind: "replay_receipt", receipt: stored.paymentReceipt };
+    return { kind: "replay_receipt", receipt: stored.paymentReceipt, stored };
   }
   const status = await getConfirmedStatus(deps, stored.sessionId);
-  if (status === "gone") return { kind: "replay_receipt", receipt: stored.paymentReceipt };
+  if (status === "gone") return { kind: "replay_receipt", receipt: stored.paymentReceipt, stored };
   if (status.status === "pending") {
     return {
       kind: "still_pending",
@@ -23825,7 +24260,7 @@ async function decidePriorSession(deps, agentName) {
     };
   }
   if (status.status === "issued") return { kind: "pay_fresh" };
-  return { kind: "replay_receipt", receipt: stored.paymentReceipt };
+  return { kind: "replay_receipt", receipt: stored.paymentReceipt, stored };
 }
 var requestQueue = Promise.resolve();
 function withRequestLock(fn) {
@@ -23840,6 +24275,20 @@ var NoPaymentOptionsError = class extends Error {
 };
 var DEFAULT_MAX_SETTLEMENT_ATTEMPTS = 20;
 var MAX_RETRY_DELAY_MS = 6e4;
+var DEFAULT_SETTLEMENT_WAIT_BUDGET_MS = 9e4;
+var DEFAULT_SETTLEMENT_STUCK_AFTER_MS = 864e5;
+function settlementAge(stored, now, stuckAfterMs) {
+  const created = stored?.createdAt ? new Date(stored.createdAt).getTime() : NaN;
+  const ageMs = Number.isNaN(created) ? 0 : Math.max(0, now.getTime() - created);
+  const hours = ageMs / 36e5;
+  const humanAge = hours < 1 ? `${Math.round(ageMs / 6e4)} minutes` : hours < 48 ? `${Math.round(hours)} hours` : `${Math.round(hours / 24)} days`;
+  return { ageMs, stuck: ageMs > stuckAfterMs, humanAge };
+}
+var FALLBACK_RETRY_DELAY_MS = 15e3;
+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 SettlementStillQueuedError = class extends Error {
   constructor(message, paymentReceipt) {
@@ -23855,9 +24304,27 @@ var SettlementOutcomeUnknownError = class extends Error {
     this.name = "SettlementOutcomeUnknownError";
   }
 };
+var SettlementReceiptVoidError = class extends Error {
+  constructor(message, paymentReceipt) {
+    super(message);
+    this.paymentReceipt = paymentReceipt;
+    this.name = "SettlementReceiptVoidError";
+  }
+};
+function isReceiptVoid(err) {
+  return err instanceof SsivcError && err.kind === "settlement_void";
+}
+function unresolvedCause(err) {
+  if (err instanceof SsivcError && err.kind === "settlement_unconfirmed") {
+    return "the payment service reports that it cannot confirm the settlement either way";
+  }
+  return `the receipt-replay call itself failed (${err instanceof Error ? err.message : String(err)})`;
+}
 async function resolveSettlement(deps, buildBody, initialOutcome, onQueued) {
   const sleep = deps.sleep ?? defaultSleep;
   const maxAttempts = deps.maxSettlementAttempts ?? DEFAULT_MAX_SETTLEMENT_ATTEMPTS;
+  const waitBudgetMs = deps.settlementWaitBudgetMs ?? DEFAULT_SETTLEMENT_WAIT_BUDGET_MS;
+  let waitedMs = 0;
   let outcome = initialOutcome;
   let lastPersistedReceipt;
   if (outcome.kind === "queued") {
@@ -23865,14 +24332,17 @@ async function resolveSettlement(deps, buildBody, initialOutcome, onQueued) {
     await onQueued(outcome.paymentReceipt);
   }
   for (let attempt = 0; outcome.kind === "queued" && attempt < maxAttempts; attempt++) {
-    const delayMs = Math.min(outcome.retryAfterSeconds * 1e3, MAX_RETRY_DELAY_MS);
+    const delayMs = retryDelayMs(outcome.retryAfterSeconds);
+    if (attempt > 0 && waitedMs + delayMs > waitBudgetMs) break;
+    waitedMs += delayMs;
     await sleep(delayMs);
     const receiptSent = outcome.paymentReceipt;
     try {
       outcome = await deps.ssivc.createSessionWithReceipt(await buildBody(), receiptSent);
     } catch (err) {
+      if (isReceiptVoid(err)) throw new SettlementReceiptVoidError(err.message, receiptSent);
       throw new SettlementOutcomeUnknownError(
-        `the settlement outcome for payment receipt ${receiptSent} could not be determined \u2014 the receipt-retry call itself failed (${err instanceof Error ? err.message : String(err)})`,
+        `the settlement outcome for payment receipt ${receiptSent} could not be determined \u2014 ` + unresolvedCause(err),
         receiptSent
       );
     }
@@ -23883,7 +24353,7 @@ async function resolveSettlement(deps, buildBody, initialOutcome, onQueued) {
   }
   if (outcome.kind === "queued") {
     throw new SettlementStillQueuedError(
-      "the sponsored payment is being processed and has not settled yet \u2014 no funds are lost and the receipt has been kept; run request_ai_birthcert_verification again shortly to resume",
+      "PAYMENT SENT \u2014 the sponsored settlement is still being processed. Nothing has gone wrong and no funds are lost: the receipt has been saved. Call check_ai_birthcert_verification in a few minutes to follow it through. Do not pay again.",
       outcome.paymentReceipt
     );
   }
@@ -23982,9 +24452,22 @@ async function requestAiBirthcertVerification(deps, input) {
     throw new Error("requestAiBirthcertVerification: agentName is required");
   }
   const agentName = input.agentName.trim();
+  if (input.dryRun && input.discardStuckReceiptAndPayFresh !== void 0) {
+    return {
+      error: `dryRun and discardStuckReceiptAndPayFresh cannot be combined \u2014 nothing was discarded and nothing was quoted. A quote never spends and never discards; discarding a receipt forfeits a real payment. Decide which one you meant and call again with only that.`
+    };
+  }
   if (input.dryRun) return quoteVerification(deps, agentName, input);
   return withRequestLock(() => requestAiBirthcertVerificationLocked(deps, agentName, input));
 }
+function optionalRequestFields(source) {
+  const fields = {};
+  if (source.agentPurpose) fields.agentPurpose = source.agentPurpose;
+  if (source.evidenceAssuranceLevel) fields.evidenceAssuranceLevel = source.evidenceAssuranceLevel;
+  if (source.ownerType) fields.ownerType = source.ownerType;
+  if (source.ownerVerified) fields.ownerVerified = source.ownerVerified;
+  return fields;
+}
 async function buildSessionBody(deps, agentName, input) {
   const fields = {
     publicKey: deps.publicKeyHex,
@@ -23994,10 +24477,7 @@ async function buildSessionBody(deps, agentName, input) {
     id: agentName,
     ownerReference: deps.holderDid
   };
-  if (input.agentPurpose) fields.agentPurpose = input.agentPurpose;
-  if (input.evidenceAssuranceLevel) fields.evidenceAssuranceLevel = input.evidenceAssuranceLevel;
-  if (input.ownerType) fields.ownerType = input.ownerType;
-  if (input.ownerVerified) fields.ownerVerified = input.ownerVerified;
+  Object.assign(fields, optionalRequestFields(input));
   const digestHex = (0, import_node_crypto5.createHash)("sha256").update(canonicalizeJson(fields), "utf8").digest("hex");
   const { signBlob: signedData } = await deps.signHexBlob(digestHex);
   return { ...fields, signedData };
@@ -24019,11 +24499,49 @@ async function quoteVerification(deps, agentName, input) {
     }
   };
 }
+async function discardStuckReceiptBeforePaying(deps, confirmReceiptId) {
+  const stored = await deps.sessionStore.get();
+  if (!stored) {
+    return {
+      refusal: {
+        error: `Nothing was discarded and nothing was paid: this wallet holds no payment receipt at all. There is nothing to start over from \u2014 call request_ai_birthcert_verification again without discardStuckReceiptAndPayFresh and it will pay normally.`
+      }
+    };
+  }
+  if (stored.paymentReceipt !== confirmReceiptId) {
+    return {
+      refusal: {
+        paymentReceipt: stored.paymentReceipt,
+        error: `discardStuckReceiptAndPayFresh does not match the stored receipt \u2014 nothing was discarded and NOTHING WAS PAID. Stored receipt is ${stored.paymentReceipt}; you sent ${confirmReceiptId}. Confirm with the user which payment they are forfeiting before retrying.`
+      }
+    };
+  }
+  if (stored.sessionId !== "") {
+    return {
+      refusal: {
+        paymentReceipt: stored.paymentReceipt,
+        error: `STOP \u2014 nothing was discarded and nothing was paid. Receipt ${stored.paymentReceipt} is not stuck: it belongs to live verification session ${stored.sessionId}, which is already paid for. Call check_ai_birthcert_verification to get its verification link and finish it \u2014 paying again here would buy a second copy of something the user already owns. If they genuinely want to abandon it, clear_stuck_payment_receipt asks for its own confirmation.`
+      }
+    };
+  }
+  await deps.sessionStore.clear();
+  return { discarded: stored.paymentReceipt };
+}
 async function requestAiBirthcertVerificationLocked(deps, agentName, input) {
+  let discardedPaymentReceipt;
+  if (input.discardStuckReceiptAndPayFresh !== void 0) {
+    const outcome = await discardStuckReceiptBeforePaying(deps, input.discardStuckReceiptAndPayFresh);
+    if ("refusal" in outcome) return outcome.refusal;
+    discardedPaymentReceipt = outcome.discarded;
+  }
   const decision = await decidePriorSession(deps, agentName);
   if (decision.kind === "still_pending") return decision.result;
   if (decision.kind === "blocked") return { error: decision.message };
-  const buildBody = () => buildSessionBody(deps, agentName, input);
+  const effectiveOptionalFields = {
+    ...decision.kind === "replay_receipt" ? optionalRequestFields(decision.stored) : {},
+    ...optionalRequestFields(input)
+  };
+  const buildBody = () => buildSessionBody(deps, agentName, { ...input, ...effectiveOptionalFields });
   const persistQueuedReceipt = async (receipt) => {
     try {
       await deps.sessionStore.set({
@@ -24031,7 +24549,12 @@ async function requestAiBirthcertVerificationLocked(deps, agentName, input) {
         agentName,
         createdAt: deps.now().toISOString(),
         verificationUrl: "",
-        paymentReceipt: receipt
+        paymentReceipt: receipt,
+        // check_ai_birthcert_verification replays this receipt with no user input to work
+        // from. Without these the replayed body silently drops whatever the user supplied here.
+        // APP-M03: the EFFECTIVE set, so a bare retry re-persists what was paid for instead of
+        // erasing it.
+        ...effectiveOptionalFields
       });
     } catch {
     }
@@ -24044,8 +24567,9 @@ async function requestAiBirthcertVerificationLocked(deps, agentName, input) {
       try {
         initialOutcome = await deps.ssivc.createSessionWithReceipt(await buildBody(), decision.receipt);
       } catch (err) {
+        if (isReceiptVoid(err)) throw new SettlementReceiptVoidError(err.message, decision.receipt);
         throw new SettlementOutcomeUnknownError(
-          `the settlement outcome for payment receipt ${decision.receipt} could not be determined \u2014 the receipt-replay call itself failed (${err instanceof Error ? err.message : String(err)})`,
+          `the settlement outcome for payment receipt ${decision.receipt} could not be determined \u2014 ` + unresolvedCause(err),
           decision.receipt
         );
       }
@@ -24070,21 +24594,42 @@ async function requestAiBirthcertVerificationLocked(deps, agentName, input) {
           agentName,
           createdAt: deps.now().toISOString(),
           verificationUrl: "",
-          paymentReceipt: err.paymentReceipt
+          paymentReceipt: err.paymentReceipt,
+          ...effectiveOptionalFields
         });
       } catch {
         return {
-          error: err.message + ` (could not save the receipt locally \u2014 keep this value to resume manually: ${err.paymentReceipt})`
+          paymentReceipt: err.paymentReceipt,
+          error: `PAYMENT SENT \u2014 the sponsored settlement is still processing, but the receipt could NOT be saved on this machine. Keep this value safe, it is the only record of the payment: ${err.paymentReceipt}. Do not pay again. Checking the status will not find it \u2014 quote this receipt id to support to resume manually.`
         };
       }
-      return { error: err.message };
+      return { settlementPending: true, paymentReceipt: err.paymentReceipt, message: err.message };
     }
     if (err instanceof SsivcError && err.kind === "blob_already_settled") {
       return { error: `payment already settled for this attempt: ${err.message}` };
     }
+    if (err instanceof SettlementReceiptVoidError) {
+      return {
+        paymentReceipt: err.paymentReceipt,
+        error: `RECEIPT VOID \u2014 this payment can no longer be used, and no credential was issued. The payment service has ruled on it: ${err.message}. Nothing was paid on this call, and the receipt is still stored. Whether the original fee was actually taken is NOT settled by this \u2014 a settlement can expire after the money has already moved \u2014 so do not tell the user they were not charged; give them receipt ${err.paymentReceipt} to quote to support. To buy the credential now, they must pay the fee AGAIN: with their explicit agreement, call request_ai_birthcert_verification with discardStuckReceiptAndPayFresh set to exactly ${err.paymentReceipt}.`
+      };
+    }
     if (err instanceof SettlementOutcomeUnknownError) {
+      const age = settlementAge(
+        decision.kind === "replay_receipt" ? decision.stored : null,
+        deps.now(),
+        deps.settlementStuckAfterMs ?? DEFAULT_SETTLEMENT_STUCK_AFTER_MS
+      );
+      if (!age.stuck) {
+        return {
+          paymentReceipt: err.paymentReceipt,
+          settlementPending: true,
+          message: `PAYMENT SENT \u2014 the settlement has not been confirmed yet, ${age.humanAge} in. Nothing is lost: receipt ${err.paymentReceipt} is saved and no new payment was attempted. Do NOT pay again. Call check_ai_birthcert_verification in a few minutes to follow it through.`
+        };
+      }
       return {
-        error: `could not determine whether the sponsored settlement succeeded or failed for payment receipt ${err.paymentReceipt} (${err.message}) \u2014 this is NOT a confirmed failure, so the receipt has been kept as-is and no new payment has been attempted; this requires manual investigation by an operator before retrying, rather than calling request_ai_birthcert_verification again`
+        paymentReceipt: err.paymentReceipt,
+        error: `OUTCOME UNKNOWN \u2014 do not retry, do not assume failure. The sponsored settlement for payment receipt ${err.paymentReceipt} could not be determined either way (${err.message}), and has been unresolved for ${age.humanAge} \u2014 past the point where it resolves on its own. The fee was most likely already taken and no credential was issued. This call did NOT pay again: the receipt is kept, and while it is kept this tool can only ever replay it, never buy a new credential. To start over, the user must first discard it with clear_stuck_payment_receipt \u2014 which forfeits that payment \u2014 and the next request then pays a SECOND fee. Both steps at once: call request_ai_birthcert_verification with discardStuckReceiptAndPayFresh set to exactly ${err.paymentReceipt}. Either way, show the user that cost and get their agreement first. Quote receipt ${err.paymentReceipt} to support.`
       };
     }
     throw err;
@@ -24094,24 +24639,149 @@ async function requestAiBirthcertVerificationLocked(deps, agentName, input) {
     agentName,
     createdAt: deps.now().toISOString(),
     verificationUrl: paid.session.verificationUrl,
-    paymentReceipt: paid.paymentReceipt
+    paymentReceipt: paid.paymentReceipt,
+    // Benign today — a record with a real sessionId never replays — but the same latent gap as the
+    // queued writes, so it carries the fields for consistency (APP-M03).
+    ...effectiveOptionalFields
   });
-  return paid.session;
+  return discardedPaymentReceipt ? { ...paid.session, discardedPaymentReceipt } : paid.session;
 }
-async function checkAiBirthcertVerification(deps) {
+async function advanceQueuedSettlement(deps, stored) {
+  const buildBody = () => buildSessionBody(deps, stored.agentName, {
+    agentName: stored.agentName,
+    ...optionalRequestFields(stored)
+  });
+  let initialOutcome;
+  try {
+    initialOutcome = await deps.ssivc.createSessionWithReceipt(await buildBody(), stored.paymentReceipt);
+  } catch (err) {
+    if (isReceiptVoid(err)) return voidReceiptOutcome(stored.paymentReceipt, err.message);
+    return unknownSettlementOutcome(stored.paymentReceipt, err, void 0, settlementAge(stored, deps.now(), deps.settlementStuckAfterMs ?? DEFAULT_SETTLEMENT_STUCK_AFTER_MS));
+  }
+  let settled;
+  try {
+    const persistReplayedReceipt = async (receipt) => {
+      try {
+        await deps.sessionStore.set({ ...stored, paymentReceipt: receipt });
+      } catch {
+      }
+    };
+    settled = await resolveSettlement(deps, buildBody, initialOutcome, persistReplayedReceipt);
+  } catch (err) {
+    if (err instanceof SettlementStillQueuedError) {
+      return { status: "settlement_pending", message: err.message, paymentReceipt: err.paymentReceipt };
+    }
+    if (err instanceof SettlementReceiptVoidError) return voidReceiptOutcome(err.paymentReceipt, err.message);
+    if (err instanceof SettlementOutcomeUnknownError) {
+      return unknownSettlementOutcome(err.paymentReceipt, void 0, err.message, settlementAge(stored, deps.now(), deps.settlementStuckAfterMs ?? DEFAULT_SETTLEMENT_STUCK_AFTER_MS));
+    }
+    throw err;
+  }
+  try {
+    await deps.sessionStore.set({
+      ...stored,
+      sessionId: settled.session.sessionId,
+      verificationUrl: settled.session.verificationUrl,
+      paymentReceipt: settled.paymentReceipt
+    });
+  } catch {
+  }
+  return {
+    sessionId: settled.session.sessionId,
+    status: "pending",
+    expiresAt: settled.session.expiresAt,
+    verificationUrl: settled.session.verificationUrl
+  };
+}
+function noStoredSession() {
+  return {
+    status: "no_session",
+    message: "No verification session found for this wallet \u2014 call request_ai_birthcert_verification first."
+  };
+}
+function voidReceiptOutcome(paymentReceipt, detail) {
+  return {
+    status: "receipt_void",
+    paymentReceipt,
+    message: `RECEIPT VOID \u2014 this payment can no longer be used and no credential was issued. The payment service has ruled on it: ${detail}. Checking again will not change this. Whether the fee was actually taken is NOT settled by this \u2014 a settlement can expire after the money has moved \u2014 so do not tell the user they were not charged; give them receipt ${paymentReceipt} to quote to support. Buying the credential now means paying the fee AGAIN, which needs their explicit agreement: request_ai_birthcert_verification with discardStuckReceiptAndPayFresh set to exactly ${paymentReceipt}.`
+  };
+}
+function unknownSettlementOutcome(paymentReceipt, err, message, age) {
+  const detail = message ?? unresolvedCause(err);
+  if (age && !age.stuck) {
+    return {
+      status: "settlement_pending",
+      paymentReceipt,
+      message: `PAYMENT SENT \u2014 the settlement has not been confirmed yet, ${age.humanAge} in. Nothing has gone wrong and no funds are lost: receipt ${paymentReceipt} is saved. Do NOT pay again. Call check_ai_birthcert_verification again in a few minutes to follow it through.`
+    };
+  }
+  return {
+    status: "settlement_pending",
+    paymentReceipt,
+    // R2-L01: the machine-readable half of the OUTCOME UNKNOWN verdict. Without it the status alone
+    // reads as "queued, check back later", which is the one piece of advice this branch must not give.
+    outcomeUnknown: true,
+    ...age ? { stuckFor: age.humanAge } : {},
+    message: `OUTCOME UNKNOWN \u2014 do not retry, do not assume failure. The settlement outcome for payment receipt ${paymentReceipt} could not be determined: ${detail}. ` + (age ? `It has been unresolved for ${age.humanAge}, which is past the point where it resolves on its own. The fee was most likely already taken and no credential was issued \u2014 say so plainly rather than implying the payment may still land. ` : "") + `The receipt has been kept. Quote this receipt id to support. ` + (age ? `To start over, clear_stuck_payment_receipt discards it \u2014 and the next request pays a SECOND fee.` : "")
+  };
+}
+async function clearStuckPaymentReceipt(deps, input) {
+  return withRequestLock(() => clearStuckPaymentReceiptLocked(deps, input));
+}
+async function clearStuckPaymentReceiptLocked(deps, input) {
   const stored = await deps.sessionStore.get();
   if (!stored) {
+    return { cleared: false, message: "Nothing to clear \u2014 this wallet has no stored verification session or payment receipt." };
+  }
+  const isLiveSession = stored.sessionId !== "";
+  if (input.confirmReceiptId === void 0) {
     return {
-      status: "no_session",
-      message: "No verification session found for this wallet \u2014 call request_ai_birthcert_verification first."
+      cleared: false,
+      requiresConfirmation: true,
+      paymentReceipt: stored.paymentReceipt,
+      ...isLiveSession ? { sessionId: stored.sessionId, verificationUrl: stored.verificationUrl } : {},
+      message: `This will discard payment receipt ${stored.paymentReceipt}` + (isLiveSession ? ` AND the live verification session ${stored.sessionId}, which may still be open and usable \u2014 check check_ai_birthcert_verification before discarding it.` : ".") + ` The payment it represents becomes unrecoverable and CANNOT be undone \u2014 if that settlement ever completes, the funds are forfeit and the credential is not issued. Only do this when the outcome is genuinely stuck. Show the receipt id to the user, get their explicit agreement, then call this tool again with confirmReceiptId set to exactly that id` + (isLiveSession ? ` and confirmDiscardLiveSession set to true.` : `.`)
     };
   }
-  if (stored.sessionId === "") {
+  if (input.confirmReceiptId !== stored.paymentReceipt) {
+    return {
+      cleared: false,
+      paymentReceipt: stored.paymentReceipt,
+      error: `confirmReceiptId does not match the stored receipt \u2014 nothing was cleared. Stored receipt is ${stored.paymentReceipt}; you sent ${input.confirmReceiptId}. Confirm you are discarding the right payment before retrying.`
+    };
+  }
+  if (isLiveSession && input.confirmDiscardLiveSession !== true) {
     return {
-      status: "no_session",
-      message: "a sponsored payment is still settling and no verification session exists yet \u2014 the payment receipt has been kept, so calling request_ai_birthcert_verification again resumes it and will not pay twice."
+      cleared: false,
+      requiresConfirmation: true,
+      paymentReceipt: stored.paymentReceipt,
+      sessionId: stored.sessionId,
+      verificationUrl: stored.verificationUrl,
+      message: `STOP \u2014 nothing was cleared. This is no longer a stuck receipt: the settlement completed and receipt ${stored.paymentReceipt} now belongs to LIVE verification session ${stored.sessionId}` + (stored.verificationUrl ? `, whose verification link is ${stored.verificationUrl}` : "") + `. The payment worked. Give the user that link and let them finish MyDigital ID verification \u2014 clearing now would throw away a session they have already paid for, and the link cannot be reissued. If they genuinely want to abandon it and start over, call again with the same confirmReceiptId AND confirmDiscardLiveSession set to true.`
     };
   }
+  await deps.sessionStore.clear();
+  return {
+    cleared: true,
+    paymentReceipt: stored.paymentReceipt,
+    ...isLiveSession ? { sessionId: stored.sessionId } : {},
+    message: `Cleared payment receipt ${stored.paymentReceipt}` + (isLiveSession ? ` AND live verification session ${stored.sessionId}, which was open and paid for \u2014 its verification link is gone and cannot be reissued.` : ".") + ` The wallet no longer holds it, so request_ai_birthcert_verification will pay fresh on the next call. Keep this receipt id in case the original payment needs to be traced.`
+  };
+}
+async function checkAiBirthcertVerification(deps) {
+  const stored = await deps.sessionStore.get();
+  if (!stored) return noStoredSession();
+  if (stored.sessionId === "") {
+    return withRequestLock(async () => {
+      const fresh = await deps.sessionStore.get();
+      if (!fresh) return noStoredSession();
+      if (fresh.sessionId === "") return advanceQueuedSettlement(deps, fresh);
+      return checkExistingSession(deps, fresh);
+    });
+  }
+  return checkExistingSession(deps, stored);
+}
+async function checkExistingSession(deps, stored) {
   const status = await deps.ssivc.getSession(stored.sessionId);
   if (status.status !== "issued" && stored.verificationUrl) {
     return { ...status, verificationUrl: stored.verificationUrl };
@@ -24251,6 +24921,56 @@ function buildToolList() {
         required: ["templateId"]
       }
     },
+    {
+      name: "get_policy_template_schema",
+      description: `Read a POLICY template's declared attribute vocabulary from chain \u2014 FREE, no payment, no signing. This is the only vocabulary that means anything on chain: the policy contract validates nothing, so an attribute name outside this list deploys cleanly and then enforces nothing at all. Accepts either { publisher, policyKey } or { templateId }. A template that cannot be read reports { error } rather than { found: false }, so "no such template" is never confused with "could not look it up".`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          templateId: { type: "string", description: "Template id, as it appears inside a deployed policy." },
+          publisher: { type: "string", description: "Publisher address. Use together with policyKey." },
+          policyKey: { type: "string", description: "Policy key. Use together with publisher." }
+        }
+      }
+    },
+    {
+      name: "get_my_policy",
+      description: `Read the spending policies this owner has deployed on chain \u2014 FREE, no payment, no signing. Defaults to this wallet's own address. Costs 2 + N chain calls and warns above 50 keys. An owner who has never deployed a policy is reported as a normal absence, NOT an error \u2014 the policy contract is created lazily on first write. A failed lookup keeps its own error state, so "we could not list your policies" is never presented as "you have none".`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          owner: { type: "string", description: "Owner address. Defaults to this wallet's configured address." }
+        }
+      }
+    },
+    {
+      name: "policy_preflight",
+      description: 'Check a draft policy BEFORE it is deployed \u2014 FREE, no payment, no signing. It answers two questions. First, is the draft well-formed: every blocker is returned at once in `blockers`, so one round of fixes is enough rather than discovering them one failure at a time. Second, and more important, does the policy MEAN what the user thinks: `interpretation` states in plain words what it actually does. ALWAYS show `interpretation` to the user, INCLUDING when ready is true \u2014 a policy can be perfectly valid and still mean something other than what was intended (a spending cap with no window is a LIFETIME cap, not a monthly one), and reporting only "ready" hides exactly that. A clean result is NOT a guarantee: `notChecked` lists what could not be verified, including whether the policy will be enforced at all and whether a payment would currently be allowed.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          policyKey: { type: "string", description: "The key this policy would be stored under." },
+          attributes: {
+            type: "array",
+            description: "The draft rules \u2014 one { attributeName, attributeType, value } per rule.",
+            items: {
+              type: "object",
+              properties: {
+                attributeName: { type: "string" },
+                attributeType: { type: "string" },
+                value: { type: "string" }
+              },
+              required: ["attributeName", "attributeType", "value"]
+            }
+          },
+          validFromBlock: { type: "string", description: "Block this policy starts at, written as a string." },
+          validToBlock: { type: "string", description: 'Block it ends at, as a string. "0" means no end.' },
+          templateId: { type: "string", description: "Template id. Supply this OR publisher + policyKey." },
+          publisher: { type: "string", description: "Publisher address, used together with policyKey." }
+        },
+        required: ["policyKey", "attributes", "validFromBlock", "validToBlock"]
+      }
+    },
     {
       name: "query_contract",
       description: 'Read-only query against a Zetrix contract or account \u2014 call an arbitrary contract method (e.g. "balanceOf", "contractInfo") and return its raw result. No signing, no state change.',
@@ -24293,7 +25013,7 @@ function buildToolList() {
     },
     {
       name: "request_ai_birthcert_verification",
-      description: `Start a Verified AI Birthcert issuance session with myid (MyDigital ID owner verification). Returns { sessionId, verificationUrl, expiresAt } \u2014 show verificationUrl to the human owner and ask them to open it and complete MyDigital ID verification (typically finishes in seconds). Once they confirm they are done, call check_ai_birthcert_verification to see whether the credential was issued. 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 \u2014 a separate, narrower cap than pay_and_fetch's, which defaults to refusing everything on mainnet. Set MAX_PAYMENT_AMOUNT to override either. It can return { error: "..." } instead of a session if that payment fails (insufficient funds, or the payment cap blocked it) \u2014 nothing is created in that case. 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.`,
+      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. Returns { sessionId, verificationUrl, expiresAt } \u2014 show verificationUrl to the human owner and ask them to open it and complete MyDigital ID verification (typically finishes in seconds). Once they confirm they are done, call check_ai_birthcert_verification to see whether the credential was issued. 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 \u2014 a separate, narrower cap than pay_and_fetch's, which defaults to refusing everything on mainnet. Set MAX_PAYMENT_AMOUNT to override either. It can return { error: "..." } instead of a session if that payment fails (insufficient funds, or the payment cap blocked it) \u2014 nothing is created in that case. It can also return { settlementPending: true, paymentReceipt, message } \u2014 this means the payment SUCCEEDED and the sponsored settlement is still clearing, which can take a few minutes. That is NOT a failure and NOT an error: report it to the user as "payment sent, still settling", never as "the payment failed". Do not pay again and do not call this tool again to retry \u2014 call check_ai_birthcert_verification to follow it through. 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.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -24313,6 +25033,10 @@ function buildToolList() {
           dryRun: {
             type: "boolean",
             description: "Ask the price WITHOUT paying. Returns { quote: { asset, maxAmountRequired, payTo, gasModel } } and spends nothing, creates no session, and starts no verification \u2014 so you can tell the user the cost before collecting anything. `maxAmountRequired` is in the asset's RAW base units; resolve decimals (wallet_status returns `display`) before quoting a figure to a human. A quote does NOT reserve the name and does NOT check whether it is already taken \u2014 myid checks uniqueness only at issuance, so a name already in use still quotes cleanly. `agentName` is still required because the server rejects a request without one, but the fee does not depend on it."
+          },
+          discardStuckReceiptAndPayFresh: {
+            type: "string",
+            description: "DESTRUCTIVE, and it SPENDS. Only for a payment that is genuinely stuck. While the wallet holds a stuck receipt this tool can only replay it \u2014 it will never buy a new credential \u2014 so this is the way to start over: it throws that payment away and pays a SECOND fee. Pass the stuck receipt id EXACTLY as check_ai_birthcert_verification or clear_stuck_payment_receipt reported it \u2014 never a guess, never true. A mismatched id discards nothing and pays nothing. Before using it, show the user the receipt id, tell them the first payment is forfeit and that this costs the fee again, and get their explicit agreement. If the receipt turns out to belong to a live session this is refused: that session is already paid for, so call check_ai_birthcert_verification instead. The result carries discardedPaymentReceipt \u2014 keep it, support needs it to trace the lost payment. A receipt only counts as stuck once it is older than SETTLEMENT_STUCK_AFTER_MS (24h by default, e.g. SETTLEMENT_STUCK_AFTER_MS=3600000 for one hour); before that the wallet will say the settlement may still be in flight, and starting over is the user decision, not yours."
           }
         },
         required: ["agentName"]
@@ -24338,9 +25062,26 @@ function buildToolList() {
     },
     {
       name: "check_ai_birthcert_verification",
-      description: 'Check the status of the most recently requested Verified AI Birthcert session (see request_ai_birthcert_verification). FREE \u2014 spends nothing and starts nothing. Use this, not request_ai_birthcert_verification, whenever the user asks where their verification link is, what happened to their session, or whether their credential is ready. While the session is still open the result carries `verificationUrl` (the same link issued at creation) and `expiresAt` \u2014 give the user both, so they know how long it is good for. Returns { status: "pending" } while the owner has not yet completed MyDigital ID verification, or { status: "issued", vcId } once myid has minted the credential \u2014 myid returns vcId ONLY when status is "issued", never otherwise. On { status: "issued" }, the wallet also fetches the credential from MBI, verifies it, and caches it locally, returning it as `vc` \u2014 it is then also visible via wallet_status and usable by prove_identity without any further call. If `cacheError` is present instead of `vc`, the credential WAS issued successfully but could not be fetched/verified/cached yet (e.g. a transient MBI error) \u2014 this is NOT the same as issuance failing, so do not retry request_ai_birthcert_verification; call check_ai_birthcert_verification again instead. Returns { status: "no_session" } if request_ai_birthcert_verification has never been called.',
+      description: 'Check the status of the most recently requested Verified AI Birthcert session (see request_ai_birthcert_verification). FREE \u2014 it never pays for anything. Use this, not request_ai_birthcert_verification, whenever the user asks where their verification link is, what happened to their session, or whether their credential is ready. While the session is still open the result carries `verificationUrl` (the same link issued at creation) and `expiresAt` \u2014 give the user both, so they know how long it is good for. Returns { status: "pending" } while the owner has not yet completed MyDigital ID verification, or { status: "issued", vcId } once myid has minted the credential \u2014 myid returns vcId ONLY when status is "issued", never otherwise. On { status: "issued" }, the wallet also fetches the credential from MBI, verifies it, and caches it locally, returning it as `vc` \u2014 it is then also visible via wallet_status and usable by prove_identity without any further call. If `cacheError` is present instead of `vc`, the credential WAS issued successfully but could not be fetched/verified/cached yet (e.g. a transient MBI error) \u2014 this is NOT the same as issuance failing, so do not retry request_ai_birthcert_verification; call check_ai_birthcert_verification again instead. Returns { status: "no_session" } if request_ai_birthcert_verification has never been called. If a previous payment is still clearing, this tool ACTIVELY ADVANCES it \u2014 so in that one case it can take up to ~90s to return (it is waiting on the settlement, not hung; every other case returns immediately). It replays the saved receipt (never a new payment) and returns the live session once it settles, so telling the user to check back here genuinely moves things forward. While it is still clearing you get { status: "settlement_pending", paymentReceipt, message }: a payment HAS been made, so never call request_ai_birthcert_verification and never tell the user it failed. Two cases, told apart by outcomeUnknown and by the first words of message: without outcomeUnknown (message leads "PAYMENT SENT") it is queued and progressing \u2014 just check again in a few minutes. With outcomeUnknown: true (message leads "OUTCOME UNKNOWN") the settlement outcome could not be determined at all and has been unresolved long enough that it is not coming back (stuckFor says how long). The fee was most likely ALREADY TAKEN and no credential was issued \u2014 say that plainly rather than implying it may still land. do not just tell the user to wait; give them the paymentReceipt and tell them to quote it to support. Quote paymentReceipt to support in either case if they ask. Separately, { status: "receipt_void" } is TERMINAL: the payment service has ruled that this receipt is finished (it expired, or the settlement failed), so checking again cannot help and no credential will come from it. That does NOT mean the fee was refunded \u2014 never tell the user they were not charged; give them paymentReceipt for support. Buying the credential then means paying the fee AGAIN, which needs their explicit agreement.',
       inputSchema: { type: "object", properties: {} }
     },
+    {
+      name: "clear_stuck_payment_receipt",
+      description: 'LAST RESORT. Discard a stuck Verified AI Birthcert payment receipt that the wallet is holding and refusing to pay past. DESTRUCTIVE and CANNOT BE UNDONE: the payment it represents becomes unrecoverable \u2014 if that settlement ever completes, the funds are forfeit and no credential is issued. Do NOT use this as a retry. If the wallet reports { status: "settlement_pending" }, the payment is still in progress and will most likely resolve on its own \u2014 call check_ai_birthcert_verification again instead; it actively advances a queued settlement. Only reach for this tool when the outcome has been stuck with no change for a long time and the user accepts losing the payment. Two steps, deliberately: call it with no arguments first and it clears NOTHING \u2014 it returns the receipt id and a warning. Show that id to the user, get their explicit agreement, then call again with confirmReceiptId set to exactly that id. A mismatched id clears nothing. If the settlement completed in between \u2014 which is exactly what happens when you follow the advice above and call check_ai_birthcert_verification first \u2014 the receipt now belongs to a LIVE, paid-for session and this tool REFUSES to clear on the id alone: it hands back the session id and verification link instead. Give that link to the user; only if they truly want to abandon a session they already paid for, call again with confirmDiscardLiveSession set to true as well.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          confirmReceiptId: {
+            type: "string",
+            description: "The receipt id to discard, copied exactly from a prior no-argument call. Omit it to be shown the id and the warning first \u2014 never guess or invent this value."
+          },
+          confirmDiscardLiveSession: {
+            type: "boolean",
+            description: "Set true ONLY after the tool has refused because the receipt now belongs to a live verification session, and the user has been shown that session's link and has explicitly chosen to throw it away anyway. Never set it pre-emptively."
+          }
+        }
+      }
+    },
     {
       name: "create_holder_account",
       description: "Create a new holder HSM account on Wallet BE (onboarding). ALWAYS check first: if an account already exists for this session, this returns { alreadyExists: true, existing: {...} } WITHOUT creating anything \u2014 ask the user whether to keep using the existing account or create a new one, then call again with confirmNew:true only if they choose new. The wallet manages its own credentials; you neither need nor can supply any. A freshly created account is saved to this MCP's local account store and reused automatically on the next restart; an explicit ZETRIX_ADDRESS in the MCP config still overrides it.",
@@ -24365,6 +25106,15 @@ function buildPayers(config2, makePay) {
     preflightCaps: config2.credentialIssuanceCaps
   };
 }
+function buildSettlementWiring(config2) {
+  return {
+    gasPreference: config2.gasPreference,
+    maxSettlementAttempts: config2.maxSettlementAttempts,
+    settlementWaitBudgetMs: config2.settlementWaitBudgetMs,
+    settlementStuckAfterMs: config2.settlementStuckAfterMs,
+    verifiedTemplateId: config2.aiBirthcertVerifiedTemplateId
+  };
+}
 function asPayRequest(accept) {
   const extra = accept.extra ?? {};
   const prepareEndpoint = extra.prepareEndpoint;
@@ -24524,17 +25274,18 @@ async function main() {
       holderDid,
       now: () => /* @__PURE__ */ new Date(),
       sessionStore: ssivcSessionStore,
-      verifiedTemplateId: config2.aiBirthcertVerifiedTemplateId,
       cache: vcCache,
       quarantine: downloadQuarantine,
-      gasPreference: config2.gasPreference,
-      maxSettlementAttempts: config2.maxSettlementAttempts,
+      // gasPreference, maxSettlementAttempts, settlementWaitBudgetMs and verifiedTemplateId —
+      // see buildSettlementWiring (R2-L03).
+      ...buildSettlementWiring(config2),
       formatAssetAmount,
       passImagesDir
     };
     return {
       request: (input) => requestAiBirthcertVerification(verifyAiBirthcertDeps, input),
-      check: () => checkAiBirthcertVerification(verifyAiBirthcertDeps)
+      check: () => checkAiBirthcertVerification(verifyAiBirthcertDeps),
+      clearStuckReceipt: (input) => clearStuckPaymentReceipt(verifyAiBirthcertDeps, input)
     };
   })() : void 0;
   const payer = async (req) => {
@@ -24578,7 +25329,13 @@ async function main() {
     { signer, vc: new MbiVpAdapter(mbi, walletBeSignerFn, messageSigner, zetrixAddress, resolveIssuerKeys, present), submitAuth }
   );
   const deps = {
-    config: { holderDid, zetrixAddress, network: config2.network },
+    config: {
+      holderDid,
+      zetrixAddress,
+      network: config2.network,
+      policyRegistryAddress: config2.policyRegistryAddress,
+      policyTemplateAddress: config2.policyTemplateAddress
+    },
     makeWallet,
     payer,
     subscribeDeps: {
@@ -24594,6 +25351,8 @@ async function main() {
       quarantine: downloadQuarantine,
       passImagesDir
     },
+    // The RAW seam, for the policy client, which reads the query_rets envelope itself.
+    chainQuery: contractQuery,
     queryContract: (input) => queryContract(input, contractQuery),
     queryTokenBalance: queryTokenBalance2,
     // Read-only, for credential_preflight's cap headroom. Preflight only ever prices credentials,
@@ -24643,5 +25402,6 @@ if (process.env.NODE_ENV !== "test") {
 0 && (module.exports = {
   asPayRequest,
   buildPayers,
+  buildSettlementWiring,
   buildToolList
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-wallet-mcp",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Agent-facing MCP wallet for Zetrix — orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   "keywords": [
     "mcp",
@@ -38,7 +38,8 @@
     "build": "tsc --noEmit && esbuild src/index.ts --bundle --platform=node --target=node18 --format=cjs --external:zetrix-sdk-nodejs --outfile=dist/server-bundle.cjs",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "typecheck:tests": "tsc --noEmit -p tsconfig.test.json"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",