@antseed/cli 0.1.143 → 0.1.145

package/dist/proxy/buyer-proxy.js

@@ -1,16 +1,18 @@
 import { createServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
 import { watchFile, unwatchFile } from 'node:fs';
-import { readFile, writeFile, rename, mkdir } from 'node:fs/promises';
+import { readFile, writeFile, rename, mkdir, readdir, stat, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
-import { ANTSEED_ATTEST_PATH, computeOnChainReputationScore, decodeSweepRequest, } from '@antseed/node';
+import { ANTSEED_BUYER_FAULT_ERROR_CODE, ANTSEED_FAULT_ATTRIBUTION_HEADER, ANTSEED_ATTEST_PATH, computeOnChainReputationScore, decodeSweepRequest, faultAttributionOf, faultCodeOf, peerSupportsCooperativeClose, } from '@antseed/node';
 import { createStreamingAdapter, detectRequestServiceApiProtocol, transformRequest, transformResponse, } from './service-api-adapter.js';
-import { DEBUG, log, extractRequestedService, summarizeRequestShape, summarizeErrorResponse, requestWantsStreaming, parsePeerPinnedService, rewritePeerPinnedServiceInBody, substituteRoutedModelAlias, overrideRoutedModelInBody, ROUTED_MODEL_ALIAS, SYSTEM_PROXY_SOURCE_HEADER, SYSTEM_ROUTED_MODEL_HEADER, } from './request-utils.js';
-import { getExplicitProviderOverride, getExplicitPeerIdOverride, resolvePeerRoutePlan, selectCandidatePeersForRouting, } from './routing.js';
+import { DEBUG, log, extractRequestedService, summarizeRequestShape, summarizeErrorResponse, requestWantsStreaming, parsePeerPinnedService, rewritePeerPinnedServiceInBody, substituteRoutedModelAlias, overrideRoutedModelInBody, ROUTED_MODEL_ALIAS, SYSTEM_PROXY_SOURCE_HEADER, SYSTEM_ROUTED_MODEL_HEADER, normalizePeerId, } from './request-utils.js';
+import { findUnannouncedRequestParameters, getExplicitProviderOverride, getExplicitPeerIdOverride, resolvePeerRoutePlan, selectCandidatePeersForRouting, } from './routing.js';
 import { computeResponseTelemetry, attachAntseedTelemetryHeaders, attachStreamingAntseedHeaders, } from './telemetry.js';
 import { DEFAULT_BUYER_PEER_REFRESH_INTERVAL_MS } from '../config/defaults.js';
 import { extractConversationIdentity, extractFirstUserSnippet, isCompletionRequestPath, isTitleGenerationRequest, parseRequestBodyObject, } from './conversation-identity.js';
 import { ConversationStore } from './conversation-store.js';
+import { recordPeerFailureEntry, clearPeerHealthEntry, isCoolingDown, parsePersistedPeerHealth, prunePeerHealth, serializePeerHealth, reasonEscalates, } from './peer-health.js';
+import { PeerAttributionTracker, HEARTBEAT_MS } from './peer-attribution.js';
 import { estimateAnthropicPromptTokens, isCountTokensPath } from './count-tokens.js';
 import { getCachedVerdict, runVerifier, verifierSupportFingerprint } from '../plugins/verifier.js';
 // Re-export for backward compatibility (used by tests and other consumers)
@@ -50,7 +52,6 @@ export function isModelNotFoundResponse(response) {
  * liveness (`lastReachedAt`) even if the DHT record is older.
  */
 const CARRY_FORWARD_TTL_MS = 2 * 60 * 60_000;
-const PEER_FAILURE_WINDOW_MS = 5 * 60_000;
 /**
  * Requests kept in the spend-attribution map. Entries outlive their request on
  * purpose (a seller-initiated auth can land after the response), so this is
@@ -61,11 +62,42 @@ const MAX_TRACKED_REQUEST_CONVERSATIONS = 512;
 const MODEL_NOT_FOUND_REFRESH_THROTTLE_MS = 30_000;
 /** Verification is expensive; bound how many verdicts we retain (TTL = peer-cache TTL). */
 const VERIFY_CACHE_MAX_ENTRIES = 1024;
+/**
+ * Statuses that prove the peer is alive and serving. Any response short of a
+ * server error counts: a peer that answers 400 or 404 is reachable, and
+ * treating only 2xx as proof would leave a stale cooldown on a healthy peer
+ * that happens to reject every request.
+ */
+function isProofOfLife(statusCode) {
+    return statusCode < 500 && statusCode !== 408;
+}
+/**
+ * Map a seller's response status onto a health reason, or null when the status
+ * says nothing about the peer's liveness.
+ */
+function failureReasonForStatus(statusCode) {
+    if (statusCode === 408)
+        return 'seller-timeout';
+    // Rate limiting is capacity pressure, not death — recorded, never escalated.
+    if (statusCode === 429)
+        return 'seller-busy';
+    if (statusCode >= 500 && statusCode <= 599)
+        return 'seller-5xx';
+    return null;
+}
+function responseFaultAttribution(response) {
+    const attribution = response.headers[ANTSEED_FAULT_ATTRIBUTION_HEADER]?.toLowerCase();
+    return attribution === 'buyer' || attribution === 'peer' || attribution === 'unknown'
+        ? attribution
+        : 'peer';
+}
 function adaptOpenAICompatibleErrorResponse(response, requestProtocol) {
     if (response.statusCode !== 402) {
         return response;
     }
-    if (requestProtocol !== 'openai-responses' && requestProtocol !== 'openai-chat-completions') {
+    if (requestProtocol !== 'openai-responses'
+        && requestProtocol !== 'openai-chat-completions'
+        && requestProtocol !== 'openai-images') {
         return response;
     }
     let parsed = null;
@@ -97,6 +129,76 @@ function adaptOpenAICompatibleErrorResponse(response, requestProtocol) {
         body: Buffer.from(JSON.stringify(wrappedError)),
     };
 }
+function adaptBuyerFaultErrorResponse(response, requestProtocol) {
+    if (response.statusCode < 400
+        || response.headers[ANTSEED_FAULT_ATTRIBUTION_HEADER]?.toLowerCase() !== 'buyer') {
+        return sanitizePeerBuyerFaultMarker(response);
+    }
+    let parsed = {};
+    try {
+        parsed = JSON.parse(Buffer.from(response.body).toString('utf-8'));
+    }
+    catch {
+        // Buyer-generated failures should be JSON, but keep a useful fallback if
+        // a future path emits plain text.
+    }
+    const nestedError = parsed.error && typeof parsed.error === 'object' && !Array.isArray(parsed.error)
+        ? parsed.error
+        : null;
+    const reason = [nestedError?.code, parsed.code, parsed.reason, nestedError?.type, parsed.error]
+        .find((value) => typeof value === 'string' && value.trim().length > 0);
+    const message = [nestedError?.message, parsed.message, parsed.error]
+        .find((value) => typeof value === 'string' && value.trim().length > 0)
+        ?? 'The request failed on the buyer.';
+    const body = requestProtocol === 'anthropic-messages'
+        ? {
+            type: 'error',
+            error: {
+                type: ANTSEED_BUYER_FAULT_ERROR_CODE,
+                message: reason ? `${message} (${reason})` : message,
+            },
+        }
+        : {
+            error: {
+                type: 'api_error',
+                code: ANTSEED_BUYER_FAULT_ERROR_CODE,
+                message,
+                ...(reason ? { param: reason } : {}),
+            },
+        };
+    return {
+        ...response,
+        headers: { ...response.headers, 'content-type': 'application/json' },
+        body: Buffer.from(JSON.stringify(body)),
+    };
+}
+function sanitizePeerBuyerFaultMarker(response) {
+    if (response.statusCode < 400)
+        return response;
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(response.body).toString('utf-8'));
+    }
+    catch {
+        return response;
+    }
+    let changed = false;
+    const scrub = (record) => {
+        for (const key of ['code', 'type', 'errorCode']) {
+            if (record[key] === ANTSEED_BUYER_FAULT_ERROR_CODE) {
+                record[key] = 'upstream_error';
+                changed = true;
+            }
+        }
+    };
+    scrub(parsed);
+    if (parsed.error && typeof parsed.error === 'object' && !Array.isArray(parsed.error)) {
+        scrub(parsed.error);
+    }
+    return changed
+        ? { ...response, body: Buffer.from(JSON.stringify(parsed)) }
+        : response;
+}
 /**
  * Inject the buyer-known peerId into a 402 payment_required JSON body.
  * The seller doesn't include its own peerId (and shouldn't — self-reported
@@ -309,6 +411,82 @@ export function makeVerifierReach(node, peer, chosenId, signal) {
         return { statusCode: resp.statusCode, headers: resp.headers, body: resp.body };
     };
 }
+const STATE_TMP_PATTERN = /^\.buyer\.state\..+\.json\.tmp$/;
+const STATE_TMP_SWEEP_MIN_AGE_MS = 60_000;
+const STATE_RENAME_RETRY_DELAYS_MS = [25, 50, 100, 200];
+/**
+ * Rename with a short bounded retry. On Windows, renaming over a file a
+ * reader briefly holds open fails with EPERM/EACCES/EBUSY; those clear within
+ * milliseconds, so retrying recovers the write instead of dropping it.
+ */
+export async function renameWithRetry(from, to) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            await rename(from, to);
+            return;
+        }
+        catch (err) {
+            const code = err.code;
+            const retryable = code === 'EPERM' || code === 'EACCES' || code === 'EBUSY';
+            if (!retryable || attempt >= STATE_RENAME_RETRY_DELAYS_MS.length)
+                throw err;
+            await new Promise((resolve) => setTimeout(resolve, STATE_RENAME_RETRY_DELAYS_MS[attempt]));
+        }
+    }
+}
+/**
+ * Delete leftover `.buyer.state.<uuid>.json.tmp` files from state writes whose
+ * rename failed in an earlier run. The age floor protects a temp file another
+ * process (e.g. `antseed buyer connection set`) is writing right now.
+ */
+export async function sweepStaleStateTmpFiles(dir, minAgeMs = STATE_TMP_SWEEP_MIN_AGE_MS) {
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return;
+    }
+    const now = Date.now();
+    for (const name of names) {
+        if (!STATE_TMP_PATTERN.test(name))
+            continue;
+        const filePath = join(dir, name);
+        try {
+            const info = await stat(filePath);
+            if (now - info.mtimeMs >= minAgeMs)
+                await unlink(filePath);
+        }
+        catch {
+            // already gone or unreadable; nothing to clean
+        }
+    }
+}
+/**
+ * Atomic read-merge-write of a JSON state file via a sibling temp file. The
+ * temp file never survives: a failed rename unlinks it before rethrowing.
+ */
+export async function mergeJsonStateFile(stateDir, stateFile, patch) {
+    await mkdir(stateDir, { recursive: true });
+    let existing = {};
+    try {
+        const raw = await readFile(stateFile, 'utf-8');
+        existing = JSON.parse(raw);
+    }
+    catch {
+        // file doesn't exist yet
+    }
+    const data = { ...existing, ...patch };
+    const tmp = join(stateDir, `.buyer.state.${randomUUID()}.json.tmp`);
+    await writeFile(tmp, JSON.stringify(data, null, 2));
+    try {
+        await renameWithRetry(tmp, stateFile);
+    }
+    catch (err) {
+        await unlink(tmp).catch(() => { });
+        throw err;
+    }
+}
 export class BuyerProxy {
     _server;
     _node;
@@ -348,7 +526,16 @@ export class BuyerProxy {
     _consecutiveEmptyDiscoveries = 0;
     _lastModelNotFoundRefreshAtMs = 0;
     _bgRefreshHandle = null;
-    _peerFailures = new Map();
+    /**
+     * Per-peer failure streaks and cooldowns. Advisory only: a cooling-down peer
+     * is still dispatched to when a request names it, so routing can never
+     * deadlock and pinned conversations keep working.
+     */
+    _peerHealth = new Map();
+    /** Decides whether a failure is the peer's fault at all. */
+    _attribution = new PeerAttributionTracker();
+    _heartbeatHandle = null;
+    _now;
     /** Latest relayer receipt per sweep authNonce, for CLI progress polling. */
     _sweepReceipts = new Map();
     /**
@@ -370,6 +557,7 @@ export class BuyerProxy {
         this._stateFile = join(config.dataDir, 'buyer.state.json');
         this._conversations = new ConversationStore(config.dataDir);
         this._pinnedPeer = config.pinnedPeerId?.toLowerCase() ?? null;
+        this._now = config.now ?? (() => Date.now());
         this._server = createServer((req, res) => {
             this._handleRequest(req, res).catch((err) => {
                 log('Unhandled error:', err);
@@ -437,6 +625,10 @@ export class BuyerProxy {
     }
     async start() {
         this._startedAtMs = Date.now();
+        // Clean up temp files orphaned by state writes whose rename failed in a
+        // previous run — each carries a full discovered-peers snapshot, so left
+        // alone they accumulate into real disk usage.
+        await sweepStaleStateTmpFiles(this._stateDir);
         // Hydrate the in-memory peer cache from the persisted state file BEFORE
         // the server starts accepting requests. This lets the first request after
         // startup route from the warm cache without blocking on DHT discovery.
@@ -455,6 +647,7 @@ export class BuyerProxy {
             });
         });
         this._startBackgroundRefresh();
+        this._startSuspendHeartbeat();
         // Trigger initial discovery immediately so the desktop can show services
         // without waiting for the first request or 5-minute interval. The sweep
         // emits each accepted metadata document as it arrives, so buyer.state.json
@@ -467,6 +660,11 @@ export class BuyerProxy {
         try {
             const raw = await readFile(this._stateFile, 'utf-8');
             const parsed = JSON.parse(raw);
+            // Cooldowns survive a restart — a peer that died ten seconds before we
+            // exited is still dead — but the parser clamps anything expired or
+            // impossibly distant, so a restart can never extend one. Nothing new can
+            // escalate until a success re-establishes that the buyer is healthy.
+            this._peerHealth = parsePersistedPeerHealth(parsed, this._now());
             const peers = parsePersistedPeers(parsed);
             if (peers.length === 0) {
                 return;
@@ -499,6 +697,10 @@ export class BuyerProxy {
             clearInterval(this._bgRefreshHandle);
             this._bgRefreshHandle = null;
         }
+        if (this._heartbeatHandle) {
+            clearInterval(this._heartbeatHandle);
+            this._heartbeatHandle = null;
+        }
         await this._writeStateFile('stopped');
         await this._conversations.flush();
         return new Promise((resolve) => {
@@ -554,22 +756,13 @@ export class BuyerProxy {
     _mergeStateFile(patch) {
         this._stateWriteChain = this._stateWriteChain.then(async () => {
             try {
-                await mkdir(this._stateDir, { recursive: true });
-                let existing = {};
-                try {
-                    const raw = await readFile(this._stateFile, 'utf-8');
-                    existing = JSON.parse(raw);
-                }
-                catch {
-                    // file doesn't exist yet
-                }
-                const data = { ...existing, ...patch };
-                const tmp = join(this._stateDir, `.buyer.state.${randomUUID()}.json.tmp`);
-                await writeFile(tmp, JSON.stringify(data, null, 2));
-                await rename(tmp, this._stateFile);
+                await mergeJsonStateFile(this._stateDir, this._stateFile, patch);
             }
-            catch {
-                // non-fatal
+            catch (err) {
+                // Non-fatal for the proxy, but the write itself is lost — session
+                // pin, default route, and peer-cache updates in this patch were not
+                // persisted. Always audible: state writes are minutes apart.
+                console.error('[proxy] buyer.state.json write failed:', err instanceof Error ? err.message : String(err));
             }
         }).catch(() => { });
         return this._stateWriteChain;
@@ -707,36 +900,119 @@ export class BuyerProxy {
         });
     }
     /**
-     * Keep buyer-local failure diagnostics without changing reachability.
-     * The router and discovery cache remain untouched; this is only state the
-     * buyer can later use for logs or UI indication.
+     * Record a failed request against a peer.
+     *
+     * Recording is unconditional — the streak and reason are useful diagnostics
+     * either way — but only failures the attribution gates accept as the peer's
+     * own move the cooldown. Discovery metadata is never evicted: a cooling-down
+     * peer stays routable, it just stops being *chosen*.
      */
-    _recordPeerFailure(peerId, reason) {
-        const now = Date.now();
-        const existing = this._peerFailures.get(peerId);
-        const shouldStartFresh = !existing || now - existing.lastFailureAt > PEER_FAILURE_WINDOW_MS;
-        const entry = shouldStartFresh
-            ? { count: 1, firstFailureAt: now, lastFailureAt: now, lastReason: reason }
-            : {
-                count: existing.count + 1,
-                firstFailureAt: existing.firstFailureAt,
-                lastFailureAt: now,
-                lastReason: reason,
-            };
-        this._peerFailures.set(peerId, entry);
-        log(`Peer ${peerId.slice(0, 12)}... failure ${entry.count} within diagnostic window `
-            + `(reason=${reason}); retaining cached discovery metadata.`);
+    _recordPeerFailure(peerId, reason, fault = 'unknown') {
+        const now = this._now();
+        const { verdict, rollbackPeerIds } = this._attribution.classify({
+            peerId,
+            reasonEscalates: reasonEscalates(reason),
+            fault,
+            now,
+        });
+        const previous = this._peerHealth.get(peerId);
+        const entry = recordPeerFailureEntry(previous, reason, now, verdict.escalate);
+        this._peerHealth.set(peerId, entry);
+        if (rollbackPeerIds.length > 0) {
+            this._rollbackPeerHealth(rollbackPeerIds, 'buyer-side outage detected');
+        }
+        if (verdict.escalate && isCoolingDown(entry, now)) {
+            const seconds = Math.round((entry.cooldownUntil - now) / 1000);
+            log(`Peer ${peerId.slice(0, 12)}... cooling down for ${seconds}s after `
+                + `${entry.failureStreak} failures (reason=${reason}).`);
+        }
+        else {
+            const why = verdict.escalate ? 'below cooldown threshold' : verdict.suppressedBy;
+            log(`Peer ${peerId.slice(0, 12)}... failure recorded (reason=${reason}); `
+                + `not cooling down: ${why}.`);
+        }
+        void this._persistPeerHealthToState();
+    }
+    /**
+     * Fold a seller's HTTP response into that peer's health.
+     *
+     * Control-plane paths are exempt for the same reason `isRouterSuccess`
+     * exempts them: a failing `/v1/models` says nothing about the peer's ability
+     * to serve inference.
+     */
+    _recordPeerResponseHealth(peerId, statusCode, path) {
+        if (isControlPlaneServicesPath(path)) {
+            if (isProofOfLife(statusCode))
+                this._rememberSuccessfulPeer(peerId);
+            return;
+        }
+        const reason = failureReasonForStatus(statusCode);
+        if (reason && statusCode >= 500) {
+            const now = this._now();
+            if (isCoolingDown(this._peerHealth.get(peerId), now)) {
+                this._rememberSuccessfulPeer(peerId);
+            }
+            this._recordPeerFailure(peerId, reason, 'peer');
+            return;
+        }
+        if (isProofOfLife(statusCode)) {
+            // A 402, a 400, even a 429 — the peer answered, so it is alive and any
+            // cooldown is stale. Throttling still gets stamped as the last reason so
+            // "alive but refusing work" stays visible in diagnostics.
+            this._rememberSuccessfulPeer(peerId);
+            if (reason) {
+                const entry = this._peerHealth.get(peerId);
+                if (entry) {
+                    this._peerHealth.set(peerId, { ...entry, lastReason: reason, lastFailureAt: this._now() });
+                }
+            }
+            return;
+        }
+        if (reason)
+            this._recordPeerFailure(peerId, reason, 'peer');
+    }
+    /**
+     * Undo cooldowns that turned out to be our fault.
+     *
+     * When the attribution gates conclude the buyer itself was down — a suspend,
+     * a dropped network — the failures recorded during that window blamed the
+     * wrong party, so the streaks they created are wound back to zero.
+     */
+    _rollbackPeerHealth(peerIds, why) {
+        let changed = false;
+        for (const peerId of peerIds) {
+            const entry = this._peerHealth.get(peerId);
+            if (!entry || (entry.failureStreak === 0 && entry.cooldownUntil === 0))
+                continue;
+            this._peerHealth.set(peerId, {
+                ...entry,
+                failureStreak: 0,
+                windowStartedAt: 0,
+                episodeStartedAt: 0,
+                cooldownUntil: 0,
+            });
+            changed = true;
+        }
+        if (changed) {
+            log(`Cleared peer cooldowns for ${peerIds.length} peer(s): ${why}.`);
+            void this._persistPeerHealthToState();
+        }
     }
     /**
      * A peer told us it does not serve the requested model. Our cached
      * metadata for it is stale (the seller may have just unadvertised the
-     * model after failing its own health checks), so record the failure for
-     * diagnostics and refresh discovery metadata in the background — throttled,
-     * since one broken model can produce a burst of these.
+     * model after failing its own health checks), so refresh discovery
+     * metadata in the background — throttled, since one broken model can
+     * produce a burst of these.
+     *
+     * Deliberately does NOT touch peer health: the response itself is proof of
+     * life (`_recordPeerResponseHealth` treats any sub-500 answer as such), and
+     * a peer that is healthy for its other models must not cool down over one
+     * stale catalog entry. The router still learns via `onResult(success:false)`
+     * so scoring reflects the miss.
      */
     _onModelNotFound(peerId, requestedService) {
-        this._recordPeerFailure(peerId, `model-not-found:${requestedService ?? 'unknown'}`);
-        const now = Date.now();
+        const now = this._now();
         if (now - this._lastModelNotFoundRefreshAtMs < MODEL_NOT_FOUND_REFRESH_THROTTLE_MS) {
             return;
         }
@@ -748,17 +1024,56 @@ export class BuyerProxy {
     /**
      * 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. Also
-     * clears buyer-local diagnostic failures because the peer recovered.
+     * DHT record grows stale. Persisted so the signal survives restarts.
+     *
+     * A response is also proof that the buyer's own network, DHT, chain RPC and
+     * wallet are working, which is what lets other peers' failures be attributed
+     * to them rather than to us.
      */
     _rememberSuccessfulPeer(peerId) {
-        this._peerFailures.delete(peerId);
+        const now = this._now();
+        this._attribution.recordSuccess(peerId, now);
+        const previous = this._peerHealth.get(peerId);
+        if (previous && (previous.failureStreak > 0 || previous.cooldownUntil > 0)) {
+            log(`Peer ${peerId.slice(0, 12)}... recovered; cooldown cleared.`);
+        }
+        this._peerHealth.set(peerId, clearPeerHealthEntry(previous, now));
+        void this._persistPeerHealthToState();
         const cached = this._cachedPeers.find((p) => p.peerId === peerId);
         if (cached) {
-            cached.lastReachedAt = Date.now();
+            cached.lastReachedAt = now;
             this._persistPeersToState();
         }
     }
+    /**
+     * Watch for the wall clock jumping forward, which means the machine slept.
+     * On wake every pending timeout and keepalive fires at once, so without this
+     * a single closed lid would cool down every peer the buyer knows.
+     */
+    _startSuspendHeartbeat() {
+        if (this._heartbeatHandle)
+            return;
+        this._attribution.onHeartbeat(this._now());
+        this._heartbeatHandle = setInterval(() => {
+            const result = this._attribution.onHeartbeat(this._now());
+            if (result && result.rollbackPeerIds.length > 0) {
+                this._rollbackPeerHealth(result.rollbackPeerIds, 'machine resumed from sleep');
+            }
+            else if (result) {
+                log('Detected a wall-clock jump; suspending peer cooldowns briefly.');
+            }
+        }, HEARTBEAT_MS);
+        this._heartbeatHandle.unref?.();
+    }
+    /** Persist health separately from `discoveredPeers`, which is rebuilt wholesale. */
+    async _persistPeerHealthToState() {
+        const now = this._now();
+        this._peerHealth = prunePeerHealth(this._peerHealth, now);
+        await this._mergeStateFile({
+            peerHealth: serializePeerHealth(this._peerHealth),
+            peerHealthUpdatedAt: now,
+        });
+    }
     async _discoverPeersFromNetwork() {
         log('Discovering peers via DHT...');
         const peers = await this._node.discoverPeers();
@@ -894,6 +1209,69 @@ export class BuyerProxy {
             res.end(JSON.stringify({ ok: true, peers: payload }));
             return;
         }
+        if (path === '/_antseed/peer-health' && method === 'GET') {
+            const now = this._now();
+            const attribution = this._attribution.snapshot(now);
+            // `buyerHealthy` and `suppressedUntil` are what make "why is this peer
+            // (not) cooling down" answerable from outside the process.
+            const peers = [...this._peerHealth.entries()].map(([peerId, entry]) => ({
+                peerId,
+                failureStreak: entry.failureStreak,
+                lastFailureAt: entry.lastFailureAt,
+                lastReason: entry.lastReason,
+                cooldownUntil: entry.cooldownUntil,
+                coolingDown: isCoolingDown(entry, now),
+                cooldownMsRemaining: isCoolingDown(entry, now) ? entry.cooldownUntil - now : 0,
+                lastSuccessAt: entry.lastSuccessAt,
+            }));
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({
+                ok: true,
+                now,
+                buyerHealthy: this._attribution.isBuyerHealthy(now),
+                lastAnySuccessAt: attribution.lastAnySuccessAt,
+                suppressionActive: attribution.suppressedUntil > 0,
+                suppressedUntil: attribution.suppressedUntil,
+                lastSuppressedBy: attribution.lastSuppressedBy,
+                peers,
+            }));
+            return;
+        }
+        if (path === '/_antseed/peer-health/clear' && method === 'POST') {
+            const chunks = [];
+            let totalSize = 0;
+            for await (const chunk of req) {
+                totalSize += chunk.length;
+                if (totalSize > 8192) {
+                    res.writeHead(413, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: 'Request body too large' }));
+                    return;
+                }
+                chunks.push(chunk);
+            }
+            let peerId;
+            try {
+                const body = JSON.parse(Buffer.concat(chunks).toString());
+                peerId = typeof body.peerId === 'string' ? body.peerId.trim().toLowerCase() : '';
+            }
+            catch {
+                res.writeHead(400, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ ok: false, error: 'Invalid JSON body' }));
+                return;
+            }
+            const normalized = normalizePeerId(peerId) ?? peerId;
+            if (!/^[0-9a-f]{40}$/.test(normalized)) {
+                res.writeHead(400, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ ok: false, error: 'peerId must be a 40-character hex peer id' }));
+                return;
+            }
+            // Deliberately does not stamp a success: the user is asking us to give
+            // the peer another chance, not asserting that it answered.
+            this._rollbackPeerHealth([normalized], 'cleared by request');
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ ok: true, peerId: normalized }));
+            return;
+        }
         if (path === '/_antseed/route' && method === 'GET') {
             res.writeHead(200, { 'content-type': 'application/json' });
             res.end(JSON.stringify({ ok: true, model: this._defaultRoutedModel }));
@@ -984,8 +1362,11 @@ export class BuyerProxy {
                     res.end(JSON.stringify({ ok: false, error: 'pinnedModel must be "<peerId>@<service>" (or empty to clear)' }));
                     return;
                 }
-                conversation = this._conversations.setPinnedModel(id, pin.length > 0 ? pin : null);
-                log(`Conversation ${id.slice(0, 40)} pin: ${pin || 'cleared'}`);
+                // 'user' marks a seller the user chose for this specific chat — the
+                // desktop's re-point sweep skips those; everything else stays 'auto'.
+                const peerSource = parsed.peerSource === 'user' ? 'user' : 'auto';
+                conversation = this._conversations.setPinnedModel(id, pin.length > 0 ? pin : null, peerSource);
+                log(`Conversation ${id.slice(0, 40)} pin: ${pin || 'cleared'}${pin ? ` (${peerSource})` : ''}`);
             }
             if ('label' in parsed) {
                 const label = typeof parsed.label === 'string' ? parsed.label : null;
@@ -1048,8 +1429,17 @@ export class BuyerProxy {
             const channels = all
                 ? this._node.getAllBuyerChannels()
                 : this._node.getActiveBuyerChannels();
+            const peers = await this._getPeers();
+            const peersById = new Map(peers.map((peer) => [peer.peerId, peer]));
+            const channelsWithCapabilities = channels.map((channel) => {
+                const peer = peersById.get(channel.peerId);
+                return {
+                    ...channel,
+                    cooperativeCloseSupported: peer ? peerSupportsCooperativeClose(peer) : false,
+                };
+            });
             res.writeHead(200, { 'content-type': 'application/json' });
-            res.end(JSON.stringify({ ok: true, channels }));
+            res.end(JSON.stringify({ ok: true, channels: channelsWithCapabilities }));
             return;
         }
         if (path.startsWith('/_antseed/buyer-usage') && method === 'GET') {
@@ -1168,6 +1558,8 @@ export class BuyerProxy {
         const isKnownApiPath = normalizedPath.startsWith('/v1/messages') ||
             normalizedPath.startsWith('/v1/chat/completions') ||
             normalizedPath.startsWith('/v1/responses') ||
+            normalizedPath.startsWith('/v1/images/generations') ||
+            normalizedPath.startsWith('/v1/images/edits') ||
             normalizedPath.startsWith('/v1/models');
         if (!isKnownApiPath) {
             res.writeHead(404, { 'content-type': 'application/json' });
@@ -1589,6 +1981,15 @@ export class BuyerProxy {
         if (!selectedRoutePlan) {
             return { done: false, statusCode: 502, responseBody: Buffer.from('No compatible provider route'), responseHeaders: { 'content-type': 'text/plain' }, errorMessage: null };
         }
+        // Soft supportedParameters check — only for direct routes, since a
+        // protocol transform rebuilds the body for the target protocol anyway.
+        if (!selectedRoutePlan.selection?.requiresTransform) {
+            const unannounced = findUnannouncedRequestParameters(selectedPeer, selectedRoutePlan.provider, requestedService, requestProtocol, serializedReq);
+            if (unannounced.length > 0) {
+                log(`Warning: request to "${requestedService}" carries parameters peer ${selectedPeer.peerId.slice(0, 12)} `
+                    + `did not announce for this service: ${unannounced.join(', ')} — the upstream may ignore or reject them`);
+            }
+        }
         const { 'x-antseed-pin-peer': _pinPeer, 'x-antseed-prefer-peer': _preferPeer, ...headersForPeer } = serializedReq.headers;
         let requestForPeer = {
             ...serializedReq,
@@ -1690,8 +2091,10 @@ export class BuyerProxy {
                         }
                     },
                 }, { signal: requestSignal });
-                let responseForClient = response;
-                if (!streamed && adaptResponse) {
+                let responseForClient = adaptBuyerFaultErrorResponse(response, requestProtocol);
+                if (!streamed
+                    && adaptResponse
+                    && responseForClient.headers[ANTSEED_FAULT_ATTRIBUTION_HEADER]?.toLowerCase() !== 'buyer') {
                     responseForClient = adaptResponse(response);
                 }
                 responseForClient = adaptOpenAICompatibleErrorResponse(responseForClient, requestProtocol);
@@ -1706,13 +2109,14 @@ export class BuyerProxy {
                     log(`${prefix}: ${summarizeErrorResponse(responseForClient)}`);
                 }
                 const telemetry = computeResponseTelemetry(requestForPeer, responseForClient.headers, responseForClient.body, selectedPeer);
+                const responseFault = responseFaultAttribution(responseForClient);
                 const modelNotFound = !streamed
                     && !isControlPlaneServicesPath(requestForPeer.path)
                     && isModelNotFoundResponse(responseForClient);
                 if (modelNotFound) {
                     this._onModelNotFound(selectedPeer.peerId, requestedService);
                 }
-                if (router) {
+                if (router && responseFault !== 'buyer') {
                     router.onResult(selectedPeer, {
                         success: !modelNotFound
                             && isRouterSuccess(responseForClient.statusCode, requestForPeer.path, retryableStatusCodes),
@@ -1720,11 +2124,14 @@ export class BuyerProxy {
                         tokens: telemetry.usage.totalTokens,
                     });
                 }
+                if (responseFault === 'buyer') {
+                    this._recordPeerFailure(selectedPeer.peerId, 'buyer-local', 'buyer');
+                }
+                else {
+                    this._recordPeerResponseHealth(selectedPeer.peerId, responseForClient.statusCode, requestForPeer.path);
+                }
                 if (streamed) {
                     // Headers already sent to client, can't retry
-                    if (responseForClient.statusCode >= 200 && responseForClient.statusCode < 400) {
-                        this._rememberSuccessfulPeer(selectedPeer.peerId);
-                    }
                     if (!res.writableEnded) {
                         res.end();
                     }
@@ -1741,9 +2148,6 @@ export class BuyerProxy {
                         errorMessage: null,
                     };
                 }
-                if (responseForClient.statusCode >= 200 && responseForClient.statusCode < 400) {
-                    this._rememberSuccessfulPeer(selectedPeer.peerId);
-                }
                 res.writeHead(responseForClient.statusCode, responseHeaders);
                 res.end(Buffer.from(responseForClient.body));
                 return { done: true };
@@ -1753,8 +2157,9 @@ export class BuyerProxy {
                 if (upstreamResponse.statusCode >= 400 && !adaptResponse) {
                     log(`Upstream raw error detail: ${summarizeErrorResponse(upstreamResponse)}`);
                 }
-                let response = upstreamResponse;
-                if (adaptResponse) {
+                let response = adaptBuyerFaultErrorResponse(upstreamResponse, requestProtocol);
+                if (adaptResponse
+                    && response.headers[ANTSEED_FAULT_ATTRIBUTION_HEADER]?.toLowerCase() !== 'buyer') {
                     response = adaptResponse(response);
                 }
                 response = adaptOpenAICompatibleErrorResponse(response, requestProtocol);
@@ -1771,13 +2176,14 @@ export class BuyerProxy {
                 }
                 const telemetry = computeResponseTelemetry(requestForPeer, response.headers, response.body, selectedPeer);
                 const responseHeaders = attachAntseedTelemetryHeaders(response.headers, selectedPeer, telemetry, requestForPeer.requestId, latencyMs);
+                const responseFault = responseFaultAttribution(response);
                 const modelNotFound = !isControlPlaneServicesPath(requestForPeer.path)
                     && isModelNotFoundResponse(response);
                 if (modelNotFound) {
                     this._onModelNotFound(selectedPeer.peerId, requestedService);
                 }
                 // Report result to router for learning
-                if (router) {
+                if (router && responseFault !== 'buyer') {
                     router.onResult(selectedPeer, {
                         success: !modelNotFound
                             && isRouterSuccess(response.statusCode, requestForPeer.path, retryableStatusCodes),
@@ -1785,13 +2191,16 @@ export class BuyerProxy {
                         tokens: telemetry.usage.totalTokens,
                     });
                 }
+                if (responseFault === 'buyer') {
+                    this._recordPeerFailure(selectedPeer.peerId, 'buyer-local', 'buyer');
+                }
+                else {
+                    this._recordPeerResponseHealth(selectedPeer.peerId, response.statusCode, requestForPeer.path);
+                }
                 // Check if retryable
                 if (retryableStatusCodes.has(response.statusCode)) {
                     return { done: false, statusCode: response.statusCode, responseBody: Buffer.from(response.body), responseHeaders, errorMessage: null };
                 }
-                if (response.statusCode >= 200 && response.statusCode < 400) {
-                    this._rememberSuccessfulPeer(selectedPeer.peerId);
-                }
                 // Forward response headers and body to the HTTP client
                 res.writeHead(response.statusCode, responseHeaders);
                 res.end(Buffer.from(response.body));
@@ -1836,7 +2245,14 @@ export class BuyerProxy {
                 }
                 return { done: true };
             }
-            this._recordPeerFailure(selectedPeer.peerId, 'request-failed');
+            // Whose fault was this? Errors raised by our own wallet, deposits,
+            // transport or state machine say nothing about the peer, and telling the
+            // user to blame the seller for their empty deposit sends them chasing the
+            // wrong fix. Anything untagged stays 'unknown', where the attribution
+            // gates decide.
+            const fault = faultAttributionOf(err);
+            const faultCode = faultCodeOf(err);
+            this._recordPeerFailure(selectedPeer.peerId, fault === 'buyer' ? 'buyer-local' : 'request-failed', fault);
             if (res.headersSent) {
                 // Headers already sent (streaming), can't retry
                 if (!res.writableEnded) {
@@ -1844,6 +2260,30 @@ export class BuyerProxy {
                 }
                 return { done: true };
             }
+            if (fault === 'buyer') {
+                const buyerResponse = adaptBuyerFaultErrorResponse({
+                    requestId: requestForPeer.requestId,
+                    statusCode: 503,
+                    headers: {
+                        'content-type': 'application/json',
+                        [ANTSEED_FAULT_ATTRIBUTION_HEADER]: 'buyer',
+                    },
+                    body: Buffer.from(JSON.stringify({
+                        error: {
+                            type: 'buyer_request_failed',
+                            code: faultCode ?? 'buyer_request_failed',
+                            message,
+                        },
+                    })),
+                }, requestProtocol);
+                return {
+                    done: false,
+                    statusCode: buyerResponse.statusCode,
+                    responseBody: Buffer.from(buyerResponse.body),
+                    responseHeaders: buyerResponse.headers,
+                    errorMessage: message,
+                };
+            }
             return { done: false, statusCode: 502, responseBody: Buffer.from(`P2P request failed: ${message}`), responseHeaders: { 'content-type': 'text/plain' }, errorMessage: message };
         }
     }