@tokenbuddy/tokenbuddy 1.0.26 → 1.0.27

package/src/daemon.ts

@@ -7,7 +7,7 @@ import { AddressInfo } from "net";
 import { ErrorCode } from "@tokenbuddy/contracts";
 import { createModuleLogger } from "@tokenbuddy/logging";
 import { BuyerStore, type PaymentConfig } from "./buyer-store.js";
-import { fetchClawtipBootstrap } from "./clawtip-bootstrap.js";
+import { DEFAULT_CLAWTIP_BOOTSTRAP_URL, fetchClawtipBootstrap } from "./clawtip-bootstrap.js";
 import type { ClawtipBootstrapResponse } from "./clawtip-bootstrap.js";
 import {
   inspectOpenClawWalletConfig,
@@ -29,7 +29,7 @@ import {
 } from "./provider-install.js";
 import {
   discoverSellerBackedModels,
-  fetchSellerRegistry,
+  fetchSellerRegistryWithTrust,
   manifestModelIds,
   manifestPaymentMethods,
   manifestProtocols,
@@ -39,13 +39,16 @@ import {
   type RegistrySeller,
   type SellerManifest,
   type SellerRegistryDocument,
+  type SellerRegistryTrustMetadata,
 } 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, type FailureKind } from "./seller-pool.js";
 import { RouteFailover, type FailoverDecision, type RouteCandidate } from "./route-failover.js";
 import { PrewarmScheduler, type PrewarmReason, type SellerProber } from "./prewarm-scheduler.js";
+import { SellerConcurrencyLimiter, type SellerConcurrencyLimiterOptions } from "./seller-concurrency-limiter.js";
 import type { PoolEntry } from "./seller-pool.js";
 import { planSellerRouteSet } from "./seller-route-planner.js";
 import type { SellerRoutePlan } from "./seller-route-planner.js";
@@ -67,9 +70,15 @@ import {
   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";
@@ -135,6 +144,17 @@ interface InitDoctorCatalogSnapshot {
   errorMessage?: string;
 }
 
+interface TrustedRegistryCacheRecord {
+  schemaVersion: 1;
+  registryUrl: string;
+  version?: number;
+  registrySha256: string;
+  cachedAt: string;
+  registryJson: string;
+  registry: SellerRegistryDocument;
+  trust: SellerRegistryTrustMetadata;
+}
+
 function clientToolStatusFromProvider(provider: ProviderCandidate): ClientToolStatus {
   return {
     id: provider.id,
@@ -234,6 +254,8 @@ export interface DaemonConfig {
   warmupRefreshIntervalSecs?: number;
   /** 预热探测超时（毫秒） */
   warmupProbeTimeoutMs?: number;
+  /** buyer 端本地 seller 并发 lease 限制；默认关闭。 */
+  sellerConcurrency?: SellerConcurrencyLimiterOptions;
 }
 
 interface SellerRoute {
@@ -242,6 +264,9 @@ interface SellerRoute {
   protocol: string;
   modelId: string;
   paymentMethod: string;
+  planSource: SellerRoutePlan["source"];
+  planReason: string;
+  planSellerCount: number;
   poolEntry?: PoolEntry;
 }
 
@@ -547,6 +572,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.
   private readonly prewarmScheduler!: PrewarmScheduler;
+  private readonly sellerConcurrencyLimiter: SellerConcurrencyLimiter;
 
   constructor(config: DaemonConfig) {
     this.tokenStore = new BuyerStore({ dbPath: config.dbPath });
@@ -559,6 +585,7 @@ export class TokenbuddyDaemon {
       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
@@ -685,7 +712,7 @@ export class TokenbuddyDaemon {
   }
 
   private async startClawtipActivationQr(): Promise<ClawtipQrResponse> {
-    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);
@@ -833,13 +860,15 @@ export class TokenbuddyDaemon {
 
   private async fetchRegistry(): Promise<SellerRegistryDocument> {
     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) {
       // v1.2 §18.9: if the bootstrap returns 413, fall back to the
@@ -859,10 +888,105 @@ 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;
     }
   }
 
+  private saveTrustedRegistryCache(fetched: { registry: SellerRegistryDocument; registryJson: string; trust: SellerRegistryTrustMetadata }): void {
+    const cache: TrustedRegistryCacheRecord = {
+      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
+    });
+  }
+
+  private loadTrustedRegistryCache(error: unknown): SellerRegistryDocument | undefined {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const record = this.tokenStore.getDaemonRuntimeConfig<unknown>(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;
+  }
+
   private runtimeSummary() {
     this.refreshSellerRoutingConfig();
     return {
@@ -877,6 +1001,7 @@ export class TokenbuddyDaemon {
       selectedSellerId: this.selectedSellerId,
       dbPath: this.config.dbPath,
       sellerRegistryUrl: this.config.sellerRegistryUrl,
+      sellerConcurrency: this.sellerConcurrencyLimiter.snapshot(),
       store: this.tokenStore.summary()
     };
   }
@@ -1193,7 +1318,7 @@ export class TokenbuddyDaemon {
     return payments.find((payment) => payment.isDefault)?.method || payments.find((payment) => payment.method === "mock")?.method;
   }
 
-  private async selectSellerRoutes(endpoint: string, modelId: string): Promise<{ routes: SellerRoute[]; plan: SellerRoutePlan; paymentMethod: string }> {
+  private async selectSellerRoutes(endpoint: string, modelId: string, requestId?: string): Promise<{ routes: SellerRoute[]; plan: SellerRoutePlan; paymentMethod: string }> {
     const protocol = this.endpointProtocol(endpoint);
     if (!protocol) {
       throw new Error(`unsupported proxy endpoint: ${endpoint}`);
@@ -1214,7 +1339,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,
@@ -1229,25 +1357,19 @@ 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: SellerRoute[] = 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,
@@ -1258,9 +1380,26 @@ 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: SellerRoute[] = 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 };
   }
 
@@ -1427,6 +1566,8 @@ export class TokenbuddyDaemon {
       reason?: string;
     }
   ): void {
+    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,
@@ -1435,8 +1576,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
@@ -1444,7 +1589,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,
@@ -1452,7 +1597,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,
@@ -1468,7 +1616,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
@@ -1533,12 +1684,31 @@ export class TokenbuddyDaemon {
     models: Array<{ id: string; sellerId: string; sellerName?: string; sellerUrl: string; supportedProtocols: string[]; paymentMethods: string[] }>;
     sellers: Array<{ id: string; name?: string; url: string; status: string; manifestSellerId?: string; errorMessage?: string }>;
   }> {
-    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
+      };
+    }
   }
 
   private readUsage(bodyText: string): UsageSummary {
@@ -2171,7 +2341,7 @@ export class TokenbuddyDaemon {
     }
 
     try {
-      const { routes, plan, paymentMethod } = await this.selectSellerRoutes(endpoint, modelId);
+      const { routes, plan, paymentMethod } = await this.selectSellerRoutes(endpoint, modelId, requestId);
       const upstreamStatusFromHeaders = (h: Headers): string | undefined => {
         const raw = h.get("x-tokenbuddy-upstream-status") || h.get("x-upstream-status");
         if (!raw) return undefined;
@@ -2182,24 +2352,57 @@ 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 {
+        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 {
             logger.info("proxy.request.started", "proxy request started", {
               requestId,
               sellerKey,
@@ -2239,7 +2442,7 @@ export class TokenbuddyDaemon {
             }
             // 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.
+            // seller; fail over immediately without marking old credit wasted.
             let token: string;
             try {
               token = await this.getOrPurchaseToken(route, requestId);
@@ -2254,7 +2457,7 @@ export class TokenbuddyDaemon {
               const decision = this.routeFailover.decide(
                 {
                   sellerId: sellerKey,
-                  errorKind: "deadline",
+                  errorKind: "purchase_failed",
                   errorMessage: this.failoverErrorMessage(purchaseError),
                   attempt
                 },
@@ -2268,7 +2471,10 @@ export class TokenbuddyDaemon {
                 routeIndex,
                 nextRouteIndex: routeIndex + 1,
                 routesRemaining: routes.length - routeIndex,
+                routesRemainingAfterCurrent: Math.max(0, routes.length - routeIndex - 1),
+                hasNextRoute: routeIndex + 1 < routes.length,
                 attempt,
+                attemptNumber: attempt + 1,
                 reason: "purchase_failed",
                 controllerReason: decision.reason,
                 controllerAction: decision.action
@@ -2304,12 +2510,15 @@ export class TokenbuddyDaemon {
             }
           };
           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,
@@ -2406,6 +2615,7 @@ export class TokenbuddyDaemon {
               const settlementExtractor = new SellerSettlementStreamExtractor();
               while (true) {
                 const { done, value } = await reader.read();
+                lease.refresh();
                 if (done) {
                   break;
                 }
@@ -2461,6 +2671,7 @@ export class TokenbuddyDaemon {
             }
 
             const responseBody = await upstreamResponse.text();
+            lease.refresh();
             markFirstByte();
             res.send(responseBody);
             const usage = this.readUsage(responseBody);
@@ -2526,6 +2737,9 @@ export class TokenbuddyDaemon {
             // failover_next
             break;
           }
+          }
+        } finally {
+          lease.release();
         }
       }
 
@@ -2651,6 +2865,55 @@ 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: unknown) {
+        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: unknown) {
+        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();
@@ -3077,7 +3340,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 });
@@ -3463,6 +3726,40 @@ function catalogSnapshotFromRegistry(registry: SellerRegistryDocument): InitDoct
   };
 }
 
+function normalizeTrustedRegistryCache(value: unknown): TrustedRegistryCacheRecord | undefined {
+  if (!value || typeof value !== "object") {
+    return undefined;
+  }
+  const data = value as Partial<TrustedRegistryCacheRecord>;
+  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`（逗号分隔）。