@bermudi/pi-delegate 0.1.1 → 0.1.2

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

@@ -0,0 +1,48 @@
+/**
+ * Session-tree leaf affinity for async tickets.
+ *
+ * An async ticket outlives the turn that spawned it. `/tree` navigation moves
+ * the session to a different leaf **within the same session file**: no
+ * `session_shutdown` fires, the extension runtime stays live, and the ticket
+ * keeps running. When it finishes, `deliverTicketResults` wakes the agent at
+ * whatever leaf is active *now* — which may be a branch that knows nothing
+ * about the task. See GitHub issue #30.
+ *
+ * pi exposes no "what leaf am I on?" query, so the current leaf has to be
+ * tracked from the `session_tree` event (`newLeafId`). That event also fires
+ * for extension-driven `ctx.navigateTree`, so this tracking covers navigation
+ * that never passed the `session_before_tree` confirm guard.
+ *
+ * State is runtime-scoped: `resetLeafTracking()` on session shutdown, since a
+ * replacement session starts on its own (unknown) leaf.
+ */
+import type { AsyncTicket } from "./types.ts";
+
+/** Leaf the session is currently on. `undefined` means no navigation has been
+ *  observed by this runtime — i.e. the leaf the session opened on. */
+let currentLeafId: string | null | undefined;
+
+/** Record a completed `/tree` navigation. */
+export function recordTreeNavigation(newLeafId: string | null): void {
+  currentLeafId = newLeafId;
+}
+
+/** Leaf id to stamp on a ticket at spawn time. */
+export function getCurrentLeafId(): string | null | undefined {
+  return currentLeafId;
+}
+
+export function resetLeafTracking(): void {
+  currentLeafId = undefined;
+}
+
+/** True when the session has navigated away from the leaf that spawned this
+ *  ticket, so delivering its result would wake the agent on a foreign branch.
+ *
+ *  Navigating away and back to the spawn leaf yields a fresh leaf id and is
+ *  therefore reported as cross-leaf. That false positive is deliberate: the
+ *  cross-leaf path only downgrades delivery to non-waking, and reconstructing
+ *  true leaf identity across a round trip is not worth the complexity. */
+export function isCrossLeafTicket(ticket: AsyncTicket): boolean {
+  return ticket.spawnLeafId !== currentLeafId;
+}

package/lifecycle.ts

@@ -20,12 +20,13 @@ 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";
 
 /** Internal seam for lifecycle-level tests without replacing session ownership. */
 type RunAgentSession = typeof runAgentSession;
@@ -72,6 +73,7 @@ function failTask(
   sessionFile?: string,
 ): TaskResult {
   return {
+    id: task.id,
     agent: task.agentName,
     output: "",
     error,
@@ -80,6 +82,7 @@ function failTask(
     usage: emptyUsage(),
     sessionFile,
     touchedFiles: [],
+    attributedFiles: [],
   };
 }
 
@@ -91,6 +94,7 @@ function completeSessionAction(
   elapsedMs?: number,
 ): TaskResult {
   return {
+    id: task.id,
     agent: task.agentName,
     output,
     durationMs: elapsedMs ?? 0,
@@ -98,6 +102,7 @@ function completeSessionAction(
     usage: emptyUsage(),
     sessionFile: undefined,
     touchedFiles: [],
+    attributedFiles: [],
   };
 }
 
@@ -266,6 +271,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 +283,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 +529,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,
@@ -558,12 +571,12 @@ 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."),
         );
       }
       // The per-session lock for action-based operations is already held by the
@@ -583,7 +596,7 @@ async function runResolvedTaskUnlocked(
       );
     }
 
-    if (task.action === "list") {
+    if (task.sessionAction === "list") {
       return finishTask(
         env,
         p,
@@ -599,6 +612,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 +668,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 +680,8 @@ async function runResolvedTaskUnlocked(
           env.signal,
           onProgress,
           gitBaseline,
-          Date.now(),
+          taskStartedAt,
+          deadlineAt,
         );
 
         cumulativeTokens += r.tokens;
@@ -682,7 +703,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 +724,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 +762,7 @@ async function runResolvedTaskUnlocked(
         cumulativeToolUses += attemptToolUsesObserved;
 
         return {
+          id: task.id,
           agent: task.agentName,
           output: r.output,
           error: r.error,
@@ -747,6 +782,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,9 +792,30 @@ 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,
@@ -781,7 +838,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,6 +855,11 @@ async function runResolvedTaskUnlocked(
         break;
       }
 
+      if (deadlineAt && Date.now() >= deadlineAt) {
+        result = buildDeadlineExceededResult(result);
+        break;
+      }
+
       p.status = "running";
       p.error = undefined;
       p.failureKind = undefined;

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,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: "..." }] }`.',
     '- 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.2",
   "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,
       ),
     );