@itpay/cli 2.0.24 → 2.0.26

package/README.md

@@ -43,6 +43,8 @@ Normative per-command contracts: [CLI Command Reference](docs/cli-reference/inde
 | `claude-code-desktop` | `claude-code` |
 | `claude-code-cli` | `terminal` |
 | `workbuddy` | `plain-chat` |
+| `kimi-code` | `terminal` |
+| `openclaw` | 必须显式提供 |
 
 `--agent-type` identifies the stable runtime and registered Agent instance. Every returned ItPay command preserves it. Different windows or chats of the same type reuse one Agent Instance; they are not separate identities. `--host` only selects the human presentation surface, and `--target` only routes output to a Host destination. Use `itpay install <agent_type> --json` for the exact responsibility.
 
@@ -59,6 +61,7 @@ The local installation keeps one Ed25519 private key and a separate registration
 - `refund create/list/get/watch/cancel`: Refund Owner flow.
 - `services get/events`: redacted support diagnostics; normal flows should use `services next`.
 - `install`, `skill show`, `docs list/show/search`: offline packaged guidance.
+- `device recover`: operator-confirmed Backend reset recovery that preserves the local private key.
 - `pay`: operator escape hatch only; normal buyers use the ItPay Checkout page.
 
 Run `itpay <command> --help` or browse [the command index](docs/cli-reference/index.md) for parameters.

package/dist/src/client/backend.js

@@ -84,16 +84,16 @@ export class BackendClient {
         return this.http.post("/v1/service-executions", input);
     }
     invokeServiceCapability(serviceExecutionID, capabilityID, input) {
-        return this.http.post(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/capabilities/${encodeURIComponent(capabilityID)}/invoke`, input);
+        return this.http.post(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/capabilities/${encodeURIComponent(capabilityID)}/invoke`, input, { replaySafe: Boolean(input.idempotency_key) });
     }
     recordServiceExecutionAction(serviceExecutionID, input) {
         return this.http.post(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/actions`, input);
     }
     createServiceExecutionCheckout(serviceExecutionID, input) {
-        return this.http.post(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/checkout`, input);
+        return this.http.post(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/checkout`, input, { replaySafe: true });
     }
     prepareServiceQuote(serviceExecutionID, input) {
-        return this.http.post(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/quotes`, input);
+        return this.http.post(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/quotes`, input, { replaySafe: true });
     }
     getServiceExecution(serviceExecutionID) {
         return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}`);

package/dist/src/client/http.js

@@ -1,6 +1,7 @@
-// Thin HTTP client for V3 backend. Keep this file boring on purpose:
-// no retries, no SDK abstractions, no business logic. Higher layers
-// own semantics (e.g. CLI commands, frontend feature hooks).
+// Thin HTTP client for V3 backend. Keep retry policy transport-only: bounded
+// retries are allowed only for reads or explicitly replay-safe writes.
+// HTTP/business failures remain owned by higher-level commands.
+import { asTransientTransportError, HttpTransportError } from "./transport.js";
 export class HttpError extends Error {
     status;
     code;
@@ -13,11 +14,13 @@ export class HttpError extends Error {
     }
 }
 export class HttpClient {
+    static MAX_TRANSPORT_RETRIES = 2;
     baseURL;
     fetchImpl;
     defaultHeaders;
     requestAuthorizer;
     recoverAuthorization;
+    transportRetryDelayMs;
     constructor(config) {
         this.baseURL = config.baseURL.replace(/\/$/, "");
         this.fetchImpl = config.fetchImpl ?? globalThis.fetch;
@@ -28,39 +31,70 @@ export class HttpClient {
         };
         this.requestAuthorizer = config.requestAuthorizer;
         this.recoverAuthorization = config.recoverAuthorization;
+        this.transportRetryDelayMs = Math.max(0, config.transportRetryDelayMs ?? 200);
     }
     async request(path, options = {}) {
         const url = path.startsWith("http") ? path : this.baseURL + path;
         const method = options.method ?? "GET";
         const body = options.body !== undefined ? JSON.stringify(options.body) : "";
         const requestPath = new URL(url).pathname + new URL(url).search;
-        for (let attempt = 0; attempt < 2; attempt += 1) {
+        const replaySafe = method === "GET" || Boolean(options.idempotencyKey) || options.replaySafe === true;
+        let authorizationRecovered = false;
+        let transportRetries = 0;
+        for (;;) {
             const headers = { ...this.defaultHeaders };
-            if (this.requestAuthorizer) {
-                Object.assign(headers, await this.requestAuthorizer({ method, path: requestPath, body }));
+            try {
+                if (this.requestAuthorizer) {
+                    Object.assign(headers, await this.requestAuthorizer({ method, path: requestPath, body }));
+                }
+            }
+            catch (error) {
+                // Authorization can perform enrollment or session POSTs before the
+                // protected request exists. Classify their transport failure, but do
+                // not inherit the outer request's replay policy for those writes.
+                if (error instanceof HttpTransportError)
+                    throw error;
+                throw asTransientTransportError(error, 1) ?? error;
             }
             if (options.bearer)
                 headers.Authorization = `Bearer ${options.bearer}`;
             if (options.idempotencyKey)
                 headers["Idempotency-Key"] = options.idempotencyKey;
-            const response = await this.fetchImpl(url, {
-                method,
-                headers,
-                ...(options.body !== undefined ? { body } : {}),
-                ...(options.signal ? { signal: options.signal } : {}),
-            });
-            const text = await response.text();
+            let response;
+            let text;
+            try {
+                response = await this.fetchImpl(url, {
+                    method,
+                    headers,
+                    ...(options.body !== undefined ? { body } : {}),
+                    ...(options.signal ? { signal: options.signal } : {}),
+                });
+                text = await response.text();
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    throw error;
+                const transportError = asTransientTransportError(error, transportRetries + 1);
+                if (!transportError)
+                    throw error;
+                if (replaySafe && transportRetries < HttpClient.MAX_TRANSPORT_RETRIES) {
+                    transportRetries += 1;
+                    await delay(this.transportRetryDelayMs * (2 ** (transportRetries - 1)));
+                    continue;
+                }
+                throw asTransientTransportError(error, transportRetries + 1) ?? error;
+            }
             const parsed = text.length > 0 ? safeParseJson(text) : undefined;
             if (response.ok)
                 return parsed;
             const error = new HttpError(response.status, parsed, `HTTP ${response.status}`);
-            if (attempt === 0 && error.status === 401 && error.code === "agent_device_session_required" && this.recoverAuthorization) {
+            if (!authorizationRecovered && error.status === 401 && error.code === "agent_device_session_required" && this.recoverAuthorization) {
+                authorizationRecovered = true;
                 await this.recoverAuthorization();
                 continue;
             }
             throw error;
         }
-        throw new Error("unreachable HTTP retry state");
     }
     get(path, options = {}) {
         return this.request(path, { ...options, method: "GET" });
@@ -72,6 +106,9 @@ export class HttpClient {
         return this.request(path, { ...options, method: "DELETE" });
     }
 }
+function delay(milliseconds) {
+    return milliseconds === 0 ? Promise.resolve() : new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
 function safeParseJson(text) {
     try {
         return JSON.parse(text);

package/dist/src/client/transport.js

@@ -0,0 +1,81 @@
+export class HttpTransportError extends Error {
+    code;
+    attempts;
+    causeCode;
+    retryable = true;
+    constructor(code, attempts, causeCode, cause) {
+        const suffix = attempts > 1 ? ` after ${attempts} attempts` : "";
+        super(`${transportMessage(code)} before a complete HTTP response was received${suffix}`, { cause });
+        this.code = code;
+        this.attempts = attempts;
+        this.causeCode = causeCode;
+        this.name = "HttpTransportError";
+    }
+}
+export function asTransientTransportError(error, attempts) {
+    if (isAbort(error))
+        return undefined;
+    const causeCode = findCauseCode(error);
+    const code = causeCode ? classifyCauseCode(causeCode) : classifyFetchFailure(error);
+    return code ? new HttpTransportError(code, attempts, causeCode, error) : undefined;
+}
+function classifyCauseCode(code) {
+    switch (code) {
+        case "ECONNRESET":
+            return "network_connection_reset";
+        case "ETIMEDOUT":
+        case "UND_ERR_CONNECT_TIMEOUT":
+        case "UND_ERR_HEADERS_TIMEOUT":
+        case "UND_ERR_BODY_TIMEOUT":
+            return "network_timeout";
+        case "EAI_AGAIN":
+            return "network_dns_temporary";
+        case "ENETUNREACH":
+        case "EHOSTUNREACH":
+            return "network_unreachable";
+        case "ECONNREFUSED":
+            return "network_connection_refused";
+        case "UND_ERR_SOCKET":
+            return "network_socket_error";
+        default:
+            return undefined;
+    }
+}
+function classifyFetchFailure(error) {
+    return error instanceof TypeError && error.message === "fetch failed"
+        ? "network_transport_failed"
+        : undefined;
+}
+function findCauseCode(error) {
+    const seen = new Set();
+    let current = error;
+    while (current && typeof current === "object" && !seen.has(current)) {
+        seen.add(current);
+        const code = current.code;
+        if (typeof code === "string" && code !== "")
+            return code;
+        current = current.cause;
+    }
+    return undefined;
+}
+function isAbort(error) {
+    return error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
+}
+function transportMessage(code) {
+    switch (code) {
+        case "network_connection_reset":
+            return "network connection was reset";
+        case "network_timeout":
+            return "network connection timed out";
+        case "network_dns_temporary":
+            return "DNS lookup was temporarily unavailable";
+        case "network_unreachable":
+            return "network was unreachable";
+        case "network_connection_refused":
+            return "network connection was refused";
+        case "network_socket_error":
+            return "network socket failed";
+        case "network_transport_failed":
+            return "network transport failed";
+    }
+}

package/dist/src/commands/checkout_handoff.js

@@ -5,16 +5,25 @@ export function shouldPrepareLocalCheckoutImage(platform) {
 export function isWorkBuddyPlainChat(agentType, platform) {
     return agentType?.trim().toLowerCase() === "workbuddy" && platform === "plain_chat";
 }
+export function buildWorkBuddyPresentFilesAction(url) {
+    return {
+        tool: "present_files",
+        arguments: { files: [url] },
+    };
+}
 export function buildCheckoutHandoff(input) {
     const handoff = { url: input.url };
-    const workBuddyLinkOnly = isWorkBuddyPlainChat(input.agentType, input.platform);
+    const workBuddyAction = isWorkBuddyPlainChat(input.agentType, input.platform);
+    if (workBuddyAction) {
+        handoff.agent_action = buildWorkBuddyPresentFilesAction(input.url);
+    }
     if (input.platform === "markdown") {
         if (input.localPath)
             handoff.qr_local_path = input.localPath;
         if (input.markdown)
             handoff.markdown = input.markdown;
     }
-    else if (input.platform === "plain_chat" && input.qrImageURL && !workBuddyLinkOnly) {
+    else if (input.platform === "plain_chat" && input.qrImageURL && !workBuddyAction) {
         handoff.qr_image_url = input.qrImageURL;
     }
     else if (input.platform === "telegram" && input.qrImageURL) {
@@ -30,7 +39,7 @@ export function buildCheckoutHandoff(input) {
 }
 function checkoutHandoffInstruction(agentType, platform, amount) {
     if (isWorkBuddyPlainChat(agentType, platform)) {
-        return `Backend 尚未确认付款。向用户说明金额 ${amount}，直接发送并打开 handoff.url，然后停止等待。不要调用 present_files，不要检查本地文件，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+        return `Backend 尚未确认付款。立即严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行一次，在右侧打开 handoff.url；确认工具调用成功后说明金额 ${amount}，然后停止等待。若工具失败，只发送原始 handoff.url，报告未自动打开并停止。不要用 present_files 打开本地文件或二维码 PNG，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }
     if (platform === "markdown") {
         return `Backend 尚未确认付款。把 handoff.markdown 原样发送到当前桌面对话，确认二维码、付款链接和金额 ${amount} 均已实际对用户可见，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;

package/dist/src/commands/install.js

@@ -15,7 +15,7 @@ const INSTRUCTIONS = {
     "codex-cli": "在 Codex CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
     "claude-code-desktop": "在 Claude Code Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
     "claude-code-cli": "在 Claude Code CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
-    workbuddy: "在 WorkBuddy 中始终传这个 Agent Type。运行会持久化 ~/.itpay-v3 的 ItPay Bash 命令前，把 Shell 工具参数 dangerouslyDisableSandbox 设为 true；用户拒绝权限时停止，不要切换 Node、删除 identity 或处理 lock。Checkout 只返回已渲染的付款 Card Link；直接打开 handoff.url，不要调用 present_files，也不要检查本地二维码文件。",
+    workbuddy: "在 WorkBuddy 中始终传这个 Agent Type。运行会持久化 ~/.itpay-v3 的 ItPay Bash 命令前，把 Shell 工具参数 dangerouslyDisableSandbox 设为 true；用户拒绝权限时停止，不要切换 Node、删除 identity 或处理 lock。Checkout 返回已渲染的付款 Card Link 和 present_files action；原样执行一次 action 打开 handoff.url，不要检查本地二维码文件。",
     "kimi-code": "保持 kimi-code Agent Type，使用标准 CLI 命令和终端付款交接；不要切换到其他平台身份。",
     openclaw: "保持 openclaw Agent Type；每个展示命令都从当前可信会话上下文显式传 --host，IM 入口同时传 --target。Telegram 使用返回的原生 message action，其他入口展示标准二维码和付款链接。",
 };

package/dist/src/commands/pay.js

@@ -2,7 +2,7 @@
 // Checkout page; this command exists for controlled integration recovery.
 import { formatMoney } from "../render/output.js";
 import { writeCommandEnvelope } from "./guidance.js";
-import { isWorkBuddyPlainChat } from "./checkout_handoff.js";
+import { buildWorkBuddyPresentFilesAction, isWorkBuddyPlainChat } from "./checkout_handoff.js";
 import { platformKeyForHost } from "../render/plan.js";
 export async function runPay(backend, options) {
     const intent = await backend.createPaymentIntent(options.checkoutID, {
@@ -20,11 +20,13 @@ function payEnvelope(intent, options) {
     const terminal = ["failed", "expired", "refunded"].includes(intent.status);
     const verified = intent.status === "verified" || intent.status === "partially_refunded";
     const handoff = {};
-    const workBuddyLinkOnly = isWorkBuddyPlainChat(options.agentType, platformKeyForHost(options.host));
-    if (!terminal && !verified && workBuddyLinkOnly) {
+    const workBuddyAction = isWorkBuddyPlainChat(options.agentType, platformKeyForHost(options.host));
+    if (!terminal && !verified && workBuddyAction) {
         const url = intent.action?.mobile_wallet_url ?? intent.action?.qr_image_url;
-        if (url)
+        if (url) {
             handoff.url = url;
+            handoff.agent_action = buildWorkBuddyPresentFilesAction(url);
+        }
     }
     else {
         if (!terminal && !verified && intent.action?.qr_image_url)
@@ -60,7 +62,7 @@ function payInstruction(options, verified, terminal, hasAction, amount) {
         return "Payment Intent 尚未返回可展示动作；不要猜测渠道链接，回到同一 Checkout 查询。";
     const platform = platformKeyForHost(options.host);
     if (isWorkBuddyPlainChat(options.agentType, platform)) {
-        return `这是受控逃生入口。说明金额 ${amount}，把 handoff.url 作为可点击链接发送给用户，然后停止等待。不要调用 present_files，不要立即查询、创建替代 Checkout 或 Payment Intent。`;
+        return `这是受控逃生入口。立即严格按 handoff.agent_action 原样执行一次，在右侧打开 handoff.url；确认工具调用成功后说明金额 ${amount} 并停止等待。若工具失败，只发送原始 handoff.url，报告未自动打开并停止。不要用 present_files 打开本地文件或二维码 PNG，不要立即查询、创建替代 Checkout 或 Payment Intent。`;
     }
     if (options.host === "codex" || options.host === "claude-code")
         return "这是受控逃生入口；把 handoff 中的二维码或钱包链接实际发到当前桌面对话，然后停止等待。";

package/dist/src/main.js

@@ -7,6 +7,7 @@ import { DeviceAuthority, DeviceAuthorizationError, DeviceStateError } from "./s
 import { CartSession } from "./state/cart_session.js";
 import { defaultHostForAgentType, normalizeHost, validateContext } from "./state/client_context.js";
 import { HttpError } from "./client/http.js";
+import { HttpTransportError } from "./client/transport.js";
 import { runReadyz } from "./commands/readyz.js";
 import { runBuy } from "./commands/buy.js";
 import { runCatalogList } from "./commands/catalog.js";
@@ -93,6 +94,7 @@ function reportCLIError(error, contract) {
     const backendOverrideError = error instanceof BackendOverrideError ? error : undefined;
     const deviceError = error instanceof DeviceAuthorizationError ? error : undefined;
     const stateError = error instanceof DeviceStateError ? error : undefined;
+    const transportError = error instanceof HttpTransportError ? error : undefined;
     const httpRecovery = errorRecoveryActions(error).map((action) => ({
         command: action.command,
         reason: action.reason ?? action.label,
@@ -134,7 +136,7 @@ function reportCLIError(error, contract) {
         writeCommandEnvelope({
             status: "error",
             error: {
-                code: incompatible ? "backend_contract_incompatible" : backendOverrideError?.code ?? commandError?.code ?? (error instanceof HttpError ? error.code : stateError?.code ?? deviceError?.code ?? contract?.code ?? "command_failed"),
+                code: incompatible ? "backend_contract_incompatible" : backendOverrideError?.code ?? commandError?.code ?? (error instanceof HttpError ? error.code : transportError?.code ?? stateError?.code ?? deviceError?.code ?? contract?.code ?? "command_failed"),
                 message: error instanceof Error ? error.message : String(error),
             },
             ...(requiredCLIVersion ? {
@@ -142,6 +144,11 @@ function reportCLIError(error, contract) {
                     current_cli_version: CLI_VERSION,
                     required_cli_version: requiredCLIVersion,
                 },
+            } : transportError ? {
+                result: {
+                    attempts: transportError.attempts,
+                    automatic_retry_performed: transportError.attempts > 1,
+                },
             } : error instanceof HttpError && error.payload?.service_execution_id ? {
                 result: {
                     service_execution_id: error.payload.service_execution_id,
@@ -172,9 +179,13 @@ function reportCLIError(error, contract) {
                                         ? "Provider 拒绝了本次请求，但未声明这是输入错误；向用户逐字报告 error.message 和 result.quota 并停止。不要修改输入、不要重试、不要创建新 Execution。"
                                         : capabilityInputInvalid
                                             ? "输入未通过本地校验，上游尚未被调用且用户额度未变化。向用户逐字报告 error.message 并停止，不要原样重试或运行其他恢复命令。用户提供修正后的输入后，继续使用当前未结束的 Execution。"
-                                            : backendOverrideError
-                                                ? "移除 ITPAY_BACKEND_URL 使用正式环境，或准确设置为 https://dev.itpay.ai。"
-                                                : commandError?.instruction ?? authorizationInstruction ?? contract?.instruction ?? "检查命令参数后重试。",
+                                            : transportError
+                                                ? transportError.attempts > 1
+                                                    ? "临时网络故障；CLI 已仅对可安全重放的操作完成有限自动重试，但仍未获得完整响应。按 recovery 查询同一资源的权威状态；不要创建替代 Checkout、Execution、Payment 或 Refund。"
+                                                    : "网络在完整响应前中断；当前写操作没有安全重放合同，因此 CLI 未自动重试。按 recovery 查询权威状态；不要原样重放或创建替代 Checkout、Execution、Payment 或 Refund。"
+                                                : backendOverrideError
+                                                    ? "移除 ITPAY_BACKEND_URL 使用正式环境，或准确设置为 https://dev.itpay.ai。"
+                                                    : commandError?.instruction ?? authorizationInstruction ?? contract?.instruction ?? "检查命令参数后重试。",
             next: null,
             recovery: incompatible
                 ? requiredCLIVersion
@@ -196,6 +207,11 @@ function reportCLIError(error, contract) {
         process.exitCode = 1;
         return;
     }
+    if (error instanceof HttpTransportError) {
+        process.stderr.write(`[${error.code}] ${error.message}\n`);
+        process.exitCode = 1;
+        return;
+    }
     if (error instanceof Error) {
         process.stderr.write(`${error.message}\n`);
         process.exitCode = 1;

package/dist/src/state/config.js

@@ -12,7 +12,7 @@ import { DeviceAuthority } from "./device_authority.js";
 import { OperationJournal } from "./operation_journal.js";
 export const DEFAULT_BASE_URL = "https://app.itpay.ai";
 export const DEV_BASE_URL = "https://dev.itpay.ai";
-export const CLI_VERSION = "2.0.24";
+export const CLI_VERSION = "2.0.26";
 export const API_CONTRACT_REVISION = "sha256:d4e94049c01b38bc77dce76bf4e49e8243adfc588541e33af6477cd5722a5bc4";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";

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

@@ -37,6 +37,7 @@
     "If backend_contract_incompatible includes result.required_cli_version, stop all ItPay business commands and use only the exact distribution-specific update recovery returned by the CLI; never replace its version with latest.",
     "After upgrading, require itpay --version to equal result.required_cli_version before running readyz again; never change Agent Type or Device identity to recover compatibility.",
     "Use one exact type: codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy, kimi-code, or openclaw.",
+    "For compatibility, a global --agent-type codex declaration is normalized immediately to codex-desktop; all registration, output, and returned commands use codex-desktop. Never generate the alias, and do not use codex as an install target.",
     "One local private key is reused, while Device registrations and quota lineage remain separate for app.itpay.ai and dev.itpay.ai.",
     "Within each official Backend registration, each Agent Type has one Agent Instance; all windows and chats of the same type reuse it.",
     "Agent Type identifies the runtime. Host controls rendering and target only identifies a presentation destination. OpenClaw requires an explicit Host and IM target; Kimi Code uses the standard terminal CLI contract.",
@@ -44,7 +45,7 @@
     "Do not change Agent Type or rotate local identity to reset quota or recover a failed command."
   ],
   "forbidden": [
-    "Do not use codex, terminal, claude-code, or plain-chat as Agent Types.",
+    "Do not use terminal, claude-code, or plain-chat as Agent Types. Do not generate codex as an Agent Type; it is accepted only as a legacy global declaration and becomes codex-desktop before any request.",
     "Do not set or suggest any Backend except the default https://app.itpay.ai or the exact test override https://dev.itpay.ai.",
     "Do not claim that install writes host configuration or registers a device; it only prints instructions.",
     "Do not create a new identity for a different window, task, chat, or process of the same Agent Type."

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

@@ -31,7 +31,7 @@
     "Use only handoff fields returned for the current Host and make them actually visible to the human.",
     "Before creating a single-Service Checkout, send the exact price confirmation requested by the current instruction, stop, and wait for explicit human agreement.",
     "After presenting a Checkout, stop. Run the returned next.command only after the human completes the payment action or asks to query the same Checkout.",
-    "For workbuddy with plain-chat, send or open the fully rendered Card Link in handoff.url and never call present_files or create another payment resource.",
+    "For workbuddy with plain-chat, execute handoff.agent_action exactly once to open the fully rendered Card Link in handoff.url; if it fails, send only the original URL and stop without creating another payment resource.",
     "For openclaw with telegram, execute the returned native message action using the current trusted target. For any other explicit OpenClaw Host, show the returned HTTPS QR image and Checkout URL.",
     "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."

package/docs/agent/buyer/render-hosts.json

@@ -33,7 +33,7 @@
     {
       "agent_type": "workbuddy",
       "default_host": "plain-chat",
-      "responsibility": "show the amount and send or open handoff.url, which is the fully rendered HTML Card Link; never call present_files; then stop"
+      "responsibility": "execute handoff.agent_action exactly once to open the fully rendered handoff.url with present_files; show the amount and stop"
     },
     {
       "agent_type": "kimi-code",
@@ -63,7 +63,8 @@
   "agent_rules": [
     "Agent Type is stable identity; Host is presentation and may be explicitly overridden.",
     "A local QR path is not visible until a desktop Agent attaches or renders that file on the human-facing surface; WorkBuddy never receives a local QR path.",
-    "For workbuddy with plain-chat, send or open only the rendered handoff.url and never call present_files, inspect files, or rebuild a QR.",
+    "For workbuddy with plain-chat, execute handoff.agent_action exactly once; it calls present_files with handoff.url as the only files element and opens the rendered Card Link in the right-side browser.",
+    "If the WorkBuddy action fails, send the original handoff.url, report that it did not auto-open, and stop without creating another payment resource.",
     "Do not claim the handoff was shown until both a usable payment image or QR and the Checkout URL are visible.",
     "IM Hosts that require a target must receive --target before Checkout creation. OpenClaw has no default Host; Kimi Code uses terminal.",
     "OpenClaw Telegram uses flat url/value buttons for deployed-version compatibility. A grant_confirmed callback carries only the Checkout ID, never a display token, and never proves payment or an active grant."
@@ -72,7 +73,7 @@
     "Do not expose display tokens separately from the tokenized Checkout handoff.",
     "Do not print base64 images, mirror lists, renderer debug state, or provider QR URLs.",
     "Do not claim a desktop attachment exists when only a filesystem path was printed.",
-    "Do not call present_files or inspect, download, or regenerate a local QR file for WorkBuddy."
+    "Do not use present_files for a local file, QR PNG, downloaded copy, or rebuilt URL in WorkBuddy."
   ],
   "next_docs": [
     {

package/docs/cli-reference/agent-types.md

@@ -14,13 +14,14 @@
 | `codex-cli` | `terminal` | 在用户可见终端渲染二维码并输出付款链接；若用户不看该终端，要求改用正确 Host。 |
 | `claude-code-desktop` | `claude-code` | 返回桌面对话可展示的 Markdown 图片和付款链接，要求先展示再等待。 |
 | `claude-code-cli` | `terminal` | 在用户可见终端输出二维码和链接，不声称已在桌面对话展示。 |
-| `workbuddy` | `plain-chat` | 只返回完整渲染的 HTML Card Link；直接打开链接，不调用 `present_files`，不返回或检查本地图片路径。 |
+| `workbuddy` | `plain-chat` | 返回完整渲染的 HTML Card Link 和可原样执行的 `present_files` action；立即打开 Card Link，不返回或检查本地图片路径。 |
 | `kimi-code` | `terminal` | 使用标准 CLI 引导，在用户可见终端渲染二维码和付款链接。 |
 | `openclaw` | 无；必须显式传入 | `--host telegram` 使用 OpenClaw 原生 `message` action；其他入口返回标准 HTTPS 二维码和付款链接。 |
 
 ## 通用规则
 
 - commerce 命令必须传 `--agent-type` 或设置 `ITPAY_AGENT_TYPE`。
+- 兼容入口 `--agent-type codex` / `ITPAY_AGENT_TYPE=codex` 仅在 CLI 参数解析边界规范化为 `codex-desktop`；登记、输出和后续命令始终使用 `codex-desktop`。新文档和 Agent 不得主动生成该别名。`itpay install codex` 仍是无效 target。
 - Agent Type 必须真实且稳定；同类型窗口复用同一实例，不得临时换名。
 - `next.command` 和 `recovery.command` 必须保留当前显式 Agent Type，不读取或回退到机器上其他类型。
 - 显式 `--host` 覆盖默认 Host，但不改变已登记的 Agent Type。
@@ -46,7 +47,8 @@
     "url": "<checkout_or_rendered_card_url>",
     "qr_local_path": "<desktop_optional_local_path>",
     "qr_image_url": "<non_workbuddy_optional_absolute_https_png>",
-    "markdown": "<desktop_optional_host_ready_markdown>"
+    "markdown": "<desktop_optional_host_ready_markdown>",
+    "agent_action": "<host_optional_native_action>"
   },
   "instruction": "<agent-type-specific instruction>",
   "next": {
@@ -66,11 +68,11 @@
 | `claude-code-desktop / claude-code` | `url, qr_local_path, markdown` |
 | `codex-cli / terminal` | `url`；非 JSON 输出另外渲染终端二维码 |
 | `claude-code-cli / terminal` | `url`；非 JSON 输出另外渲染终端二维码 |
-| `workbuddy / plain-chat` | `url`（完整渲染的 HTML Card Link） |
+| `workbuddy / plain-chat` | `url, agent_action`（`present_files(files=[url])`，打开完整渲染的 HTML Card Link） |
 | `kimi-code / terminal` | `url`；非 JSON 输出另外渲染终端二维码 |
 | `openclaw / telegram` | `url, qr_image_url, agent_action` |
 | `openclaw / other` | `url, qr_image_url` |
 
-WorkBuddy instruction 必须直接发送并打开 `handoff.url`，明确禁止 `present_files`。这个 URL 指向 Backend 已渲染的 HTML Card；不能检查本地文件、下载或重建二维码、调用 `pay` 或创建替代付款资源。显式 `--host` 仍覆盖默认展示方式。
+WorkBuddy instruction 必须要求 Agent 原样执行一次 `handoff.agent_action`，即调用 `present_files(files=[handoff.url])` 在右侧打开 Backend 已渲染的 HTML Card。调用成功后说明金额并停止；调用失败时只发送原始 `handoff.url` 并如实报告未自动打开。禁止把 `present_files` 用于本地文件或二维码 PNG，也不能下载或重建二维码、调用 `pay` 或创建替代付款资源。显式 `--host` 仍覆盖默认展示方式。
 
 OpenClaw Telegram 的 `handoff.agent_action` 是可原样执行的原生 `message` tool action。`presentation` 只包含标准 `blocks.buttons`：`📱 手机点这儿支付` 使用扁平 `url`，`📋 已授权给我读` 使用扁平 `value=itp:grant_confirmed:<checkout_id>`；二维码单独使用 action 的 `media`。CLI `instruction` 必须要求 Agent 原样执行该 action，不得改写 Presentation、换用其他消息工具或声称普通文本回复等同于已发送按钮。收到授权 callback 后立即执行 `next.command` 查询同一 Checkout，再只跟随后端返回的同一 Execution grant 流程；callback 只携带 Checkout ID，不携带 display token，也不证明付款或 grant 已生效。OpenClaw `target` 使用原生 chat target（如 `5559456744` 或 `-1001234567890:topic:42`），不添加 `telegram:` 前缀。

package/docs/cli-reference/commands/buy.md

@@ -40,6 +40,7 @@ itpay buy \
 --require-contact <email,phone>
 --host <host>
 --target <target>
+--locale <zh-CN|en>
 --qr-format <unicode|utf8|ansi|terminal>
 --qr-file <path>
 --pay
@@ -64,6 +65,7 @@ itpay buy \
 | `--require-contact` | 否 | 只接受 `email`、`phone`；缺失时先询问用户，禁止 Agent 编造。 |
 | `--host` | 条件必填 | 通常由 `--agent-type` 推导；`openclaw` 必须显式传当前入口。只改变 handoff 展示，不改变交易事实。 |
 | `--target` | 条件必填 | 要求目标会话的 IM Host 必须提供；OpenClaw 从当前可信会话上下文传入。 |
+| `--locale` | 否 | Payment Card 语言，默认 `zh-CN`；可使用 `en`。只改变 Card 文案，不改变交易事实。 |
 | `--qr-format` | 否 | 非 JSON 的终端渲染选项。 |
 | `--qr-file` | 否 | 非 JSON handoff 的明确二维码文件路径。 |
 | `--pay` | 否 | 创建 Payment Intent 的集成/运维入口；普通 Agent 流程只展示 Checkout。 |
@@ -153,7 +155,7 @@ itpay buy \
 | `buy_parameter_invalid` | quantity/timeout 非正整数，或 `--no-wait` 未配 `--pay`。 | 修正参数；本次不创建资源。 |
 | `service_quote_required` | Cart 含尚未绑定 Quote 的 Service Execution。 | 原样执行返回的 `services next <id> --json`；不要绕过 Quote 输入校验。 |
 | `idempotency_conflict` | 同一幂等操作被用于不同请求。 | 保留句柄并执行 `itpay next --json`，不要换键重建。 |
-| `buy_failed` | 网络或未知后端错误。 | 先执行 `itpay next --json` 或 `cart next --json` 恢复现有资源。 |
+| `buy_failed` | 非传输层的未知命令错误。 | 先执行 `itpay next --json` 或 `cart next --json` 恢复现有资源。传输失败使用 conventions 中的稳定 `network_*` 错误码。 |
 
 所有参数错误都必须在 HTTP 和本地 Cart 变更前被拒绝。服务 Cart 只有每条 service-backed line 都绑定有效 Quote 时才能创建 Checkout；付款后 Backend 按 Order Item 分别推进 Execution。
 
@@ -165,7 +167,7 @@ itpay buy \
 | `codex-cli` | `terminal` | `url` | 非 JSON 模式在用户可见终端渲染二维码；始终保留付款链接。 |
 | `claude-code-desktop` | `claude-code` | `url`、可用时 `qr_local_path` 和 `markdown` | 把 Markdown handoff 发到当前桌面对话，不能只输出本地路径。 |
 | `claude-code-cli` | `terminal` | `url` | 在用户可见终端展示；不能声称桌面对话已收到图片。 |
-| `workbuddy` | `plain-chat` | `url` | `url` 是完整渲染的 HTML Card Link；直接发送/打开，不调用 `present_files`，然后停止。 |
+| `workbuddy` | `plain-chat` | `url,agent_action` | 原样执行一次 `present_files(files=[url])`，在右侧打开完整渲染的 HTML Card Link，然后停止。 |
 | `kimi-code` | `terminal` | `url` | 使用标准 CLI 非 JSON 终端二维码和链接。 |
 | `openclaw` | 必须显式 | Telegram 返回 `url,qr_image_url,agent_action`；其他入口返回 `url,qr_image_url` | Telegram 执行原生 `message` action；其他入口直接展示图片和链接。 |
 

package/docs/cli-reference/commands/catalog/list.md

@@ -44,4 +44,4 @@ itpay catalog list [--json]
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 使用同一产品内容；只允许排版不同。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 使用同一产品内容；只允许排版不同。

package/docs/cli-reference/commands/checkout.md

@@ -13,13 +13,15 @@
 
 ```bash
 itpay checkout [--id <checkout_id>] [--token <display_token>]
-  [--host <host>] [--target <target>] [--json]
+  [--host <host>] [--target <target>] [--locale <zh-CN|en>] [--json]
 ```
 
 省略 `--id/--token` 时只能使用本机保存的一组完整句柄；不得把其他 Checkout 的 token 拼接使用。
 
 `--host` 默认由 `--agent-type` 决定；`openclaw` 必须显式传当前入口。IM Host 必须提供 `--target`。`--json` 输出机器可读合同，不内嵌二维码字符画或图片二进制。
 
+`--locale` 默认 `zh-CN`，可显式使用 `en`。它只改变重新渲染的 Card 文案，不改变 Checkout、付款、授权或恢复状态。
+
 ## 等待付款输出
 
 ```json
@@ -71,7 +73,7 @@ token 缺失或不匹配时使用本机句柄恢复。只有请求的 Checkout
 | `codex-cli` | `url`；普通文本模式渲染终端二维码。 |
 | `claude-code-desktop` | `url, qr_local_path, markdown`；原样发送 Markdown。 |
 | `claude-code-cli` | `url`；普通文本模式渲染终端二维码。 |
-| `workbuddy` | 只返回 `url`；它是完整渲染的 HTML Card Link。直接打开，不调用 `present_files`，不生成本地文件。 |
+| `workbuddy` | 返回 `url,agent_action`；原样执行一次 `present_files(files=[url])` 打开完整渲染的 HTML Card Link，不生成本地文件。 |
 | `kimi-code` | `url`；普通文本模式渲染标准终端二维码。 |
 | `openclaw` | Telegram 为 `url,qr_image_url,agent_action`；instruction 强制原样执行 action。`📋 已授权给我读` callback 触发同一 Checkout 查询，再由 Backend 决定是否进入 grant 读取；其他显式 Host 为 `url,qr_image_url`。 |
 

package/docs/cli-reference/commands/device.md

@@ -1,9 +1,11 @@
-# `itpay device recover`
+# `itpay device` / `itpay device recover`
 
 > **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
 
 ## 范围
 
+`itpay device` 只显示该命令组的帮助并退出，不访问 Backend、不读取或修改身份。当前唯一子命令是 `recover`。
+
 仅在运营明确确认当前 Backend 的 Device 登记数据库已重建或清空后，删除本地该 Backend 的 v2 registration：
 
 ```bash
@@ -13,3 +15,35 @@ itpay --agent-type <agent_type> device recover --confirm-backend-reset --json
 命令只作用于当前官方 Backend 的 Device registration，并保留本地 Ed25519 私钥、Cart 和业务资源。默认是 `https://app.itpay.ai`；显式测试可使用准确的 `ITPAY_BACKEND_URL=https://dev.itpay.ai`。该命令不访问 Backend、不自动创建新身份；返回的只读 `services list` 会保留同一 Backend，是重新登记入口。
 
 缺少确认参数返回 `backend_reset_confirmation_required`。普通 session 失效由 CLI 自动续期；revoked、quota、权限或未知 Backend 故障不得使用本命令。所有 Agent Type 使用相同输入和输出合同。
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|---|---:|---|
+| 全局 `--agent-type <agent_type>` | 是 | 当前真实且稳定的 Agent Type；必须位于 `device` 前。 |
+| `--confirm-backend-reset` | 是 | 确认运营已明确判定所选 Backend 的登记数据库被重建或清空。 |
+| `--json` | 否 | 输出稳定 JSON 信封；否则输出同一事实的简洁文本。 |
+
+## 标准输出
+
+```json
+{
+  "status": "backend_registration_removed",
+  "result": {
+    "backend": "https://app.itpay.ai",
+    "removed_agent_types": ["codex-desktop"],
+    "private_key_preserved": true,
+    "other_backend_registrations_preserved": true
+  },
+  "instruction": "只读列出 Service Executions，以同一私钥和 Agent Type 重新登记当前 Backend；不要删除 ~/.itpay-v3 或切换运行时。",
+  "next": {
+    "command": "itpay --agent-type codex-desktop services list --limit 1 --json",
+    "reason": "用无业务写入的签名请求重新登记当前 Backend"
+  },
+  "recovery": []
+}
+```
+
+当前 Backend 已无本地登记时，`status` 为 `backend_registration_absent`、`removed_agent_types=[]`，其余合同不变。文本输出只包含 Backend、registration 状态、私钥保留和其他 Backend 保留四项，不输出私钥、公钥、Device ID、Agent Instance ID、session、token 或本地文件内容。
+
+缺少 Agent Type 返回 `agent_type_required`；缺少确认返回 `backend_reset_confirmation_required`。其他本地恢复失败返回 `device_recovery_failed`。所有失败都必须发生在删除 registration 前；本命令不得删除整把 Device identity、Cart、operation journal 或其他 Backend 登记。

package/docs/cli-reference/commands/install.md

@@ -117,7 +117,7 @@ OpenClaw 额外明确没有默认入口：
 | `codex-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
 | `claude-code-desktop` | `claude-code` | 桌面对话必须实际展示二维码和付款链接。 |
 | `claude-code-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
-| `workbuddy` | `plain-chat` | 会持久化 `~/.itpay-v3` 的 Bash 调用先设 Shell 工具参数 `dangerouslyDisableSandbox=true`；拒绝权限时停止。Checkout 只发送/打开渲染后的 Card Link，不调用 `present_files`。 |
+| `workbuddy` | `plain-chat` | 会持久化 `~/.itpay-v3` 的 Bash 调用先设 Shell 工具参数 `dangerouslyDisableSandbox=true`；拒绝权限时停止。Checkout 原样执行返回的 `present_files` action，打开渲染后的 Card Link。 |
 | `kimi-code` | `terminal` | 使用标准 CLI 流程和终端展示，不增加 Kimi 专属命令。 |
 | `openclaw` | 无 | 必须显式提供当前入口；Telegram 使用原生 action，其他入口展示标准二维码和链接。 |
 

package/docs/cli-reference/commands/order.md

@@ -91,4 +91,4 @@ itpay services list --json
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 返回完全相同的订单事实、instruction 和 next。`order` 是状态读取命令，不构造二维码、Markdown handoff 或 Host renderer 数据。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 返回完全相同的订单事实、instruction 和 next。`order` 是状态读取命令，不构造二维码、Markdown handoff 或 Host renderer 数据。

package/docs/cli-reference/commands/orders.md

@@ -82,4 +82,4 @@ itpay orders [--limit <n>] [--status <status>] [--json]
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 行为相同；只允许展示格式差异。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 行为相同；只允许展示格式差异。

package/docs/cli-reference/commands/pay.md

@@ -100,6 +100,8 @@ API 安全合同要求后端验证 display token 是该 Checkout 当前有效的
 | `codex-cli` | `terminal` | 只在用户可见终端展示渠道动作。 |
 | `claude-code-desktop` | `claude-code` | 把安全 handoff 发到当前桌面对话。 |
 | `claude-code-cli` | `terminal` | 只在用户可见终端展示渠道动作。 |
-| `workbuddy` | `plain-chat` | 受控逃生入口只返回一个可点击的 `handoff.url`；不得调用 `present_files`。展示后停止，不立即查询或创建替代付款。 |
+| `workbuddy` | `plain-chat` | 受控逃生入口返回 `handoff.url` 和可原样执行的 `present_files` action；打开一次后停止，不立即查询或创建替代付款。 |
+| `kimi-code` | `terminal` | 使用标准 CLI 终端展示渠道动作。 |
+| `openclaw` | 必须显式提供 | 按显式 Host 返回安全渠道动作；IM Host 仍要求真实 target。 |
 
 Host 只改变 instruction；Payment Intent ID、金额、状态、重试语义和权限必须一致。

package/docs/cli-reference/commands/readyz.md

@@ -45,7 +45,7 @@ itpay readyz [--json]
 
 ## 异常处理
 
-连接失败时返回 `backend_unavailable`，要求等待当前官方 Backend 恢复后重试同一完整命令，不得在失败时切换环境或继续下单。
+已收到 Backend 不可用响应等非传输异常时返回 `backend_unavailable`。尚未收到完整 HTTP 响应的临时传输失败使用 conventions 中对应的稳定 `network_*` 错误码；`readyz` 是 GET，按全局安全传输合同最多自动重试两次。两类错误都要求等待当前官方 Backend 恢复后重试同一完整命令，不得在失败时切换环境或继续下单。
 
 非官方 URL 返回 `backend_override_forbidden`，且不提供自动 recovery：
 

package/docs/cli-reference/commands/refund/get.md

@@ -64,4 +64,4 @@ CLI 不因为退款终态自行修改订单或 grant。
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 返回完全相同的退款事实、instruction 和 next。Host 不改变 Refund Owner 状态或访问锁。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 返回完全相同的退款事实、instruction 和 next。Host 不改变 Refund Owner 状态或访问锁。

package/docs/cli-reference/commands/refund/watch.md

@@ -72,4 +72,4 @@ Timeout 只表示本次 CLI 等待结束，不表示退款失败：
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 返回相同退款事实。Desktop 不会把每次无变化轮询发送到用户对话；Host 不改变 timeout 或退款状态。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 返回相同退款事实。Desktop 不会把每次无变化轮询发送到用户对话；Host 不改变 timeout 或退款状态。

package/docs/cli-reference/commands/services/checkout.md

@@ -14,10 +14,11 @@
 ```bash
 itpay services checkout <service_execution_id> --capability <capability_id>
   [--input <key=value> ...] [--email <delivery_email>]
-  [--host <host>] [--target <target>] [--qr-format <format>] [--qr-file <path>] [--json]
+  [--host <host>] [--target <target>] [--locale <zh-CN|en>]
+  [--qr-format <format>] [--qr-file <path>] [--json]
 
 itpay services checkout <service_execution_id> --resume
-  [--host <host>] [--target <target>] [--json]
+  [--host <host>] [--target <target>] [--locale <zh-CN|en>] [--json]
 ```
 
 创建时 `--capability` 必填。最终 locked input 必须满足 capability schema：显式输入来自 `--input`，服务端也可以按已发布 contract 从当前 Execution 的已批准 action 解析输入。解析后仍缺字段时，必须在创建 Quote、Cart 或 Checkout 前失败。只有 `delivery_email_required=true` 才要求 `--email`，并必须先向用户解释邮箱用于发送可 claim 的交付链接。`--resume` 复用同一个 Checkout 并轮换 handoff token，不再索取输入或邮箱。
@@ -81,14 +82,14 @@ itpay services checkout <service_execution_id> --resume
 | `codex-cli` | `handoff={url}`；普通文本模式在用户可见终端渲染二维码。 |
 | `claude-code-desktop` | `handoff={url,qr_local_path,markdown}`；把 `handoff.markdown` 原样发送到当前桌面对话。 |
 | `claude-code-cli` | `handoff={url}`；普通文本模式在用户可见终端渲染二维码。 |
-| `workbuddy` | `handoff={url}`；`url` 是完整渲染的 HTML Card Link。直接发送/打开并停止，不得调用 `present_files`、检查或生成本地文件。 |
+| `workbuddy` | `handoff={url,agent_action}`；原样执行一次 `present_files(files=[url])` 打开完整渲染的 HTML Card Link，然后停止；不得检查或生成本地文件。 |
 | `kimi-code` | `handoff={url}`；复用标准 CLI 终端展示。 |
 | `openclaw` | 必须显式传 Host；Telegram 还必须传 OpenClaw 原生 Target，并返回必须原样执行的 `message` action；其他入口返回标准 `url,qr_image_url`。 |
 
 WorkBuddy 的准确 instruction 语义必须完整包含：
 
 ```text
-Backend 尚未确认付款。向用户说明金额，直接发送并打开 handoff.url，然后停止等待。不要调用 present_files，不要检查本地文件，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。
+Backend 尚未确认付款。立即严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行一次，在右侧打开 handoff.url；确认工具调用成功后说明金额，然后停止等待。若工具失败，只发送原始 handoff.url，报告未自动打开并停止。不要用 present_files 打开本地文件或二维码 PNG，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。
 ```
 
 `--locale` 默认 `zh-CN`，可显式使用 `--locale en`。语言只影响 Card 渲染，不改变 Checkout、付款或恢复状态。

package/docs/cli-reference/commands/services/next.md

@@ -207,4 +207,4 @@ itpay services get <service_execution_id> --json
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 返回完全相同的状态、safe payload、instruction 和 next。本命令不渲染二维码，也不包含 Host handoff。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 返回完全相同的状态、safe payload、instruction 和 next。本命令不渲染二维码，也不包含 Host handoff。

package/docs/cli-reference/commands/services/quote.md

@@ -62,4 +62,4 @@ itpay services quote <service_execution_id> --capability <capability_id>
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 返回相同 Quote 事实、instruction 和 next。本命令不显示二维码；Agent Type 只作为设备与审计上下文，不改变价格或候选规则。
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 返回相同 Quote 事实、instruction 和 next。本命令不显示二维码；Agent Type 只作为设备与审计上下文，不改变价格或候选规则。

package/docs/cli-reference/commands/skill.md

@@ -1,4 +1,4 @@
-# `itpay skill show`
+# `itpay skill` / `itpay skill show`
 
 > **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
 
@@ -6,12 +6,26 @@
 
 读取 npm 包内置的完整 ItPay Agent Skill。与按 topic 渐进读取的 `docs` 不同，本命令故意一次返回完整 `SKILL.md`，用于首次 onboarding 和身份/session 规则恢复；不访问 Backend，不修改宿主配置或本地身份。
 
+`itpay skill` 只显示该命令组的帮助并退出，不读取 Skill 内容。
+
 ```bash
 itpay [--agent-type <agent_type>] skill show itpay [--json]
 ```
 
 当前只内置 `itpay`。该 Skill 是 Buyer 与未来 Seller 的共同入口，不再按角色拆分名称。`--json` 时完整 Markdown 位于 `result.content`；文本模式直接输出完整内容。
 
+```json
+{
+  "status": "shown",
+  "result": { "skill": "itpay", "content": "<complete_packaged_SKILL.md>" },
+  "instruction": "完整读取并遵守 Skill；先如实选择当前运行环境对应的 Agent Type。",
+  "next": { "command": "itpay install --json", "reason": "选择真实且稳定的 Agent Type" },
+  "recovery": []
+}
+```
+
+已声明 Agent Type 时 instruction 确认规范类型，`next.command` 保留该类型并指向 `catalog list --json`。除完整已发布 Skill 内容外，不得附加本地路径、安装目录、环境变量、Device 状态或 Backend 数据。
+
 未声明 Agent Type 时，`next` 是 `itpay install --json`。已声明时，`next` 是保留同一类型的 `catalog list --json`。未知名称返回 `skill_not_found`；包内文件缺失或损坏返回 `skill_unavailable` 并要求重装同版本 CLI。
 
 Skill 是操作和安全合同，不是服务端业务状态。执行时仍以每个命令当前 envelope 的 `result`、`instruction` 和 `next` 为准。

package/docs/cli-reference/conventions.md

@@ -82,6 +82,40 @@ next: <one command>
 - `provider_input_rejected` 只表示 Provider 明确声明输入无效；`provider_contract_mismatch` 表示响应无法按已发布契约解释，绝不能归咎于用户输入。两者都必须停止且没有自动 recovery。
 - `backend_contract_incompatible` 只有在 Backend 返回合法 `minimum_cli_version` 时才能提供升级 recovery。npm 分发返回精确的 `npm install -g @itpay/cli@<version>`；平台 bundle 返回该平台的 Skill/plugin 更新动作。不得使用 `latest`、解析 message 猜版本或继续任何业务命令；升级后必须先用 `itpay --version` 核对完全一致，再重新运行 `readyz`。
 
+## 网络传输失败与自动重试
+
+CLI 只把“尚未收到完整 HTTP 响应”的临时传输异常映射为稳定错误码：
+
+- `network_connection_reset`
+- `network_timeout`
+- `network_dns_temporary`
+- `network_unreachable`
+- `network_connection_refused`
+- `network_socket_error`
+- `network_transport_failed`
+
+所有命令的 JSON 错误继续使用标准错误外壳，并额外返回：
+
+```json
+{
+  "status": "error",
+  "error": { "code": "network_connection_reset", "message": "<bounded_transport_fact>" },
+  "result": { "attempts": 3, "automatic_retry_performed": true },
+  "instruction": "临时网络故障；CLI 已仅对可安全重放的操作完成有限自动重试，但仍未获得完整响应。按 recovery 查询同一资源的权威状态；不要创建替代 Checkout、Execution、Payment 或 Refund。",
+  "next": null,
+  "recovery": [{ "command": "itpay <same-resource-read-command>", "reason": "读取同一资源的权威状态" }]
+}
+```
+
+重试合同必须同时满足以下边界：
+
+- `GET`、携带稳定 `Idempotency-Key` 的写请求，以及 Backend 明确保证事务性安全重放的操作，使用短递增退避，最多自动重试两次（总共三次尝试）。
+- 不具备上述合同的写请求绝不自动重放；错误中为 `attempts=1`、`automatic_retry_performed=false`，Agent 必须先查询同一资源状态。
+- 每次尝试重新生成 Device 签名；不得复用过期时间、nonce 或 Authorization header。
+- 首次 Device enrollment、Agent Instance 登记或 session challenge/verify 在生成请求签名前发生。它们的传输失败同样映射为稳定 `network_*` 错误，但这些内部 POST 没有外层业务请求的安全重放合同，因此不自动重试，并返回 `attempts=1`、`automatic_retry_performed=false`。Agent 修复网络后重跑原始命令，由 Device Authority 从已持久化状态安全恢复。
+- `AbortSignal` 主动取消、证书/TLS 信任错误、已收到的 HTTP/业务错误和 Provider 业务失败不属于该重试。
+- 稳定输出不得包含 Node/Undici cause、socket、DNS 地址、请求 header、token、签名 URL 或 Provider 原始响应。
+
 ## Instruction 模板
 
 Instruction 只回答当前最重要的一件事：

package/docs/cli-reference/index.md

@@ -14,6 +14,16 @@
 - 所有 commerce 命令必须使用真实的 `--agent-type`，不得为刷新额度伪造类型。
 - 每条命令只返回当前步骤所需事实、一条 instruction、一个首选 next；异常时最多返回两个 recovery。
 
+## 根命令
+
+```bash
+itpay [--agent-type <agent_type>] [--version] [--help]
+```
+
+不带子命令时显示帮助并退出，不访问 Backend、不读取或修改业务状态。`--version` 只输出当前 CLI 版本；`--help` 只输出命令树。全局 `--agent-type` 必须放在子命令前，并由每个返回的 ItPay `next.command` / `recovery.command` 原样保留其规范值。
+
+Commander 自动提供的 `itpay help [command]` 与 `itpay <group> help [subcommand]` 只显示对应帮助，语义等同于在目标命令上使用 `--help`；它们不访问 Backend、不读写本地业务状态，也没有 JSON 输出合同。
+
 ## 命令目录
 
 ### 环境与发现
@@ -24,6 +34,7 @@
   - [`itpay catalog list`](commands/catalog/list.md)
 - [`itpay install`](commands/install.md) - 查看指定 Agent 的安装说明
 - [`itpay skill show`](commands/skill.md) - 一次读取完整内置 ItPay Skill
+- [`itpay device recover`](commands/device.md) - 仅恢复运营已确认重建的 Backend registration
 - [`itpay docs`](commands/docs/index.md)
   - [`itpay docs list`](commands/docs/list.md)
   - [`itpay docs show`](commands/docs/show.md)

package/docs/skill-bundle-rollout/02-platform-bundle-repositories.md

@@ -213,7 +213,9 @@ bundle 不包含凭据、.env、~/.itpay-v3 或 npm token
 
 ### Step 4：CLI 发布后创建同步 PR
 
-CLI 主仓库在 `main` 提供 reusable workflow。各平台仓库每小时错峰运行 caller workflow，并可手动触发；npm `dist-tags.latest` 或请求的 bundle format 与当前 `bundle.lock.json` 不同时更新。平台仓库自身的 `GITHUB_TOKEN` 写入本仓库，因此不需要跨仓 PAT，也不会在 CLI 发布失败时提前同步未发布版本。
+CLI 主仓库在 `main` 提供 reusable workflow。各平台仓库每小时错峰运行 caller workflow，并可手动触发；npm `dist-tags.latest` 或请求的 bundle format 与当前 `bundle.lock.json` 不同时更新。同步优先使用只安装到分发仓库、只拥有 Contents/Pull requests 写权限的 `itpay-bundle-sync` GitHub App 短期 token；未配置 App 时回落到平台仓库自己的 `GITHUB_TOKEN`，但该模式创建的 PR checks 需要仓库写权限用户批准。禁止使用个人 PAT。
+
+同步决策同时读取 main 和当前版本的 open automation PR。目标版本、format 和 bundle directory 已存在于 open PR 时必须返回 `pr-current`，不得每小时重建、提交或 force-push 同一产物。
 
 检测到新版本后：
 
@@ -221,8 +223,9 @@ CLI 主仓库在 `main` 提供 reusable workflow。各平台仓库每小时错
 - 更新 manifest 版本、lock、changelog；
 - 跑全套测试；
 - 对启用 Skill 差异跟踪的平台，比较旧、新 `sourceGitSha` 的中心 `skills/itpay/SKILL.md`；有差异时创建 Draft PR、附 diff 和人工合并清单，但不覆盖平台 Skill；
-- 创建或刷新 `automation/itpay-cli-X.Y.Z` 分支和同步 PR；
-- PR 描述列出 CLI commit、integrity、平台测试和是否需要商店重新审核。
+- 创建或刷新 `automation/itpay-cli-X.Y.Z` 分支和同步 PR；同版本的后续计划任务必须为 no-op；
+- PR 描述列出 CLI commit、integrity、dependency lock、同步 run、平台测试和是否需要商店重新审核；
+- 新版本 PR 验证成功后，只关闭没有人工提交的旧机器人同步 PR；保留远程分支用于审计和恢复。
 
 同步 workflow 只开 PR，不合并、不打 tag、不发布平台商店版本。
 

package/docs/skill-bundle-rollout/04-first-wave-platforms.md

@@ -21,7 +21,7 @@
 
 ## CLI 更新机制
 
-四个平台仓库每小时错峰检查 npm `@itpay/cli` 的正式版。发现版本高于各自 `bundle.lock.json` 后，调用 CLI `main` 上的统一 reusable workflow，重建对应格式的 bundle、运行仓库测试，并以平台仓库自己的 `GITHUB_TOKEN` 创建更新 PR。该流程不需要 PAT，也不会自动合并或发布商店版本。
+五个平台仓库每小时错峰检查 npm `@itpay/cli` 的正式版。发现版本高于各自 `bundle.lock.json` 后，调用 CLI `main` 上的统一 reusable workflow，重建对应格式的 bundle并运行仓库测试。更新 PR 优先由最小权限 `itpay-bundle-sync` GitHub App 创建；仓库未配置 App 时回落到 `GITHUB_TOKEN` 并明确要求人工批准 PR checks。该流程禁止个人 PAT，不会自动合并或发布商店版本，同一个 CLI 版本已有有效 open PR 时不会重复 force-push。
 
 ## 已发现的现有资产
 

package/docs/skill-bundle-rollout/05-sync-operations.md

@@ -0,0 +1,62 @@
+# Bundle 同步运维与事故处理
+
+## 正常状态
+
+每次同步必须在 Job Summary 中给出 published version、automation branch、同步决策、凭据模式、PR URL 和关闭的 superseded PR 数量。
+
+同步决策只有以下正常结果：
+
+- `base-current`：main 已经包含目标版本，无需更新。
+- `pr-current`：当前版本的 open PR 已包含正确 bundle，不得产生新 commit。
+- `update-required`：目标版本不存在，需要构建并创建 PR。
+- `open-pr-artifact-missing`：PR 分支缺少 lock，需要重新构建。
+- `open-pr-artifact-mismatch`：PR 中的 version、format 或 bundle directory 不符合 caller 合同，需要重新构建。
+
+## 失败分类
+
+### GitHub Actions 启动故障
+
+以下证据表示仓库代码没有运行：
+
+- run 的 `steps` 为空；
+- 失败发生在 `Set up job`；
+- `Failed to resolve action download info`；
+- Hosted Runner 长时间 queued 后被 cancelled 或 timed out。
+
+先查看 GitHub Status。官方确认恢复后重跑原 SHA；不得为了这种故障修改 bundle、测试或业务代码。
+
+### Bundle 构建或测试故障
+
+以下步骤失败才属于仓库或产物问题：
+
+- Resolve published version
+- Rebuild bundle
+- Inspect upstream Skill changes
+- Verify platform bundle
+
+保留失败分支和日志，不创建或更新 PR，不跳过 `npm test`。
+
+### `action_required`
+
+由 `GITHUB_TOKEN` 创建或更新的 PR workflow 会进入 approval-required 状态。这不是测试失败，但测试尚未执行。仓库写权限用户可以批准该 run；要求零人工同步时，必须配置最小权限 GitHub App，禁止使用个人 PAT。
+
+## 重跑规则
+
+1. 只重跑仍指向当前 head SHA 的基础设施失败。
+2. 新 commit 已存在时不重跑旧 SHA。
+3. 同一个版本第二次同步必须保持 automation PR head SHA 不变。
+4. 不把 cancelled、action-required 或旧 SHA 的 success 当作当前版本通过。
+
+## Superseded PR
+
+新版本 PR 建立并通过平台 `npm test` 后，可以关闭旧机器人同步 PR。自动关闭只允许处理带同步标记、分支符合 `automation/itpay-cli-X.Y.Z`、且所有提交均由 `itpay-bundle-bot` 产生的 PR。检测到人工提交时必须保留并在 summary 中提示。关闭时保留远程分支，不自动删除历史。
+
+## GitHub App 权限
+
+`itpay-bundle-sync` 只安装到分发仓库，权限限定为：
+
+- Metadata: read
+- Contents: read/write
+- Pull requests: read/write
+
+App 不需要 Actions、Secrets、Administration、Deployments 或 Packages 写权限。私钥只存于组织 Actions secrets，通过 reusable workflow 生成当前仓库、当前 job 有效的短期 token。

package/docs/skill-bundle-rollout/README.md

@@ -16,6 +16,7 @@
 - [任务二：多平台 Bundle Skill 仓库与同步](./02-platform-bundle-repositories.md)
 - [各平台制作、验证和上传手册](./03-platform-publishing.md)
 - [首批平台执行状态（2026-07-22）](./04-first-wave-platforms.md)
+- [Bundle 同步运维与事故处理](./05-sync-operations.md)
 
 ## 已确认的当前状态
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.0.24",
+  "version": "2.0.26",
   "description": "The single ItPay CLI entry point for buy workflows and future sell workflows.",
   "type": "module",
   "bin": {