@itpay/cli 0.1.0

package/bin/itp

@@ -0,0 +1,4311 @@
+#!/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 VERSION = "0.1.2";
+const DEFAULT_API_BASE = process.env.ITPAY_API_BASE || process.env.ITPAY_CORE_BASE_URL || process.env.VOLTAGENT_API_BASE || "http://localhost:3000";
+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);
+
+main().catch((error) => {
+  outputError(error);
+  process.exit(1);
+});
+
+async function main() {
+  const args = process.argv.slice(2);
+  if ((args.length === 1 && args[0] === "--version") || args[0] === "version") {
+    output({ version: VERSION });
+    return;
+  }
+
+  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 === "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;
+  }
+  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;
+  }
+  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 (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;
+  }
+  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;
+    case "install claude-code":
+    case "install codex":
+    case "install openclaw":
+      await installRuntime(command, flags);
+      return;
+    case "doctor":
+      await doctor(flags);
+      return;
+    default:
+      output({
+        version: VERSION,
+        commands: [
+          "auth register",
+          "auth register --host gemini --display chat --no-wait --json",
+          "auth login",
+          "auth device start",
+          "auth device poll <auth_id>",
+          "setup --credits 100 --method alipay",
+          "setup --plan credit-300 --method alipay",
+          "setup --plan credit-300 --method alipay --host gemini --display chat --json",
+          "setup --credits 100 --target codex --method alipay --install-runtime",
+          "buy var_pubg_couple_skin_cny20 --sandbox --email buyer@example.com --phone +8613800000000 --json",
+          "buy var_pubg_couple_skin_cny20 --sandbox --email buyer@example.com --phone +8613800000000 --no-wait --json",
+          "buyer catalog search --query 企业工商 --category business_data_api --provider itpay_enterprise_data --json",
+          "buyer catalog get --variant var_pubg_couple_skin_cny20 --json",
+          "buyer cart create --variant var_pubg_couple_skin_cny20 --json",
+          "buyer cart create --variants var_itpay_enterprise_precise_lookup_cny05,var_itpay_enterprise_fuzzy_search_cny01 --quantities 1,1 --json",
+          "buyer cart show <cart_id> --json",
+          "buyer cart add <cart_id> --variant var_itpay_enterprise_fuzzy_search_cny01 --quantity 1 --json",
+          "buyer cart remove <cart_id> --line <cart_line_item_id> --json",
+          "buyer shelf manifest --json",
+          "buyer shelf snapshot --version <catalog_version> --json",
+          "buyer shelf delta --since <catalog_version> --json",
+          "buyer checkout create --cart <cart_id> --method alipay --email buyer@example.com --phone +8613800000000 --json",
+          "buyer checkout status <checkout_id> --json",
+          "buyer checkout resume <checkout_id> --json",
+          "buyer auth status --json",
+          "buyer payment wait <payment_intent_id> --json",
+          "buyer payment refresh-qr <payment_intent_id> --reason order-not-found --json",
+          "buyer deliveries list --checkout <checkout_id> --json",
+          "buyer deliveries show <delivery_id> --checkout <checkout_id> --json",
+          "buyer vault grants list --checkout <checkout_id> --json",
+          "buyer vault grants read <agent_read_grant_id> --json",
+          "buyer vault read --order <order_id> --artifact <vault_artifact_id> --json",
+          "account login-link --json",
+          "ops sandbox worker run-once --json",
+          "ops sandbox recover-alipay-once --json",
+          "ops sandbox payment query <payment_intent_id> --json",
+          "status --json",
+          "docs list --role buyer --json",
+          "docs show quickstart --role buyer --json",
+          "docs search <question> --role buyer --json",
+          "resume --json",
+          "resume --run-id <run_id> --host gemini --display none --json",
+          "runs list|current|show <run_id>|forget <run_id>",
+          "auth status",
+          "account show",
+          "account login-link",
+          "account set-password --password-stdin",
+          "plans list",
+          "plans show <plan>",
+          "checkout create --credits 100 --method alipay",
+          "checkout create --plan credit-300 --method alipay --idempotency-key <uuid>",
+          "checkout qr <checkout_id>",
+          "checkout open",
+          "checkout recover <checkout_id>",
+          "checkout list --limit 20",
+          "payment wait <checkout_id> --timeout 120",
+          "balance",
+          "usage --today --model <model>",
+          "grants list",
+          "grants show <grant_id>",
+          "grants install <grant_id> --target codex",
+          "grants revoke <grant_id>",
+          "keys list",
+          "keys rotate --grant <grant_id>",
+          "keys revoke --grant <grant_id>",
+          "token issue --grant <grant_id> --stdout",
+          "sync",
+          "skill show",
+          "skill show --role buyer --json",
+          "skill path --role buyer",
+          "admin orders --access-token <root_token> --new-api-user <id>",
+          "admin payment-events --access-token <root_token> --new-api-user <id>",
+          "admin outbox --access-token <root_token> --new-api-user <id>",
+          "admin process-outbox --access-token <root_token> --new-api-user <id>",
+          "admin recover-order <order_id> --access-token <root_token> --new-api-user <id>",
+          "install claude-code|codex|openclaw --grant <grant_id> [--offline|--no-test]",
+          "doctor"
+        ]
+      });
+  }
+}
+
+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("/api/ucp/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/public/shelf/manifest", { 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/public/shelf/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/public/shelf/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);
+      await maybeClaimBuyerSessionForCheckout(checkout, flags);
+      output(buyerRunOutput({
+        status: checkout.delivery_status || checkout.status,
+        checkout,
+        delivery: checkout.delivery,
+        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;
+        }
+      }
+      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, 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,
+        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 === "vault") {
+    if (subcommand === "grants") {
+      const action = rest[1] && !String(rest[1]).startsWith("--") ? rest[1] : "list";
+      if (action === "list") {
+        const grants = await listBuyerAgentReadGrants(flags);
+        output(buyerRunOutput({
+          status: "agent_read_grants",
+          ...grants,
+          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");
+        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") {
+      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}`);
+}
+
+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;
+  }
+  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("/api/ucp/v1/catalog/product", { 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("/api/ucp/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(`/api/ucp/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(`/api/ucp/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(`/api/ucp/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("/api/ucp/v1/checkouts", request, flags);
+  } catch (error) {
+    if (error?.status === 401 && readSessionToken(readCredentials()) && !flags.access_token) {
+      writeCredentials(deleteSessionCredential(readCredentials()));
+      checkout = await coreApi("/api/ucp/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/buyer/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;
+  }
+}
+
+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);
+}
+
+function parseBuyerAuthActionURL(action) {
+  const rawURL = action?.url || action?.auth_url || "";
+  if (!rawURL) return {};
+  try {
+    const parsed = new URL(rawURL);
+    const match = parsed.pathname.match(/\/v1\/buyer\/auth-sessions\/([^/]+)$/);
+    return {
+      authSessionID: match ? decodeURIComponent(match[1]) : "",
+      displayToken: parsed.searchParams.get("display_token") || ""
+    };
+  } catch {
+    return {};
+  }
+}
+
+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: action.auth_session_id || parsed.authSessionID,
+    url: action.url,
+    web_url: action.web_url || action.url,
+    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 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 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 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/buyer/accounts/${encodeURIComponent(config.account_id)}/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/vault/agent-read-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/vault/agent-read-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();
+    let auth = { authenticated: Boolean(readSessionToken(credentials)), account_id: config.account_id || null, device_id: config.device_id || null };
+    if (auth.authenticated && flags.refresh) {
+      try {
+        auth = await api("/api/itp/auth/status", { method: "GET" }, flags);
+      } catch (error) {
+        auth = { authenticated: false, account_id: config.account_id || null, error: error.message };
+      }
+    }
+      output({
+        schema_version: "itp.agent.v1",
+        status: auth.authenticated ? "idle" : "unauthenticated",
+      phase: auth.authenticated ? "idle" : "unauthenticated",
+      authenticated: Boolean(auth.authenticated),
+        account_id: auth.account_id || null,
+        device_id: auth.device_id || null,
+        next: auth.authenticated
+          ? { type: "choose_credits_or_plan", command: cliCommand("plans", "--json"), safe_for_agent: true }
+          : { type: "start_auth", command: cliCommand("setup", "--plan", "credit-300", "--method", "alipay", "--json"), safe_for_agent: true },
+        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 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/buyer/accounts/${encodeURIComponent(accountID)}/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, "voltagent.env");
+  const existing = readText(configPath, "");
+  const block = [
+    'model_provider = "voltagent"',
+    'model = "openai-code-default"',
+    "",
+    "[model_providers.voltagent]",
+    'name = "VoltaGent"',
+    `base_url = "${escapeTomlString(credentials.openai_base_url)}"`,
+    'env_key = "VOLTAGENT_API_KEY"'
+  ].join("\n");
+  const nextConfig = replaceManagedBlock(existing, "voltagent", block);
+  const configWrite = writeTextWithBackup(configPath, nextConfig, 0o600, dryRun);
+  const envWrite = writeTextWithBackup(envPath, `export VOLTAGENT_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 VOLTAGENT_API_KEY from its process environment; source ~/.itp/voltagent.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.voltagent = {
+    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: role === "voltagent" ? "voltagent" : "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: role === "voltagent" ? "voltagent" : "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 === "voltagent" || normalized === "legacy") return "voltagent";
+  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 = role === "voltagent" ? "voltagent" : "itpay-buyer";
+  const envPath = role === "buyer" ? process.env.ITPAY_BUYER_SKILL_PATH : process.env.ITPAY_CLI_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, "voltagent.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) && shouldPrepareLocalQRForJSON(mode, flags, action)) {
+      const localPath = await prepareGeneratedActionQRFile(action, flags, mode !== "file" && !flags.qr_file && !process.env.ITP_QR_FILE);
+      if (localPath) {
+        attachAgentGeneratedQRImage(action, localPath);
+        annotateHumanActionPresentation(action, "");
+        persistHumanAction(action, flags);
+        return { rendered: false, mode: "json-local-auth-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"] };
+    }
+    await attachAgentTextQR(action, flags);
+    persistHumanAction(action, flags);
+    return { rendered: false, mode: "agent-text-qr", host, outputs: ["agent_text_qr"] };
+  }
+
+  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);
+    } else {
+      await QRCode.toFile(file, action.url, { errorCorrectionLevel: "M", width: 512, margin: 2 });
+      action.local_qr_path = file;
+      action.local_qr_mime = "image/png";
+    }
+    process.stderr.write(`Alipay QR image: ${file}\n`);
+    renderResult.rendered = true;
+    renderResult.outputs.push(file);
+    if (mode === "file") return renderResult;
+  }
+
+  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;
+  if (action?.kind === "auth_qr" && mode !== "none" && mode !== "json") return true;
+  return mode === "agent" || mode === "chat";
+}
+
+function shouldGenerateLocalQRFromActionURL(action = {}) {
+  return action?.kind === "auth_qr" && Boolean(action?.url);
+}
+
+async function prepareGeneratedActionQRFile(action, flags = {}, optional = false) {
+  if (!action?.url) return "";
+  const file = flags.qr_file || process.env.ITP_QR_FILE || defaultQRFilePath(action, "");
+  try {
+    await QRCode.toFile(file, action.url, { errorCorrectionLevel: "M", width: 512, margin: 2 });
+  } 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;
+}
+
+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;
+}
+
+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 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 attachAgentGeneratedQRImage(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 ItPay first-purchase entry QR for the human to scan. It starts account login/registration/profile authorization and should continue to payment for the same checkout after approval; it is not payment proof."
+    });
+  }
+  return action;
+}
+
+async function attachAgentTextQR(action, flags = {}) {
+  if (!action?.url || action.agent_text_qr) return action;
+  const qr = await QRCode.toString(action.url, {
+    type: "utf8",
+    small: true,
+    errorCorrectionLevel: "M"
+  });
+  const lines = qr.replace(/\s+$/g, "").split(/\r?\n/);
+  const text = lines.join("\n");
+  const sha256 = crypto.createHash("sha256").update(text).digest("hex");
+  action.agent_text_qr = {
+    type: "terminal_text",
+    format: "unicode",
+    lines,
+    text,
+    fenced_text: `\`\`\`text\n${text}\n\`\`\``,
+    line_count: lines.length,
+    sha256,
+    url: action.url,
+    allowed_characters: "Only U+2588 FULL BLOCK, U+2580 UPPER HALF BLOCK, U+2584 LOWER HALF BLOCK, spaces, and newlines are valid inside the QR body.",
+    instructions: "Paste fenced_text verbatim into the normal assistant message, not the shell panel. Do not retype, translate, add line numbers, or add words inside the QR body. If any letters, digits, or Chinese characters appear inside the QR body, discard it and use the QR image URL/fallback link instead."
+  };
+  if (!Array.isArray(action.display)) {
+    action.display = [];
+  }
+  if (!action.display.some((item) => item?.type === "terminal_text")) {
+    action.display.push({
+      type: "terminal_text",
+      format: "unicode",
+      lines
+    });
+  }
+  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);
+  }
+  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: ${targetURL}`);
+    }
+    throw 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;
+    throw error;
+  }
+  return payload.data ?? payload;
+}
+
+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 = {}) {
+  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 || "http://127.0.0.1:18080";
+  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 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 {
+    throw new Error("another itp setup/status operation is running; retry shortly or remove stale ~/.itp/state.lock");
+  } 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 = `voltagent: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 `voltagent:${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",
+        "VoltaGent",
+        "-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=VoltaGent",
+        "service",
+        "VoltaGent",
+        "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",
+        "VoltaGent",
+        "-w"
+      ], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    if (store === "secret-tool") {
+      return execFileSync("secret-tool", [
+        "lookup",
+        "service",
+        "VoltaGent",
+        "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",
+        "VoltaGent"
+      ], { stdio: "ignore" });
+    }
+    if (store === "secret-tool") {
+      execFileSync("secret-tool", [
+        "clear",
+        "service",
+        "VoltaGent",
+        "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) {
+  console.error(JSON.stringify({ success: false, message: safeErrorMessage(error) }, 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));
+}