@itpay/cli 2.1.19 → 2.1.22

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

@@ -1,6 +1,6 @@
 # `itpay checkout`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,10 +1,12 @@
 # `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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围
 
-`itpay device` 只显示该命令组的帮助并退出，不访问 Backend、不读取或修改身份。当前子命令是 `recover`（运营确认 Backend 重置后删除本地登记）和 `reset-key`（服务端拒绝当前私钥登记时放弃本地密钥）。
+`itpay device` 只显示该命令组的帮助并退出，不访问 Backend、不读取或修改身份。当前子命令是 `repair-lock`（检查并修复已退出进程留下的本地锁）、`recover`（运营确认 Backend 重置后删除本地登记）和 `reset-key`（服务端拒绝当前私钥登记时放弃本地密钥）。
+
+`itpay device repair-lock --json` 只检查本地锁，保留 Device identity；活跃锁返回 `device_lock_active`，过期锁修复后返回 `device_lock_recovered`，无锁返回 `device_lock_absent`。
 
 仅在运营明确确认当前 Backend 的 Device 登记数据库已重建或清空后，删除本地该 Backend 的 v2 registration：
 

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

@@ -1,6 +1,6 @@
 # `itpay docs`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 命令范围
 

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

@@ -1,6 +1,6 @@
 # `itpay docs list`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay docs search`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay docs 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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay install`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
@@ -121,7 +121,7 @@ OpenClaw 额外明确没有默认入口：
 | `codex-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
 | `claude-code-desktop` | `claude-code` | 桌面对话必须实际展示二维码和付款链接。 |
 | `claude-code-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
-| `workbuddy` | `plain-chat` | 会持久化 `~/.itpay-v3` 的 Bash 调用先设 Shell 工具参数 `dangerouslyDisableSandbox=true`；拒绝权限时停止。Checkout 原样执行返回的 `present_files` action，打开渲染后的 Card Link。 |
+| `workbuddy` | `plain-chat` | 为 `~/.itpay-v3` 申请正常持久化权限；拒绝时报告受阻操作。Checkout 原样执行返回的 `present_files` action，打开渲染后的 Card Link。 |
 | `zcode` | `plain-chat` | Checkout 或授权返回后立即用 ZCode 内置浏览器打开 `handoff.url`；只有浏览器不可用时才展示同一个可点击链接。 |
 | `doubao-work` | `plain-chat` | Checkout 或授权时同时展示 `handoff.url` 和 `handoff.qr_image_url` 两个有标签的官方入口；优先让手机直接打开链接，二维码供保存或另一台设备扫码。 |
 | `kimi-code` | `terminal` | 使用标准 CLI 流程和终端展示，不增加 Kimi 专属命令。 |

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

@@ -1,6 +1,6 @@
 # `itpay next`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay order`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay pay`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay readyz`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay refund cancel`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay refund create`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay refund get`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
@@ -48,7 +48,7 @@ itpay refund get <refund_request_id> [--json]
 ## 终态
 
 - `succeeded`：先告诉用户退款已由 ItPay 确认成功，交付永久关闭，`next=null`。
-- `cancelled/rejected`：说明退款没有执行，交付资格可恢复，但旧 grant 不复活，需要用户重新授权，`next=null`。
+- `cancelled/rejected`：说明退款没有执行，交付资格依当前订单和 owner 状态判断；旧 grant 不复活，按返回动作决定是否需要新的授权，`next=null` 时不自行创建。
 - `failed + known_no_effect`：说明退款请求确认未发送；Agent 不重试，由平台管理员决定是否重新执行，`next=null`。
 - `failed + retryable`：说明渠道明确返回可重试失败但 Agent 不会自行重试；等待平台管理员处理，`next=null`。
 - `failed + outcome_unknown`：说明渠道结果未知、交付继续锁定且必须先对账；禁止重试或重复申请，`next=null`。

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

@@ -1,6 +1,6 @@
 # `itpay refund`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 命令范围
 

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

@@ -1,6 +1,6 @@
 # `itpay refund list`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay refund watch`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay services action`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
@@ -36,7 +36,7 @@ itpay services action <service_execution_id> --action <action_type>
 | `workflow:expand_search` | 有界新增查询 | 仅在扩展暂停（`expansion_status=paused`）时可用；必须带服务端下发的 `action_request_id`（`pa_…`）与 `expected_query_revision`，一轮一柄、用完作废。 |
 | `workflow:refine_preferences` | 无（本地重排） | 用 `--input-json` 提交偏好补丁，对已保存证据重排序。 |
 | `workflow:stop_search` | 无 | 停止未发送的扩展任务；不影响已开始或已完成的出票。 |
-| `select_journey` | 无 | 记录用户选定：`--input journey_id=<rj_…>`；仅记录选择、不改排名，后续购买仍走既有报价与受保护 Checkout。 |
+| `select_journey` | 无 | 用户亲自选定用 `--actor-type human`；用户已明确委托按规则代选用 `--actor-type agent --input selection_mode=delegated`。两者都带服务端返回的 `journey_id`，仅记录选择，后续购买仍走既有报价与受保护 Checkout。 |
 
 同一 `action_request_id` 相同内容重放返回原受理结果；相同 ID 不同内容会被判冲突。过期 `expected_query_revision` 的新动作被拒绝。
 
@@ -68,4 +68,4 @@ rank 不存在、属于旧结果集或其他 Execution、action 不允许、stat
 
 ## Agent Type / Host
 
-所有正式支持的 Local Agent Type 行为相同。需要人确认时 instruction 必须明确“先询问用户”，不能因 Desktop Host 自动代替用户选择。
+所有正式支持的 Local Agent Type 行为相同。真实条款同意仍需人确认；在用户已明确委托选择且规则未变时，Agent 可执行返回的委托选择动作，不得冒充 human。

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

@@ -1,6 +1,6 @@
 # `itpay services checkout`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay services events`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay services get`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -11,7 +11,7 @@
 
 ## 核心不变量
 
-- 一个 Execution 表示一个独立服务意图；多个意图分别执行、分别交付，但各自的 Quote 可以进入同一 Cart。
+- Execution 的边界由服务合同决定；铁路查询和购票使用不同 Execution，已有执行的等待与恢复保持原 ID。其他独立服务分别执行，其 Quote 可进入同一 Cart。
 - 任何 capability 输入都必须在状态写入、锁价、订单创建和 Provider 调用前通过 schema 校验。
 - `invoke` 只运行当前阶段允许且不需付款的 Agent-visible capability。
 - 依赖候选的付费 capability 必须继续来源 Execution；`action --candidate` 不能跨 Execution 搬运候选。

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

@@ -1,13 +1,13 @@
 # `itpay services invoke`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
 调用当前 phase 允许的非付费 Agent-visible capability。输入先按 capability schema 校验，校验失败不得迁移 execution 或记录 Provider 已调用。
 
 **上游：** `services start/next` 明确返回 invoke。
-**下游：** 候选结果、人工 action 或付费 Quote。一次 invoke 没有结果或返回 Provider 错误时必须停止；只有用户之后明确提供新输入，才启动新的 execution。
+**下游：** 候选结果、人工 action 或付费 Quote。此页的候选人工选择示例适用于相应的非铁路服务；铁路按 `rail-booking` 的已保存结果和委托选择合同。Provider 错误先按实际错误码和当前 execution 状态恢复，不猜新输入或自动新建。
 
 ## 语法与参数
 
@@ -20,13 +20,7 @@ itpay services invoke <service_execution_id> --capability <capability_id>
 
 ## 有结果输出
 
-火车票目录：`items` 保留服务端返回的全部合格方案，不按推荐数量截断。
-`result.catalog` 带搜索覆盖范围、模型来源和推荐引用；`recommended=true` 的方案排在首位。
-本地 Agent 应先解释首推及不同取舍，用户不满意时可继续查看同一次返回的完整列表。
-智能规划返回 `verified_phone_required` 时，先完成 ItPay 网页手机号验证，不在 CLI 收集手机号、身份证或姓名。
-该错误发生在供应商调用和额度预占之前。
-本地验证环境中 CLI 会返回 `verification_url`，用户在该网页验证手机号并确认连接 Agent。
-完成后重试同一条 invoke；不在终端输入或回传手机验证码。
+以下是非铁路候选服务的示例。铁路使用 `services run` 和 `services read-result` 返回的范围、完整紧凑目录与当前动作；不要把这里的 `select_candidate` 人工动作套用到已授权委托的铁路选择。
 
 ```json
 {
@@ -161,5 +155,3 @@ Provider 已收到请求时，Backend 返回同一 Execution 的权威调用和
 ## Agent Type / Host
 
 所有正式支持的 Local Agent Type 的 safe result 一致。instruction 可以适配对话表述，但不得隐藏 quota、价格或 schema 错误。
-
-本地模拟购票阶段：用户选定候选后才提交选择，并使用 `services quote --capability book_ticket` 获取实时票款加每张 2 元服务费的锁定报价。精确查询需在报价输入中指定候选里可售的 `seat_type`；智能方案沿用所选席别。`pricing_method=rail_fare_plus_fee` 不代表总价 2 元。乘客资料仅在 Checkout 网页填写。本地出票结果明确标记 `simulation=true`，不表示真实出票。

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

@@ -1,6 +1,6 @@
 # `itpay services list`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

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

@@ -1,6 +1,6 @@
 # `itpay services next`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
@@ -16,18 +16,19 @@ Backend 会根据当前 capability 选择 `current_delivery`；完整 `delivery_
 ## 语法与参数
 
 ```bash
-itpay services next <service_execution_id> [--json]
+itpay services next <service_execution_id> [--timeout <seconds>] [--since-snapshot <snapshot_id>] [--json]
 ```
 
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
 | `service_execution_id` | 是 | `services start` 或后续命令返回的 execution ID。 |
+| `--timeout <seconds>` | 否 | 同一执行上的有界只读等待，0–120 秒，默认 0；查询等待中的推荐命令使用 120。已有业务结果、真实用户动作或终态会提前返回。 |
 | `--since-snapshot <snapshot_id>` | 否 | rail.progressive.v2 增量读：传上次看到的 `snapshot_id`，未变化时只回扩展状态与 `result_not_updated`，不重复下发 journey 负载；永远不触发供应商调用。 |
 | `--json` | 否 | 输出稳定 JSON 信封；未指定时输出相同事实的简洁文本。 |
 
 需要有效 Agent Device session。命令不接受 Buyer token、capability 或服务输入。
 
-## 候选选择
+## 非铁路服务的候选选择
 
 免费或付费候选已经产生、Arazzo workflow 允许继续选择时，恢复输出必须包含当前 Result Set 的安全候选：
 
@@ -49,9 +50,9 @@ itpay services next <service_execution_id> [--json]
 }
 ```
 
-该列表来自 Backend 的 `current_result_items`，CLI 不缓存或合并其他 Execution 的候选。
+该列表来自 Backend 的 `current_result_items`，CLI 不缓存或合并其他 Execution 的候选。铁路 Exact 的正常返回改走 `read-result` 已保存车次行及逐行 `detail.command`；Smart 的委托选票用 `select_delegated`（actor-type agent），只有用户亲自选定才用 `select_user_chosen`（actor-type human）。
 
-## Agent-visible 结果
+## 非铁路服务的 Agent-visible 结果
 
 ```json
 {
@@ -196,7 +197,7 @@ itpay services next <service_execution_id> [--json]
 }
 ```
 
-`succeeded` 退款改为“交付永久关闭”，并返回 `next: null`。取消、拒绝或确定未产生资金影响的失败退款不再阻塞，但旧 grant 不会复活；用户必须重新授权。
+`succeeded` 退款改为“交付永久关闭”，并返回 `next: null`。取消、拒绝或确定未产生资金影响的失败退款不再阻塞，但旧 grant 不会复活；是否需要新的交付授权由当前 owner 状态与返回动作决定。
 
 ## 额度暂停（试用/限流）
 
@@ -248,7 +249,7 @@ itpay services run itpay-rail-booking --input-json booking.json --json
 # booking.json: {"passengers": 1, "selection": {"token": "<selection_token>", "seat_type": "O"}}
 ```
 
-`booking_offer` 只是受条件约束的可选承接：查询完成本身已满足查询目标，不自动购买；过期 token 返回明确错误，恢复方式是按 `services run` 输入合同重新查询或显式提供 `legs`。
+`booking_offer` 只是受条件约束的可选承接：查询完成本身已满足查询目标，不自动购买。过期 token 不会因重读保存结果而恢复；按当前 owner 错误与用户原请求取得新的实时选择证据，不手工拼装 `legs` 绕过失效凭据。
 
 ## 订票确认（booking review）
 
@@ -267,7 +268,8 @@ itpay services run itpay-rail-booking --input-json booking.json --json
     "required_fields": ["draft_revision", "passengers", "seat_type", "seat_preferences", "party_preference", "fallback", "notice_version", "accept_non_guaranteed"]
   },
   "instruction": "向用户展示行程与可选席别/座位偏好词表，并明确告知：座位偏好仅为请求、不保证分配。收集后经 --input-json 提交完整 JSON；draft_revision 以服务端当前值为准。",
-  "next": { "command": "itpay services action <id> --action workflow:confirm_booking --actor-type human --status approved --input-json <file> --json", "reason": "提交用户确认后的行程确认/修订" },
+  "next": null,
+  "interaction": { "input_template": { "command": "itpay services action <id> --action workflow:confirm_booking --actor-type human --status approved --input-json <file> --json", "executable": false } },
   "recovery": [{ "command": "itpay services next <id> --json", "reason": "重新读取当前 draft_revision 后重试" }]
 }
 ```
@@ -299,5 +301,5 @@ itpay services get <service_execution_id> --json
 
 - `running`/`queued`：稍后按 `next.command` 增量轮询同一执行；不要重新发起查询。
 - `paused`：首批结果已就绪、扩展暂停等待用户意图；`expand_search` 是唯一会再消耗供应商配额的动作。
-- `complete`：扩展收敛；展示推荐并等待用户选票。
-- 选票走 `select_journey` 动作（命令在 `available_actions` 或卡片的 `select` 字段里，原样执行）；乘车人身份信息永远只在受保护 Checkout 页面填写。
+- `complete`：扩展收敛；比较任务已满足就展示推荐并停止，购买委托则按明确规则选择。
+- 选票走 `select_journey` 动作：卡片的 `select_delegated` 供已授权委托的 Agent 选择，`select_user_chosen` 仅用于用户亲自选定；乘车人身份信息永远只在受保护 Checkout 页面填写。

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

@@ -1,6 +1,6 @@
 # `itpay services page`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
@@ -9,7 +9,7 @@
 **上游：** `services run`、`services next` 返回的分页提示（`catalog_page.next_offset`）。  
 **下游：** 继续翻下一页，或在用户明确选择后用 `booking_offer` 承接购票。
 
-本命令不接受 Buyer token、capability 或服务输入，不返回原始 Backend DTO 之外的额外事实；Agent 不向用户暴露 `safe_payload`、Execution 或内部 ID。
+本命令不接受 Buyer token、capability 或服务输入；CLI 可把已有保存车次投影成便于比较的业务行和购买模板，不增加供应商事实。Agent 不向用户暴露 `safe_payload`、Execution 或内部 ID。
 
 ## 语法与参数
 
@@ -24,7 +24,7 @@ rail.progressive.v2 中 `<result_item_id>` 也可以是规划快照 ID（`rps_
 | `service_execution_id` | 是 | 产生该结果集的 Execution ID。 |
 | `result_item_id` | 是 | `services next` 或分页响应中的 `service_capability_result_item_id`。 |
 | `--offset` | 否 | 从零开始的候选偏移；默认 `0`，必须是非负整数。 |
-| `--limit` | 否 | 页大小，`1` 到 `20` 的整数；默认 `5`。 |
+| `--limit` | 否 | 页大小，`1` 到 `20` 的整数；默认 `20`。 |
 | `--json` | 否 | 输出稳定 JSON 信封；未指定时输出本页候选标题的简洁文本。 |
 
 需要有效 Agent Device session。
@@ -40,20 +40,22 @@ rail.progressive.v2 中 `<result_item_id>` 也可以是规划快照 ID（`rps_
     "service_execution_id": "<id>",
     "service_capability_result_item_id": "<item_id>",
     "offset": 0,
-    "limit": 5,
+    "limit": 20,
     "total": 63,
-    "count": 5,
-    "next_offset": 5,
+    "count": 20,
+    "next_offset": 20,
     "page": { "catalog_page": { "...": "..." }, "candidates": [ { "title": "<title>" } ] }
   },
   "instruction": "读取的是已保存结果的同版本分页，不重新查询、不消耗额度。用普通语言向用户说明本页候选；铁路应付与地面估算费用分开表述；不要提及 safe_payload、Execution 或内部 ID。",
-  "next": { "command": "itpay services page <id> <item_id> --offset 5 --json", "reason": "读取同版本结果的下一页" },
+  "next": { "command": "itpay services page <id> <item_id> --offset 20 --json", "reason": "读取同版本结果的下一页" },
   "recovery": []
 }
 ```
 
 `next_offset` 为 `null` 时 `next` 为 `null`；`offset > 0` 时 `recovery` 提供回到第一页的命令。页内候选可携带 `booking_offer`，承接方式与 `services next` 结果一致。
 
+铁路 Exact 对已保存的单条车次使用 `--offset <result_offset> --limit 1 --json`，返回 `exact_train_detail`、当前席别代码与名称、库存/报价事实和 `booking_template`。模板中的 `selection.token` 来自服务端，`seat_type` 只能选当前返回的可购代码；人数按用户需求填写。查询价格不等于锁价。
+
 ## 异常处理
 
 `--offset` 非负整数、`--limit` 必须在 `1`–`20` 内，否则在发起请求前返回 `offset_invalid` / `limit_invalid` 信封，不消耗服务端分页。execution 或 result item 不存在、不属于当前设备/账号时返回错误信封，并仅建议：

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

@@ -1,6 +1,6 @@
 # `itpay services quote`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

package/docs/cli-reference/commands/services/read-result.md

@@ -1,28 +1,28 @@
 # `itpay services read-result`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 
-使用当前 Agent Device Authority，在用户创建的有效、未过期且范围匹配的 grant 内读取 Vault 保护结果。它不适用于 `agent_visible_result`。
+同一命令读取三种已保存结果：铁路 Exact 车次页自动合并成紧凑业务行、铁路 Smart 快照完整紧凑车次目录，或持有效 grant 读取 Vault 保护内容。铁路读取免费、只读且不重新调用供应商。
 
-**上游：** `services next` 返回 `vault_artifact`，且用户已在订单页面授权。  
-**下游：** Agent 仅在 grant scope 和 TTL 内使用返回字段；没有自动后续命令。
+**上游：** 铁路查询的已保存结果入口，或 `services next` 返回 `vault_artifact` 且用户已在订单页面授权。
+**下游：** 铁路紧凑行中使用逐行 `detail.command` 读取购买条件；Vault 仅在 grant scope 和 TTL 内使用返回字段。
 
 ## 语法与参数
 
 ```bash
-itpay services read-result <service_execution_id> [--json]
+itpay services read-result <service_execution_id> [--snapshot <snapshot_id>] [--journey <journey_id>] [--json]
 ```
 
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
-| `service_execution_id` | 是 | Vault 交付对应的 execution ID。 |
+| `service_execution_id` | 是 | 铁路查询或 Vault 交付对应的 execution ID。 |
 | `--journey <journey_id>` | 否 | rail.progressive.v2 规划明细：读取指定 journey 的完整卡片（分段、席别报价、接驳估计、风险标注）。免费、属主校验、不触发供应商调用。 |
-| `--snapshot <snapshot_id>` | 否 | 与 `--journey` 配合，钉住某个已提交快照（`rps_…`）；缺省时读最新 catalog 快照。 |
+| `--snapshot <snapshot_id>` | 否 | 单独使用时读取该 Smart 已提交快照的完整紧凑目录；与 `--journey` 配合时读取一条完整卡片。 |
 | `--json` | 否 | 输出稳定 JSON 信封；未指定时输出相同事实的简洁文本。 |
 
-带 `--journey` 时走规划读取分支：不经过 grant/Vault、不受 `access_locked` 影响，因为规划明细本就是免付费证据。未带选择器时原授权路径完全不变。
+Exact 执行不带选择器时读取已保存全部车次，单次最多合并 100 条并给出明确续读位置。Smart 使用 `--snapshot` 读取固定快照，或用 `--journey` 读单程明细；这些读取不走 Vault grant。其他服务不带选择器时保持原授权路径。
 
 CLI 使用已登记设备的签名 session，不接受 Checkout token、Buyer token、`agent_device_id` 参数或开发者凭证。
 

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

@@ -4,7 +4,7 @@
 
 运行 Catalog 中已发布的通用 Buyer workflow。CLI 只提交服务声明要求的输入，并复用现有 Service Execution、Checkout、交付和退款命令；它不解释或执行 Seller 提供的任意命令文本。
 
-没有提供输入时，本命令创建一次 Execution，返回已发布的 JSON input schema，并要求 Agent 继续同一 Execution。已有 Execution 必须通过 `--execution` 恢复，不能创建替代 Execution。
+没有提供输入且未指定现有 execution 时，本命令创建一次 Execution，返回已发布的 JSON input schema，并要求 Agent 继续同一 Execution。已有 Execution 必须通过 `--execution` 恢复，不能创建替代 Execution。
 
 ## 语法与参数
 
@@ -93,7 +93,7 @@ itpay services run <service_id> --execution <execution_id> --json
 }
 ```
 
-`query_quota` 如实报告两类额度各自用量，一类为零不得宣称"四次全部用完"。第四次查询的结果先正常交付，下一次新查询才需要授权。
+`query_quota` 如实报告各查询服务自己的 `used`、`limit`、`remaining`。是否暂停只以本次服务端 `admission` 为准；已有结果先正常交付，不把另一服务的额度当作本次授权。
 
 登录绑定完成后，再次运行同一条 `services run <service> --execution <id> --json`（不带输入文件）：服务端重新读取当前设备绑定身份，被暂停的 Execution 从额度节点继续，不重放已成功的供应商调用，不要求重新输入。`failed`、`recovery_required` 或已完成付款的 Execution 不能以这种方式恢复。
 

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

@@ -1,6 +1,6 @@
 # `itpay services start`
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 范围与意义
 

package/docs/cli-reference/conventions.md

@@ -1,6 +1,6 @@
 # Output And Error Contract
 
-> **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.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. The same entry point supports Buyer workflows and the existing `itpay sell` Seller workflow.
 
 ## 目标
 
@@ -78,7 +78,7 @@ next: <one command>
 - 用户口头说“已付款”不是支付事实；仅服务端 `verified` 状态有效。
 - `agent_device_session_required` 只触发一次 session 续期和同请求重试；第二次失败必须返回，不得循环或换身份。
 - `device_state_unwritable` 表示当前运行环境不能可靠持久化 `~/.itpay-v3`；保持同一 Agent Type 与 CLI/Node launcher，恢复 Host 写权限后重试原命令，不得手工造 lock、删除身份或换运行时碰运气。
-- WorkBuddy 在运行会持久化 `~/.itpay-v3` 的 ItPay Bash 命令前，必须把 Shell 工具参数 `dangerouslyDisableSandbox` 设为 `true`。若用户拒绝该权限，命令尚未执行：停止并报告，不得切换 Node、删除 identity、手工处理 lock 或换 Agent Type。
+- WorkBuddy 需通过宿主的正常权限机制允许 CLI 持久化 `~/.itpay-v3`。若被拦截，报告受阻操作和宿主原因；不切换 Node、删除 identity 或猜测性处理活跃 lock。
 - `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`。
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@itpay/cli",
-  "version": "2.1.19",
+  "version": "2.1.22",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {
-    "itp": "bin/itp",
-    "itpay": "bin/itp",
-    "itpay_cli": "bin/itp"
+    "itp": "bin/itp.mjs",
+    "itpay": "bin/itp.mjs",
+    "itpay_cli": "bin/itp.mjs"
   },
   "main": "./dist/src/main.js",
   "exports": {
@@ -15,7 +15,9 @@
   "files": [
     "bin/",
     "dist/src/",
-    "docs/",
+    "docs/agent/buyer/",
+    "docs/cli-reference/",
+    "docs/sell.md",
     "skills/",
     "README.md",
     "LICENSE",