@tokenbuddy/tokenbuddy 1.0.14 → 1.0.16

package/src/daemon.ts

@@ -2,15 +2,30 @@ import express, { Request, Response } from "express";
 import * as crypto from "crypto";
 import { spawn } from "child_process";
 import * as fs from "fs";
+import * as path from "path";
 import { AddressInfo } from "net";
+import { ErrorCode } from "@tokenbuddy/contracts";
 import { createModuleLogger } from "@tokenbuddy/logging";
-import { BuyerStore } from "./buyer-store.js";
+import { BuyerStore, type PaymentConfig } from "./buyer-store.js";
+import { fetchClawtipBootstrap } from "./clawtip-bootstrap.js";
+import type { ClawtipBootstrapResponse } from "./clawtip-bootstrap.js";
+import {
+  inspectOpenClawWalletConfig,
+} from "./init-payment-options.js";
+import {
+  startClawtipWalletBootstrap,
+  waitForClawtipActivationConfirmation,
+  type ClawtipBootstrapPayment,
+  type ParsedClawtipOutput,
+  type WaitForClawtipActivationOptions,
+} from "./init-clawtip-activation.js";
 import {
   applyProviderInstall,
   detectProviders,
   previewProviderInstall,
   rollbackProviderInstall,
   type ClaudeCodeModelMappingConfig,
+  type ProviderCandidate,
 } from "./provider-install.js";
 import {
   discoverSellerBackedModels,
@@ -25,21 +40,122 @@ import {
   type SellerRegistryDocument,
 } from "./seller-catalog.js";
 import { ModelIndex } from "./model-index.js";
-import { PrewarmCache } from "./prewarm-cache.js";
+import { PrewarmCache, prewarmKey } from "./prewarm-cache.js";
 import { CreditTracker } from "./credit-tracker.js";
 import { SellerPool, type FailureKind } from "./seller-pool.js";
 import { RouteFailover, type FailoverDecision, type RouteCandidate } from "./route-failover.js";
-import { PrewarmScheduler, type SellerProber } from "./prewarm-scheduler.js";
+import { PrewarmScheduler, type PrewarmReason, type SellerProber } from "./prewarm-scheduler.js";
 import type { PoolEntry } from "./seller-pool.js";
 import { planSellerRouteSet } from "./seller-route-planner.js";
+import type { SellerRoutePlan } from "./seller-route-planner.js";
 import {
+  assertSellerRoutingConfig,
   mergeSellerRoutingConfig,
+  normalizeSellerRoutingConfig,
+  parseSellerIdList,
   ROUTING_CONFIG_KEY,
   type BuyerSellerRoutingConfig
 } from "./seller-routing-config.js";
 
 const logger = createModuleLogger("tb-proxyd");
+const FOCUS_SET_CONFIG_KEY = "focus-set";
 const PROXY_JSON_BODY_LIMIT = "10mb";
+const SELLER_CAPACITY_BLOCK_MS = 2_000;
+const CLAWTIP_STATIC_ROUTE = "/static/clawtip";
+const CLAWTIP_RECHARGE_QR_FILE = "recharge.png";
+
+function currentModuleDir(): string {
+  if (typeof __dirname !== "undefined") {
+    return __dirname;
+  }
+
+  const stack = new Error().stack || "";
+  const fileUrlMatch = stack.match(/(file:\/\/\/[^)\n]+\/daemon\.js):\d+:\d+/);
+  if (fileUrlMatch) {
+    return path.dirname(new URL(fileUrlMatch[1]).pathname);
+  }
+
+  const filePathMatch = stack.match(/(\/[^)\n]+\/daemon\.(?:js|ts)):\d+:\d+/);
+  if (filePathMatch) {
+    return path.dirname(filePathMatch[1]);
+  }
+
+  return process.cwd();
+}
+
+interface ClientToolStatus {
+  id: string;
+  name: string;
+  status: ProviderCandidate["status"] | "manual";
+  detected: boolean;
+  configured: boolean;
+  configPath?: string;
+  commandName?: string;
+  reason: string;
+  manualConfig?: {
+    openaiBaseUrl: string;
+    anthropicBaseUrl: string;
+    apiKey: string;
+  };
+}
+
+function clientToolStatusFromProvider(provider: ProviderCandidate): ClientToolStatus {
+  return {
+    id: provider.id,
+    name: provider.name,
+    status: provider.status,
+    detected: provider.detected,
+    configured: provider.configured,
+    configPath: provider.configPath,
+    commandName: provider.commandName,
+    reason: provider.reason,
+  };
+}
+
+function buildCustomClientToolStatus(proxyPort: number): ClientToolStatus {
+  const openaiBaseUrl = `http://127.0.0.1:${proxyPort}/v1`;
+  const anthropicBaseUrl = `http://127.0.0.1:${proxyPort}`;
+  return {
+    id: "custom",
+    name: "Custom client",
+    status: "manual",
+    detected: true,
+    configured: false,
+    reason: `OpenAI-compatible: ${openaiBaseUrl} · Anthropic-compatible: ${anthropicBaseUrl}`,
+    manualConfig: {
+      openaiBaseUrl,
+      anthropicBaseUrl,
+      apiKey: "TOKENBUDDY_PROXY",
+    },
+  };
+}
+
+/**
+ * 解析 `tb-ui` 构建产物目录(daemon 静态托管 SPA 用)。
+ * 优先级:env TB_UI_DIR > npm 包内 static/ui > workspace tb-ui/dist。
+ * 找不到时记录 warning 仍允许 daemon 启动(纯 API 模式);静态请求会 404。
+ */
+function resolveUiDir(): string | undefined {
+  if (process.env.TB_UI_DIR) return process.env.TB_UI_DIR;
+  const here = currentModuleDir();
+  const bundledUiDirs = [
+    path.resolve(here, "../../static/ui"),
+    path.resolve(here, "../static/ui")
+  ];
+  for (const bundledUiDir of bundledUiDirs) {
+    if (fs.existsSync(path.join(bundledUiDir, "index.html"))) {
+      return bundledUiDir;
+    }
+  }
+  try {
+    // require.resolve 在 npm workspaces 装好时能找到 tb-ui/package.json
+    const pkgPath = require.resolve("tb-ui/package.json");
+    return path.join(path.dirname(pkgPath), "dist");
+  } catch {
+    // fallback: monorepo 假设 daemon dist 跟 tb-ui/dist 在同 root
+    return path.resolve(here, "../../tb-ui/dist");
+  }
+}
 
 /**
  * buyer 端守护进程（`tb-proxyd`）的配置。
@@ -56,6 +172,21 @@ export interface DaemonConfig {
   sellerRegistryUrl: string;
   /** 路由策略覆盖（与 `TB_SELLER_ROUTING_*` env 合并） */
   sellerRouting?: BuyerSellerRoutingConfig;
+  /** test-only override for ClawTip bootstrap payload fetch. */
+  clawtipBootstrapFetcher?: (bootstrapUrl: string) => Promise<ClawtipBootstrapResponse>;
+  /** test-only override for the existing tb init ClawTip activation runner. */
+  clawtipWalletBootstrapStarter?: (
+    payment: ClawtipBootstrapPayment,
+    options?: { home?: string }
+  ) => Promise<{ orderFile: string; parsedOutput: ParsedClawtipOutput; payCredential?: string }>;
+  /** test-only override for waiting on the existing tb init ClawTip registration loop. */
+  clawtipActivationWaiter?: (options?: WaitForClawtipActivationOptions) => Promise<boolean>;
+  /** test-only override for bundled ClawTip static assets; false disables bundled assets. */
+  clawtipBundledStaticDir?: string | false;
+  /** test-only home override for OpenClaw wallet and QR discovery. */
+  clawtipHomeDir?: string;
+  /** test-only home override for provider/client configuration detection. */
+  providerHomeDir?: string;
   /**
    * v1.2 §18.4 预热 focus-set 覆盖。
    * 缺省时由 BuyerStore 历史模型使用情况 + `TB_BUYER_WARMUP_MODELS` env 推导。
@@ -94,6 +225,24 @@ interface ProxyBodySummary {
   temperaturePresent?: boolean;
 }
 
+interface SellerHealthBody {
+  upstream?: {
+    status?: unknown;
+    lastErrorClass?: unknown;
+    last_error_class?: unknown;
+  };
+  capacity?: {
+    activeConnections?: unknown;
+    active_connections?: unknown;
+    maxConnections?: unknown;
+    max_connections?: unknown;
+    queueDepth?: unknown;
+    queue_depth?: unknown;
+    maxQueueDepth?: unknown;
+    max_queue_depth?: unknown;
+  };
+}
+
 interface SellerSettlementSummary {
   requestId: string;
   settledMicros: number;
@@ -227,6 +376,60 @@ function summarizeProxyBody(body: unknown): ProxyBodySummary {
   };
 }
 
+function finiteNumber(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}
+
+function readErrorCode(bodyText: string): string | undefined {
+  try {
+    const parsed = JSON.parse(bodyText) as { error?: { code?: unknown }; code?: unknown };
+    const code = parsed.error?.code ?? parsed.code;
+    return typeof code === "string" ? code : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function isBusyCapacityErrorBody(bodyText: string | undefined): boolean {
+  if (!bodyText) {
+    return false;
+  }
+  return readErrorCode(bodyText) === ErrorCode.BusyCapacity;
+}
+
+function capacityBlockedUntilFromHealth(body: SellerHealthBody, now: number): number | undefined {
+  const capacity = body.capacity;
+  if (!capacity) {
+    return undefined;
+  }
+  const activeConnections = finiteNumber(capacity.activeConnections ?? capacity.active_connections);
+  const maxConnections = finiteNumber(capacity.maxConnections ?? capacity.max_connections);
+  const queueDepth = finiteNumber(capacity.queueDepth ?? capacity.queue_depth);
+  const maxQueueDepth = finiteNumber(capacity.maxQueueDepth ?? capacity.max_queue_depth);
+  if (
+    activeConnections === undefined ||
+    maxConnections === undefined ||
+    queueDepth === undefined ||
+    maxQueueDepth === undefined
+  ) {
+    return undefined;
+  }
+  if (maxConnections <= 0) {
+    return undefined;
+  }
+  const connectionsFull = activeConnections >= maxConnections;
+  const queueUnavailable = maxQueueDepth <= 0;
+  const queueFull = queueUnavailable || queueDepth >= maxQueueDepth;
+  return connectionsFull && queueFull ? now + SELLER_CAPACITY_BLOCK_MS : undefined;
+}
+
 function reorderDefaultSellerFirst(sellers: RegistrySeller[], defaultSellerId: string | undefined): RegistrySeller[] {
   if (!defaultSellerId) {
     return sellers;
@@ -275,6 +478,15 @@ export class TokenbuddyDaemon {
   private selectionMode: "auto" | "manual";
   private selectedSellerId?: string;
   private sellerRouting: BuyerSellerRoutingConfig;
+  private lastRoutingPrewarmKey?: string;
+  private readonly lazyPrewarmKeys = new Set<string>();
+  private clawtipActivationWait?: Promise<void>;
+  private clawtipActivationWaitCancelToken?: { cancelled: boolean };
+  /**
+   * tb-ui v1 控制平面 `PUT /prewarm/focus-set` 写入的 explicit focus set。
+   * 优先级最高；`null` 表示回退到 env / historical（与 `resolveFocusSet()` 原行为一致）。
+   */
+  private currentFocusSet: string[] | null = null;
 
   private activePurchases = new Map<string, Promise<string>>();
 
@@ -302,13 +514,20 @@ export class TokenbuddyDaemon {
     this.tokenStore = new BuyerStore({ dbPath: config.dbPath });
     const storedRouting = this.tokenStore.getDaemonRuntimeConfig<unknown>(ROUTING_CONFIG_KEY)
       ?.config;
+    const storedFocusSet = this.tokenStore.getDaemonRuntimeConfig<{ models?: string[] }>(FOCUS_SET_CONFIG_KEY)
+      ?.config;
     this.config = config;
     this.sellerRouting = mergeSellerRoutingConfig(
       storedRouting,
       config.sellerRouting
     );
-    this.selectionMode = this.sellerRouting.mode === "fullAuto" ? "auto" : "manual";
-    this.selectedSellerId = this.sellerRouting.mode === "fixed" ? this.sellerRouting.sellerId : undefined;
+    this.selectionMode = selectionModeForRouting(this.sellerRouting);
+    this.selectedSellerId = selectedSellerIdForRouting(this.sellerRouting);
+    // tb-ui v1: explicit focus set 优先于 env / historical
+    if (storedFocusSet && Array.isArray(storedFocusSet.models)) {
+      const deduped = Array.from(new Set(storedFocusSet.models.map((m) => m.trim()).filter(Boolean)));
+      this.currentFocusSet = deduped.length > 0 ? deduped : null;
+    }
     // v1.2 §18.5: scheduler is created here (not in the field initializer)
     // because it needs the config-derived prober + idle interval.
     Object.assign(this, {
@@ -339,7 +558,22 @@ export class TokenbuddyDaemon {
         if (!res.ok) {
           return { ok: false, latencyMs: Date.now() - startedAt, httpStatus: res.status, errorMessage: `health returned ${res.status}` };
         }
-        return { ok: true, latencyMs: Date.now() - startedAt, httpStatus: res.status };
+        const now = Date.now();
+        const body = await res.json() as SellerHealthBody;
+        const upstream = body.upstream;
+        const upstreamErrorClass = upstream?.lastErrorClass ?? upstream?.last_error_class;
+        return {
+          ok: true,
+          latencyMs: now - startedAt,
+          httpStatus: res.status,
+          upstreamStatus: typeof upstream?.status === "string"
+            ? upstream.status as "healthy" | "degraded" | "unhealthy" | "unknown"
+            : undefined,
+          upstreamErrorClass: typeof upstreamErrorClass === "string"
+            ? upstreamErrorClass
+            : undefined,
+          capacityBlockedUntil: capacityBlockedUntilFromHealth(body, now)
+        };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         return { ok: false, latencyMs: 0, errorMessage: message };
@@ -357,6 +591,201 @@ export class TokenbuddyDaemon {
     return typeof address === "object" && address ? address.port : this.config.proxyPort;
   }
 
+  private clawtipStaticDir(): string {
+    return path.join(path.dirname(this.config.dbPath), "static", "clawtip");
+  }
+
+  private bundledClawtipStaticDir(): string | undefined {
+    if (this.config.clawtipBundledStaticDir === false) {
+      return undefined;
+    }
+    if (typeof this.config.clawtipBundledStaticDir === "string") {
+      return fs.existsSync(this.config.clawtipBundledStaticDir) ? this.config.clawtipBundledStaticDir : undefined;
+    }
+    const here = currentModuleDir();
+    const candidates = [
+      path.resolve(here, "../static/clawtip"),
+      path.resolve(here, "../../static/clawtip"),
+      path.resolve(process.cwd(), "packages/tokenbuddy-cli/static/clawtip")
+    ];
+    return candidates.find((candidate) => fs.existsSync(candidate));
+  }
+
+  private clawtipPublicUrl(fileName: string): string {
+    return `${CLAWTIP_STATIC_ROUTE}/${encodeURIComponent(fileName)}`;
+  }
+
+  private ensureClawtipStaticAssets(): void {
+    const outputDir = this.clawtipStaticDir();
+    fs.mkdirSync(outputDir, { recursive: true });
+    const rechargeOutputPath = path.join(outputDir, CLAWTIP_RECHARGE_QR_FILE);
+    if (fs.existsSync(rechargeOutputPath)) {
+      return;
+    }
+    const bundledDir = this.bundledClawtipStaticDir();
+    const rechargeSourcePath = bundledDir ? path.join(bundledDir, CLAWTIP_RECHARGE_QR_FILE) : undefined;
+    if (rechargeSourcePath && fs.existsSync(rechargeSourcePath)) {
+      fs.copyFileSync(rechargeSourcePath, rechargeOutputPath);
+    }
+  }
+
+  private copyClawtipQrToStatic(mediaPath: string, orderNo: string): { fileName: string; url: string; path: string } {
+    if (!fs.existsSync(mediaPath)) {
+      throw new Error(`ClawTip QR image does not exist: ${mediaPath}`);
+    }
+    const extension = safeQrExtension(mediaPath);
+    const fileName = `${safeStaticFileSegment(orderNo)}-${Date.now()}${extension}`;
+    const outputDir = this.clawtipStaticDir();
+    fs.mkdirSync(outputDir, { recursive: true });
+    const outputPath = path.join(outputDir, fileName);
+    fs.copyFileSync(mediaPath, outputPath);
+    return {
+      fileName,
+      path: outputPath,
+      url: this.clawtipPublicUrl(fileName)
+    };
+  }
+
+  private async startClawtipActivationQr(): Promise<ClawtipQrResponse> {
+    const bootstrapUrl = process.env.TOKENBUDDY_BOOTSTRAP_URL || "https://tb-wallet-bootstrap.fly.dev";
+    const fetchBootstrap = this.config.clawtipBootstrapFetcher || fetchClawtipBootstrap;
+    const bootstrap = await fetchBootstrap(bootstrapUrl);
+    const payment = normalizeClawtipActivationPayment(bootstrap);
+    const startBootstrap = this.config.clawtipWalletBootstrapStarter || startClawtipWalletBootstrap;
+    const activation = await startBootstrap(payment, { home: this.config.clawtipHomeDir });
+    if (!activation.parsedOutput.mediaPath) {
+      throw new Error("ClawTip activation did not return a QR image.");
+    }
+    const staticQr = this.copyClawtipQrToStatic(activation.parsedOutput.mediaPath, payment.orderNo);
+    const walletConfig = inspectOpenClawWalletConfig(this.config.clawtipHomeDir);
+    const existingPayment = this.tokenStore.getPayment("clawtip");
+    this.tokenStore.savePayment({
+      method: "clawtip",
+      enabled: walletConfig.exists,
+      isDefault: existingPayment?.isDefault ?? true,
+      config: {
+        ...(existingPayment?.config ?? {}),
+        bootstrapUrl,
+        orderNo: payment.orderNo,
+        amountFen: payment.amountFen,
+        indicator: payment.indicator,
+        slug: payment.slug,
+        skillId: payment.skillId,
+        description: payment.description,
+        resourceUrl: payment.resourceUrl,
+        activationOrderFile: activation.orderFile,
+        walletConfigPath: walletConfig.expectedPath,
+        walletConfigPresent: walletConfig.exists,
+        activationQrImagePath: activation.parsedOutput.mediaPath,
+        activationQrImageUrl: staticQr.url,
+        authUrl: activation.parsedOutput.authUrl,
+        clawtipId: activation.parsedOutput.clawtipId,
+        payCredentialWritten: Boolean(activation.payCredential),
+        activationCompletedBy: activation.payCredential
+          ? (walletConfig.exists ? "payCredential+wallet-config" : "payCredential")
+          : walletConfig.exists ? "wallet-config" : "pending-wallet-scan"
+      }
+    });
+    this.scheduleClawtipActivationWait(activation.parsedOutput.clawtipId);
+    return {
+      ok: true,
+      kind: "activate",
+      method: "clawtip",
+      orderNo: payment.orderNo,
+      amountFen: payment.amountFen,
+      qrImageUrl: staticQr.url,
+      sourceImagePath: activation.parsedOutput.mediaPath,
+      staticImagePath: staticQr.path,
+      authUrl: activation.parsedOutput.authUrl,
+      clawtipId: activation.parsedOutput.clawtipId,
+      orderFile: activation.orderFile,
+      walletConfigPath: walletConfig.expectedPath,
+      walletConfigPresent: walletConfig.exists,
+      requiresWalletAuth: activation.parsedOutput.requiresWalletAuth,
+      payCredentialWritten: Boolean(activation.payCredential)
+    };
+  }
+
+  private scheduleClawtipActivationWait(clawtipId?: string): void {
+    if (this.clawtipActivationWait) {
+      return;
+    }
+    const cancelToken = { cancelled: false };
+    this.clawtipActivationWaitCancelToken = cancelToken;
+    const waitForActivation = this.config.clawtipActivationWaiter || waitForClawtipActivationConfirmation;
+    this.clawtipActivationWait = waitForActivation({
+      clawtipId,
+      inspectWalletConfig: () => inspectOpenClawWalletConfig(this.config.clawtipHomeDir),
+      isCancelled: () => cancelToken.cancelled,
+      cancel: () => undefined
+    })
+      .then((walletRegistered) => {
+        if (cancelToken.cancelled) {
+          return;
+        }
+        if (!walletRegistered) {
+          logger.info("control.payment.clawtip.activation_wait.pending", "ClawTip activation wait ended before wallet registration");
+          return;
+        }
+        const walletConfig = inspectOpenClawWalletConfig(this.config.clawtipHomeDir);
+        const payment = this.tokenStore.getPayment("clawtip");
+        if (!payment || payment.method !== "clawtip") {
+          return;
+        }
+        this.tokenStore.savePayment({
+          ...payment,
+          enabled: walletConfig.exists,
+          config: {
+            ...(payment.config ?? {}),
+            walletConfigPath: walletConfig.expectedPath,
+            walletConfigPresent: walletConfig.exists,
+            activationCompletedBy: walletConfig.exists
+              ? "wallet-config"
+              : readConfigString(payment.config, "activationCompletedBy") ?? "pending-wallet-scan"
+          }
+        });
+        logger.info("control.payment.clawtip.activation_wait.completed", "ClawTip activation wait completed", {
+          walletRegistered,
+          walletConfigPresent: walletConfig.exists
+        });
+      })
+      .catch((error: unknown) => {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("control.payment.clawtip.activation_wait.failed", "ClawTip activation wait failed", { errorMessage });
+      })
+      .finally(() => {
+        if (this.clawtipActivationWaitCancelToken === cancelToken) {
+          this.clawtipActivationWaitCancelToken = undefined;
+          this.clawtipActivationWait = undefined;
+        }
+      });
+  }
+
+  private clawtipRechargeQr(): ClawtipQrResponse {
+    const payment = this.tokenStore.getPayment("clawtip");
+    const resourceUrl = readConfigString(payment?.config, "resourceUrl");
+    const orderNo = readConfigString(payment?.config, "orderNo") || "clawtip-recharge";
+    const mediaPath = path.join(this.clawtipStaticDir(), CLAWTIP_RECHARGE_QR_FILE);
+    if (!fs.existsSync(mediaPath)) {
+      throw new Error(`ClawTip fixed recharge QR image is missing: ${mediaPath}`);
+    }
+    const walletConfig = inspectOpenClawWalletConfig(this.config.clawtipHomeDir);
+    return {
+      ok: true,
+      kind: "recharge",
+      method: "clawtip",
+      orderNo,
+      qrImageUrl: this.clawtipPublicUrl(CLAWTIP_RECHARGE_QR_FILE),
+      sourceImagePath: mediaPath,
+      staticImagePath: mediaPath,
+      resourceUrl,
+      walletConfigPath: walletConfig.expectedPath,
+      walletConfigPresent: walletConfig.exists,
+      requiresWalletAuth: false,
+      payCredentialWritten: readConfigBoolean(payment?.config, "payCredentialWritten")
+    };
+  }
+
   // v1.2 §18.9: stale-cache fallback. The buyer remembers the last
   // successfully fetched registry document and reuses it when the
   // bootstrap returns 413 (`X-TokenBuddy-Registry-Too-Large: 1`). This
@@ -397,6 +826,7 @@ export class TokenbuddyDaemon {
   }
 
   private runtimeSummary() {
+    this.refreshSellerRoutingConfig();
     return {
       status: "running",
       pid: process.pid,
@@ -502,7 +932,7 @@ export class TokenbuddyDaemon {
     return payments.find((payment) => payment.isDefault)?.method || payments.find((payment) => payment.method === "mock")?.method;
   }
 
-  private async selectSellerRoutes(endpoint: string, modelId: string): Promise<SellerRoute[]> {
+  private async selectSellerRoutes(endpoint: string, modelId: string): Promise<{ routes: SellerRoute[]; plan: SellerRoutePlan; paymentMethod: string }> {
     const protocol = this.endpointProtocol(endpoint);
     if (!protocol) {
       throw new Error(`unsupported proxy endpoint: ${endpoint}`);
@@ -515,12 +945,14 @@ export class TokenbuddyDaemon {
     // v1.2: registry is the source of truth for routing. We rebuild the
     // model-index once per request (cheap; index lookup is in-memory) so
     // the response always reflects the latest seller list. The previous
-    // "fetchSellerManifest per candidate" path is removed in favor of
+    // "fetchSellerManifest per request" path is removed in favor of
     // pulling `models` directly off the registry entries.
     const registry = await this.fetchRegistry();
 
-    const routing = this.sellerRouting;
+    const routing = resolveSellerRoutingForModel(this.refreshSellerRoutingConfig(), modelId);
     const registrySellers = reorderDefaultSellerFirst(registry.sellers, registry.defaultSeller);
+    this.sellerPool.ensureRegistrySellers(registrySellers);
+    this.scheduleLazyPrewarmIfNeeded(modelId, protocol, paymentMethod);
     const poolById = new Map(this.sellerPool.snapshot().map((entry) => [entry.sellerId, entry]));
     const planned = planSellerRouteSet({
       modelId,
@@ -533,8 +965,12 @@ export class TokenbuddyDaemon {
         sellerId: entry.sellerId,
         healthScore: entry.healthScore,
         avgLatencyMs: entry.avgLatencyMs,
-        circuit: entry.circuit
-      }))
+        ttftMs: entry.ttftMs,
+        avgInferenceMs: entry.avgInferenceMs,
+        circuit: entry.circuit,
+        capacityBlockedUntil: entry.capacityBlockedUntil
+      })),
+      now: Date.now()
     });
 
     if (planned.routes.length === 0) {
@@ -564,7 +1000,122 @@ export class TokenbuddyDaemon {
       sellerCount: routes.length,
       sellers: routes.map((route) => route.seller.id)
     });
-    return routes;
+    return { routes, plan: planned, paymentMethod };
+  }
+
+  private refreshSellerRoutingConfig(): BuyerSellerRoutingConfig {
+    const storedRouting = this.tokenStore.getDaemonRuntimeConfig<unknown>(ROUTING_CONFIG_KEY)
+      ?.config;
+    const nextRouting = mergeSellerRoutingConfig(
+      storedRouting,
+      this.config.sellerRouting
+    );
+
+    if (!sameSellerRouting(this.sellerRouting, nextRouting)) {
+      const previous = this.sellerRouting;
+      this.sellerRouting = nextRouting;
+      this.selectionMode = selectionModeForRouting(nextRouting);
+      this.selectedSellerId = selectedSellerIdForRouting(nextRouting);
+      logger.info("routing.config.reloaded", "seller routing config reloaded", {
+        previousMode: previous.mode,
+        previousScorer: previous.scorer,
+        sellerRoutingMode: nextRouting.mode,
+        sellerRoutingScorer: nextRouting.scorer,
+        selectedSellerId: this.selectedSellerId
+      });
+      void this.runRoutingPrewarmSweep(nextRouting);
+    }
+
+    return this.sellerRouting;
+  }
+
+  private async runRoutingPrewarmSweep(routing: BuyerSellerRoutingConfig): Promise<void> {
+    const focusSet = this.resolveFocusSet();
+    const routingPrewarmKey = `${routingKey(routing)}\u0001${focusSet.join("\u0001")}`;
+    if (focusSet.length === 0) {
+      logger.info("prewarm.routing.skipped", "no focus set configured after routing reload; relying on lazy prewarms", {
+        sellerRoutingMode: routing.mode,
+        sellerRoutingScorer: routing.scorer
+      });
+      return;
+    }
+    if (this.lastRoutingPrewarmKey === routingPrewarmKey) {
+      return;
+    }
+    this.lastRoutingPrewarmKey = routingPrewarmKey;
+    logger.info("prewarm.routing.scheduled", "routing reload prewarm sweep scheduled", {
+      sellerRoutingMode: routing.mode,
+      sellerRoutingScorer: routing.scorer,
+      focusSetSize: focusSet.length,
+      focusSet: focusSet.slice(0, 20)
+    });
+    try {
+      await this.fetchRegistry();
+      const paymentMethod = this.defaultPaymentMethod();
+      for (const modelId of focusSet) {
+        this.schedulePrewarmForModel({
+          modelId,
+          reason: "explicit",
+          protocol: this.resolvePrewarmProtocol(modelId, paymentMethod),
+          paymentMethod
+        });
+      }
+    } catch (err) {
+      logger.warn("prewarm.routing.failed", "routing reload prewarm sweep failed", {
+        sellerRoutingMode: routing.mode,
+        sellerRoutingScorer: routing.scorer,
+        errorMessage: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+
+  private scheduleLazyPrewarmIfNeeded(modelId: string, protocol: string, paymentMethod: string): void {
+    const freshness = this.prewarmCache.freshness(modelId, protocol, paymentMethod);
+    if (freshness.present && !freshness.expired) {
+      return;
+    }
+    const key = prewarmKey(modelId, protocol, paymentMethod);
+    if (this.lazyPrewarmKeys.has(key)) {
+      return;
+    }
+    this.lazyPrewarmKeys.add(key);
+    logger.info("prewarm.lazy.scheduled", "lazy prewarm scheduled for requested model", {
+      modelId,
+      protocol,
+      paymentMethod,
+      freshnessState: freshness.state
+    });
+    this.schedulePrewarmForModel({
+      modelId,
+      reason: "lazy",
+      protocol,
+      paymentMethod
+    }).finally(() => {
+      this.lazyPrewarmKeys.delete(key);
+    });
+  }
+
+  private schedulePrewarmForModel(input: {
+    modelId: string;
+    reason: PrewarmReason;
+    protocol?: string;
+    paymentMethod?: string;
+  }): Promise<unknown> {
+    if (!input.protocol || !input.paymentMethod) {
+      logger.warn("prewarm.schedule.skipped", "prewarm schedule skipped because protocol or payment method is missing", {
+        modelId: input.modelId,
+        reason: input.reason,
+        protocol: input.protocol,
+        paymentMethod: input.paymentMethod
+      });
+      return Promise.resolve();
+    }
+    return this.prewarmScheduler.schedulePrewarm({
+      modelId: input.modelId,
+      reason: input.reason,
+      protocol: input.protocol,
+      paymentMethod: input.paymentMethod
+    });
   }
 
   private failoverErrorMessage(error: unknown): string {
@@ -580,13 +1131,16 @@ export class TokenbuddyDaemon {
    * caller side because it short-circuits the failure path with a
    * re-purchase.
    */
-  private classifyFailureStatus(status: number): FailureKind {
+  private classifyFailureStatus(status: number, bodyText?: string): FailureKind {
     if (status === 401 || status === 403) {
       return "auth_invalid";
     }
     if (status === 402) {
       return "insufficient_funds";
     }
+    if (status === 429 && isBusyCapacityErrorBody(bodyText)) {
+      return "busy_capacity";
+    }
     if (status === 400 || status === 404 || status === 422) {
       return "hard_4xx";
     }
@@ -770,7 +1324,16 @@ export class TokenbuddyDaemon {
     usage: UsageSummary,
     settlement: SellerSettlementSummary | undefined,
     prompt: string | undefined,
-    response?: string
+    response?: string,
+    extras?: {
+      ttftMs?: number;
+      fallbackCount?: number;
+      routeReason?: string;
+      falloverChain?: string[];
+      upstreamStatus?: string;
+      durationMs?: number;
+      paymentMethod?: string;
+    }
   ): void {
     if (settlement) {
       this.tokenStore.reconcileTokenBalance({
@@ -800,7 +1363,14 @@ export class TokenbuddyDaemon {
       balanceSnapshotMicros: settlement?.remainingCreditMicros,
       balanceSource: settlement ? "seller_authoritative" : "estimated",
       prompt,
-      response
+      response,
+      ttftMs: extras?.ttftMs,
+      fallbackCount: extras?.fallbackCount,
+      routeReason: extras?.routeReason,
+      falloverChain: extras?.falloverChain,
+      upstreamStatus: extras?.upstreamStatus,
+      durationMs: extras?.durationMs,
+      paymentMethod: extras?.paymentMethod
     });
     logger.info("inference.ledger.recorded", "safe inference ledger recorded", {
       requestId: settlement?.requestId || requestId,
@@ -815,7 +1385,14 @@ export class TokenbuddyDaemon {
       promptTokens: usage.promptTokens,
       completionTokens: usage.completionTokens,
       balanceSnapshotMicros: settlement?.remainingCreditMicros,
-      balanceSource: settlement ? "seller_authoritative" : "estimated"
+      balanceSource: settlement ? "seller_authoritative" : "estimated",
+      ttftMs: extras?.ttftMs,
+      fallbackCount: extras?.fallbackCount,
+      routeReason: extras?.routeReason,
+      falloverChain: extras?.falloverChain,
+      upstreamStatus: extras?.upstreamStatus,
+      durationMs: extras?.durationMs,
+      paymentMethod: extras?.paymentMethod
     });
   }
 
@@ -1316,6 +1893,10 @@ export class TokenbuddyDaemon {
 
   private async forwardProxyRequest(endpoint: string, req: Request, res: Response): Promise<void> {
     const startedAt = Date.now();
+    let firstByteAt: number | null = null;
+    const markFirstByte = (): void => {
+      if (firstByteAt === null) firstByteAt = Date.now();
+    };
     const body = req.body || {};
     const { requestedModelId, resolvedModelId } = this.resolveRouteModelId(endpoint, body);
     const modelId = resolvedModelId;
@@ -1328,7 +1909,12 @@ export class TokenbuddyDaemon {
     }
 
     try {
-      const routes = await this.selectSellerRoutes(endpoint, modelId);
+      const { routes, plan, paymentMethod } = await this.selectSellerRoutes(endpoint, modelId);
+      const upstreamStatusFromHeaders = (h: Headers): string | undefined => {
+        const raw = h.get("x-tokenbuddy-upstream-status") || h.get("x-upstream-status");
+        if (!raw) return undefined;
+        return raw === "healthy" || raw === "degraded" || raw === "unhealthy" || raw === "unknown" ? raw : "unknown";
+      };
       let lastError: unknown;
 
       for (let routeIndex = 0; routeIndex < routes.length; routeIndex += 1) {
@@ -1336,6 +1922,7 @@ export class TokenbuddyDaemon {
         const sellerKey = route.seller.id;
         logger.info("route.selected", "seller route selected", {
           sellerKey,
+          sellerId: sellerKey,
           model: modelId,
           endpoint,
           protocol: route.protocol,
@@ -1493,7 +2080,7 @@ export class TokenbuddyDaemon {
                   status: upstreamResponse.status,
                   durationMs: Date.now() - startedAt
                 });
-                const kind: FailureKind = this.classifyFailureStatus(upstreamResponse.status);
+                const kind: FailureKind = this.classifyFailureStatus(upstreamResponse.status, errorBody);
                 const decision = this.routeFailover.decide(
                   {
                     sellerId: sellerKey,
@@ -1568,6 +2155,7 @@ export class TokenbuddyDaemon {
                 // 缺 event: 行）由卖方修，buyer 不兜底。
                 const sellerChunk = settlementExtractor.push(chunk);
                 if (sellerChunk.length > 0) {
+                  markFirstByte();
                   res.write(sellerChunk);
                 }
               }
@@ -1579,11 +2167,13 @@ export class TokenbuddyDaemon {
               if (decoderTail.length > 0) {
                 const sellerTail = settlementExtractor.push(decoderTail);
                 if (sellerTail.length > 0) {
+                  markFirstByte();
                   res.write(sellerTail);
                 }
               }
               const settlementTrailing = settlementExtractor.finish();
               if (settlementTrailing.downstream.length > 0) {
+                markFirstByte();
                 res.write(settlementTrailing.downstream);
               }
               res.end();
@@ -1593,12 +2183,23 @@ export class TokenbuddyDaemon {
                 requestId,
                 { promptTokens: 0, completionTokens: 0, billedMicros: Math.max(1, bytes) },
                 this.parseSellerSettlementSummary(upstreamResponse.headers) ?? settlementTrailing.settlement ?? settlementExtractor.current(),
-                this.inferPromptForHash(body)
+                this.inferPromptForHash(body),
+                undefined,
+                {
+                  ttftMs: firstByteAt ? firstByteAt - startedAt : undefined,
+                  fallbackCount: routeIndex,
+                  routeReason: plan.reason,
+                  falloverChain: routes.slice(0, routeIndex + 1).map((r) => r.seller.id),
+                  upstreamStatus: upstreamStatusFromHeaders(upstreamResponse.headers),
+                  durationMs: Date.now() - startedAt,
+                  paymentMethod
+                }
               );
               return;
             }
 
             const responseBody = await upstreamResponse.text();
+            markFirstByte();
             res.send(responseBody);
             const usage = this.readUsage(responseBody);
             this.recordReconciledInference(
@@ -1608,7 +2209,16 @@ export class TokenbuddyDaemon {
               usage,
               this.parseSellerSettlementSummary(upstreamResponse.headers),
               this.inferPromptForHash(body),
-              responseBody
+              responseBody,
+              {
+                ttftMs: firstByteAt ? firstByteAt - startedAt : undefined,
+                fallbackCount: routeIndex,
+                routeReason: plan.reason,
+                falloverChain: routes.slice(0, routeIndex + 1).map((r) => r.seller.id),
+                upstreamStatus: upstreamStatusFromHeaders(upstreamResponse.headers),
+                durationMs: Date.now() - startedAt,
+                paymentMethod
+              }
             );
             return;
           } catch (routeError: unknown) {
@@ -1710,10 +2320,42 @@ export class TokenbuddyDaemon {
     controlApp.get("/payments", (req, res) => {
       logger.info("control.payments.requested", "control payments requested", {});
       res.status(200).json({
-        payments: this.tokenStore.listPayments()
+        payments: this.tokenStore.listPayments().map((payment) => withLiveClawtipWalletState(payment, this.config.clawtipHomeDir))
       });
     });
 
+    controlApp.post("/payments/clawtip/activate", async (req, res) => {
+      try {
+        const qr = await this.startClawtipActivationQr();
+        logger.info("control.payment.clawtip.activate_qr.created", "ClawTip activation QR copied for tb-ui", {
+          orderNo: qr.orderNo,
+          qrImageUrl: qr.qrImageUrl,
+          walletConfigPresent: qr.walletConfigPresent
+        });
+        res.status(200).json(qr);
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("control.payment.clawtip.activate_qr.failed", "ClawTip activation QR failed", { errorMessage });
+        res.status(500).json({ error: { code: "clawtip_activate_qr_failed", message: errorMessage } });
+      }
+    });
+
+    controlApp.post("/payments/clawtip/recharge", (req, res) => {
+      try {
+        const qr = this.clawtipRechargeQr();
+        logger.info("control.payment.clawtip.recharge_qr.created", "ClawTip fixed recharge QR served for tb-ui", {
+          orderNo: qr.orderNo,
+          qrImageUrl: qr.qrImageUrl,
+          walletConfigPresent: qr.walletConfigPresent
+        });
+        res.status(200).json(qr);
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("control.payment.clawtip.recharge_qr.failed", "ClawTip recharge QR failed", { errorMessage });
+        res.status(500).json({ error: { code: "clawtip_recharge_qr_failed", message: errorMessage } });
+      }
+    });
+
     controlApp.get("/ledger/purchases", (req, res) => {
       logger.info("control.ledger.requested", "control purchase ledger requested", {
         ledger: "purchases"
@@ -1855,6 +2497,41 @@ export class TokenbuddyDaemon {
       }
     });
 
+    controlApp.get("/providers/status", (_req, res) => {
+      try {
+        const providerStatuses = detectProviders({ home: this.config.providerHomeDir }).map(clientToolStatusFromProvider);
+        const clients = [
+          ...providerStatuses,
+          buildCustomClientToolStatus(this.activeProxyPort()),
+        ];
+        const configuredCount = clients.filter((client) => client.configured).length;
+        const detectedCount = clients.filter((client) => client.detected && client.status !== "manual").length;
+        logger.info("provider.status.requested", "provider status requested", {
+          clientCount: clients.length,
+          configuredCount,
+          detectedCount
+        });
+        res.status(200).json({
+          clients,
+          summary: {
+            configuredCount,
+            detectedCount,
+            totalCount: clients.length,
+            installCommand: "tb init"
+          }
+        });
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("provider.status.failed", "provider status failed", { errorMessage });
+        res.status(400).json({
+          error: {
+            code: "provider_status_failed",
+            message: errorMessage
+          }
+        });
+      }
+    });
+
     controlApp.post("/providers/install/preview", (req, res) => {
       try {
         const changes = previewProviderInstall({
@@ -1932,6 +2609,172 @@ export class TokenbuddyDaemon {
       }
     });
 
+    // ─────────────────────────────────────────────────────────────────
+    // tb-ui v1: 控制平面写端点（PR-0）
+    // 所有端点都热生效，不需重启 daemon。改完 store 即下次推理生效。
+    // ─────────────────────────────────────────────────────────────────
+
+    // 1) GET /routing/strategy — 读当前路由策略 + 来源
+    controlApp.get("/routing/strategy", (req, res) => {
+      try {
+        const stored = this.tokenStore.getDaemonRuntimeConfig<unknown>(ROUTING_CONFIG_KEY)?.config;
+        const current = this.refreshSellerRoutingConfig();
+        const source: "store" | "config" | "default" =
+          stored !== undefined ? "store" : this.config.sellerRouting ? "config" : "default";
+        logger.info("routing.strategy.read", "routing strategy read", {
+          source,
+          mode: current.mode,
+          scorer: current.scorer
+        });
+        res.status(200).json({ strategy: current, source });
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("routing.strategy.read_failed", "routing strategy read failed", { errorMessage });
+        res.status(500).json({ error: { code: "routing_strategy_read_failed", message: errorMessage } });
+      }
+    });
+
+    // 2) GET /routing/preview — 算「假如改完会怎样」，不改 state
+    //   query: modelId? protocol? paymentMethod? mode? scorer? sellerId? sellerIds?(逗号分隔)
+    controlApp.get("/routing/preview", (req, res) => {
+      try {
+        const override = buildRoutingConfigFromQuery(req.query);
+        const result = this.buildRoutingPreview({
+          modelId: typeof req.query.modelId === "string" ? req.query.modelId : undefined,
+          protocol: typeof req.query.protocol === "string" ? req.query.protocol : undefined,
+          paymentMethod: typeof req.query.paymentMethod === "string" ? req.query.paymentMethod : undefined,
+          routing: override ?? undefined
+        });
+        if ("error" in result.plan) {
+          res.status(409).json({
+            error: { code: result.plan.error, message: `cannot preview routing: ${result.plan.error}` },
+            modelId: result.modelId,
+            protocol: result.protocol,
+            paymentMethod: result.paymentMethod
+          });
+          return;
+        }
+        res.status(200).json({
+          modelId: result.modelId,
+          protocol: result.protocol,
+          paymentMethod: result.paymentMethod,
+          plan: result.plan
+        });
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("routing.preview.failed", "routing preview failed", { errorMessage });
+        res.status(400).json({ error: { code: "routing_preview_failed", message: errorMessage } });
+      }
+    });
+
+    // 3) PUT /routing/strategy — 写策略 + 热更新 + 返回 preview
+    controlApp.put("/routing/strategy", (req, res) => {
+      try {
+        const body = (req.body ?? {}) as Record<string, unknown>;
+        const normalized = normalizeSellerRoutingConfig(body);
+        // 必填字段再次校验（normalize 会回退 default，但 PUT 必须显式）
+        assertSellerRoutingConfig(normalized);
+        this.tokenStore.saveDaemonRuntimeConfig(ROUTING_CONFIG_KEY, normalized);
+        const current = this.refreshSellerRoutingConfig();
+        logger.info("routing.strategy.applied", "routing strategy applied", {
+          mode: current.mode,
+          scorer: current.scorer,
+          sellerId: current.sellerId,
+          sellerIds: current.sellerIds
+        });
+        const preview = this.buildRoutingPreview({ routing: current });
+        const previewPayload = "error" in preview.plan
+          ? { error: preview.plan.error }
+          : {
+              modelId: preview.modelId,
+              protocol: preview.protocol,
+              paymentMethod: preview.paymentMethod,
+              ...preview.plan
+            };
+        res.status(200).json({ applied: true, strategy: current, preview: previewPayload });
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("routing.strategy.apply_failed", "routing strategy apply failed", { errorMessage });
+        res.status(400).json({ error: { code: "routing_strategy_apply_failed", message: errorMessage } });
+      }
+    });
+
+    // 4) PUT /prewarm/focus-set — 设置 explicit focus set（覆盖 config.warmupModels / env）
+    //   body: { models: ["claude-3-5-sonnet", "gpt-4o"], clear?: false }
+    //   clear=true 时 models 数组可省略；表示回退 env / historical
+    controlApp.put("/prewarm/focus-set", (req, res) => {
+      try {
+        const body = (req.body ?? {}) as Record<string, unknown>;
+        const clear = body.clear === true;
+        if (clear) {
+          const result = this.applyFocusSet(null);
+          res.status(200).json({ ok: true, ...result });
+          return;
+        }
+        if (!Array.isArray(body.models)) {
+          res.status(400).json({
+            error: { code: "invalid_focus_set", message: "focus-set body must have a string[] `models` field, or `clear: true`" }
+          });
+          return;
+        }
+        const models = body.models
+          .filter((m): m is string => typeof m === "string")
+          .map((m) => m.trim())
+          .filter(Boolean);
+        const result = this.applyFocusSet(models);
+        res.status(200).json({ ok: true, ...result });
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("focus_set.apply_failed", "focus set apply failed", { errorMessage });
+        res.status(400).json({ error: { code: "focus_set_apply_failed", message: errorMessage } });
+      }
+    });
+
+    // 5) POST /daemon/restart — 优雅重启 tb-proxyd（调子进程 `tb daemon restart`）
+    //   现有 CLI 子命令（cli.ts:1129）。detached 模式让子进程独立于 daemon 生命周期。
+    controlApp.post("/daemon/restart", (req, res) => {
+      try {
+        const child = spawn("tb", ["daemon", "restart"], {
+          detached: true,
+          stdio: "ignore"
+        });
+        child.unref();
+        logger.info("daemon.restart.scheduled", "daemon restart scheduled via tb CLI");
+        res.status(202).json({ ok: true, message: "restart scheduled" });
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.warn("daemon.restart.failed", "daemon restart failed", { errorMessage });
+        res.status(500).json({ error: { code: "daemon_restart_failed", message: errorMessage } });
+      }
+    });
+
+    this.ensureClawtipStaticAssets();
+    controlApp.use(CLAWTIP_STATIC_ROUTE, express.static(this.clawtipStaticDir(), { index: false, fallthrough: false }));
+
+    // ────────────────────────────────────────────────────────────
+    // tb-ui v1: 静态托管 SPA(dist 由 `npm run build --workspace tb-ui` 生成)
+    // 必须在所有 API 路由**之后**才挂载,这样:
+    // - `/health` `/ledger/purchases` 等 API 路径仍由上面 17+ 个端点处理
+    // - 真实静态文件(`/index.html` `/assets/index-abc.js` 等)由 express.static 服务
+    // - 未匹配路径(`/overview` `/routing` 等 React Router 路径)走 SPA fallback 回 index.html
+    // ────────────────────────────────────────────────────────────
+    const uiDir = resolveUiDir();
+    if (uiDir && fs.existsSync(uiDir) && fs.existsSync(path.join(uiDir, "index.html"))) {
+      controlApp.use(express.static(uiDir, { index: "index.html", fallthrough: true }));
+      // SPA fallback: React Router 用 BrowserRouter(history mode),客户端路径如
+      // /overview /routing /ledger 不对应任何文件,必须回 index.html 让 React Router 接管。
+      // Express 已经按注册顺序匹配了所有 17+ 个 API 路由,这里只接住"什么都没匹配"的 GET。
+      controlApp.get(/^(?!\/(?:health|status|payments|sellers|models|ledger|routing|prewarm|v1\.2|daemon|providers|static)\/).*/, (_req, res) => {
+        res.sendFile(path.join(uiDir, "index.html"));
+      });
+      logger.info("ui.static.attached", "tb-ui dist attached to control plane SPA fallback", { uiDir });
+    } else {
+      logger.warn("ui.static.missing", "tb-ui dist not found; only control plane API will be served", {
+        uiDir,
+        hint: "run `npm run build --workspace tb-ui` then restart"
+      });
+    }
+
     this.controlServer = controlApp.listen(this.config.controlPort);
 
     // 2. Proxy Plane Server (17821)
@@ -1999,9 +2842,13 @@ export class TokenbuddyDaemon {
   /**
    * v1.2 §18.4: build the focus set from the explicit config, the env
    * override, and the historical usage in the buyer store. The order of
-   * precedence: explicit config > env > historical > empty.
+   * precedence: explicit `currentFocusSet` (set via `PUT /prewarm/focus-set`)
+   * > explicit config > env > historical > empty.
    */
   private resolveFocusSet(): string[] {
+    if (this.currentFocusSet !== null) {
+      return this.currentFocusSet;
+    }
     const explicit = this.config.warmupModels ?? [];
     if (explicit.length > 0) {
       return explicit;
@@ -2014,6 +2861,93 @@ export class TokenbuddyDaemon {
     return this.tokenStore.recentModels(7, 5);
   }
 
+  /**
+   * tb-ui v1 `PUT /prewarm/focus-set` 调用的统一入口。`models === null`
+   * 表示「清除 explicit focus set，回退 env/historical」。
+   * 写 store + 触发 `runRoutingPrewarmSweep`，**热生效**（不需重启 daemon）。
+   */
+  public applyFocusSet(models: string[] | null): { focusSet: string[]; source: "explicit" | "env" | "historical" | "empty" } {
+    if (models === null) {
+      this.tokenStore.removeDaemonRuntimeConfig(FOCUS_SET_CONFIG_KEY);
+      this.currentFocusSet = null;
+    } else {
+      const deduped = Array.from(new Set(models.map((m) => m.trim()).filter(Boolean)));
+      this.tokenStore.saveDaemonRuntimeConfig(FOCUS_SET_CONFIG_KEY, { models: deduped });
+      this.currentFocusSet = deduped;
+    }
+    // 触发路由重读 + 预热 sweep（如果当前 routing 已是焦点集合的依赖）。
+    this.refreshSellerRoutingConfig();
+    const focusSet = this.resolveFocusSet();
+    const source: "explicit" | "env" | "historical" | "empty" =
+      this.currentFocusSet !== null
+        ? "explicit"
+        : (this.config.warmupModels?.length ?? 0) > 0
+          ? "explicit"
+          : (process.env.TB_BUYER_WARMUP_MODELS?.trim() ?? "").length > 0
+            ? "env"
+            : focusSet.length > 0
+              ? "historical"
+              : "empty";
+    logger.info("focus_set.applied", "explicit focus set applied", {
+      source,
+      focusSetSize: focusSet.length,
+      focusSet: focusSet.slice(0, 20)
+    });
+    return { focusSet, source };
+  }
+
+  /**
+   * tb-ui v1 `GET /routing/preview` 和 `PUT /routing/strategy` 复用的 preview 计算。
+   * 接受任意 routing 覆盖（来自 request body）算「假如改成这个，路由会是啥」。
+   * 不修改任何内部 state，**纯函数式**。
+   */
+  public buildRoutingPreview(input: {
+    modelId?: string;
+    protocol?: string;
+    paymentMethod?: string;
+    routing?: Partial<BuyerSellerRoutingConfig>;
+  }): { modelId: string; protocol: string; paymentMethod: string; plan: SellerRoutePlan | { error: string } } {
+    const registry = this.lastRegistrySnapshot;
+    const focusFirst = this.resolveFocusSet()[0];
+    const registryFirst = registry?.sellers[0]?.models?.[0];
+    const modelId = input.modelId?.trim() || focusFirst || registryFirst || "";
+    const protocol = input.protocol?.trim() || "chat_completions";
+    const paymentMethod = input.paymentMethod?.trim() || this.defaultPaymentMethod() || "clawtip";
+    if (!modelId) {
+      return { modelId, protocol, paymentMethod, plan: { error: "no_focus_model_available" } };
+    }
+    if (!registry) {
+      return { modelId, protocol, paymentMethod, plan: { error: "registry_not_loaded" } };
+    }
+    const current = this.refreshSellerRoutingConfig();
+    const routing: BuyerSellerRoutingConfig = input.routing
+      ? mergeSellerRoutingConfig(current, input.routing)
+      : current;
+    const resolvedRouting = resolveSellerRoutingForModel(routing, modelId);
+    const registrySellers = reorderDefaultSellerFirst(registry.sellers, registry.defaultSeller);
+    this.sellerPool.ensureRegistrySellers(registrySellers);
+    const poolById = new Map(this.sellerPool.snapshot().map((entry) => [entry.sellerId, entry]));
+    const plan = planSellerRouteSet({
+      modelId,
+      protocol,
+      paymentMethod,
+      registrySellers,
+      routing: resolvedRouting,
+      prewarmCandidates: this.prewarmCache.get(modelId, protocol, paymentMethod)?.candidates,
+      sellerMetrics: Array.from(poolById.values()).map((entry) => ({
+        sellerId: entry.sellerId,
+        healthScore: entry.healthScore,
+        avgLatencyMs: entry.avgLatencyMs,
+        ttftMs: entry.ttftMs,
+        avgInferenceMs: entry.avgInferenceMs,
+        circuit: entry.circuit,
+        capacityBlockedUntil: entry.capacityBlockedUntil
+      })),
+      now: Date.now()
+    });
+    return { modelId, protocol, paymentMethod, plan };
+  }
+
   private async runStartupPrewarmSweep(): Promise<void> {
     const focusSet = this.resolveFocusSet();
     if (focusSet.length === 0) {
@@ -2029,7 +2963,7 @@ export class TokenbuddyDaemon {
       await this.prewarmScheduler.runStartupPrewarm(
         focusSet.map((modelId) => ({
           modelId,
-          protocol: this.resolvePrewarmProtocol(modelId)
+          protocol: this.resolvePrewarmProtocol(modelId, this.defaultPaymentMethod())
         }))
       );
     } catch (err) {
@@ -2039,9 +2973,9 @@ export class TokenbuddyDaemon {
     }
   }
 
-  private resolvePrewarmProtocol(modelId: string): string | undefined {
+  private resolvePrewarmProtocol(modelId: string, paymentMethod = "clawtip"): string | undefined {
     for (const protocol of ["chat_completions", "messages", "responses"]) {
-      if (this.modelIndex.sellersFor(modelId, { protocol, paymentMethod: "clawtip" }).length > 0) {
+      if (this.modelIndex.sellersFor(modelId, { protocol, paymentMethod }).length > 0) {
         return protocol;
       }
     }
@@ -2049,9 +2983,209 @@ export class TokenbuddyDaemon {
   }
 
   public stop() {
+    if (this.clawtipActivationWaitCancelToken) {
+      this.clawtipActivationWaitCancelToken.cancelled = true;
+    }
     if (this.controlServer) this.controlServer.close();
     if (this.proxyServer) this.proxyServer.close();
     void this.prewarmScheduler.stop();
     this.tokenStore.close();
   }
+
+  /**
+   * @internal — test-only seam to inject a registry snapshot without
+   * hitting the network. Used by `tests/control-plane-ui-endpoints.test.ts`
+   * to drive `buildRoutingPreview` deterministically. Production code
+   * must NOT call this; the real `fetchRegistry()` populates the snapshot.
+   */
+  public setLastRegistrySnapshotForTest(snapshot: SellerRegistryDocument | null): void {
+    this.lastRegistrySnapshot = snapshot;
+  }
+}
+
+function selectionModeForRouting(routing: BuyerSellerRoutingConfig): "auto" | "manual" {
+  return routing.mode === "fullAuto" ? "auto" : "manual";
+}
+
+interface ClawtipQrResponse {
+  ok: true;
+  kind: "activate" | "recharge";
+  method: "clawtip";
+  orderNo?: string;
+  amountFen?: number;
+  qrImageUrl: string;
+  sourceImagePath: string;
+  staticImagePath: string;
+  authUrl?: string;
+  clawtipId?: string;
+  orderFile?: string;
+  resourceUrl?: string;
+  walletConfigPath: string;
+  walletConfigPresent: boolean;
+  requiresWalletAuth: boolean;
+  payCredentialWritten: boolean;
+}
+
+function withLiveClawtipWalletState(payment: PaymentConfig, home?: string): PaymentConfig {
+  if (payment.method !== "clawtip") {
+    return payment;
+  }
+  const walletConfig = inspectOpenClawWalletConfig(home);
+  return {
+    ...payment,
+    enabled: payment.enabled && walletConfig.exists,
+    config: {
+      ...(payment.config ?? {}),
+      walletConfigPath: walletConfig.expectedPath,
+      walletConfigPresent: walletConfig.exists,
+      nearbyWalletConfigPaths: walletConfig.alternatePaths
+    }
+  };
+}
+
+function normalizeClawtipActivationPayment(bootstrap: ClawtipBootstrapResponse): ClawtipBootstrapPayment {
+  if (!bootstrap.payment?.orderNo || !bootstrap.payment.indicator || !bootstrap.payment.resourceUrl) {
+    throw new Error("ClawTip bootstrap response missing orderNo, indicator, or resourceUrl.");
+  }
+  return {
+    orderNo: bootstrap.payment.orderNo,
+    amountFen: bootstrap.payment.amountFen ?? bootstrap.activationFeeFen ?? 1,
+    payTo: bootstrap.payment.payTo,
+    encryptedData: bootstrap.payment.encryptedData,
+    indicator: bootstrap.payment.indicator,
+    slug: bootstrap.payment.slug,
+    skillId: bootstrap.payment.skillId,
+    description: bootstrap.payment.description,
+    resourceUrl: bootstrap.payment.resourceUrl,
+  };
+}
+
+function safeQrExtension(filePath: string): ".png" | ".jpg" | ".jpeg" | ".webp" {
+  const extension = path.extname(filePath).toLowerCase();
+  if (extension === ".jpg" || extension === ".jpeg" || extension === ".webp") {
+    return extension;
+  }
+  return ".png";
+}
+
+function safeStaticFileSegment(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "clawtip";
+}
+
+function readConfigString(config: Record<string, unknown> | undefined, key: string): string | undefined {
+  const value = config?.[key];
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function readConfigBoolean(config: Record<string, unknown> | undefined, key: string): boolean {
+  return config?.[key] === true;
+}
+
+function selectedSellerIdForRouting(routing: BuyerSellerRoutingConfig): string | undefined {
+  return routing.mode === "fixed" ? routing.sellerId : undefined;
+}
+
+function routingKey(routing: BuyerSellerRoutingConfig): string {
+  const fixedByModel = Object.entries(routing.fixedByModel ?? {})
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([modelId, sellerId]) => `${modelId}:${sellerId}`);
+  return [
+    routing.mode,
+    routing.scorer,
+    routing.sellerId ?? "",
+    ...(routing.sellerIds ?? []),
+    ...fixedByModel
+  ].join("\u0001");
+}
+
+/**
+ * 从 query string 构造 `BuyerSellerRoutingConfig` override（用于 GET /routing/preview）。
+ * 接受 `mode` / `scorer` / `sellerId` / `sellerIds`（逗号分隔）。
+ * 任一字段缺失返回 `undefined`，调用方走「用当前 routing」分支。
+ * mode / scorer 非法抛 400，由端点 handler 捕获。
+ */
+function buildRoutingConfigFromQuery(query: Record<string, unknown> | Request["query"]): Partial<BuyerSellerRoutingConfig> | undefined {
+  const mode = typeof query.mode === "string" ? query.mode.trim() : "";
+  const scorer = typeof query.scorer === "string" ? query.scorer.trim() : "";
+  const sellerId = typeof query.sellerId === "string" ? query.sellerId.trim() : "";
+  const sellerIdsRaw = typeof query.sellerIds === "string" ? query.sellerIds.trim() : "";
+  const fixedByModelRaw = typeof query.fixedByModel === "string" ? query.fixedByModel.trim() : "";
+  if (!mode && !scorer && !sellerId && !sellerIdsRaw && !fixedByModelRaw) {
+    return undefined;
+  }
+  const override: Partial<BuyerSellerRoutingConfig> = {};
+  if (mode) {
+    if (mode !== "fixed" && mode !== "fixedSet" && mode !== "fullAuto") {
+      throw new Error("mode must be fixed, fixedSet, or fullAuto");
+    }
+    override.mode = mode;
+  }
+  if (scorer) {
+    if (scorer !== "speed" && scorer !== "discount" && scorer !== "balanced") {
+      throw new Error("scorer must be speed, discount, or balanced");
+    }
+    override.scorer = scorer;
+  }
+  if (sellerId) {
+    override.sellerId = sellerId;
+  }
+  if (sellerIdsRaw) {
+    override.sellerIds = parseSellerIdList(sellerIdsRaw);
+  }
+  if (fixedByModelRaw) {
+    override.fixedByModel = parseFixedByModel(fixedByModelRaw);
+  }
+  return override;
+}
+
+function sameSellerRouting(a: BuyerSellerRoutingConfig, b: BuyerSellerRoutingConfig): boolean {
+  return a.mode === b.mode
+    && a.scorer === b.scorer
+    && optionalStringEqual(a.sellerId, b.sellerId)
+    && stringArraysEqual(a.sellerIds ?? [], b.sellerIds ?? [])
+    && fixedByModelEqual(a.fixedByModel ?? {}, b.fixedByModel ?? {});
+}
+
+function optionalStringEqual(a: string | undefined, b: string | undefined): boolean {
+  return (a ?? "") === (b ?? "");
+}
+
+function stringArraysEqual(a: string[], b: string[]): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  return a.every((entry, index) => entry === b[index]);
+}
+
+function resolveSellerRoutingForModel(routing: BuyerSellerRoutingConfig, modelId: string): BuyerSellerRoutingConfig {
+  if (routing.mode !== "fixed") {
+    return routing;
+  }
+  const fixedSellerId = routing.fixedByModel?.[modelId]?.trim() || routing.sellerId;
+  return {
+    mode: "fixed",
+    scorer: routing.scorer,
+    sellerId: fixedSellerId,
+    fixedByModel: routing.fixedByModel
+  };
+}
+
+function parseFixedByModel(value: string): Record<string, string> {
+  const entries = value
+    .split(",")
+    .map((entry) => entry.split(":"))
+    .filter((parts): parts is [string, string] => parts.length === 2)
+    .map(([modelId, sellerId]) => [modelId.trim(), sellerId.trim()] as const)
+    .filter(([modelId, sellerId]) => modelId.length > 0 && sellerId.length > 0);
+  return Object.fromEntries(entries);
+}
+
+function fixedByModelEqual(a: Record<string, string>, b: Record<string, string>): boolean {
+  const aEntries = Object.entries(a).sort(([left], [right]) => left.localeCompare(right));
+  const bEntries = Object.entries(b).sort(([left], [right]) => left.localeCompare(right));
+  return aEntries.length === bEntries.length
+    && aEntries.every(([modelId, sellerId], index) => {
+      const [otherModelId, otherSellerId] = bEntries[index] ?? [];
+      return modelId === otherModelId && sellerId === otherSellerId;
+    });
 }