@bermudi/pi-delegate 0.1.0 → 0.1.2

package/dispatch.ts

@@ -10,11 +10,19 @@ import {
   notifyWaiters,
 } from "./tickets.ts";
 import { getConcurrencyLimit, getMaxAsyncTickets } from "./config.ts";
+import { getCurrentLeafId } from "./leaf.ts";
 import { getModelKey, mapConcurrentByModel } from "./concurrency.ts";
 import { sumUsage } from "./usage.ts";
 import { runResolvedTask, updateProgressFromRun } from "./lifecycle.ts";
-import { fmtDuration, formatCompletedTask, trunc } from "./format.ts";
+import {
+  fmtDuration,
+  formatCompletedTask,
+  trunc,
+  findTouchedOverlaps,
+  formatTouchedOverlapWarning,
+} from "./format.ts";
 import { validateDelegateOperation } from "./schema.ts";
+import { notifyCrossLeafDelivery, syncDelegateStatus } from "./status.ts";
 import { validateTasks, resolveTasks } from "./task-resolution.ts";
 import type {
   AgentConfig,
@@ -23,6 +31,7 @@ import type {
   DelegateDetails,
   DelegateToolCtx,
   DelegateToolResult,
+  ParentAgentDefaults,
   ResolvedTask,
   TaskDef,
   TaskProgress,
@@ -55,9 +64,10 @@ export function validateDelegateOperationResult(
 /** Build the initial per-task progress rows from resolved tasks. */
 export function initProgress(resolved: ResolvedTask[]): TaskProgress[] {
   return resolved.map((t, i) => ({
+    id: t.id,
     index: i,
     agent: t.agentName,
-    task: trunc(t.prompt || t.action || "", 50),
+    task: trunc(t.prompt || t.sessionAction || "", 50),
     status: "pending" as const,
     durationMs: 0,
     tokens: 0,
@@ -123,6 +133,7 @@ export interface DelegateDispatchInput {
   ctx: DelegateToolCtx;
   agents: Map<string, AgentConfig>;
   parentModelId: string | undefined;
+  parentDefaults: ParentAgentDefaults;
   signal: AbortSignal | undefined;
   onUpdate: AgentToolUpdateCallback<DelegateDetails> | undefined;
 }
@@ -131,13 +142,22 @@ export interface DelegateDispatchInput {
 export async function dispatchDelegate(
   input: DelegateDispatchInput,
 ): Promise<DelegateToolResult> {
-  const { pi, params, ctx, agents, parentModelId, signal, onUpdate } = input;
+  const {
+    pi,
+    params,
+    ctx,
+    agents,
+    parentModelId,
+    parentDefaults,
+    signal,
+    onUpdate,
+  } = input;
   const tasks = params.tasks ?? [];
 
   const validationError = validateTasks(tasks, agents, parentModelId);
   if (validationError) return validationError;
 
-  const resolved = resolveTasks(tasks, ctx, agents);
+  const resolved = resolveTasks(tasks, ctx, agents, parentDefaults);
   const progress = initProgress(resolved);
   const fire = makeFireUpdater(
     onUpdate,
@@ -170,6 +190,15 @@ export async function dispatchDelegate(
   });
 }
 
+/** Deliver a settled ticket and, when leaf affinity downgraded delivery to a
+ *  non-waking `nextTurn` message, tell the human — otherwise the completion is
+ *  silent apart from the footer clearing. */
+function finishTicketDelivery(pi: ExtensionAPI, ticket: AsyncTicket): void {
+  if (deliverTicketResults(pi, ticket) === "deferred") {
+    notifyCrossLeafDelivery(ticket);
+  }
+}
+
 /** Fire-and-forget background execution. Registers an `AsyncTicket`, kicks off
  *  the concurrent run, and returns the ticket acknowledgment immediately.
  *  Results are delivered via `deliverTicketResults` when all tasks settle. */
@@ -204,8 +233,15 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
     progress: [...progress],
     controller,
     parentModelId,
+    // Leaf affinity for delivery: a ticket that outlives a /tree navigation
+    // must not wake the agent on the branch the user moved to (issue #30).
+    spawnLeafId: getCurrentLeafId(),
   };
   ticketRegistry.set(ticketId, ticket);
+  // Footer visibility for the new background work (see status.ts). Uses the
+  // ctx cached from the dispatch path in extension.ts — DelegateToolCtx is
+  // the intentionally narrowed surface and does not carry `ui`.
+  syncDelegateStatus();
 
   // Capture values for the closure — do NOT use `signal` from execute()
   // The parent turn's signal dies when execute() returns.
@@ -221,9 +257,13 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
     onProgress: (p, u) => {
       updateProgressFromRun(p, u);
       notifyWaiters(ticket);
+      // Live subagent counts in the footer. Deduped by text, so only
+      // running/pending count transitions trigger a render.
+      syncDelegateStatus();
     },
     onStatusChange: () => {
       notifyWaiters(ticket);
+      syncDelegateStatus();
     },
   };
 
@@ -243,6 +283,12 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
     ticketSignal,
   )
     .then(() => {
+      // A ticket that is already terminally "cancelled" at this point was
+      // finalized by cancelTicketForShutdown (user cancels pass through
+      // "cancelling" first): the extension runtime is being torn down, the
+      // captured `pi` is stale or about to be, and a follow-up message has
+      // no live session to land in. Skip delivery entirely.
+      if (ticket.status === "cancelled") return;
       // All tasks settled — determine final ticket status.
       // Use progress (set by runResolvedTask) for settled-ness so the
       // status reflects work completion, not just result-array density.
@@ -262,10 +308,13 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
         ticket.completedAt = Date.now();
         syncTicketBusyIndex(ticket);
       }
-      deliverTicketResults(pi, ticket);
+      syncDelegateStatus();
+      finishTicketDelivery(pi, ticket);
     })
     .catch((err) => {
-      // Defense-in-depth — should not happen if individual tasks catch properly
+      // Defense-in-depth — should not happen if individual tasks catch properly.
+      // Same shutdown guard as the .then path above.
+      if (ticket.status === "cancelled") return;
       if (ticket.status === "cancelling") {
         ticket.status = "cancelled";
       } else if (ticket.status === "running") {
@@ -274,7 +323,8 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
       ticket.error = err instanceof Error ? err.message : String(err);
       ticket.completedAt = Date.now();
       syncTicketBusyIndex(ticket);
-      deliverTicketResults(pi, ticket);
+      syncDelegateStatus();
+      finishTicketDelivery(pi, ticket);
     });
 
   return {
@@ -286,8 +336,8 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
           `${resolved.length} task(s) dispatched · ${runningCount + 1}/${getMaxAsyncTickets()} async slots in use`,
           "",
           "Completed task results are available via poll. Final results delivered automatically when all tasks complete.",
-          `Check progress: delegate({ action: "poll", ticket: "${ticketId}" }) — avoid polling in a tight loop`,
-          `Cancel if needed: delegate({ action: "cancel", ticket: "${ticketId}", force: true }) — first call without force is a preview`,
+          `Check progress: delegate({ ticketAction: "poll", ticket: "${ticketId}" }) — avoid polling in a tight loop`,
+          `Cancel if needed: delegate({ ticketAction: "cancel", ticket: "${ticketId}", force: true }) — first call without force is a preview`,
         ].join("\n"),
       },
     ],
@@ -346,6 +396,11 @@ export async function dispatchSync(
     parts.push(...formatCompletedTask(t, r));
   }
 
+  const overlapWarning = formatTouchedOverlapWarning(
+    findTouchedOverlaps(finalResults),
+  );
+  if (overlapWarning) parts.push("", overlapWarning);
+
   return {
     content: [{ type: "text", text: parts.join("\n\n") }],
     details: {
@@ -353,6 +408,7 @@ export async function dispatchSync(
       results: finalResults,
       progress,
       parentModel: parentModelId,
+      overlapWarning: overlapWarning || undefined,
     },
     // Aggregate subagent spend so Pi folds it into the parent's
     // session/footer totals. Sync dispatch only — async results arrive via a

package/extension.ts

@@ -18,7 +18,18 @@ import {
 } from "./dispatch.ts";
 import { renderDelegateCall, renderDelegateResult } from "./render-result.ts";
 import { hostCompatError } from "./host-compat.ts";
+import { invalidateHostDepsCache } from "./host.ts";
+import { recordTreeNavigation, resetLeafTracking } from "./leaf.ts";
 import { closeAllPooledAgents } from "./pool.ts";
+import {
+  activeTicketSummary,
+  clearDelegateStatusContext,
+  describeActiveTickets,
+  guardSessionReplacement,
+  guardTreeNavigation,
+  notifyActiveTicketsOnSettled,
+  syncDelegateStatus,
+} from "./status.ts";
 import type { DelegateArguments } from "./types.ts";
 
 /** Register the delegate tool and clean up its parent-session resources. */
@@ -27,7 +38,7 @@ export default function delegateExtension(pi: ExtensionAPI): void {
     name: "delegate",
     label: "Delegate to Subagents",
     description:
-      "Run parallel subagents via tasks:[{prompt}]. Sync returns results; async returns a ticket.",
+      "Run parallel subagents via tasks:[{prompt}]. Sync returns results; async=ticket. tasks:[]=full manual.",
     parameters: delegateArgumentsSchema,
     // Runs before schema validation — recovers stringified `tasks` arrays
     // (a common model mistake that would otherwise be rejected upstream).
@@ -49,17 +60,21 @@ export default function delegateExtension(pi: ExtensionAPI): void {
       if (operationResult) return operationResult;
 
       // ── Poll action ───────────────────────────────────────────────────
-      if (params.action === "poll") {
+      if (params.ticketAction === "poll") {
         return handlePoll(params, ctx);
       }
 
       // ── Cancel action ─────────────────────────────────────────────────
-      if (params.action === "cancel") {
-        return handleCancel(params);
+      if (params.ticketAction === "cancel") {
+        const result = handleCancel(params);
+        // A forced cancel flips the ticket to "cancelling" — keep the
+        // footer status in step (deduped; the preview path is a no-op).
+        syncDelegateStatus(ctx);
+        return result;
       }
 
       // ── Wait action ────────────────────────────────────────────────────
-      if (params.action === "wait") {
+      if (params.ticketAction === "wait") {
         return handleWait(params, signal, onUpdate, ctx);
       }
 
@@ -83,12 +98,26 @@ export default function delegateExtension(pi: ExtensionAPI): void {
         };
       }
 
+      // Cache the full ExtensionContext for the footer-status module before
+      // dispatch narrows it to DelegateToolCtx (which has no `ui`). The
+      // status push itself is a deduped no-op here; dispatchAsync re-syncs
+      // after registering its ticket.
+      syncDelegateStatus(ctx);
+
+      // Keep expensive host deps shared within this dispatch, not indefinitely
+      // across dispatches: edits to auth/models/settings/context files must be
+      // visible without restarting Pi.
+      invalidateHostDepsCache();
       return dispatchDelegate({
         pi,
         params,
         ctx,
         agents,
         parentModelId,
+        parentDefaults: {
+          thinking: pi.getThinkingLevel(),
+          tools: pi.getActiveTools(),
+        },
         signal,
         onUpdate,
       });
@@ -98,11 +127,62 @@ export default function delegateExtension(pi: ExtensionAPI): void {
     renderResult: renderDelegateResult,
   });
 
+  // ── Background-work visibility (see status.ts) ──────────────────────────
+  // The turn settling with live tickets is the "looks idle but isn't" moment:
+  // warn once per ticket. The footer status carries it from there.
+  pi.on("agent_settled", (_event, ctx) => {
+    notifyActiveTicketsOnSettled(ctx);
+  });
+
+  // Session replacements are cancellable — confirm before killing live work.
+  pi.on("session_before_switch", (_event, ctx) =>
+    guardSessionReplacement(ctx, "switch"),
+  );
+  pi.on("session_before_fork", (_event, ctx) =>
+    guardSessionReplacement(ctx, "fork"),
+  );
+
+  // /tree navigation stays inside the same session: nothing is torn down and
+  // live tickets keep running, but their results would land on the branch the
+  // user moves to. Ask first, and record the new leaf either way so delivery
+  // can detect the mismatch (issue #30). `session_tree` also fires for
+  // extension-driven ctx.navigateTree, which never reaches the guard.
+  pi.on("session_before_tree", (_event, ctx) => guardTreeNavigation(ctx));
+  pi.on("session_tree", (event, ctx) => {
+    recordTreeNavigation(event.newLeafId);
+    syncDelegateStatus(ctx);
+  });
+
   // ── Session shutdown: abort tickets and dispose live pooled sessions ──
-  pi.on("session_shutdown", async () => {
+  pi.on("session_shutdown", async (event, ctx) => {
+    // Quit and /reload kill background work with no cancellable hook, so
+    // leave a trace. For quit the TUI is already stopped — stderr lands in
+    // the scrollback. For reload the TUI survives — warn in place. Switch
+    // and fork already passed the confirm guard above.
+    const active = activeTicketSummary();
+    if (active.tickets.length) {
+      if (event.reason === "quit") {
+        console.error(
+          `[delegate] pi exited with ${describeActiveTickets(active)} — aborted.`,
+        );
+      } else if (event.reason === "reload") {
+        ctx.ui.notify(
+          `[delegate] reload aborted ${describeActiveTickets(active)}`,
+          "warning",
+        );
+      }
+    }
     for (const ticket of ticketRegistry.values()) {
       cancelTicketForShutdown(ticket);
     }
+    syncDelegateStatus(ctx);
+    // The runtime is invalidated right after this handler returns; aborted
+    // tickets keep unwinding asynchronously and must find no cached ctx (or
+    // captured pi) to touch. See the "cancelled"-at-entry guard in dispatch.
+    clearDelegateStatusContext();
+    // A replacement session starts on its own leaf; stale tracking would make
+    // every ticket look cross-leaf (or, worse, look same-leaf by accident).
+    resetLeafTracking();
     // Do NOT clear the ticket registry here — completed tickets are retained
     // until their TTL cleanup. Pooled AgentSessions, however, own listeners
     // and must be disposed before the parent session exits.

package/file-tracking.ts

@@ -2,9 +2,19 @@ import { execFile } from "node:child_process";
 import * as path from "node:path";
 import type { ToolActivity } from "./types.ts";
 
-/** Return absolute paths reported as changed by Git in the task cwd.
- * Git failures degrade to an empty set because file tracking is observational. */
-export async function getGitChangedFiles(cwd: string): Promise<Set<string>> {
+/**
+ * Return absolute paths reported as changed by Git in the task cwd.
+ *
+ * Touched-file tracking is best-effort, not authoritative. On success this
+ * returns the set of changed paths (possibly empty for a clean repo). On
+ * failure (non-git directory, git unavailable, timeout) it returns `undefined`
+ * so callers can tell "git failed" from "clean repo". A failed baseline
+ * suppresses git-based attribution in the runner; only explicit edit/write tool
+ * activity is captured by {@link extractTouchedFromActivities}.
+ */
+export async function getGitChangedFiles(
+  cwd: string,
+): Promise<Set<string> | undefined> {
   try {
     const runGit = (args: string[]) =>
       new Promise<string>((resolve, reject) => {
@@ -37,11 +47,22 @@ export async function getGitChangedFiles(cwd: string): Promise<Set<string>> {
     }
     return files;
   } catch {
-    return new Set();
+    return undefined;
   }
 }
 
-/** Extract file paths mutated by edit/write from the activity log. */
+/**
+ * Extract file paths from explicit edit/write tool calls in the activity log.
+ *
+ * This is the reliable, activity-based contribution to touched-file tracking.
+ * Only completed, successful tool calls are counted: an activity must have a
+ * terminal `result` and `result.isError` must be false. Interrupted or in-flight
+ * calls (no `result`) and failed calls (`result.isError` true) are skipped,
+ * because they did not actually mutate the file. bash mutations are NOT captured
+ * here; they are only captured by git diff when the task cwd is inside a git
+ * repo with git available. The combined touchedFiles list is therefore a lower
+ * bound: absence does not mean a file was unchanged.
+ */
 export function extractTouchedFromActivities(
   activities: ToolActivity[],
   cwd: string,
@@ -49,6 +70,7 @@ export function extractTouchedFromActivities(
   const files = new Set<string>();
   for (const a of activities) {
     if (a.name !== "edit" && a.name !== "write") continue;
+    if (!a.result || a.result.isError) continue;
     const raw = a.args?.path ?? a.args?.file_path ?? a.args?.filePath;
     if (typeof raw !== "string" || !raw) continue;
     files.add(path.resolve(cwd, raw));

package/format.ts

@@ -185,6 +185,11 @@ export function trunc(s: string, n: number): string {
   return s.length <= n ? s : s.slice(0, n - 1) + "…";
 }
 
+/** Render an optional task `id` in a compact, visually distinct form. */
+export function formatTaskId(id: string | undefined): string {
+  return id ? ` #${id}` : "";
+}
+
 /**
  * Extract a single-line preview of agent output for collapsed final display.
  *
@@ -340,7 +345,7 @@ function isResumableSessionFile(sessionFile: string): boolean {
  * path that didn't exist on disk.
  *
  * Emits:
- *   [FAILED|ABORTED: <error> · session: <shortpath> · touched: <files>]
+ *   [FAILED|ABORTED: <error> · session: <shortpath> · touched (best-effort): <files>]
  *   <partial output, when available>
  *   → To retry: delegate({ tasks: [{ resumeFrom: "<path>", prompt: "continue" }] })
  *
@@ -351,12 +356,12 @@ function isResumableSessionFile(sessionFile: string): boolean {
  */
 export function formatFailedTask(r: TaskResult, cwd?: string): string[] {
   const parts: string[] = [];
-  const isAbort = /abort/i.test(r.error ?? "");
+  const isAbort = r.error === "Aborted";
   // Empty string is falsy but not nullish — `||` covers both undefined and "".
   const failParts = [r.error || "unknown error"];
   if (r.sessionFile) failParts.push(`session: ${shortenPath(r.sessionFile)}`);
   const touched = cwd ? relativeTouchedSummary(r.touchedFiles, cwd) : null;
-  if (touched) failParts.push(`touched: ${touched}`);
+  if (touched) failParts.push(`touched (best-effort): ${touched}`);
   parts.push(`[${isAbort ? "ABORTED" : "FAILED"}: ${failParts.join(" · ")}]`);
 
   // Surface partial assistant output even when the task did not complete.
@@ -398,7 +403,7 @@ export function formatFailedTask(r: TaskResult, cwd?: string): string[] {
  * Emits:
  *   === <agent>: <truncated prompt> ===
  *   [WARNING: <w>]  (per warning, if any)
- *   [FAILED: ...] / [OK | <duration> | <tokens> tokens · <sessionFile> · touched: <files>]
+ *   [FAILED: ...] / [OK | <duration> | <tokens> tokens · <sessionFile> · touched (best-effort): <files>]
  *
  *   <output>  (success body only)
  *
@@ -410,10 +415,10 @@ export function formatCompletedTask(
   result: TaskResult,
 ): string[] {
   const parts: string[] = [];
-  // `|| task.action` covers action-only tasks (close/list/...) where prompt is
+  // `|| task.sessionAction` covers action-only tasks (close/list/...) where prompt is
   // empty. Async prompt tasks always set prompt, so this is a no-op there.
   parts.push(
-    `=== ${result.agent}: ${trunc(task.prompt || task.action || "", 80)} ===`,
+    `=== ${result.agent}${formatTaskId(result.id ?? task.id)}: ${trunc(task.prompt || task.sessionAction || "", 80)} ===`,
   );
   if (task.warnings?.length) {
     for (const w of task.warnings) parts.push(`[WARNING: ${w}]`);
@@ -426,7 +431,7 @@ export function formatCompletedTask(
     ];
     if (result.sessionFile) meta.push(shortenPath(result.sessionFile));
     const touched = relativeTouchedSummary(result.touchedFiles, task.cwd);
-    if (touched) meta.push(`touched: ${touched}`);
+    if (touched) meta.push(`touched (best-effort): ${touched}`);
     parts.push(
       `[${meta.join(" · ")}]\n\n${renderOutputForLLM(result.output, result.agent)}`,
     );
@@ -504,3 +509,37 @@ export function relativeTouchedSummary(
     .filter((f) => f && !f.startsWith(".."));
   return rel.length ? rel.join(", ") : null;
 }
+
+/** Find absolute paths directly attributed to more than one task result.
+ *
+ *  Overlap is computed from {@link TaskResult.attributedFiles} (edit/write
+ *  tool calls), not from {@link TaskResult.touchedFiles}, so concurrent tasks
+ *  in the same repository do not fabricate false conflicts from shared
+ *  repository-wide git snapshots. */
+export function findTouchedOverlaps(
+  results: readonly { attributedFiles?: string[] }[],
+): string[] {
+  const counts = new Map<string, number>();
+  for (const r of results) {
+    for (const f of r.attributedFiles ?? []) {
+      counts.set(f, (counts.get(f) ?? 0) + 1);
+    }
+  }
+  return [...counts.entries()]
+    .filter(([, count]) => count > 1)
+    .map(([file]) => file)
+    .sort();
+}
+
+/**
+ * Format a post-dispatch overlap warning, or null when there is no overlap.
+ *
+ * The warning is deliberately conservative: it only reports paths that two or
+ * more tasks claimed to touch. It does NOT claim that disjoint touchedFiles
+ * mean there was no conflict, and it does NOT claim filesystem isolation or
+ * rollback.
+ */
+export function formatTouchedOverlapWarning(overlaps: string[]): string | null {
+  if (!overlaps.length) return null;
+  return `WARNING: These tasks reported touching the same file(s): ${overlaps.join(", ")}. Delegate does not isolate or serialize file access and does not roll back completed writes.`;
+}

package/host-compat.ts

@@ -8,16 +8,27 @@ import type { DelegateToolResult } from "./types.ts";
  * Keep this list in sync with the actual import sites (host.ts, sessions.ts,
  * lifecycle.ts, agents.ts).
  */
-const REQUIRED_SYMBOLS = [
-  "ModelRuntime",
-  "SettingsManager",
-  "SessionManager",
-  "DefaultResourceLoader",
-  "DefaultPackageManager",
-  "createAgentSession",
-  "getAgentDir",
-  "parseFrontmatter",
-] as const;
+type ExportCheck = {
+  name: string;
+  requiredMember?: string;
+};
+
+/**
+ * Host symbols actually dereferenced by delegate. Static members are listed by
+ * `<symbol>.<member>` so we fail fast when a constructor is present but no longer
+ * exposes the required factory methods.
+ */
+const REQUIRED_EXPORTS: ExportCheck[] = [
+  { name: "ModelRuntime", requiredMember: "create" },
+  { name: "SettingsManager", requiredMember: "create" },
+  { name: "SessionManager", requiredMember: "create" },
+  { name: "SessionManager", requiredMember: "open" },
+  { name: "DefaultResourceLoader" },
+  { name: "DefaultPackageManager" },
+  { name: "createAgentSession" },
+  { name: "getAgentDir" },
+  { name: "parseFrontmatter" },
+];
 
 /**
  * Build a tool result describing any required symbols missing from a pi
@@ -27,9 +38,33 @@ const REQUIRED_SYMBOLS = [
 export function hostCompatResult(
   ns: Record<string, unknown>,
 ): DelegateToolResult | null {
-  const missing = REQUIRED_SYMBOLS.filter((name) => ns[name] === undefined);
+  const missing: string[] = [];
+  for (const entry of REQUIRED_EXPORTS) {
+    const value = ns[entry.name];
+    if (value === undefined) {
+      missing.push(`'${entry.name}'`);
+      continue;
+    }
+
+    if (typeof value !== "function") {
+      missing.push(`'${entry.name}'`);
+      continue;
+    }
+
+    if (entry.requiredMember) {
+      const symbolValue = value as unknown as { [key: string]: unknown };
+      if (!(entry.requiredMember in symbolValue)) {
+        missing.push(`'${entry.name}.${entry.requiredMember}'`);
+        continue;
+      }
+      if (typeof symbolValue[entry.requiredMember] !== "function") {
+        missing.push(`'${entry.name}.${entry.requiredMember}'`);
+      }
+    }
+  }
+
   if (missing.length === 0) return null;
-  const listed = missing.map((m) => `'${m}'`).join(", ");
+  const listed = missing.join(", ");
   return {
     content: [
       {