@herbertgao/pi-extensions 2026.9.9 → 2026.9.11

package/node_modules/pi-multi-account/pi-contract.ts

@@ -0,0 +1,281 @@
+/**
+ * What this extension assumes about Pi, written down — and checked.
+ *
+ * ## Why a ledger, and why it distinguishes two kinds of assumption
+ *
+ * A Pi update has broken this extension before, and the two cases were not the same shape:
+ *
+ * - **A method disappeared.** `AuthStorage` dropped `set()` on pi 0.84.x, which is what this
+ *   extension persisted a refreshed Anthropic token with. The file format never changed; the way
+ *   to write it did. Symptom: a fresh `/login anthropic` roughly once a day.
+ * - **A file schema was stricter than we wrote.** Slot catalogues were written into `models.json`
+ *   as bare id strings where Pi requires each model to be an object. Pi then rejected the
+ *   **entire file**, so every custom provider the user had disappeared at once.
+ *
+ * Both were silent from the outside and expensive to trace. The defence is not to guess better;
+ * it is to state the dependency, mark whether Pi actually promised it, and notice when it stops
+ * being true.
+ *
+ * ## Three rules this module exists to hold
+ *
+ * 1. **Read only the published files.** Pi hands the outside world exactly three:
+ *    `auth.json`, `models.json`, `settings.json`. A bare `pi -p --no-extensions` child reads
+ *    those and nothing else — verified by experiment on 2026-08-24. Anything we need from
+ *    deeper inside Pi is a design smell, not a dependency to formalise.
+ * 2. **Never write those files directly.** Writing goes through Pi, which owns locking,
+ *    concurrent access and migrations. The `AuthStorage` incident is what happens when the
+ *    write path is treated as ours.
+ * 3. **Check the shape, because nothing else will.** `auth.json` and `models.json` carry **no
+ *    schema version** (checked: neither has a version field; only `settings.json` records a Pi
+ *    version, which is the app's, not the format's). So a format change cannot announce itself.
+ *    The only way to notice is to look, and to say so out loud rather than fail later somewhere
+ *    unrelated.
+ *
+ * Pure by construction: this module reads nothing and writes nothing. It is handed already-parsed
+ * values and returns verdicts, so the whole ledger can be tested without a filesystem.
+ */
+
+/** Whether Pi actually promises a thing, or we merely observed it holding. */
+export type AssumptionKind = "documented" | "observed";
+
+export interface PiAssumption {
+  id: string;
+  /** The assumption, stated so it can be checked by a person after an update. */
+  fact: string;
+  kind: AssumptionKind;
+  /** Where it is promised, or where it was observed. */
+  surface: string;
+  /** What stops working here when it stops being true. */
+  breaks: string;
+}
+
+/**
+ * Every load-bearing assumption this extension makes about Pi.
+ *
+ * The `observed` rows are the re-check list after each Pi upgrade: they are behaviour nobody
+ * promised, and they can change without any note in a changelog.
+ */
+export const PI_ASSUMPTIONS: readonly PiAssumption[] = Object.freeze([
+  Object.freeze({
+    id: "auth-file",
+    fact: "Credentials live in auth.json, one entry per provider id, each carrying a `type` of `oauth` or `api_key`.",
+    kind: "documented" as const,
+    surface: "docs/providers.md, docs/models.md",
+    breaks: "Account discovery: the rotation is built from these entries.",
+  }),
+  Object.freeze({
+    id: "models-file",
+    fact: "models.json holds `providers`, and each provider's `models` is an array of OBJECTS; a bare id string invalidates the whole file.",
+    kind: "documented" as const,
+    surface: "docs/custom-provider.md, docs/models.md",
+    breaks: "Every custom provider the user has, not only ours — Pi rejects the file wholesale.",
+  }),
+  Object.freeze({
+    id: "settings-default-model-key",
+    fact: "settings.json carries `defaultProvider` and `defaultModel`.",
+    kind: "documented" as const,
+    surface: "docs/settings.md",
+    breaks: "Nothing directly; it is the key the next row writes to.",
+  }),
+  Object.freeze({
+    id: "settings-default-model-versioned-persistence",
+    fact: "Pi <=0.84.2 writes defaultProvider/defaultModel on every model switch; Pi >=0.84.3 keeps ordinary model selection session-scoped and writes the global default only for an explicit persistent selection.",
+    kind: "documented" as const,
+    surface: "Pi 0.84.3 changelog and AgentSession.setModel(model, { persist }): ordinary selection no longer rewrites the global default; Ctrl+S remains the explicit persistence action.",
+    breaks: "A bare child launched without an explicit --model inherits only the saved global default, not pi-multi-account's live rotation slot. Explicitly model-pinned broker/subagent children are unaffected.",
+  }),
+  Object.freeze({
+    id: "child-reads-published-files-only",
+    fact: "A `pi -p --no-extensions` child resolves providers from models.json plus built-ins, and credentials from auth.json — it cannot see extension-registered providers.",
+    kind: "documented" as const,
+    surface: "docs/usage.md (--no-extensions); confirmed by experiment 2026-08-24",
+    breaks: "Every claim about what a bare child can run on.",
+  }),
+  Object.freeze({
+    id: "oauth-needs-provider-declared-flow",
+    fact: "Pi honours an OAuth credential only for a provider definition that declares the flow; a models.json entry declares none, so an OAuth token under that key is never used.",
+    kind: "observed" as const,
+    surface: "Measured 2026-08-24: a published alias slot with an OAuth credential fails with \"No API key found\"; the built-in provider with the same credential authenticates.",
+    breaks: "Publishing OAuth rotation slots for children — the reason a parent-owned proxy with a placeholder key is required rather than optional.",
+  }),
+  Object.freeze({
+    id: "credential-writes-go-through-pi",
+    fact: "Credential writes must use Pi's own locked storage API, never a direct file write.",
+    kind: "documented" as const,
+    surface: "AuthStorage; learned the hard way when pi 0.84.x dropped set() and a refreshed token was thrown away daily.",
+    breaks: "Token refresh: a rotated credential that cannot be persisted is a burned credential.",
+  }),
+]);
+
+/** The three files Pi publishes to the outside world. Nothing else is an interface. */
+export const PUBLISHED_FILES = Object.freeze(["auth.json", "models.json", "settings.json"] as const);
+
+export interface ShapeVerdict {
+  file: string;
+  ok: boolean;
+  /** Populated when `ok` is false: what looked wrong, in terms a person can act on. */
+  problems: string[];
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+const SESSION_SCOPED_MODEL_SELECTION_SINCE = Object.freeze([0, 84, 3] as const);
+
+/**
+ * Whether an ordinary Pi model switch is expected to rewrite the saved global default.
+ *
+ * Pi 0.84.3 deliberately made model/thinking selection session-scoped unless the caller passes
+ * `{ persist: true }` (the TUI's explicit Ctrl+S action). Unknown/non-semver hosts are treated as
+ * session-scoped: emitting a loud compatibility warning from an assumption we cannot establish is
+ * worse than omitting an optional legacy diagnostic.
+ */
+export function piAutoPersistsSelectedModel(version: string): boolean {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version.trim());
+  if (!match) return false;
+  const actual = match.slice(1, 4).map(Number) as [number, number, number];
+  for (let index = 0; index < SESSION_SCOPED_MODEL_SELECTION_SINCE.length; index++) {
+    const delta = actual[index] - SESSION_SCOPED_MODEL_SELECTION_SINCE[index];
+    if (delta !== 0) return delta < 0;
+  }
+  return false;
+}
+
+/**
+ * `auth.json`: a flat map of provider id → credential record carrying a `type`.
+ *
+ * Deliberately shallow. This must never touch, log or return a secret — it reports the shape of
+ * the container and nothing about what is inside it.
+ */
+export function checkAuthShape(raw: unknown): ShapeVerdict {
+  const problems: string[] = [];
+  if (!isPlainObject(raw)) {
+    return { file: "auth.json", ok: false, problems: ["not a JSON object"] };
+  }
+  for (const [provider, entry] of Object.entries(raw)) {
+    if (!isPlainObject(entry)) {
+      problems.push(`${provider}: entry is not an object`);
+      continue;
+    }
+    const type = entry.type;
+    if (type !== "oauth" && type !== "api_key") {
+      // A new credential kind is not necessarily a break — but it is exactly the kind of quiet
+      // change that makes account discovery skip an account without saying why.
+      problems.push(`${provider}: unfamiliar credential type ${JSON.stringify(type)}`);
+    }
+  }
+  return { file: "auth.json", ok: problems.length === 0, problems };
+}
+
+/**
+ * `models.json`: `providers` → each with a `models` ARRAY OF OBJECTS.
+ *
+ * The array-of-objects rule is the one that has already cost a user every custom provider they
+ * had: Pi validates the whole file and rejects all of it when one entry is a bare string.
+ */
+export function checkModelsShape(raw: unknown): ShapeVerdict {
+  const problems: string[] = [];
+  if (!isPlainObject(raw)) {
+    return { file: "models.json", ok: false, problems: ["not a JSON object"] };
+  }
+  const providers = raw.providers;
+  if (providers === undefined) {
+    // An absent registry is legitimate — the user may have no custom providers at all.
+    return { file: "models.json", ok: true, problems: [] };
+  }
+  if (!isPlainObject(providers)) {
+    return { file: "models.json", ok: false, problems: ["`providers` is not an object"] };
+  }
+  for (const [provider, definition] of Object.entries(providers)) {
+    if (!isPlainObject(definition)) {
+      problems.push(`${provider}: definition is not an object`);
+      continue;
+    }
+    const models = definition.models;
+    if (models === undefined) continue;
+    if (!Array.isArray(models)) {
+      problems.push(`${provider}: \`models\` is not an array`);
+      continue;
+    }
+    const stringEntries = models.filter((model) => typeof model === "string").length;
+    if (stringEntries > 0) {
+      problems.push(
+        `${provider}: ${stringEntries} model entr${stringEntries === 1 ? "y is" : "ies are"} a bare string; Pi requires objects and rejects the ENTIRE file, taking every other custom provider with it`,
+      );
+    }
+  }
+  return { file: "models.json", ok: problems.length === 0, problems };
+}
+
+/**
+ * `settings.json`: the saved default keys are optional, but must be strings when present.
+ *
+ * Since Pi 0.84.3 their absence is ordinary: a live model selection is session-scoped unless the
+ * user explicitly persists it. Whether a saved value must track the live model is therefore a
+ * versioned behavioural check, not part of the file's shape.
+ */
+export function checkSettingsShape(raw: unknown): ShapeVerdict {
+  const problems: string[] = [];
+  if (!isPlainObject(raw)) {
+    return { file: "settings.json", ok: false, problems: ["not a JSON object"] };
+  }
+  const provider = raw.defaultProvider;
+  const model = raw.defaultModel;
+  if (provider !== undefined && typeof provider !== "string") problems.push("`defaultProvider` is not a string");
+  if (model !== undefined && typeof model !== "string") problems.push("`defaultModel` is not a string");
+  if ((provider === undefined) !== (model === undefined)) {
+    problems.push("`defaultProvider` and `defaultModel` must either both be strings or both be absent");
+  }
+  return { file: "settings.json", ok: problems.length === 0, problems };
+}
+
+/**
+ * One message for the user when a published file no longer looks the way we depend on it looking.
+ * Returns `undefined` when everything matches, so a healthy install stays silent.
+ */
+export function describeContractDrift(verdicts: readonly ShapeVerdict[]): string | undefined {
+  const broken = verdicts.filter((verdict) => !verdict.ok);
+  if (broken.length === 0) return undefined;
+  const lines = broken.flatMap((verdict) => [
+    `  ${verdict.file}:`,
+    ...verdict.problems.map((problem) => `    - ${problem}`),
+  ]);
+  return [
+    "pi-multi-account: a file Pi publishes no longer matches what this extension depends on.",
+    "This is usually a Pi upgrade changing a format that carries no version, so nothing announced it.",
+    ...lines,
+    "Rotation may behave oddly until this is resolved; run /multi-account status for the current view.",
+  ].join("\n");
+}
+
+/**
+ * Legacy-only behavioural check: on Pi <=0.84.2, does `settings.json` name the model running now?
+ *
+ * Pi >=0.84.3 intentionally separates the live session selection from the saved global default,
+ * so callers MUST gate this check with `piAutoPersistsSelectedModel()`. A bare child without an
+ * explicit `--model` then inherits the saved default by design; a broker/subagent child with an
+ * explicit provider/model remains isolated from that global value.
+ */
+export function checkSettingsTracksActive(
+  raw: unknown,
+  active: { provider: string; id: string },
+): ShapeVerdict {
+  const base = checkSettingsShape(raw);
+  if (!base.ok) return base;
+  const settings = raw as Record<string, unknown>;
+  const problems: string[] = [];
+  const recorded = `${settings.defaultProvider ?? "(unset)"}/${settings.defaultModel ?? "(unset)"}`;
+  const live = `${active.provider}/${active.id}`;
+  if (recorded !== live) {
+    problems.push(
+      `records ${recorded} while the session is running ${live}; Pi <=0.84.2 is expected to rewrite both keys on every model switch, while a bare extension-free child without --model reads the saved value — so that child would run on ${recorded}, not on the account the rotation selected`,
+    );
+  }
+  return { file: "settings.json", ok: problems.length === 0, problems };
+}
+
+/** The assumptions to re-check after a Pi upgrade — the ones nobody promised. */
+export function observedAssumptions(): readonly PiAssumption[] {
+  return PI_ASSUMPTIONS.filter((assumption) => assumption.kind === "observed");
+}

package/node_modules/pi-multi-account/provider-payload-stream.ts

@@ -0,0 +1,44 @@
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+type Shape = (payload: any, model: any, options: any) => any;
+type Api = { streamSimple: (model: any, context: any, options: any) => any };
+const requireLocal = createRequire(import.meta.url);
+let registry: { getApiProvider: (api: string) => Api | undefined } | undefined;
+
+function nativeApi(api: string): Api {
+	if (!registry) {
+		// Pi >= 0.80 moved the API registry to /compat. Resolve lazily so merely
+		// listing OAuth providers does not require loading a transport.
+		for (const entry of ["@earendil-works/pi-ai/compat", "@earendil-works/pi-ai"]) {
+			try {
+				const candidate = requireLocal(fileURLToPath(import.meta.resolve(entry)));
+				if (typeof candidate.getApiProvider === "function") { registry = candidate; break; }
+			} catch { /* Try the older public entry point. */ }
+		}
+	}
+	const provider = registry?.getApiProvider(api);
+	if (!provider) throw new Error(`Pi native API is unavailable: ${api}`);
+	return provider;
+}
+
+/** Provider-level shaping applies to every public Pi client, including calls
+ * outside the interactive agent's before_provider_request event lifecycle. */
+export function createPayloadStream(shape: Shape, resolveApi = nativeApi) {
+	return (model: any, context: any, options: any = {}) => resolveApi(model.api).streamSimple(model, context, {
+		...options,
+		onPayload: async (payload: any, actualModel: any) => {
+			const replacement = await options.onPayload?.(payload, actualModel);
+			const current = replacement === undefined ? payload : replacement;
+			const shaped = await shape(current, actualModel, options);
+			return shaped === undefined ? current : shaped;
+		},
+	});
+}
+
+export const cursorPayloadStream = createPayloadStream((payload, _model, options) => {
+	if (payload && typeof payload === "object" && typeof options.sessionId === "string" && options.sessionId.trim()) {
+		payload.pi_session_id = options.sessionId;
+	}
+	return payload;
+});

package/node_modules/pi-multi-account/provider-priority.ts

@@ -0,0 +1,189 @@
+/**
+ * Where work goes once the account it was on cannot take it.
+ *
+ * ## What was actually happening
+ *
+ * Rotation already gets the first step right: of 602 automatic failovers in this machine's black
+ * box, 588 stayed inside the same provider family — the same subscription, the same model, just
+ * another account. That is the behaviour to protect, and nothing here weakens it.
+ *
+ * The other 14 are the problem. Those are the hops taken once every account of the current family
+ * was spent, and they went nowhere in particular:
+ *
+ *     kimi-coding → openai-codex   3      cursor       → openai-codex  1
+ *     openai-codex → anthropic     3      anthropic    → cursor        1
+ *     kimi-coding → anthropic      2      ollama       → kimi-coding   2
+ *     kimi-coding → cursor         2
+ *
+ * There was no ladder being followed, because nothing expressed one. The comparator ordered
+ * cross-family candidates by liveness telemetry — measured-free first, then predicted-free, then
+ * whoever refused longest ago — and only fell through to the configured family order as a last
+ * tiebreak, by which point it almost never spoke. So the answer to "the whole family is spent,
+ * where now?" was whatever the telemetry happened to say that second.
+ *
+ * The second half of the same gap: `providerOrder` could only ever name the six specially-managed
+ * families. Accounts outside them — openrouter, zai, minimax, opencode-go-api, openai — could not
+ * be placed in the order at all, so they sat permanently last by construction. In 602 automatic
+ * failovers not one ever reached them. That is right as a default (they bill per token, while the
+ * managed families are flat-rate subscriptions), but it should be a stated policy the user can
+ * change, not an accident of the type system.
+ *
+ * ## The ladder
+ *
+ * A flat, ordered list of provider GROUPS. A group is a managed family (`anthropic`,
+ * `openai-codex`, `kimi-coding`, `cursor`, `qwen`, `ollama`) or the base id of anything else the
+ * user is logged in to (`openrouter`, `zai`, `minimax`, …) — numbered rotation slots of the same
+ * account (`openai-codex-account-3`) all collapse to one group, because preferring one slot over
+ * its sibling is rotation's job, not the ladder's.
+ *
+ * Three rules, and they are deliberately narrow:
+ *
+ * 1. **The ladder never overrides same-family.** Staying on the family preserves the model the
+ *    user picked, and it is the step that already works. The ladder only decides what happens
+ *    after that step has run out.
+ * 2. **The ladder never overrides availability.** An account on a real cooldown is not chosen
+ *    while a free one exists, whatever the ladder says. The ladder reorders candidates that are
+ *    all selectable right now; it does not resurrect spent ones.
+ * 3. **A group nobody ranked sorts after every group somebody did**, keeping its existing order
+ *    among its unranked peers. Silence is not a preference, so it must not act like one.
+ *
+ * Within those bounds the ladder outranks the liveness heuristics (`confirmed`, `predictedBusy`),
+ * and that is the point. Those heuristics answer "did the provider recently tell us it is free?",
+ * whose honest answer for an unmeasurable provider is always "no" — absence of measurement, not
+ * evidence of exhaustion. A stated preference is better evidence than a missing measurement. The
+ * cost when the ladder is wrong is bounded and self-correcting: one request, one refusal, a
+ * cooldown, and the account drops out of the candidate list on its own.
+ */
+
+/** Groups this extension manages directly: OAuth refresh, quota telemetry, live catalogue. */
+export const MANAGED_GROUPS = [
+  "anthropic",
+  "openai-codex",
+  "kimi-coding",
+  "cursor",
+  "qwen",
+  "ollama",
+] as const;
+
+/**
+ * The ladder shipped by default.
+ *
+ * Flat-rate subscriptions with real quota telemetry first, strongest coding models earliest;
+ * then the cheap/local tier; then — by omission — everything else, which is where per-token
+ * billing lands. It is the same sequence rotation already used as its final tiebreak, promoted
+ * to a stated policy so the cross-family hop stops being decided by whatever the telemetry
+ * happened to say at that moment.
+ */
+export const DEFAULT_PROVIDER_PRIORITY: string[] = [
+  "anthropic",
+  "openai-codex",
+  "kimi-coding",
+  "cursor",
+  "qwen",
+  "ollama",
+];
+
+/** What people actually type. Kept small and obvious rather than clever. */
+const ALIASES: Record<string, string> = {
+  claude: "anthropic",
+  opus: "anthropic",
+  sonnet: "anthropic",
+  codex: "openai-codex",
+  chatgpt: "openai-codex",
+  gpt: "openai-codex",
+  openaicodex: "openai-codex",
+  kimi: "kimi-coding",
+  k3: "kimi-coding",
+  moonshot: "kimi-coding",
+  qwen: "qwen",
+  alibaba: "qwen",
+  dashscope: "qwen",
+  glm: "zai",
+  zhipu: "zai",
+  router: "openrouter",
+};
+
+/**
+ * Reduce anything the user or the runtime might say to one group name.
+ *
+ * Handles a bare family, a numbered rotation slot (`kimi-coding-account-2`), a provider/model
+ * pair (`openai-codex/gpt-5.6-sol`), and the common nicknames above. Unknown names pass through
+ * normalised rather than being rejected: a provider this build has never heard of is exactly the
+ * case the old `ProviderFamily[]` type made unrankable, and it must be rankable now.
+ */
+export function normalizeGroup(raw: string): string {
+  const first = String(raw ?? "")
+    .trim()
+    .split("/")[0]
+    .trim()
+    .toLowerCase();
+  if (!first) return "";
+  const base = first.replace(/-account-\d+$/, "");
+  if ((MANAGED_GROUPS as readonly string[]).includes(base)) return base;
+  const alias = ALIASES[base.replace(/[^a-z0-9]/g, "")];
+  return alias ?? base;
+}
+
+/**
+ * Clean a user-supplied ladder: normalise each entry, drop blanks, drop repeats (first mention
+ * wins, because that is what the person meant by putting it there).
+ */
+export function normalizePriority(raw: unknown): string[] {
+  const list = Array.isArray(raw) ? raw : typeof raw === "string" ? raw.split(/[\s,]+/) : [];
+  const out: string[] = [];
+  for (const item of list) {
+    if (typeof item !== "string") continue;
+    const group = normalizeGroup(item);
+    if (!group || out.includes(group)) continue;
+    out.push(group);
+  }
+  return out;
+}
+
+/**
+ * Position of a group on the ladder. `Number.MAX_SAFE_INTEGER` for anything unranked, so an
+ * unranked group sorts after every ranked one without needing a second comparison.
+ */
+export function priorityRank(group: string, ladder: readonly string[]): number {
+  const normalized = normalizeGroup(group);
+  const index = ladder.indexOf(normalized);
+  return index < 0 ? Number.MAX_SAFE_INTEGER : index;
+}
+
+/**
+ * Comparator contribution for two candidates.
+ *
+ * Returns 0 — "no opinion, let the next tiebreak decide" — whenever neither side is ranked, and
+ * also when both sit at the same position. Only an actual difference in stated preference moves
+ * anything, which is what keeps rule 3 honest: an unranked pair is left exactly as it was.
+ */
+export function comparePriority(
+  groupA: string,
+  groupB: string,
+  ladder: readonly string[],
+): number {
+  if (ladder.length === 0) return 0;
+  const a = priorityRank(groupA, ladder);
+  const b = priorityRank(groupB, ladder);
+  if (a === b) return 0;
+  return a - b;
+}
+
+/** One line per rung, for `/multi-account priority` and the status panel. */
+export function describePriority(
+  ladder: readonly string[],
+  present: readonly string[] = [],
+): string[] {
+  const seen = new Set(present.map(normalizeGroup));
+  const lines = ladder.map((group, index) => {
+    const mark = seen.size === 0 ? "" : seen.has(group) ? "" : "  (not logged in)";
+    return `  ${index + 1}. ${group}${mark}`;
+  });
+  const rest = [...seen].filter((group) => !ladder.includes(group)).sort();
+  if (rest.length > 0) {
+    lines.push(`  ${ladder.length + 1}. everything else — ${rest.join(", ")}`);
+  } else {
+    lines.push(`  ${ladder.length + 1}. everything else`);
+  }
+  return lines;
+}

package/node_modules/pi-multi-account/slot-proxy-auth.ts

@@ -0,0 +1,167 @@
+/**
+ * How an OAuth slot is shown to an extension-free child without dropping the
+ * subscription token the parent still needs.
+ *
+ * ## Why this exists
+ *
+ * Pi's `resolveProviderAuth` keys off the stored credential *type* first. For a models.json-only
+ * provider (numbered `*-account-N` slots, and Cursor — which is not a Pi built-in) that means:
+ *
+ *   stored OAuth + no OAuth method on the provider → undefined → "No API key found"
+ *
+ * A published placeholder in models.json is never consulted. The empty-auth.json canary hid this,
+ * because there was no stored blob to win. On a real machine the blob is there — that is the
+ * subprocess failure for memory review/consolidation. Measured again 2026-08-30 after restart:
+ * the parent session was on `cursor/cursor-grok-4.6`, and
+ * `pi -p --no-extensions --model cursor/cursor-grok-4.6` died with `No API key found for cursor`
+ * while `anthropic/claude-opus-5` through the new loopback returned OK.
+ *
+ * The parent still needs the OAuth blob (refresh, identity headers, upstream). So while the
+ * matching parent-owned proxy is listening the child-facing `auth.json` entry becomes a
+ * non-secret api_key placeholder, and the OAuth blob lives in a sidecar only the parent reads.
+ * On stop, the blob is written back. Base `anthropic` is not shadowed: Pi already has an OAuth
+ * method for it, and the child presents the real token to the loopback, which admits it.
+ */
+import {
+	CURSOR_PROXY_PLACEHOLDER_KEY,
+	isCursorProviderId,
+} from "./cursor-bridge.ts";
+import {
+	needsChildFacingApiKey,
+	placeholderKeyFor,
+	proxyFamilyFor,
+	type ProxyFamily,
+} from "./slot-proxy.ts";
+
+export type AuthBlob = {
+	type?: string;
+	access?: string;
+	refresh?: string;
+	expires?: number;
+	key?: string;
+	accountId?: string;
+};
+
+/** The non-secret api_key a child must see, or undefined if this slot is not shadowed. */
+export function childFacingPlaceholderKey(slotId: string): string | undefined {
+	if (isCursorProviderId(slotId)) return CURSOR_PROXY_PLACEHOLDER_KEY;
+	if (!needsChildFacingApiKey(slotId)) return undefined;
+	const family = proxyFamilyFor(slotId);
+	return family ? placeholderKeyFor(family) : undefined;
+}
+
+export function needsAuthShadow(slotId: string): boolean {
+	return childFacingPlaceholderKey(slotId) !== undefined;
+}
+
+export function childFacingAuthEntry(family: ProxyFamily): AuthBlob {
+	return { type: "api_key", key: placeholderKeyFor(family) };
+}
+
+export function childFacingAuthEntryForSlot(slotId: string): AuthBlob | undefined {
+	const key = childFacingPlaceholderKey(slotId);
+	return key ? { type: "api_key", key } : undefined;
+}
+
+export function isChildFacingPlaceholder(
+	entry: AuthBlob | undefined,
+	family: ProxyFamily,
+): boolean {
+	return entry?.type === "api_key" && entry.key === placeholderKeyFor(family);
+}
+
+export function isChildFacingPlaceholderForSlot(
+	entry: AuthBlob | undefined,
+	slotId: string,
+): boolean {
+	const key = childFacingPlaceholderKey(slotId);
+	return !!key && entry?.type === "api_key" && entry.key === key;
+}
+
+/** What the parent should use for refresh/upstream: sidecar OAuth wins over a child-facing placeholder. */
+export function mergeParentAuth(
+	auth: Readonly<Record<string, AuthBlob>>,
+	sidecar: Readonly<Record<string, AuthBlob>>,
+): Record<string, AuthBlob> {
+	const out: Record<string, AuthBlob> = { ...auth };
+	for (const [slotId, hidden] of Object.entries(sidecar)) {
+		if (hidden?.type !== "oauth") continue;
+		if (isChildFacingPlaceholderForSlot(out[slotId], slotId)) out[slotId] = hidden;
+	}
+	return out;
+}
+
+export function applyShadowPlan(
+	slotId: string,
+	auth: Readonly<Record<string, AuthBlob>>,
+	sidecar: Readonly<Record<string, AuthBlob>>,
+): { auth: Record<string, AuthBlob>; sidecar: Record<string, AuthBlob>; changed: boolean } {
+	const facing = childFacingAuthEntryForSlot(slotId);
+	if (!facing) {
+		return { auth: { ...auth }, sidecar: { ...sidecar }, changed: false };
+	}
+	const entry = auth[slotId];
+	if (entry?.type === "oauth" && typeof entry.access === "string" && entry.access.length > 0) {
+		return {
+			auth: { ...auth, [slotId]: facing },
+			sidecar: { ...sidecar, [slotId]: entry },
+			changed: true,
+		};
+	}
+	return { auth: { ...auth }, sidecar: { ...sidecar }, changed: false };
+}
+
+export function applyRestorePlan(
+	slotId: string,
+	auth: Readonly<Record<string, AuthBlob>>,
+	sidecar: Readonly<Record<string, AuthBlob>>,
+): { auth: Record<string, AuthBlob>; sidecar: Record<string, AuthBlob>; changed: boolean } {
+	const hidden = sidecar[slotId];
+	const nextSidecar = { ...sidecar };
+	if (!hidden || hidden.type !== "oauth") {
+		return { auth: { ...auth }, sidecar: nextSidecar, changed: false };
+	}
+	delete nextSidecar[slotId];
+	if (isChildFacingPlaceholderForSlot(auth[slotId], slotId)) {
+		return {
+			auth: { ...auth, [slotId]: hidden },
+			sidecar: nextSidecar,
+			changed: true,
+		};
+	}
+	// Auth already holds a real OAuth blob (re-login while shadowed). Drop the stale copy.
+	return { auth: { ...auth }, sidecar: nextSidecar, changed: true };
+}
+
+export function applyShadowAll(
+	slotIds: readonly string[],
+	auth: Readonly<Record<string, AuthBlob>>,
+	sidecar: Readonly<Record<string, AuthBlob>>,
+): { auth: Record<string, AuthBlob>; sidecar: Record<string, AuthBlob>; changed: boolean } {
+	let nextAuth = { ...auth };
+	let nextSidecar = { ...sidecar };
+	let changed = false;
+	for (const slotId of slotIds) {
+		const step = applyShadowPlan(slotId, nextAuth, nextSidecar);
+		nextAuth = step.auth;
+		nextSidecar = step.sidecar;
+		changed = changed || step.changed;
+	}
+	return { auth: nextAuth, sidecar: nextSidecar, changed };
+}
+
+export function applyRestoreAll(
+	auth: Readonly<Record<string, AuthBlob>>,
+	sidecar: Readonly<Record<string, AuthBlob>>,
+): { auth: Record<string, AuthBlob>; sidecar: Record<string, AuthBlob>; changed: boolean } {
+	let nextAuth = { ...auth };
+	let nextSidecar = { ...sidecar };
+	let changed = false;
+	for (const slotId of Object.keys(sidecar)) {
+		const step = applyRestorePlan(slotId, nextAuth, nextSidecar);
+		nextAuth = step.auth;
+		nextSidecar = step.sidecar;
+		changed = changed || step.changed;
+	}
+	return { auth: nextAuth, sidecar: nextSidecar, changed };
+}