pi-jar 0.2.1 → 0.2.3

package/src/goal-loop.ts

@@ -5,6 +5,8 @@ import type { Goal, GoalStore } from "./goals.ts";
 import type { ModelRoleManager } from "./model-roles.ts";
 import { isSafePlanCommand } from "./plan-utils.ts";
 import type { Todo, TodoStore } from "./tasks.ts";
+import { setToolActive } from "./tool-activation.ts";
+import { projectWorkflowMessages } from "./workflow-context.ts";
 
 export const GOAL_TOOL = "jar_goal";
 export const DEFAULT_GOAL_ROUNDS = 8;
@@ -262,36 +264,23 @@ export class GoalLoop {
 
     this.pi.on("before_agent_start", async (_event, ctx) => {
       const goal = this.goal();
+      // jar_goal is only useful while a goal runs; inactive, it costs no schema or rules tokens.
+      setToolActive(this.pi, GOAL_TOOL, !!goal && goal.status !== "complete");
       if (!goal || goal.status === "complete") return;
       if (goal.status === "active" && !this.options.planActive()) await this.useRole(goal.phase === "audit" ? "advisor" : "implement", ctx);
       return { message: { customType: CONTEXT_TYPE, content: this.context(goal), display: false } };
     });
 
-    // Keep only the newest goal context and continuation. Context rewrites apply to a single LLM
-    // call, so prune on every call; scan in place and allocate only when something is stale.
+    // Never drop an already-sent goal prompt mid-history while the goal runs: that would re-bill the
+    // previous run uncached. Repeated identical context is sent once; a finished goal drops all.
     this.pi.on("context", async (event) => {
       const goal = this.goal();
       const active = !!goal && goal.status !== "complete";
-      let latestContext = -1;
-      let latestContinuation = -1;
-      let needsPrune = false;
-      for (let index = event.messages.length - 1; index >= 0; index--) {
-        const type = (event.messages[index] as { customType?: string }).customType;
-        if (type === CONTEXT_TYPE) {
-          if (!active || latestContext >= 0) needsPrune = true;
-          else latestContext = index;
-        } else if (type === CONTINUATION_TYPE) {
-          if (!active || latestContinuation >= 0) needsPrune = true;
-          else latestContinuation = index;
-        }
-      }
-      if (!needsPrune) return;
-      return { messages: event.messages.filter((raw, index) => {
-        const type = (raw as { customType?: string }).customType;
-        if (type === CONTEXT_TYPE) return active && index === latestContext;
-        if (type === CONTINUATION_TYPE) return active && index === latestContinuation;
-        return true;
-      }) };
+      const messages = projectWorkflowMessages(event.messages, {
+        [CONTEXT_TYPE]: { keep: active, dedupe: true },
+        [CONTINUATION_TYPE]: { keep: active }
+      });
+      if (messages) return { messages };
     });
 
     this.pi.on("agent_before_settle", async (event, ctx) => {

package/src/info-panels.ts

@@ -12,7 +12,10 @@ const DEFAULT_RESERVE = 16_384;
 export interface InfoPanelDeps {
   side: SideUsage;
   quota(ctx: ExtensionContext): Quota | undefined;
+  quotaFailure(ctx: ExtensionContext): { error: string; retryInMs: number } | undefined;
   quotaEnabled(): boolean;
+  /** Start a limit lookup when nothing fresh is cached: opening `/usage` is an explicit request. */
+  refreshQuota(ctx: ExtensionContext): void;
 }
 
 function reserveTokens(ctx: ExtensionContext): number {
@@ -61,10 +64,12 @@ export function registerInfoPanels(pi: ExtensionAPI, deps: InfoPanelDeps): void
       { name: "Usage", render: (width, fg) => {
         usage ??= collectUsage(sessionBranch(ctx) as never, deps.side.all());
         const quota = deps.quota(ctx);
+        const quotaFailure = quota ? undefined : deps.quotaFailure(ctx);
         return usageLines({
           stats: usage,
           ...(ctx.model?.provider ? { provider: ctx.model.provider } : {}),
           ...(quota ? { quota } : {}),
+          ...(quotaFailure ? { quotaFailure } : {}),
           quotaEnabled: deps.quotaEnabled(), now: Date.now()
         }, width, fg);
       } },
@@ -78,6 +83,7 @@ export function registerInfoPanels(pi: ExtensionAPI, deps: InfoPanelDeps): void
   const open = async (ctx: ExtensionContext, tab: number) => {
     try {
       const pages = tabs(ctx);
+      if (tab === 0) deps.refreshQuota(ctx);
       if (ctx.hasUI && ctx.mode === "tui") await openPanel(ctx, pages, tab);
       else ctx.ui.notify(pages[tab]!.render(100, plain).join("\n"), "info");
     } catch (error) { ctx.ui.notify("pi-jar: " + (error instanceof Error ? error.message : String(error)), "error"); }

package/src/model-roles.ts

@@ -153,6 +153,30 @@ export function describeRole(row: RoleRow): string {
   return row.role + "  ·  " + (row.spec?.startsWith("@") ? row.spec + " → " : "") + target + (row.scope === "project" ? "  · project" : "");
 }
 
+/** Delegated roles meant for a cheaper model than the main session: scouts discover, reviewers check. */
+export const ECONOMY_ROLES = ["scout", "reviewer"] as const;
+
+/**
+ * Economy roles whose subagents run on the main session model although a cheaper model is available, as
+ * jar_delegate picks it: the role's first available candidate, then the default role's, then the current
+ * model. The fix names @smol when the Fast role already points at a cheaper available model.
+ */
+export function premiumRoleWarnings(roles: Pick<ModelRoleManager, "resolveCandidates">, ctx: Pick<ExtensionContext, "model" | "modelRegistry">): string[] {
+  const main = ctx.model;
+  if (!main) return [];
+  const mainId = main.provider + "/" + main.id;
+  const mainPrice = main.cost.input + main.cost.output;
+  const models = ctx.modelRegistry.getAvailable();
+  const cheaper = new Set(models.filter((model) => model.cost.input + model.cost.output < mainPrice).map((model) => model.provider + "/" + model.id));
+  // Without a cheaper option there is nothing to recommend: a main model that is already economical is fine.
+  if (!cheaper.size) return [];
+  const available = new Set(models.map((model) => model.provider + "/" + model.id));
+  const pick = (role: string) => roles.resolveCandidates(role).map((item) => item.provider + "/" + item.model).find((id) => available.has(id));
+  const fix = cheaper.has(pick("smol") ?? "") ? "@smol" : "provider/model";
+  return ECONOMY_ROLES.filter((role) => (pick(role) ?? pick("default") ?? mainId) === mainId)
+    .map((role) => `⚠ ${role} subagents run on the main model ${mainId}; use a mini/haiku-class model: /roles set ${role} ${fix}`);
+}
+
 export class ModelRoleManager {
   private global: RoleConfig = readConfig(join(getAgentDir(), ROLE_FILE));
   private project: RoleConfig = { version: 2, roles: {} };
@@ -392,8 +416,8 @@ export class ModelRoleManager {
         const verb = (parts[0] ?? "").toLowerCase();
         if (!verb || verb === "list") {
           if (!verb && ctx.hasUI && ctx.mode === "tui" && openUi) { await openUi(ctx); return; }
-          ctx.ui.notify(this.list().map((row) => describeRole(row) + (this.fallbackSpecs(row.role).length
-            ? "  · fallbacks: " + this.fallbackSpecs(row.role).join(" → ") : "")).join("\n"), "info");
+          ctx.ui.notify([...this.list().map((row) => describeRole(row) + (this.fallbackSpecs(row.role).length
+            ? "  · fallbacks: " + this.fallbackSpecs(row.role).join(" → ") : "")), ...premiumRoleWarnings(this, ctx)].join("\n"), "info");
           return;
         }
         if (verb === "fallback") {

package/src/perf.ts

@@ -185,6 +185,9 @@ export class RenderScheduler {
 
 /** Mid-turn context recomputation happens at most this often; boundaries refresh at once. */
 export const CONTEXT_SAMPLE_MS = 750;
+/** Costly samples widen the window to keep mid-turn sampling near a 1% duty cycle, up to this cap. */
+export const CONTEXT_SAMPLE_MAX_MS = 5000;
+const CONTEXT_SAMPLE_DUTY = 100;
 export interface ContextUsageLike { percent?: number | null }
 export interface ContextSamplingStats {
   label: string;
@@ -197,6 +200,8 @@ export interface ContextSamplingStats {
   /** Median over the latest samples. */
   medianMs?: number;
   lastSampleAgeMs?: number;
+  /** Current mid-turn throttle window, widened from the median sample cost. */
+  windowMs: number;
   dirty: boolean;
   pending: boolean;
 }
@@ -253,20 +258,31 @@ export class ContextSampler {
       const before = this.current;
       this.sample();
       if (this.current !== before) this.changed();
-    }, Math.max(0, (this.lastSampleAt ?? Number.NEGATIVE_INFINITY) + this.throttleMs - this.now()));
+    }, Math.max(0, (this.lastSampleAt ?? Number.NEGATIVE_INFINITY) + this.windowMs() - this.now()));
     this.timer.unref?.();
   }
 
   stats(): ContextSamplingStats {
-    const sorted = [...this.durations].sort((a, b) => a - b);
+    const median = this.medianMs();
     return {
       label: this.current, ...this.counts,
-      ...(sorted.length ? { medianMs: sorted[Math.floor(sorted.length / 2)]! } : {}),
+      ...(median !== undefined ? { medianMs: median } : {}),
       ...(this.lastSampleAt !== undefined ? { lastSampleAgeMs: this.now() - this.lastSampleAt } : {}),
-      dirty: this.stale, pending: this.timer !== undefined
+      windowMs: this.windowMs(), dirty: this.stale, pending: this.timer !== undefined
     };
   }
 
+  private medianMs(): number | undefined {
+    if (!this.durations.length) return undefined;
+    return [...this.durations].sort((a, b) => a - b)[Math.floor(this.durations.length / 2)]!;
+  }
+
+  /** Cost-adaptive: large sessions whose usage walk is slow sample less often mid-turn. */
+  private windowMs(): number {
+    const cost = (this.medianMs() ?? 0) * CONTEXT_SAMPLE_DUTY;
+    return Math.max(this.throttleMs, Math.min(CONTEXT_SAMPLE_MAX_MS, Math.round(cost)));
+  }
+
   /** Session shutdown: no timer, and no reference to the old session's context. */
   dispose(): void {
     clearTimeout(this.timer);
@@ -386,6 +402,7 @@ export function formatPerf(snapshot: PerfSnapshot): string {
     ["dirty marks", count(sampling.marks)],
     ["total time", ms(sampling.totalMs)],
     ["max time", ms(sampling.maxMs) + (sampling.medianMs !== undefined ? ` (median ${ms(sampling.medianMs)})` : "")],
+    ["window", ms(sampling.windowMs) + " mid-turn"],
     ["last sample age", sampling.lastSampleAgeMs !== undefined ? age(sampling.lastSampleAgeMs) : "never"],
     ["pending", sampling.pending ? "sample scheduled" : sampling.dirty ? "yes" : "no"]
   ]);

package/src/plan.ts

@@ -11,6 +11,8 @@ import { extractApproachSteps, isSafePlanCommand, PLAN_TEMPLATE, planTextFromSte
 import { cleanText } from "./status.ts";
 import { sessionBranch } from "./session-branch.ts";
 import { type TodoStore } from "./tasks.ts";
+import { setToolActive } from "./tool-activation.ts";
+import { projectWorkflowMessages } from "./workflow-context.ts";
 
 export const PLAN_ENTRY = "pi-jar.plan";
 export const PLAN_SUBMIT_TOOL = "jar_plan_submit";
@@ -138,7 +140,8 @@ export class PlanMode {
     this.enabled = true;
     this.pendingReview = false;
     this.reminders = 0;
-    this.toolsBefore = this.pi.getActiveTools();
+    // The submit tool is active only in plan mode; never restore it with the pre-plan loadout.
+    this.toolsBefore = this.pi.getActiveTools().filter((name) => name !== PLAN_SUBMIT_TOOL);
     this.pi.setActiveTools(this.planTools(this.toolsBefore));
     this.onEnter?.(ctx);
     this.restoreRole = await this.roles.activateTemporary("plan", ctx);
@@ -413,34 +416,18 @@ export class PlanMode {
     });
 
     this.pi.on("before_agent_start", async () => {
-      if (!this.enabled) return;
+      if (!this.enabled) { setToolActive(this.pi, PLAN_SUBMIT_TOOL, false); return; }
       return { message: { customType: "pi-jar.plan-context", content: this.context(), display: false } };
     });
 
-    // Keep plan-only prompt messages bounded. When plan mode is active, retain only the newest
-    // context and newest reminder; when it is off, remove all stale plan prompt messages. Context
-    // rewrites apply to a single LLM call, so this runs on every call.
+    // Plan context is identical every turn: send its first copy only, keeping the cached prefix
+    // stable. Reminders stay in place while active; leaving plan mode drops all of them.
     this.pi.on("context", async (event) => {
-      let latestContext = -1;
-      let latestReminder = -1;
-      let needsPrune = false;
-      for (let index = event.messages.length - 1; index >= 0; index--) {
-        const type = (event.messages[index] as { customType?: string }).customType;
-        if (type === "pi-jar.plan-context") {
-          if (!this.enabled || latestContext >= 0) needsPrune = true;
-          else latestContext = index;
-        } else if (type === "pi-jar.plan-reminder") {
-          if (!this.enabled || latestReminder >= 0) needsPrune = true;
-          else latestReminder = index;
-        }
-      }
-      if (!needsPrune) return;
-      return { messages: event.messages.filter((raw, index) => {
-        const type = (raw as { customType?: string }).customType;
-        if (type === "pi-jar.plan-context") return this.enabled && index === latestContext;
-        if (type === "pi-jar.plan-reminder") return this.enabled && index === latestReminder;
-        return true;
-      }) };
+      const messages = projectWorkflowMessages(event.messages, {
+        "pi-jar.plan-context": { keep: this.enabled, dedupe: true },
+        "pi-jar.plan-reminder": { keep: this.enabled }
+      });
+      if (messages) return { messages };
     });
 
     this.pi.on("input", (event) => {

package/src/profile-ui.ts

@@ -1,5 +1,6 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { JarProfile, ProfileStore } from "./profiles.ts";
+import type { JarVisualSettings } from "./settings.ts";
 
 export type ProfileAction = "create" | "switch";
 
@@ -14,11 +15,16 @@ export interface ProfileUiOptions {
   openRoles(): Promise<void>;
 }
 
+/** Opt-in preset for heavy parallel work: the current settings with a larger retained subagent pool. */
+export const SWARM_SETTINGS = { maxSubagents: 4 } as const satisfies Partial<JarVisualSettings>;
 const CREATE = "+ Create profile…";
+const SWARM = `+ Create Swarm profile (${SWARM_SETTINGS.maxSubagents} subagents)…`;
 const FOLLOW = "Follow Pi";
 
-/** Name and theme are the only creation questions; roles are configured afterwards in the roles UI. */
-export async function promptNewProfile(ctx: ExtensionContext, options: Pick<ProfileUiOptions, "store" | "themes" | "create">): Promise<JarProfile | undefined> {
+/** Name and theme are the only creation questions; roles are configured afterwards in the roles UI.
+ *  A preset patches the copied settings once the copy is saved. */
+export async function promptNewProfile(ctx: ExtensionContext, options: Pick<ProfileUiOptions, "store" | "themes" | "create">,
+  preset?: Partial<JarVisualSettings>): Promise<JarProfile | undefined> {
   const name = await ctx.ui.input("New profile name (1–32 characters)", "");
   if (name === undefined) return undefined;
   if (/[\u0000-\u001f\u007f-\u009f]/.test(name)) { ctx.ui.notify("Profile name cannot contain control characters", "warning"); return undefined; }
@@ -31,21 +37,30 @@ export async function promptNewProfile(ctx: ExtensionContext, options: Pick<Prof
   }
   const selected = await ctx.ui.select("Choose a theme for " + normalized, [FOLLOW, ...options.themes.filter((item) => item !== "follow")]);
   if (!selected) return undefined;
-  try { return options.create(normalized, selected === FOLLOW ? "follow" : selected); }
+  let profile: JarProfile;
+  try { profile = options.create(normalized, selected === FOLLOW ? "follow" : selected); }
   catch (error) { ctx.ui.notify("Could not create profile: " + (error as Error).message, "error"); return undefined; }
+  if (!preset) return profile;
+  try { return options.store.update(profile.name, { settings: { ...profile.settings, ...preset } }); }
+  catch (error) {
+    ctx.ui.notify(`Created profile ${profile.name}, but could not apply its preset: ${(error as Error).message}`, "warning");
+    return profile;
+  }
 }
 
 /** /profiles and the settings Profiles tab: create a profile or switch to one, nothing else. */
 export async function openProfiles(ctx: ExtensionContext, options: ProfileUiOptions, action?: ProfileAction): Promise<void> {
   if (!ctx.hasUI || ctx.mode !== "tui") return;
   const active = options.store.activeName;
+  let preset: Partial<JarVisualSettings> | undefined;
   if (action !== "create") {
     const labels = new Map(options.store.list().map((profile) => [profile.name === active ? `${profile.name} (active)` : profile.name, profile.name]));
-    const choice = await ctx.ui.select(action === "switch" ? "Switch profile" : "Profiles", action === "switch" ? [...labels.keys()] : [CREATE, ...labels.keys()]);
+    const choice = await ctx.ui.select(action === "switch" ? "Switch profile" : "Profiles", action === "switch" ? [...labels.keys()] : [CREATE, SWARM, ...labels.keys()]);
     if (!choice) return;
-    if (choice !== CREATE) { await options.select(labels.get(choice)!); return; }
+    if (choice !== CREATE && choice !== SWARM) { await options.select(labels.get(choice)!); return; }
+    if (choice === SWARM) preset = SWARM_SETTINGS;
   }
-  const profile = await promptNewProfile(ctx, options);
+  const profile = await promptNewProfile(ctx, options, preset);
   if (!profile) return;
   if (options.switchBlocked()) {
     ctx.ui.notify(`Created profile ${profile.name} with ${active}'s model roles. Switch to it in a fresh session with /profiles, then set its roles with /roles.`, "info");

package/src/profiles.ts

@@ -1,7 +1,7 @@
 import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { isRoleName, normalizeSpec, parseRoleConfig, type RoleConfig } from "./model-roles.ts";
-import { isMaxSubagents, defaultVisualSettings, loadVisualSettings, type JarVisualSettings } from "./settings.ts";
+import { isMaxSubagents, defaultVisualSettings, loadVisualSettings, parseContextBudget, DEFAULT_CONTEXT_BUDGET, type JarVisualSettings } from "./settings.ts";
 import { ACCENT_NAMES } from "./accent.ts";
 import { FOOTER_FIELDS } from "./footer-settings.ts";
 import { ICON_SETS } from "./icons.ts";
@@ -16,7 +16,8 @@ export function conversationStarted(entries: readonly unknown[]): boolean {
     || (entry.type === "message" && isPlainObject(entry.message) && entry.message.role === "user")));
 }
 export function pinnedProfileId(entries: readonly unknown[]): string | undefined {
-  for (const entry of [...entries].reverse()) {
+  for (let index = entries.length - 1; index >= 0; index--) {
+    const entry = entries[index];
     if (isPlainObject(entry) && entry.type === "custom" && entry.customType === PROFILE_ENTRY
       && isPlainObject(entry.data) && entry.data.version === 1 && typeof entry.data.id === "string") return entry.data.id;
   }
@@ -40,7 +41,9 @@ function normalizeProfile(value: unknown): JarProfile | undefined {
     || !isPlainObject(settings.footer) || typeof settings.animations !== "boolean" || typeof settings.ui !== "boolean"
     || typeof settings.composer !== "boolean" || typeof settings.mascot !== "boolean" || typeof settings.suggestions !== "boolean"
     || typeof settings.advisor !== "boolean" || typeof settings.advisorGates !== "boolean"
-    || (settings.contextDiet !== undefined && typeof settings.contextDiet !== "boolean") || !Number.isInteger(settings.goalRounds)
+    || (settings.contextDiet !== undefined && typeof settings.contextDiet !== "boolean")
+    || (settings.contextBudget !== undefined && !parseContextBudget(settings.contextBudget))
+    || (settings.readCache !== undefined && typeof settings.readCache !== "boolean") || !Number.isInteger(settings.goalRounds)
     || (settings.goalRounds as number) < 1 || (settings.goalRounds as number) > 50
     || !isMaxSubagents(settings.maxSubagents) || typeof settings.accent !== "string"
     || !(settings.accent === "follow" || settings.accent === "default" || ACCENT_NAMES.includes(settings.accent as never))
@@ -49,7 +52,9 @@ function normalizeProfile(value: unknown): JarProfile | undefined {
   if (raw.name === DEFAULT_PROFILE && raw.id !== "default") return undefined;
   if (raw.name !== DEFAULT_PROFILE && (typeof raw.id !== "string" || !/^profile-[a-z0-9-]{8,64}$/.test(raw.id))) return undefined;
   for (const [role, spec] of Object.entries(raw.roles.roles)) if (!isRoleName(role) || typeof spec !== "string" || !normalizeSpec(spec)) return undefined;
-  return { id: raw.id as string, name: raw.name, theme: raw.theme, settings: { ...raw.settings, contextDiet: settings.contextDiet ?? false } as unknown as JarVisualSettings, roles: parseRoleConfig(raw.roles) };
+  const contextBudget = parseContextBudget(settings.contextBudget) ?? { ...DEFAULT_CONTEXT_BUDGET };
+  return { id: raw.id as string, name: raw.name, theme: raw.theme, settings: { ...raw.settings, contextDiet: settings.contextDiet ?? false,
+    contextBudget, readCache: settings.readCache ?? false } as unknown as JarVisualSettings, roles: parseRoleConfig(raw.roles) };
 }
 function atomicSave(file: string, document: ProfileDocument): string {
   mkdirSync(join(file, ".."), { recursive: true });

package/src/quota.ts

@@ -69,57 +69,70 @@ function codexAccountId(token: string): string | undefined {
   } catch { return undefined; }
 }
 
-/** Never persist credentials; resolve through Pi's public model registry only on explicit opt-in. */
+/**
+ * Never persist credentials; resolve through Pi's public model registry only on explicit opt-in.
+ * Resolves undefined only when cancelled; every other miss throws a short, user-facing reason.
+ */
 export async function fetchQuota(provider: QuotaProvider, resolveAuth: (provider: string) => Promise<{ auth: { apiKey?: string }; source?: string } | undefined>, signal: AbortSignal): Promise<Quota | undefined> {
+  const resolved = await resolveAuth(provider);
+  if (signal.aborted) return undefined;
+  if (!resolved?.source?.toLowerCase().includes("oauth") || !resolved.auth.apiKey) throw new Error("needs a subscription login (/login), not an API key");
+  const token = resolved.auth.apiKey;
+  const headers: Record<string, string> = { Authorization: `Bearer ${token}`, Accept: "application/json" };
+  let url: string;
+  if (provider === "openai-codex") {
+    const id = codexAccountId(token);
+    if (!id) throw new Error("login token has no ChatGPT account id");
+    headers["ChatGPT-Account-Id"] = id;
+    url = "https://chatgpt.com/backend-api/wham/usage";
+  } else {
+    headers["anthropic-beta"] = "oauth-2025-04-20";
+    url = "https://api.anthropic.com/api/oauth/usage";
+  }
+  let response: Response;
   try {
-    const resolved = await resolveAuth(provider);
-    if (signal.aborted || !resolved?.source?.toLowerCase().includes("oauth") || !resolved.auth.apiKey) return undefined;
-    const token = resolved.auth.apiKey;
-    const headers: Record<string, string> = { Authorization: `Bearer ${token}`, Accept: "application/json" };
-    let url: string;
-    if (provider === "openai-codex") {
-      const id = codexAccountId(token);
-      if (!id) return undefined;
-      headers["ChatGPT-Account-Id"] = id;
-      url = "https://chatgpt.com/backend-api/wham/usage";
-    } else {
-      headers["anthropic-beta"] = "oauth-2025-04-20";
-      url = "https://api.anthropic.com/api/oauth/usage";
-    }
-    const response = await fetch(url, { method: "GET", headers, signal: AbortSignal.any([signal, AbortSignal.timeout(5000)]) });
-    if (!response.ok) return undefined;
-    const data: unknown = await response.json();
-    if (!data || typeof data !== "object") return undefined;
-    const body = data as Record<string, unknown>;
-    if (provider === "openai-codex") {
-      const rate = body.rate_limit && typeof body.rate_limit === "object" ? body.rate_limit as Record<string, unknown> : {};
-      const parse = (window: unknown): QuotaWindow | undefined => {
-        if (!window || typeof window !== "object") return undefined;
-        const item = window as Record<string, unknown>;
-        return windowValue({ used: item.used_percent, resetsAt: typeof item.reset_at === "number" ? item.reset_at * 1000 : undefined });
-      };
-      // Window slots are not fixed: Plus accounts get a single weekly `primary_window` and a null
-      // secondary. Classify by `limit_window_seconds` (≤ 1 day is the short window), falling back
-      // to position only when the duration is absent.
-      const quota: Quota = {};
-      for (const [window, fallback] of [[rate.primary_window, "fiveHour"], [rate.secondary_window, "week"]] as const) {
-        const value = parse(window);
-        if (!value) continue;
-        const seconds = (window as Record<string, unknown>).limit_window_seconds;
-        const slot = typeof seconds === "number" && seconds > 0 ? (seconds <= 24 * 60 * 60 ? "fiveHour" : "week") : fallback;
-        if (!quota[slot]) quota[slot] = value;
-      }
-      return parseQuota(quota);
+    response = await fetch(url, { method: "GET", headers, signal: AbortSignal.any([signal, AbortSignal.timeout(5000)]) });
+  } catch (error) {
+    if (signal.aborted) return undefined;
+    throw new Error(error instanceof Error && error.name === "TimeoutError" ? "request timed out" : "request failed: " + String(error instanceof Error ? error.message : error));
+  }
+  // The Anthropic usage endpoint is shared with Claude Code and rate-limits aggressively.
+  if (!response.ok) throw new Error(response.status === 429 ? "rate limited by the provider (HTTP 429)" : `HTTP ${response.status}`);
+  const data: unknown = await response.json().catch(() => undefined);
+  if (!data || typeof data !== "object") throw new Error("unreadable usage response");
+  const body = data as Record<string, unknown>;
+  let quota: Quota | undefined;
+  if (provider === "openai-codex") {
+    const rate = body.rate_limit && typeof body.rate_limit === "object" ? body.rate_limit as Record<string, unknown> : {};
+    const parse = (window: unknown): QuotaWindow | undefined => {
+      if (!window || typeof window !== "object") return undefined;
+      const item = window as Record<string, unknown>;
+      return windowValue({ used: item.used_percent, resetsAt: typeof item.reset_at === "number" ? item.reset_at * 1000 : undefined });
+    };
+    // Window slots are not fixed: Plus accounts get a single weekly `primary_window` and a null
+    // secondary. Classify by `limit_window_seconds` (≤ 1 day is the short window), falling back
+    // to position only when the duration is absent.
+    const windows: Quota = {};
+    for (const [window, fallback] of [[rate.primary_window, "fiveHour"], [rate.secondary_window, "week"]] as const) {
+      const value = parse(window);
+      if (!value) continue;
+      const seconds = (window as Record<string, unknown>).limit_window_seconds;
+      const slot = typeof seconds === "number" && seconds > 0 ? (seconds <= 24 * 60 * 60 ? "fiveHour" : "week") : fallback;
+      if (!windows[slot]) windows[slot] = value;
     }
+    quota = parseQuota(windows);
+  } else {
+    // `utilization` is already a percentage (7.0 means 7%), not a fraction.
     const parse = (window: unknown): QuotaWindow | undefined => {
       if (!window || typeof window !== "object") return undefined;
       const item = window as Record<string, unknown>;
-      const utilization = item.utilization;
       const resetsAt = typeof item.resets_at === "string" ? Date.parse(item.resets_at) : undefined;
-      return windowValue({ used: typeof utilization === "number" && utilization <= 1 ? utilization * 100 : utilization, resetsAt });
+      return windowValue({ used: item.utilization, resetsAt });
     };
-    return parseQuota({ fiveHour: parse(body.five_hour), week: parse(body.seven_day) });
-  } catch { return undefined; }
+    quota = parseQuota({ fiveHour: parse(body.five_hour), week: parse(body.seven_day) });
+  }
+  if (!quota) throw new Error("no plan limits in the usage response");
+  return quota;
 }
 
 /**
@@ -128,7 +141,7 @@ export async function fetchQuota(provider: QuotaProvider, resolveAuth: (provider
  * lookups start only from `refresh` at session boundaries.
  */
 export class QuotaCache {
-  private entries = new Map<QuotaProvider, { value?: Quota; requestedAt: number; expiresAt: number; failures: number }>();
+  private entries = new Map<QuotaProvider, { value?: Quota; error?: string; requestedAt: number; expiresAt: number; failures: number }>();
   private pending = new Map<QuotaProvider, AbortController>();
   private requests = 0;
   private failures = 0;
@@ -147,6 +160,12 @@ export class QuotaCache {
     const cached = this.entries.get(provider);
     return cached && cached.expiresAt > now ? cached.value : undefined;
   }
+  /** Why the last lookup failed and when the next may start; undefined while pending, fresh, or never tried. */
+  failure(provider: string | undefined, now: number): { error: string; retryInMs: number } | undefined {
+    if (provider !== "openai-codex" && provider !== "anthropic" || !this.enabled || this.pending.has(provider)) return undefined;
+    const cached = this.entries.get(provider);
+    return cached?.error !== undefined && cached.expiresAt > now ? { error: cached.error, retryInMs: cached.expiresAt - now } : undefined;
+  }
   /** Start one background lookup when nothing fresh is cached and no retry delay is pending; true if it started. */
   refresh(provider: string | undefined, statuses: ReadonlyMap<string, string>, now: number): boolean {
     if (provider !== "openai-codex" && provider !== "anthropic" || !this.enabled) return false;
@@ -167,15 +186,18 @@ export class QuotaCache {
         if (this.pending.get(provider) === controller) this.pending.delete(provider);
         return;
       }
-      // A rejected lookup is a failure like an empty one: both back off instead of retrying at once.
-      void this.fetcher(provider, controller.signal).catch(() => undefined).then((value) => {
+      // A rejected lookup backs off instead of retrying at once; its reason is kept for the usage panel.
+      void this.fetcher(provider, controller.signal).then(
+        (value) => ({ value, error: value ? undefined : "no usage returned" }),
+        (error: unknown) => ({ value: undefined, error: error instanceof Error ? error.message : String(error) })
+      ).then(({ value, error }) => {
         if (controller.signal.aborted) return;
         const failures = value ? 0 : (this.entries.get(provider)?.failures ?? 0) + 1;
         if (!value) this.failures++;
         const ttl = value ? QUOTA_TTL_MS : Math.min(QUOTA_MAX_BACKOFF_MS, QUOTA_TTL_MS * 2 ** (failures - 1));
-        this.entries.set(provider, { ...(value ? { value } : {}), requestedAt: now, expiresAt: now + ttl, failures });
-        // An expired value was already hidden, so only a new value changes what renders show.
-        if (value) this.changed();
+        this.entries.set(provider, { ...(value ? { value } : { error: error ?? "no usage returned" }), requestedAt: now, expiresAt: now + ttl, failures });
+        // Either outcome replaces the "loading" state renders show.
+        this.changed();
       }).finally(() => {
         if (this.pending.get(provider) === controller) this.pending.delete(provider);
       });

package/src/roles-ui.ts

@@ -1,7 +1,7 @@
 import type { ExtensionContext, ThemeColor } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, stripTerminalSequences, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import { promptText } from "./dialogs.ts";
-import { isRoleName, normalizeSpec, THINKING, type ModelRoleManager, type RoleRow } from "./model-roles.ts";
+import { isRoleName, normalizeSpec, premiumRoleWarnings, THINKING, type ModelRoleManager, type RoleRow } from "./model-roles.ts";
 import { contentRows, optionList, sidebarWidth, splitFrame } from "./split-view.ts";
 
 type RoleAction = "model" | "fallback" | "alias" | "thinking" | "scope" | "activate" | "clear" | "new" | "delete";
@@ -44,6 +44,8 @@ async function roleScreen(ctx: ExtensionContext, roles: ModelRoleManager, initia
     let layout = { top: 1, rows: 0, leftWidth: 0, bodyX: 2, footerTop: 0 };
     let width = 80;
     const rows = () => roles.list();
+    // Read once per screen: every action closes the screen, and reopening it re-checks against the current model.
+    const warnings = premiumRoleWarnings(roles, ctx);
     const finish = (action: RoleAction) => done({ action, index: selected });
     return {
       invalidate() {},
@@ -98,7 +100,7 @@ async function roleScreen(ctx: ExtensionContext, roles: ModelRoleManager, initia
         const header = narrow ? [theme.fg("accent", `‹ ${selected + 1}/${list.length} ${row.role} ›`)] : [];
         const actions = optionList(theme, ACTIONS.map((item) => item.label), -1, ACTIONS.map((item) => item.hint))
           .map((line, at) => ACTIONS[at]!.action === "delete" && !row.custom ? theme.fg("dim", stripTerminalSequences(line)) : line);
-        const body = [...header, ...info];
+        const body = [...header, ...warnings.map((text) => theme.fg("warning", text)), ...info];
         const split = splitFrame(theme, width, "pi-jar · roles", narrow ? [] : left, body, [
           ...actions,
           theme.fg("dim", "↑↓ choose role · press a key or click an action · Esc close")