@itpay/cli 2.0.2 → 2.0.5

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

@@ -0,0 +1,68 @@
+# `itpay docs show`
+
+## 范围与意义
+
+读取一个指定 Agent 文档 topic。这是 docs 命令族中唯一返回完整文档内容的命令；不会级联读取其他 topic，也不访问 Backend。
+
+**上游：** `docs list` 或唯一匹配的 `docs search`。
+
+**下游：** 结合当前服务端状态，只执行文档中适用的一步。
+
+## 语法与参数
+
+```bash
+itpay docs show <topic> [--json]
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `topic` | 是 | `docs list/search` 返回的稳定、大小写敏感 topic。 |
+| `--json` | 否 | 把完整 topic 放进标准 envelope；推荐 Agent 使用。 |
+
+## JSON 输出
+
+```json
+{
+  "status": "shown",
+  "result": {
+    "topic": "<topic>",
+    "content": {
+      "schema_version": "itp.agent_doc.v1",
+      "topic": "<topic>",
+      "title": "<title>",
+      "purpose": "<purpose>"
+    }
+  },
+  "instruction": "只执行文档中与当前服务端状态匹配的步骤；服务端返回的当前 next 优先。",
+  "next": null,
+  "recovery": []
+}
+```
+
+`content` 示例仅显示必备头部；实际返回该 topic 的完整结构。非 JSON 模式打印 `shown`、完整 topic JSON 和同一条 instruction，不附加其他 topic。
+
+## 异常处理
+
+topic 不存在返回 `doc_not_found`：
+
+```json
+{
+  "status": "error",
+  "error": {
+    "code": "doc_not_found",
+    "message": "doc topic not found: <topic>"
+  },
+  "instruction": "使用稳定 topic 名称；不要根据标题猜 topic。",
+  "next": null,
+  "recovery": [
+    { "command": "itpay docs list --json", "reason": "列出全部 topic" },
+    { "command": "itpay docs search <topic> --json", "reason": "按关键词重新搜索" }
+  ]
+}
+```
+
+文档文件损坏使用 `docs_unavailable`，与 `docs list` 相同。
+
+## Agent Type / Host
+
+五种正式 Agent Type 使用同一 topic。topic 若包含多种 Host 指导，Agent 只采用与自身 Agent Type 和当前 Host 匹配的部分。

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

@@ -0,0 +1,112 @@
+# `itpay install`
+
+## 范围与意义
+
+读取当前 CLI 内置的 Agent Type 安装合同。它只说明 npm 安装、默认 API、默认 Host 和下一条验证命令；不修改宿主配置、不登记设备，也不调用 Backend。
+
+**上游：** 安装或更新 `@itpay/cli`。
+
+**下游：** 使用真实 Agent Type 执行 `readyz`，随后读取 Catalog。
+
+## 语法与参数
+
+```bash
+itpay install [target] [--json]
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `target` | 否 | 五种正式 Agent Type 之一；省略或传 `list` 时列出全部。Host 名称不是合法 target。 |
+| `--json` | 否 | 返回标准命令 envelope；推荐 Agent 使用。 |
+
+正式 target：`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`。
+
+## 指定 Agent Type 输出
+
+```json
+{
+  "status": "instructions_ready",
+  "result": {
+    "agent_type": "codex-desktop",
+    "default_host": "codex",
+    "default_api": "https://app.itpay.ai",
+    "install_command": "npm install -g @itpay/cli"
+  },
+  "instruction": "在 Codex Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
+  "next": {
+    "command": "itpay --agent-type codex-desktop readyz --json",
+    "reason": "验证 CLI 与默认 ItPay API 的兼容性"
+  },
+  "recovery": [
+    {
+      "command": "itpay docs show install-and-setup",
+      "reason": "查看环境覆盖和首次使用说明"
+    }
+  ]
+}
+```
+
+`result` 是客观安装事实；`instruction` 只解释当前 Agent Type 的展示责任；`next` 只有一条可执行验证命令。
+
+## 列表输出
+
+省略 target 或传 `list` 时返回五组 `agent_type/default_host`，不重复每种类型的完整 instruction：
+
+```json
+{
+  "status": "install_targets",
+  "result": {
+    "agent_types": [
+      { "agent_type": "codex-desktop", "default_host": "codex" },
+      { "agent_type": "codex-cli", "default_host": "terminal" },
+      { "agent_type": "claude-code-desktop", "default_host": "claude-code" },
+      { "agent_type": "claude-code-cli", "default_host": "terminal" },
+      { "agent_type": "workbuddy", "default_host": "plain-chat" }
+    ]
+  },
+  "instruction": "选择当前真实运行环境；同一 Agent 不要临时更换 Agent Type。",
+  "next": null,
+  "recovery": [
+    {
+      "command": "itpay docs show install-and-setup",
+      "reason": "查看安装与环境说明"
+    }
+  ]
+}
+```
+
+## Agent Type / Host
+
+| Agent Type | 默认 Host | instruction 重点 |
+| --- | --- | --- |
+| `codex-desktop` | `codex` | 桌面对话必须实际展示二维码和付款链接。 |
+| `codex-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
+| `claude-code-desktop` | `claude-code` | 桌面对话必须实际展示二维码和付款链接。 |
+| `claude-code-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
+| `workbuddy` | `plain-chat` | 当前使用通用会话交接，必须发送链接和可用图片。 |
+
+显式 `--host` 可以在后续 commerce 命令覆盖默认 Host，但不会改变 Agent Type 或设备归属。
+
+## 异常处理
+
+未知 target 返回：
+
+```json
+{
+  "status": "error",
+  "error": {
+    "code": "unsupported_agent_type",
+    "message": "unsupported install target: codex"
+  },
+  "instruction": "target 只接受：codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy。",
+  "next": null,
+  "recovery": [
+    {
+      "command": "itpay install --json",
+      "reason": "列出正式支持的 Agent Type"
+    }
+  ]
+}
+```
+
+错误不会写入本地状态。不要把 `codex`、`terminal` 或 `claude-code` 等 Host 名称当成 Agent Type。

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

@@ -0,0 +1,87 @@
+# `itpay next`
+
+## 范围与意义
+
+从本机保存的 canonical Cart、Checkout 或 Service Execution 句柄恢复一个首选动作。它是中断后的总入口，不替代具体资源的 `next/get`，也不读取或复制 Backend DTO。
+
+**上游：** 任意创建过 cart、checkout 或 execution 的 CLI 流程。
+**下游：** 返回的单一恢复命令。
+
+句柄优先级固定为：
+
+```text
+Service Execution -> Checkout -> Cart -> Catalog
+```
+
+一条 Service Execution 流程通常同时留下 Cart 和 Checkout 句柄；优先恢复最具体的 execution 可避免从旧 Cart 重建资源。
+
+## 语法与参数
+
+```bash
+itpay next [--json]
+```
+
+| 参数 | 必填 | 说明 |
+|---|---:|---|
+| `--json` | 否 | 返回标准 JSON。 |
+
+该命令只读本地 `0600` handle cache，不访问 Backend、不创建资源，也不要求 Buyer session。返回的下一条资源命令负责读取服务端权威状态。
+
+## 标准输出
+
+```json
+{
+  "status": "resume_available",
+  "result": { "resource_type": "service_execution", "resource_id": "<service_execution_id>" },
+  "instruction": "继续已有资源，不要创建重复订单或 Checkout。",
+  "next": { "command": "itpay services next <service_execution_id> --json", "reason": "读取服务端最新状态" },
+  "recovery": []
+}
+```
+
+Checkout 句柄返回：
+
+```json
+{
+  "status": "resume_available",
+  "result": { "resource_type": "checkout", "resource_id": "<checkout_id>" },
+  "instruction": "继续已有资源，不要创建重复订单或 Checkout。",
+  "next": {
+    "command": "itpay checkout --id <checkout_id> --token <display_token> --json",
+    "reason": "恢复同一 Checkout"
+  },
+  "recovery": []
+}
+```
+
+只存在 Cart 句柄时，`resource_type` 为 `cart`，下一步是 `itpay cart next --json`。
+
+没有本地句柄时：
+
+```json
+{
+  "status": "nothing_to_resume",
+  "result": {},
+  "instruction": "本地没有可恢复句柄；先读取已发布目录，不要猜测 service_id。",
+  "next": { "command": "itpay catalog list --json", "reason": "选择已发布服务" },
+  "recovery": []
+}
+```
+
+本地状态文件损坏或不可读时不静默猜测资源：
+
+```json
+{
+  "status": "local_state_invalid",
+  "result": {},
+  "instruction": "本地恢复句柄无法读取；不要猜测资源 ID，改从当前设备可见的服务执行恢复。",
+  "next": { "command": "itpay services list --json", "reason": "从服务端恢复当前设备可见的执行" },
+  "recovery": []
+}
+```
+
+若下一条资源命令发现服务端句柄已经失效，遵循该命令的结构化 recovery；不要修改本地文件或猜 ID。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 的状态、instruction 和下一步完全相同。本命令不产生二维码或 Host handoff。

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

@@ -0,0 +1,92 @@
+# `itpay order`
+
+## 范围与意义
+
+读取一笔当前 Buyer 或已绑定 Agent 可见的订单摘要、交付模式和退款访问锁。它不会返回受保护交付内容、Vault ID、内部 delivery artifact 或 Checkout token。
+
+**上游：** Checkout 完成、订单列表、邮件或 Service Execution 返回的 `order_id`。  
+**下游：** `services next`、退款状态查询，或等待同一订单继续推进。
+
+## 语法与参数
+
+```bash
+itpay order <order_id> [--host <host>] [--json]
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `order_id` | 是 | 订单 ID。 |
+| `--host <host>` | 否 | 兼容已有调用并校验 Host 名称；不改变订单事实或输出结构。 |
+| `--json` | 否 | 输出稳定 JSON 信封；未指定时输出相同事实的简洁文本。 |
+
+CLI 使用 Agent Device Authority。设备完成首次付款绑定后，已登记在同一 Buyer account 的 Agent Type 可读取该账号订单；未绑定设备不能借此获得 Buyer 权限。
+
+## 标准输出
+
+```json
+{
+  "status": "delivered",
+  "result": {
+    "order_id": "<order_id>",
+    "order_code": "<IP-code>",
+    "amount": "<amount> <currency>",
+    "delivery_mode": "vault_artifact",
+    "access_locked": false,
+    "service_execution_id": "<service_execution_id>"
+  },
+  "instruction": "根据 delivery_mode 使用对应读取入口；不要从订单摘要猜测受保护内容。",
+  "next": {
+    "command": "itpay services next <service_execution_id> --json",
+    "reason": "读取交付状态"
+  },
+  "recovery": []
+}
+```
+
+`delivery_mode` 当前为 `agent_visible_result` 或 `vault_artifact`，由 Delivery Owner 的 binding 返回，不从商品名或服务 ID 推断。文本输出依次显示同一组字段、instruction 和 next。
+
+订单尚未交付时可以暂不包含 `delivery_mode` 和 `service_execution_id`，并只建议稍后重查同一订单。
+
+## 退款访问锁
+
+退款锁生效时，退款状态优先于交付入口：
+
+```json
+{
+  "status": "delivered",
+  "result": {
+    "order_id": "<order_id>",
+    "order_code": "<IP-code>",
+    "amount": "<amount> <currency>",
+    "delivery_mode": "vault_artifact",
+    "access_locked": true,
+    "service_execution_id": "<service_execution_id>",
+    "refund": {
+      "refund_request_id": "<refund_request_id>",
+      "status": "accepted"
+    }
+  },
+  "instruction": "退款访问锁已生效；不要 reveal、创建 grant 或读取交付结果。",
+  "next": {
+    "command": "itpay refund get <refund_request_id> --json",
+    "reason": "读取退款的服务器状态"
+  },
+  "recovery": []
+}
+```
+
+退款为 `succeeded` 等终态时 `next` 为 `null`；CLI 不恢复旧 grant，也不自行解除锁。
+
+## 异常处理
+
+不存在和不属于当前账号的订单都返回不透明 `not_found`。错误 instruction 要求核对当前账号/Agent 绑定，唯一恢复入口是：
+
+```text
+itpay services list --json
+```
+
+不得通过 403/404 差异探测其他账号订单，也不得新建订单掩盖错误 ID。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 返回完全相同的订单事实、instruction 和 next。`order` 是状态读取命令，不构造二维码、Markdown handoff 或 Host renderer 数据。

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

@@ -0,0 +1,83 @@
+# `itpay orders`
+
+## 范围与意义
+
+列出当前 account-scoped Buyer session 可见的订单摘要，用于恢复订单，不返回交付 payload。
+
+**上游：** Buyer 登录并取得 account-scoped session。
+**下游：** `order <id>`。
+
+## 语法与参数
+
+```bash
+itpay orders [--limit <n>] [--status <status>] [--json]
+```
+
+| 参数 | 默认 | 说明 |
+|---|---:|---|
+| `--limit` | `20` | 最大订单数。 |
+| `--status` | 全部 | 可选：`pending_payment`、`paid`、`delivery_pending`、`delivered`、`failed`、`partially_refunded`、`refunded`、`cancelled`。 |
+| `--json` | 否 | 标准 JSON。 |
+
+`--limit` 必须是 `1..100` 的整数。命令固定使用最新优先排序，不暴露修改排序的参数。
+
+## 标准输出
+
+```json
+{
+  "status": "listed",
+  "result": {
+    "orders": [
+      {
+        "order_id": "<id>",
+        "order_code": "<IP-code>",
+        "status": "<status>",
+        "amount": "<amount> <currency>",
+        "created_at": "<RFC3339>"
+      }
+    ]
+  },
+  "instruction": "选择目标订单后读取详情；不要假设列表第一笔就是当前任务。",
+  "next": { "command": "itpay order <order_id> --json", "reason": "读取所选订单" },
+  "recovery": []
+}
+```
+
+订单列表不得包含 `checkout_id`、订单 items、交付 artifact、Vault ID 或交付 payload。无匹配订单时返回：
+
+```json
+{
+  "status": "no_orders",
+  "result": { "orders": [] },
+  "instruction": "当前账号没有符合条件的订单；不要猜测订单 ID。",
+  "next": null,
+  "recovery": [
+    { "command": "itpay services list --json", "reason": "恢复当前 Agent 设备可见的执行" }
+  ]
+}
+```
+
+## 异常处理
+
+结果按最新到最旧排列。缺少 Buyer session 时返回：
+
+```json
+{
+  "status": "error",
+  "error": {
+    "code": "session_required",
+    "message": "account-scoped Buyer session is required"
+  },
+  "instruction": "订单历史只对网页登录账号开放；不要伪造 Buyer token。Agent 可改为恢复当前设备绑定的 Service Execution。",
+  "next": null,
+  "recovery": [
+    { "command": "itpay services list --json", "reason": "恢复当前 Agent 设备可见的执行" }
+  ]
+}
+```
+
+无效 `--limit` 和 `--status` 必须在发起 HTTP 请求前返回 `limit_invalid` 或 `order_status_invalid`。Order-scoped session 返回服务端的 `account_scope_required`；CLI 不降级鉴权，也不要求 Agent 手工构造 Buyer token。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 行为相同；只允许展示格式差异。

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

@@ -0,0 +1,103 @@
+# `itpay pay`
+
+## 范围与意义
+
+为一个已存在的 Checkout 显式创建或刷新 Payment Intent。它只用于 Checkout 页面无法完成渠道动作时的受控集成恢复，不是普通 Buyer 流程。
+
+本命令不能创建 Cart、Checkout、订单或付款证明，也不能把 Payment Intent 的渠道状态当作订单已付款。
+
+**直接上游：** `buy`、`services checkout` 或 `checkout` 返回的同一组 `checkout_id` 与 display token。
+
+**直接下游：** `checkout` 读取同一 Checkout 的权威付款、订单和履约状态。
+
+## 语法与参数
+
+```bash
+itpay pay \
+  --checkout <checkout_id> \
+  --method <alipay|wechatpay> \
+  [--token <display_token>] \
+  [--refresh] \
+  [--host <host>] [--target <target>] [--json]
+```
+
+| 参数 | 必填 | 规则 |
+|---|---:|---|
+| `--checkout` | 是 | 已存在的 Checkout ID。 |
+| `--method` | 是 | 只接受 `alipay` 或 `wechatpay`；非法值不得回退为默认渠道。 |
+| `--token` | 条件必填 | 必须属于同一 Checkout。省略时只可恢复本机为该 Checkout 保存的 token。 |
+| `--refresh` | 否 | 为同一个非终态 Payment Intent 刷新渠道动作，不创建替代 Checkout。 |
+| `--host` | 否 | 默认由 `--agent-type` 推导，只影响 instruction。 |
+| `--target` | 条件必填 | 只有要求目标会话的 IM Host 需要。 |
+| `--json` | 否 | 输出紧凑机器合同。 |
+
+API 安全合同要求后端验证 display token 是该 Checkout 当前有效的 `checkout_entry` token。CLI 提交 token 不是安全边界；只有后端验证通过才允许创建或刷新 Payment Intent。
+
+## 标准输出
+
+### 渠道动作可用
+
+```json
+{
+  "status": "payment_action_ready",
+  "result": {
+    "checkout_id": "<checkout_id>",
+    "payment_intent_id": "<payment_intent_id>",
+    "payment": "waiting_user_payment",
+    "amount": "<amount> <currency>"
+  },
+  "handoff": {
+    "qr_image_url": "<optional_provider_qr>",
+    "mobile_wallet_url": "<optional_wallet_action>"
+  },
+  "instruction": "<host_specific_escape_hatch_instruction>",
+  "next": {
+    "command": "itpay checkout --id <checkout_id> --token <display_token> --json",
+    "reason": "读取同一 Checkout 的权威付款状态"
+  },
+  "recovery": []
+}
+```
+
+只返回 Agent 执行当前步骤所需的四个事实和安全渠道动作。不返回 Provider order ID、Payment Attempt、原始 Provider 响应、Checkout DTO 或重复 guidance。
+
+### 没有可展示动作
+
+`requires_action` 但响应没有二维码或钱包链接时返回 `payment_action_pending`，不生成虚假 handoff；下一步仍读取同一 Checkout。
+
+### 已确认或终态
+
+- `verified`、`partially_refunded` 返回 `payment_verified`，不再展示付款动作。
+- `failed`、`expired`、`refunded` 返回 `payment_unavailable`，不创建替代 Checkout。
+- 两者都只引导 `checkout --id ... --token ... --json` 读取服务端事实。
+
+## 重试与刷新
+
+- 数据库以 `(checkout_id, payment_method_type)` 作为 Payment Intent 业务唯一键。
+- 相同 Checkout 与 method 顺序重跑返回同一个非终态 Intent，不依赖客户端自报幂等键。
+- `--refresh` 只更新该 Intent 的渠道动作；不能创建第二个 Intent 或 Checkout。
+- 响应丢失时重跑同一命令，不换 token 或 method。
+
+## 异常处理
+
+| 错误码 | Agent 处理 |
+|---|---|
+| `payment_method_invalid` | 改用 `alipay` 或 `wechatpay`；本次没有 HTTP 请求。 |
+| `checkout_token_required` | 从 `itpay next --json` 恢复同一 Checkout；禁止拼接其他 token。 |
+| `target_required` | 为当前 IM Host 补充真实 target。 |
+| `not_found` / token invalid | 视为同一个不透明资源错误，不探测 Checkout 是否属于他人。 |
+| `invalid_state` | 回到 `checkout` 读取当前终态，不创建替代资源。 |
+| `provider_payment_failed` | 保留同一 Checkout，稍后恢复；不声称已付款。 |
+| `payment_intent_failed` | 执行 `itpay next --json` 恢复现有句柄。 |
+
+## Agent Type / Host
+
+| Agent Type | 默认 Host | Instruction |
+|---|---|---|
+| `codex-desktop` | `codex` | 把安全 handoff 实际发到当前 Codex 对话，然后查询 Checkout。 |
+| `codex-cli` | `terminal` | 只在用户可见终端展示渠道动作。 |
+| `claude-code-desktop` | `claude-code` | 把安全 handoff 发到当前桌面对话。 |
+| `claude-code-cli` | `terminal` | 只在用户可见终端展示渠道动作。 |
+| `workbuddy` | `plain-chat` | 把二维码或钱包链接发送到当前会话。 |
+
+Host 只改变 instruction；Payment Intent ID、金额、状态、重试语义和权限必须一致。

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

@@ -0,0 +1,39 @@
+# `itpay readyz`
+
+## 范围与意义
+
+检查当前配置的 ItPay API 是否可用。它只做环境诊断，不登记设备、不创建业务资源。
+
+**上游：** CLI 安装和 Backend URL 配置。
+**下游：** `catalog list` 或失败后的网络/配置修复。
+
+## 语法与参数
+
+```bash
+itpay readyz [--json]
+```
+
+| 参数 | 必填 | 说明 |
+|---|---:|---|
+| `--json` | 否 | 返回标准 JSON。 |
+
+## 标准输出
+
+```json
+{
+  "status": "ready",
+  "result": { "backend": "available" },
+  "instruction": "ItPay 可用，可以读取服务目录。",
+  "next": { "command": "itpay catalog list", "reason": "发现可用服务" },
+  "recovery": []
+}
+```
+
+## 异常处理
+
+连接失败时返回 `backend_unavailable`，要求核对 `ITPAY_BACKEND_URL` 后重试同一命令，不得继续下单。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 行为相同；本命令不渲染 Host 内容。
+

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

@@ -0,0 +1,62 @@
+# `itpay refund cancel`
+
+## 范围与意义
+
+在 Refund Owner 允许时取消 active refund。取消成功后释放访问锁，但不复活旧 Agent grant。
+
+**上游：** `refund get` 显示 `can_cancel=true`。
+**下游：** `order` 或重新进行用户授权。
+
+## 语法与参数
+
+```bash
+itpay refund cancel <refund_request_id> [--reason <reason>] [--json]
+```
+
+`--reason` 默认 `buyer_cancelled`。
+
+| 参数 | 必填 | 含义 |
+| --- | --- | --- |
+| `<refund_request_id>` | 是 | `refund create/get/watch` 返回的退款请求 ID |
+| `--reason <reason>` | 否 | 取消原因；默认 `buyer_cancelled` |
+| `--json` | 否 | 输出单个标准 JSON envelope |
+
+该命令使用当前设备的签名 Agent Device session。Refund Owner 会校验退款是否属于该设备已绑定的订单，并决定当前状态是否仍可取消；CLI 不自行释放访问锁。
+
+## 标准输出
+
+```json
+{
+  "status": "cancelled",
+  "result": { "refund_request_id": "<id>", "order_id": "<order_id>", "access_locked": false },
+  "instruction": "退款已取消；如需交付，重新进入订单并取得新的授权。",
+  "next": { "command": "itpay order <order_id> --json", "reason": "确认订单访问状态" },
+  "recovery": []
+}
+```
+
+不可取消时输出到 `stderr` 并以非零状态退出：
+
+```json
+{
+  "status": "error",
+  "error": {
+    "code": "refund_cancellation_too_late",
+    "message": "refund cancellation is too late"
+  },
+  "instruction": "取消未生效；以 Refund Owner 当前状态为准，不要重复退款或自行解除交付锁。",
+  "next": null,
+  "recovery": [
+    {
+      "command": "itpay refund get <refund_request_id> --json",
+      "reason": "读取当前权威状态"
+    }
+  ]
+}
+```
+
+出现 `not_found` 时同样只恢复到同一退款的 `refund get`，不借错误差异探测其他账号。取消成功只恢复重新申请交付授权的资格；旧 grant 永远不会复活。
+
+## Agent Type / Host
+
+`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 的业务字段、instruction 和 recovery 相同；该命令没有二维码或宿主渲染差异。