pi-jar 0.2.1 → 0.2.3

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/side-model.ts

@@ -26,6 +26,19 @@ export class SideUsage {
 
 export interface SideAnswer { text: string; model: string }
 
+/** Roles already told, this process, that they ran on the current (main) model. */
+const unsetRoleNotices = new Set<string>();
+
+/** An unassigned side role silently costs main-model prices; say so once per role. */
+function noteCurrentModel(ctx: ExtensionContext, role: string, model: string): void {
+  if (unsetRoleNotices.has(role)) return;
+  unsetRoleNotices.add(role);
+  try {
+    ctx.ui?.notify(`${role} role is unset, so it used the current model (${model}). `
+      + `Assign a cheaper one with /roles set ${role} PROVIDER/MODEL.`, "info");
+  } catch { /* the notice is advisory */ }
+}
+
 /**
  * Ask the model assigned to `role` (or the current model) a one-shot question outside the
  * conversation. Tries configured fallbacks in order on failure; cancellation never retries.
@@ -71,6 +84,7 @@ export async function askRole(ctx: ExtensionContext, roles: ModelRoleManager, us
       }
       text = text.trim();
       if (!text) throw new Error(`${name} returned an empty answer`);
+      if (!assigned) noteCurrentModel(ctx, role, name);
       return { text, model: name };
     } catch (error) {
       signal?.throwIfAborted();

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 {

package/src/suggest.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { cleanText } from "./status.ts";
+import { setToolActive } from "./tool-activation.ts";
 
 export const SUGGEST_TOOL = "jar_suggest";
 const MAX_SUGGESTION = 160;
@@ -31,12 +32,8 @@ export function registerSuggestions(pi: ExtensionAPI, state: SuggestionState, op
   pi.registerTool?.({
     name: SUGGEST_TOOL,
     label: "suggest",
-    description: "Optionally offer one useful next prompt as ghost text in the input box; Tab accepts it for editing.",
-    promptSnippet: "Optionally use jar_suggest at the end when one genuinely useful next prompt would help the user continue.",
-    promptGuidelines: [
-      "jar_suggest is best-effort, not mandatory. Use it only when there is one clear next action worth surfacing; skip it for routine completions.",
-      "When used, call it once as the final action with one imperative line under 120 characters. Do not mention jar_suggest in your reply."
-    ],
+    description: "Optionally offer one useful next prompt (one imperative line under 120 characters) as ghost text in the input box; Tab accepts it for editing. Call once as the final action; do not mention it in your reply.",
+    promptSnippet: "Optionally end with one jar_suggest call only when one clear next prompt is worth surfacing; skip it for routine completions.",
     parameters: Type.Object({ suggestion: Type.String({ description: "The user's likely next prompt, one line." }) }),
     execute: async (_id, params) => {
       const ok = state.set(params.suggestion ?? "");
@@ -50,11 +47,7 @@ export function registerSuggestions(pi: ExtensionAPI, state: SuggestionState, op
   });
 
   const sync = () => {
-    if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
-    const active = pi.getActiveTools();
-    const has = active.includes(SUGGEST_TOOL);
-    if (options.enabled() && !has && pi.getAllTools().some((tool) => tool.name === SUGGEST_TOOL)) pi.setActiveTools([...active, SUGGEST_TOOL]);
-    else if (!options.enabled() && has) pi.setActiveTools(active.filter((name) => name !== SUGGEST_TOOL));
+    setToolActive(pi, SUGGEST_TOOL, options.enabled());
     if (!options.enabled()) state.clear();
   };
 

package/src/task-tool.ts

@@ -87,16 +87,10 @@ export function registerTaskTool(
   pi.registerTool({
     name: "jar_todo",
     label: "tasks",
-    description: "Maintain session tasks: write establishes a fresh complete task plan, update changes one existing task by stable id, append adds genuinely new work, and remove deletes one task tree. start/done/open/edit remain concise status operations. Stable IDs are returned for every task.",
-    promptSnippet: "Track multi-step work with jar_todo: write the task plan first, update/remove existing tasks by stable id, append only when new work arrives mid-run, and keep one leaf in_progress.",
+    description: "Maintain session tasks. write sets the complete current plan (omitted tasks are removed; each item has content, status, optional activeForm and one level of `subtasks`, whose completion completes the parent; progress counts leaves). update changes one task by stable id, append adds genuinely new work mid-run (not a new plan), remove deletes one task tree; start/done/open/edit are concise status operations. Stable IDs are returned for every task.",
+    promptSnippet: "Track work with 3+ steps or several requests in jar_todo (skip trivial requests and questions): write the complete plan for a new request, start fresh once the old list is completed.",
     promptGuidelines: [
-      "Use jar_todo proactively, without waiting for the user, for any task with three or more distinct steps, when the user gives several tasks, or right after receiving new instructions. Skip it for single trivial requests and pure questions.",
-      "Prefer write when establishing the task plan for a new request. If the existing checklist is fully completed, start the next request with a fresh write rather than appending onto old completed work.",
-      "Use update with a stable id to revise one existing task and remove to delete one task tree. Use append mainly when the user steers or adds genuinely new requirements while an active checklist is already in progress; do not use append as the default way to create a new plan.",
-      "write with todos is the complete current task plan and removes omitted tasks. Each item has content, status, and optional activeForm/subtasks.",
-      "Break a large task into `subtasks` (same shape, one level deep). A parent's status follows its subtasks: it is completed when all of them are. Progress counts leaf tasks (subtasks and tasks without subtasks).",
-      "Keep exactly one leaf task in_progress at a time. Mark a task in_progress before you start it and completed immediately after it is verified; do not batch completions.",
-      "Only mark a task completed when it is fully done. If tests fail, work is partial or you are blocked, keep it in_progress and add a task for what must be resolved. Remove tasks that are no longer relevant."
+      "Keep exactly one leaf in_progress; mark it completed right after verifying it. Never batch completions or complete partial, failing or blocked work: keep it open and add a task for the blocker."
     ],
     parameters: Parameters,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {

package/src/tool-activation.ts

@@ -0,0 +1,14 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Activate or deactivate one registered tool. Inactive tools send neither their schema nor their
+ * prompt rules, so mode-specific tools are active only while their mode is. Pi applies a change
+ * made in before_agent_start to that run; toggling only at mode boundaries keeps the prompt stable.
+ */
+export function setToolActive(pi: ExtensionAPI, name: string, wanted: boolean): void {
+  if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
+  const active = pi.getActiveTools();
+  const has = active.includes(name);
+  if (wanted && !has && pi.getAllTools().some((tool) => tool.name === name)) pi.setActiveTools([...active, name]);
+  else if (!wanted && has) pi.setActiveTools(active.filter((tool) => tool !== name));
+}

package/src/usage-view.ts

@@ -53,7 +53,7 @@ function resetText(window: QuotaWindow, now: number): string {
   return `Resets ${when} (in ${duration(Math.max(0, at - now))})`;
 }
 
-export interface UsageView { stats: UsageStats; provider?: string; quota?: Quota; quotaEnabled: boolean; now: number }
+export interface UsageView { stats: UsageStats; provider?: string; quota?: Quota; quotaFailure?: { error: string; retryInMs: number }; quotaEnabled: boolean; now: number }
 
 /** Claude-style usage page: session totals, per-model breakdown, then plan limit bars. */
 export function usageLines(view: UsageView, width: number, fg: Paint): string[] {
@@ -79,9 +79,13 @@ export function usageLines(view: UsageView, width: number, fg: Paint): string[]
   lines.push("", heading(`Plan usage limits${view.provider ? " · " + view.provider : ""}`));
   const windows: [string, QuotaWindow | undefined][] = [["Current session (5h)", view.quota?.fiveHour], ["Current week", view.quota?.week]];
   if (!windows.some(([, window]) => window)) {
-    lines.push(fg("dim", view.provider === "anthropic" || view.provider === "openai-codex"
-      ? view.quotaEnabled ? "  Loading limits… reopen in a moment." : "  Limit lookup is off; enable it with /jar quota on."
-      : "  Plan limits are available for anthropic and openai-codex subscriptions."));
+    const supported = view.provider === "anthropic" || view.provider === "openai-codex";
+    const failure = view.quotaFailure;
+    lines.push(fg(supported && view.quotaEnabled && failure ? "warning" : "dim", !supported
+      ? "  Plan limits are available for anthropic and openai-codex subscriptions."
+      : !view.quotaEnabled ? "  Limit lookup is off; enable it with /jar quota on."
+      : failure ? `  Limits unavailable: ${failure.error}. Retrying in ${duration(failure.retryInMs)}.`
+      : "  Loading limits…"));
     return lines;
   }
   for (const [label, window] of windows) {

package/src/usage.ts

@@ -12,6 +12,8 @@ export function sessionCost(ctx: Pick<ExtensionContext, "sessionManager">): numb
   return total;
 }
 
-export function formatCost(value: number): string {
-  return `cost $${value < 0.01 && value > 0 ? value.toFixed(4) : value.toFixed(2)}`;
+/** `cost $1.23`, plus the recent average per provider call when there is one: `cost $1.23 · $0.04/call`. */
+export function formatCost(value: number, perCall?: number): string {
+  const money = (amount: number) => `$${amount < 0.01 && amount > 0 ? amount.toFixed(4) : amount.toFixed(2)}`;
+  return `cost ${money(value)}` + (perCall !== undefined && perCall > 0 ? ` · ${money(perCall)}/call` : "");
 }

package/src/workflow-context.ts

@@ -0,0 +1,37 @@
+/** How one hidden workflow message type is projected into provider context. */
+export interface WorkflowMessageRule {
+  /** False drops every message of this type (its mode is off). */
+  keep: boolean;
+  /** Drop a message whose content repeats the previously kept one of the same type. */
+  dedupe?: boolean;
+}
+
+/**
+ * Provider-context projection for hidden workflow prompts (plan/goal context, reminders,
+ * continuations). Pi caches the conversation prefix, so a message once sent must keep being sent:
+ * every keep/drop decision depends only on the messages before it, never on later ones. Dropping
+ * an older copy when a newer one arrives would change the prefix and re-bill the whole previous
+ * run uncached. Returns undefined when nothing changes.
+ */
+export function projectWorkflowMessages<T>(messages: T[], rules: Readonly<Record<string, WorkflowMessageRule>>): T[] | undefined {
+  const last = new Map<string, string>();
+  let projected: T[] | undefined;
+  for (let index = 0; index < messages.length; index++) {
+    const message = messages[index]!;
+    const type = (message as { customType?: string }).customType;
+    const rule = type === undefined ? undefined : rules[type];
+    let keep = true;
+    if (rule) {
+      if (!rule.keep) keep = false;
+      else if (rule.dedupe) {
+        const raw = (message as { content?: unknown }).content;
+        const content = typeof raw === "string" ? raw : JSON.stringify(raw ?? "");
+        if (last.get(type!) === content) keep = false;
+        else last.set(type!, content);
+      }
+    }
+    if (!keep) projected ??= messages.slice(0, index);
+    else projected?.push(message);
+  }
+  return projected;
+}