@itpay/cli 2.1.17 → 2.1.19

package/dist/src/commands/services.js

@@ -1,6 +1,8 @@
 import { HttpError } from "../client/http.js";
 import { HttpTransportError } from "../client/transport.js";
-import { operationID } from "../state/config.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";
 import { dispatchRender } from "../render/index.js";
 import { ensureIdeImageAttach } from "../render/ide.js";
@@ -16,6 +18,20 @@ import { renderTerminalQR } from "../render/qr.js";
 const RAIL_PROGRESSIVE_FEATURES = ["rail.progressive.v2"];
 import { buildCheckoutQRPlan } from "./buy.js";
 import { appendFeedbackPostmortemInstruction, CommandContractError, isTerminalServiceExecutionStatus, writeCommandEnvelope, } from "./guidance.js";
+// AUTH04: record the pause point of each Service Execution so a later
+// `itpay auth login` can resume the SAME task. Ids/stage/resume command only —
+// no chat content, PII or credentials. Best-effort: journaling never breaks
+// a command.
+function journalTaskState(serviceExecutionID, envelope, env) {
+    try {
+        const journal = new TaskJournal(taskJournalPath(env));
+        const serviceID = typeof envelope.result?.service_id === "string" ? envelope.result.service_id : undefined;
+        journal.observe(serviceExecutionID, envelope.status, serviceID ? `itpay services run ${serviceID} --execution ${serviceExecutionID} --json` : undefined);
+    }
+    catch {
+        /* local journal is advisory; never fail the envelope */
+    }
+}
 const serviceActionStatuses = new Set(["pending", "approved", "rejected", "expired", "cancelled"]);
 const RAIL_SERVICE_GUIDANCE = {
     "itpay-rail-exact": {
@@ -99,13 +115,29 @@ export async function runServicesStart(backend, serviceID, options = {}) {
     });
     if (response.workflow_entry) {
         const guidance = railServiceGuidance(serviceID);
-        writeCommandEnvelope({ status: "input_required", result: { service_execution_id: response.execution.service_execution_id, service_id: serviceID, input_schema: response.workflow_entry.input_schema, ...(guidance ? { guidance } : {}) }, instruction: guidance ? "按 result.guidance 逐项填写输入（when_to_use 说明本服务适用场景、input_fields 是必填契约、input_example 可直接照抄），然后继续同一服务执行。不要臆造字段名。" : "根据服务声明填写输入，然后继续同一服务执行。", next: { command: `itpay services run ${serviceID} --execution ${response.execution.service_execution_id} --input-json <file> --json`, reason: "提交买家输入" }, recovery: [] }, { ...options });
+        writeCommandEnvelope({
+            status: "input_required",
+            result: { service_execution_id: response.execution.service_execution_id, service_id: serviceID, input_schema: response.workflow_entry.input_schema, ...(guidance ? { guidance } : {}) },
+            instruction: guidance ? "按 result.guidance 逐项填写输入（when_to_use 说明本服务适用场景、input_fields 是必填契约、input_example 可直接照抄），然后继续同一服务执行。不要臆造字段名。" : "根据服务声明填写输入，然后继续同一服务执行。",
+            next: null,
+            interaction: {
+                schema_version: "itpay.interaction.v1",
+                stage: "input_required",
+                input_template: {
+                    command: `itpay services run ${serviceID} --execution ${response.execution.service_execution_id} --input-json <file> --json`,
+                    required_input: ["file"],
+                    executable: false,
+                },
+            },
+            recovery: []
+        }, { ...options });
         return;
     }
     const capability = response.capabilities.find((item) => item.phase === response.execution.phase && !item.requires_payment);
     const requiredInput = requiredInputFields(capability?.input_schema);
-    const command = capability
-        ? `itpay services invoke ${response.execution.service_execution_id} --capability ${capability.capability_id}${requiredInput.map((field) => ` --input ${field}=<value>`).join("")} --json`
+    const needsInput = requiredInput.length > 0;
+    const command = capability && !needsInput
+        ? `itpay services invoke ${response.execution.service_execution_id} --capability ${capability.capability_id} --json`
         : `itpay services next ${response.execution.service_execution_id} --json`;
     const capabilitySummary = capability ? {
         capability_id: capability.capability_id,
@@ -126,8 +158,19 @@ export async function runServicesStart(backend, serviceID, options = {}) {
             : "当前没有可直接调用的 capability；读取服务端下一步，不要猜测 capability。",
         next: {
             command,
-            reason: capability ? "执行当前允许的能力" : "读取服务端计算的下一步",
+            reason: capability && !needsInput ? "执行当前允许的能力" : "读取服务端计算的下一步",
         },
+        ...(capability && needsInput ? {
+            interaction: {
+                schema_version: "itpay.interaction.v1",
+                stage: "input_required",
+                input_template: {
+                    command: `itpay services invoke ${response.execution.service_execution_id} --capability ${capability.capability_id}${requiredInput.map((field) => ` --input ${field}=<value>`).join("")} --json`,
+                    required_input: requiredInput,
+                    executable: false,
+                },
+            },
+        } : {}),
         recovery: [],
     }, {
         ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
@@ -153,11 +196,19 @@ function locationConfirmationEnvelope(executionID, capabilityID, input, confirma
         result: { service_execution_id: executionID, query: input, location_confirmation: confirmation },
         instruction: "尚未查票。仅向用户确认 endpoints 中有歧义的地点，展示真实候选名称、地址和高德链接。不要自行选择候选、把区域改成车站或重复调用原查询。用户选择后保留原输入，带 location_confirmation 回到同一服务。没有候选时请用户补充已知城市或准确地名，再使用修正输入查询。",
         next: null,
-        recovery: confirmation.can_resume ? [{
-                command: `itpay services invoke ${executionID} --capability ${capabilityID}${formatInputOptions({ ...input,
-                    location_confirmation: { plan_id: confirmation.plan_id, token: confirmation.token, choices } })} --json`,
-                reason: "仅在用户明确选择后替换 choices 并执行；30 分钟有效",
-            }] : [],
+        ...(confirmation.can_resume ? {
+            interaction: {
+                schema_version: "itpay.interaction.v1",
+                stage: "location_confirmation_required",
+                input_template: {
+                    command: `itpay services invoke ${executionID} --capability ${capabilityID}${formatInputOptions({ ...input,
+                        location_confirmation: { plan_id: confirmation.plan_id, token: confirmation.token, choices } })} --json`,
+                    required_input: ["choices"],
+                    executable: false,
+                },
+            },
+        } : {}),
+        recovery: [],
     };
 }
 function requiredInputFields(schema) {
@@ -314,18 +365,33 @@ function invokedEnvelope(response, requestedCapability, capabilities, input) {
         }
     }
     else if (items.length > 0 && requestedCapability.requires_human_action) {
-        next = {
-            command: `itpay services action ${response.execution.service_execution_id} --action select_candidate --actor-type human --status approved --candidate <rank> --json`,
-            reason: "在当前 Execution 记录用户选择",
-        };
+        next = null;
     }
     else if (items.length === 0) {
         next = null;
     }
+    const interaction = items.length > 0 && requestedCapability.requires_human_action
+        ? {
+            schema_version: "itpay.interaction.v1",
+            stage: "query_results_ready",
+            by_goal: {
+                compare: { action: "present_options", max_options: 3, stop_after_presentation: true },
+                prepare_checkout: {
+                    action: "select_under_user_rules_then_prepare",
+                    requires: ["current_delegation", "eligible_current_selection", "owner_permits_next_step"],
+                },
+            },
+            input_template: {
+                command: `itpay services action ${response.execution.service_execution_id} --action select_candidate --actor-type human --status approved --candidate <rank> --json`,
+                required_input: ["rank"],
+                executable: false,
+            },
+        }
+        : undefined;
     if (preview?.resolved_locations)
         instruction += " 按 resolved_locations 说明实际解析地点；区域级位置仅是范围代表点，接驳时间不是从用户精确位置计算的。";
     return {
-        value: { status, result: baseResult, instruction, next, recovery: [] },
+        value: { status, result: baseResult, instruction, next, recovery: [], ...(interaction ? { interaction } : {}) },
         plainResult: serviceResultPlainLines(baseResult),
     };
 }
@@ -479,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];
@@ -727,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,
@@ -744,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 } : {}),
@@ -767,6 +858,7 @@ export async function runServicesGet(backend, serviceExecutionID, options = {})
 export async function runServicesNext(backend, serviceExecutionID, options = {}) {
     const response = await backend.getServiceExecution(serviceExecutionID, options.sinceSnapshot ? { sinceSnapshot: options.sinceSnapshot } : {});
     const envelope = servicesNextEnvelope(response);
+    journalTaskState(serviceExecutionID, envelope, options.env ?? process.env);
     if (response.rail_booking)
         envelope.result = { ...envelope.result, rail_booking: response.rail_booking };
     writeCommandEnvelope(envelope, {
@@ -777,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: "从第一页重新读取" }]);
     }
@@ -807,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
@@ -892,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
-                ? { 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 } : {}),
@@ -1046,12 +1136,34 @@ function railJourneySummary(card, serviceExecutionID) {
         ...(card.observed_at ? { observed_at: card.observed_at } : {}),
         ...(card.risk_notes?.length ? { risk_notes: card.risk_notes } : {}),
         ...(card.booking_support === "single_leg"
-            ? { select: `itpay services action ${serviceExecutionID} --action select_journey --actor-type human --status approved --input journey_id=${card.journey_id} --json` }
+            ? {
+                select: `itpay services action ${serviceExecutionID} --action select_journey --actor-type human --status approved --input journey_id=${card.journey_id} --json`,
+                // Delegated selection under explicit user rules is an agent action —
+                // never record it as a human pick.
+                select_delegated: `itpay services action ${serviceExecutionID} --action select_journey --actor-type agent --status approved --input journey_id=${card.journey_id} --input selection_mode=delegated --json`,
+            }
             : {}),
         ...(card.booking_offer
             ? {
                 booking_offer: card.booking_offer,
-                book: `itpay services run ${card.booking_offer.service_id} --input-json <file> --json  # file = {"selection":{"token":"${card.booking_offer.selection_token}","seat_type":"<席别>"},"passengers":<n>}`,
+                booking_template: {
+                    command: `itpay services run ${card.booking_offer.service_id} --input-json <file> --json`,
+                    required_input: ["file"],
+                    executable: false,
+                    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,
+                    },
+                },
             }
             : {}),
     };
@@ -1108,12 +1220,61 @@ 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 = {
         command: `itpay services next ${se}${plan.snapshot_id ? ` --since-snapshot ${plan.snapshot_id}` : ""} --json`,
         reason: "读取同一规划的增量进展（不触发供应商调用）",
     };
+    // Two-goal interaction contract (spec 03 §2): the local Agent picks compare
+    // or prepare_checkout from full context — the envelope teaches both branches
+    // so a delegated purchase keeps moving and a comparison never buys.
+    const bookable = journeys.find((card) => card.booking_support === "single_leg" && card.booking_offer);
+    const queryResultsInteraction = journeys.length > 0
+        ? {
+            schema_version: "itpay.interaction.v1",
+            stage: "query_results_ready",
+            by_goal: {
+                compare: { action: "present_options", max_options: 3, stop_after_presentation: true },
+                prepare_checkout: {
+                    action: "select_under_user_rules_then_prepare",
+                    recipe: "rail.selected-to-checkout.v1",
+                    requires: ["current_delegation", "eligible_current_selection", "owner_permits_next_step"],
+                    ...(bookable
+                        ? {
+                            steps: [
+                                "按用户明确规则在 journeys 中选择合格者（卡片 select_delegated 提交 agent 委托选择；人类亲自选择用 select）",
+                                `用所选卡片的 booking_template 写 owner-only 临时输入（selection token + 席别 + 人数，不含身份信息），运行 itpay services run itpay-rail-booking --input-json <file> --json`,
+                                "owner 要求聊天 review 时一次合并补齐必要字段，真实确认后提交原 workflow:confirm_booking；不得伪造 accept",
+                                `确认后恢复同一购买执行：itpay services run itpay-rail-booking --execution <实际ID> --json，沿用有界等待与受保护 Checkout`,
+                            ],
+                        }
+                        : { unavailable: "当前结果无可整段购买映射；分别说明各段风险，不得合成原子联程。" }),
+                },
+            },
+        }
+        : undefined;
+    const queryResultsCommunication = journeys.length > 0
+        ? {
+            schema_version: "itpay.communication.v1",
+            status_line: expansion === "paused"
+                ? "首批结果已就绪，扩展搜索已暂停等待用户决定"
+                : "查询结果就绪",
+            recommended_reason: plan.recommendation?.explanation?.[0],
+            human_steps: [
+                "compare：比较首选与最多两个备选后告知取舍",
+                "prepare_checkout：委托仍在时确认所选，继续官方确认页",
+                "姓名、证件、手机号只在受保护 Checkout 页填写",
+            ],
+            next_expectation: "compare：用户选定其一；prepare_checkout：委托仍在时继续到官方确认入口，人完成review与付款",
+            must_convey: [
+                "推荐与备选的时间/费用/便利性取舍",
+                "金额为查询时参考价，下单前须核验",
+                "姓名、证件、手机号只在受保护网页填写",
+            ],
+        }
+        : undefined;
     switch (expansion) {
         case "complete":
             return {
@@ -1121,10 +1282,12 @@ 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" ? "本次查询已达到上限，以下是已查到的方案，搜索范围尚未全部核验。" : "本轮规划已完成。"}向用户展示 recommendation 与 journeys 卡片（车次/时间/价格/余票状态），请用户选定 journey 后用其 select 命令提交；乘车人身份信息不在此收集，后续购买走受保护 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: "选定推荐行程" }
+                    ? { command: railJourneySummary(journeys[0], se).select, reason: "用户在 compare 后选定推荐行程时执行；prepare_checkout 且规则命中时用 select_delegated" }
                     : null,
+                ...(queryResultsInteraction ? { interaction: queryResultsInteraction } : {}),
+                ...(queryResultsCommunication ? { communication: queryResultsCommunication } : {}),
                 recovery: [],
             };
         case "paused": {
@@ -1168,8 +1331,10 @@ function railPlanningEnvelope(model) {
             return {
                 status: "awaiting_input",
                 result,
-                instruction: `${modelDegradedHint}${failedPairsHint}${directHint}${transferHint}${partialPause}规划已发布首批结果并暂停扩展：展示现有卡片与 available_actions，等待用户意图（${expandHint}）。ready 后 next 为空表示向用户汇报并等待，不是永远没有更多。`,
+                instruction: `${modelDegradedHint}${failedPairsHint}${directHint}${transferHint}${partialPause}规划已发布首批结果并暂停扩展：展示现有卡片与 available_actions，等待用户意图（${expandHint}）。ready 后 next 为空表示向用户汇报并等待，不是永远没有更多。compare：解释首选及最多两个备选后等待；prepare_checkout：委托仍在且选项合格时按 interaction.recipe 继续到官方确认入口，不再次问是否下单。`,
                 next: null,
+                ...(queryResultsInteraction ? { interaction: queryResultsInteraction } : {}),
+                ...(queryResultsCommunication ? { communication: queryResultsCommunication } : {}),
                 recovery: [],
             };
         }
@@ -1191,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: {
@@ -1216,6 +1383,17 @@ function railPlanningEnvelope(model) {
                 result,
                 instruction: `${modelDegradedHint}${manualExpansion}${transferHint}${failedPairsHint}规划进行中：已提交的卡片可先向用户展示比较；稍后按 next 增量轮询同一执行（since-snapshot 命中时负载会被压缩，但阶段与计数仍返回最新值）。不要重新发起查询。`,
                 next: nextPoll,
+                communication: {
+                    schema_version: "itpay.communication.v1",
+                    status_line: transferSearching && !manualExpansion
+                        ? "直达范围暂未找到可用方案，中转组合仍在搜索"
+                        : "规划进行中，已确认的方案可先向用户展示",
+                    next_expectation: "按 next 增量轮询同一执行；不重新发起查询",
+                    must_convey: [
+                        "当前是进行中的部分结果，不代表最终答复",
+                        ...(failedPairsHint ? ["部分站对尚未查明，不能说'没有车'"] : []),
+                    ],
+                },
                 recovery: [],
             };
         }
@@ -1373,18 +1551,48 @@ function servicesNextEnvelope(model) {
                     result: { service_execution_id: id, service_id: execution.service_id, human_action: action,
                         required_fields: requiredFields, sides },
                     instruction: "向用户展示 sides 中 status=needs_confirmation 一端的候选（名称+坐标），请用户选定后按 required_fields 逐项各传一个 --input：名称取候选 name，坐标取候选 location 的 [lng,lat]；已 resolved 的一端把其 resolved_place 原样填入。继续同一执行，不重新查询；这一步不是购买确认。",
-                    next: { command: `itpay services action ${id} --action ${action.action_type} --actor-type human --status approved${requiredFields.map((field) => ` --input ${field}=<值>`).join("")} --json`, reason: "用户确认后继续当前查询" },
+                    next: null,
+                    interaction: {
+                        schema_version: "itpay.interaction.v1",
+                        stage: "location_confirmation_required",
+                        input_template: {
+                            command: `itpay services action ${id} --action ${action.action_type} --actor-type human --status approved${requiredFields.map((field) => ` --input ${field}=<值>`).join("")} --json`,
+                            required_input: requiredFields,
+                            executable: false,
+                        },
+                    },
                     recovery: [],
                 };
             }
             const review = action.context?.review;
             if (review) {
+                // W4: when the owner projects an official web review entry, present it
+                // and wait for the human there; otherwise keep the one consolidated
+                // chat review — never fabricate an accepted review.
+                const reviewURL = [review.web_review_url, review.entry_url, review.review_url]
+                    .find((value) => typeof value === "string" && /^https:\/\//.test(value));
+                const requirementsRemaining = Array.isArray(review.requirements_remaining)
+                    ? review.requirements_remaining
+                    : undefined;
                 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: "提交用户确认后的行程确认/修订" },
+                        required_fields: requiredFields,
+                        ...(requirementsRemaining ? { requirements_remaining: requirementsRemaining } : {}) },
+                    ...(reviewURL ? { handoff: { url: reviewURL, kind: "booking_review" } } : {}),
+                    instruction: reviewURL
+                        ? "已在 handoff.url 提供官方行程确认页，请用户在该页核对行程、席别与座位偏好并确认；页面打开请求不代表用户已确认。该页失效或用户更愿在对话中确认时，仍可按下述 input_template 一次合并提交。乘客姓名/证件等身份信息不在此提交，仍走受保护 Checkout 页。"
+                        : "向用户展示 context.review 中的行程（legs）与可选席别/座位偏好词表（seat_options），并明确告知：座位偏好仅为请求、不保证分配（对应 notice_version 文案须经用户同意）。这是购买前的合并确认：把乘客人数、席别与每位乘客的座位偏好一次问清，然后按 required_fields 组装完整 JSON 对象，经 --input-json <file> 提交——draft_revision 必须等于服务端当前值，被拒绝（booking_review_changed）时重新读取后重试。未得真实确认不得提交，不能暗设 accept_non_guaranteed。乘客姓名/证件等身份信息不在此提交，仍走受保护 Checkout 页。",
+                    next: null,
+                    interaction: {
+                        schema_version: "itpay.interaction.v1",
+                        stage: "booking_review_required",
+                        input_template: {
+                            command: `itpay services action ${id} --action ${action.action_type} --actor-type human --status approved --input-json <file> --json`,
+                            required_input: requiredFields.length > 0 ? requiredFields : ["file"],
+                            executable: false,
+                        },
+                    },
                     recovery: [{ command: `itpay services next ${id} --json`, reason: "重新读取当前 draft_revision 后重试" }],
                 };
             }
@@ -1392,7 +1600,16 @@ function servicesNextEnvelope(model) {
                 status: "confirmation_required",
                 result: { service_execution_id: id, service_id: execution.service_id, human_action: action },
                 instruction: "请展示待确认的内容，请用户明确确认后，按 input_schema 填写 --input 字段。继续同一执行，不重新查询；这一步不是购买确认。",
-                next: { command: `itpay services action ${id} --action ${action.action_type} --actor-type human --status approved${requiredFields.map((field) => ` --input ${field}=<值>`).join("")} --json`, reason: "用户确认后继续当前查询" },
+                next: null,
+                interaction: {
+                    schema_version: "itpay.interaction.v1",
+                    stage: "confirmation_required",
+                    input_template: {
+                        command: `itpay services action ${id} --action ${action.action_type} --actor-type human --status approved${requiredFields.map((field) => ` --input ${field}=<值>`).join("")} --json`,
+                        required_input: requiredFields,
+                        executable: false,
+                    },
+                },
                 recovery: [],
             };
         }
@@ -1400,22 +1617,37 @@ function servicesNextEnvelope(model) {
         let command = `itpay services next ${id} --json`;
         if (state === "payment")
             command = `itpay services checkout ${id} --json`;
-        if (state === "input_required")
-            command = `itpay services run ${execution.service_id} --execution ${id} --input-json <file> --json`;
+        // input_required: the resume command needs a real file path — expose it as
+        // a non-executable input_template, not a fake `next.command`.
+        const inputTemplate = state === "input_required"
+            ? {
+                command: `itpay services run ${execution.service_id} --execution ${id} --input-json <file> --json`,
+                required_input: ["file"],
+                executable: false,
+            }
+            : undefined;
         const guidance = railServiceGuidance(execution.service_id);
         const failedStep = recovery ? failedWorkflowStep(model.workflow?.steps, model.workflow?.error_code) : undefined;
         const failedStepGuidance = failedStep ? WORKFLOW_STEP_GUIDANCE[failedStep] : undefined;
         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,
@@ -1427,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
@@ -1439,14 +1671,26 @@ function servicesNextEnvelope(model) {
                         ? "按 result.guidance 的字段契约填写输入后继续同一服务执行；不要臆造字段名。"
                         : "继续读取同一执行；缺少输入时按服务声明补齐。"),
             next: recovery ? null : { command, reason: "继续当前流程" },
-            recovery: recovery && state === "failed"
+            ...(inputTemplate || (state === "payment" && model.workflow?.human_action?.context?.review) ? {
+                interaction: {
+                    schema_version: "itpay.interaction.v1",
+                    stage: inputTemplate ? "input_required" : "payment",
+                    ...(inputTemplate ? { input_template: inputTemplate } : {}),
+                    ...(state === "payment" && model.workflow?.human_action?.context?.review ? {
+                        revise_template: {
+                            command: `itpay services action ${id} --action ${model.workflow.human_action.action_type} --actor-type human --status approved --input-json <file> --json`,
+                            required_input: ["file"],
+                            executable: false,
+                        },
+                    } : {}),
+                },
+            } : {}),
+            recovery: recovery && state === "failed" && !quoteFailure
                 ? [
                     { 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);
@@ -1801,6 +2045,12 @@ function buildServicesCheckoutEnvelope(response, checkoutURL, plan, agentType, t
             capability_id: checkoutCapabilityID(response),
             locked_input: response.locked_input,
             amount,
+            ...(checkout.checkout.expires_at ? {
+                // The shared server-owned payable deadline D: refreshing the page or
+                // re-creating a checkout can never extend it; past it the checkout
+                // and pending order are terminally cancelled.
+                payment_deadline_at: checkout.checkout.expires_at,
+            } : {}),
         },
         handoff: presentationHandoff.handoff,
         instruction: presentationHandoff.instruction,
@@ -1889,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);
         }
@@ -1913,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: "查找可能已经创建的服务执行" }]);