@bermudi/pi-delegate 0.1.0 → 0.1.2

package/tickets.ts

@@ -11,22 +11,30 @@ import {
   fmtDuration,
   fmtTokens,
   formatCompletedTask,
+  formatTaskId,
   shortenPath,
   trunc,
   getActivityAge,
   formatActivityLabel,
   taskMetaBase,
   relativeTouchedSummary,
+  findTouchedOverlaps,
+  formatTouchedOverlapWarning,
 } from "./format.ts";
+import { isCrossLeafTicket } from "./leaf.ts";
 import { renderOutputForPoll } from "./spill.ts";
 import { scheduleDeadline } from "./timer.ts";
+import { emptyUsage } from "./usage.ts";
 import type {
   AsyncTicket,
   DelegateDetails,
+  ResolvedTask,
   TaskResult,
   TicketWaiter,
 } from "./types.ts";
 
+const PENDING_RESULT_ERROR = "PENDING — result not available";
+
 const busyTicketIdsBySession = new Map<string, Set<string>>();
 const busySessionsByTicket = new Map<string, Set<string>>();
 
@@ -119,6 +127,17 @@ export function cancelTicketForShutdown(ticket: AsyncTicket): void {
   settleTicketWaiters(ticket);
 }
 
+/** Request cooperative cancellation of a live ticket: abort the workers and
+ *  move to "cancelling" so they settle and report what actually ran. Unlike
+ *  `cancelTicketForShutdown` this leaves the ticket deliverable — the runtime
+ *  is still alive, so the final "cancelled" result still reaches the user. */
+export function requestTicketCancel(ticket: AsyncTicket): void {
+  if (ticket.status !== "running") return;
+  ticket.controller.abort();
+  ticket.status = "cancelling";
+  syncTicketBusyIndex(ticket);
+}
+
 /** Check if any running async ticket holds a given sessionId.
  *  Backed by an O(1) map updated when tickets start/complete. */
 export function isSessionBusy(sessionId: string): string | null {
@@ -187,13 +206,23 @@ export function formatCompletedTicket(
     const r = ticket.results[i];
     const t = ticket.resolved[i]!;
     if (!r) {
-      parts.push(`=== ${t.agentName}: ${trunc(t.prompt || "", 80)} ===`);
+      parts.push(
+        `=== ${t.agentName}${formatTaskId(t.id)}: ${trunc(t.prompt || "", 80)} ===`,
+      );
       parts.push(`[${pendingLabelFor(i)}]`);
       continue;
     }
     parts.push(...formatCompletedTask(t, r));
   }
 
+  const completedResults = ticket.results.filter(
+    (r): r is TaskResult => r !== undefined && "touchedFiles" in r,
+  );
+  const overlapWarning = formatTouchedOverlapWarning(
+    findTouchedOverlaps(completedResults),
+  );
+  if (overlapWarning) parts.push("", overlapWarning);
+
   if (ticket.status === "cancelled") {
     parts.push(
       "",
@@ -206,7 +235,11 @@ export function formatCompletedTicket(
     details: {
       tasks: ticket.tasks,
       results: [...ticket.results].map(
-        (r, index) => r ?? { error: pendingLabelFor(index) },
+        (r, index) =>
+          r ?? {
+            ...pendingResultPlaceholder(ticket.resolved[index]),
+            error: pendingLabelFor(index),
+          },
       ),
       progress: [...ticket.progress],
       parentModel: ticket.parentModelId,
@@ -214,22 +247,49 @@ export function formatCompletedTicket(
       // the human sees which ticket they polled, even in the rich tree path.
       ticketId: ticket.id,
       status: ticket.status,
+      overlapWarning: overlapWarning || undefined,
     },
   };
 }
 
 // ── Waiter helpers ─────────────────────────────────────────────────────────
 
+function pendingResultPlaceholder(task: ResolvedTask | undefined): TaskResult {
+  return {
+    id: task?.id,
+    agent: task?.agentName ?? "unknown",
+    output: "",
+    durationMs: 0,
+    tokens: 0,
+    usage: emptyUsage(),
+    touchedFiles: [],
+    attributedFiles: [],
+    // Machine-visible and human-readable marker so structured consumers do not
+    // mistake a pending placeholder for a successful result.
+    error: PENDING_RESULT_ERROR,
+  };
+}
+
 function buildWaitDetails(ticket: AsyncTicket): DelegateDetails {
+  const completedResults = ticket.results.filter(
+    (r): r is TaskResult => r !== undefined && "touchedFiles" in r,
+  );
+  const overlapWarning = formatTouchedOverlapWarning(
+    findTouchedOverlaps(completedResults),
+  );
+  const results: TaskResult[] = [];
+  for (let i = 0; i < ticket.resolved.length; i++) {
+    const r = ticket.results[i];
+    results.push(r ?? pendingResultPlaceholder(ticket.resolved[i]));
+  }
   return {
     tasks: ticket.tasks,
-    results: ticket.results.map(
-      (r) => r ?? { error: "PENDING — result not available" },
-    ),
+    results,
     progress: [...ticket.progress],
     parentModel: ticket.parentModelId,
     ticketId: ticket.id,
     status: ticket.status,
+    overlapWarning: overlapWarning || undefined,
   };
 }
 
@@ -251,9 +311,13 @@ function buildWaitRunningUpdate(
   if (failed > 0) parts.push(`${failed} failed`);
   if (pending > 0) parts.push(`${pending} queued`);
 
+  const details = buildWaitDetails(ticket);
+  const text =
+    parts.join(" · ") +
+    (details.overlapWarning ? `\n\n${details.overlapWarning}` : "");
   return {
-    content: [{ type: "text", text: parts.join(" · ") }],
-    details: buildWaitDetails(ticket),
+    content: [{ type: "text", text }],
+    details,
   };
 }
 
@@ -261,28 +325,26 @@ function buildWaitTimeoutResult(
   ticket: AsyncTicket,
   timeoutMs: number,
 ): AgentToolResult<DelegateDetails> {
+  const details = buildWaitDetails(ticket);
+  const base = `Ticket ${ticket.id} still ${ticket.status} after ${fmtDuration(timeoutMs)} · wait timed out (ticket continues in background)`;
+  const text =
+    base + (details.overlapWarning ? `\n\n${details.overlapWarning}` : "");
   return {
-    content: [
-      {
-        type: "text",
-        text: `Ticket ${ticket.id} still ${ticket.status} after ${fmtDuration(timeoutMs)} · wait timed out (ticket continues in background)`,
-      },
-    ],
-    details: buildWaitDetails(ticket),
+    content: [{ type: "text", text }],
+    details,
   };
 }
 
 function buildWaitAbortResult(
   ticket: AsyncTicket,
 ): AgentToolResult<DelegateDetails> {
+  const details = buildWaitDetails(ticket);
+  const base = `Wait for ticket ${ticket.id} aborted · ticket continues ${ticket.status} in the background`;
+  const text =
+    base + (details.overlapWarning ? `\n\n${details.overlapWarning}` : "");
   return {
-    content: [
-      {
-        type: "text",
-        text: `Wait for ticket ${ticket.id} aborted · ticket continues ${ticket.status} in the background`,
-      },
-    ],
-    details: buildWaitDetails(ticket),
+    content: [{ type: "text", text }],
+    details,
   };
 }
 
@@ -366,23 +428,57 @@ export function notifyWaiters(ticket: AsyncTicket): void {
       continue;
     }
     active.push(w);
-    if (w.onUpdate) w.onUpdate(buildWaitRunningUpdate(ticket));
+    if (w.onUpdate) {
+      try {
+        w.onUpdate(buildWaitRunningUpdate(ticket));
+      } catch (error) {
+        // Progress delivery is an observer boundary. A host callback must not
+        // be able to fail the worker that reported the update or reject the
+        // wait promise; keep the waiter attached for the terminal result and
+        // leave the failure visible for diagnosis.
+        console.error(
+          `[delegate] wait progress callback for ticket '${ticket.id}' threw; continuing`,
+          error,
+        );
+      }
+    }
   }
   ticket.waiters = active.length ? active : undefined;
 }
 
+/** Prefix for a result whose spawn leaf is no longer the active one. The model
+ *  would otherwise read a foreign branch's work as current-turn context. */
+const CROSS_LEAF_NOTICE =
+  "NOTE: this async delegate ticket was spawned on a different branch of the " +
+  "session tree; the conversation has since navigated elsewhere (/tree). These " +
+  "results may not relate to the current line of work — verify relevance before " +
+  "acting on them.";
+
+/** How a completed ticket was handed back. `deferred` means the result was
+ *  queued without waking the agent because the session navigated away from
+ *  the spawn leaf; callers surface that to the human (see status.ts). */
+export type TicketDelivery = "none" | "waiters" | "steer" | "deferred";
+
 /** Push results into parent session via sendMessage when background ticket completes.
  *  If there are active blocking waiters, resolve them directly and suppress the
- *  automatic follow-up so completion is delivered exactly once. */
+ *  automatic follow-up so completion is delivered exactly once.
+ *
+ *  Delivery mode depends on leaf affinity (see leaf.ts). Same leaf: `steer` +
+ *  `triggerTurn`, the agent picks the result up immediately. Different leaf:
+ *  `nextTurn`, which explicitly "does not interrupt or trigger anything" — the
+ *  result waits for the human's next prompt instead of waking the agent on a
+ *  branch the task was never part of. The ticket stays pollable either way. */
 export function deliverTicketResults(
   pi: ExtensionAPI,
   ticket: AsyncTicket,
-): void {
-  if (!ticket.completedAt) return;
+): TicketDelivery {
+  if (!ticket.completedAt) return "none";
 
   // Resolve active blocking waiters directly. Stale/aborted waiters are
   // cleaned but not resolved here (their abort handlers already returned).
-  if (settleTicketWaiters(ticket)) return;
+  // A waiter is a tool call on the live leaf by construction, so leaf
+  // affinity does not apply to it.
+  if (settleTicketWaiters(ticket)) return "waiters";
 
   const formatted = formatCompletedTicket(ticket);
   const text = formatted.content
@@ -393,10 +489,12 @@ export function deliverTicketResults(
     .map((c) => c.text)
     .join("\n");
 
+  const crossLeaf = isCrossLeafTicket(ticket);
+
   pi.sendMessage(
     {
       customType: "async_delegate_result",
-      content: text,
+      content: crossLeaf ? `${CROSS_LEAF_NOTICE}\n\n${text}` : text,
       display: true,
       details: {
         ...formatted.details,
@@ -404,11 +502,11 @@ export function deliverTicketResults(
         status: ticket.status,
       },
     },
-    {
-      deliverAs: "steer",
-      triggerTurn: true,
-    },
+    crossLeaf
+      ? { deliverAs: "nextTurn" }
+      : { deliverAs: "steer", triggerTurn: true },
   );
+  return crossLeaf ? "deferred" : "steer";
 }
 
 /** Return a snapshot of one async ticket or the complete ticket roster. */
@@ -434,7 +532,7 @@ export function handlePoll(
               "No async tickets.",
               "",
               "To spawn a subagent: delegate({ tasks: [{ agent, prompt }] }).",
-              "For the full manual and agent list, call delegate({ tasks: [] }) with no top-level `action`.",
+              "For the full manual and agent list, call delegate({ tasks: [] }) with no top-level `ticketAction`.",
             ].join("\n"),
           },
         ],
@@ -467,9 +565,9 @@ export function handlePoll(
       // Copy-pasteable controls for running/cancelling tickets — a human can grab these
       // straight out of the TUI without retyping the ticket id.
       if (t.status === "running" || t.status === "cancelling") {
-        line += `\n     poll:   delegate({ action: "poll", ticket: "${t.id}" })`;
+        line += `\n     poll:   delegate({ ticketAction: "poll", ticket: "${t.id}" })`;
         if (t.status === "running") {
-          line += `\n     cancel: delegate({ action: "cancel", ticket: "${t.id}", force: true })`;
+          line += `\n     cancel: delegate({ ticketAction: "cancel", ticket: "${t.id}", force: true })`;
         }
       }
       return line;
@@ -537,9 +635,9 @@ export function handlePoll(
         if (r.touchedFiles.length > 0) {
           const t = ticket.resolved[i]!;
           const touched = relativeTouchedSummary(r.touchedFiles, t.cwd);
-          if (touched) meta.push(`touched: ${touched}`);
+          if (touched) meta.push(`touched (best-effort): ${touched}`);
         }
-        lines.push(`✓ ${r.agent} · ${meta.join(" · ")}`);
+        lines.push(`✓ ${r.agent}${formatTaskId(r.id)} · ${meta.join(" · ")}`);
         if (r.output && r.output !== "(no output)") {
           lines.push(renderOutputForPoll(r.output));
         }
@@ -549,10 +647,12 @@ export function handlePoll(
         if (r.touchedFiles.length > 0) {
           const t = ticket.resolved[i]!;
           const touched = relativeTouchedSummary(r.touchedFiles, t.cwd);
-          if (touched) meta.push(`touched: ${touched}`);
+          if (touched) meta.push(`touched (best-effort): ${touched}`);
         }
         const errorText = r.error ?? "unknown error";
-        lines.push(`✗ ${r.agent} · ${errorText} · ${meta.join(" · ")}`);
+        lines.push(
+          `✗ ${r.agent}${formatTaskId(r.id)} · ${errorText} · ${meta.join(" · ")}`,
+        );
         if (r.sessionFile)
           lines.push(`  session: ${shortenPath(r.sessionFile)}`);
         if (r.output && r.output !== "(no output)")
@@ -565,12 +665,19 @@ export function handlePoll(
         if (p.tokens > 0) parts.push(`${fmtTokens(p.tokens)} tokens`);
         const age = getActivityAge(p.lastActivityAt);
         if (age) parts.push(age);
-        lines.push(`⏳ ${p.agent} · ${parts.join(" · ")}`);
+        lines.push(`⏳ ${p.agent}${formatTaskId(p.id)} · ${parts.join(" · ")}`);
       } else {
-        lines.push(`○ ${p.agent} · waiting…`);
+        lines.push(`○ ${p.agent}${formatTaskId(p.id)} · waiting…`);
       }
     }
 
+    const completedForOverlap = completedResults.filter(
+      (r): r is TaskResult => r !== undefined,
+    );
+    const overlapWarning = formatTouchedOverlapWarning(
+      findTouchedOverlaps(completedForOverlap),
+    );
+
     const headerStatus =
       ticket.status === "cancelling" ? "CANCELLING" : "RUNNING";
     const headerParts: string[] = [
@@ -597,13 +704,13 @@ export function handlePoll(
       content: [
         {
           type: "text",
-          text: `${header}\n${lines.join("\n")}${guidance ? `\n\n${guidance}` : ""}`,
+          text: `${header}\n${lines.join("\n")}${guidance ? `\n\n${guidance}` : ""}${overlapWarning ? `\n\n${overlapWarning}` : ""}`,
         },
       ],
       details: {
         tasks: ticket.tasks,
         results: completedResults.map(
-          (r) => r ?? { error: "PENDING — result not available" },
+          (r, i) => r ?? pendingResultPlaceholder(ticket.resolved[i]),
         ),
         progress: [...ticket.progress],
         parentModel: ticket.parentModelId,
@@ -611,6 +718,7 @@ export function handlePoll(
         // (friction #2). The LLM-facing content still names the ticket id too.
         ticketId: ticket.id,
         status: ticket.status,
+        overlapWarning: overlapWarning || undefined,
       },
     };
   }
@@ -633,9 +741,9 @@ function buildCancelPreview(ticket: AsyncTicket): string {
   for (let i = 0; i < ticket.progress.length; i++) {
     const p = ticket.progress[i]!;
     if (p.status === "done") {
-      lines.push(`✓ ${p.agent} · completed`);
+      lines.push(`✓ ${p.agent}${formatTaskId(p.id)} · completed`);
     } else if (p.status === "failed") {
-      lines.push(`✗ ${p.agent} · ${p.error ?? "failed"}`);
+      lines.push(`✗ ${p.agent}${formatTaskId(p.id)} · ${p.error ?? "failed"}`);
     } else if (p.status === "running") {
       const parts: string[] = [formatActivityLabel(p)];
       if (p.toolUses > 0)
@@ -643,16 +751,16 @@ function buildCancelPreview(ticket: AsyncTicket): string {
       if (p.tokens > 0) parts.push(`${fmtTokens(p.tokens)} tokens`);
       const age = getActivityAge(p.lastActivityAt);
       if (age) parts.push(age);
-      lines.push(`⏳ ${p.agent} · ${parts.join(" · ")}`);
+      lines.push(`⏳ ${p.agent}${formatTaskId(p.id)} · ${parts.join(" · ")}`);
     } else {
-      lines.push(`○ ${p.agent} · waiting…`);
+      lines.push(`○ ${p.agent}${formatTaskId(p.id)} · waiting…`);
     }
   }
 
   lines.push(
     "",
     "WARNING: Cancelling now will abort active subagents. Files already written or shell commands already executed are NOT rolled back.",
-    `To proceed, call delegate({ action: "cancel", ticket: "${ticket.id}", force: true }).`,
+    `To proceed, call delegate({ ticketAction: "cancel", ticket: "${ticket.id}", force: true }).`,
   );
   return lines.join("\n");
 }
@@ -668,7 +776,7 @@ export function handleCancel(params: {
   if (!ticketId) {
     return {
       content: [
-        { type: "text", text: "action='cancel' requires a ticket ID." },
+        { type: "text", text: "ticketAction='cancel' requires a ticket ID." },
       ],
       details: { tasks: [], results: [], progress: [] },
     };
@@ -692,29 +800,30 @@ export function handleCancel(params: {
     };
   }
   if (!params.force) {
+    const details = buildWaitDetails(ticket);
+    const text =
+      buildCancelPreview(ticket) +
+      (details.overlapWarning ? `\n\n${details.overlapWarning}` : "");
     return {
-      content: [{ type: "text", text: buildCancelPreview(ticket) }],
-      details: buildWaitDetails(ticket),
+      content: [{ type: "text", text }],
+      details,
     };
   }
-  ticket.controller.abort();
-  ticket.status = "cancelling";
-  syncTicketBusyIndex(ticket);
+  requestTicketCancel(ticket);
+  const details = buildWaitDetails(ticket);
+  const base = `Ticket '${ticketId}' is cancelling; workers are settling. Poll for final status.`;
+  const text =
+    base + (details.overlapWarning ? `\n\n${details.overlapWarning}` : "");
   return {
-    content: [
-      {
-        type: "text",
-        text: `Ticket '${ticketId}' is cancelling; workers are settling. Poll for final status.`,
-      },
-    ],
-    details: buildWaitDetails(ticket),
+    content: [{ type: "text", text }],
+    details,
   };
 }
 
 /** Block until a ticket reaches a terminal state or `timeoutMs` expires.
  *  Progress is streamed through `onUpdate` without consuming model turns.
  *  Parent-tool abort or timeout detaches the waiter and leaves the ticket
- *  running; cancellation remains explicit (`action: "cancel"`). */
+ *  running; cancellation remains explicit (`ticketAction: "cancel"`). */
 export function handleWait(
   params: { ticket?: string; timeoutMs?: number },
   signal: AbortSignal | undefined,
@@ -727,7 +836,9 @@ export function handleWait(
   const ticketId = params.ticket;
   if (!ticketId) {
     return Promise.resolve({
-      content: [{ type: "text", text: "action='wait' requires a ticket ID." }],
+      content: [
+        { type: "text", text: "ticketAction='wait' requires a ticket ID." },
+      ],
       details: {
         tasks: [],
         results: [],

package/tools.ts

@@ -12,20 +12,22 @@ import { DEFAULT_TOOLS, READONLY_TOOLS } from "./constants.ts";
 
 /** Shorthand → concrete tool list. `*` = full agent (bash subsumes search);
  *  `ro` = read-only scout (search without shell). */
-const TOOL_GROUPS: Record<string, string[]> = {
-  "*": DEFAULT_TOOLS,
-  ro: READONLY_TOOLS,
-};
+const TOOL_GROUPS: Record<string, string[]> = Object.create(null) as Record<
+  string,
+  string[]
+>;
+TOOL_GROUPS["*"] = DEFAULT_TOOLS;
+TOOL_GROUPS.ro = READONLY_TOOLS;
 
-export const TOOL_FACTORIES: Record<string, (cwd: string) => AgentTool<any>> = {
-  read: createReadTool,
-  write: createWriteTool,
-  edit: createEditTool,
-  bash: createBashTool,
-  grep: createGrepTool,
-  find: createFindTool,
-  ls: createLsTool,
-};
+export const TOOL_FACTORIES: Record<string, (cwd: string) => AgentTool<any>> =
+  Object.create(null) as Record<string, (cwd: string) => AgentTool<any>>;
+TOOL_FACTORIES.read = createReadTool;
+TOOL_FACTORIES.write = createWriteTool;
+TOOL_FACTORIES.edit = createEditTool;
+TOOL_FACTORIES.bash = createBashTool;
+TOOL_FACTORIES.grep = createGrepTool;
+TOOL_FACTORIES.find = createFindTool;
+TOOL_FACTORIES.ls = createLsTool;
 
 /** Expand tool-group shorthands (`*`, `ro`) into concrete tool lists.
  *  Unknown names pass through unchanged for the caller to validate.
@@ -33,8 +35,7 @@ export const TOOL_FACTORIES: Record<string, (cwd: string) => AgentTool<any>> = {
 export function resolveToolGroups(tools: string[]): string[] {
   const resolved: string[] = [];
   for (const t of tools) {
-    const group = TOOL_GROUPS[t];
-    if (group) resolved.push(...group);
+    if (Object.hasOwn(TOOL_GROUPS, t)) resolved.push(...TOOL_GROUPS[t]);
     else resolved.push(t);
   }
   return [...new Set(resolved)];

package/types.ts

@@ -25,18 +25,37 @@ export interface AgentConfig {
 }
 
 // ── Tool parameter types — derived from the TypeBox schema ────────────────
-// `delegateArgumentsSchema` in schema.ts is the single source of truth; these are
-// projections of it, so schema and types cannot drift. Field semantics live
-// in the schema's `description`s (which the calling model also sees).
-// The import is type-only, so the schema.ts ↔ types.ts cycle is erased at
-// compile time.
-
-export type DelegateArguments = Static<typeof delegateArgumentsSchema>;
-export type TaskDef = NonNullable<DelegateArguments["tasks"]>[number];
+// `delegateArgumentsSchema` in schema.ts is the canonical provider-visible
+// shape. The public types add deprecated `action` aliases so existing TypeScript
+// callers remain source-compatible without advertising the overloaded fields to
+// models. The import is type-only, so the schema.ts ↔ types.ts cycle is erased
+// at compile time.
+
+type CanonicalDelegateArguments = Static<typeof delegateArgumentsSchema>;
+type CanonicalTaskDef = NonNullable<
+  CanonicalDelegateArguments["tasks"]
+>[number];
+
 /** Top-level async ticket action: "poll" | "cancel" | "wait". */
-export type DelegateAction = NonNullable<DelegateArguments["action"]>;
+export type TicketAction = NonNullable<
+  CanonicalDelegateArguments["ticketAction"]
+>;
 /** Per-task session action: "prompt" | "close" | "list". */
-export type SessionAction = NonNullable<TaskDef["action"]>;
+export type SessionAction = NonNullable<CanonicalTaskDef["sessionAction"]>;
+
+export type TaskDef = CanonicalTaskDef & {
+  /** @deprecated Use `sessionAction` instead. Runtime normalization still accepts this alias. */
+  action?: SessionAction;
+};
+
+export type DelegateArguments = Omit<CanonicalDelegateArguments, "tasks"> & {
+  /** @deprecated Use `ticketAction` instead. Runtime normalization still accepts this alias. */
+  action?: TicketAction;
+  tasks?: TaskDef[];
+};
+
+/** @deprecated Use `TicketAction` instead. */
+export type DelegateAction = TicketAction;
 
 // ── Async Ticket Types ─────────────────────────────────────────────────────
 
@@ -61,10 +80,22 @@ export interface AsyncTicket {
   controller: AbortController;
   error?: string;
   parentModelId?: string;
+  /** Session-tree leaf active when the ticket was spawned (see leaf.ts).
+   *  `undefined` = the leaf the session opened on. Compared at delivery time
+   *  so results are not used to wake the agent on a foreign branch. */
+  spawnLeafId?: string | null;
   /** Active blocking waiters. Resolved by terminal delivery or timeout/abort. */
   waiters?: TicketWaiter[];
 }
 
+/** Live parent settings captured when a delegate call starts. The built-in
+ *  `default` profile mirrors these settings, limited to tools delegate can
+ *  safely recreate without loading the parent's extensions. */
+export interface ParentAgentDefaults {
+  thinking: ThinkingLevel;
+  tools: string[];
+}
+
 export interface ReuseIntent {
   /** Explicit model requested by this call/profile; omitted means use frozen. */
   model?: Model<Api>;
@@ -73,6 +104,7 @@ export interface ReuseIntent {
 }
 
 export interface ResolvedTask {
+  id?: string;
   prompt: string;
   agent?: string;
   model: Model<Api>;
@@ -82,8 +114,10 @@ export interface ResolvedTask {
   cwd: string;
   context?: "fresh" | "with-parent-transcript";
   sessionId?: string;
-  action?: SessionAction;
+  sessionAction?: SessionAction;
   resumeFrom?: string;
+  /** Hard wall-clock budget in milliseconds, measured from task start. */
+  deadlineMs?: number;
   agentName: string;
   warnings: string[];
   /** Explicit settings that must match a live pooled session on reuse. */
@@ -109,10 +143,14 @@ export interface ToolActivity {
  *  - `model_error`: the failure is attributable to the resolved model/provider
  *    (account usage limit, quota exhausted, auth lost) — not transient for that
  *    model, so same-model retry is pointless. The parent should resume with a
- *    different `model` (see `resumeFrom` + `model`). */
-export type TaskFailureKind = "stalled" | "model_error";
+ *    different `model` (see `resumeFrom` + `model`).
+ *  - `deadline_exceeded`: the task's `deadlineMs` wall-clock budget expired
+ *    (measured from when the task left the concurrency queue). The prompt was
+ *    cooperatively aborted; completed side effects are not rolled back. */
+export type TaskFailureKind = "stalled" | "model_error" | "deadline_exceeded";
 
 export interface TaskProgress {
+  id?: string;
   index: number;
   agent: string;
   task: string;
@@ -138,9 +176,13 @@ export interface DelegateDetails {
   ticketId?: string;
   /** Terminal/live ticket status when this result comes from an async ticket. */
   status?: AsyncTicket["status"];
+  /** Global overlap warning derived from result.attributedFiles, surfaced in both
+   *  the textual content and the custom TUI. */
+  overlapWarning?: string;
 }
 
 export interface TaskResult {
+  id?: string;
   agent: string;
   output: string;
   error?: string;
@@ -159,7 +201,14 @@ export interface TaskResult {
    *  Pi sums `cost.total` for nested usage anyway. */
   usage: Usage;
   sessionFile?: string;
+  /** All files the subagent is known to have touched, including bash mutations
+   *  captured via git diff and other tasks' concurrent git changes. This is a
+   *  best-effort, repository-wide list for display, not for attribution. */
   touchedFiles: string[];
+  /** Files directly attributable to this task's edit/write tool calls. Used
+   *  for overlap detection so concurrent tasks in the same repo do not
+   *  fabricate false conflicts from shared git snapshots. */
+  attributedFiles?: string[];
 }
 
 /** Single source of truth for a subagent's runtime configuration.