@centerforagenticai/pi-multi-account 0.1.6 → 0.1.8

package/README.md

@@ -43,9 +43,14 @@ The package bundles reviewed Anthropic OAuth and Google Antigravity source under
 | Provider | `unified` | Optional exact-model logical provider generated from managed catalogs. |
 | CLI | `multi-account` | Offline cost reports, pricing refresh, period closure, and account plan history. |
 | Export | exact-model route resolver v1 | Read-only, credential-free route policy for code consumers. |
+| Export | `./public-status` v1 | Read-only live account status for other extensions over `pi.events`. |
 
 Every subcommand and argument is in [Commands, tools, and autocomplete](docs/commands.md). The resolver contract is in [Routing and recovery](docs/routing.md).
 
+### Public account status subpath
+
+Import `@centerforagenticai/pi-multi-account/public-status` and call `discoverPublicAccountStatusReader(pi.events)`. Use the package name your installation resolves: the package is installed under its published name. The subpath is a plain JavaScript module with no imports, so plain Node can load it and it never loads the extension or Pi. The v1 contract uses the query channel `pi-multi-account:public-status-service-query:v1` and returns a `public-status-v1` snapshot, or `owner-unavailable` until `session_start` finishes and after `session_shutdown`, and `source-error` when the owner fails. Version 1 covers only Anthropic and OpenAI Codex accounts; Google Antigravity accounts are omitted. Each account's `label` is the label you configured in `accountLabels`, or else the provider id. It is never read from a token. See [Commands, tools, and autocomplete](docs/commands.md#public-live-account-status-public-status).
+
 ## Configuration
 
 The extension reads one machine-global file and no project-local config:

package/package.json

@@ -1,11 +1,17 @@
 {
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Global Anthropic and OpenAI Codex multi-account OAuth routing for Pi.",
   "type": "module",
   "bin": {
     "multi-account": "scripts/multi-account.mjs"
   },
-  "exports": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./public-status": {
+      "types": "./src/public-status.d.ts",
+      "default": "./src/public-status.js"
+    }
+  },
   "files": [
     "src",
     "scripts/multi-account.mjs",
@@ -59,11 +65,11 @@
     "undici": "^8.10.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^1.0.2",
-    "@earendil-works/pi-coding-agent": "^1.0.2",
-    "@earendil-works/pi-tui": "^1.0.2",
+    "@earendil-works/pi-ai": "^1.0.4",
+    "@earendil-works/pi-coding-agent": "^1.0.4",
+    "@earendil-works/pi-tui": "^1.0.4",
     "@types/node": "^24.0.0",
-    "typebox": "1.3.34",
+    "typebox": "1.3.35",
     "typescript": "^5.9.0",
     "vitest": "^4.1.11"
   },

package/src/account-labels.ts

@@ -207,6 +207,33 @@ export function resolveAccountLabelWithinLimit(input: Readonly<{
 	});
 }
 
+/**
+ * Resolves ONLY an operator-configured label for a managed account, with the
+ * same current-limit guard as {@link resolveAccountLabelWithinLimit}.
+ *
+ * This is the public status surface's label source. It takes no token reader
+ * at all, so a token-derived identity (for example a Codex JWT `email`,
+ * `preferred_username`, or `name` claim) cannot reach it. Returns undefined when
+ * the id is malformed or above the limit, or when no valid label is configured;
+ * the caller then falls back to the provider id.
+ */
+export function resolveConfiguredAccountLabelWithinLimit(input: Readonly<{
+	providerId: string;
+	accountLimit: number;
+	configured: AccountLabelConfig;
+}>): string | undefined {
+	const slot = classifyProviderId({
+		providerId: input.providerId,
+		credentialType: "unknown",
+	});
+	if (
+		slot === null ||
+		!isProviderSlotWithinAccountLimit(slot, input.accountLimit)
+	) return undefined;
+	if (!Object.hasOwn(input.configured, input.providerId)) return undefined;
+	return normalizeLabel(input.configured[input.providerId]);
+}
+
 /**
  * Composes the string Pi shows in its login list and provider UI, pairing the
  * family's product name with the account's own label. When the label carries no

package/src/commands.ts

@@ -65,8 +65,11 @@ import { type DiagnosticLog, sanitizedJson } from "./diagnostics.js";
 import {
 	accountHealth,
 	renderStatus,
+	type AccountStatusView,
 	type StatusViewInput,
 } from "./status-view.js";
+import type { PublicAccountStatusSnapshot } from "./public-status.js";
+import { projectPublicAccountStatus } from "./public-status-projection.js";
 import type { CredentialType } from "./discovery.js";
 import { providerTypeFor, type ProviderType } from "./vendor.js";
 import type { UnsupportedModelPair } from "./model-support.js";
@@ -331,6 +334,11 @@ export interface CommandDependencies {
 	readonly activeModelId?: () => string | undefined;
 	/** Operator-facing label for a managed account, when one resolves. */
 	readonly accountLabel?: (providerId: string) => string | undefined;
+	/**
+	 * Operator-configured label only, for the public status service. Must never
+	 * derive a label from a credential.
+	 */
+	readonly publicAccountLabel?: (providerId: string) => string | undefined;
 	/** Bounded credential expiry for a managed account, when known. */
 	readonly credentialExpiry?: (providerId: string) => number | undefined;
 	/** Session-local provider/model divergence observations for operator status. */
@@ -341,6 +349,8 @@ export interface CommandDependencies {
 	) => UsageFetchStatus | undefined;
 	/** Read-only project/account/model cost intelligence for one calendar series. */
 	readonly costReport?: (periodType: PeriodType) => Promise<CostReport>;
+	/** Month API-equivalent cost report for the public status service. */
+	readonly publicCostReport?: () => Promise<CostReport>;
 	/** Explicit metered last-resort policy; never includes credential material. */
 	readonly meteredFallbackStatus?: () => MeteredFallbackStatus;
 	readonly setModel: (model: Model<Api>) => Promise<boolean>;
@@ -811,71 +821,15 @@ export class MultiAccountCommandController {
 			});
 		}
 		const currentProviderId = this.#dependencies.currentProviderId();
-		const activeAccountProviderId =
-			this.#dependencies.activeAccountProviderId?.() ?? currentProviderId;
 		// Label and expiry are resolved HERE, not per-branch, so the JSON and
 		// human-readable views cannot drift: a scripted consumer sees the same
 		// credential freshness the operator does.
-		const projected = accounts.map((account) => {
-			const disabled = this.#disabledProviders.has(account.providerId);
-			const coolingUntilMs = this.#dependencies.state.getCooldown(
-				account.providerId,
-				now,
-			)?.untilMs;
-			const unavailable =
-				this.#dependencies.state.getInvalidation(account.providerId) !==
-				undefined;
-			const usageUntrusted =
-				this.#dependencies.state.isUsageSnapshotUntrusted(
-					account.providerId,
-					now,
-				);
-			const usage = this.#dependencies.usage.get(account.providerId);
-			const view = {
-				providerId: account.providerId,
-				family: account.family,
-				// Derived live from the discovered credential type; additive field,
-				// no existing field changes. An absent credentialType defaults to
-				// the subscription type.
-				providerType: providerTypeFor(
-					account.family,
-					account.credentialType ?? "unknown",
-				),
-				active: account.providerId === activeAccountProviderId,
-				disabled,
-				unavailable,
-				...(coolingUntilMs === undefined ? {} : { coolingUntilMs }),
-				...(usageUntrusted ? { usageUntrusted: true } : {}),
-				...(usage === undefined ? {} : { usage }),
-			};
-			const health = accountHealth(view, now);
-			return {
-				...view,
-				api: account.model.api,
-				healthy: health === "ready" || health === "low-headroom",
-				...(account.accountFingerprint === undefined
-					? {}
-					: { accountFingerprint: account.accountFingerprint }),
-				usageFetch: this.#dependencies.usageFetchStatus?.(account.providerId),
-				allModelsUnsupported:
-					account.modelIds.length > 0 &&
-					account.modelIds.every((modelId) =>
-						unsupportedModels.some(
-							(pair) =>
-								pair.providerId === account.providerId &&
-								pair.modelId === modelId,
-						),
-					),
-				...this.#optionalField(
-					"label",
-					this.#dependencies.accountLabel?.(account.providerId),
-				),
-				...this.#optionalField(
-					"expiresAtMs",
-					this.#dependencies.credentialExpiry?.(account.providerId),
-				),
-			};
-		});
+		const projected = this.#projectAccountViews(
+			accounts,
+			now,
+			unsupportedModels,
+			(providerId) => this.#dependencies.accountLabel?.(providerId),
+		);
 		const meteredFallback = this.#dependencies.meteredFallbackStatus?.();
 		if (asJson) {
 			return sanitizedJson({
@@ -1459,6 +1413,130 @@ export class MultiAccountCommandController {
 		return modelId === undefined ? {} : { activeModelId: modelId };
 	}
 
+	/**
+	 * The one live per-account projection shared by `status`, `status --json`,
+	 * and the public status service. `labelFor` is a parameter because the
+	 * public service must publish only operator-configured labels, never the
+	 * token-derived label the operator status shows.
+	 */
+	#projectAccountViews(
+		accounts: readonly OperatorAccount[],
+		now: number,
+		unsupportedModels: readonly UnsupportedModelPair[],
+		labelFor: (providerId: string) => string | undefined,
+	) {
+		const activeAccountProviderId =
+			this.#dependencies.activeAccountProviderId?.() ??
+			this.#dependencies.currentProviderId();
+		return accounts.map((account) => {
+			const disabled = this.#disabledProviders.has(account.providerId);
+			const coolingUntilMs = this.#dependencies.state.getCooldown(
+				account.providerId,
+				now,
+			)?.untilMs;
+			const unavailable =
+				this.#dependencies.state.getInvalidation(account.providerId) !==
+				undefined;
+			const usageUntrusted =
+				this.#dependencies.state.isUsageSnapshotUntrusted(
+					account.providerId,
+					now,
+				);
+			const usage = this.#dependencies.usage.get(account.providerId);
+			const view = {
+				providerId: account.providerId,
+				family: account.family,
+				// Derived live from the discovered credential type; additive field,
+				// no existing field changes. An absent credentialType defaults to
+				// the subscription type.
+				providerType: providerTypeFor(
+					account.family,
+					account.credentialType ?? "unknown",
+				),
+				active: account.providerId === activeAccountProviderId,
+				disabled,
+				unavailable,
+				...(coolingUntilMs === undefined ? {} : { coolingUntilMs }),
+				...(usageUntrusted ? { usageUntrusted: true } : {}),
+				...(usage === undefined ? {} : { usage }),
+			};
+			const health = accountHealth(view, now);
+			return {
+				...view,
+				api: account.model.api,
+				healthy: health === "ready" || health === "low-headroom",
+				...(account.accountFingerprint === undefined
+					? {}
+					: { accountFingerprint: account.accountFingerprint }),
+				usageFetch: this.#dependencies.usageFetchStatus?.(account.providerId),
+				allModelsUnsupported:
+					account.modelIds.length > 0 &&
+					account.modelIds.every((modelId) =>
+						unsupportedModels.some(
+							(pair) =>
+								pair.providerId === account.providerId &&
+								pair.modelId === modelId,
+						),
+					),
+				...this.#optionalField("label", labelFor(account.providerId)),
+				...this.#optionalField(
+					"expiresAtMs",
+					this.#dependencies.credentialExpiry?.(account.providerId),
+				),
+			};
+		});
+	}
+
+	/**
+	 * Read-only snapshot for the `./public-status` event-bus service.
+	 *
+	 * Reuses the status projection, but labels come only from
+	 * `publicAccountLabel` (operator configuration). A token-derived label, such
+	 * as a Codex JWT email claim, is a human account identifier and must never
+	 * reach this surface, so the status `accountLabel` resolver is not used.
+	 */
+	async publicStatus(): Promise<PublicAccountStatusSnapshot> {
+		const nowMs = this.#now();
+		const projected = this.#projectAccountViews(
+			this.#accounts(),
+			nowMs,
+			this.#dependencies.unsupportedModels?.() ?? [],
+			(providerId) => this.#dependencies.publicAccountLabel?.(providerId),
+		);
+		const accounts = projected.map(
+			(account): AccountStatusView => ({
+				providerId: account.providerId,
+				family: account.family,
+				active: account.active,
+				disabled: account.disabled,
+				unavailable: account.unavailable,
+				...(account.coolingUntilMs === undefined
+					? {}
+					: { coolingUntilMs: account.coolingUntilMs }),
+				...(account.usageUntrusted ? { usageUntrusted: true } : {}),
+				...(account.usage === undefined ? {} : { usage: account.usage }),
+				...(account.usageFetch === undefined
+					? {}
+					: { usageFetch: account.usageFetch }),
+				...("label" in account ? { label: account.label } : {}),
+				...("expiresAtMs" in account
+					? { expiresAtMs: account.expiresAtMs }
+					: {}),
+			}),
+		);
+		let costReport: CostReport | undefined;
+		try {
+			costReport = await this.#dependencies.publicCostReport?.();
+		} catch {
+			costReport = undefined;
+		}
+		return projectPublicAccountStatus({
+			nowMs,
+			accounts,
+			...(costReport === undefined ? {} : { costReport }),
+		});
+	}
+
 	/**
 	 * Machine-readable account status for the agent-invocable tool.
 	 *

package/src/index.ts

@@ -75,7 +75,7 @@ import {
 import { parsePiCatalogSnapshot, type PiCatalogSnapshot } from "./api-pricing.js";
 import type { CostReport } from "./cost-report.js";
 import { createDefaultCostReportReader } from "./cost-report-reader.js";
-import type { PeriodType } from "./period-boundaries.js";
+import { getPeriodBounds, type PeriodType } from "./period-boundaries.js";
 import {
 	mergeRefreshedCredentials,
 	type CredentialUsability,
@@ -223,7 +223,12 @@ import { restoreManagedAliasModel } from "./session-restore.js";
 import {
 	accountFingerprint,
 	resolveAccountLabelWithinLimit,
+	resolveConfiguredAccountLabelWithinLimit,
 } from "./account-labels.js";
+import {
+	registerPublicAccountStatusService,
+	type PublicAccountStatusEventBus,
+} from "./public-status.js";
 import {
 	createAnthropicAliasProviderConfig,
 	reassertAnthropicBaseRegistration,
@@ -2277,6 +2282,14 @@ export const createMultiAccountExtension =
 		const registerLogicalApi = createLogicalApiRegistrarForFactoryGeneration();
 
 		let context: ExtensionContext | undefined;
+		// The public status service answers owner-unavailable until session_start
+		// has loaded config and discovered accounts, and again after shutdown, so
+		// a consumer never sees a default-config snapshot as authoritative.
+		let publicStatusStarted = false;
+		let publicStatusDisposed = false;
+		// The UTC day (the cost period closer's day) for which a public read last
+		// scheduled the period closer.
+		let publicStatusCostCloseDayStartMs: number | undefined;
 		let attributionStore: AttributionStore | undefined;
 		let latestLogicalPhysicalProviderId: string | undefined;
 		const logicalTerminalAssociations = createLogicalTerminalAssociationStore();
@@ -3304,6 +3317,20 @@ export const createMultiAccountExtension =
 				const label = resolveLabelFor(providerId);
 				return label === providerId ? undefined : label;
 			},
+			// The public status service publishes configured labels only. It must
+			// not use resolveLabelFor, which derives a label from the stored token
+			// (a Codex JWT email claim is a human account identifier).
+			publicAccountLabel: (providerId) => {
+				try {
+					return resolveConfiguredAccountLabelWithinLimit({
+						providerId,
+						accountLimit: config.accountLimit,
+						configured: config.accountLabels,
+					});
+				} catch {
+					return undefined;
+				}
+			},
 			// Re-read live rather than using the discovery snapshot: a long-lived
 			// session's snapshot ages out and would report healthy accounts as
 			// expired, prompting an unnecessary sign-in.
@@ -3317,6 +3344,12 @@ export const createMultiAccountExtension =
 					: usageFetcher.status(providerId, family, config);
 			},
 			costReport,
+			// The month API-equivalent report, read without the period closer:
+			// a polled public read must not drive retained-state writes.
+			publicCostReport: async () =>
+				options.costReport === undefined
+					? defaultCostReportReader("month")
+					: options.costReport("month"),
 			meteredFallbackStatus: () => {
 				const policy = openRouterPolicy();
 				const configuredPolicy = resolveOpenRouterEnvironmentPolicy({
@@ -3398,6 +3431,32 @@ export const createMultiAccountExtension =
 					}),
 			},
 		});
+		// Read-only public status service on Pi's shared event bus. Consumers
+		// discover it through the dependency-free `./public-status` subpath.
+		// Hosts without an event bus (minimal embedders and test doubles) simply
+		// do not offer the service; consumers then discover "unsupported".
+		const publicStatusEvents = (pi as { readonly events?: PublicAccountStatusEventBus })
+			.events;
+		const unregisterPublicStatusService =
+			publicStatusEvents === undefined
+				? () => {}
+				: registerPublicAccountStatusService(publicStatusEvents, async () => {
+						if (!publicStatusStarted || publicStatusDisposed) {
+							return { status: "unavailable", reason: "owner-unavailable" };
+						}
+						schedulePublicStatusCostClose(Date.now());
+						return {
+							status: "available",
+							snapshot: await commands.publicStatus(),
+						};
+					});
+		const disposePublicStatusService = (): void => {
+			// A handler a bus failed to unsubscribe must not keep publishing a
+			// frozen snapshot after shutdown; it reads owner-unavailable instead.
+			publicStatusDisposed = true;
+			publicStatusStarted = false;
+			unregisterPublicStatusService();
+		};
 		/**
 		 * The latest failure classified during the current agent run.
 		 *
@@ -4362,6 +4421,22 @@ export const createMultiAccountExtension =
 				warnCostCloseFailed();
 			}
 		};
+		// The public read itself stays write-free, but the month estimate reads
+		// closed day digests plus today's raw rows only. On the first public read
+		// of a new day, schedule the same deduplicated, leased closer a provider
+		// response uses (without awaiting it), so yesterday's spend reaches the
+		// month digest even when no provider response has arrived yet today.
+		const schedulePublicStatusCostClose = (nowMs: number): void => {
+			let dayStartMs: number;
+			try {
+				dayStartMs = getPeriodBounds(nowMs, "day").startMs;
+			} catch {
+				return;
+			}
+			if (publicStatusCostCloseDayStartMs === dayStartMs) return;
+			publicStatusCostCloseDayStartMs = dayStartMs;
+			closeCostPeriodsAfterObservation(nowMs);
+		};
 		const recordManagedAssistant = async (
 			message: AssistantMessage,
 			providerId: string,
@@ -4949,6 +5024,9 @@ export const createMultiAccountExtension =
 				} catch {
 					// The footer cannot fail session restore.
 				}
+				// Last: config is loaded and accounts are discovered, so the public
+				// status service may now publish an authoritative snapshot.
+				publicStatusStarted = !publicStatusDisposed;
 			}),
 		);
 		pi.on(
@@ -5894,6 +5972,11 @@ export const createMultiAccountExtension =
 				} catch {
 					// Footer cleanup cannot block session teardown.
 				}
+				try {
+					disposePublicStatusService();
+				} catch {
+					// Unsubscribing is best-effort and cannot block teardown.
+				}
 				resolverOwner.dispose();
 			});
 			lifecycle.register(pi);

package/src/logical-provider.ts

@@ -456,6 +456,14 @@ const VISIBLE_FAILURE_CAUSES: Readonly<Record<LogicalFailureEvidence["category"]
 export const HOST_STALE_INSTALL_MESSAGE =
 	"pi's installed files changed while this session was running; restart the pi session to load the current install.";
 
+/**
+ * Public text when the missing module is a bare package rather than one of
+ * pi's own bundle files: the dependency is absent from the install, so a
+ * restart loads the same broken tree and only a reinstall helps.
+ */
+export const HOST_MISSING_DEPENDENCY_MESSAGE =
+	"pi could not load a package it depends on; reinstall pi (or the extension that needs the package), then restart the pi session.";
+
 /**
  * Node's own phrasing, anchored at the start: pi-ai `lazyStream` keeps
  * `error.message` unprefixed. An unanchored match would misread a provider or
@@ -491,7 +499,7 @@ function hasStructuredFailureEvidence(failure: ProviderFailureSignal | undefined
  * Bounded diagnostic cause for a stale install: the Node error code and the
  * missing file's base name. Directories are dropped so no local path is kept.
  */
-function hostStaleInstallCause(error: unknown): string {
+export function hostLoadFault(error: unknown): { cause: string; missingDependency: boolean } {
 	let text = "";
 	let code: unknown;
 	try {
@@ -504,9 +512,25 @@ function hostStaleInstallCause(error: unknown): string {
 	} catch {
 		// Fall through with whatever was read.
 	}
-	const file = /['"]?([^'"\s]*\.(?:m?js|cjs|json|node))['"]?/.exec(text)?.[1]?.split(/[\\/]/).at(-1);
 	const kind = code === "ERR_MODULE_NOT_FOUND" || /ERR_MODULE_NOT_FOUND|Cannot find/.test(text) ? "ERR_MODULE_NOT_FOUND" : "dynamic-import-failed";
-	return file === undefined || file.length === 0 ? kind : `${kind} ${file.slice(0, 120)}`;
+	// Node names the missing specifier first ("Cannot find package 'x' imported
+	// from /dir/importer.js"); the importer is not what is missing.
+	// Node does not escape quotes, so a path may contain one: read up to the
+	// quote that ends the specifier (before " imported from", a CJS
+	// ". Please verify…"/"Require stack" line, or the end of the text).
+	const specifier = /Cannot find (?:module|package) '(.+?)'(?=$| imported from |\.\s|\r?\n)/.exec(text)?.[1];
+	if (specifier !== undefined && specifier.length > 0) {
+		if (!/^(?:\.{1,2}[\\/]|[\\/]|file:|[A-Za-z]:[\\/])/.test(specifier)) {
+			// A bare specifier names a package (keep "@scope/name" or "name").
+			const parts = specifier.split("/");
+			const name = (specifier.startsWith("@") ? parts.slice(0, 2) : parts.slice(0, 1)).join("/");
+			return { cause: `${kind} package ${name.slice(0, 120)}`, missingDependency: true };
+		}
+		const base = specifier.split(/[\\/]/).at(-1) ?? "";
+		return { cause: base.length === 0 ? kind : `${kind} ${base.slice(0, 120)}`, missingDependency: false };
+	}
+	const file = /['"]?([^'"\s]*\.(?:m?js|cjs|json|node))['"]?/.exec(text)?.[1]?.split(/[\\/]/).at(-1);
+	return { cause: file === undefined || file.length === 0 ? kind : `${kind} ${file.slice(0, 120)}`, missingDependency: false };
 }
 
 type SetupFailureDisposition = "context-overflow" | "retryable" | "host-final";
@@ -1167,13 +1191,15 @@ export function createLogicalProvider(
 		account: LogicalPhysicalAccount,
 		cause: unknown,
 	): void => {
+		const fault = hostLoadFault(cause);
 		box.hostStaleInstall = true;
+		box.hostMissingDependency = fault.missingDependency;
 		box.overflow = false;
 		box.preStartRetryable = false;
 		try {
 			deps.onDiagnostic?.(
 				`logical dispatch for ${account.providerId} failed loading host code (host_stale_install: ` +
-					`${hostStaleInstallCause(cause)}); restart the pi session`,
+					`${fault.cause}); ${fault.missingDependency ? "reinstall the missing package" : "restart the pi session"}`,
 			);
 		} catch {
 			// A diagnostic sink failure cannot replace a provider result.
@@ -1247,6 +1273,8 @@ export function createLogicalProvider(
 		preStartRetryable: boolean;
 		/** Setup failed because this pi process could not load its own code. */
 		hostStaleInstall?: boolean;
+		/** The missing module is a bare package, so a reinstall, not a restart, helps. */
+		hostMissingDependency?: boolean;
 		/** Whether the caller or provider shutdown aborted this physical request. */
 		cancelled?: () => boolean;
 		/**
@@ -1283,7 +1311,10 @@ export function createLogicalProvider(
 			let sawTerminal = false;
 			// Whether any event other than a leading `start` arrived. A `start`
 			// only reports that response headers arrived, so a failure after it is
-			// still the stream's first real event.
+			// still the stream's first real event. Every other non-terminal event
+			// is output (it also sets `box.sawOutput`), and a terminal ends the
+			// loop, so on the thrown path `!sawEvent` means "no content yet": this
+			// is the signal the setup-only classifications key on.
 			let sawEvent = false;
 			const recordFailureOnce = (error: unknown): HostRetryCooldownReceipt => {
 				if (box.hostStaleInstall === true) box.receipt ??= hostFaultReceipt();
@@ -1779,7 +1810,7 @@ export function createLogicalProvider(
 		return {
 			...syntheticErrorMessage(
 				modelId,
-				`${stale ? HOST_STALE_INSTALL_MESSAGE : errorMessage} ${evidence}`,
+				`${stale ? (box?.hostMissingDependency === true ? HOST_MISSING_DEPENDENCY_MESSAGE : HOST_STALE_INSTALL_MESSAGE) : errorMessage} ${evidence}`,
 				physical === undefined ? undefined : projectTerminalUsage(physical),
 				physical === undefined ? undefined : finiteNonNegative(physical.timestamp),
 			),

package/src/public-status-projection.ts

@@ -0,0 +1,187 @@
+import type { CostReport } from "./cost-report.js";
+import {
+	PUBLIC_ACCOUNT_STATUS_VERSION,
+	type PublicAccountHealth,
+	type PublicAccountStatusRecord,
+	type PublicAccountStatusSnapshot,
+	type PublicCostEstimate,
+} from "./public-status.js";
+import { accountHealth, type AccountStatusView } from "./status-view.js";
+import type { UsageSnapshot } from "./usage.js";
+
+/**
+ * Owner-side projection for the `./public-status` contract.
+ *
+ * Only the extension loads this module. Consumers import the dependency-free
+ * contract in `public-status.js` (typed by `public-status.d.ts`) instead.
+ */
+
+export interface PublicAccountStatusInput {
+	readonly nowMs: number;
+	/**
+	 * Live account views. The caller must put only an operator-configured label
+	 * in `label`; this projection publishes whatever it is given.
+	 */
+	readonly accounts: readonly AccountStatusView[];
+	readonly costReport?: CostReport;
+}
+
+function publicText(value: string, maximumBytes: number): string {
+	if (
+		value.length === 0 ||
+		Buffer.byteLength(value, "utf8") > maximumBytes ||
+		/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(value)
+	) {
+		throw new TypeError("Invalid public account status text.");
+	}
+	return value;
+}
+
+function publicTimestamp(value: number | undefined): number | null {
+	return value !== undefined && Number.isSafeInteger(value) && value >= 0
+		? value
+		: null;
+}
+
+function publicCount(value: number | undefined): number | null {
+	return value !== undefined && Number.isSafeInteger(value) && value >= 0
+		? value
+		: null;
+}
+
+function usageHeadroomPercent(usage: UsageSnapshot | undefined): number | null {
+	if (usage === undefined) return null;
+	const fractions: number[] = [];
+	if (usage.utilization !== undefined && Number.isFinite(usage.utilization)) {
+		fractions.push(1 - Math.min(1, Math.max(0, usage.utilization)));
+	}
+	if (
+		usage.remainingRequests !== undefined &&
+		usage.observedPeakRequests !== undefined &&
+		usage.observedPeakRequests > 0
+	) {
+		fractions.push(usage.remainingRequests / usage.observedPeakRequests);
+	}
+	if (
+		usage.remainingTokens !== undefined &&
+		usage.observedPeakTokens !== undefined &&
+		usage.observedPeakTokens > 0
+	) {
+		fractions.push(usage.remainingTokens / usage.observedPeakTokens);
+	}
+	if (fractions.length === 0) return null;
+	const headroom = Math.min(...fractions);
+	return Math.round(Math.min(1, Math.max(0, headroom)) * 100_000) / 1_000;
+}
+
+function recoveryAt(account: AccountStatusView): number | null {
+	const candidates = [
+		publicTimestamp(account.coolingUntilMs),
+		publicTimestamp(account.usage?.recoveryAtMs),
+		publicTimestamp(account.usageFetch?.nextAttemptAtMs),
+	].filter((value): value is number => value !== null);
+	return candidates.length === 0 ? null : Math.max(...candidates);
+}
+
+/**
+ * The month's API-equivalent estimate, or nothing. An unpriced report has no
+ * estimate, and an invalid one (a non-finite or negative amount, or bad or
+ * inverted period bounds) is dropped rather than thrown: a bad cost figure
+ * must not turn the whole snapshot, and its account health, into a
+ * `source-error`.
+ */
+function publicCostEstimate(
+	report: CostReport | undefined,
+): PublicCostEstimate | undefined {
+	const current = report?.current;
+	if (current?.apiEquivalent.status !== "priced") return undefined;
+	const amount = current.apiEquivalent.estimatedUsd;
+	const periodStart = publicTimestamp(current.periodStartMs);
+	const periodEnd = publicTimestamp(current.periodEndMs);
+	const observedAt = publicTimestamp(report?.generatedAtMs);
+	if (
+		!Number.isFinite(amount) ||
+		amount < 0 ||
+		periodStart === null ||
+		periodEnd === null ||
+		periodEnd < periodStart ||
+		observedAt === null
+	) {
+		return undefined;
+	}
+	return {
+		estimateId: `api-equivalent:${periodStart}:${periodEnd}`,
+		accountId: null,
+		classification: "estimate-not-billing",
+		source: "pi-multi-account:api-equivalent-public-rates",
+		currency: "USD",
+		amount,
+		periodStart,
+		periodEnd,
+		observedAt,
+	};
+}
+
+/**
+ * Copies the status command's live state into the narrow, renderer-independent
+ * public read projection. Credential material, fingerprints, diagnostics, and
+ * model-routing details have no fields in this result and cannot survive.
+ *
+ * The v1 consumer rejects a whole snapshot that names any family outside
+ * anthropic and openai-codex, so accounts of every other family (for example
+ * google-antigravity) are omitted rather than published or thrown on.
+ */
+export function projectPublicAccountStatus(
+	input: PublicAccountStatusInput,
+): PublicAccountStatusSnapshot {
+	if (!Number.isSafeInteger(input.nowMs) || input.nowMs < 0) {
+		throw new TypeError(
+			"Public account status observation time must be a timestamp.",
+		);
+	}
+	const accounts: PublicAccountStatusRecord[] = [];
+	for (const account of input.accounts) {
+		const family = account.family;
+		if (family !== "anthropic" && family !== "openai-codex") continue;
+		const accountId = publicText(account.providerId, 256);
+		const usage = account.usage;
+		const usageFetch = account.usageFetch;
+		const health: PublicAccountHealth = accountHealth(account, input.nowMs);
+		accounts.push({
+			accountId,
+			label: publicText(account.label ?? accountId, 256),
+			family,
+			active: account.active,
+			health,
+			usageHeadroomPercent: usageHeadroomPercent(usage),
+			remainingRequests: publicCount(usage?.remainingRequests),
+			remainingTokens: publicCount(usage?.remainingTokens),
+			recoveryAt: recoveryAt(account),
+			credentialExpiresAt: publicTimestamp(account.expiresAtMs),
+			fetchObservedAt: publicTimestamp(usage?.snapshotAtMs),
+			fetchStale:
+				usage === undefined ||
+				usage.stale === true ||
+				usageFetch?.disabled === true ||
+				(usageFetch?.failureCount ?? 0) > 0,
+			costEstimateIds: [],
+		});
+	}
+	if (
+		new Set(accounts.map((account) => account.accountId)).size !==
+		accounts.length
+	) {
+		throw new TypeError("Duplicate public account id.");
+	}
+
+	const costEstimates: PublicCostEstimate[] = [];
+	const costEstimate = publicCostEstimate(input.costReport);
+	if (costEstimate !== undefined) costEstimates.push(costEstimate);
+
+	return {
+		sourceVersion: PUBLIC_ACCOUNT_STATUS_VERSION,
+		observedAtMs: input.nowMs,
+		accounts,
+		costEstimates,
+	};
+}

package/src/public-status.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Types for the public, read-only live account status contract
+ * (`./public-status` subpath). The runtime is `public-status.js`, plain
+ * JavaScript with no imports; this hand-written declaration file must export
+ * exactly the same names (test/public-status.test.ts checks this) and, like
+ * the runtime, has no imports.
+ *
+ * The wire shape is version 1 and is frozen: the query channel, the
+ * `sourceVersion`, and the record and cost-estimate shapes must not change in
+ * place. A new shape needs a new version.
+ */
+
+export declare const PUBLIC_ACCOUNT_STATUS_VERSION: "public-status-v1";
+
+export declare const PUBLIC_ACCOUNT_STATUS_SERVICE_VERSION: 1;
+export declare const PUBLIC_ACCOUNT_STATUS_SERVICE_QUERY: "pi-multi-account:public-status-service-query:v1";
+
+/** The families the v1 consumer accepts. Other families are omitted. */
+export type PublicAccountStatusFamily = "anthropic" | "openai-codex";
+
+/** Coarse health, ordered most-severe first. */
+export type PublicAccountHealth =
+	| "unavailable"
+	| "disabled"
+	| "cooling"
+	| "rate-limited"
+	| "exhausted"
+	| "low-headroom"
+	| "ready";
+
+export interface PublicAccountStatusRecord {
+	readonly accountId: string;
+	/** Operator-configured label, else the provider id. Never token-derived. */
+	readonly label: string;
+	readonly family: PublicAccountStatusFamily;
+	readonly active: boolean;
+	readonly health: PublicAccountHealth;
+	readonly usageHeadroomPercent: number | null;
+	readonly remainingRequests: number | null;
+	readonly remainingTokens: number | null;
+	readonly recoveryAt: number | null;
+	readonly credentialExpiresAt: number | null;
+	readonly fetchObservedAt: number | null;
+	readonly fetchStale: boolean;
+	readonly costEstimateIds: readonly string[];
+}
+
+export interface PublicCostEstimate {
+	readonly estimateId: string;
+	readonly accountId: string | null;
+	readonly classification: "estimate-not-billing";
+	readonly source: "pi-multi-account:api-equivalent-public-rates";
+	readonly currency: "USD";
+	readonly amount: number;
+	readonly periodStart: number;
+	readonly periodEnd: number;
+	readonly observedAt: number;
+}
+
+export interface PublicAccountStatusSnapshot {
+	readonly sourceVersion: typeof PUBLIC_ACCOUNT_STATUS_VERSION;
+	readonly observedAtMs: number;
+	readonly accounts: readonly PublicAccountStatusRecord[];
+	readonly costEstimates: readonly PublicCostEstimate[];
+}
+
+export type PublicAccountStatusUnavailableReason =
+	| "owner-unavailable"
+	| "source-error";
+
+export type PublicAccountStatusReadResult =
+	| {
+			readonly status: "available";
+			readonly snapshot: PublicAccountStatusSnapshot;
+	  }
+	| {
+			readonly status: "unavailable";
+			readonly reason: PublicAccountStatusUnavailableReason;
+	  };
+
+export interface PublicAccountStatusReader {
+	read(): Promise<PublicAccountStatusReadResult>;
+}
+
+export type PublicAccountStatusReaderDiscovery =
+	| {
+			readonly status: "available";
+			readonly reader: PublicAccountStatusReader;
+	  }
+	| {
+			readonly status: "unsupported";
+	  };
+
+/** Structurally compatible with Pi's `pi.events`. */
+export interface PublicAccountStatusEventBus {
+	emit(channel: string, payload: unknown): void;
+	on(channel: string, handler: (payload: unknown) => void): () => void;
+}
+
+/**
+ * Register the owner extension's read-only status service on Pi's shared event
+ * transport. The callback owns the live state; this module neither stores
+ * credentials nor creates a second account manager. A throwing callback reads
+ * as `source-error` and its message never reaches the consumer.
+ */
+export declare function registerPublicAccountStatusService(
+	events: Pick<PublicAccountStatusEventBus, "on">,
+	read: () =>
+		| PublicAccountStatusReadResult
+		| Promise<PublicAccountStatusReadResult>,
+): () => void;
+
+/** Discover the optional live owner without treating absence as owner failure. */
+export declare function discoverPublicAccountStatusReader(
+	events: Pick<PublicAccountStatusEventBus, "emit">,
+): PublicAccountStatusReaderDiscovery;

package/src/public-status.js

@@ -0,0 +1,90 @@
+// Public, read-only live account status contract (`./public-status` subpath).
+//
+// This module is the whole runtime a consumer imports. It is plain JavaScript
+// so plain Node can load it from node_modules without a TypeScript loader, and
+// it deliberately has NO imports: loading the subpath must never load the
+// extension, Pi, or any credential-adjacent module. Its types live in the
+// hand-written `public-status.d.ts` beside it; the two must export the same
+// names (test/public-status.test.ts checks this). The owner-side projection
+// lives in `public-status-projection.ts`, which only the extension loads.
+//
+// The wire shape is version 1 and is frozen: the query channel, the
+// `sourceVersion`, and the record and cost-estimate shapes must not change in
+// place. A new shape needs a new version.
+
+export const PUBLIC_ACCOUNT_STATUS_VERSION = "public-status-v1";
+
+export const PUBLIC_ACCOUNT_STATUS_SERVICE_VERSION = 1;
+export const PUBLIC_ACCOUNT_STATUS_SERVICE_QUERY =
+	"pi-multi-account:public-status-service-query:v1";
+
+function record(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isQuery(value) {
+	return (
+		record(value) &&
+		value["version"] === PUBLIC_ACCOUNT_STATUS_SERVICE_VERSION &&
+		Object.keys(value).every((key) => key === "version" || key === "response")
+	);
+}
+
+function isResponse(value) {
+	return (
+		record(value) &&
+		value["version"] === PUBLIC_ACCOUNT_STATUS_SERVICE_VERSION &&
+		typeof value["createReader"] === "function" &&
+		Object.keys(value).every(
+			(key) => key === "version" || key === "createReader",
+		)
+	);
+}
+
+/**
+ * Register the owner extension's read-only status service on Pi's shared event
+ * transport. The callback owns the live state; this module neither stores
+ * credentials nor creates a second account manager. A throwing callback reads
+ * as `source-error` and its message never reaches the consumer.
+ */
+export function registerPublicAccountStatusService(events, read) {
+	return events.on(PUBLIC_ACCOUNT_STATUS_SERVICE_QUERY, (value) => {
+		if (!isQuery(value) || value.response !== undefined) return;
+		value.response = {
+			version: PUBLIC_ACCOUNT_STATUS_SERVICE_VERSION,
+			createReader: () =>
+				Object.freeze({
+					async read() {
+						try {
+							return await read();
+						} catch {
+							return { status: "unavailable", reason: "source-error" };
+						}
+					},
+				}),
+		};
+	});
+}
+
+/** Discover the optional live owner without treating absence as owner failure. */
+export function discoverPublicAccountStatusReader(events) {
+	const query = { version: PUBLIC_ACCOUNT_STATUS_SERVICE_VERSION };
+	try {
+		events.emit(PUBLIC_ACCOUNT_STATUS_SERVICE_QUERY, query);
+	} catch {
+		return { status: "unsupported" };
+	}
+	if (!isResponse(query.response)) return { status: "unsupported" };
+	try {
+		const reader = query.response.createReader();
+		if (!record(reader) || typeof reader["read"] !== "function") {
+			return { status: "unsupported" };
+		}
+		return {
+			status: "available",
+			reader: { read: reader.read.bind(reader) },
+		};
+	} catch {
+		return { status: "unsupported" };
+	}
+}