@itpay/cli 2.1.10 → 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/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,
@@ -1582,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

@@ -1356,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),
         });
@@ -1601,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, {
@@ -1621,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.10";
-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/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.10",
+  "version": "2.1.11",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {