warpmetal 0.7.5 → 0.7.7

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.6
+npm install --global @x402api/agent-wallet-cli@0.2.7
 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.5 or newer.
+artifact from the npm CLI and requires `warpmetal` CLI version 0.7.7 or newer.
 
 To test the repository marketplace after the plugin lands on `main`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "warpmetal",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "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.5` or newer for this
+1. Run `warpmetal --version` and require version `0.7.7` 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`.
@@ -136,12 +136,22 @@ WarpMetal verifies that the artifact matches the exact saved request and an
 advertised sponsored requirement, gas reservation, resource, extensions, and
 buyer payment identifier before sending its signature. The legacy
 `--payment-signature-file` input remains available for another compatible
-external signer. If a signed request returns a replacement challenge, use the
-new CLI-produced workflow and re-evaluate payment authority. Ask again when a
-human is chatting and the terms changed; in an unattended run, proceed only if
-the replacement remains within standing authority. On `manual_review` or an
+external signer. If a signed request returns `payment_rejected`, preserve its
+safe `errorCode` and `requestId` diagnostics and inspect `replacementAllowed`.
+When it is true, run the unsigned challenge flow again and re-evaluate payment
+authority before creating the one permitted replacement authorization. When it
+is false or absent, stop without signing again. On `manual_review` or an
 ambiguous attempt, stop and never create another payment.
 
+WarpMetal continues read-only backend reconciliation for
+`manual_review/stale_payment_outcome`; this is not a client bypass. Re-read the
+task on a later autonomous cycle. Only when it becomes `expired` with
+`failure.code` equal to `payment_expired_unsettled`, `paidAt` null, and
+`retrySafe` true has WarpMetal proved that the prior charge expired unpaid. An
+autonomous workflow may then prepare a new order if the original intent and
+standing authority still apply. Never reuse the old signature or infer safety
+from wallet balance, timeout, `paidAt`, `expired`, or `manual_review` alone.
+
 ## Renew autonomously within policy
 
 Configure a bounded server policy before unattended renewal. Require a
@@ -178,6 +188,11 @@ Poll a prepared or paid order with:
 warpmetal order status --task <taskId> --wait --json
 ```
 
+`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
+above.
+
 After initial provisioning and every OS reload, WarpMetal reapplies the same
 key-only policy: `PasswordAuthentication no`,
 `KbdInteractiveAuthentication no`, `PermitRootLogin prohibit-password`, and

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

@@ -69,7 +69,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.6`. A compatible
+The current integration targets `@x402api/agent-wallet-cli@0.2.7`. 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

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.6`. Do not add it as a WarpMetal dependency,
+`@x402api/agent-wallet-cli@0.2.7`. Do not add it as a WarpMetal dependency,
 install executable wallet code from an unpinned repository URL, or substitute
 a similarly named package.
 
@@ -149,7 +149,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.6
+tenant debit. During the coordinated rollout, accept only the exact 0.2.7
 platform-treasury declaration or the matched legacy tenant-credit declaration;
 never accept a mixed billing and final-charge policy.
 
@@ -191,14 +191,17 @@ current `termEndsAt` generation are different.
   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. `--wait` performs bounded retries with that exact authorization.
+  artifact. Preserve the returned durable `paymentId`; `--wait` records it in
+  private WarpMetal state and performs bounded retries with that exact authorization.
 - 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.
-- Signed HTTP 402: the artifact was definitively rejected. Run the WarpMetal
-  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.
+- Signed HTTP 402: the artifact was definitively rejected. A `paymentId` may be
+  absent because settlement never began; preserve the safe `errorCode`,
+  `requestId`, and `replacementAllowed` result instead. Only when
+  `replacementAllowed` is true may you run the unsigned WarpMetal challenge
+  flow again, inspect the replacement terms, and authorize the one permitted
+  replacement artifact. When false or absent, stop without signing again.
 - `sponsorship_allowance_unavailable`, `sponsorship_payment_cap_exceeded`,
   `sponsorship_payment_allowance_exhausted`,
   `sponsorship_volume_allowance_exhausted`, or
@@ -206,7 +209,12 @@ current `termEndsAt` generation are different.
   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.
+  mutation retries. WarpMetal may continue read-only backend reconciliation for
+  `stale_payment_outcome`; check status on a later autonomous cycle without
+  submitting a payment. Only `expired` plus
+  `failure.code: payment_expired_unsettled`, `paidAt: null`, and
+  `retrySafe: true` proves the old charge expired unpaid and permits preparing
+  a new order under current standing authority. Never reuse the old signature.
 - Expired or corrupt signed artifact, changed request digest, unexpected recipient,
   unsupported network, asset, profile, sponsorship error, or request-binding
   mismatch: stop instead of falling back or asking the buyer to fund ETH/SOL.

package/skills/warpmetal/references/renewals.md

@@ -127,7 +127,9 @@ generated QR encoding only that address.
 ## Stop and recovery states
 
 - Insufficient balance: notify once, stop, and recheck later.
-- Signed HTTP 402: re-run prepare and re-evaluate the replacement challenge.
+- Signed HTTP 402: preserve the safe rejection diagnostics. Re-run prepare and
+  re-evaluate one replacement challenge only when `replacementAllowed` is true;
+  stop when false or absent.
 - Pending or timeout after authorization: reuse the same artifact; do not sign again.
 - Price or payment rail outside policy: stop for deliberate policy revision.
 - Exhausted count, horizon, or cumulative budget: stop for deliberate policy revision.

package/skills/warpmetal/references/safety.md

@@ -115,10 +115,13 @@ Confirm the plan, hostname, OS, and public key before preparing it.
   replaces its saved challenge metadata. Re-evaluate the new terms before
   authorization; never sign or submit the expired challenge.
 - For `payment_pending`, retry the exact checkout body and the exact same
-  payment artifact. Do not create a replacement payment.
-- 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.
+  payment artifact. Preserve the returned `paymentId` as the durable x402api
+  reconciliation key. Do not create a replacement 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
+  when `replacementAllowed` is true and the new terms remain within current
+  interactive or autonomous payment authority. When false or absent, stop.
 - Treat `sponsorship_allowance_unavailable`,
   `sponsorship_payment_cap_exceeded`,
   `sponsorship_payment_allowance_exhausted`,
@@ -130,8 +133,11 @@ Confirm the plan, hostname, OS, and public key before preparing it.
   attempt and artifact through WarpMetal. Never authorize again merely because
   submission or fulfillment is uncertain, and never send the private owner
   token through `x402api pay`, `payment submit`, or `payment reconcile`.
-- Treat `manual_review` as terminal. Do not pay again and do not repeat the
-  mutation.
+- Treat `manual_review` as terminal for payments and mutations. Do not pay
+  again and do not repeat the mutation. A later read-only status check may
+  observe automatic reconciliation of `stale_payment_outcome`; only the exact
+  `expired/payment_expired_unsettled` result with `paidAt: null` and
+  `retrySafe: true` permits preparing a new order.
 - Treat HTTP 202 as accepted or pending, never as proof of success. Poll the
   returned task or operation until a documented terminal state.
 - Temporary sandbox expiry is a local hard deadline. Stop, restart, and

package/src/cli.js

@@ -379,19 +379,26 @@ async function pollGrant(
   }
 }
 
-function challengeResult(taskId, checkoutBody, response) {
+function challengeResult(
+  taskId,
+  checkoutBody,
+  response,
+  { requireChallenge = true } = {},
+) {
+  const status = response.data?.status;
+  const rejected = response.status === 402 && status === "payment_rejected";
   const paymentRequired = response.headers["payment-required"];
   const challengeHandle = response.headers["x-x402api-challenge-handle"];
-  if (response.status === 402 && !paymentRequired) {
+  if (requireChallenge && response.status === 402 && !paymentRequired) {
     throw new CliError("WarpMetal returned HTTP 402 without PAYMENT-REQUIRED.");
   }
-  if (response.status === 402 && !challengeHandle) {
+  if (requireChallenge && response.status === 402 && !challengeHandle) {
     throw new CliError(
       "WarpMetal returned HTTP 402 without X-X402API-Challenge-Handle.",
     );
   }
   return {
-    status: response.data?.status,
+    status,
     taskId,
     paymentAttemptId:
       response.data?.paymentAttemptId ||
@@ -399,6 +406,13 @@ function challengeResult(taskId, checkoutBody, response) {
     paymentRequired,
     challengeHandle,
     checkoutBodySha256: createHash("sha256").update(checkoutBody).digest("hex"),
+    ...(rejected
+      ? {
+          errorCode: response.data?.errorCode,
+          requestId: response.data?.requestId,
+          replacementAllowed: response.data?.replacementAllowed,
+        }
+      : {}),
   };
 }
 
@@ -736,13 +750,26 @@ async function handleCheckoutSubmit(client, store, options, context) {
       token,
       paymentSignature,
     });
+    if (response.data?.paymentId) {
+      await store.saveOrderPaymentId(taskId, response.data.paymentId);
+    }
     const safe = await attachPaymentWorkflow(
       client,
       store,
       taskId,
       order,
-      challengeResult(taskId, order.checkoutBody, response),
+      challengeResult(taskId, order.checkoutBody, response, {
+        requireChallenge: false,
+      }),
     );
+    if (response.status === 402 && safe.status === "payment_rejected") {
+      await store.saveOrderPaymentRejection(taskId, {
+        paymentAttemptId: safe.paymentAttemptId,
+        errorCode: safe.errorCode,
+        requestId: safe.requestId,
+        replacementAllowed: safe.replacementAllowed,
+      });
+    }
     const retryable =
       response.status === 202 &&
       ["payment_pending", "payment_finalizing"].includes(response.data?.status);
@@ -755,6 +782,7 @@ async function handleCheckoutSubmit(client, store, options, context) {
     const output = {
       ...safe,
       task: response.data?.task,
+      paymentId: response.data?.paymentId,
       message: response.data?.message,
       ...(walletPayment
         ? {
@@ -1327,6 +1355,19 @@ async function handleRenewalSubmit(client, store, options, context) {
         paymentSignature: walletPayment.paymentSignature,
       },
     );
+    if (response.data?.paymentId) {
+      await store.saveRenewalPaymentId(serverId, response.data.paymentId);
+    }
+    if (response.status === 402 && response.data?.status === "payment_rejected") {
+      await store.saveRenewalPaymentRejection(serverId, {
+        paymentAttemptId:
+          response.data?.paymentAttemptId ||
+          response.headers["x-warpmetal-payment-attempt"],
+        errorCode: response.data?.errorCode,
+        requestId: response.data?.requestId,
+        replacementAllowed: response.data?.replacementAllowed,
+      });
+    }
     const retryable =
       response.status === 202 &&
       ["payment_pending", "payment_finalizing"].includes(response.data?.status);
@@ -1339,9 +1380,13 @@ async function handleRenewalSubmit(client, store, options, context) {
       status: response.data?.status,
       serverId,
       task: response.data?.task,
+      paymentId: response.data?.paymentId,
       paymentAttemptId:
         response.data?.paymentAttemptId ||
         response.headers["x-warpmetal-payment-attempt"],
+      errorCode: response.data?.errorCode,
+      requestId: response.data?.requestId,
+      replacementAllowed: response.data?.replacementAllowed,
       walletPayment: {
         attemptId: walletPayment.attemptId,
         wallet: walletPayment.wallet,

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.6";
+export const AGENT_WALLET_VERSION = "0.2.7";
 const AGENT_WALLET_SPEC = `${AGENT_WALLET_PACKAGE}@${AGENT_WALLET_VERSION}`;
 const GAS_SPONSORSHIP_EXTENSION = "com.x402api.gas-sponsorship";
 const BASE_NETWORK = "eip155:8453";

package/src/state.js

@@ -13,7 +13,61 @@ const WALLET_PAYMENT_STATE_FIELDS = [
   "walletPayerAddress",
   "paymentArtifactExpiresAt",
   "paymentArtifactSavedAt",
+  "gatewayPaymentId",
+  "rejectedPaymentAttemptId",
+  "paymentRejectionErrorCode",
+  "paymentRejectionRequestId",
+  "paymentReplacementAllowed",
+  "paymentRejectedAt",
 ];
+const X402API_PAYMENT_ID =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SAFE_PROTOCOL_IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/;
+
+function validatedPaymentRejection({
+  paymentAttemptId,
+  errorCode,
+  requestId,
+  replacementAllowed,
+}) {
+  if (
+    typeof paymentAttemptId !== "string" ||
+    !SAFE_PROTOCOL_IDENTIFIER.test(paymentAttemptId)
+  ) {
+    throw new CliError("WarpMetal returned an invalid payment-attempt ID.", {
+      exitCode: 3,
+    });
+  }
+  for (const [label, value] of [
+    ["payment rejection error code", errorCode],
+    ["payment rejection request ID", requestId],
+  ]) {
+    if (
+      value !== undefined &&
+      (typeof value !== "string" || !SAFE_PROTOCOL_IDENTIFIER.test(value))
+    ) {
+      throw new CliError(`WarpMetal returned an invalid ${label}.`, {
+        exitCode: 3,
+      });
+    }
+  }
+  if (
+    replacementAllowed !== undefined &&
+    typeof replacementAllowed !== "boolean"
+  ) {
+    throw new CliError(
+      "WarpMetal returned an invalid payment replacement decision.",
+      { exitCode: 3 },
+    );
+  }
+  return {
+    rejectedPaymentAttemptId: paymentAttemptId,
+    paymentRejectionErrorCode: errorCode,
+    paymentRejectionRequestId: requestId,
+    paymentReplacementAllowed: replacementAllowed,
+    paymentRejectedAt: new Date().toISOString(),
+  };
+}
 
 function replaceChallenge(record, challenge) {
   const changed =
@@ -361,6 +415,94 @@ export class StateStore {
     });
   }
 
+  async saveOrderPaymentId(taskId, paymentId) {
+    if (!X402API_PAYMENT_ID.test(paymentId || "")) {
+      throw new CliError("WarpMetal returned an invalid x402api payment ID.", {
+        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,
+        });
+      }
+      order.gatewayPaymentId = paymentId;
+    });
+  }
+
+  async saveOrderPaymentRejection(taskId, rejection) {
+    const safe = validatedPaymentRejection(rejection);
+    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.paymentAttemptId &&
+        order.paymentAttemptId !== safe.rejectedPaymentAttemptId
+      ) {
+        throw new CliError(
+          "WarpMetal changed the payment-attempt ID for this authorization.",
+          { exitCode: 3 },
+        );
+      }
+      Object.assign(order, safe);
+    });
+  }
+
+  async saveRenewalPaymentId(serverId, paymentId) {
+    if (!X402API_PAYMENT_ID.test(paymentId || "")) {
+      throw new CliError("WarpMetal returned an invalid x402api payment ID.", {
+        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,
+        });
+      }
+      renewal.gatewayPaymentId = paymentId;
+    });
+  }
+
+  async saveRenewalPaymentRejection(serverId, rejection) {
+    const safe = validatedPaymentRejection(rejection);
+    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.paymentAttemptId &&
+        renewal.paymentAttemptId !== safe.rejectedPaymentAttemptId
+      ) {
+        throw new CliError(
+          "WarpMetal changed the payment-attempt ID for this renewal authorization.",
+          { exitCode: 3 },
+        );
+      }
+      Object.assign(renewal, safe);
+    });
+  }
+
   async saveAccessToken(serverId, accessToken, expiresAt) {
     await this.update((state) => {
       const server = state.servers[serverId] || { serverId };
@@ -488,11 +630,16 @@ export class StateStore {
         serverId: order.serverId,
         planId: order.planId,
         paymentAttemptId: order.paymentAttemptId,
+        paymentId: order.gatewayPaymentId,
         challengeHandle: order.challengeHandle,
         walletPaymentAttemptId: order.walletPaymentAttemptId,
         walletName: order.walletName,
         payerAddress: order.walletPayerAddress,
         paymentArtifactExpiresAt: order.paymentArtifactExpiresAt,
+        rejectedPaymentAttemptId: order.rejectedPaymentAttemptId,
+        paymentRejectionErrorCode: order.paymentRejectionErrorCode,
+        paymentRejectionRequestId: order.paymentRejectionRequestId,
+        paymentReplacementAllowed: order.paymentReplacementAllowed,
         credentialStored: Boolean(order.ownerToken),
       })),
       servers: Object.values(state.servers).map((server) => ({
@@ -523,8 +670,13 @@ export class StateStore {
         refillTargetAtomic: renewal.refillTargetAtomic,
         policy: renewal.policy,
         paymentAttemptId: renewal.paymentAttemptId,
+        paymentId: renewal.gatewayPaymentId,
         challengeHandle: renewal.challengeHandle,
         paymentArtifactExpiresAt: renewal.paymentArtifactExpiresAt,
+        rejectedPaymentAttemptId: renewal.rejectedPaymentAttemptId,
+        paymentRejectionErrorCode: renewal.paymentRejectionErrorCode,
+        paymentRejectionRequestId: renewal.paymentRejectionRequestId,
+        paymentReplacementAllowed: renewal.paymentReplacementAllowed,
       })),
     };
   }