@itpay/cli 2.0.10 → 2.0.11

package/README.md

@@ -11,7 +11,7 @@ itpay --agent-type codex-desktop readyz --json
 # follow next.command: typed skill show, then catalog list
 ```
 
-The default API is temporarily `https://dev.itpay.ai` during the 2.0.10 beta. Set `ITPAY_BACKEND_URL` only for an intentional override.
+The default API is temporarily `https://dev.itpay.ai` during the 2.0.11 beta. Set `ITPAY_BACKEND_URL` only for an intentional override.
 
 ## Output Contract
 

package/dist/src/commands/buy.js

@@ -16,6 +16,8 @@ import { ensureIdeImageAttach } from "../render/ide.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 { qualifyItPayCommand } from "../state/agent_type.js";
 export async function runBuy(backend, config, options) {
     const err = validateContext(options.host, options.target);
     if (err) {
@@ -67,6 +69,7 @@ export async function runBuy(backend, config, options) {
     const checkoutID = checkout.checkout.checkout_id;
     const displayToken = checkout.display_token;
     const checkoutURL = tokenizedCheckoutURL(checkout.checkout_url, displayToken, checkout.qr_payload);
+    const qrPNGURL = checkout.qr_png_url ? absolutePublicURL(config.baseURL, checkout.qr_png_url) : undefined;
     const orderItems = cart.items.map((item) => ({
         title: item.title,
         quantity: item.quantity,
@@ -108,21 +111,24 @@ export async function runBuy(backend, config, options) {
         nextAction: checkout.checkout.next_action,
         orderItems,
         orderCurrency: checkout.checkout.currency,
+        ...(options.agentType ? { agentType: options.agentType } : {}),
     };
-    if (checkout.qr_png_url)
-        planInput.qrPNGURL = checkout.qr_png_url;
+    if (qrPNGURL)
+        planInput.qrPNGURL = qrPNGURL;
     if (paymentIntent) {
         planInput.paymentIntentID = paymentIntent.payment_intent_id;
         planInput.paymentMethod = paymentIntent.payment_method_type;
         planInput.paymentStatus = paymentIntent.status;
     }
     const plan = buildCheckoutQRPlan(planInput);
-    // --- Download brand QR for IDE image attach (every output mode) ---
-    await ensureIdeImageAttach(plan, {
-        enabled: config.ideImageAttach,
-        ...(config.baseURL ? { baseURL: config.baseURL } : {}),
-        ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
-    });
+    // --- Download a local QR only for desktop Markdown hosts ---
+    if (shouldPrepareLocalCheckoutImage(platformKeyForHost(options.host))) {
+        await ensureIdeImageAttach(plan, {
+            enabled: config.ideImageAttach,
+            ...(config.baseURL ? { baseURL: config.baseURL } : {}),
+            ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+        });
+    }
     // --- Output ---
     if (options.jsonOutput) {
         const envelope = buildBuyEnvelope({
@@ -132,8 +138,9 @@ export async function runBuy(backend, config, options) {
             displayToken,
             plan,
             waitStatus,
-            ...(checkout.qr_png_url ? { qrPNGURL: checkout.qr_png_url } : {}),
+            ...(qrPNGURL ? { qrPNGURL } : {}),
             ...(paymentIntent ? { paymentIntent } : {}),
+            ...(options.agentType ? { agentType: options.agentType } : {}),
         });
         writeCommandEnvelope(envelope, { jsonOutput: true, ...(options.output ? { output: options.output } : {}) });
         return {
@@ -166,20 +173,11 @@ export async function runBuy(backend, config, options) {
 function buildBuyEnvelope(input) {
     const verified = input.waitStatus === "verified";
     const platform = platformKeyForHost(input.plan.host);
-    const handoff = { url: input.checkoutURL };
-    if (input.plan.ideImageAttach?.status === "downloaded" && input.plan.ideImageAttach.localPath) {
-        handoff.qr_local_path = input.plan.ideImageAttach.localPath;
-    }
-    if (platform === "markdown") {
-        handoff.markdown = buildAgentChatHandoff(input.plan).markdown;
-    }
-    else if (platform === "plain_chat" && input.qrPNGURL) {
-        handoff.qr_image_url = input.qrPNGURL;
-    }
+    const amount = formatMoney(input.cart.amount_minor, input.cart.currency);
     const result = {
         checkout_id: input.checkoutID,
         payment: verified ? "verified" : "pending",
-        amount: formatMoney(input.cart.amount_minor, input.cart.currency),
+        amount,
         item_count: input.cart.items.length,
         ...(input.paymentIntent ? {
             payment_intent_id: input.paymentIntent.payment_intent_id,
@@ -196,22 +194,26 @@ function buildBuyEnvelope(input) {
             recovery: [],
         };
     }
+    const presentationHandoff = buildCheckoutHandoff({
+        platform,
+        url: input.checkoutURL,
+        amount,
+        ...(input.agentType ? { agentType: input.agentType } : {}),
+        ...(input.qrPNGURL ? { qrImageURL: input.qrPNGURL } : {}),
+        ...(input.plan.ideImageAttach?.status === "downloaded" && input.plan.ideImageAttach.localPath
+            ? { localPath: input.plan.ideImageAttach.localPath }
+            : {}),
+        ...(platform === "markdown" ? { markdown: buildAgentChatHandoff(input.plan).markdown } : {}),
+    });
     return {
         status: "human_checkout_required",
         result,
-        handoff,
-        instruction: buyHandoffInstruction(platform),
+        handoff: presentationHandoff.handoff,
+        instruction: presentationHandoff.instruction,
         next: { command: `itpay checkout --id ${input.checkoutID} --token ${input.displayToken} --json`, reason: "稍后查询同一笔 Checkout 状态" },
         recovery: [],
     };
 }
-function buyHandoffInstruction(platform) {
-    if (platform === "markdown")
-        return "把 handoff.markdown 原样发送到当前桌面对话；二维码和链接可见后等待用户操作，不要创建新 Checkout。";
-    if (platform === "terminal")
-        return "在用户可见终端展示 handoff 中的付款入口，然后等待用户操作；不要创建新 Checkout。";
-    return "把 handoff.url 和可用二维码附件发送给用户，然后等待用户操作；不要创建新 Checkout。";
-}
 // --- SSE wait for payment verification ---
 async function waitForPaymentSSE(backend, checkoutID, displayToken, timeoutSec) {
     return new Promise((resolve) => {
@@ -237,7 +239,7 @@ async function waitForPaymentSSE(backend, checkoutID, displayToken, timeoutSec)
 export function buildCheckoutQRPlan(input) {
     const summary = `Scan the QR or open ${input.checkoutURL} to start the human checkout flow.`;
     const isPayment = input.paymentIntentID != null;
-    const afterCommand = `itpay checkout --id ${input.checkoutID} --token ${input.displayToken} --json`;
+    const afterCommand = qualifyItPayCommand(`itpay checkout --id ${input.checkoutID} --token ${input.displayToken} --json`, input.agentType);
     const platform = {
         text: summary,
         links: [
@@ -301,3 +303,11 @@ function tokenizedCheckoutURL(checkoutURL, displayToken, qrPayload) {
         return `${checkoutURL}${separator}display_token=${encodeURIComponent(displayToken)}`;
     }
 }
+function absolutePublicURL(baseURL, value) {
+    try {
+        return new URL(value, baseURL.endsWith("/") ? baseURL : `${baseURL}/`).toString();
+    }
+    catch {
+        return value;
+    }
+}

package/dist/src/commands/checkout.js

@@ -6,6 +6,7 @@ import { platformKeyForHost } from "../render/plan.js";
 import { renderTerminalQR } from "../render/qr.js";
 import { DEFAULT_BASE_URL } from "../state/config.js";
 import { buildCheckoutQRPlan } from "./buy.js";
+import { buildCheckoutHandoff, shouldPrepareLocalCheckoutImage } from "./checkout_handoff.js";
 import { writeCommandEnvelope } from "./guidance.js";
 export async function runCheckoutPresentation(backend, options) {
     const presentation = await backend.getCheckoutPresentation(options.checkoutID, options.displayToken);
@@ -37,11 +38,15 @@ export async function runCheckoutPresentation(backend, options) {
             currency: item.currency,
         })),
         orderCurrency: presentation.checkout.currency,
+        ...(options.agentType ? { agentType: options.agentType } : {}),
     });
-    await ensureIdeImageAttach(plan, {
-        ...(options.baseURL ? { baseURL: options.baseURL } : {}),
-    });
-    const envelope = pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand);
+    const platform = platformKeyForHost(host);
+    if (shouldPrepareLocalCheckoutImage(platform)) {
+        await ensureIdeImageAttach(plan, {
+            ...(options.baseURL ? { baseURL: options.baseURL } : {}),
+        });
+    }
+    const envelope = pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand, options.agentType);
     const plainResult = checkoutPlainResult(envelope.result);
     if (!options.jsonOutput && platformKeyForHost(host) === "terminal") {
         plainResult.push("qr:", await renderTerminalQR(checkoutURL, "terminal"));
@@ -52,19 +57,20 @@ export async function runCheckoutPresentation(backend, options) {
         plainResult,
     });
 }
-function pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand) {
+function pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand, agentType) {
     const platform = platformKeyForHost(plan.host);
-    const handoff = { url: checkoutURL };
-    if (plan.ideImageAttach?.status === "downloaded" && plan.ideImageAttach.localPath) {
-        handoff.qr_local_path = plan.ideImageAttach.localPath;
-    }
-    if (platform === "markdown") {
-        handoff.markdown = buildAgentChatHandoff(plan).markdown;
-    }
-    else if (platform === "plain_chat" && plan.preferredQRSources[0]) {
-        handoff.qr_image_url = plan.preferredQRSources[0];
-    }
     const amount = formatMoney(presentation.checkout.amount_minor, presentation.checkout.currency);
+    const presentationHandoff = buildCheckoutHandoff({
+        platform,
+        url: checkoutURL,
+        amount,
+        ...(agentType ? { agentType } : {}),
+        ...(plan.preferredQRSources[0] ? { qrImageURL: plan.preferredQRSources[0] } : {}),
+        ...(plan.ideImageAttach?.status === "downloaded" && plan.ideImageAttach.localPath
+            ? { localPath: plan.ideImageAttach.localPath }
+            : {}),
+        ...(platform === "markdown" ? { markdown: buildAgentChatHandoff(plan).markdown } : {}),
+    });
     return {
         status: "human_checkout_required",
         result: {
@@ -72,8 +78,8 @@ function pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand) {
             payment: "pending",
             amount,
         },
-        handoff,
-        instruction: pendingInstruction(platform, amount),
+        handoff: presentationHandoff.handoff,
+        instruction: presentationHandoff.instruction,
         next: { command: nextCommand, reason: "稍后只查询同一 Checkout" },
         recovery: [],
     };
@@ -123,13 +129,6 @@ function checkoutNeedsHumanHandoff(status) {
 function checkoutPlainResult(result) {
     return Object.entries(result).map(([key, value]) => `${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
 }
-function pendingInstruction(platform, amount) {
-    if (platform === "markdown")
-        return `Backend 尚未确认付款。把 handoff.markdown 原样发送到当前桌面对话，确认二维码、链接和金额 ${amount} 已对用户可见，然后停止等待。不要创建新 Checkout、Execution 或 Payment Intent；稍后仍然只执行 next.command 查询这一笔 Checkout。`;
-    if (platform === "terminal")
-        return `Backend 尚未确认付款。在用户可见终端展示当前同一 Checkout 的二维码、链接和金额 ${amount}，然后停止等待。不要创建新 Checkout、Execution 或 Payment Intent；稍后仍然只执行 next.command 查询这一笔 Checkout。`;
-    return `Backend 尚未确认付款。把 handoff.url 作为可点击链接发送给用户，优先把 handoff.qr_local_path 作为图片附件发送，不能发送本地附件时使用 handoff.qr_image_url，并说明金额 ${amount}，然后停止等待。不要声称付款成功，不要创建新 Checkout、Execution 或 Payment Intent。稍后仍然只执行 next.command 查询这一笔 Checkout。`;
-}
 function formatMoney(amountMinor, currency) {
     return `${(amountMinor / 100).toFixed(2)} ${currency}`;
 }

package/dist/src/commands/checkout_handoff.js

@@ -0,0 +1,37 @@
+export function shouldPrepareLocalCheckoutImage(platform) {
+    return platform === "markdown";
+}
+export function isWorkBuddyPlainChat(agentType, platform) {
+    return agentType?.trim().toLowerCase() === "workbuddy" && platform === "plain_chat";
+}
+export function buildCheckoutHandoff(input) {
+    const handoff = { url: input.url };
+    if (input.platform === "markdown") {
+        if (input.localPath)
+            handoff.qr_local_path = input.localPath;
+        if (input.markdown)
+            handoff.markdown = input.markdown;
+    }
+    else if (input.platform === "plain_chat" && input.qrImageURL) {
+        handoff.qr_image_url = input.qrImageURL;
+    }
+    return {
+        handoff,
+        instruction: checkoutHandoffInstruction(input.agentType, input.platform, input.amount, Boolean(input.qrImageURL)),
+    };
+}
+function checkoutHandoffInstruction(agentType, platform, amount, hasQRImage) {
+    if (isWorkBuddyPlainChat(agentType, platform)) {
+        if (!hasQRImage) {
+            return `Backend 尚未确认付款，且本次没有返回可展示的二维码。向用户说明金额 ${amount} 并发送 handoff.url，然后停止等待。不要调用 present_files，不要检查本地文件，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+        }
+        return `Backend 尚未确认付款。读取 handoff.qr_image_url 的完整字符串，原样作为 files 数组唯一元素调用 present_files({ files: ["<完整 qr_image_url>"] })；确认右侧二维码预览已打开后，向用户说明金额 ${amount} 并发送 handoff.url，然后停止等待。如果 present_files 失败，只发送 handoff.url 并说明二维码预览未打开，然后停止。不要检查本地文件，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+    }
+    if (platform === "markdown") {
+        return `Backend 尚未确认付款。把 handoff.markdown 原样发送到当前桌面对话，确认二维码、付款链接和金额 ${amount} 均已实际对用户可见，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+    }
+    if (platform === "terminal") {
+        return `Backend 尚未确认付款。在用户可见终端展示当前 Checkout 的二维码、handoff.url 和金额 ${amount}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+    }
+    return `Backend 尚未确认付款。把 handoff.url 和可用的 handoff.qr_image_url 实际发送到当前会话，说明金额 ${amount}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+}

package/dist/src/commands/install.js

@@ -13,7 +13,7 @@ const INSTRUCTIONS = {
     "codex-cli": "在 Codex CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
     "claude-code-desktop": "在 Claude Code Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
     "claude-code-cli": "在 Claude Code CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
-    workbuddy: "在 WorkBuddy 中始终传这个 Agent Type；当前使用 plain-chat 交接，必须把链接和可用图片发到当前会话。",
+    workbuddy: "在 WorkBuddy 中始终传这个 Agent Type；Checkout 返回 qr_image_url 时，必须按当次 instruction 调用 present_files 在右侧打开二维码，不要检查本地二维码文件。",
 };
 export function runInstall(target, options = {}) {
     if (!target || target === "list") {

package/dist/src/commands/pay.js

@@ -2,6 +2,8 @@
 // Checkout page; this command exists for controlled integration recovery.
 import { formatMoney } from "../render/output.js";
 import { writeCommandEnvelope } from "./guidance.js";
+import { isWorkBuddyPlainChat } from "./checkout_handoff.js";
+import { platformKeyForHost } from "../render/plan.js";
 export async function runPay(backend, options) {
     const intent = await backend.createPaymentIntent(options.checkoutID, {
         payment_method_type: options.method,
@@ -23,16 +25,17 @@ function payEnvelope(intent, options) {
     if (!terminal && !verified && intent.action?.mobile_wallet_url)
         handoff.mobile_wallet_url = intent.action.mobile_wallet_url;
     const hasAction = Object.keys(handoff).length > 0;
+    const amount = formatMoney(intent.amount_minor, intent.currency);
     return {
         status: verified ? "payment_verified" : terminal ? "payment_unavailable" : hasAction ? "payment_action_ready" : "payment_action_pending",
         result: {
             checkout_id: options.checkoutID,
             payment_intent_id: intent.payment_intent_id,
             payment: verified ? "verified" : intent.status,
-            amount: formatMoney(intent.amount_minor, intent.currency),
+            amount,
         },
         ...(hasAction ? { handoff } : {}),
-        instruction: payInstruction(options.host, verified, terminal, hasAction),
+        instruction: payInstruction(options, verified, terminal, hasAction, Boolean(handoff.qr_image_url), Boolean(handoff.mobile_wallet_url), amount),
         next: {
             command: `itpay checkout --id ${options.checkoutID} --token ${options.displayToken} --json`,
             reason: verified ? "读取权威订单和履约状态" : "读取同一 Checkout 的权威付款状态",
@@ -40,16 +43,24 @@ function payEnvelope(intent, options) {
         recovery: [],
     };
 }
-function payInstruction(host, verified, terminal, hasAction) {
+function payInstruction(options, verified, terminal, hasAction, hasQR, hasWallet, amount) {
     if (verified)
         return "付款已确认；不要再次展示付款动作，继续读取同一 Checkout。";
     if (terminal)
         return "Payment Intent 已终止；不要自行创建替代付款，回到同一 Checkout 读取恢复方向。";
     if (!hasAction)
         return "Payment Intent 尚未返回可展示动作；不要猜测渠道链接，回到同一 Checkout 查询。";
-    if (host === "codex" || host === "claude-code")
-        return "这是受控逃生入口；把 handoff 中的二维码或钱包链接实际发到当前桌面对话，然后查询同一 Checkout。";
-    if (host === "terminal")
-        return "这是受控逃生入口；只在用户可见终端展示 handoff，然后查询同一 Checkout。";
-    return "这是受控逃生入口；把 handoff 中的二维码或钱包链接发送到当前会话，然后查询同一 Checkout。";
+    const platform = platformKeyForHost(options.host);
+    if (isWorkBuddyPlainChat(options.agentType, platform)) {
+        if (hasQR && hasWallet)
+            return `这是受控逃生入口。读取 handoff.qr_image_url 的完整字符串，原样作为 files 数组唯一元素调用 present_files({ files: ["<完整 qr_image_url>"] })；右侧预览打开后说明金额 ${amount}、发送 handoff.mobile_wallet_url 并停止等待。如果 present_files 失败，发送 handoff.qr_image_url 和 handoff.mobile_wallet_url 并说明二维码预览未打开，然后停止。不要立即查询、创建替代 Checkout 或 Payment Intent。`;
+        if (hasQR)
+            return `这是受控逃生入口。读取 handoff.qr_image_url 的完整字符串，原样作为 files 数组唯一元素调用 present_files({ files: ["<完整 qr_image_url>"] })；右侧预览打开后说明金额 ${amount} 并停止等待。如果 present_files 失败，把 handoff.qr_image_url 作为可点击链接发送给用户并说明二维码预览未打开，然后停止。不要立即查询、创建替代 Checkout 或 Payment Intent。`;
+        return `这是受控逃生入口。说明金额 ${amount}，把 handoff.mobile_wallet_url 作为可点击链接发送给用户，然后停止等待；不要立即查询、创建替代 Checkout 或 Payment Intent。`;
+    }
+    if (options.host === "codex" || options.host === "claude-code")
+        return "这是受控逃生入口；把 handoff 中的二维码或钱包链接实际发到当前桌面对话，然后停止等待。";
+    if (options.host === "terminal")
+        return "这是受控逃生入口；只在用户可见终端展示 handoff，然后停止等待。";
+    return "这是受控逃生入口；把 handoff 中的二维码或钱包链接发送到当前会话，然后停止等待。";
 }

package/dist/src/commands/services.js

@@ -1,6 +1,7 @@
 import { operationID } from "../state/config.js";
 import { dispatchRender } from "../render/index.js";
 import { ensureIdeImageAttach } from "../render/ide.js";
+import { buildCheckoutHandoff, shouldPrepareLocalCheckoutImage } from "./checkout_handoff.js";
 import { buildAgentChatHandoff } from "../render/markdown.js";
 import { platformKeyForHost } from "../render/plan.js";
 import { renderTerminalQR } from "../render/qr.js";
@@ -398,6 +399,7 @@ export async function runServicesCheckout(backend, config, serviceExecutionID, c
             currency: item.currency,
         })),
         orderCurrency: checkout.checkout.currency,
+        ...(options.agentType ? { agentType: options.agentType } : {}),
     });
     options.persistHandoff?.({
         serviceExecutionID,
@@ -419,12 +421,14 @@ export async function runServicesCheckout(backend, config, serviceExecutionID, c
         });
         return;
     }
-    await ensureIdeImageAttach(plan, {
-        enabled: config.ideImageAttach,
-        ...(config.baseURL ? { baseURL: config.baseURL } : {}),
-        ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
-    });
-    const envelope = buildServicesCheckoutEnvelope(response, checkoutURL, plan, config.baseURL);
+    if (shouldPrepareLocalCheckoutImage(platform)) {
+        await ensureIdeImageAttach(plan, {
+            enabled: config.ideImageAttach,
+            ...(config.baseURL ? { baseURL: config.baseURL } : {}),
+            ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+        });
+    }
+    const envelope = buildServicesCheckoutEnvelope(response, checkoutURL, plan, config.baseURL, options.agentType);
     const plainResult = [
         `service_execution_id: ${response.binding.service_execution_id}`,
         `checkout_id: ${checkoutID}`,
@@ -898,20 +902,21 @@ function parseValue(value) {
         return Number(value);
     return value;
 }
-function buildServicesCheckoutEnvelope(response, checkoutURL, plan, baseURL) {
+function buildServicesCheckoutEnvelope(response, checkoutURL, plan, baseURL, agentType) {
     const checkout = response.checkout;
     const platform = platformKeyForHost(plan.host);
-    const handoff = { url: checkoutURL };
-    if (plan.ideImageAttach?.status === "downloaded" && plan.ideImageAttach.localPath) {
-        handoff.qr_local_path = plan.ideImageAttach.localPath;
-    }
-    if (platform === "markdown") {
-        handoff.markdown = buildAgentChatHandoff(plan).markdown;
-    }
-    else if (platform === "plain_chat" && checkout.qr_png_url) {
-        handoff.qr_image_url = absolutePublicURL(baseURL, checkout.qr_png_url);
-    }
     const amount = formatMoney(checkout.checkout.amount_minor, checkout.checkout.currency);
+    const presentationHandoff = buildCheckoutHandoff({
+        platform,
+        url: checkoutURL,
+        amount,
+        ...(agentType ? { agentType } : {}),
+        ...(checkout.qr_png_url ? { qrImageURL: absolutePublicURL(baseURL, checkout.qr_png_url) } : {}),
+        ...(plan.ideImageAttach?.status === "downloaded" && plan.ideImageAttach.localPath
+            ? { localPath: plan.ideImageAttach.localPath }
+            : {}),
+        ...(platform === "markdown" ? { markdown: buildAgentChatHandoff(plan).markdown } : {}),
+    });
     return {
         status: "human_checkout_required",
         result: {
@@ -921,8 +926,8 @@ function buildServicesCheckoutEnvelope(response, checkoutURL, plan, baseURL) {
             locked_input: response.locked_input,
             amount,
         },
-        handoff,
-        instruction: checkoutInstruction(platform, amount),
+        handoff: presentationHandoff.handoff,
+        instruction: presentationHandoff.instruction,
         next: {
             command: `itpay checkout --id ${checkout.checkout.checkout_id} --token ${checkout.display_token} --json`,
             reason: "仅在用户完成付款操作或要求查询后，读取同一 Checkout 的权威状态",
@@ -933,13 +938,6 @@ function buildServicesCheckoutEnvelope(response, checkoutURL, plan, baseURL) {
 function checkoutCapabilityID(response, fallback = "") {
     return response.capability_id || fallback;
 }
-function checkoutInstruction(platform, amount) {
-    if (platform === "markdown")
-        return `把 handoff.markdown 原样发送到当前桌面对话，确认二维码、付款链接和金额 ${amount} 都已实际对用户可见，然后停止等待。不要立即执行 next.command，不要创建第二个 Checkout、Execution 或调用 pay；用户完成付款操作或要求查询后，只执行 next.command。`;
-    if (platform === "terminal")
-        return `在用户可见终端展示二维码、付款链接和金额 ${amount}，然后停止等待。不要立即执行 next.command，不要创建第二个 Checkout、Execution 或调用 pay；用户完成付款操作或要求查询后，只执行 next.command。`;
-    return `现在只做以下动作：1）把 handoff.url 作为可点击付款链接发送给用户；2）优先把 handoff.qr_local_path 作为图片附件发送，不能发送本地附件时使用 handoff.qr_image_url；3）明确告诉用户本次金额是 ${amount}；4）发送完成后停止并等待用户操作。不要立即执行 next.command，不要创建第二个 Checkout，不要新建 Execution，不要调用 pay。用户表示已经完成付款或要求查询状态后，只执行 next.command；用户的话本身不是付款成功证明。`;
-}
 function absolutePublicURL(baseURL, value) {
     try {
         return new URL(value, baseURL.endsWith("/") ? baseURL : `${baseURL}/`).toString();

package/dist/src/main.js

@@ -668,6 +668,7 @@ program
         const buyOptions = {
             cartSession: session,
             host,
+            ...(config.agentType ? { agentType: config.agentType } : {}),
             ...(options.cart ? { cartID: options.cart } : {}),
             ...(options.target ? { target: options.target } : {}),
             ...(options.ref ? { clientReferenceID: options.ref } : {}),
@@ -720,6 +721,7 @@ program
             checkoutID,
             displayToken,
             host,
+            ...(config.agentType ? { agentType: config.agentType } : {}),
             baseURL: config.baseURL,
             jsonOutput: Boolean(options.json),
         });
@@ -777,6 +779,7 @@ program
             displayToken,
             method: options.method,
             host,
+            ...(config.agentType ? { agentType: config.agentType } : {}),
             ...(options.refresh ? { refreshAction: true } : {}),
             ...(jsonOutput ? { jsonOutput: true } : {}),
         });
@@ -1098,6 +1101,7 @@ services
             lockedInput: parseKeyValueList(options.input),
             resume: Boolean(options.resume),
             host: withHost(options.host ?? defaultHostForAgentType(config.agentType)),
+            ...(config.agentType ? { agentType: config.agentType } : {}),
             ...(options.target ? { target: options.target } : {}),
             ...(options.qrFormat ? { qrFormat: options.qrFormat } : {}),
             ...(options.qrFile ? { qrFilePath: options.qrFile } : {}),

package/dist/src/render/index.js

@@ -1,7 +1,7 @@
 // Render plan entry point. `dispatch` runs the right renderer based
-// on the host. Every render path goes through `ensureIdeImageAttach`
-// so the brand QR gets downloaded to /tmp and the IDE attach is in
-// place before any renderer (or the JSON output) is produced.
+// on the host. Desktop Markdown and terminal renderers prepare a local
+// image; plain-chat and IM renderers keep the server URL and never create
+// an unused local attachment.
 import { renderTerminal } from "./terminal.js";
 import { renderMarkdown } from "./markdown.js";
 import { renderPlainChat } from "./plain_chat.js";
@@ -10,8 +10,10 @@ import { renderFeishu } from "./feishu.js";
 import { platformKeyForHost } from "./plan.js";
 import { ensureIdeImageAttach } from "./ide.js";
 export async function dispatchRender(plan, options) {
-    await ensureIdeImageAttach(plan, options);
     const key = platformKeyForHost(plan.host);
+    if (key === "markdown" || key === "terminal") {
+        await ensureIdeImageAttach(plan, options);
+    }
     switch (key) {
         case "terminal": {
             const terminalOptions = {

package/dist/src/state/config.js

@@ -10,7 +10,7 @@ import { declaredAgentType } from "./agent_type.js";
 import { DeviceAuthority } from "./device_authority.js";
 import { OperationJournal } from "./operation_journal.js";
 export const DEFAULT_BASE_URL = "https://dev.itpay.ai";
-export const CLI_VERSION = "2.0.10";
+export const CLI_VERSION = "2.0.11";
 export const API_CONTRACT_REVISION = "sha256:3779f5468ea2109d4134c4ace66258c9eabe82461fa86e83c84df8c860276886";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";

package/docs/agent/buyer/payment-flow.json

@@ -30,6 +30,7 @@
     "Use only handoff fields returned for the current Host and make them actually visible to the human.",
     "Before creating a single-Service Checkout, send the exact price confirmation requested by the current instruction, stop, and wait for explicit human agreement.",
     "After presenting a Checkout, stop. Run the returned next.command only after the human completes the payment action or asks to query the same Checkout.",
+    "For workbuddy with plain-chat, present the returned HTTPS QR with present_files exactly as instructed; presentation failure falls back only to handoff.url and never creates another payment resource.",
     "Payment is verified only by Backend Checkout or Order state, never by QR rendering, redirect, or user claim.",
     "A terminal payment state must never display another payment handoff."
   ],

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

@@ -32,7 +32,7 @@
     {
       "agent_type": "workbuddy",
       "default_host": "plain-chat",
-      "responsibility": "send the returned Checkout URL and any usable image attachment to the current chat"
+      "responsibility": "when handoff.qr_image_url exists, use its exact HTTPS value as the only files element in present_files; otherwise send the Checkout URL without calling present_files; show the amount and stop"
     }
   ],
   "commands": [
@@ -49,14 +49,16 @@
   ],
   "agent_rules": [
     "Agent Type is stable identity; Host is presentation and may be explicitly overridden.",
-    "A local QR path is not visible until the Agent attaches or renders that file on the human-facing surface.",
+    "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, call present_files exactly as the returned instruction says. If it fails, send only handoff.url, report that the preview did not open, and stop.",
     "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; the initial five Agent Types currently default to desktop, terminal, or plain-chat Hosts."
   ],
   "forbidden": [
     "Do not expose display tokens separately from the tokenized Checkout handoff.",
     "Do not print base64 images, mirror lists, renderer debug state, or provider QR URLs.",
-    "Do not claim a desktop attachment exists when only a filesystem path was printed."
+    "Do not claim a desktop attachment exists when only a filesystem path was printed.",
+    "Do not inspect, download, or regenerate a local QR file for WorkBuddy."
   ],
   "next_docs": [
     { "condition": "Need payment verification rules", "topic": "payment-flow" }

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

@@ -12,7 +12,7 @@
 | `codex-cli` | `terminal` | 在用户可见终端渲染二维码并输出付款链接；若用户不看该终端，要求改用正确 Host。 |
 | `claude-code-desktop` | `claude-code` | 返回桌面对话可展示的 Markdown 图片和付款链接，要求先展示再等待。 |
 | `claude-code-cli` | `terminal` | 在用户可见终端输出二维码和链接，不声称已在桌面对话展示。 |
-| `workbuddy` | `plain-chat` | 初期返回清晰付款链接和通用图片附件信息；原生卡片细节后续补充。 |
+| `workbuddy` | `plain-chat` | 只返回 HTTPS 二维码和付款链接；要求 Agent 用 `present_files` 在右侧预览打开二维码，不返回或检查本地图片路径。 |
 
 ## 通用规则
 
@@ -37,8 +37,9 @@
   },
   "handoff": {
     "url": "<checkout_url>",
-    "qr_local_path": "<optional_local_path>",
-    "markdown": "<optional_host_ready_markdown>"
+    "qr_local_path": "<desktop_optional_local_path>",
+    "qr_image_url": "<workbuddy_optional_absolute_https_png>",
+    "markdown": "<desktop_optional_host_ready_markdown>"
   },
   "instruction": "<agent-type-specific instruction>",
   "next": {
@@ -49,3 +50,15 @@
 ```
 
 只返回当前 Host 能使用的 `handoff` 字段，不返回镜像路径列表、渲染器内部状态或重复的 action 描述。
+
+准确字段集合：
+
+| Agent Type / Host | `handoff` keys |
+|---|---|
+| `codex-desktop / codex` | `url, qr_local_path, markdown` |
+| `claude-code-desktop / claude-code` | `url, qr_local_path, markdown` |
+| `codex-cli / terminal` | `url`；非 JSON 输出另外渲染终端二维码 |
+| `claude-code-cli / terminal` | `url`；非 JSON 输出另外渲染终端二维码 |
+| `workbuddy / plain-chat` | `url, qr_image_url` |
+
+WorkBuddy instruction 只在 `handoff.qr_image_url` 存在时要求读取其完整字符串并作为 `files` 数组唯一元素调用 `present_files`。如果该可选字段不存在，必须直接发送 `handoff.url`，明确不要调用 `present_files`。两种情况都要停止等待；不能检查本地文件、下载或重建二维码、调用 `pay` 或创建替代付款资源。显式 `--host` 仍覆盖默认展示方式，因此只有 `workbuddy + plain-chat` 使用该规则。

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

@@ -87,9 +87,9 @@ itpay buy \
   },
   "handoff": {
     "url": "<tokenized_checkout_url>",
-    "qr_local_path": "<optional_host_ready_file>",
+    "qr_local_path": "<desktop_optional_host_ready_file>",
     "markdown": "<desktop_only_optional_markdown>",
-    "qr_image_url": "<plain_chat_only_optional_url>"
+    "qr_image_url": "<workbuddy_only_absolute_https_png>"
   },
   "instruction": "<current_host_instruction>",
   "next": {
@@ -102,7 +102,7 @@ itpay buy \
 
 `handoff` 只保留当前 Host 可以使用的字段。不得返回二维码 base64、镜像路径数组、renderer 状态、原始后端 DTO 或重复的 `agent_action`。
 
-**Instruction：** 先把 handoff 中的付款入口实际展示给用户，再等待用户操作；不要创建第二个 Checkout。
+**Instruction：** 必须使用下方 Agent Type 表定义的展示动作；展示完成或失败后停止。只有用户明确表示已付款或要求查询时才执行 `next.command`，并以后端状态为准。
 
 ### `--pay` 已观察到付款事件
 
@@ -159,9 +159,9 @@ itpay buy \
 | Agent Type | 默认 Host | JSON handoff | Instruction |
 |---|---|---|---|
 | `codex-desktop` | `codex` | `url`、可用时 `qr_local_path` 和 `markdown` | 把 `handoff.markdown` 原样发到当前 Codex 对话，确认二维码和链接可见后等待。 |
-| `codex-cli` | `terminal` | `url`、可用时 `qr_local_path` | 非 JSON 模式在用户可见终端渲染二维码；始终保留付款链接。 |
+| `codex-cli` | `terminal` | `url` | 非 JSON 模式在用户可见终端渲染二维码；始终保留付款链接。 |
 | `claude-code-desktop` | `claude-code` | `url`、可用时 `qr_local_path` 和 `markdown` | 把 Markdown handoff 发到当前桌面对话，不能只输出本地路径。 |
-| `claude-code-cli` | `terminal` | `url`、可用时 `qr_local_path` | 在用户可见终端展示；不能声称桌面对话已收到图片。 |
-| `workbuddy` | `plain-chat` | `url`、可用时 `qr_local_path` 和 `qr_image_url` | 发送链接和可用图片附件，不虚构原生卡片。 |
+| `claude-code-cli` | `terminal` | `url` | 在用户可见终端展示；不能声称桌面对话已收到图片。 |
+| `workbuddy` | `plain-chat` | `url, qr_image_url?` | 有 `qr_image_url` 时调用 `present_files`；没有时只发送金额和 `url` 且不调用工具。两者都停止，不读取本地文件。 |
 
 显式 `--host` 可以覆盖展示方式，但不会改变 Agent Type、设备身份、金额、权限或交易状态。

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

@@ -24,8 +24,8 @@ itpay checkout [--id <checkout_id>] [--token <display_token>]
 {
   "status": "human_checkout_required",
   "result": { "checkout_id": "<checkout_id>", "payment": "pending", "amount": "<amount> <currency>" },
-  "handoff": { "url": "<checkout_url>", "qr_local_path": "<host_optional_path>", "markdown": "<desktop_optional_markdown>" },
-  "instruction": "Backend 尚未确认付款。把当前同一 Checkout 的付款入口重新展示给用户，然后停止等待。不要声称付款成功，不要创建新 Checkout、Execution 或 Payment Intent。稍后仍然只执行 next.command 查询这一笔 Checkout。",
+  "handoff": { "url": "<checkout_url>", "qr_local_path": "<desktop_optional_path>", "qr_image_url": "<workbuddy_optional_absolute_https_png>", "markdown": "<desktop_optional_markdown>" },
+  "instruction": "<exact_agent_type_instruction>",
   "next": { "command": "itpay checkout --id <checkout_id> --token <display_token> --json", "reason": "稍后只查询同一 Checkout" },
   "recovery": []
 }
@@ -66,9 +66,9 @@ token 缺失或不匹配时使用本机句柄恢复。只有请求的 Checkout
 | Agent Type | Handoff |
 |---|---|
 | `codex-desktop` | `url, qr_local_path, markdown`；原样发送 Markdown。 |
-| `codex-cli` | `url, qr_local_path`；普通文本模式渲染终端二维码。 |
+| `codex-cli` | `url`；普通文本模式渲染终端二维码。 |
 | `claude-code-desktop` | `url, qr_local_path, markdown`；原样发送 Markdown。 |
-| `claude-code-cli` | `url, qr_local_path`；普通文本模式渲染终端二维码。 |
-| `workbuddy` | `url, qr_local_path, qr_image_url`；发送链接和可用附件。 |
+| `claude-code-cli` | `url`；普通文本模式渲染终端二维码。 |
+| `workbuddy` | `url, qr_image_url?`；有二维码 URL 时按 `services checkout` 相同规则调用 `present_files`，没有时只发送 Checkout URL，不生成本地文件。 |
 
 完成、退款或失效状态下五种 Agent Type 都只返回同一状态和下一步，不渲染二维码。

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

@@ -83,7 +83,7 @@ itpay install [target] [--json]
 | `codex-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
 | `claude-code-desktop` | `claude-code` | 桌面对话必须实际展示二维码和付款链接。 |
 | `claude-code-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
-| `workbuddy` | `plain-chat` | 当前使用通用会话交接，必须发送链接和可用图片。 |
+| `workbuddy` | `plain-chat` | Checkout 返回 `qr_image_url` 时，按当次 instruction 调用 `present_files` 在右侧打开二维码；不检查本地二维码文件。 |
 
 显式 `--host` 可以在后续 commerce 命令覆盖默认 Host，但不会改变 Agent Type 或设备归属。
 

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

@@ -98,6 +98,6 @@ API 安全合同要求后端验证 display token 是该 Checkout 当前有效的
 | `codex-cli` | `terminal` | 只在用户可见终端展示渠道动作。 |
 | `claude-code-desktop` | `claude-code` | 把安全 handoff 发到当前桌面对话。 |
 | `claude-code-cli` | `terminal` | 只在用户可见终端展示渠道动作。 |
-| `workbuddy` | `plain-chat` | 把二维码或钱包链接发送到当前会话。 |
+| `workbuddy` | `plain-chat` | 有 `qr_image_url` 时调用 `present_files`；若同时有钱包链接则发送 `mobile_wallet_url`。二维码预览失败时只发送实际存在的二维码/钱包链接；只有钱包链接时直接发送它。展示后停止，不立即查询或创建替代付款。 |
 
 Host 只改变 instruction；Payment Intent ID、金额、状态、重试语义和权限必须一致。

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

@@ -32,8 +32,8 @@ itpay services checkout <service_execution_id> --resume
     "locked_input": { "<required_key>": "<value>" },
     "amount": "<amount> <currency>"
   },
-  "handoff": { "url": "<checkout_url>", "qr_local_path": "<host_optional_path>", "markdown": "<host_optional_markdown>" },
-  "instruction": "把付款链接、可用二维码和金额实际发送给用户，然后停止并等待。不要立即执行 next.command，不要创建第二个 Checkout，不要新建 Execution，不要调用 pay。用户表示已经完成付款或要求查询状态后，只执行 next.command；用户的话本身不是付款成功证明。",
+  "handoff": { "url": "<checkout_url>", "qr_local_path": "<desktop_optional_path>", "qr_image_url": "<workbuddy_optional_absolute_https_png>", "markdown": "<desktop_optional_markdown>" },
+  "instruction": "<exact_agent_type_instruction>",
   "next": { "command": "itpay checkout --id <checkout_id> --token <display_token> --json", "reason": "仅在用户完成付款操作或要求查询后，读取同一 Checkout 的权威状态" },
   "recovery": []
 }
@@ -76,7 +76,15 @@ itpay services checkout <service_execution_id> --resume
 | Agent Type | Instruction |
 |---|---|
 | `codex-desktop` | `handoff={url,qr_local_path,markdown}`；把 `handoff.markdown` 原样发送到当前桌面对话。 |
-| `codex-cli` | `handoff={url,qr_local_path}`；普通文本模式在用户可见终端渲染二维码。 |
+| `codex-cli` | `handoff={url}`；普通文本模式在用户可见终端渲染二维码。 |
 | `claude-code-desktop` | `handoff={url,qr_local_path,markdown}`；把 `handoff.markdown` 原样发送到当前桌面对话。 |
-| `claude-code-cli` | `handoff={url,qr_local_path}`；普通文本模式在用户可见终端渲染二维码。 |
-| `workbuddy` | `handoff={url,qr_local_path,qr_image_url}`；发送可点击链接，优先把本地路径作为图片附件，不能发送本地附件时使用绝对图片 URL；发送金额后停止等待。 |
+| `claude-code-cli` | `handoff={url}`；普通文本模式在用户可见终端渲染二维码。 |
+| `workbuddy` | `handoff={url,qr_image_url?}`；有 `qr_image_url` 时读取完整值并作为 `files` 数组唯一元素调用 `present_files`；没有时直接发送金额与 `url`，不得调用 `present_files`。两者随后都停止，不得检查或生成本地文件。 |
+
+WorkBuddy 的准确 instruction 语义必须完整包含：
+
+```text
+Backend 尚未确认付款。读取 handoff.qr_image_url 的完整字符串，原样作为 files 数组唯一元素调用 present_files({ files: ["<完整 qr_image_url>"] })；确认右侧二维码预览已打开后，向用户说明金额并发送 handoff.url，然后停止等待。如果 present_files 失败，只发送 handoff.url 并说明二维码预览未打开，然后停止。不要检查本地文件，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。
+```
+
+若 `qr_image_url` 缺失，准确 instruction 必须改为：说明本次没有可展示二维码，发送金额与 `handoff.url`，明确不要调用 `present_files`，然后遵守相同停止和付款证明规则。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.0.10",
+  "version": "2.0.11",
   "description": "ItPay CLI for V3 checkout, payment, order, refund, and agent-facing render flows.",
   "type": "module",
   "bin": {

package/skills/itpay-buyer/SKILL.md

@@ -8,14 +8,14 @@ description: >
 
 # ItPay Buyer
 
-Use the CLI as the only ItPay control surface. Do not recreate API calls or hardcode a service-specific sequence.
+Use the CLI as the only ItPay control surface. Never recreate API calls or hardcode a service-specific sequence.
 
-## Critical Rules
+## Envelope Rule
 
-- Keep one honest Agent Type, one CLI/Node launcher, and one Host-approved permission context for the whole flow.
-- Treat `next.command` as the preferred continuation, not an unconditional command. If the current result already satisfies the user's stated goal, present it and stop.
-- Keep internal parsing, retries, sandbox diagnosis, and command translation out of the user response; report useful progress, results, and real human decisions only.
-- If Device state is not writable, stop. Do not switch Node, manually create lock files, delete identity, or rotate Agent Type.
+- Keep one honest Agent Type, CLI/Node launcher, and Host permission context. Supported types: `codex-desktop`, `codex-cli`, `claude-code-desktop`, `claude-code-cli`, `workbuddy`.
+- Windows, tasks, chats, processes, and model sessions are not new Agents. Never rotate Agent Type or identity to reset quota.
+- Read `status` and `result` as facts, follow `instruction`, and execute at most the applicable `next.command`; use `recovery` only when it cannot continue.
+- `next.command` is not unconditional. If the result satisfies the user's goal, present useful facts and stop; never dump the whole envelope.
 
 ## Bootstrap
 
@@ -28,31 +28,15 @@ itpay install <agent_type> --json
 itpay --agent-type <agent_type> readyz --json
 ```
 
-Follow each returned `next.command`. `readyz` deliberately points back to this complete Skill. If the Skill was read without an Agent Type, choose the real runtime with `install`; after typed `readyz`, read the Skill again and continue to Catalog.
-
-Supported types are `codex-desktop`, `codex-cli`, `claude-code-desktop`, `claude-code-cli`, and `workbuddy`. State the real stable runtime type honestly. Do not identify a window, chat, task, process, or model session as a new Agent.
+Follow the returned `next.command`. After typed `readyz`, read this complete Skill again, then continue to Catalog.
 
 ## Identity And Sessions
 
-- One local Ed25519 private key represents this ItPay installation. Never expose, copy, or rotate it to recover quota.
-- Device registrations are scoped by exact Backend API base URL. `dev`, `test`, and `app` therefore have separate server device IDs, quota lineage, Agent instances, and sessions while using the same local key.
-- Each Backend registration has one Agent Instance per `agent_type`. Different windows and chats of the same type reuse it; different types get separate instances under that registration.
-- Every commerce command must keep the explicit `--agent-type` returned in `next` and `recovery`, or use one stable `ITPAY_AGENT_TYPE`. Never fall back to another type previously used on the machine.
-- The CLI renews an expired or rejected device session and retries the same request exactly once. If that retry still fails, stop and report it; do not loop, create a new identity, or switch Agent Type.
-- A revoked v2 device is not replaced automatically. It requires an explicit operator recovery path.
-- If an operator confirms that one Backend registration database was reset, use `device recover --confirm-backend-reset` for that selected Backend only. This preserves the private key and every other Backend registration; never use it for ordinary session expiry or revocation.
-- `--host` selects presentation. `--target` is only the destination chat/channel/open ID required by some Hosts. Neither is business input or identity.
-
-## Envelope Rule
-
-For every JSON response:
-
-1. Read `status` and `result` as current facts.
-2. Follow `instruction` when explaining or presenting those facts.
-3. Execute at most the one `next.command`, filling only explicit placeholders or required user data.
-4. Use `recovery` only when the normal next step cannot continue.
-
-Do not print the whole envelope to the user. Return the useful result, a short explanation, and the next human action when needed.
+- One local Ed25519 private key represents this installation. Never expose, copy, delete, or rotate it during normal recovery.
+- `dev`, `test`, and `app` have separate Device registrations under the same key. Each registration has one Agent Instance per `agent_type`; same-type windows reuse it.
+- Keep the returned `--agent-type` on every commerce command, or use one stable `ITPAY_AGENT_TYPE`. `--host` is presentation and `--target` is routing; neither is identity or business input.
+- The CLI may renew a rejected/expired session and retry once. If it still fails or Device state is not writable, stop; do not loop, switch Node, edit locks, inspect credentials, or change identity.
+- Use `device recover --confirm-backend-reset` only after an operator confirms that Backend was reset. It preserves the key and other Backend registrations.
 
 ## Golden Flow
 
@@ -61,29 +45,37 @@ itpay --agent-type <agent_type> catalog list --json
 itpay --agent-type <agent_type> services start <service_id> --json
 ```
 
-Then execute the exact `next.command` returned by each step. It may invoke a capability, ask for a selection, create a Checkout, wait for human action, return an Agent-visible result, or read a protected result after grant.
+Then follow each returned `next.command` on the same Service Execution.
 
-`services start` creates the Execution and returns the preferred capability plus its `required_input`. Put business values only in repeated `--input key=value` options on the returned `services invoke`, `services quote`, or `services checkout` command. For example, a company keyword belongs in `--input keyword=美团`; it never belongs in `--target`.
+- Put business input only in repeated `--input key=value` options. A keyword such as `美团` never belongs in `--target`.
+- One independent service intent uses one Service Execution.
+- Candidate lists belong to their source Execution. Ask the human to select a displayed rank, then submit it on that same Execution; never construct a candidate ID.
+- Before a paid step, show the exact price, ask for required contact fields with their purpose, and wait for explicit human agreement. Never invent contact data.
+- A normal single-Execution purchase uses the exact returned `services checkout` command.
+- `services quote -> cart add --quote -> buy --cart` is only for a human who explicitly asks to combine Quotes from multiple independent Executions. It is not failure recovery.
 
-Rules:
+## Checkout Handoff
 
-- One independent service intent uses one Service Execution.
-- Every candidate list belongs to its source Service Execution. After a human selects a rank, submit the selection on that same Execution; never copy it into a new Execution or construct a candidate.
-- A normal single-Execution paid step uses the exact `services checkout` command returned by the CLI, but only after the instruction has made the price visible and the human explicitly agrees. The command internally uses the same Quote, Cart and Checkout rules.
-- `services quote -> cart add --quote -> buy --cart` is only for a human who explicitly asks to combine Quotes from multiple independent Executions. Never use it as a fallback when `services checkout` fails.
-- Ask for required email/contact fields; explain their delivery purpose and never invent them.
-- When Checkout is ready, make the amount, ItPay QR/image and URL visible on the current human surface, then stop. Do not query until the human completes the action or asks for status.
-- Normal payment happens on the ItPay Checkout page. `itpay pay` and `buy --pay` are operator escape hatches.
-- Payment is confirmed only by Backend Checkout or Order state.
-- Agent-visible results come from `services next`; do not call `read-result` for them.
-- Quota exhaustion, candidate selection, Checkout pending, payment verified and delivery each remain on the same Execution. Never create a replacement Execution to escape one of those states.
-- An Execution may have delivery history; always follow `services next` for the backend-selected current delivery instead of reusing an older result.
-- Protected results require a current human grant. The grant is scoped to one delivery, approved fields and frozen Agent audience, and expires after 15 minutes.
-- A pending refund locks every delivery path and revokes existing grants.
+When `status` is `human_checkout_required`, make the amount, ItPay Checkout QR, and `handoff.url` visible on the current human surface, then stop.
+
+- Desktop Agents: send `handoff.markdown` unchanged; confirm QR, amount, and link are visible, then stop.
+- CLI Agents: show the terminal QR, amount, and link in the watched terminal, then stop; never claim a desktop image was shown.
+- WorkBuddy with `plain-chat`: when `handoff.qr_image_url` exists, use its complete value as the only `files` element in `present_files`; confirm the right-side QR preview opened, show amount and `handoff.url`, then stop. If it is absent, send amount and `handoff.url`, do not call `present_files`, then stop.
+- If WorkBuddy `present_files` fails, send only `handoff.url`, report the failure, and stop. Never inspect files, switch Node, rebuild a QR, call `pay`, or create another Checkout.
+- An explicit `--host` overrides presentation only. It never changes Agent identity or payment state.
+
+Run `next.command` only after the human says they acted or asks for status. QR rendering, redirects, and human claims are not payment proof; only Backend Checkout or Order state is. Normal payment uses the Checkout page; `pay` and `buy --pay` are operator escape hatches, never recovery.
+
+## Delivery And Refunds
+
+- Agent-visible results come from `services next`; do not use `read-result` for them.
+- Protected results require a current 15-minute human grant scoped to one delivery, approved fields, and frozen Agent audience.
+- An Execution may have delivery history; follow `services next` for the Backend-selected current delivery.
+- A pending refund locks delivery and revokes active grants. Follow the returned refund command and state.
 
 ## Recovery
 
-Before creating anything again:
+Before creating anything again, use only the applicable read/resume command:
 
 ```bash
 itpay --agent-type <agent_type> next --json
@@ -92,16 +84,17 @@ itpay --agent-type <agent_type> services next <service_execution_id> --json
 itpay --agent-type <agent_type> services checkout <service_execution_id> --resume --json
 itpay --agent-type <agent_type> checkout --id <checkout_id> --token <display_token> --json
 itpay --agent-type <agent_type> refund get <refund_request_id> --json
-itpay --agent-type <agent_type> device recover --confirm-backend-reset --json
 ```
 
+Reuse the same Execution and Checkout. Never start another Execution, create another Checkout, change payment route, or replay a capability to bypass quota, selection, payment, delivery, grant, or refund state.
+
 ## Safety
 
 - Never invent service, capability, item, Checkout, Order, grant, or refund IDs.
 - Never expose Provider credentials, raw payloads, display tokens as standalone chat data, Buyer bearer tokens, or Device private keys.
 - Never bypass ownership, compatibility, quota, grant, or refund-lock errors.
 - Do not use `services events` in a normal flow; it is a bounded redacted diagnostic command.
-- Do not rotate Agent Type or local identity to reset free quota.
+- Keep retries, sandbox diagnosis, and command translation out of the user response. Report useful progress, results, and genuine blockers.
 
 ## Built-In Help
 
@@ -112,4 +105,4 @@ itpay docs show <topic> --json
 itpay skill show itpay-buyer --json
 ```
 
-The normative command contracts are packaged under `docs/cli-reference`.
+Normative command contracts are packaged under `docs/cli-reference`.