@centerforagenticai/pi-multi-account 0.1.5 → 0.1.6

package/src/anthropic-adaptive-stream.ts

@@ -35,6 +35,7 @@ import {
   type Api,
   type AssistantMessage,
   type AssistantMessageEventStream,
+  type JsonObject,
   calculateCost,
   type Context,
   createAssistantMessageEventStream,
@@ -53,7 +54,7 @@ type IndexedBlock =
       type: "toolCall";
       id: string;
       name: string;
-      arguments: Record<string, unknown>;
+      arguments: JsonObject;
       partialJson: string;
     } & { index: number });
 type UpstreamHelpers = {
@@ -67,15 +68,20 @@ type UpstreamHelpers = {
   convertPiToolsToAnthropic: (tools: NonNullable<Context["tools"]>, isOAuth: boolean) => unknown;
   fromClaudeCodeToolName: (name: string, tools?: NonNullable<Context["tools"]>) => string;
   buildAnthropicSystemPrompt: (systemPrompt: string | undefined, isOAuth: boolean) => unknown;
+  transportActivityListener: (options: unknown) => (() => void) | undefined;
+  createTransportActivityFetch: (onActivity: () => void) => typeof fetch;
 };
 
 const upstreamAuthPath = "../packages/pi-anthropic-oauth/src/auth.ts";
 const upstreamConvertPath = "../packages/pi-anthropic-oauth/src/convert.ts";
 const upstreamPromptPath = "../packages/pi-anthropic-oauth/src/prompt.ts";
+const upstreamTransportActivityPath =
+  "../packages/pi-anthropic-oauth/src/transport-activity.ts";
 const upstreamHelpers = {
   ...(await import(upstreamAuthPath)),
   ...(await import(upstreamConvertPath)),
   ...(await import(upstreamPromptPath)),
+  ...(await import(upstreamTransportActivityPath)),
 } as unknown as UpstreamHelpers;
 const {
   isClaudeOAuthAccessToken,
@@ -84,6 +90,8 @@ const {
   convertPiToolsToAnthropic,
   fromClaudeCodeToolName,
   buildAnthropicSystemPrompt,
+  transportActivityListener,
+  createTransportActivityFetch,
 } = upstreamHelpers;
 
 const REQUIRED_BETAS = [
@@ -230,12 +238,19 @@ export function streamAnthropicAdaptive(
 
       if (isOAuth) defaultHeaders.authorization = `Bearer ${apiKey}`;
 
+      // A caller that supplies onTransportActivity hears about every response
+      // body chunk, including the pings the SDK drops; otherwise the SDK keeps
+      // its default fetch.
+      const onTransportActivity = transportActivityListener(options);
       const client = new Anthropic({
         baseURL: model.baseUrl,
         apiKey: isOAuth ? null : apiKey,
         authToken: isOAuth ? apiKey : null,
         defaultHeaders,
         dangerouslyAllowBrowser: true,
+        ...(onTransportActivity === undefined
+          ? {}
+          : { fetch: createTransportActivityFetch(onTransportActivity) }),
       });
 
       const maxTokens =
@@ -468,10 +483,7 @@ export function streamAnthropicAdaptive(
           ) {
             block.partialJson += event.delta.partial_json;
             try {
-              block.arguments = JSON.parse(block.partialJson) as Record<
-                string,
-                unknown
-              >;
+              block.arguments = JSON.parse(block.partialJson) as JsonObject;
             } catch {}
             stream.push({
               type: "toolcall_delta",
@@ -507,10 +519,7 @@ export function streamAnthropicAdaptive(
             });
           } else if (block.type === "toolCall") {
             try {
-              block.arguments = JSON.parse(block.partialJson) as Record<
-                string,
-                unknown
-              >;
+              block.arguments = JSON.parse(block.partialJson) as JsonObject;
             } catch {}
             delete (block as { partialJson?: string }).partialJson;
             stream.push({

package/src/anthropic-alias-stream.ts

@@ -1,23 +1,26 @@
 import {
   createAssistantMessageEventStream,
   type Api,
-  type AssistantMessage,
-  type AssistantMessageEvent,
   type AssistantMessageEventStream,
-  type Context,
   type Model,
+  type Context,
+  type TranscriptContext,
   type ProviderResponse,
   type SimpleStreamOptions,
 } from "@earendil-works/pi-ai";
-import {
-  sanitizeDiagnosticText,
-  sanitizeHeaderValue,
-} from "./diagnostics.js";
-import { hostFinalStopMessage } from "./host-final-stop-message.js";
+import { projectResponseHeaders } from "./diagnostics.js";
+import { projectAliasAssistantEvent } from "./public-assistant-projection.js";
 
 export const ANTHROPIC_ALIAS_API = "hypha-anthropic-oauth" as const;
 
 export type AnthropicUpstreamStream = (
+  model: Model<Api>,
+  context: Context | TranscriptContext,
+  options?: SimpleStreamOptions,
+) => AssistantMessageEventStream;
+
+/** Legacy Pi 0.84 context-shaped stream consumed by the exact-provenance adaptive adapter. */
+export type AnthropicLegacyStream = (
   model: Model<Api>,
   context: Context,
   options?: SimpleStreamOptions,
@@ -33,68 +36,10 @@ export function sanitizeAnthropicProviderResponse(
 ): ProviderResponse {
   return {
     status: response.status,
-    headers: Object.fromEntries(
-      Object.entries(response.headers).map(([name, value]) => [
-        sanitizeDiagnosticText(name),
-        sanitizeHeaderValue(name, value),
-      ]),
-    ),
-  };
-}
-
-function withAliasAttribution(
-  message: AssistantMessage,
-  aliasModel: Model<Api>,
-): AssistantMessage {
-  return {
-    ...message,
-    api: aliasModel.api,
-    provider: aliasModel.provider,
-    model: aliasModel.id,
+    headers: projectResponseHeaders(response.headers),
   };
 }
 
-/**
- * Bounds an upstream error and, for a structured refusal or unknown stop,
- * publishes the shared host-final message. A direct alias turn reaches the
- * host's retry and compaction predicates without the unified provider, so
- * provider-authored stop wording must not make the host resend the request.
- */
-function sanitizeUpstreamError(message: AssistantMessage): AssistantMessage {
-  if (message.errorMessage === undefined) return message;
-  const sanitized: AssistantMessage = {
-    ...message,
-    errorMessage: sanitizeDiagnosticText(message.errorMessage),
-  };
-  return { ...sanitized, ...hostFinalStopMessage(sanitized) };
-}
-
-function withAliasEvent(
-  event: AssistantMessageEvent,
-  aliasModel: Model<Api>,
-): AssistantMessageEvent {
-  switch (event.type) {
-    case "done":
-      return {
-        ...event,
-        message: withAliasAttribution(event.message, aliasModel),
-      };
-    case "error":
-      return {
-        ...event,
-        error: withAliasAttribution(
-          sanitizeUpstreamError(event.error),
-          aliasModel,
-        ),
-      };
-    default:
-      return {
-        ...event,
-        partial: withAliasAttribution(event.partial, aliasModel),
-      };
-  }
-}
-
 function reattributeStream(
   upstream: AssistantMessageEventStream,
   aliasModel: Model<Api>,
@@ -103,7 +48,7 @@ function reattributeStream(
 
   void (async () => {
     for await (const event of upstream) {
-      attributed.push(withAliasEvent(event, aliasModel));
+      attributed.push(projectAliasAssistantEvent(event, aliasModel));
     }
   })();
 

package/src/codex-adapter.ts

@@ -28,9 +28,11 @@ import {
 import { cloneProviderModelCatalog } from "./catalog-rebinding.js";
 import {
   sanitizeDiagnosticText,
-  sanitizeHeaderValue,
+  projectResponseHeaders,
 } from "./diagnostics.js";
 
+import { projectAliasAssistantEvent } from "./public-assistant-projection.js";
+
 const CODEX_BASE_API = "openai-codex-responses" as const;
 /**
  * Keep alias models on Pi's host-known API id. The provider-scoped
@@ -141,56 +143,8 @@ type CodexUpstreamStream = (
   options?: SimpleStreamOptions,
 ) => AssistantMessageEventStream;
 
-function withAliasAttribution(
-  message: AssistantMessage,
-  aliasModel: Model<Api>,
-): AssistantMessage {
-  return {
-    ...message,
-    api: aliasModel.api,
-    provider: aliasModel.provider,
-    model: aliasModel.id,
-  };
-}
-
-function sanitizeUpstreamError(message: AssistantMessage): AssistantMessage {
-  if (message.errorMessage === undefined) return message;
-  return {
-    ...message,
-    errorMessage: sanitizeDiagnosticText(message.errorMessage),
-  };
-}
-
 function sanitizeProviderResponse(response: ProviderResponse): ProviderResponse {
-  return {
-    status: response.status,
-    headers: Object.fromEntries(
-      Object.entries(response.headers).map(([name, value]) => [
-        sanitizeDiagnosticText(name),
-        sanitizeHeaderValue(name, value),
-      ]),
-    ),
-  };
-}
-
-function withAliasEvent(
-  event: AssistantMessageEvent,
-  aliasModel: Model<Api>,
-): AssistantMessageEvent {
-  switch (event.type) {
-    case "done":
-      return { ...event, message: withAliasAttribution(event.message, aliasModel) };
-    case "error":
-      return {
-        ...event,
-        error: withAliasAttribution(
-          sanitizeUpstreamError(event.error),
-          aliasModel,
-        ),
-      };
-    default:
-      return { ...event, partial: withAliasAttribution(event.partial, aliasModel) };
-  }
+  return { status: response.status, headers: projectResponseHeaders(response.headers) };
 }
 
 /**
@@ -254,7 +208,7 @@ function reattributeStream(
       for await (const event of await upstream) {
         if (sawTerminal) continue;
         if (isTerminalEvent(event)) sawTerminal = true;
-        attributed.push(withAliasEvent(event, aliasModel));
+        attributed.push(projectAliasAssistantEvent(event, aliasModel));
       }
     } catch (error) {
       if (!sawTerminal) {

package/src/commands.ts

@@ -14,6 +14,7 @@ import {
 import { basename, dirname, join } from "node:path";
 import { randomUUID } from "node:crypto";
 import type { Api, Model } from "@earendil-works/pi-ai";
+import type { AccountGroupMemberAvailability } from "./account-group-members.js";
 import { acquireMachineLease } from "./machine-lease.js";
 import {
 	DECLARATION_BASE_URL,
@@ -290,9 +291,8 @@ export function declarationNoticeMessage(notice: DeclarationNotice): string {
 		: `LOGICAL ROUTING OFF: The managed model declaration is unreadable. Run ${notice.remedy}.`;
 }
 
-export interface AccountGroupCommandMemberStatus {
-	readonly providerId: string;
-	readonly eligible: boolean;
+export interface AccountGroupCommandMemberStatus extends Pick<AccountGroupMemberAvailability, "providerId" | "eligible"> {
+	/** Membership availability or an additional managed-routing/metered block. */
 	readonly reason: string;
 }
 

package/src/config.ts

@@ -30,6 +30,7 @@ import {
 import { randomUUID } from "node:crypto";
 import { basename, dirname, isAbsolute, join } from "node:path";
 import { sanitizeDiagnosticText } from "./diagnostics.js";
+import { isAccountGroupMemberReference } from "./account-group-members.js";
 import { PROJECT_KEY_PATTERN } from "./project-identity.js";
 import {
 	AccountRateHistoryError,
@@ -177,6 +178,9 @@ export interface ModelFallbackEgressAuthorization {
 /** Exact source unified model id -> ordered exact fallback model ids. */
 export type ModelFallbackMap = Readonly<Record<string, readonly string[]>>;
 
+/** Upper bound for `recoveryStallTimeoutMs`: one stalled attempt never waits longer. */
+export const MAX_RECOVERY_STALL_TIMEOUT_MS = 30 * 60_000;
+
 export interface MultiAccountConfig {
 	readonly accountLimit: number;
 	readonly sameFamilyFailover: boolean;
@@ -188,6 +192,14 @@ export interface MultiAccountConfig {
 	readonly recoveryIdleTimeoutMs: number;
 	/** Total elapsed time allowed for one complete recovery invocation. */
 	readonly recoveryAbsoluteTimeoutMs: number;
+	/**
+	 * Longest wait for the next event of one unified physical attempt, opening
+	 * included. A stall before any content ends that attempt as a pre-start
+	 * transient failure that may recover once on another account; a stall after
+	 * content ends the call with no retry. Must be less than
+	 * `recoveryIdleTimeoutMs`, so the stall fires before the invocation idles out.
+	 */
+	readonly recoveryStallTimeoutMs: number;
 	/**
 	 * Operator-chosen display labels keyed by canonical provider id, so managed
 	 * accounts are distinguishable in Pi's login list and the status view.
@@ -289,6 +301,7 @@ export const DEFAULT_CONFIG: MultiAccountConfig = {
 	cooldownMaxMs: 300_000,
 	recoveryIdleTimeoutMs: 5 * 60_000,
 	recoveryAbsoluteTimeoutMs: 30 * 60_000,
+	recoveryStallTimeoutMs: 3 * 60_000,
 	accountLabels: {},
 	projectLabels: {},
 	accountGroups: {},
@@ -315,6 +328,7 @@ const CONFIG_KEYS = new Set<keyof MultiAccountConfig>([
 	"cooldownMaxMs",
 	"recoveryIdleTimeoutMs",
 	"recoveryAbsoluteTimeoutMs",
+	"recoveryStallTimeoutMs",
 	"accountLabels",
 	"projectLabels",
 	"accountGroups",
@@ -961,10 +975,10 @@ function parseAccountGroups(
 		const providerIds = members.map((member, index) => {
 			if (
 				typeof member !== "string" ||
-				!isCanonicalSubscriptionAccountId(member, accountLimit)
+				!isAccountGroupMemberReference(member, accountLimit, MANAGED_FAMILIES)
 			) {
 				throw new ConfigValidationError(
-					`accountGroups.${groupId}[${index}] must be a canonical managed subscription provider id within accountLimit.`,
+					`accountGroups.${groupId}[${index}] must be a safe provider reference with canonical managed slots within accountLimit.`,
 				);
 			}
 			return member;
@@ -1327,6 +1341,35 @@ export function parseConfig(value: unknown): MultiAccountConfig {
 			);
 		}
 	}
+	// An omitted stall limit defaults below the effective idle limit, so a
+	// config that sets only a short `recoveryIdleTimeoutMs` stays valid and its
+	// stall can still fire first.
+	const recoveryStallTimeoutMs =
+		value["recoveryStallTimeoutMs"] ??
+		Math.min(
+			DEFAULT_CONFIG.recoveryStallTimeoutMs,
+			(recoveryIdleTimeoutMs as number) - 1,
+		);
+	if (
+		typeof recoveryStallTimeoutMs !== "number" ||
+		!Number.isFinite(recoveryStallTimeoutMs) ||
+		recoveryStallTimeoutMs < 1_000 ||
+		recoveryStallTimeoutMs > MAX_RECOVERY_STALL_TIMEOUT_MS
+	) {
+		throw new ConfigValidationError(
+			value["recoveryStallTimeoutMs"] === undefined
+				? "recoveryIdleTimeoutMs must be more than 1000 ms, so the 1000 ms minimum recoveryStallTimeoutMs can end first."
+				: `recoveryStallTimeoutMs must be a finite number from 1000 through ${MAX_RECOVERY_STALL_TIMEOUT_MS} ms.`,
+		);
+	}
+	// The engine's idle timer covers the whole invocation. A stall limit that is
+	// not shorter would let it abort the call before a stalled attempt could
+	// move to another account.
+	if (recoveryStallTimeoutMs >= (recoveryIdleTimeoutMs as number)) {
+		throw new ConfigValidationError(
+			"recoveryStallTimeoutMs must be less than recoveryIdleTimeoutMs.",
+		);
+	}
 	if (
 		typeof preemptiveExpiryWindowMs !== "number" ||
 		!Number.isFinite(preemptiveExpiryWindowMs) ||
@@ -1346,6 +1389,7 @@ export function parseConfig(value: unknown): MultiAccountConfig {
 		cooldownMaxMs,
 		recoveryIdleTimeoutMs: recoveryIdleTimeoutMs as number,
 		recoveryAbsoluteTimeoutMs: recoveryAbsoluteTimeoutMs as number,
+		recoveryStallTimeoutMs,
 		accountLabels,
 		projectLabels,
 		accountGroups,

package/src/diagnostic-store.ts

@@ -12,7 +12,11 @@ import { randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
 import {
 	sanitizeDiagnosticText,
+	projectResponseHeaders,
+	isHeaderDiagnostic,
+	HEADER_DIAGNOSTIC_MESSAGE,
 	sanitizeForJson,
+	retainDiagnosticEvents,
 	type DiagnosticEvent,
 	type DiagnosticLevel,
 	type DiagnosticPersistence,
@@ -84,13 +88,16 @@ function projectEvent(value: unknown): DiagnosticEvent | undefined {
 	if (typeof candidate.level !== "string" || !LEVELS.has(candidate.level as DiagnosticLevel)) {
 		return undefined;
 	}
-	const fields = projectFields(candidate.fields);
+	const fields = isHeaderDiagnostic(candidate.category, candidate.message)
+		? projectResponseHeaders(candidate.fields)
+		: projectFields(candidate.fields);
 	if (fields === undefined) return undefined;
 	return {
 		timestampMs: candidate.timestampMs,
 		level: candidate.level as DiagnosticLevel,
 		category: sanitizeDiagnosticText(candidate.category),
-		message: sanitizeDiagnosticText(candidate.message),
+		message: isHeaderDiagnostic(candidate.category, candidate.message)
+			? HEADER_DIAGNOSTIC_MESSAGE : sanitizeDiagnosticText(candidate.message),
 		fields,
 	};
 }
@@ -110,20 +117,15 @@ function parseCompleteEvents(raw: string): readonly DiagnosticEvent[] {
 	return events;
 }
 
-function newestLinesWithin(
+function priorityLinesWithin(
 	events: readonly DiagnosticEvent[],
 	budgetBytes: number,
 ): string {
-	const retained: string[] = [];
-	let used = 0;
-	for (let index = events.length - 1; index >= 0; index -= 1) {
-		const line = `${JSON.stringify(events[index])}\n`;
-		const bytes = Buffer.byteLength(line, "utf8");
-		if (bytes > budgetBytes - used) break;
-		retained.push(line);
-		used += bytes;
-	}
-	return retained.reverse().join("");
+	return retainDiagnosticEvents(
+		events,
+		budgetBytes,
+		(event) => Buffer.byteLength(`${JSON.stringify(event)}\n`, "utf8"),
+	).map((event) => `${JSON.stringify(event)}\n`).join("");
 }
 
 /** Machine-global, credential-free, bounded diagnostic event history. */
@@ -164,7 +166,7 @@ export class DiagnosticStore implements DiagnosticPersistence {
 			: 100;
 		if (safeLimit === 0) return [];
 		try {
-			return parseCompleteEvents(readFileSync(this.#path, "utf8")).slice(-safeLimit);
+			return retainDiagnosticEvents(parseCompleteEvents(readFileSync(this.#path, "utf8")), safeLimit);
 		} catch {
 			return [];
 		}
@@ -251,7 +253,7 @@ export class DiagnosticStore implements DiagnosticPersistence {
 				Math.floor(this.#maxBytes / 2),
 				this.#maxBytes - tailBytes,
 			);
-			const compacted = newestLinesWithin(events, targetBytes);
+			const compacted = priorityLinesWithin(events, targetBytes);
 			const encoded = compacted + tail;
 			if (Buffer.byteLength(encoded, "utf8") > this.#maxBytes) return false;
 			temporaryPath = `${this.#path}.${process.pid}.${randomUUID()}.tmp`;

package/src/diagnostics.ts

@@ -2,17 +2,38 @@ const MAX_DIAGNOSTIC_LENGTH = 512;
 const REDACTED = "[REDACTED]";
 const SENSITIVE_NAME_FRAGMENT = /(?:authorization|authentication|auth|token|credential|secret|cookie|apikey)/;
 const PRIVATE_REASONING_KEY = /^(?:thinking|reasoning)/;
-const TOKEN_QUOTA_REMAINING_HEADERS = new Set([
-  "x-ratelimit-remaining-tokens",
-  "x-ratelimit-tokens-remaining",
-  "anthropic-ratelimit-tokens-remaining",
+// Closed response observations: unknown names (including identifiers) never cross
+// the callback or retained-diagnostic boundary, even when their value looks safe.
+const COUNT_HEADERS = new Set([
+  "x-ratelimit-remaining", "x-ratelimit-remaining-requests", "x-ratelimit-requests-remaining",
+  "x-ratelimit-remaining-tokens", "x-ratelimit-tokens-remaining",
+  "anthropic-ratelimit-requests-remaining", "anthropic-ratelimit-tokens-remaining",
+  "x-ratelimit-limit-requests", "x-ratelimit-limit-tokens",
+  "anthropic-ratelimit-requests-limit", "anthropic-ratelimit-tokens-limit",
+  "retry-after-ms",
 ]);
-const TOKEN_QUOTA_DURATION_RESET_HEADERS = new Set([
-  "x-ratelimit-reset-tokens",
+const DURATION_RESET_HEADERS = new Set(["x-ratelimit-reset-requests", "x-ratelimit-reset-tokens"]);
+const ABSOLUTE_RESET_HEADERS = new Set([
+  "x-ratelimit-reset", "anthropic-ratelimit-requests-reset", "anthropic-ratelimit-tokens-reset",
+  "x-codex-primary-reset-at", "x-codex-secondary-reset-at",
 ]);
-const TOKEN_QUOTA_ABSOLUTE_RESET_HEADERS = new Set([
-  "anthropic-ratelimit-tokens-reset",
+const SECONDS_HEADERS = new Set([
+  "x-codex-primary-reset-after-seconds", "x-codex-secondary-reset-after-seconds",
 ]);
+const PERCENT_HEADERS = new Set(["x-codex-primary-used-percent", "x-codex-secondary-used-percent"]);
+const UTILIZATION_HEADERS = new Set([
+  "anthropic-ratelimit-unified-5h-utilization", "anthropic-ratelimit-unified-7d-utilization",
+  "anthropic-ratelimit-unified-7d-sonnet-utilization", "anthropic-ratelimit-unified-7d-opus-utilization",
+]);
+const STATUS_HEADERS = new Set(["anthropic-ratelimit-unified-status"]);
+const RESPONSE_HEADER_NAMES = new Set([
+  ...COUNT_HEADERS, ...DURATION_RESET_HEADERS, ...ABSOLUTE_RESET_HEADERS,
+  ...SECONDS_HEADERS, ...PERCENT_HEADERS, ...UTILIZATION_HEADERS, ...STATUS_HEADERS, "retry-after",
+]);
+export const HEADER_DIAGNOSTIC_MESSAGE = "Provider response headers observed.";
+export function isHeaderDiagnostic(category: unknown, message: unknown): boolean {
+  return category === "provider.response" || message === HEADER_DIAGNOSTIC_MESSAGE;
+}
 
 export type DiagnosticLevel = "info" | "warning" | "error";
 
@@ -128,22 +149,22 @@ function validAbsoluteReset(value: string): boolean {
   return Number.isFinite(epochMs) && epochMs >= 0 && new Date(epochMs).toUTCString() === value;
 }
 
-function validatedTokenQuotaValue(name: string, value: unknown): string | undefined {
+function validatedResponseHeaderValue(name: string, value: unknown): string | undefined {
   const normalized = name.toLowerCase();
-  const isTokenQuotaHeader = TOKEN_QUOTA_REMAINING_HEADERS.has(normalized)
-    || TOKEN_QUOTA_DURATION_RESET_HEADERS.has(normalized)
-    || TOKEN_QUOTA_ABSOLUTE_RESET_HEADERS.has(normalized);
-  if (!isTokenQuotaHeader || typeof value !== "string") return undefined;
-
-  const trimmed = value.trim();
-  if (value !== trimmed) return undefined;
-  if (TOKEN_QUOTA_REMAINING_HEADERS.has(normalized)) {
-    return validTokenCount(trimmed) ? trimmed : undefined;
+  if (!RESPONSE_HEADER_NAMES.has(normalized) || typeof value !== "string" || value !== value.trim()) return undefined;
+  if (COUNT_HEADERS.has(normalized)) return validTokenCount(value) ? value : undefined;
+  if (DURATION_RESET_HEADERS.has(normalized)) {
+    return validDuration(value) || validAbsoluteReset(value) ? value : undefined;
   }
-  if (TOKEN_QUOTA_DURATION_RESET_HEADERS.has(normalized)) {
-    return validDuration(trimmed) || validAbsoluteReset(trimmed) ? trimmed : undefined;
+  if (ABSOLUTE_RESET_HEADERS.has(normalized)) return validAbsoluteReset(value) ? value : undefined;
+  if (STATUS_HEADERS.has(normalized)) {
+    return ["allowed", "allowed_warning", "rejected"].includes(value) ? value : undefined;
   }
-  return validAbsoluteReset(trimmed) ? trimmed : undefined;
+  if (normalized === "retry-after" && validAbsoluteReset(value)) return value;
+  if (value.length > 32 || !/^\d+(?:\.\d+)?$/.test(value)) return undefined;
+  const number = Number(value);
+  const maximum = PERCENT_HEADERS.has(normalized) ? 100 : UTILIZATION_HEADERS.has(normalized) ? 1 : Number.MAX_SAFE_INTEGER / 1000;
+  return Number.isFinite(number) && number >= 0 && number <= maximum ? value : undefined;
 }
 
 /** Sanitizes and bounds one upstream-derived diagnostic value before storage. */
@@ -151,11 +172,20 @@ export function sanitizeDiagnosticText(value: unknown): string {
   return bound(redactDiagnosticText(value));
 }
 
-/** Sensitive headers are replaced wholesale except for strictly validated token-quota observations. */
+/** Compatibility scalar API; unsupported names and malformed observations are redacted. */
 export function sanitizeHeaderValue(name: string, value: unknown): string {
-  const tokenQuotaValue = validatedTokenQuotaValue(name, value);
-  if (tokenQuotaValue !== undefined) return tokenQuotaValue;
-  return isSensitiveName(name) ? REDACTED : sanitizeDiagnosticText(value);
+  return validatedResponseHeaderValue(name, value) ?? REDACTED;
+}
+
+/** Copy only named, validated quota/retry facts. Never retain caller keys or prose. */
+export function projectResponseHeaders(headers: unknown): Record<string, string> {
+  const projected: Record<string, string> = {};
+  if (typeof headers !== "object" || headers === null || Array.isArray(headers)) return projected;
+  for (const [name, value] of Object.entries(headers)) {
+    const validated = validatedResponseHeaderValue(name, value);
+    if (validated !== undefined) projected[name.toLowerCase()] = validated;
+  }
+  return projected;
 }
 
 function sanitizeFields(value: unknown, depth = 0): unknown {
@@ -202,6 +232,35 @@ export function sanitizedJson(value: unknown): string {
   return JSON.stringify(sanitizeForJson(value));
 }
 
+/**
+ * Reserve the budget for newest failures/routing facts before routine observations.
+ * Both classes share one hard bound; a priority flood evicts older priority facts.
+ * Return append order, not priority order or wall-clock order. Oversized records
+ * are skipped so one record cannot prevent smaller, useful facts from fitting.
+ */
+export function retainDiagnosticEvents(
+  events: readonly DiagnosticEvent[],
+  budget: number,
+  sizeOf: (event: DiagnosticEvent) => number = () => 1,
+): readonly DiagnosticEvent[] {
+  const retained = new Set<number>();
+  const sizes = events.map(sizeOf);
+  let used = 0;
+  for (const priority of [true, false]) {
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+      const event = events[index]!;
+      const isPriority = event.level !== "info" || event.category === "routing" ||
+        event.category.startsWith("routing.") || event.category === "logical.provider";
+      if (isPriority !== priority) continue;
+      const size = sizes[index]!;
+      if (size > budget - used) continue;
+      retained.add(index);
+      used += size;
+    }
+  }
+  return events.filter((_event, index) => retained.has(index));
+}
+
 export class DiagnosticLog {
   readonly #events: DiagnosticEvent[] = [];
   readonly #maxEvents: number;
@@ -224,7 +283,9 @@ export class DiagnosticLog {
       for (const event of persisted.slice(-this.#maxEvents)) {
         this.#events.push(Object.freeze({
           ...event,
-          fields: Object.freeze({ ...event.fields }),
+          message: isHeaderDiagnostic(event.category, event.message) ? HEADER_DIAGNOSTIC_MESSAGE : event.message,
+          fields: Object.freeze(isHeaderDiagnostic(event.category, event.message)
+            ? projectResponseHeaders(event.fields) : { ...event.fields }),
         }));
       }
     } catch {
@@ -239,18 +300,22 @@ export class DiagnosticLog {
     fields: Readonly<Record<string, unknown>> = {},
   ): DiagnosticEvent {
     const safeFields: Record<string, string> = {};
-    for (const [key, value] of Object.entries(fields)) {
+    const projectedFields = isHeaderDiagnostic(category, message) ? projectResponseHeaders(fields) : fields;
+    for (const [key, value] of Object.entries(projectedFields)) {
       safeFields[sanitizeDiagnosticText(key)] = sanitizeDiagnosticText(value);
     }
     const event = Object.freeze({
       timestampMs: this.#now(),
       level,
       category: sanitizeDiagnosticText(category),
-      message: sanitizeDiagnosticText(message),
+      message: isHeaderDiagnostic(category, message) ? HEADER_DIAGNOSTIC_MESSAGE : sanitizeDiagnosticText(message),
       fields: Object.freeze(safeFields),
     });
     this.#events.push(event);
-    if (this.#events.length > this.#maxEvents) this.#events.splice(0, this.#events.length - this.#maxEvents);
+    if (this.#events.length > this.#maxEvents) {
+      const retained = retainDiagnosticEvents(this.#events, this.#maxEvents);
+      this.#events.splice(0, this.#events.length, ...retained);
+    }
     try {
       this.#persistence?.append(event);
     } catch {
@@ -273,16 +338,13 @@ export class DiagnosticLog {
   }
 
   recordHeaders(category: string, headers: Readonly<Record<string, unknown>>): DiagnosticEvent {
-    const safeHeaders: Record<string, string> = {};
-    for (const [name, value] of Object.entries(headers)) {
-      safeHeaders[sanitizeDiagnosticText(name)] = sanitizeHeaderValue(name, value);
-    }
-    return this.record("info", category, "Provider response headers observed.", safeHeaders);
+    return this.record("info", category, HEADER_DIAGNOSTIC_MESSAGE, projectResponseHeaders(headers));
   }
 
   recent(limit = 20): readonly DiagnosticEvent[] {
     const safeLimit = Number.isSafeInteger(limit) ? Math.max(0, Math.min(limit, 100)) : 20;
-    return this.#events.slice(-safeLimit).map((event) => ({ ...event, fields: { ...event.fields } }));
+    return retainDiagnosticEvents(this.#events, safeLimit)
+      .map((event) => ({ ...event, fields: { ...event.fields } }));
   }
 
   formatRecent(limit = 20): string {