pi-jar 0.1.6 → 0.1.8

package/src/discussion.ts

@@ -88,9 +88,10 @@ async function withPaperLock<T>(file: string, run: () => T): Promise<T> {
   throw new Error("discussion paper is busy");
 }
 
-/** Append under the lock; `accept` validates against the same snapshot, so there is one read per write. */
+/** Append under the lock; `accept` validates against the same snapshot, so there is one read per write.
+ *  The written snapshot is returned too, so the caller can piggyback unseen entries without a second read. */
 function append(file: string, actor: string, entry: Omit<DiscussionEntry, "id" | "from" | "at">,
-  accept: (paper: DiscussionPaper) => string | undefined = () => undefined): Promise<DiscussionEntry | string> {
+  accept: (paper: DiscussionPaper) => string | undefined = () => undefined): Promise<{ entry: DiscussionEntry; paper: DiscussionPaper } | string> {
   return withPaperLock(file, () => {
     const paper = readPaper(file);
     const rejected = accept(paper);
@@ -106,7 +107,7 @@ function append(file: string, actor: string, entry: Omit<DiscussionEntry, "id" |
     paper.entries.push(next);
     if (paper.entries.length > MAX_DISCUSSION_ENTRIES) paper.entries.splice(0, paper.entries.length - MAX_DISCUSSION_ENTRIES);
     writePaper(file, paper);
-    return next;
+    return { entry: next, paper };
   });
 }
 
@@ -133,57 +134,94 @@ const render = (entries: readonly DiscussionEntry[], limit: number): string => {
   }
   const omitted = entries.length - lines.length;
   return (omitted ? `(${omitted} older entries omitted; use questionId to read one thread)\n` : "") + lines.join("\n")
-    + `\n(newest: ${entries.at(-1)!.id}; pass since=${entries.at(-1)!.id} to read only newer entries)`;
+    + `\n(latest ${entries.at(-1)!.id})`;
 };
 
+/** Unseen entries piggybacked on an ask/answer reply never exceed this. */
+const MAX_PIGGYBACK_CHARS = 1000;
+
 export function registerDiscussionTool(pi: ExtensionAPI, file: () => string | undefined,
   actor: () => string = () => safeActor(process.env[SUBAGENT_NAME_ENV] ?? process.env[SUBAGENT_KEY_ENV])): void {
+  // Every Pi process (moderator or child) registers its own tool, so this closure is one actor's read
+  // cursor: the highest seq it has been shown on the current paper. A different path, or a paper whose
+  // seq went backwards (recreated), starts over at zero.
+  let cursor = { path: "", seq: 0 };
+  const unseen = (path: string, paper: DiscussionPaper, me: string) => {
+    if (cursor.path !== path || paper.seq < cursor.seq) cursor = { path, seq: 0 };
+    const after = cursor.seq;
+    return paper.entries.filter((entry) => (seqOf(entry.id) ?? 0) > after && entry.from !== me);
+  };
+  const advance = (seq: number) => { cursor.seq = Math.max(cursor.seq, seq); };
+  // The cursor is one max-seq, so it may only move past everything unseen. An ask/answer reply therefore
+  // attaches unseen entries (and advances) only when every unseen non-own entry is relevant to the caller
+  // (a question addressed to it, or an answer to one of its questions) and all of them fit
+  // MAX_PIGGYBACK_CHARS; otherwise it adds a one-line count and leaves them for `list`. The question being
+  // answered (`known`) counts as seen: the caller already has it.
+  const piggyback = (path: string, paper: DiscussionPaper, me: string, known?: string): string => {
+    const fresh = unseen(path, paper, me).filter((entry) => entry.id !== known);
+    if (!fresh.length) { advance(paper.seq); return ""; }
+    const asked = new Set(paper.entries.filter((entry) => entry.kind === "question" && entry.from === me).map((entry) => entry.id));
+    const relevant = fresh.filter((entry) => entry.kind === "question" ? entry.to === me : asked.has(entry.questionId ?? ""));
+    const shown = relevant.map((entry) => entryLine(entry, MAX_LISTED_TEXT)).join("\n");
+    if (relevant.length === fresh.length && shown.length <= MAX_PIGGYBACK_CHARS) { advance(paper.seq); return "\n" + shown; }
+    return `\n(${fresh.length} new ${fresh.length === 1 ? "entry" : "entries"}${relevant.length ? `, ${relevant.length} for you` : ""}; list to read)`;
+  };
   const parameters = Type.Object({
     action: Type.Union([Type.Literal("list"), Type.Literal("ask"), Type.Literal("answer")]),
     text: Type.Optional(Type.String()),
     to: Type.Optional(Type.String()),
     questionId: Type.Optional(Type.String({ description: "answer: the question being answered. list: read only that question and its answers, in full." })),
-    since: Type.Optional(Type.String({ description: "list: only entries newer than this id (e.g. d12), so rereads cost nothing when nothing changed." }))
+    since: Type.Optional(Type.String({ description: "list: entries newer than this id (e.g. d12) instead of only unseen ones; \"d0\" rereads everything." }))
   });
   pi.registerTool?.<typeof parameters, { path?: string; entry?: DiscussionEntry }>({
     name: "jar_discuss",
     label: "discuss",
-    description: `Use the session's bounded shared discussion paper for terse cross-agent questions and answers. Prefer one precise question or answer per call; do not use it as a transcript or scratchpad. list replies are capped at ${MAX_LIST_CHARS} characters.`,
-    promptSnippet: "Use jar_discuss when another subagent needs a concrete question answered without routing a long conversation through the moderator.",
+    description: `Shared bounded Q/A paper between this session's agents; not a transcript. ask/answer reply with the new id only. list returns only entries you have not seen (≤${MAX_LIST_CHARS} chars).`,
+    promptSnippet: "Ask or answer one concrete cross-agent question on the shared discussion paper.",
     promptGuidelines: [
-      "Keep discussion entries short and decision-oriented. Read the paper before answering if the question id is unfamiliar.",
-      "When answering, address only the requested question and cite the question id. Do not continue unrelated task work inside the discussion entry.",
-      "Do not poll list while waiting for an answer: continue your task and check again later with since set to the newest id you saw; use questionId to read one thread."
+      "jar_discuss: one precise question or answer per call; answer only the given questionId. Replies never echo your text.",
+      "Answers to your questions also arrive on your next ask/answer. list shows only unseen entries; questionId reads one thread. Don't poll."
     ],
     parameters,
     async execute(_id, params) {
       const path = file();
       if (!path) return { content: [{ type: "text", text: "No shared discussion paper is active." }], details: {} };
+      const me = safeActor(actor());
       if (params.action === "list") {
-        const entries = discussionEntries(path);
+        const paper = readPaper(path);
         const thread = params.questionId ? cleanText(params.questionId, 24) : undefined;
         if (thread) {
-          const items = entries.filter((entry) => entry.id === thread || entry.questionId === thread);
+          const items = paper.entries.filter((entry) => entry.id === thread || entry.questionId === thread);
           return { content: [{ type: "text", text: render(items, MAX_DISCUSSION_TEXT) }], details: { path } };
         }
         const since = seqOf(params.since);
-        const newer = since === undefined ? entries : entries.filter((entry) => (seqOf(entry.id) ?? 0) > since);
-        if (since !== undefined && !newer.length) return { content: [{ type: "text", text: `No entries newer than ${params.since}.` }], details: { path } };
-        return { content: [{ type: "text", text: render(newer, MAX_LISTED_TEXT) }], details: { path } };
+        const fresh = unseen(path, paper, me);
+        advance(paper.seq);
+        if (since !== undefined) {
+          const newer = paper.entries.filter((entry) => (seqOf(entry.id) ?? 0) > since);
+          const text = newer.length ? render(newer, MAX_LISTED_TEXT) : `No entries newer than ${params.since}.`;
+          return { content: [{ type: "text", text }], details: { path } };
+        }
+        const latest = paper.entries.at(-1)?.id;
+        const text = fresh.length ? render(fresh, MAX_LISTED_TEXT) : `No new entries${latest ? ` (latest ${latest})` : ""}.`;
+        return { content: [{ type: "text", text }], details: { path } };
       }
       const text = cleanText(params.text ?? "", MAX_DISCUSSION_TEXT);
       if (!text) return { content: [{ type: "text", text: "Discussion text is required." }], details: {}, isError: true };
       if (params.action === "ask") {
-        const entry = await append(path, actor(), { kind: "question", text, ...(params.to ? { to: safeActor(params.to) } : {}) });
-        if (typeof entry === "string") return { content: [{ type: "text", text: entry }], details: {}, isError: true };
-        return { content: [{ type: "text", text: `Added ${entry.id}: ${entry.text}` }], details: { path, entry } };
+        const added = await append(path, me, { kind: "question", text, ...(params.to ? { to: safeActor(params.to) } : {}) });
+        if (typeof added === "string") return { content: [{ type: "text", text: added }], details: {}, isError: true };
+        const { entry, paper } = added;
+        const reply = `Added ${entry.id}${entry.to ? ` (→ ${entry.to})` : ""}.` + piggyback(path, paper, me);
+        return { content: [{ type: "text", text: reply }], details: { path, entry } };
       }
       const questionId = cleanText(params.questionId ?? "", 24);
       if (!questionId) return { content: [{ type: "text", text: "questionId is required for an answer." }], details: {}, isError: true };
-      const entry = await append(path, actor(), { kind: "answer", questionId, text }, (paper) =>
+      const added = await append(path, me, { kind: "answer", questionId, text }, (paper) =>
         paper.entries.some((item) => item.kind === "question" && item.id === questionId) ? undefined : "Unknown discussion question: " + questionId);
-      if (typeof entry === "string") return { content: [{ type: "text", text: entry }], details: {}, isError: true };
-      return { content: [{ type: "text", text: `Answered ${questionId}: ${entry.text}` }], details: { path, entry } };
+      if (typeof added === "string") return { content: [{ type: "text", text: added }], details: {}, isError: true };
+      const { entry, paper } = added;
+      return { content: [{ type: "text", text: `Answered ${questionId} as ${entry.id}.` + piggyback(path, paper, me, questionId) }], details: { path, entry } };
     }
   });
 }

package/src/quota.ts

@@ -84,7 +84,18 @@ export async function fetchQuota(provider: QuotaProvider, resolveAuth: (provider
         const item = window as Record<string, unknown>;
         return windowValue({ used: item.used_percent, resetsAt: typeof item.reset_at === "number" ? item.reset_at * 1000 : undefined });
       };
-      return parseQuota({ fiveHour: parse(rate.primary_window), week: parse(rate.secondary_window) });
+      // Window slots are not fixed: Plus accounts get a single weekly `primary_window` and a null
+      // secondary. Classify by `limit_window_seconds` (≤ 1 day is the short window), falling back
+      // to position only when the duration is absent.
+      const quota: Quota = {};
+      for (const [window, fallback] of [[rate.primary_window, "fiveHour"], [rate.secondary_window, "week"]] as const) {
+        const value = parse(window);
+        if (!value) continue;
+        const seconds = (window as Record<string, unknown>).limit_window_seconds;
+        const slot = typeof seconds === "number" && seconds > 0 ? (seconds <= 24 * 60 * 60 ? "fiveHour" : "week") : fallback;
+        if (!quota[slot]) quota[slot] = value;
+      }
+      return parseQuota(quota);
     }
     const parse = (window: unknown): QuotaWindow | undefined => {
       if (!window || typeof window !== "object") return undefined;

package/src/shell-notifications.ts

@@ -0,0 +1,104 @@
+import type { ExtensionAPI, CustomMessageEntryDraft } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { cleanText } from "./status.ts";
+import { describe, SHELL_MESSAGE, type ShellEvent, type ShellManager } from "./shells.ts";
+
+export interface ShellNotificationDetails {
+  summary: string;
+  ids: string[];
+  events: Array<{ id: string; name: string; kind: ShellEvent["kind"]; status: string; exitCode?: number | null }>;
+}
+
+/** A compact transport payload; logs are fetched explicitly, never copied into wake-up messages. */
+export function shellNotification(events: readonly ShellEvent[]): CustomMessageEntryDraft {
+  const failed = events.filter(({ kind, job }) => kind === "exit" && (job.status === "failed" || (job.status === "exited" && job.exitCode !== 0))).length;
+  const ready = events.filter(event => event.kind === "match").length;
+  const completed = events.length - ready;
+  const summary = `Background shells · ${completed} completed${failed ? ` · ${failed} failed` : ""}${ready ? ` · ${ready} ready` : ""}`;
+  const details: ShellNotificationDetails = {
+    summary, ids: events.map(event => event.job.id),
+    events: events.map(({ kind, job }) => ({ id: job.id, name: job.name, kind, status: job.status, exitCode: job.exitCode }))
+  };
+  return {
+    type: "custom_message", customType: SHELL_MESSAGE, display: true, details,
+    content: [summary, ...events.map(({ kind, job }) => kind === "match" ? `${job.id} · ${job.name} · ready: ${cleanText(job.matched ?? "", 120)}` : describe(job)),
+      "Use jar_shell output for relevant diagnostics only; observed completions do not replay."].join("\n")
+  };
+}
+
+/** Keep events in our own queue while the model runs, not Pi's irrevocable follow-up queue.
+ * Boundary entries are consumed before final settlement; output/peek/wait can acknowledge events
+ * before delivery. Idle events wake once after a debounce, and session replacement drops old work. */
+export function registerShellNotifications(pi: ExtensionAPI, manager: () => ShellManager | undefined): { notify(): void; dispose(): void } {
+  let active = false;
+  let interrupted = false;
+  let deliveryFailures = 0;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const warned = new Set<string>();
+  const cancelTimer = () => { clearTimeout(timer); timer = undefined; };
+  const take = () => {
+    cancelTimer();
+    const events = manager()?.takeNotifications() ?? [];
+    return events.length ? shellNotification(events) : undefined;
+  };
+  const notify = () => {
+    if (active || interrupted || timer || !manager()?.pendingNotifications()) return;
+    const owner = manager();
+    timer = setTimeout(() => {
+      timer = undefined;
+      if (active || interrupted || owner !== manager()) return;
+      const events = owner?.takeNotifications() ?? [];
+      if (!events.length) return;
+      const { type: _type, ...message } = shellNotification(events);
+      try { pi.sendMessage(message, { triggerTurn: true, deliverAs: "nextTurn" }); deliveryFailures = 0; }
+      catch (error) {
+        owner?.restoreNotifications(events);
+        console.error("pi-jar: could not deliver shell summary", error);
+        if (++deliveryFailures < 3) notify();
+      }
+    }, 300);
+    timer.unref?.();
+  };
+  const reset = () => { cancelTimer(); active = false; interrupted = false; deliveryFailures = 0; warned.clear(); };
+
+  pi.registerMessageRenderer?.<ShellNotificationDetails>(SHELL_MESSAGE, (message, { expanded }, theme) => {
+    const text = typeof message.content === "string" ? message.content : "Background shells";
+    const summary = message.details?.summary ?? text.split("\n", 1)[0] ?? "Background shells";
+    return new Text(expanded ? text : theme.fg("accent", cleanText(summary, 160)) + theme.fg("dim", " · expand for status"), 0, 0);
+  });
+  pi.on?.("session_start", reset);
+  pi.on?.("session_shutdown", reset);
+  pi.on?.("before_agent_start", () => {
+    active = true;
+    interrupted = false;
+    const entry = take();
+    if (!entry) return;
+    const { type: _type, ...message } = entry;
+    return { message };
+  });
+  pi.on?.("agent_start", () => { active = true; cancelTimer(); });
+  pi.on?.("turn_end", event => {
+    if (event.outcome !== "completed" || event.context?.canContinue === false) return;
+    const entry = take();
+    if (entry) return { entries: [entry], continue: true };
+  });
+  pi.on?.("agent_before_settle", event => {
+    interrupted = event.outcome !== "completed";
+    if (interrupted || event.context?.canContinue === false) return;
+    const entry = take();
+    if (entry) return { entries: [entry], continue: true };
+    // One reminder per outstanding finite job, never a self-repeating continuation loop.
+    const owner = manager();
+    const known = new Set(owner?.summaries().map(job => job.id) ?? []);
+    for (const id of warned) if (!known.has(id)) warned.delete(id);
+    const pending = (owner?.verificationPending() ?? []).filter(job => !warned.has(job.id));
+    if (!pending.length) return;
+    for (const job of pending) warned.add(job.id);
+    return { entries: [{ type: "custom_message" as const, customType: SHELL_MESSAGE, display: true,
+      content: `Verification still pending: ${pending.map(job => `${job.id} (${job.name})`).join(", ")}. Use jar_shell wait/peek for these ids before claiming success, or clearly report them as pending. Do not wait for long-lived services.`,
+      details: { summary: `${pending.length} background check(s) still pending`, ids: pending.map(job => job.id) }
+    }], continue: true };
+  });
+  pi.on?.("agent_settled", () => { active = false; notify(); });
+  return { notify, dispose: reset };
+}

package/src/shells.ts

@@ -1,4 +1,5 @@
 import { spawn, type ChildProcess } from "node:child_process";
+import { signalProcessTree } from "./async-process.ts";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
@@ -30,6 +31,8 @@ export interface ShellJob {
   signal?: string | null;
   error?: string;
   watch?: string;
+  purpose?: "task" | "service";
+  complete?: boolean;
   matched?: string;
   /** Wake the agent when the pattern matches or the process ends. */
   notify: boolean;
@@ -38,14 +41,27 @@ export interface ShellJob {
   dropped: number;
 }
 export type ShellEvent = { kind: "match" | "exit"; job: ShellJob };
-export interface StartOptions { command: string; cwd: string; name?: string; watch?: string; notify?: boolean }
+export interface StartOptions { command: string; cwd: string; name?: string; watch?: string; notify?: boolean; purpose?: "task" | "service" }
 
 const ANSI = /\x1b\][^\x07]*(?:\x07|\x1b\\)?|\x1b\[[0-?]*[ -/]*[@-~]|\x1b./g;
 
+interface ShellEntry {
+  job: ShellJob;
+  child?: ChildProcess;
+  pattern?: RegExp;
+  partial: string;
+  timer?: ReturnType<typeof setTimeout>;
+  closeTimer?: ReturnType<typeof setTimeout>;
+  finished?: boolean;
+}
+
 /** Long-running shell commands with bounded output and optional pattern watches. */
 export class ShellManager {
-  private jobs = new Map<string, { job: ShellJob; child?: ChildProcess; pattern?: RegExp; partial: string; timer?: ReturnType<typeof setTimeout> }>();
+  private jobs = new Map<string, ShellEntry>();
   private next = 1;
+  private pending = new Map<string, ShellEvent>();
+  private listeners = new Set<() => void>();
+  private disposed = false;
   private lineChars = new Map<string, number>();
   private readonly onEvent: (event: ShellEvent) => void;
   private readonly spawnShell: typeof spawn;
@@ -61,6 +77,44 @@ export class ShellManager {
     });
   }
   get(id: string): ShellJob | undefined { const entry = this.jobs.get(id); return entry && { ...entry.job, lines: [...entry.job.lines] }; }
+  acknowledge(ids: readonly string[]): void { for (const id of ids) this.pending.delete(id); }
+  takeNotifications(): ShellEvent[] { const events = [...this.pending.values()]; this.pending.clear(); return events; }
+  restoreNotifications(events: readonly ShellEvent[]): void {
+    for (const event of events) if (this.jobs.has(event.job.id) && !this.pending.has(event.job.id)) this.pending.set(event.job.id, event);
+  }
+  pendingNotifications(): number { return this.pending.size; }
+  verificationPending(): Array<Omit<ShellJob, "lines">> {
+    return [...this.jobs.values()].filter(entry => !entry.finished && entry.job.purpose !== "service").map(({ job }) => {
+      const { lines: _lines, ...summary } = job;
+      return summary;
+    });
+  }
+  private emitEvent(kind: ShellEvent["kind"], job: ShellJob): void {
+    if (!this.jobs.has(job.id) || this.disposed) return;
+    // Terminal state supersedes readiness; queue metadata only, not duplicated log buffers.
+    if (job.notify) this.pending.set(job.id, { kind, job: { ...job, lines: [] } });
+    this.onEvent({ kind, job: { ...job, lines: job.lines.slice(-20) } });
+  }
+  async wait(ids: readonly string[], timeoutMs = 1000, signal?: AbortSignal): Promise<boolean> {
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0 || timeoutMs > 30_000) throw new Error("waitMs must be between 0 and 30000");
+    for (const id of ids) if (!this.jobs.has(id)) throw new Error("no shell " + id);
+    if (this.disposed) throw new Error("shell session disposed");
+    if (signal?.aborted) throw signal.reason ?? new Error("wait cancelled");
+    const ready = () => ids.every(id => this.jobs.get(id)?.finished === true);
+    if (ready() || timeoutMs === 0) return ready();
+    return new Promise<boolean>((resolve, reject) => {
+      const cleanup = () => { clearTimeout(timer); this.listeners.delete(check); signal?.removeEventListener("abort", abort); };
+      const check = () => {
+        if (this.disposed || ids.some(id => !this.jobs.has(id))) { cleanup(); reject(new Error("shell session disposed or result expired")); }
+        else if (ready()) { cleanup(); resolve(true); }
+      };
+      const abort = () => { cleanup(); reject(signal?.reason ?? new Error("wait cancelled")); };
+      const timer = setTimeout(() => { cleanup(); resolve(false); }, timeoutMs);
+      this.listeners.add(check);
+      signal?.addEventListener("abort", abort, { once: true });
+      if (signal?.aborted) abort(); else check();
+    });
+  }
   running(): number {
     let count = 0;
     for (const { job } of this.jobs.values()) if (job.status === "running") count++;
@@ -68,6 +122,7 @@ export class ShellManager {
   }
 
   start(options: StartOptions): ShellJob {
+    if (this.disposed) throw new Error("shell session disposed");
     const command = options.command.trim();
     if (!command) throw new Error("command is required");
     if (this.running() >= MAX_RUNNING_SHELLS) throw new Error(`at most ${MAX_RUNNING_SHELLS} shells can run at once; kill one first`);
@@ -79,15 +134,17 @@ export class ShellManager {
     this.prune();
     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, lines: [], dropped: 0, ...(options.watch ? { watch: options.watch } : {}) };
-    const entry: { job: ShellJob; child?: ChildProcess; pattern?: RegExp; partial: string; timer?: ReturnType<typeof setTimeout> } = { job, partial: "", ...(pattern ? { pattern } : {}) };
+      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: "", ...(pattern ? { pattern } : {}) };
     this.jobs.set(id, entry);
     this.lineChars.set(id, 0);
     // 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 });
     entry.child = child;
     if (child.pid !== undefined) job.pid = child.pid;
-    const receive = (chunk: Buffer | string) => this.receive(entry, String(chunk));
+    const receive = (chunk: Buffer | string) => { if (!entry.finished) this.receive(entry, String(chunk)); };
+    child.stdout?.setEncoding?.("utf8");
+    child.stderr?.setEncoding?.("utf8");
     child.stdout?.on("data", receive);
     child.stderr?.on("data", receive);
     child.on("error", (error) => {
@@ -97,13 +154,31 @@ export class ShellManager {
       job.endedAt = Date.now();
       this.finish(entry);
     });
-    child.on("close", (code, signal) => {
+    const complete = (code: number | null, signal: NodeJS.Signals | null) => {
+      if (entry.finished) return;
       if (entry.partial) { this.push(entry, entry.partial); entry.partial = ""; }
       if (job.status === "running") job.status = "exited";
       job.exitCode = code;
       job.signal = signal;
       job.endedAt ??= Date.now();
       this.finish(entry);
+    };
+    child.once("close", complete);
+    child.once("exit", (code, signal) => {
+      if (entry.finished) return;
+      if (job.status === "running") job.status = "exited";
+      job.exitCode = code;
+      job.signal = signal;
+      job.endedAt ??= Date.now();
+      // Grandchildren may keep stdio open after the shell exits. Drain briefly, then reclaim
+      // the entire group and emit exactly one terminal event even if close never arrives.
+      entry.closeTimer = setTimeout(() => {
+        signalProcessTree(child);
+        child.stdout?.destroy?.();
+        child.stderr?.destroy?.();
+        complete(code, signal);
+      }, 250);
+      entry.closeTimer.unref();
     });
     this.onChange?.();
     return { ...job, lines: [] };
@@ -133,13 +208,22 @@ export class ShellManager {
     }
     if (entry.pattern && !job.matched && entry.pattern.test(line)) {
       job.matched = line;
-      this.onEvent({ kind: "match", job: { ...job, lines: job.lines.slice(-20) } });
+      this.emitEvent("match", job);
     }
   }
 
-  private finish(entry: { job: ShellJob; timer?: ReturnType<typeof setTimeout> }): void {
-    if (entry.timer) clearTimeout(entry.timer);
-    this.onEvent({ kind: "exit", job: { ...entry.job, lines: entry.job.lines.slice(-20) } });
+  private finish(entry: ShellEntry): void {
+    if (entry.finished) return;
+    entry.finished = true;
+    entry.job.complete = true;
+    entry.job.endedAt ??= Date.now();
+    clearTimeout(entry.timer);
+    clearTimeout(entry.closeTimer);
+    if (entry.child) signalProcessTree(entry.child);
+    entry.child?.stdout?.destroy?.();
+    entry.child?.stderr?.destroy?.();
+    this.emitEvent("exit", entry.job);
+    for (const listener of [...this.listeners]) listener();
     this.onChange?.();
   }
 
@@ -159,13 +243,13 @@ export class ShellManager {
     if (entry.job.status !== "running" || !entry.child) return false;
     entry.job.status = "killed";
     entry.job.endedAt = Date.now();
-    const signal = (name: NodeJS.Signals) => {
-      const pid = entry.child?.pid;
-      try { if (pid && process.platform !== "win32") process.kill(-pid, name); else entry.child?.kill(name); }
-      catch { entry.child?.kill(name); }
-    };
-    signal("SIGTERM");
-    entry.timer = setTimeout(() => signal("SIGKILL"), KILL_GRACE_MS);
+    signalProcessTree(entry.child, "SIGTERM");
+    entry.timer = setTimeout(() => {
+      signalProcessTree(entry.child!);
+      entry.child?.stdout?.destroy?.();
+      entry.child?.stderr?.destroy?.();
+      this.finish(entry);
+    }, KILL_GRACE_MS);
     entry.timer.unref?.();
     this.onChange?.();
     return true;
@@ -177,10 +261,14 @@ export class ShellManager {
     for (const { job } of finished.slice(0, Math.max(0, this.jobs.size - MAX_KEPT_SHELLS + 1))) {
       this.jobs.delete(job.id);
       this.lineChars.delete(job.id);
+      this.pending.delete(job.id);
     }
   }
 
   dispose(): void {
+    this.disposed = true;
+    this.pending.clear();
+    for (const listener of [...this.listeners]) listener();
     for (const id of this.jobs.keys()) { try { this.kill(id); } catch { /* already gone */ } }
     this.jobs.clear();
     this.lineChars.clear();
@@ -194,7 +282,7 @@ export const elapsed = (span: { startedAt: number; endedAt?: number }, now = Dat
   return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
 };
 export const shellState = (job: ShellMeta | ShellJob) => job.status === "running" ? "running"
-  : job.status === "exited" ? `exited ${job.exitCode ?? "?"}` : job.status === "failed" ? `failed: ${cleanText(job.error ?? "", 60)}` : "killed";
+  : job.status === "exited" ? `exited ${job.exitCode ?? "?"}${job.complete === false ? " (draining)" : ""}` : job.status === "failed" ? `failed: ${cleanText(job.error ?? "", 60)}` : "killed";
 export const describe = (job: ShellMeta | ShellJob) => `${job.id} · ${job.name} · ${shellState(job)} · ${elapsed(job)}${job.watch ? ` · watch /${job.watch}/${job.matched ? " matched" : ""}` : ""}`;
 const boundedTail = (lines: readonly string[], limit = MAX_TOOL_OUTPUT_CHARS): string => {
   let size = 0;
@@ -222,12 +310,15 @@ export function shellEventMessage(event: ShellEvent): string {
 }
 
 const Parameters = Type.Object({
-  action: Type.Unsafe<"start" | "list" | "output" | "kill">({ type: "string", enum: ["start", "list", "output", "kill"] }),
+  action: Type.Unsafe<"start" | "list" | "peek" | "wait" | "output" | "kill">({ type: "string", enum: ["start", "list", "peek", "wait", "output", "kill"] }),
   command: Type.Optional(Type.String({ description: "Shell command to run in the background (start)." })),
   name: Type.Optional(Type.String({ description: "Short label, e.g. \"dev server\"." })),
   watch: Type.Optional(Type.String({ description: "Regex; when a line matches you are woken once, e.g. \"ready on|error\"." })),
   notify: Type.Optional(Type.Boolean({ description: "Wake you when the pattern matches or the process ends (default true)." })),
-  id: Type.Optional(Type.String({ description: "Shell id for output/kill, e.g. s1." })),
+  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)." }))
 });
 
@@ -236,36 +327,49 @@ export function registerShells(pi: ExtensionAPI, shells: () => ShellManager | un
   pi.registerTool({
     name: SHELL_TOOL,
     label: "shell",
-    description: "Run long-lived commands (dev servers, watchers, long test runs) in the background. start returns immediately; you are woken when an optional watch pattern matches or the process exits. Use output to read recent lines and kill to stop it.",
+    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.",
     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: after starting, continue other work or end your turn; a message wakes you when the watch matches or the process ends. Kill shells you no longer need."
+      "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.",
+      "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."
     ],
     parameters: Parameters,
-    async execute(_id, params, _signal, _update, ctx) {
+    async execute(_id, params, signal, _update, ctx) {
       const manager = shells();
       const reply = (text: string) => ({ content: [{ type: "text" as const, text: text.slice(0, MAX_TOOL_OUTPUT_CHARS) }], details: {
-        jobs: (manager?.summaries() ?? []).map((job) => ({ id: job.id, name: job.name, status: job.status, pid: job.pid, exitCode: job.exitCode }))
+        jobs: (manager?.summaries() ?? []).map((job) => ({ id: job.id, name: job.name, status: job.status, purpose: job.purpose, complete: job.complete, pid: job.pid, exitCode: job.exitCode })),
+        pendingNotifications: manager?.pendingNotifications() ?? 0
       } });
       if (!manager) return reply("Background shells are unavailable before a Pi session starts.");
       try {
         switch (params.action) {
           case "start": {
             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.notify !== undefined ? { notify: params.notify } : {}), ...(params.purpose ? { purpose: params.purpose } : {}) });
             return reply(`Started ${describe(job)} (pid ${job.pid ?? "?"}). ${job.notify ? "You will be woken when it " + (job.watch ? "matches or " : "") + "exits." : "Notifications are off; check it with 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)"}`);
           }
           case "kill":
             if (!params.id) return reply("kill needs an id.");
             return reply(manager.kill(params.id) ? `Stopping ${params.id}.` : `${params.id} is not running.`);
+          case "wait": {
+            const ids = params.ids ?? (params.id ? [params.id] : manager.summaries().filter(job => job.purpose !== "service").map(job => job.id));
+            const completed = await manager.wait(ids, params.waitMs ?? 1000, signal);
+            const jobs = manager.summaries().filter(job => ids.includes(job.id));
+            manager.acknowledge(ids);
+            return reply((completed ? "Selected jobs completed." : "Wait timed out; jobs still pending. Do not claim they passed.") + (jobs.length ? "\n" + jobs.map(describe).join("\n") : " No finite tasks selected."));
+          }
           default: {
-            const jobs = manager.summaries();
+            const ids = params.ids ?? (params.id ? [params.id] : undefined);
+            const jobs = manager.summaries().filter(job => !ids || ids.includes(job.id));
+            if (ids?.some(id => !jobs.some(job => job.id === id))) return reply("Unknown shell id in selection.");
+            manager.acknowledge(jobs.map(job => job.id));
             return reply(jobs.length ? jobs.map(describe).join("\n") : "No background shells.");
           }
         }

package/src/subagent-tools.ts

@@ -0,0 +1,45 @@
+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"]);
+
+/** 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 {
+  if (["bash", "powershell", "jar_shell"].includes(name)) return "Sandboxed worktree subagents cannot run shell tools.";
+  const pathTools = new Set(["read", "edit", "write", "grep", "find", "ls", "multi_file_edit"]);
+  if (!pathTools.has(name)) return;
+  if (!workspacePathAllowed(root, cwd, ".")) return "Sandboxed worktree subagent working directory is outside its workspace.";
+  const input = args && typeof args === "object" ? args as Record<string, unknown> : {};
+  const validate = (value: unknown): string | undefined => {
+    if (typeof value !== "string" || !value || !workspacePathAllowed(root, cwd, value, name === "read")) {
+      return "Sandboxed worktree subagent cannot access outside its workspace or use an invalid path: " + String(value);
+    }
+  };
+  for (const key of ["path", "file_path", "cwd"]) if (input[key] !== undefined) {
+    const violation = validate(input[key]);
+    if (violation) return violation;
+  }
+  if (name === "multi_file_edit") {
+    if (!Array.isArray(input.edits) || !input.edits.length) return "multi_file_edit needs a non-empty edits array.";
+    for (const raw of input.edits) {
+      if (!raw || typeof raw !== "object") return "Invalid multi_file_edit entry.";
+      const entry = raw as Record<string, unknown>;
+      for (const key of ["path", "file_path", "cwd"]) if (entry[key] !== undefined) {
+        const violation = validate(entry[key]);
+        if (violation) return violation;
+      }
+      const violation = validate(entry.path ?? entry.file_path ?? input.path ?? input.file_path);
+      if (violation) return violation;
+    }
+  }
+}
+
+export function childToolAllowlist(value: string | undefined): Set<string> | undefined {
+  if (value === undefined) return;
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (!Array.isArray(parsed) || parsed.length > 64 || parsed.some(name => typeof name !== "string" || !name || RECURSIVE_TOOLS.has(name))) return new Set();
+    return new Set(parsed as string[]);
+  } catch { return new Set(); } // invalid capability data fails closed
+}

package/src/working.ts

@@ -41,14 +41,12 @@ export class WorkingState {
   prompt(open: boolean): void { this.waiting = open; }
   toolStart(id: string, name: string): void { this.tools.set(id, cleanText(name, 24) || "tool"); }
   toolEnd(id: string): void { this.tools.delete(id); }
-  /** `task` is the running jar_todo's active form; like Claude, it replaces the generic wording. */
-  view(animations: boolean, fg: (color: WorkingColor, text: string) => string, now = Date.now(), effort?: string, task?: string): WorkingView {
+  /** Keep pi-jar's light-inspired activity phrases; task titles belong in the task widget. */
+  view(animations: boolean, fg: (color: WorkingColor, text: string) => string, now = Date.now(), effort?: string, _task?: string): WorkingView {
     const phase = this.phase;
-    const activity = task ? cleanText(task, 60).replace(/[.…]+$/, "") : "";
     const elapsed = this.startedAt === undefined ? 0 : Math.max(0, Math.floor((now - this.startedAt) / 1000));
     const stage = STAGES.reduce<number>((index, threshold, next) => elapsed >= threshold ? next : index, 0);
-    const word = activity && (phase === "tool" || phase === "generating") ? activity + "…"
-      : phase === "tool" ? `Tracing light through ${[...this.tools.values()][0] ?? "tool"}…`
+    const word = phase === "tool" ? `Tracing light through ${[...this.tools.values()][0] ?? "tool"}…`
       : phase === "generating" ? PROGRESSION[Math.max(0, stage)]
       : phase === "waiting" ? "Holding the lantern for your answer…" : undefined;
     const color: WorkingColor = phase === "tool" ? "warning" : phase === "waiting" ? "muted" : "accent";