warpmetal 0.8.0 → 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "warpmetal",
-  "version": "0.8.0",
+  "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`.
@@ -178,7 +178,8 @@ 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

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,

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

@@ -59,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
 

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/cli.js

@@ -215,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")) {
@@ -806,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,
@@ -826,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));
@@ -839,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
         ? {
@@ -1404,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, {
@@ -1417,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));
@@ -1430,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"],

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,