@centerforagenticai/pi-multi-account 0.1.4 → 0.1.5

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Global Anthropic and OpenAI Codex multi-account OAuth routing for Pi.",
   "type": "module",
   "bin": {

package/packages/pi-anthropic-oauth/src/stream.ts

@@ -221,10 +221,18 @@ export function streamAnthropicOAuth(
       // which throws under fine-grained-tool-streaming (input may be invalid
       // mid-flight) and aborts the turn. The raw stream yields the same
       // RawMessageStreamEvents; tool args are already parsed leniently below.
+      // A finite non-negative integer request-local maxRetries bounds the SDK's
+      // own retries (0 sends exactly once); any other value keeps the SDK default.
+      const maxRetries = options?.maxRetries;
       const { data: anthropicStream, response: httpResponse } =
         await client.messages
           .create(params, {
             signal: options?.signal,
+            ...(Number.isFinite(maxRetries) &&
+            Number.isInteger(maxRetries) &&
+            (maxRetries ?? -1) >= 0
+              ? { maxRetries }
+              : {}),
           })
           .withResponse();
 

package/src/codex-adapter.ts

@@ -193,14 +193,81 @@ function withAliasEvent(
   }
 }
 
+/**
+ * One attributed, sanitized error terminal for an upstream that failed before
+ * producing a stream (a synchronous throw, a rejected setup, or a throwing
+ * iterator). The shape matches the host's own setup-error terminal: no content,
+ * zero usage, no diagnostics. Only the bounded, redacted error text survives.
+ * A failure after the caller's signal fired is a cancellation: it ends as
+ * `aborted`, matching the maintained stream, so it never cools the account.
+ */
+function aliasSetupErrorMessage(
+  error: unknown,
+  aliasModel: Model<Api>,
+  aborted: boolean,
+): AssistantMessage & { stopReason: "error" | "aborted" } {
+  let detail: string;
+  try {
+    detail = error instanceof Error ? error.message : String(error);
+  } catch {
+    detail = "Codex alias stream setup failed";
+  }
+  return {
+    role: "assistant",
+    content: [],
+    api: aliasModel.api,
+    provider: aliasModel.provider,
+    model: aliasModel.id,
+    usage: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 0,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    },
+    stopReason: aborted ? "aborted" : "error",
+    errorMessage: sanitizeDiagnosticText(detail),
+    timestamp: Date.now(),
+  };
+}
+
+function isTerminalEvent(event: AssistantMessageEvent): boolean {
+  return event.type === "done" || event.type === "error";
+}
+
+/**
+ * Forwards upstream events with alias attribution. Every failure mode ends in
+ * exactly one terminal: a rejected setup or a throwing iterator before any
+ * terminal becomes one attributed error event, and the attributed stream always
+ * ends, so no failure escapes as an unhandled rejection or a hang.
+ */
 function reattributeStream(
-  upstream: AssistantMessageEventStream,
+  upstream: AssistantMessageEventStream | PromiseLike<AssistantMessageEventStream>,
   aliasModel: Model<Api>,
+  signal: AbortSignal | undefined,
 ): AssistantMessageEventStream {
   const attributed = createAssistantMessageEventStream();
   void (async () => {
-    for await (const event of upstream) {
-      attributed.push(withAliasEvent(event, aliasModel));
+    let sawTerminal = false;
+    try {
+      for await (const event of await upstream) {
+        if (sawTerminal) continue;
+        if (isTerminalEvent(event)) sawTerminal = true;
+        attributed.push(withAliasEvent(event, aliasModel));
+      }
+    } catch (error) {
+      if (!sawTerminal) {
+        sawTerminal = true;
+        const message = aliasSetupErrorMessage(
+          error,
+          aliasModel,
+          signal?.aborted === true,
+        );
+        attributed.push({ type: "error", reason: message.stopReason, error: message });
+      }
+    } finally {
+      attributed.end();
     }
   })();
   return attributed;
@@ -296,10 +363,17 @@ export function createCodexAliasStream(
       };
     }
 
-    return reattributeStream(
-      upstream(upstreamModel, upstreamContext, upstreamOptions),
-      aliasModel,
-    );
+    // Defensive only under the live host: its `lazyApi` stream catches a setup
+    // throw first and returns its own setup-error terminal. A non-lazy upstream
+    // (plain Node) can still throw synchronously; convert that into the same
+    // single attributed, sanitized terminal as any other failure (UPSTREAM.md).
+    let upstreamStream: ReturnType<CodexUpstreamStream>;
+    try {
+      upstreamStream = upstream(upstreamModel, upstreamContext, upstreamOptions);
+    } catch (error) {
+      upstreamStream = Promise.reject(error) as unknown as ReturnType<CodexUpstreamStream>;
+    }
+    return reattributeStream(upstreamStream, aliasModel, options?.signal);
   };
   return aliasStream as unknown as NonNullable<ProviderConfig["streamSimple"]>;
 }

package/src/config.ts

@@ -29,6 +29,7 @@ import {
 } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { basename, dirname, isAbsolute, join } from "node:path";
+import { sanitizeDiagnosticText } from "./diagnostics.js";
 import { PROJECT_KEY_PATTERN } from "./project-identity.js";
 import {
 	AccountRateHistoryError,
@@ -167,6 +168,15 @@ export interface CrossFamilyChain {
 	readonly to: AllowedFamily;
 }
 
+/** One exact, directional model-substitution egress authorization. */
+export interface ModelFallbackEgressAuthorization {
+	readonly sourceModelId: string;
+	readonly destinationModelId: string;
+}
+
+/** Exact source unified model id -> ordered exact fallback model ids. */
+export type ModelFallbackMap = Readonly<Record<string, readonly string[]>>;
+
 export interface MultiAccountConfig {
 	readonly accountLimit: number;
 	readonly sameFamilyFailover: boolean;
@@ -238,6 +248,10 @@ export interface MultiAccountConfig {
 	 */
 	readonly preferredModels: Readonly<Record<string, readonly string[]>>;
 	readonly tierModelMap: TierModelMap;
+	/** Explicit ordered fallback policy. Absent or empty disables model substitution. */
+	readonly modelFallbacks?: ModelFallbackMap;
+	/** Directional authorization required in addition to policy for cross-vendor edges. */
+	readonly modelFallbackEgress?: readonly ModelFallbackEgressAuthorization[];
 	/**
 	 * How close to expiry a credential may get before routing prefers a fresher
 	 * same-family account, in milliseconds. Pre-emption avoids spending a turn to
@@ -284,6 +298,8 @@ export const DEFAULT_CONFIG: MultiAccountConfig = {
 	accountRateHistory: {},
 	preferredModels: {},
 	tierModelMap: Object.freeze({}),
+	modelFallbacks: Object.freeze({}),
+	modelFallbackEgress: Object.freeze([]),
 	// Comfortably longer than a turn, short enough that accounts are not retired
 	// while they still have useful life.
 	preemptiveExpiryWindowMs: 120_000,
@@ -309,6 +325,8 @@ const CONFIG_KEYS = new Set<keyof MultiAccountConfig>([
 	"accountRateHistory",
 	"preferredModels",
 	"tierModelMap",
+	"modelFallbacks",
+	"modelFallbackEgress",
 	"preemptiveExpiryWindowMs",
 	"usageFetchEnabled",
 ]);
@@ -689,6 +707,135 @@ function isValidTierModelId(value: unknown): value is string {
 	);
 }
 
+export const MAX_MODEL_FALLBACK_SOURCES = 128;
+export const MAX_MODEL_FALLBACK_DESTINATIONS = 16;
+export const MAX_MODEL_FALLBACK_EDGES = 256;
+/**
+ * Exact catalog ids: managed wire ids, OpenRouter `vendor/model[:variant]`
+ * slugs, and the `~vendor/...` and `@cf/...` forms in the pinned catalog.
+ */
+const MODEL_FALLBACK_ID_PATTERN = /^[A-Za-z0-9~@][A-Za-z0-9._:/@~-]{0,255}$/;
+
+/**
+ * A fallback id may later appear in routing diagnostics, so it is accepted only
+ * when the shared diagnostic sanitizer would leave it byte-for-byte unchanged.
+ * Anything the sanitizer would redact anywhere in the string (credential
+ * prefixes, JWTs, token/canary shapes, long opaque runs) is rejected here, and
+ * the rejection message never echoes the value.
+ */
+function isValidModelFallbackId(value: unknown): value is string {
+	return (
+		typeof value === "string" &&
+		MODEL_FALLBACK_ID_PATTERN.test(value) &&
+		sanitizeDiagnosticText(value) === value
+	);
+}
+
+function invalidModelFallbackId(field: string): ConfigValidationError {
+	return new ConfigValidationError(
+		`${field} must use an exact, non-credential model id of at most 256 characters.`,
+	);
+}
+
+function parseModelFallbacks(value: unknown): ModelFallbackMap {
+	if (value === undefined) return DEFAULT_CONFIG.modelFallbacks ?? Object.freeze({});
+	if (!isPlainObject(value)) {
+		throw new ConfigValidationError("modelFallbacks must be a plain JSON object.");
+	}
+	const entries = Object.entries(value);
+	if (entries.length > MAX_MODEL_FALLBACK_SOURCES) {
+		throw new ConfigValidationError(
+			`modelFallbacks must contain at most ${MAX_MODEL_FALLBACK_SOURCES} sources.`,
+		);
+	}
+	const parsed = Object.create(null) as Record<string, readonly string[]>;
+	for (const [sourceModelId, rawDestinations] of entries) {
+		if (!isValidModelFallbackId(sourceModelId)) {
+			throw invalidModelFallbackId("modelFallbacks source ids");
+		}
+		if (!Array.isArray(rawDestinations) || rawDestinations.length === 0) {
+			throw new ConfigValidationError(
+				"modelFallbacks values must be non-empty arrays of model ids.",
+			);
+		}
+		if (rawDestinations.length > MAX_MODEL_FALLBACK_DESTINATIONS) {
+			throw new ConfigValidationError(
+				`modelFallbacks may contain at most ${MAX_MODEL_FALLBACK_DESTINATIONS} destinations per source.`,
+			);
+		}
+		const destinations: string[] = [];
+		const seen = new Set<string>();
+		for (const destinationModelId of rawDestinations) {
+			if (!isValidModelFallbackId(destinationModelId)) {
+				throw invalidModelFallbackId("modelFallbacks destination ids");
+			}
+			if (destinationModelId === sourceModelId) {
+				throw new ConfigValidationError(
+					"modelFallbacks cannot list the source model as its own destination.",
+				);
+			}
+			if (seen.has(destinationModelId)) {
+				throw new ConfigValidationError(
+					"modelFallbacks cannot contain duplicate destinations for one source.",
+				);
+			}
+			seen.add(destinationModelId);
+			destinations.push(destinationModelId);
+		}
+		parsed[sourceModelId] = Object.freeze(destinations);
+	}
+	return Object.freeze(parsed);
+}
+
+function parseModelFallbackEgress(
+	value: unknown,
+): readonly ModelFallbackEgressAuthorization[] {
+	if (value === undefined) return DEFAULT_CONFIG.modelFallbackEgress ?? Object.freeze([]);
+	if (!Array.isArray(value)) {
+		throw new ConfigValidationError("modelFallbackEgress must be an array.");
+	}
+	if (value.length > MAX_MODEL_FALLBACK_EDGES) {
+		throw new ConfigValidationError(
+			`modelFallbackEgress must contain at most ${MAX_MODEL_FALLBACK_EDGES} edges.`,
+		);
+	}
+	const parsed: ModelFallbackEgressAuthorization[] = [];
+	const seen = new Set<string>();
+	for (const candidate of value) {
+		if (!isPlainObject(candidate)) {
+			throw new ConfigValidationError("modelFallbackEgress entries must be plain objects.");
+		}
+		const unknownKeys = Object.keys(candidate).filter(
+			(key) => key !== "sourceModelId" && key !== "destinationModelId",
+		);
+		if (unknownKeys.length > 0) {
+			throw new ConfigValidationError(
+				"modelFallbackEgress entries contain an unsupported field.",
+			);
+		}
+		const sourceModelId = candidate["sourceModelId"];
+		const destinationModelId = candidate["destinationModelId"];
+		if (!isValidModelFallbackId(sourceModelId)) {
+			throw invalidModelFallbackId("modelFallbackEgress sourceModelId");
+		}
+		if (!isValidModelFallbackId(destinationModelId)) {
+			throw invalidModelFallbackId("modelFallbackEgress destinationModelId");
+		}
+		if (sourceModelId === destinationModelId) {
+			throw new ConfigValidationError(
+				"modelFallbackEgress cannot authorize a model to itself.",
+			);
+		}
+		const key = `${sourceModelId}\u0000${destinationModelId}`;
+		if (seen.has(key)) {
+			throw new ConfigValidationError("modelFallbackEgress cannot contain duplicate edges.");
+		}
+		seen.add(key);
+		parsed.push(Object.freeze({ sourceModelId, destinationModelId }));
+	}
+	return Object.freeze(parsed);
+}
+
 export function parseTierModelMap(value: unknown): TierModelMap {
 	if (value === undefined) return DEFAULT_CONFIG.tierModelMap;
 	if (!isRecord(value)) {
@@ -1119,6 +1266,8 @@ export function parseConfig(value: unknown): MultiAccountConfig {
 	const accountRateHistory = parseAccountRateHistory(value["accountRateHistory"]);
 	const preferredModels = parsePreferredModels(value["preferredModels"]);
 	const tierModelMap = parseTierModelMap(value["tierModelMap"]);
+	const modelFallbacks = parseModelFallbacks(value["modelFallbacks"]);
+	const modelFallbackEgress = parseModelFallbackEgress(value["modelFallbackEgress"]);
 	const preemptiveExpiryWindowMs =
 		value["preemptiveExpiryWindowMs"] ??
 		DEFAULT_CONFIG.preemptiveExpiryWindowMs;
@@ -1206,6 +1355,8 @@ export function parseConfig(value: unknown): MultiAccountConfig {
 		accountRateHistory,
 		preferredModels,
 		tierModelMap,
+		modelFallbacks,
+		modelFallbackEgress,
 		preemptiveExpiryWindowMs,
 		usageFetchEnabled,
 	};

package/src/host-final-stop-message.ts

@@ -10,6 +10,13 @@ export const REFUSAL_FALLBACK_MESSAGE = "The model refused to complete the reque
 export const UNKNOWN_STOP_FALLBACK_MESSAGE =
 	"Provider stopped with an unrecognized stop reason";
 
+/**
+ * Appended when a reworded unknown stop reason omits words a host predicate acts
+ * on, so the published reason does not read as complete. Neither pinned
+ * predicate matches it, and the marked message is probed again before use.
+ */
+export const PARTLY_WITHHELD_MARKER = " (partly withheld)";
+
 /** Upper bound on the normalized stop reason named in a reworded message. */
 const MAX_NAMED_REASON_LENGTH = 64;
 
@@ -23,7 +30,7 @@ const MAX_NAMED_REASON_LENGTH = 64;
  * An unreadable predicate result counts as a match, so the caller keeps looking
  * for a safer form.
  */
-function hostWouldRedispatch(message: AssistantMessage, text: string): boolean {
+export function hostWouldRedispatch(message: AssistantMessage, text: string): boolean {
 	try {
 		const probe = { ...message, errorMessage: text };
 		return isRetryableAssistantError(probe) || isContextOverflow(probe, 0);
@@ -68,8 +75,9 @@ function normalizedReasonWords(rawStopReason: unknown): string[] {
  * The first form keeps every normalized word. When that still matches a host
  * predicate (a reason containing "overloaded" or "timeout", say), the second
  * form admits words in order and drops each one whose addition would make the
- * message match. Every admitted prefix was probed, so the result is host-final
- * by construction. An empty result yields `undefined`.
+ * message match. When any word was dropped the result ends with
+ * `PARTLY_WITHHELD_MARKER`; that marked text is probed too, and an unsafe or
+ * empty result yields `undefined`.
  */
 function unknownStopNamingReason(
 	message: AssistantMessage,
@@ -84,7 +92,11 @@ function unknownStopNamingReason(
 		const tentative = namedReasonMessage([...kept, word].join(" "));
 		if (!hostWouldRedispatch(message, tentative)) kept.push(word);
 	}
-	return kept.length === 0 ? undefined : namedReasonMessage(kept.join(" "));
+	if (kept.length === 0) return undefined;
+	const named = namedReasonMessage(kept.join(" "));
+	if (kept.length === words.length) return named;
+	const marked = `${named}${PARTLY_WITHHELD_MARKER}`;
+	return hostWouldRedispatch(message, marked) ? undefined : marked;
 }
 
 /**

package/src/index.ts

@@ -80,6 +80,7 @@ import {
 import { DiagnosticStore } from "./diagnostic-store.js";
 import { DeclarationNoticeMarker } from "./declaration-notice-marker.js";
 import { DiagnosticLog } from "./diagnostics.js";
+import { createRefusalAdvisor } from "./refusal-advice.js";
 import {
 	classifyProviderId,
 	createPublicAuthStorageAdapter,
@@ -4159,6 +4160,9 @@ export const createMultiAccountExtension =
 		const lastFailure = new Map<string, ProviderFailureSignal>();
 		const handledFailures = new WeakSet<object>();
 		const observedMessages = new WeakSet<object>();
+		// Operator advice for a structured refusal. A delegate-owned in-process
+		// session shares the foreground UI, so only the foreground advises.
+		const refusalAdvisor = createRefusalAdvisor({ foreground: !delegateOwnedSession });
 		const recordUsage = (
 			observation: () => UsageObservation | undefined,
 		): void => {
@@ -5153,6 +5157,17 @@ export const createMultiAccountExtension =
 						acceptedLogicalAssociation,
 					);
 				}
+				// Advice only: names the physical route that refused, never routes.
+				refusalAdvisor.advise(
+					originalMessage,
+					messageContext,
+					acceptedLogicalAssociation && logicalAssociation !== undefined
+						? {
+								providerId: logicalAssociation.route.providerId,
+								modelId: logicalAssociation.dispatchedModelId,
+							}
+						: {},
+				);
 
 				try {
 					const validOriginalMessage = originalMessage as AssistantMessage;
@@ -5240,6 +5255,8 @@ export const createMultiAccountExtension =
 			) {
 				return;
 			}
+			// Advice only: a managed account's structured refusal never routes.
+			refusalAdvisor.advise(event.message, messageContext, identity);
 			const subscriptionFamily = isRoutingEligibleAccountFamily(messageSlot)
 				? messageSlot.family
 				: undefined;

package/src/logical-provider.ts

@@ -16,6 +16,7 @@
 import { logicalAccountEligible, recordFailureCooldown } from "./routing.js";
 import type { ManagedAccount } from "./routing.js";
 import {
+	isContextOverflow,
 	isRetryableAssistantError,
 	type AssistantMessage,
 	type ProviderResponse,
@@ -353,6 +354,36 @@ const EXHAUSTION_LENGTH_ALLOWANCE_MULTIPLIER = 8;
 const EXHAUSTION_LENGTH_MAX_CONTEXT_FRACTION = 0.8;
 const EXHAUSTION_LENGTH_ERROR_MESSAGE = "provider returned error (usage-limit)";
 
+/**
+ * Fixed public text for a setup-shaped context overflow. The pinned host's
+ * `isContextOverflow` matches it (so the host compacts and retries once) and
+ * `isRetryableAssistantError` does not (so the host does not fail over).
+ */
+export const SETUP_CONTEXT_OVERFLOW_MESSAGE = "context_length_exceeded (provider_error)";
+
+type SetupFailureDisposition = "context-overflow" | "retryable" | "host-final";
+
+/**
+ * How the pinned host treats the raw setup text. The host checks the two
+ * predicates separately: `_handlePostAgentRun` compacts and retries once on
+ * `isContextOverflow`, while `_isRetryableError` excludes overflow and fails
+ * over on `isRetryableAssistantError`. An unreadable predicate result counts
+ * as host-final.
+ */
+function setupFailureDisposition(
+	message: AssistantMessage,
+	raw: unknown,
+): SetupFailureDisposition {
+	if (typeof raw !== "string" || raw.length === 0) return "host-final";
+	try {
+		const probe = { ...message, errorMessage: raw };
+		if (isContextOverflow(probe, 0)) return "context-overflow";
+		return isRetryableAssistantError(probe) ? "retryable" : "host-final";
+	} catch {
+		return "host-final";
+	}
+}
+
 function finiteNonNegative(value: unknown): number | undefined {
 	return typeof value === "number" && Number.isFinite(value) && value >= 0
 		? value
@@ -542,6 +573,54 @@ function projectFailureSignal(
 	};
 }
 
+/**
+ * Whether a physical terminal is the host's setup-error shape: the first event
+ * of the stream is an `error` with no content, all-zero usage, no diagnostics,
+ * no structured stop code, and no structured failure evidence.
+ *
+ * That is what pi-ai `lazyStream` (`createSetupErrorMessage`) publishes when a
+ * provider stream throws or rejects before it starts, so its `errorMessage` is
+ * raw exception text, not provider-authored failure prose. The production cause
+ * of the observed setup `TypeError` is not known (see UPSTREAM.md). The same
+ * shape also carries transient pre-start failures ("fetch failed", a 503 before
+ * `start`), so the caller decides retryability from the text, never publishes
+ * it. A real provider failure that carries a recognized code or status keeps
+ * its own text and routing.
+ */
+function isUnclassifiedSetupFailure(
+	message: AssistantMessage,
+	failure: ProviderFailureSignal,
+): boolean {
+	try {
+		if (message.stopReason !== "error") return false;
+		if (!Array.isArray(message.content) || message.content.length !== 0) return false;
+		const diagnostics = (message as { diagnostics?: unknown }).diagnostics;
+		if (diagnostics !== undefined && !(Array.isArray(diagnostics) && diagnostics.length === 0)) {
+			return false;
+		}
+		if ((message as { code?: unknown }).code !== undefined) return false;
+		const usage = projectTerminalUsage(message);
+		if (
+			usage === undefined ||
+			usage.input !== 0 ||
+			usage.output !== 0 ||
+			usage.cacheRead !== 0 ||
+			usage.cacheWrite !== 0 ||
+			usage.totalTokens !== 0 ||
+			usage.cost.total !== 0
+		) {
+			return false;
+		}
+		return (
+			failure.code === undefined &&
+			failure.httpStatus === undefined &&
+			failure.transportKind === undefined
+		);
+	} catch {
+		return false;
+	}
+}
+
 function safeProjectFailureSignal(
 	error: unknown,
 	modelId: string,
@@ -964,6 +1043,18 @@ export function createLogicalProvider(
 		return { ...candidate, [key]: projectMessage(value as AssistantMessage, modelId) };
 	};
 
+	const withPublicErrorMessage = (event: unknown, errorMessage: string): unknown => {
+		if (typeof event !== "object" || event === null) return event;
+		const candidate = event as Record<string, unknown>;
+		if (candidate.type !== "error" || typeof candidate.error !== "object" || candidate.error === null) {
+			return event;
+		}
+		return {
+			...candidate,
+			error: { ...(candidate.error as AssistantMessage), errorMessage },
+		};
+	};
+
 	const watchStream = (
 		stream: AsyncIterable<unknown>,
 		model: unknown,
@@ -975,6 +1066,7 @@ export function createLogicalProvider(
 	): AsyncIterable<unknown> => ({
 		async *[Symbol.asyncIterator]() {
 			let sawTerminal = false;
+			let sawEvent = false;
 			let failureReceipt: HostRetryCooldownReceipt | undefined;
 			const recordFailureOnce = (error: unknown): HostRetryCooldownReceipt => {
 				failureReceipt ??= coordinator.recordFailure({
@@ -1016,7 +1108,10 @@ export function createLogicalProvider(
 							? (event as { type?: unknown }).type
 							: undefined;
 					if (eventType === "done" || eventType === "error") sawTerminal = true;
+					const firstEvent = !sawEvent;
+					sawEvent = true;
 					const terminal = terminalAttribution(event);
+					let setupFailureMessage: string | undefined;
 					if (terminal !== undefined) {
 						const { message, outcome } = terminal;
 						if (outcome === "finish") {
@@ -1048,10 +1143,41 @@ export function createLogicalProvider(
 						} else {
 							const failure = safeProjectFailureSignal(message, dispatchedModelId);
 							attributeFailure(message, failure, recordFailureOnce(message));
+							if (firstEvent && isUnclassifiedSetupFailure(message, failure)) {
+								// The physical account is cooled above exactly like any other
+								// failure. Only the published text changes: the raw text is
+								// replaced by the bounded classified message the
+								// rejected-dispatch path uses, so it is never published. The
+								// setup shape is shared by transient pre-start failures ("fetch
+								// failed", a 503 before `start`), pre-start context overflows
+								// (a Codex 400 or Anthropic 413), and deterministic setup throws.
+								// The raw text decides the form: an overflow publishes a fixed
+								// overflow message so the host compacts instead of failing
+								// over; a host-retryable text keeps the retryable form and
+								// fails over; anything else is host-final (`provider_error`),
+								// so a deterministic fault is not repeated on the next account.
+								const disposition = setupFailureDisposition(message, message.errorMessage);
+								setupFailureMessage =
+									disposition === "context-overflow"
+										? SETUP_CONTEXT_OVERFLOW_MESSAGE
+										: classifiedErrorMessage(failure, disposition === "retryable");
+								try {
+									deps.onDiagnostic?.(
+										`logical dispatch for ${account.providerId} failed during stream setup; ` +
+											"published a classified failure instead of the raw setup error",
+									);
+								} catch {
+									// A diagnostic sink failure cannot replace a provider result.
+								}
+							}
 						}
 						await attempt.waitForTerminal();
 					}
-					const publicEvent = projectEvent(event, requestedModelId);
+					const projectedEvent = projectEvent(event, requestedModelId);
+					const publicEvent =
+						setupFailureMessage === undefined
+							? projectedEvent
+							: withPublicErrorMessage(projectedEvent, setupFailureMessage);
 					if (terminal !== undefined && publicEvent !== event) {
 						const publicTerminal = terminalAttribution(publicEvent);
 						if (publicTerminal !== undefined) {