@tokenbuddy/tokenbuddy 1.0.26 → 1.0.28

package/dist/src/daemon.js

@@ -6,22 +6,26 @@ import * as path from "path";
 import { ErrorCode } from "@tokenbuddy/contracts";
 import { createModuleLogger } from "@tokenbuddy/logging";
 import { BuyerStore } from "./buyer-store.js";
-import { fetchClawtipBootstrap } from "./clawtip-bootstrap.js";
+import { DEFAULT_CLAWTIP_BOOTSTRAP_URL, fetchClawtipBootstrap } from "./clawtip-bootstrap.js";
 import { inspectOpenClawWalletConfig, } from "./init-payment-options.js";
 import { startClawtipWalletBootstrap, waitForClawtipActivationConfirmation, } from "./init-clawtip-activation.js";
 import { applyProviderInstall, detectProviders, previewProviderInstall, rollbackProviderInstall, } from "./provider-install.js";
-import { discoverSellerBackedModels, fetchSellerRegistry, isBuyerVisibleRegistrySeller, normalizeSellerUrl, RegistryTooLargeError, } from "./seller-catalog.js";
+import { discoverSellerBackedModels, fetchSellerRegistryWithTrust, isBuyerVisibleRegistrySeller, normalizeSellerUrl, RegistryTooLargeError, } from "./seller-catalog.js";
+import { shouldVerifyRegistry, verifyTrustedRegistrySignature } from "./registry-trust.js";
 import { ModelIndex } from "./model-index.js";
 import { PrewarmCache, prewarmKey } from "./prewarm-cache.js";
 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 { SellerConcurrencyLimiter } from "./seller-concurrency-limiter.js";
 import { planSellerRouteSet } from "./seller-route-planner.js";
 import { assertSellerRoutingConfig, mergeSellerRoutingConfig, normalizeSellerRoutingConfig, parseSellerIdList, ROUTING_CONFIG_KEY } from "./seller-routing-config.js";
 import { assertInitSetupSteps, buildCompletedInitSetupMarker, INIT_SETUP_CONFIG_KEY, INIT_SETUP_STEPS, isFreshInitMachine, normalizeInitSetupMarker, resolveInitRecommendedModels, } from "./init-setup.js";
+import { checkPackageUpdate, runPackageUpdate, scheduleLaunchAgentRestart, } from "./package-update.js";
 const logger = createModuleLogger("tb-proxyd");
 const FOCUS_SET_CONFIG_KEY = "focus-set";
+const TRUSTED_REGISTRY_CACHE_CONFIG_KEY = "trusted-registry-snapshot";
 const PROXY_JSON_BODY_LIMIT = "10mb";
 const SELLER_CAPACITY_BLOCK_MS = 2_000;
 const CLAWTIP_STATIC_ROUTE = "/static/clawtip";
@@ -306,6 +310,7 @@ export class TokenbuddyDaemon {
     // config-derived knobs. The `!` opts out of strict-initialization so the
     // rest of the class can treat it as non-nullable.
     prewarmScheduler;
+    sellerConcurrencyLimiter;
     constructor(config) {
         this.tokenStore = new BuyerStore({ dbPath: config.dbPath });
         const storedRouting = this.tokenStore.getDaemonRuntimeConfig(ROUTING_CONFIG_KEY)
@@ -314,6 +319,7 @@ export class TokenbuddyDaemon {
             ?.config;
         this.config = config;
         this.sellerRouting = mergeSellerRoutingConfig(storedRouting, config.sellerRouting);
+        this.sellerConcurrencyLimiter = new SellerConcurrencyLimiter(config.sellerConcurrency);
         this.selectionMode = selectionModeForRouting(this.sellerRouting);
         this.selectedSellerId = selectedSellerIdForRouting(this.sellerRouting);
         // tb-ui v1: explicit focus set 优先于 env / historical
@@ -433,7 +439,7 @@ export class TokenbuddyDaemon {
         };
     }
     async startClawtipActivationQr() {
-        const bootstrapUrl = process.env.TOKENBUDDY_BOOTSTRAP_URL || "https://tb-wallet-bootstrap.fly.dev";
+        const bootstrapUrl = process.env.TOKENBUDDY_BOOTSTRAP_URL || DEFAULT_CLAWTIP_BOOTSTRAP_URL;
         const fetchBootstrap = this.config.clawtipBootstrapFetcher || fetchClawtipBootstrap;
         const bootstrap = await fetchBootstrap(bootstrapUrl);
         const payment = normalizeClawtipActivationPayment(bootstrap);
@@ -577,13 +583,15 @@ export class TokenbuddyDaemon {
     lastRegistrySnapshot = null;
     async fetchRegistry() {
         try {
-            const registry = await fetchSellerRegistry(this.config.sellerRegistryUrl);
+            const fetched = await fetchSellerRegistryWithTrust(this.config.sellerRegistryUrl);
+            const registry = fetched.registry;
             this.modelIndex.rebuild(registry.sellers, {
                 registryVersion: registry.version,
                 defaultSellerId: registry.defaultSeller
             });
             this.sellerPool.sync();
             this.lastRegistrySnapshot = registry;
+            this.saveTrustedRegistryCache(fetched);
             return registry;
         }
         catch (err) {
@@ -604,9 +612,103 @@ export class TokenbuddyDaemon {
                 this.sellerPool.sync();
                 return stale;
             }
+            const cached = this.loadTrustedRegistryCache(err);
+            if (cached) {
+                this.modelIndex.rebuild(cached.sellers, {
+                    registryVersion: cached.version,
+                    defaultSellerId: cached.defaultSeller
+                });
+                this.sellerPool.sync();
+                this.lastRegistrySnapshot = cached;
+                return cached;
+            }
             throw err;
         }
     }
+    saveTrustedRegistryCache(fetched) {
+        const cache = {
+            schemaVersion: 1,
+            registryUrl: this.config.sellerRegistryUrl,
+            version: fetched.registry.version,
+            registrySha256: fetched.trust.registrySha256,
+            cachedAt: new Date().toISOString(),
+            registryJson: fetched.registryJson,
+            registry: fetched.registry,
+            trust: fetched.trust
+        };
+        this.tokenStore.saveDaemonRuntimeConfig(TRUSTED_REGISTRY_CACHE_CONFIG_KEY, cache);
+        logger.info("registry.trusted_cache.saved", "trusted registry snapshot cached", {
+            registryUrl: cache.registryUrl,
+            registryVersion: cache.version ?? null,
+            registrySha256: cache.registrySha256,
+            verified: cache.trust.verified,
+            signingKeyId: cache.trust.signingKeyId ?? null
+        });
+    }
+    loadTrustedRegistryCache(error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const record = this.tokenStore.getDaemonRuntimeConfig(TRUSTED_REGISTRY_CACHE_CONFIG_KEY)?.config;
+        const cache = normalizeTrustedRegistryCache(record);
+        if (!cache) {
+            logger.warn("registry.trusted_cache.missing", "trusted registry cache is unavailable", {
+                registryUrl: this.config.sellerRegistryUrl,
+                errorMessage
+            });
+            return undefined;
+        }
+        if (cache.registryUrl !== this.config.sellerRegistryUrl) {
+            logger.warn("registry.trusted_cache.missing", "trusted registry cache URL mismatch", {
+                registryUrl: this.config.sellerRegistryUrl,
+                cachedRegistryUrl: cache.registryUrl,
+                errorMessage
+            });
+            return undefined;
+        }
+        const actualHash = crypto.createHash("sha256").update(cache.registryJson).digest("hex");
+        if (actualHash !== cache.registrySha256 || actualHash !== cache.trust.registrySha256) {
+            logger.warn("registry.trusted_cache.missing", "trusted registry cache hash mismatch", {
+                registryUrl: this.config.sellerRegistryUrl,
+                cachedVersion: cache.version ?? null,
+                errorMessage
+            });
+            return undefined;
+        }
+        if (shouldVerifyRegistry(this.config.sellerRegistryUrl)) {
+            if (!cache.trust.signature) {
+                logger.warn("registry.trusted_cache.missing", "trusted registry cache has no signature", {
+                    registryUrl: this.config.sellerRegistryUrl,
+                    cachedVersion: cache.version ?? null,
+                    errorMessage
+                });
+                return undefined;
+            }
+            try {
+                const signingKeyId = verifyTrustedRegistrySignature(cache.registryJson, cache.trust.signature);
+                if (cache.trust.signingKeyId && cache.trust.signingKeyId !== signingKeyId) {
+                    throw new Error("registry cache signing key mismatch");
+                }
+            }
+            catch (verifyError) {
+                logger.warn("registry.trusted_cache.missing", "trusted registry cache signature verification failed", {
+                    registryUrl: this.config.sellerRegistryUrl,
+                    cachedVersion: cache.version ?? null,
+                    errorMessage: verifyError instanceof Error ? verifyError.message : String(verifyError)
+                });
+                return undefined;
+            }
+        }
+        logger.warn("registry.trusted_cache.used", "using trusted registry cache after refresh failure", {
+            registryUrl: this.config.sellerRegistryUrl,
+            cachedVersion: cache.version ?? null,
+            cachedSellers: cache.registry.sellers.length,
+            cachedAt: cache.cachedAt,
+            registrySha256: cache.registrySha256,
+            verified: cache.trust.verified,
+            signingKeyId: cache.trust.signingKeyId ?? null,
+            errorMessage
+        });
+        return cache.registry;
+    }
     runtimeSummary() {
         this.refreshSellerRoutingConfig();
         return {
@@ -621,6 +723,7 @@ export class TokenbuddyDaemon {
             selectedSellerId: this.selectedSellerId,
             dbPath: this.config.dbPath,
             sellerRegistryUrl: this.config.sellerRegistryUrl,
+            sellerConcurrency: this.sellerConcurrencyLimiter.snapshot(),
             store: this.tokenStore.summary()
         };
     }
@@ -913,7 +1016,7 @@ export class TokenbuddyDaemon {
         const payments = this.tokenStore.listPayments().filter((payment) => payment.enabled);
         return payments.find((payment) => payment.isDefault)?.method || payments.find((payment) => payment.method === "mock")?.method;
     }
-    async selectSellerRoutes(endpoint, modelId) {
+    async selectSellerRoutes(endpoint, modelId, requestId) {
         const protocol = this.endpointProtocol(endpoint);
         if (!protocol) {
             throw new Error(`unsupported proxy endpoint: ${endpoint}`);
@@ -932,7 +1035,10 @@ export class TokenbuddyDaemon {
         const registrySellers = reorderDefaultSellerFirst(registry.sellers, registry.defaultSeller);
         this.sellerPool.ensureRegistrySellers(registrySellers);
         this.scheduleLazyPrewarmIfNeeded(modelId, protocol, paymentMethod);
+        this.sellerPool.recycleOpenCircuits();
         const poolById = new Map(this.sellerPool.snapshot().map((entry) => [entry.sellerId, entry]));
+        const concurrencySnapshot = this.sellerConcurrencyLimiter.snapshot();
+        const localConcurrencyBySellerId = new Map(concurrencySnapshot.active.map((entry) => [entry.sellerId, entry.activeCount]));
         const planned = planSellerRouteSet({
             modelId,
             protocol,
@@ -947,22 +1053,18 @@ export class TokenbuddyDaemon {
                 ttftMs: entry.ttftMs,
                 avgInferenceMs: entry.avgInferenceMs,
                 circuit: entry.circuit,
-                capacityBlockedUntil: entry.capacityBlockedUntil
+                capacityBlockedUntil: entry.capacityBlockedUntil,
+                ...(concurrencySnapshot.enabled
+                    ? {
+                        localConcurrencyActive: localConcurrencyBySellerId.get(entry.sellerId) ?? 0,
+                        localConcurrencyLimit: concurrencySnapshot.maxInFlightPerSeller
+                    }
+                    : {})
             })),
             now: Date.now()
         });
-        if (planned.routes.length === 0) {
-            throw new Error(`no compatible seller for ${endpoint} model ${modelId}`);
-        }
-        const routes = planned.routes.map((route) => ({
-            seller: route.seller,
-            manifest: null,
-            protocol,
-            modelId,
-            paymentMethod,
-            poolEntry: poolById.get(route.seller.id)
-        }));
         logger.info("route.candidates.prewarmed", "seller route candidates prewarmed", {
+            requestId,
             model: modelId,
             endpoint,
             protocol,
@@ -973,9 +1075,24 @@ export class TokenbuddyDaemon {
             routeSource: planned.source,
             routeSourceReason: planned.sourceReason,
             routeReason: planned.reason,
-            sellerCount: routes.length,
-            sellers: routes.map((route) => route.seller.id)
+            candidateDiagnostics: planned.diagnostics,
+            sellerCount: planned.routes.length,
+            sellers: planned.routes.map((route) => route.seller.id)
         });
+        if (planned.routes.length === 0) {
+            throw new Error(`no compatible seller for ${endpoint} model ${modelId}`);
+        }
+        const routes = planned.routes.map((route) => ({
+            seller: route.seller,
+            manifest: null,
+            protocol,
+            modelId,
+            paymentMethod,
+            planSource: planned.source,
+            planReason: planned.reason,
+            planSellerCount: planned.routes.length,
+            poolEntry: poolById.get(route.seller.id)
+        }));
         return { routes, plan: planned, paymentMethod };
     }
     refreshSellerRoutingConfig() {
@@ -1113,6 +1230,8 @@ export class TokenbuddyDaemon {
      * the controller loop readable.
      */
     handleFailoverDecision(decision, context) {
+        const routesRemainingAfterCurrent = Math.max(0, context.routesRemaining - 1);
+        const hasNextRoute = routesRemainingAfterCurrent > 0;
         if (decision.action === "retry_same_seller") {
             logger.warn("route.failover.retry_scheduled", "seller route retry scheduled", {
                 requestId: context.requestId,
@@ -1121,8 +1240,12 @@ export class TokenbuddyDaemon {
                 endpoint: context.endpoint,
                 routeIndex: context.routeIndex,
                 routesRemaining: context.routesRemaining,
+                routesRemainingAfterCurrent,
+                hasNextRoute,
                 attempt: context.attempt,
+                attemptNumber: context.attempt + 1,
                 nextAttempt: context.attempt + 1,
+                nextAttemptNumber: context.attempt + 2,
                 reason: decision.reason,
                 status: context.status,
                 retryDelayMs: decision.retryDelayMs
@@ -1130,7 +1253,7 @@ export class TokenbuddyDaemon {
             return;
         }
         if (decision.action === "failover_next") {
-            logger.warn("route.failover.triggered", "seller route failed over to backup candidate", {
+            logger.warn("route.failover.triggered", "seller route failed over after seller failure", {
                 requestId: context.requestId,
                 sellerKey: context.sellerKey,
                 model: context.model,
@@ -1138,7 +1261,10 @@ export class TokenbuddyDaemon {
                 routeIndex: context.routeIndex,
                 nextRouteIndex: context.routeIndex + 1,
                 routesRemaining: context.routesRemaining,
+                routesRemainingAfterCurrent,
+                hasNextRoute,
                 attempt: context.attempt,
+                attemptNumber: context.attempt + 1,
                 reason: decision.reason,
                 status: context.status,
                 wastedCreditMicros: decision.wastedCreditMicros,
@@ -1154,7 +1280,10 @@ export class TokenbuddyDaemon {
             endpoint: context.endpoint,
             routeIndex: context.routeIndex,
             routesRemaining: context.routesRemaining,
+            routesRemainingAfterCurrent,
+            hasNextRoute,
             attempt: context.attempt,
+            attemptNumber: context.attempt + 1,
             action: decision.action,
             reason: decision.reason,
             status: context.status
@@ -1198,12 +1327,32 @@ export class TokenbuddyDaemon {
         });
     }
     async listSellerBackedModels() {
-        const catalog = await discoverSellerBackedModels(this.config.sellerRegistryUrl);
-        this.lastRegistrySnapshot = sellerCatalogResultToRegistrySnapshot(catalog);
-        return {
-            models: catalog.models,
-            sellers: catalog.sellers
-        };
+        try {
+            const catalog = await discoverSellerBackedModels(this.config.sellerRegistryUrl);
+            this.lastRegistrySnapshot = catalog.registry ?? sellerCatalogResultToRegistrySnapshot(catalog);
+            if (catalog.registry && catalog.registryJson && catalog.registryTrust) {
+                this.saveTrustedRegistryCache({
+                    registry: catalog.registry,
+                    registryJson: catalog.registryJson,
+                    trust: catalog.registryTrust
+                });
+            }
+            return {
+                models: catalog.models,
+                sellers: catalog.sellers
+            };
+        }
+        catch (error) {
+            const cached = this.loadTrustedRegistryCache(error);
+            if (!cached) {
+                throw error;
+            }
+            const snapshot = catalogSnapshotFromRegistry(cached);
+            return {
+                models: snapshot.models,
+                sellers: snapshot.sellers
+            };
+        }
     }
     readUsage(bodyText) {
         const fallback = {
@@ -1777,7 +1926,7 @@ export class TokenbuddyDaemon {
             return;
         }
         try {
-            const { routes, plan, paymentMethod } = await this.selectSellerRoutes(endpoint, modelId);
+            const { routes, plan, paymentMethod } = await this.selectSellerRoutes(endpoint, modelId, requestId);
             const upstreamStatusFromHeaders = (h) => {
                 const raw = h.get("x-tokenbuddy-upstream-status") || h.get("x-upstream-status");
                 if (!raw)
@@ -1788,258 +1937,313 @@ export class TokenbuddyDaemon {
             for (let routeIndex = 0; routeIndex < routes.length; routeIndex += 1) {
                 const route = routes[routeIndex];
                 const sellerKey = route.seller.id;
-                logger.info("route.selected", "seller route selected", {
-                    sellerKey,
-                    sellerId: sellerKey,
-                    model: modelId,
-                    endpoint,
-                    protocol: route.protocol,
-                    paymentMethod: route.paymentMethod,
-                    routeIndex,
-                    backup: routeIndex > 0
-                });
-                let attempt = 0;
-                // Soft-failure retry budget; the route-failover controller decides
-                // whether the same seller should be retried or we move on. The
-                // v1 "1 retry for 4xx fallback" loop is replaced with a
-                // stateful decision per attempt.
-                // eslint-disable-next-line no-constant-condition
-                while (true) {
-                    try {
-                        logger.info("proxy.request.started", "proxy request started", {
-                            requestId,
-                            sellerKey,
-                            model: modelId,
-                            requestedModel: requestedModelId,
-                            endpoint,
-                            stream: Boolean(body.stream),
-                            attempt
-                        });
-                        const sellerUrl = normalizeSellerUrl(route.seller);
-                        const upstreamBody = this.applyResolvedModelToBody(endpoint, {
-                            ...body,
-                            requestId
-                        }, modelId);
-                        logger.info("proxy.upstream_fetch.started", "proxy upstream fetch started", {
-                            requestId,
-                            sellerKey,
-                            model: modelId,
-                            endpoint,
-                            stream: Boolean(body.stream),
-                            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"
-                        // and the request fails over to the next candidate.
-                        if (!this.routeFailover.canAutoPurchase()) {
-                            logger.warn("purchase.budget.exceeded", "session auto-purchase budget exhausted; failing over without buying", {
-                                requestId,
-                                sellerKey,
-                                model: modelId,
-                                endpoint,
-                                routeIndex
-                            });
-                            lastError = new Error("auto-purchase budget exceeded for this session");
-                            break;
-                        }
-                        // v1.1: a purchase failure means the seller is unreachable for
-                        // payment, not "transiently flapping". Do not retry the same
-                        // seller; transfer leftover to wasted and fail over immediately.
-                        let token;
+                const lease = this.sellerConcurrencyLimiter.tryAcquire(sellerKey, { requestId, modelId, endpoint });
+                if (!lease) {
+                    const routesRemaining = routes.length - routeIndex;
+                    const routesRemainingAfterCurrent = Math.max(0, routesRemaining - 1);
+                    lastError = new Error(`seller ${sellerKey} reached local concurrency limit`);
+                    logger.info("route.local_capacity.skipped", "seller route skipped by local concurrency limit", {
+                        requestId,
+                        sellerKey,
+                        sellerId: sellerKey,
+                        model: modelId,
+                        endpoint,
+                        protocol: route.protocol,
+                        paymentMethod: route.paymentMethod,
+                        routeIndex,
+                        routePlanSource: route.planSource,
+                        routePlanReason: route.planReason,
+                        routePlanSellerCount: route.planSellerCount,
+                        routesRemaining,
+                        routesRemainingAfterCurrent,
+                        hasNextRoute: routesRemainingAfterCurrent > 0,
+                        localConcurrencyEnabled: this.sellerConcurrencyLimiter.isEnabled()
+                    });
+                    continue;
+                }
+                try {
+                    logger.info("route.selected", "seller route selected", {
+                        requestId,
+                        sellerKey,
+                        sellerId: sellerKey,
+                        model: modelId,
+                        endpoint,
+                        protocol: route.protocol,
+                        paymentMethod: route.paymentMethod,
+                        routeIndex,
+                        backup: routeIndex > 0,
+                        routePlanSource: route.planSource,
+                        routePlanReason: route.planReason,
+                        routePlanSellerCount: route.planSellerCount,
+                        localConcurrencyEnabled: this.sellerConcurrencyLimiter.isEnabled(),
+                        localConcurrencyActive: lease.activeCount,
+                        localConcurrencyLimit: lease.maxInFlight
+                    });
+                    let attempt = 0;
+                    // Soft-failure retry budget; the route-failover controller decides
+                    // whether the same seller should be retried or we move on. The
+                    // v1 "1 retry for 4xx fallback" loop is replaced with a
+                    // stateful decision per attempt.
+                    // eslint-disable-next-line no-constant-condition
+                    while (true) {
                         try {
-                            token = await this.getOrPurchaseToken(route, requestId);
-                        }
-                        catch (purchaseError) {
-                            logger.warn("purchase.failed", "seller auto-purchase failed; failing over without retry", {
+                            logger.info("proxy.request.started", "proxy request started", {
                                 requestId,
                                 sellerKey,
                                 model: modelId,
+                                requestedModel: requestedModelId,
                                 endpoint,
-                                errorMessage: this.failoverErrorMessage(purchaseError)
-                            });
-                            const decision = this.routeFailover.decide({
-                                sellerId: sellerKey,
-                                errorKind: "deadline",
-                                errorMessage: this.failoverErrorMessage(purchaseError),
+                                stream: Boolean(body.stream),
                                 attempt
-                            }, routes.length - routeIndex);
-                            logger.warn("route.failover.triggered", "seller route failed over after purchase failure", {
+                            });
+                            const sellerUrl = normalizeSellerUrl(route.seller);
+                            const upstreamBody = this.applyResolvedModelToBody(endpoint, {
+                                ...body,
+                                requestId
+                            }, modelId);
+                            logger.info("proxy.upstream_fetch.started", "proxy upstream fetch started", {
                                 requestId,
                                 sellerKey,
                                 model: modelId,
                                 endpoint,
-                                routeIndex,
-                                nextRouteIndex: routeIndex + 1,
-                                routesRemaining: routes.length - routeIndex,
-                                attempt,
-                                reason: "purchase_failed",
-                                controllerReason: decision.reason,
-                                controllerAction: decision.action
+                                stream: Boolean(body.stream),
+                                bodySummary: summarizeProxyBody(upstreamBody)
                             });
-                            lastError = purchaseError;
-                            break;
-                        }
-                        // v1.2 §8: enforce a hard per-request deadline so a slow
-                        // upstream cannot hang the buyer. The deadline is honored by
-                        // the AbortController passed to `fetch`; sellers that observe
-                        // 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 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}`,
-                                "X-Request-Id": requestId,
-                                "Idempotency-Key": idempotencyKey
-                            };
-                            headers["X-TokenBuddy-Deadline-Ms"] = String(deadlineMs);
-                            try {
-                                return await fetch(`${sellerUrl}${endpoint}`, {
-                                    method: "POST",
-                                    headers,
-                                    body: JSON.stringify(upstreamBody),
-                                    signal: requestAc.signal
+                            // v1.1 §17.5: refuse to auto-purchase once the session budget is
+                            // exhausted. The seller is treated as "no auto-purchase available"
+                            // and the request fails over to the next candidate.
+                            if (!this.routeFailover.canAutoPurchase()) {
+                                logger.warn("purchase.budget.exceeded", "session auto-purchase budget exhausted; failing over without buying", {
+                                    requestId,
+                                    sellerKey,
+                                    model: modelId,
+                                    endpoint,
+                                    routeIndex
                                 });
+                                lastError = new Error("auto-purchase budget exceeded for this session");
+                                break;
                             }
-                            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, requestId);
-                                upstreamResponse = await sendSellerRequest(token);
-                                if (upstreamResponse.ok) {
-                                    logger.info("proxy.retry_after_402.succeeded", "seller request succeeded after one-shot auto purchase retry", {
-                                        requestId,
-                                        sellerKey,
-                                        model: modelId,
-                                        endpoint,
-                                        durationMs: Date.now() - startedAt
-                                    });
-                                }
-                                else {
-                                    const retryErrorBody = await upstreamResponse.text();
-                                    logger.warn("proxy.retry_after_402.failed", "seller request still failed after one-shot auto purchase retry", {
-                                        requestId,
-                                        sellerKey,
-                                        model: modelId,
-                                        endpoint,
-                                        status: upstreamResponse.status,
-                                        durationMs: Date.now() - startedAt
-                                    });
-                                    this.copyUpstreamHeaders(upstreamResponse, res);
-                                    res.status(upstreamResponse.status);
-                                    res.send(retryErrorBody);
-                                    return;
-                                }
+                            // v1.1: a purchase failure means the seller is unreachable for
+                            // payment, not "transiently flapping". Do not retry the same
+                            // seller; fail over immediately without marking old credit wasted.
+                            let token;
+                            try {
+                                token = await this.getOrPurchaseToken(route, requestId);
                             }
-                            else {
-                                logger.warn("proxy.upstream_fetch.failed", "proxy upstream fetch returned non-ok status", {
+                            catch (purchaseError) {
+                                logger.warn("purchase.failed", "seller auto-purchase failed; failing over without retry", {
                                     requestId,
                                     sellerKey,
                                     model: modelId,
                                     endpoint,
-                                    status: upstreamResponse.status,
-                                    durationMs: Date.now() - startedAt
+                                    errorMessage: this.failoverErrorMessage(purchaseError)
                                 });
-                                const kind = this.classifyFailureStatus(upstreamResponse.status, errorBody);
                                 const decision = this.routeFailover.decide({
                                     sellerId: sellerKey,
-                                    status: upstreamResponse.status,
-                                    errorKind: kind,
-                                    errorMessage: errorBody,
+                                    errorKind: "purchase_failed",
+                                    errorMessage: this.failoverErrorMessage(purchaseError),
                                     attempt
                                 }, routes.length - routeIndex);
-                                this.handleFailoverDecision(decision, {
+                                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,
+                                    routesRemainingAfterCurrent: Math.max(0, routes.length - routeIndex - 1),
+                                    hasNextRoute: routeIndex + 1 < routes.length,
                                     attempt,
-                                    status: upstreamResponse.status
+                                    attemptNumber: attempt + 1,
+                                    reason: "purchase_failed",
+                                    controllerReason: decision.reason,
+                                    controllerAction: decision.action
                                 });
-                                if (decision.action === "fail_fast" || decision.action === "abort") {
-                                    this.copyUpstreamHeaders(upstreamResponse, res);
-                                    res.status(upstreamResponse.status);
-                                    res.send(errorBody);
-                                    return;
+                                lastError = purchaseError;
+                                break;
+                            }
+                            // v1.2 §8: enforce a hard per-request deadline so a slow
+                            // upstream cannot hang the buyer. The deadline is honored by
+                            // the AbortController passed to `fetch`; sellers that observe
+                            // 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 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}`,
+                                    "X-Request-Id": requestId,
+                                    "Idempotency-Key": idempotencyKey
+                                };
+                                headers["X-TokenBuddy-Deadline-Ms"] = String(deadlineMs);
+                                try {
+                                    return await fetch(`${sellerUrl}${endpoint}`, {
+                                        method: "POST",
+                                        headers,
+                                        body: JSON.stringify(upstreamBody),
+                                        signal: requestAc.signal
+                                    });
+                                }
+                                finally {
+                                    clearTimeout(requestTimer);
                                 }
-                                if (decision.action === "retry_same_seller") {
-                                    attempt += 1;
-                                    if (decision.retryDelayMs) {
-                                        await new Promise((resolve) => setTimeout(resolve, decision.retryDelayMs));
+                            };
+                            let upstreamResponse = await sendSellerRequest(token);
+                            lease.refresh();
+                            if (!upstreamResponse.ok) {
+                                const errorBody = await upstreamResponse.text();
+                                lease.refresh();
+                                if (this.isInsufficientFundsResponse(upstreamResponse.status, errorBody)) {
+                                    token = await this.recoverFromInsufficientFunds(route, token, requestId);
+                                    upstreamResponse = await sendSellerRequest(token);
+                                    lease.refresh();
+                                    if (upstreamResponse.ok) {
+                                        logger.info("proxy.retry_after_402.succeeded", "seller request succeeded after one-shot auto purchase retry", {
+                                            requestId,
+                                            sellerKey,
+                                            model: modelId,
+                                            endpoint,
+                                            durationMs: Date.now() - startedAt
+                                        });
+                                    }
+                                    else {
+                                        const retryErrorBody = await upstreamResponse.text();
+                                        logger.warn("proxy.retry_after_402.failed", "seller request still failed after one-shot auto purchase retry", {
+                                            requestId,
+                                            sellerKey,
+                                            model: modelId,
+                                            endpoint,
+                                            status: upstreamResponse.status,
+                                            durationMs: Date.now() - startedAt
+                                        });
+                                        this.copyUpstreamHeaders(upstreamResponse, res);
+                                        res.status(upstreamResponse.status);
+                                        res.send(retryErrorBody);
+                                        return;
                                     }
-                                    continue;
                                 }
-                                // failover_next
-                                lastError = new Error(`seller ${sellerKey} returned ${upstreamResponse.status}`);
-                                break;
-                            }
-                        }
-                        // Successful response: stream or buffer.
-                        this.copyUpstreamHeaders(upstreamResponse, res);
-                        res.status(upstreamResponse.status);
-                        logger.info("proxy.upstream_fetch.succeeded", "proxy upstream fetch succeeded", {
-                            requestId,
-                            sellerKey,
-                            model: modelId,
-                            endpoint,
-                            status: upstreamResponse.status,
-                            stream: Boolean(body.stream)
-                        });
-                        const contentType = upstreamResponse.headers.get("content-type") || "";
-                        if (contentType.includes("text/event-stream") || Boolean(body.stream)) {
-                            const reader = upstreamResponse.body?.getReader();
-                            if (!reader) {
-                                res.end();
-                                return;
-                            }
-                            let bytes = 0;
-                            const decoder = new TextDecoder();
-                            const settlementExtractor = new SellerSettlementStreamExtractor();
-                            while (true) {
-                                const { done, value } = await reader.read();
-                                if (done) {
+                                else {
+                                    logger.warn("proxy.upstream_fetch.failed", "proxy upstream fetch returned non-ok status", {
+                                        requestId,
+                                        sellerKey,
+                                        model: modelId,
+                                        endpoint,
+                                        status: upstreamResponse.status,
+                                        durationMs: Date.now() - startedAt
+                                    });
+                                    const kind = this.classifyFailureStatus(upstreamResponse.status, errorBody);
+                                    const decision = this.routeFailover.decide({
+                                        sellerId: sellerKey,
+                                        status: upstreamResponse.status,
+                                        errorKind: kind,
+                                        errorMessage: errorBody,
+                                        attempt
+                                    }, routes.length - 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);
+                                        res.send(errorBody);
+                                        return;
+                                    }
+                                    if (decision.action === "retry_same_seller") {
+                                        attempt += 1;
+                                        if (decision.retryDelayMs) {
+                                            await new Promise((resolve) => setTimeout(resolve, decision.retryDelayMs));
+                                        }
+                                        continue;
+                                    }
+                                    // failover_next
+                                    lastError = new Error(`seller ${sellerKey} returned ${upstreamResponse.status}`);
                                     break;
                                 }
-                                bytes += value.byteLength;
-                                const chunk = decoder.decode(value, { stream: true });
-                                // 透明代理：把 seller 的 SSE 字节原样转给客户端，只剥离我们注入的
-                                // tokenbuddy.settlement 事件（不让客户端看到内部记账字段）。除此之外
-                                // 不做任何协议转换——卖方格式 bug（如 chat.completion.chunk prefix、
-                                // 缺 event: 行）由卖方修，buyer 不兜底。
-                                const sellerChunk = settlementExtractor.push(chunk);
-                                if (sellerChunk.length > 0) {
-                                    markFirstByte();
-                                    res.write(sellerChunk);
-                                }
                             }
-                            // flush TextDecoder 内部 buffer：stream:true 模式下最后可能留有几个字节的
-                            // 不完整 UTF-8 序列（多字节字符被切到下一 chunk 的场景），不调 stream:false
-                            // flush 就 break 会丢这批字节。上面的 stream 末尾事件（done / completed）
-                            // 之前被吞掉就是这个原因。
-                            const decoderTail = decoder.decode();
-                            if (decoderTail.length > 0) {
-                                const sellerTail = settlementExtractor.push(decoderTail);
-                                if (sellerTail.length > 0) {
+                            // Successful response: stream or buffer.
+                            this.copyUpstreamHeaders(upstreamResponse, res);
+                            res.status(upstreamResponse.status);
+                            logger.info("proxy.upstream_fetch.succeeded", "proxy upstream fetch succeeded", {
+                                requestId,
+                                sellerKey,
+                                model: modelId,
+                                endpoint,
+                                status: upstreamResponse.status,
+                                stream: Boolean(body.stream)
+                            });
+                            const contentType = upstreamResponse.headers.get("content-type") || "";
+                            if (contentType.includes("text/event-stream") || Boolean(body.stream)) {
+                                const reader = upstreamResponse.body?.getReader();
+                                if (!reader) {
+                                    res.end();
+                                    return;
+                                }
+                                let bytes = 0;
+                                const decoder = new TextDecoder();
+                                const settlementExtractor = new SellerSettlementStreamExtractor();
+                                while (true) {
+                                    const { done, value } = await reader.read();
+                                    lease.refresh();
+                                    if (done) {
+                                        break;
+                                    }
+                                    bytes += value.byteLength;
+                                    const chunk = decoder.decode(value, { stream: true });
+                                    // 透明代理：把 seller 的 SSE 字节原样转给客户端，只剥离我们注入的
+                                    // tokenbuddy.settlement 事件（不让客户端看到内部记账字段）。除此之外
+                                    // 不做任何协议转换——卖方格式 bug（如 chat.completion.chunk prefix、
+                                    // 缺 event: 行）由卖方修，buyer 不兜底。
+                                    const sellerChunk = settlementExtractor.push(chunk);
+                                    if (sellerChunk.length > 0) {
+                                        markFirstByte();
+                                        res.write(sellerChunk);
+                                    }
+                                }
+                                // flush TextDecoder 内部 buffer：stream:true 模式下最后可能留有几个字节的
+                                // 不完整 UTF-8 序列（多字节字符被切到下一 chunk 的场景），不调 stream:false
+                                // flush 就 break 会丢这批字节。上面的 stream 末尾事件（done / completed）
+                                // 之前被吞掉就是这个原因。
+                                const decoderTail = decoder.decode();
+                                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(sellerTail);
+                                    res.write(settlementTrailing.downstream);
                                 }
+                                res.end();
+                                this.recordReconciledInference(route, endpoint, requestId, { promptTokens: 0, completionTokens: 0, billedMicros: Math.max(1, bytes) }, this.parseSellerSettlementSummary(upstreamResponse.headers) ?? settlementTrailing.settlement ?? settlementExtractor.current(), 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 settlementTrailing = settlementExtractor.finish();
-                            if (settlementTrailing.downstream.length > 0) {
-                                markFirstByte();
-                                res.write(settlementTrailing.downstream);
-                            }
-                            res.end();
-                            this.recordReconciledInference(route, endpoint, requestId, { promptTokens: 0, completionTokens: 0, billedMicros: Math.max(1, bytes) }, this.parseSellerSettlementSummary(upstreamResponse.headers) ?? settlementTrailing.settlement ?? settlementExtractor.current(), this.inferPromptForHash(body), undefined, {
+                            const responseBody = await upstreamResponse.text();
+                            lease.refresh();
+                            markFirstByte();
+                            res.send(responseBody);
+                            const usage = this.readUsage(responseBody);
+                            this.recordReconciledInference(route, endpoint, requestId, usage, this.parseSellerSettlementSummary(upstreamResponse.headers), this.inferPromptForHash(body), responseBody, {
                                 ttftMs: firstByteAt ? firstByteAt - startedAt : undefined,
                                 fallbackCount: routeIndex,
                                 routeReason: plan.reason,
@@ -2050,62 +2254,51 @@ export class TokenbuddyDaemon {
                             });
                             return;
                         }
-                        const responseBody = await upstreamResponse.text();
-                        markFirstByte();
-                        res.send(responseBody);
-                        const usage = this.readUsage(responseBody);
-                        this.recordReconciledInference(route, endpoint, requestId, usage, this.parseSellerSettlementSummary(upstreamResponse.headers), this.inferPromptForHash(body), 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) {
-                        lastError = routeError;
-                        const kind = "deadline";
-                        const decision = this.routeFailover.decide({
-                            sellerId: sellerKey,
-                            errorKind: kind,
-                            errorMessage: this.failoverErrorMessage(routeError),
-                            attempt
-                        }, routes.length - routeIndex);
-                        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,
-                            model: modelId,
-                            endpoint,
-                            errorMessage: this.failoverErrorMessage(routeError),
-                            durationMs: Date.now() - startedAt
-                        });
-                        if (decision.action === "retry_same_seller") {
-                            attempt += 1;
-                            if (decision.retryDelayMs) {
-                                await new Promise((resolve) => setTimeout(resolve, decision.retryDelayMs));
+                        catch (routeError) {
+                            lastError = routeError;
+                            const kind = "deadline";
+                            const decision = this.routeFailover.decide({
+                                sellerId: sellerKey,
+                                errorKind: kind,
+                                errorMessage: this.failoverErrorMessage(routeError),
+                                attempt
+                            }, routes.length - routeIndex);
+                            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,
+                                model: modelId,
+                                endpoint,
+                                errorMessage: this.failoverErrorMessage(routeError),
+                                durationMs: Date.now() - startedAt
+                            });
+                            if (decision.action === "retry_same_seller") {
+                                attempt += 1;
+                                if (decision.retryDelayMs) {
+                                    await new Promise((resolve) => setTimeout(resolve, decision.retryDelayMs));
+                                }
+                                continue;
                             }
-                            continue;
-                        }
-                        if (decision.action === "fail_fast" || decision.action === "abort") {
-                            throw routeError;
+                            if (decision.action === "fail_fast" || decision.action === "abort") {
+                                throw routeError;
+                            }
+                            // failover_next
+                            break;
                         }
-                        // failover_next
-                        break;
                     }
                 }
+                finally {
+                    lease.release();
+                }
             }
             throw lastError instanceof Error ? lastError : new Error("all seller routes failed");
         }
@@ -2225,6 +2418,52 @@ export class TokenbuddyDaemon {
                 });
             }
         });
+        controlApp.get("/update/status", async (_req, res) => {
+            try {
+                const update = await checkPackageUpdate();
+                logger.info("control.update.status.requested", "package update status requested", {
+                    currentVersion: update.currentVersion,
+                    latestVersion: update.latestVersion,
+                    updateAvailable: update.updateAvailable
+                });
+                res.status(200).json(update);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                logger.warn("control.update.status.failed", "package update status failed", { errorMessage });
+                res.status(502).json({
+                    error: {
+                        code: "update_status_failed",
+                        message: errorMessage
+                    }
+                });
+            }
+        });
+        controlApp.post("/update/run", async (_req, res) => {
+            try {
+                const result = await runPackageUpdate({ apply: true, controlPort: this.activeControlPort() }, {
+                    restartProxyd: async () => scheduleLaunchAgentRestart()
+                });
+                logger.info("control.update.run.completed", "package update run completed", {
+                    currentVersion: result.check.currentVersion,
+                    latestVersion: result.check.latestVersion,
+                    updateAvailable: result.check.updateAvailable,
+                    installSucceeded: result.install.succeeded,
+                    restartScheduled: result.restart.scheduled === true
+                });
+                res.status(result.install.error || result.restart.error ? 500 : 200).json(result);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                logger.warn("control.update.run.failed", "package update run failed", { errorMessage });
+                res.status(500).json({
+                    error: {
+                        code: "update_run_failed",
+                        message: errorMessage
+                    }
+                });
+            }
+        });
         controlApp.post("/payments/clawtip/activate", async (req, res) => {
             try {
                 const qr = await this.startClawtipActivationQr();
@@ -2645,7 +2884,7 @@ export class TokenbuddyDaemon {
             // 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) => {
+            controlApp.get(/^(?!\/(?:health|status|payments|sellers|models|ledger|routing|prewarm|v1\.2|daemon|providers|update|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 });
@@ -2984,6 +3223,37 @@ function catalogSnapshotFromRegistry(registry) {
         }))
     };
 }
+function normalizeTrustedRegistryCache(value) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const data = value;
+    if (data.schemaVersion !== 1 ||
+        typeof data.registryUrl !== "string" ||
+        typeof data.registrySha256 !== "string" ||
+        typeof data.cachedAt !== "string" ||
+        typeof data.registryJson !== "string" ||
+        !data.registry ||
+        typeof data.registry !== "object" ||
+        !Array.isArray(data.registry.sellers) ||
+        !data.trust ||
+        typeof data.trust !== "object" ||
+        typeof data.trust.registryUrl !== "string" ||
+        typeof data.trust.registrySha256 !== "string" ||
+        typeof data.trust.verified !== "boolean") {
+        return undefined;
+    }
+    return {
+        schemaVersion: 1,
+        registryUrl: data.registryUrl,
+        version: typeof data.version === "number" ? data.version : data.registry.version,
+        registrySha256: data.registrySha256,
+        cachedAt: data.cachedAt,
+        registryJson: data.registryJson,
+        registry: data.registry,
+        trust: data.trust
+    };
+}
 /**
  * 从 query string 构造 `BuyerSellerRoutingConfig` override（用于 GET /routing/preview）。
  * 接受 `mode` / `scorer` / `sellerId` / `sellerIds`（逗号分隔）。