@itpay/cli 2.1.17 → 2.1.19

package/dist/src/state/device_authority.js

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

package/dist/src/state/task_journal.js

@@ -0,0 +1,88 @@
+// Minimal local task journal: which Service Executions are paused at a human
+// gate (login, rate limit) and how to resume the SAME execution. It stores
+// no chat history, PII, credentials or tokens — only ids, stage and the
+// resume command the owner flow already emitted. Business truth stays
+// server-side; this file only makes "continue" point at the right task.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+export const PAUSED_STAGES = new Set([
+    "login_required",
+    "rate_limited",
+    "quota_paused",
+    "auth_pending",
+    "awaiting_input",
+]);
+const TERMINAL_STAGES = new Set([
+    "completed",
+    "delivered",
+    "issued",
+    "failed",
+    "cancelled",
+    "refunded",
+]);
+export class TaskJournal {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    record(task) {
+        const file = this.readFile();
+        file.tasks[task.service_execution_id] = {
+            ...task,
+            updated_at: new Date().toISOString(),
+        };
+        this.writeFile(file);
+    }
+    clear(serviceExecutionID) {
+        const file = this.readFile();
+        if (!file.tasks[serviceExecutionID])
+            return;
+        delete file.tasks[serviceExecutionID];
+        this.writeFile(file);
+    }
+    // Observe the latest stage without deleting history; terminal stages stop
+    // the task from counting as resumable.
+    observe(serviceExecutionID, stage, resumeCommand) {
+        const file = this.readFile();
+        const existing = file.tasks[serviceExecutionID];
+        file.tasks[serviceExecutionID] = {
+            service_execution_id: serviceExecutionID,
+            ...(existing?.service_id ? { service_id: existing.service_id } : {}),
+            stage,
+            ...(resumeCommand ?? existing?.resume_command ? { resume_command: resumeCommand ?? existing.resume_command } : {}),
+            updated_at: new Date().toISOString(),
+        };
+        this.writeFile(file);
+    }
+    // Tasks paused behind login/quota gates, newest first. Terminal or
+    // completed tasks never count as "still waiting for login".
+    pausedTasks() {
+        const file = this.readFile();
+        return Object.values(file.tasks)
+            .filter((task) => PAUSED_STAGES.has(task.stage) && !TERMINAL_STAGES.has(task.stage))
+            .sort((left, right) => right.updated_at.localeCompare(left.updated_at));
+    }
+    readFile() {
+        if (!existsSync(this.path))
+            return { schema_version: "itpay.task_journal.v1", tasks: {} };
+        try {
+            const parsed = JSON.parse(readFileSync(this.path, "utf8"));
+            if (parsed.schema_version !== "itpay.task_journal.v1" || !parsed.tasks || typeof parsed.tasks !== "object") {
+                return { schema_version: "itpay.task_journal.v1", tasks: {} };
+            }
+            return parsed;
+        }
+        catch {
+            return { schema_version: "itpay.task_journal.v1", tasks: {} };
+        }
+    }
+    writeFile(file) {
+        // Bound the journal: keep only the 50 most recent task records.
+        const entries = Object.entries(file.tasks).sort((left, right) => right[1].updated_at.localeCompare(left[1].updated_at));
+        file.tasks = Object.fromEntries(entries.slice(0, 50));
+        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+        const tmp = `${this.path}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(file), { mode: 0o600 });
+        renameSync(tmp, this.path);
+    }
+}

package/docs/agent/buyer/identity-and-sessions.json

@@ -90,5 +90,13 @@
     "lock",
     "window",
     "chat"
-  ]
+  ],
+  "auth_session_states": {
+    "stages": "The CLI now reports the auth session stage exactly as the server returns it: waiting_provider (show the handoff and wait), email_verification_required (the human must verify the emailed code on the auth page), merge_confirmation_required (an existing account matches — the human must confirm the merge on the auth page), provider_pending/pending (generic wait), completed (session done — bind it, do not restart).",
+    "terminal_states": "auth_expired/auth_denied/auth_cancelled/auth_failed mean this session is over; say so plainly and start a NEW session only if the human still wants in — never keep polling a dead one.",
+    "transport_unknown": "auth_session_unknown means a network error while polling — the outcome is unknown. Keep waiting on the SAME session (it may still complete); do NOT restart auth, and do not assume denial.",
+    "missing": "auth_session_not_found means the cached session is gone server-side; start a new login.",
+    "completed_resume": "When login completes, itpay auth login resumes the remembered pending service execution automatically when one exists — you do not need to find it yourself.",
+    "path_b": "A buyer who reaches checkout without a login completes identity inside the protected checkout page; never force a separate itpay auth login first."
+  }
 }

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

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

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

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

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

@@ -0,0 +1,68 @@
+{
+  "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": "Use the booking run response directly; call its next only if it is still waiting for progress.",
+      "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.",
+        "On booking_review_invalid, re-read this booking. A seat-code spelling correction may reuse the buyer's explicit approval only if train, actual seat class, passenger count, price, and terms are unchanged; confirm material changes or missing approval.",
+        "Passenger names, ID numbers and phones are NOT in this input — they belong to the protected checkout page."
+      ]
+    },
+    {
+      "step": "checkout_handoff",
+      "read": "The current booking response may already contain handoff.url (the protected checkout page).",
+      "command": "Only if the current handoff was not presented, use the exact checkout command returned by the CLI.",
+      "notes": [
+        "Show or open the checkout exactly once; pass --viewer mobile when the buyer is on a phone.",
+        "The buyer completes identity and payment on that page (Path B — no forced separate login). Payment handoff is not payment success; wallet return is not confirmation."
+      ]
+    },
+    {
+      "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.17",
+  "version": "2.1.19",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {