@tokenbuddy/tokenbuddy 1.0.9 → 1.0.12

package/dist/src/seller-pool.js

@@ -0,0 +1,243 @@
+import { createModuleLogger } from "@tokenbuddy/logging";
+const logger = createModuleLogger("tb-proxyd:seller-pool");
+const DEFAULTS = {
+    failureThreshold: 3,
+    windowMs: 60_000,
+    windowFailureRate: 0.5,
+    openStateMs: 30_000
+};
+/**
+ * v2 SellerPool: combines `ModelIndex` (registry index), `PrewarmCache`
+ * (probe results), and `CreditTracker` (balance protection) into a single
+ * source of truth used by the route-failover controller. The pool is
+ * process-local and rebuilds its entry list from the cache whenever the
+ * cache mutates; entries not yet present in the cache are not in the pool.
+ */
+export class SellerPool {
+    modelIndex;
+    cache;
+    creditTracker;
+    failureThreshold;
+    windowMs;
+    windowFailureRate;
+    openStateMs;
+    now;
+    entries = new Map();
+    constructor(options) {
+        this.modelIndex = options.modelIndex;
+        this.cache = options.cache;
+        this.creditTracker = options.creditTracker;
+        this.failureThreshold = options.failureThreshold ?? DEFAULTS.failureThreshold;
+        this.windowMs = options.windowMs ?? DEFAULTS.windowMs;
+        this.windowFailureRate = options.windowFailureRate ?? DEFAULTS.windowFailureRate;
+        this.openStateMs = options.openStateMs ?? DEFAULTS.openStateMs;
+        this.now = options.now ?? Date.now;
+    }
+    /**
+     * Rebuild entries from the current prewarm cache. Called by
+     * `route-failover` whenever the cache is mutated (commit, invalidate,
+     * etc.) so the pool always reflects the latest probe results.
+     */
+    sync() {
+        const fresh = new Map();
+        for (const entry of this.cache.snapshot()) {
+            for (const candidate of entry.candidates) {
+                const registry = this.modelIndex.getSeller(candidate.sellerId);
+                if (!registry) {
+                    // Seller disappeared from the registry since the probe; skip.
+                    continue;
+                }
+                const previous = this.entries.get(candidate.sellerId);
+                fresh.set(candidate.sellerId, {
+                    sellerId: candidate.sellerId,
+                    url: candidate.url,
+                    registrySeller: registry,
+                    circuit: previous?.circuit ?? "closed",
+                    consecutiveFailures: previous?.consecutiveFailures ?? 0,
+                    recentFailures: previous?.recentFailures ?? [],
+                    lastSuccessAt: candidate.lastSuccessAt || previous?.lastSuccessAt || 0,
+                    lastFailAt: candidate.lastFailAt || previous?.lastFailAt || 0,
+                    lastProbeAt: entry.warmedAt,
+                    healthScore: candidate.healthScore,
+                    avgLatencyMs: candidate.avgLatencyMs
+                });
+            }
+        }
+        this.entries = fresh;
+        return this.entries.size;
+    }
+    /**
+     * Pick up to `limit` candidates for a (model, protocol, payment) triple.
+     * Sellers in the `open` circuit are skipped unless their open state has
+     * expired (they are flipped to `half_open` and included). Candidates are
+     * sorted by health score (descending) so the strongest seller goes first.
+     */
+    pick(options) {
+        const now = options.now ?? this.now();
+        const limit = options.limit ?? 4;
+        const freshness = this.cache.freshness(options.modelId, options.protocol, options.paymentMethod);
+        const resolved = this.modelIndex.resolve(options.modelId, {
+            protocol: options.protocol,
+            paymentMethod: options.paymentMethod
+        });
+        if (freshness.entry && freshness.entry.candidates.length === 0) {
+            return {
+                candidates: [],
+                reason: "prewarm_cache_empty",
+                resolved: asResolution(resolved)
+            };
+        }
+        const candidates = (freshness.entry?.candidates ?? [])
+            .map((candidate) => {
+            const entry = this.entries.get(candidate.sellerId);
+            if (!entry) {
+                return null;
+            }
+            return { entry, registrySeller: entry.registrySeller, candidate };
+        })
+            .filter((row) => row !== null)
+            .map((row) => {
+            const entry = this.maybeRecycleFromOpen(row.entry, now);
+            return { entry, registrySeller: row.registrySeller };
+        })
+            .filter((row) => row.entry.circuit !== "open")
+            .sort((a, b) => b.entry.healthScore - a.entry.healthScore)
+            .slice(0, limit);
+        return {
+            candidates,
+            reason: candidates.length > 0 ? "prewarm_cache" : "no_prewarm_candidates",
+            resolved: asResolution(resolved)
+        };
+    }
+    /**
+     * Record a successful inference against `sellerId`. The circuit closes
+     * (if it was half-open) and the credit tracker observes the latest
+     * balance via `recordSpend`.
+     */
+    recordSuccess(sellerId, balanceMicros, now = this.now()) {
+        const entry = this.entries.get(sellerId);
+        if (!entry) {
+            return undefined;
+        }
+        const next = {
+            ...entry,
+            circuit: "closed",
+            consecutiveFailures: 0,
+            recentFailures: [],
+            lastSuccessAt: now,
+            healthScore: Math.min(100, Math.max(entry.healthScore, 60))
+        };
+        this.entries.set(sellerId, next);
+        this.creditTracker.recordSpend(sellerId, balanceMicros);
+        logger.info("pool.success.recorded", "seller pool entry marked successful", {
+            sellerId,
+            balanceMicros,
+            healthScore: next.healthScore
+        });
+        return next;
+    }
+    /**
+     * Record a failure against `sellerId`. Returns the new PoolEntry. The
+     * caller (route-failover) uses the returned `entry.circuit` and the
+     * entry's `lastFailAt` to decide whether to fail over, retry, or stop.
+     * On a non-recoverable failure (`hard_4xx`, `auth_invalid`,
+     * `insufficient_funds`) the credit is also transferred to the wasted
+     * bucket so the wasted-micros counter stays accurate.
+     */
+    recordFailure(sellerId, kind, options = {}) {
+        const entry = this.entries.get(sellerId);
+        if (!entry) {
+            return undefined;
+        }
+        const now = options.now ?? this.now();
+        const recentFailures = [...entry.recentFailures, now].filter((ts) => ts >= now - this.windowMs);
+        const consecutiveFailures = entry.consecutiveFailures + 1;
+        const failureRate = recentFailures.length / Math.max(1, this.windowMs / 1000);
+        const overThreshold = consecutiveFailures >= this.failureThreshold;
+        const overRate = failureRate >= this.windowFailureRate;
+        const isHard = kind === "hard_4xx" || kind === "auth_invalid" || kind === "no_compatible";
+        const circuit = isHard || overThreshold || overRate ? "open" : entry.circuit;
+        const next = {
+            ...entry,
+            circuit,
+            consecutiveFailures,
+            recentFailures,
+            lastFailAt: now
+        };
+        this.entries.set(sellerId, next);
+        if (options.transferLeftover || isHard) {
+            this.creditTracker.transferLeftoverToWasted(sellerId, options.reason ?? kind);
+        }
+        if (circuit === "open") {
+            logger.warn("pool.circuit_opened", "seller pool entry transitioned to circuit_open", {
+                sellerId,
+                kind,
+                consecutiveFailures,
+                recentFailureRate: failureRate,
+                threshold: this.failureThreshold
+            });
+        }
+        return next;
+    }
+    /**
+     * Expose a per-seller credit / circuit snapshot to the route-failover.
+     * Used to decide whether a soft failure should retry on the same seller
+     * (刚买窗口保护) or fail over immediately.
+     */
+    inspect(sellerId) {
+        const entry = this.entries.get(sellerId);
+        const freshPurchase = this.creditTracker.isInFreshPurchaseWindow(sellerId, this.now());
+        const autoPurchaseAvailable = this.creditTracker.canAutoPurchase(this.now());
+        return { entry, freshPurchase, autoPurchaseAvailable };
+    }
+    /**
+     * Manually mark an entry as `open`. Used by the registry loop when a
+     * seller is removed from the registry: the entry lingers for a grace
+     * period but is unreachable, so opening the circuit prevents any
+     * further selection.
+     */
+    markOpen(sellerId, reason, now = this.now()) {
+        const entry = this.entries.get(sellerId);
+        if (!entry) {
+            return;
+        }
+        this.entries.set(sellerId, { ...entry, circuit: "open", lastFailAt: now });
+        logger.warn("pool.circuit_force_opened", "seller pool entry forced to circuit_open", {
+            sellerId,
+            reason
+        });
+    }
+    /**
+     * List all known pool entries. Used by `tb doctor` and tests.
+     */
+    snapshot() {
+        return Array.from(this.entries.values()).map((entry) => ({ ...entry, recentFailures: [...entry.recentFailures] }));
+    }
+    size() {
+        return this.entries.size;
+    }
+    maybeRecycleFromOpen(entry, now) {
+        if (entry.circuit !== "open") {
+            return entry;
+        }
+        if (now - entry.lastFailAt < this.openStateMs) {
+            return entry;
+        }
+        const recycled = { ...entry, circuit: "half_open" };
+        this.entries.set(entry.sellerId, recycled);
+        logger.info("pool.circuit_half_opened", "seller pool entry recycled to half_open", {
+            sellerId: entry.sellerId,
+            openStateMs: this.openStateMs
+        });
+        return recycled;
+    }
+}
+function asResolution(resolved) {
+    return {
+        modelId: resolved.modelId,
+        matched: resolved.matched,
+        candidates: resolved.sellers,
+        missingModelsFlag: resolved.missingModelsFlag
+    };
+}
+//# sourceMappingURL=seller-pool.js.map

package/dist/src/seller-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seller-pool.js","sourceRoot":"","sources":["../../src/seller-pool.ts"],"names":[],"mappings":"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"}

package/dist/src/stream-failover.d.ts

@@ -0,0 +1,78 @@
+/**
+ * v1.2 §6 / §18.10: stream-failover policy. The buyer honors the
+ * "abort + client retry" contract: once the first SSE byte has been
+ * written to the client, an upstream stream failure is surfaced as an
+ * abrupt close plus a `X-TokenBuddy-Retry-Hint: 1` trailer. The client
+ * (OpenAI / Anthropic SDK or any consumer honoring the OpenAI retry
+ * contract) re-issues the request and the buyer serves it from a
+ * healthy seller.
+ *
+ * The decisions in this module are intentionally one-way: the buyer
+ * never tries to splice two streams together (option B in the design
+ * doc) because that would double-charge and would require non-trivial
+ * idempotency re-design. v1.2 = abort + retry; v2 may revisit.
+ */
+export interface StreamFailoverOptions {
+    retryHintHeader?: string;
+    now?: () => number;
+}
+export interface StreamFailoverDecision {
+    action: "abort_with_retry_hint" | "let_stream_complete";
+    reason: string;
+    retryHintValue: string;
+    firstChunkCommitted: boolean;
+    bytesFlushed: number;
+}
+export declare class StreamFailover {
+    private readonly retryHintHeader;
+    private readonly now;
+    private firstChunkCommitted;
+    private bytesFlushed;
+    constructor(options?: StreamFailoverOptions);
+    /**
+     * Record that the buyer's response stream has written its first chunk
+     * to the client. From this point on, the route-failover controller
+     * cannot switch sellers without the client's knowledge; failures
+     * must abort the stream and rely on the client to retry.
+     */
+    markFirstChunkCommitted(): void;
+    /**
+     * Track total bytes written to the client. Used by `tb doctor` and
+     * the inference ledger to attribute partial-stream usage.
+     */
+    recordBytesWritten(bytes: number): void;
+    /**
+     * Decide what to do when the upstream stream breaks. If the first
+     * chunk has already been written, the only option is to abort and
+     * surface the retry hint. Otherwise the controller is free to fail
+     * over to the next seller.
+     */
+    decideOnStreamAbort(reason: string): StreamFailoverDecision;
+    /**
+     * Read-only snapshot of the current stream state. The route-failover
+     * controller calls this to decide whether the next chunk is the first
+     * one (failover still possible) or a follow-up (abort required).
+     */
+    snapshot(): {
+        firstChunkCommitted: boolean;
+        bytesFlushed: number;
+    };
+    /**
+     * Reset the failover state when a brand-new request starts. The
+     * `forwardProxyRequest` controller calls this before each new
+     * inference request.
+     */
+    reset(): void;
+    /**
+     * The HTTP header to set on the abort response so the client knows
+     * it should retry. Exposed so the controller and the test fixtures
+     * can refer to the same constant.
+     */
+    get headerName(): string;
+}
+/**
+ * Constant for the "retry hint value" used on stream-abort responses.
+ * Exposed so callers can refer to the same value in tests.
+ */
+export declare const STREAM_FAILOVER_RETRY_HINT = "1";
+//# sourceMappingURL=stream-failover.d.ts.map

package/dist/src/stream-failover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-failover.d.ts","sourceRoot":"","sources":["../../src/stream-failover.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,qBAAqB;IACpC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,uBAAuB,GAAG,qBAAqB,CAAC;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,YAAY,CAAK;gBAEb,OAAO,GAAE,qBAA0B;IAK/C;;;;;OAKG;IACH,uBAAuB,IAAI,IAAI;IAO/B;;;OAGG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIvC;;;;;OAKG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,sBAAsB;IAuB3D;;;;OAIG;IACH,QAAQ,IAAI;QAAE,mBAAmB,EAAE,OAAO,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE;IAOlE;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAKb;;;;OAIG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;CACF;AAED;;;GAGG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAC"}

package/dist/src/stream-failover.js

@@ -0,0 +1,93 @@
+import { createModuleLogger } from "@tokenbuddy/logging";
+const logger = createModuleLogger("tb-proxyd:stream-failover");
+export class StreamFailover {
+    retryHintHeader;
+    now;
+    firstChunkCommitted = false;
+    bytesFlushed = 0;
+    constructor(options = {}) {
+        this.retryHintHeader = options.retryHintHeader ?? "X-TokenBuddy-Retry-Hint";
+        this.now = options.now ?? Date.now;
+    }
+    /**
+     * Record that the buyer's response stream has written its first chunk
+     * to the client. From this point on, the route-failover controller
+     * cannot switch sellers without the client's knowledge; failures
+     * must abort the stream and rely on the client to retry.
+     */
+    markFirstChunkCommitted() {
+        if (this.firstChunkCommitted) {
+            return;
+        }
+        this.firstChunkCommitted = true;
+    }
+    /**
+     * Track total bytes written to the client. Used by `tb doctor` and
+     * the inference ledger to attribute partial-stream usage.
+     */
+    recordBytesWritten(bytes) {
+        this.bytesFlushed += bytes;
+    }
+    /**
+     * Decide what to do when the upstream stream breaks. If the first
+     * chunk has already been written, the only option is to abort and
+     * surface the retry hint. Otherwise the controller is free to fail
+     * over to the next seller.
+     */
+    decideOnStreamAbort(reason) {
+        if (!this.firstChunkCommitted) {
+            return {
+                action: "let_stream_complete",
+                reason: "no_chunks_yet_committed",
+                retryHintValue: "0",
+                firstChunkCommitted: false,
+                bytesFlushed: 0
+            };
+        }
+        logger.warn("stream.failover.aborted", "upstream stream broke after first chunk; aborting client with retry hint", {
+            reason,
+            bytesFlushed: this.bytesFlushed
+        });
+        return {
+            action: "abort_with_retry_hint",
+            reason,
+            retryHintValue: "1",
+            firstChunkCommitted: true,
+            bytesFlushed: this.bytesFlushed
+        };
+    }
+    /**
+     * Read-only snapshot of the current stream state. The route-failover
+     * controller calls this to decide whether the next chunk is the first
+     * one (failover still possible) or a follow-up (abort required).
+     */
+    snapshot() {
+        return {
+            firstChunkCommitted: this.firstChunkCommitted,
+            bytesFlushed: this.bytesFlushed
+        };
+    }
+    /**
+     * Reset the failover state when a brand-new request starts. The
+     * `forwardProxyRequest` controller calls this before each new
+     * inference request.
+     */
+    reset() {
+        this.firstChunkCommitted = false;
+        this.bytesFlushed = 0;
+    }
+    /**
+     * The HTTP header to set on the abort response so the client knows
+     * it should retry. Exposed so the controller and the test fixtures
+     * can refer to the same constant.
+     */
+    get headerName() {
+        return this.retryHintHeader;
+    }
+}
+/**
+ * Constant for the "retry hint value" used on stream-abort responses.
+ * Exposed so callers can refer to the same value in tests.
+ */
+export const STREAM_FAILOVER_RETRY_HINT = "1";
+//# sourceMappingURL=stream-failover.js.map

package/dist/src/stream-failover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-failover.js","sourceRoot":"","sources":["../../src/stream-failover.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,MAAM,GAAG,kBAAkB,CAAC,2BAA2B,CAAC,CAAC;AA6B/D,MAAM,OAAO,cAAc;IACR,eAAe,CAAS;IACxB,GAAG,CAAe;IAC3B,mBAAmB,GAAG,KAAK,CAAC;IAC5B,YAAY,GAAG,CAAC,CAAC;IAEzB,YAAY,UAAiC,EAAE;QAC7C,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,yBAAyB,CAAC;QAC5E,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACrC,CAAC;IAED;;;;;OAKG;IACH,uBAAuB;QACrB,IAAI,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAC7B,OAAO;QACT,CAAC;QACD,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAClC,CAAC;IAED;;;OAGG;IACH,kBAAkB,CAAC,KAAa;QAC9B,IAAI,CAAC,YAAY,IAAI,KAAK,CAAC;IAC7B,CAAC;IAED;;;;;OAKG;IACH,mBAAmB,CAAC,MAAc;QAChC,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAC9B,OAAO;gBACL,MAAM,EAAE,qBAAqB;gBAC7B,MAAM,EAAE,yBAAyB;gBACjC,cAAc,EAAE,GAAG;gBACnB,mBAAmB,EAAE,KAAK;gBAC1B,YAAY,EAAE,CAAC;aAChB,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,yBAAyB,EAAE,0EAA0E,EAAE;YACjH,MAAM;YACN,YAAY,EAAE,IAAI,CAAC,YAAY;SAChC,CAAC,CAAC;QACH,OAAO;YACL,MAAM,EAAE,uBAAuB;YAC/B,MAAM;YACN,cAAc,EAAE,GAAG;YACnB,mBAAmB,EAAE,IAAI;YACzB,YAAY,EAAE,IAAI,CAAC,YAAY;SAChC,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,QAAQ;QACN,OAAO;YACL,mBAAmB,EAAE,IAAI,CAAC,mBAAmB;YAC7C,YAAY,EAAE,IAAI,CAAC,YAAY;SAChC,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,IAAI,CAAC,mBAAmB,GAAG,KAAK,CAAC;QACjC,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;IACxB,CAAC;IAED;;;;OAIG;IACH,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,eAAe,CAAC;IAC9B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenbuddy/tokenbuddy",
-  "version": "1.0.9",
+  "version": "1.0.12",
   "description": "TokenBuddy Client CLI and Daemon",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",

package/src/buyer-store.ts

@@ -14,6 +14,13 @@ export interface CachedToken {
   reservedMicros: number;
   spentMicros: number;
   balanceSource?: string;
+  /**
+   * ISO-8601 expiry timestamp sourced from the seller's
+   * `/purchase/complete` response. v1.2 PR-fix: the buyer now
+   * checks this on every cached-token lookup so we never serve a
+   * stale access token to the upstream.
+   */
+  expiresAt?: string;
 }
 
 export interface PaymentConfig {
@@ -322,7 +329,7 @@ export class BuyerStore {
 
   public getToken(sellerKey: string): CachedToken | undefined {
     const stmt = this.db.prepare(
-      "SELECT token, balance_micros, reserved_micros, spent_micros, balance_source FROM token_cache WHERE seller_key = ?"
+      "SELECT token, balance_micros, reserved_micros, spent_micros, balance_source, expires_at FROM token_cache WHERE seller_key = ?"
     );
     const row = stmt.get(sellerKey) as {
       token: string;
@@ -330,6 +337,7 @@ export class BuyerStore {
       reserved_micros: number;
       spent_micros: number;
       balance_source: string | null;
+      expires_at: string | null;
     } | undefined;
     if (!row) {
       return undefined;
@@ -339,7 +347,8 @@ export class BuyerStore {
       balanceMicros: row.balance_micros,
       reservedMicros: row.reserved_micros,
       spentMicros: row.spent_micros,
-      balanceSource: row.balance_source || undefined
+      balanceSource: row.balance_source || undefined,
+      expiresAt: row.expires_at || undefined
     };
   }
 
@@ -768,4 +777,25 @@ export class BuyerStore {
     const row = this.db.prepare(`SELECT COUNT(*) AS count FROM ${tableName}`).get() as { count: number };
     return row.count;
   }
+
+  /**
+   * v1.2 §18.4: aggregate inference-ledger rows from the last `days`
+   * window and return the top `limit` most-used model ids. The focus-set
+   * builder uses this when no explicit warmup configuration is provided.
+   */
+  public recentModels(days: number, limit: number): string[] {
+    if (days <= 0 || limit <= 0) {
+      return [];
+    }
+    const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+    const rows = this.db.prepare(
+      `SELECT model_id, COUNT(*) AS uses
+         FROM inference_ledger
+        WHERE created_at >= ? AND model_id IS NOT NULL AND model_id != ''
+        GROUP BY model_id
+        ORDER BY uses DESC, model_id ASC
+        LIMIT ?`
+    ).all(cutoff, limit) as Array<{ model_id: string; uses: number }>;
+    return rows.map((row) => row.model_id);
+  }
 }

package/src/cli.ts

@@ -714,6 +714,9 @@ export function buildCli(): Command {
           providers,
           sellerRegistryUrl: daemonStatus?.sellerRegistryUrl,
         });
+        const v12Snapshot = daemonRunning
+          ? await fetchV12Snapshot(controlUrl)
+          : null;
         console.log(JSON.stringify({
           daemon: {
             running: daemonRunning,
@@ -733,6 +736,7 @@ export function buildCli(): Command {
             plistPath,
             plistExists: plistPath ? fs.existsSync(plistPath) : false
           },
+          v12: v12Snapshot,
           ...diagnostics,
         }, null, 2));
         return;
@@ -791,8 +795,65 @@ export function buildCli(): Command {
         sellerRegistryUrl: daemonStatus?.sellerRegistryUrl,
         providers,
       });
+
+      // v1.2 §18.11: append the prewarm cache / pool / credit summary
+      // block so users can see at a glance how much of their budget is
+      // being burned by failover and which sellers are in circuit_open.
+      if (daemonRunning) {
+        await renderDoctorV12Section(controlUrl);
+      }
     });
 
+  // v1.2 §18.11 helpers for `tb doctor` / `tb doctor --json`.
+  async function fetchV12Snapshot(controlUrl: string): Promise<unknown | null> {
+    try {
+      const res = await fetch(`${controlUrl}/v1.2/prewarm`);
+      if (!res.ok) {
+        return null;
+      }
+      return await res.json();
+    } catch {
+      return null;
+    }
+  }
+
+  async function renderDoctorV12Section(controlUrl: string): Promise<void> {
+    try {
+      const res = await fetch(`${controlUrl}/v1.2/prewarm`);
+      if (!res.ok) {
+        return;
+      }
+      const snapshot = (await res.json()) as {
+        prewarm: { entries: Array<{ modelId: string; state: string; candidateCount: number; warmedAt: number; ttlMs: number; consecutiveWarmingFailures: number }>; size: number };
+        pool: { size: number; entries: Array<{ sellerId: string; circuit: string; healthScore: number }> };
+        credit: { totalWastedMicros: number; wastedSinceLastDoctorRun: number; purchasesInLastMinute: number; purchaseBudgetPerMinute: number; perSeller: Array<{ sellerId: string; currentBalanceMicros: number; leftoverCreditMicros: number }> };
+        focusSet: string[];
+        scheduler: { inFlight: number; queueDepth: number; totalSucceeded: number; totalFailed: number };
+      };
+      console.log("");
+      console.log("=== v1.2 Fallback Pipeline ===");
+      console.log(`Focus Set: ${snapshot.focusSet.length === 0 ? "(empty; using lazy prewarms)" : snapshot.focusSet.join(", ")}`);
+      console.log(`Prewarm Cache: ${snapshot.prewarm.size} entries`);
+      for (const entry of snapshot.prewarm.entries.slice(0, 10)) {
+        console.log(`  - ${entry.modelId} [${entry.state}] ${entry.candidateCount} candidates, age ${Math.max(0, Date.now() - entry.warmedAt)}ms / ttl ${entry.ttlMs}ms`);
+      }
+      const open = snapshot.pool.entries.filter((e) => e.circuit !== "closed");
+      console.log(`Seller Pool: ${snapshot.pool.size} entries, ${open.length} non-closed`);
+      for (const entry of open.slice(0, 5)) {
+        console.log(`  - ${entry.sellerId} [${entry.circuit}] healthScore=${entry.healthScore}`);
+      }
+      console.log(`Credit: totalWasted=${snapshot.credit.totalWastedMicros}μ, sinceLastDoctor=${snapshot.credit.wastedSinceLastDoctorRun}μ, purchasesInLastMinute=${snapshot.credit.purchasesInLastMinute}/${snapshot.credit.purchaseBudgetPerMinute}`);
+      for (const seller of snapshot.credit.perSeller.slice(0, 5)) {
+        console.log(`  - ${seller.sellerId} balance=${seller.currentBalanceMicros}μ, leftover=${seller.leftoverCreditMicros}μ`);
+      }
+      console.log(`Scheduler: inFlight=${snapshot.scheduler.inFlight}, queueDepth=${snapshot.scheduler.queueDepth}, succeeded=${snapshot.scheduler.totalSucceeded}, failed=${snapshot.scheduler.totalFailed}`);
+    } catch (err) {
+      // Doctor must not fail because of an optional section.
+      const message = err instanceof Error ? err.message : String(err);
+      console.log(`\n(v1.2 snapshot unavailable: ${message})`);
+    }
+  }
+
   // 2. tb payment
   const payment = program.command("payment").description("Manage payment methods");