@itpay/cli 2.1.41 → 2.1.44

package/dist/src/state/task_journal.js

@@ -0,0 +1,90 @@
+// 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];
+        if (existing && existing.stage === stage && (resumeCommand === undefined || existing.resume_command === resumeCommand))
+            return;
+        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/cart-checkout.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 single public CLI entry point for Buyer services and the existing itpay sell Seller workflow; $itpay is its user-facing Skill invocation.",
   "topic": "cart-checkout",
   "title": "Canonical Cart And Checkout Routing",
   "purpose": "Use the canonical server Cart and route service-backed lines through Service Execution without hardcoded service logic.",
@@ -32,11 +32,12 @@
     }
   ],
   "agent_rules": [
-    "The Backend Cart is business truth; ~/.itpay-v3/cart.json only stores local recovery handles and explicit drafts.",
+    "The Backend Cart is business truth; the current backend-isolated local cart state file only stores local recovery handles and explicit drafts.",
     "Run the exact next.command returned by the CLI. Do not extract or invent a capability from a raw list.",
-    "One service intent uses one Service Execution. Start another execution for another independent intent.",
-    "Ask for email only when the selected capability requires protected delivery; never invent contact data.",
-    "A lost Checkout response is retried with the same Cart and persisted idempotency operation."
+    "Railway query and booking use distinct Service Executions for one purchase journey. Start another execution for an independent intent.",
+    "Only non-rail capabilities explicitly requiring delivery email may ask its purpose and value. Railway notification contact belongs to the protected checkout page with verified account email reuse; the Agent must not guess or collect it in chat.",
+    "A lost Checkout response is retried with the same Cart and persisted idempotency operation.",
+    "A single railway service checkout normally follows its booking execution; Cart is used only when the returned flow calls for it."
   ],
   "forbidden": [
     "Do not call ordinary buy for a service-backed Cart line.",
@@ -59,5 +60,6 @@
     "service execution",
     "resume",
     "contact"
-  ]
+  ],
+  "purchase_consent": "Candidate selection is not price approval. Service-backed quote/cart/checkout requires a current scoped approve_purchase record; use the complete server template, default false. Only genuine matching approval allows true; material price/subject/terms changes invalidate it. Restore an existing Checkout before creating anything."
 }

package/docs/agent/buyer/catalog-list.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 single public CLI entry point for Buyer services and the existing itpay sell Seller workflow; $itpay is its user-facing Skill invocation.",
   "topic": "catalog-list",
   "title": "Browse ItPay V3 Service Catalog",
   "purpose": "Explain available services, outcomes, conditions, and prices in human language without exposing catalog identifiers.",
@@ -18,25 +18,44 @@
   ],
   "output_interpretation": {
     "item_format": "Explain the title, what the human receives, any auxiliary discovery step, and the published price.",
-    "service_flow": "Explain discovery as an auxiliary identity-confirmation step, including free quota and paid continuation. Present primary_service as the actual paid outcome. Read all values from the manifest.",
+    "service_flow": "Legacy catalog only: read service_flow facts as published; do not reinterpret old discovery/paid identities as a new public definition. New definitions expose operations within one service.",
     "variant_selection": "Internal IDs are for the Agent's next command only and are never shown or requested from the human.",
-    "price_note": "amount_minor is in minor units (e.g., 10000 = 100.00 CNY). The CLI formats prices as XX.YY currency automatically."
+    "price_note": "amount_minor is in minor units (e.g., 10000 = 100.00 CNY). The CLI formats prices as XX.YY currency automatically.",
+    "railway": "Railway entries point to itpay docs show rail-booking; use its query and booking contracts instead of a generic start→invoke→cart sequence.",
+    "service_definition": "Prefer immutable service_definition: one public service with declared operations, pinned schemas and billing modes. Free query does not mean free purchase; dynamic needs a real quote. Do not choose a zero placeholder variant."
   },
   "agent_rules": [
     "Use catalog list only when the human asks for a new service, not when they want an earlier purchase.",
     "Read the variant IDs and prices from the output; do not invent them.",
-    "Explain the customer journey from service_flow instead of presenting every variant as an unrelated service.",
+    "Explain the returned public service operations and pricing; use legacy service_flow only when no service_definition is present.",
     "State free quota, paid continuation price, email requirement, and claim purpose exactly as published; do not exaggerate or omit conditions.",
     "Ask the human to choose only when multiple services could satisfy the goal; never make them choose an internal variant or offer ID.",
-    "After services start, submit service keywords only through the returned capability command's --input key=value options; --target is never a search keyword."
+    "Use each service’s returned input contract; railway planning and booking follow rail-booking, not a universal Cart route."
   ],
   "human_language": {
-    "prefer": ["服务", "查询", "报告", "免费次数", "价格", "你会得到什么"],
-    "avoid": ["service_id", "variant_id", "offer_id", "capability", "manifest"]
+    "prefer": [
+      "服务",
+      "查询",
+      "报告",
+      "免费次数",
+      "价格",
+      "你会得到什么"
+    ],
+    "avoid": [
+      "service_id",
+      "variant_id",
+      "offer_id",
+      "capability",
+      "manifest"
+    ]
   },
   "next_docs": [
     {
-      "condition": "Buyer selected a service and wants to purchase",
+      "condition": "Railway service selected",
+      "topic": "rail-booking"
+    },
+    {
+      "condition": "Non-rail Buyer selected a service and wants to purchase",
       "topic": "cart-checkout",
       "file": "docs/agent/buyer/cart-checkout.json"
     }
@@ -50,5 +69,6 @@
     "what to buy",
     "有哪些",
     "服务列表"
-  ]
+  ],
+  "purchase_consent": "Candidate selection is not price approval. Service-backed quote/cart/checkout requires a current scoped approve_purchase record; use the complete server template, default false. Only genuine matching approval allows true; material price/subject/terms changes invalidate it. Restore an existing Checkout before creating anything."
 }

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

@@ -1,18 +1,18 @@
 {
   "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 single public CLI entry point for Buyer services and the existing itpay sell Seller workflow; $itpay is its user-facing Skill invocation.",
   "topic": "identity-and-sessions",
   "title": "Device Identity And Session Recovery",
   "purpose": "Explain stable local identity, official Backend-scoped registrations, Agent Type instances, and bounded automatic session recovery.",
   "when_to_use": [
     "A different Agent window or runtime starts using an existing CLI installation.",
-    "The CLI reports device_state_unwritable, or the Backend reports agent_identity_required, agent_device_session_required, or agent_device_revoked.",
+    "The CLI reports device_state_unwritable, or the Backend reports agent_identity_required, agent_device_session_required, agent_device_not_found, or agent_device_revoked.",
     "An operator confirms that the currently selected official Backend registration database was reset."
   ],
   "identity_model": {
     "local_key": "One owner-only Ed25519 private key for the local installation.",
-    "backend_registration": "One registration per official Backend: app.itpay.ai by default and dev.itpay.ai only with the exact test override.",
+    "backend_registration": "One registration per configured official Backend. Follow the current CLI backend allowlist; do not switch to evade failures.",
     "agent_instance": "One instance per agent_type under each Backend registration; same-type windows and chats reuse it.",
     "presentation": "Host and target route output only and never identify the Agent or provide business input."
   },
@@ -21,13 +21,15 @@
     "On one HTTP 401 with code agent_device_session_required, it invalidates only the current Backend and Agent Type session, renews it, and retries the exact request once.",
     "A second failure is returned to the Agent. The CLI does not loop, switch Agent Type, rotate the key, or create a replacement v2 device.",
     "When a previously unseen Agent Type is registered under an existing Device, the CLI skips locally known Agent Instances that the Backend reports as revoked and uses the first remaining valid Instance. It never reactivates a revoked Instance or replaces the Device; if none is valid, registration stops.",
-    "A revoked v2 registration requires explicit operator recovery; it is never silently replaced."
+    "When the Backend reports agent_device_not_found (HTTP 404) for a locally known registration — for example after the Backend registration database was rebuilt — the CLI drops only that Backend's registration and re-enrolls once with the same private key, re-attaching to the same device and quota lineage where the Backend still holds the key.",
+    "A revoked v2 registration requires explicit operator recovery; it is never silently replaced.",
+    "Re-enrolling a public key the Backend already holds re-attaches to the existing device and quota lineage after proof-of-possession; it never creates a duplicate device. An internal_error is a server failure: preserve the key and wait for service recovery. If enrollment returns agent_device_key_rotated or agent_device_key_conflict, stop automatic recovery. Only an explicit human/operator decision to abandon the old identity permits reset-key; old execution access does not migrate."
   ],
   "local_state_recovery": [
-    "Device state updates use an atomic directory lock and owner-only atomic file replacement; no lock file is opened with fs.open or fs.openSync.",
+    "Device state uses an owner-only atomic file replacement and a lock that the CLI can inspect. On a stale lock, run the returned device repair-lock command; it only reclaims a proven stale owner.",
     "Operation idempotency uses one immutable owner-only record per operation key. Different commands and Agent processes do not share a global operation-journal lock; legacy operations.json is read only.",
     "On device_state_unwritable, use the reported operation and errno to diagnose the failing stage without exposing local paths; keep the same Agent Type and CLI/Node launcher, restore Host-approved persistent access to ~/.itpay-v3, then retry the original command.",
-    "Do not manually create or delete state locks, switch Node runtimes, delete identity, or rotate Agent Type as a retry strategy."
+    "Do not delete a live lock, switch Node runtimes, delete identity, or rotate Agent Type as a retry strategy."
   ],
   "commands": [
     {
@@ -44,19 +46,24 @@
       "intent": "recover after an operator-confirmed reset of the selected official Backend registration database",
       "command": "itpay --agent-type <agent_type> device recover --confirm-backend-reset --json",
       "success_signal": "only the selected Backend registration is removed and the private key and other Backend registration remain"
+    },
+    {
+      "intent": "repair only a proven stale local device lock",
+      "command": "itpay device repair-lock --json",
+      "success_signal": "the CLI reports whether the lock was stale and reclaimed; an active owner stays protected"
     }
   ],
   "agent_rules": [
     "Use the real runtime type and keep it stable across every command in the flow.",
     "Keep the same CLI/Node launcher and Host-approved permission context for the whole flow.",
     "Treat a new window, chat, task, or process of the same runtime as the same Agent Type, not a new identity.",
-    "Expect production traffic to use https://app.itpay.ai. Use https://dev.itpay.ai only for an explicit test and keep the complete returned Backend-prefixed command for that entire flow.",
+    "Production defaults to https://app.itpay.ai; explicit sandbox or dev testing uses https://sandbox.itpay.ai or https://dev.itpay.ai. Keep the complete returned Backend-prefixed command for that flow.",
     "After automatic recovery fails, stop and report the exact code, selected official Backend, Agent Type, and command family without exposing private keys or tokens."
   ],
   "forbidden": [
     "Do not delete ~/.itpay-v3, rotate the key, switch Agent Type, or repeatedly retry to obtain fresh quota.",
     "Do not use device recover for session expiry, revocation, quota recovery, or an unconfirmed Backend failure.",
-    "Do not redirect the CLI to test, local, an IP, or any custom Backend; only the exact official dev.itpay.ai test override is allowed.",
+    "Do not switch Backend to evade a failure. Allowed public URLs are app.itpay.ai, sandbox.itpay.ai and dev.itpay.ai; local loopback requires the explicit CLI development flag.",
     "Do not use --target as identity or service input."
   ],
   "next_docs": [
@@ -83,5 +90,15 @@
     "lock",
     "window",
     "chat"
-  ]
+  ],
+  "auth_session_states": {
+    "stages": "Report the actual server stage: waiting_provider (show the official handoff), email_verification_required (explicit or legacy identity verification; follow the current official page), merge_confirmation_required (the human must prove both accounts and explicitly confirm or cancel the frozen merge), provider_pending/pending (wait), completed (bind the original session and resume the same service). Ordinary login needs one verified supported identity; do not require both phone and email.",
+    "terminal_states": "auth_expired/auth_denied/auth_cancelled/auth_failed mean this session is over; say so plainly and respect denial or cancellation. Start a new session only on an explicit login request; never keep polling a dead one.",
+    "transport_unknown": "auth_status_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_missing means the cached session is gone. An explicit auth login opens one fresh official session in that call; auth status stays read-only.",
+    "completed_resume": "After login completes, execute the returned command to resume the same paused service execution. Login does not silently run that command.",
+    "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.",
+    "identity_binding": "Phone is recommended first, wallets next, email is a separate Other options choice. Extra identities are optional bindings. A phone conflict does not prove account ownership: independent target authentication and explicit human merge confirmation are required. Never use the same SMS proof twice, approve a merge for the user, or treat login/identity binding as payment consent. Service-specific contact requirements stay in the service."
+  },
+  "key_reset_decision": "Only after explicit user/operator acceptance of abandoning the old identity, consult device reset-key help; this is not automatic error recovery, and old execution access does not migrate."
 }

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.",
@@ -18,7 +18,7 @@
     {
       "intent": "list supported Agent Types",
       "command": "itpay install --json",
-      "success_signal": "status is install_targets and exactly eight supported Agent Type definitions are returned"
+      "success_signal": "status is install_targets and exactly nine supported Agent Type definitions are returned"
     },
     {
       "intent": "read setup for the real runtime",
@@ -28,33 +28,34 @@
     {
       "intent": "verify the selected official Backend",
       "command": "<execute the exact next.command returned by install>",
-      "success_signal": "status is ready and next points to the packaged Skill with the same Agent Type and Backend"
+      "success_signal": "ready proves Backend liveness only; retain the actual Agent Type and Backend, then verify device access"
     },
     {
-      "intent": "load the complete packaged operating contract",
-      "command": "<execute the exact next.command returned by readyz>",
-      "success_signal": "status is shown and next is null so the Agent can route the human's natural-language intent"
+      "intent": "verify device access after Backend liveness",
+      "command": "itpay auth status --json",
+      "success_signal": "authenticated or successful login_required proves device access; pending/unknown is not ready"
     }
   ],
   "agent_rules": [
     "For first setup, read the complete Skill from this installed package before network checks. Select the actual Agent Type once through install and retain the same launcher and Backend. Do not reread the same version Skill, repeat initialization for ordinary tasks, or start login or business to prove setup.",
-    "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://dev.itpay.ai; no other Backend is allowed.",
-    "minimum_cli_version is a protocol floor, not a verified matching artifact. If incompatible, stop and ask the maintainer for the matching distribution; do not guess a version or downgrade.",
-    "Only use verified matching artifacts; never change Agent Type or Device identity to recover compatibility.",
-    "Use one exact type: codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy, zcode, kimi-code, or openclaw.",
+    "Run installation separately and preserve full output and its exit code. Nonzero stops preparation even if an older CLI runs. Same-version reuse requires verified executable, registry channel target, contract and official source; do not force or bypass host protection.",
+    "Report ItPay ready only after Backend and device checks succeed; otherwise preparation is incomplete. Account login is not required for setup.",
+    "The current public setup link selects the channel and matching contract: latest/app for production, next/dev for beta. Do not let an old bundle or memory override this choice.",
+    "Production defaults to https://app.itpay.ai. Testing may set ITPAY_BACKEND_URL to the exact official URL the configured official test Backend only when explicitly requested; follow the CLI allowlist.",
+    "If Backend compatibility cannot be verified, stop this round. minimum_cli_version is a protocol floor, not a verified matching artifact. Ask the maintainer for the matching distribution; do not guess a version or downgrade.",
+    "Only install a replacement when its exact artifact and Backend contract have been verified; then reread that package Skill. Never change Agent Type or Device identity to recover compatibility.",
+    "Use one exact type: codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy, zcode, doubao-work, kimi-code, or openclaw.",
     "For compatibility, a global --agent-type codex declaration is normalized immediately to codex-desktop; all registration, output, and returned commands use codex-desktop. Never generate the alias, and do not use codex as an install target.",
-    "One local private key is reused, while Device registrations and quota lineage remain separate for app.itpay.ai and dev.itpay.ai.",
+    "One local private key is reused, while Device registrations and quota lineage remain separate for app.itpay.ai, sandbox.itpay.ai and dev.itpay.ai.",
     "Within each official Backend registration, each Agent Type has one Agent Instance; all windows and chats of the same type reuse it.",
     "Agent Type identifies the runtime. Host and target only select a presentation destination; load render-hosts only when a handoff cannot be shown.",
     "Keep the exact Agent Type in every next or recovery command; do not fall back to a type previously used by another runtime.",
     "Do not change Agent Type or rotate local identity to reset quota or recover a failed command.",
-    "For production setup, itpay device status --json verifies the device against the current Backend. device_ready does not establish account binding; binding is unavailable to this CLI and no auth login action is inferred."
+    "Skillhub and local host bundles are separate installed artifacts; verify their version and packaged Skill/docs instead of assuming an npm update changed them."
   ],
   "forbidden": [
     "Do not use terminal, claude-code, or plain-chat as Agent Types. Do not generate codex as an Agent Type; it is accepted only as a legacy global declaration and becomes codex-desktop before any request.",
-    "Do not set or suggest any Backend except the default https://app.itpay.ai or the exact test override https://dev.itpay.ai.",
+    "Do not set or suggest a Backend outside the CLI allowlist: https://app.itpay.ai, https://sandbox.itpay.ai, https://dev.itpay.ai; local loopback requires the CLI development flag. Do not switch Backend to evade a failure.",
     "Do not claim that install writes host configuration or registers a device; it only prints instructions.",
     "Do not create a new identity for a different window, task, chat, or process of the same Agent Type."
   ],
@@ -77,6 +78,7 @@
     "claude code",
     "workbuddy",
     "zcode",
+    "doubao work",
     "kimi code",
     "openclaw"
   ]

package/docs/agent/buyer/orders-refunds.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 single public CLI entry point for Buyer services and the existing itpay sell Seller workflow; $itpay is its user-facing Skill invocation.",
   "topic": "orders-refunds",
   "title": "Order, Delivery, Customer Care And Refund Recovery",
   "purpose": "Explain paid-order and delivery problems to the human, then read or manage the same owned Order without guessing payment, consumption, or refund state.",
@@ -16,6 +16,11 @@
       "command": "itpay --agent-type <agent_type> order <order_id> --json",
       "success_signal": "one compact owned-order summary and one current next step are returned"
     },
+    {
+      "intent": "read railway refund/change targets and complete current input templates",
+      "command": "itpay --agent-type <agent_type> aftercare list --order <order_id> --json",
+      "success_signal": "safe original itinerary, available leg/passenger targets, requests and full refund/change templates"
+    },
     {
       "intent": "request a refund",
       "command": "itpay --agent-type <agent_type> refund create --order <order_id> --reason buyer_requested --json",
@@ -34,19 +39,23 @@
     {
       "intent": "cancel before provider submission",
       "command": "itpay --agent-type <agent_type> refund cancel <refund_request_id> --json",
-      "success_signal": "the Refund Owner cancels the request and requires a new delivery authorization"
+      "success_signal": "the Refund Owner returns the current cancellation and access state; old grants do not revive"
     }
   ],
   "agent_rules": [
     "Act as the human's ItPay service representative: explain payment, delivery, access, and refund facts in plain language before giving the next action.",
     "After verified payment, say the Order is recorded and the human must not pay again. Recover that same Order or Service Execution if delivery is delayed or fails.",
     "ItPay derives payment, amount, currency, account ownership, and refund policy from the owned order; explain only their user-facing meaning.",
-    "Unconsumed delivery normally follows the automatic policy; consumed delivery normally requires manual review. These are policy routes, not promises of a successful or instant refund.",
+    "A railway order can contain 1–3 legs paid together and issued separately. Report all-issued only when every leg is issued; retain issued tickets on a partial failure or unknown result. Railway return and platform refund follow per-leg supplier facts; do not promise a full refund or create replacement tickets.",
+    "Read this order’s current refund policy. Railway return depends on supplier ticket facts and may require manual review; platform refund status alone does not prove a train ticket was returned.",
     "A refund request freezes all delivery paths and revokes existing grants immediately.",
-    "Cancellation or rejection restores eligibility but never reactivates an old grant.",
-    "Use get or watch after interruption; do not infer success from elapsed time.",
+    "Cancellation or rejection follows the returned order policy and never reactivates an old grant automatically.",
+    "Use get after interruption; explicit watch defaults to a bounded 20-second window and returns on change or manual attention. Do not restart watch automatically or infer success from elapsed time.",
     "Never switch CLI/MCP lanes or identities to recover an order or refund error.",
-    "A read-only MCP Agent may explain policy and order facts, but directs refund actions to the ItPay Dashboard or a full Local CLI Agent."
+    "A read-only MCP Agent may explain policy and order facts, but directs refund actions to the ItPay Dashboard or a full Local CLI Agent.",
+    "Railway refund or manual change: use aftercare list for structured ticket targets. Match the user’s explicit legs/passengers; only ask when that scope is missing. Explain the scope and manual handling before create using the returned complete JSON. No supplier reference or amount is needed from the user.",
+    "Aftercare acceptance, supplier completion and platform money status are separate. Only real scope consent may set user_confirmed_scope=true. A concrete change proposal requires fresh approval of the current proposal revision and fees; the original purchase consent cannot approve it. This release has no automatic change payment link.",
+    "Partial refunds do not mean every ticket was returned. The platform delivery lock remains; use the safe aftercare journey for remaining-ticket facts, never promise validity from historical issued state. Protected ticket numbers still require account authorization."
   ],
   "human_explanations": {
     "payment_verified": "Payment is confirmed and the Order is recorded. Do not ask the human to pay again; continue the same delivery.",
@@ -55,11 +64,11 @@
     "refund_automatic": "The request is on the automatic policy path because the delivery is reported unconsumed; only the final server status proves success.",
     "refund_manual": "The request requires human review, commonly because delivery was consumed. Manual review is not a rejection.",
     "refund_unknown": "The payment channel outcome is unknown. Delivery stays locked while ItPay reconciles; never submit or replay another refund.",
-    "refund_succeeded": "ItPay confirms the refund succeeded and delivery is permanently closed."
+    "refund_succeeded": "ItPay confirms this request’s money refund succeeded. Verify its scope and the remaining-ticket facts separately; only the order’s full refunded state establishes all platform money returned."
   },
   "forbidden": [
     "Do not fabricate Buyer sessions, Device IDs or payment references.",
-    "Do not read delivery while refund access_locked is true.",
+    "Do not consume locked platform delivery; authorized safe remaining-ticket status reads are separate.",
     "Do not claim a refund succeeded before the Refund Owner says succeeded.",
     "Do not promise an unconditional refund, instant arrival, or a channel result that ItPay has not confirmed.",
     "Do not blame the human for a Provider, delivery, platform, or payment-channel failure."
@@ -92,5 +101,12 @@
     "交付失败",
     "没有收到结果",
     "能不能退"
-  ]
+  ],
+  "rail_notifications": {
+    "channels": "Delivery notices reach the checkout-confirmed contact: email always works; a verified mainland SMS recipient is optional and checkout-scoped. The passenger phone, the login phone and the notification recipient are independent facts.",
+    "status_read": "Use the current returned reader for ticket state; order summaries do not expose per-leg notification delivery records. Do not infer a sent or delivered notification.",
+    "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."
+  },
+  "consumption_and_access": "Platform content consumption is not train usage; access_locked freezes platform delivery and does not prove ticket validity. Read actual refund/ticket facts; a future departure does not guarantee eligibility."
 }

package/docs/agent/buyer/payment-flow.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 single public CLI entry point for Buyer services and the existing itpay sell Seller workflow; $itpay is its user-facing Skill invocation.",
   "topic": "payment-flow",
   "title": "Human Checkout Handoff And Payment Verification",
   "purpose": "Show the ItPay Checkout to the human and recover authoritative payment state without creating duplicate payment resources.",
@@ -13,7 +13,7 @@
     {
       "intent": "present the Checkout handoff",
       "command": "<execute the exact command returned by buy or services checkout>",
-      "success_signal": "the human can see both the ItPay Checkout QR or image and the Checkout URL"
+      "success_signal": "the returned official URL and/or QR supported by the actual Host is visible to the human"
     },
     {
       "intent": "read authoritative Checkout state",
@@ -29,7 +29,8 @@
   "agent_rules": [
     "Normal buyer flow opens the ItPay Checkout page; itpay pay and buy --pay are operator escape hatches.",
     "Use only handoff fields returned for the current Host and make them actually visible to the human.",
-    "Before creating a single-Service Checkout, send the exact price confirmation requested by the current instruction, stop, and wait for explicit human agreement.",
+    "Obtain only missing required agreement or material price/term changes. Reuse a valid explicit confirmation for unchanged terms; never invent it.",
+    "For a railway journey, show one official checkout for all legs: one total/payment, separate issuance. The page shares its authoritative payment_deadline_at/server_now/payment_remaining_seconds; reaching zero requires reading current status, not declaring cancellation.",
     "After presenting a Checkout, stop. Run the returned next.command only after the human completes the payment action or asks to query the same Checkout.",
     "Use only the handoff fields returned for the current Host. Load render-hosts if the official handoff is not visible.",
     "Payment is verified only by Backend Checkout or Order state, never by QR rendering, redirect, or user claim.",
@@ -65,5 +66,6 @@
     "付款后",
     "不要重复付款",
     "支付确认"
-  ]
+  ],
+  "purchase_consent": "Candidate selection is not price approval. Service-backed quote/cart/checkout requires a current scoped approve_purchase record; use the complete server template, default false. Only genuine matching approval allows true; material price/subject/terms changes invalidate it. Restore an existing Checkout before creating anything."
 }

package/docs/agent/buyer/purchased-content.json

@@ -29,20 +29,34 @@
   "intent_routing": {
     "previous_content": "Use vault list, optionally with the subject as --query.",
     "purchase_history": "Use orders.",
-    "new_service": "Use catalog only when the human asks for a new query or purchase.",
+    "new_service": "For a new railway request, read rail-booking; for other new services, use catalog. No previous-content match does not block a separately requested new railway query.",
     "ambiguous": "Ask whether the human wants an earlier purchase or a new query before calling ItPay."
   },
   "authorization_flow": [
     "Run the original list, orders, or read command.",
     "OpenClaw must pass its current trusted host and required target on the original command so the authorization continuation preserves the real presentation destination.",
-    "If it returns human_authorization_required, run only its next.command once.",
+    "If it returns human_authorization_required and context is complete, run its executable next.command once. If next is null or context/consent is missing, fill the returned interaction/input_template first; never invent host, target or consent.",
     "Make the returned handoff genuinely visible and stop.",
     "After the human says authorization is complete, rerun the original read command unchanged.",
     "Never rerun vault access as a status check."
   ],
   "human_language": {
-    "prefer": ["previously purchased content", "past report", "purchase history", "已购内容", "以前购买的报告", "购买记录"],
-    "avoid": ["Vault", "artifact", "Device", "Buyer", "grant", "start token"]
+    "prefer": [
+      "previously purchased content",
+      "past report",
+      "purchase history",
+      "已购内容",
+      "以前购买的报告",
+      "购买记录"
+    ],
+    "avoid": [
+      "Vault",
+      "artifact",
+      "Device",
+      "Buyer",
+      "grant",
+      "start token"
+    ]
   },
   "partial_results": {
     "available": "Explain the returned section normally.",