pi-jar 0.1.4 → 0.1.6

package/src/model-roles.ts

@@ -11,7 +11,11 @@ export const BUILTIN_ROLES = [
   { role: "plan", label: "Architect", usedBy: "plan mode" },
   { role: "implement", label: "Builder", usedBy: "goal implement rounds and approved plans" },
   { role: "advisor", label: "Advisor", usedBy: "second opinions, stuck-work gates and the goal audit" },
-  { role: "task", label: "Subtask", usedBy: "delegated tasks" },
+  { role: "moderator", label: "Moderator", usedBy: "main-agent multi-agent coordination" },
+  { role: "scout", label: "Scout", usedBy: "cheap delegated discovery and codebase scouting" },
+  { role: "worker", label: "Worker", usedBy: "sandboxed delegated implementation" },
+  { role: "reviewer", label: "Reviewer", usedBy: "forked delegated review and verification" },
+  { role: "task", label: "Subtask", usedBy: "legacy or explicitly generic delegated tasks" },
   { role: "commit", label: "Commit", usedBy: "/jar commit messages" }
 ] as const;
 export const MODEL_ROLES = BUILTIN_ROLES.map((item) => item.role);
@@ -24,7 +28,7 @@ export interface RoleTag { name?: string; color?: string }
 export interface RoleConfig { version: 2; roles: Record<string, string>; cycleOrder?: string[]; tags?: Record<string, RoleTag>; fallbacks?: Record<string, string[]> }
 export interface RoleRow {
   role: string; label: string; usedBy?: string; custom: boolean;
-  spec?: string; scope?: RoleScope; resolved?: ResolvedRole; error?: string;
+  spec?: string; scope?: RoleScope; resolved?: ResolvedRole; error?: string; fallbacks: string[];
 }
 
 export const ROLE_FILE = "pi-jar-roles.json";
@@ -180,6 +184,23 @@ export class ModelRoleManager {
     return result && !("error" in result) ? result : undefined;
   }
 
+  /** Primary role target followed by its configured fallbacks, de-duplicated in priority order. */
+  resolveCandidates(role: string): ResolvedRole[] {
+    const candidates: ResolvedRole[] = [];
+    const primary = this.resolve(role);
+    if (primary) candidates.push(primary);
+    for (const spec of this.fallbackSpecs(role)) {
+      try { candidates.push(this.resolveSpec(spec)); } catch { /* malformed alias targets are skipped */ }
+    }
+    const seen = new Set<string>();
+    return candidates.filter((item) => {
+      const key = item.provider + "/" + item.model + ":" + (item.thinking ?? "");
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }
+
   get(role: string): RoleAssignment | undefined {
     const resolved = this.resolve(role);
     if (!resolved) return undefined;
@@ -196,7 +217,7 @@ export class ModelRoleManager {
     ];
     return rows.map((row) => {
       const result = resolveRole(roles, row.role);
-      return { ...row, spec: roles[row.role], scope: this.scopeOf(row.role),
+      return { ...row, spec: roles[row.role], scope: this.scopeOf(row.role), fallbacks: this.fallbackSpecs(row.role),
         ...(result && "error" in result ? { error: result.error } : result ? { resolved: result } : {}) };
     });
   }
@@ -219,39 +240,46 @@ export class ModelRoleManager {
   }
 
   async activate(role: string, ctx: ExtensionContext, quiet = false): Promise<boolean> {
-    const result = resolveRole(this.merged(), role);
-    if (result && "error" in result) {
-      if (!quiet) ctx.ui.notify("Role " + role + ": " + result.error, "warning");
-      return false;
-    }
-    if (!result) {
+    const primary = resolveRole(this.merged(), role);
+    const primaryError = primary && "error" in primary ? primary.error : undefined;
+    const candidates = this.resolveCandidates(role);
+    if (!candidates.length) {
+      if (primaryError) {
+        if (!quiet) ctx.ui.notify("Role " + role + ": " + primaryError, "warning");
+        return false;
+      }
       if (!quiet) ctx.ui.notify("Role " + role + " follows the current model; assign one with /roles", "info");
       this.active = role;
       this.status(ctx);
       return true;
     }
-    const model = ctx.modelRegistry.find(result.provider, result.model);
-    if (!model) {
-      if (!quiet) ctx.ui.notify("Model not found for role " + role + ": " + result.provider + "/" + result.model, "warning");
-      return false;
-    }
-    let changed: boolean;
-    this.applying = true;
-    try { changed = await this.pi.setModel(model); } finally { this.applying = false; }
-    if (!changed) {
-      if (!quiet) ctx.ui.notify("No configured authentication for " + result.provider + "/" + result.model, "warning");
-      return false;
+
+    const failures: string[] = [];
+    for (let index = 0; index < candidates.length; index++) {
+      const candidate = candidates[index]!;
+      const model = ctx.modelRegistry.find(candidate.provider, candidate.model);
+      if (!model) { failures.push(candidate.provider + "/" + candidate.model + " not found"); continue; }
+      let changed: boolean;
+      this.applying = true;
+      try { changed = await this.pi.setModel(model); } finally { this.applying = false; }
+      if (!changed) { failures.push(candidate.provider + "/" + candidate.model + " unavailable"); continue; }
+      if (candidate.thinking) this.withApplying(() => this.pi.setThinkingLevel(candidate.thinking!));
+      this.active = role;
+      this.status(ctx);
+      if (!quiet) {
+        ctx.ui.notify("Role " + role + " · " + candidate.provider + "/" + candidate.model
+          + (candidate.thinking ? " · " + candidate.thinking : "") + (index ? " · fallback " + index : ""), "info");
+      }
+      return true;
     }
-    if (result.thinking) this.withApplying(() => this.pi.setThinkingLevel(result.thinking!));
-    this.active = role;
-    this.status(ctx);
-    if (!quiet) ctx.ui.notify("Role " + role + " · " + result.provider + "/" + result.model + (result.thinking ? " · " + result.thinking : ""), "info");
-    return true;
+
+    if (!quiet) ctx.ui.notify("No usable model for role " + role + ": " + failures.join("; "), "warning");
+    return false;
   }
 
   /** Switch to a role for a bounded workflow; the returned function restores the previous model. */
   async activateTemporary(role: string, ctx: ExtensionContext): Promise<() => Promise<void>> {
-    if (!this.resolve(role)) return async () => {};
+    if (!this.resolveCandidates(role).length) return async () => {};
     const previousModel = ctx.model;
     const previousThinking = this.pi.getThinkingLevel();
     const previousActive = this.active;
@@ -276,7 +304,7 @@ export class ModelRoleManager {
 
   /** Activate the next assigned role in the cycle order. */
   async cycle(ctx: ExtensionContext): Promise<string | undefined> {
-    const order = this.cycleOrder().filter((role) => this.resolve(role));
+    const order = this.cycleOrder().filter((role) => this.resolveCandidates(role).length > 0);
     if (!order.length) { ctx.ui.notify("No roles in the cycle order are assigned; configure them with /roles", "info"); return undefined; }
     const next = order[(order.indexOf(this.active ?? "") + 1) % order.length]!;
     return await this.activate(next, ctx) ? next : undefined;
@@ -322,7 +350,7 @@ export class ModelRoleManager {
     if (scope === "project") this.project = next; else this.global = next;
   }
 
-  register(openUi?: (ctx: ExtensionContext) => Promise<void>): void {
+  register(openUi?: (ctx: ExtensionContext) => Promise<void>, options: { activateDefault?: () => boolean } = {}): void {
     const manual = (_event: unknown, ctx: ExtensionContext) => {
       if (this.applying) return;
       this.manualEpoch++;
@@ -333,7 +361,8 @@ export class ModelRoleManager {
     this.pi.on("session_start", async (_event, ctx) => {
       this.load(ctx.cwd);
       this.active = undefined;
-      if (this.resolve("default")) await this.activate("default", ctx, true);
+      // Delegated children already received their role model/effort via CLI arguments.
+      if (options.activateDefault?.() !== false && this.resolveCandidates("default").length) await this.activate("default", ctx, true);
     });
 
     this.pi.registerCommand("roles", {

package/src/plan.ts

@@ -75,7 +75,6 @@ export class PlanMode {
   private reminders = 0;
   private reviewing = false;
   private compacting = false;
-  private contextDirty = true;
   private compactGeneration = 0;
   private executionRestore: (() => Promise<void>) | undefined;
   private executionRunning = false;
@@ -137,7 +136,6 @@ export class PlanMode {
     try { this.ensureDirectory(ctx); }
     catch (error) { ctx.ui.notify("Plan mode unavailable: cannot create plan directory: " + (error as Error).message, "error"); return; }
     this.enabled = true;
-    this.contextDirty = true;
     this.pendingReview = false;
     this.reminders = 0;
     this.toolsBefore = this.pi.getActiveTools();
@@ -152,7 +150,6 @@ export class PlanMode {
   private async leave(ctx: ExtensionContext, persist = true): Promise<void> {
     const wasEnabled = this.enabled;
     this.enabled = false;
-    this.contextDirty = true;
     this.compacting = false;
     this.pendingReview = false;
     this.compactGeneration++;
@@ -417,14 +414,13 @@ export class PlanMode {
 
     this.pi.on("before_agent_start", async () => {
       if (!this.enabled) return;
-      this.contextDirty = true;
       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 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.
     this.pi.on("context", async (event) => {
-      if (!this.contextDirty) return;
       let latestContext = -1;
       let latestReminder = -1;
       let needsPrune = false;
@@ -438,7 +434,6 @@ export class PlanMode {
           else latestReminder = index;
         }
       }
-      this.contextDirty = false;
       if (!needsPrune) return;
       return { messages: event.messages.filter((raw, index) => {
         const type = (raw as { customType?: string }).customType;
@@ -460,7 +455,6 @@ export class PlanMode {
         return;
       }
       this.reminders++;
-      this.contextDirty = true;
       return {
         entries: [{ type: "custom_message", customType: "pi-jar.plan-reminder", display: false,
           content: `[PI-JAR PLAN MODE] You ended the turn without ${PLAN_SUBMIT_TOOL}. If the plan is ready, write it to the plan directory and call ${PLAN_SUBMIT_TOOL}. If you need a decision from the user, use jar_ask. Do not ask for approval in chat.` }],
@@ -480,8 +474,8 @@ export class PlanMode {
       if (this.enabled && this.pendingReview) await this.review(ctx);
     });
 
-    this.pi.on("session_start", async (_event, ctx) => { this.contextDirty = true; await this.restore(sessionBranch(ctx), ctx); });
-    this.pi.on("session_tree", async (_event, ctx) => { this.contextDirty = true; await this.restore(sessionBranch(ctx), ctx); });
+    this.pi.on("session_start", async (_event, ctx) => { await this.restore(sessionBranch(ctx), ctx); });
+    this.pi.on("session_tree", async (_event, ctx) => { await this.restore(sessionBranch(ctx), ctx); });
     this.pi.on("session_shutdown", async (_event, ctx) => { if (this.enabled) await this.leave(ctx, false); });
   }
 }

package/src/roles-ui.ts

@@ -4,10 +4,11 @@ import { promptText } from "./dialogs.ts";
 import { isRoleName, normalizeSpec, THINKING, type ModelRoleManager, type RoleRow } from "./model-roles.ts";
 import { contentRows, optionList, sidebarWidth, splitFrame } from "./split-view.ts";
 
-type RoleAction = "model" | "alias" | "thinking" | "scope" | "activate" | "clear" | "new" | "delete";
+type RoleAction = "model" | "fallback" | "alias" | "thinking" | "scope" | "activate" | "clear" | "new" | "delete";
 const ACTIONS: { action: RoleAction; key: string; hint: string; label: string }[] = [
   { action: "activate", key: "\r", hint: "⏎", label: "Activate this role now" },
   { action: "model", key: "m", hint: "m", label: "Assign a model" },
+  { action: "fallback", key: "f", hint: "f", label: "Set fallback model" },
   { action: "alias", key: "a", hint: "a", label: "Alias another role (@role)" },
   { action: "thinking", key: "t", hint: "t", label: "Set thinking effort" },
   { action: "scope", key: "s", hint: "s", label: "Move between global and project" },
@@ -28,6 +29,7 @@ function detail(row: RoleRow, active: string | undefined): [ThemeColor, string][
     [target[0], "Model     " + target[1]],
     ["muted", "Alias     " + (row.resolved && row.resolved.via.length > 1 ? row.resolved.via.join(" → ") : "—")],
     ["muted", "Effort    " + (row.resolved?.thinking ?? "follow current")],
+    ["muted", "Fallback  " + (row.fallbacks.length ? row.fallbacks.join(" → ") : "—")],
     ["muted", "Scope     " + (row.scope ?? "unset") + (row.scope === "project" ? "  (.pi/pi-jar-roles.json)" : row.scope === "global" ? "  (agent dir)" : "")],
     ["dim", ""],
     ["dim", "Specs: provider/model[:effort] · @role[:effort] · *"],
@@ -41,7 +43,6 @@ async function roleScreen(ctx: ExtensionContext, roles: ModelRoleManager, initia
     let scroll = 0;
     let layout = { top: 1, rows: 0, leftWidth: 0, bodyX: 2, footerTop: 0 };
     let width = 80;
-    let actionsTop = -1;
     const rows = () => roles.list();
     const finish = (action: RoleAction) => done({ action, index: selected });
     return {
@@ -67,9 +68,9 @@ async function roleScreen(ctx: ExtensionContext, roles: ModelRoleManager, initia
         if (event.type !== "click" || event.button !== "left") return;
         if (event.y === 0 && event.x >= width - 3) { done(undefined); return { handled: true }; }
         const row = event.y - layout.top;
-        // Actions are listed in the detail pane, one per row.
-        const actionIndex = row - actionsTop;
-        if (row >= 0 && row < layout.rows && event.x >= layout.bodyX && actionIndex >= 0 && actionIndex < ACTIONS.length) {
+        // Actions stay in the footer so even short terminals can click every action.
+        const actionIndex = event.y - layout.footerTop;
+        if (event.x >= 2 && event.x < width - 2 && actionIndex >= 0 && actionIndex < ACTIONS.length) {
           finish(ACTIONS[actionIndex]!.action); return { handled: true };
         }
         if (row >= 0 && row < layout.rows && (layout.leftWidth === 0 || event.x < layout.leftWidth + 3)) {
@@ -81,7 +82,7 @@ async function roleScreen(ctx: ExtensionContext, roles: ModelRoleManager, initia
         width = Math.max(24, available);
         const list = rows();
         selected = Math.max(0, Math.min(list.length - 1, selected));
-        const height = Math.min(contentRows(5, 8), Math.max(12 + ACTIONS.length + 2, list.length));
+        const height = Math.min(contentRows(ACTIONS.length + 4, 4), Math.max(13, list.length));
         if (selected < scroll) scroll = selected;
         if (selected >= scroll + height) scroll = selected - height + 1;
         const active = roles.activeRole();
@@ -97,11 +98,9 @@ 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);
-        // Actions come right after the facts; the spec help (last three lines) goes last.
-        const facts = info.slice(0, -3), help = info.slice(-3);
-        const body = [...header, ...facts, theme.fg("accent", "Actions"), ...actions, ...help];
-        actionsTop = header.length + facts.length + 1;
+        const body = [...header, ...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")
         ], height);
         layout = split.layout;
@@ -149,6 +148,15 @@ async function applyAction(ctx: ExtensionContext, roles: ModelRoleManager, row:
       if (selected) roles.update(row.role, selected + effort(), scope);
       return;
     }
+    case "fallback": {
+      const models = ctx.modelRegistry.getAvailable().slice().sort((a, b) => (a.provider + "/" + a.id).localeCompare(b.provider + "/" + b.id));
+      if (!models.length) { ctx.ui.notify("No authenticated models are currently available", "warning"); return; }
+      const choices = ["Clear fallback", ...models.map((model) => model.provider + "/" + model.id)];
+      const selected = await ctx.ui.select("Fallback model for " + row.role, choices);
+      if (!selected) return;
+      roles.updateFallbacks(row.role, selected === "Clear fallback" ? [] : [selected], scope);
+      return;
+    }
     case "alias": {
       const targets = roles.list().filter((item) => item.role !== row.role).map((item) => "@" + item.role);
       const selected = await ctx.ui.select("Alias " + row.role + " to", targets);

package/src/settings-ui.ts

@@ -2,7 +2,7 @@ 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 { ICON_SETS } from "./icons.ts";
-import { GOAL_ROUND_CHOICES, type JarAccent, type JarVisualSettings } from "./settings.ts";
+import { GOAL_ROUND_CHOICES, MAX_SUBAGENT_CHOICES, type JarAccent, type JarVisualSettings } from "./settings.ts";
 
 const LABELS: Record<FooterField, string> = {
   model: "Model", effort: "Model effort", sessionName: "Session name", cwd: "Working directory",
@@ -35,25 +35,37 @@ 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))];
-    const fields = () => page === "footer" ? FOOTER_FIELDS.length : page === "pi" ? 5 : 7;
+    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" ? 6 : 7;
+    const finishChoice = () => { selected = choosing === "maxSubagents" ? 3 : 2; choosing = undefined; };
     const piError = (error: unknown) => ctx.ui.notify("Could not change Pi setting: " + (error as Error).message, "error");
-    const pageSize = () => Math.min(fields(), Math.max(4, (process.stdout.rows ?? 24) - 9));
+    const explainPool = () => choosing === "maxSubagents" || (page === "pi" && !choosing && selected === 3);
+    const pageSize = () => Math.min(fields(), Math.max(4, (process.stdout.rows ?? 24) - (explainPool() ? 10 : 9)));
     const firstVisible = () => Math.min(Math.max(0, selected - pageSize() + 1), Math.max(0, fields() - pageSize()));
     const visibleCount = () => Math.min(pageSize(), fields());
     const apply = (index: number) => {
       const state = current();
-      if (page === "footer") {
+      if (choosing) {
+        if (choosing === "maxSubagents") update({ ...state, maxSubagents: MAX_SUBAGENT_CHOICES[index]! });
+        else update({ ...state, goalRounds: GOAL_ROUND_CHOICES[index]! });
+        finishChoice();
+      } else if (page === "footer") {
         const field = FOOTER_FIELDS[index];
         if (field) update({ ...state, footer: { ...state.footer, [field]: !state.footer[field] } });
       } else if (page === "pi") {
         if (index === 0 && pi) { try { pi.setFullscreen(!pi.get().fullscreen); ctx.ui.notify("Pi TUI mode saved; restart Pi to apply", "info"); } catch (error) { piError(error); } }
         else if (index === 1 && pi) { try { pi.setCopyOnSelect(!pi.get().copyOnSelect); } catch (error) { piError(error); } }
         else if (index === 2) {
-          const at = GOAL_ROUND_CHOICES.indexOf(state.goalRounds as never);
-          update({ ...state, goalRounds: GOAL_ROUND_CHOICES[(at + 1) % GOAL_ROUND_CHOICES.length]! });
+          choosing = "goalRounds";
+          selected = Math.max(0, GOAL_ROUND_CHOICES.indexOf(state.goalRounds as never));
         }
-        else if (index === 3) update({ ...state, advisor: !state.advisor });
-        else if (index === 4) update({ ...state, advisorGates: !state.advisorGates });
+        else if (index === 3) {
+          choosing = "maxSubagents";
+          selected = Math.max(0, MAX_SUBAGENT_CHOICES.indexOf(state.maxSubagents));
+        }
+        else if (index === 4) update({ ...state, advisor: !state.advisor });
+        else if (index === 5) update({ ...state, advisorGates: !state.advisorGates });
       } else if (index === 0) {
         const at = Math.max(0, accents.indexOf(state.accent));
         update({ ...state, accent: accents[(at + 1) % accents.length]! });
@@ -77,7 +89,12 @@ export async function openJarSettings(
     return {
       invalidate() {},
       handleInput(data: string) {
-        if (matchesKey(data, Key.escape) || data === "q") { done(); return; }
+        if (matchesKey(data, Key.escape) || data === "q") {
+          if (choosing) { finishChoice(); tui.requestRender(); } else done();
+          return;
+        }
+        if (choosing && (matchesKey(data, Key.tab) || matchesKey(data, Key.right)
+          || matchesKey(data, Key.shift("tab")) || matchesKey(data, Key.left))) return;
         if (matchesKey(data, Key.tab) || matchesKey(data, Key.right)) {
           page = PAGES[(PAGES.indexOf(page) + 1) % PAGES.length]!;
           selected = 0;
@@ -97,6 +114,7 @@ export async function openJarSettings(
         if (event.type !== "click" || event.button !== "left") return;
         if (event.y === 0 && event.x >= width - 4) { done(); return { handled: true }; }
         if (event.y === 1) {
+          choosing = undefined;
           if (event.x >= 2 && event.x < Math.min(width - 2, 19)) { page = "appearance"; selected = 0; }
           else if (event.x >= 19 && event.x < Math.min(width - 2, 32)) { page = "footer"; selected = 0; }
           else if (event.x >= 32 && event.x < width - 2) { page = "pi"; selected = 0; }
@@ -121,14 +139,17 @@ export async function openJarSettings(
           + "   " + theme.fg(page === "pi" ? "accent" : "muted", "[ Pi ]"));
         const prefs = pi?.get();
         const divider = theme.fg("dim", "├" + "─".repeat(Math.max(0, width - 2)) + "┤");
-        const allRows = page === "footer"
+        const allRows = choosing
+          ? choices().map((choice, index) => row(index, String(choice), state[choosing!] === choice ? "CURRENT" : "", true))
+          : page === "footer"
           ? FOOTER_FIELDS.map((field, index) => row(index, LABELS[field], state.footer[field] ? "ON" : "OFF", state.footer[field]))
           : page === "pi" ? [
             row(0, "Mouse clicks (Pi fullscreen, restart)", !prefs ? "N/A" : prefs.fullscreen ? "ON" : "OFF", !!prefs?.fullscreen),
             row(1, "Copy on select", !prefs ? "N/A" : prefs.copyOnSelect ? "ON" : "OFF", !!prefs?.copyOnSelect),
             row(2, "Goal auto rounds", String(state.goalRounds), true),
-            row(3, "Advisor (jar_advisor, /advisor)", state.advisor ? "ON" : "OFF", state.advisor),
-            row(4, "Advisor gates (loops, repeated failures)", state.advisorGates ? "ON" : "OFF", state.advisorGates)
+            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(0, "Accent", state.accent === "follow" ? "FOLLOW PI" : state.accent.toUpperCase(), true),
             row(1, "Motion", state.animations ? "ON" : "OFF", state.animations),
@@ -141,11 +162,16 @@ export async function openJarSettings(
         const start = firstVisible();
         const rows = allRows.slice(start, start + pageSize());
         return [top, tabs, divider,
-          line(theme.fg("accent", page === "footer" ? " FOOTER VISIBILITY" : page === "pi" ? " PI & WORKFLOWS" : " APPEARANCE & MOTION")),
-          line(theme.fg("dim", page === "footer" ? ` Footer fields ${start + 1}–${start + rows.length}/${fields()}`
+          line(theme.fg("accent", choosing === "maxSubagents" ? " MAX SUBAGENTS · RETAINED LIVE POOL"
+            : choosing === "goalRounds" ? " GOAL AUTO ROUNDS" : page === "footer" ? " FOOTER VISIBILITY" : page === "pi" ? " PI & WORKFLOWS" : " 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" : " Accent cycles through loaded themes")),
           ...rows,
-          line(theme.fg("dim", " Tab: section · ↑↓: choose · Enter/click: change · Esc")),
+          line(theme.fg("dim", choosing ? " ↑↓: choose · Enter/click: save · Esc: cancel"
+            : " Tab: section · ↑↓: choose · Enter/click: change · Esc")),
+          ...(explainPool() ? [line(theme.fg("dim", " Lowering does not terminate existing subagents"))] : []),
           theme.fg("dim", "╰" + "─".repeat(Math.max(0, width - 2)) + "╯")];
       }
     };

package/src/settings.ts

@@ -17,6 +17,8 @@ export interface JarVisualSettings {
   suggestions: boolean;
   /** Automatic implement/audit rounds per user message while a goal is active. */
   goalRounds: number;
+  /** Retained live subagent pool, including idle/paused agents; lowering does not terminate them. */
+  maxSubagents: MaxSubagents;
   /** The jar_advisor second-opinion tool and /advisor. */
   advisor: boolean;
   /** Consult the advisor automatically when the agent repeats a tool call or keeps failing. */
@@ -27,10 +29,15 @@ export interface JarVisualSettings {
 }
 
 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];
+export function isMaxSubagents(value: unknown): value is MaxSubagents {
+  return MAX_SUBAGENT_CHOICES.some((choice) => choice === value);
+}
 
 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, advisor: true, advisorGates: true, icons: "unicode", footer: { ...footer } };
+  return { version: 1, accent: "follow", animations: true, ui: true, composer: true, mascot: true, suggestions: true, goalRounds: 8, maxSubagents: 4, advisor: true, advisorGates: true, icons: "unicode", footer: { ...footer } };
 }
 
 /** Legacy footer choices are imported only while the new file is absent. Never modify the old file. */
@@ -60,6 +67,7 @@ export function loadVisualSettings(directory: string): JarVisualSettings {
     suggestions: typeof value.suggestions === "boolean" ? value.suggestions : fallback.suggestions,
     goalRounds: typeof value.goalRounds === "number" && Number.isInteger(value.goalRounds) && value.goalRounds >= 1 && value.goalRounds <= 50
       ? value.goalRounds : fallback.goalRounds,
+    maxSubagents: isMaxSubagents(value.maxSubagents) ? value.maxSubagents : fallback.maxSubagents,
     advisor: typeof value.advisor === "boolean" ? value.advisor : fallback.advisor,
     advisorGates: typeof value.advisorGates === "boolean" ? value.advisorGates : fallback.advisorGates,
     icons: ICON_SETS.some((set) => set === value.icons) ? value.icons as IconSet : fallback.icons,

package/src/status.ts

@@ -73,7 +73,8 @@ export function collectStatuses(statuses: ReadonlyMap<string, string>, now: numb
     const id = rawKey.slice(ROLE_PREFIX.length);
     if (!/^[a-z0-9][a-z0-9-]{0,31}$/.test(id)) continue;
     const role = cachedRole(id, rawValue);
-    if (!role || role.expiresAt == null || role.expiresAt <= now || role.expiresAt > now + ROLE_TTL_MS) {
+    const ttl = id.startsWith("delegate-") ? 24 * 60 * 60_000 : ROLE_TTL_MS;
+    if (!role || role.expiresAt == null || role.expiresAt <= now || role.expiresAt > now + ttl) {
       extras.push(`${id}: unavailable`);
       continue;
     }

package/src/task-tool.ts

@@ -4,7 +4,7 @@ import { Type } from "typebox";
 import type { Todo, TodoInput, TodoStatus } from "./tasks.ts";
 import { TODO_STATUSES, TodoStore, todoMark, todoProgress, todoTotals } from "./tasks.ts";
 
-const ACTIONS = ["write", "list", "append", "remove", "replace", "add", "start", "done", "open", "edit", "delete"] as const;
+const ACTIONS = ["write", "list", "append", "remove", "update", "add", "start", "done", "open", "edit", "delete"] as const;
 const Action = Type.Unsafe<(typeof ACTIONS)[number]>({ type: "string", enum: [...ACTIONS] });
 const Status = Type.Unsafe<(typeof TODO_STATUSES)[number]>({ type: "string", enum: [...TODO_STATUSES] });
 const Content = Type.String({ description: "Imperative task title, e.g. \"Run the tests\"." });
@@ -19,10 +19,10 @@ const Parameters = Type.Object({
     subtasks: Type.Optional(Type.Array(Type.Object({ id: Type.Optional(Type.String()), content: Content, status: Status, activeForm: ActiveForm }), {
       description: "Optional steps of this task (one level deep). The task's status then follows its subtasks."
     }))
-  }), { description: "For append: new tasks only. For replace: exactly one replacement task. With write (or no action): the complete list, replacing it." })),
+  }), { description: "For append: new tasks only. For update: exactly one updated task. With write (or no action): the complete list, replacing it." })),
   action: Type.Optional(Action),
-  id: Type.Optional(Type.String({ description: "Stable task id for replace/remove/start/done/open/edit/delete. On a parent, start runs its first open subtask; done/open apply to all its subtasks." })),
-  title: Type.Optional(Type.String({ description: "Task title for append/add/edit/replace." })),
+  id: Type.Optional(Type.String({ description: "Stable task id for update/remove/start/done/open/edit/delete. On a parent, start runs its first open subtask; done/open apply to all its subtasks." })),
+  title: Type.Optional(Type.String({ description: "Task title for append/add/edit/update." })),
   status: Type.Optional(Status),
   activeForm: ActiveForm,
   parent: Type.Optional(Type.String({ description: "For append/add: id of a top-level task to add the new task under as a subtask." })),
@@ -42,6 +42,8 @@ interface TaskToolDetails {
   changed?: string;
   /** Full stable id index, including items outside the bounded preview. */
   ids?: { id: string; title: string; parentId?: string }[];
+  /** Optional deliberately small render surface for terse mutations such as start/done. */
+  display?: Todo[];
   truncated?: boolean;
   /** Subtask counts of previewed parents when the preview cuts the list. */
   progress?: { id: string; done: number; total: number }[];
@@ -85,11 +87,13 @@ export function registerTaskTool(
   pi.registerTool({
     name: "jar_todo",
     label: "tasks",
-    description: "Maintain session tasks incrementally: append adds todos (or title), remove deletes id and its subtasks, replace updates only id using title/status/activeForm or exactly one todos item. Omitted replacement fields/subtasks are preserved. append with parent adds subtasks. Stable IDs are returned for every task. Legacy write (or todos without action) replaces the entire list. add/delete and start/done/open/edit/list remain supported.",
-    promptSnippet: "Track multi-step work with jar_todo: append new tasks, replace/remove by stable id, keep one leaf in_progress, complete tasks as they finish.",
+    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.",
     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 incremental actions: append with todos adds only new tasks; replace with id updates only that task; remove with id deletes only that task tree. Use the returned stable IDs. write with todos is legacy full-list replacement and removes omitted tasks. Each todos item has content, status, and optional activeForm/subtasks.",
+      "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."
@@ -109,7 +113,7 @@ export function registerTaskTool(
           if (!Array.isArray(params.todos)) throw new Error();
           inputs = params.todos.map(toInput);
         } catch { error = "todos must be an array of task objects with array subtasks."; }
-        if (!["write", "append", "replace"].includes(action)) error = "todos may only be used with write, append, or replace; no tasks were changed.";
+        if (!["write", "append", "update"].includes(action)) error = "todos may only be used with write, append, or update; no tasks were changed.";
       }
       if (!error) switch (action) {
         case "list":
@@ -125,15 +129,15 @@ export function registerTaskTool(
           if (!error) changedId = current.all().find((item) => !before.has(item.id))?.id;
           break;
         }
-        case "replace": {
-          if (!params.id) { error = "replace needs a valid existing task id."; break; }
-          if (inputs && (inputs.length !== 1 || params.title !== undefined || params.status !== undefined || params.activeForm !== undefined)) { error = "replace accepts exactly one todos item OR title/status/activeForm fields."; break; }
+        case "update": {
+          if (!params.id) { error = "update needs a valid existing task id."; break; }
+          if (inputs && (inputs.length !== 1 || params.title !== undefined || params.status !== undefined || params.activeForm !== undefined)) { error = "update accepts exactly one todos item OR title/status/activeForm fields."; break; }
           const replacement = inputs?.[0] ?? {
             ...(params.title !== undefined ? { title: params.title } : {}),
             ...(params.status !== undefined ? { status: params.status } : {}),
             ...(params.activeForm !== undefined ? { activeForm: params.activeForm } : {})
           };
-          error = current.replace(params.id, replacement);
+          error = current.update(params.id, replacement);
           if (!error) changedId = params.id;
           break;
         }
@@ -154,7 +158,7 @@ export function registerTaskTool(
           if (!item) error = `${action} needs a valid id from jar_todo list.`;
           else if (action === "start" && progress.total && progress.done === progress.total) error = `every subtask of ${item.id} is completed; open it or add a subtask first.`;
           else if (!current.setStatus(item.id, action === "start" ? "in_progress" : action === "done" ? "completed" : "pending")) error = "Could not save the task.";
-          else changedId = item.id;
+          else changedId = action === "start" ? (current.current()?.id ?? item.id) : item.id;
           break;
         }
         case "edit":
@@ -177,6 +181,8 @@ export function registerTaskTool(
       const group = root ? items.filter((item) => item.id === root || item.parentId === root) : [];
       const mutationItems = action === "write" || action === "append" ? items : group;
       const mutationPreview = mutationItems.slice(0, 8);
+      const terseMutation = action === "start" || action === "done";
+      const terseItem = terseMutation && changedId ? items.find((item) => item.id === changedId) : undefined;
       // Keep task prose bounded while still returning every addressable id in canonical order.
       const idIndex = mutationItems.length > 8
         ? "\nTask IDs (list order): " + items.map((item, index) => `${index + 1}=${item.id}`).join(", ") + "\nUse list for all task titles."
@@ -185,7 +191,11 @@ export function registerTaskTool(
         ? `Could not ${action} tasks: ${error} (${summary(items)}).`
         : action === "list"
           ? `Tasks (${summary(items)}):\n${lines(items)}`
-          : `Task list updated (${summary(items)}).${mutationPreview.length ? "\n" + mutationPreview.map((item) => line(items, item)).join("\n") : ""}${idIndex}\n${REMINDER}`;
+          : action === "start" && terseItem
+            ? `Started task:\n${line(items, terseItem)}`
+            : action === "done" && terseItem
+              ? `Completed task:\n${line(items, terseItem)}`
+              : `Task list updated (${summary(items)}).${mutationPreview.length ? "\n" + mutationPreview.map((item) => line(items, item)).join("\n") : ""}${idIndex}\n${REMINDER}`;
       // A subagent's parent mirrors the checklist from these details, so children send it whole.
       const preview = process.env.PI_JAR_CHILD ? items : items.slice(0, 8);
       const truncated = preview.length < items.length;
@@ -198,6 +208,7 @@ export function registerTaskTool(
         details: {
           action, items: preview, total: state.total, done: state.done, count: items.length,
           ids: items.map(({ id, title, parentId }) => ({ id, title, ...(parentId ? { parentId } : {}) })),
+          ...(terseItem ? { display: [{ ...terseItem }] } : {}),
           ...(state.current ? { current: state.current } : {}),
           ...(truncated ? { truncated: true } : {}),
           ...(progress.length ? { progress } : {}),
@@ -218,15 +229,19 @@ export function registerTaskTool(
       if (isPartial) return new Text(theme.fg("warning", "Updating tasks…"), 0, 0);
       const details = result.details as TaskToolDetails | undefined;
       const items = details?.items ?? [];
+      const displayItems = details?.display ?? items;
       // Older results predate `count`, when `total` counted every item.
       const count = details?.count ?? details?.total ?? items.length;
       const totals = details?.total === undefined ? todoTotals(items) : { done: details.done, total: details.total };
       if (!count) return new Text(theme.fg("dim", "No tracked tasks."), 0, 0);
       const known = new Map((details?.progress ?? []).map((value) => [value.id, value]));
-      const shown = expanded ? items : items.slice(0, 8);
-      let text = theme.fg("dim", `${totals.done}/${totals.total} done${details?.current ? " · now: " + details.current : ""}`);
-      for (const item of shown) text += "\n" + todoRow(item, (color, value) => theme.fg(color, value), (value) => theme.bold(value), known.get(item.id) ?? todoProgress(items, item.id));
-      if (details?.truncated || shown.length < count) text += "\n" + theme.fg("dim", `  … +${Math.max(0, count - shown.length)} more · /jar tasks`);
+      const shown = details?.display ? displayItems : expanded ? items : items.slice(0, 8);
+      let text = details?.display ? "" : theme.fg("dim", `${totals.done}/${totals.total} done${details?.current ? " · now: " + details.current : ""}`);
+      for (const item of shown) {
+        const row = todoRow(item, (color, value) => theme.fg(color, value), (value) => theme.bold(value), known.get(item.id) ?? todoProgress(items, item.id));
+        text += (text ? "\n" : "") + row;
+      }
+      if (!details?.display && (details?.truncated || shown.length < count)) text += "\n" + theme.fg("dim", `  … +${Math.max(0, count - shown.length)} more · /jar tasks`);
       return new Text(text, 0, 0);
     }
   });