warpmetal 0.7.6 → 0.7.7

package/README.md

@@ -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.6 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.6",
+  "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.6` 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/payments.md

@@ -196,10 +196,12 @@ current `termEndsAt` generation are different.
 - 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. Preserve its
-  `paymentId`, then 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
@@ -207,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

@@ -117,9 +117,11 @@ 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.
-- A signed HTTP 402 rejects that signature. Preserve its `paymentId`, request a
-  new live challenge, and create one replacement authorization after checking the new terms against the current
-  interactive or autonomous payment authority.
+- 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`,
@@ -131,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

@@ -385,6 +385,8 @@ function challengeResult(
   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 (requireChallenge && response.status === 402 && !paymentRequired) {
@@ -396,7 +398,7 @@ function challengeResult(
     );
   }
   return {
-    status: response.data?.status,
+    status,
     taskId,
     paymentAttemptId:
       response.data?.paymentAttemptId ||
@@ -404,6 +406,13 @@ function challengeResult(
     paymentRequired,
     challengeHandle,
     checkoutBodySha256: createHash("sha256").update(checkoutBody).digest("hex"),
+    ...(rejected
+      ? {
+          errorCode: response.data?.errorCode,
+          requestId: response.data?.requestId,
+          replacementAllowed: response.data?.replacementAllowed,
+        }
+      : {}),
   };
 }
 
@@ -753,6 +762,14 @@ async function handleCheckoutSubmit(client, store, options, context) {
         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);
@@ -1341,6 +1358,16 @@ async function handleRenewalSubmit(client, store, options, context) {
     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);
@@ -1357,6 +1384,9 @@ async function handleRenewalSubmit(client, store, options, context) {
       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/state.js

@@ -14,9 +14,60 @@ const WALLET_PAYMENT_STATE_FIELDS = [
   "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 =
@@ -386,6 +437,28 @@ export class StateStore {
     });
   }
 
+  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.", {
@@ -408,6 +481,28 @@ export class StateStore {
     });
   }
 
+  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 };
@@ -541,6 +636,10 @@ export class StateStore {
         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) => ({
@@ -574,6 +673,10 @@ export class StateStore {
         paymentId: renewal.gatewayPaymentId,
         challengeHandle: renewal.challengeHandle,
         paymentArtifactExpiresAt: renewal.paymentArtifactExpiresAt,
+        rejectedPaymentAttemptId: renewal.rejectedPaymentAttemptId,
+        paymentRejectionErrorCode: renewal.paymentRejectionErrorCode,
+        paymentRejectionRequestId: renewal.paymentRejectionRequestId,
+        paymentReplacementAllowed: renewal.paymentReplacementAllowed,
       })),
     };
   }