@itpay/cli 0.1.10 → 0.2.0

package/bin/itp

@@ -1,24 +1,14 @@
 #!/usr/bin/env node
 
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import crypto from "node:crypto";
-import { execFileSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import QRCode from "qrcode";
-
-const DEFAULT_API_BASE = process.env.ITPAY_API_BASE || process.env.ITPAY_CORE_API_BASE || process.env.ITPAY_CORE_BASE_URL || "https://dev.api.itpay.ai";
-const CONFIG_DIR = path.join(os.homedir(), ".itp");
-const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
-const STATE_PATH = path.join(CONFIG_DIR, "state.json");
-const CREDENTIALS_PATH = path.join(CONFIG_DIR, "credentials.json");
-const RUNS_DIR = path.join(CONFIG_DIR, "runs");
-const LOCK_PATH = path.join(CONFIG_DIR, "state.lock");
-const CLI_FILE = fileURLToPath(import.meta.url);
-const CLI_DIR = path.dirname(CLI_FILE);
-const PACKAGE_ROOT = path.dirname(CLI_DIR);
-const VERSION = packageVersion();
+import { output, outputError, parseFlags, readState, VERSION } from "../lib/env.js";
+import { docs, skill } from "../lib/docs.js";
+import { ops, admin } from "../lib/ops.js";
+import { buyer, buyerBuy } from "../lib/buyer.js";
+import {
+  accountLoginLink, accountSetPassword, accountShow, agentStatus, authDevice, authLogin, authRegister, authStatus, balance,
+  checkoutCreate, checkoutList, checkoutOpen, checkoutQR, checkoutRecover, doctor, grantsInstall, grantsList, grantsRevoke,
+  grantsShow, installRuntime, keys, paymentWait, plansList, plansShow, resume, runs, setup, sync, token, usage
+} from "../lib/runtime.js";
 
 main().catch((error) => {
   outputError(error);
@@ -35,160 +25,70 @@ async function main() {
   const [group, command, ...rest] = args;
   const flags = parseFlags(rest);
 
-  if (group === "usage") {
-    await usage(parseFlags(args.slice(1)));
-    return;
-  }
-  if (group === "balance") {
-    await balance(parseFlags(args.slice(1)));
-    return;
-  }
-  if (group === "plans" && (!command || String(command).startsWith("--"))) {
-    await plansList(parseFlags(args.slice(1)));
-    return;
-  }
-  if (group === "setup") {
-    await setup(parseFlags(args.slice(1)));
-    return;
-  }
+  if (group === "usage") return usage(parseFlags(args.slice(1)));
+  if (group === "balance") return balance(parseFlags(args.slice(1)));
+  if (group === "plans" && (!command || String(command).startsWith("--"))) return plansList(parseFlags(args.slice(1)));
+  if (group === "setup") return setup(parseFlags(args.slice(1)));
   if (group === "buy") {
     const buyFlags = parseFlags(command && String(command).startsWith("--") ? args.slice(1) : rest);
     if (command && !String(command).startsWith("--")) buyFlags.selection = command;
-    await buyerBuy(buyFlags);
-    return;
-  }
-  if (group === "buyer") {
-    await buyer(command, rest, parseFlags(rest));
-    return;
-  }
-  if (group === "ops") {
-    await ops(command, rest, parseFlags(rest));
-    return;
+    return buyerBuy(buyFlags);
   }
+  if (group === "buyer") return buyer(command, rest, parseFlags(rest));
+  if (group === "ops") return ops(command, rest, parseFlags(rest));
   if (group === "docs") {
     const docsCommand = command && !String(command).startsWith("--") ? command : "list";
     const docsFlags = parseFlags(command && String(command).startsWith("--") ? args.slice(1) : rest);
-    await docs(docsCommand, command && String(command).startsWith("--") ? [] : rest, docsFlags);
-    return;
-  }
-  if (group === "status") {
-    await agentStatus(parseFlags(args.slice(1)));
-    return;
-  }
-  if (group === "resume") {
-    await resume(parseFlags(args.slice(1)));
-    return;
+    return docs(docsCommand, command && String(command).startsWith("--") ? [] : rest, docsFlags);
   }
+  if (group === "status") return agentStatus(parseFlags(args.slice(1)));
+  if (group === "resume") return resume(parseFlags(args.slice(1)));
   if (group === "runs") {
     const runCommand = command && !String(command).startsWith("--") ? command : "current";
     const runFlags = parseFlags(command && String(command).startsWith("--") ? args.slice(1) : rest);
-    if (rest[0] && !String(rest[0]).startsWith("--")) {
-      runFlags.run_id = rest[0];
-    }
-    await runs(runCommand, runFlags);
-    return;
-  }
-  if (group === "doctor") {
-    await doctor(parseFlags(args.slice(1)));
-    return;
+    if (rest[0] && !String(rest[0]).startsWith("--")) runFlags.run_id = rest[0];
+    return runs(runCommand, runFlags);
   }
+  if (group === "doctor") return doctor(parseFlags(args.slice(1)));
   if (group === "skill") {
     const skillCommand = command && !String(command).startsWith("--") ? command : "show";
     const skillFlags = parseFlags(command && String(command).startsWith("--") ? args.slice(1) : rest);
-    await skill(skillCommand, skillFlags);
-    return;
-  }
-  if (group === "keys") {
-    await keys(command, parseFlags(rest));
-    return;
-  }
-  if (group === "token") {
-    await token(command, parseFlags(rest));
-    return;
-  }
-  if (group === "sync") {
-    await sync(parseFlags(args.slice(1)));
-    return;
-  }
-  if (group === "admin") {
-    await admin(command, rest, parseFlags(rest));
-    return;
+    return skill(skillCommand, skillFlags);
   }
+  if (group === "keys") return keys(command, parseFlags(rest));
+  if (group === "token") return token(command, parseFlags(rest));
+  if (group === "sync") return sync(parseFlags(args.slice(1)));
+  if (group === "admin") return admin(command, rest, parseFlags(rest));
   if (group === "auth" && command === "device") {
     const deviceFlags = parseFlags(rest.slice(1));
-    if (rest[0] === "poll" && rest[1] && !String(rest[1]).startsWith("--")) {
-      deviceFlags.auth_id = rest[1];
-    }
-    await authDevice(rest[0], deviceFlags);
-    return;
-  }
-
-  switch (`${group || ""} ${command || ""}`.trim()) {
-    case "auth register":
-      await authRegister(flags);
-      return;
-    case "auth login":
-      await authLogin(flags);
-      return;
-    case "auth status":
-      await authStatus(flags);
-      return;
-    case "account show":
-      await accountShow(flags);
-      return;
-    case "account login-link":
-      await accountLoginLink(flags);
-      return;
-    case "account set-password":
-      await accountSetPassword(flags);
-      return;
-    case "plans list":
-      await plansList(flags);
-      return;
-    case "plans show":
-      await plansShow(rest[0], flags);
-      return;
-    case "checkout create":
-      await checkoutCreate(flags);
-      return;
-    case "checkout recover":
-      await checkoutRecover(rest[0] || readState().last_checkout_id, flags);
-      return;
-    case "checkout open":
-      await checkoutOpen(flags);
-      return;
-    case "checkout qr":
-      await checkoutQR(rest[0] || readState().last_checkout_id, flags);
-      return;
-    case "checkout list":
-      await checkoutList(flags);
-      return;
-    case "payment wait":
-      await paymentWait(rest[0] || readState().last_checkout_id, flags);
-      return;
-    case "balance":
-      await balance(flags);
-      return;
-    case "grants list":
-      await grantsList(flags);
-      return;
-    case "grants show":
-      await grantsShow(rest[0], flags);
-      return;
-    case "grants install":
-      await grantsInstall(rest[0], flags);
-      return;
-    case "grants revoke":
-      await grantsRevoke(rest[0], flags);
-      return;
+    if (rest[0] === "poll" && rest[1] && !String(rest[1]).startsWith("--")) deviceFlags.auth_id = rest[1];
+    return authDevice(rest[0], deviceFlags);
+  }
+
+  switch ([group || "", command || ""].join(" ").trim()) {
+    case "auth register": return authRegister(flags);
+    case "auth login": return authLogin(flags);
+    case "auth status": return authStatus(flags);
+    case "account show": return accountShow(flags);
+    case "account login-link": return accountLoginLink(flags);
+    case "account set-password": return accountSetPassword(flags);
+    case "plans list": return plansList(flags);
+    case "plans show": return plansShow(rest[0], flags);
+    case "checkout create": return checkoutCreate(flags);
+    case "checkout recover": return checkoutRecover(rest[0] || readState().last_checkout_id, flags);
+    case "checkout open": return checkoutOpen(flags);
+    case "checkout qr": return checkoutQR(rest[0] || readState().last_checkout_id, flags);
+    case "checkout list": return checkoutList(flags);
+    case "payment wait": return paymentWait(rest[0] || readState().last_checkout_id, flags);
+    case "balance": return balance(flags);
+    case "grants list": return grantsList(flags);
+    case "grants show": return grantsShow(rest[0], flags);
+    case "grants install": return grantsInstall(rest[0], flags);
+    case "grants revoke": return grantsRevoke(rest[0], flags);
     case "install claude-code":
     case "install codex":
-    case "install openclaw":
-      await installRuntime(command, flags);
-      return;
-    case "doctor":
-      await doctor(flags);
-      return;
+    case "install openclaw": return installRuntime(command, flags);
+    case "doctor": return doctor(flags);
     default:
       output({
         version: VERSION,
@@ -244,4413 +144,3 @@ async function main() {
       });
   }
 }
-
-async function authRegister(flags) {
-  const response = await completeDeviceAuth(flags);
-  output(response);
-}
-
-async function setup(flags) {
-  return await withStateLock(async () => {
-    const target = flags.target || flags.runtime || "generic";
-    const purchase = normalizePurchaseFlags(flags, true);
-    const plan = purchase.plan || null;
-    const credits = purchase.credits || null;
-    const method = flags.method || "alipay";
-    validateLivePaymentFlags(method, flags);
-    const shouldInstallRuntime = Boolean(flags.install_runtime || flags.install_config || flags.write_runtime_config) && !flags.no_runtime_install && !flags.no_install;
-    if (shouldInstallRuntime && target === "generic") {
-      throw new Error("--install-runtime requires --target codex, --target claude-code, or --target openclaw");
-    }
-
-    let run = prepareSetupRun(flags, { target, plan, credits, method, install_runtime: shouldInstallRuntime });
-    const setupFlags = { ...flags, runtime: target, run_id: run.run_id };
-    if (shouldReturnAfterAgentTextQR(setupFlags)) {
-      setupFlags.no_wait_auth = true;
-      setupFlags.no_wait_payment = true;
-    }
-    run = updateRun(run, { phase: "checking_auth", status: "running", api_base: apiBase(setupFlags) });
-
-    const auth = await ensureAuthenticated(setupFlags);
-    if (!auth.authenticated) {
-      run = mergeRun(run, {
-        phase: "waiting_human_auth",
-        status: "waiting_human_auth",
-        auth: {
-          auth_id: auth.auth_id,
-          status: "pending",
-          expires_at: auth.expires_at
-        },
-        human_action: auth.human_action || null,
-        safe_summary: "Waiting for Alipay authentication scan."
-      });
-      writeRun(run);
-      output(agentRunResponse(run, {
-        status: "waiting_human_auth",
-        action: "scan_alipay_auth",
-        auth_id: auth.auth_id,
-        user_code: auth.user_code,
-        verification_uri: auth.verification_uri,
-        verification_uri_complete: auth.verification_uri_complete,
-        alipay_authorization_url: auth.alipay_authorization_url,
-        expires_at: auth.expires_at,
-        interval: auth.interval,
-        human_action: auth.human_action,
-        next_action: {
-          type: "show_qr_and_wait",
-          command: resumeCommand(run, setupFlags, { no_wait_payment: Boolean(setupFlags.no_wait_payment) }),
-          retry_after_ms: Number(auth.interval || 2) * 1000
-        }
-      }));
-      return;
-    }
-
-    run = mergeRun(run, {
-      phase: "authenticated",
-      status: "running",
-      account: {
-        authenticated: true,
-        account_id: auth.account_id,
-        device_id: auth.device_id,
-        newapi_user_id: auth.newapi_user_id || null,
-        session_reused: Boolean(auth.session_reused)
-      },
-      auth: {
-        ...(run.auth || {}),
-        status: "consumed"
-      },
-      human_action: null,
-      safe_summary: "Agent device authenticated."
-    });
-    writeRun(run);
-
-    let checkout = run.checkout?.checkout_id
-      ? await api(`/api/itp/checkout/${encodeURIComponent(run.checkout.checkout_id)}`, { method: "GET" }, setupFlags)
-      : null;
-    if (!checkout || isTerminalCheckoutFailure(checkout.status)) {
-      checkout = await createCheckoutResult({
-        ...setupFlags,
-        plan,
-        credits,
-        method,
-        idempotency_key: flags.idempotency_key || run.idempotency_key
-      });
-    }
-
-    run = mergeRun(run, {
-      phase: checkout.grant_id ? "grant_ready" : "waiting_human_payment",
-      status: checkout.grant_id ? "grant_ready" : "waiting_human_payment",
-      plan_id: checkout.plan_id || plan,
-      credits: checkout.credits || credits,
-      purchase_kind: checkout.purchase?.kind || purchase.kind,
-      checkout: {
-        checkout_id: checkout.checkout_id,
-        order_id: checkout.order_id,
-        status: checkout.status,
-        expires_at: checkout.expires_at,
-        purchase: checkout.purchase || null
-      },
-      payment: {
-        provider: method,
-        status: checkout.status
-      },
-      grant: {
-        ...(run.grant || {}),
-        grant_id: checkout.grant_id || run.grant?.grant_id || null
-      },
-      human_action: checkout.human_action || null,
-      safe_summary: checkout.grant_id ? "Payment verified and grant is ready." : "Waiting for Alipay payment scan."
-    });
-    writeRun(run);
-
-    if (checkout.human_action) {
-      await renderHumanAction(checkout.human_action, setupFlags);
-    } else if (checkout.payment?.cashier_url) {
-      process.stderr.write(`Open Alipay payment URL: ${checkout.payment.cashier_url}\n`);
-    }
-
-    if (!checkout.grant_id && (setupFlags.no_wait_payment || setupFlags.no_wait)) {
-      output(agentRunResponse(run, {
-        status: "waiting_human_payment",
-        action: "scan_alipay_payment",
-        account_id: auth.account_id,
-        device_id: auth.device_id,
-        checkout_id: checkout.checkout_id,
-        order_id: checkout.order_id,
-        plan_id: checkout.plan_id || plan,
-        credits: checkout.credits || credits,
-        purchase: checkout.purchase || null,
-        expires_at: checkout.expires_at,
-        payment: checkout.payment,
-        human_action: checkout.human_action,
-        next_action: checkout.next_action || {
-          type: "show_qr_and_wait",
-          command: resumeCommand(run, setupFlags),
-          retry_after_ms: 2000
-        }
-      }));
-      return;
-    }
-
-    const payment = checkout.grant_id
-      ? { status: checkout.status, checkout_id: checkout.checkout_id, order_id: checkout.order_id, grant_id: checkout.grant_id }
-      : await paymentWaitResult(checkout.checkout_id, setupFlags);
-    run = mergeRun(readRun(run.run_id) || run, {
-      phase: "grant_ready",
-      checkout: {
-        ...(run.checkout || {}),
-        checkout_id: payment.checkout_id,
-        order_id: payment.order_id,
-        status: payment.status
-      },
-      payment: {
-        provider: method,
-        status: payment.status
-      },
-      grant: {
-        grant_id: payment.grant_id,
-        installed: false
-      },
-      human_action: null,
-      safe_summary: "Payment verified and grant is ready."
-    });
-    writeRun(run);
-
-    const grant = await grantsInstallResult(payment.grant_id, { ...setupFlags, target });
-    const runtimeInstall = shouldInstallRuntime
-      ? await installRuntimeResult(target, {
-        ...setupFlags,
-        grant: payment.grant_id,
-        no_test: flags.test ? false : true
-      })
-      : {
-        status: "skipped",
-        reason: "runtime_config_install_is_opt_in",
-        command: target === "generic"
-          ? `${cliCommand("install")} <target> --grant ${shellQuote(payment.grant_id)} --json`
-          : cliCommand("install", target, "--grant", payment.grant_id, "--json")
-      };
-    const tokenCommand = cliCommand("token", "issue", "--grant", payment.grant_id, "--stdout");
-    run = mergeRun(readRun(run.run_id) || run, {
-      phase: shouldInstallRuntime ? "done" : "grant_ready",
-      status: shouldInstallRuntime ? "installed" : "grant_ready",
-      grant: {
-        grant_id: payment.grant_id,
-        installed: true,
-        credential_store: grant.credential?.credential_store || null
-      },
-      result: {
-        base_url: grant.base_url,
-        openai_base_url: grant.openai_base_url,
-        anthropic_base_url: grant.anthropic_base_url,
-        gemini_base_url: grant.gemini_base_url
-      },
-      safe_summary: shouldInstallRuntime ? "Runtime configured." : "Grant credential stored."
-    });
-    writeRun(run);
-
-    output(agentRunResponse(run, {
-      status: shouldInstallRuntime ? "installed" : "grant_ready",
-      account_id: auth.account_id,
-      device_id: auth.device_id,
-      checkout_id: checkout.checkout_id,
-      order_id: checkout.order_id,
-      plan_id: checkout.plan_id || plan,
-      credits: checkout.credits || credits,
-      purchase: checkout.purchase || null,
-      grant_id: payment.grant_id,
-      target,
-      base_url: grant.base_url,
-      openai_base_url: grant.openai_base_url,
-      anthropic_base_url: grant.anthropic_base_url,
-      gemini_base_url: grant.gemini_base_url,
-      credential: {
-        stored: true,
-        credential_store: grant.credential?.credential_store,
-        warning: grant.credential?.warning,
-        token_command: tokenCommand,
-        stdout_required_for_raw_token: true
-      },
-      auth,
-      checkout,
-      payment,
-      grant_install: grant,
-      runtime_install: runtimeInstall,
-      next_action: shouldInstallRuntime
-        ? null
-        : {
-          type: "configure_agent_optional",
-          token_command: tokenCommand,
-          runtime_install_command: runtimeInstall.command
-        }
-    }));
-  });
-}
-
-async function buyerBuy(flags) {
-  const selectionID = flags.selection || flags.variant || flags.catalog_variant_id || flags.item || flags.catalog_item_id;
-  if (!selectionID) throw new Error("catalog variant id is required, for example: itp buy var_pubg_couple_skin_cny20 --sandbox --email buyer@example.com --phone +8613800000000 --json");
-  const selection = await resolveBuyerCatalogSelection(selectionID, flags);
-  const cart = await createBuyerCart(selection, flags);
-  let checkout = await createBuyerCheckoutFromCart(cart, selection, flags);
-  if (checkout.next_required_action === "auth_qr" || checkout.identity_status === "waiting_human_auth") {
-    await renderHumanAction(checkout.human_action, flags);
-    if (flags.no_wait || flags.no_wait_auth) {
-      output(buyerRunOutput({
-        status: "waiting_human_auth",
-        selection,
-        cart,
-        checkout,
-        human_action: checkout.human_action,
-        agent_next_actions: checkout.agent_next_actions || ["wait_human_auth", "poll_checkout"],
-        next: {
-          command: cliCommand("buyer", "checkout", "resume", checkout.checkout_id, "--json"),
-          safe_for_agent: true,
-          instruction: "After presenting the first-purchase auth-to-payment QR, keep this resume command running/waiting. Do not stop at QR display unless the human explicitly asks you to pause."
-        }
-      }));
-      return;
-    }
-    checkout = await waitBuyerCheckoutAuth(checkout, flags);
-  }
-  const intent = checkout.payment_intent_id
-    ? await getBuyerPaymentIntent(checkout.payment_intent_id, flags)
-    : await createBuyerPaymentIntent(checkout.checkout_id, flags);
-  await renderItPayPaymentAction(intent, flags);
-
-  if (flags.no_wait || flags.no_wait_payment) {
-    output(buyerRunOutput({
-      status: "waiting_user_payment",
-      selection,
-      cart,
-      checkout,
-      payment_intent: intent,
-      agent_next_actions: intent.agent_next_actions || ["wait_payment"],
-      next: { command: cliCommand("buyer", "payment", "wait", intent.payment_intent_id, "--json") }
-    }));
-    return;
-  }
-
-  const event = await waitBuyerPayment(intent, flags);
-  const delivery = await waitBuyerDelivery(checkout.checkout_id, flags);
-  const finalCheckout = delivery.checkout || checkout;
-  const delivered = isBuyerDeliveryComplete(finalCheckout);
-  output(buyerRunOutput({
-    status: delivered ? "delivery_claimable" : event.event_type === "payment_intent.verified" ? "payment_verified" : "waiting_user_payment",
-    selection,
-    cart,
-    checkout: finalCheckout,
-    payment_intent: intent,
-    payment_event: event,
-    delivery: delivery.delivery || finalCheckout.delivery || null,
-    agent_next_actions: delivered ? deliveryAwareAgentNextActions(finalCheckout) : (finalCheckout.agent_next_actions || event.agent_next_actions || intent.agent_next_actions || ["poll_checkout"]),
-    optional_agent_read_grant: optionalAgentReadGrantHint(finalCheckout.checkout_id || checkout.checkout_id, finalCheckout),
-    next: delivered
-      ? { type: "human_check_email", safe_for_agent: true }
-      : { command: cliCommand("buyer", "checkout", "status", checkout.checkout_id, "--json"), safe_for_agent: true }
-  }));
-}
-
-async function buyer(command, rest, flags) {
-  const subcommand = rest[0] && !String(rest[0]).startsWith("--") ? rest[0] : "";
-  if (command === "catalog") {
-    if (subcommand === "search") {
-      const query = flags.query || flags.q || "";
-      const body = {
-        query,
-        filters: buyerCatalogSearchFilters(flags),
-        context: {},
-        pagination: {}
-      };
-      if (flags.currency) body.context.currency = String(flags.currency);
-      if (flags.page_size || flags.limit) body.pagination.limit = Number(flags.page_size || flags.limit);
-      if (flags.cursor) body.pagination.cursor = String(flags.cursor);
-      const catalog = await coreApi("/v1/catalog/search", { method: "POST", body }, flags);
-      output(buyerRunOutput({
-        status: "catalog_search_results",
-        catalog,
-        products: catalog.products || [],
-        agent_next_actions: ["choose_variant"]
-      }));
-      return;
-    }
-    if (subcommand === "get") {
-      const selectionID = flags.variant || flags.catalog_variant_id || flags.item || flags.catalog_item_id || rest[1];
-      const detail = await getBuyerUCPProduct(selectionID, flags);
-      const selection = selectionFromUCPProduct(detail, selectionID, flags);
-      output(buyerRunOutput({
-        status: "catalog_product",
-        product: detail.product,
-        messages: detail.messages || [],
-        selection,
-        agent_next_actions: ["create_cart"]
-      }));
-      return;
-    }
-  }
-  if (command === "cart") {
-    if (subcommand === "create") {
-      const selectionIDs = buyerCartSelectionIDs(rest, flags);
-      const selections = await resolveBuyerCatalogSelections(selectionIDs, flags);
-      const cart = await createBuyerCartFromSelections(selections, flags);
-      output(buyerRunOutput({
-        status: "cart_created",
-        selection: selections.length === 1 ? selections[0] : undefined,
-        selections,
-        cart,
-        cart_id: cart.cart_id || cart.id,
-        agent_next_actions: cart.agent_next_actions || ["create_checkout_from_cart"]
-      }));
-      return;
-    }
-    if (subcommand === "add") {
-      const cartID = flags.cart || flags.cart_id || positional(rest, 1) || readState().last_core_cart_id;
-      if (!cartID) throw new Error("cart_id is required");
-      const selectionIDs = buyerCartSelectionIDs(["add"], flags);
-      const selections = await resolveBuyerCatalogSelections(selectionIDs, flags);
-      if (selections.length !== 1) throw new Error("buyer cart add requires exactly one --variant");
-      const cart = await addBuyerCartLineItem(cartID, selections[0], flags);
-      output(buyerRunOutput({
-        status: "cart_updated",
-        selection: selections[0],
-        cart,
-        cart_id: cart.cart_id || cart.id,
-        agent_next_actions: cart.agent_next_actions || ["view_cart", "create_checkout_from_cart"]
-      }));
-      return;
-    }
-    if (subcommand === "remove" || subcommand === "delete") {
-      const cartID = flags.cart || flags.cart_id || positional(rest, 1) || readState().last_core_cart_id;
-      const lineID = flags.line || flags.line_id || flags.cart_line_item_id || positional(rest, 2);
-      if (!cartID) throw new Error("cart_id is required");
-      if (!lineID) throw new Error("cart_line_item_id is required; run buyer cart show <cart_id> --json first");
-      const cart = await removeBuyerCartLineItem(cartID, lineID, flags);
-      output(buyerRunOutput({
-        status: "cart_updated",
-        cart,
-        cart_id: cart.cart_id || cart.id,
-        removed_line_item_id: lineID,
-        agent_next_actions: cart.agent_next_actions || ["view_cart", "create_checkout_from_cart"]
-      }));
-      return;
-    }
-    if (subcommand === "show" || subcommand === "status") {
-      const cartID = flags.cart || flags.cart_id || positional(rest, 1) || readState().last_core_cart_id;
-      if (!cartID) throw new Error("cart_id is required");
-      const cart = await getBuyerCart(cartID, flags);
-      output(buyerRunOutput({
-        status: cart.status || "cart_ready",
-        cart,
-        cart_id: cart.cart_id || cart.id,
-        agent_next_actions: cart.agent_next_actions || ["create_checkout_from_cart"]
-      }));
-      return;
-    }
-  }
-  if (command === "shelf") {
-    if (subcommand === "manifest") {
-      output(await coreApi("/v1/catalog/manifests/current", { method: "GET" }, flags));
-      return;
-    }
-    if (subcommand === "snapshot") {
-      const version = flags.version || positional(rest, 1);
-      if (!version) throw new Error("snapshot version is required");
-      output(await coreApi(`/v1/catalog/snapshots/${encodeURIComponent(version)}`, { method: "GET" }, flags));
-      return;
-    }
-    if (subcommand === "delta") {
-      const since = flags.since || positional(rest, 1);
-      if (!since) throw new Error("delta --since version is required");
-      const params = new URLSearchParams({ since });
-      output(await coreApi(`/v1/catalog/delta?${params.toString()}`, { method: "GET" }, flags));
-      return;
-    }
-  }
-  if (command === "checkout") {
-    if (subcommand === "create") {
-      const cartID = flags.cart || flags.cart_id;
-      if (cartID) {
-        const cart = await getBuyerCart(cartID, flags);
-        const checkout = await createBuyerCheckoutFromCart(cart, null, flags);
-        if (checkout.next_required_action === "auth_qr" || checkout.identity_status === "waiting_human_auth") {
-          await renderHumanAction(checkout.human_action, flags);
-        }
-        output(buyerRunOutput({
-          status: "checkout_created",
-          cart,
-          checkout,
-          agent_next_actions: checkout.agent_next_actions || ["create_payment_intent"],
-          next: checkout.next_required_action === "auth_qr" || checkout.identity_status === "waiting_human_auth"
-            ? {
-              command: cliCommand("buyer", "checkout", "resume", checkout.checkout_id, "--json"),
-              safe_for_agent: true,
-              instruction: "After presenting the first-purchase auth-to-payment QR, keep this resume command running/waiting. Do not stop at QR display unless the human explicitly asks you to pause."
-            }
-            : undefined
-        }));
-        return;
-      }
-      const selectionID = flags.variant || flags.catalog_variant_id || flags.item || flags.catalog_item_id;
-      const selection = await resolveBuyerCatalogSelection(selectionID, flags);
-      const cart = await createBuyerCart(selection, flags);
-      const checkout = await createBuyerCheckoutFromCart(cart, selection, flags);
-      if (checkout.next_required_action === "auth_qr" || checkout.identity_status === "waiting_human_auth") {
-        await renderHumanAction(checkout.human_action, flags);
-      }
-      output(buyerRunOutput({
-        status: "checkout_created",
-        selection,
-        cart,
-        checkout,
-        agent_next_actions: checkout.agent_next_actions || ["create_payment_intent"],
-        next: checkout.next_required_action === "auth_qr" || checkout.identity_status === "waiting_human_auth"
-          ? {
-            command: cliCommand("buyer", "checkout", "resume", checkout.checkout_id, "--json"),
-            safe_for_agent: true,
-            instruction: "After presenting the first-purchase auth-to-payment QR, keep this resume command running/waiting. Do not stop at QR display unless the human explicitly asks you to pause."
-          }
-          : undefined
-      }));
-      return;
-    }
-    if (subcommand === "status") {
-      const checkoutID = flags.checkout || flags.checkout_id || positional(rest, 1) || readState().last_core_checkout_id;
-      if (!checkoutID) throw new Error("checkout_id is required");
-      const checkout = await getBuyerCheckout(checkoutID, flags);
-      const claimedSession = await maybeClaimBuyerSessionForCheckout(checkout, flags);
-      output(buyerRunOutput({
-        status: checkout.delivery_status || checkout.status,
-        checkout,
-        delivery: checkout.delivery,
-        buyer_session: buyerSessionClaimStatus(claimedSession),
-        agent_next_actions: deliveryAwareAgentNextActions(checkout),
-        optional_agent_read_grant: optionalAgentReadGrantHint(checkout.checkout_id, checkout)
-      }));
-      return;
-    }
-    if (subcommand === "resume") {
-      const checkoutID = flags.checkout || flags.checkout_id || positional(rest, 1) || readState().last_core_checkout_id;
-      if (!checkoutID) throw new Error("checkout_id is required");
-      let checkout = await getBuyerCheckout(checkoutID, flags);
-      if (checkout.next_required_action === "auth_qr" || checkout.identity_status === "waiting_human_auth") {
-        await renderHumanAction(checkout.human_action, flags);
-        if (flags.no_wait || flags.no_wait_auth) {
-          output(buyerRunOutput({
-            status: "waiting_human_auth",
-            checkout,
-            human_action: checkout.human_action,
-            agent_next_actions: checkout.agent_next_actions || ["wait_human_auth", "poll_checkout"],
-            next: {
-              command: cliCommand("buyer", "checkout", "resume", checkoutID, "--json"),
-              safe_for_agent: true,
-              instruction: "Run this resume command and keep it active; do not stop after showing the auth-to-payment QR unless the human explicitly asks you to pause."
-            }
-          }));
-          return;
-        }
-        checkout = await waitBuyerCheckoutAuth(checkout, flags);
-        if (checkout.next_required_action === "auth_qr" || checkout.identity_status === "waiting_human_auth") {
-          output(buyerRunOutput({
-            status: "waiting_human_auth",
-            checkout,
-            human_action: checkout.human_action,
-            agent_next_actions: checkout.agent_next_actions || ["wait_human_auth", "poll_checkout"],
-            next: {
-              command: cliCommand("buyer", "checkout", "resume", checkoutID, "--json"),
-              safe_for_agent: true,
-              instruction: "Auth is still pending. Keep waiting/resuming the same checkout; do not create a new checkout."
-            }
-          }));
-          return;
-          }
-        }
-        const claimedSession = await maybeClaimBuyerSessionForCheckout(checkout, flags);
-        if (checkout.payment_intent_id) {
-          const intent = await getBuyerPaymentIntent(checkout.payment_intent_id, flags);
-          await renderItPayPaymentAction(intent, flags);
-          output(buyerRunOutput({
-            status: intent.status === "verified" ? "payment_verified" : "waiting_user_payment",
-            checkout,
-            payment_intent: intent,
-            buyer_session: buyerSessionClaimStatus(claimedSession),
-            agent_next_actions: intent.agent_next_actions || checkout.agent_next_actions || ["wait_payment"]
-          }));
-          return;
-        }
-      if (checkout.agent_next_actions?.includes("create_payment_intent") || checkout.next_required_action === "create_payment_intent") {
-        const intent = await createBuyerPaymentIntent(checkout.checkout_id, flags);
-        await renderItPayPaymentAction(intent, flags);
-        output(buyerRunOutput({ status: "waiting_user_payment", checkout, payment_intent: intent, agent_next_actions: intent.agent_next_actions || ["wait_payment"] }));
-        return;
-      }
-      output(buyerRunOutput({
-        status: checkout.delivery_status || checkout.status,
-        checkout,
-        delivery: checkout.delivery,
-        buyer_session: buyerSessionClaimStatus(claimedSession),
-        agent_next_actions: deliveryAwareAgentNextActions(checkout),
-        optional_agent_read_grant: optionalAgentReadGrantHint(checkout.checkout_id, checkout)
-      }));
-      return;
-    }
-  }
-  if (command === "payment" && subcommand === "wait") {
-    const paymentIntentID = flags.payment_intent || flags.payment_intent_id || positional(rest, 1) || readState().last_core_payment_intent_id;
-    if (!paymentIntentID) throw new Error("payment_intent_id is required");
-    const intent = await getBuyerPaymentIntent(paymentIntentID, flags);
-    const event = intent.status === "verified"
-      ? { event_type: "payment_intent.verified", payment_intent_id: paymentIntentID, agent_next_actions: intent.agent_next_actions || ["poll_checkout"] }
-      : await waitBuyerPayment(intent, flags);
-    output(buyerRunOutput({ status: event.event_type === "payment_intent.verified" ? "payment_verified" : "waiting_user_payment", payment_intent: intent, payment_event: event, agent_next_actions: event.agent_next_actions || intent.agent_next_actions }));
-    return;
-  }
-  if (command === "payment" && subcommand === "refresh-qr") {
-    const paymentIntentID = flags.payment_intent || flags.payment_intent_id || positional(rest, 1) || readState().last_core_payment_intent_id;
-    if (!paymentIntentID) throw new Error("payment_intent_id is required");
-    const refreshed = await refreshBuyerPaymentQR(paymentIntentID, flags);
-    await renderItPayPaymentAction(refreshed, flags);
-    output(buyerRunOutput({
-      status: refreshed.status === "verified" ? "payment_verified" : "waiting_user_payment",
-      payment_intent: refreshed,
-      agent_next_actions: refreshed.agent_next_actions || ["wait_payment"],
-      next: refreshed.status === "verified"
-        ? { command: cliCommand("buyer", "checkout", "status", refreshed.checkout_id, "--json"), safe_for_agent: true }
-        : { command: cliCommand("buyer", "payment", "wait", refreshed.payment_intent_id, "--json"), safe_for_agent: true }
-    }));
-    return;
-  }
-  if (command === "deliveries") {
-    if (subcommand === "list") {
-      const checkoutID = flags.checkout || flags.checkout_id || readState().last_core_checkout_id;
-      if (!checkoutID) throw new Error("--checkout is required");
-      const checkout = await getBuyerCheckout(checkoutID, flags);
-      output(buyerDeliveryListOutput(checkout));
-      return;
-    }
-    if (subcommand === "show") {
-      const checkoutID = flags.checkout || flags.checkout_id || readState().last_core_checkout_id;
-      if (!checkoutID) throw new Error("--checkout is required for agent-safe delivery status");
-      const checkout = await getBuyerCheckout(checkoutID, flags);
-      output({
-        schema_version: "itp.buyer.v1",
-        status: checkout.delivery?.status || checkout.delivery_status,
-        delivery_id: positional(rest, 1) || flags.delivery || flags.delivery_id || null,
-        checkout_id: checkout.checkout_id,
-        delivery: checkout.delivery || null,
-        agent_next_actions: deliveryAwareAgentNextActions(checkout),
-        optional_agent_read_grant: optionalAgentReadGrantHint(checkout.checkout_id, checkout),
-        secrets: { raw_content_included: false, claim_token_included: false }
-      });
-      return;
-    }
-  }
-  if (command === "refund") {
-    if (subcommand === "create") {
-      const orderID = flags.order || flags.order_id || positional(rest, 1);
-      if (!orderID) throw new Error("order_id is required");
-      const refund = await createBuyerRefund(orderID, flags);
-      if (refund.status === "policy_risk_confirmation_required") {
-        output(buyerRunOutput(refund));
-        return;
-      }
-      output(buyerRunOutput({
-        status: refund.status || "refund_requested",
-        refund,
-        refund_eligibility: refund.refund_eligibility || null,
-        agent_next_actions: ["watch_refund_status", "explain_refund_policy"]
-      }));
-      return;
-    }
-    if (subcommand === "list") {
-      const orderID = flags.order || flags.order_id || positional(rest, 1);
-      if (!orderID) throw new Error("order_id is required");
-      const refunds = await listBuyerRefunds(orderID, flags);
-      output(buyerRunOutput({
-        status: "refunds",
-        order_id: orderID,
-        ...refunds,
-        agent_next_actions: ["show_refund_status"]
-      }));
-      return;
-    }
-    if (subcommand === "show") {
-      const refundID = flags.refund || flags.refund_id || positional(rest, 1);
-      if (!refundID) throw new Error("refund_id is required");
-      const refund = await getBuyerRefund(refundID, flags);
-      output(buyerRunOutput({
-        status: refund.status || "refund",
-        refund,
-        agent_next_actions: ["show_refund_status"]
-      }));
-      return;
-    }
-    if (subcommand === "cancel") {
-      const refundID = flags.refund || flags.refund_id || positional(rest, 1);
-      if (!refundID) throw new Error("refund_id is required");
-      const refund = await cancelBuyerRefund(refundID, flags);
-      output(buyerRunOutput({
-        status: refund.status || "refund_canceled",
-        refund,
-        agent_next_actions: ["show_refund_status", "claim_delivery_if_still_needed"]
-      }));
-      return;
-    }
-  }
-  if (command === "vault") {
-    if (subcommand === "grants") {
-      const action = rest[1] && !String(rest[1]).startsWith("--") ? rest[1] : "list";
-      if (action === "list") {
-        const claimedSession = await ensureBuyerSessionForVaultAccess(flags);
-        const grants = await listBuyerAgentReadGrants(flags);
-        output(buyerRunOutput({
-          status: "agent_read_grants",
-          ...grants,
-          buyer_session: buyerSessionClaimStatus(claimedSession),
-          agent_next_actions: grants.agent_readable_grants?.length ? ["read_agent_grant_view"] : ["wait_for_human_agent_read_grant"]
-        }));
-        return;
-      }
-      if (action === "read" || action === "show") {
-        const grantID = flags.grant || flags.grant_id || flags.agent_read_grant_id || positional(rest, 2);
-        if (!grantID) throw new Error("agent_read_grant_id is required");
-        await ensureBuyerSessionForVaultAccess(flags);
-        const view = await readBuyerAgentReadGrant(grantID, flags);
-        output(buyerRunOutput({
-          status: "agent_read_grant_view",
-          grant: view,
-          agent_next_actions: ["use_human_approved_fields_only"]
-        }));
-        return;
-      }
-    }
-    if (subcommand === "read") {
-      await ensureBuyerSessionForVaultAccess(flags);
-      const view = await readBuyerVaultArtifactGrant(flags);
-      output(buyerRunOutput({
-        status: "agent_read_grant_view",
-        grant: view,
-        agent_next_actions: ["use_human_approved_fields_only"]
-      }));
-      return;
-    }
-  }
-  if (command === "account" && subcommand === "login-link") {
-    await accountLoginLink(flags);
-    return;
-  }
-  if (command === "auth" && subcommand === "status") {
-    output(await buyerAuthStatusOutput(flags));
-    return;
-  }
-  throw new Error(`unknown buyer command: ${[command, subcommand].filter(Boolean).join(" ") || ""}`);
-}
-
-function buyerCatalogSearchFilters(flags = {}) {
-  const filters = {};
-  const categories = csvValues(flags.category || flags.categories);
-  if (categories.length) filters.categories = categories;
-
-  const mappings = [
-    ["service_type", "ai.itpay.service_type"],
-    ["delivery_method", "ai.itpay.delivery_method"],
-    ["provider", "ai.itpay.provider"],
-    ["provider_product_id", "ai.itpay.provider_product_id"],
-    ["provider_product", "ai.itpay.provider_product_id"],
-    ["sensitivity_level", "ai.itpay.sensitivity_level"],
-    ["sensitivity", "ai.itpay.sensitivity_level"],
-    ["delivery_mode", "ai.itpay.delivery_mode"],
-    ["settlement_group", "ai.itpay.settlement_group"]
-  ];
-  for (const [flagName, filterName] of mappings) {
-    if (flags[flagName]) filters[filterName] = String(flags[flagName]);
-  }
-
-  const listMappings = [
-    ["use_case", "ai.itpay.taxonomy.use_cases"],
-    ["use_cases", "ai.itpay.taxonomy.use_cases"],
-    ["input_facet", "ai.itpay.taxonomy.input_facets"],
-    ["input_facets", "ai.itpay.taxonomy.input_facets"],
-    ["output_facet", "ai.itpay.taxonomy.output_facets"],
-    ["output_facets", "ai.itpay.taxonomy.output_facets"],
-    ["required_profile_field", "ai.itpay.required_profile_fields"],
-    ["required_profile_fields", "ai.itpay.required_profile_fields"],
-    ["agent_runtime", "ai.itpay.agent_runtimes"],
-    ["agent_runtimes", "ai.itpay.agent_runtimes"]
-  ];
-  for (const [flagName, filterName] of listMappings) {
-    const values = csvValues(flags[flagName]);
-    if (values.length) filters[filterName] = values;
-  }
-
-  const boolMappings = [
-    ["payment_qr_mpm", "ai.itpay.payment.qr_mpm"],
-    ["merchant_verified", "ai.itpay.merchant_verified"],
-    ["requires_human_input", "ai.itpay.requires_human_input"],
-    ["requires_webauthn_reveal", "ai.itpay.requires_webauthn_reveal"],
-    ["agent_may_execute_query", "ai.itpay.agent_may_execute_query"],
-    ["agent_may_view_raw_result", "ai.itpay.agent_may_view_raw_result"]
-  ];
-  for (const [flagName, filterName] of boolMappings) {
-    if (flags[flagName] !== undefined) filters[filterName] = booleanFlag(flags[flagName]);
-  }
-
-  const hasMin = flags.price_min !== undefined || flags.min_price !== undefined;
-  const hasMax = flags.price_max !== undefined || flags.max_price !== undefined;
-  const min = hasMin ? Number(flags.price_min ?? flags.min_price) : NaN;
-  const max = hasMax ? Number(flags.price_max ?? flags.max_price) : NaN;
-  if (Number.isFinite(min) || Number.isFinite(max)) {
-    filters.price = {};
-    if (Number.isFinite(min)) filters.price.min = min;
-    if (Number.isFinite(max)) filters.price.max = max;
-  }
-  return filters;
-}
-
-function csvValues(value) {
-  if (value === undefined || value === null || value === false) return [];
-  if (Array.isArray(value)) return value.map((item) => String(item).trim()).filter(Boolean);
-  return String(value).split(",").map((item) => item.trim()).filter(Boolean);
-}
-
-function booleanFlag(value) {
-  if (value === true || value === false) return value;
-  const normalized = String(value).trim().toLowerCase();
-  if (["1", "true", "yes", "y", "on"].includes(normalized)) return true;
-  if (["0", "false", "no", "n", "off"].includes(normalized)) return false;
-  throw new Error(`invalid boolean flag value: ${value}`);
-}
-
-function intFlag(value, name) {
-  const number = Number(value);
-  if (!Number.isInteger(number)) throw new Error(`${name} must be an integer`);
-  return number;
-}
-
-async function ops(command, rest, flags) {
-  if (command !== "sandbox") throw new Error(`unknown ops command: ${command || ""}`);
-  const area = rest[0];
-  const action = rest[1];
-  if (area === "worker" && action === "run-once") {
-    output(await coreApi("/v1/sandbox/workers/run-once", { method: "POST", ops: true }, flags));
-    return;
-  }
-  if (area === "recover-alipay-once") {
-    output(await coreApi("/v1/local/workers/recover-alipay-sandbox-once", { method: "POST", ops: true }, flags));
-    return;
-  }
-  if (area === "payment" && action === "query") {
-    const paymentIntentID = flags.payment_intent || flags.payment_intent_id || positional(rest, 2);
-    if (!paymentIntentID) throw new Error("payment_intent_id is required");
-    output(await coreApi(`/v1/payment-intents/${encodeURIComponent(paymentIntentID)}/alipay-sandbox-query`, { method: "POST", ops: true }, flags));
-    return;
-  }
-  if (area === "refund") {
-    const refundID = flags.refund || flags.refund_id || positional(rest, 2);
-    if (!refundID) throw new Error("refund_id is required");
-    if (action === "show") {
-      output(await coreApi(`/v1/sandbox/ops/refunds/${encodeURIComponent(refundID)}`, { method: "GET", ops: true }, flags));
-      return;
-    }
-    if (action === "approve" || action === "reject") {
-      output(await coreApi(`/v1/sandbox/ops/refunds/${encodeURIComponent(refundID)}/${action}`, {
-        method: "POST",
-        ops: true,
-        idempotencyKey: flags.idempotency_key || `idem_cli_refund_${action}_${refundID}`,
-        body: {
-          reason_code: flags.reason || flags.reason_code || (action === "approve" ? "approved_by_ops" : "not_eligible"),
-          note: flags.note || ""
-        }
-      }, flags));
-      return;
-    }
-    if (action === "execute") {
-      output(await coreApi(`/v1/sandbox/ops/refunds/${encodeURIComponent(refundID)}/execute`, {
-        method: "POST",
-        ops: true,
-        idempotencyKey: flags.idempotency_key || `idem_cli_refund_execute_${refundID}`
-      }, flags));
-      return;
-    }
-  }
-  if (area === "ledger" && action === "entries") {
-    const params = new URLSearchParams();
-    if (flags.order || flags.order_id) params.set("order_id", String(flags.order || flags.order_id));
-    if (flags.refund || flags.refund_id) params.set("refund_id", String(flags.refund || flags.refund_id));
-    if (flags.payment_intent || flags.payment_intent_id) params.set("payment_intent_id", String(flags.payment_intent || flags.payment_intent_id));
-    if ([...params.keys()].length === 0) {
-      throw new Error("ledger filter is required: use --order, --refund, or --payment-intent");
-    }
-    output(await coreApi(`/v1/sandbox/ops/ledger/entries${queryString(params)}`, { method: "GET", ops: true }, flags));
-    return;
-  }
-  if (area === "reconciliation") {
-    if (action === "run") {
-      output(await coreApi("/v1/sandbox/ops/reconciliation-runs", {
-        method: "POST",
-        ops: true,
-        idempotencyKey: flags.idempotency_key || `idem_cli_reconciliation_${cryptoRandom()}`,
-        body: {
-          reconciliation_run_id: flags.reconciliation_run_id || flags.run_id || "",
-          status: flags.status || "matched",
-          expected_amount_minor: intFlag(flags.expected_amount_minor || flags.expected || 0, "expected_amount_minor"),
-          observed_amount_minor: intFlag(flags.observed_amount_minor || flags.observed || 0, "observed_amount_minor"),
-          currency: flags.currency || "CNY",
-          raw_statement_ref: flags.raw_statement_ref || flags.statement_ref || ""
-        }
-      }, flags));
-      return;
-    }
-    if (action === "show") {
-      const runID = flags.reconciliation_run_id || flags.run_id || positional(rest, 2);
-      if (!runID) throw new Error("reconciliation_run_id is required");
-      output(await coreApi(`/v1/sandbox/ops/reconciliation-runs/${encodeURIComponent(runID)}`, { method: "GET", ops: true }, flags));
-      return;
-    }
-  }
-  if (area === "settlement" && action === "show") {
-    const settlementBatchID = flags.settlement_batch || flags.settlement_batch_id || positional(rest, 2);
-    if (!settlementBatchID) throw new Error("settlement_batch_id is required");
-    output(await coreApi(`/v1/sandbox/ops/settlement-batches/${encodeURIComponent(settlementBatchID)}`, { method: "GET", ops: true }, flags));
-    return;
-  }
-  throw new Error(`unknown ops sandbox command: ${rest.join(" ")}`);
-}
-
-async function resolveBuyerCatalogSelection(selectionID, flags = {}) {
-  if (!selectionID) throw new Error("catalog selection id is required");
-  const detail = await getBuyerUCPProduct(selectionID, flags);
-  return selectionFromUCPProduct(detail, selectionID, flags);
-}
-
-async function resolveBuyerCatalogSelections(selectionIDs, flags = {}) {
-  const ids = selectionIDs.map((id) => String(id).trim()).filter(Boolean);
-  if (!ids.length) throw new Error("at least one catalog variant id is required");
-  const selections = [];
-  for (const id of ids) {
-    selections.push(await resolveBuyerCatalogSelection(id, flags));
-  }
-  return selections;
-}
-
-async function getBuyerUCPProduct(selectionID, flags = {}) {
-  if (!selectionID) throw new Error("catalog selection id is required");
-  const body = {
-    id: String(selectionID),
-    filters: {},
-    context: {}
-  };
-  if (flags.currency) body.context.currency = String(flags.currency);
-  return await coreApi("/v1/catalog/selections/resolve", { method: "POST", body }, flags);
-}
-
-function selectionFromUCPProduct(detail, selectionID, flags = {}) {
-  const product = detail?.product;
-  if (!product) throw new Error(`catalog selection not found: ${selectionID}`);
-  const variants = Array.isArray(product.variants) ? product.variants : [];
-  const selectedVariantID = product.selected?.variant_id || selectionID;
-  const variant = variants.find((candidate) => candidate.id === selectionID) ||
-    variants.find((candidate) => candidate.id === selectedVariantID) ||
-    variants[0];
-  if (!variant) throw new Error(`catalog product has no variants: ${selectionID}`);
-  const metadata = {
-    ...(product.metadata || {}),
-    ...(variant.metadata || {})
-  };
-  const requiredFields = Array.isArray(metadata["ai.itpay.required_profile_fields"])
-    ? metadata["ai.itpay.required_profile_fields"].map((field) => String(field)).filter(Boolean)
-    : [];
-  return {
-    catalog_item_id: product.id,
-    catalog_variant_id: variant.id,
-    ucp_variant_id: variant.id,
-    offer_id: flags.offer || flags.offer_id || metadata["ai.itpay.offer_id"] || "",
-    catalog_version: metadata["ai.itpay.catalog_version"] || product.selected?.catalog_version || "",
-    expected_amount: Number(flags.expected_amount || variant.price?.amount || 0),
-    currency: flags.currency || variant.price?.currency || metadata.currency || "",
-    title: product.title,
-    description: product.description || variant.description || "",
-    variant_title: variant.title,
-    required_contact_fields: requiredFields,
-    product,
-    variant,
-    metadata,
-    purchasable: variant.availability?.available !== false
-  };
-}
-
-async function createBuyerCart(selection, flags = {}) {
-  return await createBuyerCartFromSelections([selection], flags);
-}
-
-async function createBuyerCartFromSelections(selections, flags = {}) {
-  if (!Array.isArray(selections) || !selections.length) throw new Error("at least one catalog selection is required");
-  const quantities = buyerCartQuantities(selections.length, flags);
-  const lineItems = selections.map((selection, index) => {
-    if (!selection?.purchasable) throw new Error(`catalog variant is not purchasable: ${selection?.catalog_variant_id || selection?.ucp_variant_id || index}`);
-    return {
-      item: { id: selection.catalog_variant_id || selection.ucp_variant_id },
-      quantity: quantities[index],
-      input: buyerLineInputForSelection(selection, flags, index)
-    };
-  });
-  const currencies = new Set(selections.map((selection) => String(flags.currency || selection.currency || "")).filter(Boolean));
-  if (currencies.size > 1) {
-    throw new Error(`selected variants have different currencies: ${Array.from(currencies).join(", ")}`);
-  }
-  const currency = flags.currency || selections[0]?.currency || "";
-  const body = {
-    line_items: lineItems,
-    context: {},
-    client_reference_id: flags.cart_client_reference_id || flags.client_reference_id || `cli_cart_${Date.now()}`
-  };
-  if (currency) body.context.currency = String(currency);
-  const cart = await coreApi("/v1/carts", {
-    method: "POST",
-    idempotencyKey: flags.cart_idempotency_key || `idem_cli_cart_${cryptoRandom()}`,
-    body
-  }, flags);
-  writeState({ ...readState(), last_core_cart_id: cart.cart_id || cart.id });
-  return cart;
-}
-
-function buyerCartSelectionIDs(rest, flags = {}) {
-  const raw = flags.variants || flags.variant_ids || flags.variant || flags.catalog_variant_id || flags.item || flags.catalog_item_id || positional(rest, 1);
-  if (!raw) return [];
-  if (Array.isArray(raw)) return raw.flatMap((value) => splitCSV(value));
-  return splitCSV(raw);
-}
-
-function buyerCartQuantities(count, flags = {}) {
-  const raw = flags.quantities || flags.quantity || flags.qty;
-  const values = raw === undefined || raw === null || raw === true
-    ? []
-    : splitCSV(raw).map((value) => Number(value));
-  if (values.length && values.length !== count) {
-    throw new Error(`--quantities must provide ${count} value(s), got ${values.length}`);
-  }
-  const quantities = values.length ? values : Array(count).fill(1);
-  for (const quantity of quantities) {
-    if (!Number.isInteger(quantity) || quantity <= 0) {
-      throw new Error(`cart quantity must be a positive integer, got ${quantity}`);
-    }
-  }
-  return quantities;
-}
-
-function buyerLineInputForSelection(selection, flags = {}, index = 0) {
-  const input = parseBuyerInputs(flags, index);
-  const providerProductID = String(selection?.metadata?.["ai.itpay.provider_product_id"] || selection?.variant?.metadata?.["ai.itpay.provider_product_id"] || "");
-  if (providerProductID === "81api_company_fuzzy_search") {
-    if (!input.company_name && flags.company_name) input.company_name = String(flags.company_name).trim();
-    if (!input.company_name && flags.keyword) input.company_name = String(flags.keyword).trim();
-    if (!input.PageNum && flags.page_num) input.PageNum = String(flags.page_num).trim();
-    if (!input.PageNum) input.PageNum = "1";
-    if (!input.company_name) {
-      throw new Error("企业工商数据模糊查询 requires --input company_name=<关键词> or --company-name <关键词>. Ask the user for a company keyword/short name before checkout.");
-    }
-  }
-  if (providerProductID === "81api_company_base_info") {
-    if (!input.company_name_or_credit_no && flags.company_name_or_credit_no) input.company_name_or_credit_no = String(flags.company_name_or_credit_no).trim();
-    if (!input.company_name_or_credit_no && flags.company_name) input.company_name_or_credit_no = String(flags.company_name).trim();
-    if (!input.isRaiseErrorCode && flags.is_raise_error_code !== undefined) input.isRaiseErrorCode = String(flags.is_raise_error_code).trim();
-    if (!input.isRaiseErrorCode) input.isRaiseErrorCode = "0";
-    if (!input.company_name_or_credit_no) {
-      throw new Error("企业工商数据精准查询 requires --input company_name_or_credit_no=<完整企业名称或统一社会信用代码>. If the user only gave a brand/short name, run fuzzy search first or resolve the exact registered company name before checkout.");
-    }
-  }
-  return input;
-}
-
-function parseBuyerInputs(flags = {}, index = 0) {
-  const input = {};
-  const rawValues = [];
-  for (const key of ["input", "inputs"]) {
-    const raw = flags[key];
-    if (Array.isArray(raw)) rawValues.push(...raw);
-    else if (raw !== undefined && raw !== true) rawValues.push(raw);
-  }
-  for (const raw of rawValues) {
-    for (const part of splitInputParts(raw)) {
-      const eq = part.indexOf("=");
-      if (eq <= 0) throw new Error(`invalid --input ${part}; expected key=value`);
-      const key = part.slice(0, eq).trim();
-      const value = part.slice(eq + 1).trim();
-      if (key) input[key] = value;
-    }
-  }
-  const indexed = flags[`input_${index + 1}`] || flags[`inputs_${index + 1}`];
-  if (indexed && indexed !== true) {
-    for (const part of splitInputParts(indexed)) {
-      const eq = part.indexOf("=");
-      if (eq <= 0) throw new Error(`invalid indexed input ${part}; expected key=value`);
-      input[part.slice(0, eq).trim()] = part.slice(eq + 1).trim();
-    }
-  }
-  return input;
-}
-
-function splitInputParts(raw) {
-  const text = String(raw || "").trim();
-  if (!text) return [];
-  if (text.startsWith("{")) {
-    const parsed = JSON.parse(text);
-    return Object.entries(parsed).map(([key, value]) => `${key}=${value}`);
-  }
-  return text.split(",").map((part) => part.trim()).filter(Boolean);
-}
-
-function splitCSV(value) {
-  return String(value || "")
-    .split(",")
-    .map((part) => part.trim())
-    .filter(Boolean);
-}
-
-async function getBuyerCart(cartID, flags = {}) {
-  if (!cartID) throw new Error("cart_id is required");
-  return await coreApi(`/v1/carts/${encodeURIComponent(cartID)}`, { method: "GET" }, flags);
-}
-
-async function addBuyerCartLineItem(cartID, selection, flags = {}) {
-  if (!cartID) throw new Error("cart_id is required");
-  if (!selection?.purchasable) throw new Error(`catalog variant is not purchasable: ${selection?.catalog_variant_id || selection?.ucp_variant_id || ""}`);
-  const quantity = buyerCartQuantities(1, flags)[0];
-  const body = {
-    item: { id: selection.catalog_variant_id || selection.ucp_variant_id },
-    quantity,
-    input: buyerLineInputForSelection(selection, flags, 0)
-  };
-  const cart = await coreApi(`/v1/carts/${encodeURIComponent(cartID)}/line-items`, {
-    method: "POST",
-    idempotencyKey: flags.cart_idempotency_key || `idem_cli_cart_add_${cryptoRandom()}`,
-    body
-  }, flags);
-  writeState({ ...readState(), last_core_cart_id: cart.cart_id || cart.id });
-  return cart;
-}
-
-async function removeBuyerCartLineItem(cartID, lineID, flags = {}) {
-  if (!cartID) throw new Error("cart_id is required");
-  if (!lineID) throw new Error("cart_line_item_id is required");
-  const cart = await coreApi(`/v1/carts/${encodeURIComponent(cartID)}/line-items/${encodeURIComponent(lineID)}`, {
-    method: "DELETE"
-  }, flags);
-  writeState({ ...readState(), last_core_cart_id: cart.cart_id || cart.id });
-  return cart;
-}
-
-async function createBuyerCheckoutFromCart(cart, selection = null, flags = {}) {
-  const cartID = typeof cart === "string" ? cart : (cart?.cart_id || cart?.id);
-  if (!cartID) throw new Error("cart_id is required");
-  const deliveryContact = {};
-  if (flags.email) deliveryContact.email = flags.email;
-  if (flags.phone) deliveryContact.phone = flags.phone;
-  const missing = requiredDeliveryContactFields(selection).filter((field) => !deliveryContact[field]);
-  if (missing.length) {
-    throw new Error(`missing required delivery contact: ${missing.join(", ")}; provide ${missing.map((field) => `--${field} <value>`).join(" ")}`);
-  }
-  const request = {
-    method: "POST",
-    idempotencyKey: flags.checkout_idempotency_key || flags.idempotency_key || `idem_cli_checkout_${cartID}`,
-    body: {
-      cart_id: cartID,
-      client_reference_id: flags.checkout_client_reference_id || flags.client_reference_id || `cli_checkout_${cartID}`,
-      delivery_contact: deliveryContact
-    }
-  };
-  let checkout;
-  try {
-    checkout = await coreApi("/v1/checkouts", request, flags);
-  } catch (error) {
-    if (error?.status === 401 && readSessionToken(readCredentials()) && !flags.access_token) {
-      writeCredentials(deleteSessionCredential(readCredentials()));
-      checkout = await coreApi("/v1/checkouts", request, flags);
-    } else {
-      throw error;
-    }
-  }
-  writeState({ ...readState(), last_core_cart_id: cartID, last_core_checkout_id: checkout.checkout_id });
-  rememberCoreAuthAction(checkout.checkout_id, checkout.human_action);
-  return checkout;
-}
-
-function requiredDeliveryContactFields(selection) {
-  if (Array.isArray(selection?.required_contact_fields)) {
-    return selection.required_contact_fields.map((field) => String(field).trim()).filter(Boolean);
-  }
-  const fields = selection?.delivery?.requires_contact_fields;
-  return Array.isArray(fields) ? fields.map((field) => String(field).trim()).filter(Boolean) : [];
-}
-
-async function createBuyerPaymentIntent(checkoutID, flags = {}) {
-  if (!checkoutID) throw new Error("checkout_id is required");
-  const method = String(flags.method || flags.payment_method || "alipay").toLowerCase();
-  const provider = String(flags.provider || flags.preferred_provider || method).toLowerCase();
-  const intent = await coreApi(`/v1/checkouts/${encodeURIComponent(checkoutID)}/payment-intents`, {
-    method: "POST",
-    idempotencyKey: flags.payment_idempotency_key || flags.idempotency_key || `idem_cli_payment_${cryptoRandom()}`,
-    body: {
-      payment_method_type: method,
-      preferred_provider: provider
-    }
-  }, flags);
-  writeState({ ...readState(), last_core_checkout_id: checkoutID, last_core_payment_intent_id: intent.payment_intent_id });
-  return intent;
-}
-
-async function waitBuyerCheckoutAuth(checkout, flags = {}) {
-  const checkoutID = checkout?.checkout_id || checkout;
-  if (!checkoutID) throw new Error("checkout_id is required");
-  const timeoutMs = Number(flags.auth_timeout || flags.timeout || 900) * 1000;
-  const started = Date.now();
-  let lastHeartbeatAt = 0;
-  let current = typeof checkout === "string" ? await getBuyerCheckout(checkoutID, flags) : checkout;
-  const authAction = current?.human_action || readCoreAuthAction(checkoutID) || null;
-  rememberCoreAuthAction(checkoutID, authAction);
-  while (Date.now() - started < timeoutMs) {
-    if (current.payment_intent_id || current.identity_status === "identity_resolved" || current.next_required_action !== "auth_qr") {
-      await maybeClaimBuyerSessionFromAuthAction(authAction, flags);
-      return current;
-    }
-    lastHeartbeatAt = writeWaitHeartbeat({
-      kind: "ItPay buyer auth",
-      idName: "checkout_id",
-      idValue: checkoutID,
-      status: current.identity_status || current.next_required_action || "waiting_human_auth",
-      action: current.human_action || null,
-      lastHeartbeatAt,
-      flags,
-      command: cliCommand("buyer", "checkout", "resume", checkoutID, "--json")
-    });
-    await sleep(Number(flags.auth_poll_ms || flags.poll_ms || 2000));
-    current = await getBuyerCheckout(checkoutID, flags);
-  }
-  await maybeClaimBuyerSessionFromAuthAction(authAction, flags);
-  return current;
-}
-
-async function maybeClaimBuyerSessionFromAuthAction(action, flags = {}) {
-  const parsed = parseBuyerAuthActionURL(action);
-  if (!parsed.authSessionID || !parsed.displayToken) return null;
-  try {
-    const response = await coreApi(`/v1/session-exchanges/auth-sessions/${encodeURIComponent(parsed.authSessionID)}/agent-session?display_token=${encodeURIComponent(parsed.displayToken)}`, {
-      method: "POST"
-    }, flags);
-    const rawToken = response.raw_session_token || response.session_token || response.session?.raw_session_token;
-    if (!rawToken) return response;
-    writeSessionCredentials({
-      account_id: response.buyer_account_id,
-      device_id: response.agent_device_id,
-      session_token: rawToken
-    });
-    writeConfig({
-      api_base: coreApiBase(flags),
-      account_id: response.buyer_account_id,
-      device_id: response.agent_device_id
-    });
-    forgetCoreAuthAction(response.checkout_id);
-    return response;
-  } catch (error) {
-    if (!flags.quiet) {
-      process.stderr.write(`ItPay buyer session claim skipped: ${safeErrorMessage(error)}\n`);
-    }
-    return null;
-  }
-}
-
-function buyerSessionClaimStatus(claimed = null) {
-  const config = readConfig();
-  const hasSession = Boolean(readSessionToken());
-  if (!claimed && !hasSession) return undefined;
-  return {
-    status: "buyer_session_saved",
-    session_stored: true,
-    buyer_account_id: claimed?.buyer_account_id || config.account_id || null,
-    agent_device_id: claimed?.agent_device_id || config.device_id || null,
-    token_included: false,
-    agent_next_actions: ["reuse_buyer_session", "list_agent_read_grants"]
-  };
-}
-
-async function maybeClaimBuyerSessionForCheckout(checkout, flags = {}) {
-  if (!checkout?.checkout_id) return null;
-  if (readSessionToken()) return null;
-  if (checkout.identity_status !== "identity_resolved" && !checkout.payment_intent_id) return null;
-  const action = checkout.human_action || readCoreAuthAction(checkout.checkout_id);
-  return await maybeClaimBuyerSessionFromAuthAction(action, flags);
-}
-
-async function ensureBuyerSessionForVaultAccess(flags = {}) {
-  if (readSessionToken()) return null;
-  const checkoutID =
-    flags.checkout ||
-    flags.checkout_id ||
-    readState().last_core_checkout_id ||
-    readState().last_core_auth_checkout_id;
-  if (checkoutID) {
-    try {
-      const checkout = await getBuyerCheckout(checkoutID, flags);
-      rememberCoreAuthAction(checkout.checkout_id || checkoutID, checkout.human_action);
-      const claimed = await maybeClaimBuyerSessionForCheckout(checkout, { ...flags, quiet: true });
-      if (claimed || readSessionToken()) return claimed;
-    } catch {
-      // Continue with the locally remembered auth action below.
-    }
-    const action = readCoreAuthAction(checkoutID);
-    const claimed = await maybeClaimBuyerSessionFromAuthAction(action, { ...flags, quiet: true });
-    if (claimed || readSessionToken()) return claimed;
-  }
-  const state = readState();
-  const entries = Object.entries(state.core_auth_actions || {});
-  for (const [, action] of entries.reverse()) {
-    const claimed = await maybeClaimBuyerSessionFromAuthAction(action, { ...flags, quiet: true });
-    if (claimed || readSessionToken()) return claimed;
-  }
-  return null;
-}
-
-function parseBuyerAuthActionURL(action) {
-  if (!action || typeof action !== "object") return {};
-  let authSessionID = String(action.auth_session_id || "").trim();
-  if (!authSessionID && String(action.id || "").startsWith("auth_")) {
-    authSessionID = String(action.id).trim();
-  }
-  let displayToken = "";
-  let sourceURL = "";
-  for (const rawURL of buyerAuthActionCandidateURLs(action)) {
-    try {
-      const parsed = new URL(rawURL);
-      const token = parsed.searchParams.get("display_token") || "";
-      if (token && !displayToken) displayToken = token;
-      const match = parsed.pathname.match(/(?:^|\/)v1\/session-exchanges\/auth-sessions\/([^/?#]+)(?:\/|$)/);
-      if (match && !authSessionID) authSessionID = decodeURIComponent(match[1]);
-      if (!sourceURL && (match || token)) sourceURL = rawURL;
-      if (authSessionID && displayToken) break;
-    } catch {
-      // Ignore non-URL display entries.
-    }
-  }
-  return { authSessionID, displayToken, sourceURL };
-}
-
-function buyerAuthActionCandidateURLs(action) {
-  const urls = [];
-  for (const key of ["url", "web_url", "auth_url", "oauth_start_url", "mobile_wallet_url"]) {
-    if (action?.[key]) urls.push(String(action[key]));
-  }
-  const presentationDisplay = action?.presentation?.display;
-  if (Array.isArray(presentationDisplay)) {
-    for (const entry of presentationDisplay) {
-      if (entry?.url) urls.push(String(entry.url));
-    }
-  }
-  if (Array.isArray(action?.display)) {
-    for (const entry of action.display) {
-      if (entry?.url) urls.push(String(entry.url));
-    }
-  }
-  return urls;
-}
-
-function rememberCoreAuthAction(checkoutID, action) {
-  if (!checkoutID || action?.kind !== "auth_qr") return;
-  const parsed = parseBuyerAuthActionURL(action);
-  if (!parsed.authSessionID || !parsed.displayToken) return;
-  const state = readState();
-  const existing = state.core_auth_actions && typeof state.core_auth_actions === "object" ? state.core_auth_actions : {};
-  const entries = Object.entries(existing).slice(-19);
-  const next = Object.fromEntries(entries);
-  next[checkoutID] = {
-    kind: "auth_qr",
-    id: action.id || action.auth_session_id || parsed.authSessionID,
-    auth_session_id: parsed.authSessionID,
-    url: action.url || parsed.sourceURL,
-    web_url: action.web_url || action.url || parsed.sourceURL,
-    expires_at: action.expires_at || null,
-    saved_at: new Date().toISOString()
-  };
-  writeState({ ...state, core_auth_actions: next, last_core_auth_checkout_id: checkoutID });
-}
-
-function readCoreAuthAction(checkoutID) {
-  if (!checkoutID) return null;
-  const state = readState();
-  return state.core_auth_actions?.[checkoutID] || null;
-}
-
-function forgetCoreAuthAction(checkoutID) {
-  if (!checkoutID) return;
-  const state = readState();
-  if (!state.core_auth_actions?.[checkoutID]) return;
-  const next = { ...state.core_auth_actions };
-  delete next[checkoutID];
-  writeState({ ...state, core_auth_actions: next });
-}
-
-async function getBuyerCheckout(checkoutID, flags = {}) {
-  return await coreApi(`/v1/checkouts/${encodeURIComponent(checkoutID)}`, { method: "GET" }, flags);
-}
-
-async function createBuyerRefund(orderID, flags = {}) {
-  if (flags.amount !== undefined) {
-    throw new Error("use --amount-minor for refund amount");
-  }
-  if (flags.refund_scope && flags.refund_scope !== "order") {
-    throw new Error("unsupported_refund_scope");
-  }
-  const order = await getBuyerOrderDetail(orderID, flags);
-  const eligibility = order.refund_eligibility || order.order_detail?.refund_eligibility || null;
-  if (eligibility && eligibility.likely_refundable === false && !booleanFlag(flags.confirm_policy_risk || false)) {
-    return {
-      status: "policy_risk_confirmation_required",
-      order_id: orderID,
-      refund_eligibility: eligibility,
-      agent_next_actions: [
-        "explain_refund_policy",
-        "ask_human_to_confirm_policy_risk",
-        `retry_with_${cliCommand("buyer", "refund", "create", orderID, "--confirm-policy-risk", "true", "--json")}`
-      ],
-      submitted: false
-    };
-  }
-  return await coreApi(`/v1/me/orders/${encodeURIComponent(orderID)}/refunds`, {
-    method: "POST",
-    headers: { "X-ItPay-Client-Surface": "cli" },
-    idempotencyKey: flags.idempotency_key || `idem_cli_refund_create_${orderID}`,
-    body: {
-      refund_scope: flags.refund_scope || "order",
-      order_line_item_ids: csvValues(flags.order_line_item_ids || flags.line_ids || flags.line_id),
-      amount_minor: intFlag(flags.amount_minor, "amount_minor"),
-      currency: flags.currency || "CNY",
-      reason_code: flags.reason || flags.reason_code || "buyer_requested",
-      reason_note: flags.note || flags.reason_note || ""
-    }
-  }, flags);
-}
-
-async function getBuyerOrderDetail(orderID, flags = {}) {
-  return await coreApi(`/v1/me/orders/${encodeURIComponent(orderID)}`, { method: "GET" }, flags);
-}
-
-async function listBuyerRefunds(orderID, flags = {}) {
-  return await coreApi(`/v1/me/orders/${encodeURIComponent(orderID)}/refunds`, { method: "GET" }, flags);
-}
-
-async function getBuyerRefund(refundID, flags = {}) {
-  return await coreApi(`/v1/me/refunds/${encodeURIComponent(refundID)}`, { method: "GET" }, flags);
-}
-
-async function cancelBuyerRefund(refundID, flags = {}) {
-  return await coreApi(`/v1/me/refunds/${encodeURIComponent(refundID)}/cancel`, {
-    method: "POST",
-    headers: { "X-ItPay-Client-Surface": "cli" },
-    idempotencyKey: flags.idempotency_key || `idem_cli_refund_cancel_${refundID}`,
-    body: {
-      reason_code: flags.reason || flags.reason_code || "buyer_changed_mind",
-      reason_note: flags.note || flags.reason_note || ""
-    }
-  }, flags);
-}
-
-async function getBuyerPaymentIntent(paymentIntentID, flags = {}) {
-  return await coreApi(`/v1/payment-intents/${encodeURIComponent(paymentIntentID)}`, { method: "GET" }, flags);
-}
-
-async function refreshBuyerPaymentQR(paymentIntentID, flags = {}) {
-  const intent = await getBuyerPaymentIntent(paymentIntentID, flags);
-  if (intent.status === "verified") return intent;
-  const refreshURL = intent.qr_refresh_url;
-  if (!refreshURL) {
-    throw new Error("payment intent does not expose qr_refresh_url; refresh is supported only for refreshable Alipay sandbox QR intents");
-  }
-  return await coreApi(refreshURL, {
-    method: "POST",
-    body: {
-      reason: normalizeQRRefreshReasonForCLI(flags.reason || flags.refresh_reason || "order_not_found")
-    }
-  }, flags);
-}
-
-function normalizeQRRefreshReasonForCLI(reason) {
-  const normalized = String(reason || "").trim().toLowerCase().replaceAll("-", "_");
-  if (["order_not_found", "qr_unavailable", "manual_refresh", "human_open"].includes(normalized)) return normalized;
-  return "manual_refresh";
-}
-
-async function renderItPayPaymentAction(intent, flags = {}) {
-  const action = intent?.human_action ? { ...intent.human_action } : (intent?.payment_url ? {
-    id: intent.payment_intent_id,
-    title: "Scan with Alipay",
-    url: intent.payment_url,
-    expires_at: intent.qr?.expires_at
-  } : null);
-  if (action) {
-    if (intent?.qr_png_url || intent?.qr?.png_url) {
-      action.qr_png_url = intent.qr_png_url || intent.qr.png_url;
-    }
-    if (intent?.mobile_wallet_url) {
-      action.mobile_wallet_url = intent.mobile_wallet_url;
-    }
-  }
-  if (action && (intent?.qr_image_url || intent?.qr?.image_url)) {
-    action.qr_image_url = intent.qr_image_url || intent.qr.image_url;
-    action.display_mode = intent.qr?.scan_mode || "itpay_entry_qr";
-    action.description = action.description || "Scan the ItPay payment entry QR; ItPay will safely hand off to Alipay.";
-  }
-  const result = await renderHumanAction(action, flags);
-  if (intent && action) {
-    intent.human_action = { ...(intent.human_action || {}), ...action };
-    if (action.local_qr_path) intent.local_qr_path = action.local_qr_path;
-    if (action.preferred_qr_url) intent.preferred_qr_url = action.preferred_qr_url;
-    if (action.mobile_wallet_url) intent.mobile_wallet_url = action.mobile_wallet_url;
-  }
-  return result;
-}
-
-async function waitBuyerPayment(intent, flags = {}) {
-  const paymentIntentID = intent?.payment_intent_id || intent;
-  if (!paymentIntentID) throw new Error("payment_intent_id is required");
-  let cursor = flags.cursor || intent?.agent_wait?.cursor || "";
-  const waitURL = flags.wait_url || intent?.agent_wait?.wait_url || `/v1/payment-intents/${encodeURIComponent(paymentIntentID)}/events/wait`;
-  const timeoutMs = Number(flags.timeout || 900) * 1000;
-  const started = Date.now();
-  let lastHeartbeatAt = 0;
-  let lastEvent = null;
-  while (Date.now() - started < timeoutMs) {
-    const params = new URLSearchParams();
-    if (cursor) params.set("cursor", cursor);
-    params.set("timeout", String(flags.poll_timeout || "30s"));
-    const event = await coreApi(appendURLQuery(waitURL, params), { method: "GET" }, flags);
-    lastEvent = event;
-    cursor = event.cursor || cursor;
-    if (event.event_type === "payment_intent.verified") return event;
-    if (event.event_type && event.event_type !== "wait.timeout") return event;
-    lastHeartbeatAt = writeWaitHeartbeat({
-      kind: "ItPay payment notify",
-      idName: "payment_intent_id",
-      idValue: paymentIntentID,
-      status: event.event_type === "wait.timeout" ? "still_waiting" : (event.event_type || "still_waiting"),
-      action: intent?.human_action || null,
-      lastHeartbeatAt,
-      flags,
-      command: cliCommand("buyer", "payment", "wait", paymentIntentID, "--json")
-    });
-  }
-  return lastEvent || { event_type: "wait.timeout", payment_intent_id: paymentIntentID, cursor, agent_next_actions: ["wait_payment"] };
-}
-
-async function waitBuyerDelivery(checkoutID, flags = {}) {
-  const timeoutMs = Number(flags.delivery_timeout || 30) * 1000;
-  const started = Date.now();
-  let checkout = await getBuyerCheckout(checkoutID, flags);
-  while (!isBuyerDeliveryComplete({ checkout }) && Date.now() - started < timeoutMs) {
-    await sleep(Number(flags.delivery_poll_ms || 2000));
-    checkout = await getBuyerCheckout(checkoutID, flags);
-  }
-  return { checkout, delivery: checkout.delivery || null };
-}
-
-function isBuyerDeliveryComplete(result) {
-  const checkout = result?.checkout || result || {};
-  const delivery = checkout.delivery || result?.delivery || {};
-  return checkout.delivery_status === "delivered" ||
-    delivery.status === "delivery_claimable" ||
-    delivery.next_required_action === "check_email" ||
-    checkout.agent_next_actions?.includes("stop_check_email");
-}
-
-function buyerRunOutput(value = {}) {
-  return normalizeBuyerMoneyFields(stripInternalBuyerFields({
-    schema_version: "itp.buyer.v1",
-    docs: value.docs || buyerDocsFor(value),
-    ...value,
-    secrets: {
-      raw_content_included: false,
-      claim_token_included: false,
-      provider_raw_payload_included: false
-    }
-  }));
-}
-
-function normalizeBuyerMoneyFields(value) {
-  if (Array.isArray(value)) return value.map((item) => normalizeBuyerMoneyFields(item));
-  if (!value || typeof value !== "object") return value;
-  const next = {};
-  for (const [key, item] of Object.entries(value)) {
-    next[key] = normalizeBuyerMoneyFields(item);
-  }
-  if (
-    typeof next.amount === "number" &&
-    Number.isFinite(next.amount) &&
-    typeof next.currency === "string" &&
-    next.currency.trim()
-  ) {
-    const currency = next.currency.trim().toUpperCase();
-    next.amount_minor = Number.isInteger(next.amount) ? next.amount : Math.round(next.amount);
-    next.amount_major = Number((next.amount_minor / 100).toFixed(2));
-    next.display_amount = `${currency} ${(next.amount_minor / 100).toFixed(2)}`;
-    next.amount_unit = "minor";
-  }
-  return next;
-}
-
-function buyerDocsFor(value = {}) {
-  const topics = new Set();
-  const status = String(value.status || "").toLowerCase();
-  const actions = Array.isArray(value.agent_next_actions) ? value.agent_next_actions : [];
-  if (status.includes("catalog")) topics.add("catalog-search");
-  if (status.includes("cart") || actions.includes("create_checkout_from_cart")) topics.add("cart-checkout");
-  if (status.includes("checkout") || actions.includes("create_payment_intent")) topics.add("cart-checkout");
-  if (status.includes("human_auth") || actions.includes("wait_human_auth") || value.human_action?.kind === "auth_qr" || value.checkout?.human_action?.kind === "auth_qr") {
-    topics.add("cart-checkout");
-    topics.add("payment-qr");
-  }
-  if (status.includes("waiting_user_payment") || actions.includes("wait_payment") || value.payment_intent?.human_action || value.payment_intent?.qr_image_url) {
-    topics.add("payment-qr");
-    topics.add("payment-wait");
-  }
-  if (status.includes("payment_verified") || value.payment_event?.event_type === "payment_intent.verified") topics.add("secure-delivery");
-  if (status.includes("delivery") || value.delivery || actions.includes("stop_check_email")) {
-    topics.add("secure-delivery");
-    topics.add("human-claim-ui");
-    topics.add("vault-agent-read");
-  }
-  if (status.includes("agent_read_grant") || value.agent_readable_grants || value.grant || actions.includes("read_agent_grant_view") || actions.includes("list_agent_read_grants")) {
-    topics.add("vault-agent-read");
-  }
-  if (topics.size === 0) topics.add("quickstart");
-  return Array.from(topics).map((topic) => buyerDocRef(topic));
-}
-
-function buyerDocRef(topic) {
-  return {
-    topic,
-    command: cliCommand("docs", "show", topic, "--role", "buyer", "--json")
-  };
-}
-
-function buyerDeliveryListOutput(checkout) {
-  const delivery = checkout.delivery || null;
-  const checkoutID = checkout.checkout_id;
-  return buyerRunOutput({
-    status: delivery?.status || checkout.delivery_status,
-    checkout_id: checkoutID,
-    deliveries: delivery ? [{
-      checkout_id: checkoutID,
-      status: delivery.status,
-      next_required_action: delivery.next_required_action,
-      channels: delivery.channels || [],
-      artifact_status: delivery.artifact_status,
-      sensitive_content_redacted: delivery.sensitive_content_redacted !== false
-    }] : [],
-    agent_next_actions: deliveryAwareAgentNextActions(checkout),
-    optional_agent_read_grant: optionalAgentReadGrantHint(checkoutID, checkout)
-  });
-}
-
-function deliveryAwareAgentNextActions(checkout = {}) {
-  const actions = Array.isArray(checkout.agent_next_actions) ? [...checkout.agent_next_actions] : [];
-  if (isBuyerDeliveryComplete(checkout) && !actions.includes("optionally_request_agent_read_grant")) {
-    actions.push("optionally_request_agent_read_grant");
-  }
-  return actions;
-}
-
-function optionalAgentReadGrantHint(checkoutID, checkout = {}) {
-  if (!checkoutID || !isBuyerDeliveryComplete(checkout)) return undefined;
-  return {
-    type: "optional_human_passkey_agent_read_grant",
-    safe_for_agent: true,
-    requires_human: true,
-    instruction: "If the human wants you to analyze or use the delivered result, ask them to open the ItPay claim/account page, reveal with Passkey, choose 'Give to Agent / 一键给 Agent', select fields, and confirm. After they approve, do not ask for a grant id; run the probe command.",
-    docs_command: cliCommand("docs", "show", "vault-agent-read", "--role", "buyer", "--json"),
-    probe_command: cliCommand("buyer", "vault", "grants", "list", "--checkout", checkoutID, "--json"),
-    read_pattern: cliCommand("buyer", "vault", "read", "--order", "<order_id>", "--artifact", "<vault_artifact_id>", "--json")
-  };
-}
-
-async function buyerAuthStatusOutput(flags = {}) {
-  const config = readConfig();
-  const credentials = readCredentials();
-  const token = readSessionToken(credentials);
-  if (token && config.account_id) {
-    try {
-      const status = await coreApi("/v1/me/auth/status", { method: "GET" }, flags);
-      return buyerRunOutput({
-        status: "authenticated_buyer_session",
-        authenticated: true,
-        buyer_account_id: status.buyer_account_id || config.account_id,
-        agent_device_id: config.device_id || null,
-        account_status: status.account_status,
-        sensitive_redacted: true,
-        agent_next_actions: ["search_catalog", "view_orders", "list_agent_read_grants"]
-      });
-    } catch (error) {
-      return buyerRunOutput({
-        status: "buyer_session_invalid",
-        authenticated: false,
-        buyer_account_id: config.account_id || null,
-        agent_device_id: config.device_id || null,
-        error: safeErrorMessage(error),
-        agent_next_actions: ["create_checkout_for_human_auth"]
-      });
-    }
-  }
-  return buyerRunOutput({
-    status: "public_purchase_mode",
-    authenticated: false,
-    auth_required_for_discovery: false,
-    agent_next_actions: ["search_catalog", "create_checkout_for_human_auth"],
-    note: "Catalog discovery is public. Checkout creates a human auth-to-payment QR and saves a buyer session after the human authorizes."
-  });
-}
-
-async function listBuyerAgentReadGrants(flags = {}) {
-  const params = new URLSearchParams();
-  const mappings = [
-    ["checkout", "checkout_id"],
-    ["checkout_id", "checkout_id"],
-    ["order", "order_id"],
-    ["order_id", "order_id"],
-    ["artifact", "vault_artifact_id"],
-    ["vault_artifact", "vault_artifact_id"],
-    ["vault_artifact_id", "vault_artifact_id"],
-    ["line", "order_line_item_id"],
-    ["line_id", "order_line_item_id"],
-    ["order_line_item_id", "order_line_item_id"]
-  ];
-  for (const [flagName, paramName] of mappings) {
-    if (flags[flagName] !== undefined && flags[flagName] !== null && flags[flagName] !== false) {
-      params.set(paramName, String(flags[flagName]));
-    }
-  }
-  const query = params.toString();
-  return await coreApi(`/v1/me/agent-grants${query ? `?${query}` : ""}`, { method: "GET" }, flags);
-}
-
-async function readBuyerAgentReadGrant(grantID, flags = {}) {
-  if (!grantID) throw new Error("agent_read_grant_id is required");
-  return await coreApi(`/v1/me/agent-grants/${encodeURIComponent(grantID)}/view`, { method: "GET" }, flags);
-}
-
-async function readBuyerVaultArtifactGrant(flags = {}) {
-  const grants = await listBuyerAgentReadGrants(flags);
-  const list = Array.isArray(grants.agent_readable_grants) ? grants.agent_readable_grants : [];
-  if (!list.length) {
-    throw new Error("no active agent-readable grant found; ask the human to open the account portal and confirm one-key agent authorization with Passkey");
-  }
-  const grant = list[0];
-  const grantID = grant.agent_read_grant_id || grant.agent_readGrantID;
-  if (!grantID) throw new Error("active grant did not include agent_read_grant_id");
-  const view = await readBuyerAgentReadGrant(grantID, flags);
-  return {
-    ...view,
-    discovered_grant: grant
-  };
-}
-
-async function agentStatus(flags) {
-  const runId = flags.run_id || readState().current_run_id;
-  const run = readRun(runId);
-  if (!run) {
-    const config = readConfig();
-    const credentials = readCredentials();
-    const hasLocalSession = Boolean(readSessionToken(credentials));
-    const auth = flags.refresh
-      ? await refreshBuyerSessionForStatus(flags)
-      : {
-          authenticated: hasLocalSession,
-          session_verified: false,
-          account_id: config.account_id || null,
-          device_id: config.device_id || null,
-          auth_source: hasLocalSession ? "local_files_unverified" : "local_files"
-        };
-    output({
-      schema_version: "itp.agent.v1",
-      status: auth.authenticated
-        ? (auth.session_verified === false ? "local_session_unverified" : "idle")
-        : "unauthenticated",
-      phase: auth.authenticated ? "idle" : "unauthenticated",
-      authenticated: Boolean(auth.authenticated),
-      session_verified: auth.session_verified !== false,
-      auth_source: auth.auth_source,
-      account_id: auth.account_id || null,
-      device_id: auth.device_id || null,
-      next: nextActionForAuthStatus(auth, flags),
-      agent_next_actions: auth.authenticated && auth.session_verified !== false
-        ? ["search_catalog", "view_orders", "create_refund_if_needed", "list_agent_read_grants"]
-        : ["run_status_refresh", "start_human_auth_if_unauthenticated"],
-      note: auth.authenticated && auth.session_verified === false
-        ? "Local buyer session exists but the server has not verified it. Run the next.command before order/refund/account operations."
-        : undefined,
-      error: auth.error || undefined,
-      secrets: { raw_key_included: false, session_token_included: false }
-    });
-    return;
-  }
-  const refreshed = flags.refresh ? await refreshRun(run, flags) : run;
-  writeRun(refreshed);
-  output(agentRunResponse(refreshed));
-}
-
-async function refreshBuyerSessionForStatus(flags = {}) {
-  const config = readConfig();
-  const credentials = readCredentials();
-  if (!readSessionToken(credentials)) {
-    return {
-      authenticated: false,
-      session_verified: true,
-      account_id: config.account_id || null,
-      device_id: config.device_id || null,
-      auth_source: "core_no_session"
-    };
-  }
-  try {
-    const status = await coreApi("/v1/me/auth/status", { method: "GET" }, flags);
-    return {
-      authenticated: true,
-      session_verified: true,
-      account_id: status.buyer_account_id || config.account_id || null,
-      device_id: config.device_id || null,
-      account_status: status.account_status || null,
-      auth_source: "core"
-    };
-  } catch (error) {
-    return {
-      authenticated: false,
-      session_verified: true,
-      account_id: config.account_id || null,
-      device_id: config.device_id || null,
-      auth_source: "core",
-      error: safeErrorMessage(error)
-    };
-  }
-}
-
-function nextActionForAuthStatus(auth = {}, flags = {}) {
-  if (auth.authenticated && auth.session_verified === false) {
-    return { type: "verify_buyer_session", command: cliCommand("status", "--refresh", "--json"), safe_for_agent: true };
-  }
-  if (auth.authenticated) {
-    return { type: "buyer_ready", command: cliCommand("buyer", "auth", "status", "--json"), safe_for_agent: true };
-  }
-  return { type: "start_auth", command: cliCommand("setup", "--plan", "credit-300", "--method", "alipay", "--json"), safe_for_agent: true };
-}
-
-async function resume(flags) {
-  const runId = flags.run_id || readState().current_run_id;
-  const run = readRun(runId);
-  if (!run) throw new Error("no active run found");
-  if (["done", "installed"].includes(run.status) || run.phase === "done") {
-    output(agentRunResponse(run));
-    return;
-  }
-  await setup({
-    ...flags,
-    run_id: run.run_id,
-    resume: true,
-    plan: run.plan_id || flags.plan,
-    credits: run.plan_id ? flags.credits : run.credits || flags.credits,
-    method: run.payment_method || flags.method,
-    target: run.target || flags.target,
-    install_runtime: run.install_runtime || flags.install_runtime
-  });
-}
-
-async function runs(command, flags) {
-  if (command === "current") {
-    const run = readRun(flags.run_id || readState().current_run_id);
-    output(run ? agentRunResponse(run) : { schema_version: "itp.agent.v1", status: "none", runs: [] });
-    return;
-  }
-  if (command === "list") {
-    output({ runs: listRuns().map(agentRunResponse) });
-    return;
-  }
-  if (command === "show") {
-    const run = readRun(flags.run_id || flags.id);
-    if (!run) throw new Error("run not found");
-    output(agentRunResponse(run));
-    return;
-  }
-  if (command === "forget") {
-    const runId = flags.run_id || flags.id;
-    if (!runId || runId === "forget") throw new Error("run_id is required");
-    const file = runPath(runId);
-    if (fs.existsSync(file)) fs.unlinkSync(file);
-    const state = readState();
-    if (state.current_run_id === runId) {
-      delete state.current_run_id;
-      writeState(state);
-    }
-    output({ status: "forgotten", run_id: runId });
-    return;
-  }
-  throw new Error(`unknown runs command: ${command || ""}`);
-}
-
-async function startDeviceAuth(flags) {
-  const runtime = flags.runtime || "unknown";
-  return await api("/api/itp/auth/device/start", {
-    method: "POST",
-    body: {
-      device: {
-        display_name: os.hostname(),
-        runtime,
-        os: os.platform(),
-        arch: os.arch(),
-        itp_version: VERSION
-      }
-    }
-  }, flags);
-}
-
-async function completeDeviceAuth(flags) {
-  const start = await startDeviceAuth(flags);
-  if (flags.no_wait) {
-    writeState({ ...readState(), last_auth_id: start.auth_id });
-    updateCurrentRun({
-      phase: "waiting_human_auth",
-      auth: { auth_id: start.auth_id, status: "pending", expires_at: start.expires_at },
-      human_action: start.human_action || null,
-      safe_summary: "Waiting for Alipay authentication scan."
-    }, flags);
-    await renderHumanAction(start.human_action, flags);
-    return start;
-  }
-  await maybeMockApproveDeviceAuth(start.auth_id, flags);
-  const response = await waitDeviceAuth(start.auth_id, flags, start);
-  if (!response.auth) {
-    throw new Error(`device auth ended without session: ${response.status || "unknown"}`);
-  }
-  writeSessionCredentials(response.auth);
-  writeConfig({
-    api_base: apiBase(flags),
-    account_id: response.auth.account_id,
-    device_id: response.auth.device_id,
-    web_console_url: response.auth.web_console_url
-  });
-  writeState({ ...readState(), last_auth_id: start.auth_id });
-  return { ...sanitizeAuthResponse(response.auth), auth_id: start.auth_id, status: response.status };
-}
-
-async function ensureAuthenticated(flags) {
-  const config = readConfig();
-  const credentials = readCredentials();
-  if (readSessionToken(credentials)) {
-    try {
-      const status = await api("/api/itp/auth/status", { method: "GET" }, flags);
-      if (status.authenticated !== false) {
-        return {
-          authenticated: true,
-          account_id: status.account_id || config.account_id || null,
-          device_id: status.device_id || config.device_id || null,
-          newapi_user_id: status.newapi_user_id || null,
-          session_reused: true
-        };
-      }
-    } catch {
-      deleteSessionCredential(credentials);
-      writeCredentials(credentials);
-    }
-  }
-  const resumableRun = readRun(flags.run_id || readState().current_run_id);
-  if ((flags.resume || flags.auth_id) && resumableRun?.auth?.auth_id && !resumableRun.account?.authenticated && !resumableRun.checkout?.checkout_id && !flags.no_wait && !flags.no_wait_auth) {
-    await renderHumanAction(resumableRun.human_action, flags);
-    await maybeMockApproveDeviceAuth(resumableRun.auth.auth_id, flags);
-    const response = await waitDeviceAuth(resumableRun.auth.auth_id, flags);
-    if (!response.auth) {
-      return {
-        authenticated: false,
-        status: response.status || "waiting_human_auth",
-        auth_id: resumableRun.auth.auth_id,
-        expires_at: resumableRun.auth.expires_at,
-        human_action: resumableRun.human_action
-      };
-    }
-    writeSessionCredentials(response.auth);
-    writeConfig({
-      api_base: apiBase(flags),
-      account_id: response.auth.account_id,
-      device_id: response.auth.device_id,
-      web_console_url: response.auth.web_console_url
-    });
-    writeState({ ...readState(), last_auth_id: resumableRun.auth.auth_id });
-    return { ...sanitizeAuthResponse(response.auth), auth_id: resumableRun.auth.auth_id, authenticated: true, session_reused: false };
-  }
-  if (flags.no_wait || flags.no_wait_auth) {
-    const start = await startDeviceAuth(flags);
-    writeState({ ...readState(), last_auth_id: start.auth_id });
-    updateCurrentRun({
-      phase: "waiting_human_auth",
-      auth: { auth_id: start.auth_id, status: "pending", expires_at: start.expires_at },
-      human_action: start.human_action || null,
-      safe_summary: "Waiting for Alipay authentication scan."
-    }, flags);
-    await renderHumanAction(start.human_action, flags);
-    return {
-      authenticated: false,
-      status: "waiting_human_auth",
-      action: "scan_alipay_auth",
-      auth_id: start.auth_id,
-      user_code: start.user_code,
-      verification_uri: start.verification_uri,
-      verification_uri_complete: start.verification_uri_complete,
-      alipay_authorization_url: start.alipay_authorization_url,
-      expires_at: start.expires_at,
-      interval: start.interval,
-      human_action: start.human_action
-    };
-  }
-  const auth = await completeDeviceAuth(flags);
-  return { ...auth, authenticated: true, session_reused: false };
-}
-
-async function maybeMockApproveDeviceAuth(authId, flags) {
-  if (!(flags.mock_approve || process.env.ITPAY_MOCK_APPROVE === "true" || process.env.ITPAY_MOCK_APPROVE === "1")) {
-    return;
-  }
-  if (!fakeTestingAllowed(flags)) {
-    throw new Error("mock approval is developer-only and disabled for agent runs; use real Alipay sandbox authentication");
-  }
-  const alipayUserId = flags.alipay_user_id || process.env.ITPAY_MOCK_ALIPAY_USER_ID || `2088${crypto.randomInt(100000000000, 999999999999)}`;
-  await api(`/api/itp/auth/device/${encodeURIComponent(authId)}/mock-approve`, {
-    method: "POST",
-    body: { alipay_user_id: alipayUserId }
-  }, flags);
-}
-
-async function authDevice(command, flags) {
-  if (command === "start") {
-    const response = await startDeviceAuth(flags);
-    writeState({ ...readState(), last_auth_id: response.auth_id });
-    await renderHumanAction(response.human_action, flags);
-    output(response);
-    return;
-  }
-  if (command === "poll") {
-    const authId = flags.auth_id || flags.device_auth_id || readState().last_auth_id;
-    if (!authId) throw new Error("auth_id is required");
-    const response = await waitDeviceAuth(authId, flags);
-    if (response.auth) {
-      writeSessionCredentials(response.auth);
-      writeConfig({
-        api_base: apiBase(flags),
-        account_id: response.auth.account_id,
-        device_id: response.auth.device_id,
-        web_console_url: response.auth.web_console_url
-      });
-    }
-    output(response.auth ? { ...sanitizeAuthResponse(response.auth), auth_id: authId, status: response.status } : response);
-    return;
-  }
-  throw new Error(`unknown auth device command: ${command || ""}`);
-}
-
-async function waitDeviceAuth(authId, flags, start = null) {
-  const started = Date.now();
-  const timeoutMs = Number(flags.timeout || 600) * 1000;
-  let intervalMs = 2000;
-  let lastHeartbeatAt = 0;
-  let lastStatus = "authorization_pending";
-  const action = start?.human_action || null;
-  if (start) {
-    updateCurrentRun({
-      phase: "waiting_human_auth",
-      auth: { auth_id: start.auth_id, status: "pending", expires_at: start.expires_at },
-      human_action: start.human_action || null,
-      safe_summary: "Waiting for Alipay authentication scan."
-    }, flags);
-    await renderHumanAction(start.human_action, flags);
-    if (!start.human_action) process.stderr.write(`Open Alipay auth URL: ${start.verification_uri_complete || start.alipay_authorization_url}\n`);
-    if (start.user_code) process.stderr.write(`Alipay auth code: ${start.user_code}\n`);
-  }
-  while (Date.now() - started < timeoutMs) {
-    const response = await api(`/api/itp/auth/device/${encodeURIComponent(authId)}/poll`, { method: "POST" }, flags);
-    lastStatus = response.status || lastStatus;
-    if (response.auth?.session_token) {
-      return response;
-    }
-    if (response.status === "authorization_pending") {
-      intervalMs = Number(response.interval || 2) * 1000;
-      lastHeartbeatAt = writeWaitHeartbeat({
-        kind: "Alipay authentication",
-        idName: "auth_id",
-        idValue: authId,
-        status: response.status,
-        action,
-        lastHeartbeatAt,
-        flags,
-        command: cliCommand("auth", "device", "poll", authId, "--timeout", String(Math.ceil((timeoutMs - (Date.now() - started)) / 1000)), "--json")
-      });
-      await sleep(intervalMs);
-      continue;
-    }
-    if (response.status === "approved") {
-      return response;
-    }
-    if (response.status === "expired" || response.status === "consumed" || response.error) {
-      throw new Error(response.error || `device auth ended with status: ${response.status}`);
-    }
-    await sleep(intervalMs);
-  }
-  throw new Error(`device auth timed out at status ${lastStatus}; run \`itp auth device poll ${authId} --timeout 600\``);
-}
-
-async function authLogin(flags) {
-  const runtime = flags.runtime || "unknown";
-  if (flags.password && !flags.password_stdin) {
-    throw new Error("use --password-stdin to avoid leaking passwords into shell history");
-  }
-  const password = flags.password_stdin
-    ? fs.readFileSync(0, "utf8").trim()
-    : undefined;
-  if (flags.password_stdin && !password) {
-    throw new Error("password is required on stdin");
-  }
-  const response = await api("/api/itp/auth/login", {
-    method: "POST",
-    body: {
-      username: flags.username || undefined,
-      password,
-      access_token: flags.access_token || undefined,
-      device: {
-        display_name: os.hostname(),
-        runtime,
-        os: os.platform(),
-        arch: os.arch(),
-        itp_version: VERSION
-      }
-    }
-  }, flags);
-  writeSessionCredentials(response);
-  writeConfig({
-    api_base: apiBase(flags),
-    account_id: response.account_id,
-    device_id: response.device_id,
-    web_console_url: response.web_console_url
-  });
-  output(sanitizeAuthResponse(response));
-}
-
-async function authStatus(flags) {
-  const config = readConfig();
-  const credentials = readCredentials();
-  if (!readSessionToken(credentials)) {
-    output({ authenticated: false, account_id: config.account_id || null });
-    return;
-  }
-  try {
-    const status = await api("/api/itp/auth/status", { method: "GET" }, flags);
-    output(status);
-  } catch (error) {
-    output({
-      authenticated: false,
-      account_id: config.account_id || null,
-      error: error.message
-    });
-  }
-}
-
-async function accountShow(flags) {
-  output(await api("/api/itp/account", { method: "GET" }, flags));
-}
-
-async function accountLoginLink(flags) {
-  const config = readConfig();
-  const accountID = flags.account || flags.account_id || flags.buyer_account || flags.buyer_account_id || config.account_id;
-  if (!accountID) {
-    throw new Error("buyer account id is required; complete a buyer purchase first or pass --account-id");
-  }
-  if (!readSessionToken()) {
-    throw new Error("buyer account session is required; complete first-purchase auth or run buyer checkout resume first");
-  }
-  const link = await coreApi("/v1/me/portal-login-links", { method: "POST" }, flags);
-  output(buyerRunOutput({
-    status: "account_portal_login_link_created",
-    account_id: accountID,
-    portal_login_link: link,
-    login_url: link.login_url,
-    expires_at: link.expires_at,
-    agent_next_actions: link.agent_next_actions || ["show_login_link_to_human_only"],
-    next: {
-      type: "human_open_account_portal_link",
-      safe_for_agent: false,
-      requires_human: true,
-      agent_must_not_open: true,
-      instruction: "Give this one-time ItPay account portal link to the human buyer. Do not open it yourself; the human portal is redacted and protected content stays locked until human reveal."
-    }
-  }));
-}
-
-async function accountSetPassword(flags) {
-  if (!flags.password_stdin) {
-    throw new Error("use --password-stdin to avoid leaking passwords into shell history");
-  }
-  const password = fs.readFileSync(0, "utf8").trim();
-  if (!password) throw new Error("password is required on stdin");
-  output(await api("/api/itp/account/password", {
-    method: "POST",
-    body: { password }
-  }, flags));
-}
-
-async function plansList(flags) {
-  output(await api("/api/itp/plans", { method: "GET" }, flags));
-}
-
-async function plansShow(plan, flags) {
-  if (!plan) throw new Error("plan id is required");
-  output(await api(`/api/itp/plans/${encodeURIComponent(plan)}`, { method: "GET" }, flags));
-}
-
-async function checkoutCreate(flags) {
-  const response = await createCheckoutResult(flags);
-  await renderHumanAction(response.human_action, flags);
-  output(response);
-}
-
-async function createCheckoutResult(flags) {
-  const purchase = normalizePurchaseFlags(flags, true);
-  const method = flags.method || "alipay";
-  validateLivePaymentFlags(method, flags);
-  const currentRun = readRun(flags.run_id || readState().current_run_id);
-  const idempotencyKey = flags.idempotency_key || currentRun?.idempotency_key || cryptoRandom();
-  const body = {
-    payment_method: method,
-    idempotency_key: idempotencyKey
-  };
-  if (purchase.plan) body.plan_id = purchase.plan;
-  if (purchase.credits) body.credits = purchase.credits;
-  const response = await api("/api/itp/checkout", {
-    method: "POST",
-    body
-  }, flags);
-  writeState({ ...readState(), last_checkout_id: response.checkout_id, last_grant_id: response.grant_id || null });
-  updateCurrentRun({
-    phase: response.grant_id ? "grant_ready" : "waiting_human_payment",
-    plan_id: response.plan_id || purchase.plan || null,
-    credits: response.credits || purchase.credits || null,
-    purchase_kind: response.purchase?.kind || purchase.kind,
-    checkout: {
-      checkout_id: response.checkout_id,
-      order_id: response.order_id,
-      status: response.status,
-      expires_at: response.expires_at,
-      purchase: response.purchase || null
-    },
-    payment: {
-      provider: method,
-      status: response.status
-    },
-    grant: {
-      ...(currentRun?.grant || {}),
-      grant_id: response.grant_id || currentRun?.grant?.grant_id || null
-    },
-    human_action: response.human_action || null,
-    safe_summary: response.grant_id ? "Payment verified and grant is ready." : "Waiting for Alipay payment scan."
-  }, flags);
-  return response;
-}
-
-function validateLivePaymentFlags(method, flags = {}) {
-  if (String(method).toLowerCase() === "fake" && !fakeTestingAllowed(flags)) {
-    throw new Error("fake payment is developer-only and disabled for agent runs; use --method alipay for local, sandbox, and live testing");
-  }
-  if ((flags.mock_approve || process.env.ITPAY_MOCK_APPROVE === "true" || process.env.ITPAY_MOCK_APPROVE === "1") && !fakeTestingAllowed(flags)) {
-    throw new Error("mock approval is developer-only and disabled for agent runs; use real Alipay sandbox authentication");
-  }
-}
-
-function fakeTestingAllowed(flags = {}) {
-  return flags.allow_fake || process.env.ITP_ALLOW_FAKE_PAYMENT === "true" || process.env.ITP_ALLOW_FAKE_PAYMENT === "1";
-}
-
-async function paymentWait(checkoutId, flags) {
-  output(await paymentWaitResult(checkoutId, flags));
-}
-
-async function paymentWaitResult(checkoutId, flags) {
-  if (!checkoutId) throw new Error("checkout_id is required");
-  const started = Date.now();
-  const timeoutMs = Number(flags.timeout || 120) * 1000;
-  let lastRecoverAt = 0;
-  let lastHeartbeatAt = 0;
-  let lastResponse = null;
-  while (Date.now() - started < timeoutMs) {
-    let response = await api(`/api/itp/checkout/${encodeURIComponent(checkoutId)}`, { method: "GET" }, flags);
-    lastResponse = response;
-    if (isTerminalCheckoutFailure(response.status)) {
-      throw new Error(`checkout ended with status: ${response.status}`);
-    }
-    if (isSuccessfulCheckout(response)) {
-      writeState({ ...readState(), last_checkout_id: checkoutId, last_grant_id: response.grant_id });
-      updateCurrentRun({
-        phase: "grant_ready",
-        checkout: { checkout_id: checkoutId, order_id: response.order_id, status: response.status, expires_at: response.expires_at },
-        grant: { grant_id: response.grant_id, installed: false },
-        human_action: null,
-        safe_summary: "Payment verified and grant is ready."
-      }, flags);
-      return { status: "grant_issued", checkout_id: checkoutId, order_id: response.order_id, grant_id: response.grant_id };
-    }
-    if (shouldRecoverCheckout(response.status) && Date.now() - lastRecoverAt > 5000) {
-      lastRecoverAt = Date.now();
-      response = await api(`/api/itp/checkout/${encodeURIComponent(checkoutId)}/recover`, { method: "POST" }, flags);
-      lastResponse = response;
-      if (isTerminalCheckoutFailure(response.status)) {
-        throw new Error(`checkout ended with status: ${response.status}`);
-      }
-      if (isSuccessfulCheckout(response)) {
-        writeState({ ...readState(), last_checkout_id: checkoutId, last_grant_id: response.grant_id });
-        updateCurrentRun({
-          phase: "grant_ready",
-          checkout: { checkout_id: checkoutId, order_id: response.order_id, status: response.status, expires_at: response.expires_at },
-          grant: { grant_id: response.grant_id, installed: false },
-          human_action: null,
-          safe_summary: "Payment verified and grant is ready."
-        }, flags);
-        return { status: "grant_issued", checkout_id: checkoutId, order_id: response.order_id, grant_id: response.grant_id, recovered: true };
-      }
-    }
-    lastHeartbeatAt = writeWaitHeartbeat({
-      kind: "Alipay payment",
-      idName: "checkout_id",
-      idValue: checkoutId,
-      status: response.status || "waiting",
-      action: response.human_action || null,
-      lastHeartbeatAt,
-      flags,
-      command: cliCommand("payment", "wait", checkoutId, "--timeout", String(Math.ceil((timeoutMs - (Date.now() - started)) / 1000)), "--json")
-    });
-    await sleep(2000);
-  }
-  try {
-    const response = await api(`/api/itp/checkout/${encodeURIComponent(checkoutId)}/recover`, { method: "POST" }, flags);
-    lastResponse = response;
-    if (isTerminalCheckoutFailure(response.status)) {
-      throw new Error(`checkout ended with status: ${response.status}`);
-    }
-    if (isSuccessfulCheckout(response)) {
-      writeState({ ...readState(), last_checkout_id: checkoutId, last_grant_id: response.grant_id });
-      updateCurrentRun({
-        phase: "grant_ready",
-        checkout: { checkout_id: checkoutId, order_id: response.order_id, status: response.status, expires_at: response.expires_at },
-        grant: { grant_id: response.grant_id, installed: false },
-        human_action: null,
-        safe_summary: "Payment verified and grant is ready."
-      }, flags);
-      return { status: "grant_issued", checkout_id: checkoutId, order_id: response.order_id, grant_id: response.grant_id, recovered: true };
-    }
-  } catch (error) {
-    if (isTerminalCheckoutFailure(lastResponse?.status)) {
-      throw error;
-    }
-    // Preserve the timeout message below; recover is a best-effort final attempt.
-  }
-  if (lastResponse?.status) {
-    throw new Error(`payment wait timed out at checkout status ${lastResponse.status}; run \`itp checkout recover ${checkoutId}\` later`);
-  }
-  throw new Error("payment wait timed out; run `itp checkout recover` later");
-}
-
-async function checkoutRecover(checkoutId, flags) {
-  if (!checkoutId) throw new Error("checkout_id is required");
-  const response = await api(`/api/itp/checkout/${encodeURIComponent(checkoutId)}/recover`, { method: "POST" }, flags);
-  if (response.grant_id) {
-    writeState({ ...readState(), last_checkout_id: checkoutId, last_grant_id: response.grant_id });
-  }
-  output(response);
-}
-
-async function checkoutOpen(flags) {
-  const state = readState();
-  if (!state.last_checkout_id) throw new Error("no checkout found in local state");
-  const response = await api(`/api/itp/checkout/${encodeURIComponent(state.last_checkout_id)}`, { method: "GET" }, flags);
-  output(response.payment || response);
-}
-
-async function checkoutQR(checkoutId, flags) {
-  if (!checkoutId) throw new Error("checkout_id is required");
-  const response = await api(`/api/itp/checkout/${encodeURIComponent(checkoutId)}/qr`, { method: "GET" }, flags);
-  await renderHumanAction(response.human_action, flags);
-  output(response);
-}
-
-async function checkoutList(flags) {
-  const params = new URLSearchParams();
-  if (flags.limit) params.set("limit", flags.limit);
-  const suffix = params.toString() ? `?${params.toString()}` : "";
-  output(await api(`/api/itp/orders${suffix}`, { method: "GET" }, flags));
-}
-
-async function balance(flags) {
-  output(await api("/api/itp/balance", { method: "GET" }, flags));
-}
-
-async function usage(flags) {
-  const params = new URLSearchParams();
-  if (flags.model) params.set("model", flags.model);
-  if (flags.grant) params.set("grant_id", flags.grant);
-  if (flags.grant_id) params.set("grant_id", flags.grant_id);
-  if (flags.from) params.set("from", flags.from);
-  if (flags.to) params.set("to", flags.to);
-  if (flags.today) {
-    const start = new Date();
-    start.setHours(0, 0, 0, 0);
-    params.set("from", Math.floor(start.getTime() / 1000).toString());
-  }
-  const suffix = params.toString() ? `?${params.toString()}` : "";
-  output(await api(`/api/itp/usage${suffix}`, { method: "GET" }, flags));
-}
-
-async function grantsList(flags) {
-  output(await api("/api/itp/grants", { method: "GET" }, flags));
-}
-
-async function grantsShow(grantId, flags) {
-  if (!grantId) throw new Error("grant_id is required");
-  output(await api(`/api/itp/grants/${encodeURIComponent(grantId)}`, { method: "GET" }, flags));
-}
-
-async function grantsInstall(grantId, flags) {
-  output(await grantsInstallResult(grantId, flags));
-}
-
-async function grantsInstallResult(grantId, flags) {
-  grantId = grantId || readState().last_grant_id;
-  if (!grantId) throw new Error("grant_id is required");
-  const target = flags.target || "generic";
-  const response = await api(`/api/itp/grants/${encodeURIComponent(grantId)}/install`, {
-    method: "POST",
-    body: { target }
-  }, flags);
-  const storedCredential = storeGrantCredential(grantId, {
-    key: response.credential.key_once,
-    target,
-    base_url: response.base_url,
-    openai_base_url: response.openai_base_url,
-    anthropic_base_url: response.anthropic_base_url,
-    gemini_base_url: response.gemini_base_url,
-    models: response.models || [],
-    install_profiles: response.install_profiles || []
-  });
-  const grantsDir = path.join(CONFIG_DIR, "grants");
-  ensureConfigDir();
-  fs.mkdirSync(grantsDir, { recursive: true });
-  try {
-    fs.chmodSync(grantsDir, 0o700);
-  } catch {
-    // Best effort; grant metadata does not contain gateway keys.
-  }
-  const metadataPath = path.join(grantsDir, `${grantId}.json`);
-  fs.writeFileSync(metadataPath, JSON.stringify({
-    grant_id: grantId,
-    target,
-    base_url: response.base_url,
-    models: response.models,
-    install_profiles: response.install_profiles
-  }, null, 2), { mode: 0o600 });
-  fs.chmodSync(metadataPath, 0o600);
-  writeState({ ...readState(), last_grant_id: grantId });
-  updateCurrentRun({
-    phase: "grant_ready",
-    grant: {
-      grant_id: grantId,
-      installed: true,
-      credential_store: storedCredential.credential_store || null
-    },
-    result: {
-      base_url: response.base_url,
-      openai_base_url: response.openai_base_url,
-      anthropic_base_url: response.anthropic_base_url,
-      gemini_base_url: response.gemini_base_url
-    },
-    safe_summary: "Grant credential stored."
-  }, flags);
-  return {
-    ...response,
-    credential: {
-      type: response.credential.type,
-      stored: true,
-      credential_store: storedCredential.credential_store,
-      warning: storedCredential.credential_warning || undefined
-    }
-  };
-}
-
-async function grantsRevoke(grantId, flags) {
-  grantId = grantId || flags.grant || readState().last_grant_id;
-  if (!grantId) throw new Error("grant_id is required");
-  const response = await api(`/api/itp/grants/${encodeURIComponent(grantId)}/revoke`, { method: "POST" }, flags);
-  deleteGrantCredential(grantId);
-  const state = readState();
-  if (state.last_grant_id === grantId) {
-    delete state.last_grant_id;
-    writeState(state);
-  }
-  output(response);
-}
-
-async function installRuntime(target, flags) {
-  output(await installRuntimeResult(target, flags));
-}
-
-async function installRuntimeResult(target, flags) {
-  const grantId = flags.grant || readState().last_grant_id;
-  if (!grantId) throw new Error("grant id is required");
-  const credentials = readGrantCredential(grantId);
-  if (!credentials) throw new Error(`grant ${grantId} is not installed; run grants install first`);
-  if (!credentials.key) {
-    throw new Error(`grant ${grantId} credential key is unavailable; run keys rotate or grants install again`);
-  }
-
-  const dryRun = Boolean(flags.dry_run);
-  const result = installTargetConfig(target, grantId, credentials, dryRun);
-  const shouldTest = !dryRun && !flags.offline && !flags.no_test;
-  const modelCheck = shouldTest
-    ? await doctorModelCheck(target, credentials)
-    : { attempted: false, skipped: true, reason: dryRun ? "dry_run" : flags.offline ? "offline" : "no_test" };
-  result.model_check = modelCheck;
-  result.tested = Boolean(modelCheck.ok);
-  if (modelCheck.attempted && !modelCheck.ok) {
-    result.warnings.push(`Model endpoint check failed: ${modelCheck.error || modelCheck.status || "unknown error"}`);
-  }
-
-  if (!dryRun && !flags.offline) {
-    await api(`/api/itp/grants/${encodeURIComponent(grantId)}/install-ack`, {
-      method: "POST",
-      body: {
-        target,
-        status: "installed",
-        tested: result.tested,
-        config_path: result.files[0]?.path || "",
-        last_error: result.warnings.join("; ")
-      }
-    }, flags);
-  }
-  return result;
-}
-
-function shouldRecoverCheckout(status) {
-  return ["paid_verified", "granting", "grant_failed"].includes(status);
-}
-
-function isSuccessfulCheckout(response) {
-  return Boolean(response?.grant_id) && ["grant_issued", "grant_installed"].includes(response.status);
-}
-
-function isTerminalCheckoutFailure(status) {
-  return ["expired", "payment_failed", "verify_failed", "amount_mismatch", "revoked"].includes(status);
-}
-
-function installTargetConfig(target, grantId, credentials, dryRun) {
-  if (target === "codex") return installCodex(grantId, credentials, dryRun);
-  if (target === "claude-code") return installClaudeCode(grantId, credentials, dryRun);
-  if (target === "openclaw") return installOpenClaw(grantId, credentials, dryRun);
-  throw new Error(`unsupported install target: ${target}`);
-}
-
-function installClaudeCode(grantId, credentials, dryRun) {
-  const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
-  const current = readJSON(settingsPath, {});
-  current.env = {
-    ...(current.env || {}),
-    ANTHROPIC_BASE_URL: credentials.anthropic_base_url,
-    ANTHROPIC_AUTH_TOKEN_HELPER: `${quoteShell(currentExecutable())} token issue --grant ${quoteShell(grantId)} --stdout`
-  };
-  delete current.env.ANTHROPIC_API_KEY;
-  const write = writeJSONWithBackup(settingsPath, current, dryRun);
-  return {
-    target: "claude-code",
-    grant_id: grantId,
-    status: dryRun ? "dry_run" : "installed",
-    files: [{ path: settingsPath, action: write.action, backup_path: write.backup_path || null }],
-    warnings: [
-      "Claude Code will call itp as an auth token helper; no gateway key was written to settings.json."
-    ]
-  };
-}
-
-function installCodex(grantId, credentials, dryRun) {
-  const configPath = path.join(os.homedir(), ".codex", "config.toml");
-  const envPath = path.join(CONFIG_DIR, "itpay.env");
-  const existing = readText(configPath, "");
-  const block = [
-    'model_provider = "itpay"',
-    'model = "openai-code-default"',
-    "",
-    "[model_providers.itpay]",
-    'name = "ItPay"',
-    `base_url = "${escapeTomlString(credentials.openai_base_url)}"`,
-    'env_key = "ITPAY_API_KEY"'
-  ].join("\n");
-  const nextConfig = replaceManagedBlock(existing, "itpay", block);
-  const configWrite = writeTextWithBackup(configPath, nextConfig, 0o600, dryRun);
-  const envWrite = writeTextWithBackup(envPath, `export ITPAY_API_KEY=${quoteShell(credentials.key)}\n`, 0o600, dryRun);
-  return {
-    target: "codex",
-    grant_id: grantId,
-    status: dryRun ? "dry_run" : "installed",
-    files: [
-      { path: configPath, action: configWrite.action, backup_path: configWrite.backup_path || null },
-      { path: envPath, action: envWrite.action, backup_path: envWrite.backup_path || null }
-    ],
-    warnings: [
-      "Codex reads ITPAY_API_KEY from its process environment; source ~/.itp/itpay.env before starting Codex if your launcher does not load it."
-    ]
-  };
-}
-
-function installOpenClaw(grantId, credentials, dryRun) {
-  const configPath = path.join(os.homedir(), ".openclaw", "config.json");
-  const current = readJSON(configPath, {});
-  current.models = current.models || {};
-  current.models.providers = current.models.providers || {};
-  current.models.providers.itpay = {
-    baseUrl: credentials.openai_base_url,
-    api: "openai-compatible",
-    apiKey: credentials.key,
-    models: credentials.models || []
-  };
-  const write = writeJSONWithBackup(configPath, current, dryRun);
-  return {
-    target: "openclaw",
-    grant_id: grantId,
-    status: dryRun ? "dry_run" : "installed",
-    files: [{ path: configPath, action: write.action, backup_path: write.backup_path || null }],
-    warnings: [
-      "OpenClaw does not expose a stable token-helper contract here, so the key is written only to the user-level config file with 0600 permissions."
-    ]
-  };
-}
-
-async function doctor(flags) {
-  const config = readConfig();
-  const credentials = readCredentials();
-  const target = flags.target || null;
-  const grantId = flags.grant || readState().last_grant_id || null;
-  const grantCredential = grantId ? readGrantCredential(grantId) : null;
-  output({
-    itp_version: VERSION,
-    api_base: config.api_base || apiBase(flags),
-    account_id: config.account_id || null,
-    device_id: config.device_id || null,
-    authenticated: Boolean(readSessionToken(credentials)),
-    grants_cached: Object.keys(credentials).filter((k) => k.startsWith("grant_")).length,
-    grant_id: grantId,
-    target,
-    target_config: target ? runtimeConfigStatus(target) : null,
-    model_check: grantCredential && !flags.offline ? await doctorModelCheck(target, grantCredential) : null,
-    grant_credential_store: grantCredential?.credential_store || null,
-    warning: grantCredential?.credential_warning || undefined,
-    credential_store: {
-      path: CREDENTIALS_PATH,
-      mode: fileMode(CREDENTIALS_PATH),
-      native: detectNativeCredentialStore(),
-      fallback: true
-    },
-    session_credential_store: credentials.session_token_store || (credentials.session_token ? "file" : null),
-    session_credential_warning: credentials.session_token_warning || undefined
-  });
-}
-
-async function docs(command, rest = [], flags = {}) {
-  const role = normalizeDocsRole(flags.role || "buyer");
-  if (command === "list" || !command) {
-    const docsList = listAgentDocs(role);
-    output({
-      schema_version: "itp.agent_doc_index.v1",
-      role,
-      topics: docsList.map((doc) => ({
-        topic: doc.topic,
-        title: doc.title,
-        purpose: doc.purpose,
-        command: cliCommand("docs", "show", doc.topic, "--role", role, "--json"),
-        next_docs: Array.isArray(doc.next_docs) ? doc.next_docs.map((next) => next.topic).filter(Boolean) : []
-      })),
-      start_here: cliCommand("docs", "show", "quickstart", "--role", role, "--json"),
-      search_command: cliCommand("docs", "search", "<question>", "--role", role, "--json")
-    });
-    return;
-  }
-  if (command === "show" || command === "read") {
-    const topic = flags.topic || positionalArgs(rest)[0] || "quickstart";
-    output(loadAgentDoc(role, topic));
-    return;
-  }
-  if (command === "search") {
-    const query = String(flags.query || flags.q || positionalArgs(rest).join(" ")).trim();
-    if (!query) throw new Error("docs search query is required");
-    const matches = searchAgentDocs(role, query);
-    output({
-      schema_version: "itp.agent_doc_search.v1",
-      role,
-      query,
-      matches,
-      fallback: matches.length ? null : {
-        topic: "quickstart",
-        command: cliCommand("docs", "show", "quickstart", "--role", role, "--json")
-      }
-    });
-    return;
-  }
-  throw new Error(`unknown docs command: ${command}`);
-}
-
-function normalizeDocsRole(role) {
-  const normalized = String(role || "buyer").trim().toLowerCase();
-  if (normalized === "buyer" || normalized === "itpay-buyer") return "buyer";
-  throw new Error(`unsupported docs role: ${role}`);
-}
-
-function listAgentDocs(role) {
-  const docsDir = resolveDocsDir(role);
-  return fs.readdirSync(docsDir)
-    .filter((name) => name.endsWith(".json"))
-    .map((name) => loadAgentDoc(role, name.replace(/\.json$/, "")))
-    .sort((a, b) => docTopicOrder(a.topic) - docTopicOrder(b.topic) || a.topic.localeCompare(b.topic));
-}
-
-function loadAgentDoc(role, topic) {
-  const normalizedTopic = normalizeDocTopic(topic);
-  const file = path.join(resolveDocsDir(role), `${normalizedTopic}.json`);
-  if (!fs.existsSync(file)) {
-    throw new Error(`agent docs topic not found: ${normalizedTopic}`);
-  }
-  const doc = readJSON(file, null);
-  if (!doc || doc.role !== role || doc.topic !== normalizedTopic) {
-    throw new Error(`invalid agent docs topic: ${normalizedTopic}`);
-  }
-  return {
-    ...doc,
-    source: {
-      packaged_path: file,
-      command: cliCommand("docs", "show", normalizedTopic, "--role", role, "--json")
-    }
-  };
-}
-
-function searchAgentDocs(role, query) {
-  const rawQuery = String(query).toLowerCase();
-  const terms = rawQuery.split(/\s+/).filter(Boolean);
-  return listAgentDocs(role)
-    .map((doc) => {
-      const docTerms = (doc.search_terms || []).map((term) => String(term).toLowerCase()).filter(Boolean);
-      const haystack = [
-        doc.topic,
-        doc.title,
-        doc.purpose,
-        ...(doc.when_to_use || []),
-        ...(doc.agent_rules || []),
-        ...(doc.forbidden || []),
-        ...docTerms
-      ].join(" ").toLowerCase();
-      const score = terms.reduce((sum, term) => sum + (haystack.includes(term) ? 1 : 0), 0) +
-        docTerms.reduce((sum, term) => sum + (rawQuery.includes(term) ? 1 : 0), 0);
-      return { doc, score };
-    })
-    .filter((entry) => entry.score > 0)
-    .sort((a, b) => b.score - a.score || docTopicOrder(a.doc.topic) - docTopicOrder(b.doc.topic))
-    .slice(0, 5)
-    .map((entry) => ({
-      topic: entry.doc.topic,
-      title: entry.doc.title,
-      purpose: entry.doc.purpose,
-      score: entry.score,
-      command: cliCommand("docs", "show", entry.doc.topic, "--role", role, "--json"),
-      next_docs: Array.isArray(entry.doc.next_docs) ? entry.doc.next_docs.map((next) => next.topic).filter(Boolean) : []
-    }));
-}
-
-function resolveDocsDir(role) {
-  const candidates = [
-    process.env.ITPAY_CLI_DOCS_DIR,
-    path.join(PACKAGE_ROOT, "docs", "agent", role),
-    path.join(path.dirname(CLI_DIR), "share", "itpay_cli", "docs", "agent", role),
-    path.join(process.cwd(), "docs", "agent", role)
-  ].filter(Boolean);
-  const found = candidates.find((candidate) => fs.existsSync(candidate));
-  if (!found) {
-    throw new Error(`ItPay agent docs not found for role ${role}. Checked: ${candidates.join(", ")}`);
-  }
-  return found;
-}
-
-function normalizeDocTopic(topic) {
-  return String(topic || "").trim().toLowerCase().replaceAll("_", "-");
-}
-
-function docTopicOrder(topic) {
-  const order = [
-    "quickstart",
-    "catalog-search",
-    "product-recommendation",
-    "cart-checkout",
-    "payment-qr",
-    "payment-wait",
-    "qr-refresh",
-    "secure-delivery",
-    "human-claim-ui",
-    "account-portal",
-    "vault-agent-read",
-    "recovery",
-    "safety-policy"
-  ];
-  const index = order.indexOf(topic);
-  return index === -1 ? 999 : index;
-}
-
-async function skill(command, flags) {
-  const role = normalizeSkillRole(flags.role || flags.skill || "buyer");
-  const skillPath = resolveSkillPath(role);
-  if (!command || command === "show" || command === "read") {
-    const content = fs.readFileSync(skillPath, "utf8");
-    if (flags.json) {
-      output({ skill: "itpay-buyer", role, path: skillPath, content });
-    } else {
-      process.stdout.write(content.endsWith("\n") ? content : `${content}\n`);
-    }
-    return;
-  }
-  if (command === "path") {
-    if (flags.json) {
-      output({ skill: "itpay-buyer", role, path: skillPath });
-    } else {
-      process.stdout.write(`${skillPath}\n`);
-    }
-    return;
-  }
-  throw new Error(`unknown skill command: ${command}`);
-}
-
-function normalizeSkillRole(role) {
-  const normalized = String(role || "buyer").trim().toLowerCase();
-  if (normalized === "buyer" || normalized === "itpay-buyer") return "buyer";
-  if (normalized === "merchant" || normalized === "itpay-merchant") {
-    throw new Error("merchant skill is not packaged yet; use --role buyer for current external-agent tests");
-  }
-  throw new Error(`unsupported skill role: ${role}`);
-}
-
-function resolveSkillPath(role = "buyer") {
-  const skillDirName = "itpay-buyer";
-  const envPath = process.env.ITPAY_BUYER_SKILL_PATH;
-  const candidates = [
-    envPath,
-    process.env.ITPAY_CLI_SKILL_PATH,
-    path.join(PACKAGE_ROOT, "skills", skillDirName, "SKILL.md"),
-    path.join(path.dirname(CLI_DIR), "share", "itpay_cli", "skills", skillDirName, "SKILL.md"),
-    path.join(process.cwd(), "skills", skillDirName, "SKILL.md")
-  ].filter(Boolean);
-  const found = candidates.find((candidate) => fs.existsSync(candidate));
-  if (!found) {
-    throw new Error(`ItPay skill file not found for role ${role}. Checked: ${candidates.join(", ")}`);
-  }
-  return found;
-}
-
-async function doctorModelCheck(target, credentials) {
-  const baseUrl = target === "claude-code"
-    ? credentials.anthropic_base_url
-    : target === "codex" || target === "openclaw"
-      ? credentials.openai_base_url
-      : credentials.openai_base_url || credentials.base_url;
-  if (!baseUrl || !credentials.key) {
-    return { attempted: false, ok: false, error: "missing base_url or credential" };
-  }
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), 3000);
-  try {
-    const response = await fetch(`${baseUrl.replace(/\/$/, "")}/models`, {
-      method: "GET",
-      headers: { Authorization: `Bearer ${credentials.key}` },
-      signal: controller.signal
-    });
-    return {
-      attempted: true,
-      ok: response.ok,
-      status: response.status,
-      endpoint: `${baseUrl.replace(/\/$/, "")}/models`
-    };
-  } catch (error) {
-    return {
-      attempted: true,
-      ok: false,
-      endpoint: `${baseUrl.replace(/\/$/, "")}/models`,
-      error: error.message
-    };
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-function runtimeConfigStatus(target) {
-  const paths = {
-    "claude-code": [path.join(os.homedir(), ".claude", "settings.json")],
-    codex: [path.join(os.homedir(), ".codex", "config.toml"), path.join(CONFIG_DIR, "itpay.env")],
-    openclaw: [path.join(os.homedir(), ".openclaw", "config.json")]
-  };
-  return (paths[target] || []).map((file) => ({
-    path: file,
-    exists: fs.existsSync(file),
-    mode: fileMode(file)
-  }));
-}
-
-async function keys(command, flags) {
-  const credentials = readCredentials();
-  const grants = Object.entries(credentials)
-    .filter(([key]) => key.startsWith("grant_"))
-    .map(([key, value]) => ({
-      grant_id: key.slice("grant_".length),
-      target: value.target,
-      base_url: value.base_url,
-      credential_store: value.credential_store || "file",
-      key: value.key ? maskSecret(value.key) : "stored"
-    }));
-  if (!command || command === "list") {
-    output({ keys: grants });
-    return;
-  }
-  if (command === "revoke") {
-    const grantId = flags.grant || grants[0]?.grant_id;
-    if (!grantId) throw new Error("grant id is required");
-    const response = await api(`/api/itp/grants/${encodeURIComponent(grantId)}/revoke`, { method: "POST" }, flags);
-    deleteGrantCredential(grantId);
-    output(response);
-    return;
-  }
-  if (command === "rotate") {
-    const grantId = flags.grant || grants[0]?.grant_id;
-    if (!grantId) throw new Error("grant id is required");
-    const existing = readCredentials()[`grant_${grantId}`] || {};
-    const response = await api(`/api/itp/grants/${encodeURIComponent(grantId)}/rotate`, { method: "POST" }, flags);
-    const storedCredential = storeGrantCredential(grantId, {
-      key: response.credential.key_once,
-      target: existing.target || flags.target || "",
-      base_url: response.base_url,
-      openai_base_url: response.openai_base_url,
-      anthropic_base_url: response.anthropic_base_url,
-      gemini_base_url: response.gemini_base_url,
-      models: response.models || [],
-      install_profiles: response.install_profiles || []
-    });
-    output({
-      ...response,
-      credential: {
-        type: response.credential.type,
-        rotated: true,
-        stored: true,
-        credential_store: storedCredential.credential_store,
-        warning: storedCredential.credential_warning || undefined
-      }
-    });
-    return;
-  }
-  throw new Error(`unknown keys command: ${command}`);
-}
-
-async function token(command, flags) {
-  if (command !== "issue") throw new Error(`unknown token command: ${command || ""}`);
-  const grantId = flags.grant || readState().last_grant_id;
-  if (!grantId) throw new Error("grant id is required");
-  const credentials = readGrantCredential(grantId);
-  if (!credentials?.key) throw new Error(`grant ${grantId} is not installed locally`);
-  if (flags.stdout) {
-    process.stdout.write(credentials.key);
-    return;
-  }
-  output({
-    grant_id: grantId,
-    key: maskSecret(credentials.key),
-    stdout_required_for_raw_token: true
-  });
-}
-
-async function sync(flags) {
-  const [account, balanceResult, grants] = await Promise.all([
-    api("/api/itp/account", { method: "GET" }, flags),
-    api("/api/itp/balance", { method: "GET" }, flags),
-    api("/api/itp/grants", { method: "GET" }, flags)
-  ]);
-  output({ account, balance: balanceResult, grants });
-}
-
-async function refreshRun(run, flags = {}) {
-  let next = { ...run };
-  const credentials = readCredentials();
-  const hasSession = Boolean(readSessionToken(credentials));
-
-  if (next.auth?.auth_id && !hasSession) {
-    try {
-      const auth = await api(`/api/itp/auth/device/${encodeURIComponent(next.auth.auth_id)}/poll`, { method: "POST" }, flags);
-      if (auth.auth?.session_token) {
-        writeSessionCredentials(auth.auth);
-        writeConfig({
-          api_base: apiBase(flags),
-          account_id: auth.auth.account_id,
-          device_id: auth.auth.device_id,
-          web_console_url: auth.auth.web_console_url
-        });
-        next = mergeRun(next, {
-          phase: "authenticated",
-          status: "running",
-          account: {
-            authenticated: true,
-            account_id: auth.auth.account_id,
-            device_id: auth.auth.device_id,
-            newapi_user_id: auth.auth.newapi_user_id || null
-          },
-          auth: { status: "consumed" },
-          human_action: null,
-          safe_summary: "Agent device authenticated."
-        });
-      } else if (auth.status === "authorization_pending") {
-        next = mergeRun(next, {
-          phase: "waiting_human_auth",
-          status: "waiting_human_auth",
-          auth: { status: "pending", expires_at: auth.expires_at },
-          human_action: auth.human_action || auth.next_action?.human_action || next.human_action || null,
-          safe_summary: "Waiting for Alipay authentication scan."
-        });
-      } else if (auth.status) {
-        next = mergeRun(next, {
-          phase: auth.status === "expired" ? "expired" : "failed",
-          status: auth.status === "expired" ? "expired" : "failed",
-          auth: { status: auth.status },
-          safe_summary: auth.error || `Auth status: ${auth.status}`
-        });
-      }
-    } catch (error) {
-      next = mergeRun(next, { last_error: safeErrorMessage(error), safe_summary: "Could not refresh auth status." });
-    }
-  }
-
-  if (readSessionToken(readCredentials())) {
-    try {
-      const authStatusResult = await api("/api/itp/auth/status", { method: "GET" }, flags);
-      next = mergeRun(next, {
-        account: {
-          authenticated: authStatusResult.authenticated !== false,
-          account_id: authStatusResult.account_id || next.account?.account_id || null,
-          device_id: authStatusResult.device_id || next.account?.device_id || null,
-          newapi_user_id: authStatusResult.newapi_user_id || null
-        }
-      });
-    } catch (error) {
-      next = mergeRun(next, { last_error: safeErrorMessage(error) });
-    }
-  }
-
-  if (next.checkout?.checkout_id && readSessionToken(readCredentials())) {
-    try {
-      const checkout = await api(`/api/itp/checkout/${encodeURIComponent(next.checkout.checkout_id)}`, { method: "GET" }, flags);
-      next = mergeRun(next, {
-        phase: checkout.grant_id ? "grant_ready" : checkout.status === "waiting_user_payment" ? "waiting_human_payment" : next.phase,
-        status: checkout.grant_id ? "grant_ready" : checkout.status === "waiting_user_payment" ? "waiting_human_payment" : next.status,
-        checkout: {
-          checkout_id: checkout.checkout_id,
-          order_id: checkout.order_id,
-          status: checkout.status,
-          expires_at: checkout.expires_at
-        },
-        payment: { provider: next.payment_method, status: checkout.status },
-        grant: { ...(next.grant || {}), grant_id: checkout.grant_id || next.grant?.grant_id || null },
-        human_action: checkout.human_action || null,
-        safe_summary: checkout.grant_id ? "Payment verified and grant is ready." : checkout.status === "waiting_user_payment" ? "Waiting for Alipay payment scan." : `Checkout status: ${checkout.status}`
-      });
-    } catch (error) {
-      next = mergeRun(next, { last_error: safeErrorMessage(error), safe_summary: "Could not refresh checkout status." });
-    }
-  }
-
-  const grantId = next.grant?.grant_id || readState().last_grant_id;
-  if (grantId) {
-    const credential = readGrantCredential(grantId);
-    if (credential?.key || credential?.credential_ref) {
-      next = mergeRun(next, {
-        phase: next.install_runtime ? next.phase : "grant_ready",
-        grant: { grant_id: grantId, installed: true, credential_store: credential.credential_store || "file" },
-        safe_summary: "Grant credential stored."
-      });
-    }
-  }
-  return next;
-}
-
-function agentRunResponse(run, extra = {}) {
-  const status = extra.status || (run.status && run.status !== "running" ? run.status : phaseToStatus(run.phase));
-  return {
-    schema_version: "itp.agent.v1",
-    status,
-    run_id: run.run_id,
-    phase: run.phase || status,
-    auth_id: extra.auth_id || run.auth?.auth_id || null,
-    account_id: extra.account_id || run.account?.account_id || null,
-    device_id: extra.device_id || run.account?.device_id || null,
-    checkout_id: extra.checkout_id || run.checkout?.checkout_id || null,
-    order_id: extra.order_id || run.checkout?.order_id || null,
-    grant_id: extra.grant_id || run.grant?.grant_id || null,
-    plan_id: extra.plan_id || run.plan_id || null,
-    credits: extra.credits || run.credits || run.checkout?.purchase?.credits_granted || null,
-    purchase: extra.purchase || run.checkout?.purchase || undefined,
-    target: extra.target || run.target || "generic",
-    base_url: extra.base_url || run.result?.base_url || undefined,
-    openai_base_url: extra.openai_base_url || run.result?.openai_base_url || undefined,
-    anthropic_base_url: extra.anthropic_base_url || run.result?.anthropic_base_url || undefined,
-    gemini_base_url: extra.gemini_base_url || run.result?.gemini_base_url || undefined,
-    credential: extra.credential || (run.grant?.installed ? {
-      stored: true,
-      credential_store: run.grant?.credential_store,
-      token_command: run.grant?.grant_id ? cliCommand("token", "issue", "--grant", run.grant.grant_id, "--stdout") : undefined,
-      stdout_required_for_raw_token: true
-    } : undefined),
-    human_action: extra.human_action || run.human_action || undefined,
-    next: extra.next || nextActionForRun(run),
-    next_action: extra.next_action || undefined,
-    safe_user_message: extra.safe_user_message || safeUserMessageForRun(run),
-    safe_summary: run.safe_summary || undefined,
-    warnings: extra.warnings || [],
-    secrets: {
-      raw_key_included: false,
-      session_token_included: false
-    },
-    ...extra
-  };
-}
-
-function phaseToStatus(phase) {
-  if (phase === "waiting_human_auth") return "waiting_human_auth";
-  if (phase === "waiting_human_payment") return "waiting_human_payment";
-  if (phase === "grant_ready") return "grant_ready";
-  if (phase === "done") return "done";
-  if (phase === "expired") return "expired";
-  if (phase === "failed") return "failed";
-  return phase || "running";
-}
-
-function nextActionForRun(run) {
-  if (run.phase === "waiting_human_auth") {
-    return { type: "show_qr_and_wait", command: resumeCommand(run, runResumeFlags(run)), retry_after_ms: 2000, safe_for_agent: true };
-  }
-  if (run.phase === "waiting_human_payment") {
-    return { type: "show_qr_and_wait", command: resumeCommand(run, runResumeFlags(run, { display: "none" })), retry_after_ms: 2000, safe_for_agent: true };
-  }
-  if (["paid_verified", "granting", "grant_failed"].includes(run.checkout?.status)) {
-    return { type: "recover_checkout", command: cliCommand("checkout", "recover", run.checkout.checkout_id, "--json"), safe_for_agent: true };
-  }
-  if (run.grant?.grant_id && !run.grant?.installed) {
-    return { type: "install_grant", command: cliCommand("grants", "install", run.grant.grant_id, "--target", run.target || "generic", "--json"), safe_for_agent: true };
-  }
-  if (run.grant?.installed) {
-    return { type: "done", safe_for_agent: true };
-  }
-  return { type: "resume", command: resumeCommand(run, runResumeFlags(run)), safe_for_agent: true };
-}
-
-function runResumeFlags(run, overrides = {}) {
-  return {
-    host: run.agent_host || undefined,
-    display: run.agent_display || undefined,
-    qr_format: run.agent_qr_format || undefined,
-    api_base: run.api_base || undefined,
-    ...overrides
-  };
-}
-
-function resumeCommand(run, flags = {}, options = {}) {
-  const args = ["resume", "--run-id", run.run_id, "--json"];
-  appendPassthroughFlag(args, flags, "host");
-  appendPassthroughFlag(args, flags, "display");
-  appendPassthroughFlag(args, flags, "qr_format", "qr-format");
-  appendPassthroughFlag(args, flags, "api_base", "api-base");
-  appendPassthroughFlag(args, flags, "api_timeout", "api-timeout");
-  if (options.no_wait_payment) args.push("--no-wait-payment");
-  return cliCommand(...args);
-}
-
-function appendPassthroughFlag(args, flags, key, flagName = key) {
-  const value = flags[key];
-  if (value === undefined || value === null || value === false) return;
-  args.push(`--${flagName}`);
-  if (value !== true) args.push(String(value));
-}
-
-function cliCommand(...args) {
-  const override = process.env.ITP_COMMAND;
-  const base = override
-    ? override
-    : `${shellQuote(process.execPath)} ${shellQuote(CLI_FILE)}`;
-  return [base, ...args.map((arg) => shellQuote(String(arg)))].join(" ");
-}
-
-function shellQuote(value) {
-  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) return value;
-  return `'${value.replace(/'/g, "'\\''")}'`;
-}
-
-function safeUserMessageForRun(run) {
-  if (run.phase === "waiting_human_auth") return "Please scan the Alipay authentication QR. I will continue automatically after approval.";
-  if (run.phase === "waiting_human_payment") return "Please scan the Alipay payment QR. I will continue automatically after payment is verified.";
-  if (run.grant?.installed) return "Payment verified. The API credential is stored locally.";
-  return run.safe_summary || "ITPay setup is in progress.";
-}
-
-function safeErrorMessage(error) {
-  return String(error?.message || error || "unknown error")
-    .replace(/itp_sess_[A-Za-z0-9_-]+/g, "itp_sess_****")
-    .replace(/sk-[A-Za-z0-9_-]+/g, "sk-****");
-}
-
-function humanActionSummaryLines(action) {
-  if (!action?.url) return [];
-  const lines = [
-    "ITP HUMAN ACTION REQUIRED",
-    `Title: ${action.title || "Scan with Alipay"}`,
-    `URL: ${action.url}`
-  ];
-  if (action.local_qr_path) {
-    lines.push(`Local QR image: ${action.local_qr_path}`);
-  }
-  if (action.qr_png_url) {
-    lines.push(`QR PNG: ${action.qr_png_url}`);
-  }
-  if (action.qr_image_url) {
-    lines.push(`QR image: ${action.qr_image_url}`);
-  }
-  if (action.mobile_wallet_url) {
-    lines.push(`Mobile wallet link: ${action.mobile_wallet_url}`);
-  }
-  if (action.oauth_start_url) {
-    lines.push(`Alipay auth fallback: ${action.oauth_start_url}`);
-  }
-  if (action.fallback_text && !action.fallback_text.includes(action.url)) {
-    lines.push(`Fallback: ${action.fallback_text}`);
-  }
-  if (action.expires_at) {
-    lines.push(`Expires at: ${formatActionTime(action.expires_at)}`);
-  }
-  return lines;
-}
-
-function writeHumanActionSummary(action, suffix = "") {
-  const lines = humanActionSummaryLines(action);
-  if (!lines.length) return;
-  process.stderr.write(`\n${lines.join("\n")}${suffix ? `\n${suffix}` : ""}\n\n`);
-}
-
-function waitHeartbeatMs(flags = {}) {
-  if (flags.quiet || process.env.ITP_WAIT_HEARTBEAT_SECONDS === "0") return 0;
-  return Math.max(5000, Number(flags.heartbeat || process.env.ITP_WAIT_HEARTBEAT_SECONDS || 20) * 1000);
-}
-
-function writeWaitHeartbeat({ kind, idName, idValue, status, action, lastHeartbeatAt, flags, command }) {
-  const heartbeatMs = waitHeartbeatMs(flags);
-  if (!heartbeatMs) return lastHeartbeatAt;
-  const now = Date.now();
-  if (now - lastHeartbeatAt < heartbeatMs) return lastHeartbeatAt;
-  const lines = [
-    `ITP waiting for ${kind}: ${idName}=${idValue} status=${status}`,
-    action?.url ? `URL: ${action.url}` : null,
-    action?.local_qr_path ? `Local QR image: ${action.local_qr_path}` : null,
-    action?.qr_png_url ? `QR PNG: ${action.qr_png_url}` : null,
-    action?.qr_image_url ? `QR image: ${action.qr_image_url}` : null,
-    action?.mobile_wallet_url ? `Mobile wallet link: ${action.mobile_wallet_url}` : null,
-    action?.oauth_start_url ? `Alipay auth fallback: ${action.oauth_start_url}` : null,
-    command ? `Resume command: ${command}` : null
-  ].filter(Boolean);
-  process.stderr.write(`\n${lines.join("\n")}\n\n`);
-  return now;
-}
-
-async function renderHumanAction(action, flags = {}) {
-  if (!action?.url) return null;
-  const qrImageURL = preferredHumanActionQRURL(action);
-  const mode = String(flags.display || process.env.ITP_DISPLAY || "").toLowerCase() || "auto";
-  annotateHumanActionPresentation(action, qrImageURL);
-  if (flags.json || mode === "none" || mode === "json") {
-    if (qrImageURL && shouldPrepareLocalQRForJSON(mode, flags, action)) {
-      const localPath = await prepareLocalQRFile(action, qrImageURL, flags, mode !== "file" && !flags.qr_file && !process.env.ITP_QR_FILE);
-      if (localPath) {
-        attachAgentQRImage(action, qrImageURL, localPath);
-        persistHumanAction(action, flags);
-        return { rendered: false, mode: "json-local-qr", outputs: [localPath] };
-      }
-    }
-    if (!qrImageURL && shouldGenerateLocalQRFromActionURL(action, mode, flags)) {
-      const localPath = await prepareLocalQRFromActionURL(action, flags, mode !== "file" && !flags.qr_file && !process.env.ITP_QR_FILE);
-      if (localPath) {
-        attachAgentLocalQR(action, localPath);
-        annotateHumanActionPresentation(action, "");
-        persistHumanAction(action, flags);
-        return { rendered: false, mode: "json-local-url-qr", outputs: [localPath] };
-      }
-    }
-    return { rendered: false, mode: flags.json ? "json" : mode };
-  }
-  const host = String(process.env.ITP_HOST || flags.host || "").toLowerCase();
-  if (["discord", "telegram", "whatsapp"].includes(host)) {
-    return { rendered: false, mode: "chat-json", host };
-  }
-  if (shouldUseAgentTextQR(flags)) {
-    if (qrImageURL) {
-      const localPath = await prepareLocalQRFile(action, qrImageURL, flags, true);
-      attachAgentQRImage(action, qrImageURL, localPath);
-      persistHumanAction(action, flags);
-      return { rendered: false, mode: localPath ? "agent-local-image-qr" : "agent-image-qr", host, outputs: [localPath || "preferred_qr_url"] };
-    }
-    if (shouldGenerateLocalQRFromActionURL(action, mode, flags)) {
-      const localPath = await prepareLocalQRFromActionURL(action, flags, true);
-      if (localPath) {
-        attachAgentLocalQR(action, localPath);
-        annotateHumanActionPresentation(action, "");
-        persistHumanAction(action, flags);
-        return { rendered: false, mode: "agent-local-url-qr", host, outputs: [localPath] };
-      }
-    }
-    process.stderr.write(`No QR image available. Open action URL: ${action.url}\n`);
-    persistHumanAction(action, flags);
-    return { rendered: false, mode: "agent-url-fallback", host, outputs: ["action_url"] };
-  }
-
-  const renderResult = { rendered: false, mode, outputs: [] };
-  writeHumanActionSummary(action);
-  if ((mode === "auto" || mode === "browser") && shouldOpenBrowser(flags)) {
-    if (openBrowser(action.mobile_wallet_url || qrImageURL || action.url)) {
-      renderResult.rendered = true;
-      renderResult.outputs.push("browser");
-    }
-    if (mode === "browser") return renderResult;
-  }
-
-  if (mode === "file" || flags.qr_file || process.env.ITP_QR_FILE) {
-    const file = flags.qr_file || process.env.ITP_QR_FILE || defaultQRFilePath(action, qrImageURL);
-    if (qrImageURL) {
-      await downloadQRImage(qrImageURL, file, flags);
-      action.local_qr_path = file;
-      action.local_qr_mime = qrMimeType(qrImageURL, action);
-      process.stderr.write(`Alipay QR image: ${file}\n`);
-      renderResult.rendered = true;
-      renderResult.outputs.push(file);
-      if (mode === "file") return renderResult;
-    } else {
-      const localPath = shouldGenerateLocalQRFromActionURL(action, mode, flags)
-        ? await prepareLocalQRFromActionURL(action, flags, false)
-        : "";
-      if (localPath) {
-        attachAgentLocalQR(action, localPath);
-        annotateHumanActionPresentation(action, "");
-        process.stderr.write(`Alipay action QR image: ${localPath}\n`);
-        renderResult.rendered = true;
-        renderResult.outputs.push(localPath);
-        if (mode === "file") return renderResult;
-      } else {
-        process.stderr.write(`No QR image available. Open action URL: ${action.url}\n`);
-      }
-    }
-  }
-
-  if (qrImageURL) {
-    process.stderr.write(`Alipay QR image URL: ${qrImageURL}\n`);
-    if (action.mobile_wallet_url) process.stderr.write(`Mobile wallet link: ${action.mobile_wallet_url}\n`);
-    renderResult.outputs.push("preferred_qr_url");
-    return renderResult;
-  }
-
-  if ((mode === "auto" || mode === "terminal") && shouldRenderTerminalQR(host)) {
-    const qr = await QRCode.toString(action.url, {
-      type: terminalQRType(flags, host),
-      small: true,
-      errorCorrectionLevel: "M"
-    });
-    process.stderr.write(`\n${action.title || "Scan with Alipay"}\n`);
-    if (action.description) process.stderr.write(`${action.description}\n`);
-    process.stderr.write(`${qr}\n`);
-    process.stderr.write(`Alipay action URL: ${action.url}\n`);
-    if (action.expires_at) process.stderr.write(`Expires at: ${formatActionTime(action.expires_at)}\n`);
-    renderResult.rendered = true;
-    renderResult.outputs.push("terminal");
-    return renderResult;
-  }
-
-  process.stderr.write(`${action.fallback_text || `Open Alipay URL: ${action.url}`}\n`);
-  renderResult.outputs.push("url");
-  return renderResult;
-}
-
-function preferredHumanActionQRURL(action) {
-  return action?.qr_png_url ||
-    humanActionPresentationURL(action, "qr_png_url") ||
-    action?.qr_image_url ||
-    action?.qr?.png_url ||
-    action?.qr?.image_url ||
-    humanActionPresentationURL(action, "qr_svg_url") ||
-    "";
-}
-
-function humanActionPresentationURL(action, type) {
-  const display = action?.presentation?.display;
-  if (!Array.isArray(display)) return "";
-  const found = display.find((item) => item?.type === type && item?.url);
-  return found?.url || "";
-}
-
-function annotateHumanActionPresentation(action, qrImageURL) {
-  if (!action) return action;
-  if (qrImageURL) {
-    action.preferred_qr_url = qrImageURL;
-    action.preferred_qr_mime = qrMimeType(qrImageURL, action);
-  }
-  const mobileURL = action.mobile_wallet_url || humanActionPresentationURL(action, "mobile_wallet_url");
-  if (mobileURL) action.mobile_wallet_url = mobileURL;
-  action.agent_display_hint = {
-    primary: action.local_qr_path ? "local_qr_path" : (action.qr_png_url ? "qr_png_url" : "preferred_qr_url"),
-    desktop: action.kind === "auth_qr"
-      ? "Show local_qr_path when present; otherwise show the ItPay first-purchase entry URL. This QR starts login/registration/profile authorization and should continue to payment for the same checkout after approval; it is not payment proof."
-      : "Show local_qr_path when present; otherwise show qr_png_url/preferred_qr_url directly. This is an ItPay-hosted human QR image and may render the native provider payment code; do not render your own QR from payment_entry_url.",
-    mobile: "Show mobile_wallet_url as a clickable human-only fallback when present.",
-    proof: "Only payment_intent.verified proves payment. QR display or page open is not payment proof."
-  };
-  return action;
-}
-
-function shouldPrepareLocalQRForJSON(mode, flags = {}, action = {}) {
-  if (mode === "file" || flags.qr_file || process.env.ITP_QR_FILE) return true;
-  if (action?.qr_png_url || action?.preferred_qr_url || action?.qr_image_url) return true;
-  return false;
-}
-
-function shouldGenerateLocalQRFromActionURL(action = {}, mode = "", flags = {}) {
-  if (!action?.url) return false;
-  if (action.kind === "auth_qr") return true;
-  return mode === "file" || Boolean(flags.qr_file || process.env.ITP_QR_FILE);
-}
-
-async function prepareLocalQRFile(action, qrImageURL, flags = {}, optional = false) {
-  if (!qrImageURL) return "";
-  const file = flags.qr_file || process.env.ITP_QR_FILE || defaultQRFilePath(action, qrImageURL);
-  try {
-    await downloadQRImage(qrImageURL, file, flags);
-  } catch (error) {
-    if (!optional) throw error;
-    action.local_qr_error = safeErrorMessage(error);
-    return "";
-  }
-  action.local_qr_path = file;
-  action.local_qr_mime = qrMimeType(qrImageURL, action);
-  return file;
-}
-
-async function prepareLocalQRFromActionURL(action, flags = {}, optional = false) {
-  if (!action?.url) return "";
-  const file = flags.qr_file || process.env.ITP_QR_FILE || defaultGeneratedQRFilePath(action);
-  try {
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    await QRCode.toFile(file, action.url, {
-      type: "png",
-      errorCorrectionLevel: "M",
-      margin: 2,
-      width: 512
-    });
-  } catch (error) {
-    if (!optional) throw error;
-    action.local_qr_error = safeErrorMessage(error);
-    return "";
-  }
-  action.local_qr_path = file;
-  action.local_qr_mime = "image/png";
-  return file;
-}
-
-function defaultQRFilePath(action, qrImageURL) {
-  const id = sanitizeFilename(action?.payment_intent_id || action?.id || "qr");
-  return path.join(os.tmpdir(), `itp-${id}.${qrFileExtension(qrImageURL, action)}`);
-}
-
-function defaultGeneratedQRFilePath(action) {
-  const id = sanitizeFilename(action?.payment_intent_id || action?.id || "qr");
-  return path.join(os.tmpdir(), `itp-${id}.png`);
-}
-
-function qrFileExtension(qrImageURL, action = {}) {
-  const mime = qrMimeType(qrImageURL, action);
-  if (mime === "image/png") return "png";
-  if (mime === "image/svg+xml") return "svg";
-  return "img";
-}
-
-function qrMimeType(qrImageURL, action = {}) {
-  if (qrImageURL && action?.qr_png_url && qrImageURL === action.qr_png_url) return "image/png";
-  if (String(qrImageURL || "").toLowerCase().includes(".png")) return "image/png";
-  if (String(qrImageURL || "").toLowerCase().includes(".svg")) return "image/svg+xml";
-  return action?.preferred_qr_mime || "image/png";
-}
-
-function sanitizeFilename(value) {
-  return String(value || "qr").replace(/[^A-Za-z0-9_.-]/g, "_").slice(0, 96) || "qr";
-}
-
-function formatActionTime(value) {
-  if (value === null || value === undefined || value === "") return "";
-  if (typeof value === "number" || /^[0-9]+$/.test(String(value))) {
-    const numeric = Number(value);
-    const millis = numeric > 100000000000 ? numeric : numeric * 1000;
-    const date = new Date(millis);
-    if (!Number.isNaN(date.getTime())) return date.toISOString();
-  }
-  const date = new Date(String(value));
-  if (!Number.isNaN(date.getTime())) return date.toISOString();
-  return String(value);
-}
-
-function shouldUseAgentTextQR(flags = {}) {
-  const mode = String(flags.display || process.env.ITP_DISPLAY || "").toLowerCase() || "auto";
-  const host = String(process.env.ITP_HOST || flags.host || "").toLowerCase();
-  return mode === "chat" || mode === "agent" || (["gemini", "gemini-cli"].includes(host) && mode === "auto");
-}
-
-function shouldReturnAfterAgentTextQR(flags = {}) {
-  if (flags.wait || flags.wait_human) return false;
-  return shouldUseAgentTextQR(flags);
-}
-
-function attachAgentQRImage(action, qrImageURL, localPath = "") {
-  if (!action || !qrImageURL) return action;
-  action.preferred_qr_url = qrImageURL;
-  if (qrMimeType(qrImageURL, action) === "image/png") {
-    action.qr_png_url = action.qr_png_url || qrImageURL;
-  } else {
-    action.qr_image_url = action.qr_image_url || qrImageURL;
-  }
-  if (!Array.isArray(action.display)) {
-    action.display = [];
-  }
-  if (!action.display.some((item) => item?.type === "image")) {
-    action.display.push({
-      type: "image",
-      format: qrFileExtension(qrImageURL, action),
-      url: qrImageURL,
-      local_path: localPath || undefined,
-      instructions: "Render local_path when present; otherwise render this ItPay-hosted QR image for the human to scan. ItPay may render a native provider payment code inside the image, but the agent must not request, decode, or expose provider payloads. Do not encode payment_entry_url or mobile_wallet_url into your own QR."
-    });
-  }
-  return action;
-}
-
-function attachAgentLocalQR(action, localPath = "") {
-  if (!action || !localPath) return action;
-  if (!Array.isArray(action.display)) {
-    action.display = [];
-  }
-  if (!action.display.some((item) => item?.type === "image" && item?.local_path === localPath)) {
-    action.display.push({
-      type: "image",
-      format: "png",
-      local_path: localPath,
-      instructions: "Render this local QR image for the human to scan. It encodes the ItPay human action URL, not a provider raw QR payload."
-    });
-  }
-  return action;
-}
-
-async function downloadQRImage(qrImageURL, file, flags = {}) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), apiTimeoutMs(flags));
-  let response;
-  try {
-    response = await fetch(qrImageURL, { method: "GET", signal: controller.signal });
-  } catch (error) {
-    if (error?.name === "AbortError") {
-      throw new Error(`QR image download timed out: ${qrImageURL}`);
-    }
-    throw error;
-  } finally {
-    clearTimeout(timer);
-  }
-  if (!response.ok) {
-    throw new Error(`QR image download failed: ${response.status}`);
-  }
-  const bytes = new Uint8Array(await response.arrayBuffer());
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, bytes);
-}
-
-function persistHumanAction(action, flags = {}) {
-  const runId = flags.run_id || readState().current_run_id;
-  if (!runId || !action?.id) return;
-  const run = readRun(runId);
-  if (!run?.human_action?.id || run.human_action.id !== action.id) return;
-  writeRun(mergeRun(run, { human_action: action }));
-}
-
-function shouldRenderTerminalQR(host) {
-  if (process.stderr.isTTY) return true;
-  return ["gemini", "gemini-cli"].includes(host);
-}
-
-function terminalQRType(flags = {}, host = "") {
-  const requested = String(flags.qr_format || process.env.ITP_QR_FORMAT || "").toLowerCase();
-  if (requested === "unicode" || requested === "utf8") return "utf8";
-  if (requested === "ansi" || requested === "terminal") return "terminal";
-  if (["gemini", "gemini-cli"].includes(host)) return "utf8";
-  return "terminal";
-}
-
-function shouldOpenBrowser(flags = {}) {
-  if (flags.no_open_browser || process.env.ITP_OPEN_BROWSER === "false" || process.env.ITP_OPEN_BROWSER === "0") return false;
-  if (flags.open_browser || process.env.ITP_OPEN_BROWSER === "true" || process.env.ITP_OPEN_BROWSER === "1") return true;
-  if (process.env.SSH_CONNECTION || process.env.CI) return false;
-  return Boolean(process.stderr.isTTY && (process.platform === "darwin" || process.platform === "win32" || process.env.DISPLAY || process.env.WAYLAND_DISPLAY || process.env.WSL_DISTRO_NAME));
-}
-
-function openBrowser(targetURL) {
-  try {
-    if (process.platform === "darwin") {
-      execFileSync("open", [targetURL], { stdio: "ignore", timeout: 2000 });
-      return true;
-    }
-    if (process.platform === "win32") {
-      execFileSync("cmd", ["/c", "start", "", targetURL], { stdio: "ignore", timeout: 2000 });
-      return true;
-    }
-    if (process.env.WSL_DISTRO_NAME && commandExists("cmd.exe")) {
-      execFileSync("cmd.exe", ["/c", "start", "", targetURL], { stdio: "ignore", timeout: 2000 });
-      return true;
-    }
-    if (commandExists("xdg-open")) {
-      execFileSync("xdg-open", [targetURL], { stdio: "ignore", timeout: 2000 });
-      return true;
-    }
-  } catch {
-    return false;
-  }
-  return false;
-}
-
-async function admin(command, rest, flags) {
-  if (command === "orders") {
-    const params = new URLSearchParams();
-    for (const key of ["account_id", "status", "provider", "limit"]) {
-      if (flags[key]) params.set(key, flags[key]);
-    }
-    const suffix = params.toString() ? `?${params.toString()}` : "";
-    output(await api(`/api/itp/admin/orders${suffix}`, { method: "GET" }, flags));
-    return;
-  }
-  if (command === "payment-events") {
-    const params = new URLSearchParams();
-    for (const key of ["order_id", "checkout_id", "out_trade_no", "provider", "event_type", "signature_verified", "limit"]) {
-      if (flags[key]) params.set(key, flags[key]);
-    }
-    const suffix = params.toString() ? `?${params.toString()}` : "";
-    output(await api(`/api/itp/admin/payment-events${suffix}`, { method: "GET" }, flags));
-    return;
-  }
-  if (command === "outbox") {
-    const params = new URLSearchParams();
-    for (const key of ["status", "event_type", "aggregate_id", "limit"]) {
-      if (flags[key]) params.set(key, flags[key]);
-    }
-    const suffix = params.toString() ? `?${params.toString()}` : "";
-    output(await api(`/api/itp/admin/outbox${suffix}`, { method: "GET" }, flags));
-    return;
-  }
-  if (command === "process-outbox") {
-    output(await api("/api/itp/admin/outbox/process", { method: "POST" }, flags));
-    return;
-  }
-  if (command === "recover-order") {
-    const orderId = rest[0];
-    if (!orderId) throw new Error("order_id is required");
-    output(await api(`/api/itp/admin/orders/${encodeURIComponent(orderId)}/recover`, { method: "POST" }, flags));
-    return;
-  }
-  throw new Error(`unknown admin command: ${command || ""}`);
-}
-
-async function coreApi(pathname, options = {}, flags = {}) {
-  const headers = { "Content-Type": "application/json" };
-  const credentials = readCredentials();
-  if (flags.access_token) {
-    const raw = String(flags.access_token);
-    headers.Authorization = raw.toLowerCase().startsWith("bearer ") ? raw : `Bearer ${raw}`;
-  } else {
-    const sessionToken = readSessionToken(credentials);
-    if (sessionToken) headers.Authorization = `Bearer ${sessionToken}`;
-  }
-  if (options.idempotencyKey || flags.idempotency_key) {
-    headers["Idempotency-Key"] = String(options.idempotencyKey || flags.idempotency_key);
-  }
-  if (!options.noAgentHeaders) {
-    headers["X-ItPay-Agent-Fingerprint"] = coreAgentFingerprint(flags);
-    headers["X-ItPay-Agent-Name"] = coreAgentDisplayName(flags);
-  }
-  if (options.ops) {
-    headers["X-ItPay-Ops-Token"] = sandboxOpsToken(flags);
-  }
-  Object.assign(headers, options.headers || {});
-  if (flags.request_id) headers["X-Request-ID"] = String(flags.request_id);
-  if (flags.correlation_id) headers["X-Correlation-ID"] = String(flags.correlation_id);
-  const targetURL = coreURL(pathname, flags);
-  const timeoutMs = apiTimeoutMs(flags);
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  let response;
-  try {
-    response = await fetch(targetURL, {
-      method: options.method || "GET",
-      headers,
-      body: options.body ? JSON.stringify(options.body) : undefined,
-      signal: controller.signal
-    });
-  } catch (error) {
-    if (error?.name === "AbortError") {
-      throw new Error(`request timed out after ${Math.ceil(timeoutMs / 1000)}s: ${safeRequestTarget(targetURL)}`);
-    }
-    throw new Error(`network request failed: ${safeRequestTarget(targetURL)}: ${safeErrorMessage(error)}`);
-  } finally {
-    clearTimeout(timer);
-  }
-  const text = await response.text();
-  let payload = {};
-  if (text) {
-    try {
-      payload = JSON.parse(text);
-    } catch {
-      payload = { text };
-    }
-  }
-  if (!response.ok || payload.success === false) {
-    const error = new Error(payload.error || payload.message || `request failed: ${response.status}`);
-    error.status = response.status;
-    if (response.status === 401 && String(pathname).startsWith("/v1/me/")) {
-      error.message = "buyer session required or expired; run status --refresh --json, then run setup --method alipay --json if unauthenticated";
-      error.next = [
-        { type: "verify_buyer_session", command: cliCommand("status", "--refresh", "--json"), safe_for_agent: true },
-        { type: "start_auth_if_needed", command: cliCommand("setup", "--method", "alipay", "--json"), safe_for_agent: true }
-      ];
-    }
-    throw error;
-  }
-  return payload.data ?? payload;
-}
-
-function safeRequestTarget(target) {
-  try {
-    const url = new URL(String(target));
-    return `${url.origin}${url.pathname}`;
-  } catch {
-    return String(target).split("?")[0];
-  }
-}
-
-function coreAgentFingerprint(flags = {}) {
-  const explicit = flags.agent_fingerprint || flags.agent_device_fingerprint || process.env.ITPAY_AGENT_FINGERPRINT || process.env.ITPAY_AGENT_DEVICE_FINGERPRINT;
-  if (explicit) return String(explicit);
-  const state = readState();
-  if (state.core_agent_fingerprint) return state.core_agent_fingerprint;
-  const fingerprint = `itp_cli_${cryptoRandom()}`;
-  writeState({ ...state, core_agent_fingerprint: fingerprint });
-  return fingerprint;
-}
-
-function coreAgentDisplayName(flags = {}) {
-  return String(flags.agent_name || flags.agent_display_name || process.env.ITPAY_AGENT_NAME || "ItPay CLI buyer agent");
-}
-
-function coreURL(pathname, flags = {}) {
-  if (/^https?:\/\//i.test(String(pathname))) return String(pathname);
-  return `${coreApiBase(flags)}${pathname.startsWith("/") ? "" : "/"}${pathname}`;
-}
-
-function coreApiBase(flags = {}, config = readConfig()) {
-  const base = flags.api_base || flags.core_api_base || process.env.ITPAY_API_BASE || process.env.ITPAY_CORE_API_BASE || process.env.ITPAY_CORE_BASE_URL || config.api_base || "https://dev.api.itpay.ai";
-  return String(base).replace(/\/$/, "");
-}
-
-function sandboxOpsToken(flags = {}) {
-  const token = flags.ops_token || flags.sandbox_ops_token || process.env.ITPAY_SANDBOX_OPS_TOKEN || process.env.ITPAY_OPS_TOKEN;
-  if (!token) throw new Error("sandbox ops token is required; set ITPAY_SANDBOX_OPS_TOKEN or pass --ops-token");
-  return String(token);
-}
-
-function queryString(params) {
-  const raw = params.toString();
-  return raw ? `?${raw}` : "";
-}
-
-function appendURLQuery(target, params) {
-  const suffix = params.toString();
-  if (!suffix) return target;
-  return `${target}${String(target).includes("?") ? "&" : "?"}${suffix}`;
-}
-
-function positional(values, index) {
-  const value = values[index];
-  if (!value || String(value).startsWith("--")) return "";
-  return String(value);
-}
-
-function positionalArgs(values = []) {
-  const result = [];
-  for (let i = 0; i < values.length; i += 1) {
-    const value = values[i];
-    if (!value) continue;
-    if (String(value).startsWith("--")) {
-      const next = values[i + 1];
-      if (next && !String(next).startsWith("--")) i += 1;
-      continue;
-    }
-    result.push(String(value));
-  }
-  return result;
-}
-
-function stripInternalBuyerFields(value) {
-  if (Array.isArray(value)) return value.map(stripInternalBuyerFields);
-  if (!value || typeof value !== "object") return value;
-  const result = {};
-  for (const [key, nested] of Object.entries(value)) {
-    if (key === "next_actions") continue;
-    result[key] = stripInternalBuyerFields(nested);
-  }
-  return result;
-}
-
-async function api(pathname, options, flags = {}) {
-  const config = readConfig();
-  const credentials = readCredentials();
-  const base = apiBase(flags, config);
-  const headers = { "Content-Type": "application/json" };
-  if (flags.access_token) {
-    headers.Authorization = String(flags.access_token);
-  } else {
-    const sessionToken = readSessionToken(credentials);
-    if (sessionToken) {
-      headers.Authorization = `Bearer ${sessionToken}`;
-    }
-  }
-  if (flags.new_api_user || flags.new_api_user_id || flags.user_id) {
-    headers["New-Api-User"] = String(flags.new_api_user || flags.new_api_user_id || flags.user_id);
-  }
-  const timeoutMs = apiTimeoutMs(flags);
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  let response;
-  try {
-    response = await fetch(`${base}${pathname}`, {
-      method: options.method,
-      headers,
-      body: options.body ? JSON.stringify(options.body) : undefined,
-      signal: controller.signal
-    });
-  } catch (error) {
-    if (error?.name === "AbortError") {
-      throw new Error(`request timed out after ${Math.ceil(timeoutMs / 1000)}s: ${pathname}`);
-    }
-    throw error;
-  } finally {
-    clearTimeout(timer);
-  }
-  const payload = await response.json().catch(() => ({}));
-  if (!response.ok || payload.success === false) {
-    throw new Error(payload.message || `request failed: ${response.status}`);
-  }
-  return payload.data ?? payload;
-}
-
-function apiTimeoutMs(flags = {}) {
-  const seconds = Number(flags.api_timeout || process.env.ITP_API_TIMEOUT_SECONDS || 45);
-  if (!Number.isFinite(seconds) || seconds <= 0) return 45000;
-  return Math.max(5000, seconds * 1000);
-}
-
-function parseFlags(args) {
-  const flags = {};
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
-    if (!arg.startsWith("--")) continue;
-    const key = arg.slice(2).replaceAll("-", "_");
-    const next = args[i + 1];
-    if (!next || next.startsWith("--")) {
-      flags[key] = true;
-    } else {
-      flags[key] = next;
-      i += 1;
-    }
-  }
-  return flags;
-}
-
-function normalizePurchaseFlags(flags, required = false) {
-  const plan = typeof flags.plan === "string" ? flags.plan.trim() : "";
-  const rawCredits = flags.credits ?? flags.credit ?? null;
-  const hasCredits = rawCredits !== null && rawCredits !== undefined && rawCredits !== false;
-  if (plan && hasCredits) {
-    throw new Error("use either --plan or --credits, not both");
-  }
-  if (hasCredits) {
-    const credits = Number(rawCredits);
-    if (!Number.isInteger(credits) || credits < 20) {
-      throw new Error("--credits must be an integer greater than or equal to 20");
-    }
-    return {
-      kind: "custom",
-      plan: null,
-      credits,
-      key: `credits-${credits}`
-    };
-  }
-  if (plan) {
-    if (plan === "coding-100") {
-      throw new Error("coding-100 is disabled; use credit-100, credit-300, credit-500, or --credits <amount>");
-    }
-    return {
-      kind: "plan",
-      plan,
-      credits: null,
-      key: `plan-${plan}`
-    };
-  }
-  if (required) {
-    throw new Error("choose a purchase: --credits <integer >=20> or --plan credit-100|credit-300|credit-500");
-  }
-  return { kind: null, plan: null, credits: null, key: "none" };
-}
-
-function apiBase(flags = {}, config = readConfig()) {
-  return (flags.api_base || config.api_base || DEFAULT_API_BASE).replace(/\/$/, "");
-}
-
-function readConfig() {
-  return readJSON(CONFIG_PATH, {});
-}
-
-function packageVersion() {
-  try {
-    return JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8")).version || "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-}
-
-function writeConfig(value) {
-  writeJSON0600(CONFIG_PATH, value);
-}
-
-function readState() {
-  return readJSON(STATE_PATH, {});
-}
-
-function writeState(value) {
-  writeJSON0600(STATE_PATH, value);
-}
-
-function runPath(runId) {
-  return path.join(RUNS_DIR, `${runId}.json`);
-}
-
-function readRun(runId) {
-  if (!runId) return null;
-  return readJSON(runPath(runId), null);
-}
-
-function listRuns() {
-  if (!fs.existsSync(RUNS_DIR)) return [];
-  return fs.readdirSync(RUNS_DIR)
-    .filter((name) => name.endsWith(".json"))
-    .map((name) => readJSON(path.join(RUNS_DIR, name), null))
-    .filter(Boolean)
-    .sort((a, b) => String(b.updated_at || "").localeCompare(String(a.updated_at || "")));
-}
-
-function writeRun(run) {
-  if (!run?.run_id) throw new Error("run_id is required");
-  ensureConfigDir();
-  fs.mkdirSync(RUNS_DIR, { recursive: true });
-  try {
-    fs.chmodSync(RUNS_DIR, 0o700);
-  } catch {
-    // Best effort on platforms without POSIX modes.
-  }
-  const next = {
-    ...run,
-    schema_version: "itp.run.v1",
-    updated_at: new Date().toISOString()
-  };
-  const file = runPath(next.run_id);
-  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
-  fs.writeFileSync(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
-  fs.renameSync(tmp, file);
-  try {
-    fs.chmodSync(file, 0o600);
-  } catch {
-    // Best effort on platforms without POSIX modes.
-  }
-  writeState({ ...readState(), current_run_id: next.run_id });
-  return next;
-}
-
-function mergeRun(run, patch) {
-  return {
-    ...(run || {}),
-    ...patch,
-    auth: patch.auth === undefined ? run?.auth : { ...(run?.auth || {}), ...(patch.auth || {}) },
-    account: patch.account === undefined ? run?.account : { ...(run?.account || {}), ...(patch.account || {}) },
-    checkout: patch.checkout === undefined ? run?.checkout : { ...(run?.checkout || {}), ...(patch.checkout || {}) },
-    payment: patch.payment === undefined ? run?.payment : { ...(run?.payment || {}), ...(patch.payment || {}) },
-    grant: patch.grant === undefined ? run?.grant : { ...(run?.grant || {}), ...(patch.grant || {}) },
-    result: patch.result === undefined ? run?.result : { ...(run?.result || {}), ...(patch.result || {}) }
-  };
-}
-
-function updateRun(run, patch) {
-  return writeRun(mergeRun(run, patch));
-}
-
-function updateCurrentRun(patch, flags = {}) {
-  const run = readRun(flags.run_id || readState().current_run_id);
-  if (!run) return null;
-  return writeRun(mergeRun(run, patch));
-}
-
-function prepareSetupRun(flags, options) {
-  const explicitRunId = flags.run_id || null;
-  const state = readState();
-  let run = explicitRunId ? readRun(explicitRunId) : (!flags.new_run ? readRun(state.current_run_id) : null);
-  const reusable = run
-    && !["done", "installed", "failed", "cancelled"].includes(run.status)
-    && run.phase !== "done"
-    && (!run.plan_id || run.plan_id === options.plan)
-    && (options.plan || !run.credits || Number(run.credits) === Number(options.credits || 0))
-    && (!run.payment_method || run.payment_method === options.method);
-  if (reusable) {
-    return writeRun(mergeRun(run, {
-      target: options.target,
-      plan_id: options.plan,
-      credits: options.credits,
-      purchase_kind: options.plan ? "plan" : "custom",
-      payment_method: options.method,
-      agent_host: flags.host || run.agent_host || null,
-      agent_display: flags.display || run.agent_display || null,
-      agent_qr_format: flags.qr_format || run.agent_qr_format || null,
-      install_runtime: Boolean(options.install_runtime),
-      status: "running"
-    }));
-  }
-  if (flags.resume && explicitRunId && !run) {
-    throw new Error(`run not found: ${explicitRunId}`);
-  }
-  const runId = explicitRunId || `run_${cryptoRandom()}`;
-  return writeRun({
-    schema_version: "itp.run.v1",
-    run_id: runId,
-    created_at: new Date().toISOString(),
-    api_base: apiBase(flags),
-    target: options.target,
-    install_runtime: Boolean(options.install_runtime),
-    plan_id: options.plan,
-    credits: options.credits,
-    purchase_kind: options.plan ? "plan" : "custom",
-    payment_method: options.method,
-    agent_host: flags.host || null,
-    agent_display: flags.display || null,
-    agent_qr_format: flags.qr_format || null,
-    idempotency_key: flags.idempotency_key || `setup:${runId}:${options.plan || `credits-${options.credits}`}`,
-    phase: "new",
-    status: "running",
-    safe_summary: "Setup started."
-  });
-}
-
-async function withStateLock(fn) {
-  ensureConfigDir();
-  const staleMs = 10 * 60 * 1000;
-  try {
-    const stat = fs.statSync(LOCK_PATH);
-    const lock = readJSON(LOCK_PATH, {});
-    if ((lock.pid && !processIsRunning(lock.pid)) || Date.now() - stat.mtimeMs > staleMs) {
-      fs.unlinkSync(LOCK_PATH);
-    }
-  } catch {
-    // No lock or unreadable stale state.
-  }
-  let fd;
-  try {
-    fd = fs.openSync(LOCK_PATH, "wx", 0o600);
-    fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, started_at: new Date().toISOString() }));
-  } catch {
-    const error = new Error(`another itp setup/status operation is running; if no other ItPay CLI is active, remove the stale lock and retry: rm -f ${LOCK_PATH}`);
-    error.next = [
-      { type: "check_status", command: cliCommand("status", "--refresh", "--json"), safe_for_agent: true },
-      { type: "clear_stale_lock", command: `rm -f ${shellQuote(LOCK_PATH)}`, safe_for_agent: true }
-    ];
-    throw error;
-  } finally {
-    if (fd !== undefined) fs.closeSync(fd);
-  }
-  try {
-    return await fn();
-  } finally {
-    try {
-      fs.unlinkSync(LOCK_PATH);
-    } catch {
-      // Best effort cleanup.
-    }
-  }
-}
-
-function readCredentials() {
-  return readJSON(CREDENTIALS_PATH, {});
-}
-
-function writeCredentials(value) {
-  writeJSON0600(CREDENTIALS_PATH, value);
-}
-
-function writeJSON0600(file, value) {
-  ensureConfigDir();
-  fs.writeFileSync(file, JSON.stringify(value, null, 2), { mode: 0o600 });
-  fs.chmodSync(file, 0o600);
-}
-
-function writeSessionCredentials(response) {
-  const currentAccountId = readConfig().account_id;
-  let credentials = deleteSessionCredential(readCredentials());
-  if (currentAccountId && currentAccountId !== response.account_id) {
-    for (const key of Object.keys(credentials)) {
-      if (key.startsWith("grant_")) {
-        const grantId = key.slice("grant_".length);
-        deleteGrantCredential(grantId);
-      }
-    }
-    credentials = {};
-  }
-  writeCredentials({ ...credentials, ...storeSessionCredential(response) });
-}
-
-function storeSessionCredential(response) {
-  const token = response.session_token;
-  const ref = `itpay:session:${response.account_id}:${response.device_id}`;
-  const nativeStore = writeNativeSecret(ref, token);
-  if (nativeStore.ok) {
-    return {
-      session_token_store: nativeStore.store,
-      session_token_ref: nativeStore.ref
-    };
-  }
-  return {
-    session_token: token,
-    session_token_store: "file",
-    session_token_warning: nativeStore.error
-  };
-}
-
-function readSessionToken(credentials = readCredentials()) {
-  if (credentials.session_token) {
-    return credentials.session_token;
-  }
-  if (credentials.session_token_store && credentials.session_token_ref) {
-    return readNativeSecret(credentials.session_token_store, credentials.session_token_ref);
-  }
-  return "";
-}
-
-function deleteSessionCredential(credentials) {
-  if (!credentials) {
-    return {};
-  }
-  if (credentials.session_token_store && credentials.session_token_ref) {
-    deleteNativeSecret(credentials.session_token_store, credentials.session_token_ref);
-  }
-  delete credentials.session_token;
-  delete credentials.session_token_store;
-  delete credentials.session_token_ref;
-  delete credentials.session_token_warning;
-  return credentials;
-}
-
-function sanitizeAuthResponse(response) {
-  const { session_token, ...safe } = response;
-  return { ...safe, session_stored: Boolean(session_token) };
-}
-
-function storeGrantCredential(grantId, credential) {
-  const credentials = readCredentials();
-  const key = credential.key;
-  const record = { ...credential };
-  delete record.key;
-  const nativeStore = writeNativeSecret(grantSecretRef(grantId), key);
-  if (nativeStore.ok) {
-    record.credential_store = nativeStore.store;
-    record.credential_ref = nativeStore.ref;
-  } else {
-    record.key = key;
-    record.credential_store = "file";
-    record.credential_warning = nativeStore.error;
-  }
-  credentials[`grant_${grantId}`] = record;
-  writeCredentials(credentials);
-  return record;
-}
-
-function readGrantCredential(grantId) {
-  const record = readCredentials()[`grant_${grantId}`];
-  if (!record) return null;
-  if (record.key) return record;
-  const key = readNativeSecret(record.credential_store, record.credential_ref);
-  return key ? { ...record, key } : record;
-}
-
-function deleteGrantCredential(grantId) {
-  const credentials = readCredentials();
-  const record = credentials[`grant_${grantId}`];
-  if (record?.credential_store && record?.credential_ref) {
-    deleteNativeSecret(record.credential_store, record.credential_ref);
-  }
-  delete credentials[`grant_${grantId}`];
-  writeCredentials(credentials);
-}
-
-function grantSecretRef(grantId) {
-  return `itpay:${grantId}`;
-}
-
-function detectNativeCredentialStore() {
-  if (!shouldUseNativeCredentialStore()) return "file";
-  if (process.platform === "darwin" && commandExists("security")) return "macos-keychain";
-  if (process.platform === "linux" && commandExists("secret-tool")) return "secret-tool";
-  return "unavailable";
-}
-
-function writeNativeSecret(ref, secret) {
-  if (!secret) return { ok: false, error: "empty secret" };
-  if (!shouldUseNativeCredentialStore()) {
-    return { ok: false, error: "native credential store disabled for non-interactive agent host" };
-  }
-  if (process.platform === "darwin" && commandExists("security")) {
-    try {
-      execFileSync("security", [
-        "add-generic-password",
-        "-a",
-        ref,
-        "-s",
-        "ItPay",
-        "-w",
-        secret,
-        "-U"
-      ], { stdio: "ignore" });
-      return { ok: true, store: "macos-keychain", ref };
-    } catch (error) {
-      return { ok: false, error: `macOS Keychain unavailable: ${error.message}` };
-    }
-  }
-  if (process.platform === "linux" && commandExists("secret-tool")) {
-    try {
-      execFileSync("secret-tool", [
-        "store",
-        "--label=ItPay",
-        "service",
-        "ItPay",
-        "account",
-        ref
-      ], { input: secret, stdio: ["pipe", "ignore", "ignore"] });
-      return { ok: true, store: "secret-tool", ref };
-    } catch (error) {
-      return { ok: false, error: `secret-tool unavailable: ${error.message}` };
-    }
-  }
-  return { ok: false, error: "native credential store unavailable" };
-}
-
-function shouldUseNativeCredentialStore() {
-  const store = String(process.env.ITP_CREDENTIAL_STORE || "").toLowerCase();
-  if (store === "file") return false;
-  if (store === "native" || store === "keychain" || store === "secret-tool") return true;
-  const disabled = String(process.env.ITP_DISABLE_NATIVE_CREDENTIAL_STORE || "").toLowerCase();
-  if (["1", "true", "yes"].includes(disabled)) return false;
-  if (process.env.CODEX_CI || process.env.CODEX_SHELL || process.env.CODEX_THREAD_ID) return false;
-  if (process.env.CI && !process.env.GITHUB_ACTIONS) return false;
-  return true;
-}
-
-function readNativeSecret(store, ref) {
-  if (!store || !ref) return "";
-  try {
-    if (store === "macos-keychain") {
-      return execFileSync("security", [
-        "find-generic-password",
-        "-a",
-        ref,
-        "-s",
-        "ItPay",
-        "-w"
-      ], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-    }
-    if (store === "secret-tool") {
-      return execFileSync("secret-tool", [
-        "lookup",
-        "service",
-        "ItPay",
-        "account",
-        ref
-      ], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-    }
-  } catch {
-    return "";
-  }
-  return "";
-}
-
-function deleteNativeSecret(store, ref) {
-  try {
-    if (store === "macos-keychain") {
-      execFileSync("security", [
-        "delete-generic-password",
-        "-a",
-        ref,
-        "-s",
-        "ItPay"
-      ], { stdio: "ignore" });
-    }
-    if (store === "secret-tool") {
-      execFileSync("secret-tool", [
-        "clear",
-        "service",
-        "ItPay",
-        "account",
-        ref
-      ], { stdio: "ignore" });
-    }
-  } catch {
-    // The local record is still removed; missing native secrets are harmless.
-  }
-}
-
-function commandExists(command) {
-  try {
-    execFileSync("which", [command], { stdio: "ignore" });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function processIsRunning(pid) {
-  const numericPid = Number(pid);
-  if (!Number.isInteger(numericPid) || numericPid <= 0) return false;
-  try {
-    process.kill(numericPid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function ensureConfigDir() {
-  fs.mkdirSync(CONFIG_DIR, { recursive: true });
-  try {
-    fs.chmodSync(CONFIG_DIR, 0o700);
-  } catch {
-    // Best effort; individual secret files are still written as 0600.
-  }
-}
-
-function readText(file, fallback) {
-  try {
-    return fs.readFileSync(file, "utf8");
-  } catch {
-    return fallback;
-  }
-}
-
-function readJSON(file, fallback) {
-  try {
-    return JSON.parse(fs.readFileSync(file, "utf8"));
-  } catch {
-    return fallback;
-  }
-}
-
-function writeJSONWithBackup(file, value, dryRun) {
-  return writeTextWithBackup(file, `${JSON.stringify(value, null, 2)}\n`, 0o600, dryRun);
-}
-
-function writeTextWithBackup(file, content, mode, dryRun) {
-  const backupPath = fs.existsSync(file) ? `${file}.itp-bak-${Date.now()}` : "";
-  if (dryRun) {
-    return { action: fs.existsSync(file) ? "would_update" : "would_create", backup_path: backupPath || null };
-  }
-  const dir = path.dirname(file);
-  if (dir === CONFIG_DIR) {
-    ensureConfigDir();
-  } else {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-  if (backupPath) {
-    fs.copyFileSync(file, backupPath);
-    fs.chmodSync(backupPath, mode);
-  }
-  fs.writeFileSync(file, content, { mode });
-  fs.chmodSync(file, mode);
-  return { action: backupPath ? "updated" : "created", backup_path: backupPath || null };
-}
-
-function fileMode(file) {
-  try {
-    return `0${(fs.statSync(file).mode & 0o777).toString(8)}`;
-  } catch {
-    return null;
-  }
-}
-
-function replaceManagedBlock(source, name, block) {
-  const start = `# >>> itp ${name}`;
-  const end = `# <<< itp ${name}`;
-  const managed = `${start}\n${block.trim()}\n${end}`;
-  const pattern = new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}`, "m");
-  const trimmed = source.trimEnd();
-  if (pattern.test(source)) return source.replace(pattern, managed);
-  return `${trimmed}${trimmed ? "\n\n" : ""}${managed}\n`;
-}
-
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-function escapeTomlString(value) {
-  return String(value).replaceAll("\\", "\\\\").replaceAll('"', '\\"');
-}
-
-function currentExecutable() {
-  return process.argv[1] || "itp";
-}
-
-function quoteShell(value) {
-  return `'${String(value).replaceAll("'", "'\\''")}'`;
-}
-
-function output(value) {
-  console.log(JSON.stringify(value, null, 2));
-}
-
-function outputError(error) {
-  const payload = { success: false, message: safeErrorMessage(error) };
-  if (error?.next) payload.next = error.next;
-  console.error(JSON.stringify(payload, null, 2));
-}
-
-function maskSecret(secret) {
-  if (!secret) return "";
-  if (secret.length <= 8) return "********";
-  return `${secret.slice(0, 4)}********${secret.slice(-4)}`;
-}
-
-function cryptoRandom() {
-	return crypto.randomUUID();
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}