@tokenbuddy/tokenbuddy 1.0.12 → 1.0.14

package/src/daemon.ts

@@ -23,7 +23,6 @@ import {
   type RegistrySeller,
   type SellerManifest,
   type SellerRegistryDocument,
-  type SellerRoutingPreference,
 } from "./seller-catalog.js";
 import { ModelIndex } from "./model-index.js";
 import { PrewarmCache } from "./prewarm-cache.js";
@@ -32,22 +31,39 @@ 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 type { PoolEntry } from "./seller-pool.js";
+import { planSellerRouteSet } from "./seller-route-planner.js";
+import {
+  mergeSellerRoutingConfig,
+  ROUTING_CONFIG_KEY,
+  type BuyerSellerRoutingConfig
+} from "./seller-routing-config.js";
 
 const logger = createModuleLogger("tb-proxyd");
 const PROXY_JSON_BODY_LIMIT = "10mb";
 
+/**
+ * buyer 端守护进程（`tb-proxyd`）的配置。
+ * 由 `startDaemon(config)` 注入；字段缺省时由内部补齐。
+ */
 export interface DaemonConfig {
+  /** 本地控制端口（如 healthz / 控制接口） */
   controlPort: number;
+  /** 对 buyer 客户端暴露的反向代理端口（OpenAI / Anthropic 协议入口） */
   proxyPort: number;
+  /** buyer 端 SQLite 路径（用于 store、credit tracker、prewarm cache） */
   dbPath: string;
+  /** seller 注册表拉取 URL（通常是 wallet-bootstrap 的 `/registry/sellers`） */
   sellerRegistryUrl: string;
-  selectionMode?: "auto" | "manual";
-  selectedSellerId?: string;
-  // v1.2 §18.4: focus-set override. When omitted, the daemon derives the
-  // focus set from the BuyerStore's historical model usage and the
-  // `TB_BUYER_WARMUP_MODELS` env var (comma-separated).
+  /** 路由策略覆盖（与 `TB_SELLER_ROUTING_*` env 合并） */
+  sellerRouting?: BuyerSellerRoutingConfig;
+  /**
+   * v1.2 §18.4 预热 focus-set 覆盖。
+   * 缺省时由 BuyerStore 历史模型使用情况 + `TB_BUYER_WARMUP_MODELS` env 推导。
+   */
   warmupModels?: string[];
+  /** 预热模型目录刷新间隔（秒） */
   warmupRefreshIntervalSecs?: number;
+  /** 预热探测超时（毫秒） */
   warmupProbeTimeoutMs?: number;
 }
 
@@ -66,6 +82,18 @@ interface UsageSummary {
   billedMicros: number;
 }
 
+interface ProxyBodySummary {
+  bodyType: string;
+  messageCount?: number;
+  inputItemCount?: number;
+  toolCount?: number;
+  hasMessages?: boolean;
+  hasInput?: boolean;
+  hasTools?: boolean;
+  maxTokensPresent?: boolean;
+  temperaturePresent?: boolean;
+}
+
 interface SellerSettlementSummary {
   requestId: string;
   settledMicros: number;
@@ -105,11 +133,13 @@ class SellerSettlementStreamExtractor {
     return blocks
       .map((block) => this.processBlock(block))
       .filter((block) => block.length > 0)
-      .join("\n\n");
+      .map((block) => `${block}\n\n`)
+      .join("");
   }
 
   public finish(): { downstream: string; settlement: SellerSettlementSummary | undefined } {
-    const downstream = this.pending.trim() ? this.processBlock(this.pending) : "";
+    const processed = this.pending.trim() ? this.processBlock(this.pending) : "";
+    const downstream = processed ? processed : "";
     this.pending = "";
     return { downstream, settlement: this.settlement };
   }
@@ -171,6 +201,42 @@ function parseSellerSettlementObject(raw: string): SellerSettlementSummary | und
   }
 }
 
+function arrayLength(value: unknown): number | undefined {
+  return Array.isArray(value) ? value.length : undefined;
+}
+
+function summarizeProxyBody(body: unknown): ProxyBodySummary {
+  if (!body || typeof body !== "object") {
+    return { bodyType: typeof body };
+  }
+
+  const data = body as Record<string, unknown>;
+  const messages = arrayLength(data.messages);
+  const input = arrayLength(data.input);
+  const tools = arrayLength(data.tools);
+  return {
+    bodyType: "object",
+    messageCount: messages,
+    inputItemCount: input,
+    toolCount: tools,
+    hasMessages: messages !== undefined,
+    hasInput: data.input !== undefined,
+    hasTools: tools !== undefined,
+    maxTokensPresent: data.max_tokens !== undefined || data.maxTokens !== undefined,
+    temperaturePresent: data.temperature !== undefined
+  };
+}
+
+function reorderDefaultSellerFirst(sellers: RegistrySeller[], defaultSellerId: string | undefined): RegistrySeller[] {
+  if (!defaultSellerId) {
+    return sellers;
+  }
+  return [
+    ...sellers.filter((seller) => seller.id === defaultSellerId),
+    ...sellers.filter((seller) => seller.id !== defaultSellerId)
+  ];
+}
+
 interface PurchaseCreateResponse {
   purchaseId?: string;
   purchase_id?: string;
@@ -195,6 +261,12 @@ interface PurchaseCompleteResponse extends PurchaseCreateResponse {
   token_class?: string;
 }
 
+/**
+ * buyer 端守护进程。
+ * 负责启动两个 Express 服务：控制接口（healthz + 控制路由）+ 反向代理（OpenAI / Anthropic 协议入口）。
+ * 同时跑后台任务：seller catalog 周期拉取、model-index 刷新、prewarm scheduler、credit tracker。
+ * 推荐用 `startDaemon(config)` 启动 / `stopDaemon(daemon)` 优雅关闭，避免直接管理生命周期。
+ */
 export class TokenbuddyDaemon {
   private config: DaemonConfig;
   private tokenStore: BuyerStore;
@@ -202,6 +274,7 @@ export class TokenbuddyDaemon {
   private proxyServer?: any;
   private selectionMode: "auto" | "manual";
   private selectedSellerId?: string;
+  private sellerRouting: BuyerSellerRoutingConfig;
 
   private activePurchases = new Map<string, Promise<string>>();
 
@@ -227,16 +300,15 @@ export class TokenbuddyDaemon {
 
   constructor(config: DaemonConfig) {
     this.tokenStore = new BuyerStore({ dbPath: config.dbPath });
-    const routingPreference =
-      this.tokenStore.getDaemonRuntimeConfig<SellerRoutingPreference>("routing")
-        ?.config;
+    const storedRouting = this.tokenStore.getDaemonRuntimeConfig<unknown>(ROUTING_CONFIG_KEY)
+      ?.config;
     this.config = config;
-    this.selectionMode =
-      config.selectionMode ||
-      (routingPreference?.mode === "fixed" ? "manual" : routingPreference?.mode) ||
-      "auto";
-    this.selectedSellerId =
-      config.selectedSellerId || routingPreference?.sellerId;
+    this.sellerRouting = mergeSellerRoutingConfig(
+      storedRouting,
+      config.sellerRouting
+    );
+    this.selectionMode = this.sellerRouting.mode === "fullAuto" ? "auto" : "manual";
+    this.selectedSellerId = this.sellerRouting.mode === "fixed" ? this.sellerRouting.sellerId : undefined;
     // 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, {
@@ -253,7 +325,7 @@ export class TokenbuddyDaemon {
     return async (seller, signal) => {
       try {
         const ac = new AbortController();
-        const timer = setTimeout(() => ac.abort(new Error("healthz timeout")), timeoutMs);
+        const timer = setTimeout(() => ac.abort(new Error("health timeout")), timeoutMs);
         if (signal) {
           if (signal.aborted) {
             ac.abort(signal.reason);
@@ -262,10 +334,10 @@ export class TokenbuddyDaemon {
           }
         }
         const startedAt = Date.now();
-        const res = await fetch(`${seller.url.replace(/\/+$/, "")}/healthz`, { signal: ac.signal });
+        const res = await fetch(`${seller.url.replace(/\/+$/, "")}/health`, { signal: ac.signal });
         clearTimeout(timer);
         if (!res.ok) {
-          return { ok: false, latencyMs: Date.now() - startedAt, httpStatus: res.status, errorMessage: `healthz returned ${res.status}` };
+          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 };
       } catch (err) {
@@ -325,14 +397,15 @@ export class TokenbuddyDaemon {
   }
 
   private runtimeSummary() {
-    const sellerRoutingMode = this.selectedSellerId ? "fixed" : this.selectionMode;
     return {
       status: "running",
       pid: process.pid,
       controlPort: this.activeControlPort(),
       proxyPort: this.activeProxyPort(),
       selectionMode: this.selectionMode,
-      sellerRoutingMode,
+      sellerRoutingMode: this.sellerRouting.mode,
+      sellerRoutingScorer: this.sellerRouting.scorer,
+      sellerRouting: this.sellerRouting,
       selectedSellerId: this.selectedSellerId,
       dbPath: this.config.dbPath,
       sellerRegistryUrl: this.config.sellerRegistryUrl,
@@ -446,32 +519,35 @@ export class TokenbuddyDaemon {
     // pulling `models` directly off the registry entries.
     const registry = await this.fetchRegistry();
 
-    const indexCandidates = this.modelIndex.sellersFor(modelId, { protocol, paymentMethod });
-    let ordered = indexCandidates;
-    if (this.selectionMode === "manual" && this.selectedSellerId) {
-      ordered = indexCandidates.filter((seller) => seller.id === this.selectedSellerId);
-    } else if (this.selectionMode === "manual" && registry.defaultSeller) {
-      ordered = indexCandidates.filter((seller) => seller.id === registry.defaultSeller);
-    } else if (registry.defaultSeller) {
-      // auto mode: default first, then backups in registry order
-      ordered = [
-        ...indexCandidates.filter((seller) => seller.id === registry.defaultSeller),
-        ...indexCandidates.filter((seller) => seller.id !== registry.defaultSeller)
-      ];
-    }
+    const routing = this.sellerRouting;
+    const registrySellers = reorderDefaultSellerFirst(registry.sellers, registry.defaultSeller);
+    const poolById = new Map(this.sellerPool.snapshot().map((entry) => [entry.sellerId, entry]));
+    const planned = planSellerRouteSet({
+      modelId,
+      protocol,
+      paymentMethod,
+      registrySellers,
+      routing,
+      prewarmCandidates: this.prewarmCache.get(modelId, protocol, paymentMethod)?.candidates,
+      sellerMetrics: Array.from(poolById.values()).map((entry) => ({
+        sellerId: entry.sellerId,
+        healthScore: entry.healthScore,
+        avgLatencyMs: entry.avgLatencyMs,
+        circuit: entry.circuit
+      }))
+    });
 
-    if (ordered.length === 0) {
+    if (planned.routes.length === 0) {
       throw new Error(`no compatible seller for ${endpoint} model ${modelId}`);
     }
 
-    const poolById = new Map(this.sellerPool.snapshot().map((entry) => [entry.sellerId, entry]));
-    const routes: SellerRoute[] = ordered.map((seller) => ({
-      seller,
+    const routes: SellerRoute[] = planned.routes.map((route) => ({
+      seller: route.seller,
       manifest: null,
       protocol,
       modelId,
       paymentMethod,
-      poolEntry: poolById.get(seller.id)
+      poolEntry: poolById.get(route.seller.id)
     }));
 
     logger.info("route.candidates.prewarmed", "seller route candidates prewarmed", {
@@ -480,6 +556,11 @@ export class TokenbuddyDaemon {
       protocol,
       paymentMethod,
       selectionMode: this.selectionMode,
+      sellerRoutingMode: routing.mode,
+      sellerRoutingScorer: routing.scorer,
+      routeSource: planned.source,
+      routeSourceReason: planned.sourceReason,
+      routeReason: planned.reason,
       sellerCount: routes.length,
       sellers: routes.map((route) => route.seller.id)
     });
@@ -519,23 +600,118 @@ export class TokenbuddyDaemon {
    */
   private handleFailoverDecision(
     decision: FailoverDecision,
-    context: { sellerKey: string; endpoint: string; routeIndex: number; status?: number; reason?: string }
+    context: {
+      requestId: string;
+      sellerKey: string;
+      model: string;
+      endpoint: string;
+      routeIndex: number;
+      routesRemaining: number;
+      attempt: number;
+      status?: number;
+      reason?: string;
+    }
   ): void {
     if (decision.action === "retry_same_seller") {
+      logger.warn("route.failover.retry_scheduled", "seller route retry scheduled", {
+        requestId: context.requestId,
+        sellerKey: context.sellerKey,
+        model: context.model,
+        endpoint: context.endpoint,
+        routeIndex: context.routeIndex,
+        routesRemaining: context.routesRemaining,
+        attempt: context.attempt,
+        nextAttempt: context.attempt + 1,
+        reason: decision.reason,
+        status: context.status,
+        retryDelayMs: decision.retryDelayMs
+      });
       return;
     }
     if (decision.action === "failover_next") {
       logger.warn("route.failover.triggered", "seller route failed over to backup candidate", {
+        requestId: context.requestId,
         sellerKey: context.sellerKey,
+        model: context.model,
         endpoint: context.endpoint,
         routeIndex: context.routeIndex,
+        nextRouteIndex: context.routeIndex + 1,
+        routesRemaining: context.routesRemaining,
+        attempt: context.attempt,
         reason: decision.reason,
         status: context.status,
         wastedCreditMicros: decision.wastedCreditMicros,
         freshPurchase: decision.freshPurchase,
         retryAttemptsBeforeFailover: decision.retryAttemptsBeforeFailover
       });
+      return;
     }
+    logger.warn("route.failover.terminal", "seller route failover reached terminal decision", {
+      requestId: context.requestId,
+      sellerKey: context.sellerKey,
+      model: context.model,
+      endpoint: context.endpoint,
+      routeIndex: context.routeIndex,
+      routesRemaining: context.routesRemaining,
+      attempt: context.attempt,
+      action: decision.action,
+      reason: decision.reason,
+      status: context.status
+    });
+  }
+
+  private logPaymentProofResolved(route: SellerRoute, proofSource: "command" | "file" | "env", requestId?: string): void {
+    logger.info("purchase.payment_proof.resolved", "payment proof resolved for purchase completion", {
+      requestId,
+      sellerKey: route.seller.id,
+      model: route.modelId,
+      paymentMethod: route.paymentMethod,
+      proofSource,
+      proofPresent: true
+    });
+  }
+
+  private logPurchaseLedgerRecorded(input: {
+    requestId?: string;
+    sellerKey: string;
+    modelId: string;
+    purchaseId: string;
+    paymentMethod: string;
+    status: string;
+    creditMicros: number;
+    currency: string;
+    durationMs: number;
+  }): void {
+    logger.info("purchase.ledger.recorded", "safe purchase ledger recorded", {
+      requestId: input.requestId,
+      sellerKey: input.sellerKey,
+      model: input.modelId,
+      purchaseId: input.purchaseId,
+      paymentMethod: input.paymentMethod,
+      ledgerStatus: input.status,
+      creditMicros: input.creditMicros,
+      currency: input.currency,
+      durationMs: input.durationMs
+    });
+  }
+
+  private logTokenBalanceReconciled(
+    route: SellerRoute,
+    requestId: string,
+    settlement: SellerSettlementSummary
+  ): void {
+    logger.info("token.balance.reconciled", "seller token balance reconciled from settlement", {
+      requestId: settlement.requestId || requestId,
+      sellerKey: route.seller.id,
+      model: route.modelId,
+      remainingCreditMicros: settlement.remainingCreditMicros,
+      reservedMicros: settlement.reservedBalanceMicros ?? 0,
+      spentMicros: settlement.spentMicros ?? 0,
+      settledMicros: settlement.settledMicros,
+      settledUsdMicros: settlement.settledUsdMicros,
+      priceVersion: settlement.priceVersion,
+      balanceSource: "seller_settlement_summary"
+    });
   }
 
   private async listSellerBackedModels(): Promise<{
@@ -604,6 +780,7 @@ export class TokenbuddyDaemon {
         spentMicros: settlement.spentMicros ?? 0,
         balanceSource: "seller_settlement_summary"
       });
+      this.logTokenBalanceReconciled(route, requestId, settlement);
     }
 
     const settledMicros = settlement?.settledMicros;
@@ -633,6 +810,11 @@ export class TokenbuddyDaemon {
       status: settlement ? "settled" : "estimated",
       estimatedMicros: usage.billedMicros,
       settledMicros,
+      settledUsdMicros: settlement?.settledUsdMicros,
+      billedMicros: settledMicros ?? usage.billedMicros,
+      promptTokens: usage.promptTokens,
+      completionTokens: usage.completionTokens,
+      balanceSnapshotMicros: settlement?.remainingCreditMicros,
       balanceSource: settlement ? "seller_authoritative" : "estimated"
     });
   }
@@ -693,19 +875,20 @@ export class TokenbuddyDaemon {
     }
   }
 
-  private async recoverFromInsufficientFunds(route: SellerRoute, token: string): Promise<string> {
+  private async recoverFromInsufficientFunds(route: SellerRoute, token: string, requestId?: string): Promise<string> {
     const sellerKey = route.seller.id;
     this.tokenStore.markTokenStale(sellerKey);
     const snapshot = await this.refreshSellerBalance(route, token, "seller_402_refresh");
     const rebuyMinBalanceMicros = this.tokenRebuyMinBalanceMicros();
     if (!snapshot || snapshot.availableMicros <= rebuyMinBalanceMicros) {
       logger.info("purchase.retry_after_402.started", "seller 402 triggered one-shot auto purchase retry", {
+        requestId,
         sellerKey,
         model: route.modelId,
         availableMicros: snapshot?.availableMicros ?? 0,
         rebuyMinBalanceMicros
       });
-      return await this.getOrPurchaseToken(route);
+      return await this.getOrPurchaseToken(route, requestId);
     }
     const cached = this.tokenStore.getToken(sellerKey);
     return cached?.token || token;
@@ -742,16 +925,16 @@ export class TokenbuddyDaemon {
    * than this for a single seller; on expiry the request is aborted and
    * the route-failover controller can either retry the same seller with
    * a smaller body or fail over. Configurable via
-   * `TB_PROXYD_REQUEST_DEADLINE_MS` (default 30s).
+   * `TB_PROXYD_REQUEST_DEADLINE_MS` (default 180s).
    */
   private requestDeadlineMs(): number {
     const raw = process.env.TB_PROXYD_REQUEST_DEADLINE_MS;
     if (!raw) {
-      return 30_000;
+      return 180_000;
     }
     const parsed = Number(raw);
     if (!Number.isInteger(parsed) || parsed < 1000) {
-      return 30_000;
+      return 180_000;
     }
     return parsed;
   }
@@ -774,7 +957,7 @@ export class TokenbuddyDaemon {
     return parsed;
   }
 
-  private async getOrPurchaseToken(route: SellerRoute): Promise<string> {
+  private async getOrPurchaseToken(route: SellerRoute, requestId?: string): Promise<string> {
     const sellerKey = route.seller.id;
     const sellerUrl = normalizeSellerUrl(route.seller);
     const { modelId, paymentMethod } = route;
@@ -792,6 +975,7 @@ export class TokenbuddyDaemon {
     const tokenStillFresh = Number.isFinite(expiresAtMs) && Date.now() + this.tokenExpirySafetyMarginMs() < expiresAtMs;
     if (cached && tokenStillFresh && cached.balanceMicros > rebuyMinBalanceMicros) {
       logger.info("token.cache.hit", "seller token cache hit", {
+        requestId,
         sellerKey,
         model: modelId,
         balanceMicros: cached.balanceMicros,
@@ -800,6 +984,7 @@ export class TokenbuddyDaemon {
       return cached.token;
     }
     logger.info("token.cache.miss", "seller token cache miss", {
+      requestId,
       sellerKey,
       model: modelId,
       balanceMicros: cached?.balanceMicros || 0,
@@ -811,6 +996,7 @@ export class TokenbuddyDaemon {
     const purchasePromise = this.activePurchases.get(purchaseKey);
     if (purchasePromise) {
       logger.info("purchase.lock.awaited", "parallel request awaiting active purchase", {
+        requestId,
         sellerKey,
         model: modelId
       });
@@ -821,6 +1007,7 @@ export class TokenbuddyDaemon {
       const startedAt = Date.now();
       const amountUsdMicros = this.autoPurchaseAmountUsdMicros();
       logger.info("purchase.token.started", "seller token purchase started", {
+        requestId,
         sellerKey,
         model: modelId,
         paymentMethod,
@@ -828,6 +1015,13 @@ export class TokenbuddyDaemon {
       });
       try {
         // 1. purchase/create
+        logger.info("purchase.create.started", "seller purchase create started", {
+          requestId,
+          sellerKey,
+          model: modelId,
+          paymentMethod,
+          amountUsdMicros
+        });
         const createRes = await fetch(`${sellerUrl}/purchase/create`, {
           method: "POST",
           headers: { "Content-Type": "application/json" },
@@ -844,6 +1038,7 @@ export class TokenbuddyDaemon {
           logger.warn("purchase.create.failed", "seller purchase create failed", {
             sellerKey,
             model: modelId,
+            requestId,
             status: createRes.status,
             errorMessage: createData.error?.message || "purchase/create failed",
             durationMs: Date.now() - startedAt
@@ -867,11 +1062,29 @@ export class TokenbuddyDaemon {
         logger.info("purchase.create.succeeded", "seller purchase created", {
           sellerKey,
           model: modelId,
+          requestId,
           purchaseId,
-          status: createRes.status
+          paymentMethod,
+          httpStatus: createRes.status,
+          purchaseStatus: createData.status || "pending",
+          creditMicros: createData.creditMicros ?? createData.credit_micros,
+          currency: createData.currency,
+          expiresAtPresent: Boolean(createData.expiresAt || createData.expires_at),
+          paymentReferencePresent: Boolean(createData.paymentReference || createData.payment_reference),
+          paymentInstructionsPresent: Boolean(createData.paymentInstructions || createData.payment_instructions),
+          quotePresent: Boolean(createData.quote),
+          durationMs: Date.now() - startedAt
         });
 
-        const paymentProof = await this.resolvePaymentProof(route, createData);
+        const paymentProof = await this.resolvePaymentProof(route, createData, requestId);
+        logger.info("purchase.complete.started", "seller purchase complete started", {
+          requestId,
+          sellerKey,
+          model: modelId,
+          purchaseId,
+          paymentMethod,
+          durationMs: Date.now() - startedAt
+        });
         const completeRes = await fetch(`${sellerUrl}/purchase/complete`, {
           method: "POST",
           headers: { "Content-Type": "application/json" },
@@ -887,6 +1100,7 @@ export class TokenbuddyDaemon {
           logger.warn("purchase.complete.failed", "seller purchase complete failed", {
             sellerKey,
             model: modelId,
+            requestId,
             purchaseId,
             status: completeRes.status,
             errorMessage: completeData.error?.message || "purchase/complete failed",
@@ -903,6 +1117,7 @@ export class TokenbuddyDaemon {
         const creditMicros = completeData.creditMicros ?? completeData.credit_micros ?? createData.creditMicros ?? createData.credit_micros ?? 0;
         const currency = completeData.currency || createData.currency || "USD";
         const expiresAt = new Date(Date.now() + 86400 * 1000).toISOString();
+        const ledgerStatus = completeData.status || "funded";
 
         this.tokenStore.saveToken(sellerKey, token, tokenClass, creditMicros, expiresAt);
         this.tokenStore.recordPurchaseLedger({
@@ -910,27 +1125,44 @@ export class TokenbuddyDaemon {
           sellerKey,
           modelId,
           paymentMethod,
-          status: completeData.status || "funded",
+          status: ledgerStatus,
           creditMicros,
           currency,
           paymentReference: completeData.paymentReference || completeData.payment_reference,
           completedAt: new Date().toISOString()
         });
+        this.logPurchaseLedgerRecorded({
+          requestId,
+          sellerKey,
+          modelId,
+          purchaseId,
+          paymentMethod,
+          status: ledgerStatus,
+          creditMicros,
+          currency,
+          durationMs: Date.now() - startedAt
+        });
         // v1.1: feed the credit tracker so the route-failover controller
         // knows the seller is inside the fresh-purchase window.
         this.creditTracker.recordPurchase(sellerKey, creditMicros, creditMicros);
         logger.info("purchase.token.succeeded", "seller token purchased", {
+          requestId,
           sellerKey,
           model: modelId,
           purchaseId,
+          paymentMethod,
           tokenClass,
           creditMicros,
+          currency,
+          ledgerStatus,
+          completeStatus: completeRes.status,
           durationMs: Date.now() - startedAt
         });
 
         return token;
       } catch (error: unknown) {
         logger.error("purchase.token.failed", "seller token purchase failed", {
+          requestId,
           sellerKey,
           model: modelId,
           errorMessage: error instanceof Error ? error.message : String(error),
@@ -946,7 +1178,7 @@ export class TokenbuddyDaemon {
     return purchaseTask;
   }
 
-  private async resolvePaymentProof(route: SellerRoute, createData: PurchaseCreateResponse): Promise<string> {
+  private async resolvePaymentProof(route: SellerRoute, createData: PurchaseCreateResponse, requestId?: string): Promise<string> {
     if (route.paymentMethod === "mock") {
       return "mock-proof-data";
     }
@@ -957,16 +1189,21 @@ export class TokenbuddyDaemon {
 
     const proofCommand = process.env.TB_PROXYD_CLAWTIP_PROOF_COMMAND;
     if (proofCommand?.trim()) {
-      return await this.runClawtipProofCommand(route, createData, proofCommand.trim());
+      const proof = await this.runClawtipProofCommand(route, createData, proofCommand.trim(), requestId);
+      this.logPaymentProofResolved(route, "command", requestId);
+      return proof;
     }
 
     const proofFile = process.env.TOKENBUDDY_CLAWTIP_PAYMENT_PROOF_FILE || process.env.TOKENBUDDY_CLAWTIP_PROOF_FILE;
     if (proofFile?.trim()) {
-      return fs.readFileSync(proofFile.trim(), "utf8").trim();
+      const proof = fs.readFileSync(proofFile.trim(), "utf8").trim();
+      this.logPaymentProofResolved(route, "file", requestId);
+      return proof;
     }
 
     const proof = process.env.TOKENBUDDY_CLAWTIP_PAYMENT_PROOF;
     if (proof?.trim()) {
+      this.logPaymentProofResolved(route, "env", requestId);
       return proof.trim();
     }
 
@@ -976,7 +1213,8 @@ export class TokenbuddyDaemon {
   private runClawtipProofCommand(
     route: SellerRoute,
     createData: PurchaseCreateResponse,
-    commandPath: string
+    commandPath: string,
+    requestId?: string
   ): Promise<string> {
     const timeoutMs = this.clawtipProofTimeoutMs();
     const payload = JSON.stringify({
@@ -989,6 +1227,7 @@ export class TokenbuddyDaemon {
     });
 
     logger.info("purchase.clawtip_proof.started", "clawtip proof provider started", {
+      requestId,
       sellerKey: route.seller.id,
       model: route.modelId,
       timeoutMs
@@ -1045,6 +1284,7 @@ export class TokenbuddyDaemon {
           return;
         }
         logger.info("purchase.clawtip_proof.succeeded", "clawtip proof provider succeeded", {
+          requestId,
           sellerKey: route.seller.id,
           model: route.modelId,
           durationMs: Date.now() - startedAt
@@ -1132,7 +1372,7 @@ export class TokenbuddyDaemon {
               model: modelId,
               endpoint,
               stream: Boolean((body as { stream?: unknown }).stream),
-              upstreamBody
+              bodySummary: summarizeProxyBody(upstreamBody)
             });
             // v1.1 §17.5: refuse to auto-purchase once the session budget is
             // exhausted. The seller is treated as "no auto-purchase available"
@@ -1153,7 +1393,7 @@ export class TokenbuddyDaemon {
             // seller; transfer leftover to wasted and fail over immediately.
             let token: string;
             try {
-              token = await this.getOrPurchaseToken(route);
+              token = await this.getOrPurchaseToken(route, requestId);
             } catch (purchaseError) {
               logger.warn("purchase.failed", "seller auto-purchase failed; failing over without retry", {
                 requestId,
@@ -1162,7 +1402,7 @@ export class TokenbuddyDaemon {
                 endpoint,
                 errorMessage: this.failoverErrorMessage(purchaseError)
               });
-              this.routeFailover.decide(
+              const decision = this.routeFailover.decide(
                 {
                   sellerId: sellerKey,
                   errorKind: "deadline",
@@ -1171,6 +1411,19 @@ export class TokenbuddyDaemon {
                 },
                 routes.length - routeIndex
               );
+              logger.warn("route.failover.triggered", "seller route failed over after purchase failure", {
+                requestId,
+                sellerKey,
+                model: modelId,
+                endpoint,
+                routeIndex,
+                nextRouteIndex: routeIndex + 1,
+                routesRemaining: routes.length - routeIndex,
+                attempt,
+                reason: "purchase_failed",
+                controllerReason: decision.reason,
+                controllerAction: decision.action
+              });
               lastError = purchaseError;
               break;
             }
@@ -1180,9 +1433,9 @@ export class TokenbuddyDaemon {
           // the `X-TokenBuddy-Deadline-Ms` header (PR-6) can propagate
           // it to their own upstream fetch via the same signal.
           const deadlineMs = this.requestDeadlineMs();
-          const requestAc = new AbortController();
-          const requestTimer = setTimeout(() => requestAc.abort(new Error("buyer deadline exceeded")), deadlineMs);
           const sendSellerRequest = async (token: string) => {
+            const requestAc = new AbortController();
+            const requestTimer = setTimeout(() => requestAc.abort(new Error("buyer deadline exceeded")), deadlineMs);
             const headers: Record<string, string> = {
               "Content-Type": "application/json",
               "Authorization": `Bearer ${token}`,
@@ -1190,19 +1443,23 @@ export class TokenbuddyDaemon {
               "Idempotency-Key": idempotencyKey
             };
             headers["X-TokenBuddy-Deadline-Ms"] = String(deadlineMs);
-            return fetch(`${sellerUrl}${endpoint}`, {
-              method: "POST",
-              headers,
-              body: JSON.stringify(upstreamBody),
-              signal: requestAc.signal
-            });
+            try {
+              return await fetch(`${sellerUrl}${endpoint}`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(upstreamBody),
+                signal: requestAc.signal
+              });
+            } finally {
+              clearTimeout(requestTimer);
+            }
           };
           let upstreamResponse = await sendSellerRequest(token);
 
             if (!upstreamResponse.ok) {
               const errorBody = await upstreamResponse.text();
               if (this.isInsufficientFundsResponse(upstreamResponse.status, errorBody)) {
-                token = await this.recoverFromInsufficientFunds(route, token);
+                token = await this.recoverFromInsufficientFunds(route, token, requestId);
                 upstreamResponse = await sendSellerRequest(token);
                 if (upstreamResponse.ok) {
                   logger.info("proxy.retry_after_402.succeeded", "seller request succeeded after one-shot auto purchase retry", {
@@ -1247,7 +1504,16 @@ export class TokenbuddyDaemon {
                   },
                   routes.length - routeIndex
                 );
-                this.handleFailoverDecision(decision, { sellerKey, endpoint, routeIndex });
+                this.handleFailoverDecision(decision, {
+                  requestId,
+                  sellerKey,
+                  model: modelId,
+                  endpoint,
+                  routeIndex,
+                  routesRemaining: routes.length - routeIndex,
+                  attempt,
+                  status: upstreamResponse.status
+                });
                 if (decision.action === "fail_fast" || decision.action === "abort") {
                   this.copyUpstreamHeaders(upstreamResponse, res);
                   res.status(upstreamResponse.status);
@@ -1357,7 +1623,16 @@ export class TokenbuddyDaemon {
               },
               routes.length - routeIndex
             );
-            this.handleFailoverDecision(decision, { sellerKey, endpoint, routeIndex, reason: "exception" });
+            this.handleFailoverDecision(decision, {
+              requestId,
+              sellerKey,
+              model: modelId,
+              endpoint,
+              routeIndex,
+              routesRemaining: routes.length - routeIndex,
+              attempt,
+              reason: "exception"
+            });
             logger.warn("proxy.route.failed", "seller route failed before response", {
               requestId,
               sellerKey,
@@ -1587,7 +1862,6 @@ export class TokenbuddyDaemon {
           proxyUrl: String(req.body?.proxyUrl || ""),
           model: typeof req.body?.model === "string" ? req.body.model : undefined,
           providerSelections: req.body?.providerSelections,
-          sellerRouting: req.body?.sellerRouting,
           home: typeof req.body?.home === "string" ? req.body.home : undefined
         });
         logger.info("provider.install.previewed", "provider install previewed", {
@@ -1616,7 +1890,6 @@ export class TokenbuddyDaemon {
           proxyUrl: String(req.body?.proxyUrl || ""),
           model: typeof req.body?.model === "string" ? req.body.model : undefined,
           providerSelections: req.body?.providerSelections,
-          sellerRouting: req.body?.sellerRouting,
           home: typeof req.body?.home === "string" ? req.body.home : undefined
         }, this.tokenStore);
         logger.info("provider.install.applied", "provider install applied", {
@@ -1709,7 +1982,10 @@ export class TokenbuddyDaemon {
       proxyPort: this.config.proxyPort,
       dbPath: this.config.dbPath,
       sellerRegistryUrl: this.config.sellerRegistryUrl,
-      selectionMode: this.selectionMode
+      selectionMode: this.selectionMode,
+      sellerRoutingMode: this.sellerRouting.mode,
+      sellerRoutingScorer: this.sellerRouting.scorer,
+      selectedSellerId: this.selectedSellerId
     });
 
     // v1.2 §18.5: kick off the on-demand prewarm pipeline. The startup
@@ -1749,7 +2025,13 @@ export class TokenbuddyDaemon {
       focusSet: focusSet.slice(0, 20)
     });
     try {
-      await this.prewarmScheduler.runStartupPrewarm(focusSet);
+      await this.fetchRegistry();
+      await this.prewarmScheduler.runStartupPrewarm(
+        focusSet.map((modelId) => ({
+          modelId,
+          protocol: this.resolvePrewarmProtocol(modelId)
+        }))
+      );
     } catch (err) {
       logger.warn("prewarm.startup.failed", "startup prewarm sweep failed", {
         errorMessage: err instanceof Error ? err.message : String(err)
@@ -1757,6 +2039,15 @@ export class TokenbuddyDaemon {
     }
   }
 
+  private resolvePrewarmProtocol(modelId: string): string | undefined {
+    for (const protocol of ["chat_completions", "messages", "responses"]) {
+      if (this.modelIndex.sellersFor(modelId, { protocol, paymentMethod: "clawtip" }).length > 0) {
+        return protocol;
+      }
+    }
+    return undefined;
+  }
+
   public stop() {
     if (this.controlServer) this.controlServer.close();
     if (this.proxyServer) this.proxyServer.close();