llm-relay 0.62.0 → 0.63.0

package/dist/server.js

@@ -57,9 +57,6 @@ const INTERNAL_REQUEST_HEADERS = new Set([
     CONTROL_AUTHORIZATION_HEADER,
 ]);
 const INBOUND_AUTH = ["authorization", "x-api-key"];
-// `MAX_TASK_LEN` lived here until the admin routes moved to `routes/admin.ts`, which owns the
-// `?task=` bound now. Two copies of a limit drift; the one at the boundary that accepts the
-// request is the one that counts.
 export const TOKENLESS_CONTROL_READ_PATHS = Object.freeze([
     "/v1/models",
     "/models",
@@ -77,22 +74,6 @@ const CONTROL_ROUTES = new Set([
     "/health",
     "/candidates",
 ]);
-/**
- * Request admission for mutating and command-rendering routes.
- *
- * Binding to loopback is NOT authorization. Any web page the user visits can
- * issue a cross-origin POST to 127.0.0.1, and because the handler JSON-parses
- * whatever body arrives regardless of declared content type, a `text/plain` POST
- * is a CORS *simple request* — no preflight, and it succeeds. The attacker never
- * reads the response, but every interesting operation here is a WRITE: flipping
- * offload routing, rewriting config.json on disk, marking dispatch lanes spent,
- * or spending provider keys.
- *
- * Returns null when the request may proceed, or a reason to reject with 403.
- * A CLI sends no Origin, so an ABSENT Origin is allowed; a present-but-unknown
- * one is not. Host is checked against the loopback names to close DNS rebinding,
- * where a hostile name resolves to 127.0.0.1 and thus looks local to the socket.
- */
 function admissionFailure(req, pathname, server, cfg, authorization) {
     const expected = listenerAuthority(server, cfg);
     if (!expected)
@@ -104,8 +85,6 @@ function admissionFailure(req, pathname, server, cfg, authorization) {
     if (rawHostValues.length !== 1 || !host || host.hostname !== expected.hostname || host.port !== expected.port) {
         return "Host authority does not match the bound listener";
     }
-    // Header presence is significant: Origin: null and Origin: "" are present-invalid,
-    // rather than falling into the trusted non-browser/CLI path.
     if (Object.hasOwn(req.headers, "origin")) {
         const origin = parseOrigin(req.headers.origin);
         if (!origin || origin.scheme !== "http:" || origin.hostname !== expected.hostname || origin.port !== expected.port) {
@@ -115,8 +94,6 @@ function admissionFailure(req, pathname, server, cfg, authorization) {
     const mutating = req.method !== "GET" && req.method !== "HEAD";
     if (mutating) {
         const ct = (req.headers["content-type"] ?? "").toString().split(";")[0]?.trim().toLowerCase();
-        // Requiring application/json is what makes a body-bearing cross-origin POST
-        // need a preflight, which a hostile page cannot satisfy.
         if (ct !== "application/json") {
             return `mutating requests require content-type: application/json (got ${ct || "none"})`;
         }
@@ -174,9 +151,7 @@ function listenerAuthority(server, cfg) {
     return { hostname: normalizeHostname(configuredHost), port: address.port };
 }
 const MAX_VALIDATE_BYTES = 8 * 1024 * 1024;
-/** 25 MiB decoded document × base64 expansion, plus JSON-envelope headroom. */
 export const DEFAULT_MAX_BODY_BYTES = 36 * 1024 * 1024;
-/** A bare programmatic proxy has no persistence owner, so dashboard reads fail closed as empty. */
 const UNAVAILABLE_ACCOUNTING_READER = Object.freeze({
     readDay: () => ({ status: "missing", value: null }),
     readDays: () => ({
@@ -196,55 +171,28 @@ export function createProxy(cfg, deps = {}) {
     const logger = new MetadataLogger(cfg.log);
     const isDestructive = destructiveMatcher(cfg.repair.destructiveTools);
     const catalog = deps.catalog ?? new ModelCatalog();
-    /**
-     * The lane cadence rides the ping tick (owner decision 2026-08-29): catalog re-probes keep
-     * rosters fresh, and quota probes re-test recorded lane deaths so no lane stays parked on a
-     * stale record. Skipped under vitest — the suite exercises `LaneCadence` directly with
-     * injected seams, and a test proxy must never spawn a real lane.
-     */
     const laneCadence = process.env.VITEST ? null : new LaneCadence(cfg);
     const pingLoop = deps.pingLoop ??
         new PingLoop(cfg, catalog, laneCadence ? { onTick: (now) => laneCadence.poke(now) } : {});
     const breaker = deps.breaker ?? new CircuitBreaker();
-    /**
-     * Cooling state survives a restart, like ping health already did.
-     *
-     * Without this the relay discarded every cooldown and the whole unexplained-429 escalation
-     * ladder on restart, then walked back into the same walls — measured here as a 19.9-hour
-     * cooldown learned from 7 consecutive 429s on one deployment and 26 on another.
-     *
-     * ⚠ Skipped under vitest for the reason the probe loop is: a test proxy must not read or write
-     * the developer's live cooling state. `getBreakerStatePath()` also redirects under vitest, so
-     * this is belt and braces — the suite exercises the mechanism directly with an explicit path.
-     */
     if (!process.env.VITEST)
         installBreakerPersistence(breaker);
-    // The ladder's exhaustion state survives a restart for the same reason — the report route
-    // accepts vendor-stated cooldowns up to 30 days, exactly the rows worth keeping.
     if (!process.env.VITEST)
         installDispatchExhaustionPersistence(cfg);
-    // Process-local and deliberately credential-wide: a deployment switch must not reset fairness.
     const credentialLru = new CredentialLru();
     const modelCallRecorder = deps.modelCallRecorder ?? (process.env.VITEST ? undefined : recordModelCall);
     const accountingRecorder = deps.accountingRecorder ?? NOOP_ACCOUNTING_RECORDER;
-    // One port per proxy: both request fronts price through the SAME published figures.
     const accountingPricePort = deps.accountingPricePortOverride ?? buildAccountingPricePort(catalog, cfg);
-    // Do not create a second persistence store here.  The CLI owns the production store lifecycle
-    // and supplies the same object as recorder and reader; a bare in-memory proxy reports no data.
     const dashboardAuth = new DashboardAuthManager();
     const dashboardAssetRoot = deps.dashboardAssetRoot ?? getProductionDashboardAssetRoot();
     const dashboardStatic = new DashboardStaticHandler({
         assetRoot: dashboardAssetRoot,
-        // Vite writes this only at build time. Source-driven runs therefore fail closed for assets
-        // rather than discovering or probing a development server on each request.
         manifestPath: join(dashboardAssetRoot, ".vite", "manifest.json"),
     });
     const dashboardRead = createDashboardSnapshotReadPort({
         accounting: deps.accountingReader ?? UNAVAILABLE_ACCOUNTING_READER,
         relayVersion: deps.dashboardRelayVersion ?? "unknown",
         attributionPolicy: deps.dashboardAttributionPolicy ?? "unknown",
-        // The Quota/Cooldown panels' producer. `usedInWindow` is store-only, so a bare in-memory
-        // proxy passes null and its quota rows simply carry localUsed null.
         availability: createAvailabilityProducer({
             breaker,
             config: cfg,
@@ -257,10 +205,6 @@ export function createProxy(cfg, deps = {}) {
     const stickySessions = stickyConfig === true || (typeof stickyConfig === "object" && stickyConfig.enabled)
         ? new StickySessionManager(typeof stickyConfig === "object" ? stickyConfig : undefined)
         : undefined;
-    // Gap 12: the deployment-level quota demotion term. Built once per proxy; each call re-reads
-    // live breaker state and the store's in-memory window. `deps.accountingReader` is narrowed the
-    // same way the dashboard producer above narrows it, so a bare programmatic proxy simply has no
-    // localUsed figure and the term stays inert.
     const quotaDemotion = createQuotaDemotionFn({
         cfg,
         breaker,
@@ -268,18 +212,6 @@ export function createProxy(cfg, deps = {}) {
             ? deps.accountingReader
             : null,
     });
-    // The cost class of a deployment, resolved LIVE from the catalog, for facts that apply to only
-    // one class. Built once per proxy like `quotaDemotion` above, and read fresh on every call so it
-    // tracks the catalog's own 10-minute refresh.
-    //
-    // ⚠ Why this exists: OpenRouter's `403 Key limit exceeded (weekly limit)` names the KEY, but it
-    // is a SPEND limit — its surface is the PAID subset. A credential-scoped demotion took out 18
-    // free models that were answering 200 (measured 2026-08-28). A `group` scope with a member list
-    // cannot fix it either, because a provider moves models between free, discounted and paid on its
-    // own schedule. Referencing the CLASSIFIER rather than a list is what cannot go stale.
-    //
-    // ⚠ Anthropic passthrough is definitionally not free — it spends primary quota — so it reports
-    // `paid` rather than a guess, exactly as the `targetCandidates` assessment above does.
     const costClassOf = (attempt) => {
         const t = attempt.target;
         if (t.kind !== "openai" || !t.model)
@@ -288,22 +220,9 @@ export function createProxy(cfg, deps = {}) {
             return assessCost(t.model, catalog.cachedLimits(t.provider, t.model), cfg.providers[t.provider]?.tierType).costClass;
         }
         catch {
-            // Unknown class ⇒ a cost-filtered fact simply does not apply. Never demote on a
-            // classification we could not make.
             return undefined;
         }
     };
-    // G2: the operator-set refusal ceilings. Narrowed to the SAME in-memory `usedInWindow` seam the
-    // demotion term reads — a bare programmatic proxy has no ledger and its caps simply never fire
-    // (unknown usage ⇒ no refusal). Built once per proxy; each call re-reads the live window.
-    //
-    // ⚠ The read is NARROWED BY THE CAP'S OWN SCOPE, which `evaluateHardCap` states per call: a
-    // `limits.models.<id>.hard` ceiling is compared against that deployment's usage, a flat
-    // credential/provider ceiling against the credential's usage across every model. Passing one
-    // fixed scope is how enforcement and `/candidates` drifted apart — they shared the evaluator
-    // but asked the ledger different questions, so a per-deployment cap refused `m/x` for requests
-    // spent entirely on `m/y`. All three consumers now narrow on exactly this rule (see
-    // `candidates.ts` and `availability-snapshot.ts`).
     const hardCapEvaluator = (attempt, now) => {
         try {
             const parsed = parseCredentialId(attempt.credentialId);
@@ -318,7 +237,6 @@ export function createProxy(cfg, deps = {}) {
             });
         }
         catch {
-            // A routing guard must not be able to fail a request; degrade to no opinion.
             return null;
         }
     };
@@ -331,14 +249,9 @@ export function createProxy(cfg, deps = {}) {
             controlAuthorization = createControlAuthorization(resolveControlAuthorizationConfigDir(cfg.sourcePath));
         }
         catch {
-            // Data-plane and tokenless status reads remain available. Protected control
-            // work fails closed through the absent port instead of preventing startup.
             controlAuthorization = undefined;
         }
     }
-    // Secret-bearing reshapers are request-local. Provider-backed forms are rehydrated from the
-    // provider config at the repair decision so current fleet slots and current env snapshots bind
-    // the egress. The implicit form instead keeps the exact credential that served the bad answer.
     const providerBackedReshaper = (targets, now) => new CredentialWalkReshaper(expandCredentialAttempts(targets), {
         lru: credentialLru,
         walkBudgetMs: cfg.walkBudgetMs ?? DEFAULT_WALK_BUDGET_MS,
@@ -380,8 +293,6 @@ export function createProxy(cfg, deps = {}) {
             return providerBackedReshaper(targets, now);
         }
         if (cfg.reshaper) {
-            // A legacy standalone endpoint owns only its declared authEnv. It has no provider identity,
-            // so never infer one from a coincidentally matching base/model and never attach a fleet.
             return new HttpReshaper(cfg.reshaper, resolveCredential(cfg.reshaper.authEnv));
         }
         const spec = reshaperForTarget(servedAttempt.target);
@@ -416,30 +327,11 @@ export function createProxy(cfg, deps = {}) {
             hardCap: hardCapEvaluator,
         }).catch((e) => {
             failClosed(res, 502, `llm-relay internal error: ${e.message}`);
-            // Last-resort net. `handle` logs every turn it terminates itself, so reaching
-            // here means a turn ended with NO log record — the operator would see a client
-            // error with nothing at all in the log to match it against. A duplicate line
-            // in some future edge case is much cheaper than an invisible request.
             logger.write(baseLog(started, req.url ?? "/", false, false, 502, "skipped", null));
         });
     });
-    /**
-     * Actually run the background health loop.
-     *
-     * ⚠ `PingLoop.start()` was called from NOWHERE in `src/`. The class has a complete adaptive
-     * cadence — speed/normal/slow modes, idle detection, `noteUserActivity()` — and every bit of it
-     * was dead code, so the only probes ever recorded were the ones a human triggered by hitting
-     * `/ping` by hand. That is the real reason a long-running relay reported `verdict: Pending` and
-     * an empty `p95` for every model it had supposedly been monitoring for days: nothing was
-     * monitoring anything. Persisting samples (probe-cache) and rehydrating them (cadence) are both
-     * pointless without this line.
-     *
-     * Skipped under vitest: a test proxy must not start probing real providers in the background.
-     */
     if (!process.env.VITEST) {
         server.on("listening", () => {
-            // Give the probe loop a concrete routing roster before its first tick. On a warm restart
-            // this is immediate from the catalog cache; a cold network refresh expands it later.
             materializeDynamicPools(cfg, catalog);
             pingLoop.start();
         });
@@ -456,12 +348,8 @@ function isCallerVisibleAccountingPath(method, pathname) {
         || pathname === "/v1/responses"
         || pathname === "/responses";
 }
-/** Records caller-visible terminals that occur before parsed-request accounting exists. */
 function recordEarlyTerminalAccounting(recorder, startedAt, client) {
     try {
-        // failureKind "unknown", not "protocol": the enum's only protocol kind means a
-        // PROVIDER answered with a malformed envelope, and this request never left the
-        // relay — nothing reached any provider to be protocol about.
         createAccountingRequest({ recorder, startedAt, client }).complete({
             outcome: "error",
             failureKind: "unknown",
@@ -470,7 +358,6 @@ function recordEarlyTerminalAccounting(recorder, startedAt, client) {
         });
     }
     catch {
-        // Accounting is observational and must never change caller traffic.
     }
 }
 function serveAccountingAttribution(attempt) {
@@ -512,16 +399,6 @@ function accountingTokens(usage, estimatedInputTokens, includeEstimatedOutput) {
             : {}),
     };
 }
-/**
- * Build the published-price lookup the accounting lifecycle prices spend through.
- *
- * Request-path safe by construction: `cachedLimits()` reads the in-memory catalog
- * cache and NEVER fetches (same contract as the context guardrail's lookup), and the
- * synced capability snapshot is memoized on its file mtime. A deployment that
- * publishes no price resolves to null and stays UNPRICED — never priced at a
- * fallback or a default. The reference rung uses the snapshot for the same model id,
- * labelled `reference`, exactly as `/candidates` already labels it.
- */
 function buildAccountingPricePort(catalog, cfg) {
     return (provider, model) => {
         const p = cfg.providers[provider];
@@ -532,9 +409,6 @@ function buildAccountingPricePort(catalog, cfg) {
         const matched = data
             ? findTierModel(model, data.byNorm, data.exactByNorm)
             : null;
-        // A FUZZY match borrows a different SKU's row (`glm-5.2` → `glm-5.2-max`). A
-        // borrowed score mis-ranks a pool; a borrowed PRICE would mis-state spend — so
-        // this path takes the stricter exact-only rule, like `contextWindowResolver`.
         const tier = matched?.match === "exact" ? matched.rec : undefined;
         const meta = resolveMetadata(model, {
             providerLimits,
@@ -555,11 +429,6 @@ function buildAccountingPricePort(catalog, cfg) {
         };
     };
 }
-/**
- * Request accounting is intentionally separate from health state: health owns
- * routing decisions, while this helper only observes actual egress and the
- * downstream response lifetime. Every method is fail-open for proxy traffic.
- */
 class RequestAccountingState {
     estimatedInputTokens;
     pricePort;
@@ -602,20 +471,6 @@ class RequestAccountingState {
             credentialId: attempt.credentialId,
         });
     }
-    /**
-     * CONTRACT: the returned handle MUST be completed exactly once, on every exit
-     * path (success, refusal, transport error, cancellation). Only `complete()`
-     * removes an entry from `active`, and `finalizeIfReady()` refuses to finish the
-     * request while `active` is non-empty — so a custom `Reshaper` that starts an
-     * attempt and drops the handle stalls this request's `request-completed` event
-     * until the store LRU-evicts it, and the day aggregate silently misses the turn.
-     *
-     * Deliberately NO eager sweep here: once the caller response is terminal, a
-     * still-active attempt is usually a REAL repair in flight being aborted by the
-     * disconnect, and its own `complete(cancelled/aborted)` lands a few ticks later.
-     * Sweeping at finalize time races that and would relabel honest cancellations as
-     * `error/unknown`; the in-tree reshapers all complete in `finally`.
-     */
     startRepair(options) {
         return this.start("repair", {
             startedAt: options.startedAt,
@@ -636,16 +491,12 @@ class RequestAccountingState {
             }
         }
         catch {
-            // Accounting must not perturb a successful response write.
         }
     }
     complete(attempt, outcome, failureKind, usage, endedAt = Date.now()) {
         if (attempt === null)
             return;
         try {
-            // The backend observer also sees a provisional prefix that stream-commit may
-            // withhold for failover. Only a committed serve attempt actually forwarded it;
-            // repair output is consumed internally and remains independently metered.
             attempt.complete({
                 outcome,
                 failureKind,
@@ -654,7 +505,6 @@ class RequestAccountingState {
             });
         }
         catch {
-            // The recorder and its packets are strictly observational.
         }
         this.active.delete(attempt);
         this.committed.delete(attempt);
@@ -685,20 +535,6 @@ class RequestAccountingState {
         if (this.finalized || this.request === null || this.responseTerminal === null)
             return;
         if (this.active.size > 0) {
-            // Two very different reasons for a still-active attempt:
-            //
-            // - On "close" (client disconnect mid-turn) a REAL repair is usually still in
-            //   flight, being aborted by that same disconnect; its own
-            //   complete("cancelled"/"aborted") lands within a few ticks. Returning here
-            //   lets that honest completion happen instead of relabelling it.
-            // - On "finish" the handler has fully written, so every in-tree reshaper has
-            //   long since completed its handle in `finally`. Anything still active is a
-            //   DROPPED handle from a custom Reshaper that ignored the startRepair
-            //   contract; sweeping it keeps the request from stalling unfinalized until
-            //   store eviction. Recorded as error/unknown — the one honest statement,
-            //   since nothing observed how the abandoned egress ended. A late real
-            //   completion is harmlessly ignored: complete() is idempotent and this
-            //   object is finalized immediately after.
             if (this.responseTerminal !== "finished")
                 return;
             for (const attempt of [...this.active]) {
@@ -726,7 +562,6 @@ class RequestAccountingState {
             }
         }
         catch {
-            // A malformed accounting packet must never affect the caller response.
         }
     }
 }
@@ -766,7 +601,6 @@ function dashboardHeaders(req) {
     }
     return headers;
 }
-/** Canonical dashboard origin synthesis, including the brackets required by IPv6 URLs. */
 export function dashboardExpectedOriginForAuthority(hostname, port) {
     const host = hostname.includes(":") ? `[${hostname}]` : hostname;
     return `http://${host}:${port}`;
@@ -777,14 +611,8 @@ function dashboardExpectedOrigin(server, cfg) {
         return null;
     return dashboardExpectedOriginForAuthority(authority.hostname, authority.port);
 }
-/**
- * Treat percent spellings of the dashboard namespace as dashboard requests even when malformed.
- * They are never canonicalized or served; this is only a fail-closed egress boundary.
- */
 function dashboardNamespaceTarget(path) {
     const rawPath = path.split("?", 1)[0] ?? "";
-    // Literal routes retain their deliberately narrow mount. Percent-bearing lookalikes take the
-    // stricter path below so an encoded separator/query/dot/backslash can never fall through.
     if (!rawPath.includes("%"))
         return rawPath === "/dashboard" || rawPath.startsWith("/dashboard/");
     const percentTolerant = rawPath.replace(/%([0-9a-fA-F]{2})/g, (_match, hex) => String.fromCharCode(Number.parseInt(hex, 16)));
@@ -800,8 +628,6 @@ function failDashboardClosed(res, status, message) {
 async function handleDashboardAdapter(req, res, path, started, cfg, h) {
     if (!dashboardNamespaceTarget(path))
         return false;
-    // Static handling is synchronous and intentionally receives the raw target: query strings and
-    // alternate spellings are not cache variants on this tokenless surface.
     const staticResponse = h.dashboardStatic.handle({ method: req.method ?? "GET", path });
     if (staticResponse.handled) {
         const staticHeaders = staticResponse.status === 404 || staticResponse.status === 405
@@ -825,22 +651,15 @@ async function handleDashboardAdapter(req, res, path, started, cfg, h) {
         admission: {
             hostAuthorized: true,
             expectedOrigin,
-            // Bootstrap is a dashboard-specific control operation. The generic admission above
-            // remains unchanged for every existing route; this only supplies the route contract.
             controlAuthorized: validateControlAuthorization(h.controlAuthorization, req.headers),
         },
         readBody: (maxBytes) => readBody(req, maxBytes),
     }, { auth: h.dashboardAuth, read: h.dashboardRead });
     if (response.handled) {
         writeDashboardResponse(res, response);
-        // One metadata record per dashboard answer, mirroring the admin-route convention:
-        // status + logSafePath(path) only. The session/bootstrap tokens travel as headers and
-        // body bytes, neither of which this record can carry (`served` is null, no attempts).
         h.logger.write(baseLog(started, path, false, false, response.status, "skipped", null));
         return true;
     }
-    // Do not let a dashboard lookalike reach proxy routing. This covers unknown API paths and
-    // every other /dashboard/* spelling while preserving all existing non-dashboard routes.
     failDashboardClosed(res, 404, "dashboard route not found");
     h.logger.write(baseLog(started, path, false, false, 404, "skipped", null));
     return true;
@@ -859,9 +678,6 @@ async function handle(req, res, cfg, h) {
         h.logger.write(baseLog(started, path, false, false, 403, "skipped", null));
         return;
     }
-    // The dashboard owns a deliberately tiny route namespace.  It must run before the generic
-    // proxy body reader: static GET/HEAD never buffer, and dashboard writes retain their 16 KiB
-    // cap rather than inheriting the data-plane's 36 MiB allowance.
     if (await handleDashboardAdapter(req, res, path, started, cfg, h))
         return;
     let reqBuf;
@@ -892,53 +708,22 @@ async function handle(req, res, cfg, h) {
     const handled = await handleAdminRoutes(req, res, pathname, path, started, reqJson, cfg, h);
     if (handled)
         return;
-    // ONE full-body token walk per request, shared with the context guardrail below.
-    // estimateRequestTokens walks the entire parsed body — potentially tens of MB — so
-    // computing it once per consumer paid that twice on every caller-visible request.
-    // ⚠ Reassigned below: a stripped `@relay:` directive shrinks the body, and the
-    // guardrail must judge the body that will actually reach the backend.
     let estimatedRequestTokens = estimateRequestTokens(reqJson);
-    // Only exact caller-visible inference routes create a request lifecycle.
-    // Admin/control aliases and prefix lookalikes remain outside accounting.
-    // (Deliberately constructed even under the NOOP recorder: the lifecycle also owns
-    // `isRequestClosed()`, which is how a running repair learns the client went away.)
     const accounting = isCallerVisibleAccountingPath(req.method, pathname)
         ? new RequestAccountingState(h.accountingRecorder, res, started, estimatedRequestTokens, requestClient, h.accountingPricePort)
         : null;
     const isCountTokens = req.method === "POST" && pathname === "/v1/messages/count_tokens";
     const isMessages = req.method === "POST" && pathname.startsWith("/v1/messages") && !isCountTokens;
-    // Real traffic is the signal the adaptive cadence was built around: probe briskly while the
-    // proxy is in use, drop to `slow` once it has been idle. `noteUserActivity()` had no callers
-    // either, so the loop could never have left its startup mode even if it had been running.
     h.pingLoop?.noteUserActivity();
-    // Route the request's model to a concrete provider + backend model candidates.
-    //
-    // ⚠ `subagentSpec` must run INSIDE this try. It throws `RoutingError` for an
-    // unresolvable `@relay:` directive, and while it sat outside, that throw escaped
-    // to `createProxy`'s top-level catch and surfaced as `502 llm-relay internal
-    // error: …` with NO log line — fail-closed and loud, but mislabelled as a proxy
-    // bug and invisible to the operator. A bad directive is a client routing error
-    // (400) like any other unresolvable spec.
     let targetCandidates;
-    // Hoisted out of the try: the served response has to say whether the answer came from below the
-    // requested effort band, and that is only knowable from the pool that was actually addressed.
     let degradedSpecs = null;
     let addressedPool = null;
     try {
-        // A SUBAGENT request may route somewhere other than its nominal model: either an explicit
-        // `@relay: <spec>` in the dispatcher's prompt (stripped here, so the model never sees it),
-        // Claude's cc_is_subagent marker, or Codex's request metadata header. Main-conversation
-        // requests remain untouched unless that front door's rule explicitly uses scope "all".
         const subSpec = subagentSpec(reqJson, model, cfg, req.headers, requestClient);
         const routedModel = subSpec ?? model;
         materializeDynamicPools(cfg, h.catalog);
-        // Re-serialize whenever a subagent spec applied — the @relay: line was stripped from reqJson
-        // in place, and it must not reach the backend even when the spec matches the nominal model.
         if (subSpec !== null) {
             reqBuf = Buffer.from(JSON.stringify(reqJson), "utf8");
-            // The body just shrank, so the shared token estimate is stale for anything downstream
-            // of this point — notably the context guardrail. Accounting already captured the
-            // pre-strip figure, which is correct there: that walk measured what the CLIENT sent.
             estimatedRequestTokens = estimateRequestTokens(reqJson);
         }
         targetCandidates = resolveTargets(routedModel, cfg);
@@ -947,18 +732,6 @@ async function handle(req, res, cfg, h) {
             const tail = cfg.routing.poolDegraded?.[addressedPool];
             degradedSpecs = tail && tail.length > 0 ? new Set(tail) : null;
         }
-        // The freeOnly guard: rerouted-by-offload traffic must not spend money. Enforced on the
-        // RESOLVED candidates, not the spec — a pool lists free and paid members side by side, and
-        // "the pool is mostly free" is exactly the assumption this exists to not rely on. Refusal is
-        // loud (a clean 503 naming the rule), never a fall-through: falling through to
-        // `routing.default` is the Anthropic passthrough, i.e. the very spend being guarded against.
-        // ⚠ The guard covers a DIRECTLY ADDRESSED pool too, not only offload-rerouted traffic.
-        // Gating it on `subSpec !== null` meant it never ran for the case it most needed to: a
-        // dispatch `cliLane` runs `claude -p --model pool/<name>`, whose requests are a MAIN
-        // conversation — no subagent marker, no `@relay:` directive — so the free-lane traffic this
-        // flag exists to bound walked straight past it. `pool/<name>` is by construction relay-routed
-        // free-lane traffic and never the vendor passthrough, and the guard can only ever refuse to
-        // spend, so extending it there cannot cost anyone an answer they were entitled to.
         const addressesPool = typeof routedModel === "string" && routedModel.startsWith("pool/");
         if ((subSpec !== null || addressesPool) && freeOnlyApplies(offloadRule(cfg, requestClient), subSpec !== null)) {
             const kept = [];
@@ -966,11 +739,7 @@ async function handle(req, res, cfg, h) {
             for (const t of targetCandidates) {
                 const assessment = t.kind === "openai" && t.model
                     ? assessCost(t.model, h.catalog.cachedLimits(t.provider, t.model), cfg.providers[t.provider]?.tierType)
-                    : null; // anthropic passthrough — primary quota, definitionally not free
-                // A deployment that STATED it is not free outranks a price table that says it is. The
-                // `provider-tier` basis is an assumption about a roster; a 403 naming a subscription is
-                // that deployment correcting us. (`isCostBlocked` excludes `allowance-exhausted` — a
-                // spent allowance is not a price, and must not be laundered into one here either.)
+                    : null;
                 if (assessment?.costClass === "free" && !isCostBlocked(t.provider, null, t.model, { costClass: assessment.costClass }))
                     kept.push(t);
                 else if (!blocked) {
@@ -1001,28 +770,9 @@ async function handle(req, res, cfg, h) {
         }
         throw e;
     }
-    // Demote unusable candidates — and do NOTHING else to the order.
-    //
-    // ⚠ Deliberately NOT `getHealthyTargets()`: that filters AND re-sorts by measured
-    // stability, which is a second ranking pass competing with the deployment-fitness ranking
-    // `resolveTargets` already applied. Two ranking passes
-    // means neither decides the order, and live health then PROMOTES on evidence that
-    // is often a single request's latency. Health is used here only to demote, never
-    // to promote: a target the breaker is cooling steps aside, everything else keeps
-    // its fitness order. (The re-sort was invisible for as long as an untracked target
-    // scored a flat 100 and `Array.prototype.sort` is stable — INV-TS-7.)
-    // The OpenAI front (Chat Completions / Responses) is detected BEFORE the context guardrail so
-    // the guardrail covers it: both fronts resolve concrete target deployments, and the estimator
-    // walks all three wire shapes. The front went without this pruning until 0.17.0 — the same
-    // "two paths, two policies, one of them empty" failure mode as the pool-failover incident.
     const openAiFrontProtocol = detectOpenAiFrontProtocol(req.method, pathname);
     const routingNow = Date.now();
-    // Resolve the credential once per configured candidate after all route-level pruning. The
-    // resulting attempt is immutable for this request: retries and both public fronts must not
-    // observe an environment change halfway through a provider attempt.
     const attempts = expandCredentialAttempts(targetCandidates);
-    // An explicit empty/disabled/model-scoped/missing fleet cannot make egress.  Keeping a
-    // synthetic first attempt here would accidentally turn a configuration error into a request.
     if (attempts.length === 0) {
         failClosed(res, 502, "llm-relay configuration: no enabled credential slot is available for the resolved target");
         h.logger.write(baseLog(started, path, hadTools, false, 502, "skipped", null));
@@ -1050,15 +800,7 @@ async function handle(req, res, cfg, h) {
             }
         }
     }
-    // Context guardrail — enforced ONLY against a limit the serving provider published about its own
-    // deployment. An unknown limit means no guardrail: the request goes upstream and the provider
-    // answers with its own (authoritative) error.
-    //
-    // Candidates whose published context limits are exceeded by the estimated prompt tokens are pruned.
-    // If all candidates are pruned, fail closed with 400 naming the context limit.
     if ((isMessages || openAiFrontProtocol) && reqJson) {
-        // The single walk computed above (re-run here ONLY if an `@relay:` directive was
-        // stripped, which shrinks the body this guardrail is judging).
         const estimatedTokens = estimatedRequestTokens;
         if (estimatedTokens > 0) {
             const remainingAttempts = [];
@@ -1096,9 +838,6 @@ async function handle(req, res, cfg, h) {
         evidenceFor: (attempt) => credentialEvidence(attempt, cfg, h.breaker, routingNow),
     });
     const credentialTrace = new CredentialAttemptTrace(cfg);
-    // OpenAI-compatible FRONT: route both Chat Completions and Responses requests through the
-    // resolved target. The adapter supports OpenAI-compatible and Anthropic backends, so Codex and
-    // OpenAI-native IDEs can use the same relay that Claude clients use in the other direction.
     if (openAiFrontProtocol) {
         await openAiFrontPath(res, credentialWalk, credentialTrace, {
             reqJson,
@@ -1118,11 +857,6 @@ async function handle(req, res, cfg, h) {
         }, h);
         return;
     }
-    // OpenAI-compatible backends expose ONLY /chat/completions — they have no
-    // count_tokens route and no other Anthropic paths. Rather than mistranslate
-    // those into a chat completion (yielding a spurious 400/garbage), answer
-    // count_tokens locally with a cheap estimate and reject other paths cleanly.
-    // For an Anthropic backend everything forwards as before (it speaks these).
     if (target.kind === "openai") {
         if (isCountTokens) {
             const input_tokens = Math.max(1, estimateRequestTokens(reqJson));
@@ -1137,14 +871,10 @@ async function handle(req, res, cfg, h) {
             return;
         }
     }
-    // Candidate execution loop: CredentialWalk owns breadth-first slot expansion,
-    // request-local suppression, and the wall-clock start budget.
     const attemptTrace = new RequestAttemptTrace();
     const pool429 = new Pool429Tracker();
     const tried = [];
     while (!res.destroyed) {
-        // G2's attempt boundary: an offer whose operator-set hard cap is reached is refused here,
-        // before any egress, and the loop comes straight back for the next candidate.
         const resolvedAttempt = nextUncappedAttempt(h, credentialWalk, attemptTrace, pool429);
         if (!resolvedAttempt)
             break;
@@ -1192,8 +922,6 @@ async function handle(req, res, cfg, h) {
                     reqJson,
                     anthropicHeaders: forwardHeaders,
                     wantsStream,
-                    // Reaches the dialect-rescue commit points: a tool call the relay reconstructs out of
-                    // model TEXT is refused when it names a destructive tool.
                     isDestructive: h.isDestructive,
                     usage,
                     signal: controller.signal,
@@ -1245,8 +973,6 @@ async function handle(req, res, cfg, h) {
                 const walkEnd = endWalk(h, res, "anthropic", credentialWalk, attemptTrace, pool429, status, sticky, credentialTrace, () => baseLog(started, path, hadTools, false, status, "skipped", target, attemptTrace.snapshot()), {
                     kind: "transport",
                     message: aborted ? "backend timed out" : `backend unreachable: ${e.message}`,
-                    // Preserved cross-front residue: this handle exit omits served-by while its OpenAI
-                    // twin includes it. Unifying it is now a one-line `servedBy` follow-up.
                 });
                 if (walkEnd)
                     continue;
@@ -1301,9 +1027,6 @@ async function handle(req, res, cfg, h) {
                     ? await probeStreamForCommit(backendRes.body, "anthropic-messages", {
                         isCancelled: () => res.destroyed,
                         malformedProvenance: target.kind === "openai" ? "local" : "upstream",
-                        // Declared, never inferred from the wire: only a stream the dialect wrapper actually
-                        // wrapped has a signal, so an upstream echoing the refusal code cannot mint `local`
-                        // provenance for itself and thereby dodge both failover and breaker accounting.
                         ...(dialectRefusalSignalOf(backendRes) ? { relayRefusal: dialectRefusalSignalOf(backendRes) } : {}),
                     })
                     : { kind: "dead", reason: "stream has no body", provenance: "upstream" };
@@ -1332,14 +1055,9 @@ async function handle(req, res, cfg, h) {
                         kind: "dead-stream",
                         message: `llm-relay: ${probe.reason}`,
                         errorType: probe.errorType,
-                        // Who produced this status. A dead PRE-COMMIT stream the relay judged `local` is the
-                        // proxy's own verdict, and saying so is the header's documented job — it was simply
-                        // never written on this path.
                         errorOrigin: probe.provenance,
                         servedBy: tried.join(", "),
                         shouldTryNext: probe.provenance === "upstream",
-                        // Preserved residue: handle gates dead streams on `!res.destroyed`; the OpenAI
-                        // front additionally requires `!res.writableEnded`.
                     });
                     if (walkEnd)
                         continue;
@@ -1405,10 +1123,6 @@ async function handle(req, res, cfg, h) {
                 if (repairResult !== null) {
                     recordCredentialOutcome(credentialWalk, credentialTrace, resolvedAttempt, { kind: "protocol" });
                     credentialRecorded = true;
-                    // Deliberate endWalk holdout: this records a dead turn, never records final, and its
-                    // continue branch never records failover because recordDeadTurn already counted the cell
-                    // and cleared only429. Converting it would need skipFinal/skipFailover flags — exactly the
-                    // silent-skip hazard endWalk exists to prevent.
                     pool429.recordDeadTurn();
                     const next = !res.destroyed ? nextUncappedAttempt(h, credentialWalk, attemptTrace, pool429) : undefined;
                     if (next)
@@ -1470,47 +1184,11 @@ async function handle(req, res, cfg, h) {
             res.off("close", onResClose);
         }
     }
-    // THE all-capped refusal site — the only one on this front, deliberately.
-    //
-    // `allCapped()` requires `!egressed`, and every failover arm above runs only after a candidate
-    // egressed, so a check inside one could never be true: the loop exit is the sole place the
-    // condition can hold. (Eight such inner checks existed and were dead code on the request path;
-    // the rule they LOOK like they enforce — a walk that mixes caps with real failures keeps its
-    // last upstream error — is enforced by `egressed`, and pinned by the mixed-walk tests.) A walk
-    // that exhausted for any other reason reaches here with nothing capped and must stay silent:
-    // its caller already replied.
     if (!res.headersSent && !res.destroyed && pool429.allCapped()) {
         respondAllCapped(res, h, { started, path, hadTools, streamed: wantsStream }, "anthropic", pool429, attemptTrace.snapshot());
     }
 }
-/**
- * Order candidates worst-last WITHOUT dropping any: live, then credential-faulted, then cooling.
- *
- * Three states, and the distinction between them is the whole point:
- *   - live               — breaker closed, no standing 401/403. Keeps its fitness order.
- *   - credential-faulted — answered 401/403 recently. It is not sick, it is unusable, and it
- *                          must not cost a round-trip per request ahead of a working member.
- *   - cooling            — breaker open (rate-limited or repeatedly failing).
- *
- * Demotion, not filtering. The previous `filter(isHealthy)` with a keep-everything fallback
- * removed cooling candidates outright whenever at least one was healthy, so a pool could be
- * narrowed to a single member and then have nothing to fall back to when that one failed too.
- * Ordering is strictly better: a demoted target is only ever reached after every better one has
- * actually failed on this request, and a pool with 14 members always has 14 chances.
- *
- * Stable within each band, so the already-computed deployment fitness still decides among equals.
- */
-/**
- * `"<spec> (below <band>)"` when this answer came from the pool's degrade tail, else null.
- *
- * The "loudly" half of automatic degradation. Falling back to a weaker live model is the right
- * behaviour — a band with nothing behind it turns "the strongest models are busy" into "no answer
- * at all" — but only because the caller is told. An unannounced downgrade is indistinguishable
- * from getting what you asked for.
- */
 function paidLabel(cfg, h, target) {
-    // Only openai-kind targets carry a price we can assess; the anthropic passthrough is the
-    // caller's own subscription and is reported by the absence of any pool at all.
     if (target.kind !== "openai" || !target.model)
         return null;
     const assessment = assessCost(target.model, h.catalog.cachedLimits(target.provider, target.model), cfg.providers[target.provider]?.tierType);
@@ -1524,12 +1202,9 @@ function degradedLabel(pool, degraded, target) {
     const spec = specOfTarget(target);
     return degraded.has(spec) ? `${spec} (below ${pool})` : null;
 }
-/** Is a learned allowance exhaustion still cooling this target? Never throws — no store, no cooling. */
 function cooledByAllowance(attempt, now, costClass) {
     try {
         const { target } = attempt;
-        // `exactOptionalPropertyTypes` is on: an explicit `undefined` is not the same as absent, and
-        // absent is what "the caller could not classify this" must look like to `factsFor`.
         const until = cooldownUntil(target.provider, attempt.credentialId, target.model ?? null, {
             now,
             ...(costClass === undefined ? {} : { costClass }),
@@ -1540,17 +1215,6 @@ function cooledByAllowance(attempt, now, costClass) {
         return false;
     }
 }
-/**
- * Gap 12: a SPENT quota demotes to the same cooling band as an outage (spec §5.4), because both
- * mean "this cell cannot serve right now, and it comes back on its own". A spent allowance is not
- * a sick backend, so the term never touches failure counters; registering the cooldown with
- * source "quota" exists purely so `/candidates`, the dashboard Cooldowns panel and
- * `llm-relay candidates` can SEE why the member stepped aside — and so a sticky pin or a degrade
- * tail check later in this same request reads the demotion too, without a second resolver pass.
- *
- * Learned limits gate only under `routing.quota.enforceLearned`; unknown quota yields null here
- * and has no effect whatsoever. Never throws, never drops, never refuses.
- */
 function cooledByQuota(attempt, breaker, quotaDemotion, now) {
     if (!quotaDemotion)
         return false;
@@ -1566,16 +1230,12 @@ function targetUsability(attempt, breaker, now, quotaDemotion, costClassOf) {
         return "cooling";
     if (cooledByAllowance(attempt, now, costClassOf?.(attempt)))
         return "cooling";
-    // A stated/declared quota at zero belongs in the SAME band as allowance-exhaustion above: both
-    // are temporary conditions on a deployment that is otherwise healthy, and ordering them ahead
-    // of live members is the whole point — the walk should spend its round-trips where capacity is.
     if (cooledByQuota(attempt, breaker, quotaDemotion, now))
         return "cooling";
     if (breaker.hasCredentialFault(identity, now))
         return "credential-fault";
     return "live";
 }
-/** Resolve every configured slot once, then retain deployment order while taking credential rounds. */
 function expandCredentialAttempts(targets) {
     const expanded = [];
     for (const target of targets) {
@@ -1600,7 +1260,7 @@ function credentialEvidence(attempt, cfg, breaker, now) {
     try {
         facts = factsFor(attempt.target.provider, attempt.credentialId, attempt.target.model ?? null, { now });
     }
-    catch { /* persistent evidence is best effort */ }
+    catch { }
     const cost = attempt.target.kind === "openai" && attempt.target.model
         ? assessCost(attempt.target.model, null, provider?.tierType).costClass
         : "paid";
@@ -1608,29 +1268,18 @@ function credentialEvidence(attempt, cfg, breaker, now) {
         facts,
         health: breaker.isHealthy(identity, now) ? "unknown" : "unhealthy",
         credentialFault: breaker.hasCredentialFault(identity, now),
-        // `cost` here is deliberately assessed with NO catalog limits (see above), so it can say
-        // `free` from a provider tier but never `paid` from a price. Passing it would under-report a
-        // paid deployment as unclassified, so this evidence view reports cooling for cost-filtered
-        // facts the same fail-safe way any unclassified caller does: they simply do not apply.
         cooling: cooledByAllowance(attempt, now, undefined),
         saturated: provider?.maxConcurrent != null && breaker.inFlightCredential(attempt.credentialId) >= provider.maxConcurrent,
         quota: state?.quotaObservations ?? [],
         cost,
     };
 }
-/**
- * Get the soonest cooldown lift time for a cooling attempt.
- * Checks breaker state first (covers breaker cooling + quota demotion), then target-facts for allowance facts.
- * Returns null if no known lift time (unknown).
- */
 function coolingLiftTime(attempt, breaker, now, costClassOf) {
     const identity = targetIdentity(attempt);
-    // 1. Breaker cooldown (covers failure/429/402 cooling AND quota demotion cooling)
     const breakerState = breaker.getState(identity);
     if (breakerState && breakerState.cooldownUntil > now) {
         return breakerState.cooldownUntil;
     }
-    // 2. Allowance exhaustion fact (target-facts) - only if not already covered by breaker
     const costClass = costClassOf?.(attempt);
     const factCooldown = cooldownUntil(attempt.target.provider, attempt.credentialId, attempt.target.model ?? null, {
         now,
@@ -1641,14 +1290,6 @@ function coolingLiftTime(attempt, breaker, now, costClassOf) {
     }
     return null;
 }
-/**
- * Keep every credential row of a deployment together while ordering deployments by their
- * best-ranked row. CredentialWalk performs the breadth-first interleaving when it offers rows.
- * Tracked like `orderByUsabilityTracked` so the request path can announce a displaced first choice.
- *
- * Within the COOLING band, order by soonest known lift time (ascending). Unknown lifts sort last.
- * Stable within ties and unknowns.
- */
 function orderDeploymentGroupsByUsability(attempts, breaker, now, quotaDemotion, costClassOf) {
     const preferred = groupCredentialAttempts(attempts)[0]?.attempts[0];
     const live = [];
@@ -1663,18 +1304,16 @@ function orderDeploymentGroupsByUsability(attempts, breaker, now, quotaDemotion,
         else
             live.push(group);
     }
-    // Sort cooling band by soonest lift time (ascending). Unknown (null) sorts last.
-    // Stable sort preserves original order for ties and unknowns.
     cooling.sort((a, b) => {
         const liftA = coolingLiftTime(a.attempts[0], breaker, now, costClassOf);
         const liftB = coolingLiftTime(b.attempts[0], breaker, now, costClassOf);
         if (liftA === null && liftB === null)
-            return 0; // both unknown - preserve order
+            return 0;
         if (liftA === null)
-            return 1; // A unknown sorts after B
+            return 1;
         if (liftB === null)
-            return -1; // B unknown sorts after A
-        return liftA - liftB; // both known - ascending by lift time
+            return -1;
+        return liftA - liftB;
     });
     const ordered = [...live, ...faulted, ...cooling].flatMap((group) => group.attempts);
     let quotaDemotedFirst = null;
@@ -1688,7 +1327,6 @@ function orderDeploymentGroupsByUsability(attempts, breaker, now, quotaDemotion,
     }
     return { ordered, quotaDemotedFirst };
 }
-/** Metadata-only trace: credential values and storage locations never enter it. */
 class CredentialAttemptTrace {
     cfg;
     entries = [];
@@ -1769,18 +1407,6 @@ function recordCredentialOutcome(walk, trace, attempt, outcome) {
     walk.record(attempt, outcome);
     trace.record(attempt, outcome);
 }
-/**
- * G2's attempt boundary — EVERY `CredentialWalk.next()` on both public fronts goes through here.
- *
- * A candidate whose operator-set hard cap is reached is refused IN THIS PROCESS, before any
- * egress and before `recordStarted()`: no provider request, no LRU touch, no breaker mutation,
- * no accounting attempt — the capped key spends literally nothing. It is still announced three
- * ways: a status-only `capped` entry in the metadata log's attempt list, an `Nxcapped` tally in
- * `x-llm-relay-pool-attempts`, and the soonest cap boundary kept on the tracker so an ALL-CAPPED
- * walk can state its Retry-After instead of inventing one. "Health demotes, never drops" still
- * governs the WALK — the capped cell stays listed everywhere and lifts at the period boundary;
- * only this attempt is refused.
- */
 function nextUncappedAttempt(h, walk, attemptTrace, tracker) {
     const now = Date.now();
     for (;;) {
@@ -1789,8 +1415,6 @@ function nextUncappedAttempt(h, walk, attemptTrace, tracker) {
             return undefined;
         const verdict = h.hardCap(candidate, now);
         if (verdict === null) {
-            // Announce the offer BEFORE returning: the tracker needs to know a candidate is in flight so
-            // a cap it sees while the loop asks for the next one is ordered after this candidate.
             tracker.noteOffered();
             return candidate;
         }
@@ -1823,9 +1447,6 @@ function endWalk(h, res, front, walk, attemptTrace, tracker, status, sticky, cre
     const shouldTryNext = exit.shouldTryNext ?? true;
     let next;
     if (exit.kind === "dead-stream") {
-        // Dead streams gate liveness BEFORE advancing the walk. That preserves the old lazy policy:
-        // capped/rejected cells are not recorded after the client side is already dead. The two
-        // fronts' liveness spellings intentionally remain different pending a separate unification.
         const canContinue = front === "anthropic"
             ? !res.destroyed
             : !res.writableEnded && !res.destroyed;
@@ -1834,13 +1455,7 @@ function endWalk(h, res, front, walk, attemptTrace, tracker, status, sticky, cre
             : undefined;
     }
     else {
-        // Transport and post-header failures advance BEFORE checking response liveness. Preserve that
-        // eager ordering: recordCapped/walk.recordRejected must still fire for skipped capped cells.
         next = shouldTryNext ? nextUncappedAttempt(h, walk, attemptTrace, tracker) : undefined;
-        // A response that died mid-walk forces the FINALIZE path even with a next candidate in hand
-        // (the pre-refactor shape): walking on for a gone client would spend another upstream request
-        // with no recordFinal and no log record at this exit. Unreachable today only because every
-        // eager caller pre-guards on res liveness — this keeps the helper safe if one stops.
         if (res.writableEnded || res.destroyed)
             next = undefined;
     }
@@ -1862,28 +1477,13 @@ function endWalk(h, res, front, walk, attemptTrace, tracker, status, sticky, cre
     h.logger.write(log());
     return false;
 }
-/**
- * The ALL-CAPPED refusal — the loud half of G2.
- *
- * Every walked candidate was refused by an operator-set cap, so the relay answers 429 itself:
- * there is no upstream error to pass through, and staying silent would hang the client. The body
- * names the caps (axis/period, inclusive used/cap, basis `operator-declared`) in each front's
- * NATIVE error shape, so an ordinary client's rate-limit handling just works. `Retry-After` is
- * derived ONLY from the soonest UTC period boundary any walked cap lifts at; when no boundary
- * resolves the header is omitted and the body says so — a duration is never invented. Metadata
- * only: labels, numbers, no message text, no key material.
- */
 function respondAllCapped(res, h, ctx, front, tracker, attempts) {
     if (res.headersSent)
         return;
     const summary = tracker.summary();
-    // One rendering, shared by the body and the header: two calls could disagree about the bound.
     const capped = tracker.cappedSummary();
     const labels = capped ?? "every candidate";
     const resetAt = tracker.cappedResetAt();
-    // The reset is a DERIVED UTC boundary (minute/day), so it always resolves for any cap this
-    // module can declare — but the fail-safe stays: when it somehow does not, the header is omitted
-    // and the body says the lift time is unknown rather than inventing a duration.
     const message = `llm-relay: request refused by operator-declared hard cap(s): ${labels}. ` +
         `No provider was contacted.` +
         (resetAt !== null
@@ -1904,10 +1504,6 @@ function respondAllCapped(res, h, ctx, front, tracker, attempts) {
     res.end(JSON.stringify(body));
     h.logger.write(baseLog(ctx.started, ctx.path, ctx.hadTools, ctx.streamed, 429, "skipped", null, attempts));
 }
-/**
- * Promote a pin only inside its live capability segment. In particular, a live degrade-tail pin
- * never jumps a live in-band member; the tail remains a fallback after the requested band.
- */
 function applyStickyOrdering(ordered, pinnedSpec, breaker, degraded, now, quotaDemotion, costClassOf) {
     const groups = groupCredentialAttempts(ordered);
     const pinnedIndex = groups.findIndex((group) => specOfTarget(group.attempts[0].target) === pinnedSpec);
@@ -1915,7 +1511,6 @@ function applyStickyOrdering(ordered, pinnedSpec, breaker, degraded, now, quotaD
     const pinned = pinnedGroup?.attempts[0];
     if (!pinned || !pinnedGroup)
         return { targets: ordered, status: "bypassed: not-in-pool" };
-    // The first row is the credential selector's best-ranked usable slot for this deployment.
     const usability = targetUsability(pinned, breaker, now, quotaDemotion, costClassOf);
     if (usability !== "live")
         return { targets: ordered, status: `bypassed: ${usability}` };
@@ -1930,8 +1525,6 @@ function applyStickyOrdering(ordered, pinnedSpec, breaker, degraded, now, quotaD
     }
     if (pinnedIndex === 0)
         return { targets: ordered, status: "pinned, natural" };
-    // Move the deployment group, not an individual row. CredentialWalk will still offer one slot
-    // per deployment round, so the pin cannot cluster every credential ahead of other deployments.
     const reordered = [pinnedGroup, ...groups.filter((_, index) => index !== pinnedIndex)]
         .flatMap((group) => group.attempts);
     return { targets: reordered, status: "pinned, reordered" };
@@ -1957,30 +1550,11 @@ export function orderByUsability(attempts, breaker = globalCircuitBreaker, now =
     const { ordered } = orderByUsabilityTracked(attempts, breaker, now);
     return ordered;
 }
-/**
- * Gap 12's walk-order orderer. Kept pure: its exported shape must not change, and the
- * quota-demotion ANNOUNCEMENT lives in exactly one place —
- * `orderDeploymentGroupsByUsability` above — because two copies of the displacement check
- * would drift silently (the first version of this block was unreachable here).
- *
- * Within the COOLING band, order by soonest known lift time (ascending). Unknown lifts sort last.
- * Stable within ties and unknowns.
- */
 function orderByUsabilityTracked(attempts, breaker, now, quotaDemotion, costClassOf) {
     const live = [];
     const faulted = [];
     const cooling = [];
     for (const attempt of attempts) {
-        // A learned allowance exhaustion cools a target the breaker may know nothing about. That is
-        // the whole point of the ACCOUNT scope: one member's stated "you have depleted your monthly
-        // included credits" is a fact about the credential, so its siblings are spent too and should
-        // step aside without each first spending a round-trip to be told so individually. Measured
-        // here: `pool/xhigh`'s 15 members share only four independent quota domains, so the walk was
-        // rediscovering four facts fifteen times.
-        //
-        // Demotion, never exclusion — same contract as the rest of this function, and doubly so here:
-        // an exhausted allowance is a temporary condition on a deployment that is still free, and a
-        // pool with nothing else left must still be able to try it.
         const usability = targetUsability(attempt, breaker, now, quotaDemotion, costClassOf);
         if (usability === "cooling")
             cooling.push(attempt);
@@ -1989,8 +1563,6 @@ function orderByUsabilityTracked(attempts, breaker, now, quotaDemotion, costClas
         else
             live.push(attempt);
     }
-    // Sort cooling band by soonest lift time (ascending). Unknown (null) sorts last.
-    // Stable sort preserves original order for ties and unknowns.
     cooling.sort((a, b) => {
         const liftA = coolingLiftTime(a, breaker, now, costClassOf);
         const liftB = coolingLiftTime(b, breaker, now, costClassOf);
@@ -2013,30 +1585,10 @@ export function classifyStatus(status) {
         return "retriable";
     return "client";
 }
-/** Whether another pool candidate is useful; health mutation occurs only at terminal completion. */
 function shouldTryNext(cls) {
     return cls === "retriable" || cls === "credential";
 }
-/**
- * Wall-clock ceiling on STARTING further failover attempts — one policy, both fronts, same maxim
- * as `classifyStatus`. A deep pool could legitimately spend members × timeoutMs on one request;
- * the budget bounds the walk, never the answer: an attempt already in flight is not aborted, and
- * the first TWO attempts are always allowed, so a slow-failing first candidate cannot starve the
- * request of its one retry. 0 disables. Default fork-validated in freellmapi (45s) — adoption
- * review §1.5.
- */
 export const DEFAULT_WALK_BUDGET_MS = 45_000;
-/**
- * Streamed-response deadline split (adoption review §1.2) — one policy, both fronts.
- *
- * One flat `timeoutMs` spanning the whole attempt mis-serves streams in both directions: a
- * healthy long generation still emitting bytes at the deadline is killed mid-answer, while a
- * genuinely dead stream is not detected until the same deadline. So once a stream is chosen for
- * serving, the total deadline DISARMS and an inter-byte watchdog takes over: every arriving
- * chunk re-arms it, and only silence for the full window aborts — through the same controller,
- * so the existing mid-stream error path reports it honestly. Default fork-validated in
- * freellmapi (90s); `stallTimeoutMs: 0` keeps the old single-deadline behavior.
- */
 export const DEFAULT_STALL_TIMEOUT_MS = 90_000;
 function withStallWatchdog(upstream, controller, stallMs) {
     if (!upstream.body)
@@ -2065,57 +1617,21 @@ function withStallWatchdog(upstream, controller, stallMs) {
         headers: upstream.headers,
     });
 }
-/**
- * How many capped cells `x-llm-relay-capped` may NAME before the rest are counted (`+K more`).
- *
- * The header is diagnostic, not a manifest: five lines is enough to see which credentials and
- * which axis stopped the request, and it keeps a fully capped 30-member dynamic pool from
- * emitting a ~1.2 KB header — a capped attempt costs no walk budget, so every member reaches it.
- */
 const MAX_CAPPED_HEADER_CELLS = 5;
-/**
- * All-429 exhaustion policy — one policy, both fronts (same maxim as `classifyStatus`).
- *
- * When the whole pool is rate-limited, the client is served the LAST candidate's real 429, but
- * that candidate's Retry-After may be the pool's worst: the earliest reset among the walked 429s
- * is when the POOL next has capacity. Only an all-429 walk qualifies — a mixed walk says nothing
- * about when the pool frees up, so any non-429 failure leaves the final header untouched.
- */
 class Pool429Tracker {
     minRetryAfterMs = null;
     only429 = true;
-    /** status → how many candidates answered it. Ordering lives in `firstSeenAt`. */
     counts = new Map();
-    /**
-     * Outcome kind → the walk position it was FIRST seen at, so the breakdown reads in WALK order.
-     *
-     * ⚠ Positions are stamped, not appended, because the two kinds of outcome arrive out of order:
-     * a cap is recorded while the walk is being asked for the next candidate — i.e. BEFORE the
-     * candidate already in flight has been counted. Appending made a walk that went `A:429 →
-     * B:capped` render `1xcapped, 1x429`, reversing what actually happened. See `stampCapped`.
-     */
     firstSeenAt = new Map();
-    /** Monotonic walk position handed out by `stamp()`; never a candidate count. */
     order = 0;
-    /** True while a candidate has been offered and its provider outcome has not been counted yet. */
     inFlight = false;
-    /** Caps observed while a candidate was in flight: they follow that candidate's own outcome. */
     deferredCapped = false;
-    /** G2: candidates skipped before egress because an operator-set hard cap was reached. */
     cappedLabels = [];
-    /** Soonest UTC boundary any walked cap lifts at — the pool's own next capacity instant. */
     soonestCapResetAt = null;
-    /** Set at the ONE true egress boundary (`onEgress`), so "no provider was contacted" stays provable. */
     egressed = false;
-    /** Called exactly where a backend request is about to start — see `onEgress` on both fronts. */
     noteEgress() {
         this.egressed = true;
     }
-    /**
-     * A candidate was OFFERED to the loop (it passed the cap gate and will be attempted). Nothing
-     * is tallied here — this only marks that an outcome for it is still to come, which is what
-     * lets a cap seen in the meantime be stamped AFTER it.
-     */
     noteOffered() {
         this.inFlight = true;
     }
@@ -2123,14 +1639,12 @@ class Pool429Tracker {
         if (!this.firstSeenAt.has(key))
             this.firstSeenAt.set(key, ++this.order);
     }
-    /** Place the deferred `capped` term once the in-flight candidate's own outcome is counted. */
     stampCapped() {
         if (!this.deferredCapped)
             return;
         this.deferredCapped = false;
         this.stamp("capped");
     }
-    /** Record a response being failed over past. */
     recordFailover(status, retryAfterMs) {
         this.count(status);
         if (status === 429) {
@@ -2142,21 +1656,10 @@ class Pool429Tracker {
             this.only429 = false;
         }
     }
-    /** Record the response actually served — the walk's last candidate, success or failure. */
     recordFinal(status) {
         this.count(status);
     }
-    /**
-     * Record a candidate skipped BEFORE egress by an operator-set hard cap (G2).
-     *
-     * Deliberately NOT folded into `recordFailover`: a cap is not a provider answer, so it must
-     * neither trip the breaker nor set `only429 = false` — when every candidate is capped, that
-     * flag's meaning ("nothing else went wrong") is exactly what licenses the synthesized refusal.
-     */
     recordCapped(label, resetsAt) {
-        // One tally entry per OUTCOME KIND, matching how statuses count: two distinct capped cells
-        // are still one `Nxcapped` term in the breakdown. Its POSITION waits for the candidate
-        // already in flight, whose outcome the loop has not counted yet.
         if (this.inFlight)
             this.deferredCapped = true;
         else
@@ -2165,29 +1668,12 @@ class Pool429Tracker {
         this.soonestCapResetAt =
             this.soonestCapResetAt === null ? resetsAt : Math.min(this.soonestCapResetAt, resetsAt);
     }
-    /** The soonest cap boundary across the walk, for the all-capped Retry-After; null otherwise. */
     cappedResetAt() {
         return this.soonestCapResetAt;
     }
-    /**
-     * True when this walk offered at least one candidate and EVERY one of them was refused by an
-     * operator-set hard cap before egress — no provider answered anything at all. That is the exact
-     * license for the relay-synthesized 429: any real provider outcome among the failures means the
-     * last real upstream error is the more honest body, and the caps ride beside it in the
-     * pool-attempts tally instead.
-     */
     allCapped() {
         return this.cappedLabels.length > 0 && this.counts.size === 0 && !this.egressed;
     }
-    /**
-     * `"a/nim/m requests/day 450/450"` lines, in walk order — metadata only, and BOUNDED.
-     *
-     * A capped attempt consumes no walk start budget (`credential-select.ts` gates that on
-     * `#started`), so every member of a fully capped 30-member dynamic pool reaches this list and
-     * an unbounded join is a ~1.2 KB header. At most `MAX_CAPPED_HEADER_CELLS` cells are named and
-     * the remainder is counted — the client learns the shape of the refusal without the response
-     * carrying the whole roster.
-     */
     cappedSummary() {
         if (this.cappedLabels.length === 0)
             return null;
@@ -2196,47 +1682,23 @@ class Pool429Tracker {
         const shown = this.cappedLabels.slice(0, MAX_CAPPED_HEADER_CELLS).join("; ");
         return `${shown}; +${this.cappedLabels.length - MAX_CAPPED_HEADER_CELLS} more`;
     }
-    /** A backend answered 200, but its malformed tool call remained unusable after repair. */
     recordDeadTurn() {
         this.only429 = false;
         this.count("dead-turn");
     }
-    /** A refusal in this walk whose meaning the relay could not look up. */
     unknownRefusals = 0;
     noteUnknownRefusal() {
         this.unknownRefusals += 1;
     }
-    /** How many, or null when every refusal was understood. */
     unknownCount() {
         return this.unknownRefusals > 0 ? this.unknownRefusals : null;
     }
     count(status) {
         this.counts.set(status, (this.counts.get(status) ?? 0) + 1);
         this.stamp(status);
-        // This candidate's outcome is in; anything capped while it was in flight comes next.
         this.inFlight = false;
         this.stampCapped();
     }
-    /**
-     * The walk, as one line: `"13 tried, 0 served: 4x402, 5x429, 3x403, 1x400"`.
-     *
-     * ⚠ ASCII only. This is an HTTP header value, and Node latin1-encodes those — a `×` reaches a
-     * UTF-8 client as mojibake. Caught on a live pool, where the header read `6�402`.
-     *
-     * A pool's error is one member's error, and that is genuinely misleading when the other twelve
-     * failed for three other reasons: the client is handed HuggingFace's 402 and told to go buy
-     * credits, when the correct action is "use another pool". The BODY still carries that member's
-     * real upstream error — a true upstream error beats a synthesized one, the same maxim the
-     * context guardrail and the all-429 policy follow — so the aggregate rides alongside it in a
-     * header and in the log, where it costs the client nothing and answers "what actually happened"
-     * without a round of manual probing.
-     *
-     * G2 caps appear in the breakdown as `Nxcapped`, in walk order beside the provider outcomes:
-     * they ARE candidates this request consumed, even though no provider saw them.
-     *
-     * Null for a single-candidate walk: there is no aggregate to report, and emitting one would
-     * dress up an ordinary passthrough error as a pool exhaustion.
-     */
     summary() {
         let tried = 0;
         let served = 0;
@@ -2248,34 +1710,20 @@ class Pool429Tracker {
         tried += this.cappedLabels.length;
         if (tried < 2)
             return null;
-        // A walk that ended while a candidate was still in flight never counted its outcome, so a cap
-        // deferred behind it would otherwise be dropped from the breakdown entirely.
         this.stampCapped();
         const parts = [...this.firstSeenAt.entries()]
             .sort((a, b) => a[1] - b[1])
             .map(([key]) => (key === "capped" ? `${this.cappedLabels.length}xcapped` : `${this.counts.get(key) ?? 0}x${key}`));
         return `${tried} tried, ${served} served: ${parts.join(", ")}`;
     }
-    /** Retry-After (ms) to serve on the FINAL response, or undefined to leave its real header alone. */
     overrideMs(finalStatus, finalRetryAfterMs) {
         if (finalStatus !== 429 || !this.only429 || this.minRetryAfterMs === null)
             return undefined;
         return Math.min(this.minRetryAfterMs, finalRetryAfterMs ?? Infinity);
     }
 }
-/**
- * Feed the proxy's own request outcome into runtime telemetry — the "observed traffic"
- * evidence consumed by `deploymentFitness()` on the operational axis (after capability
- * eligibility is decided by `getStrength()`) and reported under `observed` in `/candidates`.
- * `getStrength()` ranks capability using ONLY the synced capability snapshot (basis
- * "snapshot" → neutral 50); it does not consume runtime telemetry. Only targets with a
- * concrete model id are recorded; the Anthropic passthrough has none. Skipped under vitest
- * so tests never write the user's real telemetry file.
- */
 function recordCall(h, attempt, ok, completedAt) {
     const { target, usage } = attempt;
-    // Keep the historical default writer out of the test filesystem, but never suppress an
-    // explicit recorder: that seam is how ledger callers observe every terminal attempt.
     if (!target.model || !h.modelCallRecorder)
         return;
     try {
@@ -2286,10 +1734,8 @@ function recordCall(h, attempt, ok, completedAt) {
         });
     }
     catch {
-        /* telemetry is best-effort, never in the request's way */
     }
 }
-/** Request-scoped, bounded attempt metadata shared by both public fronts. */
 class RequestAttemptTrace {
     entries = [];
     record(target, status, started, completedAt) {
@@ -2302,7 +1748,6 @@ class RequestAttemptTrace {
             ms: Math.max(0, completedAt - started),
         });
     }
-    /** G2: an operator-set hard cap refused this candidate BEFORE any provider egress. */
     recordCapped(target, at) {
         this.record(target, "capped", at, at);
     }
@@ -2338,11 +1783,6 @@ function beginHealthAttempt(h, resolvedAttempt, started, trace, usage, accountin
         completed: false,
     };
 }
-/**
- * The candidate loops' client-gone reaction, shared by both fronts: when the client connection
- * closes before the response is finished, abort the caller-facing work and the in-flight backend
- * fetch together. One definition, so the two loops cannot drift.
- */
 function abortOnClientClose(res, callerController, controller) {
     return () => {
         if (!res.writableEnded) {
@@ -2351,21 +1791,7 @@ function abortOnClientClose(res, callerController, controller) {
         }
     };
 }
-/**
- * Learn a deployment's real context ceiling from an error it just returned.
- *
- * ⚠ Called from BOTH request paths, right beside `observeAttemptHeaders`, and for the same reason
- * that helper is shared: this repo has already shipped one defect where the OpenAI front had no
- * copy of a policy the Anthropic path enforced ("two paths, two policies, one of them empty" — see
- * docs/pool-failover.md). A learning loop that only ran on one front would silently know less
- * about half the traffic.
- *
- * Called only with bytes already buffered by inspectCandidateResponse, so learning never tees or
- * consumes the Response that may still need to become the client's terminal real error.
- */
 function observeContextLimit(status, target, body) {
-    // Context-length rejections are 400 (OpenAI-compatible) or 413. Anything else is a different
-    // fault, and scanning every error body would be work for nothing.
     if (status !== 400 && status !== 413)
         return;
     if (target.model === undefined)
@@ -2379,24 +1805,9 @@ function observeContextLimit(status, target, body) {
         recordObservedContextLimit(target.provider, target.model, stated);
     }
     catch {
-        // Learning is best-effort and never in the request's way.
     }
 }
-/**
- * Learn a deployment's stated OUTPUT-token ceiling (`max_tokens`) from an error it just returned.
- *
- * ⚠ Called from BOTH request paths beside `observeContextLimit`, for the same reason that helper
- * documents: a learning loop wired into only one front would silently know nothing about half the
- * traffic (docs/pool-failover.md). Called with bytes already buffered by
- * `inspectCandidateResponse`, so it never tees or consumes the Response that may still become the
- * client's terminal real error.
- *
- * Display-only by owner decision (docs/max-output-caps-design-2026-08-29.md): the fact renders in
- * `llm-relay candidates`; nothing clamps, refuses, or routes on it.
- */
 function observeMaxOutput(status, target, body) {
-    // A max_tokens rejection is a request-validation 400 (or a 413 variant); same gate as the
-    // context observer beside it.
     if (status !== 400 && status !== 413)
         return;
     if (target.model === undefined)
@@ -2410,21 +1821,8 @@ function observeMaxOutput(status, target, body) {
         recordObservedMaxOutput(target.provider, target.model, stated);
     }
     catch {
-        // Learning is best-effort and never in the request's way.
     }
 }
-/**
- * Record the durable half of provider-stated quota observations as learned rate-limit facts.
- *
- * A header pair like `x-ratelimit-limit-requests-day: 1000` is the deployment stating its own
- * ceiling — first-party evidence, same standing as an error body that says it. The observation
- * already had to be explicitly attributed (axis AND period named in the header, limit AND
- * remaining in one bucket), so nothing here guesses.
- *
- * ⚠ minute/day only. `quota-observation.ts` also recognizes month and unknown periods; there is no
- * measurement kind for either (a monthly ceiling is allowance territory, not rate), so they are
- * skipped rather than forced into a kind that would misstate them.
- */
 function observeStatedRateLimits(attempt, observations) {
     if (observations.length === 0)
         return;
@@ -2435,7 +1833,6 @@ function observeStatedRateLimits(attempt, observations) {
         for (const o of observations) {
             if (!Number.isFinite(o.limit) || o.limit <= 0)
                 continue;
-            // Month/unknown have no fact kind on purpose (see above); only minute/day are measurements.
             if (o.period !== "minute" && o.period !== "day")
                 continue;
             recordObservedRateLimit(target.provider, attempt.resolvedAttempt.credentialId, target.model, [
@@ -2444,25 +1841,8 @@ function observeStatedRateLimits(attempt, observations) {
         }
     }
     catch {
-        // Learning is best-effort and never in the request's way — observeAttemptHeaders itself may
-        // throw when the breaker rejects an observation, but this must not.
     }
 }
-/**
- * Learn a deployment's stated rate limits from an error body it just returned.
- *
- * ⚠ Called from BOTH request paths beside `observeContextLimit`, for the same reason that helper
- * documents: this repo has already shipped one defect where the OpenAI front had no copy of a
- * policy the Anthropic path enforced ("two paths, two policies, one of them empty" — see
- * docs/pool-failover.md). A learning loop that only ran on one front would silently know less
- * about half the traffic. Called with bytes already buffered by `inspectCandidateResponse`, so it
- * never tees or consumes the Response that may still become the client's terminal real error.
- *
- * ⚠ 429 only. A 402 (credits) or 403 (gating) is a different fact about a DIFFERENT axis, already
- * handled by the eligibility/refusal machinery; scanning those bodies for rate wording risks
- * recording a ceiling from prose that merely mentions one. Conservative default; revisit only with
- * evidence of a real provider stating its limit on a non-429.
- */
 function observeRateLimit(attempt, status, body) {
     if (status !== 429)
         return;
@@ -2477,15 +1857,8 @@ function observeRateLimit(attempt, status, body) {
         recordObservedRateLimit(attempt.target.provider, attempt.credentialId, attempt.target.model, stated);
     }
     catch {
-        // Learning is best-effort and never in the request's way.
     }
 }
-/**
- * Relay protocol adapters sometimes wrap a provider's JSON refusal inside their own error
- * message. Interpret the original nested payload as well as the outer wire body so a confirmed
- * signature means the same thing on every front. This is deterministic unwrapping only: no text
- * is classified or inferred here.
- */
 function refusalBodyCandidates(body) {
     const candidates = [];
     const queued = [body];
@@ -2511,7 +1884,6 @@ function refusalBodyCandidates(body) {
                     break;
                 }
                 catch {
-                    // Keep looking for the start of a nested JSON payload.
                 }
             }
             continue;
@@ -2554,72 +1926,25 @@ function observeEligibility(attempt, status, retryAfterMs, body) {
             }
         }
         if (verdict === null) {
-            // The fail-safe: an unrecognized refusal changes nothing about routing. It is held so a
-            // researcher can say what it means, and only then will it ever bind.
             recordUnknownRefusal(target.provider, target.model, status, body);
             return { unknown: true };
         }
-        // The verdict's scope TEMPLATE becomes a concrete scope here, using this request's provider
-        // and model. A provider-scoped verdict therefore covers every deployment behind that
-        // credential from one observation — which is the whole point: a stated credit balance or a
-        // rejected key is one fact, and rediscovering it once per model is pure waste.
         const scope = materializeScope(verdict.scope, target.provider, attempt.credentialId, target.model);
         const reset = resolveReset(verdict, retryAfterMs, matchedBody);
         recordFact(verdict.class, scope, {
             retryAfterMs: reset?.ms ?? null,
             ...(reset === null ? {} : { untilBasis: reset.basis }),
-            // The verdict's cost filter travels with it. Without this the reviewer's "paid deployments
-            // only" would be accepted, displayed, and then silently dropped on the way to the store —
-            // the verdict would demote everything the scope covers, which is the defect it was written
-            // to prevent.
             ...(verdict.costClasses === undefined ? {} : { costClasses: verdict.costClasses }),
         });
         return { unknown: false, scope };
     }
     catch {
-        /* learning is best-effort and never in the request's way */
     }
     return { unknown: false };
 }
-/**
- * Does the free-only guard bind this request?
- *
- *   explicit `true`  → always. The owner's standing "this lane never spends money", which a
- *                      per-call `@relay:` directive and a dispatch cliLane must not outrank.
- *   explicit `false` → never. Spending was opted into deliberately.
- *   UNSET            → defaults ON for offload-rerouted traffic, OFF for a directly addressed pool.
- *
- * ⚠ That asymmetry is the whole point, and it is why `loadConfig` keeps "unset" distinguishable
- * from "false". Offload exists to spend somebody else's free capacity instead of your
- * subscription, so an install that has never thought about cost must not discover the feature by
- * being billed for it — the default belongs there. But a request that *names* `pool/<name>` is an
- * explicit routing choice by someone who knows what a pool is, and silently gating all of it on a
- * flag they never set would turn every unpriced deployment into a 503 for a decision they did not
- * make. Defaulting both the same way was tried: it failed 29 tests, all of them pool traffic that
- * had nothing to do with offload, which is exactly the surprise a user would have hit.
- */
 function freeOnlyApplies(rule, rerouted) {
     return rule.freeOnly ?? rerouted;
 }
-/**
- * When the condition this refusal describes clears, best evidence first.
- *
- *   1. `Retry-After` — the header, stated by THIS response.
- *   2. A reviewed `field` rule — also read from THIS response, just from a place only a reviewer
- *      knew to look (Google's `retryDelay`, which no header carries).
- *   3. The generic body parse — the same class of evidence, found without being told where.
- *   4. A reviewed `fixed` window — a reviewer's knowledge of the provider, not a measurement of
- *      this response, so it ranks below everything the response actually said.
- *   5. null ⇒ the fact kind's default TTL.
- *
- * ⚠ The ordering is the point. A reviewer may know MORE than the response (that a daily quota
- * resets in hours when the body says nothing), but never more than the response about itself — so
- * an assertion can fill a gap and can never overrule a statement.
- *
- * Returns the value AND which rung produced it, so `recordFact` can persist the provenance
- * (`untilBasis`) beside the expiry rather than the availability producer having to re-derive it
- * from vendor prose in a read path.
- */
 function resolveReset(interpretation, headerMs, body) {
     if (headerMs !== null)
         return { ms: headerMs, basis: "retry-after" };
@@ -2638,14 +1963,6 @@ function resolveReset(interpretation, headerMs, body) {
     }
     return null;
 }
-/**
- * Statuses whose body can carry a durable fact.
- *
- * 429 is included, but narrowly: an ordinary rate limit stays the breaker's business and produces
- * no fact, because only the small set of messages that NAME an account-level limit matches a seed.
- * Reading the body costs nothing here — it is already being discarded — and the alternative was
- * never learning the one 429 that is worth learning.
- */
 function carriesEligibilityFact(status) {
     return (status === 400 ||
         status === 401 ||
@@ -2655,12 +1972,6 @@ function carriesEligibilityFact(status) {
         status === 410 ||
         status === 429);
 }
-/**
- * Inspect an error response once and rebuild it from the same bytes. The caller may either discard
- * the rebuilt response when CredentialWalk offers another candidate or serve it as the terminal
- * real upstream error. A body failure after headers is returned as a distinct protocol outcome;
- * it must never be rebuilt as an empty response under the provider's original credential status.
- */
 async function inspectCandidateResponse(res, attempt, retryAfterMs) {
     const propagatedFailure = postHeaderBodyFailure(res);
     if (propagatedFailure)
@@ -2706,15 +2017,9 @@ function walkOutcomeForResponse(status, localFailure, scope) {
 }
 function observeAttemptHeaders(h, attempt, status, retryAfterMs, headers) {
     const observedAt = Date.now();
-    // Provider-stated quota from the response that just served real traffic. Keep every attributed
-    // axis/period pair: reducing it to one scalar can conflate requests/day with tokens/minute.
     const quotaObservations = headers
         ? extractQuotaObservations(headers, { observedAt })
         : [];
-    // The `limit` half of a provider-stated quota observation is DURABLE — it is what the deployment
-    // says it allows — so it is also recorded as a learned rate-limit fact (spec §4 Rung 1: header
-    // observations are not their own rung; the limit IS the rung-1 measurement). `remaining` and
-    // `resetsAt` stay volatile here with the breaker.
     observeStatedRateLimits(attempt, quotaObservations);
     const result = h.breaker.observeHeaders(attempt.handle, {
         target: attempt.identity,
@@ -2760,22 +2065,13 @@ function completeAttemptSuccess(h, attempt, status) {
     attempt.trace.record(attempt.target, status, attempt.started, completedAt);
     recordCall(h, attempt, true, completedAt);
     attempt.accounting?.complete(attempt.accountingAttempt, "success", null, attempt.usage, completedAt);
-    // A served request is first-party proof that this deployment exists and that the credential has
-    // allowance RIGHT NOW — strictly better evidence than any stored refusal, so it clears the
-    // record, including the account-scoped one. That is how a topped-up balance or a rolled-over
-    // month recovers well before the TTL would have expired, with no restart. Same contract as the
-    // breaker clearing a credential fault on success.
     try {
         const cleared = clearFacts(attempt.target.provider, attempt.resolvedAttempt.credentialId, attempt.target.model ?? null);
-        // A stated bad credential has just been disproved, so the per-deployment 401s it caused are
-        // stale evidence about a problem that no longer exists. Clearing them together is what makes a
-        // key rotation recover the WHOLE provider at once instead of one model per expiry.
         if (cleared.includes("credential-invalid")) {
             h.breaker.clearCredentialFaults(attempt.resolvedAttempt.credentialId);
         }
     }
     catch {
-        /* best-effort */
     }
 }
 function completeAttemptFailure(h, attempt, options) {
@@ -2819,11 +2115,6 @@ function completeAttemptCancelled(h, attempt, reason) {
     attempt.trace.record(attempt.target, "cancelled", attempt.started, completedAt);
     attempt.accounting?.complete(attempt.accountingAttempt, "cancelled", "aborted", attempt.usage, completedAt);
 }
-/**
- * A Response proves fetch reached the provider and received headers. A later body rejection is
- * therefore not a provider-wide transport failure and a credential-looking status is not usable
- * evidence about the credential. Close only this deployment unless the client or deadline won.
- */
 function completePostHeaderBodyFailure(h, downstream, signal, attempt, credentialWalk, credentialTrace, resolvedAttempt) {
     if (downstream.destroyed) {
         completeAttemptCancelled(h, attempt, "client disconnected while reading provider response body");
@@ -2856,30 +2147,12 @@ function detectOpenAiFrontProtocol(method, pathname) {
         return "responses";
     return null;
 }
-/**
- * OpenAI front: serve a resolved candidate's Chat Completions or Responses request, preserving
- * the OpenAI wire contract. Direct OpenAI Chat Completions remain verbatim; translated paths use
- * the backend adapter, which keeps the internal Anthropic-shaped seam but does not run the
- * Anthropic tool-repair layer for OpenAI callers.
- *
- * ⚠ This path failed over across candidates for exactly as long as this comment has existed,
- * which is to say it never did. It was handed `healthyTargets[0]` and returned before the
- * Anthropic path's failover loop, and it reported outcomes to runtime telemetry but never to the
- * circuit breaker — so a rate-limited candidate was neither stepped over within a request nor
- * demoted for the next one, and a 14-member pool served every single request from the same dead
- * member. Measured: 8 sequential requests to a 14-candidate pool, 6 consecutive 429s, 0 other
- * candidates tried, breaker `lastStatus: null` throughout. Both halves are fixed here; the
- * classification and breaker accounting come from the SAME helpers the Anthropic path uses, so
- * the two cannot drift apart again.
- */
 async function openAiFrontPath(res, credentialWalk, credentialTrace, ctx, h) {
     const tried = [];
     const attemptTrace = new RequestAttemptTrace();
     const directTools = toolSchemaMap(ctx.reqJson);
     const pool429 = new Pool429Tracker();
     while (!res.destroyed) {
-        // G2's attempt boundary, shared with the Anthropic front: a capped offer is refused here
-        // before any egress and the loop comes straight back for the next candidate.
         const resolvedAttempt = nextUncappedAttempt(h, credentialWalk, attemptTrace, pool429);
         if (!resolvedAttempt)
             break;
@@ -2918,7 +2191,6 @@ async function openAiFrontPath(res, credentialWalk, credentialTrace, ctx, h) {
                 }
                 throw e;
             }
-            /* attempt begins at the real egress callback */
             const recoveryAudit = { value: null };
             const processRecoveredChat = async (recovered) => {
                 const assistant = {
@@ -3128,8 +2400,6 @@ async function openAiFrontPath(res, credentialWalk, credentialTrace, ctx, h) {
                         errorOrigin: probe.provenance,
                         servedBy: tried.join(", "),
                         shouldTryNext: probe.provenance === "upstream",
-                        // Preserved residue: OpenAI dead streams require both writable-open and not
-                        // destroyed; handle's Anthropic path checks only `!res.destroyed`.
                     });
                     if (walkEnd)
                         continue;
@@ -3152,9 +2422,6 @@ async function openAiFrontPath(res, credentialWalk, credentialTrace, ctx, h) {
             pool429.recordFinal(upstream.status);
             let responseBytesWritten = false;
             try {
-                // One announcement set for both fronts — see `ServedAnnouncementContext`. The credential
-                // headers are read here, after `recordCredentialOutcome` above settled the winning slot,
-                // which is the per-attempt attribution a bare shared call would otherwise lose.
                 const headers = responseHeadersForTarget(upstream, {
                     target,
                     tried,
@@ -3163,7 +2430,6 @@ async function openAiFrontPath(res, credentialWalk, credentialTrace, ctx, h) {
                     poolUnknownRefusals: pool429.unknownCount(),
                     credentialHeaders: credentialTrace.headers(),
                     degraded: degradedLabel(ctx.addressedPool ?? null, ctx.degradedSpecs ?? null, target),
-                    // The announcement computed at walk-order time, beside the same demotion that produced it.
                     quotaDemoted: ctx.quotaDemotedFirst,
                     paid: ctx.cfg ? paidLabel(ctx.cfg, h, target) : null,
                     sticky: ctx.sticky,
@@ -3212,10 +2478,6 @@ async function openAiFrontPath(res, credentialWalk, credentialTrace, ctx, h) {
             const audit = recoveryAudit.value;
             const log = {
                 ...baseLog(ctx.started, ctx.path, ctx.hadTools, streamed, upstream.status, audit?.validated ?? "skipped", target, attemptTrace.snapshot(), upstreamReportedModel(reportedModelSource), resolvedAttempt.credentialId),
-                // This front's TRANSLATED lane (anything but openai-kind + Chat) runs through
-                // `fetchBackend`, so a Codex `/v1/responses` turn on an openai-kind target gets the same
-                // id mint the Messages front does — and it must be reported on the SERVED turn, not only
-                // on the mid-stream error path that already carried it.
                 ...toolUseIdRewriteField(reportedModelSource),
             };
             h.logger.write(audit ? {
@@ -3250,29 +2512,13 @@ async function openAiFrontPath(res, credentialWalk, credentialTrace, ctx, h) {
             res.off("close", onResClose);
         }
     }
-    // Same single refusal site as the Anthropic front (see the note there): a walk whose every
-    // candidate was refused before the first egress reaches here with nothing sent, and owes the
-    // client its refusal. Anything that egressed keeps its own upstream error instead.
     if (!res.headersSent && !res.destroyed && pool429.allCapped()) {
         respondAllCapped(res, h, { started: ctx.started, path: ctx.path, hadTools: ctx.hadTools, streamed: ctx.wantsStream }, "openai", pool429, attemptTrace.snapshot());
     }
 }
-/**
- * The metadata-only `tool_use` id-minting counter for this response, or nothing when the host's
- * own ids were already unique.
- *
- * Read from the response the backend adapter produced, and only at LOG time: on a stream the pass
- * runs while the body drains, so the figure is final once the request is over and would be a guess
- * any earlier. A count, never an id.
- */
 function toolUseIdRewriteField(source) {
     const rewrites = toolUseIdRewrites(source);
-    // The REQUEST-direction sibling: ids the mapper rewrote to the provider's stated shape
-    // (`compat.toolCallIds: "strict9"`). Final before egress, but read here so both counters travel
-    // together and a stream reports both in the one place it can.
     const outbound = toolCallIdRewrites(source);
-    // The other request-direction pass (`compat.thoughtSignature: "sentinel"`). It has NO response
-    // header of its own, so this is the only surface the operator can see it on.
     const sentinels = thoughtSignatureSentinels(source);
     return {
         ...(rewrites === undefined ? {} : { toolUseIdRewrites: rewrites }),
@@ -3280,16 +2526,8 @@ function toolUseIdRewriteField(source) {
         ...(sentinels === undefined ? {} : { thoughtSignatureSentinels: sentinels }),
     };
 }
-/** Winning-candidate response metadata, shared by transparent and repair streaming paths. */
 function responseHeadersForTarget(backendRes, ctx) {
     const responseHeaders = filterResponseHeaders(backendRes.headers);
-    // The winner below 400, every deployment tried at or above it. The header's own declaration is
-    // the contract — "when every candidate fails it carries the list that was tried instead, so an
-    // exhausted pool is self-describing" — and `docs/reference.md` states it to users. This front
-    // used to omit it entirely on a terminal error while the OpenAI front supplied it, so the same
-    // documented behaviour was delivered by one path and not the other.
-    // ⚠ Not the transport-exit omission at the `handle` catch, which is a RECORDED deliberate
-    // residue: a transport exhaustion has no HTTP response to describe.
     responseHeaders[SERVED_BY_HEADER] = backendRes.status < 400 || !ctx.tried?.length
         ? specOfTarget(ctx.target)
         : ctx.tried.join(", ");
@@ -3298,12 +2536,6 @@ function responseHeadersForTarget(backendRes, ctx) {
     }
     if (ctx.poolSummary)
         responseHeaders[POOL_ATTEMPTS_HEADER] = ctx.poolSummary;
-    // Counts only candidates stepped over: terminal refusal bodies are not buffered on this path.
-    // ⚠ Emitted on SUCCESS too, and that is the point: the count is the push half of the eligibility
-    // queue — "a NEW kind of refusal just appeared, run `llm-relay eligibility` while the context is
-    // still in hand". A later candidate answering does not un-see the refusal. The OpenAI front used
-    // to compute it only inside its own `status >= 400` branch and so swallowed exactly that case.
-    // The count is positive-or-null and never 0, so this truthy test is exact.
     if (ctx.poolUnknownRefusals)
         responseHeaders[UNKNOWN_REFUSAL_HEADER] = String(ctx.poolUnknownRefusals);
     if (ctx.degraded)
@@ -3319,7 +2551,6 @@ function responseHeadersForTarget(backendRes, ctx) {
         responseHeaders[STICKY_PROVENANCE_HEADER] = sticky;
     return responseHeaders;
 }
-/** detect/default: forward bytes unchanged, observe + log if applicable. */
 async function transparentPath(res, backendRes, timer, ctx, h) {
     if (!res.headersSent)
         res.writeHead(backendRes.status, responseHeadersForTarget(backendRes, ctx));
@@ -3358,29 +2589,17 @@ async function transparentPath(res, backendRes, timer, ctx, h) {
                     markAttemptCommitted(ctx.attempt);
                 res.end(bytes);
             }
-            // Same as the OpenAI front's terminal branch: the served response is the last candidate's,
-            // and for a single-member pool the only refusal we will ever see. Errors are never streamed,
-            // so this branch is where they land.
-            // NOTE: observeEligibility was already called in inspectCandidateResponse for this response.
-            // Calling it again here would double-count the refusal signature in the eligibility queue.
             if (ctx.willValidate && bytes.length <= MAX_VALIDATE_BYTES)
                 assistant = parseAssistant(bytes.toString("utf8"));
         }
     }
     catch (e) {
-        // The head was committed at the top of this function, so the client is already
-        // reading a 200. Say the stream broke rather than closing on a truncated answer,
-        // and LOG the turn — this throw used to escape to the top-level catch, which
-        // could only `res.end()` and never logged.
         handleMidStreamError(res, e, ctx.started, ctx.path, ctx.hadTools, ctx.streamed, backendRes.status, ctx.target, ctx.attempt, h, (msg) => ctx.streamed ? sseError(msg) : null, ctx.reportedModelSource, ctx.signal.aborted, responseBytesWritten);
         return;
     }
     finally {
         clearTimeout(timer);
     }
-    // A client disconnect can make writeChunk stop without throwing. Leave the handle pending so
-    // the routing-level finally records cancellation instead of validating a partial response and
-    // charging it to provider health.
     if (res.destroyed)
         return;
     let validated = "skipped";
@@ -3420,7 +2639,6 @@ async function transparentPath(res, backendRes, timer, ctx, h) {
         ...toolUseIdRewriteField(ctx.reportedModelSource),
     });
 }
-/** repair: route to the streaming or buffered variant. */
 async function repairPath(res, backendRes, timer, ctx, h) {
     if (ctx.streamed) {
         await repairStreamingPath(res, backendRes, timer, ctx, h);
@@ -3430,21 +2648,12 @@ async function repairPath(res, backendRes, timer, ctx, h) {
         return repairBufferedPath(res, backendRes, timer, ctx, h);
     }
 }
-/**
- * repair, streaming: forward text-block SSE frames to the client as they arrive;
- * withhold everything from the first tool_use `content_block_start` onward. At
- * end-of-stream, validate the reconstructed message — if the tool calls are valid,
- * flush the withheld frames byte-for-byte (fully transparent); if invalid, repair
- * and re-emit only the corrected trailing blocks. `message_start` and any leading
- * text have already reached the client, so a pure-text response streams through
- * with zero added latency.
- */
 async function repairStreamingPath(res, backendRes, timer, ctx, h) {
     const filtered = responseHeadersForTarget(backendRes, ctx);
-    let acc = ""; // full decoded stream, for reconstruction
-    let overflow = false; // acc exceeded the validate cap → give up repair
-    let work = Buffer.alloc(0); // raw bytes not yet split into complete frames
-    const held = []; // frames withheld from the client (first tool_use onward)
+    let acc = "";
+    let overflow = false;
+    let work = Buffer.alloc(0);
+    const held = [];
     let buffering = false;
     let firstToolUseIndex = -1;
     let headWritten = res.headersSent;
@@ -3472,7 +2681,6 @@ async function repairStreamingPath(res, backendRes, timer, ctx, h) {
         if (!overflow) {
             acc += frame.toString("utf8");
             if (acc.length > MAX_VALIDATE_BYTES) {
-                // Too large to validate/repair safely: stop holding, stream the rest.
                 overflow = true;
                 if (buffering) {
                     await flushHeld();
@@ -3502,21 +2710,15 @@ async function repairStreamingPath(res, backendRes, timer, ctx, h) {
                 let end;
                 while ((end = frameEnd(work)) !== -1) {
                     const frame = work.subarray(0, end);
-                    work = Buffer.from(work.subarray(end)); // detach from the growing buffer
+                    work = Buffer.from(work.subarray(end));
                     await processFrame(frame);
                 }
             }
         }
         if (work.length)
-            await processFrame(work); // trailing partial frame
+            await processFrame(work);
     }
     catch (e) {
-        // The upstream stream broke part-way. Anything withheld in `held` is a partial
-        // tool call and is DROPPED rather than flushed — half a tool_use is exactly the
-        // malformed call this proxy exists to keep out of the harness — and the client
-        // gets an explicit error event instead of a stream that simply stops. If the
-        // head has not been written yet (a failure before any text frame) this is still
-        // a clean 502. Either way the turn is logged.
         held.length = 0;
         handleMidStreamError(res, e, ctx.started, ctx.path, ctx.hadTools, true, backendRes.status, ctx.target, ctx.attempt, h, sseError, ctx.reportedModelSource, ctx.signal.aborted, responseBytesWritten);
         return;
@@ -3532,7 +2734,6 @@ async function repairStreamingPath(res, backendRes, timer, ctx, h) {
     let errorKinds = [];
     let repairOutcome = "none";
     if (overflow || !buffering) {
-        // Nothing was withheld (pure text, or gave up): stream already complete.
         if (!buffering) {
             const assistant = overflow ? null : reconstructFromSse(acc);
             if (assistant) {
@@ -3571,7 +2772,7 @@ async function repairStreamingPath(res, backendRes, timer, ctx, h) {
                 signal: ctx.callerSignal,
             });
             repairOutcome = decision.outcome;
-            ensureHead(); // message_start + leading text already forwarded
+            ensureHead();
             if (decision.outcome === "fixed" && decision.message) {
                 if (!res.writableEnded) {
                     const tail = emitSseTail(decision.message, firstToolUseIndex);
@@ -3581,7 +2782,6 @@ async function repairStreamingPath(res, backendRes, timer, ctx, h) {
                 }
             }
             else {
-                // Head already committed — surface a mid-stream SSE error, never a fabricated call.
                 if (!res.writableEnded)
                     res.end(sseError(`llm-relay: tool call could not be repaired (${decision.outcome})`));
             }
@@ -3614,16 +2814,12 @@ async function repairStreamingPath(res, backendRes, timer, ctx, h) {
         ...toolUseIdRewriteField(ctx.reportedModelSource),
     });
 }
-/** repair, buffered (non-streamed JSON): buffer, validate; if invalid, reshape and re-emit. */
 async function repairBufferedPath(res, backendRes, timer, ctx, h) {
     let bytes;
     try {
         bytes = Buffer.from(await backendRes.arrayBuffer());
     }
     catch (e) {
-        // Nothing has been written yet on this path, so this is a clean 502 rather than
-        // a truncated body — but it still has to be LOGGED, which the bare finally did
-        // not do: the throw went straight to the top-level catch.
         handleMidStreamError(res, e, ctx.started, ctx.path, ctx.hadTools, ctx.streamed, backendRes.status, ctx.target, ctx.attempt, h, () => null, ctx.reportedModelSource, ctx.signal.aborted);
         return null;
     }
@@ -3635,8 +2831,6 @@ async function repairBufferedPath(res, backendRes, timer, ctx, h) {
     const assistant = ctx.streamed
         ? reconstructFromSse(bytes.toString("utf8"))
         : parseAssistant(bytes.toString("utf8"));
-    // W8's winning-candidate metadata assembly is shared with transparent and streaming repair;
-    // sticky provenance must describe the candidate that actually commits here too.
     const filtered = responseHeadersForTarget(backendRes, ctx);
     let repairOutcome = "none";
     let validated = "skipped";
@@ -3654,8 +2848,6 @@ async function repairBufferedPath(res, backendRes, timer, ctx, h) {
     };
     if (!assistant) {
         if (backendRes.status < 400) {
-            // A successful status with no Anthropic message is not a successful provider attempt.
-            // Nothing has been committed yet on this buffered path, so return a bounded clean 502.
             validated = "fail";
             errorKinds = ["invalid_upstream_envelope"];
             failClosed(res, 502, "llm-relay: invalid Anthropic upstream envelope", recordFinalWalk(502, stickyProvenanceHeaders(ctx.sticky)));
@@ -3677,7 +2869,7 @@ async function repairBufferedPath(res, backendRes, timer, ctx, h) {
         if (r.valid) {
             validated = r.uncheckableCount > 0 ? "uncheckable" : "pass";
             recordFinalWalk(backendRes.status, filtered);
-            res.writeHead(backendRes.status, filtered); // pass through untouched
+            res.writeHead(backendRes.status, filtered);
             if (!res.writableEnded) {
                 if (backendRes.status < 400 && bytes.length > 0)
                     markAttemptCommitted(ctx.attempt);
@@ -3701,11 +2893,8 @@ async function repairBufferedPath(res, backendRes, timer, ctx, h) {
                 emitFixed(res, backendRes.status, filtered, decision.message, ctx.wantsStream, () => markAttemptCommitted(ctx.attempt));
             }
             else if (decision.outcome === "failed") {
-                // Nothing has been committed on the buffered path. The outer candidate loop decides
-                // whether this request can resume or whether this remains the terminal fail-clean 502.
             }
             else {
-                // fail-clean: loud, well-formed error rather than a silently broken call.
                 failClosed(res, 502, `llm-relay: tool call could not be repaired (${decision.outcome})`, recordFinalWalk(502, stickyProvenanceHeaders(ctx.sticky)));
             }
         }
@@ -3761,18 +2950,6 @@ function emitFixed(res, status, filtered, message, wantsStream, beforeBody) {
         }
     }
 }
-/**
- * Re-serialize a repaired message as a buffered Anthropic Message — the JSON counterpart
- * of `emitSse`, and it now follows the same rules.
- *
- * It used to hardcode `id: "msg_repair"`, take `model` from what the CLIENT asked for (which
- * is routinely not the deployment that answered), and zero-fill `usage`. All three rewrote
- * the response's identity on the way through: every repaired turn looked like the same
- * message, attributed to the wrong model, reporting a token count nobody measured. The
- * backend's own values are carried whenever the response had them; an unknown id falls back
- * to the same relay-marked synthetic id the streaming path uses, and an unreported `usage`
- * is OMITTED rather than stated as zero.
- */
 function toAnthropicMessage(msg) {
     return {
         id: msg.id ?? syntheticMessageId(),
@@ -3785,46 +2962,14 @@ function toAnthropicMessage(msg) {
         ...(msg.usage ? { usage: msg.usage } : {}),
     };
 }
-/** A provider declared an authEnv whose variable is unset — a configuration error, not a passthrough. */
 export class CredentialConfigError extends Error {
     constructor(provider, authEnv) {
         super(`provider "${provider}" declares authEnv ${authEnv} but it is unset or blank`);
         this.name = "CredentialConfigError";
     }
 }
-/**
- * The headers forwarded upstream for one request (INV-HS-8).
- *
- * Exported so the `declared-missing` branch is directly assertable: it is meant to
- * be unreachable through the request path (`resolveTargets` drops keyless targets),
- * so an end-to-end test cannot reach it, and an invariant nothing can check is an
- * invariant that quietly stops holding.
- *
- * The three `CredentialState`s are three different obligations:
- *  - `not-declared`   — a real passthrough. The caller's own credential is FORWARDED;
- *                       that is the whole point of the anthropic passthrough. A provider may
- *                       DECLARE this with `credentialMode: "passthrough"`, and declare the
- *                       opposite with `credentialMode: "contained"` — a keyless backend that is
- *                       not the caller's own vendor (a local daemon, a second relay, someone
- *                       else's Anthropic-format endpoint) must not receive their credential just
- *                       because it needs none of its own. Omitting the field still forwards, so
- *                       existing configs keep working, and config load warns instead.
- *  - `declared-present` — the provider's own key is attached and the caller's inbound
- *                       `Authorization`/`x-api-key` are REMOVED, never merged.
- *  - `declared-missing` — the caller's inbound `Authorization`/`x-api-key` are REMOVED
- *                       *and* the request fails. "Removed" is strictly stronger than
- *                       "we did not add one of our own": the defect this replaces
- *                       satisfied the weaker reading while forwarding the caller's
- *                       Anthropic token verbatim to a third-party base URL.
- */
 export function buildForwardHeaders(inbound, attempt) {
     const { target, credential } = attempt;
-    // Containment is DECLARED, not inferred from key presence. The old
-    // `stripAuth = !!apiKey` was identically falsy for two opposite configurations —
-    // "no authEnv declared" (an intentional passthrough: forward the caller's own
-    // credential) and "authEnv declared but unset" (a misconfiguration) — so in the
-    // second case the caller's own Anthropic token was forwarded verbatim to a
-    // third-party base URL. Only a real passthrough forwards inbound auth now.
     const stripAuth = credential.state !== "not-declared" || target.credentialMode === "contained";
     const out = {};
     for (const [k, v] of Object.entries(inbound)) {
@@ -3833,10 +2978,6 @@ export function buildForwardHeaders(inbound, attempt) {
             continue;
         if (INTERNAL_REQUEST_HEADERS.has(key))
             continue;
-        // The REMOVAL, for both declared states. It happens before the throw below so
-        // that no code path can observe a header map still carrying the caller's
-        // credential — not the throw's own error, not a future caller that decides to
-        // handle the error and reuse what was built.
         if (stripAuth && INBOUND_AUTH.includes(key))
             continue;
         if (v === undefined)
@@ -3846,9 +2987,6 @@ export function buildForwardHeaders(inbound, attempt) {
     if (!out["anthropic-version"])
         out["anthropic-version"] = DEFAULT_ANTHROPIC_VERSION;
     if (credential.state === "declared-missing") {
-        // Should be unreachable — resolveTargets drops keyless targets — but thrown
-        // rather than silently proceeding so a routing change that lets one through
-        // fails loudly instead of egressing whatever the caller happened to send.
         throw new CredentialConfigError(target.provider, target.authEnv);
     }
     Object.assign(out, buildAuthHeaders(credential.value, target.authHeader));
@@ -3885,15 +3023,6 @@ async function forwardLocalResponse(res, response) {
         res.writeHead(response.status, headers);
     res.end(bytes);
 }
-/**
- * Parse a buffered (non-streamed) backend response into the shape the validator inspects.
- *
- * `id` / `model` / `stop_sequence` are read here for the same reason `reconstructFromSse`
- * reads them off `message_start`: a repaired buffered response is re-serialized from this
- * shape, so anything not captured here is gone by the time it is re-emitted — which is how
- * every repaired non-streamed turn used to go out under the constant `msg_repair` with the
- * backend's real id discarded. Absent fields stay absent; nothing is invented.
- */
 function parseAssistant(text) {
     try {
         const j = JSON.parse(text);
@@ -3917,12 +3046,6 @@ function parseAssistant(text) {
         return null;
     }
 }
-/**
- * End offset (exclusive) of the first complete SSE frame in `buf`, or -1 if no
- * frame boundary is present yet. Frames are delimited by a blank line — `\n\n`
- * (LF) or `\r\n\r\n` (CRLF); whichever boundary comes first wins. Operates on
- * raw bytes so multibyte UTF-8 in event payloads is never split.
- */
 function frameEnd(buf) {
     const lf = buf.indexOf("\n\n", 0, "latin1");
     const crlf = buf.indexOf("\r\n\r\n", 0, "latin1");
@@ -3932,10 +3055,6 @@ function frameEnd(buf) {
         return crlf + 4;
     return lf + 2;
 }
-/**
- * If `frame` is a `content_block_start` event opening a `tool_use` block, return
- * its block index; otherwise null. This is the trigger to start withholding.
- */
 function frameOpensToolUse(frame) {
     const dataLines = [];
     for (const line of frame.toString("utf8").split(/\r?\n/)) {
@@ -3960,39 +3079,14 @@ function frameOpensToolUse(frame) {
         return null;
     return typeof e.index === "number" ? e.index : 0;
 }
-/** A single Anthropic-style SSE `error` event, for failing an already-open stream. */
 function sseError(message) {
     const data = JSON.stringify({ type: "error", error: { type: "api_error", message } });
     return `event: error\ndata: ${data}\n\n`;
 }
-/** The OpenAI-front equivalent: an error object in a plain `data:` frame. */
 function openAiSseError(message) {
     return `data: ${JSON.stringify({ error: { message, type: "api_error" } })}\n\n`;
 }
-/**
- * The log `errorKinds` entry for an upstream body that failed part-way through.
- *
- * A distinct kind, not a validator error kind: the response was never validated,
- * it was cut off. It is what makes a truncated turn greppable in the log at all.
- */
 const MID_STREAM_ERROR_KIND = "backend_stream_failed";
-/**
- * Terminate a response whose upstream body threw PART-WAY THROUGH.
- *
- * By the time a body is consumed the head is usually already committed, so
- * `failClosed` degrades to a bare `res.end()` and the client cannot tell a
- * truncated answer from a complete one. Where the committed response is a stream
- * we can still say so — `errorFrame` carries the protocol-appropriate error event
- * (Anthropic `event: error`, or an OpenAI `data:` frame on the OpenAI front) —
- * and where it is not, closing is all that remains. Pass `null` for a committed
- * non-stream response; inventing a frame in the wrong protocol is worse than
- * closing.
- *
- * ⚠ The caller MUST also write a log record. Previously the throw propagated out
- * of these paths past `h.logger.write` to `createProxy`'s top-level catch, so a
- * mid-stream backend failure produced a truncated 200 AND no log line at all —
- * invisible to the operator, and indistinguishable from success to the client.
- */
 function endMidStreamFailure(res, errorFrame, message) {
     if (res.writableEnded || res.destroyed)
         return;
@@ -4002,13 +3096,6 @@ function endMidStreamFailure(res, errorFrame, message) {
     }
     res.end(errorFrame ?? undefined);
 }
-/**
- * Handle a mid-stream failure (socket reset / network drop mid-response).
- *
- * Emits protocol-appropriate error frames (SSE event/data or none for non-stream),
- * completes the attempt's still-provisional health handle as a failure and writes a
- * metadata log record with `MID_STREAM_ERROR_KIND`.
- */
 function handleMidStreamError(res, e, started, path, hadTools, streamed, backendStatus, target, attempt, h, errorFrameBuilder, reportedModelSource, deadlineAborted = false, committed = false) {
     const message = midStreamMessage(e);
     const errorFrame = errorFrameBuilder(message);
@@ -4030,7 +3117,6 @@ function handleMidStreamError(res, e, started, path, hadTools, streamed, backend
         ...toolUseIdRewriteField(reportedModelSource),
     });
 }
-/** The client-facing description of a mid-transfer upstream failure. */
 function midStreamMessage(e) {
     const errStr = e && typeof e === "object" && "message" in e && typeof e.message === "string"
         ? e.message
@@ -4054,11 +3140,7 @@ function readBody(req, maxBytes = DEFAULT_MAX_BODY_BYTES) {
             if (total > maxBytes) {
                 done = true;
                 cleanup();
-                // Drain without retaining the rest so the client can receive the explicit 413 response.
                 req.resume();
-                // Tagged, not described: the dashboard route classifies 413-vs-500 from this CODE. It used
-                // to regex-match this very message string, i.e. the relay inferring its own intent from
-                // prose — see `BODY_TOO_LARGE_CODE`. Harmless for the other caller, which ignores it.
                 reject(Object.assign(new Error("request body too large"), { code: BODY_TOO_LARGE_CODE }));
                 return;
             }
@@ -4112,12 +3194,7 @@ async function writeChunk(res, chunk, beforeWrite) {
         return false;
     }
 }
-function failClosed(res, status, message, headers, 
-/**
- * Error type for the body. Defaults to `api_error`, which is what every caller wanted before a
- * relay-authored refusal could reach here — so an omitted argument is byte-identical to before.
- */
-errorType = "api_error") {
+function failClosed(res, status, message, headers, errorType = "api_error") {
     if (res.headersSent) {
         if (!res.writableEnded)
             res.end();
@@ -4126,20 +3203,6 @@ errorType = "api_error") {
     res.writeHead(status, { ...headers, "content-type": "application/json" });
     res.end(JSON.stringify({ type: "error", error: { type: errorType, message } }));
 }
-/**
- * Build the metadata record for one turn.
- *
- * `served` is the target a backend request was actually DISPATCHED to, or `null`
- * when none was — a guardrail rejection, a routing error, an admin endpoint, or
- * anything answered locally. It is a required parameter, without a default, so
- * `tsc` names every call site that has not decided which of the two it is; a
- * default would quietly turn "nobody decided" into a confident claim.
- *
- * The model the CLIENT asked for is deliberately NOT recorded (OBS-b5ade458 is
- * finished): routing resolves a tier/pool spec to a `ResolvedTarget`, so it is
- * routinely not the model that answered, and it was the id every "which model
- * trips the validator" reading of this log was attributed to.
- */
 function pickString(obj, key) {
     if (typeof obj === "object" && obj !== null) {
         const v = obj[key];