@tokenbuddy/tokenbuddy 1.0.12 → 1.0.13

package/dist/src/daemon.js

@@ -12,6 +12,8 @@ import { CreditTracker } from "./credit-tracker.js";
 import { SellerPool } from "./seller-pool.js";
 import { RouteFailover } from "./route-failover.js";
 import { PrewarmScheduler } from "./prewarm-scheduler.js";
+import { planSellerRouteSet } from "./seller-route-planner.js";
+import { mergeSellerRoutingConfig, ROUTING_CONFIG_KEY } from "./seller-routing-config.js";
 const logger = createModuleLogger("tb-proxyd");
 const PROXY_JSON_BODY_LIMIT = "10mb";
 function numericHeaderField(value) {
@@ -34,10 +36,12 @@ class SellerSettlementStreamExtractor {
         return blocks
             .map((block) => this.processBlock(block))
             .filter((block) => block.length > 0)
-            .join("\n\n");
+            .map((block) => `${block}\n\n`)
+            .join("");
     }
     finish() {
-        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 };
     }
@@ -96,6 +100,44 @@ function parseSellerSettlementObject(raw) {
         return undefined;
     }
 }
+function arrayLength(value) {
+    return Array.isArray(value) ? value.length : undefined;
+}
+function summarizeProxyBody(body) {
+    if (!body || typeof body !== "object") {
+        return { bodyType: typeof body };
+    }
+    const data = body;
+    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, defaultSellerId) {
+    if (!defaultSellerId) {
+        return sellers;
+    }
+    return [
+        ...sellers.filter((seller) => seller.id === defaultSellerId),
+        ...sellers.filter((seller) => seller.id !== defaultSellerId)
+    ];
+}
+/**
+ * buyer 端守护进程。
+ * 负责启动两个 Express 服务：控制接口（healthz + 控制路由）+ 反向代理（OpenAI / Anthropic 协议入口）。
+ * 同时跑后台任务：seller catalog 周期拉取、model-index 刷新、prewarm scheduler、credit tracker。
+ * 推荐用 `startDaemon(config)` 启动 / `stopDaemon(daemon)` 优雅关闭，避免直接管理生命周期。
+ */
 export class TokenbuddyDaemon {
     config;
     tokenStore;
@@ -103,6 +145,7 @@ export class TokenbuddyDaemon {
     proxyServer;
     selectionMode;
     selectedSellerId;
+    sellerRouting;
     activePurchases = new Map();
     // v1.2 fallback pipeline: model-index, prewarm-cache, credit-tracker,
     // pool, and route-failover together replace the v1
@@ -125,15 +168,12 @@ export class TokenbuddyDaemon {
     prewarmScheduler;
     constructor(config) {
         this.tokenStore = new BuyerStore({ dbPath: config.dbPath });
-        const routingPreference = this.tokenStore.getDaemonRuntimeConfig("routing")
+        const storedRouting = this.tokenStore.getDaemonRuntimeConfig(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, {
@@ -149,7 +189,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);
@@ -159,10 +199,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 };
             }
@@ -219,14 +259,15 @@ export class TokenbuddyDaemon {
         }
     }
     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,
@@ -325,32 +366,33 @@ export class TokenbuddyDaemon {
         // "fetchSellerManifest per candidate" path is removed in favor of
         // 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)
-            ];
-        }
-        if (ordered.length === 0) {
+        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 (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 = ordered.map((seller) => ({
-            seller,
+        const routes = 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", {
             model: modelId,
@@ -358,6 +400,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)
         });
@@ -394,20 +441,88 @@ export class TokenbuddyDaemon {
      */
     handleFailoverDecision(decision, context) {
         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
+        });
+    }
+    logPaymentProofResolved(route, proofSource, requestId) {
+        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
+        });
+    }
+    logPurchaseLedgerRecorded(input) {
+        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
+        });
+    }
+    logTokenBalanceReconciled(route, requestId, settlement) {
+        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"
+        });
     }
     async listSellerBackedModels() {
         const catalog = await discoverSellerBackedModels(this.config.sellerRegistryUrl);
@@ -455,6 +570,7 @@ export class TokenbuddyDaemon {
                 spentMicros: settlement.spentMicros ?? 0,
                 balanceSource: "seller_settlement_summary"
             });
+            this.logTokenBalanceReconciled(route, requestId, settlement);
         }
         const settledMicros = settlement?.settledMicros;
         this.tokenStore.recordInferenceLedger({
@@ -483,6 +599,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"
         });
     }
@@ -541,19 +662,20 @@ export class TokenbuddyDaemon {
             return /insufficient funds/i.test(bodyText);
         }
     }
-    async recoverFromInsufficientFunds(route, token) {
+    async recoverFromInsufficientFunds(route, token, requestId) {
         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;
@@ -586,16 +708,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).
      */
     requestDeadlineMs() {
         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;
     }
@@ -616,7 +738,7 @@ export class TokenbuddyDaemon {
         }
         return parsed;
     }
-    async getOrPurchaseToken(route) {
+    async getOrPurchaseToken(route, requestId) {
         const sellerKey = route.seller.id;
         const sellerUrl = normalizeSellerUrl(route.seller);
         const { modelId, paymentMethod } = route;
@@ -634,6 +756,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,
@@ -642,6 +765,7 @@ export class TokenbuddyDaemon {
             return cached.token;
         }
         logger.info("token.cache.miss", "seller token cache miss", {
+            requestId,
             sellerKey,
             model: modelId,
             balanceMicros: cached?.balanceMicros || 0,
@@ -652,6 +776,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
             });
@@ -661,6 +786,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,
@@ -668,6 +794,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" },
@@ -684,6 +817,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
@@ -705,12 +839,30 @@ export class TokenbuddyDaemon {
                     expiresAt: createData.expiresAt || createData.expires_at
                 });
                 logger.info("purchase.create.succeeded", "seller purchase created", {
+                    sellerKey,
+                    model: modelId,
+                    requestId,
+                    purchaseId,
+                    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, requestId);
+                logger.info("purchase.complete.started", "seller purchase complete started", {
+                    requestId,
                     sellerKey,
                     model: modelId,
                     purchaseId,
-                    status: createRes.status
+                    paymentMethod,
+                    durationMs: Date.now() - startedAt
                 });
-                const paymentProof = await this.resolvePaymentProof(route, createData);
                 const completeRes = await fetch(`${sellerUrl}/purchase/complete`, {
                     method: "POST",
                     headers: { "Content-Type": "application/json" },
@@ -726,6 +878,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",
@@ -741,33 +894,51 @@ 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({
                     purchaseId,
                     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) {
                 logger.error("purchase.token.failed", "seller token purchase failed", {
+                    requestId,
                     sellerKey,
                     model: modelId,
                     errorMessage: error instanceof Error ? error.message : String(error),
@@ -782,7 +953,7 @@ export class TokenbuddyDaemon {
         this.activePurchases.set(purchaseKey, purchaseTask);
         return purchaseTask;
     }
-    async resolvePaymentProof(route, createData) {
+    async resolvePaymentProof(route, createData, requestId) {
         if (route.paymentMethod === "mock") {
             return "mock-proof-data";
         }
@@ -791,19 +962,24 @@ 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();
         }
         throw new Error("clawtip auto purchase requires TB_PROXYD_CLAWTIP_PROOF_COMMAND or a ClawTip proof env/file");
     }
-    runClawtipProofCommand(route, createData, commandPath) {
+    runClawtipProofCommand(route, createData, commandPath, requestId) {
         const timeoutMs = this.clawtipProofTimeoutMs();
         const payload = JSON.stringify({
             sellerKey: route.seller.id,
@@ -814,6 +990,7 @@ export class TokenbuddyDaemon {
             quote: createData.quote
         });
         logger.info("purchase.clawtip_proof.started", "clawtip proof provider started", {
+            requestId,
             sellerKey: route.seller.id,
             model: route.modelId,
             timeoutMs
@@ -868,6 +1045,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
@@ -948,7 +1126,7 @@ export class TokenbuddyDaemon {
                             model: modelId,
                             endpoint,
                             stream: Boolean(body.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"
@@ -969,7 +1147,7 @@ export class TokenbuddyDaemon {
                         // seller; transfer leftover to wasted and fail over immediately.
                         let token;
                         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", {
@@ -979,12 +1157,25 @@ export class TokenbuddyDaemon {
                                 endpoint,
                                 errorMessage: this.failoverErrorMessage(purchaseError)
                             });
-                            this.routeFailover.decide({
+                            const decision = this.routeFailover.decide({
                                 sellerId: sellerKey,
                                 errorKind: "deadline",
                                 errorMessage: this.failoverErrorMessage(purchaseError),
                                 attempt
                             }, 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;
                         }
@@ -994,9 +1185,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) => {
+                            const requestAc = new AbortController();
+                            const requestTimer = setTimeout(() => requestAc.abort(new Error("buyer deadline exceeded")), deadlineMs);
                             const headers = {
                                 "Content-Type": "application/json",
                                 "Authorization": `Bearer ${token}`,
@@ -1004,18 +1195,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", {
@@ -1059,7 +1255,16 @@ export class TokenbuddyDaemon {
                                     errorMessage: errorBody,
                                     attempt
                                 }, 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);
@@ -1149,7 +1354,16 @@ export class TokenbuddyDaemon {
                             errorMessage: this.failoverErrorMessage(routeError),
                             attempt
                         }, 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,
@@ -1371,7 +1585,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", {
@@ -1400,7 +1613,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", {
@@ -1490,7 +1702,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
         // sweep runs after the configured jitter window (5-10s by default);
@@ -1527,7 +1742,11 @@ 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", {
@@ -1535,6 +1754,14 @@ export class TokenbuddyDaemon {
             });
         }
     }
+    resolvePrewarmProtocol(modelId) {
+        for (const protocol of ["chat_completions", "messages", "responses"]) {
+            if (this.modelIndex.sellersFor(modelId, { protocol, paymentMethod: "clawtip" }).length > 0) {
+                return protocol;
+            }
+        }
+        return undefined;
+    }
     stop() {
         if (this.controlServer)
             this.controlServer.close();