warpmetal 0.3.1 → 0.4.0

package/README.md

@@ -4,8 +4,10 @@ The official command-line client and portable Agent Skill for WarpMetal.
 
 The CLI uses the public API at `https://api.warpmetal.com`, stores generated
 WarpMetal credentials in a user-private state file, and never reads or stores
-wallet private keys or SSH private-key contents. Version 0.3 adds guarded OS
-reload and Agent Runtime recovery to the fixed-size, isolated sandbox workflow.
+wallet private keys or SSH private-key contents. Version 0.4 adds a guarded
+x402api Agent Wallet handoff: WarpMetal writes the exact credential-free payment
+request, explains the next commands to an agent, validates the returned payment
+artifact, and submits it without absorbing wallet custody.
 
 ## Distribution
 
@@ -21,9 +23,16 @@ remains the stable executable API.
 
 ## Install
 
+WarpMetal supports Node.js 20 and 22. The separate x402api Agent Wallet
+requires Node.js 22; it is not a WarpMetal package dependency. Install the
+published wallet CLI with the exact version WarpMetal reports:
+
 ```sh
 npm install --global warpmetal
 warpmetal --help
+
+npm install --global @x402api/agent-wallet-cli@0.2.1
+x402api help --json
 ```
 
 Install the bundled skill for supported coding agents:
@@ -58,6 +67,44 @@ Pass `--json` for structured, secret-redacted output. Use
 `WARPMETAL_API_URL` for an alternate API origin and `WARPMETAL_HOME` for an
 alternate state directory.
 
+## Pay through the x402api Agent Wallet
+
+After preparing an order, request its live payment challenge:
+
+```sh
+warpmetal checkout challenge --task <taskId> --json
+```
+
+On HTTP 402 the CLI returns exact `paymentTerms`, the pinned
+`@x402api/agent-wallet-cli` package contract, and argv arrays under
+`paymentWorkflow`. It also writes an owner-only request envelope that contains
+the exact checkout URL and body but no WarpMetal credential. The published
+launch wallet accepts sponsored Base USDC and sponsored Solana USDC/USDT only;
+the returned terms identify compatible alternatives and confirm that the buyer
+does not need ETH or SOL. After inspecting the terms and approving payment,
+invoke the returned authorization argv with a dedicated wallet name:
+
+```sh
+x402api payment authorize \
+  --wallet <wallet-name> \
+  --request-envelope <path-returned-by-warpmetal> \
+  --artifact-out <path-returned-by-warpmetal> \
+  --json
+
+warpmetal checkout submit \
+  --task <taskId> \
+  --payment-artifact <owner-only-artifact-path> \
+  --wait \
+  --json
+```
+
+The x402api Agent Wallet is a separate, merchant-neutral executable. Install
+its matching `x402api-pay` skill with `x402api skill install --output <agent-skill-directory>/x402api-pay --json`.
+Do not use `x402api pay`, `payment submit`, or `payment reconcile` for WarpMetal:
+checkout requires the private WarpMetal owner token, so x402api authorizes and
+WarpMetal submits. WarpMetal keeps `--payment-signature-file` for another
+compatible external signer.
+
 ## Security boundary
 
 - Order and access tokens are never printed; they are written to
@@ -68,8 +115,9 @@ alternate state directory.
 - WarpMetal applies key-only OpenSSH configuration on initial provisioning and
   every OS reload. Password and keyboard-interactive login are disabled; never
   request, store, or expect a VPS login password.
-- The CLI accepts an externally produced x402 `PAYMENT-SIGNATURE` from a file.
-Wallet key management and signing remain outside this package.
+- The CLI writes x402api-compatible request envelopes and accepts validated
+  x402api payment artifacts or a compatible external `PAYMENT-SIGNATURE` file.
+  Wallet key management and signing remain outside this package.
 - Destructive or state-changing commands require explicit confirmations and
   generate idempotency keys by default.
 - Runtime bootstrap credentials remain memory-only. Signed supervisor bundles

package/package.json

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

package/skills/warpmetal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: warpmetal
-description: Safely purchase and manage WarpMetal VPS servers and Agent Runtime sandboxes with the official warpmetal CLI. Use when a shell-capable agent needs live VPS discovery, x402 ordering, provisioning, server management, optional runtime installation, fixed-size sandbox creation, persistent or temporary lifetime, per-agent SSH access, sandbox connection, access revocation, or workspace deletion.
+description: Safely purchase and manage WarpMetal VPS servers and Agent Runtime sandboxes with the official warpmetal CLI, including x402api Agent Wallet payment handoff. Use when a shell-capable agent needs live VPS discovery, x402 payment authorization, ordering, provisioning, server management, optional runtime installation, fixed-size sandbox creation, persistent or temporary lifetime, per-agent SSH access, sandbox connection, access revocation, or workspace deletion.
 ---
 
 # WarpMetal
@@ -19,12 +19,15 @@ with ad hoc HTTP commands.
    authorizing payment, using an SSH identity, or changing a server.
 5. Read [references/cli-reference.md](references/cli-reference.md) when choosing
    a command or interpreting an exit code.
-6. Read [references/runtime.md](references/runtime.md) before requesting,
+6. Read [references/payments.md](references/payments.md) before creating or
+   funding a wallet, authorizing payment, or resolving an ambiguous attempt.
+7. Read [references/runtime.md](references/runtime.md) before requesting,
    installing, accessing, expiring, or deleting Agent Runtime sandboxes.
 
-Never read, print, summarize, upload, or commit the WarpMetal state file. Never
-read an SSH private-key file. Pass its path only to a command designed to use
-it. Never request or handle a wallet seed phrase or private key.
+Never read, print, summarize, upload, or commit the WarpMetal state file,
+x402api keystore, password file, payment request envelope, or payment artifact.
+Never read an SSH private-key file. Pass private paths only to commands designed
+to use them. Never request or handle a wallet seed phrase or private key.
 
 WarpMetal provisions and reloads servers with key-only OpenSSH access. Password
 and keyboard-interactive login are disabled, including for root. Never request,
@@ -64,26 +67,44 @@ open the state file to retrieve the credential.
 
 ## Authorize payment
 
-Run `warpmetal checkout challenge --task <taskId> --json` to obtain the live
-x402 terms. Before any wallet creation, funding, or signature, show the user
-the exact amount, asset, network, recipient, and expiration derived from the
-live challenge and obtain explicit approval.
-
-Use a compatible external wallet signer to produce one `PAYMENT-SIGNATURE`
-header value in a file. Do not pass wallet secrets to WarpMetal or the CLI.
-After approval, submit it with:
+Run `warpmetal checkout challenge --task <taskId> --json`. The CLI validates
+the live x402 terms, writes an owner-only credential-free request envelope, and
+returns `paymentTerms` plus exact `paymentWorkflow.authorize.argv` and
+`paymentWorkflow.submit.argv` arrays. Do not reconstruct those commands or
+open either file.
+
+Show the user the exact amount, asset, network, recipient, profile, and maximum
+authorization lifetime from `paymentTerms`; obtain explicit approval before
+signing or submission. Follow [references/payments.md](references/payments.md)
+to install the exact `paymentWorkflow.signerPackage.spec`, verify the V1
+machine contract, install its matching `x402api-pay` skill, and select or fund
+a dedicated network-specific wallet. Require `agentWalletSupported: true`,
+`sponsoredNetworkFee: true`, and `buyerNativeFeeRequired: false` on the chosen
+live term. Never fall back to a historical buyer-funded or TRON profile.
+
+After approval, invoke the returned authorize argv once. The separate
+`x402api` executable owns the wallet, validates the envelope, and writes the
+payment artifact. Then invoke the returned submit argv, equivalent to:
 
 ```sh
 warpmetal checkout submit \
   --task <taskId> \
-  --payment-signature-file <path> \
+  --payment-artifact <owner-only-artifact-path> \
   --wait \
   --json
 ```
 
-If the command reports a rejected signature, inspect the replacement live
-challenge and request new approval where its terms changed. If it reports
-`manual_review`, stop immediately and never create another payment.
+Do not use `x402api pay`, `x402api payment submit`, or `x402api payment
+reconcile` for this checkout. Those commands submit credential-free requests,
+but WarpMetal must add its private owner token locally.
+
+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 request approval again when terms changed. On
+`manual_review` or an ambiguous attempt, stop and never create another payment.
 
 ## Provision and manage
 

package/skills/warpmetal/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "WarpMetal VPS"
-  short_description: "Manage WarpMetal VPS and agent sandboxes safely"
-  default_prompt: "Use $warpmetal to provision a VPS and manage isolated agent sandboxes safely."
+  short_description: "Purchase and manage WarpMetal compute safely"
+  default_prompt: "Use $warpmetal to purchase a VPS through the guarded x402 wallet handoff and manage isolated agent sandboxes safely."

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

@@ -33,11 +33,14 @@ warpmetal order prepare \
   [--idempotency-key <key>] \
   --json
 
-warpmetal checkout challenge --task <taskId> --json
+warpmetal checkout challenge \
+  --task <taskId> \
+  [--request-envelope-out <path>] \
+  --json
 
 warpmetal checkout submit \
   --task <taskId> \
-  --payment-signature-file <path> \
+  (--payment-artifact <path> | --payment-signature-file <path>) \
   [--wait] [--timeout-seconds <n>] \
   --json
 
@@ -47,8 +50,29 @@ warpmetal order status \
   --json
 ```
 
-The payment signature file must contain one HTTP header value. The CLI does
-not create or store wallet keys and does not sign x402 challenges.
+On HTTP 402, `checkout challenge` validates and displays exact payment terms,
+writes a credential-free x402api V1 request envelope with owner-only
+permissions, and returns the exact pinned wallet package, V1 contract probe,
+matching wallet-skill install, authorization, and WarpMetal submission argv
+arrays. The default envelope and suggested artifact paths live under the
+private WarpMetal state directory. An explicit output path must not already
+contain different content.
+
+The current integration targets `@x402api/agent-wallet-cli@0.2.1`. A compatible
+live term is marked `agentWalletSupported: true` and must use the sponsored
+Base USDC or Solana USDC/USDT launch profile with buyer native fees disabled.
+WarpMetal rejects a challenge with no compatible sponsored term. Because the
+checkout is authenticated, do not substitute `x402api pay`, `payment submit`,
+or `payment reconcile` for the returned WarpMetal submission command.
+
+`--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,
+signature, sponsorship expiry, file type, and permissions before submission.
+It reports only safe attempt metadata. The compatibility
+`--payment-signature-file` input must contain one HTTP header value. WarpMetal
+never creates, imports, reads, or stores wallet keys and does not sign x402
+challenges itself. See [payments.md](payments.md).
 
 ## Server management
 

package/skills/warpmetal/references/payments.md

@@ -0,0 +1,110 @@
+# WarpMetal payment workflow
+
+## Contents
+
+- Trust boundary
+- Wallet setup and funding
+- Exact purchase workflow
+- Retries and recovery
+
+## Trust boundary
+
+WarpMetal is the merchant tool. It owns product selection, the private owner
+credential, exact checkout bytes, submission, provisioning, and fulfillment.
+The separate x402api Agent Wallet owns encrypted network keys, balance checks,
+payment authorization, and durable payment attempts. Never merge their state
+files or pass a WarpMetal credential to `x402api`.
+
+WarpMetal runs on Node.js 20 or 22. The x402api Agent Wallet currently requires
+Node.js 22. Use the exact published package reported by
+`paymentWorkflow.signerPackage.spec`; the current contract is
+`@x402api/agent-wallet-cli@0.2.1`. Do not add it as a WarpMetal dependency,
+install executable wallet code from an unpinned repository URL, or substitute
+a similarly named package.
+
+The wallet package ships its own version-matched `x402api-pay` skill. Install
+that skill into the directory used by Codex, Claude Code, or another portable
+Agent Skills runtime with the returned `paymentWorkflow.walletSkill.install.argv`.
+The command refuses to overwrite an existing directory; do not delete an old
+skill automatically.
+
+## Wallet setup and funding
+
+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.
+2. Ensure an operator configured `X402API_WALLET_PASSWORD_FILE` as an owner-only
+   file, or is supervising `--password-stdin`. Never read either value.
+3. Use `x402api wallet list --json` and reuse a dedicated persistent wallet for
+   the exact challenge network.
+4. Create a wallet only with explicit approval. Keep Base and Solana wallets
+   separate; never import the owner's primary seed or key. TRON wallet
+   management exists, but the published launch payer cannot authorize TRON.
+5. Use `x402api wallet balance --wallet <name> --json`. If funding is short,
+   show the public address, exact network, token, and atomic deficit. The owner
+   funds the token address from a wallet they control. Sponsored launch
+   payments never ask the buyer to fund ETH or SOL.
+
+Treat the dedicated wallet's funded balance as spend authority available to
+the agent, bounded by any wallet-local maximum payment policy. WarpMetal still
+requires explicit approval immediately before its payment authorization and
+submission workflow.
+
+## Exact purchase workflow
+
+```sh
+warpmetal checkout challenge --task <taskId> --json
+```
+
+Read only the returned safe JSON. Confirm `paymentTerms`, then use the exact
+argv arrays returned under `paymentWorkflow`:
+
+```text
+paymentWorkflow.authorize.argv
+  x402api payment authorize --wallet <wallet-name>
+    --request-envelope <owner-only-request-path>
+    --artifact-out <owner-only-artifact-path> --json
+
+paymentWorkflow.submit.argv
+  warpmetal checkout submit --task <taskId>
+    --payment-artifact <owner-only-artifact-path> --wait --json
+```
+
+Replace only `<wallet-name>` after selecting the wallet for the advertised
+network. Do not parse, rewrite, copy, or display the request envelope or payment
+artifact. The envelope excludes the WarpMetal owner token; the artifact holds
+the complete payment signature and remains owner-only.
+
+Choose only a term marked `agentWalletSupported: true`,
+`sponsoredNetworkFee: true`, and `buyerNativeFeeRequired: false`. The supported
+launch profiles are sponsored Base USDC and sponsored Solana USDC/USDT, bound
+by the strict `com.x402api.gas-sponsorship` extension. Stop on an expired gas
+reservation or any buyer-funded, unsupported, or unbound alternative.
+
+Do not replace the two-stage workflow with `x402api pay`, `payment submit`, or
+`payment reconcile`. Those wallet commands can submit an exact credential-free
+endpoint; WarpMetal checkout requires a private owner token that must never
+enter the wallet envelope. Use x402api only for authorization and WarpMetal for
+submission and merchant reconciliation.
+
+WarpMetal rejects an artifact whose request digest, selected payment
+requirement, resource, extension set, buyer payment identifier, signature,
+expiry, sponsorship lifetime, file type, or permissions do not match the saved
+challenge. Keep `--payment-signature-file` only as a compatibility path for
+another external signer.
+
+## Retries and recovery
+
+- `payment_pending` or `payment_finalizing`: keep the same checkout bytes and
+  artifact. `--wait` 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 approval allow it.
+- `manual_review`: payment or fulfillment may be final. Stop all payment and
+  mutation retries.
+- Expired or corrupt 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/safety.md

@@ -34,8 +34,15 @@
 - Give each agent a distinct sandbox-specific SSH key and grant. Never reuse
   the owner host key or one agent key across multiple sandboxes.
 - Never request, read, transmit, or store a wallet seed phrase or private key.
-- Never put a token, payment signature, private key, or state-file content in
-  a prompt, URL, log, screenshot, source file, or shell argument.
+- Install only the exact `@x402api/agent-wallet-cli` version and matching
+  bundled `x402api-pay` skill reported by WarpMetal. Never substitute an
+  unpinned repository checkout or similarly named wallet package.
+- Never read or display an x402api password file, encrypted keystore, request
+  envelope, payment artifact, or complete payment signature. Pass only their
+  paths to the documented commands.
+- Never put a token, payment signature, payment artifact, wallet password,
+  private key, or state-file content in a prompt, URL, log, screenshot, source
+  file, or shell argument.
 
 ## Required confirmations
 
@@ -71,9 +78,13 @@ Confirm the plan, hostname, OS, and public key before preparing it.
 
 - Reuse the same idempotency key only for the exact same logical request.
 - For `payment_pending`, retry the exact checkout body and the exact same
-  payment signature. Do not create a replacement payment.
+  payment artifact. Do not create a replacement payment.
 - A signed HTTP 402 rejects that signature. Use the new live challenge for one
-  replacement authorization.
+  replacement authorization after checking the new terms and approval.
+- On timeout or restart after wallet authorization, reuse the saved x402api
+  attempt and artifact through WarpMetal. Never authorize again merely because
+  submission or fulfillment is uncertain, and never send the private owner
+  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 HTTP 202 as accepted or pending, never as proof of success. Poll the

package/src/cli.js

@@ -14,6 +14,13 @@ import { connectionProfile, writeConnectionProfile } from "./connection.js";
 import { CliError, toErrorMessage } from "./errors.js";
 import { installSkill } from "./install-skill.js";
 import { installRuntime } from "./installer.js";
+import {
+  createPaymentRequestEnvelope,
+  defaultPaymentPaths,
+  paymentWorkflow,
+  readPaymentArtifact,
+  writePaymentRequestEnvelope,
+} from "./payment.js";
 import {
   readSandboxFile,
   requireTemporaryConfirmation,
@@ -66,8 +73,9 @@ Usage:
     --ssh-public-key-file <path> [--runtime-file <path>] [--confirm TEMPORARY]
     [--email <address>] [--idempotency-key <key>]
   warpmetal order status --task <taskId> [--wait] [--timeout-seconds <n>]
-  warpmetal checkout challenge --task <taskId>
-  warpmetal checkout submit --task <taskId> --payment-signature-file <path>
+  warpmetal checkout challenge --task <taskId> [--request-envelope-out <path>]
+  warpmetal checkout submit --task <taskId>
+    (--payment-artifact <path> | --payment-signature-file <path>)
     [--wait] [--timeout-seconds <n>]
   warpmetal server login --server <serverId> --identity <private-key-path>
   warpmetal server get --server <serverId>
@@ -112,6 +120,16 @@ function writeLine(stream, value = "") {
   stream.write(`${value}\n`);
 }
 
+function shellCommand(argv) {
+  return argv
+    .map((value) =>
+      /^[A-Za-z0-9_./:=+@-]+$/.test(value)
+        ? value
+        : `'${value.replaceAll("'", `'\\''`)}'`,
+    )
+    .join(" ");
+}
+
 function emit(stream, value, json, human) {
   if (json) writeLine(stream, JSON.stringify(value, null, 2));
   else writeLine(stream, human);
@@ -344,6 +362,46 @@ function challengeResult(taskId, checkoutBody, response) {
   };
 }
 
+async function attachPaymentWorkflow(
+  client,
+  store,
+  taskId,
+  order,
+  safe,
+  requestedEnvelopePath,
+) {
+  if (!safe.paymentRequired) return safe;
+  const request = createPaymentRequestEnvelope({
+    baseUrl: client.baseUrl,
+    checkoutPath: order.checkoutPath,
+    checkoutBody: order.checkoutBody,
+    paymentRequired: safe.paymentRequired,
+    merchantReference: taskId,
+  });
+  const defaults = defaultPaymentPaths(
+    store.directory,
+    taskId,
+    request.challengeDigest,
+  );
+  const requestEnvelopePath = await writePaymentRequestEnvelope(
+    requestedEnvelopePath || defaults.requestEnvelopePath,
+    request.envelope,
+  );
+  const workflow = paymentWorkflow({
+    taskId,
+    requestEnvelopePath,
+    paymentArtifactPath: defaults.paymentArtifactPath,
+  });
+  Object.assign(safe, {
+    paymentTerms: request.terms,
+    paymentRequestDigest: request.requestDigest,
+    paymentChallengeDigest: request.challengeDigest,
+    paymentWorkflow: workflow,
+  });
+  await store.savePaymentChallenge(taskId, safe);
+  return safe;
+}
+
 async function handleHealth(client, { json, stdout }) {
   const result = await client.health();
   emit(
@@ -470,16 +528,23 @@ async function handleCheckoutChallenge(client, store, options, context) {
     bodyText: order.checkoutBody,
     token,
   });
-  const safe = challengeResult(taskId, order.checkoutBody, response);
-  if (safe.paymentRequired) {
-    await store.savePaymentChallenge(taskId, safe);
-  }
+  const safe = await attachPaymentWorkflow(
+    client,
+    store,
+    taskId,
+    order,
+    challengeResult(taskId, order.checkoutBody, response),
+    stringOption(options, "request-envelope-out"),
+  );
+  const paymentInstructions = safe.paymentWorkflow
+    ? `\nWallet package: ${safe.paymentWorkflow.signerPackage.spec} (Node ${safe.paymentWorkflow.signerNodeRequirement})\nInstall: ${shellCommand(safe.paymentWorkflow.signerPackage.install.argv)}\nVerify: ${shellCommand(safe.paymentWorkflow.signerContract.probe.argv)}\nRequest envelope: ${safe.paymentWorkflow.requestEnvelopePath}\nAuthorize: ${shellCommand(safe.paymentWorkflow.authorize.argv)}\nSubmit with WarpMetal: ${shellCommand(safe.paymentWorkflow.submit.argv)}`
+    : "";
   emit(
     context.stdout,
     safe,
     context.json,
     response.status === 402
-      ? `Payment authorization required for ${taskId}.\nPAYMENT-REQUIRED: ${safe.paymentRequired}`
+      ? `Payment authorization required for ${taskId}.${paymentInstructions}`
       : `Checkout status for ${taskId}: ${safe.status}`,
   );
   return response.status === 409 ? 6 : response.status === 402 ? 7 : 0;
@@ -487,19 +552,45 @@ async function handleCheckoutChallenge(client, store, options, context) {
 
 async function handleCheckoutSubmit(client, store, options, context) {
   const taskId = stringOption(options, "task", { required: true });
-  const signatureFile = stringOption(options, "payment-signature-file", {
-    required: true,
-  });
-  const paymentSignature = await readHeaderValueFile(
-    signatureFile,
-    "The payment signature file",
-  );
+  const signatureFile = stringOption(options, "payment-signature-file");
+  const artifactFile = stringOption(options, "payment-artifact");
+  if (Boolean(signatureFile) === Boolean(artifactFile)) {
+    throw new CliError(
+      "Use exactly one of --payment-artifact or --payment-signature-file.",
+      { exitCode: 2 },
+    );
+  }
   const order = await store.order(taskId);
   if (!order?.checkoutPath || !order?.checkoutBody) {
     throw new CliError(`No exact checkout state exists for ${taskId}.`, {
       exitCode: 2,
     });
   }
+  let walletPayment;
+  let paymentSignature;
+  if (artifactFile) {
+    if (!order.paymentRequired) {
+      throw new CliError(
+        `No saved PAYMENT-REQUIRED challenge exists for ${taskId}. Run warpmetal checkout challenge first.`,
+        { exitCode: 2 },
+      );
+    }
+    const expected = createPaymentRequestEnvelope({
+      baseUrl: client.baseUrl,
+      checkoutPath: order.checkoutPath,
+      checkoutBody: order.checkoutBody,
+      paymentRequired: order.paymentRequired,
+      merchantReference: taskId,
+    });
+    walletPayment = await readPaymentArtifact(artifactFile, expected);
+    paymentSignature = walletPayment.paymentSignature;
+    await store.saveWalletPaymentAttempt(taskId, walletPayment);
+  } else {
+    paymentSignature = await readHeaderValueFile(
+      signatureFile,
+      "The payment signature file",
+    );
+  }
   const token = await requireTaskToken(store, taskId, options, context.env);
   const wait = booleanOption(options, "wait");
   const deadline = timeoutDeadline(
@@ -512,8 +603,13 @@ async function handleCheckoutSubmit(client, store, options, context) {
       token,
       paymentSignature,
     });
-    const safe = challengeResult(taskId, order.checkoutBody, response);
-    if (safe.paymentRequired) await store.savePaymentChallenge(taskId, safe);
+    const safe = await attachPaymentWorkflow(
+      client,
+      store,
+      taskId,
+      order,
+      challengeResult(taskId, order.checkoutBody, response),
+    );
     const retryable =
       response.status === 202 &&
       ["payment_pending", "payment_finalizing"].includes(response.data?.status);
@@ -527,6 +623,19 @@ async function handleCheckoutSubmit(client, store, options, context) {
       ...safe,
       task: response.data?.task,
       message: response.data?.message,
+      ...(walletPayment
+        ? {
+            walletPayment: {
+              attemptId: walletPayment.attemptId,
+              requestDigest: walletPayment.requestDigest,
+              buyerPaymentIdentifier: walletPayment.buyerPaymentIdentifier,
+              wallet: walletPayment.wallet,
+              payerAddress: walletPayment.payerAddress,
+              artifactPath: walletPayment.path,
+              expiresAt: walletPayment.expiresAt,
+            },
+          }
+        : {}),
     };
     emit(
       context.stdout,
@@ -662,12 +771,7 @@ async function handleServerReload(client, store, options, context) {
     options,
     "acknowledge-agent-runtime-reset",
   );
-  const token = await requireReloadToken(
-    store,
-    serverId,
-    options,
-    context.env,
-  );
+  const token = await requireReloadToken(store, serverId, options, context.env);
   const server = (await client.getServer(serverId, token)).data?.task;
   if (server?.agentRuntime && !acknowledgeRuntimeReset) {
     throw new CliError(
@@ -717,7 +821,7 @@ async function handleServerReload(client, store, options, context) {
         ? " Verify and refresh the owner SSH host key, reinstall Agent Runtime, then refresh every sandbox connection profile."
         : operation?.state === "succeeded"
           ? " Verify and refresh the owner SSH host key before reconnecting."
-        : ""),
+          : ""),
   );
   if (operation?.state === "manual_review") return 6;
   if (operation?.state === "failed") return 5;
@@ -1399,13 +1503,19 @@ async function dispatch(positionals, options, passthrough, context) {
       ]);
       return handleTaskStatus(client, store, options, context);
     case "checkout challenge":
-      rejectUnknownOptions(options, [...COMMON_OPTIONS, "task", "token-file"]);
+      rejectUnknownOptions(options, [
+        ...COMMON_OPTIONS,
+        "task",
+        "token-file",
+        "request-envelope-out",
+      ]);
       return handleCheckoutChallenge(client, store, options, context);
     case "checkout submit":
       rejectUnknownOptions(options, [
         ...COMMON_OPTIONS,
         "task",
         "token-file",
+        "payment-artifact",
         "payment-signature-file",
         "wait",
         "timeout-seconds",