@itpay/cli 2.1.9 → 2.1.11

package/dist/src/client/backend.js

@@ -139,8 +139,9 @@ export class BackendClient {
     prepareServiceQuote(serviceExecutionID, input) {
         return this.http.post(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/quotes`, input, { replaySafe: true });
     }
-    getServiceExecution(serviceExecutionID) {
-        return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}`);
+    getServiceExecution(serviceExecutionID, opts = {}) {
+        const query = opts.sinceSnapshot ? `?since_snapshot=${encodeURIComponent(opts.sinceSnapshot)}` : "";
+        return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}${query}`);
     }
     listServiceExecutions(limit = 50) {
         return this.http.get(`/v1/service-executions?limit=${limit}`);
@@ -155,6 +156,10 @@ export class BackendClient {
     getGrantedServiceResult(serviceExecutionID) {
         return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/granted-result`);
     }
+    getRailJourneyDetail(serviceExecutionID, journeyID, snapshotID) {
+        const query = snapshotID ? `?snapshot=${encodeURIComponent(snapshotID)}` : "";
+        return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/rail-planning/journeys/${encodeURIComponent(journeyID)}${query}`);
+    }
 }
 // --- SSE streaming helper ---
 async function streamSSE(url, onEvent, signal) {

package/dist/src/commands/buy.js

@@ -203,6 +203,7 @@ function buildBuyEnvelope(input) {
     const presentationHandoff = buildCheckoutHandoff({
         platform,
         url: input.plan.linkOnlyURL ?? input.checkoutURL,
+        mobileUrl: input.checkoutURL,
         amount,
         plan: input.plan,
         ...(input.agentType ? { agentType: input.agentType } : {}),

package/dist/src/commands/checkout.js

@@ -22,7 +22,7 @@ export async function runCheckoutPresentation(backend, options) {
         });
         return;
     }
-    const checkoutURL = checkoutPageURL(options.baseURL, options.checkoutID, options.displayToken);
+    const checkoutURL = savedCheckoutURLOrFallback(options.savedCheckoutURL, options.checkoutID, options.displayToken, checkoutPageURL(options.baseURL, options.checkoutID, options.displayToken));
     const cardURL = localizeCardURL(absolutePublicURL(options.baseURL, presentation.card_url ?? checkoutCardURL(options.baseURL, options.checkoutID, options.displayToken)), locale);
     const qrPNGURL = absolutePublicURL(options.baseURL, presentation.card_png_url ?? presentation.qr_png_url ?? checkoutCardPNGURL(options.baseURL, options.checkoutID, options.displayToken));
     const localizedPNGURL = localizeCardURL(qrPNGURL, locale);
@@ -68,6 +68,7 @@ function pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand, a
     const presentationHandoff = buildCheckoutHandoff({
         platform,
         url: plan.linkOnlyURL ?? checkoutURL,
+        mobileUrl: checkoutURL,
         amount,
         plan,
         ...(agentType ? { agentType } : {}),
@@ -164,6 +165,20 @@ function checkoutPageURL(baseURL, checkoutID, displayToken) {
     const root = publicRoot(baseURL);
     return `${root}/checkout/${encodeURIComponent(checkoutID)}?display_token=${encodeURIComponent(displayToken)}`;
 }
+function savedCheckoutURLOrFallback(savedURL, checkoutID, displayToken, fallback) {
+    if (!savedURL) {
+        return fallback;
+    }
+    try {
+        const parsed = new URL(savedURL);
+        const belongsToCheckout = parsed.pathname === `/checkout/${checkoutID}`;
+        const sameToken = parsed.searchParams.get("display_token") === displayToken;
+        return belongsToCheckout && sameToken ? savedURL : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
 function checkoutCardURL(baseURL, checkoutID, displayToken) {
     const root = publicRoot(baseURL);
     return `${root}/v1/checkouts/${encodeURIComponent(checkoutID)}/card?display_token=${encodeURIComponent(displayToken)}`;

package/dist/src/commands/checkout_handoff.js

@@ -17,8 +17,26 @@ export function buildWorkBuddyPresentFilesAction(url) {
         arguments: { files: [url] },
     };
 }
+function hasCompleteCheckoutTokens(url) {
+    if (!url) {
+        return false;
+    }
+    try {
+        const parsed = new URL(url);
+        return Boolean(parsed.searchParams.get("display_token") && parsed.searchParams.get("complete_exchange_token"));
+    }
+    catch {
+        return false;
+    }
+}
 export function buildCheckoutHandoff(input) {
     const handoff = { url: input.url };
+    // mobile_url is only emitted when the link carries the complete token pair;
+    // a display-token-only link cannot finish the same-device exchange after payment.
+    const mobileUrl = hasCompleteCheckoutTokens(input.mobileUrl) ? input.mobileUrl : undefined;
+    if (mobileUrl) {
+        handoff.mobile_url = mobileUrl;
+    }
     const workBuddyAction = isWorkBuddyPlainChat(input.agentType, input.platform);
     if (workBuddyAction) {
         handoff.agent_action = buildWorkBuddyPresentFilesAction(input.url);
@@ -40,27 +58,41 @@ export function buildCheckoutHandoff(input) {
     }
     return {
         handoff,
-        instruction: checkoutHandoffInstruction(input.agentType, input.platform, input.amount),
+        instruction: checkoutHandoffInstruction(input.agentType, input.platform, input.amount, Boolean(mobileUrl)),
     };
 }
-function checkoutHandoffInstruction(agentType, platform, amount) {
+function checkoutHandoffInstruction(agentType, platform, amount, hasMobileLink) {
     if (isWorkBuddyPlainChat(agentType, platform)) {
-        return `Backend 尚未确认付款。立即严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行一次，在右侧打开 handoff.url；确认工具调用成功后说明金额 ${amount}，然后停止等待。若工具失败，只发送原始 handoff.url，报告未自动打开并停止。不要用 present_files 打开本地文件或二维码 PNG，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+        const mobileSentence = hasMobileLink
+            ? "，然后把 handoff.mobile_url 作为可点击链接发给用户，说明“手机端点开可直接跳转支付宝或微信支付；小程序内打不开时复制到手机浏览器打开即可”"
+            : "";
+        const failLinks = hasMobileLink ? "发送 handoff.url 与 handoff.mobile_url" : "发送原始 handoff.url";
+        return `Backend 尚未确认付款。立即严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行一次，在右侧打开 handoff.url；确认工具调用成功后说明金额 ${amount}${mobileSentence}，然后停止等待。若工具失败，只${failLinks}，报告未自动打开并停止。不要用 present_files 打开本地文件或二维码 PNG，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }
     if (isZCodePlainChat(agentType, platform)) {
-        return `Backend 尚未确认付款。立即用 ZCode 内置浏览器打开 handoff.url，让用户完成付款；确认已发起打开后说明金额 ${amount}，然后停止等待。不要只粘贴文字链接，不要下载、解析或重建二维码，不要创建新 Checkout、Payment Intent 或 Execution。只有内置浏览器明确不可用时，才展示同一个可点击 handoff.url。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+        const mobileSentence = hasMobileLink
+            ? "，并把 handoff.mobile_url 发给用户备用（手机端点开可直接跳转支付宝或微信支付）"
+            : "";
+        const fallbackLinks = hasMobileLink ? "同一个可点击 handoff.url 与 handoff.mobile_url" : "同一个可点击 handoff.url";
+        return `Backend 尚未确认付款。立即用 ZCode 内置浏览器打开 handoff.url，让用户完成付款；确认已发起打开后说明金额 ${amount}${mobileSentence}，然后停止等待。不要只粘贴文字链接，不要下载、解析或重建二维码，不要创建新 Checkout、Payment Intent 或 Execution。只有内置浏览器明确不可用时，才展示${fallbackLinks}。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }
     if (agentType?.trim().toLowerCase() === "doubao-work" && platform === "plain_chat") {
-        return `Backend 尚未确认付款。在当前豆包工作对话中展示两个有标签的官方入口：将 handoff.url 标为“手机直接打开收银台”，将 handoff.qr_image_url 标为“二维码图片（保存或用另一台设备扫码）”。说明金额 ${amount} 后停止等待。不要解析或单独输出 URL credential，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+        const directLink = hasMobileLink ? "handoff.mobile_url" : "handoff.url";
+        const directLabel = hasMobileLink ? "手机直接打开收银台（可跳转支付宝/微信）" : "手机直接打开收银台";
+        return `Backend 尚未确认付款。在当前豆包工作对话中展示两个有标签的官方入口：将 ${directLink} 标为“${directLabel}”，将 handoff.qr_image_url 标为“二维码图片（保存或用另一台设备扫码）”。说明金额 ${amount} 后停止等待。不要解析或单独输出 URL credential，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }
     if (platform === "markdown") {
-        return `Backend 尚未确认付款。把 handoff.markdown 原样发送到当前桌面对话，确认二维码、付款链接和金额 ${amount} 均已实际对用户可见，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+        const mobileSentence = hasMobileLink ? "，并附 handoff.mobile_url 供手机端点击直达支付" : "";
+        return `Backend 尚未确认付款。把 handoff.markdown 原样发送到当前桌面对话，确认二维码、付款链接和金额 ${amount} 均已实际对用户可见${mobileSentence}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }
     if (platform === "terminal") {
-        return `Backend 尚未确认付款。在用户可见终端展示当前 Checkout 的二维码、handoff.url 和金额 ${amount}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+        const mobileSentence = hasMobileLink ? "，并展示 handoff.mobile_url 供手机端点击直达支付" : "";
+        return `Backend 尚未确认付款。在用户可见终端展示当前 Checkout 的二维码、handoff.url 和金额 ${amount}${mobileSentence}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }
     if (agentType?.trim().toLowerCase() === "openclaw" && platform === "telegram") {
-        return `Backend 尚未确认付款或授权状态。立即使用 OpenClaw 原生 message tool，严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行；它会发送金额 ${amount}、二维码、📱 手机点这儿支付和 📋 已授权给我读。不得改写 presentation、换用其他消息工具、拆开按钮发送或用普通回复声称按钮已经发送。确认 message tool 调用成功后停止等待。收到 callback_data "itp:grant_confirmed:<checkout_id>" 时，表示用户声明已在收银台授权读取；立即执行 next.command 查询同一 Checkout，再只执行 Backend 返回的 next.command 进入同一 Execution 的 grant 流程。该 callback 不证明付款成功或 grant 已生效；Backend 未返回 grant_active 前不得读取或猜测结果。若原生 message tool 明确失败或当前 Telegram 未启用 inline buttons，只发送现有 handoff.qr_image_url、金额和 handoff.url，报告按钮不可用并停止；不要创建新的 Checkout、Payment Intent 或 Execution。`;
+        const failLinks = hasMobileLink ? "handoff.qr_image_url、金额、handoff.url 与 handoff.mobile_url" : "handoff.qr_image_url、金额和 handoff.url";
+        return `Backend 尚未确认付款或授权状态。立即使用 OpenClaw 原生 message tool，严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行；它会发送金额 ${amount}、二维码、📱 手机点这儿支付和 📋 已授权给我读。不得改写 presentation、换用其他消息工具、拆开按钮发送或用普通回复声称按钮已经发送。确认 message tool 调用成功后停止等待。收到 callback_data "itp:grant_confirmed:<checkout_id>" 时，表示用户声明已在收银台授权读取；立即执行 next.command 查询同一 Checkout，再只执行 Backend 返回的 next.command 进入同一 Execution 的 grant 流程。该 callback 不证明付款成功或 grant 已生效；Backend 未返回 grant_active 前不得读取或猜测结果。若原生 message tool 明确失败或当前 Telegram 未启用 inline buttons，只发送现有 ${failLinks}，报告按钮不可用并停止；不要创建新的 Checkout、Payment Intent 或 Execution。`;
     }
-    return `Backend 尚未确认付款。把 handoff.url 和可用的 handoff.qr_image_url 实际发送到当前会话，说明金额 ${amount}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+    const urlList = hasMobileLink ? "handoff.url、handoff.mobile_url（手机端点击直达支付）和可用的 handoff.qr_image_url" : "handoff.url 和可用的 handoff.qr_image_url";
+    return `Backend 尚未确认付款。把 ${urlList} 实际发送到当前会话，说明金额 ${amount}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
 }

package/dist/src/commands/order.js

@@ -38,6 +38,10 @@ function orderEnvelope(order, delivery, lockedRefund) {
     else if (order.status === "cancelled") {
         instruction = "先告诉用户这笔订单已经取消，没有可继续的付款或交付；不要创建替代订单，除非用户另行提出新的购买。";
     }
+    else if (order.status === "pending_payment") {
+        instruction = "先告诉用户订单正在等待付款，超时未支付会被自动取消；不要创建替代订单，也不要重复发起支付授权。";
+        next = { command: `itpay order ${order.order_id} --json`, reason: "刷新订单支付状态" };
+    }
     else if (!["delivered", "refunded", "failed", "cancelled"].includes(order.status)) {
         instruction = "先告诉用户订单仍在处理，已记录的付款和订单不需要重复创建；稍后查询同一订单，不要创建替代订单。";
         next = { command: `itpay order ${order.order_id} --json`, reason: "刷新订单状态" };
@@ -48,6 +52,7 @@ function orderEnvelope(order, delivery, lockedRefund) {
             order_id: order.order_id,
             ...(order.order_code ? { order_code: order.order_code } : {}),
             amount: formatMoney(order.amount_minor, order.currency),
+            ...(order.payment_deadline_at ? { payment_deadline_at: order.payment_deadline_at } : {}),
             ...(delivery ? { delivery_mode: delivery.delivery_mode } : {}),
             access_locked: Boolean(lockedRefund),
             ...(delivery?.service_execution_id ? { service_execution_id: delivery.service_execution_id } : {}),

package/dist/src/commands/services.js

@@ -9,6 +9,10 @@ import { localizeCardURL, normalizeCardLocale } from "../render/locale.js";
 import { buildAgentChatHandoff } from "../render/markdown.js";
 import { platformKeyForHost } from "../render/plan.js";
 import { renderTerminalQR } from "../render/qr.js";
+// Declared at execution creation: the client understands the rail.progressive.v2
+// response format (rail_planning projection, snapshot paging, rsel_ handles).
+// The server alone decides service version, quota and provider credentials.
+const RAIL_PROGRESSIVE_FEATURES = ["rail.progressive.v2"];
 import { buildCheckoutQRPlan } from "./buy.js";
 import { appendFeedbackPostmortemInstruction, CommandContractError, isTerminalServiceExecutionStatus, writeCommandEnvelope, } from "./guidance.js";
 const serviceActionStatuses = new Set(["pending", "approved", "rejected", "expired", "cancelled"]);
@@ -87,6 +91,7 @@ export async function runServicesStart(backend, serviceID, options = {}) {
         service_id: serviceID,
         client_context: {
             host,
+            features: [...RAIL_PROGRESSIVE_FEATURES],
             ...(options.target ? { target: options.target } : {}),
             ...(options.clientContext ?? {}),
         },
@@ -759,7 +764,7 @@ export async function runServicesGet(backend, serviceExecutionID, options = {})
     });
 }
 export async function runServicesNext(backend, serviceExecutionID, options = {}) {
-    const response = await backend.getServiceExecution(serviceExecutionID);
+    const response = await backend.getServiceExecution(serviceExecutionID, options.sinceSnapshot ? { sinceSnapshot: options.sinceSnapshot } : {});
     const envelope = servicesNextEnvelope(response);
     if (response.rail_booking)
         envelope.result = { ...envelope.result, rail_booking: response.rail_booking };
@@ -781,14 +786,19 @@ export async function runServicesPage(backend, serviceExecutionID, resultItemID,
     const response = await backend.getServiceExecutionResultItemPage(serviceExecutionID, resultItemID, offset, limit);
     const page = response.page;
     const container = (page.result ?? page);
-    const catalogPage = (container.catalog_page ?? {});
+    // rail.progressive.v2 saved pages key journeys/journey_page; legacy result
+    // items key candidates/catalog_page. Both are committed, read-only slices.
+    const v2Page = (container.journey_page ?? {});
+    const catalogPage = (container.catalog_page ?? v2Page);
     const nextOffset = typeof catalogPage.next_offset === "number" ? catalogPage.next_offset : null;
-    const candidates = Array.isArray(container.candidates) ? container.candidates : [];
+    const journeys = Array.isArray(container.journeys) ? container.journeys : [];
+    const candidates = Array.isArray(container.candidates) ? container.candidates : journeys;
     const envelope = {
         status: candidates.length > 0 ? "result_page" : "result_page_end",
         result: {
             service_execution_id: response.service_execution_id,
-            service_capability_result_item_id: response.service_capability_result_item_id,
+            ...(response.service_capability_result_item_id ? { service_capability_result_item_id: response.service_capability_result_item_id } : {}),
+            ...(response.snapshot_id ? { snapshot_id: response.snapshot_id } : {}),
             offset: catalogPage.offset ?? offset,
             limit: catalogPage.limit ?? limit,
             total: catalogPage.total ?? candidates.length,
@@ -798,7 +808,10 @@ export async function runServicesPage(backend, serviceExecutionID, resultItemID,
         },
         instruction: "读取的是已保存结果的同版本分页，不重新查询、不消耗额度。用普通语言向用户说明本页候选（车次、席别、时刻、费用口径），铁路应付与地面估算费用分开表述；不要提及 safe_payload、Execution 或内部 ID。",
         next: nextOffset !== null
-            ? { command: `itpay services page ${serviceExecutionID} ${resultItemID} --offset ${nextOffset} --json`, reason: "读取同版本结果的下一页" }
+            ? { command: response.snapshot_id
+                    ? `itpay services page ${serviceExecutionID} ${resultItemID} --cursor rcur_${nextOffset} --json`
+                    : `itpay services page ${serviceExecutionID} ${resultItemID} --offset ${nextOffset} --json`,
+                reason: "读取同版本结果的下一页" }
             : null,
         recovery: offset > 0
             ? [{ command: `itpay services page ${serviceExecutionID} ${resultItemID} --json`, reason: "回到第一页" }]
@@ -850,6 +863,33 @@ export async function runServicesList(backend, options = {}) {
     });
 }
 export async function runServicesReadResult(backend, serviceExecutionID, options = {}) {
+    // rail.progressive.v2 planning read: --journey/--snapshot select committed
+    // planning evidence — a free owner-validated read that never touches the
+    // grant/Vault path. Without the selectors the authorized-delivery flow is
+    // unchanged.
+    if (options.journey) {
+        const detail = await backend.getRailJourneyDetail(serviceExecutionID, options.journey, options.snapshot);
+        writeCommandEnvelope({
+            status: "ready",
+            result: {
+                service_execution_id: serviceExecutionID,
+                plan_id: detail.plan_id,
+                snapshot_id: detail.snapshot_id,
+                query_revision: detail.query_revision,
+                journey: detail.journey,
+            },
+            instruction: "展示该 journey 的完整明细（车次、分段、席别报价、接驳估计与风险标注）。rail_payable 只是该行程当前可购报价的参考价，不是锁价；下单前须走受保护 Checkout 收集乘车人。",
+            next: detail.journey?.booking_support === "single_leg"
+                ? { command: `itpay services action ${serviceExecutionID} --action select_journey --actor-type human --status approved --input journey_id=${detail.journey.journey_id} --json`, reason: "选定此行程" }
+                : { command: `itpay services next ${serviceExecutionID} --since-snapshot ${detail.snapshot_id} --json`, reason: "返回规划进展" },
+            recovery: [],
+        }, {
+            ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+            ...(options.output ? { output: options.output } : {}),
+            plainResult: servicesNextPlainResult(detail.journey),
+        });
+        return;
+    }
     const response = await backend.getGrantedServiceResult(serviceExecutionID);
     let orderID;
     try {
@@ -941,6 +981,102 @@ function railBookingEnvelope(model) {
         recovery: [],
     };
 }
+function railJourneySummary(card, serviceExecutionID) {
+    const rides = Array.isArray(card.rides) ? card.rides : [];
+    const trains = rides.map((ride) => ride.train_code).filter(Boolean);
+    const first = rides[0];
+    const last = rides.at(-1);
+    const offer = card.representative_offer;
+    return {
+        journey_id: card.journey_id,
+        route: (card.route_names?.length ? card.route_names : card.route ?? []).join("→"),
+        ...(trains.length ? { trains } : {}),
+        ...(first?.departure || last?.arrival ? { time: `${first?.departure ?? ""}–${last?.arrival ?? ""}` } : {}),
+        ...(offer ? { price: formatMoney(offer.rail_payable_minor, offer.currency) } : { price: "unknown" }),
+        availability: card.availability,
+        booking_support: card.booking_support,
+        ...(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` }
+            : {}),
+        ...(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>}`,
+            }
+            : {}),
+    };
+}
+// rail.progressive.v2 read projection: committed snapshots only; polling never
+// triggers supplier calls. Recommendation is absent until the decision stage
+// commits — alternatives still render so users can compare early.
+function railPlanningEnvelope(model) {
+    const plan = model.rail_planning;
+    const se = model.execution.service_execution_id;
+    const expansion = plan.search?.expansion_status ?? "running";
+    const journeys = [plan.recommendation, ...(plan.alternatives ?? [])].filter(Boolean);
+    const cards = journeys.map((card) => railJourneySummary(card, se));
+    const result = {
+        service_execution_id: se,
+        rail_planning: {
+            readiness: plan.readiness,
+            query_revision: plan.query_revision,
+            snapshot_id: plan.snapshot_id,
+            expansion_status: expansion,
+            ...(plan.search?.reason ? { reason: plan.search.reason } : {}),
+            ...(plan.search?.poll_after_ms ? { poll_after_ms: plan.search.poll_after_ms } : {}),
+            ...(plan.result_not_updated ? { result_not_updated: true } : {}),
+            ...(plan.budgets ? { budgets: plan.budgets } : {}),
+            ...(plan.coverage ? { coverage: plan.coverage } : {}),
+        },
+        ...(plan.recommendation ? { recommendation: railJourneySummary(plan.recommendation, se) } : {}),
+        ...(cards.length ? { journeys: cards } : {}),
+        ...(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: "读取同一规划的增量进展（不触发供应商调用）",
+    };
+    switch (expansion) {
+        case "complete":
+            return {
+                status: "ready",
+                result,
+                instruction: "规划已收敛：向用户展示 recommendation 与 journeys 卡片（车次/时间/价格/余票状态），请用户选定 journey 后用其 select 命令提交；乘车人身份信息不在此收集，后续购买走受保护 Checkout。",
+                next: journeys[0]?.booking_support === "single_leg"
+                    ? { command: railJourneySummary(journeys[0], se).select, reason: "选定推荐行程" }
+                    : null,
+                recovery: [],
+            };
+        case "paused":
+            return {
+                status: "awaiting_input",
+                result,
+                instruction: "规划已发布首批结果并暂停扩展：展示现有卡片与 available_actions，等待用户意图（expand_search 是唯一会再消耗供应商配额的命令，其余均为本地读取）。ready 后 next 为空表示向用户汇报并等待，不是永远没有更多。",
+                next: null,
+                recovery: [],
+            };
+        case "failed":
+        case "cancelled":
+        case "expired":
+            return {
+                status: expansion,
+                result,
+                instruction: "本次规划已结束且不可续用；展示已有卡片后如需重查请用户确认后用同一服务新建执行。不要自动重新发起。",
+                next: null,
+                recovery: [{ command: `itpay services events ${se} --json`, reason: "读取同一任务的处理记录" }],
+            };
+        default:
+            return {
+                status: "planning",
+                result,
+                instruction: "规划进行中：已提交的卡片可先向用户展示比较；稍后按 next 增量轮询同一执行（since-snapshot 命中时负载会被压缩）。不要重新发起查询。",
+                next: nextPoll,
+                recovery: [],
+            };
+    }
+}
 function terminalExecutionEnvelope(model) {
     const execution = model.execution;
     const currentDelivery = model.current_delivery ?? model.delivery_bindings.at(-1);
@@ -1026,6 +1162,8 @@ function servicesNextEnvelope(model) {
     }
     if (model.rail_booking)
         return railBookingEnvelope(model);
+    if (model.rail_planning)
+        return railPlanningEnvelope(model);
     if (latestRun && ["failed", "cancelled"].includes(latestRun.status) && !model.workflow_entry) {
         return {
             status: latestRun.status,
@@ -1500,6 +1638,7 @@ function buildServicesCheckoutEnvelope(response, checkoutURL, plan, agentType, t
     const presentationHandoff = buildCheckoutHandoff({
         platform,
         url: plan.linkOnlyURL ?? checkoutURL,
+        mobileUrl: checkoutURL,
         amount,
         plan,
         ...(agentType ? { agentType } : {}),
@@ -1581,7 +1720,7 @@ export async function runServicesRun(backend, config, serviceID, input, options
         if (!id) {
             const started = await backend.startServiceExecution({
                 service_id: serviceID,
-                client_context: { host: options.host ?? "terminal", ...(options.target ? { target: options.target } : {}) },
+                client_context: { host: options.host ?? "terminal", features: [...RAIL_PROGRESSIVE_FEATURES], ...(options.target ? { target: options.target } : {}) },
                 ...(input !== undefined ? { input } : {}),
             });
             id = started.execution.service_execution_id;

package/dist/src/main.js

@@ -910,6 +910,9 @@ program
         await runCheckoutPresentation(backend, {
             checkoutID,
             displayToken,
+            ...(snap.lastCheckoutID === checkoutID && snap.lastCheckoutURL
+                ? { savedCheckoutURL: snap.lastCheckoutURL }
+                : {}),
             host,
             ...(options.target ? { target: options.target } : {}),
             ...(config.agentType ? { agentType: config.agentType } : {}),
@@ -1353,14 +1356,21 @@ services
     .argument("<service_execution_id>")
     .argument("<result_item_id>")
     .option("--offset <offset>", "zero-based candidate offset", Number, 0)
+    .option("--cursor <cursor>", "opaque v2 page cursor (rcur_<offset>); takes precedence over --offset")
     .option("--limit <limit>", "page size (1-20)", Number, 5)
     .option("--json", "output JSON")
     .action(async (serviceExecutionID, resultItemID, options) => {
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
+        const cursorOffset = typeof options.cursor === "string" && /^rcur_\d+$/.test(options.cursor)
+            ? Number(options.cursor.slice(5))
+            : undefined;
+        if (options.cursor !== undefined && cursorOffset === undefined) {
+            throw new CommandContractError("cursor_invalid", "--cursor must be an opaque rcur_<offset> token from a previous page response", "--cursor 需为上一页返回的 rcur_<offset> 不透明游标。", []);
+        }
         await runServicesPage(backend, serviceExecutionID, resultItemID, {
-            offset: options.offset,
+            offset: cursorOffset ?? options.offset,
             limit: options.limit,
             jsonOutput: Boolean(options.json),
         });
@@ -1598,12 +1608,13 @@ services
     .command("next")
     .description("Show the next recommended agent action for a Service Execution")
     .argument("<service_execution_id>")
+    .option("--since-snapshot <snapshot_id>", "delta read: suppress the journey payload when unchanged")
     .option("--json", "output JSON instead of terminal text")
     .action(async (serviceExecutionID, options) => {
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        await runServicesNext(backend, serviceExecutionID, { jsonOutput: Boolean(options.json) });
+        await runServicesNext(backend, serviceExecutionID, { jsonOutput: Boolean(options.json), sinceSnapshot: options.sinceSnapshot });
     }
     catch (error) {
         reportCLIError(error, {
@@ -1618,12 +1629,14 @@ services
     .command("read-result")
     .description("Read a human-granted service result for this agent")
     .argument("<service_execution_id>")
+    .option("--snapshot <snapshot_id>", "rail.progressive.v2: read one journey from a committed planning snapshot")
+    .option("--journey <journey_id>", "rail.progressive.v2: journey id to read")
     .option("--json", "output JSON instead of terminal text")
     .action(async (serviceExecutionID, options) => {
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        await runServicesReadResult(backend, serviceExecutionID, { jsonOutput: Boolean(options.json) });
+        await runServicesReadResult(backend, serviceExecutionID, { jsonOutput: Boolean(options.json), snapshot: options.snapshot, journey: options.journey });
     }
     catch (error) {
         reportCLIError(error, {

package/dist/src/state/config.js

@@ -15,8 +15,8 @@ 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.9";
-export const API_CONTRACT_REVISION = "sha256:66a95bbc5ec9d7b35747cf87206c63dd45983f26de21afab582d8dd63bf198f7";
+export const CLI_VERSION = "2.1.11";
+export const API_CONTRACT_REVISION = "sha256:653bead80f71a65f2edd1356bcdfe0ce3a3b99828a48cbf081f2dadac82c7e02";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";

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

@@ -46,7 +46,9 @@
         "depart_after": "Do not depart before this time.",
         "arrive_before": "Do not arrive after this time.",
         "priority": "One of balanced | fastest | cheapest | safest | flexible.",
-        "max_transfers": "Integer 0-2, allowed transfer count."
+        "max_transfers": "Integer 0-2, allowed transfer count.",
+        "passengers": "Integer 1-5, default 1: adult passenger count reflected in per-leg inventory and amounts. NOT identity records.",
+        "preference_context": "Bounded object, max 4 string-valued keys (<=200 chars each) of soft ranking preferences, e.g. {\"no_taxi\":\"true\"}. Validated allowlist; never carry passenger identity."
       },
       "example": {
         "origin": "中山古镇",
@@ -74,7 +76,9 @@
     "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.",
-    "Repeating the same selection restores the same booking execution instead of creating a second one."
+    "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 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": {
     "policy": "itpay-rail-exact and itpay-rail-smart each allow 2 anonymous queries per enrolled device lineage — independent counters, not a shared pool of 4.",
@@ -100,7 +104,14 @@
     "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.",
-    "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."
+    "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.",
+    "plan_conflict": "409: the action_request_id/expected_query_revision/snapshot_id no longer matches owner state. Re-read services next and reuse the fresh action handle; an identical replay of an accepted action still returns its original acceptance.",
+    "stale_cursor": "The paging cursor was minted against an older snapshot; restart paging from the current snapshot_id.",
+    "snapshot_not_found": "Unknown or superseded snapshot id; read the current projection for the latest snapshot.",
+    "journey_not_in_snapshot": "The rj_ reference is not inside the saved snapshot; pick a journey from the current page/projection.",
+    "plan_expired": "The 15-minute plan lifecycle ended: expansion stopped and the snapshot is read-only evidence; start a new execution for a fresh search. In-flight checkout/payment is unaffected.",
+    "action_request_invalid": "The action payload failed validation (unknown patch fields, malformed handle); copy the command from available_actions instead of composing it.",
+    "selection_stale": "The rsel_ token no longer matches the current snapshot/policy; re-read the journey and take the fresh booking_offer."
   },
   "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.",
@@ -118,7 +129,12 @@
     "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."
+    "Do not claim payment equals ticket issuance; issuance is asynchronous and confirmed only by the issued seat status.",
+    "For v2 plans, act only on available_actions[] from the current projection: run the exact command the backend returned, then re-read; never invent action types, request ids, revisions or fields.",
+    "expand_search is the only intent that may spend provider budget; refine_preferences re-ranks saved data first and does not by itself expand.",
+    "A paused/expired/complete plan is still readable and selectable from its saved snapshot; never start a replacement execution to keep polling.",
+    "stop_search pauses scheduling but keeps saved data and existing selections; booking stays reachable only through the allowed actions the owner reports.",
+    "When since_snapshot returns result_not_updated, keep the previous snapshot and still surface the latest expansion status/end reason to the user."
   ],
   "human_language": {
     "prefer": [
@@ -161,5 +177,15 @@
     "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."
+  },
+  "progressive_v2": {
+    "capability": "New CLI declares client_context.features=[\"rail.progressive.v2\"] at service start. It is a response-format declaration only; quota, service version and provider credentials stay server-decided. Old clients keep the legacy projection; never create a second execution to probe.",
+    "read_model": "While the plan workflow is active, services next carries rail_planning: schema_version, plan_id (jp_), query_revision, snapshot_id (rps_), readiness, expansion {status, reason, poll_after_ms, new_results_guaranteed}, coverage, budgets, recommendation + up to 4 alternatives (journey cards rj_), available_actions with concrete commands, result_item_id.",
+    "expansion_states": "queued/running: automatic work remains; paused: batch sufficient or auto window ended, expand only on explicit intent; complete/cancelled: budget or frontier exhausted — snapshot stays read-only, expand action absent; failed: reason visible after a published snapshot, readiness stays ready; expired: 15-minute lifecycle end — evidence read-only, in-flight purchase unaffected.",
+    "reads": "services next --since-snapshot <rps_…> suppresses the journey payload but always returns the latest expansion status. read-result gains --snapshot, --journey <rj_…> and an opaque --cursor bound to snapshot+filter+sort (stale -> stale_cursor). Reads never call the provider, never extend lifecycle, never invoke the model.",
+    "actions": "Three allowlisted planning actions ride POST actions with action_type workflow:expand_search | workflow:refine_preferences | workflow:stop_search. input_snapshot carries server-issued action_request_id plus expected_query_revision and snapshot_id; refine adds a validated preference_patch. Always copy the concrete command from available_actions[]; never assemble fields. Same id + same payload returns the stored acceptance; same id + different payload -> plan_conflict.",
+    "journey_card": "Cards carry station names, train codes, dated times, transfer/same-run notes, observed_at price time and handles. representative_offer.ticket_offers[] lists one purchasable segment per entry (leg_index, offer_id, service_ref, station codes, travel_date, seat_type, passengers, integer-minor amounts); per-item amounts sum to the total. rides[] (ridden legs) and ticket_offers[] (purchasable segments) are different lists — never infer transfers or fees from array lengths.",
+    "selection": "booking_support=single_leg cards carry booking_offer {service_id: itpay-rail-booking, selection_token: rsel_…}; submit it to itpay-rail-booking with passengers as today. separate_legs_only cards expose no whole-journey token — each leg is quoted and confirmed separately via its protected detail; never assemble legs JSON yourself. booking_support=none has no selection action.",
+    "honesty": "Coverage is bounded: repeat searched_scope/notices verbatim, never claim national-exhaustive search, and surface missing prices as unknown — never 0."
   }
 }

package/docs/agent/buyer/render-hosts.json

@@ -33,17 +33,17 @@
     {
       "agent_type": "workbuddy",
       "default_host": "plain-chat",
-      "responsibility": "execute handoff.agent_action exactly once to open the fully rendered handoff.url with present_files; show the amount and stop"
+      "responsibility": "execute handoff.agent_action exactly once to open the fully rendered handoff.url with present_files, then send handoff.mobile_url as a clickable link that jumps straight into Alipay or WeChat Pay on a phone; show the amount and stop"
     },
     {
       "agent_type": "zcode",
       "default_host": "plain-chat",
-      "responsibility": "open handoff.url immediately in the ZCode built-in browser and stop; only show the same clickable URL when the built-in browser is unavailable"
+      "responsibility": "open handoff.url immediately in the ZCode built-in browser, also send handoff.mobile_url as the phone-friendly entry, then stop; when the built-in browser is unavailable show both clickable links"
     },
     {
       "agent_type": "doubao-work",
       "default_host": "plain-chat",
-      "responsibility": "show handoff.url as the preferred same-phone checkout or authorization link and handoff.qr_image_url as the labeled save-or-scan fallback; state the amount for Checkout and stop"
+      "responsibility": "show handoff.mobile_url as the preferred same-phone checkout or authorization link and handoff.qr_image_url as the labeled save-or-scan fallback; state the amount for Checkout and stop"
     },
     {
       "agent_type": "kimi-code",
@@ -73,10 +73,11 @@
   "agent_rules": [
     "Agent Type is stable identity; Host is presentation and may be explicitly overridden.",
     "A local QR path is not visible until a desktop Agent attaches or renders that file on the human-facing surface; WorkBuddy never receives a local QR path.",
-    "For workbuddy with plain-chat, execute handoff.agent_action exactly once; it calls present_files with handoff.url as the only files element and opens the rendered Card Link in the right-side browser.",
-    "For zcode with plain-chat, open handoff.url in the built-in browser. Do not only paste text, download or rebuild a QR, or invent a private browser-tool payload; use the same clickable URL only as fallback.",
-    "For doubao-work with plain-chat, show two labeled official links: handoff.url for direct same-phone opening and handoff.qr_image_url for saving or scanning on another device; do not parse credentials, download or rebuild the QR, or create an alternative resource.",
-    "If the WorkBuddy action fails, send the original handoff.url, report that it did not auto-open, and stop without creating another payment resource.",
+    "For workbuddy with plain-chat, execute handoff.agent_action exactly once; it calls present_files with handoff.url as the only files element and opens the rendered Card Link in the right-side browser, then send handoff.mobile_url so phone users can tap straight into Alipay or WeChat Pay.",
+    "For zcode with plain-chat, open handoff.url in the built-in browser and also send handoff.mobile_url as the phone entry; do not only paste text, download or rebuild a QR, or invent a private browser-tool payload; when the built-in browser is unavailable show both clickable links.",
+    "For doubao-work with plain-chat, show two labeled official links: handoff.mobile_url for direct same-phone opening and handoff.qr_image_url for saving or scanning on another device; do not parse credentials, download or rebuild the QR, or create an alternative resource.",
+    "If the WorkBuddy action fails, send the original handoff.url and handoff.mobile_url, report that it did not auto-open, and stop without creating another payment resource.",
+    "handoff.mobile_url is the phone-friendly Checkout URL; when the current client cannot open links in place (for example a mobile mini program), send it and tell the human to copy it into the phone browser where it can jump into Alipay or WeChat Pay. It is only returned when the handoff carries the complete token pair; when absent, handoff.url remains the entry.",
     "Do not claim the handoff was shown until both a usable payment image or QR and the Checkout URL are visible.",
     "IM Hosts that require a target must receive --target before Checkout creation. OpenClaw has no default Host; Kimi Code uses terminal.",
     "OpenClaw Telegram uses flat url/value buttons for deployed-version compatibility. A grant_confirmed callback carries only the Checkout ID, never a display token, and never proves payment or an active grant."

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

@@ -27,6 +27,19 @@ itpay services action <service_execution_id> --action <action_type>
 
 普通 Agent 优先使用 `--candidate <rank>`。CLI 只从当前 Execution 的 `current_result_items` 解析 Result Item ID；Backend 再读取权威 Invocation 和 Stable Hash。Agent 不提交 Hash，也不能使用其他 Execution 或外部来源的候选。`--result-item` 只用于已持有当前 Execution 内部句柄的受控恢复，不应要求用户提供。
 
+## 规划动作（rail.progressive.v2）
+
+`services next` 的 `rail_planning.available_actions` 会给出可直接执行的完整命令。规划动作只允许以下类型，由 planning owner 校验执行归属、plan 状态与幂等键，不影响 Arazzo `human_action` 状态机或公共执行状态：
+
+| action_type | 供应商消耗 | 说明 |
+| --- | --- | --- |
+| `workflow:expand_search` | 有界新增查询 | 仅在扩展暂停（`expansion_status=paused`）时可用；必须带服务端下发的 `action_request_id`（`pa_…`）与 `expected_query_revision`，一轮一柄、用完作废。 |
+| `workflow:refine_preferences` | 无（本地重排） | 用 `--input-json` 提交偏好补丁，对已保存证据重排序。 |
+| `workflow:stop_search` | 无 | 停止未发送的扩展任务；不影响已开始或已完成的出票。 |
+| `select_journey` | 无 | 记录用户选定：`--input journey_id=<rj_…>`；仅记录选择、不改排名，后续购买仍走既有报价与受保护 Checkout。 |
+
+同一 `action_request_id` 相同内容重放返回原受理结果；相同 ID 不同内容会被判冲突。过期 `expected_query_revision` 的新动作被拒绝。
+
 ## 标准输出
 
 ```json

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

@@ -22,6 +22,7 @@ itpay services next <service_execution_id> [--json]
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
 | `service_execution_id` | 是 | `services start` 或后续命令返回的 execution ID。 |
+| `--since-snapshot <snapshot_id>` | 否 | rail.progressive.v2 增量读：传上次看到的 `snapshot_id`，未变化时只回扩展状态与 `result_not_updated`，不重复下发 journey 负载；永远不触发供应商调用。 |
 | `--json` | 否 | 输出稳定 JSON 信封；未指定时输出相同事实的简洁文本。 |
 
 需要有效 Agent Device session。命令不接受 Buyer token、capability 或服务输入。
@@ -291,3 +292,12 @@ itpay services get <service_execution_id> --json
 ## Agent Type / Host
 
 所有正式支持的 Local Agent Type 返回完全相同的状态、safe payload、instruction 和 next。本命令不渲染二维码，也不包含 Host handoff。
+
+## 渐进规划（rail.progressive.v2）
+
+智能铁路规划服务在执行读模型上附带 `rail_planning` 投影：`readiness`（pending/ready/expired）、`search.expansion_status`（queued/running/paused/complete/cancelled/failed/expired）、`recommendation` 与 `alternatives` 行程卡片、以及服务端给出的完整 `available_actions` 命令。
+
+- `running`/`queued`：稍后按 `next.command` 增量轮询同一执行；不要重新发起查询。
+- `paused`：首批结果已就绪、扩展暂停等待用户意图；`expand_search` 是唯一会再消耗供应商配额的动作。
+- `complete`：扩展收敛；展示推荐并等待用户选票。
+- 选票走 `select_journey` 动作（命令在 `available_actions` 或卡片的 `select` 字段里，原样执行）；乘车人身份信息永远只在受保护 Checkout 页面填写。

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

@@ -14,7 +14,9 @@
 ## 语法与参数
 
 ```bash
-itpay services page <service_execution_id> <result_item_id> [--offset <offset>] [--limit <limit>] [--json]
+itpay services page <service_execution_id> <result_item_id> [--offset <offset>] [--limit <limit>] [--cursor <rcur_n>] [--json]
+
+rail.progressive.v2 中 `<result_item_id>` 也可以是规划快照 ID（`rps_…`，见 `services next` 返回的 `snapshot_id`）：分页读取该不可变快照内的 journey 卡片，`--cursor` 使用上一页返回的 `rcur_<offset>` 不透明游标。
 ```
 
 | 参数 | 必填 | 说明 |

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

@@ -18,8 +18,12 @@ itpay services read-result <service_execution_id> [--json]
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
 | `service_execution_id` | 是 | Vault 交付对应的 execution ID。 |
+| `--journey <journey_id>` | 否 | rail.progressive.v2 规划明细：读取指定 journey 的完整卡片（分段、席别报价、接驳估计、风险标注）。免费、属主校验、不触发供应商调用。 |
+| `--snapshot <snapshot_id>` | 否 | 与 `--journey` 配合，钉住某个已提交快照（`rps_…`）；缺省时读最新 catalog 快照。 |
 | `--json` | 否 | 输出稳定 JSON 信封；未指定时输出相同事实的简洁文本。 |
 
+带 `--journey` 时走规划读取分支：不经过 grant/Vault、不受 `access_locked` 影响，因为规划明细本就是免付费证据。未带选择器时原授权路径完全不变。
+
 CLI 使用已登记设备的签名 session，不接受 Checkout token、Buyer token、`agent_device_id` 参数或开发者凭证。
 
 CLI 直接请求 Backend 的当前有效 Grant。历史 `delivery_bindings` 不作为访问判断；Backend 负责验证当前 Vault、Agent instance、Buyer、scope、TTL 和退款锁。

package/package.json

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

package/skills/itpay/SKILL.md

@@ -76,6 +76,13 @@ platform whenever possible. Only show the same clickable URL when no browser
 or native action is available; never ask the human to run a command or rebuild
 a QR code.
 
+Checkout handoffs also carry `handoff.mobile_url`: send it alongside the main
+link and tell the human that on a phone it opens the cashier and can jump
+straight into Alipay or WeChat Pay. When the current client cannot open links
+itself (for example a mobile mini program without a side panel), send
+`mobile_url` and tell the human to copy it into the phone's browser if it does
+not open in place.
+
 ## Serve The Human
 
 - Ask the human only to choose, authorize, pay, provide required contact