@pi-unipi/fusion 2.18.1 → 2.19.1

package/README.md

@@ -92,8 +92,15 @@ persist across handoffs. The sidekick's context compacts independently of the
 lead's (it is its own pi session). `sidekick({message, block:true})` waits by
 default; `block:false` returns immediately and delivers a
 `<subagent_completion_notification>`. Calling it while busy steers the same
-handoff. `read_subagent({agent_id?, block?, timeout?})` reads or waits for a
-handoff.
+handoff. Background tasks keep that handoff open through their completion
+notification and any follow-up turn, so the report is not released at an
+intermediate checkpoint. If a prompt arrives while the child is processing,
+Fusion retries it once with pi's `followUp` streaming behavior. Sidekick work
+renders as ordinary tool activity — handoff ids, `agent_id`, and
+`read_subagent` protocol text never reach the terminal. Detached
+handoffs stay visible in a live sidekick widget above the editor until their
+completion card arrives.
+`read_subagent({agent_id?, block?, timeout?})` reads or waits for a handoff.
 
 The child receives `UNIPI_FUSION_CHILD=1` and `UNIPI_SUBAGENT_CHILD=1`; the
 Fusion extension guard prevents child processes from registering Fusion tools,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/fusion",
-  "version": "2.18.1",
+  "version": "2.19.1",
   "description": "Devin-style model picker, fusion presets (lead + sidekick), and Local Fusion runtime for UniPi",
   "type": "module",
   "main": "src/index.ts",
@@ -32,8 +32,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.18.0",
-    "@pi-unipi/subagents": "2.18.1"
+    "@pi-unipi/core": "2.19.1",
+    "@pi-unipi/subagents": "2.19.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.0",

package/src/index.ts

@@ -40,6 +40,8 @@ import { estimateSavings } from "./savings.js";
 import { EDIT_NUDGE, bashNudge, leadPolicy, sidekickSystemPrompt, type FusionIdentity } from "./prompts.js";
 import { isTrivialShell, BASH_NUDGE_EVERY } from "./nudge.js";
 import { registerFusionTools } from "./tools.js";
+import { shouldShowSidekickWidget } from "./sidekick-widget.js";
+import { frameSidekick, markdownText, renderSidekickTranscript, sidekickWorkingHeader, type ThemeLike } from "./transcript.js";
 
 export const MODEL_COMMAND = `${UNIPI_PREFIX}model`;
 export const PRESET_COMMAND = `${UNIPI_PREFIX}fusion-preset`;
@@ -118,6 +120,10 @@ export default function fusionExtension(pi: ExtensionAPI): void {
   let leadToolCalls = 0;
   let editNudgedThisTurn = false;
   let bashStreak = 0;
+  let attached = false;
+  let widgetTimer: NodeJS.Timeout | undefined;
+  let widgetTimerKind: "publish" | "clear" | undefined;
+  let widgetLastAt = 0;
 
   function identity(ctx: ExtensionContext): FusionIdentity {
     const reg = registryOf(ctx);
@@ -161,8 +167,79 @@ export default function fusionExtension(pi: ExtensionAPI): void {
     }
   }
 
+  function clearSidekickWidget(): void {
+    if (widgetTimer !== undefined) {
+      clearTimeout(widgetTimer);
+      widgetTimer = undefined;
+      widgetTimerKind = undefined;
+    }
+    const ctx = lastCtx;
+    if (!ctx?.hasUI || typeof ctx.ui.setWidget !== "function") return;
+    const clear = () => {
+      widgetTimer = undefined;
+      widgetTimerKind = undefined;
+      widgetLastAt = Date.now();
+      ctx.ui.setWidget("fusion-sidekick", undefined);
+    };
+    const wait = Math.max(0, 150 - (Date.now() - widgetLastAt));
+    if (wait === 0) clear();
+    else {
+      widgetTimerKind = "clear";
+      widgetTimer = setTimeout(clear, wait);
+      widgetTimer.unref();
+    }
+  }
+
+  function publishSidekickWidget(): void {
+    const ctx = lastCtx;
+    if (!ctx?.hasUI || typeof ctx.ui.setWidget !== "function") return;
+    const progress = runtime?.progress();
+    if (!runtime || !shouldShowSidekickWidget(runtime.isBusy(), attached) || !progress) {
+      ctx.ui.setWidget("fusion-sidekick", undefined);
+      return;
+    }
+    ctx.ui.setWidget("fusion-sidekick", (_tui, theme) => {
+      const themeLike = theme as unknown as ThemeLike & { bg: (color: string, text: string) => string };
+      return frameSidekick(themeLike, "working", renderSidekickTranscript(themeLike, {
+        events: progress.events,
+        droppedEvents: progress.droppedEvents,
+        header: sidekickWorkingHeader(themeLike, progress),
+        expanded: false,
+        isPartial: true,
+        renderText: markdownText,
+      }));
+    }, { placement: "aboveEditor" });
+  }
+
+  function publishSidekickWidgetLater(): void {
+    const ctx = lastCtx;
+    if (!ctx?.hasUI || typeof ctx.ui.setWidget !== "function") return;
+    if (widgetTimer !== undefined && widgetTimerKind === "publish") return;
+    if (widgetTimer !== undefined) {
+      clearTimeout(widgetTimer);
+      widgetTimer = undefined;
+      widgetTimerKind = undefined;
+    }
+    const wait = Math.max(0, 150 - (Date.now() - widgetLastAt));
+    const publish = () => {
+      widgetTimer = undefined;
+      widgetTimerKind = undefined;
+      widgetLastAt = Date.now();
+      publishSidekickWidget();
+    };
+    if (wait === 0) publish();
+    else {
+      widgetTimerKind = "publish";
+      widgetTimer = setTimeout(publish, wait);
+      widgetTimer.unref();
+    }
+  }
+
   function publishStatusLater(): void {
-    if (lastCtx) publishStatus(lastCtx);
+    if (lastCtx) {
+      publishStatus(lastCtx);
+      publishSidekickWidgetLater();
+    }
   }
 
   function leadSessionId(ctx: ExtensionContext): string {
@@ -186,6 +263,8 @@ export default function fusionExtension(pi: ExtensionAPI): void {
   }
 
   function stopRuntime(): void {
+    clearSidekickWidget();
+    attached = false;
     runtime?.kill();
     runtime = undefined;
     leadToolCalls = 0;
@@ -206,8 +285,20 @@ export default function fusionExtension(pi: ExtensionAPI): void {
 
   registerFusionTools(pi, {
     getRuntime,
-    onReport: (ctx) => publishStatus(ctx),
+    onReport: (ctx) => {
+      attached = false;
+      clearSidekickWidget();
+      publishStatus(ctx);
+    },
     onHandoffStart: (ctx) => publishStatus(ctx),
+    onAttach: () => {
+      attached = true;
+      clearSidekickWidget();
+    },
+    onDetach: () => {
+      attached = false;
+      publishSidekickWidgetLater();
+    },
   });
   pi.registerCommand("unipi:fusion-stats", {
     description: "Estimated Fusion savings (sidekick tokens priced at lead rates)",

package/src/sidekick-runtime.ts

@@ -15,6 +15,7 @@ export interface SidekickSpawnConfig {
   spawn?: typeof defaultSpawn;
   command?: { command: string; args: string[] };
   onProgress?: () => void;
+  settleGraceMs?: number;
 }
 
 export interface SidekickUsage {
@@ -54,11 +55,15 @@ export interface HandoffReport {
 
 interface PendingHandoff {
   id: string;
+  message: string;
   startedAt: number;
   usage: SidekickUsage;
   progress: HandoffProgress;
+  retriedPrompt: boolean;
+  openBgTasks: number;
+  settled: boolean;
+  settleTimer?: NodeJS.Timeout;
   resolve: (report: HandoffReport) => void;
-  reject: (error: Error) => void;
 }
 
 const emptyUsage = (): SidekickUsage => ({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 });
@@ -193,16 +198,35 @@ export class SidekickRuntime {
     }
   }
 
+  private requestLastAssistantText(): void {
+    const current = this.pending;
+    if (current === undefined) return;
+    this.responseText = (text) => this.finish(this.abortRequested ? "aborted" : this.pendingError === undefined ? "completed" : "error", text, this.pendingError);
+    this.responseError = (error) => this.finish("error", undefined, error.message);
+    try {
+      this.send({ type: "get_last_assistant_text" });
+    } catch (error) {
+      this.finish("error", undefined, error instanceof Error ? error.message : String(error));
+    }
+  }
+
   private handleMessage(message: Record<string, unknown>): void {
     if (message.type === "response") {
       const command = message.command;
       if (command === "prompt" && message.success === false) {
-        const error = new Error(String(message.error ?? "Sidekick prompt rejected"));
+        const errorText = String(message.error ?? "Sidekick prompt rejected");
         const current = this.pending;
-        this.pending = undefined;
-        this.responseError = undefined;
-        this.responseText = undefined;
-        current?.reject(error);
+        if (current === undefined) return;
+        if (/already processing/i.test(errorText) && !current.retriedPrompt) {
+          current.retriedPrompt = true;
+          try {
+            this.send({ id: current.id, type: "prompt", message: current.message, streamingBehavior: "followUp" });
+          } catch (error) {
+            this.finish("error", undefined, error instanceof Error ? error.message : String(error));
+          }
+        } else {
+          this.finish("error", undefined, errorText);
+        }
       } else if (command === "get_last_assistant_text") {
         const data = message.data as Record<string, unknown> | undefined;
         const text = typeof data?.text === "string" ? data.text : this.pending?.progress.textTail ?? "";
@@ -224,6 +248,7 @@ export class SidekickRuntime {
       this.closeOpenText();
       this.pending.progress.toolCalls += 1;
       const args = message.args !== undefined && typeof message.args === "object" && message.args !== null ? message.args as Record<string, unknown> : undefined;
+      if (message.toolName === "bg_run" && args?.notifyOnCompletion !== false && args?.triggerOnCompletion !== false) this.pending.openBgTasks += 1;
       const argsText = args === undefined ? "" : JSON.stringify(args).replace(/\s+/gu, " ");
       const summary = `${String(message.toolName ?? "tool")}(${argsText})`.slice(0, 40);
       this.pending.progress.recentTools = [...this.pending.progress.recentTools, summary].slice(-6);
@@ -237,6 +262,7 @@ export class SidekickRuntime {
         event.endedAt = Date.now();
         event.isError = message.isError === true;
         event.output = this.toolOutput(message.result);
+        if (event.name === "bg_run" && event.isError) this.pending.openBgTasks = Math.max(0, this.pending.openBgTasks - 1);
       }
       this.notifyProgress();
     } else if (message.type === "message_update") {
@@ -251,7 +277,19 @@ export class SidekickRuntime {
       }
     } else if (message.type === "message_end") {
       const msg = message.message as Record<string, unknown> | undefined;
-      if (msg?.role === "assistant") {
+      if (msg?.role === "custom" && msg.customType === "background-task-notification") {
+        this.pending.openBgTasks = Math.max(0, this.pending.openBgTasks - 1);
+        if (this.pending.openBgTasks === 0 && this.pending.settled) {
+          clearTimeout(this.pending.settleTimer);
+          this.pending.settleTimer = setTimeout(() => {
+            const current = this.pending;
+            if (current === undefined || !current.settled || current.openBgTasks > 0) return;
+            this.requestLastAssistantText();
+          }, this.cfg.settleGraceMs ?? 3000);
+          this.pending.settleTimer.unref();
+        }
+        this.notifyProgress();
+      } else if (msg?.role === "assistant") {
         this.closeOpenText();
         this.notifyProgress();
         if (msg.stopReason === "error" && typeof msg.errorMessage === "string") this.pendingError = msg.errorMessage;
@@ -267,16 +305,18 @@ export class SidekickRuntime {
           });
         }
       }
+    } else if (message.type === "agent_start") {
+      clearTimeout(this.pending.settleTimer);
+      this.pending.settleTimer = undefined;
+      this.pending.settled = false;
+      this.notifyProgress();
     } else if (message.type === "agent_settled") {
-      this.responseText = undefined;
-      this.responseError = undefined;
-      this.responseText = (text) => this.finish(this.abortRequested ? "aborted" : this.pendingError === undefined ? "completed" : "error", text, this.pendingError);
-      this.responseError = (error) => this.finish("error", undefined, error.message);
-      try {
-        this.send({ type: "get_last_assistant_text" });
-      } catch (error) {
-        this.finish("error", undefined, error instanceof Error ? error.message : String(error));
+      this.pending.settled = true;
+      if (this.pending.openBgTasks > 0) {
+        this.notifyProgress();
+        return;
       }
+      this.requestLastAssistantText();
     }
   }
 
@@ -293,6 +333,8 @@ export class SidekickRuntime {
   private finish(status: HandoffReport["status"], text?: string, error?: string): void {
     const current = this.pending;
     if (current === undefined) return;
+    clearTimeout(current.settleTimer);
+    current.settleTimer = undefined;
     this.pending = undefined;
     this.responseText = undefined;
     this.responseError = undefined;
@@ -323,19 +365,20 @@ export class SidekickRuntime {
     const id = randomUUID();
     const startedAt = Date.now();
     let resolve!: (report: HandoffReport) => void;
-    let reject!: (error: Error) => void;
-    const done = new Promise<HandoffReport>((res, rej) => {
+    const done = new Promise<HandoffReport>((res) => {
       resolve = res;
-      reject = rej;
     });
     this.pendingError = undefined;
     this.pending = {
       id,
+      message,
       startedAt,
       usage: emptyUsage(),
       progress: { toolCalls: 0, recentTools: [], textTail: "", startedAt, events: [], droppedEvents: 0 },
+      retriedPrompt: false,
+      openBgTasks: 0,
+      settled: false,
       resolve,
-      reject,
     };
     this.latestHandoff = { id, done };
     try {

package/src/sidekick-widget.ts

@@ -0,0 +1,3 @@
+export function shouldShowSidekickWidget(busy: boolean, attached: boolean): boolean {
+  return busy && !attached;
+}

package/src/tools.ts

@@ -1,8 +1,8 @@
-import { Markdown, Text, type Component } from "@earendil-works/pi-tui";
-import { getMarkdownTheme, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text, type Component } from "@earendil-works/pi-tui";
+import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import type { SidekickRuntime, HandoffProgress, HandoffReport } from "./sidekick-runtime.js";
-import { frameSidekick, renderSidekickTranscript, type ThemeLike as TranscriptTheme } from "./transcript.js";
+import { duration, markdownText, renderSidekickTranscript, sidekickWorkingHeader } from "./transcript.js";
 
 const SidekickParams = Type.Object({
   message: Type.String({ description: "A concrete implementation or verification brief for the sidekick" }),
@@ -18,10 +18,8 @@ export interface FusionToolDeps {
   getRuntime: (ctx: ExtensionContext) => SidekickRuntime | undefined;
   onReport?: (ctx: ExtensionContext, report: HandoffReport) => void;
   onHandoffStart?: (ctx: ExtensionContext) => void;
-}
-
-function duration(ms: number): string {
-  return `${(ms / 1000).toFixed(1)}s`;
+  onAttach?: (ctx: ExtensionContext) => void;
+  onDetach?: (ctx: ExtensionContext) => void;
 }
 
 function firstLine(value: string): string {
@@ -60,7 +58,7 @@ async function waitForReport(
   ctx: ExtensionContext,
   onUpdate?: (update: unknown) => void,
   timeoutMs = 2700000,
-): Promise<{ report?: HandoffReport; interrupted?: string; aborted?: boolean }> {
+): Promise<{ report?: HandoffReport; interrupted?: string; aborted?: boolean; error?: string }> {
   const started = Date.now();
   let lastProgressKey = "";
   while (true) {
@@ -72,8 +70,14 @@ async function waitForReport(
     const remaining = timeoutMs - (Date.now() - started);
     if (remaining <= 0) return {};
     const timer = new Promise<undefined>((resolve) => setTimeout(() => resolve(undefined), Math.min(500, remaining)));
-    const report = await Promise.race([done, timer]);
-    if (report !== undefined) return { report };
+    const outcome = await Promise.race([
+      done.then((report) => ({ report }), (error) => ({ error: error instanceof Error ? error.message : String(error) })),
+      timer,
+    ]);
+    if (outcome !== undefined) {
+      if ("error" in outcome) return { error: outcome.error };
+      return { report: outcome.report };
+    }
     const progress = progressText(runtime, id);
     const key = progressKey(runtime, id);
     if (key !== lastProgressKey) {
@@ -94,16 +98,26 @@ function completionMessage(report: HandoffReport): { customType: string; content
 
 type ThemeLike = {
   fg: (color: string, text: string) => string;
-  bg: (color: string, text: string) => string;
   bold: (text: string) => string;
 };
 
-function transcriptTheme(theme: ThemeLike): TranscriptTheme {
-  return { fg: (color, text) => theme.fg(color, text), bold: (text) => theme.bold(text) };
-}
-
-function markdownText(markdown: string): Markdown {
-  return new Markdown(markdown, 0, 0, getMarkdownTheme());
+// Model-facing result text carries handoff ids and protocol instructions the
+// lead needs; none of it may reach the terminal. Anything rendered as plain
+// content goes through this first.
+const HANDOFF_ID = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi;
+function displayText(text: string): string {
+  return text
+    .replace(/<\/?subagent_completion_notification[^>]*>/g, "")
+    .replace(/use `?read_subagent`?[^.\n]*\.?/gi, "")
+    .replace(HANDOFF_ID, "")
+    .replace(/agent_id[ =]?"?"?/g, "")
+    .replace(/read_subagent\([^)]*\)/g, "read_subagent")
+    .replace(/\(\s*\)/g, "")
+    .replace(/[ \t]{2,}/g, " ")
+    .replace(/\bHandoff\s*(?=(is|was|failed|aborted|started)\b)/g, "The handoff ")
+    .replace(/ for\s*\./g, ".")
+    .replace(/ +$/gm, "")
+    .trim();
 }
 
 function contentText(content: unknown): string {
@@ -111,18 +125,29 @@ function contentText(content: unknown): string {
   return content.map((part) => typeof part === "object" && part !== null && typeof (part as { text?: unknown }).text === "string" ? (part as { text: string }).text : "").filter(Boolean).join("\n");
 }
 
+function backgroundComponent(theme: ThemeLike): Component {
+  return new Text(`${theme.fg("accent", theme.bold("◆ sidekick"))} ${theme.fg("dim", "· continuing in background")}`, 0, 0);
+}
+
+type ToolDetails = Partial<HandoffReport> & { progress?: HandoffProgress; background?: boolean; id?: string };
+
+function reportHeader(theme: ThemeLike, label: string, report: HandoffReport | undefined): string {
+  const status = report?.status ?? "done";
+  return `${theme.fg(status === "completed" ? "success" : "error", "◆")} ${theme.fg("accent", theme.bold(`${label} ${status}`))} ${theme.fg("dim", report ? `· ${String(report.toolCalls)} tool calls · ${duration(report.durationMs)} · in ${String(report.usage.input)} / out ${String(report.usage.output)} tokens` : "")}`;
+}
+
 function renderToolTranscript(result: { content?: unknown; details?: unknown; isError?: boolean }, options: { expanded?: boolean }, theme: ThemeLike, label: "sidekick" | "read_subagent"): Component {
-  const details = result.details as (HandoffReport & { progress?: HandoffProgress }) | { progress?: HandoffProgress } | undefined;
+  const details = result.details as ToolDetails | undefined;
+  if (details?.background === true) return backgroundComponent(theme);
+  const hasProgress = details !== undefined && "progress" in details;
   const progress = details?.progress;
+  if (hasProgress && progress === undefined) return backgroundComponent(theme);
   const report = progress ? undefined : details as HandoffReport | undefined;
   const events = progress?.events ?? report?.events;
   const partial = progress !== undefined;
-  const status = partial ? "working" : report?.status === "completed" && !result.isError ? "completed" : "error";
-  if (!events) return frameSidekick(theme, status, new Text(contentText(result.content), 0, 0));
-  const header = partial
-    ? `${theme.fg("accent", theme.bold(`◆ ${label} working`))} ${theme.fg("dim", `· ${String(progress.toolCalls)} tool calls · ${duration(Date.now() - progress.startedAt)}`)}`
-    : `${theme.fg(report?.status === "completed" ? "success" : "error", "◆")} ${theme.fg("accent", theme.bold(`${label} ${report?.status ?? "done"}`))} ${theme.fg("dim", report ? `· ${report.id} · ${String(report.toolCalls)} tool calls · ${duration(report.durationMs)} · in ${String(report.usage.input)} / out ${String(report.usage.output)} tokens` : "")}`;
-  return frameSidekick(theme, status, renderSidekickTranscript(transcriptTheme(theme), {
+  if (!events) return new Text(displayText(contentText(result.content)), 0, 0);
+  const header = partial ? sidekickWorkingHeader(theme, progress, label) : reportHeader(theme, label, report);
+  return renderSidekickTranscript(theme, {
     events,
     droppedEvents: progress?.droppedEvents,
     header,
@@ -130,20 +155,19 @@ function renderToolTranscript(result: { content?: unknown; details?: unknown; is
     isPartial: partial,
     report,
     renderText: markdownText,
-  }));
+  });
 }
 
 function renderCompletionCard(theme: ThemeLike, report: HandoffReport | undefined): Component {
-  const status = report?.status === "completed" ? "completed" : "error";
-  if (!report) return frameSidekick(theme, "error", new Text(`${theme.fg("accent", "◆")} ${theme.fg("accent", theme.bold("sidekick done"))}`, 0, 0));
-  return frameSidekick(theme, status, renderSidekickTranscript(transcriptTheme(theme), {
+  if (!report) return new Text(`${theme.fg("accent", "◆")} ${theme.fg("accent", theme.bold("sidekick done"))}`, 0, 0);
+  return renderSidekickTranscript(theme, {
     events: report.events ?? [],
-    header: `${theme.fg(report.status === "completed" ? "success" : "error", "◆")} ${theme.fg("accent", theme.bold(`sidekick ${report.status}`))} ${theme.fg("dim", `· ${report.id} · ${String(report.toolCalls)} tool calls · ${duration(report.durationMs)}`)}`,
+    header: reportHeader(theme, "sidekick", report),
     expanded: false,
     isPartial: false,
     report,
     renderText: markdownText,
-  }));
+  });
 }
 
 export function registerFusionTools(pi: ExtensionAPI, deps: FusionToolDeps): void {
@@ -155,7 +179,7 @@ export function registerFusionTools(pi: ExtensionAPI, deps: FusionToolDeps): voi
     description: "Hand off work to your persistent sidekick subagent (one per session; context and shells persist across handoffs; runs on the same machine). block:true (default) waits and returns the report. block:false returns immediately and the report arrives later as a <subagent_completion_notification>. Calling again while a handoff is running injects the message as an interrupt rather than starting a second sidekick.",
     parameters: SidekickParams,
     renderShell: "self",
-    renderCall: (args, theme) => frameSidekick(theme as unknown as ThemeLike, "working", new Text(`${theme.fg("toolTitle", theme.bold("◆ sidekick"))} ${theme.fg("dim", firstLine(String(args.message)).slice(0, 100))}`, 0, 0)),
+    renderCall: (args, theme) => new Text(`${theme.fg("toolTitle", theme.bold("◆ sidekick"))} ${theme.fg("dim", firstLine(String(args.message)).slice(0, 100))}`, 0, 0),
     renderResult: (result, options, theme) => renderToolTranscript(result, options, theme as unknown as ThemeLike, "sidekick"),
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
       const runtime = deps.getRuntime(ctx);
@@ -168,16 +192,20 @@ export function registerFusionTools(pi: ExtensionAPI, deps: FusionToolDeps): voi
           deps.onReport?.(ctx, report);
           pi.sendMessage(completionMessage(report) as never, { deliverAs: "followUp", triggerTurn: true } as never);
         }).catch(() => undefined);
-        return result(`Handoff ${handoff.id} started in the background. You will receive a <subagent_completion_notification agent_id="${handoff.id}"> when it finishes; use read_subagent to wait.`);
+        deps.onDetach?.(ctx);
+        return result(`Handoff ${handoff.id} started in the background. You will receive a <subagent_completion_notification agent_id="${handoff.id}"> when it finishes; use read_subagent to wait.`, { background: true, id: handoff.id });
       }
+      deps.onAttach?.(ctx);
       const waited = await waitForReport(runtime, handoff.id, handoff.done, signal, ctx, onUpdate ? (update) => onUpdate(update as never) : undefined);
       if (waited.report) {
         deps.onReport?.(ctx, waited.report);
         return result(reportText(waited.report), waited.report, waited.report.status !== "completed");
       }
+      deps.onDetach?.(ctx);
+      if (waited.error) return result(`Handoff ${handoff.id} failed: ${waited.error}`, undefined, true);
       if (waited.aborted) return result(`${progressText(runtime, handoff.id)}\nHandoff ${handoff.id} aborted.`, undefined, true);
-      if (waited.interrupted) return result(`A user message arrived while the sidekick (agent_id ${handoff.id}) was working. The handoff continues in the background. Act on the user's message first, then call read_subagent({agent_id:"${handoff.id}", block:true}) to collect the report or sidekick({message}) to redirect it.\n${waited.interrupted}`);
-      return result(`Handoff ${handoff.id} is still running.\n${progressText(runtime, handoff.id)}`);
+      if (waited.interrupted) return result(`A user message arrived while the sidekick (agent_id ${handoff.id}) was working. The handoff continues in the background. Act on the user's message first, then call read_subagent({agent_id:"${handoff.id}", block:true}) to collect the report or sidekick({message}) to redirect it.\n${waited.interrupted}`, { progress: runtime.progress(handoff.id), id: handoff.id });
+      return result(`Handoff ${handoff.id} is still running.\n${progressText(runtime, handoff.id)}`, { progress: runtime.progress(handoff.id), id: handoff.id });
     },
   });
 
@@ -187,7 +215,7 @@ export function registerFusionTools(pi: ExtensionAPI, deps: FusionToolDeps): voi
     description: "Read a sidekick handoff report by agent_id (omit for the latest). block:true waits for completion (default timeout 2700s when omitted); block:false returns the current progress snapshot immediately.",
     parameters: ReadSubagentParams,
     renderShell: "self",
-    renderCall: (args, theme) => frameSidekick(theme as unknown as ThemeLike, "working", new Text(`${theme.fg("toolTitle", theme.bold("◆ read_subagent"))} ${theme.fg("dim", args.agent_id ?? "latest")}`, 0, 0)),
+    renderCall: (args, theme) => new Text(`${theme.fg("toolTitle", theme.bold("◆ read_subagent"))} ${theme.fg("dim", args.block === false ? "· snapshot" : "· waiting")}`, 0, 0),
     renderResult: (result, options, theme) => renderToolTranscript(result, options, theme as unknown as ThemeLike, "read_subagent"),
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
       const runtime = deps.getRuntime(ctx);
@@ -198,16 +226,19 @@ export function registerFusionTools(pi: ExtensionAPI, deps: FusionToolDeps): voi
       const selected = runtime.reports.get(id);
       if (selected) return result(reportText(selected), selected, selected.status !== "completed");
       if (id !== latest.id) return result(`No sidekick handoff found for ${id}.`, undefined, true);
-      if (params.block !== true) return result(`Handoff ${id} is still running.\n${progressText(runtime, id)}`);
+      if (params.block !== true) return result(`Handoff ${id} is still running.\n${progressText(runtime, id)}`, { progress: runtime.progress(id), id });
+      deps.onAttach?.(ctx);
       const timeoutMs = (params.timeout ?? 2700) * 1000;
       const waited = await waitForReport(runtime, id, latest.done, signal, ctx, onUpdate ? (update) => onUpdate(update as never) : undefined, timeoutMs);
       if (waited.report) {
         deps.onReport?.(ctx, waited.report);
         return result(reportText(waited.report), waited.report, waited.report.status !== "completed");
       }
+      deps.onDetach?.(ctx);
+      if (waited.error) return result(`Handoff ${id} failed: ${waited.error}`, undefined, true);
       if (waited.aborted) return result(`Handoff ${id} aborted.`, undefined, true);
-      if (waited.interrupted) return result(`A user message arrived while the sidekick (agent_id ${id}) was working.\n${waited.interrupted}`);
-      return result(`Handoff ${id} is still running.\n${progressText(runtime, id)}`);
+      if (waited.interrupted) return result(`A user message arrived while the sidekick (agent_id ${id}) was working.\n${waited.interrupted}`, { progress: runtime.progress(id), id });
+      return result(`Handoff ${id} is still running.\n${progressText(runtime, id)}`, { progress: runtime.progress(id), id });
     },
   });
 

package/src/transcript.ts

@@ -1,11 +1,24 @@
-import { Box, Container, Text, type Component } from "@earendil-works/pi-tui";
-import type { SidekickEvent } from "./sidekick-runtime.js";
+import { Box, Container, Markdown, Text, type Component } from "@earendil-works/pi-tui";
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import type { HandoffProgress, SidekickEvent } from "./sidekick-runtime.js";
 
 export interface ThemeLike {
   fg: (color: string, text: string) => string;
   bold: (text: string) => string;
 }
 
+export function duration(ms: number): string {
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+export function markdownText(markdown: string): Component {
+  return new Markdown(markdown, 0, 0, getMarkdownTheme());
+}
+
+export function sidekickWorkingHeader(theme: ThemeLike, progress: Pick<HandoffProgress, "toolCalls" | "startedAt">, label = "sidekick"): string {
+  return `${theme.fg("accent", theme.bold(`◆ ${label} working`))} ${theme.fg("dim", `· ${String(progress.toolCalls)} tool calls · ${duration(Date.now() - progress.startedAt)}`)}`;
+}
+
 export class RailComponent implements Component {
   constructor(private readonly inner: Component, private readonly rail: string) {}