@tokenbuddy/tokenbuddy 1.0.6 → 1.0.8

package/tests/tokenbuddy.test.ts

@@ -1,6 +1,19 @@
 import { TokenbuddyDaemon } from "../src/daemon.js";
-import { BuyerStore, resolveBuyerStorePath } from "../src/buyer-store.js";
-import { buildCli } from "../src/cli.js";
+import { BuyerStore, resolveBuyerStorePath, type PaymentConfig } from "../src/buyer-store.js";
+import {
+  buildCli,
+  fetchClawtipBootstrap,
+  normalizeClawtipBootstrapResourceUrl,
+} from "../src/cli.js";
+import {
+  checkOpenClawRuntime,
+  parseClawtipCliOutput,
+  readClawtipPayCredential,
+  resolveClawtipQrMediaPath,
+  startClawtipWalletBootstrap,
+  waitForClawtipActivationConfirmation,
+  writeClawtipOrderFile,
+} from "../src/init-clawtip-activation.js";
 import {
   applyProviderInstall,
   detectProviders,
@@ -10,14 +23,21 @@ import {
 import { detectTerminals } from "../src/terminal-detect.js";
 import {
   buildInitSuccessMessage,
-  buildInitTerminalOptions,
+  buildInitTerminalSelectionState,
   detectExistingClawtipBinding,
+  inspectClawtipWalletReadiness,
+  inspectOpenClawWalletConfig,
   INIT_COMING_SOON_PAYMENT_OPTIONS,
   INIT_PAYMENT_OPTIONS,
   noteInitComingSoonPayments,
   OTHER_TERMINAL_OPTION,
   validateInitTerminalSelection,
 } from "../src/init-payment-options.js";
+import { printDoctorClawtipWallet } from "../src/doctor-clawtip-wallet.js";
+import {
+  detectTerminalImageDisplay,
+  displayTerminalImage,
+} from "../src/terminal-image.js";
 import * as path from "path";
 import * as fs from "fs";
 import http from "http";
@@ -26,6 +46,8 @@ import zlib from "zlib";
 
 const TEMP_BUYER_DB = path.resolve(__dirname, "../../data-test/buyer-cache-test.db");
 const TEMP_STORE_ROOT = path.resolve(__dirname, "../../data-test/buyer-store-test");
+const INSPECTION_STORE_ROOT = path.resolve(__dirname, "../../data-test/json-inspection-store");
+const INSPECTION_HOME = path.resolve(__dirname, "../../data-test/json-inspection-home");
 const PACKAGE_JSON = path.resolve(__dirname, "../package.json");
 
 function rmSqliteFiles(dbPath: string): void {
@@ -119,15 +141,27 @@ describe("BuyerStore safe SQLite persistence", () => {
     expect(store.getToken("seller-a")).toBeUndefined();
 
     store.saveToken("seller-a", "raw-token-secret", "model:gpt-4", 500000, "2030-01-01T00:00:00.000Z");
-    expect(store.getToken("seller-a")).toEqual({
+    expect(store.getToken("seller-a")).toMatchObject({
       token: "raw-token-secret",
-      balanceMicros: 500000
+      balanceMicros: 500000,
+      reservedMicros: 0,
+      spentMicros: 0,
+      balanceSource: "purchase_complete"
     });
 
-    store.deductBalance("seller-a", 120000);
-    expect(store.getToken("seller-a")).toEqual({
+    store.reconcileTokenBalance({
+      sellerKey: "seller-a",
+      balanceMicros: 499890,
+      reservedMicros: 0,
+      spentMicros: 110,
+      balanceSource: "seller_settlement_summary"
+    });
+    expect(store.getToken("seller-a")).toMatchObject({
       token: "raw-token-secret",
-      balanceMicros: 380000
+      balanceMicros: 499890,
+      reservedMicros: 0,
+      spentMicros: 110,
+      balanceSource: "seller_settlement_summary"
     });
   });
 
@@ -471,6 +505,55 @@ describe("TokenBuddy init payment options", () => {
     }));
   });
 
+  test("requires the OpenClaw wallet config before reusing ClawTip metadata", () => {
+    const payment: PaymentConfig = {
+      method: "clawtip",
+      enabled: true,
+      isDefault: true,
+      updatedAt: "2026-05-30T00:00:00.000Z",
+      config: {
+        orderNo: "order_123",
+        resourceUrl: "https://example.test/pay"
+      }
+    };
+
+    const missingWallet = inspectClawtipWalletReadiness(payment, {
+      expectedPath: "/tmp/home/.openclaw/configs/config.json",
+      configsDirExists: true,
+      exists: false,
+      alternatePaths: ["/tmp/home/.openclaw/configs/config.json.bak"]
+    });
+    expect(missingWallet.status).toBe("metadata_missing_wallet");
+    expect(missingWallet.savedBinding?.orderNo).toBe("order_123");
+    expect(missingWallet.reusableBinding).toBeUndefined();
+
+    const readyWallet = inspectClawtipWalletReadiness(payment, {
+      expectedPath: "/tmp/home/.openclaw/configs/config.json",
+      configsDirExists: true,
+      exists: true,
+      alternatePaths: []
+    });
+    expect(readyWallet.status).toBe("ready");
+    expect(readyWallet.reusableBinding?.orderNo).toBe("order_123");
+  });
+
+  test("detects renamed OpenClaw wallet config files as nearby files", () => {
+    const home = path.join(TEMP_STORE_ROOT, "openclaw-home");
+    const configsDir = path.join(home, ".openclaw", "configs");
+    rmDir(home);
+    fs.mkdirSync(configsDir, { recursive: true });
+    fs.writeFileSync(path.join(configsDir, "config.json.bak"), "{}", "utf8");
+
+    const wallet = inspectOpenClawWalletConfig(home);
+
+    expect(wallet.exists).toBe(false);
+    expect(wallet.configsDirExists).toBe(true);
+    expect(wallet.expectedPath).toBe(path.join(configsDir, "config.json"));
+    expect(wallet.alternatePaths).toEqual([
+      path.join(configsDir, "config.json.bak")
+    ]);
+  });
+
   test("builds a clear init success message with summary lines", () => {
     const message = buildInitSuccessMessage([
       "2 programming terminals configured for TokenBuddy.",
@@ -483,8 +566,8 @@ describe("TokenBuddy init payment options", () => {
     expect(message).toContain("Run `tb doctor` to audit status anytime.");
   });
 
-  test("builds terminal options with configured entries marked as already installed", () => {
-    const options = buildInitTerminalOptions([
+  test("builds terminal selection with configured entries separated from selectable options", () => {
+    const selection = buildInitTerminalSelectionState([
       {
         id: "codex",
         name: "Codex CLI",
@@ -505,11 +588,13 @@ describe("TokenBuddy init payment options", () => {
       }
     ]);
 
-    expect(options).toEqual([
+    expect(selection.installed).toEqual([
       expect.objectContaining({
-        value: "codex:installed",
+        value: "codex",
         label: "Codex CLI（已安装）"
-      }),
+      })
+    ]);
+    expect(selection.options).toEqual([
       expect.objectContaining({
         value: "hermes",
         label: "Hermes Terminal"
@@ -521,14 +606,467 @@ describe("TokenBuddy init payment options", () => {
     ]);
   });
 
-  test("requires at least one actionable terminal choice", () => {
+  test("requires at least one terminal choice", () => {
     expect(validateInitTerminalSelection([])).toBe("Select at least one terminal or choose Other.");
-    expect(validateInitTerminalSelection(["codex:installed"])).toBe(
-      "Installed terminals are already configured. Select another terminal or choose Other."
-    );
     expect(validateInitTerminalSelection(["other"])).toBeUndefined();
     expect(validateInitTerminalSelection(["hermes"])).toBeUndefined();
   });
+
+  test("waits for ClawTip scan confirmation until the wallet config appears", async () => {
+    let attempts = 0;
+    const inspectWalletConfig = jest.fn(() => {
+      attempts += 1;
+      return {
+        expectedPath: "/tmp/home/.openclaw/configs/config.json",
+        configsDirExists: true,
+        exists: attempts >= 3,
+        alternatePaths: []
+      };
+    });
+    const sleep = jest.fn(async () => undefined);
+
+    await expect(waitForClawtipActivationConfirmation({
+      inspectWalletConfig,
+      pollIntervalMs: 10,
+      sleep,
+    })).resolves.toBe(true);
+
+    expect(inspectWalletConfig).toHaveBeenCalledTimes(3);
+    expect(sleep).toHaveBeenCalledTimes(2);
+  });
+
+  test("cancels ClawTip scan confirmation on Ctrl+C", async () => {
+    const cancelled = jest.fn();
+    await expect(
+      waitForClawtipActivationConfirmation({
+        inspectWalletConfig: () => ({
+          expectedPath: "/tmp/home/.openclaw/configs/config.json",
+          configsDirExists: true,
+          exists: false,
+          alternatePaths: []
+        }),
+        isCancelled: () => true,
+        cancel: cancelled,
+        pollIntervalMs: 10,
+        sleep: async () => undefined,
+      })
+    ).resolves.toBe(false);
+
+    expect(cancelled).toHaveBeenCalledWith("ClawTip activation cancelled.");
+  });
+
+  test("parses ClawTip auth URL and clawtipId from pay CLI output", () => {
+    const parsed = parseClawtipCliOutput(
+      "请扫码 https://clawtip.jd.com/qrcode?foo=1&clawtipId=device-789 完成授权"
+    );
+
+    expect(parsed.requiresWalletAuth).toBe(true);
+    expect(parsed.authUrl).toBe("https://clawtip.jd.com/qrcode?foo=1&clawtipId=device-789");
+    expect(parsed.clawtipId).toBe("device-789");
+  });
+
+  test("ignores bootstrap env endpoint noise when parsing the real ClawTip auth URL", () => {
+    const parsed = parseClawtipCliOutput([
+      "process.env.CLAWTIP_PAY https://ms.jr.jd.com/gw2/generic/hyqy/h5/m/clawtipPay",
+      "请扫码 https://idt.jd.com/unifiedAuthM/plat/safeMonitor/?authFlowUid=abc 完成授权",
+    ].join("\n"));
+
+    expect(parsed.authUrl).toBe(
+      "https://idt.jd.com/unifiedAuthM/plat/safeMonitor/?authFlowUid=abc"
+    );
+  });
+
+  test("parses the official ClawTip wallet QR image path", () => {
+    const parsed = parseClawtipCliOutput([
+      "从 .env.prod 加载环境变量",
+      "/Users/test/.openclaw/workspace/clawtip/qrcode/clawtip-index-code.png",
+    ].join("\n"));
+
+    expect(parsed.mediaPath).toBe("/Users/test/.openclaw/workspace/clawtip/qrcode/clawtip-index-code.png");
+    expect(parsed.requiresWalletAuth).toBe(true);
+  });
+
+  test("surfaces ClawTip upstream payment errors directly", async () => {
+    const parsed = parseClawtipCliOutput("ClawTip 返回错误：商家信息有误");
+
+    expect(parsed.failureMessage).toContain("商家信息有误");
+    await expect(startClawtipWalletBootstrap({
+      orderNo: "order_error",
+      amountFen: 1,
+      payTo: "pay-to-test",
+      encryptedData: "ciphertext",
+      indicator: "indicator_error",
+      slug: "tb-wallet-bootstrap",
+      skillId: "si-tb-wallet-bootstrap",
+      description: "TokenBuddy ClawTip wallet activation",
+      resourceUrl: "https://tb-wallet-bootstrap.fly.dev"
+    }, {
+      home: path.join(TEMP_STORE_ROOT, "clawtip-error-home"),
+      runClawtipCommand: async () => "ClawTip 返回错误：商家信息有误",
+    })).rejects.toThrow("ClawTip pay failed: ClawTip 返回错误：商家信息有误");
+  });
+
+  test("uses only ClawTip CLI media paths for QR resolution", () => {
+    expect(resolveClawtipQrMediaPath({
+      authUrl: "https://clawtip.jd.com/qrcode?clawtipId=device-789",
+      clawtipId: "device-789",
+      mediaPath: "/tmp/clawtip/qrcode-1.png",
+      requiresWalletAuth: true,
+      walletReady: false,
+    }, "/tmp/orders/order-1.json")).toBe("/tmp/clawtip/qrcode-1.png");
+  });
+
+  test("fails ClawTip QR resolution when pay CLI emits no QR source", () => {
+    expect(() => resolveClawtipQrMediaPath({
+      authUrl: undefined,
+      clawtipId: undefined,
+      mediaPath: undefined,
+      requiresWalletAuth: false,
+      walletReady: false,
+    }, "/tmp/orders/order-1.json")).toThrow("ClawTip pay did not return a QR media file.");
+  });
+
+  test("checks OpenClaw before ClawTip wallet bootstrap", async () => {
+    const calls: string[][] = [];
+    const openClawVersion = await checkOpenClawRuntime({
+      runOpenClawCommand: async (args) => {
+        calls.push(["openclaw", ...args]);
+        return "OpenClaw 2026.5.18";
+      },
+    });
+
+    expect(openClawVersion).toBe("OpenClaw 2026.5.18");
+    expect(calls).toEqual([
+      ["openclaw", "--version"],
+    ]);
+  });
+
+  test("normalizes the bootstrap resource URL away from the public registry endpoint", () => {
+    expect(normalizeClawtipBootstrapResourceUrl(
+      "https://tb-wallet-bootstrap.fly.dev",
+      "https://tb-wallet-bootstrap.fly.dev/registry/sellers"
+    )).toBe("https://tb-wallet-bootstrap.fly.dev");
+
+    expect(normalizeClawtipBootstrapResourceUrl(
+      "https://tb-wallet-bootstrap.fly.dev/base",
+      "https://tb-wallet-bootstrap.fly.dev/registry/sellers"
+    )).toBe("https://tb-wallet-bootstrap.fly.dev/base");
+
+    expect(normalizeClawtipBootstrapResourceUrl(
+      "https://tb-wallet-bootstrap.fly.dev",
+      "https://example.test/pay"
+    )).toBe("https://example.test/pay");
+  });
+
+  test("rejects a bootstrap response that still uses the placeholder ClawTip payTo", async () => {
+    const originalFetch = global.fetch;
+    global.fetch = jest.fn(async () => new Response(JSON.stringify({
+      activationFeeFen: 1,
+      payment: {
+        orderNo: "order_placeholder",
+        indicator: "indicator_placeholder",
+        payTo: "bootstrap-pay-to",
+        resourceUrl: "https://tb-wallet-bootstrap.fly.dev/registry/sellers",
+      }
+    }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" }
+    })) as typeof fetch;
+
+    try {
+      await expect(fetchClawtipBootstrap("https://tb-wallet-bootstrap.fly.dev")).rejects.toThrow(
+        "ClawTip bootstrap service is misconfigured: payTo is still the placeholder"
+      );
+    } finally {
+      global.fetch = originalFetch;
+    }
+  });
+
+  test("writes the Rust-compatible ClawTip order file shape", () => {
+    const home = path.join(TEMP_STORE_ROOT, "clawtip-order-home");
+    rmDir(home);
+
+    const orderFile = writeClawtipOrderFile({
+      orderNo: "order_123",
+      amountFen: 1,
+      payTo: "pay-to-test",
+      encryptedData: "ciphertext",
+      indicator: "indicator_123",
+      slug: "tb-wallet-bootstrap",
+      skillId: "si-tb-wallet-bootstrap",
+      description: "TokenBuddy ClawTip wallet activation",
+      resourceUrl: "https://tb-wallet-bootstrap.fly.dev"
+    }, home);
+
+    expect(orderFile).toBe(path.join(
+      home,
+      ".openclaw",
+      "skills",
+      "orders",
+      "indicator_123",
+      "order_123.json"
+    ));
+
+    const saved = JSON.parse(fs.readFileSync(orderFile, "utf8"));
+    expect(saved).toEqual(expect.objectContaining({
+      "skill-id": "si-tb-wallet-bootstrap",
+      order_no: "order_123",
+      amount: 1,
+      encrypted_data: "ciphertext",
+      pay_to: "pay-to-test",
+      slug: "tb-wallet-bootstrap",
+      resource_url: "https://tb-wallet-bootstrap.fly.dev"
+    }));
+  });
+
+  test("starts ClawTip payment activation and reads payCredential from the order file", async () => {
+    const home = path.join(TEMP_STORE_ROOT, "clawtip-bootstrap-home");
+    rmDir(home);
+
+    const activation = await startClawtipWalletBootstrap({
+      orderNo: "order_456",
+      amountFen: 1,
+      payTo: "pay-to-test",
+      encryptedData: "ciphertext",
+      indicator: "indicator_456",
+      slug: "tb-wallet-bootstrap",
+      skillId: "si-tb-wallet-bootstrap",
+      description: "TokenBuddy ClawTip wallet activation",
+      resourceUrl: "https://tb-wallet-bootstrap.fly.dev"
+    }, {
+      home,
+      runClawtipCommand: async () => {
+        const orderFile = path.join(
+          home,
+          ".openclaw",
+          "skills",
+          "orders",
+          "indicator_456",
+          "order_456.json"
+        );
+        const order = JSON.parse(fs.readFileSync(orderFile, "utf8"));
+        order.payCredential = "credential_456";
+        fs.writeFileSync(orderFile, JSON.stringify(order, null, 2), "utf8");
+        return "已获取到支付凭证";
+      }
+    });
+
+    expect(activation.orderFile).toBe(path.join(
+      home,
+      ".openclaw",
+      "skills",
+      "orders",
+      "indicator_456",
+      "order_456.json"
+    ));
+    expect(activation.payCredential).toBe("credential_456");
+    expect(readClawtipPayCredential(activation.orderFile)).toBe("credential_456");
+  });
+
+  test("recovers the latest generated ClawTip QR media path when pay output omits MEDIA", async () => {
+    const home = path.join(TEMP_STORE_ROOT, "clawtip-bootstrap-qr-home");
+    rmDir(home);
+
+    const activation = await startClawtipWalletBootstrap({
+      orderNo: "order_789",
+      amountFen: 1,
+      payTo: "pay-to-test",
+      encryptedData: "ciphertext",
+      indicator: "indicator_789",
+      slug: "tb-wallet-bootstrap",
+      skillId: "si-tb-wallet-bootstrap",
+      description: "TokenBuddy ClawTip wallet activation",
+      resourceUrl: "https://tb-wallet-bootstrap.fly.dev"
+    }, {
+      home,
+      runClawtipCommand: async () => {
+        const qrDir = path.join(home, ".openclaw", "workspace", "clawtip", "qrcode");
+        fs.mkdirSync(qrDir, { recursive: true });
+        const qrPath = path.join(qrDir, "qrcode-generated.png");
+        fs.writeFileSync(qrPath, "png", "utf8");
+        return [
+          "process.env.CLAWTIP_PAY https://ms.jr.jd.com/gw2/generic/hyqy/h5/m/clawtipPay",
+          "请扫码 https://idt.jd.com/unifiedAuthM/plat/safeMonitor/?authFlowUid=abc 完成授权",
+        ].join("\n");
+      }
+    });
+
+    expect(activation.parsedOutput.authUrl).toBe(
+      "https://idt.jd.com/unifiedAuthM/plat/safeMonitor/?authFlowUid=abc"
+    );
+    expect(activation.parsedOutput.mediaPath).toBe(
+      path.join(home, ".openclaw", "workspace", "clawtip", "qrcode", "qrcode-generated.png")
+    );
+  });
+
+  test("recovers ClawTip QR media even when pay output only writes payCredential", async () => {
+    const home = path.join(TEMP_STORE_ROOT, "clawtip-bootstrap-credential-and-qr-home");
+    rmDir(home);
+
+    const activation = await startClawtipWalletBootstrap({
+      orderNo: "order_credential_qr",
+      amountFen: 1,
+      payTo: "pay-to-test",
+      encryptedData: "ciphertext",
+      indicator: "indicator_credential_qr",
+      slug: "tb-wallet-bootstrap",
+      skillId: "si-tb-wallet-bootstrap",
+      description: "TokenBuddy ClawTip wallet activation",
+      resourceUrl: "https://tb-wallet-bootstrap.fly.dev"
+    }, {
+      home,
+      runClawtipCommand: async () => {
+        const orderFile = path.join(
+          home,
+          ".openclaw",
+          "skills",
+          "orders",
+          "indicator_credential_qr",
+          "order_credential_qr.json"
+        );
+        const order = JSON.parse(fs.readFileSync(orderFile, "utf8"));
+        order.payCredential = "credential_without_wallet_config";
+        fs.writeFileSync(orderFile, JSON.stringify(order, null, 2), "utf8");
+
+        const qrDir = path.join(home, ".openclaw", "workspace", "clawtip", "qrcode");
+        fs.mkdirSync(qrDir, { recursive: true });
+        const qrPath = path.join(qrDir, "qrcode-credential.png");
+        fs.writeFileSync(qrPath, "png", "utf8");
+        return "已获取到支付凭证";
+      }
+    });
+
+    expect(activation.payCredential).toBe("credential_without_wallet_config");
+    expect(activation.parsedOutput.requiresWalletAuth).toBe(true);
+    expect(activation.parsedOutput.mediaPath).toBe(
+      path.join(home, ".openclaw", "workspace", "clawtip", "qrcode", "qrcode-credential.png")
+    );
+  });
+
+  test("doctor prompts tb init when no ClawTip wallet is available", () => {
+    const lines: string[] = [];
+
+    printDoctorClawtipWallet({
+      status: "missing",
+      ready: false,
+      paymentMetadataPresent: false,
+      walletConfigPresent: false,
+      configsDirExists: false,
+      expectedPath: "/tmp/home/.openclaw/configs/config.json",
+      alternatePaths: [],
+      message: "ClawTip payment metadata and local OpenClaw wallet config are not configured.",
+    }, (line) => {
+      lines.push(line);
+    });
+
+    expect(lines.join("\n")).toContain(
+      "Action: Run `tb init` and choose ClawTip to bind a wallet before using ClawTip-backed purchases."
+    );
+  });
+});
+
+describe("TokenBuddy terminal image display", () => {
+  const imagePath = "/Users/test/.openclaw/workspace/clawtip/qrcode/clawtip-index-code.png";
+
+  test("detects inline image capable terminals only when stdout is a TTY", () => {
+    expect(detectTerminalImageDisplay({
+      env: { TERM_PROGRAM: "iTerm.app" },
+      stdoutIsTTY: true,
+    })).toBe("iterm");
+    expect(detectTerminalImageDisplay({
+      env: { WEZTERM_EXECUTABLE: "/Applications/WezTerm.app/wezterm" },
+      stdoutIsTTY: true,
+    })).toBe("iterm");
+    expect(detectTerminalImageDisplay({
+      env: { KITTY_WINDOW_ID: "1" },
+      stdoutIsTTY: true,
+    })).toBe("kitty");
+    expect(detectTerminalImageDisplay({
+      env: { TERM_PROGRAM: "iTerm.app" },
+      stdoutIsTTY: false,
+    })).toBeUndefined();
+  });
+
+  test("renders the ClawTip QR image inline for iTerm2-compatible terminals", async () => {
+    const writes: string[] = [];
+    const runCommand = jest.fn(async () => undefined);
+
+    const result = await displayTerminalImage(imagePath, {
+      env: { TERM_PROGRAM: "iTerm.app" },
+      stdoutIsTTY: true,
+      fileExists: () => true,
+      readFile: () => Buffer.from("png-bytes"),
+      write: (chunk) => {
+        writes.push(chunk);
+      },
+      runCommand,
+    });
+
+    expect(result).toEqual(expect.objectContaining({
+      method: "inline-iterm",
+      displayed: true,
+    }));
+    expect(writes.join("")).toContain("\u001B]1337;File=");
+    expect(writes.join("")).toContain("inline=1");
+    expect(runCommand).not.toHaveBeenCalled();
+  });
+
+  test("renders the ClawTip QR image inline for Kitty terminals", async () => {
+    const writes: string[] = [];
+
+    const result = await displayTerminalImage(imagePath, {
+      env: { TERM: "xterm-kitty" },
+      stdoutIsTTY: true,
+      fileExists: () => true,
+      write: (chunk) => {
+        writes.push(chunk);
+      },
+    });
+
+    expect(result).toEqual(expect.objectContaining({
+      method: "inline-kitty",
+      displayed: true,
+    }));
+    expect(writes.join("")).toContain("\u001B_Ga=T,t=f,f=100,c=60;");
+  });
+
+  test("opens the ClawTip QR image with the system viewer when inline images are unsupported", async () => {
+    const runCommand = jest.fn(async () => undefined);
+
+    const result = await displayTerminalImage(imagePath, {
+      env: { TERM_PROGRAM: "Apple_Terminal" },
+      platform: "darwin",
+      stdoutIsTTY: true,
+      fileExists: () => true,
+      runCommand,
+    });
+
+    expect(result).toEqual(expect.objectContaining({
+      method: "system-open",
+      displayed: true,
+      fallbackCommand: `open ${imagePath}`,
+    }));
+    expect(runCommand).toHaveBeenCalledWith("open", [imagePath]);
+  });
+
+  test("falls back to a manual open command when the system viewer fails", async () => {
+    const result = await displayTerminalImage(imagePath, {
+      env: {},
+      platform: "darwin",
+      stdoutIsTTY: true,
+      fileExists: () => true,
+      runCommand: async () => {
+        throw new Error("no gui session");
+      },
+    });
+
+    expect(result).toEqual(expect.objectContaining({
+      method: "manual",
+      displayed: false,
+      fallbackCommand: `open ${imagePath}`,
+    }));
+    expect(result.message).toContain("no gui session");
+  });
 });
 
 describe("TokenBuddy JSON inspection commands", () => {
@@ -538,10 +1076,31 @@ describe("TokenBuddy JSON inspection commands", () => {
   let proxyPort: number;
   let previousControlPort: string | undefined;
   let previousProxyPort: string | undefined;
+  let previousBuyerStoreRoot: string | undefined;
+  let previousHome: string | undefined;
 
   beforeEach((done) => {
     previousControlPort = process.env.TB_PROXYD_CONTROL_PORT;
     previousProxyPort = process.env.TB_PROXYD_PROXY_PORT;
+    previousBuyerStoreRoot = process.env.TOKENBUDDY_BUYER_STORE;
+    previousHome = process.env.HOME;
+    rmDir(INSPECTION_STORE_ROOT);
+    rmDir(INSPECTION_HOME);
+    process.env.TOKENBUDDY_BUYER_STORE = INSPECTION_STORE_ROOT;
+    process.env.HOME = INSPECTION_HOME;
+    fs.mkdirSync(path.join(INSPECTION_HOME, ".openclaw", "configs"), { recursive: true });
+    fs.writeFileSync(path.join(INSPECTION_HOME, ".openclaw", "configs", "config.json.bak"), "{}", "utf8");
+    const store = new BuyerStore();
+    store.savePayment({
+      method: "clawtip",
+      enabled: true,
+      isDefault: true,
+      config: {
+        orderNo: "order_json",
+        resourceUrl: "https://example.test/pay"
+      }
+    });
+    store.close();
     proxyServer = http.createServer((req, res) => {
       res.setHeader("Content-Type", "application/json");
       if (req.url === "/v1/models") {
@@ -650,8 +1209,22 @@ describe("TokenBuddy JSON inspection commands", () => {
     } else {
       process.env.TB_PROXYD_PROXY_PORT = previousProxyPort;
     }
+    if (previousBuyerStoreRoot === undefined) {
+      delete process.env.TOKENBUDDY_BUYER_STORE;
+    } else {
+      process.env.TOKENBUDDY_BUYER_STORE = previousBuyerStoreRoot;
+    }
+    if (previousHome === undefined) {
+      delete process.env.HOME;
+    } else {
+      process.env.HOME = previousHome;
+    }
     jest.restoreAllMocks();
-    controlServer.close(() => proxyServer.close(done));
+    controlServer.close(() => proxyServer.close(() => {
+      rmDir(INSPECTION_STORE_ROOT);
+      rmDir(INSPECTION_HOME);
+      done();
+    }));
   });
 
   test("doctor --json reports daemon and provider state", async () => {
@@ -694,6 +1267,16 @@ describe("TokenBuddy JSON inspection commands", () => {
       count: 1,
       registryUrl: "https://example.test/registry/sellers",
     });
+    expect(parsed.clawtipWallet).toMatchObject({
+      status: "metadata_missing_wallet",
+      ready: false,
+      paymentMetadataPresent: true,
+      walletConfigPresent: false,
+      expectedPath: path.join(INSPECTION_HOME, ".openclaw", "configs", "config.json"),
+      alternatePaths: [
+        path.join(INSPECTION_HOME, ".openclaw", "configs", "config.json.bak")
+      ]
+    });
     expect(parsed.providers).toEqual(expect.arrayContaining([
       expect.objectContaining({ id: "codex" }),
       expect.objectContaining({ id: "claude-code" })
@@ -709,6 +1292,10 @@ describe("TokenBuddy JSON inspection commands", () => {
     await buildCli().parseAsync(["node", "tb", "doctor"]);
 
     const joined = output.join("\n");
+    expect(joined).toContain("--- ClawTip Wallet ---");
+    expect(joined).toContain("❌ ClawTip Wallet [metadata_missing_wallet]");
+    expect(joined).toContain("Payment metadata: present");
+    expect(joined).toContain("Wallet config: missing");
     expect(joined).toContain("Checking local control plane and proxy endpoints...");
     expect(joined).toContain("Refreshing seller registry...");
     expect(joined).toContain("Model catalog hidden in `tb doctor`. Run `tb models` for the current model summary.");
@@ -1003,9 +1590,11 @@ describe("TokenBuddy CLI and Daemon Integration Tests", () => {
   let mockSellerServer: http.Server;
   let sellerReqCount = 0;
   let completeReqCount = 0;
+  let balanceReqCount = 0;
   let mockSellerPort: number;
   let daemonControlPort: number;
   let daemonProxyPort: number;
+  const insufficientFundsAttempts = new Map<string, number>();
   const sellerRequests: Array<{
     url?: string;
     authorization?: string;
@@ -1024,6 +1613,25 @@ describe("TokenBuddy CLI and Daemon Integration Tests", () => {
     });
   });
 
+  function setSettlementHeader(res: http.ServerResponse, requestId: string, settledMicros: number, remainingCreditMicros: number): void {
+    res.setHeader("X-TokenBuddy-Settlement", JSON.stringify({
+      requestId,
+      request_id: requestId,
+      settledMicros,
+      settled_micros: settledMicros,
+      settledUsdMicros: settledMicros,
+      settled_usd_micros: settledMicros,
+      remainingCreditMicros,
+      remaining_credit_micros: remainingCreditMicros,
+      reservedBalanceMicros: 0,
+      reserved_balance_micros: 0,
+      spentMicros: settledMicros,
+      spent_micros: settledMicros,
+      priceVersion: "openrouter_usd.v1",
+      price_version: "openrouter_usd.v1"
+    }));
+  }
+
   beforeAll((done) => {
     mockSellerServer = http.createServer(async (req, res) => {
       res.setHeader("Content-Type", "application/json");
@@ -1107,6 +1715,22 @@ describe("TokenBuddy CLI and Daemon Integration Tests", () => {
         return;
       }
 
+      if (req.url === "/v1/balance") {
+        balanceReqCount++;
+        sellerRequests.push({
+          url: req.url,
+          authorization: req.headers.authorization
+        });
+        res.end(JSON.stringify({
+          tokenId: "cred_mock",
+          creditMicros: 1000,
+          reservedMicros: 0,
+          spentMicros: 1999000,
+          currency: "Micros"
+        }));
+        return;
+      }
+
       if (req.url === "/v1/chat/completions") {
         const body = await readJsonBody(req);
         sellerRequests.push({
@@ -1115,12 +1739,37 @@ describe("TokenBuddy CLI and Daemon Integration Tests", () => {
           idempotencyKey: req.headers["idempotency-key"] as string | undefined,
           body
         });
+        if (body.requestId === "chat_req_402_retry") {
+          const attempts = insufficientFundsAttempts.get(body.requestId) || 0;
+          insufficientFundsAttempts.set(body.requestId, attempts + 1);
+          if (attempts === 0) {
+            res.statusCode = 402;
+            res.end(JSON.stringify({
+              error: {
+                code: "insufficient_funds",
+                message: "Insufficient funds"
+              }
+            }));
+            return;
+          }
+        }
         if (body.stream) {
           res.writeHead(200, { "Content-Type": "text/event-stream" });
           res.write("data: {\"id\":\"chatcmpl-stream\",\"choices\":[{\"delta\":{\"content\":\"hello\"}}]}\n\n");
+          res.write("event: tokenbuddy.settlement\n");
+          res.write(`data: ${JSON.stringify({
+            requestId: body.requestId || "stream_req_mock",
+            settledMicros: 110,
+            settledUsdMicros: 110,
+            remainingCreditMicros: 1999890,
+            reservedBalanceMicros: 0,
+            spentMicros: 110,
+            priceVersion: "openrouter_usd.v1"
+          })}\n\n`);
           res.end("data: [DONE]\n\n");
           return;
         }
+        setSettlementHeader(res, body.requestId || "chat_req_mock", 110, 1999890);
         res.end(JSON.stringify({
           id: "chatcmpl-mock",
           usage: { prompt_tokens: 10, completion_tokens: 10 }
@@ -1159,6 +1808,7 @@ describe("TokenBuddy CLI and Daemon Integration Tests", () => {
           res.end(compressed);
           return;
         }
+        setSettlementHeader(res, body.requestId || "responses_req_mock", 64, 1999936);
         res.end(JSON.stringify({
           id: "resp-mock",
           usage: { input_tokens: 7, output_tokens: 9 }
@@ -1174,6 +1824,7 @@ describe("TokenBuddy CLI and Daemon Integration Tests", () => {
           idempotencyKey: req.headers["idempotency-key"] as string | undefined,
           body
         });
+        setSettlementHeader(res, body.requestId || "messages_req_mock", 44, 1999956);
         res.end(JSON.stringify({
           id: "msg-mock",
           usage: { input_tokens: 5, output_tokens: 6 }
@@ -1198,6 +1849,8 @@ describe("TokenBuddy CLI and Daemon Integration Tests", () => {
     rmSqliteFiles(TEMP_BUYER_DB);
     sellerReqCount = 0;
     completeReqCount = 0;
+    balanceReqCount = 0;
+    insufficientFundsAttempts.clear();
     sellerRequests.length = 0;
     const seedStore = new BuyerStore({ dbPath: TEMP_BUYER_DB });
     seedStore.savePayment({
@@ -1385,11 +2038,75 @@ describe("TokenBuddy CLI and Daemon Integration Tests", () => {
     const inferences = await (await fetch(`${controlUrl}/ledger/inferences`)).json() as any;
     expect(purchases.purchases.some((entry: any) => entry.purchaseId === "pur_mock_123" && entry.paymentMethod === "mock")).toBe(true);
     expect(inferences.inferences.filter((entry: any) => entry.endpoint === "/v1/chat/completions")).toHaveLength(11);
+    const chatLedgers = inferences.inferences.filter((entry: any) => entry.requestId === "chat_req_parallel");
+    expect(chatLedgers).toHaveLength(10);
+    expect(chatLedgers).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        billedMicros: 110,
+        estimatedMicros: 80,
+        settledMicros: 110,
+        settledUsdMicros: 110,
+        priceVersion: "openrouter_usd.v1",
+        balanceSnapshotMicros: 1999890,
+        balanceSource: "seller_authoritative"
+      })
+    ]));
+    expect(balanceReqCount).toBe(0);
+    const store = new BuyerStore({ dbPath: TEMP_BUYER_DB });
+    try {
+      expect(store.getToken("mock-seller")).toMatchObject({
+        balanceMicros: 1999890,
+        reservedMicros: 0,
+        spentMicros: 110,
+        balanceSource: "seller_settlement_summary"
+      });
+    } finally {
+      store.close();
+    }
     const publicOutput = JSON.stringify({ purchases, inferences });
     expect(publicOutput).not.toContain("raw concurrent prompt secret");
     expect(publicOutput).not.toContain("tok_mock_token_abc");
   });
 
+  test("refreshes balance, auto-purchases, and retries once after seller 402 insufficient funds", async () => {
+    const store = new BuyerStore({ dbPath: TEMP_BUYER_DB });
+    store.saveToken("mock-seller", "tok_existing_high_cache", "model:gpt-4", 900000, "2030-01-01T00:00:00.000Z");
+    store.close();
+
+    const response = await fetch(`http://127.0.0.1:${daemonProxyPort}/v1/chat/completions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Idempotency-Key": "idem-402-retry"
+      },
+      body: JSON.stringify({
+        model: "gpt-4",
+        messages: [{ role: "user", content: "trigger 402" }],
+        requestId: "chat_req_402_retry"
+      })
+    });
+
+    expect(response.ok).toBe(true);
+    expect((await response.json() as any).id).toBe("chatcmpl-mock");
+    expect(balanceReqCount).toBe(1);
+    expect(sellerRequests.filter((request) => request.url === "/v1/chat/completions" && request.body?.requestId === "chat_req_402_retry")).toHaveLength(2);
+    expect(sellerRequests.filter((request) => request.url === "/purchase/create")).toHaveLength(1);
+    expect(sellerRequests.filter((request) => request.url === "/purchase/complete")).toHaveLength(1);
+    expect(sellerRequests.filter((request) => request.url === "/v1/chat/completions" && request.body?.requestId === "chat_req_402_retry")
+      .every((request) => request.idempotencyKey === "idem-402-retry")).toBe(true);
+
+    const inferences = await (await fetch(`http://127.0.0.1:${daemonControlPort}/ledger/inferences`)).json() as any;
+    expect(inferences.inferences).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        requestId: "chat_req_402_retry",
+        billedMicros: 110,
+        estimatedMicros: 80,
+        settledMicros: 110,
+        balanceSource: "seller_authoritative"
+      })
+    ]));
+  });
+
   test("proxies models, responses, and anthropic message endpoints through compatible seller manifests", async () => {
     const proxyUrl = `http://127.0.0.1:${daemonProxyPort}`;
 
@@ -1520,11 +2237,20 @@ describe("TokenBuddy CLI and Daemon Integration Tests", () => {
     const body = await response.text();
     expect(body).toContain("chatcmpl-stream");
     expect(body).toContain("[DONE]");
+    expect(body).not.toContain("tokenbuddy.settlement");
     expect(sellerRequests.find((request) => request.url === "/v1/chat/completions" && request.body?.stream)?.idempotencyKey).toBe("idem-stream-preserved");
 
     const inferences = await (await fetch(`http://127.0.0.1:${daemonControlPort}/ledger/inferences`)).json() as any;
     expect(inferences.inferences).toEqual(expect.arrayContaining([
-      expect.objectContaining({ endpoint: "/v1/chat/completions", requestId: "stream_req_1" })
+      expect.objectContaining({
+        endpoint: "/v1/chat/completions",
+        requestId: "stream_req_1",
+        status: "settled",
+        billedMicros: 110,
+        settledMicros: 110,
+        settledUsdMicros: 110,
+        balanceSource: "seller_authoritative"
+      })
     ]));
     const publicOutput = JSON.stringify(inferences);
     expect(publicOutput).not.toContain("raw stream prompt secret");