@bermudi/pi-delegate 0.1.0 → 0.1.2

package/manual.ts

@@ -70,10 +70,36 @@ export function getSubagentManualMarkdown(
     "**Why you're seeing this:** no tasks were provided, so the tool returned help instead of dispatching. Nothing is broken. To dispatch subagents, put task fields inside `tasks: [{ ... }]`.",
     "",
     "```ts",
-    'delegate({ tasks: [{ prompt: "Investigate the auth module" }] })',
+    'delegate({ tasks: [{ agent: "default", prompt: "Investigate the auth module" }] })',
     "```",
     "",
-    "Delegate subagents to execute tasks in parallel. Each subagent gets an independent context, system prompt, model, tools, and thinking level. 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. 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",
     "",
@@ -112,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",
     "",
@@ -152,27 +178,35 @@ 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 check one ticket',
+    '- `delegate({ ticketAction: "wait", ticket: "abc123", timeoutMs: 600000 })` \u2014 block until finished or timeout',
+    '- `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: "..." }] }`.',
-    "- An ad-hoc task with no `tools` uses `*`; a named task uses its profile; a profile with no tools uses `*`.",
+    '- 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/model.ts

@@ -6,8 +6,7 @@ import { VALID_THINKING } from "./constants.ts";
 export interface ResolvedModelRequest {
   model: Model<Api> | undefined;
   /** Pi-style `:<thinking-level>` suffix stripped to make the reference
-   *  resolve. Reported so the caller can warn — it is NOT honored as a
-   *  thinking level; the task's `thinking` field is the only thinking input. */
+   *  resolve. The caller may use it as a last-resort thinking default. */
   strippedSuffix?: ThinkingLevel;
 }
 
@@ -32,8 +31,8 @@ function resolveModelReference(
  * stripped and the base reference is resolved — models learned this syntax
  * from Pi's CLI (e.g. `openai-codex/gpt-5.6-luna:max`) and keep emitting it,
  * so hard-failing the whole call over it is worse than tolerating it. The
- * suffix is deliberately NOT fed into thinking resolution: a single knob
- * (the `thinking` field) beats two knobs with a silent precedence rule. */
+ * suffix is returned separately so task resolution can use it as a
+ * last-resort default while keeping explicit `thinking` authoritative. */
 export function resolveModelRequest(
   spec: string | undefined,
   registry: ModelRegistry,

package/package.json

@@ -1,25 +1,6 @@
 {
   "name": "@bermudi/pi-delegate",
-  "version": "0.1.0",
-  "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.80.9",
-    "@earendil-works/pi-ai": "^0.80.9",
-    "@earendil-works/pi-coding-agent": "^0.80.9",
-    "@earendil-works/pi-tui": "^0.80.9",
-    "@marcfargas/pi-test-harness": "^0.6.1",
-    "@sinclair/typebox": "^0.34.0",
-    "esbuild": "^0.27.0",
-    "prettier": "^3.8.4",
-    "typescript": "^5.9.0"
-  },
-  "private": false,
-  "scripts": {
-    "test": "bun test",
-    "typecheck": "tsc --noEmit",
-    "build": "esbuild delegate.ts --bundle --platform=neutral --packages=external --format=esm --banner:js=\"// @ts-nocheck\" --outfile=delegate.bundle.ts",
-    "format": "prettier --write \"**/*.ts\""
-  },
-  "type": "module",
+  "version": "0.1.2",
   "description": "Delegate tool for the Pi coding agent.",
   "keywords": [
     "pi-package"
@@ -28,6 +9,7 @@
     "type": "git",
     "url": "git+https://github.com/bermudi/pi-delegate.git"
   },
+  "type": "module",
   "files": [
     "*.ts",
     "!*.test.ts",
@@ -39,5 +21,28 @@
     "extensions": [
       "./delegate.ts"
     ]
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "^0.80.9",
+    "@earendil-works/pi-ai": "^0.80.9",
+    "@earendil-works/pi-coding-agent": "^0.80.9",
+    "@earendil-works/pi-tui": "^0.80.9",
+    "@marcfargas/pi-test-harness": "^0.6.1",
+    "esbuild": "^0.27.0",
+    "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",
+    "typecheck": "tsc --noEmit",
+    "build": "esbuild delegate.ts --bundle --platform=neutral --packages=external --format=esm --banner:js=\"// @ts-nocheck\" --outfile=.build/delegate.bundle.ts",
+    "format": "prettier --write \"**/*.ts\""
+  },
+  "dependencies": {
+    "@sinclair/typebox": "0.34.52"
   }
 }

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/pool.ts

@@ -97,10 +97,25 @@ let poolAbortTimeoutMs = DEFAULT_POOL_ABORT_TIMEOUT_MS;
  *  delegate calls with the same sessionId queue instead of interleaving. */
 const sessionLocks = new Map<string, Promise<void>>();
 
+type PoolShutdownState = "open" | "closing" | "closed";
+let poolState: PoolShutdownState = "open";
+let closePromise: Promise<void> | null = null;
+
 function now(): number {
   return Date.now();
 }
 
+function assertPoolOpenForNormalWork(): void {
+  if (poolState !== "open") {
+    throw new Error("Session pool is not accepting new work.");
+  }
+}
+
+function waitForActiveSessionLocks(): Promise<void> {
+  const locks = [...sessionLocks.values()];
+  return Promise.all(locks).then(() => undefined);
+}
+
 // ── Read + validate ───────────────────────────────────────────────────────
 
 /** Look up a pooled session and validate a reuse request against its frozen
@@ -115,8 +130,8 @@ function now(): number {
  *  - mismatch → pooled but its immutable configuration conflicts with this
  *               request. Caller formats the structured diff into an error.
  *
- *  lastUsed is bumped by commit() on a successful run, not here — so a checkout
- *  that bails (e.g. a resumeFrom conflict at the caller) does not affect stats. */
+ *  lastUsed is bumped by recordUse() after a completed pool hit, not here — so
+ *  a checkout that bails (e.g. a resumeFrom conflict) does not affect stats. */
 export function checkout(
   sessionId: string,
   candidate: ConfigCandidate,
@@ -187,28 +202,26 @@ export function checkout(
 
 // ── The sole mutator (besides close) ──────────────────────────────────────
 
-/** Record the outcome of a run against a sessionId. Decides insert-vs-recordUse
- *  internally by map presence:
- *   - present (pool hit)  → bump lastUsed, totalTokens, promptCount.
- *   - absent  (fresh/resume success) → insert with the frozen config.
+/**
+ * Insert the first successful prompt for a fresh/resumed session into the pool.
  *
- *  MUST be called inside withSessionLock(sessionId, …) — the map-presence
- *  decision is sound only because the lock serializes same-sessionId tasks, so
- *  no concurrent commit can race the insert. MUST only be called on run success
- *  (insert-only-on-success is caller-gated). Returns true when the session is
- *  now pool-owned, false when a fresh session could not be inserted because it
- *  lacks the manager/file required by a pooled entry. */
+ *  MUST be called inside withSessionLock(sessionId, …) and only when this run
+ *  should transfer ownership from lifecycle to the pool. Returns true when the
+ *  session is now pool-owned, false when insertion is blocked (shutdown) or
+ *  impossible (missing manager/file).
+ */
 export function commit(sessionId: string, payload: CommitPayload): boolean {
-  const existing = agentPool.get(sessionId);
-  if (existing) {
-    // Pool hit: session already pooled, just bump stats.
-    existing.lastUsed = now();
-    existing.totalTokens += payload.tokens;
-    existing.promptCount++;
-    return true;
+  // Shutdown-aware policy: once shutdown has started, inserting a new pool entry
+  // is unsafe. The lifecycle handles the still-owned session (abort/cleanup) and
+  // should dispose it instead of inserting it after the barrier begins.
+  if (poolState !== "open") {
+    return false;
   }
+
   // Miss → success: insert. A pooled entry needs a concrete file/manager.
   if (!payload.sessionManager || !payload.sessionFile) return false;
+
+  if (agentPool.has(sessionId)) return false;
   agentPool.set(sessionId, {
     session: payload.session,
     sessionManager: payload.sessionManager,
@@ -222,6 +235,20 @@ export function commit(sessionId: string, payload: CommitPayload): boolean {
   return true;
 }
 
+/** Record a completed run against an existing pooled session. This is separate
+ *  from commit() so lifecycle can distinguish ownership transfer from hit
+ *  accounting. Returns true only when the sessionId is currently pooled.
+ */
+export function recordUse(sessionId: string, tokens: number): boolean {
+  const existing = agentPool.get(sessionId);
+  if (!existing) return false;
+
+  existing.lastUsed = now();
+  existing.totalTokens += tokens;
+  existing.promptCount++;
+  return true;
+}
+
 // ── Read-only defaults (for task-resolution) ──────────────────────────────
 
 /** Frozen config for a pooled session, or undefined if not pooled. Lock-free —
@@ -242,10 +269,26 @@ export function configFor(
  *  (lifecycle) can bracket the ENTIRE acquire/run/commit flow; checkout/commit
  *  do NOT lock internally because their only caller is already inside this
  *  bracket. Close is also invoked under this lock, so it never disposes an
- *  in-flight prompt. */
+ *  in-flight prompt.
+ *
+ *  External callers must go through this exported path only while the pool is
+ *  open. Internal callers that are already synchronized by a higher-level lock
+ *  can use `withSessionLockInternal`.
+ */
 export async function withSessionLock<T>(
   sessionId: string,
   fn: () => Promise<T>,
+): Promise<T> {
+  assertPoolOpenForNormalWork();
+  return withSessionLockInternal(sessionId, fn);
+}
+
+/** Internal lock variant that does not reject during shutdown. Use only from
+ *  lifecycle/control paths that already account for pool shutdown state.
+ */
+async function withSessionLockInternal<T>(
+  sessionId: string,
+  fn: () => Promise<T>,
 ): Promise<T> {
   const prev = sessionLocks.get(sessionId);
   let resolve!: () => void;
@@ -303,8 +346,8 @@ function beginAbort(session: AgentSession): Promise<AbortOutcome> {
 }
 
 /** Close and dispose one pooled session. A caller holds the per-session lock
- * while closing, so abort cannot race a reuse. All cleanup is attempted before
- * an error is surfaced; a removed session is never silently retained. */
+ *  while closing, so abort cannot race a reuse. All cleanup is attempted before
+ *  an error is surfaced; a removed session is never silently retained. */
 async function closePooledAgentAfterAbort(
   sessionId: string,
   abort: Promise<AbortOutcome>,
@@ -346,44 +389,117 @@ async function closePooledAgentAfterAbort(
   return true;
 }
 
-/** Abort, dispose, and remove one pooled session. Returns false when the id
- * is already absent; cleanup failures are aggregated after removal. */
-export async function closePooledAgent(sessionId: string): Promise<boolean> {
+/** Internal close helper for callers that already own (or are obtaining) the
+ *  session lock. */
+async function closePooledAgentAfterLock(sessionId: string): Promise<boolean> {
   const pooled = agentPool.get(sessionId);
   if (!pooled) return false;
   return closePooledAgentAfterAbort(sessionId, beginAbort(pooled.session));
 }
 
+/** @internal Close while the caller already owns the per-session lock. */
+export async function _closePooledAgentWithoutLock(
+  sessionId: string,
+): Promise<boolean> {
+  return closePooledAgentAfterLock(sessionId);
+}
+
+/** Abort, dispose, and remove one pooled session. Returns false when the id
+ * is already absent; cleanup failures are aggregated after removal.
+ * During shutdown or after close, this waits for shutdown to finish and
+ * returns `false` instead of throwing.
+ */
+export async function closePooledAgent(sessionId: string): Promise<boolean> {
+  if (poolState !== "open") {
+    const existing = closePromise;
+    if (existing) {
+      try {
+        await existing;
+      } catch {
+        // Keep public close idempotent during and after shutdown.
+      }
+    }
+    return false;
+  }
+
+  let awaitShutdown: Promise<void> | undefined;
+  let closed = false;
+
+  await withSessionLockInternal(sessionId, async () => {
+    // A shutdown can begin while this call waits for its lock. Avoid waiting
+    // for closePromise inside this lock: do that work after releasing it, so
+    // closeAll can acquire the lock and dispose the same session.
+    if (poolState !== "open") {
+      awaitShutdown = closePromise ?? undefined;
+      return;
+    }
+    closed = await closePooledAgentAfterLock(sessionId);
+  });
+
+  if (awaitShutdown) {
+    try {
+      await awaitShutdown;
+    } catch {
+      // Keep public close idempotent during and after shutdown.
+    }
+  }
+
+  return closed;
+}
+
 /** Dispose every live pooled session when the parent Pi session ends. First
- * request cancellation immediately, then acquire each session's lock before
- * disposal. The lock prevents an in-flight lifecycle from committing a live
- * session after shutdown has removed it. Attempts all cleanup before reporting
- * any failures. */
+ * request cancellation immediately, then wait for all in-flight session locks,
+ * then acquire each remaining session's lock before disposal. Attempts are
+ * executed for all sessions before reporting failures. Idempotent callers share
+ * the same completion promise, including failures.
+ */
 export async function closeAllPooledAgents(): Promise<void> {
-  const aborts = new Map<string, Promise<AbortOutcome>>(
-    [...agentPool].map(([sessionId, pooled]) => [
-      sessionId,
-      beginAbort(pooled.session),
-    ]),
-  );
-  const results = await Promise.allSettled(
-    [...aborts].map(([sessionId, abort]) =>
-      withSessionLock(sessionId, () =>
-        closePooledAgentAfterAbort(sessionId, abort),
+  if (closePromise) {
+    return closePromise;
+  }
+  if (poolState === "closed") {
+    const completed = Promise.resolve();
+    closePromise = completed;
+    return completed;
+  }
+
+  poolState = "closing";
+
+  const completion = (async () => {
+    const aborts = new Map<string, Promise<AbortOutcome>>(
+      [...agentPool].map(([sessionId, pooled]) => [
+        sessionId,
+        beginAbort(pooled.session),
+      ]),
+    );
+
+    await waitForActiveSessionLocks();
+
+    const results = await Promise.allSettled(
+      [...aborts].map(([sessionId, abort]) =>
+        withSessionLockInternal(sessionId, () =>
+          closePooledAgentAfterAbort(sessionId, abort),
+        ),
       ),
-    ),
-  );
-  const failures = results
-    .filter(
-      (result): result is PromiseRejectedResult => result.status === "rejected",
-    )
-    .map((result) => result.reason);
-  if (failures.length) {
-    throw new AggregateError(
-      failures,
-      "Failed to close one or more pooled sessions.",
     );
-  }
+    const failures = results
+      .filter(
+        (result): result is PromiseRejectedResult =>
+          result.status === "rejected",
+      )
+      .map((result) => result.reason);
+    if (failures.length) {
+      throw new AggregateError(
+        failures,
+        "Failed to close one or more pooled sessions.",
+      );
+    }
+  })();
+
+  closePromise = completion.finally(() => {
+    poolState = "closed";
+  });
+  return closePromise;
 }
 
 /** List live pooled agents. Sessions remain available until explicit close or
@@ -416,5 +532,7 @@ export function _setPoolAbortTimeoutForTesting(
 export function _resetPoolForTesting(): void {
   agentPool.clear();
   sessionLocks.clear();
+  poolState = "open";
+  closePromise = null;
   poolAbortTimeoutMs = DEFAULT_POOL_ABORT_TIMEOUT_MS;
 }

package/render-branches.ts

@@ -1,8 +1,9 @@
-import { Markdown } from "@earendil-works/pi-tui";
+import { Markdown, type MarkdownTheme } from "@earendil-works/pi-tui";
 import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
 import {
   fmtDuration,
   fmtTokens,
+  formatTaskId,
   getActivityAge,
   indent,
   tree,
@@ -17,6 +18,25 @@ import { stripAnsi, resolveCarriageReturn } from "./utils.ts";
 import { getMaxConcurrent } from "./config.ts";
 import type { TaskProgress, TaskResult } from "./types.ts";
 
+/**
+ * Render markdown output when a compatible host theme hook exists. If the host
+ * does not expose `getMarkdownTheme`, return plain text lines as a safe fallback
+ * so a single missing host hook cannot crash the renderer.
+ */
+function renderOutputLines(raw: string, width: number): string[] {
+  const trimmed = raw.trim();
+  if (!trimmed) return [];
+  try {
+    if (typeof getMarkdownTheme !== "function") return trimmed.split("\n");
+    const theme = getMarkdownTheme();
+    if (typeof theme !== "object" || !theme) return trimmed.split("\n");
+    const md = new Markdown(trimmed, 0, 0, theme as MarkdownTheme);
+    return md.render(width);
+  } catch (_error) {
+    return trimmed.split("\n");
+  }
+}
+
 /** Renderer state — the live subset of Pi's `ToolRenderContext.state`. */
 export interface RenderState {
   startedAt?: number;
@@ -88,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,
           ),
         );
@@ -107,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,
           ),
         );
@@ -127,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,
             ),
           );
@@ -210,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,
           ),
         );
@@ -241,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}`,
@@ -288,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"
@@ -303,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,
       ),
     );
@@ -365,8 +402,7 @@ export function renderFinalBranch(ctx: BranchCtx, h: RenderHelpers): void {
       let mdLines: string[] | undefined = state[cacheKey] as
         string[] | undefined;
       if (!mdLines || state[`${cacheKey}_src`] !== r.output) {
-        const md = new Markdown(r.output.trim(), 0, 0, getMarkdownTheme());
-        mdLines = md.render(Math.max(20, w - ind.length));
+        mdLines = renderOutputLines(r.output, Math.max(20, w - ind.length));
         state[`${cacheKey}_src`] = r.output;
         state[cacheKey] = mdLines;
       }

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 {