warpmetal 0.6.0 → 0.7.1

package/README.md

@@ -17,6 +17,8 @@ payment artifact, and submits it without absorbing wallet custody.
   executable
 - Skill: `skills/warpmetal` in the GitHub repository and bundled inside the
   npm package
+- Codex plugin: the skills-only package under `plugins/warpmetal`, exposed for
+  repository testing by `.agents/plugins/marketplace.json`
 
 Keeping the skill beside the CLI gives Codex, Claude, and other Agent
 Skills-compatible tools one canonical set of safety instructions while the CLI
@@ -32,7 +34,7 @@ published wallet CLI with the exact version WarpMetal reports:
 npm install --global warpmetal
 warpmetal --help
 
-npm install --global @x402api/agent-wallet-cli@0.2.1
+npm install --global @x402api/agent-wallet-cli@0.2.3
 x402api help --json
 ```
 
@@ -52,6 +54,29 @@ layout. Agents that support that layout but use another installation path can
 consume that directory directly; they do not need a different WarpMetal API
 integration.
 
+## Codex plugin
+
+The repository also contains a skills-only WarpMetal plugin for the public
+Plugins Directory shared by Codex and ChatGPT. The plugin remains a separate
+artifact from the npm CLI and requires `warpmetal` CLI version 0.7.1 or newer.
+
+To test the repository marketplace after the plugin lands on `main`:
+
+```sh
+codex plugin marketplace add warpmetal/agent-kit --ref main
+codex plugin add warpmetal@warpmetal
+```
+
+Run the plugin-specific repository checks with:
+
+```sh
+npm run plugin:check
+```
+
+Public submission materials, reviewer cases, and the owner checklist live in
+`submission/openai`. Public publication happens through the OpenAI Platform;
+the repo marketplace is only for development, testing, and direct distribution.
+
 ## First commands
 
 ```sh
@@ -85,13 +110,19 @@ After preparing an order, request its live payment challenge:
 warpmetal checkout challenge --task <taskId> --json
 ```
 
-On HTTP 402 the CLI returns exact `paymentTerms`, the pinned
+On HTTP 402 the CLI returns exact `paymentTerms`, the opaque `challengeHandle`
+that WarpMetal uses for merchant-side reconciliation, the pinned
 `@x402api/agent-wallet-cli` package contract, and argv arrays under
 `paymentWorkflow`. It also writes an owner-only request envelope that contains
-the exact checkout URL and body but no WarpMetal credential. The published
+the exact checkout URL and body but no WarpMetal credential or challenge
+handle. The handle is not a buyer payment identifier and is never a wallet
+signing input. The published
 launch wallet accepts sponsored Base USDC and sponsored Solana USDC/USDT only;
 the returned terms identify compatible alternatives and confirm that the buyer
-does not need ETH or SOL. Payment authority depends on execution context:
+does not need ETH or SOL. x402api pays the actual network fee from its platform
+treasury; the merchant tenant's active allowance controls sponsorship
+admission but is not charged actual gas. Payment authority depends on execution
+context:
 
 - When a human is actively chatting with the agent, show the exact live terms
   and ask for confirmation immediately before authorizing and submitting.
@@ -141,11 +172,13 @@ after authorization.
 
 If funding is short in an interactive conversation, tell the human the exact
 top-up in normal and atomic units, the network, stablecoin and contract/mint,
-and the payer wallet's public receiving address. The human sends the token to
-that wallet address, never to the token contract/mint or WarpMetal's payment
-recipient, and never sends ETH or SOL for a sponsored payment. In an unattended
-run, use a preconfigured refill or escalation mechanism or stop with
-`funding_required`.
+and the payer wallet's public receiving address. The returned
+`paymentWorkflow.fundingWorkflow` provides safe address and balance argv plus a
+presentation contract: render that public address as both a QR code and
+copyable text. The human sends the token to that wallet address, never to the
+token contract/mint or WarpMetal's payment recipient, and never sends ETH or
+SOL for a sponsored payment. In an unattended run, use a preconfigured refill
+or escalation mechanism or stop with `funding_required`.
 
 ## Autonomous renewal and refill
 
@@ -168,7 +201,11 @@ warpmetal renewal configure \
 ```
 
 The recipient must follow the one-time verification link before lifecycle or
-refill mail is sent. A recurring unattended agent can then run:
+refill mail is sent. If no verified notification email exists, `renewal
+configure` returns `email_required` before changing policy. Supply `--email`,
+or deliberately continue with `--without-email-notifications`; the latter does
+not enable signed refill-email workflows. A recurring unattended agent can then
+run:
 
 ```sh
 warpmetal renewal due --all --json
@@ -176,14 +213,16 @@ warpmetal renewal run --all-due --json
 ```
 
 Inside policy, the CLI returns the exact Agent Wallet authorization and submit
-argv. If balance is insufficient, run the returned `refillWorkflow.argv` with
-its `X402API_NOTIFICATION_URL` environment value. `x402api wallet
+argv. If balance is insufficient, `refillWorkflow` is returned only when the
+server has an active verified notification subscription. Run its argv with the
+returned `X402API_NOTIFICATION_URL` environment value. `x402api wallet
 notify-refill` signs an opaque subscription reference and wallet-produced
 balance fields; it cannot choose an email address. WarpMetal verifies the
 wallet signature and current on-chain balance before emailing the verified
-human the network, stablecoin, public wallet address, and required minimum
-top-up. The human may transfer more than that minimum; the renewal policy—not
-the refill target—remains the spending authority.
+human the network, stablecoin, public wallet address, required minimum top-up,
+and a locally generated QR encoding only that wallet address. The address is
+also repeated as copyable text. The human may transfer more than that minimum;
+the renewal policy—not the refill target—remains the spending authority.
 
 The agent never sends a partial x402 payment. If no verified refill path
 exists, it reports `funding_required`. If a previous payment is pending or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "warpmetal",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Agent-safe CLI and skill for purchasing, renewing, and managing WarpMetal VPS servers",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
   },
   "scripts": {
     "check": "node --check bin/warpmetal.js && node --check src/api.js && node --check src/args.js && node --check src/cli.js && node --check src/connection.js && node --check src/errors.js && node --check src/install-skill.js && node --check src/installer.js && node --check src/payment.js && node --check src/runtime.js && node --check src/ssh.js && node --check src/state.js && node --check src/version.js",
+    "plugin:check": "node --test test/plugin.test.js",
     "test": "node --test",
     "prepack": "npm run check && npm test"
   },

package/skills/warpmetal/SKILL.md

@@ -11,9 +11,10 @@ with ad hoc HTTP commands.
 
 ## Start safely
 
-1. Run `warpmetal --version`.
-2. If it is missing, ask before installing software, then install the official
-   npm package only from `https://www.npmjs.com/package/warpmetal`.
+1. Run `warpmetal --version` and require version `0.7.1` or newer for this
+   plugin. If it is missing or older, explain the compatibility requirement,
+   ask before installing or upgrading software, and use only the official npm
+   package from `https://www.npmjs.com/package/warpmetal`.
 3. Use `--json` for every agent-driven command.
 4. Read [references/safety.md](references/safety.md) before preparing an order,
    authorizing payment, using an SSH identity, or changing a server.
@@ -111,7 +112,9 @@ task or operator limit.
 After interactive confirmation or autonomous policy validation, invoke the
 returned authorize argv once. The separate
 `x402api` executable owns the wallet, validates the envelope, and writes the
-payment artifact. Then invoke the returned submit argv, equivalent to:
+payment artifact. The returned `challengeHandle` is opaque merchant
+reconciliation metadata; never copy it into the request envelope or treat it as
+the buyer payment identifier. Then invoke the returned submit argv, equivalent to:
 
 ```sh
 warpmetal checkout submit \
@@ -152,9 +155,12 @@ price, asset, network, count, horizon, or total-budget mismatch.
 Run `warpmetal renewal prepare --server <serverId> --json`, then invoke only
 the returned `paymentWorkflow.authorize.argv` and
 `paymentWorkflow.submit.argv`. If authorization reports insufficient balance,
-set the returned `refillWorkflow.environment`, invoke its exact argv once, and
-stop until funding arrives. The signed refill intent resolves to a verified
-human contact; never add an email address to it. Never make a partial payment.
+use `paymentWorkflow.fundingWorkflow` to obtain the public address and balance,
+then show the address as both a QR code and copyable text. Only when
+`refillNotification.available` is true, set the returned
+`refillWorkflow.environment`, invoke its exact argv once, and stop until
+funding arrives. The signed refill intent resolves to a verified human contact;
+never add an email address to it. Never make a partial payment.
 
 After funding, prepare again, authorize exactly once, submit with WarpMetal,
 and confirm the returned `termEndsAt`. On `reconcile_pending` or

package/skills/warpmetal/references/cli-reference.md

@@ -53,19 +53,25 @@ warpmetal order status \
 ```
 
 On HTTP 402, `checkout challenge` validates and displays exact payment terms,
-writes a credential-free x402api V1 request envelope with owner-only
+writes the opaque x402api `challengeHandle` to private WarpMetal state for
+merchant reconciliation, and writes a credential-free x402api V1 request envelope with owner-only
 permissions, and returns the exact pinned wallet package, V1 contract probe,
 matching wallet-skill install, authorization, and WarpMetal submission argv
 arrays. The default envelope and suggested artifact paths live under the
 private WarpMetal state directory. An explicit output path must not already
-contain different content.
+contain different content. `challengeHandle` is intentionally absent from the
+wallet envelope: it is neither a buyer payment identifier nor signing input.
 
-The current integration targets `@x402api/agent-wallet-cli@0.2.1`. A compatible
+The current integration targets `@x402api/agent-wallet-cli@0.2.3`. A compatible
 live term is marked `agentWalletSupported: true` and must use the sponsored
 Base USDC or Solana USDC/USDT launch profile with buyer native fees disabled.
-WarpMetal rejects a challenge with no compatible sponsored term. Because the
-checkout is authenticated, do not substitute `x402api pay`, `payment submit`,
-or `payment reconcile` for the returned WarpMetal submission command.
+For the current declaration, x402api pays actual gas from its platform treasury
+while the merchant tenant's allowance controls sponsorship admission. WarpMetal
+retains the matched legacy tenant-credit declaration during rollout and rejects
+mixed policy pairs. WarpMetal rejects a challenge with no compatible sponsored
+term. Because the checkout is authenticated, do not substitute `x402api pay`,
+`payment submit`, or `payment reconcile` for the returned WarpMetal submission
+command.
 
 `--payment-artifact` accepts the owner-only JSON artifact produced by a
 compatible pinned x402api Agent Wallet release. WarpMetal validates its request
@@ -101,7 +107,8 @@ warpmetal renewal configure \
   (--maximum-renewals <n> | --renew-through <UTC>) \
   [--maximum-total-spend-atomic <amount>] \
   --allowed-network <network> --allowed-asset <asset> \
-  --wallet <name> [--refill-target-atomic <amount>] [--email <address>] --json
+  --wallet <name> [--refill-target-atomic <amount>] \
+  [--email <address> | --without-email-notifications] --json
 warpmetal renewal status --server <serverId> --json
 warpmetal renewal due (--server <serverId> | --all) --json
 warpmetal renewal prepare --server <serverId> --json
@@ -113,9 +120,12 @@ warpmetal notifications configure --server <serverId> --email <address> \
 warpmetal notifications status --server <serverId> --json
 ```
 
-`renewal prepare` returns exact payment and refill argv arrays. `renewal run`
-is an agent-facing state machine, not a wallet-signing daemon. See
-[renewals.md](renewals.md).
+Without a verified notification email, renewal configuration asks for an email
+before mutating policy unless `--without-email-notifications` explicitly opts
+out. `renewal prepare` always returns safe funding address/balance argv and
+returns signed refill-email argv only for a verified active subscription.
+`renewal run` is an agent-facing state machine, not a wallet-signing daemon.
+See [renewals.md](renewals.md).
 
 ## Server management
 

package/skills/warpmetal/references/payments.md

@@ -19,7 +19,7 @@ files or pass a WarpMetal credential to `x402api`.
 WarpMetal runs on Node.js 20 or 22. The x402api Agent Wallet currently requires
 Node.js 22. Use the exact published package reported by
 `paymentWorkflow.signerPackage.spec`; the current contract is
-`@x402api/agent-wallet-cli@0.2.1`. Do not add it as a WarpMetal dependency,
+`@x402api/agent-wallet-cli@0.2.3`. Do not add it as a WarpMetal dependency,
 install executable wallet code from an unpinned repository URL, or substitute
 a similarly named package.
 
@@ -66,10 +66,12 @@ skill automatically.
 
 6. If funding is short in an interactive conversation, show the exact deficit
    in normal token units and atomic units, the exact network, token symbol and
-   contract/mint, and the payer wallet's public receiving address. Tell the
-   human to transfer the token to the payer wallet address, never to the token
-   contract/mint or `paymentTerms.recipient`. Sponsored launch payments never
-   ask the buyer to fund ETH or SOL. Recheck the balance after the transfer.
+   contract/mint, and the payer wallet's public receiving address. Render only
+   that public address as a QR code and repeat the full address as copyable
+   text. Tell the human to transfer the token to the payer wallet address,
+   never to the token contract/mint or `paymentTerms.recipient`. Sponsored
+   launch payments never ask the buyer to fund ETH or SOL. Recheck the balance
+   after the transfer.
 7. If funding is short in an unattended run, use only a preconfigured refill
    mechanism returned by WarpMetal. For a configured renewal, set the returned
    `refillWorkflow.environment`, invoke `refillWorkflow.argv` once, and stop
@@ -89,7 +91,7 @@ Use this structure when asking a human to fund the wallet:
 > wallet `<payer-wallet-address>`. Token contract/mint: `<asset-identifier>`.
 > Send the token to the payer wallet address, not to the token contract/mint and
 > not to WarpMetal's payment recipient. Do not send ETH or SOL; the network fee
-> is sponsored.
+> is paid by x402api from its platform treasury.
 
 ## Exact purchase workflow
 
@@ -114,7 +116,11 @@ paymentWorkflow.submit.argv
 Replace only `<wallet-name>` after selecting the wallet for the advertised
 network. Do not parse, rewrite, copy, or display the request envelope or payment
 artifact. The envelope excludes the WarpMetal owner token; the artifact holds
-the complete payment signature and remains owner-only.
+the complete payment signature and remains owner-only. The safe challenge JSON
+also contains `challengeHandle`, an opaque value retained by WarpMetal for
+merchant reconciliation. It is deliberately excluded from the x402api V1
+request envelope and must not be confused with the wallet-created buyer payment
+identifier.
 
 Choose only a term marked `agentWalletSupported: true`,
 `sponsoredNetworkFee: true`, and `buyerNativeFeeRequired: false`. The supported
@@ -122,6 +128,12 @@ launch profiles are sponsored Base USDC and sponsored Solana USDC/USDT, bound
 by the strict `com.x402api.gas-sponsorship` extension. Stop on an expired gas
 reservation or any buyer-funded, unsupported, or unbound alternative.
 
+x402api pays actual gas from its platform treasury. The merchant tenant's
+active sponsorship allowance controls admission, but actual gas is not a
+tenant debit. During the coordinated rollout, accept only the exact 0.2.3
+platform-treasury declaration or the matched legacy tenant-credit declaration;
+never accept a mixed billing and final-charge policy.
+
 Among valid sponsored terms, honor an explicit task or operator network and
 asset preference. Otherwise prefer a compatible wallet that is already
 sufficiently funded. If several terms remain, choose the first compatible term
@@ -162,6 +174,12 @@ current `termEndsAt` generation are different.
   challenge flow again, inspect the replacement terms, and authorize one new
   artifact only when the protocol and current interactive or autonomous
   payment authority allow it.
+- `sponsorship_allowance_unavailable`, `sponsorship_payment_cap_exceeded`,
+  `sponsorship_payment_allowance_exhausted`,
+  `sponsorship_volume_allowance_exhausted`, or
+  `sponsorship_gas_budget_exhausted`: the wallet treats the authorization as
+  terminal. The merchant tenant must restore or change its allowance and issue
+  a fresh challenge; never retry the artifact or fall back to buyer-funded gas.
 - `manual_review`: payment or fulfillment may be final. Stop all payment and
   mutation retries.
 - Expired or corrupt artifact, changed request digest, unexpected recipient,

package/skills/warpmetal/references/renewals.md

@@ -23,15 +23,18 @@ warpmetal renewal configure \
   --allowed-asset <exact-contract-or-mint> \
   --wallet <agent-wallet-name> \
   [--refill-target-atomic <target>] \
-  [--email <human-address>] \
+  [--email <human-address> | --without-email-notifications] \
   --json
 ```
 
-`--email` queues verification; refill and expanded lifecycle notices remain
-disabled until the human opens the verification link. A refill target is a
-funding target, not spend permission, and cannot exceed the per-renewal cap.
-The human may transfer more than the displayed deficit. The agent may spend
-only the exact renewal amount allowed by policy.
+Without an active verified notification email, configuration asks for one
+before changing policy. `--email` queues verification; refill and expanded
+lifecycle notices remain disabled until the human opens the verification link.
+Use `--without-email-notifications` only as an explicit opt-out; no signed
+refill-email workflow is returned in that state. A refill target is a funding
+target, not spend permission, and cannot exceed the per-renewal cap. The human
+may transfer more than the displayed deficit. The agent may spend only the
+exact renewal amount allowed by policy.
 
 The WarpMetal CLI stores only the local wallet name. The backend stores
 non-secret limits, counters, payment rail, time horizon, and an opaque
@@ -70,8 +73,10 @@ one policy-compatible rail, and returns:
 ```text
 paymentWorkflow.authorize.argv
 paymentWorkflow.submit.argv
-refillWorkflow.environment
-refillWorkflow.argv
+paymentWorkflow.fundingWorkflow
+refillNotification
+refillWorkflow.environment (verified email only)
+refillWorkflow.argv (verified email only)
 ```
 
 Invoke the authorize argv once. It writes an owner-only artifact. Then invoke
@@ -112,10 +117,12 @@ authoritative balance before queuing email. The intent cannot name a recipient
 email, tenant, or product.
 
 In a human conversation, also display the exact deficit, network, token symbol,
-contract or mint, and payer wallet address. Tell the human to fund the payer
+contract or mint, and payer wallet address. Render only that public address as
+a QR code and repeat it as copyable text. Tell the human to fund the payer
 wallet address—not the token contract/mint and not WarpMetal's merchant
 recipient. Do not ask for ETH or SOL because supported network fees are
-sponsored.
+sponsored. A refill email repeats the address as text and includes a locally
+generated QR encoding only that address.
 
 ## Stop and recovery states
 

package/skills/warpmetal/references/safety.md

@@ -110,6 +110,13 @@ Confirm the plan, hostname, OS, and public key before preparing it.
 - A signed HTTP 402 rejects that signature. Use the new live challenge for one
   replacement authorization after checking the new terms against the current
   interactive or autonomous payment authority.
+- Treat `sponsorship_allowance_unavailable`,
+  `sponsorship_payment_cap_exceeded`,
+  `sponsorship_payment_allowance_exhausted`,
+  `sponsorship_volume_allowance_exhausted`, and
+  `sponsorship_gas_budget_exhausted` as terminal for the current authorization.
+  Require the merchant tenant to restore or change its sponsorship allowance
+  and issue a fresh challenge; never switch to buyer-funded gas.
 - On timeout or restart after wallet authorization, reuse the saved x402api
   attempt and artifact through WarpMetal. Never authorize again merely because
   submission or fulfillment is uncertain, and never send the private owner

package/src/api.js

@@ -216,6 +216,14 @@ export class WarpMetalClient {
     );
   }
 
+  deleteNotifications(serverId, token) {
+    return this.request(
+      "DELETE",
+      `/servers/${encodeURIComponent(serverId)}/notifications`,
+      { token },
+    );
+  }
+
   renewalCheckout(planId, { bodyText, token, paymentSignature }) {
     return this.checkout(`/checkout/${encodeURIComponent(planId)}/renew`, {
       bodyText,

package/src/cli.js

@@ -84,6 +84,7 @@ Usage:
   warpmetal renewal configure --server <serverId> --renew-before-days <n>
     --maximum-payment-atomic <amount> (--maximum-renewals <n> | --renew-through <UTC>)
     --allowed-network <CAIP-2> --allowed-asset <asset> --wallet <name>
+    [--email <address> | --without-email-notifications]
   warpmetal renewal status|prepare|submit|run ...
   warpmetal renewal due (--server <serverId> | --all)
   warpmetal notifications configure --server <serverId> --email <address>
@@ -364,9 +365,15 @@ async function pollGrant(
 
 function challengeResult(taskId, checkoutBody, response) {
   const paymentRequired = response.headers["payment-required"];
+  const challengeHandle = response.headers["x-x402api-challenge-handle"];
   if (response.status === 402 && !paymentRequired) {
     throw new CliError("WarpMetal returned HTTP 402 without PAYMENT-REQUIRED.");
   }
+  if (response.status === 402 && !challengeHandle) {
+    throw new CliError(
+      "WarpMetal returned HTTP 402 without X-X402API-Challenge-Handle.",
+    );
+  }
   return {
     status: response.data?.status,
     taskId,
@@ -374,6 +381,7 @@ function challengeResult(taskId, checkoutBody, response) {
       response.data?.paymentAttemptId ||
       response.headers["x-warpmetal-payment-attempt"],
     paymentRequired,
+    challengeHandle,
     checkoutBodySha256: createHash("sha256").update(checkoutBody).digest("hex"),
   };
 }
@@ -645,7 +653,7 @@ async function handleCheckoutChallenge(client, store, options, context) {
     stringOption(options, "request-envelope-out"),
   );
   const paymentInstructions = safe.paymentWorkflow
-    ? `\nWallet package: ${safe.paymentWorkflow.signerPackage.spec} (Node ${safe.paymentWorkflow.signerNodeRequirement})\nInstall: ${shellCommand(safe.paymentWorkflow.signerPackage.install.argv)}\nVerify: ${shellCommand(safe.paymentWorkflow.signerContract.probe.argv)}\nRequest envelope: ${safe.paymentWorkflow.requestEnvelopePath}\nAuthorize: ${shellCommand(safe.paymentWorkflow.authorize.argv)}\nSubmit with WarpMetal: ${shellCommand(safe.paymentWorkflow.submit.argv)}`
+    ? `\nWallet package: ${safe.paymentWorkflow.signerPackage.spec} (Node ${safe.paymentWorkflow.signerNodeRequirement})\nInstall: ${shellCommand(safe.paymentWorkflow.signerPackage.install.argv)}\nVerify: ${shellCommand(safe.paymentWorkflow.signerContract.probe.argv)}\nRequest envelope: ${safe.paymentWorkflow.requestEnvelopePath}\nAuthorize: ${shellCommand(safe.paymentWorkflow.authorize.argv)}\nIf funding is short, run ${shellCommand(safe.paymentWorkflow.fundingWorkflow.address.argv)} and ${shellCommand(safe.paymentWorkflow.fundingWorkflow.balance.argv)}, then show the payer address as both a QR code and copyable text.\nSubmit with WarpMetal: ${shellCommand(safe.paymentWorkflow.submit.argv)}`
     : "";
   emit(
     context.stdout,
@@ -775,6 +783,44 @@ export function refillRenewBy(termEndsAt, currentTime = Date.now()) {
   return new Date(Number.isFinite(parsed) && parsed > minimum ? parsed : minimum).toISOString();
 }
 
+function activeNotificationSubscription(notifications) {
+  const subscription = notifications?.subscription;
+  return Boolean(
+    notifications?.configured &&
+      subscription?.verified &&
+      !subscription?.disabled,
+  );
+}
+
+function refillNotificationState(notifications, policy) {
+  const subscription = notifications?.subscription;
+  if (!notifications?.configured || !subscription || subscription.disabled) {
+    return {
+      available: false,
+      reason: "verified_email_required",
+      subscription: subscription || null,
+    };
+  }
+  if (!subscription.verified) {
+    return {
+      available: false,
+      reason: "email_verification_required",
+      subscription,
+    };
+  }
+  if (
+    policy?.notificationReference &&
+    subscription.reference !== policy.notificationReference
+  ) {
+    return {
+      available: false,
+      reason: "notification_reference_mismatch",
+      subscription,
+    };
+  }
+  return { available: true, reason: null, subscription };
+}
+
 async function handleRenewalConfigure(client, store, options, context) {
   const serverId = stringOption(options, "server", { required: true });
   const wallet = stringOption(options, "wallet", { required: true });
@@ -818,7 +864,72 @@ async function handleRenewalConfigure(client, store, options, context) {
   for (const [key, value] of Object.entries(body)) {
     if (value === undefined) delete body[key];
   }
+  const email = stringOption(options, "email");
+  const withoutEmailNotifications = booleanOption(
+    options,
+    "without-email-notifications",
+  );
+  if (email && withoutEmailNotifications) {
+    throw new CliError(
+      "Use either --email or --without-email-notifications, not both.",
+      { exitCode: 2 },
+    );
+  }
   const token = await requireServerToken(store, serverId, options, context.env);
+  let notifications = (await client.getNotifications(serverId, token)).data;
+  if (
+    body.enabled &&
+    !email &&
+    !withoutEmailNotifications &&
+    !activeNotificationSubscription(notifications)
+  ) {
+    const verificationPending = Boolean(
+      notifications.configured &&
+        notifications.subscription &&
+        !notifications.subscription.disabled,
+    );
+    const action = verificationPending
+      ? "email_verification_required"
+      : "email_required";
+    const output = {
+      action,
+      serverId,
+      reason: verificationPending
+        ? "Verify the existing notification email or resend verification with --email."
+        : "A verified email enables renewal and wallet-refill notifications.",
+      notifications,
+      next: {
+        configureEmail: `warpmetal renewal configure ... --email <address>`,
+        continueWithoutEmail:
+          "warpmetal renewal configure ... --without-email-notifications",
+      },
+    };
+    emit(
+      context.stdout,
+      output,
+      context.json,
+      verificationPending
+        ? `Verify the notification email for ${serverId}, or rerun with --email to resend verification. To opt out explicitly, rerun with --without-email-notifications.`
+        : `An email is needed for renewal and wallet-refill notifications. Rerun with --email <address>, or opt out explicitly with --without-email-notifications.`,
+    );
+    return 6;
+  }
+  if (email) {
+    notifications = (
+      await client.putNotifications(serverId, { email }, token)
+    ).data;
+  } else if (
+    withoutEmailNotifications &&
+    notifications.configured &&
+    notifications.subscription &&
+    !notifications.subscription.disabled
+  ) {
+    await client.deleteNotifications(serverId, token);
+    notifications = {
+      ...notifications,
+      subscription: { ...notifications.subscription, disabled: true },
+    };
+  }
   const result = await client.putRenewalPolicy(serverId, body, token);
   await store.saveRenewalPolicy(
     serverId,
@@ -826,19 +937,27 @@ async function handleRenewalConfigure(client, store, options, context) {
     wallet,
     refillTargetAtomic,
   );
-  const email = stringOption(options, "email");
-  let notifications;
-  if (email) {
-    notifications = (
-      await client.putNotifications(serverId, { email }, token)
-    ).data;
-  }
-  const output = { ...result.data, wallet, refillTargetAtomic, notifications };
+  const notificationState = {
+    optedOut: withoutEmailNotifications,
+    refillAvailable: activeNotificationSubscription(notifications),
+    status: withoutEmailNotifications
+      ? "opted_out"
+      : activeNotificationSubscription(notifications)
+        ? "verified"
+        : "verification_required",
+  };
+  const output = {
+    ...result.data,
+    wallet,
+    refillTargetAtomic,
+    notifications,
+    notificationState,
+  };
   emit(
     context.stdout,
     output,
     context.json,
-    `Configured bounded renewal for ${serverId} with wallet ${wallet}.${email ? " Check the email verification link." : ""}`,
+    `Configured bounded renewal for ${serverId} with wallet ${wallet}.${email && !notificationState.refillAvailable ? " Check the email verification link." : withoutEmailNotifications ? " Email and wallet-refill notifications were explicitly skipped." : ""}`,
   );
   return 0;
 }
@@ -866,6 +985,7 @@ async function attachRenewalPaymentWorkflow(
   serverId,
   server,
   renewal,
+  notifications,
   response,
   requestedEnvelopePath,
 ) {
@@ -924,6 +1044,7 @@ async function attachRenewalPaymentWorkflow(
     taskId: server.id,
     serverId,
     kind: "renewal",
+    wallet: renewal.wallet,
     requestEnvelopePath,
     paymentArtifactPath: defaults.paymentArtifactPath,
   });
@@ -932,27 +1053,39 @@ async function attachRenewalPaymentWorkflow(
     BigInt(renewal.refillTargetAtomic) >= BigInt(term.amountAtomic)
       ? renewal.refillTargetAtomic
       : term.amountAtomic;
-  const refillWorkflow = {
-    environment: {
-      X402API_NOTIFICATION_URL: `${client.baseUrl}/notifications/x402api/refill`,
-    },
-    argv: [
-      "x402api",
-      "wallet",
-      "notify-refill",
-      "--wallet",
-      renewal.wallet,
-      "--subscription-reference",
-      renewal.policy.notificationReference,
-      "--renew-by",
-      refillRenewBy(server.termEndsAt),
-      "--target-balance-atomic",
-      refillTarget,
-      "--reason",
-      "renewal",
-      "--json",
-    ],
-  };
+  Object.assign(workflow.fundingWorkflow, {
+    network: term.network,
+    asset: term.asset,
+    requiredPaymentAtomic: term.amountAtomic,
+    targetBalanceAtomic: refillTarget,
+  });
+  const refillNotification = refillNotificationState(
+    notifications,
+    renewal.policy,
+  );
+  const refillWorkflow = refillNotification.available
+    ? {
+        environment: {
+          X402API_NOTIFICATION_URL: `${client.baseUrl}/notifications/x402api/refill`,
+        },
+        argv: [
+          "x402api",
+          "wallet",
+          "notify-refill",
+          "--wallet",
+          renewal.wallet,
+          "--subscription-reference",
+          refillNotification.subscription.reference,
+          "--renew-by",
+          refillRenewBy(server.termEndsAt),
+          "--target-balance-atomic",
+          refillTarget,
+          "--reason",
+          "renewal",
+          "--json",
+        ],
+      }
+    : undefined;
   Object.assign(safe, {
     serverId,
     paymentTerms: request.terms,
@@ -960,6 +1093,7 @@ async function attachRenewalPaymentWorkflow(
     paymentRequestDigest: request.requestDigest,
     paymentChallengeDigest: request.challengeDigest,
     paymentWorkflow: workflow,
+    refillNotification,
     refillWorkflow,
   });
   await store.saveRenewalChallenge(serverId, {
@@ -968,6 +1102,7 @@ async function attachRenewalPaymentWorkflow(
     termEndsAt: server.termEndsAt,
     paymentRequired: safe.paymentRequired,
     paymentAttemptId: safe.paymentAttemptId,
+    challengeHandle: safe.challengeHandle,
     paymentRequestDigest: safe.paymentRequestDigest,
     paymentChallengeDigest: safe.paymentChallengeDigest,
     paymentRequestEnvelopePath: requestEnvelopePath,
@@ -988,9 +1123,10 @@ function renewalActionExitCode(action) {
 
 async function prepareRenewal(client, store, serverId, options, context) {
   const token = await requireServerToken(store, serverId, options, context.env);
-  const [serverResult, policyResult] = await Promise.all([
+  const [serverResult, policyResult, notificationsResult] = await Promise.all([
     client.getServer(serverId, token),
     client.getRenewalPolicy(serverId, token),
+    client.getNotifications(serverId, token),
   ]);
   if (!policyResult.data.configured) {
     return {
@@ -1032,6 +1168,7 @@ async function prepareRenewal(client, store, serverId, options, context) {
     serverId,
     serverResult.data.task,
     local,
+    notificationsResult.data,
     response,
     stringOption(options, "request-envelope-out"),
   );
@@ -1053,8 +1190,16 @@ async function prepareRenewal(client, store, serverId, options, context) {
 async function handleRenewalPrepare(client, store, options, context) {
   const serverId = stringOption(options, "server", { required: true });
   const safe = await prepareRenewal(client, store, serverId, options, context);
+  const fundingInstructions = safe.paymentWorkflow
+    ? `\nIf funding is short, run ${shellCommand(safe.paymentWorkflow.fundingWorkflow.address.argv)} and ${shellCommand(safe.paymentWorkflow.fundingWorkflow.balance.argv)}. Show the returned payer address as both a QR code and copyable text, with the exact network, asset, and deficit.`
+    : "";
+  const refillInstructions = safe.refillWorkflow
+    ? `\nFor verified email refill, set ${Object.entries(safe.refillWorkflow.environment).map(([key, value]) => `${key}=${value}`).join(" ")} and run: ${shellCommand(safe.refillWorkflow.argv)}`
+    : safe.paymentWorkflow
+      ? `\nVerified email refill is unavailable (${safe.refillNotification.reason}). Configure and verify notifications, or fund the displayed payer address directly.`
+      : "";
   const instructions = safe.paymentWorkflow
-    ? `\nAuthorize: ${shellCommand(safe.paymentWorkflow.authorize.argv)}\nIf the wallet is short of funds, set ${Object.entries(safe.refillWorkflow.environment).map(([key, value]) => `${key}=${value}`).join(" ")} and run: ${shellCommand(safe.refillWorkflow.argv)}\nSubmit: ${shellCommand(safe.paymentWorkflow.submit.argv)}`
+    ? `\nAuthorize: ${shellCommand(safe.paymentWorkflow.authorize.argv)}${fundingInstructions}${refillInstructions}\nSubmit: ${shellCommand(safe.paymentWorkflow.submit.argv)}`
     : "";
   emit(
     context.stdout,
@@ -2325,6 +2470,7 @@ async function dispatch(positionals, options, passthrough, context) {
         "allowed-asset",
         "refill-target-atomic",
         "email",
+        "without-email-notifications",
         "disabled",
       ]);
       return handleRenewalConfigure(client, store, options, context);

package/src/payment.js

@@ -15,7 +15,7 @@ const MAX_ARTIFACT_BYTES = 1024 * 1024;
 const MAX_SIGNATURE_BYTES = 512 * 1024;
 
 export const AGENT_WALLET_PACKAGE = "@x402api/agent-wallet-cli";
-export const AGENT_WALLET_VERSION = "0.2.1";
+export const AGENT_WALLET_VERSION = "0.2.3";
 const AGENT_WALLET_SPEC = `${AGENT_WALLET_PACKAGE}@${AGENT_WALLET_VERSION}`;
 const GAS_SPONSORSHIP_EXTENSION = "com.x402api.gas-sponsorship";
 const BASE_NETWORK = "eip155:8453";
@@ -183,6 +183,14 @@ function paymentResource(value, label) {
 function validateGasSponsorship(declaration) {
   const info = declaration.info;
   const schema = declaration.schema;
+  const platformTreasuryPolicy =
+    isObject(info) &&
+    info.billingParty === "platform_treasury" &&
+    info.finalChargePolicy === "platform_treasury_actual_cost";
+  const legacyTenantCreditPolicy =
+    isObject(info) &&
+    info.billingParty === "tenant_service_credit" &&
+    info.finalChargePolicy === "canonical_actual_gas_capped_by_reservation";
   const infoKeys = [
     "billingParty",
     "buyerNativeFeeRequired",
@@ -199,8 +207,7 @@ function validateGasSponsorship(declaration) {
     info.version !== 1 ||
     info.mode !== "facilitator_pays" ||
     info.buyerNativeFeeRequired !== false ||
-    info.billingParty !== "tenant_service_credit" ||
-    info.finalChargePolicy !== "canonical_actual_gas_capped_by_reservation" ||
+    (!platformTreasuryPolicy && !legacyTenantCreditPolicy) ||
     typeof info.maximumReservationEvidenceDigest !== "string" ||
     !SHA256.test(info.maximumReservationEvidenceDigest) ||
     typeof info.expiresAt !== "string" ||
@@ -696,6 +703,7 @@ export function paymentWorkflow({
   taskId,
   serverId,
   kind = "checkout",
+  wallet = "<wallet-name>",
   requestEnvelopePath,
   paymentArtifactPath,
 }) {
@@ -739,7 +747,7 @@ export function paymentWorkflow({
         "payment",
         "authorize",
         "--wallet",
-        "<wallet-name>",
+        wallet,
         "--request-envelope",
         requestEnvelopePath,
         "--artifact-out",
@@ -747,6 +755,27 @@ export function paymentWorkflow({
         "--json",
       ],
     },
+    fundingWorkflow: {
+      action: "fund_wallet",
+      trigger: "insufficient_asset_balance",
+      wallet,
+      address: {
+        argv: ["x402api", "wallet", "address", "--wallet", wallet, "--json"],
+      },
+      balance: {
+        argv: ["x402api", "wallet", "balance", "--wallet", wallet, "--json"],
+      },
+      presentation: {
+        qrPayloadField: "address",
+        textPayloadField: "address",
+        showQr: true,
+        showAddressString: true,
+        showExactDeficit: true,
+        showNetworkAndAsset: true,
+      },
+      safety:
+        "Encode and fund only the payer wallet public address. Never fund the token contract, mint, or WarpMetal merchant recipient; sponsored payments do not require ETH or SOL.",
+    },
     submit: {
       argv:
         kind === "renewal"

package/src/state.js

@@ -280,6 +280,7 @@ export class StateStore {
     {
       paymentRequired,
       paymentAttemptId,
+      challengeHandle,
       paymentRequestDigest,
       paymentChallengeDigest,
       paymentWorkflow,
@@ -293,6 +294,7 @@ export class StateStore {
         });
       order.paymentRequired = paymentRequired;
       order.paymentAttemptId = paymentAttemptId;
+      order.challengeHandle = challengeHandle;
       order.paymentRequestDigest = paymentRequestDigest;
       order.paymentChallengeDigest = paymentChallengeDigest;
       order.paymentRequestEnvelopePath = paymentWorkflow?.requestEnvelopePath;
@@ -465,6 +467,7 @@ export class StateStore {
         serverId: order.serverId,
         planId: order.planId,
         paymentAttemptId: order.paymentAttemptId,
+        challengeHandle: order.challengeHandle,
         walletPaymentAttemptId: order.walletPaymentAttemptId,
         walletName: order.walletName,
         payerAddress: order.walletPayerAddress,
@@ -499,6 +502,7 @@ export class StateStore {
         refillTargetAtomic: renewal.refillTargetAtomic,
         policy: renewal.policy,
         paymentAttemptId: renewal.paymentAttemptId,
+        challengeHandle: renewal.challengeHandle,
         paymentArtifactExpiresAt: renewal.paymentArtifactExpiresAt,
       })),
     };