warpmetal 0.7.9 → 0.8.1

package/README.md

@@ -34,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.8
+npm install --global @x402api/agent-wallet-cli@0.2.9
 x402api help --json
 ```
 
@@ -58,7 +58,7 @@ integration.
 
 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.8 or newer.
+artifact from the npm CLI and requires `warpmetal` CLI version 0.8.1 or newer.
 
 To test the repository marketplace after the plugin lands on `main`:
 
@@ -130,6 +130,12 @@ external-recipient extension bindings to match the advertised alternatives
 exactly, then preserves the chosen authorization artifact byte-for-byte for
 every pending or ambiguous retry.
 
+Submission output includes the server-validated `paymentId`, `confirmed`, and
+`finalized` fields when WarpMetal supplies lifecycle evidence. Retry only while
+confirmation is pending. As soon as `confirmed` is true, stop all payment
+submission—even when `finalized` is false—and let WarpMetal continue signed-
+receipt finality while provisioning or renewal proceeds.
+
 - When a human is actively chatting with the agent, show the exact live terms
   and ask for confirmation immediately before authorizing and submitting.
 - In an unattended run, a pre-funded dedicated wallet is standing spend
@@ -197,7 +203,7 @@ or escalation mechanism or stop with `funding_required`.
 
 Configure renewal only with explicit bounds. This example allows at most 12
 renewals, enforces a 30 USDC per-payment ceiling and a 360 USDC cumulative
-budget, and requests a verified notification recipient:
+budget, and activates a human notification recipient after server authorization:
 
 ```sh
 warpmetal renewal configure \
@@ -213,12 +219,26 @@ warpmetal renewal configure \
   --json
 ```
 
-The recipient must follow the one-time verification link before lifecycle or
-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:
+No email verification is required: the saved owner credential or an SSH-derived
+server token authorizes the change. WarpMetal queues a branded transactional
+advisory identifying the server, why the address was added, and a link that
+removes only that address. Up to five active addresses may be attached
+to one server. If none 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 notifications add --server <serverId> --email ops@example.com --json
+warpmetal notifications list --server <serverId> --json
+warpmetal notifications remove --server <serverId> --recipient <recipientId> --json
+warpmetal notifications events --server <serverId> --events renewal.due,server.ready --json
+warpmetal notifications disable --server <serverId> --json
+```
+
+After provisioning, `warpmetal order status` includes the structured
+`ask_human_for_notification_email` next action until a recipient is active or
+the human explicitly opts out. Public CLI output contains only masked addresses.
 
 ```sh
 warpmetal renewal due --all --json
@@ -227,17 +247,17 @@ warpmetal renewal run --all-due --json
 
 Inside policy, the CLI returns the exact Agent Wallet authorization and submit
 argv. If balance is insufficient, `refillWorkflow` is returned only when the
-server has an active verified notification subscription. Run its argv with the
+server has an active notification recipient. 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, required minimum top-up,
+wallet signature and current on-chain balance before emailing every active
+human recipient 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
+The agent never sends a partial x402 payment. If no active recipient refill path
 exists, it reports `funding_required`. If a previous payment is pending or
 ambiguous, it reconciles the saved attempt and never signs a second payment.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "warpmetal",
-  "version": "0.7.9",
+  "version": "0.8.1",
   "description": "Agent-safe CLI and skill for purchasing, renewing, and managing WarpMetal VPS servers",
   "type": "module",
   "bin": {

package/skills/warpmetal/SKILL.md

@@ -11,7 +11,7 @@ with ad hoc HTTP commands.
 
 ## Start safely
 
-1. Run `warpmetal --version` and require version `0.7.8` or newer for this
+1. Run `warpmetal --version` and require version `0.8.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`.
@@ -173,11 +173,13 @@ 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;
+funding arrives. The signed refill intent resolves server-side to the active
+SSH-authorized human recipients;
 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
+and require `confirmed: true` before accepting the returned `termEndsAt`.
+Stop payment submission at confirmation even when `finalized` is false. On `reconcile_pending` or
 `manual_review`, do not create another authorization.
 
 ## Provision and manage
@@ -188,6 +190,15 @@ Poll a prepared or paid order with:
 warpmetal order status --task <taskId> --wait --json
 ```
 
+When the ready response contains
+`nextAction.action: ask_human_for_notification_email`, ask the human whether
+they want renewal and lifecycle notices. If yes, add the supplied address with
+`warpmetal notifications add --server <serverId> --email <address> --json`.
+The server credential is the authorization; there is no email verification
+step. The address receives a branded advisory and can remove itself without
+affecting other recipients. If the human declines, run the returned
+`notifications disable` command so future status checks do not ask again.
+
 `manual_review` remains terminal for payment and mutation attempts. A later
 read-only status check may observe the backend's authoritative reconciliation;
 prepare a replacement only for the exact `retrySafe: true` result described

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

@@ -72,7 +72,7 @@ retire that attempt and return a new `paymentAttemptId`. The CLI replaces the
 saved challenge and stale wallet-attempt metadata; use only the newly returned
 workflow.
 
-The current integration targets `@x402api/agent-wallet-cli@0.2.8`. A compatible
+The current integration targets `@x402api/agent-wallet-cli@0.2.9`. 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.
 For the current declaration, x402api pays actual gas from its platform treasury
@@ -83,6 +83,12 @@ term. Because the checkout is authenticated, do not substitute `x402api pay`,
 `payment submit`, or `payment reconcile` for the returned WarpMetal submission
 command.
 
+`warpmetal checkout submit` and `warpmetal renewal submit` surface
+`paymentId`, `confirmed`, and `finalized` from WarpMetal and persist those safe
+lifecycle fields in private CLI state. `confirmed: true` is terminal for
+payment submission and starts the business operation; `finalized: false` only
+means signed-receipt reconciliation continues asynchronously.
+
 `--payment-artifact` accepts the owner-only JSON artifact produced by a
 compatible pinned x402api Agent Wallet release. WarpMetal validates its request
 and payment-requirement digests, resource, extensions, buyer payment identifier,
@@ -125,15 +131,25 @@ warpmetal renewal prepare --server <serverId> --json
 warpmetal renewal submit --server <serverId> \
   --payment-artifact <path> [--wait] --json
 warpmetal renewal run (--server <serverId> | --all-due) --json
-warpmetal notifications configure --server <serverId> --email <address> \
+warpmetal notifications add --server <serverId> --email <address> \
   [--events <comma-separated-events>] --json
-warpmetal notifications status --server <serverId> --json
+warpmetal notifications list --server <serverId> --json
+warpmetal notifications remove --server <serverId> --recipient <recipientId> --json
+warpmetal notifications events --server <serverId> \
+  --events <comma-separated-events> --json
+warpmetal notifications disable --server <serverId> --json
 ```
 
-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.
+After a server becomes ready, `order status` returns
+`nextAction.action: ask_human_for_notification_email` when setup has not been
+completed or dismissed. Ask the human for an optional address, then use
+`notifications add`; the server credential authorizes immediate activation, so
+there is no verification step. A branded advisory identifies the server and
+provides recipient-scoped removal. Up to five active recipients are supported.
+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 when at least one active recipient exists.
 `renewal run` is an agent-facing state machine, not a wallet-signing daemon.
 See [renewals.md](renewals.md).
 

package/skills/warpmetal/references/payments.md

@@ -25,7 +25,7 @@ contract.
 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.8`. Do not add it as a WarpMetal dependency,
+`@x402api/agent-wallet-cli@0.2.9`. Do not add it as a WarpMetal dependency,
 install executable wallet code from an unpinned repository URL, or substitute
 a similarly named package.
 
@@ -39,7 +39,9 @@ skill automatically.
 
 1. Install the exact `paymentWorkflow.signerPackage.install.argv` under Node
    22. Run `command -v x402api` and the returned
-   `paymentWorkflow.signerContract.probe.argv`. Require contract version 1.
+   `paymentWorkflow.signerContract.probe.argv`. Require contract version 1 and
+   every entry in `paymentWorkflow.signerContract.requiredCommands` to appear
+   in the probe's `commands` array.
 2. Run the exact `paymentWorkflow.walletWorkflow.setup.argv`. The idempotent
    `x402api wallet setup --json` command creates an owner-only managed unlock
    file inside the x402api home directory and never prints its generated
@@ -152,7 +154,7 @@ 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.8
+tenant debit. During the coordinated rollout, accept only the exact 0.2.9
 platform-treasury declaration or the matched legacy tenant-credit declaration;
 never accept a mixed billing and final-charge policy.
 
@@ -193,9 +195,15 @@ current `termEndsAt` generation are different.
   wallet-attempt metadata when it saves the new challenge. Inspect the new
   terms and authorize only the new workflow; never reuse an expired envelope or
   artifact.
-- `payment_pending` or `payment_finalizing`: keep the same checkout bytes and
-  artifact. Preserve the returned durable `paymentId`; `--wait` records it in
-  private WarpMetal state and performs bounded retries with that exact authorization.
+- `payment_pending`, or legacy `payment_finalizing`, without
+  `confirmed: true`: keep the same checkout bytes and artifact. Preserve the
+  returned durable `paymentId`; `--wait` records it in private WarpMetal state
+  and performs bounded retries with that exact authorization.
+- `confirmed: true`: stop payment submission immediately, including when
+  `finalized` is false or a legacy pending-like status is present. WarpMetal
+  has admitted provisioning or renewal exactly once and will reconcile payment
+  detail plus the signed final receipt asynchronously. Never authorize a
+  replacement because receipt finality is pending.
 - Timeout or process restart after authorization: use the saved x402api attempt
   ID and artifact. Reconcile with WarpMetal and reuse its submit argv. Never
   authorize again merely because submission is unknown.

package/skills/warpmetal/references/renewals.md

@@ -27,9 +27,10 @@ warpmetal renewal configure \
   --json
 ```
 
-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.
+Without an active notification recipient, configuration asks for one before
+changing policy. `--email` immediately activates the address because the owner
+or SSH-derived server credential authorizes the change. WarpMetal sends a
+transactional advisory to the new address; it does not require verification.
 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
@@ -58,7 +59,8 @@ The CLI does not install a daemon. Treat actions as follows:
 - `refill_required`: follow the signed refill workflow and stop.
 - `reconcile_pending`: preserve the artifact and reconcile; never authorize again.
 - `manual_review`: stop all payment and mutation retries.
-- `renewed`: verify the new `termEndsAt` and stop successfully.
+- `renewed` with `confirmed: true`: verify the new `termEndsAt` and stop
+  payment submission successfully, even when `finalized` is false.
 
 ## Authorize and submit renewal
 
@@ -75,8 +77,8 @@ paymentWorkflow.authorize.argv
 paymentWorkflow.submit.argv
 paymentWorkflow.fundingWorkflow
 refillNotification
-refillWorkflow.environment (verified email only)
-refillWorkflow.argv (verified email only)
+refillWorkflow.environment (active recipient only)
+refillWorkflow.argv (active recipient only)
 ```
 
 Invoke the authorize argv once. It writes an owner-only artifact. Then invoke

package/skills/warpmetal/references/safety.md

@@ -117,6 +117,9 @@ Confirm the plan, hostname, OS, and public key before preparing it.
 - For `payment_pending`, retry the exact checkout body and the exact same
   payment artifact. Preserve the returned `paymentId` as the durable x402api
   reconciliation key. Do not create a replacement payment.
+- For `confirmed: true`, stop payment submission even when `finalized` is
+  false. Finality and reorg checks are read-only WarpMetal backend work; they
+  never authorize another payment.
 - A signed HTTP 402 rejects that signature. A `paymentId` can be absent;
   preserve the safe `errorCode`, `requestId`, and `replacementAllowed` result.
   Request a new live challenge and create the one permitted replacement only

package/src/api.js

@@ -208,19 +208,43 @@ export class WarpMetalClient {
     );
   }
 
-  putNotifications(serverId, body, token) {
+  putNotifications(serverId, body, token, idempotencyKey) {
     return this.request(
       "PUT",
       `/servers/${encodeURIComponent(serverId)}/notifications`,
-      { body, token },
+      { body, token, idempotencyKey },
+    );
+  }
+
+  addNotificationRecipient(serverId, body, token, idempotencyKey) {
+    return this.request(
+      "POST",
+      `/servers/${encodeURIComponent(serverId)}/notification-recipients`,
+      { body, token, idempotencyKey },
+    );
+  }
+
+  patchNotifications(serverId, body, token, idempotencyKey) {
+    return this.request(
+      "PATCH",
+      `/servers/${encodeURIComponent(serverId)}/notifications`,
+      { body, token, idempotencyKey },
     );
   }
 
-  deleteNotifications(serverId, token) {
+  deleteNotifications(serverId, token, idempotencyKey) {
     return this.request(
       "DELETE",
       `/servers/${encodeURIComponent(serverId)}/notifications`,
-      { token },
+      { token, idempotencyKey },
+    );
+  }
+
+  deleteNotificationRecipient(serverId, recipientId, token, idempotencyKey) {
+    return this.request(
+      "DELETE",
+      `/servers/${encodeURIComponent(serverId)}/notification-recipients/${encodeURIComponent(recipientId)}`,
+      { token, idempotencyKey },
     );
   }
 

package/src/cli.js

@@ -87,8 +87,14 @@ Usage:
     [--email <address> | --without-email-notifications]
   warpmetal renewal status|prepare|submit|run ...
   warpmetal renewal due (--server <serverId> | --all)
-  warpmetal notifications configure --server <serverId> --email <address>
-  warpmetal notifications status --server <serverId>
+  warpmetal notifications add --server <serverId> --email <address>
+    [--events <comma-separated-events>] [--idempotency-key <key>]
+  warpmetal notifications list --server <serverId>
+  warpmetal notifications remove --server <serverId> --recipient <recipientId>
+    [--idempotency-key <key>]
+  warpmetal notifications events --server <serverId> --events <comma-separated-events>
+    [--idempotency-key <key>]
+  warpmetal notifications disable --server <serverId> [--idempotency-key <key>]
   warpmetal identity generate --hostname <name> [--ssh-key-name <name>]
   warpmetal identity list
   warpmetal server identity --server <serverId>
@@ -209,6 +215,42 @@ function suggestedDelay(result, fallback = 2) {
   );
 }
 
+function paymentLifecycle(result) {
+  const confirmed = result.data?.confirmed;
+  const finalized = result.data?.finalized;
+  if (confirmed === undefined && finalized === undefined) {
+    return { confirmed: undefined, finalized: undefined };
+  }
+  if (
+    typeof confirmed !== "boolean" ||
+    typeof finalized !== "boolean" ||
+    (finalized && !confirmed)
+  ) {
+    throw new CliError("WarpMetal returned contradictory payment lifecycle evidence.", {
+      exitCode: 3,
+    });
+  }
+  if (confirmed && !result.data?.paymentId) {
+    throw new CliError("WarpMetal confirmed payment without a payment ID.", {
+      exitCode: 3,
+    });
+  }
+  if (["provisioning", "renewed"].includes(result.data?.status) && !confirmed) {
+    throw new CliError("WarpMetal returned a terminal payment status without confirmation.", {
+      exitCode: 3,
+    });
+  }
+  return { confirmed, finalized };
+}
+
+function paymentSubmissionPending(result, lifecycle) {
+  return (
+    result.status === 202 &&
+    lifecycle.confirmed !== true &&
+    ["payment_pending", "payment_finalizing"].includes(result.data?.status)
+  );
+}
+
 async function readHeaderValueFile(path, label) {
   const value = (await readFile(resolve(path), "utf8")).trim();
   if (!value || value.includes("\n") || value.includes("\r")) {
@@ -673,11 +715,40 @@ async function handleTaskStatus(client, store, options, context) {
   const result = booleanOption(options, "wait")
     ? await pollTask(client, taskId, token, timeout)
     : await client.getTask(taskId, token);
+  const output = { ...result.data };
+  let notificationMessage = "";
+  if (result.data.task.state === "ready" && result.data.task.serverId) {
+    try {
+      const notifications = (
+        await client.getNotifications(result.data.task.serverId, token)
+      ).data;
+      output.notifications = notifications;
+      if (notifications.setupRecommended) {
+        output.nextAction = {
+          action: "ask_human_for_notification_email",
+          optional: true,
+          reason:
+            "A human can receive renewal, wallet refill, and server lifecycle notifications.",
+          addCommand: `warpmetal notifications add --server ${result.data.task.serverId} --email <address> --json`,
+          skipCommand: `warpmetal notifications disable --server ${result.data.task.serverId} --json`,
+        };
+        notificationMessage =
+          `\nAsk the human whether they want renewal and lifecycle notifications. ` +
+          `If yes, run: warpmetal notifications add --server ${result.data.task.serverId} --email <address>`;
+      }
+    } catch (error) {
+      output.notificationSetup = {
+        action: "check_notifications",
+        unavailable: true,
+        reason: toErrorMessage(error),
+      };
+    }
+  }
   emit(
     context.stdout,
-    result.data,
+    output,
     context.json,
-    `${result.data.task.id}: ${result.data.task.state}${result.data.task.publicIp ? ` (${result.data.task.publicIp})` : ""}`,
+    `${result.data.task.id}: ${result.data.task.state}${result.data.task.publicIp ? ` (${result.data.task.publicIp})` : ""}${notificationMessage}`,
   );
   return result.data.task.state === "manual_review" ? 6 : 0;
 }
@@ -771,8 +842,12 @@ async function handleCheckoutSubmit(client, store, options, context) {
       token,
       paymentSignature,
     });
+    const lifecycle = paymentLifecycle(response);
     if (response.data?.paymentId) {
       await store.saveOrderPaymentId(taskId, response.data.paymentId);
+      if (lifecycle.confirmed !== undefined) {
+        await store.saveOrderPaymentOutcome(taskId, response.data.paymentId, lifecycle);
+      }
     }
     const safe = await attachPaymentWorkflow(
       client,
@@ -791,9 +866,7 @@ async function handleCheckoutSubmit(client, store, options, context) {
         replacementAllowed: safe.replacementAllowed,
       });
     }
-    const retryable =
-      response.status === 202 &&
-      ["payment_pending", "payment_finalizing"].includes(response.data?.status);
+    const retryable = paymentSubmissionPending(response, lifecycle);
     if (wait && retryable) {
       ensureBeforeDeadline(deadline, `Checkout ${taskId}`);
       await delay(suggestedDelay(response));
@@ -804,6 +877,8 @@ async function handleCheckoutSubmit(client, store, options, context) {
       ...safe,
       task: response.data?.task,
       paymentId: response.data?.paymentId,
+      confirmed: lifecycle.confirmed,
+      finalized: lifecycle.finalized,
       message: response.data?.message,
       ...(walletPayment
         ? {
@@ -853,8 +928,9 @@ function activeNotificationSubscription(notifications) {
   const subscription = notifications?.subscription;
   return Boolean(
     notifications?.configured &&
-      subscription?.verified &&
-      !subscription?.disabled,
+      !subscription?.disabled &&
+      Array.isArray(subscription?.recipients) &&
+      subscription.recipients.length > 0,
   );
 }
 
@@ -863,14 +939,14 @@ function refillNotificationState(notifications, policy) {
   if (!notifications?.configured || !subscription || subscription.disabled) {
     return {
       available: false,
-      reason: "verified_email_required",
+      reason: "active_notification_recipient_required",
       subscription: subscription || null,
     };
   }
-  if (!subscription.verified) {
+  if (!Array.isArray(subscription.recipients) || subscription.recipients.length === 0) {
     return {
       available: false,
-      reason: "email_verification_required",
+      reason: "active_notification_recipient_required",
       subscription,
     };
   }
@@ -949,20 +1025,10 @@ async function handleRenewalConfigure(client, store, options, context) {
     !withoutEmailNotifications &&
     !activeNotificationSubscription(notifications)
   ) {
-    const verificationPending = Boolean(
-      notifications.configured &&
-        notifications.subscription &&
-        !notifications.subscription.disabled,
-    );
-    const action = verificationPending
-      ? "email_verification_required"
-      : "email_required";
     const output = {
-      action,
+      action: "email_required",
       serverId,
-      reason: verificationPending
-        ? "Verify the existing notification email or resend verification with --email."
-        : "A verified email enables renewal and wallet-refill notifications.",
+      reason: "A human email enables renewal and wallet-refill notifications.",
       notifications,
       next: {
         configureEmail: `warpmetal renewal configure ... --email <address>`,
@@ -974,27 +1040,27 @@ async function handleRenewalConfigure(client, store, options, context) {
       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.`,
+      `Ask the human for an email to receive renewal and lifecycle notifications for ${serverId}, then rerun with --email <address>. To opt out explicitly, rerun with --without-email-notifications.`,
     );
     return 6;
   }
   if (email) {
     notifications = (
-      await client.putNotifications(serverId, { email }, token)
+      await client.addNotificationRecipient(
+        serverId,
+        { email },
+        token,
+        stringOption(options, "idempotency-key") || idempotencyKey("notification-add"),
+      )
+    ).data;
+  } else if (withoutEmailNotifications) {
+    notifications = (
+      await client.deleteNotifications(
+        serverId,
+        token,
+        stringOption(options, "idempotency-key") || idempotencyKey("notification-disable"),
+      )
     ).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(
@@ -1009,8 +1075,8 @@ async function handleRenewalConfigure(client, store, options, context) {
     status: withoutEmailNotifications
       ? "opted_out"
       : activeNotificationSubscription(notifications)
-        ? "verified"
-        : "verification_required",
+        ? "active"
+        : "recipient_required",
   };
   const output = {
     ...result.data,
@@ -1023,7 +1089,7 @@ async function handleRenewalConfigure(client, store, options, context) {
     context.stdout,
     output,
     context.json,
-    `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." : ""}`,
+    `Configured bounded renewal for ${serverId} with wallet ${wallet}.${email ? " The notification recipient is active and its security advisory was queued." : withoutEmailNotifications ? " Email and wallet-refill notifications were explicitly skipped." : ""}`,
   );
   return 0;
 }
@@ -1257,9 +1323,9 @@ async function handleRenewalPrepare(client, store, options, context) {
     ? `\n${walletWorkflowInstructions(safe.paymentWorkflow)}. 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)}`
+    ? `\nFor human refill notification, 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.`
+      ? `\nEmail refill is unavailable (${safe.refillNotification.reason}). Add a notification recipient, or fund the displayed payer address directly.`
       : "";
   const instructions = safe.paymentWorkflow
     ? `\nAuthorize: ${shellCommand(safe.paymentWorkflow.authorize.argv)}${fundingInstructions}${refillInstructions}\nSubmit: ${shellCommand(safe.paymentWorkflow.submit.argv)}`
@@ -1378,8 +1444,16 @@ async function handleRenewalSubmit(client, store, options, context) {
         paymentSignature: walletPayment.paymentSignature,
       },
     );
+    const lifecycle = paymentLifecycle(response);
     if (response.data?.paymentId) {
       await store.saveRenewalPaymentId(serverId, response.data.paymentId);
+      if (lifecycle.confirmed !== undefined) {
+        await store.saveRenewalPaymentOutcome(
+          serverId,
+          response.data.paymentId,
+          lifecycle,
+        );
+      }
     }
     if (response.status === 402 && response.data?.status === "payment_rejected") {
       await store.saveRenewalPaymentRejection(serverId, {
@@ -1391,9 +1465,7 @@ async function handleRenewalSubmit(client, store, options, context) {
         replacementAllowed: response.data?.replacementAllowed,
       });
     }
-    const retryable =
-      response.status === 202 &&
-      ["payment_pending", "payment_finalizing"].includes(response.data?.status);
+    const retryable = paymentSubmissionPending(response, lifecycle);
     if (booleanOption(options, "wait") && retryable) {
       ensureBeforeDeadline(deadline, `Renewal ${serverId}`);
       await delay(suggestedDelay(response));
@@ -1404,6 +1476,8 @@ async function handleRenewalSubmit(client, store, options, context) {
       serverId,
       task: response.data?.task,
       paymentId: response.data?.paymentId,
+      confirmed: lifecycle.confirmed,
+      finalized: lifecycle.finalized,
       paymentAttemptId:
         response.data?.paymentAttemptId ||
         response.headers["x-warpmetal-payment-attempt"],
@@ -1464,38 +1538,113 @@ async function handleRenewalDue(client, store, options, context) {
   return due.length ? 8 : 0;
 }
 
-async function handleNotificationsConfigure(client, store, options, context) {
+function notificationEvents(options, { required = false } = {}) {
+  const eventValue = stringOption(options, "events", { required });
+  if (!eventValue) return undefined;
+  const events = eventValue.split(",").map((value) => value.trim());
+  if (events.some((value) => !value)) {
+    throw new CliError("--events must contain comma-separated event names.", {
+      exitCode: 2,
+    });
+  }
+  return events;
+}
+
+async function handleNotificationsAdd(client, store, options, context) {
   const serverId = stringOption(options, "server", { required: true });
   const email = stringOption(options, "email", { required: true });
-  const eventValue = stringOption(options, "events");
   const body = { email };
-  if (eventValue) body.events = eventValue.split(",").map((value) => value.trim());
+  const events = notificationEvents(options);
+  if (events) body.events = events;
   const token = await requireServerToken(store, serverId, options, context.env);
-  const result = await client.putNotifications(serverId, body, token);
+  const result = await client.addNotificationRecipient(
+    serverId,
+    body,
+    token,
+    stringOption(options, "idempotency-key") || idempotencyKey("notification-add"),
+  );
   emit(
     context.stdout,
     result.data,
     context.json,
-    `Verification email queued for ${result.data.subscription.email}.`,
+    result.data.created
+      ? `${result.data.recipient.email} is active for ${serverId}; WarpMetal queued a security advisory to that address.`
+      : `${result.data.recipient.email} was already active for ${serverId}.`,
   );
   return 0;
 }
 
-async function handleNotificationsStatus(client, store, options, context) {
+async function handleNotificationsList(client, store, options, context) {
   const serverId = stringOption(options, "server", { required: true });
   const token = await requireServerToken(store, serverId, options, context.env);
   const result = await client.getNotifications(serverId, token);
+  const count = result.data.subscription?.recipients?.length || 0;
   emit(
     context.stdout,
     result.data,
     context.json,
     result.data.configured
-      ? `${serverId}: notifications ${result.data.subscription.verified ? "verified" : "awaiting verification"}`
+      ? `${serverId}: ${count} active notification recipient${count === 1 ? "" : "s"}`
       : `${serverId}: notifications are not configured`,
   );
   return 0;
 }
 
+async function handleNotificationsRemove(client, store, options, context) {
+  const serverId = stringOption(options, "server", { required: true });
+  const recipientId = stringOption(options, "recipient", { required: true });
+  const token = await requireServerToken(store, serverId, options, context.env);
+  const result = await client.deleteNotificationRecipient(
+    serverId,
+    recipientId,
+    token,
+    stringOption(options, "idempotency-key") || idempotencyKey("notification-remove"),
+  );
+  emit(
+    context.stdout,
+    result.data,
+    context.json,
+    `Removed ${recipientId} from ${serverId} notifications.`,
+  );
+  return 0;
+}
+
+async function handleNotificationsEvents(client, store, options, context) {
+  const serverId = stringOption(options, "server", { required: true });
+  const events = notificationEvents(options, { required: true });
+  const token = await requireServerToken(store, serverId, options, context.env);
+  const result = await client.patchNotifications(
+    serverId,
+    { events },
+    token,
+    stringOption(options, "idempotency-key") || idempotencyKey("notification-events"),
+  );
+  emit(
+    context.stdout,
+    result.data,
+    context.json,
+    `Updated notification events for ${serverId}.`,
+  );
+  return 0;
+}
+
+async function handleNotificationsDisable(client, store, options, context) {
+  const serverId = stringOption(options, "server", { required: true });
+  const token = await requireServerToken(store, serverId, options, context.env);
+  const result = await client.deleteNotifications(
+    serverId,
+    token,
+    stringOption(options, "idempotency-key") || idempotencyKey("notification-disable"),
+  );
+  emit(
+    context.stdout,
+    result.data,
+    context.json,
+    `Disabled lifecycle notifications for ${serverId}.`,
+  );
+  return 0;
+}
+
 async function loginServer(client, store, serverId, identity) {
   const challenge = (await client.issueSshChallenge(serverId)).data;
   const signature = await signSshChallenge(challenge.payload, identity);
@@ -2553,6 +2702,7 @@ async function dispatch(positionals, options, passthrough, context) {
         "email",
         "without-email-notifications",
         "disabled",
+        "idempotency-key",
       ]);
       return handleRenewalConfigure(client, store, options, context);
     case "renewal status":
@@ -2597,6 +2747,7 @@ async function dispatch(positionals, options, passthrough, context) {
         "request-envelope-out",
       ]);
       return handleRenewalRun(client, store, options, context);
+    case "notifications add":
     case "notifications configure":
       rejectUnknownOptions(options, [
         ...COMMON_OPTIONS,
@@ -2604,15 +2755,43 @@ async function dispatch(positionals, options, passthrough, context) {
         "token-file",
         "email",
         "events",
+        "idempotency-key",
       ]);
-      return handleNotificationsConfigure(client, store, options, context);
+      return handleNotificationsAdd(client, store, options, context);
+    case "notifications list":
     case "notifications status":
       rejectUnknownOptions(options, [
         ...COMMON_OPTIONS,
         "server",
         "token-file",
       ]);
-      return handleNotificationsStatus(client, store, options, context);
+      return handleNotificationsList(client, store, options, context);
+    case "notifications remove":
+      rejectUnknownOptions(options, [
+        ...COMMON_OPTIONS,
+        "server",
+        "token-file",
+        "recipient",
+        "idempotency-key",
+      ]);
+      return handleNotificationsRemove(client, store, options, context);
+    case "notifications events":
+      rejectUnknownOptions(options, [
+        ...COMMON_OPTIONS,
+        "server",
+        "token-file",
+        "events",
+        "idempotency-key",
+      ]);
+      return handleNotificationsEvents(client, store, options, context);
+    case "notifications disable":
+      rejectUnknownOptions(options, [
+        ...COMMON_OPTIONS,
+        "server",
+        "token-file",
+        "idempotency-key",
+      ]);
+      return handleNotificationsDisable(client, store, options, context);
     case "server login":
       rejectUnknownOptions(options, [...COMMON_OPTIONS, "server", "identity"]);
       return handleServerLogin(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.8";
+export const AGENT_WALLET_VERSION = "0.2.9";
 const AGENT_WALLET_SPEC = `${AGENT_WALLET_PACKAGE}@${AGENT_WALLET_VERSION}`;
 const GAS_SPONSORSHIP_EXTENSION = "com.x402api.gas-sponsorship";
 const BASE_NETWORK = "eip155:8453";
@@ -842,6 +842,9 @@ export function paymentWorkflow({
     signerContract: {
       version: 1,
       probe: { argv: ["x402api", "help", "--json"] },
+      requiredCommands: [
+        "payment authorize --wallet <name> --request-envelope <file> --artifact-out <file>",
+      ],
     },
     signerReleaseStatus:
       "published launch payer; sponsored Base USDC and Solana USDC/USDT only",

package/src/state.js

@@ -14,6 +14,8 @@ const WALLET_PAYMENT_STATE_FIELDS = [
   "paymentArtifactExpiresAt",
   "paymentArtifactSavedAt",
   "gatewayPaymentId",
+  "gatewayPaymentConfirmed",
+  "gatewayPaymentFinalized",
   "rejectedPaymentAttemptId",
   "paymentRejectionErrorCode",
   "paymentRejectionRequestId",
@@ -437,6 +439,43 @@ export class StateStore {
     });
   }
 
+  async saveOrderPaymentOutcome(taskId, paymentId, { confirmed, finalized }) {
+    if (
+      !X402API_PAYMENT_ID.test(paymentId || "") ||
+      typeof confirmed !== "boolean" ||
+      typeof finalized !== "boolean" ||
+      (finalized && !confirmed)
+    ) {
+      throw new CliError("WarpMetal returned invalid payment lifecycle evidence.", {
+        exitCode: 3,
+      });
+    }
+    await this.update((state) => {
+      const order = state.orders[taskId];
+      if (!order) {
+        throw new CliError(`No local order state exists for ${taskId}.`, {
+          exitCode: 2,
+        });
+      }
+      if (order.gatewayPaymentId && order.gatewayPaymentId !== paymentId) {
+        throw new CliError("WarpMetal changed the x402api payment ID for this attempt.", {
+          exitCode: 3,
+        });
+      }
+      if (
+        (order.gatewayPaymentConfirmed === true && !confirmed) ||
+        (order.gatewayPaymentFinalized === true && !finalized)
+      ) {
+        throw new CliError("WarpMetal payment lifecycle evidence moved backward.", {
+          exitCode: 3,
+        });
+      }
+      order.gatewayPaymentId = paymentId;
+      order.gatewayPaymentConfirmed = confirmed;
+      order.gatewayPaymentFinalized = finalized;
+    });
+  }
+
   async saveOrderPaymentRejection(taskId, rejection) {
     const safe = validatedPaymentRejection(rejection);
     await this.update((state) => {
@@ -481,6 +520,43 @@ export class StateStore {
     });
   }
 
+  async saveRenewalPaymentOutcome(serverId, paymentId, { confirmed, finalized }) {
+    if (
+      !X402API_PAYMENT_ID.test(paymentId || "") ||
+      typeof confirmed !== "boolean" ||
+      typeof finalized !== "boolean" ||
+      (finalized && !confirmed)
+    ) {
+      throw new CliError("WarpMetal returned invalid payment lifecycle evidence.", {
+        exitCode: 3,
+      });
+    }
+    await this.update((state) => {
+      const renewal = state.renewals[serverId];
+      if (!renewal) {
+        throw new CliError(`No local renewal state exists for ${serverId}.`, {
+          exitCode: 2,
+        });
+      }
+      if (renewal.gatewayPaymentId && renewal.gatewayPaymentId !== paymentId) {
+        throw new CliError("WarpMetal changed the x402api payment ID for this renewal.", {
+          exitCode: 3,
+        });
+      }
+      if (
+        (renewal.gatewayPaymentConfirmed === true && !confirmed) ||
+        (renewal.gatewayPaymentFinalized === true && !finalized)
+      ) {
+        throw new CliError("WarpMetal renewal payment lifecycle evidence moved backward.", {
+          exitCode: 3,
+        });
+      }
+      renewal.gatewayPaymentId = paymentId;
+      renewal.gatewayPaymentConfirmed = confirmed;
+      renewal.gatewayPaymentFinalized = finalized;
+    });
+  }
+
   async saveRenewalPaymentRejection(serverId, rejection) {
     const safe = validatedPaymentRejection(rejection);
     await this.update((state) => {
@@ -631,6 +707,8 @@ export class StateStore {
         planId: order.planId,
         paymentAttemptId: order.paymentAttemptId,
         paymentId: order.gatewayPaymentId,
+        paymentConfirmed: order.gatewayPaymentConfirmed,
+        paymentFinalized: order.gatewayPaymentFinalized,
         challengeHandle: order.challengeHandle,
         walletPaymentAttemptId: order.walletPaymentAttemptId,
         walletName: order.walletName,
@@ -671,6 +749,8 @@ export class StateStore {
         policy: renewal.policy,
         paymentAttemptId: renewal.paymentAttemptId,
         paymentId: renewal.gatewayPaymentId,
+        paymentConfirmed: renewal.gatewayPaymentConfirmed,
+        paymentFinalized: renewal.gatewayPaymentFinalized,
         challengeHandle: renewal.challengeHandle,
         paymentArtifactExpiresAt: renewal.paymentArtifactExpiresAt,
         rejectedPaymentAttemptId: renewal.rejectedPaymentAttemptId,