@itpay/cli 2.1.18 → 2.1.19

package/dist/src/commands/services.js

@@ -1,5 +1,6 @@
 import { HttpError } from "../client/http.js";
 import { HttpTransportError } from "../client/transport.js";
+import { DeviceLockBusyError, DeviceStateError } from "../state/device_authority.js";
 import { operationID, taskJournalPath } from "../state/config.js";
 import { TaskJournal } from "../state/task_journal.js";
 import { validateContext } from "../state/client_context.js";
@@ -544,7 +545,33 @@ export async function runServicesAction(backend, serviceExecutionID, actionType,
         request.result_item_id = resultItemID;
     if (options.requiredBefore)
         request.required_before = options.requiredBefore;
-    const response = await backend.recordServiceExecutionAction(serviceExecutionID, request);
+    let response;
+    try {
+        response = await backend.recordServiceExecutionAction(serviceExecutionID, request);
+    }
+    catch (error) {
+        if (error instanceof HttpError && ["booking_review_invalid", "booking_review_changed", "booking_review_locked"].includes(error.code)) {
+            throw new CommandContractError(error.code, error.message, error.code === "booking_review_invalid"
+                ? "确认输入与当前草稿不符。重新读取同一booking的review模板，席别使用返回的代码，不填显示名或猜新值。若仅修正代码写法，且车次、实际席别、人数、价格及条款等已确认内容未变，可沿用用户已有明确确认后提交；草稿实质变化或缺少真实同意时，先请用户确认变化内容。"
+                : error.code === "booking_review_changed"
+                    ? "草稿版本已变化；重新读取同一booking的当前review与revision，经用户核对后再提交。"
+                    : "当前购买已有付款尝试；读取同一booking及订单状态，不创建新订单或重做付款。", [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取同一booking的当前状态与review" }]);
+        }
+        throw error;
+    }
+    if ("state" in response) {
+        const updated = await backend.getServiceExecution(serviceExecutionID);
+        const envelope = servicesNextEnvelope(updated);
+        envelope.result = {
+            ...envelope.result,
+            planning_action: { action_id: response.action_id, state: response.state, replayed: response.replayed },
+        };
+        writeCommandEnvelope(envelope, {
+            ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+            ...(options.output ? { output: options.output } : {}),
+        });
+        return;
+    }
     if (selection && actionType === "select_candidate" && response.status === "approved") {
         const updated = await backend.getServiceExecution(serviceExecutionID);
         const preferred = updated.allowed_actions?.[0];
@@ -792,6 +819,7 @@ export async function runServicesGet(backend, serviceExecutionID, options = {})
     const lockedRefund = response.refunds.find((refund) => refund.access_locked);
     const nextState = servicesNextEnvelope(response);
     const result = {
+        ...nextState.result,
         service_execution_id: execution.service_execution_id,
         service_id: execution.service_id,
         status: execution.status,
@@ -809,13 +837,11 @@ export async function runServicesGet(backend, serviceExecutionID, options = {})
         } : {}),
     };
     const envelope = {
-        status: "shown",
+        status: nextState.status,
         result,
-        instruction: lockedRefund || isTerminalServiceExecutionStatus(execution.status)
-            ? nextState.instruction
-            : "时间线仅用于解释和恢复；按当前首选动作继续，不要重放已完成步骤。",
+        instruction: nextState.instruction,
         next: nextState.next ? { command: nextState.next.command, reason: "继续当前首选动作" } : null,
-        recovery: [{ command: `itpay services events ${serviceExecutionID} --json`, reason: "仅在需要完整诊断事件时使用" }],
+        recovery: nextState.recovery,
     };
     writeCommandEnvelope(envelope, {
         ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
@@ -843,7 +869,7 @@ export async function runServicesNext(backend, serviceExecutionID, options = {})
 }
 export async function runServicesPage(backend, serviceExecutionID, resultItemID, options = {}) {
     const offset = options.offset ?? 0;
-    const limit = options.limit ?? 5;
+    const limit = options.limit ?? 20;
     if (!Number.isInteger(offset) || offset < 0) {
         throw new CommandContractError("offset_invalid", "--offset must be a non-negative integer", "offset 必须是非负整数；本次未读取服务端分页。", [{ command: `itpay services page ${serviceExecutionID} ${resultItemID} --json`, reason: "从第一页重新读取" }]);
     }
@@ -873,11 +899,11 @@ export async function runServicesPage(backend, serviceExecutionID, resultItemID,
             next_offset: nextOffset,
             page,
         },
-        instruction: "读取的是已保存结果的同版本分页，不重新查询、不消耗额度。用普通语言向用户说明本页候选（车次、席别、时刻、费用口径），铁路应付与地面估算费用分开表述；不要提及 safe_payload、Execution 或内部 ID。",
+        instruction: "读取的是已保存结果的同版本分页，不重新查询、不消耗额度。先读完所需页，再合并回答用户；不要逐页播报。",
         next: nextOffset !== null
             ? { command: response.snapshot_id
-                    ? `itpay services page ${serviceExecutionID} ${resultItemID} --cursor rcur_${nextOffset} --json`
-                    : `itpay services page ${serviceExecutionID} ${resultItemID} --offset ${nextOffset} --json`,
+                    ? `itpay services page ${serviceExecutionID} ${resultItemID} --cursor rcur_${nextOffset} --limit ${limit} --json`
+                    : `itpay services page ${serviceExecutionID} ${resultItemID} --offset ${nextOffset} --limit ${limit} --json`,
                 reason: "读取同版本结果的下一页" }
             : null,
         recovery: offset > 0
@@ -958,10 +984,8 @@ export async function runServicesReadResult(backend, serviceExecutionID, options
                 query_revision: committed.query_revision,
                 catalog,
             },
-            instruction: "catalog 是本次查询的完整无损目录：journeys 为全部可行组合（含超出预览分页的组合），plans 是每个组合下的购票方案，stations/services/offers/ground_options 为共享字典，field_legend 解释紧凑字段。逐组合向用户说明车次、换乘与接驳取舍；席别与价格以 plans 内报价为准、下单前仍需核验；姓名身份证手机号只在 ItPay 网页填写。",
-            next: journeys.length > 0 && journeys[0]?.ref && journeys[0].ref !== "?"
-                ? { command: `itpay services read-result ${serviceExecutionID} --snapshot ${committed.snapshot_id} --journey ${journeys[0].ref} --json`, reason: "查看单个行程明细" }
-                : { command: `itpay services next ${serviceExecutionID} --since-snapshot ${committed.snapshot_id} --json`, reason: "返回规划进展" },
+            instruction: "catalog 是本次查询的完整已保存目录。按用户问题筛选全部journeys并一次回答；只有需要单程细节时才读取journey。价格和余票供比较，购买前须实时报价。",
+            next: null,
             recovery: [],
         }, {
             ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
@@ -1126,7 +1150,19 @@ function railJourneySummary(card, serviceExecutionID) {
                     command: `itpay services run ${card.booking_offer.service_id} --input-json <file> --json`,
                     required_input: ["file"],
                     executable: false,
-                    input_example: { selection: { token: card.booking_offer.selection_token, seat_type: "<席别>" }, passengers: "<n>" },
+                    seat_choices: (card.representative_offer?.ticket_offers ?? []).map((offer) => ({
+                        seat_type: offer.seat_type,
+                        seat_name: offer.seat_name,
+                    })).filter((seat) => typeof seat.seat_type === "string"),
+                    input_example: {
+                        selection: {
+                            token: card.booking_offer.selection_token,
+                            ...(typeof card.representative_offer?.ticket_offers?.[0]?.seat_type === "string"
+                                ? { seat_type: card.representative_offer.ticket_offers[0].seat_type }
+                                : {}),
+                        },
+                        passengers: card.passengers ?? 1,
+                    },
                 },
             }
             : {}),
@@ -1184,6 +1220,7 @@ function railPlanningEnvelope(model) {
         ...(plan.notices?.length ? { notices: plan.notices } : {}),
         ...(plan.recommendation ? { recommendation: railJourneySummary(plan.recommendation, se) } : {}),
         ...(cards.length ? { journeys: cards } : {}),
+        ...(plan.snapshot_id ? { full_result: { command: `itpay services read-result ${se} --snapshot ${plan.snapshot_id} --json`, meaning: "读取已保存的完整目录；推荐和journeys仅是摘要" } } : {}),
         ...(plan.available_actions?.length ? { available_actions: plan.available_actions } : {}),
     };
     const nextPoll = {
@@ -1245,7 +1282,7 @@ function railPlanningEnvelope(model) {
                 result,
                 // §7.3: the lead line carries real combination counts bucketed by
                 // verified transfer count — seat rows never inflate the journey count.
-                instruction: `${journeyMix ? `本次共${journeyMix}（席别不重复计数）。` : ""}${plan.search?.reason === "budget_exhausted" ? "本次查询已达到上限，以下是已查到的方案，搜索范围尚未全部核验。" : "本轮规划已完成。"}compare：解释首选及最多两个有意义备选的时间/费用/便利性取舍后等待用户选择。prepare_checkout：用户已明确委托按规则选择时，按 interaction.recipe 选合格者并继续到官方确认页，不再次问是否下单；身份、review和最终付款边界仍然生效。乘车人身份信息不在此收集，后续购买走受保护 Checkout。`,
+                instruction: `${journeyMix ? `本次共${journeyMix}（席别不重复计数）。` : ""}${plan.search?.reason === "budget_exhausted" ? "本次查询已达到上限，以下是已查到的方案，搜索范围尚未全部核验。" : "本轮规划已完成。"}推荐和journeys是摘要；追问其他车次先读取 full_result 的已保存完整目录。compare：解释首选及最多两个有意义备选的时间/费用/便利性取舍后等待用户选择。prepare_checkout：用户已明确委托按规则选择时，按 interaction.recipe 选合格者并继续到官方确认页，不再次问是否下单；身份、review和最终付款边界仍然生效。乘车人身份信息不在此收集，后续购买走受保护 Checkout。`,
                 next: journeys[0]?.booking_support === "single_leg"
                     ? { command: railJourneySummary(journeys[0], se).select, reason: "用户在 compare 后选定推荐行程时执行；prepare_checkout 且规则命中时用 select_delegated" }
                     : null,
@@ -1319,9 +1356,11 @@ function railPlanningEnvelope(model) {
             return {
                 status: expansion,
                 result,
-                instruction: `${modelDegradedHint}${failedPairsHint}${savedCatalog}${partial}本次规划已结束且不可续用；展示已有卡片后如需重查请用户确认后用同一服务新建执行。不要自动重新发起。`,
+                instruction: `${modelDegradedHint}${failedPairsHint}${savedCatalog}${partial}${expansion === "expired" ? "规划已过期，已保存目录仍可读取并回答历史结果追问；购买须重新核验实时余票与报价。" : "本次规划已结束，展示已有结果；需要新的供应商观测时再明确发起查询。"}`,
                 next: null,
-                recovery: [{ command: `itpay services events ${se} --json`, reason: "读取同一任务的处理记录" }],
+                recovery: plan.snapshot_id
+                    ? [{ command: `itpay services read-result ${se} --snapshot ${plan.snapshot_id} --json`, reason: "读取同一任务已保存的完整目录" }]
+                    : [{ command: `itpay services next ${se} --json`, reason: "读取同一任务当前状态" }],
             };
         }
         default: {
@@ -1593,14 +1632,22 @@ function servicesNextEnvelope(model) {
         const failedInvocation = recovery
             ? [...model.provider_invocations].reverse().find((item) => typeof item.status === "string" && item.status.startsWith("failed"))
             : undefined;
-        const errorDetail = typeof failedInvocation?.error_message === "string" && failedInvocation.error_message ? failedInvocation.error_message : undefined;
         const providerErrorCode = typeof failedInvocation?.error_code === "string" && failedInvocation.error_code ? failedInvocation.error_code : undefined;
+        const quoteFailure = execution.service_id === "itpay-rail-booking" ? {
+            quote_source_unavailable: "实时车票数据暂不可用；保留原选择，稍后按用户意愿重新核验，不创建替代订单。",
+            quote_train_changed: "所选车次的时刻或运行信息已变化；向用户说明并征询是否重新查票。",
+            quote_seat_changed: "所选席别已变化；向用户说明并征询新的席别选择。",
+            quote_seat_unavailable: "所选席别当前无足够余票；告知用户并由其决定是否换方案。",
+            quote_refresh_expired: "实时报价过程超时；保留原选择，不把旧价当可付款价格。",
+        }[providerErrorCode ?? ""] : undefined;
         const failedInstruction = recovery
-            ? failedStepGuidance
-                ? `执行在「${failedStepGuidance.meaning}」步失败：${failedStepGuidance.hint}${errorDetail ? `。供应商返回：${errorDetail}` : ""}。本执行已终止不能续用；修正后用同一服务新建执行重试，不要盲目重放。`
-                : state === "failed"
-                    ? `执行已失败${failedStep ? `（失败步骤：${failedStep}）` : ""}且不可续用；修正输入后用同一服务新建执行重试。`
-                    : "执行未完成，请按步骤错误处理；不要重建执行或重复调用。"
+            ? quoteFailure
+                ? quoteFailure
+                : failedStepGuidance
+                    ? `执行在「${failedStepGuidance.meaning}」步失败：${failedStepGuidance.hint}。本执行已终止不能续用；先核对原因，不要盲目重放。`
+                    : state === "failed"
+                        ? `执行已失败${failedStep ? `（失败步骤：${failedStep}）` : ""}且不可续用；修正输入后用同一服务新建执行重试。`
+                        : "执行未完成，请按步骤错误处理；不要重建执行或重复调用。"
             : undefined;
         return {
             status: state,
@@ -1612,7 +1659,7 @@ function servicesNextEnvelope(model) {
                 ...(guidance && state === "input_required" ? { guidance } : {}),
                 ...(failedStep ? { failed_step: failedStep, ...(failedStepGuidance ? { failed_step_meaning: failedStepGuidance.meaning } : {}) } : {}),
                 ...(providerErrorCode ? { provider_error_code: providerErrorCode } : {}),
-                ...(errorDetail ? { error_detail: errorDetail } : {}),
+                ...(providerErrorCode && !quoteFailure ? { diagnostic_code: providerErrorCode } : {}),
                 ...(recovery ? { retryable: state === "failed" } : {}),
             },
             instruction: failedInstruction
@@ -1638,7 +1685,7 @@ function servicesNextEnvelope(model) {
                     } : {}),
                 },
             } : {}),
-            recovery: recovery && state === "failed"
+            recovery: recovery && state === "failed" && !quoteFailure
                 ? [
                     { command: `itpay services start ${execution.service_id} --json`, reason: "修正输入后重新发起（本执行已终止不能续用）" },
                     ...(guidance ? [{ command: "itpay docs show rail-booking --json", reason: "查看本服务输入字段契约与示例" }] : []),
@@ -2092,12 +2139,12 @@ export async function runServicesRun(backend, config, serviceID, input, options
         const until = Date.now() + (options.timeoutSeconds ?? 120) * 1000;
         const sleep = options.sleep ?? ((milliseconds) => new Promise(resolve => setTimeout(resolve, milliseconds)));
         const paid = () => model.payment_bindings.some((binding) => binding.status === "payment_verified") || model.checkout_bindings.some((binding) => binding.status === "payment_verified");
-        // §7.2: for progressive services the committed rail_planning projection is
-        // itself a deliverable — return the same railPlanningEnvelope as soon as it
-        // exists instead of hiding every stage behind the 120s workflow poll. The
-        // owner keeps advancing in the background; the CLI returning early never
-        // cancels it.
-        while ((["queued", "running", "delivery"].includes(model.workflow?.status ?? "") || (model.workflow?.status === "payment" && paid())) && !model.current_delivery && !model.rail_planning && Date.now() < until) {
+        // A planning projection can exist before any usable result or user action.
+        // Keep the existing bounded wait until there is something to hand over.
+        const planningDeliverable = () => Boolean(model.rail_planning && (model.rail_planning.recommendation || model.rail_planning.alternatives?.length ||
+            ["complete", "paused", "failed", "cancelled", "expired"].includes(model.rail_planning.search?.expansion_status ?? "") ||
+            model.rail_planning.available_actions?.some((action) => ["select_journey", "expand_search"].includes(action.type))));
+        while ((["queued", "running", "delivery"].includes(model.workflow?.status ?? "") || (model.workflow?.status === "payment" && paid())) && !model.current_delivery && !planningDeliverable() && Date.now() < until) {
             await sleep(options.pollIntervalMS ?? 1500);
             model = await backend.getServiceExecution(id);
         }
@@ -2116,7 +2163,10 @@ export async function runServicesRun(backend, config, serviceID, input, options
         await runServicesNext(backend, id, options);
     }
     catch (cause) {
-        if (cause instanceof CommandContractError || cause instanceof HttpError)
+        if (cause instanceof HttpError && cause.code === "rail_seat_code_invalid" && id) {
+            throw new CommandContractError(cause.code, cause.message, "席别必须使用原查询 booking_template.seat_choices 中与名称对应的代码，不能填“二等座”等显示名。用原 selection token 与真实人数修正输入，继续同一booking execution；若只是代码写法修正且车次、席别名称、人数等购买条件未变，沿用用户已给的确认，不再重复询问。", [{ command: `itpay services next ${id} --json`, reason: "读取同一booking当前状态后修正输入" }]);
+        }
+        if (cause instanceof CommandContractError || cause instanceof HttpError || cause instanceof DeviceLockBusyError || cause instanceof DeviceStateError)
             throw cause;
         if (cause instanceof HttpTransportError && !id) {
             throw new CommandContractError("workflow_start_outcome_unknown", cause.message, "创建服务执行时没有收到完整响应。先查询当前身份可见的执行；不要直接重跑并创建替代执行。", [{ command: "itpay services list --json", reason: "查找可能已经创建的服务执行" }]);

package/dist/src/main.js

@@ -7,7 +7,7 @@ import { runServicesRun } from "./commands/services.js";
 // orchestrate; HTTP and rendering live in src/client and src/render.
 import { Command } from "commander";
 import { BackendOverrideError, CLI_VERSION, cliDistribution, loadConfig, cartSessionPath, newBackendClient } from "./state/config.js";
-import { DeviceAuthority, DeviceAuthorizationError, DeviceStateError } from "./state/device_authority.js";
+import { DeviceAuthority, DeviceAuthorizationError, DeviceLockBusyError, DeviceStateError } from "./state/device_authority.js";
 import { CartSession } from "./state/cart_session.js";
 import { defaultHostForAgentType, normalizeHost, validateContext } from "./state/client_context.js";
 import { HttpError } from "./client/http.js";
@@ -116,6 +116,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 lockError = error instanceof DeviceLockBusyError ? error : undefined;
     const transportError = error instanceof HttpTransportError ? error : undefined;
     const httpRecovery = errorRecoveryActions(error).map((action) => ({
         command: action.command,
@@ -154,24 +155,30 @@ function reportCLIError(error, contract) {
             command: "itpay skill show itpay --json",
             reason: "读取 Device 状态边界；修复当前 Host 的持久写权限后重试原命令",
         }] : [];
+    const lockRecovery = lockError ? [{
+            command: "itpay device repair-lock --json",
+            reason: "检查锁持有者；只回收已退出进程留下的锁，不改变设备身份",
+        }] : [];
     const authorizationInstruction = stateError
         ? "当前运行环境无法写入 owner-only Device 状态；请保持同一 Node、CLI 和 Agent Type，在允许持久写入 ~/.itpay-v3 的执行环境中重试。不要手工创建 lock、删除 identity 或换运行时碰运气。"
-        : error instanceof HttpError && error.code === "agent_device_session_required"
-            ? "CLI 已自动续期并重试同一请求一次，仍被拒绝；停止重试，不要切换 Agent Type 或旋转身份。"
-            : deviceError?.code === "agent_device_revoked"
-                ? "Backend 已撤销当前 Device 登记；CLI 没有自动创建替代身份。停止重试并请用户或运营恢复登记。"
-                : 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) {
+        : lockError
+            ? "另一个进程仍在更新本地身份。执行 recovery 检查；若持有者仍活跃，等待后继续原任务，不要删除锁或重建身份。"
+            : error instanceof HttpError && error.code === "agent_device_session_required"
+                ? "CLI 已自动续期并重试同一请求一次，仍被拒绝；停止重试，不要切换 Agent Type 或旋转身份。"
+                : deviceError?.code === "agent_device_revoked"
+                    ? "Backend 已撤销当前 Device 登记；CLI 没有自动创建替代身份。停止重试并请用户或运营恢复登记。"
+                    : 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 || lockError || stateError) {
         writeCommandEnvelope({
             status: "error",
             error: {
-                code: incompatible ? "backend_contract_incompatible" : backendOverrideError?.code ?? commandError?.code ?? (error instanceof HttpError ? error.code : transportError?.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 ?? lockError?.code ?? deviceError?.code ?? contract?.code ?? "command_failed"),
                 message: error instanceof Error ? error.message : String(error),
             },
             ...(requiredCLIVersion ? {
@@ -228,9 +235,9 @@ function reportCLIError(error, contract) {
                     : []
                 : backendInternal || providerConnectionUnavailable || providerTemporary || providerInputRejected || providerContractMismatch || providerRejected || capabilityInputInvalid
                     ? []
-                    : backendOverrideError ? [] : commandError?.recovery ?? (stateError ? stateRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
+                    : backendOverrideError ? [] : commandError?.recovery ?? (stateError ? stateRecovery : lockError ? lockRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
         }, {
-            ...(contract?.jsonOutput !== undefined ? { jsonOutput: contract.jsonOutput } : backendOverrideError ? { jsonOutput: process.argv.includes("--json") } : {}),
+            ...(contract?.jsonOutput !== undefined ? { jsonOutput: contract.jsonOutput } : backendOverrideError || lockError || stateError ? { jsonOutput: process.argv.includes("--json") } : {}),
             output: (text) => { process.stderr.write(text); },
         });
         process.exitCode = 1;
@@ -331,6 +338,30 @@ for (const action of ["login", "status"]) {
 }
 // --- device ---------------------------------------------------------------
 const deviceCmd = program.command("device").description("Recover the current official Backend registration after an operator-confirmed reset");
+deviceCmd
+    .command("repair-lock")
+    .description("Safely inspect and recover a local Device identity lock left by an exited process")
+    .option("--json", "output JSON instead of terminal text")
+    .action((options) => {
+    try {
+        const config = loadConfig();
+        const status = new DeviceAuthority({
+            baseURL: config.baseURL,
+            ...(config.agentType ? { requestedAgentType: config.agentType } : {}),
+            compatibilityHeaders: {},
+        }).repairLock();
+        writeCommandEnvelope({
+            status: status === "recovered" ? "device_lock_recovered" : status === "active" ? "device_lock_active" : "device_lock_absent",
+            result: { lock_status: status, device_identity_preserved: true },
+            instruction: status === "active" ? "本地身份正由存活进程更新；稍后继续原任务。" : "本地锁无需进一步处理；继续原任务。",
+            next: null,
+            recovery: [],
+        }, { jsonOutput: Boolean(options.json), plainResult: [`lock: ${status}`, "device_identity: preserved"] });
+    }
+    catch (error) {
+        reportCLIError(error, { jsonOutput: Boolean(options.json), code: "device_lock_repair_failed", instruction: "本地锁无法安全检查；保留设备身份并联系维护者。" });
+    }
+});
 deviceCmd
     .command("recover")
     .description("Forget only the current official Backend registration while preserving the local private key")

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.18";
+export const CLI_VERSION = "2.1.19";
 export const API_CONTRACT_REVISION = "sha256:2f9fbcdc5cd0630910abb52671304cc019e348e9a778017ec92ddc3513b3639f";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";

package/dist/src/state/device_authority.js

@@ -43,12 +43,25 @@ export class DeviceAuthority {
     }
     async ensureAuthorization() {
         if (!this.pending) {
-            this.pending = withFileLock(`${this.statePath}.lock`, () => this.prepareAuthorization()).finally(() => {
+            this.pending = this.cachedAuthorization() ?? withFileLock(`${this.statePath}.lock`, () => this.prepareAuthorization());
+            this.pending = this.pending.finally(() => {
                 this.pending = undefined;
             });
         }
         return this.pending;
     }
+    cachedAuthorization() {
+        const agentType = this.requestedAgentType;
+        if (!agentType)
+            return undefined;
+        const state = this.readState();
+        const registration = state?.registrations[this.backendKey];
+        const session = registration?.sessions[agentType];
+        if (!registration?.agentInstances[agentType] || !session || Date.parse(session.expiresAt) <= Date.now() + 60_000)
+            return undefined;
+        const privateKey = this.readPrivateKey();
+        return privateKey ? Promise.resolve({ state: registration, agentType, session, privateKey }) : undefined;
+    }
     async recoverAuthorization() {
         await withFileLock(`${this.statePath}.lock`, async () => {
             const state = this.readState();
@@ -61,6 +74,9 @@ export class DeviceAuthority {
             this.writeState(state);
         });
     }
+    repairLock() {
+        return inspectAndRecoverLock(`${this.statePath}.lock`);
+    }
     async recoverBackendReset() {
         return withFileLock(`${this.statePath}.lock`, async () => {
             const state = this.readState();
@@ -236,6 +252,7 @@ export class DeviceAuthority {
             method: "POST",
             headers: { "Content-Type": "application/json", Accept: "application/json", ...this.compatibilityHeaders, ...extraHeaders },
             body,
+            signal: AbortSignal.timeout(15_000),
         });
         const payload = await response.json().catch(() => ({}));
         if (!response.ok)
@@ -300,6 +317,13 @@ export class DeviceStateError extends Error {
         this.name = "DeviceStateError";
     }
 }
+export class DeviceLockBusyError extends Error {
+    code = "device_lock_busy";
+    constructor() {
+        super("ItPay device identity is being updated by another process");
+        this.name = "DeviceLockBusyError";
+    }
+}
 function emptyDeviceState() {
     return { schemaVersion: "itpay.device.v2", registrations: {} };
 }
@@ -344,9 +368,9 @@ async function withFileLock(path, run) {
     catch (error) {
         throw asDeviceStatePathError(error, "prepare_lock") ?? error;
     }
-    const ownerToken = randomUUID();
+    const ownerToken = `${process.pid}:${randomUUID()}`;
     let acquired = false;
-    for (let attempt = 0; attempt < 200; attempt += 1) {
+    for (let attempt = 0; attempt < 800; attempt += 1) {
         try {
             writeFileSync(path, ownerToken, { encoding: "utf8", flag: "wx", mode: 0o600 });
             chmodSync(path, 0o600);
@@ -357,20 +381,12 @@ async function withFileLock(path, run) {
             const code = error.code;
             if (code !== "EEXIST")
                 throw asDeviceStateError(error, "acquire_lock") ?? error;
-            try {
-                if (Date.now() - statSync(path).mtimeMs > 30_000)
-                    moveLockAside(path, "stale", "remove_stale_lock");
-            }
-            catch (statError) {
-                if (statError.code !== "ENOENT") {
-                    throw asDeviceStateError(statError, "inspect_lock") ?? statError;
-                }
-            }
+            inspectAndRecoverLock(path);
             await new Promise((resolve) => setTimeout(resolve, 25));
         }
     }
     if (!acquired)
-        throw new Error("timed out waiting for ItPay device identity lock");
+        throw new DeviceLockBusyError();
     try {
         return await run();
     }
@@ -378,6 +394,46 @@ async function withFileLock(path, run) {
         releaseLock(path, ownerToken);
     }
 }
+function inspectAndRecoverLock(path) {
+    let token;
+    let age;
+    try {
+        const lockStat = statSync(path);
+        age = Date.now() - lockStat.mtimeMs;
+        token = lockStat.isDirectory() ? "" : readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "absent";
+        throw asDeviceStateError(error, "inspect_lock") ?? error;
+    }
+    const ownerPID = /^(\d+):[0-9a-f-]+$/.exec(token)?.[1];
+    if (ownerPID) {
+        try {
+            process.kill(Number(ownerPID), 0);
+            return "active";
+        }
+        catch (error) {
+            if (error.code !== "ESRCH")
+                return "active";
+        }
+    }
+    else if (age <= 30_000) {
+        return "active";
+    }
+    // Recheck the exact owner before moving the lock; another process may have renewed it.
+    try {
+        if (token ? readFileSync(path, "utf8") !== token : !statSync(path).isDirectory())
+            return "active";
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "absent";
+        throw asDeviceStateError(error, "inspect_lock") ?? error;
+    }
+    moveLockAside(path, "stale", "remove_stale_lock");
+    return "recovered";
+}
 function releaseLock(path, ownerToken) {
     try {
         if (readFileSync(path, "utf8") !== ownerToken)

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

@@ -1,7 +1,7 @@
 {
   "schema_version": "itp.agent_doc.v1",
   "role": "buyer",
-  "product_scope": "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_scope": "itpay is the public CLI entry point for Buyer services and existing itpay sell Seller workflows.",
   "topic": "install-and-setup",
   "title": "Install And Identify The ItPay Agent Runtime",
   "purpose": "Select the real Agent Type, verify one official Backend, and load the packaged Skill through one linear setup path.",
@@ -32,7 +32,7 @@
     }
   ],
   "agent_rules": [
-    "Start with install, identify the current real runtime from result.agent_types, run itpay install <agent_type> --json yourself, and then execute each returned next.command unchanged until the Skill is loaded.",
+    "For first setup or a runtime change, identify the real Agent Type once, run itpay install <agent_type> --json yourself, and follow its setup continuation until the packaged Skill is loaded. Ordinary service requests start from the Skill's service command, without repeating install or readyz.",
     "After setup, tell the human only that ItPay is ready; never ask them to run setup commands or explain technical setup steps.",
     "Use the CLI distribution already provided by the current npm package, Skill, or plugin; update only through that distribution's own instructions.",
     "Production defaults to https://app.itpay.ai. Testing may set ITPAY_BACKEND_URL to the exact official URL https://sandbox.itpay.ai; no other Backend is allowed.",

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

@@ -13,9 +13,9 @@
     "A query returned login_required or rate_limited."
   ],
   "service_selection": {
-    "itpay-rail-exact": "Use when the buyer knows BOTH the exact departure and arrival railway station names (e.g. 古镇 → 广州南). It is one station-pair + one travel_date query: filter the returned list locally for remembered train numbers or time windows — do NOT re-query per train. Do NOT use it with only a city or fuzzy location.",
+    "itpay-rail-exact": "Use when both exact railway station names are known, or when a few credible station-pair hypotheses can be checked with exact (e.g. 古镇 → 广州南). It is one station-pair + one travel_date query: filter the returned list locally for remembered train numbers or time windows — do NOT re-query per train. Do not silently treat a city name as its station.",
     "itpay-rail-smart": "Use when the buyer has a city name, an area, an address, or wants transfer planning and recommendations. The platform resolves locations to stations itself; never silently convert a city into its namesake station.",
-    "itpay-rail-booking": "Purchase service — use ONLY after the buyer explicitly chose a train and seat from a query result. Starts quote → protected checkout → payment → asynchronous issuance on one execution. Never queried for schedules.",
+    "itpay-rail-booking": "Purchase service — use after the buyer chooses a train/seat or delegates selection under clear rules. Starts draft/review → live quote → protected checkout → asynchronous issuance on one execution. Never queried for schedules.",
     "svc_qizhidao_company_lookup": "Not a railway service; do not mix intents."
   },
   "input_contract": {
@@ -62,7 +62,7 @@
         "passengers": "Integer 1-5: number of passengers, NOT passenger identity records.",
         "selection": {
           "token": "The booking_offer.selection_token carried on the chosen result item.",
-          "seat_type": "Seat code when the user picked a specific class, e.g. O."
+          "seat_type": "Use the seat_type code shown with seat_name in the returned booking_template.seat_choices (e.g. O = 二等座); never submit the display name as the code. Omit this optional field when the returned offer has no code; never guess."
         }
       },
       "explicit_legs": {
@@ -74,10 +74,10 @@
   },
   "selection_flow": [
     "Exact results carry per-train candidates; smart results carry journeys. Bookable options carry booking_offer with a server-signed selection_token.",
-    "The token binds the stored result snapshot and the chosen option. Submit it with passengers (and seat_type when the user picked a class); the server derives the authoritative legs and re-quotes live. Do NOT hand-build legs JSON from the visible result.",
-    "An expired or foreign token returns a clear error; recover by running a fresh query or by explicit legs — never by guessing token contents.",
+    "The token binds the stored result snapshot and the chosen option. Submit it with passengers (and the exact seat_type code from booking_template.seat_choices when the user picked a class); the server derives the authoritative legs and re-quotes live. Do NOT hand-build legs JSON from the visible result. If only the code spelling is corrected and the confirmed train, actual seat class, passenger count, price, and terms remain identical, reuse the buyer's explicit approval. Material draft changes or missing approval require confirmation.",
+    "A historical selection identifies the original choice; booking refreshes current fare and inventory. A foreign buyer is rejected. Never guess token contents or hand-build legs as recovery.",
     "Repeating the same selection restores the same booking execution instead of creating a second one.",
-    "v2 single-leg cards carry an opaque rsel_ selection_token bound to owner, execution, query revision, snapshot, journey/offer, policy and expiry; a stale or foreign token returns selection_stale — re-read the snapshot for a fresh offer instead of retrying.",
+    "v2 single-leg cards carry an opaque rsel_ selection_token bound to the buyer and saved journey/offer. The original selection can enter booking after its search window expires; live quote determines whether that exact train and seat remain purchasable.",
     "v2 separate_legs_only journeys never carry a whole-journey token: open the journey detail, pick one leg, and use that leg's owner-issued booking_offer; each leg is quoted and confirmed independently with no joint guarantee."
   ],
   "trial_and_login": {
@@ -88,8 +88,7 @@
     "purchase_after_trial": "Selecting a saved option and buying it does not consume search quota and works even when trial is exhausted."
   },
   "flow": [
-    "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.",
+    "For a known railway service, submit input directly with services run <service> --input-json <file> --json; keep the returned execution for follow-ups.",
     "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. 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.",
     "Whether or not the query was free, the answer is the same shape under compare: one preferred option, at most two meaningful alternatives, the key trade-offs — then stop and wait for the buyer. Do not stack more options or chain into purchase.",
@@ -122,7 +121,7 @@
     "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.",
+    "Pick the service by the buyer's input precision: known stations or a few credible station-pair hypotheses → itpay-rail-exact; broader fuzzy locations → itpay-rail-smart; explicit purchase intent after a selection → itpay-rail-booking.",
     "Choose the goal first (see goals): compare presents one preferred option plus at most two meaningful alternatives then waits; prepare_checkout selects under the buyer's rules and continues to the official confirmation entry without re-asking.",
     "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.",
@@ -200,6 +199,6 @@
       "A pending/login/error state is never new intent; withdrawal updates the goal but never rewrites a completed payment.",
       "Neither goal authorizes payment or skips confirmation: payment, terms and passenger identity stay behind their own gates."
     ],
-    "recipe": "For the query→booking→review→checkout continuity after a valid selection, load the rail-fast-checkout topic (itpay docs show rail-fast-checkout --json)."
+    "recipe": "The Skill first screen describes query→booking→review→checkout. Load rail-fast-checkout only when the current response leaves a stage detail unclear."
   }
 }

package/docs/agent/buyer/rail-fast-checkout.json

@@ -21,7 +21,7 @@
     {
       "step": "start_booking",
       "command": "itpay services run itpay-rail-booking --input-json /tmp/itpay-booking-input.json --json",
-      "then": "itpay services next <execution_id> --json",
+      "then": "Use the booking run response directly; call its next only if it is still waiting for progress.",
       "expected_status": "booking_review_required"
     },
     {
@@ -33,13 +33,14 @@
       "notes": [
         "draft_revision must equal the current server value; booking_review_changed means re-read services next and resubmit, never bump locally.",
         "accept_non_guaranteed is true only when the buyer actually agreed; never fabricate a human approval.",
+        "On booking_review_invalid, re-read this booking. A seat-code spelling correction may reuse the buyer's explicit approval only if train, actual seat class, passenger count, price, and terms are unchanged; confirm material changes or missing approval.",
         "Passenger names, ID numbers and phones are NOT in this input — they belong to the protected checkout page."
       ]
     },
     {
       "step": "checkout_handoff",
-      "read": "services next returns checkout_required/payment_pending with handoff.url (the protected checkout page).",
-      "command": "itpay checkout --id <checkout_id> --token <display_token> --present auto --json",
+      "read": "The current booking response may already contain handoff.url (the protected checkout page).",
+      "command": "Only if the current handoff was not presented, use the exact checkout command returned by the CLI.",
       "notes": [
         "Show or open the checkout exactly once; pass --viewer mobile when the buyer is on a phone.",
         "The buyer completes identity and payment on that page (Path B — no forced separate login). Payment handoff is not payment success; wallet return is not confirmation."

package/package.json

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

package/skills/itpay/SKILL.md

@@ -13,12 +13,62 @@ Use the `itpay` CLI as the only ItPay control surface. Infer the human's goal,
 choose one first command, then follow each returned envelope. Run technology
 for the human; never ask them to run commands or learn internal concepts.
 
+## The Whole Trip
+
+ItPay finds services, runs them and delivers results. A known railway request
+starts with the railway commands below; use catalog only to discover an unknown
+service. Existing purchases resume from their original execution or order.
+Seller work uses `itpay sell`.
+
+Railway: understand date, places, time limits, passengers and purchase intent →
+query one station pair with exact, or plan uncertain places/routes with smart →
+select a matching offer → create booking draft → obtain genuine human review
+when required → refresh quote and hand over the official page → human pays →
+check issuance. A comparison stops at the query result. A delegated purchase
+continues until a required human step or the official handoff. Login and review
+are pause points; a draft, payment entry, paid order and issued ticket are
+different states.
+
+| Stage | Command shape | What comes back |
+| --- | --- | --- |
+| Query | `itpay services run itpay-rail-exact --input-json <query-file> --json` or `itpay-rail-smart` | Query execution, effective request, recommendation, saved snapshot and bookable selection |
+| Follow-up | `itpay services read-result <query-execution> --snapshot <snapshot> --json` | Full saved catalog; filter it for the new question before making another supplier query |
+| Booking | `itpay services run itpay-rail-booking --input-json <booking-file> --json` | Separate booking execution, draft and current review requirement |
+| Human review, if requested | `itpay services action <booking-execution> --action workflow:confirm_booking --actor-type human --status approved --input-json <review-file> --json` | Recorded confirmation and actual next step; approve only after real human consent, using the returned template |
+| Continue, if requested | `itpay services run itpay-rail-booking --execution <booking-execution> --json` | Fresh quote and official page, or the next required action |
+| After human payment | `itpay services next <booking-execution> --json` | Payment and issuance facts; report issuance only when confirmed |
+
+Create the JSON files yourself. Exact query needs `origin`, `destination`,
+`travel_date`; filter time limits against returned rows. Smart accepts those
+fields plus actual constraints such as `arrive_before`, `priority`, and
+`passengers`. Booking input uses the returned `selection.token`, selected
+`seat_type`, and passenger count; never assemble legs from prose. Copy the
+complete review template and revision from the current booking response.
+For `booking_review_invalid`, re-read that same booking. If only a seat code
+was written incorrectly and the confirmed train, actual seat class, passenger
+count, price, and terms are unchanged, reuse the buyer's explicit approval.
+Ask for confirmation if the draft materially changed or approval is missing.
+Keep the query execution/snapshot for follow-ups, selection for booking, and
+booking execution/order for review and payment. Do not substitute one ID for
+another. `result` is the current fact, `instruction` its meaning, `next` the
+current continuation, `handoff` the human entry, and `recovery` an exceptional
+path. `next: null` can mean comparison complete or a human/template pause.
+
+One exact comparison normally takes one query run. Chat review of a typical
+booking targets query run, booking run, review action, and sometimes one
+booking continuation before the official page; extra detail reads, login and
+location ambiguity add calls. This is a guide, never a reason to skip consent.
+You may test a few credible station-pair hypotheses with exact, reuse saved
+results, continue under an existing delegation, and combine missing facts in
+one question. Do not change date, relax a hard constraint, expand paid search
+or pay without authorization.
+
 ## Route The Human's Intent
 
 | Human intent | First action |
 | --- | --- |
 | Create, sell or publish a service | `itpay sell guide --json`, then `itpay sell status --json` |
-| Discover services or make a new query | `itpay catalog list --json` |
+| Discover an unknown service | `itpay catalog list --json` |
 | View previously purchased content | `itpay vault list --json` |
 | Find a previous result by subject | `itpay vault list --query <subject> --json` |
 | Inspect purchase history | `itpay orders --json` |
@@ -38,7 +88,7 @@ Three services, three different jobs — pick by the human's input, never merge
 | Human has | Service |
 | --- | --- |
 | Exact departure AND arrival station names | `itpay-rail-exact` (direct query) |
-| City/area/address, or wants transfer planning | `itpay-rail-smart` (location resolution + planning) |
+| Station pair or route is uncertain after a few credible hypotheses, or needs broad transfer planning | `itpay-rail-smart` (location resolution + planning) |
 | Chose a train/seat and wants to buy | `itpay-rail-booking` (quote → protected checkout → issuance) |
 
 ### Choose The Goal First
@@ -74,11 +124,8 @@ supports route hypotheses only, never same-day schedule/price/inventory facts.
 A saved snapshot's pages, journey detail and rerank are free reads; a new live
 observation needs the owner's authorization.
 
-After a valid selection under `prepare_checkout`, the short
-`rail-fast-checkout` recipe covers query→booking→review→checkout continuity:
-`itpay docs show rail-fast-checkout --json`. It reuses existing
-`services run`/`action`/`checkout` — no fast-buy command, no payment bypass,
-no fabricated human approval.
+Read the `rail-fast-checkout` topic only for a stage detail the current return
+does not explain. Continue from the original execution and current return.
 
 Query results carry a server-issued `booking_offer.selection_token` on bookable
 options; for a purchase submit that token plus passenger count — never
@@ -90,6 +137,11 @@ failure — resume the same execution after `itpay auth login`. For the full
 input contract and states, load the rail-booking topic via
 `itpay docs search rail-booking --json`.
 
+At checkout, an official login page can be the normal entry to traveler
+confirmation and then payment. Tell the human what the page currently asks
+them to do; do not call a draft a reserved ticket or a payment link a paid
+order. A seat preference may be requested but is not a seat guarantee.
+
 ## Follow One Envelope
 
 For each JSON response: