@itpay/cli 2.1.19 → 2.1.29

package/dist/src/commands/skill.js

@@ -24,7 +24,7 @@ export function runSkillShow(name, options = {}) {
         result: { skill: ITPAY_SKILL, content },
         instruction: agentType
             ? agentType === "workbuddy"
-                ? "完整读取并遵守 Skill；把自己视为服务用户的代理，先理解用户要购买新服务、查看已购内容、查询订单还是处理退款，并先解释用户权益，再选择对应的第一条命令。保持 workbuddy 和同一 Node/CLI launcher。运行会持久化 ~/.itpay-v3 的 ItPay Bash 命令前，把 Shell 工具参数 dangerouslyDisableSandbox 设为 true；用户拒绝权限时停止，不要切换 Node、删除 identity 或处理 lock。"
+                ? "完整读取并遵守 Skill；按用户意图选择第一条命令。保持 workbuddy 和同一 CLI launcher，并为 ~/.itpay-v3 申请宿主允许的持久化权限；权限被拒时报告受阻操作，不删除 identity。"
                 : `完整读取并遵守 Skill；把自己视为服务用户的代理，先理解用户意图和解释用户权益，再选择购买、已购内容、订单或退款对应的第一条命令。当前 Agent Type 是 ${agentType}，后续命令保持不变。`
             : "完整读取并遵守 Skill；先如实选择当前运行环境对应的 Agent Type。",
         next: agentType

package/dist/src/commands/vault.js

@@ -1,7 +1,7 @@
 import { HttpError } from "../client/http.js";
-import { requiresTarget } from "../state/client_context.js";
+import { requiresTarget, validateContext } from "../state/client_context.js";
 import { formatMoney } from "../render/output.js";
-import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
+import { CommandContractError, shellArgument, writeCommandEnvelope } from "./guidance.js";
 import { buildVaultHandoff } from "./vault_handoff.js";
 function outputOptions(options, plainResult) {
     return {
@@ -19,21 +19,21 @@ export async function runVaultList(backend, input) {
         const value = await backend.listBuyerVaultArtifacts(input);
         writeCommandEnvelope({
             status: value.items.length ? "vault_listed" : "no_vault_artifacts",
-            result: { items: value.items, next_cursor: value.next_cursor || null },
+            result: { items: value.items.map(item => ({ ...item, amount: formatMoney(item.amount_minor, item.currency), reader: { command: vaultReadCommand(item.artifact_ref, [], input), reason: "读取这一已购内容" } })), next_cursor: value.next_cursor || null },
             instruction: value.items.length
-                ? "用编号、服务名称、内容主体、购买时间、金额和订单号说明匹配结果，不要向用户显示内部内容标识。一个精确匹配可按用户原始查看意图继续读取；多个匹配必须让用户选择。"
+                ? "用编号、服务名称、内容主体、购买时间、金额和订单号说明匹配结果，不要向用户显示内部内容标识。一个精确匹配可按用户原始查看意图继续读取；已有任务可明确匹配时读取对应行；只有真实歧义才让用户选择。"
                 : "当前账号没有匹配的已购内容。向用户说明没有找到，不要猜测内容标识、自动购买或发起新的服务查询。",
-            next: null,
+            next: value.next_cursor ? { command: `itpay vault list --limit ${input.limit}${input.query ? ` --query ${shellArgument(input.query)}` : ""} --cursor ${shellArgument(value.next_cursor)}${contextFlags(input)} --json`, reason: "读取同一筛选的下一页" } : null,
             recovery: [],
-        }, outputOptions(input, value.items.map((item, index) => `${index + 1}. ${item.service_title}${item.subject_label ? ` · ${item.subject_label}` : ""} · ${formatMoney(item.amount_minor, item.currency)} · ${item.purchased_at} · ${item.order_code} · ${item.order_status}`)));
+        }, outputOptions(input));
     }
     catch (error) {
         if (error instanceof HttpError && error.code === "vault_authorization_required") {
             writeCommandEnvelope({
                 status: "human_authorization_required",
                 result: { intent: "list_purchased_content", query: input.query ?? "" },
-                instruction: `需要用户确认一次身份和只读权限。执行 next.command 生成官方入口，不要声称链接已经创建；用户完成后重新运行原始 vault list 命令。${accessContextInstruction(input)}`,
-                next: { command: vaultAccessCommand(undefined, input), reason: "创建一次账号读取授权" }, recovery: [],
+                instruction: `需要用户确认一次身份和只读权限。按当前动作或待填模板生成官方入口，不要声称链接已经创建；用户完成后重新运行原始 vault list 命令。${accessContextInstruction(input)}`,
+                ...vaultAccessGuidance(undefined, input), recovery: [],
             }, outputOptions(input));
             return;
         }
@@ -41,6 +41,9 @@ export async function runVaultList(backend, input) {
     }
 }
 export async function runVaultAccess(backend, artifactRef, options) {
+    const issue = validateContext(options.host, options.target);
+    if (issue)
+        throw new CommandContractError(issue.code, issue.message, "先补齐当前可信会话的真实宿主和目标；尚未创建授权请求。", [], { schema_version: "itpay.interaction.v1", stage: "input_required", input_template: { command: vaultAccessCommand(artifactRef, options), required_input: issue.code === "target_required" ? ["target"] : ["host"], executable: false } });
     const value = await backend.createVaultAccessRequest(artifactRef
         ? { purpose: "artifact_reveal", artifact_ref: artifactRef }
         : { purpose: "account_window" });
@@ -90,23 +93,23 @@ export async function runVaultRead(backend, artifactRef, sections, options) {
                 : value.status === "result_preparing"
                     ? "这份已购内容仍在准备。稍后只重试同一 read，不要重新授权、购买或调用 Provider。"
                     : "这份已购内容当前不可用。停止，不要重试、重新购买或绕过退款锁。",
-            next: null, recovery: [],
+            next: value.status === "result_preparing" ? { command: vaultReadCommand(artifactRef, normalized, options), reason: "稍后读取同一内容及原sections；不重新授权或购买" } : null, recovery: [],
         }, outputOptions(options));
     }
     catch (error) {
         if (error instanceof HttpError && error.code === "artifact_authorization_required") {
             writeCommandEnvelope({
                 status: "human_authorization_required", result: { artifact_ref: artifactRef },
-                instruction: `这份内容需要用户单独确认读取权限。执行 next.command 生成一次官方入口；用户完成后重新运行原始 read，不要重复创建授权请求。${accessContextInstruction(options)}`,
-                next: { command: vaultAccessCommand(artifactRef, options), reason: "创建一次内容读取授权" }, recovery: [],
+                instruction: `这份内容需要用户单独确认读取权限。按当前动作或待填模板生成一次官方入口；用户完成后重新运行原始 read，不要重复创建授权请求。${accessContextInstruction(options)}`,
+                ...vaultAccessGuidance(artifactRef, options), recovery: [],
             }, outputOptions(options));
             return;
         }
         if (error instanceof HttpError && error.code === "vault_authorization_required") {
             writeCommandEnvelope({
                 status: "human_authorization_required", result: { artifact_ref: artifactRef },
-                instruction: `账号读取授权已缺失或过期。执行 next.command 生成一次官方入口；用户完成后重新运行原始 read。${accessContextInstruction(options)}`,
-                next: { command: vaultAccessCommand(undefined, options), reason: "创建一次账号读取授权" }, recovery: [],
+                instruction: `账号读取授权已缺失或过期。按当前动作或待填模板生成一次官方入口；用户完成后重新运行原始 read。${accessContextInstruction(options)}`,
+                ...vaultAccessGuidance(undefined, options), recovery: [],
             }, outputOptions(options));
             return;
         }
@@ -121,7 +124,7 @@ export function vaultAccessCommand(artifactRef, options) {
     const host = options.host ?? (openClaw ? "<host>" : undefined);
     if (host)
         parts.push("--host", host);
-    const target = options.target ?? (openClaw && (!options.host || requiresTarget(options.host)) ? "<target>" : undefined);
+    const target = options.target ?? (((openClaw && !options.host) || (options.host && requiresTarget(options.host))) ? "<target>" : undefined);
     if (target)
         parts.push("--target", shellArgument(target));
     parts.push("--json");
@@ -132,10 +135,14 @@ export function accessContextInstruction(options) {
         ? " 将 <host> 和 <target> 替换为当前可信 OpenClaw 会话的真实值，不要照抄占位符或猜测目标。"
         : "";
 }
-function shellArgument(value) {
-    if (value.startsWith("<") && value.endsWith(">"))
-        return value;
-    if (/^[\p{L}\p{N}._:=/-]+$/u.test(value))
-        return value;
-    return `'${value.replaceAll("'", `'"'"'`)}'`;
+function contextFlags(options) {
+    return `${options.host ? ` --host ${options.host}` : ""}${options.target ? ` --target ${shellArgument(options.target)}` : ""}`;
+}
+function vaultReadCommand(artifact, sections, options) {
+    return `itpay vault read --artifact ${shellArgument(artifact)}${sections.map(section => ` --section ${shellArgument(section)}`).join("")}${contextFlags(options)} --json`;
+}
+export function vaultAccessGuidance(artifact, options) {
+    const command = vaultAccessCommand(artifact, options);
+    const missing = [...(options.agentType === "openclaw" && !options.host ? ["host"] : []), ...(options.host && requiresTarget(options.host) && !options.target || options.agentType === "openclaw" && !options.host && !options.target ? ["target"] : [])];
+    return missing.length ? { next: null, interaction: { schema_version: "itpay.interaction.v1", stage: "input_required", input_template: { command, required_input: missing, executable: false } } } : { next: { command, reason: "创建一次官方只读授权入口；用户完成后恢复原reader" } };
 }

package/dist/src/main.js

@@ -25,7 +25,7 @@ import { runCancelRefund, runGetRefund, runListRefunds, runRefund, runWatchRefun
 import { runCartAdd, runCartAddQuoteServer, runCartAddServer, runCartAbandonServer, runCartClear, runCartNext, runCartRemove, runCartRemoveServer, runCartShow, runCartShowServer, } from "./commands/cart.js";
 import { CommandContractError, errorRecoveryActions, printErrorRecovery, writeCommandEnvelope } from "./commands/guidance.js";
 import { runDocsList, runDocsShow, runDocsSearch } from "./commands/docs.js";
-import { runInstall } from "./commands/install.js";
+import { INSTALL_AGENT_TYPES, runInstall } from "./commands/install.js";
 import { runSkillShow } from "./commands/skill.js";
 import { runNext } from "./commands/next.js";
 import { runVaultAccess, runVaultList, runVaultRead } from "./commands/vault.js";
@@ -139,17 +139,12 @@ function reportCLIError(error, contract) {
     const providerContractMismatch = error instanceof HttpError && error.code === "provider_contract_mismatch";
     const capabilityInputInvalid = error instanceof HttpError && error.code === "capability_input_invalid";
     const deviceKeyResettable = Boolean(deviceError && (deviceError.code === "agent_device_key_rotated" ||
-        deviceError.code === "agent_device_key_conflict" ||
-        (deviceError.enrollmentFailed && deviceError.status === 500)));
+        deviceError.code === "agent_device_key_conflict"));
     const deviceRecovery = deviceError ? [
         {
             command: "itpay skill show itpay --json",
             reason: "读取 ItPay 身份边界；该错误需要用户或运营恢复 Backend 登记，不能通过换类型或删除本地身份绕过",
         },
-        ...(deviceKeyResettable ? [{
-                command: "itpay device reset-key --confirm-key-reset --json",
-                reason: "服务端拒绝以当前私钥完成设备登记；生成全新 Ed25519 密钥并重新登记（旧设备身份在服务端保留为孤儿，不影响新身份和额度谱系）",
-            }] : []),
     ] : [];
     const stateRecovery = stateError ? [{
             command: "itpay skill show itpay --json",
@@ -167,10 +162,10 @@ function reportCLIError(error, contract) {
                 ? "CLI 已自动续期并重试同一请求一次，仍被拒绝；停止重试，不要切换 Agent Type 或旋转身份。"
                 : deviceError?.code === "agent_device_revoked"
                     ? "Backend 已撤销当前 Device 登记；CLI 没有自动创建替代身份。停止重试并请用户或运营恢复登记。"
-                    : deviceKeyResettable && deviceError?.status === 500
-                        ? "服务端未能完成设备登记。先原样重试一次原命令：服务端会把已登记的同一公钥幂等挂回原设备。若仍返回 internal_error（Backend 未含该修复），执行 itpay device reset-key --confirm-key-reset 生成全新密钥后重试。"
+                    : deviceError?.enrollmentFailed && deviceError.status === 500
+                        ? "服务端未能完成设备登记；保持原密钥和Agent Type，说明系统故障，待服务端恢复后继续原任务。不要重置身份。"
                         : deviceKeyResettable
-                            ? "服务端记录显示当前设备私钥已不再有效（已轮换或与既有登记冲突）。执行 itpay device reset-key --confirm-key-reset 生成全新密钥并重新登记。"
+                            ? "服务端拒绝当前设备私钥登记（轮换或冲突）。停止自动恢复；换钥会放弃旧身份，旧执行访问不会迁移。仅用户或运营明确决定放弃旧身份后，按 device reset-key 帮助执行。"
                             : deviceError
                                 ? "Device 身份验证失败；停止重试，不要切换 Agent Type、删除状态或旋转私钥。"
                                 : undefined;
@@ -226,9 +221,10 @@ function reportCLIError(error, contract) {
                                                     ? "临时网络故障；CLI 已仅对可安全重放的操作完成有限自动重试，但仍未获得完整响应。按 recovery 查询同一资源的权威状态；不要创建替代 Checkout、Execution、Payment 或 Refund。"
                                                     : "网络在完整响应前中断；当前写操作没有安全重放合同，因此 CLI 未自动重试。按 recovery 查询权威状态；不要原样重放或创建替代 Checkout、Execution、Payment 或 Refund。"
                                                 : backendOverrideError
-                                                    ? "移除 ITPAY_BACKEND_URL 使用正式环境，或准确设置为 https://sandbox.itpay.ai。"
+                                                    ? "移除 ITPAY_BACKEND_URL 使用正式环境，或按当前测试目标准确设置为 https://sandbox.itpay.ai 或 https://dev.itpay.ai。不要通过切换环境规避当前错误。"
                                                     : commandError?.instruction ?? authorizationInstruction ?? contract?.instruction ?? "检查命令参数后重试。",
             next: null,
+            ...(commandError?.interaction ? { interaction: commandError.interaction } : {}),
             recovery: incompatible
                 ? requiredCLIVersion
                     ? [distributionUpgradeAction(requiredCLIVersion)]
@@ -238,7 +234,7 @@ function reportCLIError(error, contract) {
                     : backendOverrideError ? [] : commandError?.recovery ?? (stateError ? stateRecovery : lockError ? lockRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
         }, {
             ...(contract?.jsonOutput !== undefined ? { jsonOutput: contract.jsonOutput } : backendOverrideError || lockError || stateError ? { jsonOutput: process.argv.includes("--json") } : {}),
-            output: (text) => { process.stderr.write(text); },
+            output: (text) => { process.stdout.write(text); },
         });
         process.exitCode = 1;
         return;
@@ -323,7 +319,7 @@ for (const action of ["login", "status"]) {
             // and non-JSON output is human-readable instead of a raw JSON dump.
             const envelope = {
                 status: String(result.status ?? "error"),
-                result: (result.result ?? result),
+                result: (result.result ?? Object.fromEntries(Object.entries(result).filter(([key]) => !["status", "instruction", "next", "recovery", "handoff"].includes(key)))),
                 ...(result.handoff ? { handoff: result.handoff } : {}),
                 instruction: typeof result.instruction === "string" ? result.instruction : "按返回状态继续。",
                 next: (result.next ?? null),
@@ -422,8 +418,11 @@ deviceCmd
     .action(async (options) => {
     const config = loadConfig();
     try {
+        if (!config.agentType || !INSTALL_AGENT_TYPES.some(type => type === config.agentType)) {
+            throw new CommandContractError("agent_type_required", "supported Agent Type required before key reset", "先按真实宿主配置正式支持的Agent Type；尚未修改本地密钥。", [{ command: "itpay install --json", reason: "读取当前宿主配置" }]);
+        }
         if (!options.confirmKeyReset) {
-            throw new CommandContractError("key_reset_confirmation_required", "--confirm-key-reset is required", "仅当服务端拒绝以当前私钥完成设备登记（internal_error、agent_device_key_rotated 或 agent_device_key_conflict）时使用；会放弃本地设备身份并重新登记，旧设备在服务端保留为孤儿。", [{ command: "itpay docs show identity-and-sessions --json", reason: "检查适用边界" }]);
+            throw new CommandContractError("key_reset_confirmation_required", "--confirm-key-reset is required", "仅在用户或运营明确决定放弃旧身份后使用；会丢弃本地私钥，旧执行访问不会迁移。internal_error 需服务端恢复，不能换钥。", [{ command: "itpay docs show identity-and-sessions --json", reason: "检查适用边界" }]);
         }
         const reset = await new DeviceAuthority({
             baseURL: config.baseURL,
@@ -437,9 +436,9 @@ deviceCmd
                 private_key_preserved: false,
                 server_side_device: "orphaned_under_previous_key",
             },
-            instruction: "本地设备私钥已重置；下一次需要设备身份的命令会以全新 Ed25519 密钥重新登记并获得新的额度谱系。服务端旧设备记录保留为孤儿；如需清理请走运营流程。",
+            instruction: "本地设备私钥已重置；下一次需要设备身份的命令会以全新 Ed25519 密钥重新登记；这不能恢复旧身份的订单或用于刷新额度。服务端旧设备记录保留为孤儿；如需清理请走运营流程。",
             next: {
-                command: `itpay --agent-type ${config.agentType ?? "<agent_type>"} services list --limit 1 --json`,
+                command: `itpay --agent-type ${config.agentType} services list --limit 1 --json`,
                 reason: "用无业务写入的签名请求完成新密钥的重新登记",
             },
             recovery: [],
@@ -1413,7 +1412,7 @@ services
     .argument("<result_item_id>")
     .option("--offset <offset>", "zero-based candidate offset", Number, 0)
     .option("--cursor <cursor>", "opaque v2 page cursor (rcur_<offset>); takes precedence over --offset")
-    .option("--limit <limit>", "page size (1-20)", Number, 5)
+    .option("--limit <limit>", "page size (1-20)", Number, 20)
     .option("--json", "output JSON")
     .action(async (serviceExecutionID, resultItemID, options) => {
     const config = loadConfig();
@@ -1477,12 +1476,18 @@ services
     .argument("<service_execution_id>")
     .requiredOption("--capability <capability_id>")
     .option("--input <key=value>", "redacted input summary", collectOption, [])
+    .option("--input-json <file>", "JSON object containing the complete capability input")
     .option("--json", "output JSON")
     .action(async (serviceExecutionID, options) => {
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        await runServicesInvoke(backend, config, serviceExecutionID, options.capability, parseKeyValueList(options.input), { jsonOutput: Boolean(options.json) });
+        const recovery = [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取当前动作要求" }];
+        if (options.inputJson && options.input.length > 0) {
+            throw new CommandContractError("capability_input_invalid", "--input and --input-json cannot be combined", "嵌套输入用 --input-json <file>，扁平输入用 --input key=value，二选一；本次未调用供应商。", recovery);
+        }
+        const input = options.inputJson ? readInputJsonObject(options.inputJson, "capability_input_invalid", recovery) : parseKeyValueList(options.input);
+        await runServicesInvoke(backend, config, serviceExecutionID, options.capability, input, { jsonOutput: Boolean(options.json) });
     }
     catch (error) {
         reportCLIError(error, {
@@ -1665,12 +1670,16 @@ services
     .description("Show the next recommended agent action for a Service Execution")
     .argument("<service_execution_id>")
     .option("--since-snapshot <snapshot_id>", "delta read: suppress the journey payload when unchanged")
+    .option("--timeout <seconds>", "wait up to 120 seconds for a useful result on this execution", (value) => Number(value))
     .option("--json", "output JSON instead of terminal text")
     .action(async (serviceExecutionID, options) => {
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        await runServicesNext(backend, serviceExecutionID, { jsonOutput: Boolean(options.json), sinceSnapshot: options.sinceSnapshot });
+        if (options.timeout !== undefined && (!Number.isInteger(options.timeout) || options.timeout < 0 || options.timeout > 120)) {
+            throw new Error("--timeout must be an integer from 0 to 120");
+        }
+        await runServicesNext(backend, serviceExecutionID, { jsonOutput: Boolean(options.json), sinceSnapshot: options.sinceSnapshot, timeoutSeconds: options.timeout });
     }
     catch (error) {
         reportCLIError(error, {
@@ -1683,22 +1692,28 @@ services
 });
 services
     .command("read-result")
-    .description("Read a human-granted service result for this agent")
+    .description("Read saved railway results or human-granted service content")
     .argument("<service_execution_id>")
-    .option("--snapshot <snapshot_id>", "rail.progressive.v2: read one journey from a committed planning snapshot")
+    .option("--snapshot <snapshot_id>", "Smart: saved snapshot catalog; add --journey for a journey detail. Exact: saved station-pair rows without --snapshot")
     .option("--journey <journey_id>", "rail.progressive.v2: journey id to read")
+    .option("--offset <offset>", "saved journey offset", Number, 0)
+    .option("--limit <limit>", "rows per page (1-20): Exact 20, Smart 3", Number)
+    .option("--all", "read every saved journey page")
     .option("--json", "output JSON instead of terminal text")
     .action(async (serviceExecutionID, options) => {
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        await runServicesReadResult(backend, serviceExecutionID, { jsonOutput: Boolean(options.json), snapshot: options.snapshot, journey: options.journey });
+        await runServicesReadResult(backend, serviceExecutionID, { jsonOutput: Boolean(options.json), snapshot: options.snapshot, journey: options.journey,
+            offset: options.offset, limit: options.limit, all: Boolean(options.all) });
     }
     catch (error) {
         reportCLIError(error, {
             jsonOutput: Boolean(options.json),
-            code: "agent_access_denied",
-            instruction: "请用户在订单页面重新授权；不要使用开发者权限绕过授权或退款锁。",
+            code: error instanceof HttpError && error.code === "agent_access_denied" ? "agent_access_denied" : "service_result_read_failed",
+            instruction: error instanceof HttpError && error.code === "agent_access_denied"
+                ? "请用户在订单页面重新授权；不要使用开发者权限绕过授权或退款锁。"
+                : "读取同一服务的已保存结果；若快照已不可读，先查看该服务当前状态和有效动作。",
             recovery: [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "检查交付模式和 grant 状态" }],
         });
     }

package/dist/src/render/markdown.js

@@ -24,9 +24,6 @@ export function buildAgentChatHandoff(plan) {
     if (plan.orderItems?.length) {
         lines.push(`项目：${plan.orderItems.map((item) => `${item.title} x${item.quantity}`).join("、")}`);
     }
-    if (plan.afterActionCommand) {
-        lines.push("", `付款后查询：\`${plan.afterActionCommand}\``);
-    }
     return {
         type: "send_payment_handoff",
         must_send_to_user: true,

package/dist/src/state/account_auth.js

@@ -59,11 +59,11 @@ const TERMINAL_SESSION_STATES = {
     },
     cancelled: {
         status: 'auth_cancelled',
-        instruction: '用户在官方页取消了授权。如仍需登录，重新运行 itpay auth login。',
+        instruction: '用户在官方页取消了授权；停止登录。只有用户明确重新要求授权时才发起新的登录。',
     },
     denied: {
         status: 'auth_denied',
-        instruction: '官方授权被拒绝。重新运行 itpay auth login 生成新请求。',
+        instruction: '官方授权被拒绝；停止登录，不自动创建新请求。只有用户明确重新要求授权时才重新登录。',
     },
 };
 class AuthRequestError extends Error {
@@ -200,9 +200,13 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
                 }
                 catch (error) {
                     if (error instanceof AuthRequestError && (error.httpStatus === 404 || error.httpStatus === 410)) {
-                        return sessionGone(env, purpose, baseURL, open.sessionID);
+                        rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
+                        // The explicit login call may open one fresh session now. Status
+                        // remains read-only and still reports the missing old session.
+                    }
+                    else {
+                        return authStatusUnknown(open.sessionID);
                     }
-                    return authStatusUnknown(open.sessionID);
                 }
             }
         }
@@ -285,7 +289,7 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
                     status: terminal.status,
                     result: { dashboard_auth_session_id: state.sessionID, stage: progress.status },
                     instruction: terminal.instruction,
-                    next: { command: 'itpay auth login --json', reason: '重新发起官方授权' },
+                    next: ['denied', 'cancelled'].includes(progress.status) ? null : { command: 'itpay auth login --json', reason: '需要登录时重新发起官方授权' },
                     recovery: [],
                 };
             }

package/dist/src/state/cart_session.js

@@ -55,9 +55,12 @@ export class CartSession {
             ...(this.state.lastDisplayToken ? { lastDisplayToken: this.state.lastDisplayToken } : {}),
             ...(this.state.lastCheckoutURL ? { lastCheckoutURL: this.state.lastCheckoutURL } : {}),
         };
+        const contents = JSON.stringify(toSave, null, 2);
+        if (existsSync(path) && readFileSync(path, "utf-8") === contents)
+            return;
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
         const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
-        writeFileSync(temporary, JSON.stringify(toSave, null, 2), { encoding: "utf-8", mode: 0o600 });
+        writeFileSync(temporary, contents, { encoding: "utf-8", mode: 0o600 });
         chmodSync(temporary, 0o600);
         renameSync(temporary, path);
         chmodSync(path, 0o600);

package/dist/src/state/config.js

@@ -15,7 +15,7 @@ import { OperationJournal } from "./operation_journal.js";
 export const DEFAULT_BASE_URL = "https://app.itpay.ai";
 export const DEV_BASE_URL = "https://dev.itpay.ai";
 export const SANDBOX_BASE_URL = "https://sandbox.itpay.ai";
-export const CLI_VERSION = "2.1.19";
+export const CLI_VERSION = "2.1.29";
 export const API_CONTRACT_REVISION = "sha256:2f9fbcdc5cd0630910abb52671304cc019e348e9a778017ec92ddc3513b3639f";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";

package/dist/src/state/task_journal.js

@@ -45,6 +45,8 @@ export class TaskJournal {
     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 } : {}),

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.",
+    "Railway query and booking use distinct Service Executions for one purchase journey. Start another execution for an 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."
+    "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.",

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.",
@@ -20,7 +20,8 @@
     "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.",
     "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."
   },
   "agent_rules": [
     "Use catalog list only when the human asks for a new service, not when they want an earlier purchase.",
@@ -28,15 +29,32 @@
     "Explain the customer journey from service_flow instead of presenting every variant as an unrelated service.",
     "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"
     }

package/docs/agent/buyer/identity-and-sessions.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": "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.",
@@ -12,7 +12,7 @@
   ],
   "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 sandbox.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."
   },
@@ -23,13 +23,13 @@
     "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.",
     "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. If enrollment verification keeps failing with internal_error, or returns agent_device_key_rotated or agent_device_key_conflict, `itpay device reset-key --confirm-key-reset` is the supported way to start over with a fresh key."
+    "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": [
     {
@@ -48,22 +48,22 @@
       "success_signal": "only the selected Backend registration is removed and the private key and other Backend registration remain"
     },
     {
-      "intent": "abandon the local device key after the Backend refuses to complete enrollment with it (persistent internal_error, agent_device_key_rotated, or agent_device_key_conflict)",
-      "command": "itpay device reset-key --confirm-key-reset --json",
-      "success_signal": "the local private key is discarded and the next command enrolls as a brand-new device"
+      "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://sandbox.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 dev, local, an IP, or any custom Backend; only the exact official sandbox.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": [
@@ -93,10 +93,11 @@
   ],
   "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.",
+    "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."
-  }
+  },
+  "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

@@ -35,20 +35,21 @@
     "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.",
+    "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_contract_incompatible includes result.required_cli_version, stop all ItPay business commands and use only the exact distribution-specific update recovery returned by the CLI; never replace its version with latest.",
     "After upgrading, require itpay --version to equal result.required_cli_version before running readyz again; 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 sandbox.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."
+    "Do not change Agent Type or rotate local identity to reset quota or recover a failed command.",
+    "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://sandbox.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."
   ],