@centerforagenticai/pi-multi-account 0.1.4 → 0.1.6

package/README.md

@@ -6,7 +6,7 @@ Concurrent Anthropic, OpenAI Codex, and Google Antigravity OAuth accounts for Pi
 
 ## What it does
 
-When a managed account reaches a limit or loses authorization, `pi-multi-account` waits for Pi's own retries to settle, selects an eligible route, and sends one fixed continuation. It never replays the failed provider request.
+When a managed account reaches a limit or loses authorization, `pi-multi-account` waits for Pi's own retries to settle, selects an eligible route, and sends one fixed continuation. It never replays the failed provider request, with one bounded exception: a `unified` logical call that fails before showing any output may move once to another account serving the same model.
 
 - Registers numbered OAuth account aliases without copying credentials out of Pi's `AuthStorage`.
 - Routes within a provider family first, then through explicit owning-vendor or cross-family policy.
@@ -54,7 +54,7 @@ The extension reads one machine-global file and no project-local config:
 $PI_CODING_AGENT_DIR/pi-multi-account/config.json
 ```
 
-When `PI_CODING_AGENT_DIR` is unset, the root is `~/.pi/agent`. Missing configuration uses conservative defaults. Same-family failover and usage fetches ship on; cross-family routing and OpenRouter ship off. Malformed or unknown fields fail extension initialization closed while Pi keeps running.
+When `PI_CODING_AGENT_DIR` is unset, the root is `~/.pi/agent`. Missing configuration uses conservative defaults. Same-family failover and usage fetches ship on; cross-family routing and OpenRouter ship off. Malformed or unknown fields keep discovery, `/login`, and repair commands available, but block requests and automatic routing until valid config is loaded. Correct the global config and run `/multi-account reload` or `/reload`. A failed reload retains the last valid policy.
 
 | Key | Default | Purpose |
 | --- | --- | --- |
@@ -65,13 +65,27 @@ When `PI_CODING_AGENT_DIR` is unset, the root is `~/.pi/agent`. Missing configur
 | `accountGroups` and defaults | `{}` | Restrict a session, exact cwd, or global fallback to named account allow-lists. |
 | `usageFetchEnabled` | all managed families `true` | Enable fail-soft provider usage fetches. |
 
+Account groups may list exact configured Pi provider IDs, including built-in API
+and custom providers. Unknown, removed, or unavailable members stay inactive;
+other listed usable members can serve, with no fallback outside the group.
+Membership does not transfer credential or routing ownership to this extension.
+Under an active group, select physical models: host virtual models can choose
+other providers and are unsupported. Physical models on mixed providers still work.
+Unrestricted virtual selection keeps the host's behavior.
+When a group prevents `unified` selection, the turn error names the group, its
+original source, and a bounded cause. It reports outside-group availability
+without naming excluded accounts. This guidance does not authorize a send or
+prove that request credentials have resolved.
+Listing `openrouter` does not enable it: the current named-group metered block
+remains in force.
+
 The full schema, defaults, examples, timing controls, labels, and rate-history fields are in [Configuration reference](docs/configuration.md).
 
 ## When it runs
 
 The extension discovers accounts and registers aliases at `session_start`. It checks account-group and OpenRouter safety before a run, tracks model selection and provider responses, repairs failed assistant history at `message_end`, and releases resources at `session_shutdown`.
 
-Reactive routing starts only at `agent_settled`, after Pi's provider retry and compaction loop. A classified provider failure can schedule one fixed `deliverAs: "followUp"` continuation. It does not replay the prompt, provider request, or uncertain tool work. More detail is in [Routing and recovery](docs/routing.md).
+Reactive routing starts only at `agent_settled`, after Pi's provider retry and compaction loop. A classified provider failure can schedule one fixed `deliverAs: "followUp"` continuation. It does not replay the prompt, provider request, or uncertain tool work. A `unified` call is different: it recovers inside the call, before any output, with at most two physical sends, and never continues after settlement. `recoveryStallTimeoutMs` bounds the wait for a physical attempt's response to start. More detail is in [Routing and recovery](docs/routing.md#in-call-recovery).
 
 ## Develop
 

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Global Anthropic and OpenAI Codex multi-account OAuth routing for Pi.",
   "type": "module",
   "bin": {
@@ -59,11 +59,11 @@
     "undici": "^8.10.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.84.4",
-    "@earendil-works/pi-coding-agent": "0.84.4",
-    "@earendil-works/pi-tui": "0.84.4",
+    "@earendil-works/pi-ai": "^1.0.2",
+    "@earendil-works/pi-coding-agent": "^1.0.2",
+    "@earendil-works/pi-tui": "^1.0.2",
     "@types/node": "^24.0.0",
-    "typebox": "1.3.7",
+    "typebox": "1.3.34",
     "typescript": "^5.9.0",
     "vitest": "^4.1.11"
   },

package/packages/pi-anthropic-oauth/package.json

@@ -47,8 +47,8 @@
     "@earendil-works/pi-coding-agent": ">=0.80.8"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.84.4",
-    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@earendil-works/pi-ai": ">=0.84.4",
+    "@earendil-works/pi-coding-agent": ">=0.84.4",
     "typescript": "^5.9.3"
   }
 }

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

@@ -10,6 +10,7 @@ import {
   type Model,
   type SimpleStreamOptions,
   type StopReason,
+  type ToolCall,
 } from "@earendil-works/pi-ai";
 import { isClaudeOAuthAccessToken, USER_AGENT } from "./auth.js";
 import {
@@ -20,6 +21,10 @@ import {
 } from "./convert.js";
 import { projectContext } from "./context.js";
 import { buildAnthropicSystemPrompt } from "./prompt.js";
+import {
+  createTransportActivityFetch,
+  transportActivityListener,
+} from "./transport-activity.js";
 
 const REQUIRED_BETAS = [
   "claude-code-20250219",
@@ -132,12 +137,19 @@ export function streamAnthropicOAuth(
 
       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 =
@@ -221,10 +233,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();
 
@@ -363,10 +383,9 @@ export function streamAnthropicOAuth(
           ) {
             block.partialJson += event.delta.partial_json;
             try {
-              block.arguments = JSON.parse(block.partialJson) as Record<
-                string,
-                unknown
-              >;
+              block.arguments = JSON.parse(
+                block.partialJson,
+              ) as ToolCall["arguments"];
             } catch {}
             stream.push({
               type: "toolcall_delta",
@@ -402,10 +421,9 @@ export function streamAnthropicOAuth(
             });
           } else if (block.type === "toolCall") {
             try {
-              block.arguments = JSON.parse(block.partialJson) as Record<
-                string,
-                unknown
-              >;
+              block.arguments = JSON.parse(
+                block.partialJson,
+              ) as ToolCall["arguments"];
             } catch {}
             delete (block as { partialJson?: string }).partialJson;
             stream.push({

package/packages/pi-anthropic-oauth/src/transport-activity.ts

@@ -0,0 +1,59 @@
+/**
+ * Byte-level transport liveness for one streamed Anthropic request.
+ *
+ * The Anthropic SDK drops the server's `ping` events before they reach a
+ * stream consumer, so a model that thinks silently for minutes is
+ * indistinguishable from a dead connection at the event level. A caller that
+ * needs to tell them apart passes `onTransportActivity` in the request options;
+ * this wrapper then reports every response body chunk (pings included) without
+ * reading, buffering, or retaining its content.
+ *
+ * The callback receives no arguments. A throwing callback is contained so it
+ * can never break the response. Without the option the SDK keeps its default
+ * fetch and the request path is unchanged.
+ */
+
+export type TransportActivityListener = () => void;
+
+export function transportActivityListener(
+  options: unknown,
+): TransportActivityListener | undefined {
+  if (typeof options !== "object" || options === null) return undefined;
+  const listener = (options as { onTransportActivity?: unknown })
+    .onTransportActivity;
+  return typeof listener === "function"
+    ? (listener as TransportActivityListener)
+    : undefined;
+}
+
+export function createTransportActivityFetch(
+  onActivity: TransportActivityListener,
+): typeof fetch {
+  // Read the global at construction, as the SDK's own default does.
+  const baseFetch = globalThis.fetch;
+  const notify = (): void => {
+    try {
+      onActivity();
+    } catch {
+      // Liveness reporting is best-effort and must not break the response.
+    }
+  };
+  return async (input, init) => {
+    const response = await baseFetch(input, init);
+    const body = response.body;
+    if (body === null) return response;
+    const observed = body.pipeThrough(
+      new TransformStream<Uint8Array, Uint8Array>({
+        transform(chunk, controller) {
+          notify();
+          controller.enqueue(chunk);
+        },
+      }),
+    );
+    return new Response(observed, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers,
+    });
+  };
+}

package/packages/pi-antigravity/package.json

@@ -60,13 +60,13 @@
     "@earendil-works/pi-coding-agent": ">=0.80.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.84.2",
+    "@earendil-works/pi-ai": ">=0.84.2",
     "@eslint/js": "^10.0.1",
     "@types/node": "^26.1.1",
     "eslint": "^10.7.0",
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.7.0",
-    "pi-ai-087": "npm:@earendil-works/pi-ai@0.87.1",
+    "pi-ai-087": "npm:@earendil-works/pi-ai@>=0.87.1",
     "prettier": "^3.9.5",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.64.0"

package/packages/pi-antigravity/src/models/discovery.ts

@@ -19,6 +19,7 @@ import {
   registerDiscoveredModelEnums,
   restoreDynamicModelEnums,
   snapshotDynamicModelEnums,
+  type AntigravityModelConfig,
 } from "./models.js";
 
 export const DEFAULT_CATALOG_REFRESH_INTERVAL_MS = 4 * 60 * 60 * 1000;
@@ -144,7 +145,7 @@ function apiKeyFromCredential(credential: Credential | undefined): string | unde
   return undefined;
 }
 
-function toStoredModels(models: ProviderModelConfig[]): Model<Api>[] {
+function toStoredModels(models: AntigravityModelConfig[]): Model<Api>[] {
   return models.map((model) => ({
     ...model,
     api: ANTIGRAVITY_API,

package/packages/pi-antigravity/src/models/grouping.ts

@@ -1,9 +1,9 @@
-import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import type { AntigravityModelConfig } from "./models.js";
 import { ThinkingEffort } from "../types/enums.js";
 import type { AntigravityRouting, ModelInfoRaw } from "../types/types.js";
 
 export type AntigravityCatalog = {
-  models: ProviderModelConfig[];
+  models: AntigravityModelConfig[];
   routing: Record<string, AntigravityRouting>;
 };
 
@@ -108,7 +108,7 @@ export function buildAntigravityCatalog(
 
   if (groups.size === 0) return fallback;
 
-  const models: ProviderModelConfig[] = [];
+  const models: AntigravityModelConfig[] = [];
   const routing: Record<string, AntigravityRouting> = {};
 
   for (const group of groups.values()) {
@@ -222,8 +222,8 @@ function displayFamily(displayName: string | undefined): string | undefined {
 
 function synthesizeModel(
   group: RuntimeGroup,
-  fallbackModels: ProviderModelConfig[],
-): { model: ProviderModelConfig; routing: AntigravityRouting } {
+  fallbackModels: AntigravityModelConfig[],
+): { model: AntigravityModelConfig; routing: AntigravityRouting } {
   const template = familyTemplate(group.publicId, fallbackModels);
   const advertisedLevels = advertisedThinkingLevels(group);
   const routing = routingFromVariants(group.publicId, group.variants, group.unsuffixed);
@@ -322,8 +322,10 @@ function routingFromVariants(
   };
 }
 
-function thinkingLevelMapFromLevels(levels: Set<string>): ProviderModelConfig["thinkingLevelMap"] {
-  const map: NonNullable<ProviderModelConfig["thinkingLevelMap"]> = {};
+function thinkingLevelMapFromLevels(
+  levels: Set<string>,
+): AntigravityModelConfig["thinkingLevelMap"] {
+  const map: NonNullable<AntigravityModelConfig["thinkingLevelMap"]> = {};
   for (const level of PI_LEVELS) {
     map[level] = levels.has(level) ? level : null;
   }
@@ -333,8 +335,8 @@ function thinkingLevelMapFromLevels(levels: Set<string>): ProviderModelConfig["t
 
 function familyTemplate(
   publicId: string,
-  fallbackModels: ProviderModelConfig[],
-): ProviderModelConfig | undefined {
+  fallbackModels: AntigravityModelConfig[],
+): AntigravityModelConfig | undefined {
   if (/^gemini-.*-flash/i.test(publicId)) {
     return fallbackModels.find((model) => /^gemini-.*-flash/i.test(model.id));
   }
@@ -403,7 +405,7 @@ function parseGeminiVersion(id: string): number {
   return Number(match[1]) * 1000 + Number(match[2] || 0);
 }
 
-function comparePublicModels(a: ProviderModelConfig, b: ProviderModelConfig): number {
+function comparePublicModels(a: AntigravityModelConfig, b: AntigravityModelConfig): number {
   const rankA = modelRank(a.id);
   const rankB = modelRank(b.id);
   if (rankA[0] !== rankB[0]) return rankA[0] - rankB[0];

package/packages/pi-antigravity/src/models/models.ts

@@ -3,6 +3,13 @@ import type { AntigravityRouting, ThinkingWire } from "../types/types.js";
 import { ThinkingEffort } from "../types/enums.js";
 import type { AntigravityCatalog } from "./grouping.js";
 
+/**
+ * Chat-model registration shape. Pi 1.0 widened `ProviderModelConfig` to a union
+ * of chat, image, and classifier configs; Antigravity registers chat models only.
+ * On older Pi hosts the type is not a union and this resolves to it unchanged.
+ */
+export type AntigravityModelConfig = Extract<ProviderModelConfig, { reasoning: boolean }>;
+
 export const PROVIDER_ID = "antigravity";
 export const PROVIDER_NAME = "Antigravity";
 
@@ -210,10 +217,10 @@ const thinkingLevelMaps = {
     xhigh: null,
     max: null,
   },
-} satisfies Record<string, ProviderModelConfig["thinkingLevelMap"]>;
+} satisfies Record<string, AntigravityModelConfig["thinkingLevelMap"]>;
 
 /** Same set as `agy models`, collapsed to public Pi model IDs. */
-export const ANTIGRAVITY_MODELS: ProviderModelConfig[] = [
+export const ANTIGRAVITY_MODELS: AntigravityModelConfig[] = [
   {
     id: "gemini-3.8-flash",
     name: "Gemini 3.8 Flash (Antigravity)",
@@ -296,10 +303,10 @@ export const ANTIGRAVITY_MODELS: ProviderModelConfig[] = [
   },
 ];
 
-let currentModels: ProviderModelConfig[] = ANTIGRAVITY_MODELS;
+let currentModels: AntigravityModelConfig[] = ANTIGRAVITY_MODELS;
 let currentRouting: Record<string, AntigravityRouting> = { ...ANTIGRAVITY_ROUTING };
 
-export function getCurrentAntigravityModels(): ProviderModelConfig[] {
+export function getCurrentAntigravityModels(): AntigravityModelConfig[] {
   return currentModels;
 }
 

package/src/account-group-failure.ts

@@ -0,0 +1,149 @@
+import { isAccountGroupMemberReference, type AccountGroupMemberAvailability } from "./account-group-members.js";
+import { MANAGED_FAMILIES } from "./config.js";
+import type { EffectiveAccountGroupResolution } from "./group-policy.js";
+
+export type AccountGroupFailureBlockReason =
+	| "delegate-origin-unresolved" | "context-unavailable"
+	| "driver-origin-unresolved" | "delegate-resolution-unavailable"
+	| "driver-resolution-unavailable" | "config-invalid" | "resolution-failed";
+const BLOCK_REASONS: readonly AccountGroupFailureBlockReason[] = [
+	"delegate-origin-unresolved", "context-unavailable", "driver-origin-unresolved",
+	"delegate-resolution-unavailable", "driver-resolution-unavailable", "config-invalid", "resolution-failed",
+];
+
+/** Already-authorized policy only; never resolve a cwd or a delegate identity here. */
+export type AccountGroupFailurePolicy =
+	| { readonly kind: "resolved"; readonly resolution: EffectiveAccountGroupResolution; readonly members: readonly string[] }
+	| { readonly kind: "blocked"; readonly reason: AccountGroupFailureBlockReason };
+
+/** Copied availability facts, not credentials, status metadata or raw provider errors. */
+export interface AccountGroupFailureCandidate extends Pick<AccountGroupMemberAvailability, "providerId" | "eligible"> {
+	readonly servesModel: boolean;
+	readonly authenticated?: boolean;
+	readonly exhausted?: boolean;
+	readonly coolingDown?: boolean;
+	readonly reason?: AccountGroupMemberAvailability["reason"];
+}
+
+export type AccountGroupFailureReason =
+	| AccountGroupFailureBlockReason | "policy-unavailable"
+	| "no-serving-members" | "no-managed-serving-members"
+	| "authentication-unavailable" | "cooldown" | "exhausted"
+	| "authorization-snapshot-unavailable" | "availability-unresolved";
+
+export interface AccountGroupFailureView {
+	readonly reason: AccountGroupFailureReason;
+	readonly source?: EffectiveAccountGroupResolution["source"];
+	readonly groupId?: string;
+	readonly outsideEligible: boolean;
+	readonly message: string;
+	readonly help: string;
+}
+
+export interface AccountGroupFailureInput {
+	readonly policy: AccountGroupFailurePolicy;
+	readonly modelId: string;
+	readonly accountLimit: number;
+	readonly candidates: readonly AccountGroupFailureCandidate[];
+}
+
+// Pinned pi-ai retry.js/overflow.js act on error prose, not a group error code.
+// Plain labels cannot contain the space-bearing patterns. Exclude the remaining
+// compact patterns too; never manufacture an AssistantMessage to validate text.
+const HOST_TRIGGER_LABEL = /overloaded|rate.?limit|429|500|502|503|504|524|service.?unavailable|server.?error|internal.?error|provider.?returned.?error|network.?error|connection.?(?:error|refused|lost)|getaddrinfo|ENOTFOUND|EAI_AGAIN|upstream.?connect|timeout|terminated|websocket.?(?:closed|error)|ResourceExhausted|request_too_large|model_context_window_exceeded|context[_]length[_]exceeded/i;
+
+function safeLabel(value: string, maxLength: number, fallback: string): string {
+	return typeof value === "string" && value.length <= maxLength &&
+		/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) && !HOST_TRIGGER_LABEL.test(value)
+		? value : fallback;
+}
+
+function managedProvider(providerId: string): boolean {
+	return MANAGED_FAMILIES.some((family) => providerId === family || providerId.startsWith(`${family}-account-`));
+}
+
+const REASON_TEXT: Readonly<Record<AccountGroupFailureReason, readonly [string, string]>> = {
+	"delegate-origin-unresolved": ["delegate-origin-unresolved: the delegate parent could not be verified", "Start a worker from a verified parent session."],
+	"context-unavailable": ["context-unavailable: the session policy context is unavailable", "Wait for the session context, then try again."],
+	"driver-origin-unresolved": ["driver-origin-unresolved: the durable delegate parent could not be verified", "Start a child from a verified parent session."],
+	"delegate-resolution-unavailable": ["delegate-resolution-unavailable: the parent policy is unavailable", "Restore the verified parent session policy before starting a worker."],
+	"driver-resolution-unavailable": ["driver-resolution-unavailable: the durable parent policy is unavailable", "Restore the verified parent session policy before starting a child."],
+	"config-invalid": ["config-invalid: the account policy configuration is invalid", "Correct the global configuration and run /multi-account reload."],
+	"resolution-failed": ["resolution-failed: the session policy could not be read safely", "Repair the session account-group store before trying again."],
+	"policy-unavailable": ["the authorized account-group policy is unavailable", "Check /multi-account group status before trying again."],
+	"no-serving-members": ["no listed member serves this model", "Select a model served by a listed member or choose another group."],
+	"no-managed-serving-members": ["no eligible managed member serves this unified model", "Select a listed physical model or choose a group with managed members."],
+	"authentication-unavailable": ["serving managed members need usable authorization; sign in", "Sign in with /login, then run /multi-account rediscover, or choose another group."],
+	"cooldown": ["serving managed members are cooling down", "Wait for recovery or choose another group."],
+	"exhausted": ["serving managed members have exhausted their available usage", "Wait for usage to recover or choose another group."],
+	"authorization-snapshot-unavailable": ["the authorization snapshot is unavailable", "Check provider availability, then try again or choose another group."],
+	"availability-unresolved": ["no eligible managed member is available; the cause is not established", "Check /multi-account group status, sign in if needed, or choose another group."],
+};
+
+function failureView(
+	reason: AccountGroupFailureReason,
+	modelId: string,
+	outsideEligible: boolean,
+	resolution?: Exclude<EffectiveAccountGroupResolution, { readonly source: "unrestricted" }>,
+): AccountGroupFailureView {
+	const [text, help] = REASON_TEXT[reason];
+	const model = safeLabel(modelId, 128, "selected-model");
+	const groupId = resolution === undefined ? undefined : safeLabel(resolution.groupId, 64, "selected-group");
+	const source = resolution?.source;
+	const heading = groupId === undefined ? "Account group scope" : `Account group "${groupId}" (${source})`;
+	const message = `${heading} cannot serve ${model}: ${text}. ${help}${outsideEligible ? " Eligible accounts exist outside this group; they remain excluded." : ""}`;
+	// Only named output facts; never return caller policy, candidate objects or prose.
+	if (groupId === undefined || source === undefined) {
+		return Object.freeze({ reason, outsideEligible, message, help });
+	}
+	return Object.freeze({ reason, groupId, source, outsideEligible, message, help });
+}
+
+/**
+ * Format a failed unified selection from one call's already-authorized facts.
+ * This observes nothing, changes no policy and grants no dispatch permission.
+ * Undefined preserves the caller's existing unrestricted error byte-for-byte.
+ * Mixed or unobserved causes stay unresolved, never guessed as missing auth.
+ */
+export function formatAccountGroupFailure(input: AccountGroupFailureInput): AccountGroupFailureView | undefined {
+	const policy = input.policy;
+	if (policy.kind === "blocked") {
+		const reason = Object.hasOwn(REASON_TEXT, policy.reason) && BLOCK_REASONS.includes(policy.reason)
+			? policy.reason : "policy-unavailable";
+		return failureView(reason, input.modelId, false);
+	}
+	if (policy.kind !== "resolved") return failureView("policy-unavailable", input.modelId, false);
+	const resolution = policy.resolution;
+	if (resolution.source === "unrestricted") return undefined;
+	if (resolution.source !== "session-override" && resolution.source !== "cwd-default" && resolution.source !== "global-default") {
+		return failureView("policy-unavailable", input.modelId, false);
+	}
+	if (!Number.isInteger(input.accountLimit) || input.accountLimit < 1 || input.accountLimit > 32) {
+		return failureView("policy-unavailable", input.modelId, false, resolution);
+	}
+	const validId = (id: string): boolean => isAccountGroupMemberReference(id, input.accountLimit, MANAGED_FAMILIES);
+	const members = new Set(policy.members.filter(validId));
+	const candidates = input.candidates.filter((row) => validId(row.providerId)).map((row) => ({
+		providerId: row.providerId,
+		servesModel: row.servesModel === true,
+		eligible: row.eligible === true,
+		authenticated: row.authenticated === false ? false : undefined,
+		exhausted: row.exhausted === true,
+		coolingDown: row.coolingDown === true,
+		reason: row.reason === "authentication unavailable" || row.reason === "authorization snapshot unavailable" ? row.reason : undefined,
+	}));
+	const inside = candidates.filter((row) => members.has(row.providerId));
+	const serving = inside.filter((row) => row.servesModel === true);
+	const managed = serving.filter((row) => managedProvider(row.providerId));
+	if (managed.some((row) => row.eligible === true)) return undefined;
+	const outsideEligible = candidates.some((row) => !members.has(row.providerId) && row.servesModel === true && row.eligible === true);
+	let reason: AccountGroupFailureReason;
+	if (inside.some((row) => row.reason === "authorization snapshot unavailable")) reason = "authorization-snapshot-unavailable";
+	else if (serving.length === 0) reason = "no-serving-members";
+	else if (managed.length === 0 || serving.some((row) => !managedProvider(row.providerId) && row.eligible === true)) reason = "no-managed-serving-members";
+	else if (managed.every((row) => row.authenticated === false || row.reason === "authentication unavailable")) reason = "authentication-unavailable";
+	else if (managed.every((row) => row.exhausted === true)) reason = "exhausted";
+	else if (managed.every((row) => row.coolingDown === true)) reason = "cooldown";
+	else reason = "availability-unresolved";
+	return failureView(reason, input.modelId, outsideEligible, resolution);
+}

package/src/account-group-members.ts

@@ -0,0 +1,139 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+type GroupMemberRegistry = Pick<
+	ExtensionContext["modelRegistry"],
+	"getAll" | "getAvailable"
+> & Partial<Pick<
+	ExtensionContext["modelRegistry"],
+	"getRegisteredProviderIds" | "getProviderAuthStatus"
+>>;
+
+export type AccountGroupMemberReason =
+	| "recognized and available"
+	| "excluded by active group"
+	| "unknown or removed provider"
+	| "authentication unavailable"
+	| "model unavailable"
+	| "virtual model unsupported by active group"
+	| "authorization snapshot unavailable";
+
+export interface AccountGroupMemberAvailability {
+	readonly providerId: string;
+	readonly eligible: boolean;
+	readonly reason: AccountGroupMemberReason;
+}
+
+export interface AccountGroupRegistrySnapshot {
+	readonly providerIds: ReadonlySet<string>;
+	readonly modelProviderIds: ReadonlySet<string>;
+	readonly availableModels: readonly {
+		readonly providerId: string;
+		readonly modelId: string;
+		readonly api: string;
+	}[] | undefined;
+}
+
+/** Public Pi virtual API marker; provider identity/auth cannot confine its targets. */
+export function isAccountGroupVirtualModel(
+	model: Readonly<{ api: string }> | undefined,
+): boolean {
+	return model?.api === "pi-virtual";
+}
+
+/** Syntax alone grants no authority and does not enroll a provider in routing. */
+export function isAccountGroupMemberReference(
+	value: unknown,
+	accountLimit: number,
+	managedFamilies: readonly string[],
+): value is string {
+	if (
+		typeof value !== "string" ||
+		!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value)
+	) return false;
+	if (!Number.isInteger(accountLimit) || accountLimit < 1 || accountLimit > 32) {
+		return false;
+	}
+	for (const family of managedFamilies) {
+		if (value === family) return true;
+		const prefix = `${family}-account-`;
+		if (!value.startsWith(prefix)) continue;
+		const suffix = value.slice(prefix.length);
+		const slot = Number(suffix);
+		return Number.isSafeInteger(slot) && slot >= 2 &&
+			slot <= accountLimit && String(slot) === suffix;
+	}
+	return true;
+}
+
+/** Public synchronous snapshots only: no credential resolver, refresh, label or key. */
+export function readAccountGroupRegistrySnapshot(
+	registry: GroupMemberRegistry | undefined,
+): AccountGroupRegistrySnapshot {
+	const providerIds = new Set<string>();
+	const modelProviderIds = new Set<string>();
+	let availableModels: AccountGroupRegistrySnapshot["availableModels"];
+	try {
+		for (const row of registry?.getAll() ?? []) {
+			providerIds.add(row.provider);
+			modelProviderIds.add(row.provider);
+		}
+		for (const id of registry?.getRegisteredProviderIds?.() ?? []) {
+			providerIds.add(id);
+		}
+	} catch {
+		return {
+			providerIds: new Set(), modelProviderIds: new Set(),
+			availableModels: undefined,
+		};
+	}
+	try {
+		// getAvailable() is cached catalog/auth-check metadata, not resolved request
+		// credentials. A configured command can pass without executing. A failed
+		// metadata read excludes only its member; request auth remains host-owned.
+		const authConfigured = new Map<string, boolean>();
+		availableModels = registry?.getAvailable().filter((row) => {
+			if (!authConfigured.has(row.provider)) {
+				try {
+					const configured = registry.getProviderAuthStatus === undefined ||
+						registry.getProviderAuthStatus(row.provider).configured === true;
+					authConfigured.set(row.provider, configured);
+				} catch {
+					authConfigured.set(row.provider, false);
+				}
+			}
+			return authConfigured.get(row.provider) === true;
+		}).map((row) => ({ providerId: row.provider, modelId: row.id, api: row.api }));
+	} catch {
+		availableModels = undefined;
+	}
+	return { providerIds, modelProviderIds, availableModels };
+}
+
+/** Exact membership and live availability, independent of managed routing ownership. */
+export function accountGroupMemberAvailability(
+	providerId: string,
+	members: readonly string[],
+	snapshot: AccountGroupRegistrySnapshot,
+	modelId?: string,
+): AccountGroupMemberAvailability {
+	let reason: AccountGroupMemberReason;
+	const available = snapshot.availableModels;
+	if (!snapshot.providerIds.has(providerId)) reason = "unknown or removed provider";
+	else if (!members.includes(providerId)) reason = "excluded by active group";
+	else if (available === undefined) reason = "authorization snapshot unavailable";
+	else if (!snapshot.modelProviderIds.has(providerId)) reason = "model unavailable";
+	else if (!available.some((row) => row.providerId === providerId)) {
+		reason = "authentication unavailable";
+	} else if (modelId !== undefined && !available.some(
+		(row) => row.providerId === providerId && row.modelId === modelId,
+	)) {
+		reason = "model unavailable";
+	} else if (!available.some((row) =>
+		row.providerId === providerId &&
+		(modelId === undefined || row.modelId === modelId) &&
+		!isAccountGroupVirtualModel(row),
+	)) {
+		reason = "virtual model unsupported by active group";
+	} else reason = "recognized and available";
+	return { providerId, eligible: reason === "recognized and available", reason };
+}