@itpay/cli 2.0.3 → 2.0.5

package/dist/src/render/output.js

@@ -3,9 +3,6 @@ export function formatMoney(amountMinor, currency) {
     const major = (amountMinor / 100).toFixed(2);
     return `${major} ${currency}`;
 }
-export function renderReady(payload) {
-    return `backend ${payload.status} (version ${payload.version})`;
-}
 export function renderOrder(order) {
     const lines = [];
     lines.push(`order ${order.order_id}`);
@@ -36,6 +33,8 @@ export function renderRefund(refund) {
         `  status:  ${refund.status}`,
         `  amount:  ${formatMoney(refund.amount_minor, refund.currency)}`,
         refund.reason ? `  reason:  ${refund.reason}` : "",
+        `  access:  ${refund.access_locked ? "locked" : "available"}`,
+        `  policy:  ${refund.decision_mode === "automatic" ? "automatic" : "admin review"}`,
     ]
         .filter((line) => line.length > 0)
         .join("\n");

package/dist/src/state/cart_session.js

@@ -7,6 +7,7 @@ import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
 export class CartSession {
     state;
+    loadFailed = false;
     constructor(currency) {
         this.state = { currency, items: [] };
     }
@@ -23,8 +24,6 @@ export class CartSession {
                         }
                     });
                 }
-                if (persisted.agentDeviceID)
-                    session.state.agentDeviceID = persisted.agentDeviceID;
                 if (persisted.lastCartID)
                     session.state.lastCartID = persisted.lastCartID;
                 if (persisted.lastCartItemID)
@@ -40,6 +39,7 @@ export class CartSession {
             }
             catch {
                 session.state.items = [];
+                session.loadFailed = true;
             }
         }
         return session;
@@ -48,7 +48,6 @@ export class CartSession {
         const toSave = {
             currency: this.state.currency,
             items: this.state.items.map((item) => ({ ...item })),
-            ...(this.state.agentDeviceID ? { agentDeviceID: this.state.agentDeviceID } : {}),
             ...(this.state.lastCartID ? { lastCartID: this.state.lastCartID } : {}),
             ...(this.state.lastCartItemID ? { lastCartItemID: this.state.lastCartItemID } : {}),
             ...(this.state.lastServiceExecutionID ? { lastServiceExecutionID: this.state.lastServiceExecutionID } : {}),
@@ -84,11 +83,7 @@ export class CartSession {
         }
     }
     clear() {
-        this.state = {
-            currency: this.state.currency,
-            items: [],
-            ...(this.state.agentDeviceID ? { agentDeviceID: this.state.agentDeviceID } : {}),
-        };
+        this.state = { currency: this.state.currency, items: [] };
     }
     show() {
         return JSON.parse(JSON.stringify(this.state));
@@ -107,7 +102,8 @@ export class CartSession {
     }
     rememberCheckout(input) {
         this.state.items = [];
-        this.state.lastCartID = input.cartID;
+        delete this.state.lastCartID;
+        delete this.state.lastCartItemID;
         this.state.lastCheckoutID = input.checkoutID;
         this.state.lastDisplayToken = input.displayToken;
         this.state.lastCheckoutURL = input.checkoutURL;
@@ -117,18 +113,15 @@ export class CartSession {
     rememberServerCart(input) {
         this.state.items = [];
         this.state.lastCartID = input.cartID;
+        delete this.state.lastCartItemID;
+        delete this.state.lastServiceExecutionID;
+        delete this.state.lastCheckoutID;
+        delete this.state.lastDisplayToken;
+        delete this.state.lastCheckoutURL;
         if (input.cartItemID)
             this.state.lastCartItemID = input.cartItemID;
         if (input.serviceExecutionID)
             this.state.lastServiceExecutionID = input.serviceExecutionID;
-        if (input.agentDeviceID)
-            this.state.agentDeviceID = input.agentDeviceID;
-    }
-    ensureAgentDeviceID(fallback) {
-        if (!this.state.agentDeviceID) {
-            this.state.agentDeviceID = fallback;
-        }
-        return this.state.agentDeviceID;
     }
     get lastCartID() {
         return this.state.lastCartID;
@@ -148,4 +141,7 @@ export class CartSession {
     get currency() {
         return this.state.currency;
     }
+    get stateLoadFailed() {
+        return this.loadFailed;
+    }
 }

package/dist/src/state/client_context.js

@@ -56,10 +56,12 @@ export function hasDedicatedRenderer(host) {
 }
 export function defaultHostForAgentType(agentType) {
     const normalized = agentType?.trim().toLowerCase() ?? "";
-    if (normalized.startsWith("codex"))
+    if (normalized === "codex-desktop")
         return "codex";
-    if (normalized.startsWith("claude-code"))
+    if (normalized === "claude-code-desktop")
         return "claude-code";
+    if (normalized === "workbuddy")
+        return "plain-chat";
     return "terminal";
 }
 export function validateContext(host, target) {

package/dist/src/state/config.js

@@ -9,8 +9,8 @@ import { BackendClient } from "../client/backend.js";
 import { DeviceAuthority } from "./device_authority.js";
 import { OperationJournal } from "./operation_journal.js";
 export const DEFAULT_BASE_URL = "https://app.itpay.ai";
-export const CLI_VERSION = "2.0.3";
-export const API_CONTRACT_REVISION = "sha256:d2870f3ee6fa4ee8a0a3ee75ae272a1a476935aae824123cf46607d62168f1f2";
+export const CLI_VERSION = "2.0.5";
+export const API_CONTRACT_REVISION = "sha256:3e6b650c62fa54eb8b9ea6b86857cfef594313871e2bf1b9f3ca4ff3cc6e1612";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";
@@ -25,7 +25,6 @@ export function cartSessionPath(env = process.env) {
 export function loadConfig(env = process.env) {
     const baseURL = env.ITPAY_BACKEND_URL || DEFAULT_BASE_URL;
     const bearerToken = env.ITPAY_BEARER_TOKEN || undefined;
-    const agentDeviceID = env.ITPAY_AGENT_DEVICE_ID || "";
     const agentType = env.ITPAY_AGENT_TYPE || agentTypeFromArgv(process.argv);
     const checkoutCurrency = env.ITPAY_CURRENCY || "CNY";
     const idempotencyKey = env.ITPAY_IDEMPOTENCY_KEY || `cli_${shortRandom()}`;
@@ -33,7 +32,6 @@ export function loadConfig(env = process.env) {
     const ideImageDirOverride = env.ITPAY_IDE_IMAGE_DIR_OVERRIDE;
     return {
         baseURL,
-        agentDeviceID,
         ...(agentType ? { agentType } : {}),
         checkoutCurrency,
         idempotencyKey,

package/dist/src/state/device_authority.js

@@ -2,7 +2,7 @@ import { createHash, createPrivateKey, generateKeyPairSync, randomUUID, sign, }
 import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
-const PROTECTED_PATHS = ["/v1/carts", "/v1/service-executions", "/v1/agent-instances"];
+const PROTECTED_PATHS = ["/v1/carts", "/v1/service-executions", "/v1/agent-instances", "/v1/orders", "/v1/refunds"];
 export class DeviceAuthority {
     baseURL;
     requestedAgentType;

package/docs/agent/buyer/cart-checkout.json

@@ -2,105 +2,49 @@
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
   "topic": "cart-checkout",
-  "title": "V3 Cart-First Checkout",
-  "purpose": "Teach the agent to use the current V3 canonical server cart flow without treating local CLI state as business truth.",
+  "title": "Canonical Cart And Checkout Routing",
+  "purpose": "Use the canonical server Cart and route service-backed lines through Service Execution without hardcoded service logic.",
   "when_to_use": [
-    "The user already chose a catalog item, variant, and offer.",
-    "The agent needs to add a catalog item to a server cart before checkout.",
-    "The agent wants to understand how service-backed cart items create or resume Service Execution."
+    "A catalog item or variant is ready to add.",
+    "An interrupted Cart or Checkout needs recovery."
   ],
-  "required_state": {
-    "needs": [
-      "catalog_item_id",
-      "catalog_variant_id",
-      "offer_id"
-    ],
-    "optional": [
-      "quantity",
-      "contact email",
-      "contact phone",
-      "agent_device_id for service-backed items"
-    ],
-    "must_not_need": [
-      "catalog search support from this CLI"
-    ]
-  },
   "commands": [
     {
-      "intent": "add the first line to the canonical server cart",
-      "command": "itpay cart add --item <catalog_item_id> --variant <catalog_variant_id> --offer <offer_id> --quantity 1 --host <client> --json",
-      "success_signal": "JSON includes cart_id and cart_item_id; service-backed lines also include service_execution_id and top-level next_actions"
+      "intent": "add one published line",
+      "command": "itpay --agent-type <agent_type> cart add --item <catalog_item_id> --variant <catalog_variant_id> --offer <offer_id> --quantity 1 --json",
+      "success_signal": "result identifies the canonical cart line and next contains one executable recovery or service command"
     },
     {
-      "intent": "recover the next step for the current cart",
-      "command": "itpay cart next --json",
-      "success_signal": "JSON includes next_actions derived from the canonical server cart and Service Execution read model"
+      "intent": "read the canonical Cart route",
+      "command": "itpay --agent-type <agent_type> cart next --json",
+      "success_signal": "service-backed lines route to services next; ordinary lines route to buy"
     },
     {
-      "intent": "inspect the current canonical server cart before checkout",
-      "command": "itpay cart show",
-      "success_signal": "server cart lines, checkout readiness, and service refs are printed"
+      "intent": "create an ordinary Checkout",
+      "command": "itpay --agent-type <agent_type> buy --cart <cart_id> --json",
+      "success_signal": "status is human_checkout_required and handoff contains only fields usable by the current Host"
     },
     {
-      "intent": "soft-remove one active line from the canonical server cart",
-      "command": "itpay cart remove --line <cart_item_id>",
-      "success_signal": "the line is removed from the server cart; quote-locked or checkout-bound lines return a conflict"
-    },
-    {
-      "intent": "abandon the canonical server cart",
-      "command": "itpay cart clear",
-      "success_signal": "the server cart is abandoned, active lines are soft-removed, and local handles are cleared"
-    },
-    {
-      "intent": "create checkout from a server cart that is ready for checkout",
-      "command": "itpay buy --cart <cart_id> --host <client> [--contact-email <email>] [--contact-phone <phone>]",
-      "success_signal": "the CLI either renders checkout_qr or emits an interaction request for missing contact data"
-    },
-    {
-      "intent": "create quote lock and checkout for a service-backed cart item",
-      "command": "itpay services checkout <service_execution_id> --capability <paid_capability_id> [--email <email>] --json",
-      "success_signal": "the quote lock is bound to the original server cart item when present; JSON includes checkout_id and display_token"
-    },
-    {
-      "intent": "read the next Service Execution action",
-      "command": "itpay services next <service_execution_id> --json",
-      "success_signal": "JSON includes next_actions such as invoke capability, select result item, or checkout"
+      "intent": "create or resume a service Checkout",
+      "command": "itpay --agent-type <agent_type> services checkout <service_execution_id> --capability <capability_id> [--input key=value] [--email <email>] --json",
+      "success_signal": "one Checkout handoff is returned; rerun with --resume after output or token loss"
     }
   ],
   "agent_rules": [
-    "The current V3 CLI uses server cart as the business source of truth. Local ~/.itpay-v3/cart.json only caches last ids and explicit local drafts.",
-    "Prefer top-level next_actions and itpay next/cart next/services next over hardcoded service-specific flows.",
-    "Use cart add/show/remove/clear before checkout. Remove and clear are server-side soft state changes, not hard deletes.",
-    "For service-backed items, use service_execution_id from cart add/show as the canonical handle for services invoke/action/checkout.",
-    "Do not call buy --cart on a service-backed cart item until the required service action and quote lock are complete.",
-    "Do not remove quote-locked or checkout-bound cart lines. Continue checkout/payment or use refund/cancel owner flow after payment.",
-    "If required contact data is missing, prefer --require-contact so the CLI can emit a structured interaction request.",
-    "Do not invent buyer email or phone values; let the human provide them when required.",
-    "Only request --email when the selected capability declares delivery_email_required. Tell the buyer it sends the protected result claim link.",
-    "The happy-path buy flow creates cart and checkout, then renders checkout_qr. It should not create a payment intent first."
+    "The Backend Cart is business truth; ~/.itpay-v3/cart.json only stores local recovery handles and explicit drafts.",
+    "Run the exact next.command returned by the CLI. Do not extract or invent a capability from a raw list.",
+    "One service intent uses one Service Execution. Start another execution for another independent intent.",
+    "Ask for email only when the selected capability requires protected delivery; never invent contact data.",
+    "A lost Checkout response is retried with the same Cart and persisted idempotency operation."
   ],
   "forbidden": [
-    "Do not treat local cart files as durable business truth.",
-    "Do not create duplicate checkout commands if the first handoff is still usable.",
-    "Do not treat QR display as proof of payment."
+    "Do not call ordinary buy for a service-backed Cart line.",
+    "Do not create a second Checkout when the existing one can be resumed.",
+    "Do not treat QR display as payment verification."
   ],
   "next_docs": [
-    {
-      "condition": "Need host rendering details after checkout is created",
-      "topic": "render-hosts",
-      "file": "docs/agent/buyer/render-hosts.json"
-    },
-    {
-      "condition": "Need order or refund follow-up after payment",
-      "topic": "orders-refunds",
-      "file": "docs/agent/buyer/orders-refunds.json"
-    }
+    { "condition": "Checkout handoff is ready", "topic": "payment-flow" },
+    { "condition": "Host rendering needs clarification", "topic": "render-hosts" }
   ],
-  "search_terms": [
-    "cart",
-    "checkout",
-    "buy",
-    "购物车",
-    "结账"
-  ]
+  "search_terms": ["cart", "checkout", "service execution", "resume", "contact"]
 }

package/docs/agent/buyer/install-and-setup.json

@@ -2,81 +2,37 @@
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
   "topic": "install-and-setup",
-  "title": "Install and Configure ItPay V3 CLI for Agent Hosts",
-  "purpose": "Guide the agent or runtime owner through installing and configuring the itpay CLI for different agent hosts.",
+  "title": "Install And Identify The ItPay Agent Runtime",
+  "purpose": "Install the CLI and select one of the five supported Agent Types without confusing Agent Type with Host.",
   "when_to_use": [
-    "First-time setup of the itpay CLI.",
-    "The agent needs to be configured for a specific host (Codex, Claude Code, etc.).",
-    "The buyer wants to use itpay in a new environment."
+    "The CLI is being installed or upgraded.",
+    "The agent needs to confirm its stable runtime identity and default output Host."
   ],
   "commands": [
     {
-      "intent": "list all supported install targets",
-      "command": "itpay install",
-      "success_signal": "Table of targets (claude-code, codex, terminal, telegram, feishu) with config file paths."
+      "intent": "list supported Agent Types",
+      "command": "itpay install --json",
+      "success_signal": "status is install_targets and exactly five agent_type/default_host pairs are returned"
     },
     {
-      "intent": "show install instructions for a specific target",
-      "command": "itpay install claude-code",
-      "success_signal": "Step-by-step instructions for Claude Code setup."
-    },
-    {
-      "intent": "show install instructions for Codex / Trae",
-      "command": "itpay install codex",
-      "success_signal": "Step-by-step instructions for Codex/Trae setup."
+      "intent": "read setup for the real runtime",
+      "command": "itpay install <agent_type> --json",
+      "success_signal": "status is instructions_ready and next is a readyz command using that exact Agent Type"
     }
   ],
-  "env_vars": {
-    "ITPAY_BACKEND_URL": {
-      "required": false,
-      "description": "Optional V3 backend override. The CLI defaults to https://app.itpay.ai.",
-      "examples": ["http://localhost:18080", "https://test.itpay.ai"]
-    },
-    "ITPAY_BEARER_TOKEN": {
-      "required": false,
-      "description": "Bearer token for authenticated operations (orders list, vault, profile). Not needed for anonymous cart/checkout.",
-      "acquired_from": "Sign in via web at /signin, then copy the session token."
-    },
-    "ITPAY_CART_SESSION_PATH": {
-      "required": false,
-      "description": "Custom path for the cart session file. Default: ~/.itpay-v3/cart.json"
-    },
-    "ITPAY_AGENT_DEVICE_ID": {
-      "required": false,
-      "description": "Legacy compatibility input. V3 enrolls a signed device identity under ~/.itpay-v3/device; agents should not rotate or invent this value."
-    },
-    "ITPAY_AGENT_TYPE": {
-      "required": false,
-      "description": "Agent runtime type. Set this or pass --agent-type for commerce commands, for example codex-desktop or claude-code-cli."
-    },
-    "ITPAY_CURRENCY": {
-      "required": false,
-      "description": "Default currency for cart operations. Default: CNY"
-    }
-  },
-  "host_requirements": {
-    "terminal": "No special config needed. QR renders as ASCII in terminal or saved as PNG file.",
-    "codex": "Use --host codex or --host trae. Markdown output with images and links.",
-    "claude-code": "Use --host claude-code. Markdown format with image references.",
-    "telegram": "Use --host telegram --target <chat_id>. Output includes openclaw_message payloads.",
-    "feishu": "Use --host feishu --target <open_id>. Output is Feishu Interactive Card JSON.",
-    "lark": "Use --host lark --target <open_id>. Same as feishu format."
-  },
   "agent_rules": [
-    "Use the built-in https://app.itpay.ai production default; override ITPAY_BACKEND_URL only for another deliberate environment.",
-    "Install globally with npm install -g @itpay/cli for all hosts.",
-    "Identify the real runtime with --agent-type or ITPAY_AGENT_TYPE; do not invent a new type to obtain quota.",
-    "Run `itpay install` without arguments to see all supported targets.",
-    "Server cart facts persist in backend Postgres. ~/.itpay-v3/cart.json only caches last ids, checkout display token, and explicit local drafts."
+    "Install with npm install -g @itpay/cli.",
+    "Use the default https://app.itpay.ai API unless an environment override is deliberate.",
+    "Use one exact type: codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, or workbuddy.",
+    "Agent Type identifies the runtime and device instance. Host only controls human-facing rendering.",
+    "Do not change Agent Type to reset quota or recover a failed command."
+  ],
+  "forbidden": [
+    "Do not use codex, terminal, claude-code, or plain-chat as Agent Types.",
+    "Do not claim that install writes host configuration or registers a device; it only prints instructions."
+  ],
+  "next_docs": [
+    { "condition": "Installation is verified", "topic": "quickstart" }
   ],
-  "search_terms": [
-    "install",
-    "setup",
-    "configure",
-    "first time",
-    "setup",
-    "安装",
-    "配置",
-    "environment"
-  ]
+  "search_terms": ["install", "agent type", "host", "codex", "claude code", "workbuddy"]
 }

package/docs/agent/buyer/orders-refunds.json

@@ -2,75 +2,53 @@
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
   "topic": "orders-refunds",
-  "title": "Orders, Payment Escape Hatch, And Refund Requests",
-  "purpose": "Teach the agent how to inspect orders and create refund requests with the current V3 CLI package.",
+  "title": "Order, Delivery And Refund Recovery",
+  "purpose": "Read owned orders and manage refunds through signed Agent authority without guessing payment or refund state.",
   "when_to_use": [
-    "The user wants to inspect one order.",
-    "The agent needs to list orders for an account-scoped bearer session.",
-    "The user wants to request a refund.",
-    "The checkout page is unavailable and the operator needs the payment-intent escape hatch."
+    "An order or Service Execution was interrupted after payment.",
+    "The buyer asks to request, track, or cancel a refund."
   ],
-  "required_state": {
-    "needs": [
-      "order_id for order or refund flows",
-      "ITPAY_BEARER_TOKEN for refund flows"
-    ],
-    "optional": [
-      "refund reason; defaults to buyer_requested"
-    ]
-  },
   "commands": [
     {
-      "intent": "read one canonical order by id",
-      "command": "itpay order <order_id>",
-      "success_signal": "order details and a status hint are printed"
+      "intent": "read one order",
+      "command": "itpay --agent-type <agent_type> order <order_id> --json",
+      "success_signal": "one compact owned-order summary and one current next step are returned"
     },
     {
-      "intent": "list account-visible orders",
-      "command": "ITPAY_BEARER_TOKEN=<account_scoped_token> itpay orders --limit 20",
-      "success_signal": "orders are listed, or the CLI prints that no orders were found"
+      "intent": "request a refund",
+      "command": "itpay --agent-type <agent_type> refund create --order <order_id> --reason buyer_requested --json",
+      "success_signal": "the Refund Owner returns its request id, policy status, consumption state, and access lock"
     },
     {
-      "intent": "create a payment intent only when the normal checkout page cannot do it",
-      "command": "itpay pay --checkout <checkout_id> --method alipay",
-      "success_signal": "payment_intent_id and current payment state are printed"
+      "intent": "recover one refund",
+      "command": "itpay --agent-type <agent_type> refund get <refund_request_id> --json",
+      "success_signal": "one authoritative refund snapshot is returned"
     },
     {
-      "intent": "request a refund for an order",
-      "command": "ITPAY_BEARER_TOKEN=<account_scoped_token> itpay refund --order <order_id> --reason buyer_requested",
-      "success_signal": "refund request id and refund status are printed"
+      "intent": "wait through provider processing",
+      "command": "itpay --agent-type <agent_type> refund watch <refund_request_id> --json",
+      "success_signal": "one terminal refund envelope or one resumable timeout envelope is returned"
+    },
+    {
+      "intent": "cancel before provider submission",
+      "command": "itpay --agent-type <agent_type> refund cancel <refund_request_id> --json",
+      "success_signal": "the Refund Owner cancels the request and requires a new delivery authorization"
     }
   ],
   "agent_rules": [
-    "Use itpay order when you already know the exact order id.",
-    "Use itpay orders only with an account-scoped bearer token. Missing or wrong scope should be surfaced as an error, not guessed away.",
-    "Treat itpay pay as an operator escape hatch. The checkout handoff remains the preferred path.",
-    "Never ask the user or client to supply refund payment ids, amount, currency, buyer id, or actor; the backend derives them from the owned order.",
-    "The refund response is the current source of truth; do not assume success locally."
+    "The Backend derives payment, amount, currency, Buyer and refund policy from the owned order.",
+    "A refund request freezes all delivery paths and revokes existing grants immediately.",
+    "Cancellation or rejection restores eligibility but never reactivates an old grant.",
+    "Use get or watch after interruption; do not infer success from elapsed time.",
+    "Account-wide orders requires an account-scoped Buyer bearer; exact order and refund routes support the bound signed Agent where documented."
   ],
   "forbidden": [
-    "Do not fabricate bearer tokens.",
-    "Do not create a payment intent first if normal checkout rendering is available.",
-    "Do not claim a refund succeeded before the backend response says so."
+    "Do not fabricate Buyer sessions, Device IDs or payment references.",
+    "Do not read delivery while refund access_locked is true.",
+    "Do not claim a refund succeeded before the Refund Owner says succeeded."
   ],
   "next_docs": [
-    {
-      "condition": "Need the initial buyer flow",
-      "topic": "quickstart",
-      "file": "docs/agent/buyer/quickstart.json"
-    },
-    {
-      "condition": "Need host-specific render behavior for checkout handoff",
-      "topic": "render-hosts",
-      "file": "docs/agent/buyer/render-hosts.json"
-    }
+    { "condition": "Need the original purchase path", "topic": "quickstart" }
   ],
-  "search_terms": [
-    "order",
-    "orders",
-    "refund",
-    "payment intent",
-    "退款",
-    "订单"
-  ]
+  "search_terms": ["order", "refund", "cancel", "watch", "delivery lock", "grant"]
 }

package/docs/agent/buyer/payment-flow.json

@@ -2,76 +2,43 @@
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
   "topic": "payment-flow",
-  "title": "ItPay V3 Payment Flow — From Checkout to Verified Payment",
-  "purpose": "Teach the agent how to hand a checkout to the human, let the ItPay checkout page create provider payment, and verify payment state.",
+  "title": "Human Checkout Handoff And Payment Verification",
+  "purpose": "Show the ItPay Checkout to the human and recover authoritative payment state without creating duplicate payment resources.",
   "when_to_use": [
-    "The agent has created a checkout and needs to hand it to the human.",
-    "The buyer wants to pay via Alipay or WeChat Pay.",
-    "The agent needs to wait for payment verification before confirming success."
+    "buy or services checkout returned human_checkout_required.",
+    "The agent restarted or lost the Checkout output before payment was confirmed."
   ],
   "commands": [
     {
-      "intent": "create checkout from a canonical server cart and render ItPay checkout page handoff",
-      "command": "itpay buy --cart <cart_id> --host <client> --contact-email <email>",
-      "success_signal": "ItPay checkout QR/URL is rendered for the human; payment intent is not created by the agent."
+      "intent": "present the Checkout handoff",
+      "command": "<execute the exact command returned by buy or services checkout>",
+      "success_signal": "the human can see both the ItPay Checkout QR or image and the Checkout URL"
     },
     {
-      "intent": "create service-execution quote lock and render ItPay checkout page handoff",
-      "command": "itpay services checkout <service_execution_id> --capability <paid_capability_id> [--email <email>]",
-      "success_signal": "The quote lock is bound to the original server cart item when present; ItPay checkout QR/URL is rendered for the human; the checkout page handles authorization and provider payment."
+      "intent": "read authoritative Checkout state",
+      "command": "itpay checkout --id <checkout_id> --token <display_token> --json",
+      "success_signal": "pending returns one human handoff; completed returns no payment handoff and routes to delivery"
     },
     {
-      "intent": "create service-execution checkout with machine-readable handoff",
-      "command": "itpay services checkout <service_execution_id> --capability <paid_capability_id> [--email <email>] --json",
-      "success_signal": "JSON with kind='checkout_handoff_required', next_action='open_human_checkout', checkout_url, display_token, qr_png_url, and brand_qr_local_path."
-    },
-    {
-      "intent": "recover a service checkout after output loss, process restart, or token expiry",
+      "intent": "recover a service Checkout handoff",
       "command": "itpay services checkout <service_execution_id> --resume --json",
-      "success_signal": "The existing checkout is reused and a fresh handoff is persisted before rendering."
-    },
-    {
-      "intent": "inspect checkout state after payment",
-      "command": "itpay checkout --id <checkout_id> --token <display_token>",
-      "success_signal": "Current checkout status, any payment intents, and buyer session state."
+      "success_signal": "the same unpaid Checkout is reused with a fresh short-lived handoff"
     }
   ],
-  "payment_flow_states": {
-    "quote_bound": "Checkout created, no payment intent yet. Show the ItPay checkout QR/URL to the human.",
-    "payment_pending": "Payment intent created, waiting for buyer to complete payment.",
-    "payment_succeeded": "Payment verified via SSE event payment_intent.verified.",
-    "completed": "Order delivered."
-  },
   "agent_rules": [
-    "Do not call itpay pay or use --pay for the normal buyer flow; those are operator escape hatches.",
-    "The human opens the ItPay checkout page first; the page handles authorization and creates the Alipay/WeChat payment intent.",
-    "For JSON output, render brand_qr_local_path or qr_png_url to the human; do not render provider qr.alipay.com directly.",
-    "After timeout, re-run checkout --id ... --token ... to check current state before retrying.",
-    "Payment success is confirmed ONLY by backend events, not by QR display or buyer claim."
+    "Normal buyer flow opens the ItPay Checkout page; itpay pay and buy --pay are operator escape hatches.",
+    "Use only handoff fields returned for the current Host and make them actually visible to the human.",
+    "Payment is verified only by Backend Checkout or Order state, never by QR rendering, redirect, or user claim.",
+    "A terminal payment state must never display another payment handoff."
+  ],
+  "forbidden": [
+    "Do not render a provider QR in place of the ItPay Checkout handoff.",
+    "Do not mix a display token from another Checkout.",
+    "Do not create a replacement Checkout after an uncertain response; recover first."
   ],
   "next_docs": [
-    {
-      "condition": "Payment verified, need to check order state",
-      "topic": "orders-refunds",
-      "file": "docs/agent/buyer/orders-refunds.json"
-    },
-    {
-      "condition": "Need to understand render behavior per host",
-      "topic": "render-hosts",
-      "file": "docs/agent/buyer/render-hosts.json"
-    }
+    { "condition": "Payment is verified", "topic": "orders-refunds" },
+    { "condition": "The current Host cannot display the handoff", "topic": "render-hosts" }
   ],
-  "search_terms": [
-    "payment",
-    "pay",
-    "alipay",
-    "wechat",
-    "QR",
-    "payment intent",
-    "wait",
-    "SSE",
-    "verified",
-    "支付",
-    "扫码"
-  ]
+  "search_terms": ["payment", "checkout", "QR", "display token", "resume", "verified"]
 }