@itpay/cli 2.1.12 → 2.1.18

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

@@ -13,7 +13,7 @@
     "A query returned login_required or rate_limited."
   ],
   "service_selection": {
-    "itpay-rail-exact": "Use when the buyer knows BOTH the exact departure and arrival railway station names (e.g. 古镇 → 广州南). Direct train query, fastest path. Do NOT use it with only a city or fuzzy location.",
+    "itpay-rail-exact": "Use when the buyer knows BOTH the exact departure and arrival railway station names (e.g. 古镇 → 广州南). It is one station-pair + one travel_date query: filter the returned list locally for remembered train numbers or time windows — do NOT re-query per train. Do NOT use it with only a city or fuzzy location.",
     "itpay-rail-smart": "Use when the buyer has a city name, an area, an address, or wants transfer planning and recommendations. The platform resolves locations to stations itself; never silently convert a city into its namesake station.",
     "itpay-rail-booking": "Purchase service — use ONLY after the buyer explicitly chose a train and seat from a query result. Starts quote → protected checkout → payment → asynchronous issuance on one execution. Never queried for schedules.",
     "svc_qizhidao_company_lookup": "Not a railway service; do not mix intents."
@@ -67,7 +67,7 @@
       },
       "explicit_legs": {
         "passengers": "Integer 1-5.",
-        "legs": "Array of 1-3 legs, each: from_station_code, to_station_code, travel_date, train_code, departure_time (HH:MM), arrival_time (HH:MM), arrival_days (int 0-7), seat_type. Only use when no booking_offer is available; never guess these values."
+        "legs": "Array with exactly ONE leg: from_station_code, to_station_code, travel_date, train_code, departure_time (HH:MM), arrival_time (HH:MM), arrival_days (int 0-7), seat_type. The public review accepts a single leg; only use when no booking_offer is available, and never guess these values. For v2 separate_legs_only journeys, book one leg at a time via that leg's own booking_offer — never a multi-leg basket."
       },
       "boundary": "Identity fields (names, ID numbers, phones) never belong in this input; they are collected on the protected checkout page."
     }
@@ -92,6 +92,7 @@
     "Submit input with services run <service> --execution <id> --input-json <file> --json on the SAME execution.",
     "itpay-rail-smart may stop at a location confirmation step; show the candidate places to the buyer, then continue the same execution after the human confirms.",
     "After the buyer explicitly picks a train/seat, run itpay-rail-booking with the selection token (preferred) or explicit legs. The execution then pauses at the booking review (workflow:confirm_booking): services next returns booking_review_required with human_action.context.review carrying draft_revision, legs, seat_options and notice_version.",
+    "Whether or not the query was free, the answer is the same shape under compare: one preferred option, at most two meaningful alternatives, the key trade-offs — then stop and wait for the buyer. Do not stack more options or chain into purchase.",
     "Collect the review input and submit it with services action <id> --action workflow:confirm_booking --actor-type human --status approved --input-json <file> --json. Required fields: draft_revision (exact server value), passengers, seat_type, seat_preferences (one entry per passenger_index 0..n-1, values limited to that leg's seat_options), party_preference, fallback=automatic_assignment, notice_version, accept_non_guaranteed=true. Only after an accepted review does the server quote and offer checkout.",
     "The booking execution reaches a protected checkout: passenger identity data is entered by the human on that page, never through the CLI. Account authentication may happen inside checkout — do not force a separate auth login first (Path B).",
     "Payment success does not mean the ticket is issued. Issuance is asynchronous; keep reading the same execution with services next.",
@@ -122,6 +123,7 @@
   },
   "agent_rules": [
     "Pick the service by the buyer's input precision: exact station names → itpay-rail-exact; anything fuzzier → itpay-rail-smart; explicit purchase intent after a selection → itpay-rail-booking.",
+    "Choose the goal first (see goals): compare presents one preferred option plus at most two meaningful alternatives then waits; prepare_checkout selects under the buyer's rules and continues to the official confirmation entry without re-asking.",
     "Never invent input field names. If the guidance block or this doc does not list a field, do not send it.",
     "Never ask the buyer for passenger names, ID numbers, or phone numbers in chat; those are collected only on the protected checkout page.",
     "Never reconstruct provider-shaped legs JSON when a booking_offer.selection_token is available; submit the token plus passengers.",
@@ -187,5 +189,17 @@
     "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."
+  },
+  "goals": {
+    "compare": "Buyer wants to see options and keeps the final choice. Present one preferred option plus at most two meaningful alternatives, then wait. A fully-specified query with no purchase delegation stays compare.",
+    "prepare_checkout": "Buyer named the product, or delegated selection under explicit rules and asked for the purchase entry. Select under those rules, explain the match, and continue to the official confirmation/payment entry without re-asking '要不要买'. Clear delegation missing only the date asks for the date alone.",
+    "boundaries": [
+      "Decide locally from the whole conversation (negations, conditions, references, latest withdrawal); no trigger-word lists, no regex, no field-completeness classifier, no mode flag, never ask the human to name a mode.",
+      "Explicit buyer rules outrank default recommendations; missing facts are unknown, never assumed satisfied.",
+      "compare must not continue into selection; prepare_checkout must not silently downgrade to waiting.",
+      "A pending/login/error state is never new intent; withdrawal updates the goal but never rewrites a completed payment.",
+      "Neither goal authorizes payment or skips confirmation: payment, terms and passenger identity stay behind their own gates."
+    ],
+    "recipe": "For the query→booking→review→checkout continuity after a valid selection, load the rail-fast-checkout topic (itpay docs show rail-fast-checkout --json)."
   }
 }

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

@@ -0,0 +1,67 @@
+{
+  "schema_version": "itp.agent_doc.v1",
+  "role": "buyer_agent",
+  "product_scope": "itpay_rail",
+  "topic": "rail-fast-checkout",
+  "title": "Rail Fast Checkout — One Human Question, Owners Do The Rest",
+  "purpose": "After the buyer has picked a train/seat (prepare_checkout delegation), carry one valid selection through booking review, protected checkout and issuance tracking with a single consolidated human interaction — using only existing commands and owner-issued handles.",
+  "when_to_use": [
+    "The buyer explicitly picked a train/seat or delegated selection under rules, and you hold a bookable option with booking_offer.selection_token from itpay-rail-exact or itpay-rail-smart.",
+    "Do NOT use for a plain schedule query (compare goal) — present one preferred option plus up to two alternatives and wait instead."
+  ],
+  "steps": [
+    {
+      "step": "create_booking_input",
+      "command": "printf '%s' '{\"passengers\":1,\"selection\":{\"token\":\"<token>\"}}' > /tmp/itpay-booking-input.json",
+      "notes": [
+        "Fill <token> with the current result's booking_offer.selection_token; add selection.seat_type when the buyer picked a class. Create the file yourself under /tmp — the buyer never sees a path.",
+        "Never reconstruct legs JSON when a token is available; the owner derives authoritative legs and re-quotes live."
+      ]
+    },
+    {
+      "step": "start_booking",
+      "command": "itpay services run itpay-rail-booking --input-json /tmp/itpay-booking-input.json --json",
+      "then": "itpay services next <execution_id> --json",
+      "expected_status": "booking_review_required"
+    },
+    {
+      "step": "one_consolidated_review",
+      "read": "human_action.context.review carries legs, seat_options, draft_revision and notice_version.",
+      "ask_human_once": "Show the itinerary, seat options and the seat-preference disclaimer in one message; collect passengers count, seat_type, one seat preference per passenger slot, party_preference, and agreement to the notice_version terms.",
+      "web_review": "If the review projection carries an official web entry (handoff.url in the envelope), prefer it: open it for the buyer and wait there; the chat fallback remains valid if the page is unavailable.",
+      "submit": "itpay services action <execution_id> --action workflow:confirm_booking --actor-type human --status approved --input-json /tmp/itpay-review.json --json",
+      "notes": [
+        "draft_revision must equal the current server value; booking_review_changed means re-read services next and resubmit, never bump locally.",
+        "accept_non_guaranteed is true only when the buyer actually agreed; never fabricate a human approval.",
+        "Passenger names, ID numbers and phones are NOT in this input — they belong to the protected checkout page."
+      ]
+    },
+    {
+      "step": "checkout_handoff",
+      "read": "services next returns checkout_required/payment_pending with handoff.url (the protected checkout page).",
+      "command": "itpay checkout --id <checkout_id> --token <display_token> --present auto --json",
+      "notes": [
+        "Show or open the checkout exactly once; pass --viewer mobile when the buyer is on a phone.",
+        "The buyer completes identity and payment on that page (Path B — no forced separate login). Payment handoff is not payment success; wallet return is not confirmation."
+      ]
+    },
+    {
+      "step": "track_issuance",
+      "command": "itpay services next <execution_id> --json",
+      "then": "itpay orders show <order_id> --json",
+      "expected_status": ["paid_pending_issuance", "issued"],
+      "notes": [
+        "Issuance is asynchronous — paid does not mean ticketed. Keep reading the SAME execution; never create a replacement.",
+        "On issued, report the order state; if seat details are still syncing, advise checking 12306 instead of re-querying."
+      ]
+    }
+  ],
+  "never": [
+    "Never build legs JSON from visible result fields while a selection_token exists.",
+    "Never run a second services run for the same selection — repeat submission restores the same execution.",
+    "Never ask for passenger identity, verification codes, or payment details in chat.",
+    "Never claim payment equals issuance, or a displayed handoff equals human approval.",
+    "Never invent command flags, action types, revisions or tokens; copy server-issued handles verbatim."
+  ],
+  "search_terms": ["fast checkout", "快速下单", "一键购票", "rail checkout recipe"]
+}

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

@@ -13,7 +13,10 @@
 
 ```bash
 itpay checkout [--id <checkout_id>] [--token <display_token>]
-  [--host <host>] [--target <target>] [--locale <zh-CN|en>] [--json]
+  [--host <host>] [--target <target>] [--locale <zh-CN|en>]
+  [--present <auto|browser|image|link|none>] [--no-open] [--viewer <desktop|mobile|unknown>]
+  [--relay-option <ref>] [--confirm-relay] [--request-key <key>] [--relay-status <relay_id>]
+  [--json]
 ```
 
 省略 `--id/--token` 时只能使用本机保存的一组完整句柄；不得把其他 Checkout 的 token 拼接使用。
@@ -22,6 +25,12 @@ itpay checkout [--id <checkout_id>] [--token <display_token>]
 
 `--locale` 默认 `zh-CN`，可显式使用 `en`。它只改变重新渲染的 Card 文案，不改变 Checkout、付款、授权或恢复状态。
 
+展示控制（display plane，不创建任何新的付款路径）：
+
+- `--present` 一次只选一种展示方式：`browser` 打开系统浏览器、`image` 展示官方二维码图片、`link` 给出可点击链接、`none` 只说明状态、`auto`（默认）按宿主能力选择一种。`--json` 下默认只返回展示计划而不执行打开；显式 `--present browser` 即是一次打开请求。`ITPAY_NO_BROWSER=1` 与 `--no-open` 都禁止打开浏览器。已付款、已退款或报价失效的 Checkout 不会发起任何展示动作，只读取原状态。
+- `--viewer` 告知用户正在看哪类设备：`mobile` 时不会把二维码当作同机可读方式；`desktop` 时才考虑打开浏览器。
+- 消息转发（relay）要求服务端已签发的脱敏联系人引用 `--relay-option`、稳定幂等键 `--request-key` 和显式人类同意 `--confirm-relay`，三者缺一不可；CLI 不自行发送短信或邮件。`--relay-status <relay_id>` 只读取一次既有转发结果，绝不重发。`--present` 与 relay 互斥。当前 Backend 未提供 relay 能力时会如实返回不可用。
+
 ## 等待付款输出
 
 ```json

package/docs/reviews/agent-ux-handoff-2026-09-23/IMPLEMENTATION-EVIDENCE.md

@@ -0,0 +1,174 @@
+# Agent UX Handoff — CLI Implementation Evidence
+
+Implements the W0–W7 contract from
+`compose:docs/reviews/agent-ux-handoff-2026-09-23/README.md` (PR #215,
+branch `spec/agent-ux-human-handoff-20260923`). Scope: `@itpay/cli` only, plus
+the one compose-side AUTH05 gate fix. No Planner V2 behavior changed; no new
+payment path; protected Checkout remains the only identity/payment surface.
+
+## W0 — Baseline fingerprint
+
+| Item | Value |
+|---|---|
+| CLI baseline commit | `760d20420ab71b7df0e61540bf5fd93543bfeb5a` |
+| Package version | `@itpay/cli@2.1.17` (already published to `next`) |
+| Node / npm | v24.10.0 / 11.6.1 |
+| Baseline tests | 292/292 pass at baseline |
+| Post-change tests | 309/309 pass (`npm test`), `npm run test:package` → `packed CLI smoke passed` |
+| Coverage gate | lines 85.79 / statements 85.79 / functions 93.24 / branches 77.06 — all above thresholds (85/85/90/70) |
+| Compose side | AUTH05 gate change + unit test; `go build ./...` clean, `internal/app/identity` + `internal/adapters/postgres` tests pass |
+
+## Contract preserved / extended
+
+- `status`/`result`/`handoff`/`instruction`/`next`/`recovery` unchanged.
+- New optional `interaction` (`itpay.interaction.v1`: `stage`, `by_goal`,
+  `input_template`, `recipe`) and `communication` (`itpay.communication.v1`:
+  `status_line`, `recommended_reason`, `human_steps`, `next_expectation`,
+  `must_convey`).
+- All nested `itpay ` command strings inside `result`, `handoff`,
+  `interaction` and `communication` are qualified by `qualifyCommandsDeep`
+  (Agent Type + Backend URL) at envelope write time (`src/commands/guidance.ts`).
+- `next` is `null` whenever no fully-bound executable exists; unresolved
+  values live in `input_template` with `required_input` + `executable:false`.
+
+## Issue → fix → verification map
+
+### AUTH (src/state/account_auth.ts, src/state/task_journal.ts, src/main.ts, tests/ux_envelope.test.ts)
+
+| Issue | Fix | Test |
+|---|---|---|
+| AUTH01 pending compression | `stage` is reported verbatim; `email_verification_required`/`merge_confirmation_required` get distinct instructions | `AUTH01: distinct pending stages…` |
+| AUTH02 completed→replaced | completed open session binds in place via stored start_token; no second auth session is created | `AUTH02: binds in place` (asserts zero POST to `/v1/dashboard/auth-sessions`) |
+| AUTH03 transport→new session | poll/bind/绑定状态 transport failure → `auth_status_unknown`; saved session file preserved; no new request | `AUTH03: transport failure keeps the saved session…` |
+| AUTH04 placeholder resume | `TaskJournal` (`~/.itpay-v3/tasks.<env>.json`) records paused executions; `authenticated` resumes the exact journaled command or explicitly says none exists | `AUTH04: resumes the exact journaled task` + `…says so instead of emitting a placeholder` |
+| AUTH05 wallet login gate | compose: `RequireVerifiedContact` = phone OR email verified; Checkout-bound sessions keep Path B exemption | `TestDashboardWalletGateAcceptsPhoneOrEmailAndKeepsCheckoutExemption` |
+| AUTH06 raw JSON output | `itpay auth login|status` goes through `writeCommandEnvelope` (qualified, human-readable non-JSON, clean `--json`) | exercised via `agentAuth` envelope assertions |
+| AUTH07 status classification | `auth_session_missing` (404/410), `auth_status_unknown` (transport), `login_required` (no session), terminal states distinct (`auth_expired/denied/cancelled/failed`) | `AUTH07: server-side missing…` + `terminal auth states…` |
+| SEC01 credential exposure | auth handoff marked `contains_credentials: true`; instruction forbids writing start_token into chat/logs | code review + handoff field assertion |
+
+### W3 services continuity (src/commands/services.ts)
+
+| Requirement | Implementation |
+|---|---|
+| Two-goal semantics | `interaction.by_goal.compare` (present ≤3 options, stop) / `prepare_checkout` (select under user rules → continue to official entry, no re-ask) on `query_results_ready` |
+| No fake executable next | `select`/`book`/`<rank>`/`<file>` placeholders moved to `interaction.input_template`/`booking_template` with `executable:false`; `next` holds only fully-bound commands or `null` |
+| Server-issued actions verbatim | `available_actions[]` copied through untouched |
+| `planning` progress state | `communication` block (status_line/next_expectation/must_convey) without selection semantics |
+| Booking review | `booking_review_required` keeps legs/seat_options/draft_revision/notice_version disclosure; consumes optional `review.web_review_url|entry_url` as `handoff` when the owner projects one (W4 web-review seam); chat consolidated review remains fallback; never fabricates approval |
+| Journal writes | `runServicesNext` observes every envelope into `TaskJournal` |
+
+### W5 presentation/relay (src/state/client_context.ts, src/commands/presentation.ts, src/render/browser.ts, src/commands/checkout.ts, src/main.ts)
+
+| Requirement | Implementation |
+|---|---|
+| Context extension | `ViewerDevice`, `ExecutorLocality`, `ClientCapabilities`, `hostCapabilities()` — Agent Type is never used as viewer/executor proxy |
+| Deterministic resolver | `resolvePresentation`: business blockers first (paid/refund/unknown-amount → `read_same_order`, expired quote → `recover_expired_quote`, policy → blockers); then 1 recommended + ≤2 alternatives; explicit choice honored only when feasible; failed routes never silently retried; unknown capability ≠ yes; QR never offered to the mobile device being looked at; remote executor can't open a local browser |
+| `itpay checkout` flags | `--present auto\|browser\|image\|link\|none`, `--no-open`, `--viewer`, `--relay-option`, `--confirm-relay`, `--request-key`, `--relay-status`; present⊥relay mutually exclusive; `--json` plans without side effects, explicit `--present browser` is the display request |
+| Browser opener | argv-array spawn (no shell), HTTPS official origins only, loopback only behind `ITPAY_CLI_DEV=1`, no userinfo/arbitrary schemes; `dispatch_accepted` ≠ `page_loaded` |
+| Relay | `resolveRelay` enforces issued-option + request-key + explicit consent; backend capability absent → honest `unavailable`; `--relay-status` read-only |
+
+## Evidence separation (per W0/W7)
+
+| Class | Count | Where |
+|---|---|---|
+| In-process unit/contract tests (new) | 17 | `tests/ux_envelope.test.ts` |
+| Existing suite updated to new contract | 9 assertions moved to `interaction.*` | `tests/smoke.test.ts` |
+| Mock backend extended | auth sessions + binding endpoints + failure injection | `tests/mock_backend.ts` |
+| Packed-package smoke | pass | `npm run test:package` |
+
+## NOT executed — remains open for acceptance
+
+- No target-agent (Astra/harness) runs against real models.
+- No real browser/native-host display verification — only `isPresentableURL` +
+  argv construction are unit-tested; `openInSystemBrowser` spawn is not e2e.
+- No SMS/email/wallet relay test — backend relay endpoints do not exist; CLI
+  returns honest `unavailable`.
+- No payment/issuance/refund flow test — those owners were untouched.
+- Tarball-installed CLI behavior verified only by `scripts/package-smoke.mjs`,
+  not by a manual install run.
+- The 72-check matrix from `VALIDATION.json` maps to implementation status
+  here; actual model/host acceptance rows stay "not executed" — this document
+  does not claim them.
+
+---
+
+## Addendum — 09 Checkout Lifecycle & UX Repair (compose `codex/checkout-lifecycle-ux`, base `59f95a1`)
+
+Spec: `09-CHECKOUT-LIFECYCLE-AND-UX-REPAIR-20260927.md`. Implemented the
+server-owned payment deadline, checkout-scoped phone reuse, in-page desktop QR,
+and shared deadline projection; CLI consumes the same fields.
+
+### Single payable deadline D (backend)
+
+| Requirement | Implementation | Test |
+|---|---|---|
+| One deadline everywhere | `checkouts.expires_at` = `min(created_at + PaymentTTL(15m), earliest bound quote-lock expiry)` set in `CreateCheckout`; copied verbatim to `orders.payment_deadline_at` by `EnsurePendingOrderForAuthorizedCheckout`; legacy rows fall back to `PaymentDeadline(created_at, ttl, quote expiry)`, never re-anchored | `TestLifecycleSingleDeadlineRealPG`, `TestLifecycleEarlyQuoteWinsDeadlineRealPG` (real PG) |
+| Refresh never extends | persisted `expires_at` wins; reused intents keep their expiry | same test: second intent call returns identical `expires_at`, zero extra provider calls |
+| Expiry truly cancels | `ExpireStalePendingOrders` single-tx cascade: order→cancelled, checkout→expired, intents→expired, quote locks→expired, bindings→expired, executions→cancelled+event, display tokens→expired, auth sessions→expired; `FOR UPDATE SKIP LOCKED`; orphan executions swept only when no live payment path remains | `TestLifecycleExpirySweepCascadeRealPG`: pre-D no-op, post-D full cascade, repeat sweep idempotent |
+| Paid protected | candidate scan requires `status='pending_payment'`; conditional UPDATE loses the race to a verified payment | `TestLifecyclePaidSurvivesAndLateCallbackReconcilesRealPG` |
+| Late provider funds | `CompleteProviderPayment` returns `Reconciled:true`, persists funds evidence, never resurrects cancelled order | same test: late TRADE_SUCCESS after sweep → reconciled, order stays `cancelled` |
+| New actions refused at D | `ErrPaymentWindowClosed` → HTTP 410 `payment_window_closed`; `<1min` remaining refuses new QR/wallet actions; `paymentActionExpiry = min(now+actionTTL, D)` clamped into provider `TimeoutExpress`/`time_expire` | unit tests in `internal/app/payment`, `internal/httpapi/handlers`; PG test asserts intent `expires_at = D` |
+
+### Phone (checkout-scoped, privacy-preserving)
+
+- `ports.BuyerProfile` exposes `LoginPhone`/`PhoneVerified`; presentation projects
+  `account_phone_option` = `{source, masked_recipient}` only — the raw number
+  never leaves the server.
+- `order_contacts` rows are checkout-scoped: `InsertAccountOrderContact` copies
+  the verified account phone under a row lock (refused on expired/terminal
+  checkout, `ErrOrderContactLocked` once a payment action exists);
+  `GetVerifiedOrderContact` feeds `RequireDeliveryContact` and the masked
+  `verified_sms_contact` projection.
+- Replacement phone = OTP-verified `order_contact` challenge; it never writes
+  the account login phone. `UpdateDeliveryContact` gates `phone_source:
+  account_phone` on a live buyer session and reads the account-side verified
+  number server-side — client-submitted digits are not trusted.
+- Real-PG tests: `TestLifecycleOrderContactScopeRealPG` covers reuse
+  roundtrip, cross-checkout isolation, upsert versioning, post-payment lock,
+  expired-checkout refusal.
+
+### Shared projection & clients
+
+- `CheckoutPresentation`/`Order`/buyer summaries emit `payment_deadline_at`,
+  `server_now`, `payment_remaining_seconds`; expired pending orders project
+  `cancelled` and drop the deadline field.
+- Web: `paymentCountdown.ts` ticks from server values only (never extends);
+  `PaymentDeadlineBadge` shared by OrdersPage/OrderDetailPage; CheckoutPage
+  disables payment at zero and re-reads the backend; desktop Alipay QR renders
+  in-page via `qrcode` with the copy "展示付款码不会直接扣款".
+- CLI: `itpay checkout`/`itpay order` envelopes carry the same deadline fields;
+  pending instructions state the exact deadline and that refresh does not
+  extend it; expiry guidance routes to re-quote rather than replaying stale
+  payment actions. `Order`/`CheckoutPresentation` types extended in
+  `src/client/types.ts`.
+
+### Harness fix (per §6)
+
+- `ux_harness.py` interventions now classify `human_product_step` (login/OTP/
+  passenger confirmation/QR scan — requires step+operator+scope+a same-order
+  backend_observation in `verification_event_ids`) vs `engineering_rescue`
+  (still fail); unclassified legacy entries stay conservative.
+- `relative_file` no longer rejects runs under symlinked tempdirs (macOS
+  `/var`→`/private/var`); symlink checks now apply inside the run dir only.
+- Prompts updated (UI-OPERATOR/USER-SIMULATOR/ASTRA-REVIEWER/README).
+- `test_harness.py` 25/25, including 6 new classification cases.
+
+### Actually executed (this round)
+
+- Backend unit: `go test ./internal/app/{checkout,payment,order,railbooking,identity} ./internal/presenter ./internal/httpapi/handlers` — all green.
+- Real PG (`ITPAY_V3_TEST_DATABASE_URL`, isolated per-test DB): 6 new
+  lifecycle tests + golden regression suite (`SearchSelectCheckoutGoldenFlow`,
+  receipt aggregation, provider-failure, quota transition) — all green.
+- Web: `npm run typecheck` clean; `npm test` 73/73.
+- CLI: 309/309 tests (240 smoke + 69 unit), tarball package smoke previously
+  green; contract/package `tsc` clean.
+- Harness: `python3 -m unittest test_harness` 25/25.
+
+### NOT executed (unchanged honesty)
+
+- No real Alipay/WeChat channel call — fake `AlipayPaymentClient` records
+  requests only; provider sandbox validation remains open.
+- No real browser e2e of the QR modal / countdown; no real-device OTP.
+- No deployed dev-environment verification of the new checkout path.
+- Harness changes are structural (classifier + fixtures); no real triadic run
+  was executed.

package/package.json

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

package/skills/itpay/SKILL.md

@@ -41,13 +41,53 @@ Three services, three different jobs — pick by the human's input, never merge
 | City/area/address, or wants transfer planning | `itpay-rail-smart` (location resolution + planning) |
 | Chose a train/seat and wants to buy | `itpay-rail-booking` (quote → protected checkout → issuance) |
 
+### Choose The Goal First
+
+From the full context — negations, conditions, references, the latest
+withdrawal — decide locally between two goals. Never use keyword lists,
+regular expressions, or field-completeness as a classifier, and never ask the
+human to name a mode. There is no `--mode` flag.
+
+- `compare` — the human wants to see options and keeps the final choice.
+  Present one preferred option plus at most two meaningful alternatives, then
+  stop and wait. All fields being present does not authorize a purchase.
+- `prepare_checkout` — the human named the product, or delegated selection
+  under explicit rules and asked for the purchase entry. Select a valid option
+  under those rules, then continue to the official confirmation/payment entry
+  without asking "要不要买" again. If the delegation is clear but one required
+  fact (e.g. the date) is missing, ask only for that fact — not whether to buy.
+
+Default to `compare` when delegation is unclear. A pending, login, or error
+state is never new user intent; withdrawal updates the goal immediately but
+never rewrites a completed payment.
+
+Explicit user rules outrank default recommendations: "13:00之后最早够两张二等座，
+没有就往后找" means same date, same station pair, seat-class + quantity filter,
+departure-time order — not per-train re-queries, date changes, station swaps,
+upgrades, waitlists, or endless retries. Missing facts are `unknown`, never
+assumed satisfied. "08:00出门" includes ground transfer and station buffer;
+"当天到" checks the calendar date, not just the clock time.
+
+`itpay-rail-exact` is one station-pair + date query — filter the returned list
+locally rather than re-querying per remembered train number. Model memory
+supports route hypotheses only, never same-day schedule/price/inventory facts.
+A saved snapshot's pages, journey detail and rerank are free reads; a new live
+observation needs the owner's authorization.
+
+After a valid selection under `prepare_checkout`, the short
+`rail-fast-checkout` recipe covers query→booking→review→checkout continuity:
+`itpay docs show rail-fast-checkout --json`. It reuses existing
+`services run`/`action`/`checkout` — no fast-buy command, no payment bypass,
+no fabricated human approval.
+
 Query results carry a server-issued `booking_offer.selection_token` on bookable
 options; for a purchase submit that token plus passenger count — never
 reconstruct train legs by hand. Passenger names, ID numbers and phone numbers
 belong only on the protected checkout page, never in chat. Each query service
-has its own free trial count (2+2, not a shared pool); `login_required` pauses
-the query, it is not a failure — resume the same execution after `itpay auth
-login`. For the full input contract and states, load the rail-booking topic via
+has its own free trial count
+(2+2, not a shared pool); `login_required` pauses the query, it is not a
+failure — resume the same execution after `itpay auth login`. For the full
+input contract and states, load the rail-booking topic via
 `itpay docs search rail-booking --json`.
 
 ## Follow One Envelope
@@ -61,6 +101,18 @@ For each JSON response:
    and any required human action is complete.
 5. Use `recovery` only when the normal continuation cannot proceed.
 
+Newer envelopes may also carry an `interaction` block (`stage`, `by_goal`,
+`input_template`, `recipe`) and a `communication` block (`status_line`,
+`recommended_reason`, `human_steps`, `next_expectation`, `must_convey`). These
+are the same meaning in three languages: the schema for machines, `instruction`
+for you, `communication` for what the human hears. They never disagree; if a
+host renders only one lane, `instruction` still tells you what to do.
+
+Two `input_template` details matter: entries whose `placeholders` field lists
+unresolved values are NOT executable — fill them and submit via `--input-json
+<file>`; and when `next` is `null`, the honest `input_template`/`recipe` path
+in `interaction` is the continuation — do not invent a direct command.
+
 Never print raw envelopes, commands, internal IDs, error classes, or technical
 diagnostics to the human. Explain the service result and the next human choice
 in ordinary language. When a boundary is unclear, load one topic only: