@bermudi/pi-delegate 0.1.1 → 0.1.3

package/lifecycle.ts

@@ -20,12 +20,14 @@ import {
   persistSessionHeader,
   setParentSession,
 } from "./sessions.ts";
-import { runAgentSession } from "./runner.ts";
+import { runAgentSession, formatDeadlineExceededError } from "./runner.ts";
 import { getGitChangedFiles } from "./file-tracking.ts";
 import { getHostDeps } from "./host.ts";
 import { resolveCwd, validateResumeFromPath } from "./utils.ts";
 import { getWholeTaskMaxRetries, getWholeTaskBaseDelayMs } from "./config.ts";
 import { addUsage, emptyUsage } from "./usage.ts";
+import { scheduleDeadline } from "./timer.ts";
+import { recordTask } from "./telemetry.ts";
 
 /** Internal seam for lifecycle-level tests without replacing session ownership. */
 type RunAgentSession = typeof runAgentSession;
@@ -72,6 +74,7 @@ function failTask(
   sessionFile?: string,
 ): TaskResult {
   return {
+    id: task.id,
     agent: task.agentName,
     output: "",
     error,
@@ -80,6 +83,7 @@ function failTask(
     usage: emptyUsage(),
     sessionFile,
     touchedFiles: [],
+    attributedFiles: [],
   };
 }
 
@@ -91,6 +95,7 @@ function completeSessionAction(
   elapsedMs?: number,
 ): TaskResult {
   return {
+    id: task.id,
     agent: task.agentName,
     output,
     durationMs: elapsedMs ?? 0,
@@ -98,6 +103,7 @@ function completeSessionAction(
     usage: emptyUsage(),
     sessionFile: undefined,
     touchedFiles: [],
+    attributedFiles: [],
   };
 }
 
@@ -182,8 +188,22 @@ function finishTask(
   env: TaskRunEnv,
   p: TaskProgress,
   r: TaskResult,
+  task: ResolvedTask,
+  retries = 0,
 ): TaskResult {
   updateProgressFromResult(p, r);
+  if (env.telemetryCallId) {
+    recordTask({
+      callId: env.telemetryCallId,
+      generation: env.telemetryGeneration,
+      async: env.async ?? false,
+      taskIndex: p.index,
+      task,
+      progress: p,
+      result: r,
+      retries,
+    });
+  }
   env.onStatusChange?.();
   return r;
 }
@@ -266,6 +286,7 @@ function canRetryWholeTask(
   return (
     result.failureKind !== "stalled" &&
     result.failureKind !== "model_error" &&
+    result.failureKind !== "deadline_exceeded" &&
     !task.sessionId &&
     !task.resumeFrom &&
     result.touchedFiles.length === 0 &&
@@ -277,16 +298,23 @@ function canRetryWholeTask(
 async function sleepForWholeTaskRetry(
   signal: AbortSignal | undefined,
   delayMs: number,
+  deadlineAt?: number,
 ): Promise<void> {
   if (signal?.aborted) return;
+  if (deadlineAt !== undefined && Date.now() >= deadlineAt) return;
+
+  const retryAt = Date.now() + delayMs;
+  const wakeAt =
+    deadlineAt !== undefined ? Math.min(retryAt, deadlineAt) : retryAt;
+
   await new Promise<void>((resolve) => {
-    let timeout: ReturnType<typeof setTimeout>;
+    let clear: (() => void) | undefined;
     const done = () => {
-      clearTimeout(timeout);
+      clear?.();
       signal?.removeEventListener("abort", done);
       resolve();
     };
-    timeout = setTimeout(done, delayMs);
+    clear = scheduleDeadline(wakeAt, done);
     if (!signal) return;
     signal.addEventListener("abort", done, { once: true });
   });
@@ -516,7 +544,7 @@ function resolveResumableSessionFile(
  *  Used by both sync (params.async === false) and async (params.async === true) paths.
  *  When task.sessionId is set, the entire acquire/run/close lifecycle runs under
  *  a per-session mutex so concurrent tasks with the same sessionId serialize
- *  cleanly. The lock also covers action='close' and the early-busy/abort paths. */
+ *  cleanly. The lock also covers sessionAction='close' and the early-busy/abort paths. */
 export async function runResolvedTask(
   env: TaskRunEnv,
   task: ResolvedTask,
@@ -540,7 +568,7 @@ async function runResolvedTaskUnlocked(
   try {
     // ── Aborted before we started? ───────────────────────────────────
     if (env.signal?.aborted) {
-      return finishTask(env, p, failTask(task, "Aborted"));
+      return finishTask(env, p, failTask(task, "Aborted"), task);
     }
 
     // ── Session busy guard (defense-in-depth) ────────────────────────
@@ -550,7 +578,7 @@ async function runResolvedTaskUnlocked(
       const busyTicketId = isSessionBusy(task.sessionId);
       if (busyTicketId && busyTicketId !== env.ticketId) {
         const msg = `Session '${task.sessionId}' is already in use by ticket ${busyTicketId}. Each session can only handle one task at a time.`;
-        return finishTask(env, p, failTask(task, msg));
+        return finishTask(env, p, failTask(task, msg), task);
       }
     }
 
@@ -558,12 +586,13 @@ async function runResolvedTaskUnlocked(
     p.model = task.model?.id;
 
     // ── Session action handling ───────────────────────────────────────
-    if (task.action === "close") {
+    if (task.sessionAction === "close") {
       if (!task.sessionId) {
         return finishTask(
           env,
           p,
-          failTask(task, "action='close' requires sessionId."),
+          failTask(task, "sessionAction='close' requires sessionId."),
+          task,
         );
       }
       // The per-session lock for action-based operations is already held by the
@@ -580,10 +609,11 @@ async function runResolvedTaskUnlocked(
             : `Session '${task.sessionId}' not found.`,
           Date.now() - env.delegateStartedAt,
         ),
+        task,
       );
     }
 
-    if (task.action === "list") {
+    if (task.sessionAction === "list") {
       return finishTask(
         env,
         p,
@@ -592,6 +622,7 @@ async function runResolvedTaskUnlocked(
           `Active sessions:\n${pool.listPooledAgents().join("\n")}`,
           Date.now() - env.delegateStartedAt,
         ),
+        task,
       );
     }
 
@@ -599,6 +630,10 @@ async function runResolvedTaskUnlocked(
     let cumulativeTokens = 0;
     let cumulativeToolUses = 0;
     const taskStartedAt = Date.now();
+    const deadlineAt =
+      task.deadlineMs && task.deadlineMs > 0
+        ? taskStartedAt + task.deadlineMs
+        : undefined;
     let accumulatedUsage = emptyUsage();
 
     const onAttemptProgress = (u: AgentProgressUpdate): void => {
@@ -651,7 +686,10 @@ async function runResolvedTaskUnlocked(
 
         // Snapshot git status before the run so touchedFiles can diff after.
         // AgentSession owns retry/compaction internally — runAgentSession just
-        // drives the prompt and maps events to the progress model.
+        // drives the prompt and maps events to the progress model. Git failures
+        // degrade to an undefined baseline, which tells the runner to skip
+        // git-based attribution entirely; see getGitChangedFiles for the
+        // contract.
         const gitBaseline = await getGitChangedFiles(task.cwd);
         let r = await runAgentSessionForTesting(
           acquired.session,
@@ -660,7 +698,8 @@ async function runResolvedTaskUnlocked(
           env.signal,
           onProgress,
           gitBaseline,
-          Date.now(),
+          taskStartedAt,
+          deadlineAt,
         );
 
         cumulativeTokens += r.tokens;
@@ -682,7 +721,11 @@ async function runResolvedTaskUnlocked(
             // Pool misses (including resumeFrom) transfer ownership only on
             // successful completion; failures are owned by lifecycle and must
             // be disposed in this finally path.
-            if (!r.error && r.failureKind !== "stalled") {
+            if (
+              !r.error &&
+              r.failureKind !== "stalled" &&
+              r.failureKind !== "deadline_exceeded"
+            ) {
               const committed = pool.commit(task.sessionId, {
                 session: acquired.session,
                 sessionManager: acquired.sessionManager,
@@ -699,28 +742,37 @@ async function runResolvedTaskUnlocked(
               sessionReleased = sessionReleased || committed;
             }
           } else {
-            // A stalled pooled attempt is not safe to keep; remove from the
-            // pool and let the lifecycle-owned finalizer handle disposal.
-            if (r.failureKind === "stalled") {
+            // A stalled, parent-aborted, or mid-prompt deadline-exceeded pooled
+            // attempt is not safe to keep; the session may have been mutated.
+            // A pre-prompt deadline (runner never called session.prompt()) left
+            // the session in its pre-task state, so return it to the pool intact.
+            if (
+              r.failureKind === "stalled" ||
+              r.error === "Aborted" ||
+              (r.failureKind === "deadline_exceeded" && r.prompted !== false)
+            ) {
               try {
                 sessionReleased =
                   (await pool._closePooledAgentWithoutLock(task.sessionId)) ||
                   sessionReleased;
               } catch (error) {
-                // Preserve the primary stalled result while logging the cleanup
+                // Preserve the primary failure result while logging the cleanup
                 // failure explicitly. A pooled session may still be removed by
                 // the pool; a pool-miss remains lifecycle-owned and is handled
                 // by the finally path above.
                 console.error(
-                  `[delegate] failed to dispose stalled pooled session '${task.sessionId}'`,
+                  `[delegate] failed to dispose aborted, stalled, or deadline-exceeded pooled session '${task.sessionId}'`,
                   error,
                 );
               }
-            } else {
-              // Pool hits stay owned by the pool, and non-stalled completions
-              // (including failed attempts) must still count usage.
+            } else if (r.failureKind !== "deadline_exceeded") {
+              // Pool hits stay owned by the pool, and non-stalled, non-aborted
+              // completions (including failed attempts) must still count usage.
               pool.recordUse(task.sessionId, r.tokens);
             }
+            // Pre-prompt deadline (prompted === false): the pooled session was
+            // checked out but never used. Leave it in the pool with no usage
+            // recorded.
           }
         }
 
@@ -728,6 +780,7 @@ async function runResolvedTaskUnlocked(
         cumulativeToolUses += attemptToolUsesObserved;
 
         return {
+          id: task.id,
           agent: task.agentName,
           output: r.output,
           error: r.error,
@@ -747,6 +800,7 @@ async function runResolvedTaskUnlocked(
           usage: r.usage,
           sessionFile,
           touchedFiles: r.touchedFiles,
+          attributedFiles: r.attributedFiles ?? [],
         };
       } finally {
         // This runs for ordinary success, normal provider failure, whole-task
@@ -756,24 +810,51 @@ async function runResolvedTaskUnlocked(
       }
     };
 
+    const buildDeadlineExceededResult = (prior?: TaskResult): TaskResult => {
+      const budgetMs = Math.max(0, (deadlineAt ?? 0) - taskStartedAt);
+      return {
+        id: task.id,
+        agent: task.agentName,
+        output: prior?.output ?? "",
+        error: formatDeadlineExceededError(budgetMs),
+        failureKind: "deadline_exceeded",
+        durationMs: prior?.durationMs ?? 0,
+        tokens: prior?.tokens ?? 0,
+        usage: prior?.usage ?? emptyUsage(),
+        sessionFile: prior?.sessionFile,
+        touchedFiles: prior?.touchedFiles ?? [],
+        attributedFiles: prior?.attributedFiles ?? [],
+      };
+    };
+
     let result: TaskResult;
     try {
-      result = await runAttempt();
+      if (deadlineAt && Date.now() >= deadlineAt) {
+        result = buildDeadlineExceededResult(undefined);
+      } else {
+        result = await runAttempt();
+      }
     } catch (err) {
       const failure = failTask(
         task,
         err instanceof Error ? err.message : String(err),
       );
-      return finishTask(env, p, {
-        ...failure,
-        durationMs: Math.max(failure.durationMs, Date.now() - taskStartedAt),
-        tokens: accumulatedUsage.totalTokens,
-        usage: accumulatedUsage,
-      });
+      return finishTask(
+        env,
+        p,
+        {
+          ...failure,
+          durationMs: Math.max(failure.durationMs, Date.now() - taskStartedAt),
+          tokens: accumulatedUsage.totalTokens,
+          usage: accumulatedUsage,
+        },
+        task,
+      );
     }
 
     const maxRetries = resolvedWholeTaskMaxRetries();
     const baseDelayMs = resolvedWholeTaskBaseDelayMs();
+    let retriesExecuted = 0;
     for (
       let retry = 0;
       retry < maxRetries && canRetryWholeTask(task, result, hasBashExecution);
@@ -781,7 +862,7 @@ async function runResolvedTaskUnlocked(
     ) {
       const delayMs = baseDelayMs * 2 ** retry;
       p.durationMs = Math.max(p.durationMs, Date.now() - taskStartedAt);
-      await sleepForWholeTaskRetry(env.signal, delayMs);
+      await sleepForWholeTaskRetry(env.signal, delayMs, deadlineAt);
       if (env.signal?.aborted) {
         // Preserve any partial output/session path from the last failed attempt
         // while recording that the retry loop was aborted. The task already
@@ -798,10 +879,16 @@ async function runResolvedTaskUnlocked(
         break;
       }
 
+      if (deadlineAt && Date.now() >= deadlineAt) {
+        result = buildDeadlineExceededResult(result);
+        break;
+      }
+
       p.status = "running";
       p.error = undefined;
       p.failureKind = undefined;
       env.onStatusChange?.();
+      retriesExecuted++;
       try {
         result = await runAttempt();
       } catch (err) {
@@ -819,12 +906,18 @@ async function runResolvedTaskUnlocked(
       }
     }
 
-    return finishTask(env, p, {
-      ...result,
-      durationMs: Math.max(result.durationMs, Date.now() - taskStartedAt),
-      tokens: Math.max(cumulativeTokens, accumulatedUsage.totalTokens),
-      usage: accumulatedUsage,
-    });
+    return finishTask(
+      env,
+      p,
+      {
+        ...result,
+        durationMs: Math.max(result.durationMs, Date.now() - taskStartedAt),
+        tokens: Math.max(cumulativeTokens, accumulatedUsage.totalTokens),
+        usage: accumulatedUsage,
+      },
+      task,
+      retriesExecuted,
+    );
   } catch (err) {
     // Any acquired session is released by runAttempt's finally before an
     // exception reaches this boundary. This outer catch handles unexpected
@@ -834,6 +927,7 @@ async function runResolvedTaskUnlocked(
       env,
       p,
       failTask(task, err instanceof Error ? err.message : String(err)),
+      task,
     );
   }
 }

package/manual.ts

@@ -73,13 +73,33 @@ export function getSubagentManualMarkdown(
     'delegate({ tasks: [{ agent: "default", prompt: "Investigate the auth module" }] })',
     "```",
     "",
-    "Delegate subagents to execute tasks in parallel. Each subagent gets an independent context. Use the built-in `default` profile when it should mirror the live parent's model, thinking level, delegatable native tools, and base system prompt. Custom agents can be defined inline in a task or persisted as Markdown files.",
+    "Delegate subagents to execute tasks in parallel. Each subagent gets an independent conversation but uses the real filesystem at its task `cwd`; tasks sharing a directory can observe and overwrite one another's changes. Fresh prompts must therefore be self-contained, and dependent or shared-file work should run separately.",
+    "",
+    "The three handles have different lifetimes:",
+    "",
+    "- **ticket** — controls one async batch with `poll`, `wait`, or `cancel`.",
+    "- **sessionId** — a caller-chosen key for a live multi-turn worker, retained until close or parent shutdown.",
+    "- **resumeFrom** — an absolute `.jsonl` transcript path used to recover an interrupted worker.",
+    "",
+    "Each task entry may also carry an optional `id` — a caller-provided per-dispatch correlation key. Duplicate `id` values in the same call are rejected; when omitted, tasks are identified by array index, agent, and prompt.",
+    "",
+    "Subagents cannot call `delegate` recursively. Their tool activity runs at `cwd`, while Pi stores the runtime session transcript in its own session directory outside that `cwd`.",
+    "",
+    "## Touched Files (best-effort)",
+    "",
+    "The `touched:` list in each task result is a **best-effort lower bound**, not an authoritative record.",
+    "",
+    "- `write` and `edit` tool calls are captured reliably from the activity log.",
+    "- `bash` mutations are captured only when the task `cwd` is inside a git repo and git is available, via `git status` against the pre-run baseline.",
+    "- In a non-git directory, bash-mutated files are not reported.",
+    "- Git failures degrade to an empty diff.",
+    "- A path missing from `touched:` does **not** mean the file was unchanged. Delegate does not isolate file access or roll back writes.",
     "",
     "## Built-in Agent",
     "",
     "- **default**: mirrors the live parent model, thinking level, delegatable native tools, and base system prompt.",
     "",
-    "Parent extension/MCP tools are not copied, and project context is rebuilt safely for the task's `cwd`. Per-task fields remain explicit overrides.",
+    "Parent extension/MCP tools are not copied. Parent-global `AGENTS.md` instructions are also excluded. Project-local context is rebuilt safely for the task's `cwd`; per-task fields remain explicit overrides.",
     "",
     "## Available Custom Agents",
     "",
@@ -118,10 +138,10 @@ export function getSubagentManualMarkdown(
     'delegate({ tasks: [{ prompt: "Now check the tests for that module", sessionId: "auth-research" }] })',
     "",
     "// Clean up when done",
-    'delegate({ tasks: [{ sessionId: "auth-research", action: "close" }] })',
+    'delegate({ tasks: [{ sessionId: "auth-research", sessionAction: "close" }] })',
     "```",
     "",
-    'Pooled agents remain live until `action: "close"` or parent Pi session shutdown.',
+    'Pooled agents remain live until `sessionAction: "close"` or parent Pi session shutdown.',
     "",
     "## Resuming Previous Sessions",
     "",
@@ -158,28 +178,36 @@ export function getSubagentManualMarkdown(
     "",
     "## Async Mode",
     "",
-    "Set `async: true` to run tasks in the background. The top-level `action` controls the ticket:",
+    "Set `async: true` to run tasks in the background. The top-level `ticketAction` controls the ticket:",
     "",
     "```ts",
     'delegate({ async: true, tasks: [{ prompt: "Investigate auth", systemPrompt: "You are a focused investigator.", tools: ["read", "grep", "find", "ls"] }] })',
     "```",
     "",
-    '- `delegate({ action: "poll" })` \u2014 list all tickets',
-    '- `delegate({ action: "poll", ticket: "abc123" })` \u2014 check one ticket',
-    '- `delegate({ action: "wait", ticket: "abc123", timeoutMs: 600000 })` \u2014 block until finished or timeout',
-    '- `delegate({ action: "cancel", ticket: "abc123" })` \u2014 preview activity and partial effects before cancelling',
-    '- `delegate({ action: "cancel", ticket: "abc123", force: true })` \u2014 abort after review',
+    '- `delegate({ ticketAction: "poll" })` \u2014 list all tickets',
+    '- `delegate({ ticketAction: "poll", ticket: "abc123" })` \u2014 take one progress snapshot',
+    '- `delegate({ ticketAction: "wait", ticket: "abc123" })` \u2014 block until finished; omit `timeoutMs` when the result is needed this turn',
+    '- `delegate({ ticketAction: "wait", ticket: "abc123", timeoutMs: 600000 })` \u2014 bounded wait; timeout includes the latest snapshot, so do not poll afterward',
+    '- `delegate({ ticketAction: "cancel", ticket: "abc123" })` \u2014 preview activity and partial effects before cancelling',
+    '- `delegate({ ticketAction: "cancel", ticket: "abc123", force: true })` \u2014 abort after review',
     "",
     `See the field tables above for the full semantics. Max ${getMaxAsyncTickets()} concurrent async tickets.`,
+    "Async results arrive as follow-up messages, so Pi cannot fold their usage into the parent session total; displayed task usage remains informational.",
     "",
     "## Gotchas",
     "",
+    "- Dispatch validation is batch-wide and runs before spawning: one invalid task rejects the call without starting its siblings.",
     "- `*` means read/write/edit/bash, not every tool. `grep`, `find`, and `ls` are valid explicit tools and are the `ro` preset.",
     '- `tasks` is an array. The tool recovers common stringified calls for compatibility, but canonical calls use `{ tasks: [{ prompt: "..." }] }`.',
     '- Use `agent: "default"` for the parent\'s live model/thinking/native tools/base prompt. Omitting `agent` creates an ad-hoc task with delegate defaults.',
     "- An ad-hoc task with no `tools` uses `*`; a named custom task uses its profile; a profile with no tools uses `*`.",
     "- Subagents inherit all skills discovered in their `cwd` (via AgentSession's resource loader). Per-task skill filtering is not supported — curate the cwd's skill set instead.",
     `- Sync \`delegate\` runs at most ${getMaxConcurrent()} tasks at once (the rest queue, not fail). Use \`async: true\` to move work to the background.`,
+    "- `deadlineMs` is a per-task wall-clock budget measured from when the task starts running (after queuing). It requests cooperative abort and is not a hard kill; completed writes/commands remain. Omission disables the deadline.",
+    "",
+    "## Legacy `action` compatibility",
+    "",
+    "The overloaded `action` field was split into `ticketAction` (poll/wait/cancel) and `sessionAction` (prompt/close/list). Legacy `action` values are still accepted at runtime through automatic normalization, but new calls should use the canonical fields. Programmatic TypeScript consumers should note the exported type `DelegateAction` is now `TicketAction`.",
     "",
     "## Config",
     "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bermudi/pi-delegate",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Delegate tool for the Pi coding agent.",
   "keywords": [
     "pi-package"
@@ -32,6 +32,9 @@
     "prettier": "^3.8.4",
     "typescript": "^5.9.0"
   },
+  "patchedDependencies": {
+    "@marcfargas/pi-test-harness@0.6.1": "patches/@marcfargas%2Fpi-test-harness@0.6.1.patch"
+  },
   "private": false,
   "scripts": {
     "test": "bun test",

package/patches/@marcfargas%2Fpi-test-harness@0.6.1.patch

@@ -0,0 +1,13 @@
+diff --git a/dist/session.js b/dist/session.js
+index f7dc5de9be959c541ee4bab0ad1424656993bbe9..e515073926f0fbb0e2bc566a9b17f5f15f80a1a1 100644
+--- a/dist/session.js
++++ b/dist/session.js
+@@ -12,7 +12,7 @@ import * as fs from "node:fs";
+ import * as path from "node:path";
+ import * as os from "node:os";
+ import { createAgentSession, DefaultResourceLoader, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+-import { getModel } from "@earendil-works/pi-ai";
++import { getModel } from "@earendil-works/pi-ai/compat";
+ import { createPlaybookStreamFn } from "./playbook.js";
+ import { interceptToolExecution } from "./mock-tools.js";
+ import { createMockUIContext } from "./mock-ui.js";

package/render-branches.ts

@@ -3,6 +3,7 @@ import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
 import {
   fmtDuration,
   fmtTokens,
+  formatTaskId,
   getActivityAge,
   indent,
   tree,
@@ -107,7 +108,7 @@ export function renderPartialBranch(ctx: BranchCtx, h: RenderHelpers): void {
       case "done":
         lines.push(
           truncLine(
-            `${tree(i, total)} ${theme.fg("success", "✓")} ${theme.bold(p.agent)}${modelLabel(p)}${statJoin([fmtDuration(p.durationMs), `${fmtTokens(p.tokens)} tokens`])}`,
+            `${tree(i, total)} ${theme.fg("success", "✓")} ${theme.bold(p.agent)}${p.id ? theme.fg("accent", formatTaskId(p.id)) : ""}${modelLabel(p)}${statJoin([fmtDuration(p.durationMs), `${fmtTokens(p.tokens)} tokens`])}`,
             w,
           ),
         );
@@ -126,7 +127,7 @@ export function renderPartialBranch(ctx: BranchCtx, h: RenderHelpers): void {
       case "failed":
         lines.push(
           truncLine(
-            `${tree(i, total)} ${theme.fg("error", "✗")} ${theme.bold(p.agent)}${modelLabel(p)}${p.error ? theme.fg("error", ` ${p.error}`) : ""}`,
+            `${tree(i, total)} ${theme.fg("error", "✗")} ${theme.bold(p.agent)}${p.id ? theme.fg("accent", formatTaskId(p.id)) : ""}${modelLabel(p)}${p.error ? theme.fg("error", ` ${p.error}`) : ""}`,
             w,
           ),
         );
@@ -146,14 +147,19 @@ export function renderPartialBranch(ctx: BranchCtx, h: RenderHelpers): void {
         {
           const activityAge = getActivityAge(p.lastActivityAt);
           const ageTag = activityAge ? ` · ${activityAge}` : "";
-          const stallTag =
-            p.failureKind === "stalled"
-              ? theme.fg("warning", " · stall detected · cancellation pending")
-              : "";
+          const issueTag =
+            p.failureKind === "deadline_exceeded"
+              ? theme.fg("error", " · deadline exceeded · cancellation pending")
+              : p.failureKind === "stalled"
+                ? theme.fg(
+                    "warning",
+                    " · stall detected · cancellation pending",
+                  )
+                : "";
           const glyph = theme.fg("warning", spinnerFrame());
           lines.push(
             truncLine(
-              `${tree(i, total)} ${glyph} ${theme.bold(p.agent)}${modelLabel(p)}${statJoin(runParts)}${stallTag}${theme.fg("muted", ageTag)}`,
+              `${tree(i, total)} ${glyph} ${theme.bold(p.agent)}${p.id ? theme.fg("accent", formatTaskId(p.id)) : ""}${modelLabel(p)}${statJoin(runParts)}${issueTag}${theme.fg("muted", ageTag)}`,
               w,
             ),
           );
@@ -229,7 +235,7 @@ export function renderPartialBranch(ctx: BranchCtx, h: RenderHelpers): void {
         );
         lines.push(
           truncLine(
-            `${tree(i, total)} ${theme.fg("muted", "○")} ${theme.bold(p.agent)}${modelLabel(p)} ${queuedTag}`,
+            `${tree(i, total)} ${theme.fg("muted", "○")} ${theme.bold(p.agent)}${p.id ? theme.fg("accent", formatTaskId(p.id)) : ""}${modelLabel(p)} ${queuedTag}`,
             w,
           ),
         );
@@ -260,12 +266,18 @@ export function renderFinalBranch(ctx: BranchCtx, h: RenderHelpers): void {
   const totalTokens = progress.reduce((sum, p) => sum + p.tokens, 0);
   const ticketId = ctx.ticketId;
   const ticketStatus = ctx.ticketStatus;
-  const isLive = ticketStatus === "running" || ticketStatus === "cancelling";
+  // A terminal ticket can retain a stale running/pending row while its workers
+  // unwind. Keep the row presentation terminal in that case; an absent status
+  // is the synchronous-render path, where task status remains authoritative.
+  const ticketIsLive =
+    ticketStatus === undefined ||
+    ticketStatus === "running" ||
+    ticketStatus === "cancelling";
   const elapsed = state.startedAt
     ? fmtDuration(Date.now() - state.startedAt)
     : fmtDuration(progress.reduce((sum, p) => sum + p.durationMs, 0));
 
-  if (ticketId && isLive) {
+  if (ticketId && ticketIsLive) {
     // Background ticket — frame it as in-progress, not a finished result.
     const ticketParts = [
       `ticket ${ticketId}`,
@@ -307,9 +319,15 @@ export function renderFinalBranch(ctx: BranchCtx, h: RenderHelpers): void {
           : p.status === "running"
             ? theme.fg("warning", "◐")
             : theme.fg("muted", "○");
-    const taskPreview = theme.fg("muted", trunc(p.task, w - 30));
+    const taskId = p.id ? formatTaskId(p.id) : "";
+    const taskIdTag = p.id ? theme.fg("accent", taskId) : "";
+    const taskIdWidth = p.id ? taskId.length : 0;
+    const previewBudget = Math.max(1, w - 30 - taskIdWidth);
+    const taskPreview = theme.fg("muted", trunc(p.task, previewBudget));
     const isLive =
-      p.status === "running" || (p.status === "pending" && !isCancelledPending);
+      ticketIsLive &&
+      (p.status === "running" ||
+        (p.status === "pending" && !isCancelledPending));
     // Live tasks show an activity/waiting hint instead of final stats.
     const liveTail =
       p.status === "running"
@@ -322,7 +340,7 @@ export function renderFinalBranch(ctx: BranchCtx, h: RenderHelpers): void {
       : "";
     lines.push(
       truncLine(
-        `${tree(i, total)} ${icon} ${theme.bold(p.agent)}${modelLabel(p)} ${taskPreview}${isLive ? liveTail : cancelledTail || statJoin([fmtDuration(p.durationMs), `${fmtTokens(p.tokens)} tokens`])}`,
+        `${tree(i, total)} ${icon} ${theme.bold(p.agent)}${modelLabel(p)}${taskIdTag} ${taskPreview}${isLive ? liveTail : cancelledTail || statJoin([fmtDuration(p.durationMs), `${fmtTokens(p.tokens)} tokens`])}`,
         w,
       ),
     );

package/render-result.ts

@@ -166,6 +166,18 @@ export function renderDelegateResult(
     ticketStatus,
   };
 
+  // Surface the touched-file overlap warning at the top of the TUI. The same
+  // text already lives in the textual content, but the progress-based renderer
+  // ignores content, so we must render it explicitly from details. Rendering it
+  // before the progress tree places it at the top of the budgeted region, so it
+  // survives truncation from the bottom when many tasks collapse the view.
+  if (details?.overlapWarning) {
+    lines.push(
+      truncLine(theme.fg("warning", `⚠ ${details.overlapWarning}`), w),
+      "",
+    );
+  }
+
   if (options.isPartial) {
     renderPartialBranch(branchCtx, helpers);
   } else {