pi-jar 0.2.1 → 0.2.3

package/src/delegate.ts

@@ -28,7 +28,8 @@ import {
 export const DELEGATE_TOOL = "jar_delegate";
 /** Set in child processes so a subagent never delegates again. */
 export const CHILD_ENV = "PI_JAR_CHILD";
-export const MAX_DELEGATES = 4;
+/** Retained pool when no limit is configured; matches the settings default (the opt-in Swarm profile uses 4). */
+export const MAX_DELEGATES = 2;
 export const SUBAGENT_LIMIT_CHOICES = [2, 4, 6, 8, 16] as const;
 /** Read-only subagents also keep jar_todo so their checklist shows in the activity view. */
 export const READ_ONLY_TOOLS = ["read", "grep", "find", "ls", "jar_todo", "jar_discuss"] as const;
@@ -41,6 +42,9 @@ const allowedInMode = (mode: DelegateExecutionMode, name: string) => !RECURSIVE_
 export type DelegateMode = "scout" | "fork" | "worktree";
 type DelegateExecutionMode = DelegateMode | "direct";
 const MAX_OUTPUT_CHARS = 12_000;
+/** Shared budget for the reports one synchronous jar_delegate result returns; the rest stays one jar_subagent report away. */
+const MAX_RESULT_REPORT_CHARS = 16_000;
+const MIN_RUN_REPORT_CHARS = 2000;
 /** A working child that sends no RPC event for this long is treated as hung and killed. */
 const IDLE_TIMEOUT_MS = 10 * 60_000;
 /** After exit, grandchildren (MCP servers, shells) can hold the stdio pipes open; stop waiting for close. */
@@ -55,6 +59,8 @@ const STATUS_REFRESH_MS = 20_000;
 const LIVE_UPDATE_MS = 1000;
 /** Visible message that wakes the moderator when a resumed subagent's turn ends. */
 export const SUBAGENT_MESSAGE = "pi-jar.subagent";
+/** An event carries at most this much of a report; the full report stays one `jar_subagent report` away. */
+export const EVENT_SUMMARY_CHARS = 400;
 const NOTIFY_COALESCE_MS = 250;
 const MAX_EVENT_TEXT = 16_000;
 /** Transcript entries kept per run; tool output and text are clipped so a run stays well under 2 MiB. */
@@ -201,7 +207,7 @@ export function delegatePrompt(task: string, write: boolean, mode: DelegateExecu
     "Track multi-step work with jar_todo (when available) so your progress is visible. The moderator may steer, pause or resume you; preserve scope across those controls.",
     "Use jar_discuss when available for short cross-agent questions and answers. Keep discussion messages narrow; it is for coordination, not a transcript.",
     "Finish with a self-contained report in these sections:",
-    "## Summary — the outcome in one to three sentences.",
+    `## Summary — the outcome in one to three sentences, under ${EVENT_SUMMARY_CHARS} characters: the moderator's notification shows only this.`,
     "## Details — findings or changes, with file paths (and line numbers where useful).",
     "## Verification — what you checked or ran, and the results.",
     "## Open issues — risks, unknowns and follow-ups, or \"none\".",
@@ -214,6 +220,22 @@ export function delegatePrompt(task: string, write: boolean, mode: DelegateExecu
 const cleanBlock = (value: string, limit: number): string => value.slice(0, limit * 2)
   .replace(ANSI, "").replace(/\r\n?/g, "\n").replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, " ").replace(/\n{3,}/g, "\n\n").trim().slice(0, limit);
 
+/** One line of at most EVENT_SUMMARY_CHARS, marked with … when clipped. */
+const summaryLine = (text: string): string => {
+  const line = cleanText(text, EVENT_SUMMARY_CHARS + 1);
+  return line.length > EVENT_SUMMARY_CHARS ? line.slice(0, EVENT_SUMMARY_CHARS - 1) + "…" : line;
+};
+const SUMMARY_HEADING = /^\s*#{1,6}\s*summary\b[\s:—–-]*(.*)$/i;
+/** What an event shows of a report: its `## Summary` section (its opening when the child skipped the format) on one line. */
+export function eventSummary(report: string): string {
+  const lines = report.split("\n");
+  const start = lines.findIndex((line) => SUMMARY_HEADING.test(line));
+  if (start < 0) return summaryLine(report);
+  const end = lines.findIndex((line, index) => index > start && /^\s*#{1,6}\s/.test(line));
+  const section = [SUMMARY_HEADING.exec(lines[start]!)![1]!, ...lines.slice(start + 1, end < 0 ? undefined : end)].join(" ");
+  return summaryLine(section.trim() ? section : report);
+}
+
 /** Whether `promise` settles within `ms`; the timer never keeps the process alive. */
 const settlesWithin = (promise: Promise<unknown>, ms: number): Promise<boolean> => {
   let timer: NodeJS.Timeout | undefined;
@@ -828,7 +850,7 @@ export function startDelegate(run: DelegateRun, args: string[], prompt: string,
     try {
       // Cross a settled boundary so the active task's report cannot answer the question.
       if (run.state === "working" && !await pause()) return undefined;
-      const instruction = "Moderator BTW: answer only this question in one compact paragraph. Preserve your assigned task scope for the next resume. Question: " + question;
+      const instruction = `Moderator BTW: answer only this question in one compact paragraph under ${EVENT_SUMMARY_CHARS} characters. Preserve your assigned task scope for the next resume. Question: ` + question;
       if (!beginPrompt(instruction, wasPaused)) return undefined;
       const answered = await settlesWithin(waitSettled(), 2 * 60_000);
       if (!answered) { void pause(); return undefined; }
@@ -1090,6 +1112,12 @@ export class DelegateRegistry {
     for (const record of records) this.entries.set(record.key, { record });
     this.notify();
   }
+  /** Key/state of every record in insertion order: a cheap change test for per-tick listeners (no sweep, sort or copies). */
+  stateSignature(): string {
+    let signature = "";
+    for (const [key, { record }] of this.entries) signature += key + ":" + record.run.state + " ";
+    return signature;
+  }
   notify(): void {
     this.sweep();
     for (const listener of this.listeners) {
@@ -1124,7 +1152,7 @@ const fileList = (files: readonly string[], limit: number) => files.slice(0, lim
 const todoLine = (todo: Todo) => `${todo.parentId ? "    " : "  "}${todo.status === "completed" ? "[x]" : todo.status === "in_progress" ? "[~]" : "[ ]"} ${todo.title}`;
 
 /** What the parent agent reads back: the run's facts (time, tools, files, tasks, failures), then its own report. */
-export function runReport(run: DelegateRun, now = Date.now()): string {
+export function runReport(run: DelegateRun, now = Date.now(), outputLimit = MAX_OUTPUT_CHARS, key?: string): string {
   const counts = Object.entries(run.toolCounts).sort((a, b) => b[1] - a[1]).map(([name, count]) => `${name}×${count}`).join(", ");
   const facts = [
     run.startedAt !== undefined ? `took ${duration((run.endedAt ?? now) - run.startedAt)}` : "never started",
@@ -1143,23 +1171,26 @@ export function runReport(run: DelegateRun, now = Date.now()): string {
   }
   const failures = run.transcript.filter((entry): entry is ToolEntry => entry.kind === "tool" && entry.status === "error").slice(-5);
   if (failures.length) lines.push(`- failed tool calls: ${failures.map((entry) => cleanText(`${entry.name} ${entry.hint}`, 80)).join("; ")}`);
-  lines.push("", run.output || "(no report)");
+  const output = run.output.length > outputLimit
+    ? run.output.slice(0, outputLimit) + `\n… [report truncated; jar_subagent report ${key ?? run.name} returns the full text]`
+    : run.output;
+  lines.push("", output || "(no report)");
   return lines.join("\n");
 }
 
 const DelegateModeSchema = Type.Union([Type.Literal("scout"), Type.Literal("fork"), Type.Literal("worktree")]);
 const Parameters = Type.Object({
   tasks: Type.Array(Type.Object({
-    task: Type.String({ description: "Task instruction. scout sees only this task; fork/worktree also inherit the parent's active conversation branch." }),
+    task: Type.String({ description: "Task instruction. scout sees only this; fork/worktree also inherit your conversation." }),
     name: Type.Optional(Type.String({ description: "Short label, e.g. \"auth scout\"." })),
-    role: Type.Optional(Type.String({ description: "pi-jar role override. Defaults by mode: scout→scout, fork→reviewer, worktree→worker; then role fallbacks/current model." })),
+    role: Type.Optional(Type.String({ description: "pi-jar role override; defaults by mode (scout→scout, fork→reviewer, worktree→worker), then role fallbacks/current model." })),
     mode: Type.Optional(DelegateModeSchema),
     tools: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 80 }), { minItems: 1, maxItems: 64, uniqueItems: true,
-      description: "Explicit child tool allowlist. scout/fork remain read-only; worktree accepts only sandbox-aware file tools. Browser/web tools may be enabled when active in the parent." })),
-    inheritTools: Type.Optional(Type.Boolean({ description: "Inherit the parent's currently active tool names, subject to mode safety restrictions. Recursive pi-jar delegation tools are always removed." }))
+      description: "Explicit child tool allowlist; grant narrowly. scout/fork stay read-only; worktree accepts only path-guarded file tools; web/browser tools only when active here." })),
+    inheritTools: Type.Optional(Type.Boolean({ description: "Inherit your active tools, filtered by mode safety; recursive delegation tools are always removed." }))
   }), { minItems: 1, maxItems: 16 }),
   mode: Type.Optional(DelegateModeSchema),
-  write: Type.Optional(Type.Boolean({ description: "Deprecated compatibility switch. true keeps the old shared-workspace editing mode; prefer mode=\"worktree\"." }))
+  write: Type.Optional(Type.Boolean({ description: "Deprecated: true = legacy shared-workspace editing; prefer mode=\"worktree\"." }))
 });
 
 const glyph = (state: DelegateState) => state === "done" ? "✔" : state === "failed" ? "✖" : state === "stopped" ? "■" : state === "working" ? "●" : "○";
@@ -1188,7 +1219,7 @@ export interface DelegateController {
 export interface DelegateOptions {
   /** Snapshot names of tools active in the parent session. */
   getActiveToolNames?: () => readonly string[];
-  /** Allowed sizes: 2, 4, 6, 8, 16; defaults to 4. Read on every launch. */
+  /** Allowed sizes: 2, 4, 6, 8, 16; defaults to MAX_DELEGATES. Read on every launch. */
   getMaxSubagents?: () => number;
   /** Shares the delegate lifecycle and capacity with scout orchestration. */
   onController?: (controller: DelegateController) => void;
@@ -1203,6 +1234,8 @@ export interface DelegateOptions {
   discussionRetire?: (key: string) => void;
   /** Unread discussion messages waiting for an agent, shown in the moderator's fleet line. */
   discussionUnread?: (key: string) => number;
+  /** The moderator's unread discussion mail as one notice, marked read; it rides along with subagent events. */
+  discussionDigest?: () => string | undefined;
   /** Settled quiet time before a retained child's process hibernates; defaults to HIBERNATE_AFTER_MS. */
   hibernateAfterMs?: number;
 }
@@ -1215,21 +1248,16 @@ const remainingTasks = (run: DelegateRun): string[] => {
   return leaves.filter((todo) => todo.status !== "completed").map((todo) => todo.title).slice(0, 20);
 };
 
-const taskLabel = (task: string): string => {
-  const text = cleanText(task, 4096);
-  return text.length > 160 ? text.slice(0, 159) + "…" : text;
-};
-
-const controlReport = (report: SubagentStopReport): string => [
+/** The stop handoff, compact like every event: summary, what changed and reached /diff, what is left. `kept` is
+ *  the workspace still holding unapplied changes, if any; a reconciled or discarded worktree is gone. */
+const controlReport = (report: SubagentStopReport, kept: string | undefined): string => [
   `${report.key} · ${report.name} · ${report.state}`,
-  // The moderator already holds the full task in its own jar_delegate call; echo only a label.
-  `task: ${taskLabel(report.task)}`,
-  `workspace: ${report.workspace ?? "none"}`,
-  `changed: ${report.changed.length ? report.changed.join(", ") : "none"}`,
-  `applied: ${report.applied.length ? report.applied.join(", ") : "none"}`,
-  `remaining: ${report.remaining.length ? report.remaining.join("; ") : "none explicitly tracked"}`,
-  report.error ? `error: ${report.error}` : "",
-  report.last ? `last: ${cleanBlock(report.last, 1200)}` : ""
+  `summary: ${report.last ? eventSummary(report.last) : "(no report)"}`,
+  `changed: ${report.changed.length ? fileList(report.changed, 10) : "none"} · applied: ${report.applied.length ? fileList(report.applied, 10) : "none"}`,
+  kept ? `workspace kept: ${kept} (stop retries reconciliation; discard drops it)` : "",
+  report.remaining.length ? `remaining: ${report.remaining.slice(0, 3).map((title) => cleanText(title, 80)).join("; ")}`
+    + (report.remaining.length > 3 ? ` (+${report.remaining.length - 3} more)` : "") : "",
+  report.error ? `error: ${cleanText(report.error, 300)}` : ""
 ].filter(Boolean).join("\n");
 
 /** Peek is task progress only, read from memory: no git, transcript or report reads. */
@@ -1254,9 +1282,19 @@ const peekRecord = (record: SubagentRecord): string => {
     ] : [])
   ].filter(Boolean).join("\n");
 };
-/** The wake-up after a resumed turn: its progress plus the bounded report the turn produced. */
-const settledRecord = (record: SubagentRecord): string =>
-  peekRecord(record) + (record.run.output ? `\nlast: ${cleanBlock(record.run.output, 1200)}` : "");
+/** A settled turn as its event shows it: state and progress, the report's summary, changed files. */
+const turnEvent = (record: SubagentRecord): string => {
+  const run = record.run;
+  const leaves = leafTodos(run.todos);
+  const done = leaves.filter((todo) => todo.status === "completed").length;
+  return [
+    `${record.key} · ${run.name} · ${run.state}${leaves.length ? ` · ${done}/${leaves.length} tasks` : ""}`,
+    `summary: ${run.output ? eventSummary(run.output) : "(no report)"}`,
+    run.filesEdited.length ? `changed: ${fileList(run.filesEdited, 10)}` : "",
+    run.error ? `error: ${cleanText(run.error, 300)}` : "",
+    isRecovery(record) ? `workspace kept: ${run.workspace} (stop retries reconciliation; discard drops it)` : ""
+  ].filter(Boolean).join("\n");
+};
 
 /** One queued moderator notification; several coalesce into a single pi-jar.subagent message. */
 interface SubagentEvent { record: SubagentRecord; kind: "turn" | "control"; label: string; content: string; detail: Record<string, unknown> }
@@ -1302,6 +1340,10 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
     try { return Math.max(0, Math.floor(options.discussionUnread?.(key) ?? 0)) || 0; }
     catch { return 0; } // the count is decoration; the fleet line must still render
   };
+  const discussionDigest = (): string | undefined => {
+    try { return options.discussionDigest?.(); }
+    catch (error) { console.error("pi-jar: could not read the moderator's discussion mail", error); return undefined; }
+  };
   const retireDiscussion = (key: string) => {
     try { options.discussionRetire?.(key); } catch (error) { console.error("pi-jar: could not retire a subagent's discussion identity", error); }
   };
@@ -1316,10 +1358,8 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
     }).join("\n");
     return { message: { customType: "pi-jar.moderator-context", display: false, content: [
       "[PI-JAR MODERATOR MODE]",
-      "You are the coordinator while retained subagents do delegated work. Decompose and route work, steer only to correct direction, use ask for terse BTW questions, and use jar_discuss for structured cross-agent Q/A.",
-      "Initial/resumed turns and asynchronous ask/pause/stop operations wake you with pi-jar.subagent events. Accepted receipts are not completion: do not poll peek or claim files applied before the final event. Keep responding to user steering or do other work.",
-      "Do not duplicate work already owned by a retained subagent. Stop completed workers to obtain their handoff and reconcile worktree changes into /diff. Synthesize the final answer from their reports and evidence.",
-      "Hibernated agents are idle with their process closed to save memory; resume and ask relaunch them with context and workspace intact.",
+      "Retained subagents own their delegated tasks: don't duplicate their work. Their turn ends and ask/pause/stop results arrive as pi-jar.subagent events; an accepted receipt is not completion, so keep working and never poll peek.",
+      "Hibernated agents are idle with the process closed; resume and ask relaunch them intact. Stop finished workers to reconcile worktree changes into /diff, then synthesize from their reports.",
       "Retained fleet:",
       fleet
     ].join("\n") } };
@@ -1358,9 +1398,12 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
     pendingEvents.clear();
     if (!events.length) return;
     const summary = cleanText(`Subagents · ${events.map(event => event.label).join(" · ")}`, 160);
+    // Discussion mail rides along with events delivered anyway; on its own it never wakes the moderator.
+    const mail = discussionDigest();
     return {
       customType: SUBAGENT_MESSAGE, display: true, details: { summary, events: events.map(event => event.detail) },
-      content: [`[PI-JAR SUBAGENT] ${summary}`, ...events.map(event => event.content), "Review, then resume, ask or stop retained agents as needed."].join("\n\n")
+      content: [`[PI-JAR SUBAGENT] ${summary}`, ...events.map(event => event.content), ...(mail ? [mail] : []),
+        "Summaries only: jar_subagent report <agent> returns a full report. Resume, ask or stop retained agents as needed."].join("\n\n")
     };
   };
   const scheduleWake = () => {
@@ -1384,7 +1427,7 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
   pi.registerMessageRenderer?.<{ summary?: string }>(SUBAGENT_MESSAGE, (message, { expanded }, theme) => {
     const text = typeof message.content === "string" ? message.content : "Subagents";
     const summary = message.details?.summary ?? text.split("\n", 1)[0] ?? "Subagents";
-    return new Text(expanded ? text : theme.fg("accent", cleanText(summary, 160)) + theme.fg("dim", " · expand for report"), 0, 0);
+    return new Text(expanded ? text : theme.fg("accent", cleanText(summary, 160)) + theme.fg("dim", " · expand for details"), 0, 0);
   });
   pi.on?.("agent_start", () => { moderatorActive = true; moderatorInterrupted = false; clearTimeout(wakeTimer); wakeTimer = undefined; });
   pi.on?.("turn_end", boundary);
@@ -1401,7 +1444,7 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
         // Freeze reports at the settled boundary. A fast resume must not overwrite a queued
         // initial report, and multiple turns before delivery must each be delivered.
         queueEvent(`${key}:${record.run.resumes}`, { record, kind: "turn", label: `${record.run.name} turn ended`,
-          content: settledRecord(record), detail: { key, turn: record.run.resumes } });
+          content: turnEvent(record), detail: { key, turn: record.run.resumes } });
       }
     }
   });
@@ -1409,14 +1452,11 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
   const delegateTool: ToolDefinition<typeof Parameters> = {
     name: DELEGATE_TOOL,
     label: "delegate",
-    description: `Start retained session-scoped subagents within the configured retained pool limit and return immediately. scout is fresh/read-only and defaults to the scout role; fork inherits the parent conversation read-only and defaults to reviewer; worktree inherits context, defaults to worker, and edits in an isolated Git worktree. Each task may provide an explicit tools allowlist or inheritTools=true to filter the parent's active tools by mode. Turn completions arrive as pi-jar.subagent event messages; control workers with jar_subagent. Settled agents hibernate (process closed, context kept) until resumed. Worktree changes apply only when the moderator stops that agent; at most ${RECOVERY_LIMIT} worktree workspaces may be active or awaiting recovery at once.`,
-    promptSnippet: "Act as moderator: delegate parallel work, then continue responding to the user while subagents run. Their turn completions arrive as pi-jar.subagent event messages; steer, pause or stop them with jar_subagent without polling.",
+    description: `Start retained subagents and return immediately; the pool limit counts idle, paused and hibernated agents. fork and worktree inherit this conversation; a worktree's isolated Git changes reach /diff only when you stop it, and at most ${RECOVERY_LIMIT} worktree workspaces may be active or awaiting recovery (resolve with jar_subagent stop or discard). Turn completions arrive as pi-jar.subagent events with a short summary and changed files; jar_subagent report returns a full report. Settled agents hibernate (process closed, context kept) until resumed.`,
+    promptSnippet: "Start retained parallel subagents: scout (cheap read-only discovery), fork (read-only review with your context), worktree (isolated implementation).",
     promptGuidelines: [
-      "When useful work can be delegated, act as the moderator: decompose, assign, monitor, resolve disagreements, and synthesize. Do not redo a delegated implementation yourself while its worker is active.",
-      "Use scout for cheap independent discovery, fork/reviewer for context-aware review, and worktree/worker for implementation. Explicit task.role overrides these mode defaults. Grant optional task.tools narrowly; task.inheritTools snapshots active parent tools then filters by mode. Scout/fork stay read-only; worktree only accepts path-guarded tools.",
-      "Retained agents become idle after each turn and hibernate after a quiet period; resume and ask relaunch them with their context. Initial and resumed turn completions arrive as pi-jar.subagent event messages, so keep responding to user steering while they work; do not poll jar_subagent peek. Reuse them with jar_subagent resume instead of spawning replacements; pause them when priorities change; stop completed workers to reconcile their worktree into /diff.",
-      "Use jar_subagent ask for a brief BTW question to one worker. For agent-to-agent questions, have them use jar_discuss so answers stay structured and cheap.",
-      "Respect the configured pool limit, including idle, paused and hibernated agents. Stop agents you no longer need; resolve failed worktree recovery records (stop to retry, discard to drop) before starting more worktree agents."
+      "Delegate only when there are ≥2 independent chunks that each need ≥10 tool calls; otherwise do the work yourself.",
+      "After delegating, moderate: completions arrive as pi-jar.subagent events, so keep working and never poll; don't redo delegated work; reuse retained agents (jar_subagent resume) instead of spawning; stop finished workers to apply worktree changes into /diff."
     ],
     parameters: Parameters,
     async execute(_id, params, signal, onUpdate, ctx) {
@@ -1793,7 +1833,10 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
         signal?.removeEventListener("abort", abortAll);
         publish();
         toolReturned = true;
-        return { content: [{ type: "text", text: runs.map((run) => runReport(run)).join("\n\n") + "\n\nSubagent launch is asynchronous; turn reports arrive as pi-jar.subagent events. You can continue working or steer the fleet with jar_subagent." }], details: details() };
+        return { content: [{ type: "text", text: [
+          `Subagent launch is asynchronous: ${plural(records.length, "agent")} started; turn reports arrive as pi-jar.subagent events. Keep working or steer with jar_subagent; don't poll.`,
+          ...records.map(({ key, run }) => `- ${key} · ${run.name} · ${run.mode} · ${run.role}${run.model ? " · " + run.model : ""}`)
+        ].join("\n") }], details: details() };
       }
       await startup;
       publish();
@@ -1809,7 +1852,9 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
         flushUpdate();
         toolReturned = true;
       }
-      return { content: [{ type: "text", text: runs.map((run) => runReport(run)).join("\n\n") }], details: details(),
+      const outputLimit = Math.max(MIN_RUN_REPORT_CHARS, Math.floor(MAX_RESULT_REPORT_CHARS / Math.max(1, runs.length)));
+      const keys = new Map(records.map(({ key, run }) => [run, key]));
+      return { content: [{ type: "text", text: runs.map((run) => runReport(run, Date.now(), outputLimit, keys.get(run))).join("\n\n") }], details: details(),
         ...(runs.some((run) => run.state === "failed") ? { isError: true } : {}) };
       } finally { releaseReservation(); }
     },
@@ -1852,7 +1897,7 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
       if (!launched) throw new Error(result.content.map((part) => "text" in part ? part.text : "").join("\n"));
       const record = registry.get(`delegate-${launched}-1`);
       if (!record) throw new Error("Scout session was discarded");
-      // This launch is an internal democracy vote; its caller is already awaiting the result,
+      // This launch is an internal council vote; its caller is already awaiting the result,
       // so the moderator does not need a duplicate unsolicited completion notification.
       watched.delete(record.key);
       deleteSettled(record.key);
@@ -1906,26 +1951,25 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
     const status = result.isError ? "failed" : "completed";
     // The stop handoff supersedes any queued turn report for the same agent.
     if (operation.action === "stop") deleteSettled(record.key);
+    const text = result.content.map(part => part.text).join("\n");
     queueEvent(operation.id, { record, kind: "control", label: `${operation.action} ${record.run.name} ${status}`,
-      content: `${operation.action} ${operation.id} ${status}:\n${result.content.map(part => part.text).join("\n")}`,
+      // A stop handoff is already compact; any other result (a BTW answer, an error) is clipped like a summary.
+      content: `${operation.action} ${operation.id} ${status}:\n${operation.action === "stop" ? text : summaryLine(text)}`,
       detail: { operationId: operation.id, action: operation.action, key: record.key, status, report: result.details } });
   };
 
   pi.registerTool({
     name: "jar_subagent",
     label: "subagent",
-    description: "Non-blocking moderator control for retained subagents. peek, steer, resume and discard return immediately. ask, pause and stop return an accepted operation receipt; the final answer or handoff arrives as a pi-jar.subagent event. Settled agents hibernate (process closed, context and workspace kept); resume and ask relaunch them transparently. Stop completion safely reconciles worktree changes; acceptance does not mean changes are applied yet. discard removes an unresolved worktree recovery workspace without applying it.",
-    promptSnippet: "Use jar_subagent as the moderator control plane. Prefer peek over rereading transcripts; reuse paused/idle/hibernated agents with resume; stop finished workers to reconcile their work.",
+    description: "Non-blocking control for retained subagents. peek: task progress only (plus workspace and changed files of an unresolved worktree recovery). report: an agent's latest full report, for retained and recently finished agents. steer: redirect a working agent. resume: continue an idle, paused or hibernated agent (hibernated ones relaunch transparently). ask, pause and stop return an accepted receipt; the answer or handoff arrives as a pi-jar.subagent event. stop aborts any active turn, retires the agent, reports changes and remaining work, and reconciles worktree changes into /diff (on a failed recovery record it retries). discard removes an unresolved recovery workspace without applying it.",
+    promptSnippet: "Moderator control for retained subagents: peek, report, steer, ask, pause, resume, stop, discard.",
     promptGuidelines: [
-      "peek returns only task progress, plus workspace and changed files for unresolved worktree recovery records. Do not poll: initial/resumed turns and control completions send pi-jar.subagent events. Stop returns an accepted receipt first, then changed files and the full handoff in its completion event.",
-      "Use steer for active direction and ask for a brief BTW question. ask, pause and stop do not wait on the child; continue responding to the user until their completion event arrives.",
-      "Pause when an agent should stop spending tokens but keep its context/workspace. Resume the same agent later instead of spawning a replacement; a hibernated agent resumes exactly like an idle one.",
-      "Stop when an agent is no longer needed. Stop aborts any active turn, retires the process, reports progress/workspace/changes/remaining work, and reconciles safe worktree changes into /diff. On a failed/conflicted worktree recovery record, stop retries reconciliation; discard it only when its changes are not wanted."
+      "Results arrive as pi-jar.subagent events; never poll. Reuse idle/paused/hibernated agents with resume instead of spawning; ask = one brief BTW question; pause keeps context without spending; read report only when an event summary is not enough."
     ],
     parameters: Type.Object({
       action: Type.Union([
         Type.Literal("peek"), Type.Literal("steer"), Type.Literal("ask"),
-        Type.Literal("pause"), Type.Literal("resume"), Type.Literal("stop"), Type.Literal("discard")
+        Type.Literal("pause"), Type.Literal("resume"), Type.Literal("stop"), Type.Literal("discard"), Type.Literal("report")
       ]),
       agent: Type.Optional(Type.String({ description: "Subagent key or unique name. Omit only for peek to show all retained agents." })),
       message: Type.Optional(Type.String({ description: "Direction, BTW question, or resume instruction." }))
@@ -1942,6 +1986,7 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
       const agent = params.agent ?? "";
       const record = registry.resolve(agent);
       if (!record) return { content: [{ type: "text", text: "Subagent not found or name is ambiguous: " + agent }], isError: true };
+      if (params.action === "report") return { content: [{ type: "text", text: runReport(record.run) }] };
       const stopping = pendingControls.get(record.key + ":stop");
       const controlling = pendingControls.get(record.key + ":control");
       if (stopping || (controlling && params.action !== "stop")) {
@@ -1990,7 +2035,7 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
       }
       const report = await registry.stop(record.key);
       if (!report) return { content: [{ type: "text", text: "Subagent is already retired: " + record.run.name }] };
-      return { content: [{ type: "text", text: controlReport(report) }], details: report, isError: !!report.error };
+      return { content: [{ type: "text", text: controlReport(report, record.run.workspace) }], details: report, isError: !!report.error };
       };
       // Internal registry APIs remain awaited for shutdown/reconciliation correctness. Only the
       // external tool boundary is detached, so parent steering never waits on a child turn or Git.

package/src/discussion-hub.ts

@@ -14,6 +14,8 @@ const MAX_DISCUSSION_AGENTS = 64;
 /** A list reply never exceeds this, however many messages match; each listed message is clipped too. */
 export const MAX_LIST_CHARS = 4000;
 export const MAX_LISTED_TEXT = 400;
+/** A turn-start notice carries at most this much unread mail; the rest stays one `list` away. */
+export const MAX_NOTICE_CHARS = 2000;
 /** Unread mail piggybacked on an ask/answer reply never exceeds this. */
 const MAX_PIGGYBACK_CHARS = 1000;
 const BROADCAST: Record<string, true> = { all: true, "*": true, everyone: true, broadcast: true };
@@ -168,11 +170,11 @@ export class DiscussionHub {
 
   /** Unread mail, oldest first within the reply budget; the cursor moves past what was shown, so paging
    *  loses nothing. `since` rereads relevant messages newer than an id, read or not. */
-  list(key: string, since?: number): ListResult {
+  list(key: string, since?: number, budget = MAX_LIST_CHARS): ListResult {
     const agent = this.agent(key);
     const items = this.messages.filter((message) => this.relevant(agent, message)
       && (since === undefined ? !this.read(agent, message) : message.id > since));
-    const { views, shown } = this.select(items, MAX_LISTED_TEXT);
+    const { views, shown } = this.select(items, MAX_LISTED_TEXT, budget);
     this.markRead(agent, shown);
     const latest = this.messages.at(-1)?.id;
     return { messages: views, more: items.length - views.length, ...(latest ? { latest } : {}), unread: this.unreadOf(agent).length };
@@ -214,8 +216,9 @@ export class DiscussionHub {
     return { ...result, agents, unanswered: { total: open.length, questions } };
   }
 
-  unread(key: string): UnreadResult {
-    const unread = this.unreadOf(this.agent(key));
+  /** `except` leaves that sender's mail out, so the moderator's view of a subagent's mailbox never echoes its own messages. */
+  unread(key: string, except?: string): UnreadResult {
+    const unread = this.unreadOf(this.agent(key)).filter((message) => message.from !== except);
     return { unread: unread.length, ...(unread.length ? { newest: unread.at(-1)!.id } : {}) };
   }
 
@@ -334,13 +337,13 @@ export class DiscussionHub {
   }
 
   /** Oldest first into the budget; at least one message, so paging always progresses. */
-  private select(items: readonly Stored[], limit: number): { views: MessageView[]; shown: Stored[] } {
+  private select(items: readonly Stored[], limit: number, budget = MAX_LIST_CHARS): { views: MessageView[]; shown: Stored[] } {
     const views: MessageView[] = [];
     let used = 0;
     for (const message of items) {
       const view = this.view(message, limit);
       const size = messageLine(view).length + 1;
-      if (views.length && used + size > MAX_LIST_CHARS) break;
+      if (views.length && used + size > budget) break;
       views.push(view);
       used += size;
     }

package/src/discussion.ts

@@ -6,8 +6,8 @@ import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import {
-  DiscussionError, DiscussionHub, MAX_DISCUSSION_BYTES, MAX_DISCUSSION_MESSAGES, MAX_DISCUSSION_TEXT, MAX_LIST_CHARS, messageLine,
-  MODERATOR, parseDiscussionId, type ListResult, type PendingResult, type PostResult, type ThreadResult, type UnreadResult
+  DiscussionError, DiscussionHub, MAX_DISCUSSION_BYTES, MAX_DISCUSSION_MESSAGES, MAX_DISCUSSION_TEXT, MAX_LIST_CHARS, MAX_NOTICE_CHARS, messageLine,
+  MODERATOR, parseDiscussionId, type ListResult, type PendingResult, type PostResult, type ThreadResult
 } from "./discussion-hub.ts";
 import { cleanText } from "./status.ts";
 
@@ -44,7 +44,8 @@ export interface DiscussionTransport {
   list(since?: number): Promise<ListResult>;
   thread(questionId: number, since?: number): Promise<ThreadResult>;
   pending(): Promise<PendingResult>;
-  unread(): Promise<UnreadResult>;
+  /** Unread mail for a turn-start notice, marked read: a list within the smaller notice budget. */
+  inbox(): Promise<ListResult>;
 }
 
 /** A 1600-character message JSON-escapes to well under this; anything larger is not from our client. */
@@ -65,7 +66,7 @@ const transportOf = (request: Request): DiscussionTransport => ({
   list: (since) => request("list", since === undefined ? {} : { since }) as Promise<ListResult>,
   thread: (questionId, since) => request("thread", since === undefined ? { questionId } : { questionId, since }) as Promise<ThreadResult>,
   pending: () => request("pending", {}) as Promise<PendingResult>,
-  unread: () => request("unread", {}) as Promise<UnreadResult>
+  inbox: () => request("inbox", {}) as Promise<ListResult>
 });
 
 /** Shared by the tool adapter and the broker, so a bad id is rejected the same way on both sides. */
@@ -147,7 +148,12 @@ export class DiscussionBroker {
     this.notify();
   }
 
-  unreadFor(key: string): number { return this.hub.has(key) ? this.hub.unread(key).unread : 0; }
+  /** Unread mail waiting for an agent, minus the moderator's own messages: the moderator's fleet line never
+   *  echoes its broadcasts or questions back to it. */
+  unreadFor(key: string): number { return this.hub.has(key) ? this.hub.unread(key, MODERATOR).unread : 0; }
+
+  /** The moderator's unread mail as one notice, marked read, to ride along with subagent events delivered anyway. */
+  digest(): string | undefined { return inboxNotice(this.call(MODERATOR, "inbox", {}) as ListResult); }
 
   stats(): DiscussionStats {
     return {
@@ -254,7 +260,7 @@ export class DiscussionBroker {
         case "list": return this.hub.list(key, idArgument(args.since, "since", false));
         case "thread": return this.hub.thread(key, idArgument(args.questionId, "questionId", true)!, idArgument(args.since, "since", false));
         case "pending": return this.hub.pending(key);
-        case "unread": return this.hub.unread(key);
+        case "inbox": return this.hub.list(key, undefined, MAX_NOTICE_CHARS);
         default: throw new DiscussionError("Unknown discussion operation.");
       }
     } catch (error) {
@@ -363,6 +369,16 @@ export function discussionClientFromEnv(env: NodeJS.ProcessEnv = process.env): D
 
 const plural = (count: number, word: string) => `${count} ${word}${count === 1 ? "" : "s"}`;
 
+/** Unread mail as one notice; it is marked read once fetched, so a message is never announced twice. */
+export function inboxNotice(result: ListResult): string | undefined {
+  if (!result.messages.length) return undefined;
+  return [
+    "Discussion mail (now read; reply with jar_discuss answer):",
+    ...result.messages.map(messageLine),
+    ...(result.more ? [`(${plural(result.more, "more unread message")}; jar_discuss list)`] : [])
+  ].join("\n");
+}
+
 export function registerDiscussionTool(pi: ExtensionAPI, transport: () => DiscussionTransport | undefined): void {
   const parameters = Type.Object({
     action: Type.Union([Type.Literal("ask"), Type.Literal("answer"), Type.Literal("list"), Type.Literal("thread"), Type.Literal("pending")]),
@@ -376,12 +392,8 @@ export function registerDiscussionTool(pi: ExtensionAPI, transport: () => Discus
   pi.registerTool?.<typeof parameters, Record<string, never>>({
     name: "jar_discuss",
     label: "discuss",
-    description: `Parent-brokered Q/A between this session's moderator and subagents; not a transcript, and it never wakes anyone. ask/answer reply with the new id only. list returns only unread messages for you: questions to you, broadcasts, answers to your questions (≤${MAX_LIST_CHARS} chars).`,
-    promptSnippet: "Ask or answer one concrete cross-agent question through the session discussion broker.",
-    promptGuidelines: [
-      "jar_discuss: one precise question or answer per call. ask to moderator, a subagent key or unique name, or omit to to broadcast; answer needs the questionId. Replies never echo your text.",
-      "Answers to your questions also arrive on your next ask/answer. list shows only unread messages for you; thread reads one question in full; pending summarizes open items. Don't poll."
-    ],
+    description: `Parent-brokered Q/A between this session's moderator and subagents; never wakes anyone. ask/answer reply with the new id (never your text) plus your unread mail when it fits. Unread mail (questions to you, broadcasts, answers to your questions; never your own) also arrives once at your next turn start. list: your unread (≤${MAX_LIST_CHARS} chars); thread: one question in full; pending: open counts.`,
+    promptSnippet: "One concise cross-agent question or answer per call; unread mail reaches you at turn start, so never poll.",
     parameters,
     async execute(_id, params) {
       const broker = transport();
@@ -441,19 +453,16 @@ export function registerDiscussionTool(pi: ExtensionAPI, transport: () => Discus
     }
   });
 
-  // At a natural boundary only: a hidden notice joins the turn that is starting anyway. Discussion
-  // traffic never sends a message or triggers a turn, so agents cannot wake each other into a loop.
-  let notified: number | undefined;
+  // At a natural boundary only: unread mail joins the turn that is starting anyway, as one hidden message
+  // that already carries it, so reading it costs no list call. Discussion traffic never sends a message
+  // or triggers a turn, so agents cannot wake each other into a loop.
   pi.on?.("before_agent_start", async () => {
     const broker = transport();
     if (!broker) return;
-    let state: UnreadResult;
+    let inbox: ListResult;
     // Advisory only: a broker failure surfaces on the agent's next jar_discuss call instead of delaying this turn.
-    try { state = await broker.unread(); } catch { return; }
-    // Once per newest unread message: ignored mail is not re-announced every turn.
-    if (!state.unread || state.newest === notified) return;
-    notified = state.newest;
-    return { message: { customType: DISCUSSION_NOTICE, display: false,
-      content: `You have ${plural(state.unread, "unread discussion message")}. Use jar_discuss list when relevant.` } };
+    try { inbox = await broker.inbox(); } catch { return; }
+    const content = inboxNotice(inbox);
+    if (content) return { message: { customType: DISCUSSION_NOTICE, display: false, content } };
   });
 }

package/src/footer.ts

@@ -18,6 +18,8 @@ export interface FooterView extends JarStatus {
   cwd?: string;
   settings?: FooterSettings;
   context: string;
+  /** The last call's prompt is past the context budget: the context metric turns amber. */
+  overBudget?: boolean;
   goal?: string;
   /** pi-jar's own short indicators (changes to review), shown before extras. */
   chips?: readonly string[];
@@ -139,7 +141,7 @@ function footerLines(view: FooterView, width: number, theme: FooterTheme, hits:
   const quota = view.quota;
   const windowList = [quota?.fiveHour && `5h ${Math.round(quota.fiveHour.used)}%`, quota?.week && `week ${Math.round(quota.week.used)}%`].filter((value): value is string => !!value);
   const windows = windowList.map((value, index) => index ? value : withIcon("quota", value));
-  const cost = view.cost ? metric("cost", "cost", cleanText(view.cost, 20)) : undefined;
+  const cost = view.cost ? metric("cost", "cost", cleanText(view.cost, 32)) : undefined;
   const memory = view.memory ? metric("memory", "ram", view.memory) : undefined;
   const prefix = view.demo ? theme.fg("warning", "DEMO") : "";
   const effort = show.effort && view.effort ? theme.fg(EFFORT_COLORS[view.effort], THINKING_ICONS[view.effort] ? withIcon(THINKING_ICONS[view.effort]!, view.effort) : view.effort) : "";
@@ -151,6 +153,8 @@ function footerLines(view: FooterView, width: number, theme: FooterTheme, hits:
   // Context is never dropped; optional metrics move to a second line on medium widths.
   const metrics = [...(show.context ? [context] : []), ...(show.memory && contentWidth >= 90 && memory ? [memory] : []), ...(show.cost && contentWidth >= 52 && cost ? [cost] : []), ...(show.quota && contentWidth >= 90 ? windows : [])];
   let right = theme.fg("dim", metrics.join("  ·  "));
+  // Context always leads the metrics when shown, so only its own color changes past the budget.
+  if (view.overBudget && show.context) right = theme.fg("warning", context) + (metrics.length > 1 ? theme.fg("dim", "  ·  " + metrics.slice(1).join("  ·  ")) : "");
   if (contentWidth < 52 && attention && contentWidth >= 26) {
     const room = Math.max(0, contentWidth - Math.min(visibleWidth(left), 12) - visibleWidth(right) - 4);
     right = theme.fg(primary?.state === "failed" ? "error" : "warning", truncateToWidth(attention, Math.min(room, 14))) + " " + right;