pi-jar 0.2.2 → 0.2.3

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";
@@ -41,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))
@@ -50,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")

package/src/settings-ui.ts

@@ -1,8 +1,9 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth, visibleWidth, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import { FOOTER_FIELDS, type FooterField } from "./footer-settings.ts";
+import { formatTokens } from "./context-budget.ts";
 import { ICON_SETS } from "./icons.ts";
-import { GOAL_ROUND_CHOICES, MAX_SUBAGENT_CHOICES, type JarAccent, type JarVisualSettings } from "./settings.ts";
+import { CONTEXT_BUDGET_ACTIONS, CONTEXT_BUDGET_CHOICES, GOAL_ROUND_CHOICES, MAX_SUBAGENT_CHOICES, type JarAccent, type JarVisualSettings } from "./settings.ts";
 import type { ProfileAction } from "./profile-ui.ts";
 
 const LABELS: Record<FooterField, string> = {
@@ -39,10 +40,11 @@ export async function openJarSettings(
     let width = 64;
     const accents: JarAccent[] = ["follow", ...availableAccents.filter((name): name is JarAccent =>
       name === "default" || ["gray", "pink", "teal", "azure", "violet", "amber"].includes(name))];
-    let choosing: "goalRounds" | "maxSubagents" | undefined;
-    const choices = () => choosing === "maxSubagents" ? MAX_SUBAGENT_CHOICES : GOAL_ROUND_CHOICES;
-    const fields = () => choosing ? choices().length : page === "footer" ? FOOTER_FIELDS.length : page === "pi" ? 7 : page === "profiles" ? 2 : 7;
-    const finishChoice = () => { selected = choosing === "maxSubagents" ? 3 : 2; choosing = undefined; };
+    let choosing: "goalRounds" | "maxSubagents" | "contextBudget" | undefined;
+    const choices = () => choosing === "maxSubagents" ? MAX_SUBAGENT_CHOICES : choosing === "contextBudget" ? CONTEXT_BUDGET_CHOICES : GOAL_ROUND_CHOICES;
+    const fields = () => choosing ? choices().length : page === "footer" ? FOOTER_FIELDS.length : page === "pi" ? 10 : page === "profiles" ? 2 : 7;
+    // Back on the row that opened the picker.
+    const finishChoice = () => { selected = choosing === "maxSubagents" ? 3 : choosing === "contextBudget" ? 8 : 2; choosing = undefined; };
     const piError = (error: unknown) => ctx.ui.notify("Could not change Pi setting: " + (error as Error).message, "error");
     const explainPool = () => choosing === "maxSubagents" || (page === "pi" && !choosing && selected === 3);
     const pageSize = () => Math.min(fields(), Math.max(4, (process.stdout.rows ?? 24) - (explainPool() ? 10 : 9)));
@@ -52,6 +54,7 @@ export async function openJarSettings(
       const state = current();
       if (choosing) {
         if (choosing === "maxSubagents") update({ ...state, maxSubagents: MAX_SUBAGENT_CHOICES[index]! });
+        else if (choosing === "contextBudget") update({ ...state, contextBudget: { ...state.contextBudget, softTokens: CONTEXT_BUDGET_CHOICES[index]! } });
         else update({ ...state, goalRounds: GOAL_ROUND_CHOICES[index]! });
         finishChoice();
       } else if (page === "profiles") {
@@ -75,6 +78,15 @@ export async function openJarSettings(
         else if (index === 4) update({ ...state, advisor: !state.advisor });
         else if (index === 5) update({ ...state, advisorGates: !state.advisorGates });
         else if (index === 6) update({ ...state, contextDiet: !state.contextDiet });
+        else if (index === 7) {
+          const at = CONTEXT_BUDGET_ACTIONS.indexOf(state.contextBudget.action);
+          update({ ...state, contextBudget: { ...state.contextBudget, action: CONTEXT_BUDGET_ACTIONS[(at + 1) % CONTEXT_BUDGET_ACTIONS.length]! } });
+        }
+        else if (index === 8) {
+          choosing = "contextBudget";
+          selected = Math.max(0, CONTEXT_BUDGET_CHOICES.indexOf(state.contextBudget.softTokens as never));
+        }
+        else if (index === 9) update({ ...state, readCache: !state.readCache });
       } else if (index === 0) {
         const at = Math.max(0, accents.indexOf(state.accent));
         update({ ...state, accent: accents[(at + 1) % accents.length]! });
@@ -150,8 +162,10 @@ export async function openJarSettings(
           + (profiles ? "   " + theme.fg(page === "profiles" ? "accent" : "muted", "[ Profiles ]") : ""));
         const prefs = pi?.get();
         const divider = theme.fg("dim", "├" + "─".repeat(Math.max(0, width - 2)) + "┤");
+        const budgetOn = state.contextBudget.action !== "off";
+        const chosen = choosing === "contextBudget" ? state.contextBudget.softTokens : choosing ? state[choosing] : undefined;
         const allRows = choosing
-          ? choices().map((choice, index) => row(index, String(choice), state[choosing!] === choice ? "CURRENT" : "", true))
+          ? choices().map((choice, index) => row(index, choosing === "contextBudget" ? formatTokens(choice) + " tokens" : String(choice), chosen === choice ? "CURRENT" : "", true))
           : page === "footer"
           ? FOOTER_FIELDS.map((field, index) => row(index, LABELS[field], state.footer[field] ? "ON" : "OFF", state.footer[field]))
           : page === "pi" ? [
@@ -161,7 +175,10 @@ export async function openJarSettings(
             row(3, "Max subagents (retained live pool)", String(state.maxSubagents), true),
             row(4, "Advisor (jar_advisor, /advisor)", state.advisor ? "ON" : "OFF", state.advisor),
             row(5, "Advisor gates (loops, repeated failures)", state.advisorGates ? "ON" : "OFF", state.advisorGates),
-          row(6, "Context diet (prior-turn reasoning)", state.contextDiet ? "ON" : "OFF", state.contextDiet)
+          row(6, "Context diet (prior-turn reasoning)", state.contextDiet ? "ON" : "OFF", state.contextDiet),
+            row(7, "Context budget (past the limit)", state.contextBudget.action.toUpperCase(), budgetOn),
+            row(8, "Context budget limit", formatTokens(state.contextBudget.softTokens), budgetOn),
+            row(9, "Repeated-read stub (unchanged re-reads)", state.readCache ? "ON" : "OFF", state.readCache)
           ] : page === "profiles" ? [
             row(0, "Switch profile…", profiles!.activeName(), true),
             row(1, "Create profile…", "OPEN", true)
@@ -178,11 +195,13 @@ export async function openJarSettings(
         const rows = allRows.slice(start, start + pageSize());
         return [top, tabs, divider,
           line(theme.fg("accent", choosing === "maxSubagents" ? " MAX SUBAGENTS · RETAINED LIVE POOL"
+            : choosing === "contextBudget" ? " CONTEXT BUDGET · SOFT LIMIT"
             : choosing === "goalRounds" ? " GOAL AUTO ROUNDS" : page === "footer" ? " FOOTER VISIBILITY" : page === "pi" ? " PI & WORKFLOWS" : page === "profiles" ? " PROFILES" : " APPEARANCE & MOTION")),
           line(theme.fg("dim", explainPool() ? " Live pool includes idle/paused subagents"
             : choosing ? " Select a value; Enter/click to save, Esc to cancel"
             : page === "footer" ? ` Footer fields ${start + 1}–${start + rows.length}/${fields()}`
-            : page === "pi" ? " Fullscreen mode enables clicks and copy-on-select"
+            : page === "pi" ? (selected === 7 || selected === 8 ? " Past the limit: suggest /compact or /new, or compact at a safe point"
+              : selected === 9 ? " An unchanged re-read of the same range returns a short stub" : " Fullscreen mode enables clicks and copy-on-select")
             : page === "profiles" ? " Switch only in a fresh, idle session; roles via /roles" : " Accent cycles through loaded themes")),
           ...rows,
           line(theme.fg("dim", choosing ? " ↑↓: choose · Enter/click: save · Esc: cancel"

package/src/settings.ts

@@ -25,11 +25,29 @@ export interface JarVisualSettings {
   advisorGates: boolean;
   /** Opt-in provider-context pruning of reasoning from completed earlier user turns. */
   contextDiet: boolean;
+  /** Context-size guard: past softTokens, suggest /compact or /new, or compact at the next safe point. */
+  contextBudget: ContextBudget;
+  /** Opt-in: an unchanged repeated `read` of the same range returns a short stub instead of the content. */
+  readCache: boolean;
   /** Glyph set for footer, composer and views: unicode, Nerd Font icons, or plain ascii. */
   icons: IconSet;
   footer: FooterSettings;
 }
 
+export const CONTEXT_BUDGET_ACTIONS = ["off", "suggest", "compact"] as const;
+export type ContextBudgetAction = (typeof CONTEXT_BUDGET_ACTIONS)[number];
+export interface ContextBudget { softTokens: number; action: ContextBudgetAction }
+export const CONTEXT_BUDGET_CHOICES = [80_000, 120_000, 160_000, 200_000] as const;
+export const DEFAULT_CONTEXT_BUDGET: ContextBudget = { softTokens: 120_000, action: "suggest" };
+/** Accepts any stored integer budget in a sane range, not only the picker's choices. */
+export function parseContextBudget(value: unknown): ContextBudget | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const { softTokens, action } = value as Record<string, unknown>;
+  if (typeof softTokens !== "number" || !Number.isInteger(softTokens) || softTokens < 10_000 || softTokens > 2_000_000) return undefined;
+  if (!CONTEXT_BUDGET_ACTIONS.some((choice) => choice === action)) return undefined;
+  return { softTokens, action: action as ContextBudgetAction };
+}
+
 export const GOAL_ROUND_CHOICES = [4, 8, 12, 20] as const;
 export const MAX_SUBAGENT_CHOICES = [2, 4, 6, 8, 16] as const;
 export type MaxSubagents = (typeof MAX_SUBAGENT_CHOICES)[number];
@@ -39,7 +57,7 @@ export function isMaxSubagents(value: unknown): value is MaxSubagents {
 
 export const SETTINGS_FILE = "pi-jar-settings.json";
 export function defaultVisualSettings(footer: FooterSettings = DEFAULT_FOOTER_SETTINGS): JarVisualSettings {
-  return { version: 1, accent: "follow", animations: true, ui: true, composer: true, mascot: true, suggestions: true, goalRounds: 8, maxSubagents: 4, advisor: true, advisorGates: true, contextDiet: false, icons: "unicode", footer: { ...footer } };
+  return { version: 1, accent: "follow", animations: true, ui: true, composer: true, mascot: true, suggestions: true, goalRounds: 8, maxSubagents: 2, advisor: true, advisorGates: false, contextDiet: false, contextBudget: { ...DEFAULT_CONTEXT_BUDGET }, readCache: false, icons: "unicode", footer: { ...footer } };
 }
 
 /** Legacy footer choices are imported only while the new file is absent. Never modify the old file. */
@@ -73,6 +91,8 @@ export function loadVisualSettings(directory: string): JarVisualSettings {
     advisor: typeof value.advisor === "boolean" ? value.advisor : fallback.advisor,
     advisorGates: typeof value.advisorGates === "boolean" ? value.advisorGates : fallback.advisorGates,
     contextDiet: typeof value.contextDiet === "boolean" ? value.contextDiet : fallback.contextDiet,
+    contextBudget: parseContextBudget(value.contextBudget) ?? fallback.contextBudget,
+    readCache: typeof value.readCache === "boolean" ? value.readCache : fallback.readCache,
     icons: ICON_SETS.some((set) => set === value.icons) ? value.icons as IconSet : fallback.icons,
     footer: Object.fromEntries(FOOTER_FIELDS.map((field) => [field,
       typeof footer[field] === "boolean" ? footer[field] : fallback.footer[field]])) as FooterSettings

package/src/shells.ts

@@ -53,6 +53,9 @@ export interface ShellJob {
 export type ShellEvent = { kind: "match" | "exit"; job: ShellJob };
 export interface StartOptions { command: string; cwd: string; name?: string; watch?: string; notify?: boolean; purpose?: "task" | "service" }
 export interface ShellManagerOptions { budgetChars?: number; liveTailChars?: number }
+/** One caller read: `missed` lines were trimmed before they were read, `skipped` unread lines
+ * were retained but fell outside the requested line limit. */
+export interface ShellRead { lines: string[]; missed: number; skipped: number }
 export interface ShellStats {
   /** Processes still alive, including killed jobs in their grace period and draining trees. */
   live: number;
@@ -75,6 +78,11 @@ interface ShellEntry {
   partial: string;
   /** Retained line characters, maintained incrementally with the manager total. */
   chars: number;
+  /** Absolute index (`dropped` + offset) of the first line the agent has not read. Absolute, so
+   * trimming never invalidates it; a cursor below `dropped` means trimmed lines went unread. */
+  cursor: number;
+  /** Length of the unterminated `partial` already shown; reset once that line is committed. */
+  partialRead: number;
   timer?: ReturnType<typeof setTimeout>;
   closeTimer?: ReturnType<typeof setTimeout>;
   finished?: boolean;
@@ -179,7 +187,7 @@ export class ShellManager {
     const id = "s" + this.next++;
     const job: ShellJob = { id, name: cleanText(options.name || command, 40), command, cwd: options.cwd, startedAt: Date.now(), status: "running",
       notify: options.notify ?? true, complete: false, purpose: options.purpose ?? (options.watch ? "service" : "task"), lines: [], dropped: 0, ...(options.watch ? { watch: options.watch } : {}) };
-    const entry: ShellEntry = { job, partial: "", chars: 0, ...(pattern ? { pattern } : {}) };
+    const entry: ShellEntry = { job, partial: "", chars: 0, cursor: 0, partialRead: 0, ...(pattern ? { pattern } : {}) };
     this.jobs.set(id, entry);
     // Own process group so kill() stops the whole tree (dev servers spawn children).
     const child = this.spawnShell("/bin/sh", ["-c", command], { cwd: options.cwd, detached: process.platform !== "win32", stdio: ["ignore", "pipe", "pipe"], env: process.env });
@@ -230,7 +238,9 @@ export class ShellManager {
   private receive(entry: ShellEntry, text: string): void {
     const parts = (entry.partial + text.replace(/\r\n/g, "\n")).split("\n");
     entry.partial = parts.pop() ?? "";
-    if (entry.partial.length > MAX_LINE_CHARS) { this.push(entry, entry.partial); entry.partial = ""; }
+    // A committed line repeats any prefix shown as partial; the new partial is unread.
+    if (parts.length) entry.partialRead = 0;
+    if (entry.partial.length > MAX_LINE_CHARS) { this.push(entry, entry.partial); entry.partial = ""; entry.partialRead = 0; }
     for (const line of parts) this.push(entry, line);
   }
 
@@ -303,7 +313,7 @@ export class ShellManager {
     this.onChange?.();
   }
 
-  /** Last `count` lines (1–400). */
+  /** Last `count` lines (1–400) for display; never moves the agent's read cursor. */
   output(id: string, count = 40): string[] {
     const entry = this.jobs.get(id);
     if (!entry) throw new Error("no shell " + id);
@@ -313,6 +323,29 @@ export class ShellManager {
     return [...entry.job.lines.slice(-(limit - 1)), entry.partial];
   }
 
+  /** The agent's read: lines since its cursor (newest `count` kept), or the trailing window with
+   * `all`. Either way the cursor moves to the end, so the next read returns only newer lines.
+   * An unterminated last line is shown only when it grew since the previous read. */
+  read(id: string, count = 40, all = false): ShellRead {
+    const entry = this.jobs.get(id);
+    if (!entry) throw new Error("no shell " + id);
+    const { job } = entry;
+    let result: ShellRead;
+    if (all) result = { lines: this.output(id, count), missed: 0, skipped: 0 };
+    else {
+      const limit = Math.max(1, Math.min(MAX_OUTPUT_LINES, Math.floor(count)));
+      const partial = entry.partial.length > entry.partialRead;
+      const first = Math.max(0, entry.cursor - job.dropped);
+      const skipped = Math.max(0, job.lines.length - first + (partial ? 1 : 0) - limit);
+      const lines = job.lines.slice(first + skipped);
+      if (partial) lines.push(entry.partial);
+      result = { lines, missed: Math.max(0, job.dropped - entry.cursor), skipped };
+    }
+    entry.cursor = job.dropped + job.lines.length;
+    entry.partialRead = entry.partial.length;
+    return result;
+  }
+
   /** Diagnostics snapshot, computed on demand in one pass over ≤ MAX_KEPT_SHELLS jobs. */
   stats(): ShellStats {
     let live = 0;
@@ -407,6 +440,14 @@ const boundedTail = (lines: readonly string[], limit = MAX_TOOL_OUTPUT_CHARS): s
   return (omitted ? `… ${omitted} earlier line(s) omitted\n` : "") + kept.join("\n");
 };
 
+/** A read as tool text: notes for lines the caller will not see, then the bounded lines. */
+const readText = (read: ShellRead): string => {
+  const notes: string[] = [];
+  if (read.missed) notes.push(`… ${read.missed} unread line(s) were trimmed from the log`);
+  if (read.skipped) notes.push(`… ${read.skipped} older unread line(s) skipped; raise lines to see more`);
+  return [...notes, boundedTail(read.lines)].join("\n");
+};
+
 /** The message that wakes the agent when a watched shell matches or ends. */
 export function shellEventMessage(event: ShellEvent): string {
   const { job } = event;
@@ -426,8 +467,9 @@ const Parameters = Type.Object({
   purpose: Type.Optional(Type.Union([Type.Literal("task"), Type.Literal("service")], { description: "task is finite and must be checked before claiming completion; service is intentionally long-lived (default with watch)." })),
   id: Type.Optional(Type.String({ description: "Shell id for output/kill/wait/peek, e.g. s1." })),
   ids: Type.Optional(Type.Array(Type.String(), { maxItems: 20, description: "Selected ids for wait/peek. Omit to inspect all jobs or wait for finite tasks only." })),
-  waitMs: Type.Optional(Type.Number({ minimum: 0, maximum: 30000, description: "Bounded event-driven wait (default 1000ms, maximum 30000). Esc cancels the wait, not the shell." })),
-  lines: Type.Optional(Type.Number({ description: "How many trailing output lines to return (default 40, max 400)." }))
+  waitMs: Type.Optional(Type.Number({ minimum: 0, maximum: 30000, description: "start: wait up to this long (0–30000ms) for the job to exit; returns its exit code and output in one call, or the output so far if still running. wait: bounded event-driven wait (default 1000ms). Esc cancels the wait, not the shell." })),
+  lines: Type.Optional(Type.Number({ description: "Line limit for output and start with waitMs (default 40, max 400): the newest unread lines, or the trailing window with all." })),
+  all: Type.Optional(Type.Boolean({ description: "output: return the trailing window again instead of only lines new since your last read." }))
 });
 
 export function registerShells(pi: ExtensionAPI, shells: () => ShellManager | undefined): void {
@@ -435,13 +477,11 @@ export function registerShells(pi: ExtensionAPI, shells: () => ShellManager | un
   pi.registerTool({
     name: SHELL_TOOL,
     label: "shell",
-    description: "Run background jobs. start returns immediately; notifications are compact and coalesced. peek reads status, wait checks selected tasks with a bounded event-driven wait, output loads logs and kill stops a process. Observed results are acknowledged so stale notifications do not replay. Verify relevant checks before claiming completion; do not wait for long-lived services.",
-    promptSnippet: "Use jar_shell for long-running or never-ending commands instead of blocking bash.",
+    description: "Background jobs: services, watchers and long commands; finite commands under ~2 min (build, test, git) belong in bash. start returns immediately, or with waitMs waits (≤30s) for exit and returns the exit code and output in one call. output returns only lines new since your last read (all: true for the trailing window). peek/list read status, wait blocks boundedly on selected finite jobs, kill stops the process tree. Completion notifications are compact, coalesced and arrive at the next safe turn boundary; they cannot interrupt an in-flight response, so when no useful work remains call wait instead of idling. Results read via output/peek/list/wait/start-with-waitMs are acknowledged and do not replay. Set watch to a regex for the line you wait for (e.g. \"listening|ready|error\"); mark never-ending jobs purpose: service, never wait on services, and kill shells you no longer need.",
+    promptSnippet: "Services, watchers and long jobs in the background.",
     promptGuidelines: [
-      "Use jar_shell start for servers, watchers and slow commands; set watch to a regex for the line you are waiting for (e.g. \"listening|ready|error\").",
-      "Do not poll: work while commands run, then use wait with explicit ids for relevant checks before the final summary. A bounded wait returns pending jobs honestly; never claim success without their exit codes. Do not wait for services/watchers. output, peek, list and wait acknowledge observed events, preventing stale replay.",
-      "Completion events cannot interrupt an in-flight model response. If no useful work remains, call wait for the relevant finite jobs immediately instead of thinking or waiting for an automatic wake-up.",
-      "Notifications contain coalesced status, not log dumps. Inspect output only for relevant diagnostics. Mark never-ending jobs purpose: service and kill shells you no longer need."
+      "Use bash for finite commands expected under ~2 min (build, test, git); jar_shell only for services, watchers or long jobs; short-but-uncertain: jar_shell start with waitMs.",
+      "Don't poll jar_shell; keep working, then wait on explicit ids before the final summary. Never claim a check passed without its exit code."
     ],
     parameters: Parameters,
     async execute(_id, params, signal, _update, ctx) {
@@ -454,15 +494,37 @@ export function registerShells(pi: ExtensionAPI, shells: () => ShellManager | un
       try {
         switch (params.action) {
           case "start": {
+            // Validate before spawning: failing after the spawn would hide the running job's id.
+            const waitMs = params.waitMs === undefined ? undefined : Math.max(0, Math.min(30_000, params.waitMs));
+            if (waitMs !== undefined && !Number.isFinite(waitMs)) return reply("start failed: waitMs must be a number of milliseconds.");
             const job = manager.start({ command: params.command ?? "", cwd: ctx.cwd, ...(params.name ? { name: params.name } : {}), ...(params.watch ? { watch: params.watch } : {}),
               ...(params.notify !== undefined ? { notify: params.notify } : {}), ...(params.purpose ? { purpose: params.purpose } : {}) });
-            return reply(`Started ${describe(job)} (pid ${job.pid ?? "?"}). ${job.notify ? "Completion reaches the model at the next safe turn boundary (or wakes it when idle). If no other useful work remains, use wait now." : "Notifications are off; check it with output."}`);
+            const started = `Started ${describe(job)} (pid ${job.pid ?? "?"}).`;
+            const later = job.notify ? "Completion reaches the model at the next safe turn boundary (or wakes it when idle). If no other useful work remains, use wait now." : "Notifications are off; check it with output.";
+            if (waitMs === undefined) return reply(`${started} ${later}`);
+            let completed: boolean;
+            try { completed = await manager.wait([job.id], waitMs, signal); }
+            catch (error) {
+              // Esc ends the wait, never the job; the caller still needs its id.
+              if (!signal?.aborted) throw error;
+              return reply(`${started} Wait cancelled; the job keeps running. ${later}`);
+            }
+            const read = manager.read(job.id, params.lines ?? 40);
+            const output = read.lines.length || read.missed ? "\n" + readText(read) : " (no output)";
+            // These lines and (when finished) the exit code are surfaced now: a later completion
+            // notification would only repeat them.
+            manager.acknowledge([job.id]);
+            if (!completed) return reply(`${started} Still running after ${waitMs}ms. ${later}${output}`);
+            return reply(describe(manager.summaries().find(summary => summary.id === job.id) ?? job) + output);
           }
           case "output": {
             if (!params.id) return reply("output needs an id.");
-            const lines = manager.output(params.id, params.lines ?? 40);
-            manager.acknowledge([params.id]);
-            return reply(`${describe(manager.get(params.id)!)}\n${lines.length ? boundedTail(lines) : "(no output yet)"}`);
+            const { id } = params;
+            const read = manager.read(id, params.lines ?? 40, params.all === true);
+            manager.acknowledge([id]);
+            const head = describe(manager.summaries().find(summary => summary.id === id)!);
+            if (read.lines.length || read.missed) return reply(`${head}\n${readText(read)}`);
+            return reply(`${head} · ${params.all ? "no output" : "no new output; all: true repeats the last lines"}`);
           }
           case "kill":
             if (!params.id) return reply("kill needs an id.");

package/src/subagent-tools.ts

@@ -2,7 +2,7 @@ import { workspacePathAllowed } from "./delegate-worktree.ts";
 
 export const CHILD_TOOLS_ENV = "PI_JAR_CHILD_TOOLS";
 export const WEB_TOOLS = ["web_enable", "web_search", "fetch_content", "get_search_content", "source_check"] as const;
-export const RECURSIVE_TOOLS = new Set(["jar_delegate", "jar_subagent", "jar_democracy"]);
+export const RECURSIVE_TOOLS = new Set(["jar_delegate", "jar_subagent", "jar_council"]);
 
 /** Multi-file tools must validate each effective target, not just the top-level default path. */
 export function worktreeToolViolation(root: string, cwd: string, name: string, args: unknown): string | undefined {