@antseed/cli 0.1.94 → 0.1.96

package/dist/proxy/buyer-proxy.js

@@ -4,15 +4,21 @@ import { watch } from 'node:fs';
 import { readFile, writeFile, rename, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { createOpenAIChatToAnthropicStreamingAdapter, createOpenAIChatToResponsesStreamingAdapter, createOpenAIResponsesToChatStreamingAdapter, detectRequestServiceApiProtocol, transformAnthropicMessagesRequestToOpenAIChat, transformOpenAIChatRequestToOpenAIResponses, transformOpenAIChatResponseToAnthropicMessage, transformOpenAIChatResponseToOpenAIResponses, transformOpenAIResponsesRequestToOpenAIChat, transformOpenAIResponsesResponseToOpenAIChat, } from './service-api-adapter.js';
-import { DEBUG, log, extractRequestedService, summarizeRequestShape, summarizeErrorResponse, requestWantsStreaming, rewriteServiceInBody, isConnectionChurnError, isConnectionHealthy, isLoopbackPeer, } from './request-utils.js';
-import { getExplicitProviderOverride, getExplicitPeerIdOverride, getPreferredPeerIdHint, resolvePeerRoutePlan, selectCandidatePeersForRouting, } from './routing.js';
+import { DEBUG, log, extractRequestedService, summarizeRequestShape, summarizeErrorResponse, requestWantsStreaming, rewriteServiceInBody, isConnectionChurnError, isConnectionHealthy, } from './request-utils.js';
+import { getExplicitProviderOverride, getExplicitPeerIdOverride, resolvePeerRoutePlan, selectCandidatePeersForRouting, } from './routing.js';
 import { computeResponseTelemetry, attachAntseedTelemetryHeaders, attachStreamingAntseedHeaders, } from './telemetry.js';
 // Re-export for backward compatibility (used by tests and other consumers)
 export { selectCandidatePeersForRouting } from './routing.js';
 export { rewriteServiceInBody } from './request-utils.js';
 const RETRYABLE_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504]);
-/** Max age for carrying forward peers not seen in the latest DHT scan. */
-const CARRY_FORWARD_TTL_MS = 30 * 60_000;
+/**
+ * Max age for carrying forward peers not seen in the latest DHT scan.
+ * Intentionally longer than `peer-lookup.ts` `maxAnnouncementAgeMs` (30 min) so
+ * a peer that misses one reannounce cycle doesn't hit both cliffs at once.
+ * For peers we have recently reached over the transport, we trust local
+ * liveness (`lastReachedAt`) even if the DHT record is older.
+ */
+const CARRY_FORWARD_TTL_MS = 2 * 60 * 60_000;
 function adaptOpenAICompatibleErrorResponse(response, requestProtocol) {
     if (response.statusCode !== 402) {
         return response;
@@ -125,13 +131,20 @@ export function parsePersistedPeers(parsed, nowMs = Date.now(), maxAgeMs = CARRY
         const lastSeen = typeof entry.lastSeen === 'number' && Number.isFinite(entry.lastSeen)
             ? entry.lastSeen
             : 0;
-        if (lastSeen <= 0 || nowMs - lastSeen >= maxAgeMs)
+        const lastReachedAt = typeof entry.lastReachedAt === 'number' && Number.isFinite(entry.lastReachedAt)
+            ? entry.lastReachedAt
+            : 0;
+        // Keep if either DHT observation or successful transport contact is within window.
+        const freshnessAnchor = Math.max(lastSeen, lastReachedAt);
+        if (freshnessAnchor <= 0 || nowMs - freshnessAnchor >= maxAgeMs)
             continue;
         const peer = {
             peerId: peerId,
             lastSeen,
             providers,
         };
+        if (lastReachedAt > 0)
+            peer.lastReachedAt = lastReachedAt;
         if (typeof entry.displayName === 'string')
             peer.displayName = entry.displayName;
         if (typeof entry.publicAddress === 'string')
@@ -154,6 +167,21 @@ export function parsePersistedPeers(parsed, nowMs = Date.now(), maxAgeMs = CARRY
         if (typeof entry.maxConcurrency === 'number') {
             peer.maxConcurrency = entry.maxConcurrency;
         }
+        if (typeof entry.onChainChannelCount === 'number' && Number.isFinite(entry.onChainChannelCount)) {
+            peer.onChainChannelCount = entry.onChainChannelCount;
+        }
+        if (typeof entry.onChainGhostCount === 'number' && Number.isFinite(entry.onChainGhostCount)) {
+            peer.onChainGhostCount = entry.onChainGhostCount;
+        }
+        if (typeof entry.onChainTotalVolumeUsdcMicros === 'number' && Number.isFinite(entry.onChainTotalVolumeUsdcMicros)) {
+            peer.onChainTotalVolumeUsdcMicros = entry.onChainTotalVolumeUsdcMicros;
+        }
+        if (typeof entry.onChainLastSettledAtSec === 'number' && Number.isFinite(entry.onChainLastSettledAtSec)) {
+            peer.onChainLastSettledAtSec = entry.onChainLastSettledAtSec;
+        }
+        if (typeof entry.onChainStatsFetchedAt === 'number' && Number.isFinite(entry.onChainStatsFetchedAt)) {
+            peer.onChainStatsFetchedAt = entry.onChainStatsFetchedAt;
+        }
         peers.push(peer);
     }
     return peers;
@@ -184,8 +212,6 @@ export class BuyerProxy {
     _peerRefreshPromise = null;
     _lastStaleCacheLogAtMs = 0;
     _bgRefreshHandle = null;
-    _lastSuccessfulPeerId = null;
-    _lastSuccessfulPeerByRouteKey = new Map();
     constructor(config) {
         this._node = config.node;
         this._port = config.port;
@@ -349,13 +375,28 @@ export class BuyerProxy {
     }
     _replacePeers(incoming) {
         const incomingById = new Map(incoming.map((p) => [p.peerId, p]));
+        const prevById = new Map(this._cachedPeers.map((p) => [p.peerId, p]));
         const now = Date.now();
-        // Carry forward previously known peers that are missing from this scan,
-        // preserving their lastSeen timestamp. A missed DHT scan doesn't mean
-        // the peer is unavailable — it just wasn't discovered this time.
-        const merged = [...incoming];
+        // For peers re-observed in this scan, preserve `lastReachedAt` from the
+        // previous cache entry — the DHT announcement doesn't carry that field,
+        // and losing it on each refresh would defeat the carry-forward tracking.
+        const merged = incoming.map((peer) => {
+            const prev = prevById.get(peer.peerId);
+            if (prev?.lastReachedAt && (!peer.lastReachedAt || prev.lastReachedAt > peer.lastReachedAt)) {
+                return { ...peer, lastReachedAt: prev.lastReachedAt };
+            }
+            return peer;
+        });
+        // Carry forward previously known peers that are missing from this scan.
+        // A missed DHT scan doesn't mean the peer is unavailable — it just wasn't
+        // discovered this time. Use the fresher of `lastSeen` and `lastReachedAt`
+        // as the liveness anchor: a recently-contacted peer survives even if its
+        // DHT record has aged out.
         for (const prev of this._cachedPeers) {
-            if (!incomingById.has(prev.peerId) && now - prev.lastSeen < CARRY_FORWARD_TTL_MS) {
+            if (incomingById.has(prev.peerId))
+                continue;
+            const freshnessAnchor = Math.max(prev.lastSeen, prev.lastReachedAt ?? 0);
+            if (freshnessAnchor > 0 && now - freshnessAnchor < CARRY_FORWARD_TTL_MS) {
                 merged.push({ ...prev });
             }
         }
@@ -389,10 +430,27 @@ export class BuyerProxy {
                 defaultInputUsdPerMillion: p.defaultInputUsdPerMillion ?? 0,
                 defaultOutputUsdPerMillion: p.defaultOutputUsdPerMillion ?? 0,
                 maxConcurrency: p.maxConcurrency ?? 0,
+                currentLoad: p.currentLoad ?? null,
+                // On-chain stats read authoritatively by the buyer from AntseedChannels.
+                // Persisted so `antseed network browse` can render richer UI without a
+                // fresh DHT + RPC round-trip.
+                onChainChannelCount: p.onChainChannelCount ?? null,
+                onChainGhostCount: p.onChainGhostCount ?? null,
+                onChainTotalVolumeUsdcMicros: p.onChainTotalVolumeUsdcMicros ?? null,
+                onChainLastSettledAtSec: p.onChainLastSettledAtSec ?? null,
+                onChainStatsFetchedAt: p.onChainStatsFetchedAt ?? null,
                 lastSeen: p.lastSeen,
+                lastReachedAt: p.lastReachedAt ?? null,
             };
         });
-        this._mergeStateFile({ discoveredPeers: peers, peersUpdatedAt: Date.now() });
+        const onChainRefreshedAt = this._cachedPeers
+            .map((p) => p.onChainStatsFetchedAt ?? 0)
+            .reduce((max, v) => (v > max ? v : max), 0);
+        this._mergeStateFile({
+            discoveredPeers: peers,
+            peersUpdatedAt: Date.now(),
+            ...(onChainRefreshedAt > 0 ? { onChainStatsRefreshedAt: onChainRefreshedAt } : {}),
+        });
     }
     _evictPeer(peerId) {
         const before = this._cachedPeers.length;
@@ -404,49 +462,18 @@ export class BuyerProxy {
             log(`Evicted failing peer ${peerId.slice(0, 12)}... from cache (${this._cachedPeers.length} remaining)`);
         }
     }
-    _rememberSuccessfulPeer(routeKey, peerId) {
-        this._lastSuccessfulPeerId = peerId;
-        this._lastSuccessfulPeerByRouteKey.set(routeKey, peerId);
-        // Keep map bounded to prevent unbounded growth from long-running channels.
-        const MAX_ROUTE_HISTORY = 200;
-        if (this._lastSuccessfulPeerByRouteKey.size > MAX_ROUTE_HISTORY) {
-            const oldestKey = this._lastSuccessfulPeerByRouteKey.keys().next().value;
-            if (typeof oldestKey === 'string') {
-                this._lastSuccessfulPeerByRouteKey.delete(oldestKey);
-            }
-        }
-    }
-    _forgetSuccessfulPeer(routeKey, peerId) {
-        const rememberedForRoute = this._lastSuccessfulPeerByRouteKey.get(routeKey);
-        if (rememberedForRoute === peerId) {
-            this._lastSuccessfulPeerByRouteKey.delete(routeKey);
-        }
-        if (this._lastSuccessfulPeerId === peerId) {
-            const stillUsedByOtherRoute = Array.from(this._lastSuccessfulPeerByRouteKey.values())
-                .some((rememberedPeerId) => rememberedPeerId === peerId);
-            if (!stillUsedByOtherRoute) {
-                this._lastSuccessfulPeerId = null;
-            }
+    /**
+     * Stamp `lastReachedAt` on a peer after a successful request so the
+     * carry-forward heuristic can trust local transport liveness even when the
+     * DHT record grows stale. Persisted so the signal survives restarts.
+     */
+    _rememberSuccessfulPeer(peerId) {
+        const cached = this._cachedPeers.find((p) => p.peerId === peerId);
+        if (cached) {
+            cached.lastReachedAt = Date.now();
+            this._persistPeersToState();
         }
     }
-    _buildRouteKey(path, requestProtocol, requestedService, explicitProvider) {
-        const normalizedPath = path.split('?')[0]?.trim().toLowerCase() ?? '/';
-        const pathGroup = (normalizedPath.startsWith('/v1/messages')
-            ? '/v1/messages'
-            : normalizedPath.startsWith('/v1/chat/completions')
-                ? '/v1/chat/completions'
-                : normalizedPath.startsWith('/v1/responses')
-                    ? '/v1/responses'
-                    : normalizedPath.startsWith('/v1/models')
-                        ? '/v1/models'
-                        : normalizedPath);
-        return [
-            pathGroup,
-            requestProtocol ?? 'unknown-protocol',
-            requestedService ?? 'unknown-service',
-            explicitProvider ?? 'auto-provider',
-        ].join('|');
-    }
     async _discoverPeersFromNetwork() {
         log('Discovering peers via DHT...');
         const peers = await this._node.discoverPeers();
@@ -700,6 +727,45 @@ export class BuyerProxy {
                 onClientAbort();
             }
         });
+        const requestProtocol = detectRequestServiceApiProtocol(serializedReq);
+        const requestedService = extractRequestedService(serializedReq);
+        log(`Routing: protocol=${requestProtocol ?? 'null'} service=${requestedService ?? 'null'}`);
+        const explicitProvider = getExplicitProviderOverride(serializedReq);
+        const explicitPeerId = getExplicitPeerIdOverride(serializedReq, effectivePinnedPeer ?? undefined);
+        log(`Routing hints: provider=${explicitProvider ?? 'auto'} pin-peer=${explicitPeerId ?? 'none'}`);
+        // Auto peer selection is disabled. Every request MUST target a specific
+        // peer, either via the per-request `x-antseed-pin-peer` header or via a
+        // session-wide pin set by `antseed buyer connection set --peer <peerId>`.
+        //
+        // Surface the error in the structured shape OpenAI/Anthropic SDKs expect
+        // (`{ error: { type, code, message, ... } }`) so callers see a proper
+        // .message on their error objects instead of a raw text/plain body. We
+        // use HTTP 400 — the request is missing required information the buyer
+        // cannot infer on its own — which is what SDK retry/error logic treats
+        // as a non-retryable client mistake.
+        if (!explicitPeerId) {
+            log('Request rejected: no peer pinned');
+            const errorMessage = 'No peer pinned. Auto-selection is disabled.\n'
+                + 'Pin a peer one of two ways:\n'
+                + '  • Per-request header:   x-antseed-pin-peer: <peerId>    (40-char hex EVM address)\n'
+                + '  • Session pin:          antseed buyer connection set --peer <peerId>\n'
+                + 'Discover peers with:       antseed network browse';
+            res.writeHead(400, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({
+                error: {
+                    type: 'no_peer_pinned',
+                    code: 'no_peer_pinned',
+                    message: errorMessage,
+                    param: 'x-antseed-pin-peer',
+                    help: {
+                        perRequestHeader: 'x-antseed-pin-peer: <peerId>',
+                        sessionPin: 'antseed buyer connection set --peer <peerId>',
+                        discoverPeers: 'antseed network browse',
+                    },
+                },
+            }));
+            return;
+        }
         // Discover peers
         const peers = await this._getPeers();
         if (peers.length === 0) {
@@ -708,15 +774,17 @@ export class BuyerProxy {
             res.end('No sellers available on the network. Is a seeder running?');
             return;
         }
-        const requestProtocol = detectRequestServiceApiProtocol(serializedReq);
-        const requestedService = extractRequestedService(serializedReq);
-        log(`Routing: protocol=${requestProtocol ?? 'null'} service=${requestedService ?? 'null'}`);
-        const explicitProvider = getExplicitProviderOverride(serializedReq);
-        const explicitPeerId = getExplicitPeerIdOverride(serializedReq, effectivePinnedPeer ?? undefined);
-        const preferredPeerId = getPreferredPeerIdHint(serializedReq);
-        log(`Routing hints: provider=${explicitProvider ?? 'auto'} pin-peer=${explicitPeerId ?? 'none'} prefer-peer=${preferredPeerId ?? 'none'}`);
-        const routeKey = this._buildRouteKey(serializedReq.path, requestProtocol, requestedService, explicitProvider);
-        const selectPeers = (candidateSources) => selectCandidatePeersForRouting(candidateSources, requestProtocol, requestedService, explicitProvider);
+        // Narrow the candidate set to just the pinned peer (if we already know
+        // about it) before running the per-peer protocol/service match. This
+        // avoids wasting work — and spamming "Service strict-miss" log lines —
+        // on every other discovered peer. If the pinned peer isn't in cache yet,
+        // fall through with the full list so the "not in candidate set → force
+        // refresh" path still works.
+        const narrowToPinned = (sources) => {
+            const match = sources.find((p) => p.peerId.toLowerCase() === explicitPeerId);
+            return match ? [match] : sources;
+        };
+        const selectPeers = (candidateSources) => selectCandidatePeersForRouting(narrowToPinned(candidateSources), requestProtocol, requestedService, explicitProvider);
         let hasForcedRefresh = false;
         const refreshPeerSelection = async (reason) => {
             if (hasForcedRefresh) {
@@ -746,150 +814,44 @@ export class BuyerProxy {
         }
         log(`Routing candidates: ${routingPeers.length} peer(s)`);
         const router = this._node.router;
-        if (explicitPeerId) {
-            // Pinned peers must use fresh discovery data so IP changes are picked up.
-            // Safe with the hasForcedRefresh guard: if an earlier refresh already ran
-            // this request, the cache is already fresh and cacheAgeMs will be < TTL.
-            const cacheAgeMs = Date.now() - this._cacheLastUpdatedAtMs;
-            if (cacheAgeMs > this._peerCacheTtlMs) {
-                await refreshPeerSelection(`pinned peer with stale cache (${cacheAgeMs}ms old)`);
-            }
-            let pinnedRoutingPeers = routingPeers;
-            let pinnedRoutePlans = routingPlans;
-            let selectedPeer = pinnedRoutingPeers.find((p) => p.peerId.toLowerCase() === explicitPeerId) ?? null;
-            if (!selectedPeer) {
-                await refreshPeerSelection(`pinned peer ${explicitPeerId.slice(0, 12)}... not in candidate set`);
-                pinnedRoutingPeers = routingPeers;
-                pinnedRoutePlans = routingPlans;
-                selectedPeer = pinnedRoutingPeers.find((p) => p.peerId.toLowerCase() === explicitPeerId) ?? null;
-            }
-            if (!selectedPeer) {
-                const source = serializedReq.headers['x-antseed-pin-peer'] ? 'x-antseed-pin-peer header' : '--peer flag';
-                const peerDiscovered = discoveredPeers.some((peer) => peer.peerId.toLowerCase() === explicitPeerId);
-                const protocolLabel = requestProtocol ? `protocol=${requestProtocol}` : 'protocol=unknown';
-                const providerLabel = explicitProvider ? `provider=${explicitProvider}` : 'provider=auto';
-                const serviceLabel = requestedService ? `service=${requestedService}` : 'service=none';
-                const mismatchHint = peerDiscovered
-                    ? `Peer is discoverable but filtered as incompatible (${protocolLabel}, ${providerLabel}, ${serviceLabel}).`
-                    : 'Peer is not discoverable right now.';
-                log(`Pinned peer ${explicitPeerId.slice(0, 12)}... not found in candidate list (${source})`);
-                res.writeHead(502, { 'content-type': 'text/plain' });
-                res.end(`Pinned peer ${explicitPeerId.slice(0, 12)}... is not available or does not support this request. ${mismatchHint}`);
-                return;
-            }
-            log(`Using pinned peer ${selectedPeer.peerId.slice(0, 12)}...`);
-            const result = await this._dispatchToPeer(res, serializedReq, selectedPeer, routeKey, pinnedRoutePlans, requestProtocol, requestedService, explicitProvider, router, RETRYABLE_STATUS_CODES, clientAbortController.signal);
-            if (!result.done) {
-                this._forgetSuccessfulPeer(routeKey, selectedPeer.peerId);
-                // Pinned peer returned a retryable error, but we don't retry — send error to client
-                res.writeHead(result.statusCode, result.responseHeaders);
-                res.end(result.responseBody);
-            }
-            return;
+        // Pinned-peer dispatch (the only path — auto-selection is disabled).
+        // Pinned peers must use fresh discovery data so IP changes are picked up.
+        // Safe with the hasForcedRefresh guard: if an earlier refresh already ran
+        // this request, the cache is already fresh and cacheAgeMs will be < TTL.
+        const cacheAgeMs = Date.now() - this._cacheLastUpdatedAtMs;
+        if (cacheAgeMs > this._peerCacheTtlMs) {
+            await refreshPeerSelection(`pinned peer with stale cache (${cacheAgeMs}ms old)`);
         }
-        // Non-pinned: retry with failover on provider errors
-        const MAX_ATTEMPTS = 3;
-        const triedPeerIds = new Set();
-        let lastStatusCode = 502;
-        let lastResponseBody = null;
-        let lastResponseHeaders = { 'content-type': 'text/plain' };
-        for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
-            const availableCandidates = routingPeers.filter((peer) => !triedPeerIds.has(peer.peerId));
-            if (availableCandidates.length === 0)
-                break;
-            let selectedPeer = null;
-            // Prefer a recently successful peer for the same request route.
-            if (attempt === 0) {
-                const routePreferredPeerId = this._lastSuccessfulPeerByRouteKey.get(routeKey);
-                if (routePreferredPeerId) {
-                    const remembered = availableCandidates.find((peer) => peer.peerId === routePreferredPeerId) ?? null;
-                    if (remembered) {
-                        selectedPeer = remembered;
-                        log(`Reusing last successful route peer ${selectedPeer.peerId.slice(0, 12)}...`);
-                    }
-                }
-            }
-            // Fallback to the latest globally successful peer.
-            if (!selectedPeer && attempt === 0 && this._lastSuccessfulPeerId && !requestedService) {
-                const remembered = availableCandidates.find((peer) => peer.peerId === this._lastSuccessfulPeerId) ?? null;
-                if (remembered) {
-                    selectedPeer = remembered;
-                    log(`Reusing last successful peer ${selectedPeer.peerId.slice(0, 12)}...`);
-                }
-            }
-            // Soft peer affinity: try caller-preferred peer first, but allow normal fallback.
-            if (!selectedPeer && attempt === 0 && preferredPeerId) {
-                const preferred = availableCandidates.find((peer) => peer.peerId.toLowerCase() === preferredPeerId) ?? null;
-                if (preferred) {
-                    selectedPeer = preferred;
-                    log(`Preferring requested peer ${selectedPeer.peerId.slice(0, 12)}...`);
-                }
-            }
-            // Prefer local peers on first attempt
-            if (!selectedPeer && attempt === 0) {
-                const localPeers = availableCandidates.filter((peer) => isLoopbackPeer(peer));
-                if (localPeers.length > 0) {
-                    selectedPeer = router
-                        ? router.selectPeer(serializedReq, localPeers)
-                        : localPeers[0] ?? null;
-                    if (selectedPeer) {
-                        log(`Preferring local peer ${selectedPeer.peerId.slice(0, 12)}... @ ${selectedPeer.publicAddress ?? 'unknown'}`);
-                    }
-                }
-            }
-            // Prefer peers that can serve the request protocol directly without adapter transform.
-            if (!selectedPeer && requestProtocol === 'anthropic-messages') {
-                const shouldPreferDirect = !requestedService || /claude|anthropic/i.test(requestedService);
-                if (shouldPreferDirect) {
-                    const directPeers = availableCandidates.filter((peer) => {
-                        const plan = routingPlans.get(peer.peerId);
-                        if (!plan)
-                            return false;
-                        return !plan.selection || !plan.selection.requiresTransform;
-                    });
-                    if (directPeers.length > 0) {
-                        selectedPeer = router
-                            ? router.selectPeer(serializedReq, directPeers)
-                            : directPeers[0] ?? null;
-                        if (selectedPeer) {
-                            log(`Preferring direct protocol peer ${selectedPeer.peerId.slice(0, 12)}...`);
-                        }
-                    }
-                }
-            }
-            if (!selectedPeer) {
-                selectedPeer = router
-                    ? (router.selectPeer(serializedReq, availableCandidates) ?? availableCandidates[0] ?? null)
-                    : availableCandidates[0] ?? null;
-            }
-            if (!selectedPeer)
-                break;
-            triedPeerIds.add(selectedPeer.peerId);
-            const result = await this._dispatchToPeer(res, serializedReq, selectedPeer, routeKey, routingPlans, requestProtocol, requestedService, explicitProvider, router, RETRYABLE_STATUS_CODES, clientAbortController.signal);
-            if (result.done)
-                return;
-            this._forgetSuccessfulPeer(routeKey, selectedPeer.peerId);
-            // Request failed with a retryable error — try another peer
-            lastStatusCode = result.statusCode;
-            lastResponseBody = result.responseBody;
-            lastResponseHeaders = result.responseHeaders;
-            if (attempt < MAX_ATTEMPTS - 1) {
-                log(`Peer ${selectedPeer.peerId.slice(0, 12)}... returned ${result.statusCode}, retrying with another peer (attempt ${attempt + 2}/${MAX_ATTEMPTS})`);
-            }
+        let pinnedRoutingPeers = routingPeers;
+        let pinnedRoutePlans = routingPlans;
+        let selectedPeer = pinnedRoutingPeers.find((p) => p.peerId.toLowerCase() === explicitPeerId) ?? null;
+        if (!selectedPeer) {
+            await refreshPeerSelection(`pinned peer ${explicitPeerId.slice(0, 12)}... not in candidate set`);
+            pinnedRoutingPeers = routingPeers;
+            pinnedRoutePlans = routingPlans;
+            selectedPeer = pinnedRoutingPeers.find((p) => p.peerId.toLowerCase() === explicitPeerId) ?? null;
         }
-        // All retries exhausted or no peers available
-        if (!res.headersSent) {
-            if (lastResponseBody) {
-                log(`All ${triedPeerIds.size} peer(s) failed, returning last error (${lastStatusCode})`);
-                res.writeHead(lastStatusCode, lastResponseHeaders);
-                res.end(lastResponseBody);
-            }
-            else {
-                const diagnostics = this._formatPeerSelectionDiagnostics(routingPeers);
-                log('No peers available for request');
-                res.writeHead(502, { 'content-type': 'text/plain' });
-                res.end(`Router could not select a suitable peer. ${diagnostics}`);
-            }
+        if (!selectedPeer) {
+            const source = serializedReq.headers['x-antseed-pin-peer'] ? 'x-antseed-pin-peer header' : '--peer flag or session pin';
+            const peerDiscovered = discoveredPeers.some((peer) => peer.peerId.toLowerCase() === explicitPeerId);
+            const protocolLabel = requestProtocol ? `protocol=${requestProtocol}` : 'protocol=unknown';
+            const providerLabel = explicitProvider ? `provider=${explicitProvider}` : 'provider=auto';
+            const serviceLabel = requestedService ? `service=${requestedService}` : 'service=none';
+            const mismatchHint = peerDiscovered
+                ? `Peer is discoverable but filtered as incompatible (${protocolLabel}, ${providerLabel}, ${serviceLabel}).`
+                : 'Peer is not discoverable right now.';
+            log(`Pinned peer ${explicitPeerId.slice(0, 12)}... not found in candidate list (${source})`);
+            res.writeHead(502, { 'content-type': 'text/plain' });
+            res.end(`Pinned peer ${explicitPeerId.slice(0, 12)}... is not available or does not support this request. ${mismatchHint}`);
+            return;
+        }
+        log(`Using pinned peer ${selectedPeer.peerId.slice(0, 12)}...`);
+        const result = await this._dispatchToPeer(res, serializedReq, selectedPeer, pinnedRoutePlans, requestProtocol, requestedService, explicitProvider, router, RETRYABLE_STATUS_CODES, clientAbortController.signal);
+        if (!result.done) {
+            // Pinned peer returned a retryable error. We never retry against another
+            // peer — auto-selection is disabled — so surface the error to the client.
+            res.writeHead(result.statusCode, result.responseHeaders);
+            res.end(result.responseBody);
         }
     }
     /**
@@ -897,7 +859,7 @@ export class BuyerProxy {
      * was sent to the client (success or non-retryable error), or retry info if the
      * caller should try another peer.
      */
-    async _dispatchToPeer(res, serializedReq, selectedPeer, routeKey, routePlanByPeerId, requestProtocol, requestedService, explicitProvider, router, retryableStatusCodes, requestSignal) {
+    async _dispatchToPeer(res, serializedReq, selectedPeer, routePlanByPeerId, requestProtocol, requestedService, explicitProvider, router, retryableStatusCodes, requestSignal) {
         const selectedRoutePlan = routePlanByPeerId.get(selectedPeer.peerId)
             ?? resolvePeerRoutePlan(selectedPeer, requestProtocol, requestedService, explicitProvider);
         if (!selectedRoutePlan) {
@@ -1013,7 +975,7 @@ export class BuyerProxy {
                 if (streamed) {
                     // Headers already sent to client, can't retry
                     if (responseForClient.statusCode >= 200 && responseForClient.statusCode < 400) {
-                        this._rememberSuccessfulPeer(routeKey, selectedPeer.peerId);
+                        this._rememberSuccessfulPeer(selectedPeer.peerId);
                     }
                     if (!res.writableEnded) {
                         res.end();
@@ -1032,7 +994,7 @@ export class BuyerProxy {
                     };
                 }
                 if (responseForClient.statusCode >= 200 && responseForClient.statusCode < 400) {
-                    this._rememberSuccessfulPeer(routeKey, selectedPeer.peerId);
+                    this._rememberSuccessfulPeer(selectedPeer.peerId);
                 }
                 res.writeHead(responseForClient.statusCode, responseHeaders);
                 res.end(Buffer.from(responseForClient.body));
@@ -1072,7 +1034,7 @@ export class BuyerProxy {
                     return { done: false, statusCode: response.statusCode, responseBody: Buffer.from(response.body), responseHeaders, errorMessage: null };
                 }
                 if (response.statusCode >= 200 && response.statusCode < 400) {
-                    this._rememberSuccessfulPeer(routeKey, selectedPeer.peerId);
+                    this._rememberSuccessfulPeer(selectedPeer.peerId);
                 }
                 // Forward response headers and body to the HTTP client
                 res.writeHead(response.statusCode, responseHeaders);
@@ -1147,7 +1109,6 @@ export class BuyerProxy {
                 // Evict only the failing peer — others remain usable.
                 this._evictPeer(selectedPeer.peerId);
             }
-            this._forgetSuccessfulPeer(routeKey, selectedPeer.peerId);
             if (res.headersSent) {
                 // Headers already sent (streaming), can't retry
                 if (!res.writableEnded) {