@itpay/cli 2.1.8 → 2.1.9

package/dist/src/commands/services.js

@@ -1095,6 +1095,17 @@ function servicesNextEnvelope(model) {
                     recovery: [],
                 };
             }
+            const review = action.context?.review;
+            if (review) {
+                return {
+                    status: "booking_review_required",
+                    result: { service_execution_id: id, service_id: execution.service_id, human_action: action,
+                        required_fields: requiredFields },
+                    instruction: "向用户展示 context.review 中的行程（legs）与可选席别/座位偏好词表（seat_options），并明确告知：座位偏好仅为请求、不保证分配（对应 notice_version 文案须经用户同意）。收集乘客人数、席别与每位乘客偏好后，按 required_fields 组装完整 JSON 对象，经 --input-json <file> 提交——draft_revision 必须等于服务端当前值，被拒绝（booking_review_changed）时重新读取后重试。乘客姓名/证件等身份信息不在此提交，仍走受保护 Checkout 页。",
+                    next: { command: `itpay services action ${id} --action ${action.action_type} --actor-type human --status approved --input-json <file> --json`, reason: "提交用户确认后的行程确认/修订" },
+                    recovery: [{ command: `itpay services next ${id} --json`, reason: "重新读取当前 draft_revision 后重试" }],
+                };
+            }
             return {
                 status: "confirmation_required",
                 result: { service_execution_id: id, service_id: execution.service_id, human_action: action },
@@ -1139,7 +1150,9 @@ function servicesNextEnvelope(model) {
             },
             instruction: failedInstruction
                 ?? (state === "payment"
-                    ? "服务已到付款步骤，使用现有 Checkout 完成扫码付款。"
+                    ? (model.workflow?.human_action?.context?.review
+                        ? "服务已到付款步骤，可直接 Checkout 付款；如需调整席别/座位偏好，先用 confirm_booking 动作修订（会重新报价并锁定新价），完成后再付款。"
+                        : "服务已到付款步骤，使用现有 Checkout 完成扫码付款。")
                     : guidance
                         ? "按 result.guidance 的字段契约填写输入后继续同一服务执行；不要臆造字段名。"
                         : "继续读取同一执行；缺少输入时按服务声明补齐。"),
@@ -1149,7 +1162,9 @@ function servicesNextEnvelope(model) {
                     { command: `itpay services start ${execution.service_id} --json`, reason: "修正输入后重新发起（本执行已终止不能续用）" },
                     ...(guidance ? [{ command: "itpay docs show rail-booking --json", reason: "查看本服务输入字段契约与示例" }] : []),
                 ]
-                : [],
+                : state === "payment" && model.workflow?.human_action?.context?.review
+                    ? [{ command: `itpay services action ${id} --action ${model.workflow.human_action.action_type} --actor-type human --status approved --input-json <file> --json`, reason: "付款前修订席别/座位偏好（draft_revision 以服务端为准）" }]
+                    : [],
         };
     }
     const terminalEnvelope = terminalExecutionEnvelope(model);

package/dist/src/main.js

@@ -1,6 +1,6 @@
 import { agentAuth } from "./state/account_auth.js";
 import { registerSell } from "./sell/commands.js";
-import { readFileSync as readWorkflowInputFile } from "node:fs";
+import { readFileSync as readWorkflowInputFile, statSync as statWorkflowInputFile } from "node:fs";
 import { runServicesRun } from "./commands/services.js";
 // V3 CLI entrypoint. Each command maps 1:1 to a route family in
 // services/backend/internal/httpapi/handlers/*.go. Commands only
@@ -137,10 +137,19 @@ function reportCLIError(error, contract) {
     const providerInputRejected = error instanceof HttpError && error.code === "provider_input_rejected";
     const providerContractMismatch = error instanceof HttpError && error.code === "provider_contract_mismatch";
     const capabilityInputInvalid = error instanceof HttpError && error.code === "capability_input_invalid";
-    const deviceRecovery = deviceError ? [{
+    const deviceKeyResettable = Boolean(deviceError && (deviceError.code === "agent_device_key_rotated" ||
+        deviceError.code === "agent_device_key_conflict" ||
+        (deviceError.enrollmentFailed && deviceError.status === 500)));
+    const deviceRecovery = deviceError ? [
+        {
             command: "itpay skill show itpay --json",
             reason: "读取 ItPay 身份边界；该错误需要用户或运营恢复 Backend 登记，不能通过换类型或删除本地身份绕过",
-        }] : [];
+        },
+        ...(deviceKeyResettable ? [{
+                command: "itpay device reset-key --confirm-key-reset --json",
+                reason: "服务端拒绝以当前私钥完成设备登记；生成全新 Ed25519 密钥并重新登记（旧设备身份在服务端保留为孤儿，不影响新身份和额度谱系）",
+            }] : []),
+    ] : [];
     const stateRecovery = stateError ? [{
             command: "itpay skill show itpay --json",
             reason: "读取 Device 状态边界；修复当前 Host 的持久写权限后重试原命令",
@@ -151,9 +160,13 @@ function reportCLIError(error, contract) {
             ? "CLI 已自动续期并重试同一请求一次，仍被拒绝；停止重试，不要切换 Agent Type 或旋转身份。"
             : deviceError?.code === "agent_device_revoked"
                 ? "Backend 已撤销当前 Device 登记；CLI 没有自动创建替代身份。停止重试并请用户或运营恢复登记。"
-                : deviceError
-                    ? "Device 身份验证失败；停止重试，不要切换 Agent Type、删除状态或旋转私钥。"
-                    : undefined;
+                : deviceKeyResettable && deviceError?.status === 500
+                    ? "服务端未能完成设备登记。先原样重试一次原命令：服务端会把已登记的同一公钥幂等挂回原设备。若仍返回 internal_error（Backend 未含该修复），执行 itpay device reset-key --confirm-key-reset 生成全新密钥后重试。"
+                    : deviceKeyResettable
+                        ? "服务端记录显示当前设备私钥已不再有效（已轮换或与既有登记冲突）。执行 itpay device reset-key --confirm-key-reset 生成全新密钥并重新登记。"
+                        : deviceError
+                            ? "Device 身份验证失败；停止重试，不要切换 Agent Type、删除状态或旋转私钥。"
+                            : undefined;
     if (contract || commandError || backendOverrideError) {
         writeCommandEnvelope({
             status: "error",
@@ -359,6 +372,53 @@ deviceCmd
         });
     }
 });
+deviceCmd
+    .command("reset-key")
+    .description("Discard the local Ed25519 device key and all Backend registrations so the next command enrolls as a new device")
+    .option("--confirm-key-reset", "confirm that the current device key must be abandoned and a new identity created")
+    .option("--json", "output JSON instead of terminal text")
+    .action(async (options) => {
+    const config = loadConfig();
+    try {
+        if (!options.confirmKeyReset) {
+            throw new CommandContractError("key_reset_confirmation_required", "--confirm-key-reset is required", "仅当服务端拒绝以当前私钥完成设备登记（internal_error、agent_device_key_rotated 或 agent_device_key_conflict）时使用；会放弃本地设备身份并重新登记，旧设备在服务端保留为孤儿。", [{ command: "itpay docs show identity-and-sessions --json", reason: "检查适用边界" }]);
+        }
+        const reset = await new DeviceAuthority({
+            baseURL: config.baseURL,
+            ...(config.agentType ? { requestedAgentType: config.agentType } : {}),
+            compatibilityHeaders: {},
+        }).resetDeviceKey();
+        writeCommandEnvelope({
+            status: "device_key_reset",
+            result: {
+                removed_backend_registrations: reset.removedBackends,
+                private_key_preserved: false,
+                server_side_device: "orphaned_under_previous_key",
+            },
+            instruction: "本地设备私钥已重置；下一次需要设备身份的命令会以全新 Ed25519 密钥重新登记并获得新的额度谱系。服务端旧设备记录保留为孤儿；如需清理请走运营流程。",
+            next: {
+                command: `itpay --agent-type ${config.agentType ?? "<agent_type>"} services list --limit 1 --json`,
+                reason: "用无业务写入的签名请求完成新密钥的重新登记",
+            },
+            recovery: [],
+        }, {
+            jsonOutput: Boolean(options.json),
+            plainResult: [
+                `removed_backend_registrations: ${reset.removedBackends.join(", ") || "none"}`,
+                "private_key: rotated (previous key discarded)",
+                "server_side_device: orphaned under previous key",
+            ],
+        });
+    }
+    catch (error) {
+        reportCLIError(error, {
+            jsonOutput: Boolean(options.json),
+            code: "device_key_reset_failed",
+            instruction: "仅在确认要放弃当前设备私钥时使用；普通 session 失效或 revoked 不需要本命令。",
+            recovery: [{ command: "itpay docs show identity-and-sessions --json", reason: "检查 Device 恢复边界" }],
+        });
+    }
+});
 // --- skill ----------------------------------------------------------------
 const skillCmd = program.command("skill").description("Read complete packaged Agent skills");
 skillCmd
@@ -1231,6 +1291,25 @@ vault
     }
 });
 // --- service execution ----------------------------------------------------
+const WORKFLOW_INPUT_JSON_MAX_BYTES = 256 * 1024;
+function readInputJsonObject(file, code, recovery) {
+    let parsed;
+    try {
+        if (statWorkflowInputFile(file).size > WORKFLOW_INPUT_JSON_MAX_BYTES) {
+            throw new CommandContractError(code, `--input-json file exceeds ${WORKFLOW_INPUT_JSON_MAX_BYTES} bytes`, "输入文件过大；只提交服务端 input_schema 声明的字段。", recovery);
+        }
+        parsed = JSON.parse(readWorkflowInputFile(file, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof CommandContractError)
+            throw error;
+        throw new CommandContractError(code, `--input-json is not readable valid JSON: ${error instanceof Error ? error.message : String(error)}`, "确认文件存在且为合法 JSON；按服务端 input_schema 字段填写。", recovery);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new CommandContractError(code, "--input-json must contain a JSON object", "确认输入必须是 JSON 对象；按服务端 input_schema 字段填写。", recovery);
+    }
+    return parsed;
+}
 const services = program.command("services").description("Generic V3 Service Execution commands");
 services
     .command("run")
@@ -1245,10 +1324,11 @@ services
     .action(async (serviceID, options) => {
     const config = loadConfig();
     try {
-        const input = options.inputJson ? JSON.parse(readWorkflowInputFile(options.inputJson, "utf8")) : undefined;
-        if (input !== undefined && (!input || typeof input !== "object" || Array.isArray(input))) {
-            throw new Error("input JSON must be an object");
-        }
+        const input = options.inputJson
+            ? readInputJsonObject(options.inputJson, "workflow_input_invalid", [
+                { command: `itpay services run ${serviceID} --json`, reason: "重新读取服务输入声明" },
+            ])
+            : undefined;
         if (!Number.isFinite(options.timeout) || options.timeout < 0 || options.timeout > 600) {
             throw new Error("timeout must be between 0 and 600 seconds");
         }
@@ -1362,12 +1442,18 @@ services
     .option("--result-item <service_capability_result_item_id>")
     .option("--required-before <step>")
     .option("--input <key=value>", "action input snapshot", collectOption, [])
+    .option("--input-json <file>", "JSON object containing the full action input snapshot")
     .option("--json", "output JSON instead of terminal text")
     .action(async (serviceExecutionID, options) => {
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        await runServicesAction(backend, serviceExecutionID, options.action, parseKeyValueList(options.input), {
+        const recovery = [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取当前动作要求" }];
+        if (options.inputJson && options.input.length > 0) {
+            throw new CommandContractError("service_action_invalid", "--input and --input-json cannot be combined", "--input 与 --input-json 只能二选一：嵌套结构用 --input-json <file>，扁平键值用 --input key=value。", recovery);
+        }
+        const fileInput = options.inputJson ? readInputJsonObject(options.inputJson, "service_action_invalid", recovery) : {};
+        await runServicesAction(backend, serviceExecutionID, options.action, { ...fileInput, ...parseKeyValueList(options.input) }, {
             ...(options.actorType ? { actorType: options.actorType } : {}),
             ...(options.actorId ? { actorID: options.actorId } : {}),
             ...(options.status ? { status: options.status } : {}),

package/dist/src/state/config.js

@@ -15,7 +15,7 @@ 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 SANDBOX_BASE_URL = "https://sandbox.itpay.ai";
-export const CLI_VERSION = "2.1.8";
+export const CLI_VERSION = "2.1.9";
 export const API_CONTRACT_REVISION = "sha256:66a95bbc5ec9d7b35747cf87206c63dd45983f26de21afab582d8dd63bf198f7";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";

package/dist/src/state/device_authority.js

@@ -73,6 +73,27 @@ export class DeviceAuthority {
             return { removed: true, agentTypes };
         });
     }
+    async resetDeviceKey() {
+        return withFileLock(`${this.statePath}.lock`, async () => {
+            const state = this.readState();
+            const removedBackends = state ? Object.keys(state.registrations).sort() : [];
+            // Delete the key first: if the process dies before the state write, the
+            // next run treats the missing key as a fresh install and completes the
+            // reset itself; it can never pair a new key with stale registrations.
+            if (existsSync(this.privateKeyPath)) {
+                try {
+                    unlinkSync(this.privateKeyPath);
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT") {
+                        throw asDeviceStateError(error, "remove_private_key") ?? error;
+                    }
+                }
+            }
+            this.writeState(emptyDeviceState());
+            return { removedBackends };
+        });
+    }
     async prepareAuthorization() {
         let state = this.readState() ?? emptyDeviceState();
         const agentType = this.requestedAgentType;
@@ -83,8 +104,14 @@ export class DeviceAuthority {
         if (!privateKey) {
             const pair = generateKeyPairSync("ed25519");
             privateKey = pair.privateKey;
-            this.writePrivateKey(pair.privateKey.export({ format: "pem", type: "pkcs8" }).toString());
+            // Persist an empty state before the new key ever reaches disk so a crash
+            // can never pair the new key with registrations bound to the old one.
+            // A crash between the two writes leaves either no key (fresh retry) or a
+            // key with no registrations (the backend re-attaches to the existing
+            // device instead of creating a duplicate).
             state = emptyDeviceState();
+            this.writeState(state);
+            this.writePrivateKey(pair.privateKey.export({ format: "pem", type: "pkcs8" }).toString());
         }
         let registration = state.registrations[this.backendKey];
         if (!registration && state.legacyRegistration) {
@@ -102,7 +129,21 @@ export class DeviceAuthority {
             registration = await this.enroll(agentType, privateKey);
         }
         state.registrations[this.backendKey] = registration;
-        const session = await this.ensureRegistrationAgentType(registration, agentType, privateKey, false);
+        let session;
+        try {
+            session = await this.ensureRegistrationAgentType(registration, agentType, privateKey, false);
+        }
+        catch (error) {
+            if (!isUnknownDeviceRegistration(error))
+                throw error;
+            // The backend lost this registration (e.g. its identity store was
+            // rebuilt). Drop the stale record and enroll once: the same key either
+            // re-attaches to the surviving device or creates a fresh one.
+            delete state.registrations[this.backendKey];
+            registration = await this.enroll(agentType, privateKey);
+            state.registrations[this.backendKey] = registration;
+            session = await this.ensureRegistrationAgentType(registration, agentType, privateKey, false);
+        }
         this.writeState(state);
         return { state: registration, agentType, session, privateKey };
     }
@@ -136,16 +177,23 @@ export class DeviceAuthority {
         if (!publicJWK.x)
             throw new Error("unable to export Ed25519 public key");
         const publicKey = Buffer.from(publicJWK.x, "base64url").toString("base64");
-        const started = await this.publicJSON("/v1/agent-device-enrollments", { public_key: publicKey, agent_type: agentType });
-        const proof = enrollmentProofMessage(started.agent_device_enrollment_id, started.challenge);
-        const verified = await this.publicJSON(`/v1/agent-device-enrollments/${encodeURIComponent(started.agent_device_enrollment_id)}/verify`, { challenge: started.challenge, signature: sign(null, Buffer.from(proof), privateKey).toString("base64") });
-        return {
-            deviceID: verified.agent_device_id,
-            deviceKeyID: verified.agent_device_key_id,
-            quotaLineageID: verified.quota_lineage_id,
-            agentInstances: { [verified.agent_type]: verified.agent_instance_id },
-            sessions: {},
-        };
+        try {
+            const started = await this.publicJSON("/v1/agent-device-enrollments", { public_key: publicKey, agent_type: agentType });
+            const proof = enrollmentProofMessage(started.agent_device_enrollment_id, started.challenge);
+            const verified = await this.publicJSON(`/v1/agent-device-enrollments/${encodeURIComponent(started.agent_device_enrollment_id)}/verify`, { challenge: started.challenge, signature: sign(null, Buffer.from(proof), privateKey).toString("base64") });
+            return {
+                deviceID: verified.agent_device_id,
+                deviceKeyID: verified.agent_device_key_id,
+                quotaLineageID: verified.quota_lineage_id,
+                agentInstances: { [verified.agent_type]: verified.agent_instance_id },
+                sessions: {},
+            };
+        }
+        catch (error) {
+            if (error instanceof DeviceAuthorizationError)
+                error.enrollmentFailed = true;
+            throw error;
+        }
     }
     async ensureSession(state, agentType, privateKey, force = false) {
         const existing = state.sessions[agentType];
@@ -233,6 +281,7 @@ export class DeviceAuthority {
 export class DeviceAuthorizationError extends Error {
     status;
     code;
+    enrollmentFailed = false;
     constructor(status, code, message) {
         super(message);
         this.status = status;
@@ -257,6 +306,9 @@ function emptyDeviceState() {
 function canMovePastLegacyRegistration(error) {
     return error instanceof DeviceAuthorizationError && (error.code === "agent_device_revoked" || error.status === 404);
 }
+function isUnknownDeviceRegistration(error) {
+    return error instanceof DeviceAuthorizationError && (error.code === "agent_device_not_found" || error.status === 404);
+}
 function normalizeBackendKey(value) {
     const url = new URL(value);
     url.search = "";

package/docs/agent/buyer/identity-and-sessions.json

@@ -7,7 +7,7 @@
   "purpose": "Explain stable local identity, official Backend-scoped registrations, Agent Type instances, and bounded automatic session recovery.",
   "when_to_use": [
     "A different Agent window or runtime starts using an existing CLI installation.",
-    "The CLI reports device_state_unwritable, or the Backend reports agent_identity_required, agent_device_session_required, or agent_device_revoked.",
+    "The CLI reports device_state_unwritable, or the Backend reports agent_identity_required, agent_device_session_required, agent_device_not_found, or agent_device_revoked.",
     "An operator confirms that the currently selected official Backend registration database was reset."
   ],
   "identity_model": {
@@ -21,7 +21,9 @@
     "On one HTTP 401 with code agent_device_session_required, it invalidates only the current Backend and Agent Type session, renews it, and retries the exact request once.",
     "A second failure is returned to the Agent. The CLI does not loop, switch Agent Type, rotate the key, or create a replacement v2 device.",
     "When a previously unseen Agent Type is registered under an existing Device, the CLI skips locally known Agent Instances that the Backend reports as revoked and uses the first remaining valid Instance. It never reactivates a revoked Instance or replaces the Device; if none is valid, registration stops.",
-    "A revoked v2 registration requires explicit operator recovery; it is never silently replaced."
+    "When the Backend reports agent_device_not_found (HTTP 404) for a locally known registration — for example after the Backend registration database was rebuilt — the CLI drops only that Backend's registration and re-enrolls once with the same private key, re-attaching to the same device and quota lineage where the Backend still holds the key.",
+    "A revoked v2 registration requires explicit operator recovery; it is never silently replaced.",
+    "Re-enrolling a public key the Backend already holds re-attaches to the existing device and quota lineage after proof-of-possession; it never creates a duplicate device. If enrollment verification keeps failing with internal_error, or returns agent_device_key_rotated or agent_device_key_conflict, `itpay device reset-key --confirm-key-reset` is the supported way to start over with a fresh key."
   ],
   "local_state_recovery": [
     "Device state updates use an atomic directory lock and owner-only atomic file replacement; no lock file is opened with fs.open or fs.openSync.",
@@ -44,6 +46,11 @@
       "intent": "recover after an operator-confirmed reset of the selected official Backend registration database",
       "command": "itpay --agent-type <agent_type> device recover --confirm-backend-reset --json",
       "success_signal": "only the selected Backend registration is removed and the private key and other Backend registration remain"
+    },
+    {
+      "intent": "abandon the local device key after the Backend refuses to complete enrollment with it (persistent internal_error, agent_device_key_rotated, or agent_device_key_conflict)",
+      "command": "itpay device reset-key --confirm-key-reset --json",
+      "success_signal": "the local private key is discarded and the next command enrolls as a brand-new device"
     }
   ],
   "agent_rules": [

package/docs/agent/buyer/rail-booking.json

@@ -26,7 +26,11 @@
         "travel_date": "Travel date in YYYY-MM-DD. The field name must be exactly travel_date; aliases like date are rejected."
       },
       "optional": "None. additionalProperties is false — extra fields are rejected by the provider.",
-      "example": {"origin": "古镇", "destination": "广州南", "travel_date": "2026-09-19"}
+      "example": {
+        "origin": "古镇",
+        "destination": "广州南",
+        "travel_date": "2026-09-19"
+      }
     },
     "itpay-rail-smart": {
       "required": {
@@ -44,7 +48,12 @@
         "priority": "One of balanced | fastest | cheapest | safest | flexible.",
         "max_transfers": "Integer 0-2, allowed transfer count."
       },
-      "example": {"origin": "中山古镇", "destination": "广州南", "travel_date": "2026-09-19", "priority": "fastest"}
+      "example": {
+        "origin": "中山古镇",
+        "destination": "广州南",
+        "travel_date": "2026-09-19",
+        "priority": "fastest"
+      }
     },
     "itpay-rail-booking": {
       "preferred": {
@@ -78,7 +87,8 @@
     "services start <service> --json returns input_required plus the guidance block for rail services.",
     "Submit input with services run <service> --execution <id> --input-json <file> --json on the SAME execution.",
     "itpay-rail-smart may stop at a location confirmation step; show the candidate places to the buyer, then continue the same execution after the human confirms.",
-    "After the buyer explicitly picks a train/seat, run itpay-rail-booking with the selection token (preferred) or explicit legs.",
+    "After the buyer explicitly picks a train/seat, run itpay-rail-booking with the selection token (preferred) or explicit legs. The execution then pauses at the booking review (workflow:confirm_booking): services next returns booking_review_required with human_action.context.review carrying draft_revision, legs, seat_options and notice_version.",
+    "Collect the review input and submit it with services action <id> --action workflow:confirm_booking --actor-type human --status approved --input-json <file> --json. Required fields: draft_revision (exact server value), passengers, seat_type, seat_preferences (one entry per passenger_index 0..n-1, values limited to that leg's seat_options), party_preference, fallback=automatic_assignment, notice_version, accept_non_guaranteed=true. Only after an accepted review does the server quote and offer checkout.",
     "The booking execution reaches a protected checkout: passenger identity data is entered by the human on that page, never through the CLI. Account authentication may happen inside checkout — do not force a separate auth login first (Path B).",
     "Payment success does not mean the ticket is issued. Issuance is asynchronous; keep reading the same execution with services next.",
     "If seat details are still syncing after issuance, advise the buyer to verify the itinerary on 12306 instead of repeating the query."
@@ -89,25 +99,67 @@
     "search": "Supplier query failed: most commonly a wrong field name (must be travel_date) or a nonexistent station name; recheck input against this doc.",
     "catalog_or_recommend": "Location resolved but no feasible trains: change the date or stations.",
     "login_required_is_not_failure": "login_required / rate_limited pause the execution; they are NOT failures and never justify a replacement execution.",
-    "general_rule": "Never replay a failed execution and never guess different field names; correct the input and start a new execution of the same service."
+    "general_rule": "Never replay a failed execution and never guess different field names; correct the input and start a new execution of the same service.",
+    "booking_review_changed": "The submitted draft_revision is stale: re-read services next for the current review projection and resubmit the full input; do not bump the revision yourself."
   },
   "seat_preferences": {
     "meaning": "A buyer's seat-letter preference may be planned per leg before payment. The plan is submitted to the supplier when encodable; unsupported combinations fall back to automatic assignment.",
     "letters": "Evidence-backed letters only: O=ABCDF (second class), M=ACDF (first class), 9=ACF (business class). Other layouts auto-assign.",
-    "boundary": "Never claim a preference was fulfilled before supplier confirmation; check the issued seat in the order/status output."
+    "boundary": "Never claim a preference was fulfilled before supplier confirmation; check the issued seat in the order/status output.",
+    "review_contract": "Submitted inside the confirm_booking action via --input-json (nested JSON; --input key=value cannot express it and must not be combined with it). One preference per passenger slot, passenger_index 0-based. draft_revision must equal the server projection; a stale revision returns booking_review_changed — re-read services next and resubmit, never increment locally.",
+    "revision": "While payment has not started, the same execution accepts a revised review: resubmit confirm_booking with the new draft_revision; the old unpaid quote/checkout is retired and re-quoted. After a payment attempt the review is closed — never create a replacement purchase."
   },
   "agent_rules": [
     "Pick the service by the buyer's input precision: exact station names → itpay-rail-exact; anything fuzzier → itpay-rail-smart; explicit purchase intent after a selection → itpay-rail-booking.",
     "Never invent input field names. If the guidance block or this doc does not list a field, do not send it.",
     "Never ask the buyer for passenger names, ID numbers, or phone numbers in chat; those are collected only on the protected checkout page.",
     "Never reconstruct provider-shaped legs JSON when a booking_offer.selection_token is available; submit the token plus passengers.",
+    "Seat preferences are requests, not guarantees: always repeat the notice that automatic assignment remains possible, and never claim a specific seat before the issued order shows it.",
+    "Take draft_revision only from the current services next review projection; on booking_review_changed re-read instead of retrying the stale value.",
     "login_required and rate_limited are pauses, not failures: resume the same execution, never spawn a replacement.",
     "Do not repeat or replay a failed execution; correct the input and start a new one.",
     "Do not claim payment equals ticket issuance; issuance is asynchronous and confirmed only by the issued seat status."
   ],
   "human_language": {
-    "prefer": ["车次", "出发站", "到达站", "出行日期", "座位", "余票", "出票中", "已出票", "登录后继续免费查询"],
-    "avoid": ["workflow", "execution", "provider", "seat_source", "candidate_id", "token", "quota"]
+    "prefer": [
+      "车次",
+      "出发站",
+      "到达站",
+      "出行日期",
+      "座位",
+      "余票",
+      "出票中",
+      "已出票",
+      "登录后继续免费查询"
+    ],
+    "avoid": [
+      "workflow",
+      "execution",
+      "provider",
+      "seat_source",
+      "candidate_id",
+      "token",
+      "quota"
+    ]
   },
-  "search_terms": ["rail", "railway", "train", "ticket", "火车", "火车票", "高铁", "车票", "车次", "seat", "booking", "rail-booking"]
+  "search_terms": [
+    "rail",
+    "railway",
+    "train",
+    "ticket",
+    "火车",
+    "火车票",
+    "高铁",
+    "车票",
+    "车次",
+    "seat",
+    "booking",
+    "rail-booking"
+  ],
+  "notifications": {
+    "channels": "Delivery notices reach the checkout-confirmed contact: email always works; a verified mainland SMS recipient is optional and checkout-scoped. The passenger phone, the login phone and the notification recipient are independent facts.",
+    "status_read": "The order read exposes masked per-leg notification entries (keys: issued, details_pending, seat_ready) with channel, status and masked recipient — never raw numbers.",
+    "truthfulness": "Provider acceptance is not delivery; an uncertain send outcome is reconciled, not silently retried. A notification failure never changes ticket or refund state; report it as a delivery detail, not an order failure.",
+    "unavailable": "If SMS is not configured or a recipient is unverified, email still satisfies the contact policy — never present an unverified phone as enabled."
+  }
 }

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

@@ -87,6 +87,7 @@ Terminal and error states:
 ## Rules
 
 - The human's phone number and SMS code are entered only on the official page — never through chat or CLI input. A `buyer_id`, a typed phone string, or a passenger phone is **not** proof of phone verification.
+- Verified email OR verified mainland phone both establish a valid login; the user picks on the page. Phone verification is not a prerequisite for registered free search — a verified email alone is sufficient.
 - Login never grants Vault content, passenger history, or another Agent's authority. Other devices/platforms enroll and authorize separately.
 - After `authenticated`, server-side identity is re-read; an anonymous execution blocked at the quota step resumes with `services run <service> --execution <id> --json` — no new execution, no re-asked itinerary.
 - Refusing or cancelling login deletes nothing: saved results and purchase options remain usable.

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

@@ -4,7 +4,7 @@
 
 ## 范围
 
-`itpay device` 只显示该命令组的帮助并退出，不访问 Backend、不读取或修改身份。当前唯一子命令是 `recover`。
+`itpay device` 只显示该命令组的帮助并退出，不访问 Backend、不读取或修改身份。当前子命令是 `recover`（运营确认 Backend 重置后删除本地登记）和 `reset-key`（服务端拒绝当前私钥登记时放弃本地密钥）。
 
 仅在运营明确确认当前 Backend 的 Device 登记数据库已重建或清空后，删除本地该 Backend 的 v2 registration：
 
@@ -24,6 +24,18 @@ Type 或执行 `device recover`；应保留身份并重试原命令一次，持
 
 缺少确认参数返回 `backend_reset_confirmation_required`。普通 session 失效由 CLI 自动续期；revoked、quota、权限或未知 Backend 故障不得使用本命令。所有 Agent Type 使用相同输入和输出合同。
 
+## `itpay device reset-key`
+
+仅在服务端拒绝以当前私钥完成设备登记时使用（登记阶段持续返回 `internal_error`，或返回 `agent_device_key_rotated` / `agent_device_key_conflict`）。这是本地操作，不访问 Backend：
+
+```bash
+itpay device reset-key --confirm-key-reset --json
+```
+
+命令删除本地 Ed25519 私钥并清空所有 Backend 的本地登记记录；下一次需要设备身份的命令会以全新密钥重新登记为新设备。服务端旧设备记录保留为孤儿，不会被删除或复用；原设备的额度谱系不迁移。先尝试普通重试——Backend 会把已验证私钥的重复登记幂等挂回原设备，只有在该修复不可用或私钥已被服务端轮换/冲突时才需要本命令。
+
+缺少确认参数返回 `key_reset_confirmation_required`；本地文件操作失败返回 `device_key_reset_failed`。本命令不得删除 Cart、operation journal 或 `~/.itpay-v3` 的其他内容。
+
 ## 参数
 
 | 参数 | 必填 | 说明 |

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

@@ -16,9 +16,15 @@ itpay services action <service_execution_id> --action <action_type>
   [--actor-type <actor_type>] [--actor-id <actor_id>]
   [--status <pending|approved|rejected|expired|cancelled>]
   [--candidate <rank> | --result-item <result_item_id>]
-  [--required-before <step>] [--input <key=value> ...] [--json]
+  [--required-before <step>] [--input <key=value> ...]
+  [--input-json <file>] [--json]
 ```
 
+| 选项 | 说明 |
+|---|---|
+| `--input <key=value>` | 逐项提交 action input；值可为 JSON 字面量（对象/数组/布尔/数字），可重复。 |
+| `--input-json <file>` | UTF-8 JSON 文件；顶层必须是 object，整体作为 action input；文件不超过 256 KiB。适合嵌套结构（如订票确认的 `seat_preferences`）。**与 `--input` 互斥**：同时给出时在发起请求前返回 `service_action_invalid`。文件不存在、非合法 JSON 或顶层非 object 同样在本地报结构化错误，不发生网络写。 |
+
 普通 Agent 优先使用 `--candidate <rank>`。CLI 只从当前 Execution 的 `current_result_items` 解析 Result Item ID；Backend 再读取权威 Invocation 和 Stable Hash。Agent 不提交 Hash，也不能使用其他 Execution 或外部来源的候选。`--result-item` 只用于已持有当前 Execution 内部句柄的受控恢复，不应要求用户提供。
 
 ## 标准输出
@@ -45,6 +51,8 @@ itpay services action <service_execution_id> --action <action_type>
 
 rank 不存在、属于旧结果集或其他 Execution、action 不允许、status 非法时均不写 action；返回结构化错误并且只引导同一 Execution 的 `services next`。不得新建 Execution、重新 invoke 或构造候选 ID。相同候选重试幂等；同一结果集改选另一个候选返回冲突，不覆盖已批准事实。
 
+订票类 `workflow:confirm_booking` 动作要求嵌套输入（`passengers`、`seat_type`、逐乘客 `seat_preferences`、`draft_revision`、`notice_version` 等），一律经 `--input-json <file>` 提交完整 JSON 对象。`draft_revision` 必须等于 `services next` 投影的 `context.review.draft_revision`；服务端拒绝 `booking_review_changed` 时重新读取后重试，不得自行递增。乘客姓名、证件号等身份信息不在此提交，仍由受保护 Checkout 页收集。
+
 ## Agent Type / Host
 
 所有正式支持的 Local Agent Type 行为相同。需要人确认时 instruction 必须明确“先询问用户”，不能因 Desktop Host 自动代替用户选择。

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

@@ -6,9 +6,11 @@
 
 为单个 Service Execution 快速创建或恢复 Checkout，并按 Host 向人交接付款入口。它是 `services quote -> cart add --quote -> buy --cart` 的单项快捷方式，必须复用相同的 Quote、Cart 和 Checkout Use Case。
 
-未注册/未登录用户不要求先执行 `itpay auth login`（Path B）：官方 checkout 页内完成必要的钱包认证、创建或复用账号并取得页面权限；人在页面上确认旅客、通知邮箱和最终报价后付款。支付确认沿用既有设备绑定机制，不再独立绑定。checkout 内完成账号认证不等于账号已通过手机号验证；钱包显示名、账号手机号与乘车人身份互相独立。
+未注册/未登录用户不要求先执行 `itpay auth login`（Path B）：官方 checkout 页内完成必要的钱包认证、创建或复用账号并取得页面权限；人在页面上确认旅客、通知联系方式和最终报价后付款。支付确认沿用既有设备绑定机制，不再独立绑定。checkout 内完成账号认证不等于账号已通过手机号验证；钱包显示名、账号手机号与乘车人身份互相独立。
 
-**上游：** `services next` 返回的 `prepare_quote` capability 和已验证输入。
+**通知联系方式（铁路单）：** 订单级联系策略要求至少一个可用通道——邮箱，或在 checkout 页内经验证的大陆手机号（order-contact 验证码只校验收件人，不创建/合并登录身份）。有效邮箱即可独立完成 checkout；SMS 不是必填项，SMS 能力未配置时不得阻塞邮箱通道。该策略仅适用于铁路订单，企知道等既有服务的联系策略不变。乘客证件手机号、账号登录手机号与通知收件人是三个独立事实，互不替代。
+
+**上游：** `services next` 返回的 `prepare_quote` capability 和已验证输入。铁路购票执行必须先通过 `workflow:confirm_booking` review（见 `services next` 的 `booking_review_required`），后端才生成可支付报价；review 开放期间不创建 Checkout。
 **下游：** 人完成 Checkout，随后 `checkout` 或 `services next`。
 
 ## 语法与参数

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

@@ -57,6 +57,8 @@ itpay services get <service_execution_id> [--json]
 
 `timeline` 只保留最近 20 个公开节点；超过时增加 `timeline_truncated: true`。它不返回 event ID 或 `redacted_summary`。交付存在时可增加 `delivery_mode`；退款锁存在时增加 `access_locked` 和退款 ID/status，并优先返回锁定 instruction。
 
+订票类 Execution 的 `workflow:confirm_booking` 待确认/待修订状态不在 timeline 中展开细节——行程、`seat_options` 与当前 `draft_revision` 一律通过 `services next` 的 `booking_review_required` 投影读取；`get` 只用于确认执行仍处于可继续状态。
+
 ## 异常处理
 
 默认不返回原始 events、Provider metadata、内部 bindings、Arazzo workflow、capability schema、candidate hash、client context 或完整 payload。需要完整但仍经服务端脱敏的事件时才运行 `services events`。

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

@@ -249,6 +249,35 @@ itpay services run itpay-rail-booking --input-json booking.json --json
 
 `booking_offer` 只是受条件约束的可选承接：查询完成本身已满足查询目标，不自动购买；过期 token 返回明确错误，恢复方式是按 `services run` 输入合同重新查询或显式提供 `legs`。
 
+## 订票确认（booking review）
+
+`itpay-rail-booking` 在报价前停在 `workflow:confirm_booking` 人工确认节点。`services next` 返回 `booking_review_required`，`human_action.context.review` 携带服务端投影：`draft_revision`、`legs`（含可编码的 `seat_options`）、`notice_version` 等。乘客身份信息永不在此投影，也不经 CLI 提交。
+
+```json
+{
+  "status": "booking_review_required",
+  "result": {
+    "service_execution_id": "<id>",
+    "service_id": "itpay-rail-booking",
+    "human_action": {
+      "action_type": "workflow:confirm_booking",
+      "context": { "review": { "draft_revision": 1, "legs": [], "seat_options": {} } }
+    },
+    "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": "提交用户确认后的行程确认/修订" },
+  "recovery": [{ "command": "itpay services next <id> --json", "reason": "重新读取当前 draft_revision 后重试" }]
+}
+```
+
+规则：
+
+- `seat_preferences` 逐乘客一条，`passenger_index` 从 0 起、人数 1–5、取值限该席别 `seat_options`；`party_preference`、`fallback=automatic_assignment`、`notice_version`、`accept_non_guaranteed=true` 全部必填。
+- `draft_revision` 必须等于投影值；服务端返回 `booking_review_changed` 时重新 `services next` 读取后重试，不得自行递增或重放旧 revision。
+- 付款暂停且 review 仍开放时，`next` 指向 Checkout 恢复，`recovery` 附带修订命令（`services action … confirm_booking --input-json`）——修订回到同一执行重新报价，不产生第二笔订单或付款。
+- 支付已在途/完成后 review 关闭，修订被拒绝；按返回的同一订单状态继续，不得新建执行。
+
 ## 异常处理
 
 execution 不存在或不属于当前设备/账号时返回错误信封，并仅建议：

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

@@ -21,7 +21,7 @@ itpay services run <service_id>
 | 参数 | 说明 |
 | --- | --- |
 | `service_id` | Catalog 返回的服务 ID。恢复时必须与 Execution 所属服务一致。 |
-| `--input-json` | UTF-8 JSON 文件；顶层必须是 object，并符合服务发布的 input schema。 |
+| `--input-json` | UTF-8 JSON 文件；顶层必须是 object，并符合服务发布的 input schema；文件不超过 256 KiB。文件不可读、非合法 JSON 或顶层非 object 时在本地报 `workflow_input_invalid`，不发生网络写。 |
 | `--execution` | 恢复同一 Execution。不得用它切换服务或绕过原状态。 |
 | `--timeout` | 本次等待 workflow 状态变化的秒数，默认 120，范围 0–600；超时只返回当前状态。 |
 | `--host` / `--target` | Host 展示上下文，不是业务输入或 Buyer 身份。 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.1.8",
+  "version": "2.1.9",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {