pi-jar 0.1.5 → 0.1.7

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/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";