@centerforagenticai/pi-multi-account 0.1.4 → 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,66 +143,85 @@ type CodexUpstreamStream = (
   options?: SimpleStreamOptions,
 ) => AssistantMessageEventStream;
 
-function withAliasAttribution(
-  message: AssistantMessage,
+function sanitizeProviderResponse(response: ProviderResponse): ProviderResponse {
+  return { status: response.status, headers: projectResponseHeaders(response.headers) };
+}
+
+/**
+ * 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>,
-): AssistantMessage {
+  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 {
-    ...message,
+    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 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) };
-  }
+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(projectAliasAssistantEvent(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 +317,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/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

@@ -29,6 +29,8 @@ import {
 } from "node:fs";
 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,
@@ -167,6 +169,18 @@ 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[]>>;
+
+/** 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;
@@ -178,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.
@@ -238,6 +260,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
@@ -275,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: {},
@@ -284,6 +311,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,
@@ -299,6 +328,7 @@ const CONFIG_KEYS = new Set<keyof MultiAccountConfig>([
 	"cooldownMaxMs",
 	"recoveryIdleTimeoutMs",
 	"recoveryAbsoluteTimeoutMs",
+	"recoveryStallTimeoutMs",
 	"accountLabels",
 	"projectLabels",
 	"accountGroups",
@@ -309,6 +339,8 @@ const CONFIG_KEYS = new Set<keyof MultiAccountConfig>([
 	"accountRateHistory",
 	"preferredModels",
 	"tierModelMap",
+	"modelFallbacks",
+	"modelFallbackEgress",
 	"preemptiveExpiryWindowMs",
 	"usageFetchEnabled",
 ]);
@@ -689,6 +721,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)) {
@@ -814,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;
@@ -1119,6 +1280,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;
@@ -1178,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) ||
@@ -1197,6 +1389,7 @@ export function parseConfig(value: unknown): MultiAccountConfig {
 		cooldownMaxMs,
 		recoveryIdleTimeoutMs: recoveryIdleTimeoutMs as number,
 		recoveryAbsoluteTimeoutMs: recoveryAbsoluteTimeoutMs as number,
+		recoveryStallTimeoutMs,
 		accountLabels,
 		projectLabels,
 		accountGroups,
@@ -1206,6 +1399,8 @@ export function parseConfig(value: unknown): MultiAccountConfig {
 		accountRateHistory,
 		preferredModels,
 		tierModelMap,
+		modelFallbacks,
+		modelFallbackEgress,
 		preemptiveExpiryWindowMs,
 		usageFetchEnabled,
 	};