@itpay/cli 2.0.35 → 2.0.37

package/README.md

@@ -53,6 +53,7 @@ Normative per-command contracts: [CLI Command Reference](docs/cli-reference/inde
 | `claude-code-desktop` | `claude-code` |
 | `claude-code-cli` | `terminal` |
 | `workbuddy` | `plain-chat` |
+| `zcode` | `plain-chat` |
 | `kimi-code` | `terminal` |
 | `openclaw` | 必须显式提供 |
 

package/dist/src/commands/buy.js

@@ -17,7 +17,7 @@ import { localizeCardURL, normalizeCardLocale } from "../render/locale.js";
 import { buildAgentChatHandoff } from "../render/markdown.js";
 import { formatMoney } from "../render/output.js";
 import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
-import { buildCheckoutHandoff, shouldPrepareLocalCheckoutImage } from "./checkout_handoff.js";
+import { buildCheckoutHandoff, isLinkOnlyBrowserAgent, shouldPrepareLocalCheckoutImage } from "./checkout_handoff.js";
 import { qualifyItPayCommand } from "../state/agent_type.js";
 export async function runBuy(backend, config, options) {
     const err = validateContext(options.host, options.target);
@@ -267,7 +267,7 @@ export function buildCheckoutQRPlan(input) {
         host: input.host,
         summary,
         url: input.qrPayload,
-        ...(input.agentType?.trim().toLowerCase() === "workbuddy" && input.cardURL ? { linkOnlyURL: input.cardURL } : {}),
+        ...(isLinkOnlyBrowserAgent(input.agentType, platformKeyForHost(input.host)) && input.cardURL ? { linkOnlyURL: input.cardURL } : {}),
         preferredQRSources: [input.qrPNGURL ?? input.qrPayload],
         checkoutID: input.checkoutID,
         platform,

package/dist/src/commands/checkout_handoff.js

@@ -5,6 +5,12 @@ export function shouldPrepareLocalCheckoutImage(platform) {
 export function isWorkBuddyPlainChat(agentType, platform) {
     return agentType?.trim().toLowerCase() === "workbuddy" && platform === "plain_chat";
 }
+export function isZCodePlainChat(agentType, platform) {
+    return agentType?.trim().toLowerCase() === "zcode" && platform === "plain_chat";
+}
+export function isLinkOnlyBrowserAgent(agentType, platform) {
+    return isWorkBuddyPlainChat(agentType, platform) || isZCodePlainChat(agentType, platform);
+}
 export function buildWorkBuddyPresentFilesAction(url) {
     return {
         tool: "present_files",
@@ -23,7 +29,7 @@ export function buildCheckoutHandoff(input) {
         if (input.markdown)
             handoff.markdown = input.markdown;
     }
-    else if (input.platform === "plain_chat" && input.qrImageURL && !workBuddyAction) {
+    else if (input.platform === "plain_chat" && input.qrImageURL && !isLinkOnlyBrowserAgent(input.agentType, input.platform)) {
         handoff.qr_image_url = input.qrImageURL;
     }
     else if (input.platform === "telegram" && input.qrImageURL) {
@@ -41,6 +47,9 @@ function checkoutHandoffInstruction(agentType, platform, amount) {
     if (isWorkBuddyPlainChat(agentType, platform)) {
         return `Backend 尚未确认付款。立即严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行一次，在右侧打开 handoff.url；确认工具调用成功后说明金额 ${amount}，然后停止等待。若工具失败，只发送原始 handoff.url，报告未自动打开并停止。不要用 present_files 打开本地文件或二维码 PNG，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }
+    if (isZCodePlainChat(agentType, platform)) {
+        return `Backend 尚未确认付款。立即用 ZCode 内置浏览器打开 handoff.url，让用户完成付款；确认已发起打开后说明金额 ${amount}，然后停止等待。不要只粘贴文字链接，不要下载、解析或重建二维码，不要创建新 Checkout、Payment Intent 或 Execution。只有内置浏览器明确不可用时，才展示同一个可点击 handoff.url。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+    }
     if (platform === "markdown") {
         return `Backend 尚未确认付款。把 handoff.markdown 原样发送到当前桌面对话，确认二维码、付款链接和金额 ${amount} 均已实际对用户可见，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }

package/dist/src/commands/install.js

@@ -7,6 +7,7 @@ export const INSTALL_AGENT_TYPES = [
     "claude-code-desktop",
     "claude-code-cli",
     "workbuddy",
+    "zcode",
     "kimi-code",
     "openclaw",
 ];
@@ -16,6 +17,7 @@ const INSTRUCTIONS = {
     "claude-code-desktop": "在 Claude Code Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
     "claude-code-cli": "在 Claude Code CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
     workbuddy: "在 WorkBuddy 中始终传这个 Agent Type。运行会持久化 ~/.itpay-v3 的 ItPay Bash 命令前，把 Shell 工具参数 dangerouslyDisableSandbox 设为 true；用户拒绝权限时停止，不要切换 Node、删除 identity 或处理 lock。Checkout 返回已渲染的付款 Card Link 和 present_files action；原样执行一次 action 打开 handoff.url，不要检查本地二维码文件。",
+    zcode: "在 ZCode 中始终传这个 Agent Type。Checkout 或授权返回 handoff.url 后，立即用 ZCode 内置浏览器打开；不要只粘贴文字链接或重建二维码。只有内置浏览器不可用时才展示同一个可点击链接。",
     "kimi-code": "保持 kimi-code Agent Type，使用标准 CLI 命令和终端付款交接；不要切换到其他平台身份。",
     openclaw: "保持 openclaw Agent Type；每个展示命令都从当前可信会话上下文显式传 --host，IM 入口同时传 --target。Telegram 使用返回的原生 message action，其他入口展示标准二维码和付款链接。",
 };

package/dist/src/commands/pay.js

@@ -2,7 +2,7 @@
 // Checkout page; this command exists for controlled integration recovery.
 import { formatMoney } from "../render/output.js";
 import { writeCommandEnvelope } from "./guidance.js";
-import { buildWorkBuddyPresentFilesAction, isWorkBuddyPlainChat } from "./checkout_handoff.js";
+import { buildWorkBuddyPresentFilesAction, isWorkBuddyPlainChat, isZCodePlainChat } from "./checkout_handoff.js";
 import { platformKeyForHost } from "../render/plan.js";
 export async function runPay(backend, options) {
     const intent = await backend.createPaymentIntent(options.checkoutID, {
@@ -20,12 +20,17 @@ function payEnvelope(intent, options) {
     const terminal = ["failed", "expired", "refunded"].includes(intent.status);
     const verified = intent.status === "verified" || intent.status === "partially_refunded";
     const handoff = {};
-    const workBuddyAction = isWorkBuddyPlainChat(options.agentType, platformKeyForHost(options.host));
-    if (!terminal && !verified && workBuddyAction) {
-        const url = intent.action?.mobile_wallet_url ?? intent.action?.qr_image_url;
+    const platform = platformKeyForHost(options.host);
+    const workBuddyAction = isWorkBuddyPlainChat(options.agentType, platform);
+    const zcodeAction = isZCodePlainChat(options.agentType, platform);
+    if (!terminal && !verified && (workBuddyAction || zcodeAction)) {
+        const url = zcodeAction
+            ? intent.action?.qr_image_url ?? intent.action?.mobile_wallet_url
+            : intent.action?.mobile_wallet_url ?? intent.action?.qr_image_url;
         if (url) {
             handoff.url = url;
-            handoff.agent_action = buildWorkBuddyPresentFilesAction(url);
+            if (workBuddyAction)
+                handoff.agent_action = buildWorkBuddyPresentFilesAction(url);
         }
     }
     else {
@@ -64,6 +69,9 @@ function payInstruction(options, verified, terminal, hasAction, amount) {
     if (isWorkBuddyPlainChat(options.agentType, platform)) {
         return `这是受控逃生入口。立即严格按 handoff.agent_action 原样执行一次，在右侧打开 handoff.url；确认工具调用成功后说明金额 ${amount} 并停止等待。若工具失败，只发送原始 handoff.url，报告未自动打开并停止。不要用 present_files 打开本地文件或二维码 PNG，不要立即查询、创建替代 Checkout 或 Payment Intent。`;
     }
+    if (isZCodePlainChat(options.agentType, platform)) {
+        return `这是受控逃生入口。立即用 ZCode 内置浏览器打开 handoff.url；确认已发起打开后说明金额 ${amount} 并停止等待。不要只粘贴文字链接，不要下载或重建二维码，不要立即查询、创建替代 Checkout 或 Payment Intent。只有内置浏览器明确不可用时，才展示同一个可点击 handoff.url。`;
+    }
     if (options.host === "codex" || options.host === "claude-code")
         return "这是受控逃生入口；把 handoff 中的二维码或钱包链接实际发到当前桌面对话，然后停止等待。";
     if (options.host === "terminal")

package/dist/src/commands/vault_handoff.js

@@ -1,7 +1,7 @@
 import { platformKeyForHost } from "../render/plan.js";
 import { downloadBrandQRToTmp } from "../render/ide.js";
 import { renderTerminalQR } from "../render/qr.js";
-import { buildWorkBuddyPresentFilesAction, isWorkBuddyPlainChat } from "./checkout_handoff.js";
+import { buildWorkBuddyPresentFilesAction, isWorkBuddyPlainChat, isZCodePlainChat } from "./checkout_handoff.js";
 const AUTH_ATTACH_REASON = "The human must be able to open or scan this official ItPay authorization handoff. " +
     "Render the local image in the current desktop chat; if that fails, show the unchanged official URL.";
 export async function buildVaultHandoff(input) {
@@ -14,6 +14,12 @@ export async function buildVaultHandoff(input) {
             instruction: "向用户说明这是查看已购内容的只读授权，然后严格按 handoff.agent_action 原样执行一次。打开成功后停止等待；失败时只发送同一个 handoff.url。用户完成后重新运行最初的读取命令，不要再次创建授权请求。",
         };
     }
+    if (isZCodePlainChat(input.agentType, platform)) {
+        return {
+            handoff,
+            instruction: "向用户说明这是查看已购内容的只读授权，然后立即用 ZCode 内置浏览器打开 handoff.url。确认已发起打开后停止等待；不要只粘贴文字链接，也不要下载或重建二维码。只有内置浏览器明确不可用时，才展示同一个可点击 handoff.url。用户完成后重新运行最初的读取命令，不要再次创建授权请求。",
+        };
+    }
     if (platform === "markdown") {
         const downloaded = input.imageAttachEnabled && input.qrPNGURL
             ? await downloadBrandQRToTmp(input.qrPNGURL, "auth", input.requestID, {

package/dist/src/state/client_context.js

@@ -62,6 +62,8 @@ export function defaultHostForAgentType(agentType) {
         return "claude-code";
     if (normalized === "workbuddy")
         return "plain-chat";
+    if (normalized === "zcode")
+        return "plain-chat";
     if (normalized === "openclaw")
         return undefined;
     return "terminal";

package/dist/src/state/config.js

@@ -12,8 +12,8 @@ import { DeviceAuthority } from "./device_authority.js";
 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 CLI_VERSION = "2.0.35";
-export const API_CONTRACT_REVISION = "sha256:a249912e4afb3267694081231334eb8a2ec653ceb9bbcbca91969b6977159e50";
+export const CLI_VERSION = "2.0.37";
+export const API_CONTRACT_REVISION = "sha256:b97025ee4e6f7539757d6aedbe193dd65b3a0f84f1111f678abb5e757065f888";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";

package/dist/src/state/device_authority.js

@@ -1,5 +1,5 @@
 import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomUUID, sign, } from "node:crypto";
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmdirSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 const PROTECTED_PATHS = ["/v1/carts", "/v1/service-executions", "/v1/agent-instances", "/v1/orders", "/v1/refunds", "/v1/me", "/v1/vault"];
@@ -292,10 +292,12 @@ async function withFileLock(path, run) {
     catch (error) {
         throw asDeviceStatePathError(error, "prepare_lock") ?? error;
     }
+    const ownerToken = randomUUID();
     let acquired = false;
     for (let attempt = 0; attempt < 200; attempt += 1) {
         try {
-            mkdirSync(path, { mode: 0o700 });
+            writeFileSync(path, ownerToken, { encoding: "utf8", flag: "wx", mode: 0o600 });
+            chmodSync(path, 0o600);
             acquired = true;
             break;
         }
@@ -305,7 +307,7 @@ async function withFileLock(path, run) {
                 throw asDeviceStateError(error, "acquire_lock") ?? error;
             try {
                 if (Date.now() - statSync(path).mtimeMs > 30_000)
-                    removeLock(path, "remove_stale_lock");
+                    moveLockAside(path, "stale", "remove_stale_lock");
             }
             catch (statError) {
                 if (statError.code !== "ENOENT") {
@@ -321,19 +323,33 @@ async function withFileLock(path, run) {
         return await run();
     }
     finally {
-        removeLock(path, "release_lock");
+        releaseLock(path, ownerToken);
     }
 }
-function removeLock(path, operation) {
+function releaseLock(path, ownerToken) {
     try {
-        if (statSync(path).isDirectory())
-            rmdirSync(path);
-        else
-            unlinkSync(path);
+        if (readFileSync(path, "utf8") !== ownerToken)
+            return;
+        moveLockAside(path, "released", "release_lock");
     }
     catch (error) {
         if (error.code !== "ENOENT")
-            throw asDeviceStateError(error, operation) ?? error;
+            throw asDeviceStateError(error, "release_lock") ?? error;
+    }
+}
+function moveLockAside(path, suffix, operation) {
+    try {
+        renameSync(path, `${path}.${suffix}`);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            return;
+        if (code === "EEXIST" || code === "ENOTEMPTY") {
+            renameSync(path, `${path}.${suffix}.${randomUUID()}`);
+            return;
+        }
+        throw asDeviceStateError(error, operation) ?? error;
     }
 }
 function asDeviceStateError(error, operation) {

package/dist/src/state/operation_journal.js

@@ -1,80 +1,93 @@
-import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, existsSync, linkSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
 export class OperationJournal {
-    path;
-    constructor(path) {
-        this.path = path;
+    legacyPath;
+    constructor(legacyPath) {
+        this.legacyPath = legacyPath;
     }
     async getOrCreate(operationKey) {
-        return withFileLock(`${this.path}.lock`, async () => {
-            const state = this.read();
-            const existing = state.operations[operationKey];
-            if (existing)
-                return existing.id;
-            const id = `op_${randomUUID().replaceAll("-", "")}`;
-            state.operations[operationKey] = { id, createdAt: new Date().toISOString() };
-            atomicOwnerOnlyWrite(this.path, JSON.stringify(state, null, 2));
-            return id;
-        });
-    }
-    read() {
-        if (existsSync(this.path)) {
+        const operationKeyHash = createHash("sha256").update(operationKey).digest("hex");
+        const recordDirectory = `${this.legacyPath}.d`;
+        const recordPath = resolve(recordDirectory, `${operationKeyHash}.json`);
+        const existing = readRecord(recordPath, operationKeyHash);
+        if (existing)
+            return existing.id;
+        mkdirSync(recordDirectory, { recursive: true, mode: 0o700 });
+        chmodSync(recordDirectory, 0o700);
+        const record = {
+            schemaVersion: "itpay.operation.v2",
+            operationKeyHash,
+            id: this.readLegacyID(operationKey) ?? `op_${randomUUID().replaceAll("-", "")}`,
+            createdAt: new Date().toISOString(),
+        };
+        const temporaryPath = resolve(recordDirectory, `.${basename(recordPath)}.${process.pid}.${randomUUID()}.tmp`);
+        try {
+            writeFileSync(temporaryPath, JSON.stringify(record, null, 2), { encoding: "utf8", flag: "wx", mode: 0o600 });
+            chmodSync(temporaryPath, 0o600);
             try {
-                const parsed = JSON.parse(readFileSync(this.path, "utf8"));
-                if (parsed.schemaVersion === "itpay.operations.v1" && parsed.operations)
-                    return parsed;
+                linkSync(temporaryPath, recordPath);
+                chmodSync(recordPath, 0o600);
+                return record.id;
             }
-            catch {
-                // A malformed local cache is replaced; server facts remain authoritative.
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                const winner = readRecord(recordPath, operationKeyHash);
+                if (!winner)
+                    throw new Error("ItPay operation journal record disappeared during publication");
+                return winner.id;
             }
         }
-        return { schemaVersion: "itpay.operations.v1", operations: {} };
-    }
-}
-function atomicOwnerOnlyWrite(path, value) {
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
-    writeFileSync(temporary, value, { encoding: "utf8", mode: 0o600 });
-    chmodSync(temporary, 0o600);
-    renameSync(temporary, path);
-    chmodSync(path, 0o600);
-}
-async function withFileLock(path, run) {
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    let descriptor;
-    for (let attempt = 0; attempt < 200; attempt += 1) {
-        try {
-            descriptor = openSync(path, "wx", 0o600);
-            break;
-        }
-        catch (error) {
-            if (error.code !== "EEXIST")
-                throw error;
+        finally {
             try {
-                if (Date.now() - statSync(path).mtimeMs > 30_000)
-                    unlinkSync(path);
+                unlinkSync(temporaryPath);
             }
-            catch (statError) {
-                if (statError.code !== "ENOENT")
-                    throw statError;
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
             }
-            await new Promise((resolve) => setTimeout(resolve, 25));
         }
     }
-    if (descriptor === undefined)
-        throw new Error("timed out waiting for ItPay operation journal lock");
-    try {
-        return await run();
-    }
-    finally {
-        closeSync(descriptor);
+    readLegacyID(operationKey) {
+        if (!existsSync(this.legacyPath))
+            return undefined;
         try {
-            unlinkSync(path);
+            const parsed = JSON.parse(readFileSync(this.legacyPath, "utf8"));
+            if (parsed.schemaVersion !== "itpay.operations.v1" || !parsed.operations)
+                return undefined;
+            const id = parsed.operations[operationKey]?.id;
+            return typeof id === "string" && isOperationID(id) ? id : undefined;
         }
-        catch (error) {
-            if (error.code !== "ENOENT")
-                throw error;
+        catch {
+            return undefined;
         }
     }
 }
+function readRecord(path, expectedHash) {
+    if (!existsSync(path))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new Error("ItPay operation journal record is invalid");
+    }
+    if (!isOperationRecord(parsed, expectedHash)) {
+        throw new Error("ItPay operation journal record is invalid");
+    }
+    return parsed;
+}
+function isOperationRecord(value, expectedHash) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return record.schemaVersion === "itpay.operation.v2" &&
+        record.operationKeyHash === expectedHash &&
+        typeof record.id === "string" && isOperationID(record.id) &&
+        typeof record.createdAt === "string" && !Number.isNaN(Date.parse(record.createdAt));
+}
+function isOperationID(value) {
+    return /^op_[a-zA-Z0-9_-]+$/.test(value);
+}

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

@@ -25,8 +25,9 @@
   ],
   "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.",
+    "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 a lock, switch Node runtimes, delete identity, or rotate Agent Type as a retry strategy."
+    "Do not manually create or delete state locks, switch Node runtimes, delete identity, or rotate Agent Type as a retry strategy."
   ],
   "commands": [
     {

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

@@ -13,7 +13,7 @@
     {
       "intent": "list supported Agent Types",
       "command": "itpay install --json",
-      "success_signal": "status is install_targets and exactly seven supported Agent Type definitions are returned"
+      "success_signal": "status is install_targets and exactly eight supported Agent Type definitions are returned"
     },
     {
       "intent": "read setup for the real runtime",
@@ -38,7 +38,7 @@
     "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.",
     "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, kimi-code, or openclaw.",
+    "Use one exact type: codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy, zcode, 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.",
     "Within each official Backend registration, each Agent Type has one Agent Instance; all windows and chats of the same type reuse it.",
@@ -70,6 +70,7 @@
     "codex",
     "claude code",
     "workbuddy",
+    "zcode",
     "kimi code",
     "openclaw"
   ]

package/docs/agent/buyer/render-hosts.json

@@ -35,6 +35,11 @@
       "default_host": "plain-chat",
       "responsibility": "execute handoff.agent_action exactly once to open the fully rendered handoff.url with present_files; show the amount and stop"
     },
+    {
+      "agent_type": "zcode",
+      "default_host": "plain-chat",
+      "responsibility": "open handoff.url immediately in the ZCode built-in browser and stop; only show the same clickable URL when the built-in browser is unavailable"
+    },
     {
       "agent_type": "kimi-code",
       "default_host": "terminal",
@@ -64,6 +69,7 @@
     "Agent Type is stable identity; Host is presentation and may be explicitly overridden.",
     "A local QR path is not visible until a desktop Agent attaches or renders that file on the human-facing surface; WorkBuddy never receives a local QR path.",
     "For workbuddy with plain-chat, execute handoff.agent_action exactly once; it calls present_files with handoff.url as the only files element and opens the rendered Card Link in the right-side browser.",
+    "For zcode with plain-chat, open handoff.url in the built-in browser. Do not only paste text, download or rebuild a QR, or invent a private browser-tool payload; use the same clickable URL only as fallback.",
     "If the WorkBuddy action fails, send the original handoff.url, report that it did not auto-open, and stop without creating another payment resource.",
     "Do not claim the handoff was shown until both a usable payment image or QR and the Checkout URL are visible.",
     "IM Hosts that require a target must receive --target before Checkout creation. OpenClaw has no default Host; Kimi Code uses terminal.",
@@ -92,6 +98,7 @@
     "terminal",
     "desktop",
     "workbuddy",
+    "zcode",
     "kimi code",
     "openclaw",
     "telegram"

package/docs/cli-reference/agent-types.md

@@ -15,6 +15,7 @@
 | `claude-code-desktop` | `claude-code` | 返回桌面对话可展示的 Markdown 图片和官方链接，要求先展示再等待。 |
 | `claude-code-cli` | `terminal` | 在用户可见终端输出二维码和官方链接，不声称已在桌面对话展示。 |
 | `workbuddy` | `plain-chat` | 返回完整渲染的 HTML Card Link 和可原样执行的 `present_files` action；立即打开 Card Link，不返回或检查本地图片路径。 |
+| `zcode` | `plain-chat` | 返回完整渲染的官方 URL；立即用 ZCode 内置浏览器打开，不只粘贴文字链接，也不返回或重建二维码图片。 |
 | `kimi-code` | `terminal` | 使用标准 CLI 引导，在用户可见终端渲染二维码和付款链接。 |
 | `openclaw` | 无；必须显式传入 | `--host telegram` 使用 OpenClaw 原生 `message` action；其他入口返回标准 HTTPS 二维码和付款链接。 |
 
@@ -27,11 +28,12 @@
 - 显式 `--host` 覆盖默认 Host，但不改变已登记的 Agent Type。
 - `--target` 只路由人类展示，不是身份，也不是 capability 业务输入。
 - Host 只影响 `instruction` 和 `handoff`，不得改变金额、订单、权限、quota 或交付状态。
-- 七种 Agent Type 使用同一命令输入和 JSON 外壳；OpenClaw 只在 `handoff` 的既有扩展位置增加平台 action，不改变交易字段。
-- 非展示命令在七种 Agent Type 下返回相同业务结果，只允许 `instruction` 措辞不同。只有 Host 客观无法展示某种媒介时，`handoff` 才按既有可选字段做最小裁剪。
+- 所有正式 Agent Type 使用同一命令输入和 JSON 外壳；OpenClaw 只在 `handoff` 的既有扩展位置增加平台 action，不改变交易字段。
+- 非展示命令在所有正式 Agent Type 下返回相同业务结果，只允许 `instruction` 措辞不同。只有 Host 客观无法展示某种媒介时，`handoff` 才按既有可选字段做最小裁剪。
 - `openclaw` 没有默认 Host。展示命令必须显式传 `--host`；缺少时在任何 Checkout 创建或状态迁移前返回 `host_required`。
 - OpenClaw 的 IM Host 必须提供 `--target`。缺失时在任何 Checkout 创建前返回 `target_required`。
 - `kimi-code` 是 CLI 型 Agent，复用 `terminal` Host 和现有 CLI 展示，不增加 Kimi 专属交易协议。
+- `zcode` 使用 `plain-chat` Host 和官方 URL-only handoff。Agent 必须自行在 ZCode 内置浏览器打开 URL；只有内置浏览器确实不可用时才向用户展示同一个可点击链接。
 - session 失效时 CLI 只续期并重试原请求一次；再次失败立即返回。revoked v2 Device 不自动换身份。
 - 同一 Device 首次登记新的 Agent Type 时，CLI 只使用本地已登记且 Backend 仍接受的既有 Agent Instance 完成签名登记；被撤销的 Instance 会被跳过且不会恢复。若没有任何既有 Instance 可用，CLI 必须停止，不得重新登记 Device、旋转私钥或借用其他 Backend。
 
@@ -76,12 +78,15 @@ URL 内 credential 不得被提取、单独输出、记录或重建。
 | `codex-cli / terminal` | `url`；非 JSON 输出另外渲染终端二维码 |
 | `claude-code-cli / terminal` | `url`；非 JSON 输出另外渲染终端二维码 |
 | `workbuddy / plain-chat` | `url, agent_action`（`present_files(files=[url])`，打开完整渲染的 HTML Card Link） |
+| `zcode / plain-chat` | `url`（立即用 ZCode 内置浏览器打开；不返回图片或平台私有 action） |
 | `kimi-code / terminal` | `url`；非 JSON 输出另外渲染终端二维码 |
 | `openclaw / telegram` | `url, qr_image_url, agent_action` |
 | `openclaw / other` | `url, qr_image_url` |
 
 WorkBuddy instruction 必须要求 Agent 原样执行一次 `handoff.agent_action`，即调用 `present_files(files=[handoff.url])` 在右侧打开 Backend 已渲染的 HTML Card。调用成功后说明金额并停止；调用失败时只发送原始 `handoff.url` 并如实报告未自动打开。禁止把 `present_files` 用于本地文件或二维码 PNG，也不能下载或重建二维码、调用 `pay` 或创建替代付款资源。显式 `--host` 仍覆盖默认展示方式。
 
+ZCode instruction 必须明确要求 Agent 立即用内置浏览器打开 `handoff.url`，确认已发起打开后说明金额并停止。不得只把 URL 当作文字粘贴给用户，也不得下载、解析或重建二维码。只有内置浏览器明确不可用时，才把同一个 `handoff.url` 作为可点击链接展示。CLI 不猜测或输出 ZCode 私有工具调用 JSON。
+
 OpenClaw Telegram 的 `handoff.agent_action` 是可原样执行的原生 `message` tool action。`presentation` 只包含标准 `blocks.buttons`：`📱 手机点这儿支付` 使用扁平 `url`，`📋 已授权给我读` 使用扁平 `value=itp:grant_confirmed:<checkout_id>`；二维码单独使用 action 的 `media`。CLI `instruction` 必须要求 Agent 原样执行该 action，不得改写 Presentation、换用其他消息工具或声称普通文本回复等同于已发送按钮。收到授权 callback 后立即执行 `next.command` 查询同一 Checkout，再只跟随后端返回的同一 Execution grant 流程；callback 只携带 Checkout ID，不携带 display token，也不证明付款或 grant 已生效。OpenClaw `target` 使用原生 chat target（如 `5559456744` 或 `-1001234567890:topic:42`），不添加 `telegram:` 前缀。
 
 ### Purchased-content authorization
@@ -89,7 +94,7 @@ OpenClaw Telegram 的 `handoff.agent_action` 是可原样执行的原生 `messag
 `vault access` 使用相同字段集合，但不包含金额、Checkout ID、付款状态或付款
 查询命令。桌面 handoff 的 Markdown 标题和链接必须明确为“授权查看已购
 内容”；Terminal 显示授权二维码；WorkBuddy 用 `present_files` 打开完整
-`handoff.url`；OpenClaw 使用返回的图片/原生 action。
+`handoff.url`；ZCode 用内置浏览器打开完整 `handoff.url`；OpenClaw 使用返回的图片/原生 action。
 
 授权 handoff 展示后 `next=null`。用户明确表示已完成时，Agent只重新执行
 产生授权要求的原始 `vault list`、`orders` 或 `vault read`，不得再次执行

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

@@ -135,7 +135,7 @@ itpay buy \
 
 ## 幂等与中断恢复
 
-- CLI 在本机 operation journal 中为 `checkout.create:<cart_id>` 保存稳定幂等键。
+- CLI 在本机 `operations.json.d/`（dev 使用独立目录）中为 `checkout.create:<cart_id>` 保存一条不可变、owner-only 的稳定幂等记录；不同操作不共享全局锁。
 - HTTP 请求通过 `Idempotency-Key` 提交该键。
 - Checkout 响应丢失时，重跑同一命令会复用已保存的 canonical Cart 和同一幂等键。
 - 后端返回同一个待处理 Checkout，并轮换新的交接 token；不会创建第二笔订单。
@@ -168,6 +168,7 @@ itpay buy \
 | `claude-code-desktop` | `claude-code` | `url`、可用时 `qr_local_path` 和 `markdown` | 把 Markdown handoff 发到当前桌面对话，不能只输出本地路径。 |
 | `claude-code-cli` | `terminal` | `url` | 在用户可见终端展示；不能声称桌面对话已收到图片。 |
 | `workbuddy` | `plain-chat` | `url,agent_action` | 原样执行一次 `present_files(files=[url])`，在右侧打开完整渲染的 HTML Card Link，然后停止。 |
+| `zcode` | `plain-chat` | `url` | 立即用 ZCode 内置浏览器打开 URL；只有浏览器不可用时才展示同一个可点击链接。 |
 | `kimi-code` | `terminal` | `url` | 使用标准 CLI 非 JSON 终端二维码和链接。 |
 | `openclaw` | 必须显式 | Telegram 返回 `url,qr_image_url,agent_action`；其他入口返回 `url,qr_image_url` | Telegram 执行原生 `message` action；其他入口直接展示图片和链接。 |
 

package/docs/cli-reference/commands/cart/add.md

@@ -85,4 +85,4 @@ Quote 模式返回：
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种类型都写入真实 Agent Type。默认 Host 分别是 `codex`、`terminal`、`claude-code`、`terminal`、`plain-chat`。业务输出合同相同；此命令本身不显示二维码。
+所有正式支持的 Local Agent Type 都写入真实 Agent Type，并使用 Agent Type reference 声明的默认 Host。业务输出合同相同；此命令本身不显示二维码。

package/docs/cli-reference/commands/cart/clear.md

@@ -52,4 +52,4 @@ itpay cart clear [--local] [--json]
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 行为相同。
+所有正式支持的 Local Agent Type 行为相同。

package/docs/cli-reference/commands/cart/index.md

@@ -29,4 +29,4 @@ itpay cart --help
 
 ## Agent Type / Host
 
-Cart 事实在 `codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 下相同；`add` 创建 client context 时记录真实 Agent Type 和 Host。
+Cart 事实在所有正式支持的 Local Agent Type 下相同；`add` 创建 client context 时记录真实 Agent Type 和 Host。

package/docs/cli-reference/commands/cart/next.md

@@ -70,4 +70,4 @@ itpay buy --cart <cart_id> --json
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 的业务字段、instruction 和 next 相同。本命令不产生二维码或 Host handoff。
+所有正式支持的 Local Agent Type 的业务字段、instruction 和 next 相同。本命令不产生二维码或 Host handoff。

package/docs/cli-reference/commands/cart/remove.md

@@ -52,4 +52,4 @@ quote/checkout 已锁定时返回 `cart_item_locked`，要求继续已有 Checko
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 行为相同。
+所有正式支持的 Local Agent Type 行为相同。

package/docs/cli-reference/commands/cart/show.md

@@ -64,4 +64,4 @@ canonical 输出不得包含 Catalog variant/offer、line input、Service quote
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 行为相同。
+所有正式支持的 Local Agent Type 行为相同。

package/docs/cli-reference/commands/catalog/index.md

@@ -25,4 +25,4 @@ itpay catalog --help
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种支持类型的目录事实完全相同。instruction 可按 Agent Type 调整措辞，但不得改变服务排序、价格或可用能力。
+所有正式支持的 Local Agent Type 的目录事实完全相同。instruction 可按 Agent Type 调整措辞，但不得改变服务排序、价格或可用能力。

package/docs/cli-reference/commands/catalog/list.md

@@ -44,4 +44,4 @@ itpay catalog list [--json]
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 使用同一产品内容；只允许排版不同。
+所有正式支持的 Local Agent Type 使用同一产品内容；只允许排版不同。

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

@@ -76,6 +76,7 @@ token 缺失或不匹配时使用本机句柄恢复。只有请求的 Checkout
 | `claude-code-desktop` | `url, qr_local_path, markdown`；原样发送 Markdown。 |
 | `claude-code-cli` | `url`；普通文本模式渲染终端二维码。 |
 | `workbuddy` | 返回 `url,agent_action`；原样执行一次 `present_files(files=[url])` 打开完整渲染的 HTML Card Link，不生成本地文件。 |
+| `zcode` | 返回 `url`；立即用 ZCode 内置浏览器打开，不只粘贴文字链接，也不生成或重建二维码文件。 |
 | `kimi-code` | `url`；普通文本模式渲染标准终端二维码。 |
 | `openclaw` | Telegram 为 `url,qr_image_url,agent_action`；instruction 强制原样执行 action。`📋 已授权给我读` callback 触发同一 Checkout 查询，再由 Backend 决定是否进入 grant 读取；其他显式 Host 为 `url,qr_image_url`。 |
 

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

@@ -14,6 +14,14 @@ itpay --agent-type <agent_type> device recover --confirm-backend-reset --json
 
 命令只作用于当前官方 Backend 的 Device registration，并保留本地 Ed25519 私钥、Cart 和业务资源。默认是 `https://app.itpay.ai`；显式测试可使用准确的 `ITPAY_BACKEND_URL=https://dev.itpay.ai`。该命令不访问 Backend、不自动创建新身份；返回的只读 `services list` 会保留同一 Backend，是重新登记入口。
 
+同一台电脑上的多个 Local Agent Type 共享本地 Device key，但各自使用独立 Agent
+Instance。CLI 只在原子更新 Device state 时使用短期本地锁；释放和 stale recovery
+通过 rename 完成，不依赖 Host 删除文件，因此 WorkBuddy 等 sandbox 的
+safe-delete/trash shim 不应阻断正常命令。该锁不在 Backend，不会让另一台电脑或
+另一个 Buyer 等待。遇到本地锁错误时不得删除 `~/.itpay-v3/device`、切换 Agent
+Type 或执行 `device recover`；应保留身份并重试原命令一次，持续失败时报告
+`device_state_unwritable` 或 lock timeout。
+
 缺少确认参数返回 `backend_reset_confirmation_required`。普通 session 失效由 CLI 自动续期；revoked、quota、权限或未知 Backend 故障不得使用本命令。所有 Agent Type 使用相同输入和输出合同。
 
 ## 参数

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

@@ -27,4 +27,4 @@ itpay docs --help
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 使用同一文档源；topic 内容可以包含各类型专属 section。
+所有正式支持的 Local Agent Type 使用同一文档源；topic 内容可以包含各类型专属 section。完整类型列表以 `itpay install --json` 和 Agent Type reference 为准。

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

@@ -50,4 +50,4 @@ itpay docs show <topic> --json
 
 ## Agent Type / Host
 
-七种正式 Agent Type 返回相同结果。本命令没有 Host 渲染、设备登记或本地业务状态写入。
+所有正式 Agent Type 返回相同结果。本命令没有 Host 渲染、设备登记或本地业务状态写入。

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

@@ -68,4 +68,4 @@ itpay docs search <query> [--json]
 
 ## Agent Type / Host
 
-七种正式 Agent Type 行为相同。本命令不产生 Host handoff。
+所有正式 Agent Type 行为相同。本命令不产生 Host handoff。

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

@@ -67,4 +67,4 @@ topic 不存在返回 `doc_not_found`：
 
 ## Agent Type / Host
 
-七种正式 Agent Type 使用同一 topic。topic 若包含多种 Host 指导，Agent 只采用与自身 Agent Type 和当前 Host 匹配的部分。
+所有正式 Agent Type 使用同一 topic。topic 若包含多种 Host 指导，Agent 只采用与自身 Agent Type 和当前 Host 匹配的部分。

package/docs/cli-reference/commands/feedback/submit.md

@@ -73,6 +73,9 @@ Markdown：
 
 没有用户评论时省略 Summary，但仍保存 Context。只写用户明确内容和已知安全上下文；禁止 Token、Session、联系方式、内部身份、
 Provider 响应、Vault payload、完整命令输出、stack trace 或环境变量。
+CLI 不读取或上传 Host 对话、WorkBuddy/ZCode sandbox 日志或其他本地 Agent
+记录。用户自愿提供本地证据时，Agent 也只能提炼与本单有关的安全摘要，不能把原始
+日志作为 Feedback note 上传。
 
 ## 成功 JSON
 

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

@@ -18,10 +18,10 @@ itpay install [target] [--json]
 
 | 参数 | 必填 | 说明 |
 | --- | --- | --- |
-| `target` | 否 | 七种正式 Agent Type 之一；省略或传 `list` 时列出全部。Host 名称不是合法 target。 |
+| `target` | 否 | 八种正式 Agent Type 之一；省略或传 `list` 时列出全部。Host 名称不是合法 target。 |
 | `--json` | 否 | 返回标准命令 envelope；推荐 Agent 使用。 |
 
-正式 target：`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw`。
+正式 target：`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`zcode`、`kimi-code`、`openclaw`。
 
 ## 指定 Agent Type 输出
 
@@ -77,7 +77,7 @@ OpenClaw 额外明确没有默认入口：
 
 ## 列表输出
 
-省略 target 或传 `list` 时返回七组运行时定义，不重复每种类型的完整 instruction：
+省略 target 或传 `list` 时返回八组运行时定义，不重复每种类型的完整 instruction：
 
 ```json
 {
@@ -89,6 +89,7 @@ OpenClaw 额外明确没有默认入口：
       { "agent_type": "claude-code-desktop", "default_host": "claude-code" },
       { "agent_type": "claude-code-cli", "default_host": "terminal" },
       { "agent_type": "workbuddy", "default_host": "plain-chat" },
+      { "agent_type": "zcode", "default_host": "plain-chat" },
       { "agent_type": "kimi-code", "default_host": "terminal" },
       {
         "agent_type": "openclaw",
@@ -120,6 +121,7 @@ OpenClaw 额外明确没有默认入口：
 | `claude-code-desktop` | `claude-code` | 桌面对话必须实际展示二维码和付款链接。 |
 | `claude-code-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
 | `workbuddy` | `plain-chat` | 会持久化 `~/.itpay-v3` 的 Bash 调用先设 Shell 工具参数 `dangerouslyDisableSandbox=true`；拒绝权限时停止。Checkout 原样执行返回的 `present_files` action，打开渲染后的 Card Link。 |
+| `zcode` | `plain-chat` | Checkout 或授权返回后立即用 ZCode 内置浏览器打开 `handoff.url`；只有浏览器不可用时才展示同一个可点击链接。 |
 | `kimi-code` | `terminal` | 使用标准 CLI 流程和终端展示，不增加 Kimi 专属命令。 |
 | `openclaw` | 无 | 必须显式提供当前入口；Telegram 使用原生 action，其他入口展示标准二维码和链接。 |
 
@@ -138,7 +140,7 @@ OpenClaw 额外明确没有默认入口：
     "code": "unsupported_agent_type",
     "message": "unsupported install target: codex"
   },
-  "instruction": "target 只接受：codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy, kimi-code, openclaw。",
+  "instruction": "target 只接受：codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy, zcode, kimi-code, openclaw。",
   "next": null,
   "recovery": [
     {

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

@@ -86,4 +86,4 @@ Checkout 句柄返回：
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 的状态、instruction 和下一步完全相同。本命令不产生二维码或 Host handoff。
+所有正式支持的 Local Agent Type 的状态、instruction 和下一步完全相同。本命令不产生二维码或 Host handoff。

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

@@ -91,4 +91,4 @@ itpay services list --json
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 返回完全相同的订单事实、instruction 和 next。`order` 是状态读取命令，不构造二维码、Markdown handoff 或 Host renderer 数据。
+所有正式支持的 Local Agent Type 返回完全相同的订单事实、instruction 和 next。`order` 是状态读取命令，不构造二维码、Markdown handoff 或 Host renderer 数据。

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

@@ -103,6 +103,7 @@ API 安全合同要求后端验证 display token 是该 Checkout 当前有效的
 | `claude-code-desktop` | `claude-code` | 把安全 handoff 发到当前桌面对话。 |
 | `claude-code-cli` | `terminal` | 只在用户可见终端展示渠道动作。 |
 | `workbuddy` | `plain-chat` | 受控逃生入口返回 `handoff.url` 和可原样执行的 `present_files` action；打开一次后停止，不立即查询或创建替代付款。 |
+| `zcode` | `plain-chat` | 受控逃生入口返回 `handoff.url`；同时存在渠道动作时优先使用浏览器可打开的 `qr_image_url`，只有它缺失时才回退到 `mobile_wallet_url`。立即用内置浏览器打开并停止，浏览器不可用时才展示同一个链接。 |
 | `kimi-code` | `terminal` | 使用标准 CLI 终端展示渠道动作。 |
 | `openclaw` | 必须显式提供 | 按显式 Host 返回安全渠道动作；IM Host 仍要求真实 target。 |
 

package/docs/cli-reference/commands/refund/cancel.md

@@ -61,4 +61,4 @@ itpay refund cancel <refund_request_id> [--reason <reason>] [--json]
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 的业务字段、instruction 和 recovery 相同；该命令没有二维码或宿主渲染差异。
+所有正式支持的 Local Agent Type 的业务字段、instruction 和 recovery 相同；该命令没有二维码或宿主渲染差异。

package/docs/cli-reference/commands/refund/create.md

@@ -84,4 +84,4 @@ CLI 使用 Device Authority 或已有 Buyer bearer，并用订单+原因生成
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 使用相同 Device Authority、退款政策和输出。未绑定订单时不得改用新 Device ID、Buyer ID 或开发者权限绕过 Owner 鉴权。
+所有正式支持的 Local Agent Type 使用相同 Device Authority、退款政策和输出。未绑定订单时不得改用新 Device ID、Buyer ID 或开发者权限绕过 Owner 鉴权。

package/docs/cli-reference/commands/refund/get.md

@@ -64,4 +64,4 @@ CLI 不因为退款终态自行修改订单或 grant。
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 返回完全相同的退款事实、instruction 和 next。Host 不改变 Refund Owner 状态或访问锁。
+所有正式支持的 Local Agent Type 返回完全相同的退款事实、instruction 和 next。Host 不改变 Refund Owner 状态或访问锁。

package/docs/cli-reference/commands/refund/index.md

@@ -40,4 +40,4 @@ itpay refund --help
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种类型使用同一签名 Device Authority 和退款状态机；Host 不影响退款资格。
+所有正式支持的 Local Agent Type 使用同一签名 Device Authority 和退款状态机；Host 不影响退款资格。

package/docs/cli-reference/commands/refund/list.md

@@ -67,4 +67,4 @@ itpay refund list --order <order_id> [--json]
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 的业务字段、instruction 和 next 完全相同；本命令没有 Host 渲染差异。
+所有正式支持的 Local Agent Type 的业务字段、instruction 和 next 完全相同；本命令没有 Host 渲染差异。

package/docs/cli-reference/commands/refund/watch.md

@@ -72,4 +72,4 @@ Timeout 只表示本次 CLI 等待结束，不表示退款失败：
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 返回相同退款事实。Desktop 不会把每次无变化轮询发送到用户对话；Host 不改变 timeout 或退款状态。
+所有正式支持的 Local Agent Type 返回相同退款事实。Desktop 不会把每次无变化轮询发送到用户对话；Host 不改变 timeout 或退款状态。

package/docs/cli-reference/commands/services/action.md

@@ -47,4 +47,4 @@ rank 不存在、属于旧结果集或其他 Execution、action 不允许、stat
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 行为相同。需要人确认时 instruction 必须明确“先询问用户”，不能因 Desktop Host 自动代替用户选择。
+所有正式支持的 Local Agent Type 行为相同。需要人确认时 instruction 必须明确“先询问用户”，不能因 Desktop Host 自动代替用户选择。

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

@@ -83,6 +83,7 @@ itpay services checkout <service_execution_id> --resume
 | `claude-code-desktop` | `handoff={url,qr_local_path,markdown}`；把 `handoff.markdown` 原样发送到当前桌面对话。 |
 | `claude-code-cli` | `handoff={url}`；普通文本模式在用户可见终端渲染二维码。 |
 | `workbuddy` | `handoff={url,agent_action}`；原样执行一次 `present_files(files=[url])` 打开完整渲染的 HTML Card Link，然后停止；不得检查或生成本地文件。 |
+| `zcode` | `handoff={url}`；立即用 ZCode 内置浏览器打开，然后停止；只有浏览器不可用时才展示同一个可点击链接。 |
 | `kimi-code` | `handoff={url}`；复用标准 CLI 终端展示。 |
 | `openclaw` | 必须显式传 Host；Telegram 还必须传 OpenClaw 原生 Target，并返回必须原样执行的 `message` action；其他入口返回标准 `url,qr_image_url`。 |
 
@@ -92,6 +93,12 @@ WorkBuddy 的准确 instruction 语义必须完整包含：
 Backend 尚未确认付款。立即严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行一次，在右侧打开 handoff.url；确认工具调用成功后说明金额，然后停止等待。若工具失败，只发送原始 handoff.url，报告未自动打开并停止。不要用 present_files 打开本地文件或二维码 PNG，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。
 ```
 
+ZCode 的准确 instruction 语义必须完整包含：
+
+```text
+Backend 尚未确认付款。立即用 ZCode 内置浏览器打开 handoff.url，让用户完成付款；确认已发起打开后说明金额，然后停止等待。不要只粘贴文字链接，不要下载、解析或重建二维码，不要创建新 Checkout、Payment Intent 或 Execution。只有内置浏览器明确不可用时，才展示同一个可点击 handoff.url。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。
+```
+
 `--locale` 默认 `zh-CN`，可显式使用 `--locale en`。语言只影响 Card 渲染，不改变 Checkout、付款或恢复状态。
 
 OpenClaw 的 Host/Target 校验必须发生在读取 execution 后、创建 Checkout 前；校验失败不能调用 Checkout 创建接口。Telegram `agent_action.arguments.presentation` 只使用 `blocks.buttons`，其中 `📱 手机点这儿支付` 使用扁平 `url`，`📋 已授权给我读` 使用 `value=itp:grant_confirmed:<checkout_id>`。准确 instruction 必须要求 Agent 立即用原生 `message` tool 原样执行 `handoff.agent_action`，不得改写 Presentation、换工具或用普通回复冒充按钮已发送。收到该 callback 表示用户声明已在收银台授权读取；Agent 立即执行 `next.command` 查询同一 Checkout，再只按 Backend 返回的 `next.command` 进入同一 Execution grant 流程。callback 不包含 display token，也不证明付款或 grant active；Backend 未返回 `grant_active` 前不得读取结果。

package/docs/cli-reference/commands/services/events.md

@@ -72,4 +72,4 @@ CLI 只投影：`sequence`、`type`、`status`、`phase`、可选 `capability_id
 
 ## Agent Type / Host
 
-七种正式 Agent Type 的事件字段、鉴权和 redaction 完全相同；Host 不影响可见性，也不产生 handoff。
+所有正式 Agent Type 的事件字段、鉴权和 redaction 完全相同；Host 不影响可见性，也不产生 handoff。

package/docs/cli-reference/commands/services/get.md

@@ -65,4 +65,4 @@ execution 不存在或不属于当前身份时保留不透明 `not_found`，只
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 的状态、timeline、instruction 和 next 相同。本命令没有二维码或 Host handoff。
+所有正式支持的 Local Agent Type 的状态、timeline、instruction 和 next 相同。本命令没有二维码或 Host handoff。

package/docs/cli-reference/commands/services/index.md

@@ -44,4 +44,4 @@ itpay services --help
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 共享状态机；Agent Type 只影响身份归属和 Host instruction，不允许影响 quota 规则或服务能力。
+所有正式支持的 Local Agent Type 共享状态机；Agent Type 只影响身份归属和 Host instruction，不允许影响 quota 规则或服务能力。

package/docs/cli-reference/commands/services/invoke.md

@@ -152,4 +152,4 @@ Provider 已收到请求时，Backend 返回同一 Execution 的权威调用和
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 的 safe result 一致。instruction 可以适配对话表述，但不得隐藏 quota、价格或 schema 错误。
+所有正式支持的 Local Agent Type 的 safe result 一致。instruction 可以适配对话表述，但不得隐藏 quota、价格或 schema 错误。

package/docs/cli-reference/commands/services/list.md

@@ -60,4 +60,4 @@ itpay services list [--limit <number>] [--json]
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 返回相同列表格式；Agent instance 权限决定可见范围。本命令没有 Host handoff。
+所有正式支持的 Local Agent Type 返回相同列表格式；Agent instance 权限决定可见范围。本命令没有 Host handoff。

package/docs/cli-reference/commands/services/next.md

@@ -209,4 +209,4 @@ itpay services get <service_execution_id> --json
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 返回完全相同的状态、safe payload、instruction 和 next。本命令不渲染二维码，也不包含 Host handoff。
+所有正式支持的 Local Agent Type 返回完全相同的状态、safe payload、instruction 和 next。本命令不渲染二维码，也不包含 Host handoff。

package/docs/cli-reference/commands/services/quote.md

@@ -62,4 +62,4 @@ itpay services quote <service_execution_id> --capability <capability_id>
 
 ## Agent Type / Host
 
-`codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 七种 Agent Type 返回相同 Quote 事实、instruction 和 next。本命令不显示二维码；Agent Type 只作为设备与审计上下文，不改变价格或候选规则。
+所有正式支持的 Local Agent Type 返回相同 Quote 事实、instruction 和 next。本命令不显示二维码；Agent Type 只作为设备与审计上下文，不改变价格或候选规则。

package/docs/cli-reference/commands/services/read-result.md

@@ -97,4 +97,4 @@ itpay services next <id> --json
 
 ## Agent Type / Host
 
-同一 Buyer account 下已登记的 `codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy`、`kimi-code`、`openclaw` 可按政策领取同一订单授权；每个类型仍需自己的有效 Device Authority。七种类型返回相同字段、TTL 和错误，不因 Host 扩大 grant scope。
+同一 Buyer account 下已登记的正式 Local Agent Type 可按政策领取同一订单授权；每个类型仍需自己的有效 Device Authority。所有类型返回相同字段、TTL 和错误，不因 Host 扩大 grant scope。

package/docs/cli-reference/commands/vault/access.md

@@ -52,9 +52,12 @@ Agent不得提取、单独输出、记录或重建其中的 credential；但不
 | `codex-cli / terminal` | `url`；文本模式同时渲染终端二维码 |
 | `claude-code-cli / terminal` | `url`；文本模式同时渲染终端二维码 |
 | `workbuddy / plain-chat` | `url, agent_action` |
+| `zcode / plain-chat` | `url`；立即用内置浏览器打开，浏览器不可用时才展示可点击链接 |
 | `kimi-code / terminal` | `url`；文本模式同时渲染终端二维码 |
 | `openclaw / telegram` | `url, qr_image_url, agent_action` |
 | `openclaw / other` | `url, qr_image_url` |
 
 桌面二维码下载失败时保留 `handoff.url`，instruction 必须要求如实说明图片
 未显示并发送同一个 URL；不得创建替代请求。
+
+ZCode 不接收图片路径或二维码 URL。instruction 必须要求 Agent立即用内置浏览器打开完整 `handoff.url`，然后停止等待；不得只粘贴文字链接或重建二维码。仅当内置浏览器明确不可用时才展示同一个可点击链接。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.0.35",
+  "version": "2.0.37",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {
@@ -30,6 +30,7 @@
     "claude-code",
     "codex",
     "openclaw",
+    "zcode",
     "trae"
   ],
   "license": "MIT",

package/skills/itpay/SKILL.md

@@ -51,6 +51,11 @@ itpay docs search <keyword> --json
 
 The current Backend response always overrides general documentation.
 
+When a handoff returns an official URL, open it yourself on the current
+platform whenever possible. Only show the same clickable URL when no browser
+or native action is available; never ask the human to run a command or rebuild
+a QR code.
+
 ## Serve The Human
 
 - Ask the human only to choose, authorize, pay, provide required contact