@itpay/cli 2.1.17 → 2.1.19

package/dist/src/main.js

@@ -7,7 +7,7 @@ import { runServicesRun } from "./commands/services.js";
 // orchestrate; HTTP and rendering live in src/client and src/render.
 import { Command } from "commander";
 import { BackendOverrideError, CLI_VERSION, cliDistribution, loadConfig, cartSessionPath, newBackendClient } from "./state/config.js";
-import { DeviceAuthority, DeviceAuthorizationError, DeviceStateError } from "./state/device_authority.js";
+import { DeviceAuthority, DeviceAuthorizationError, DeviceLockBusyError, DeviceStateError } from "./state/device_authority.js";
 import { CartSession } from "./state/cart_session.js";
 import { defaultHostForAgentType, normalizeHost, validateContext } from "./state/client_context.js";
 import { HttpError } from "./client/http.js";
@@ -116,6 +116,7 @@ function reportCLIError(error, contract) {
     const backendOverrideError = error instanceof BackendOverrideError ? error : undefined;
     const deviceError = error instanceof DeviceAuthorizationError ? error : undefined;
     const stateError = error instanceof DeviceStateError ? error : undefined;
+    const lockError = error instanceof DeviceLockBusyError ? error : undefined;
     const transportError = error instanceof HttpTransportError ? error : undefined;
     const httpRecovery = errorRecoveryActions(error).map((action) => ({
         command: action.command,
@@ -154,24 +155,30 @@ function reportCLIError(error, contract) {
             command: "itpay skill show itpay --json",
             reason: "读取 Device 状态边界；修复当前 Host 的持久写权限后重试原命令",
         }] : [];
+    const lockRecovery = lockError ? [{
+            command: "itpay device repair-lock --json",
+            reason: "检查锁持有者；只回收已退出进程留下的锁，不改变设备身份",
+        }] : [];
     const authorizationInstruction = stateError
         ? "当前运行环境无法写入 owner-only Device 状态；请保持同一 Node、CLI 和 Agent Type，在允许持久写入 ~/.itpay-v3 的执行环境中重试。不要手工创建 lock、删除 identity 或换运行时碰运气。"
-        : error instanceof HttpError && error.code === "agent_device_session_required"
-            ? "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 生成全新密钥后重试。"
-                    : deviceKeyResettable
-                        ? "服务端记录显示当前设备私钥已不再有效（已轮换或与既有登记冲突）。执行 itpay device reset-key --confirm-key-reset 生成全新密钥并重新登记。"
-                        : deviceError
-                            ? "Device 身份验证失败；停止重试，不要切换 Agent Type、删除状态或旋转私钥。"
-                            : undefined;
-    if (contract || commandError || backendOverrideError) {
+        : lockError
+            ? "另一个进程仍在更新本地身份。执行 recovery 检查；若持有者仍活跃，等待后继续原任务，不要删除锁或重建身份。"
+            : error instanceof HttpError && error.code === "agent_device_session_required"
+                ? "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 生成全新密钥后重试。"
+                        : deviceKeyResettable
+                            ? "服务端记录显示当前设备私钥已不再有效（已轮换或与既有登记冲突）。执行 itpay device reset-key --confirm-key-reset 生成全新密钥并重新登记。"
+                            : deviceError
+                                ? "Device 身份验证失败；停止重试，不要切换 Agent Type、删除状态或旋转私钥。"
+                                : undefined;
+    if (contract || commandError || backendOverrideError || lockError || stateError) {
         writeCommandEnvelope({
             status: "error",
             error: {
-                code: incompatible ? "backend_contract_incompatible" : backendOverrideError?.code ?? commandError?.code ?? (error instanceof HttpError ? error.code : transportError?.code ?? stateError?.code ?? deviceError?.code ?? contract?.code ?? "command_failed"),
+                code: incompatible ? "backend_contract_incompatible" : backendOverrideError?.code ?? commandError?.code ?? (error instanceof HttpError ? error.code : transportError?.code ?? stateError?.code ?? lockError?.code ?? deviceError?.code ?? contract?.code ?? "command_failed"),
                 message: error instanceof Error ? error.message : String(error),
             },
             ...(requiredCLIVersion ? {
@@ -228,9 +235,9 @@ function reportCLIError(error, contract) {
                     : []
                 : backendInternal || providerConnectionUnavailable || providerTemporary || providerInputRejected || providerContractMismatch || providerRejected || capabilityInputInvalid
                     ? []
-                    : backendOverrideError ? [] : commandError?.recovery ?? (stateError ? stateRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
+                    : backendOverrideError ? [] : commandError?.recovery ?? (stateError ? stateRecovery : lockError ? lockRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
         }, {
-            ...(contract?.jsonOutput !== undefined ? { jsonOutput: contract.jsonOutput } : backendOverrideError ? { jsonOutput: process.argv.includes("--json") } : {}),
+            ...(contract?.jsonOutput !== undefined ? { jsonOutput: contract.jsonOutput } : backendOverrideError || lockError || stateError ? { jsonOutput: process.argv.includes("--json") } : {}),
             output: (text) => { process.stderr.write(text); },
         });
         process.exitCode = 1;
@@ -311,7 +318,18 @@ for (const action of ["login", "status"]) {
         const config = loadConfig();
         try {
             const result = await agentAuth(action, config.baseURL, newBackendClient(config));
-            process.stdout.write(JSON.stringify(result) + "\n");
+            // AUTH06: auth output goes through the same envelope renderer as every
+            // other command — next/recovery keep Agent Type + Backend qualification
+            // 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.handoff ? { handoff: result.handoff } : {}),
+                instruction: typeof result.instruction === "string" ? result.instruction : "按返回状态继续。",
+                next: (result.next ?? null),
+                recovery: (result.recovery ?? []),
+            };
+            writeCommandEnvelope(envelope, { jsonOutput: Boolean(options.json) });
         }
         catch (error) {
             reportCLIError(error, { jsonOutput: Boolean(options.json), code: "account_login_failed", instruction: "完成官方网页登录后重试 itpay auth status；不要清除设备登记。" });
@@ -320,6 +338,30 @@ for (const action of ["login", "status"]) {
 }
 // --- device ---------------------------------------------------------------
 const deviceCmd = program.command("device").description("Recover the current official Backend registration after an operator-confirmed reset");
+deviceCmd
+    .command("repair-lock")
+    .description("Safely inspect and recover a local Device identity lock left by an exited process")
+    .option("--json", "output JSON instead of terminal text")
+    .action((options) => {
+    try {
+        const config = loadConfig();
+        const status = new DeviceAuthority({
+            baseURL: config.baseURL,
+            ...(config.agentType ? { requestedAgentType: config.agentType } : {}),
+            compatibilityHeaders: {},
+        }).repairLock();
+        writeCommandEnvelope({
+            status: status === "recovered" ? "device_lock_recovered" : status === "active" ? "device_lock_active" : "device_lock_absent",
+            result: { lock_status: status, device_identity_preserved: true },
+            instruction: status === "active" ? "本地身份正由存活进程更新；稍后继续原任务。" : "本地锁无需进一步处理；继续原任务。",
+            next: null,
+            recovery: [],
+        }, { jsonOutput: Boolean(options.json), plainResult: [`lock: ${status}`, "device_identity: preserved"] });
+    }
+    catch (error) {
+        reportCLIError(error, { jsonOutput: Boolean(options.json), code: "device_lock_repair_failed", instruction: "本地锁无法安全检查；保留设备身份并联系维护者。" });
+    }
+});
 deviceCmd
     .command("recover")
     .description("Forget only the current official Backend registration while preserving the local private key")
@@ -893,6 +935,13 @@ program
     .option("--id <checkout_id>")
     .option("--token <display_token>")
     .option("--locale <locale>", "payment card language: zh-CN|en", "zh-CN")
+    .option("--present <method>", "display once: auto|browser|image|link|none (JSON default plans only)")
+    .option("--no-open", "never open a browser window")
+    .option("--viewer <viewer>", "device the human is looking at: desktop|mobile|unknown")
+    .option("--relay-option <ref>", "server-issued contact option reference for message relay")
+    .option("--confirm-relay", "confirm the human explicitly consented to this relay send")
+    .option("--request-key <key>", "stable idempotency key for a relay request")
+    .option("--relay-status <relay_id>", "read a prior relay result; never resends")
     .option("--json", "output compact JSON")
     .action(async (options) => {
     const config = loadConfig();
@@ -919,6 +968,13 @@ program
             baseURL: config.baseURL,
             locale: options.locale,
             jsonOutput: Boolean(options.json),
+            ...(options.present ? { present: options.present } : {}),
+            ...(options.noOpen ? { noOpen: true } : {}),
+            ...(options.viewer ? { viewer: options.viewer } : {}),
+            ...(options.relayOption ? { relayOption: options.relayOption } : {}),
+            ...(options.confirmRelay ? { confirmRelay: true } : {}),
+            ...(options.requestKey ? { requestKey: options.requestKey } : {}),
+            ...(options.relayStatus ? { relayStatus: options.relayStatus } : {}),
         });
     }
     catch (error) {

package/dist/src/render/browser.js

@@ -0,0 +1,65 @@
+// Local browser dispatch for `--present browser`. Opens the URL via the OS
+// opener with an argv array — never a model-generated shell string. Dispatch
+// proves only that the request was accepted by the OS; it never means the
+// page became visible (that would be `page_loaded`, which needs evidence).
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+// Official HTTPS origins (or the loopback dev origin behind ITPAY_CLI_DEV).
+// No userinfo, no non-http(s) schemes, no redirect chains — the opener gets
+// exactly this URL once.
+export function isPresentableURL(raw, baseURL, env = process.env) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    if (url.username || url.password)
+        return false;
+    if (env.ITPAY_CLI_DEV === "1" && /^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(url.origin))
+        return true;
+    if (url.protocol !== "https:")
+        return false;
+    const allowedOrigins = new Set(["https://app.itpay.ai", "https://sandbox.itpay.ai", "https://dev.itpay.ai"]);
+    if (baseURL) {
+        try {
+            allowedOrigins.add(new URL(baseURL).origin);
+        }
+        catch {
+            /* ignore malformed base URL */
+        }
+    }
+    return allowedOrigins.has(url.origin);
+}
+export function openInSystemBrowser(raw, baseURL, env = process.env) {
+    if (!isPresentableURL(raw, baseURL, env)) {
+        return Promise.resolve({ status: "failed", reason: "url_rejected" });
+    }
+    const [command, args] = openerArgv(raw);
+    if (!command) {
+        return Promise.resolve({ status: "unavailable", reason: "no system opener on this platform" });
+    }
+    return new Promise((resolvePromise) => {
+        const child = spawn(command, args, { detached: true, stdio: "ignore" });
+        child.once("error", (error) => resolvePromise({ status: "failed", reason: error.message }));
+        child.once("spawn", () => {
+            child.unref();
+            resolvePromise({ status: "dispatch_accepted", argv: [command, ...args] });
+        });
+    });
+}
+function openerArgv(url) {
+    switch (platform()) {
+        case "darwin":
+            return ["open", [url]];
+        case "win32":
+            return ["cmd.exe", ["/c", "start", "", url]];
+        case "linux":
+        case "freebsd":
+        case "openbsd":
+            return ["xdg-open", [url]];
+        default:
+            return [undefined, []];
+    }
+}

package/dist/src/state/account_auth.js

@@ -3,6 +3,8 @@ import { homedir } from 'node:os';
 import { dirname, resolve } from 'node:path';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, rmSync } from 'node:fs';
 import { writeLocalPNG } from '../render/qr.js';
+import { TaskJournal } from './task_journal.js';
+import { taskJournalPath } from './config.js';
 export function sellerAuthPath(baseURL, env = process.env, purpose = "seller") {
     return resolve(env.HOME || homedir(), '.itpay-v3', `${purpose}-${createHash('sha256').update(baseURL).digest('hex').slice(0, 16)}.json`);
 }
@@ -32,46 +34,176 @@ export function sellerAuth(action, baseURL, env = process.env, fetcher = fetch)
 export function agentAuth(action, baseURL, backend, env = process.env, fetcher = fetch) {
     return accountAuth(action, baseURL, env, fetcher, backend);
 }
+// AUTH01: dashboard session stages stay distinct — the human must know exactly
+// what the official page still needs instead of a generic "pending".
+const ACTIVE_SESSION_STAGES = ['created', 'waiting_provider', 'email_verification_required', 'merge_confirmation_required'];
+function stageInstruction(stage) {
+    if (stage === 'email_verification_required') {
+        return '钱包授权已完成，官方页还需要完成联系方式验证（邮箱或手机，以页面实际提供的方式为准）。完成后继续原查询，不用重说行程。';
+    }
+    if (stage === 'merge_confirmation_required') {
+        return '官方页需要用户确认账号合并决定后才能完成登录；不要替用户选择，也不要新建授权请求。';
+    }
+    return '用户仍在官方页面完成登录；保留当前 handoff，不要生成新二维码或新请求。';
+}
+// AUTH07: distinct outcomes stay distinct — a technical failure is never
+// reported as a user denial, and a missing session is its own state.
+const TERMINAL_SESSION_STATES = {
+    expired: {
+        status: 'auth_expired',
+        instruction: '授权请求已过期。重新运行 itpay auth login 生成新请求；之前的查询输入在服务端保留，可恢复。',
+    },
+    failed: {
+        status: 'auth_failed',
+        instruction: '官方授权因技术原因未完成（不是用户拒绝）。重新运行 itpay auth login 生成新请求。',
+    },
+    cancelled: {
+        status: 'auth_cancelled',
+        instruction: '用户在官方页取消了授权。如仍需登录，重新运行 itpay auth login。',
+    },
+    denied: {
+        status: 'auth_denied',
+        instruction: '官方授权被拒绝。重新运行 itpay auth login 生成新请求。',
+    },
+};
+class AuthRequestError extends Error {
+    httpStatus;
+    constructor(httpStatus, message) {
+        super(message);
+        this.httpStatus = httpStatus;
+        this.name = 'AuthRequestError';
+    }
+}
+// AUTH03: transport/read uncertainty never maps to "denied" or a new session —
+// the stored session stays on disk and the caller retries the same poll.
+function authStatusUnknown(sessionID) {
+    return {
+        status: 'auth_status_unknown',
+        result: sessionID ? { dashboard_auth_session_id: sessionID } : {},
+        instruction: '读取官方授权状态时遇到网络或服务端临时故障；原授权请求已保留。稍后重读同一状态，不要新建授权、不要清除本地登记。',
+        next: { command: 'itpay auth status --json', reason: '稍后重读同一授权状态', poll_after_ms: 5000 },
+        recovery: [],
+    };
+}
+function sessionGone(env, purpose, baseURL, sessionID) {
+    rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
+    return {
+        status: 'auth_session_missing',
+        result: sessionID ? { dashboard_auth_session_id: sessionID } : {},
+        instruction: '之前的授权请求在服务端已不存在。重新运行 itpay auth login 生成新请求。',
+        next: { command: 'itpay auth login --json', reason: '重新发起官方授权' },
+        recovery: [],
+    };
+}
+// AUTH04: a successful bind resumes the SAME task that paused for login —
+// from the local task journal, never a placeholder and never a guess at the
+// latest order.
+function authenticatedEnvelope(env, phoneVerified) {
+    const paused = new TaskJournal(taskJournalPath(env)).pausedTasks()
+        .filter((task) => task.stage === 'login_required' || task.stage === 'quota_paused');
+    const resumable = paused.filter((task) => typeof task.resume_command === 'string');
+    const result = { bound: true, phone_verified: phoneVerified };
+    let instruction = '登录与绑定已完成，告知用户可继续之前的查询；已注册账号查询不消耗试用次数，仍受正常限流。';
+    let next = null;
+    if (resumable.length === 1) {
+        next = { command: resumable[0].resume_command, reason: '恢复登录前暂停的同一查询' };
+    }
+    else if (resumable.length > 1) {
+        result.paused_executions = resumable.map((task) => ({
+            service_execution_id: task.service_execution_id,
+            ...(task.service_id ? { service_id: task.service_id } : {}),
+            resume_command: task.resume_command,
+        }));
+        instruction += ' 有多个暂停的查询：只恢复与当前用户目标对应的那一个，不要一次恢复全部。';
+    }
+    else {
+        instruction += ' 当前没有待恢复的暂停查询；不构造恢复命令。';
+    }
+    return { status: 'authenticated', result, instruction, next, recovery: [] };
+}
 async function accountAuth(action, baseURL, env, fetcher, backend) {
     const purpose = backend ? 'agent-login' : 'seller';
     const command = backend ? 'itpay auth status' : 'itpay sell auth status';
     if (backend) {
-        const current = await backend.agentAccountStatus();
-        if (current.status === 'authenticated')
-            return {
-                status: 'authenticated',
-                result: { bound: true, phone_verified: current.phone_verified === true },
-                instruction: '设备已绑定账号，可继续之前的查询或购买；登录不附带任何额外授权。',
-                next: { command: 'itpay services run <service_id> --execution <pending_execution_id> --json', reason: '恢复被额度暂停的原执行' },
-                recovery: [],
-            };
+        try {
+            const current = await backend.agentAccountStatus();
+            if (current.status === 'authenticated')
+                return authenticatedEnvelope(env, current.phone_verified === true);
+        }
+        catch (error) {
+            if (error instanceof AuthRequestError)
+                throw error;
+            // AUTH03: even the binding-status probe can hit transport failure; the
+            // truthful state is "unknown", never an implicit unbound or a fresh login.
+            return authStatusUnknown(undefined);
+        }
     }
     async function request(path, init = {}) {
         const response = await fetcher(baseURL + path, { ...init, redirect: 'error', signal: AbortSignal.timeout(15000) });
         if (!response.ok)
-            throw new Error(`ItPay authorization failed (${response.status}); retry login if expired`);
+            throw new AuthRequestError(response.status, `ItPay authorization failed (${response.status}); retry login if expired`);
         return response;
     }
+    function pollOpenSession(state) {
+        return request(`/v1/dashboard/auth-sessions/${encodeURIComponent(state.sessionID)}?poll_token=${encodeURIComponent(state.pollToken)}`)
+            .then((response) => response.json());
+    }
+    async function bindSavedSession(state) {
+        const bound = await backend.bindAgentAccount({ dashboard_auth_session_id: state.sessionID, start_token: state.startToken });
+        if (bound.status !== 'authenticated')
+            throw new Error('Agent binding did not complete');
+        rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
+        return authenticatedEnvelope(env, bound.phone_verified === true);
+    }
     if (action === 'login') {
         if (backend) {
             const open = read(baseURL, env, purpose);
             if (open?.sessionID && open.pollToken && open.startToken) {
                 try {
-                    const current = await (await request(`/v1/dashboard/auth-sessions/${encodeURIComponent(open.sessionID)}?poll_token=${encodeURIComponent(open.pollToken)}`)).json();
-                    if (['created', 'waiting_provider', 'email_verification_required', 'merge_confirmation_required'].includes(current.status)) {
+                    const current = await pollOpenSession(open);
+                    // AUTH02: a completed-but-unbound session binds in place; never
+                    // create a second auth session for the same login.
+                    if (current.status === 'completed')
+                        return await bindSavedSession(open);
+                    if (ACTIVE_SESSION_STAGES.includes(current.status)) {
                         const url = open.authURL ?? '';
                         const qr = url ? await writeLocalPNG(url).catch(() => undefined) : undefined;
                         return {
                             status: 'auth_pending',
-                            result: { dashboard_auth_session_id: open.sessionID, expires_at: current.expires_at, methods: ['phone', 'email', 'alipay', 'wechat'] },
-                            handoff: { url, ...(qr ? { qr_local_path: qr.filePath, markdown: `![ItPay 官方授权二维码](${qr.filePath})` } : {}) },
-                            instruction: '已有进行中的官方授权请求，沿用同一链接或二维码；不要生成新请求。用户在页面内选择手机号验证码、邮箱或钱包完成登录。',
+                            result: {
+                                dashboard_auth_session_id: open.sessionID,
+                                stage: current.status,
+                                expires_at: current.expires_at,
+                                methods: ['phone', 'email', 'alipay', 'wechat'],
+                            },
+                            // SEC01: the handoff URL carries one-time credentials — it goes
+                            // to the human only, never into logs, prompts, or PR material.
+                            handoff: {
+                                url,
+                                contains_credentials: true,
+                                ...(qr ? { qr_local_path: qr.filePath, markdown: `![ItPay 官方授权二维码](${qr.filePath})` } : {}),
+                            },
+                            instruction: `${stageInstruction(current.status)} 沿用同一链接或二维码；不要生成新请求。`,
                             next: { command: 'itpay auth status --json', reason: '用户完成页面登录后确认绑定', poll_after_ms: 5000 },
                             recovery: [],
                         };
                     }
+                    const terminal = TERMINAL_SESSION_STATES[current.status];
+                    if (terminal) {
+                        rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
+                        // Fall through to a fresh session only after a definitive
+                        // terminal state; anything else keeps the stored session.
+                    }
+                    else {
+                        return authStatusUnknown(open.sessionID);
+                    }
+                }
+                catch (error) {
+                    if (error instanceof AuthRequestError && (error.httpStatus === 404 || error.httpStatus === 410)) {
+                        return sessionGone(env, purpose, baseURL, open.sessionID);
+                    }
+                    return authStatusUnknown(open.sessionID);
                 }
-                catch { /* fall through to a fresh request */ }
             }
         }
         const response = await request('/v1/dashboard/auth-sessions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ return_to: backend ? '/' : '/seller' }) });
@@ -95,14 +227,16 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
                 status: 'auth_pending',
                 result: {
                     dashboard_auth_session_id: result.dashboard_auth_session_id,
+                    stage: 'created',
                     expires_at: result.expires_at,
                     methods: ['phone', 'email', 'alipay', 'wechat'],
                 },
                 handoff: {
                     url: url.href,
+                    contains_credentials: true,
                     ...(qr ? { qr_local_path: qr.filePath, markdown: `![ItPay 官方授权二维码](${qr.filePath})` } : {}),
                 },
-                instruction: '把官方授权页或二维码交给用户。用户在页面内选择手机号验证码、邮箱或钱包完成登录；不要替用户输入手机号或验证码，start_token 不要写入聊天记录。',
+                instruction: '把官方授权页或二维码交给用户。用户在页面内选择手机号验证码、邮箱或钱包完成登录；不要替用户输入手机号或验证码，start_token 不要写入聊天记录或日志。',
                 next: { command: 'itpay auth status --json', reason: '用户完成页面登录后确认绑定', poll_after_ms: 5000 },
                 recovery: [],
             };
@@ -119,36 +253,50 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
     }
     if (!backend && sellerSessionToken(baseURL, env))
         return { status: 'authenticated', base_url: baseURL, expires_at: state?.expiresAt };
-    if (!state?.sessionID || !state.pollToken || !state.startToken)
-        return { status: 'login_required' };
-    const path = `/v1/dashboard/auth-sessions/${encodeURIComponent(state.sessionID)}`;
-    const progress = await (await request(`${path}?poll_token=${encodeURIComponent(state.pollToken)}`)).json();
+    if (!state?.sessionID || !state.pollToken || !state.startToken) {
+        // AUTH07: a bare `status` with no session is its own truthful state, not a
+        // failure and not an implicit login.
+        if (!backend)
+            return { status: 'login_required' };
+        return {
+            status: 'login_required',
+            result: {},
+            instruction: '当前设备尚未绑定账号，也没有进行中的授权请求。需要时运行 itpay auth login 发起官方登录。',
+            next: { command: 'itpay auth login --json', reason: '需要账号绑定时发起官方授权' },
+            recovery: [],
+        };
+    }
+    let progress;
+    try {
+        progress = await pollOpenSession(state);
+    }
+    catch (error) {
+        if (error instanceof AuthRequestError && (error.httpStatus === 404 || error.httpStatus === 410)) {
+            return sessionGone(env, purpose, baseURL, state.sessionID);
+        }
+        return authStatusUnknown(state.sessionID);
+    }
     if (progress.status !== 'completed') {
         if (backend) {
-            if (progress.status === 'expired') {
+            const terminal = TERMINAL_SESSION_STATES[progress.status];
+            if (terminal) {
                 rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
                 return {
-                    status: 'auth_expired',
-                    result: { dashboard_auth_session_id: state.sessionID },
-                    instruction: '授权请求已过期。重新运行 itpay auth login 生成新请求；之前的查询输入在服务端保留，可恢复。',
-                    next: { command: 'itpay auth login --json', reason: '重新发起官方授权' },
-                    recovery: [],
-                };
-            }
-            if (progress.status === 'failed' || progress.status === 'cancelled' || progress.status === 'denied') {
-                rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
-                return {
-                    status: progress.status === 'failed' ? 'auth_denied' : `auth_${progress.status}`,
-                    result: { dashboard_auth_session_id: state.sessionID },
-                    instruction: '官方授权未通过或被取消。重新运行 itpay auth login 生成新请求。',
+                    status: terminal.status,
+                    result: { dashboard_auth_session_id: state.sessionID, stage: progress.status },
+                    instruction: terminal.instruction,
                     next: { command: 'itpay auth login --json', reason: '重新发起官方授权' },
                     recovery: [],
                 };
             }
             return {
                 status: 'auth_pending',
-                result: { dashboard_auth_session_id: state.sessionID },
-                instruction: '用户仍在官方页面完成登录；保留当前 handoff，不要生成新二维码或新请求。',
+                result: {
+                    dashboard_auth_session_id: state.sessionID,
+                    stage: progress.status,
+                    ...(progress.expires_at ? { expires_at: progress.expires_at } : {}),
+                },
+                instruction: stageInstruction(progress.status),
                 next: { command: 'itpay auth status --json', reason: '轮询同一授权请求', poll_after_ms: 5000 },
                 recovery: [],
             };
@@ -156,19 +304,18 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
         return { status: progress.status, instruction: 'Finish login and email verification in the browser.' };
     }
     if (backend) {
-        const result = await backend.bindAgentAccount({ dashboard_auth_session_id: state.sessionID, start_token: state.startToken });
-        if (result.status !== 'authenticated')
-            throw new Error('Agent binding did not complete');
-        rmSync(sellerAuthPath(baseURL, env, purpose), { force: true });
-        return {
-            status: 'authenticated',
-            result: { bound: true, phone_verified: result.phone_verified === true },
-            instruction: '登录与绑定已完成，告知用户可继续之前的查询；已注册账号查询不消耗试用次数，仍受正常限流。',
-            next: { command: 'itpay services run <service_id> --execution <pending_execution_id> --json', reason: '恢复被额度暂停的原查询' },
-            recovery: [],
-        };
+        try {
+            return await bindSavedSession(state);
+        }
+        catch (error) {
+            if (error instanceof AuthRequestError)
+                throw error;
+            // Binding outcome unknown: keep the session so a retry can still bind
+            // the same completed login instead of creating a new one.
+            return authStatusUnknown(state.sessionID);
+        }
     }
-    const claimed = await request(`${path}/claim?start_token=${encodeURIComponent(state.startToken)}`, { method: 'POST' });
+    const claimed = await request(`/v1/dashboard/auth-sessions/${encodeURIComponent(state.sessionID)}/claim?start_token=${encodeURIComponent(state.startToken)}`, { method: 'POST' });
     const token = /(?:^|[, ]+)itpay_buyer_session=([^;]+)/.exec(claimed.headers.get('set-cookie') ?? '')?.[1];
     const session = await claimed.json();
     if (!token || !session.expires_at || !(Date.parse(session.expires_at) > Date.now()))

package/dist/src/state/client_context.js

@@ -79,3 +79,73 @@ export function validateContext(host, target) {
     }
     return undefined;
 }
+export function normalizeViewer(raw) {
+    const v = raw?.trim().toLowerCase();
+    if (v === "desktop" || v === "mobile")
+        return v;
+    return "unknown";
+}
+export function normalizeLocality(raw) {
+    const v = raw?.trim().toLowerCase();
+    if (v === "same_device" || v === "remote" || v === "cloud")
+        return v;
+    return "unknown";
+}
+// Conservative declared capability table per host. Terminal/desktop agent
+// hosts run where a human watches a screen and a system browser exists;
+// IM hosts can send links/buttons but cannot be assumed to open pages;
+// plain-chat surfaces get links and copyable entries only.
+export function hostCapabilities(host) {
+    switch (host) {
+        case "terminal":
+        case "codex":
+        case "claude-code":
+            return {
+                user_visible_browser: "unknown",
+                system_browser: "yes",
+                clickable_https: "yes",
+                image_visible: host === "terminal" ? "no" : "unknown",
+                native_url_button: "no",
+                user_visible_terminal: "yes",
+                other_device_scan: "yes",
+                send_message: "yes",
+            };
+        case "telegram":
+        case "feishu":
+        case "lark":
+            return {
+                user_visible_browser: "no",
+                system_browser: "no",
+                clickable_https: "yes",
+                image_visible: "yes",
+                native_url_button: "yes",
+                user_visible_terminal: "no",
+                other_device_scan: "unknown",
+                send_message: "yes",
+            };
+        case "discord":
+        case "whatsapp":
+            return {
+                user_visible_browser: "no",
+                system_browser: "no",
+                clickable_https: "yes",
+                image_visible: "yes",
+                native_url_button: "unknown",
+                user_visible_terminal: "no",
+                other_device_scan: "unknown",
+                send_message: "yes",
+            };
+        case "plain-chat":
+        default:
+            return {
+                user_visible_browser: "no",
+                system_browser: "unknown",
+                clickable_https: "yes",
+                image_visible: "no",
+                native_url_button: "unknown",
+                user_visible_terminal: "no",
+                other_device_scan: "unknown",
+                send_message: "yes",
+            };
+    }
+}

package/dist/src/state/config.js

@@ -15,11 +15,12 @@ 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.17";
-export const API_CONTRACT_REVISION = "sha256:c6125896053540d1b56f9d106df499ac90162fb8fa4cce619c8029e90f771f85";
+export const CLI_VERSION = "2.1.19";
+export const API_CONTRACT_REVISION = "sha256:2f9fbcdc5cd0630910abb52671304cc019e348e9a778017ec92ddc3513b3639f";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";
+const TASK_JOURNAL_FILENAME = "tasks.json";
 export function cliDistribution(env = process.env) {
     if (env.ITPAY_DISTRIBUTION === "openclaw-skill-bundle")
         return "openclaw-skill-bundle";
@@ -75,6 +76,16 @@ export function cartSessionPath(env = process.env) {
     mkdirSync(dir, { recursive: true });
     return resolve(dir, stateFilename(CART_SESSION_FILENAME, resolveBackendURL(env)));
 }
+// Task journal (AUTH04): paused Service Executions per backend, so a login
+// completion can resume the SAME task instead of guessing from the latest order.
+export function taskJournalPath(env = process.env) {
+    if (env.ITPAY_TASK_JOURNAL_PATH) {
+        return resolve(env.ITPAY_TASK_JOURNAL_PATH);
+    }
+    const dir = stateDir(env);
+    mkdirSync(dir, { recursive: true });
+    return resolve(dir, stateFilename(TASK_JOURNAL_FILENAME, resolveBackendURL(env)));
+}
 export function loadConfig(env = process.env) {
     const baseURL = resolveBackendURL(env);
     const bearerToken = env.ITPAY_BEARER_TOKEN || undefined;