pi-better-background-tasks 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",

package/src/runtime.ts

@@ -4,6 +4,7 @@ import { appendLine, appendWatchResult, retainLogTail, resolveMaxLogBytes } from
 import { evaluateCondition } from "./conditions.js";
 import { processExists, runCommandOnce, spawnCommand, stopProcessGroup } from "./process.js";
 import { ensureTaskDir, logPathFor, nextTaskId, readMeta, writeMeta } from "./registry.js";
+import { getCallbackBatcher } from "./shared-callback-batcher.js";
 import type { BackgroundTaskCallbackOrigin, BackgroundTaskMeta, CommandSpec, Condition, TerminalResult } from "./types.js";
 import { isTerminalStatus } from "./types.js";
 
@@ -304,24 +305,37 @@ async function notifyTerminal(
   if (meta.callback === false || meta.callbackSentAt || meta.callbackSuppressedAt) return;
   const latest = readMeta(meta.id) ?? meta;
   if (latest.callback === false || latest.callbackSentAt || latest.callbackSuppressedAt) return;
-  const suppressionReason = getCallbackSuppressionReason(latest, getActiveSession?.());
-  if (suppressionReason) {
-    latest.callbackSuppressedAt = Date.now();
-    latest.callbackSuppressedReason = suppressionReason;
-    writeMeta(latest);
-    return;
-  }
   const label = latest.name ? `${latest.name} (${latest.id})` : latest.id;
-  try {
-    await pi.sendUserMessage(
-      `Background task ${label} reached terminal status ${latest.status}. Inspect the compact result with bg_task_status id=${latest.id}; call bg_task_log only if the status summary is insufficient.`,
-      { deliverAs: "followUp" },
-    );
-    latest.callbackSentAt = Date.now();
-    writeMeta(latest);
-  } catch {
-    // Leave callbackSentAt unset so the originating session can attempt delivery once.
-  }
+  getCallbackBatcher(pi).enqueue({
+    source: "background-task",
+    id: latest.id,
+    label,
+    status: latest.status,
+    detailTool: "bg_task_status",
+    callback: true,
+    isDelivered: () => {
+      const current = readMeta(latest.id);
+      return current?.callbackSentAt !== undefined || current?.callbackSuppressedAt !== undefined;
+    },
+    getSuppressionReason: () => {
+      const current = readMeta(latest.id);
+      if (!current) return "background task metadata is unavailable";
+      return getCallbackSuppressionReason(current, getActiveSession?.());
+    },
+    onDelivered: (at) => {
+      const current = readMeta(latest.id);
+      if (!current || current.callbackSentAt !== undefined || current.callbackSuppressedAt !== undefined) return;
+      current.callbackSentAt = at;
+      writeMeta(current);
+    },
+    onSuppressed: (reason, at) => {
+      const current = readMeta(latest.id);
+      if (!current || current.callbackSentAt !== undefined || current.callbackSuppressedAt !== undefined) return;
+      current.callbackSuppressedAt = at;
+      current.callbackSuppressedReason = reason;
+      writeMeta(current);
+    },
+  });
 }
 
 function getCallbackSuppressionReason(

package/src/shared-callback-batcher.ts

@@ -0,0 +1,320 @@
+// Generated from packages/callback-batcher/index.ts. Do not edit directly.
+export type CallbackSource = "subagent" | "background-task";
+export type CallbackDetailTool = "subagent_result" | "bg_task_status";
+
+export interface CallbackBatchHost {
+  sendMessage(
+    message: { customType: string; content: string; display: boolean },
+    options: Record<string, unknown>,
+  ): unknown;
+}
+
+export interface CallbackBatchEvent {
+  source: CallbackSource;
+  id: string;
+  label: string;
+  status: string;
+  detailTool: CallbackDetailTool;
+  callback?: boolean;
+  isDelivered?: () => boolean;
+  getSuppressionReason?: () => string | undefined;
+  onDelivered?: (at: number) => void;
+  onSuppressed?: (reason: string, at: number) => void;
+}
+
+export interface UrgentCallbackEvent {
+  source: CallbackSource;
+  id: string;
+  label: string;
+  status: "orphaned" | "lost" | string;
+  customType: string;
+  content: string;
+  isDelivered?: () => boolean;
+  getSuppressionReason?: () => string | undefined;
+  onDelivered?: (at: number) => void;
+  onSuppressed?: (reason: string, at: number) => void;
+}
+
+export interface CallbackBatcherOptions {
+  windowMs?: number;
+  retryMs?: number;
+}
+
+export interface CallbackBatcher {
+  enqueue(event: CallbackBatchEvent): boolean;
+  flush(): Promise<boolean>;
+  deliverUrgent(event: UrgentCallbackEvent): boolean | Promise<boolean>;
+  cancel(): void;
+  pendingCount(): number;
+}
+
+interface PendingEvent {
+  event: CallbackBatchEvent;
+  sequence: number;
+}
+
+interface SharedCallbackBatcherState {
+  byHost: WeakMap<object, CallbackBatcher>;
+}
+
+const GLOBAL_STATE_KEY = Symbol.for("@1aboveio/pi-better-harness/callback-batcher");
+const DEFAULT_WINDOW_MS = 100;
+const DEFAULT_RETRY_MS = 1_000;
+const MAX_LABEL_CHARS = 160;
+const MAX_ID_CHARS = 200;
+const MAX_STATUS_CHARS = 80;
+
+export const CALLBACK_BATCH_WINDOW_ENV = "PI_BETTER_CALLBACK_BATCH_MS";
+export const DEFAULT_CALLBACK_BATCH_WINDOW_MS = DEFAULT_WINDOW_MS;
+
+export function resolveCallbackBatchWindowMs(
+  value: unknown = process.env[CALLBACK_BATCH_WINDOW_ENV],
+): number {
+  if (value === undefined || value === null || value === "") return DEFAULT_WINDOW_MS;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return DEFAULT_WINDOW_MS;
+  return Math.max(0, Math.min(5_000, Math.floor(parsed)));
+}
+
+export function formatCallbackBatch(events: readonly CallbackBatchEvent[]): string {
+  const count = events.length;
+  const heading = `${count} background completion${count === 1 ? " is" : "s are"} ready:`;
+  const rows = events.map((event) => {
+    const source = boundedField(event.source, 40);
+    const id = boundedField(event.id, MAX_ID_CHARS);
+    const label = boundedField(event.label, MAX_LABEL_CHARS);
+    const status = boundedField(event.status, MAX_STATUS_CHARS);
+    const detail = event.detailTool === "bg_task_status"
+      ? `bg_task_status id=${id}`
+      : `subagent_result id=${JSON.stringify(id)}`;
+    return `- source=${source} | id=${id} | label=${JSON.stringify(label)} | status=${status} | inspect: ${detail}`;
+  });
+  return [
+    heading,
+    ...rows,
+    "Retrieve durable results/status with the listed tools. Full results and logs are intentionally omitted.",
+  ].join("\n");
+}
+
+export function createCallbackBatcher(
+  host: CallbackBatchHost,
+  options: CallbackBatcherOptions = {},
+): CallbackBatcher {
+  const windowMs = options.windowMs ?? resolveCallbackBatchWindowMs();
+  const retryMs = Math.max(0, options.retryMs ?? DEFAULT_RETRY_MS);
+  const pending = new Map<string, PendingEvent>();
+  const inFlight = new Set<string>();
+  const urgentInFlight = new Set<string>();
+  let sequence = 0;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let flushPromise: Promise<boolean> | undefined;
+
+  const cancelTimer = (): void => {
+    if (timer) clearTimeout(timer);
+    timer = undefined;
+  };
+
+  const schedule = (delayMs: number): void => {
+    if (timer || pending.size === 0) return;
+    timer = setTimeout(() => {
+      timer = undefined;
+      void api.flush();
+    }, Math.max(0, delayMs));
+    timer.unref?.();
+  };
+
+  const enqueue = (event: CallbackBatchEvent): boolean => {
+    if (event.callback === false) return false;
+    const key = eventKey(event);
+    if (pending.has(key) || inFlight.has(key)) return false;
+    pending.set(key, { event, sequence: sequence++ });
+    schedule(windowMs);
+    return true;
+  };
+
+  const performFlush = async (): Promise<boolean> => {
+    cancelTimer();
+    const snapshot = [...pending.entries()]
+      .sort((a, b) => a[1].sequence - b[1].sequence);
+    pending.clear();
+    for (const [key] of snapshot) inFlight.add(key);
+
+    const deliverable: Array<[string, PendingEvent]> = [];
+    for (const item of snapshot) {
+      const [key, pendingEvent] = item;
+      const disposition = eventDisposition(pendingEvent.event);
+      if (disposition.kind === "delivered") {
+        inFlight.delete(key);
+        continue;
+      }
+      if (disposition.kind === "suppressed") {
+        invokeSuppressed(pendingEvent.event, disposition.reason, Date.now());
+        inFlight.delete(key);
+        continue;
+      }
+      deliverable.push(item);
+    }
+
+    if (deliverable.length === 0) {
+      if (pending.size > 0) schedule(windowMs);
+      return true;
+    }
+
+    try {
+      await host.sendMessage(
+        {
+          customType: "background-completion-batch",
+          content: formatCallbackBatch(deliverable.map(([, item]) => item.event)),
+          display: true,
+        },
+        { deliverAs: "followUp", triggerTurn: true },
+      );
+    } catch {
+      for (const [key] of deliverable) inFlight.delete(key);
+      const retryItems = [...deliverable, ...pending.entries()]
+        .sort((a, b) => a[1].sequence - b[1].sequence);
+      pending.clear();
+      for (const [key, item] of retryItems) {
+        if (!pending.has(key)) pending.set(key, item);
+      }
+      schedule(retryMs);
+      return false;
+    }
+
+    const deliveredAt = Date.now();
+    for (const [key, item] of deliverable) {
+      invokeDelivered(item.event, deliveredAt);
+      inFlight.delete(key);
+    }
+    if (pending.size > 0) schedule(windowMs);
+    return true;
+  };
+
+  const flush = (): Promise<boolean> => {
+    if (flushPromise) return flushPromise;
+    flushPromise = performFlush().finally(() => {
+      flushPromise = undefined;
+    });
+    return flushPromise;
+  };
+
+  const deliverUrgent = (event: UrgentCallbackEvent): boolean | Promise<boolean> => {
+    const key = eventKey(event);
+    if (urgentInFlight.has(key)) return false;
+    const disposition = eventDisposition(event);
+    if (disposition.kind === "delivered") return true;
+    if (disposition.kind === "suppressed") {
+      invokeSuppressed(event, disposition.reason, Date.now());
+      return true;
+    }
+
+    urgentInFlight.add(key);
+    try {
+      const handoff = host.sendMessage(
+        { customType: event.customType, content: event.content, display: true },
+        { deliverAs: "followUp", triggerTurn: true },
+      );
+      if (isPromiseLike(handoff)) {
+        return Promise.resolve(handoff).then(
+          () => {
+            invokeDelivered(event, Date.now());
+            return true;
+          },
+          () => false,
+        ).finally(() => urgentInFlight.delete(key));
+      }
+      invokeDelivered(event, Date.now());
+      urgentInFlight.delete(key);
+      return true;
+    } catch {
+      urgentInFlight.delete(key);
+      return false;
+    }
+  };
+
+  const api: CallbackBatcher = {
+    enqueue,
+    flush,
+    deliverUrgent,
+    cancel() {
+      cancelTimer();
+      pending.clear();
+    },
+    pendingCount() {
+      return pending.size;
+    },
+  };
+  return api;
+}
+
+export function getCallbackBatcher(
+  host: CallbackBatchHost,
+  options: CallbackBatcherOptions = {},
+): CallbackBatcher {
+  const state = globalState();
+  const key = host as object;
+  const existing = state.byHost.get(key);
+  if (existing) return existing;
+  const created = createCallbackBatcher(host, options);
+  state.byHost.set(key, created);
+  return created;
+}
+
+export function cancelCallbackBatch(host: CallbackBatchHost): void {
+  globalState().byHost.get(host as object)?.cancel();
+}
+
+function globalState(): SharedCallbackBatcherState {
+  const root = globalThis as typeof globalThis & {
+    [GLOBAL_STATE_KEY]?: SharedCallbackBatcherState;
+  };
+  root[GLOBAL_STATE_KEY] ??= { byHost: new WeakMap<object, CallbackBatcher>() };
+  return root[GLOBAL_STATE_KEY];
+}
+
+function eventKey(event: Pick<CallbackBatchEvent, "source" | "id" | "status">): string {
+  return `${event.source}\u0000${event.id}\u0000${event.status}`;
+}
+
+function eventDisposition(
+  event: Pick<CallbackBatchEvent, "isDelivered" | "getSuppressionReason">,
+): { kind: "deliver" } | { kind: "delivered" } | { kind: "suppressed"; reason: string } {
+  try {
+    if (event.isDelivered?.()) return { kind: "delivered" };
+  } catch {
+    return { kind: "suppressed", reason: "durable delivery state could not be verified" };
+  }
+  try {
+    const reason = event.getSuppressionReason?.();
+    return reason ? { kind: "suppressed", reason } : { kind: "deliver" };
+  } catch {
+    return { kind: "suppressed", reason: "callback ownership could not be verified" };
+  }
+}
+
+function invokeDelivered(
+  event: Pick<CallbackBatchEvent, "onDelivered">,
+  at: number,
+): void {
+  try { event.onDelivered?.(at); } catch { /* handoff already succeeded */ }
+}
+
+function invokeSuppressed(
+  event: Pick<CallbackBatchEvent, "onSuppressed">,
+  reason: string,
+  at: number,
+): void {
+  try { event.onSuppressed?.(reason, at); } catch { /* best effort durable suppression */ }
+}
+
+function boundedField(value: unknown, maxChars: number): string {
+  const oneLine = String(value ?? "").replace(/\s+/g, " ").trim();
+  if (oneLine.length <= maxChars) return oneLine;
+  return `${oneLine.slice(0, Math.max(0, maxChars - 3))}...`;
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (typeof value === "object" || typeof value === "function")
+    && value !== null
+    && typeof (value as PromiseLike<unknown>).then === "function";
+}

package/src/shared-navigator.ts

@@ -39,6 +39,11 @@ export type BackgroundWorkDetail = {
   metadata: Array<{ label: string; value: string }>;
   foldedSections?: Array<{ id: string; label: string; text: string; collapsedText?: string; expandedByDefault?: boolean }>;
   evidence: { label: string; text: string };
+  transcript?: Array<
+    | { type: "assistant"; content: Array<{ type: string; text?: string; thinking?: string }>; streaming: boolean }
+    | { type: "tool"; id?: string; name: string; args?: unknown; result?: unknown; isError: boolean; state: "running" | "completed" }
+  >;
+  transcriptDiagnostic?: string;
   footerActions?: string[];
 };
 
@@ -54,6 +59,8 @@ export type BackgroundWorkProvider = {
   label: string;
   priority: number;
   visibleCount(): number;
+  showSection?(rows: BackgroundWorkRow[], now: number): boolean;
+  parentRow?(now: number): BackgroundWorkRow | null;
   listRows(now: number): BackgroundWorkRow[];
   detail(id: string, now: number, options?: { logTailLines?: number }): BackgroundWorkDetail | null;
   armCloseLabel(row: BackgroundWorkRow): string;
@@ -66,6 +73,7 @@ type HostDeps = {
   isOpenTrigger: (data: string) => boolean;
   matchKey: (data: string, keyId: string) => boolean;
   truncate: (s: string, width: number) => string;
+  createTranscriptComponent?: (detail: BackgroundWorkDetail, theme: unknown) => Component;
 };
 
 type NavigatorState = {
@@ -82,6 +90,7 @@ type NavigatorState = {
   mainListCloseArm?: { id: string; armedAt: number };
   mainListCloseArmTimer?: ReturnType<typeof setTimeout>;
   mainListDeadlineScheduler?: RenderScheduler;
+  editorComponent?: Component;
   detailOverlayRows?: number;
   dispose?: () => void;
 };
@@ -98,8 +107,7 @@ export const CLOSE_ARM_MS = 3000;
 export const DEFAULT_LOG_TAIL_ROWS = 10;
 export const LOG_TAIL_ROW_CHOICES = [10, 25] as const;
 const MAIN_LIST_FALLBACK_WIDTH = 100;
-const DETAIL_OVERLAY_HEADER_MARGIN_ROWS = 5;
-const DETAIL_OVERLAY_FOOTER_MARGIN_ROWS = 3;
+const DETAIL_OVERLAY_FOOTER_ROWS = 3;
 const EVIDENCE_SECTION_ID = "__evidence__";
 const RUNNING_DOT_GLYPH = "●";
 const RUNNING_DOT_FRAMES = ["dim", "accent", "accent", "dim"] as const;
@@ -314,7 +322,7 @@ function renderWidth(width: number): number {
   return Number.isFinite(width) && width > 0 ? Math.floor(width) : MAIN_LIST_FALLBACK_WIDTH;
 }
 
-type InternalRow = BackgroundWorkRow & { navigatorId: string; providerLabel: string };
+type InternalRow = BackgroundWorkRow & { navigatorId: string; providerLabel: string; parentRow?: boolean };
 
 function rowKey(providerId: string, id: string): string {
   return `${providerId}:${id}`;
@@ -332,6 +340,19 @@ function listRows(now = Date.now()): InternalRow[] {
     let providerRows: BackgroundWorkRow[] = [];
     try { providerRows = provider.listRows(now) ?? []; } catch { providerRows = []; }
     const orderedProviderRows = [...providerRows].sort((a, b) => b.sortStartedAt - a.sortStartedAt || rowDisplayName(a).localeCompare(rowDisplayName(b)));
+    let showSection = orderedProviderRows.length > 0 || provider.parentRow !== undefined;
+    try { showSection = provider.showSection?.(orderedProviderRows, now) ?? showSection; } catch { showSection = false; }
+    if (!showSection) continue;
+    let parentRow: BackgroundWorkRow | null = null;
+    try { parentRow = provider.parentRow?.(now) ?? null; } catch { parentRow = null; }
+    if (parentRow) {
+      rows.push({
+        ...parentRow,
+        navigatorId: rowKey(parentRow.providerId, parentRow.id),
+        providerLabel: provider.label,
+        parentRow: true,
+      });
+    }
     for (const row of orderedProviderRows) {
       rows.push({ ...row, navigatorId: rowKey(provider.id, row.id), providerLabel: provider.label });
     }
@@ -377,7 +398,7 @@ function focusMainList(): void {
   const rows = listRows();
   if (rows.length === 0) return;
   const s = state();
-  syncMainListSelection(rows);
+  s.mainListSelectedId = rows.find((row) => row.parentRow && row.id === "main")?.navigatorId ?? rows[0]!.navigatorId;
   s.mainListFocused = true;
   refreshMainListWidget();
 }
@@ -422,13 +443,13 @@ function buildMainListLines(
 }
 
 function shortcutsLine(focused: boolean, fg: (color: string, value: string) => string): string {
-  const keys = focused ? "↑↓ select · Enter detail · x stop · Esc unfocus" : "← to navigate";
+  const keys = focused ? "↑↓ switch · Enter detail · x stop · Esc unfocus" : "← to navigate";
   return dim(keys, fg);
 }
 
 function providerGroupLabel(label: string, fg: (color: string, value: string) => string): string {
   const normalized = singleLine(label).toLowerCase();
-  return `${dim("▸", fg)} ${fg("warning", normalized)}`;
+  return fg("warning", normalized);
 }
 
 function formatMainListRow(row: InternalRow, selected: boolean, fg: (color: string, value: string) => string, width: number): string {
@@ -516,13 +537,14 @@ function detailFor(navigatorId: string, now = Date.now(), options?: { logTailLin
 }
 
 function closeFor(row: InternalRow): BackgroundWorkCloseOutcome {
+  if (row.parentRow) return { action: "not-closable", providerId: row.providerId, id: row.id };
   const provider = state().providers.get(row.providerId);
   if (!provider) return { action: "missing", providerId: row.providerId, id: row.id };
   try { return provider.close(row.id); } catch { return { action: "missing", providerId: row.providerId, id: row.id }; }
 }
 
 function closeHintFor(row: InternalRow | undefined): string | null {
-  if (!row) return null;
+  if (!row || row.parentRow) return null;
   const provider = state().providers.get(row.providerId);
   if (!provider) return null;
   try { return `${provider.armCloseLabel(row)} ${row.name || row.id}`; } catch { return null; }
@@ -547,6 +569,7 @@ function installNavigatorEditor(ui: any, deps: HostDeps): unknown {
 }
 
 function wrapEditor(inner: any, deps: HostDeps): unknown {
+  if (inner && typeof inner.render === "function") state().editorComponent = inner as Component;
   return new Proxy(inner, {
     get(target, prop) {
       if (prop === "handleInput") {
@@ -577,16 +600,24 @@ function handleMainListInput(data: string, deps: HostDeps): boolean {
   }
   if (deps.matchKey(data, "up")) {
     clearMainListCloseArm();
-    if (moveMainListSelection(-1)) refreshMainListWidget();
+    if (moveMainListSelection(-1)) {
+      refreshMainListWidget();
+      if (!selectedMainListRow()?.parentRow) openNavigator();
+    }
     return true;
   }
   if (deps.matchKey(data, "down")) {
     clearMainListCloseArm();
-    if (moveMainListSelection(1)) refreshMainListWidget();
+    if (moveMainListSelection(1)) {
+      refreshMainListWidget();
+      if (!selectedMainListRow()?.parentRow) openNavigator();
+    }
     return true;
   }
   if (deps.matchKey(data, "enter")) {
-    openNavigator();
+    const selected = selectedMainListRow();
+    if (selected?.parentRow) unfocusMainList();
+    else openNavigator();
     return true;
   }
   if (data === "x" || data === "X" || deps.matchKey(data, "x") || deps.matchKey(data, "X")) {
@@ -602,7 +633,7 @@ function handleMainListInput(data: string, deps: HostDeps): boolean {
 
 function handleMainListCloseKey(): void {
   const row = selectedMainListRow();
-  if (!row) return;
+  if (!row || row.parentRow) return;
   const s = state();
   const now = Date.now();
   const arm = s.mainListCloseArm;
@@ -678,6 +709,8 @@ function createOverlayComponent(
   let closeArm: { id: string; armedAt: number } | undefined;
   let closeArmTimer: ReturnType<typeof setTimeout> | undefined;
   let closed = false;
+  let transcriptDetail: BackgroundWorkDetail | null = null;
+  let transcriptComponent: Component | null = null;
 
   const fg = (color: string, value: string) => theme?.fg ? theme.fg(color, value) : value;
 
@@ -693,12 +726,24 @@ function createOverlayComponent(
   });
 
   function refreshRows(): void {
-    const selectedId = overlayState.rows[overlayState.selected]?.navigatorId;
+    const selectedId = state().mainListSelectedId ?? overlayState.rows[overlayState.selected]?.navigatorId;
     overlayState.rows = listRows();
     const nextIdx = selectedId ? overlayState.rows.findIndex((row) => row.navigatorId === selectedId) : -1;
     overlayState.selected = nextIdx >= 0 ? nextIdx : Math.min(overlayState.selected, Math.max(0, overlayState.rows.length - 1));
   }
 
+  function selectOverlayRow(next: number): void {
+    overlayState.selected = Math.min(Math.max(0, overlayState.rows.length - 1), Math.max(0, next));
+    state().mainListSelectedId = overlayState.rows[overlayState.selected]?.navigatorId;
+    clearCloseArm();
+    refreshMainListWidget();
+  }
+
+  function activateSelectedRow(): void {
+    if (selectedRow()?.parentRow) close();
+    else openDetail();
+  }
+
   function clearCloseArm(): void {
     if (closeArmTimer) clearTimeout(closeArmTimer);
     closeArmTimer = undefined;
@@ -720,13 +765,16 @@ function createOverlayComponent(
   }
 
   function selectedRow(): InternalRow | undefined {
-    if (mode === "detail" && detailId) return overlayState.rows.find((row) => row.navigatorId === detailId);
     return overlayState.rows[overlayState.selected];
   }
 
   function openDetail(): void {
     const row = selectedRow();
     if (!row) return;
+    if (row.parentRow) {
+      close();
+      return;
+    }
     clearCloseArm();
     detailId = row.navigatorId;
     expandedSections.clear();
@@ -797,10 +845,43 @@ function createOverlayComponent(
 
   return {
     render(width: number) {
-      const lines = mode === "detail"
-        ? buildDetailLines(detail, width, deps.truncate, fg, { expandedSections, logTailRows, minRows: state().detailOverlayRows })
-        : buildListLines(overlayState, width, deps.truncate, fg);
-      return lines;
+      refreshRows();
+      const railLines = mode === "detail"
+        ? buildMainListLines(overlayState.rows, width, deps.truncate, fg, {
+            selectedId: selectedRow()?.navigatorId,
+            focused: true,
+          })
+        : [];
+      const editorLines = mode === "detail" ? renderEditorLines(width) : [];
+      const bottomLines = [...railLines, ...editorLines];
+      const overlayRows = state().detailOverlayRows;
+      const detailRows = overlayRows === undefined ? undefined : Math.max(1, overlayRows - bottomLines.length);
+      let contentLines: string[];
+      if (mode === "detail" && detail?.transcript && deps.createTranscriptComponent) {
+        if (transcriptDetail !== detail || !transcriptComponent) {
+          transcriptDetail = detail;
+          transcriptComponent = deps.createTranscriptComponent(detail, theme);
+        }
+        contentLines = buildTranscriptDetailLines(
+          detail,
+          transcriptComponent.render(width),
+          width,
+          deps.truncate,
+          fg,
+          { minRows: detailRows },
+        );
+      } else {
+        transcriptDetail = null;
+        transcriptComponent = null;
+        contentLines = mode === "detail"
+          ? buildDetailLines(detail, width, deps.truncate, fg, { expandedSections, logTailRows, minRows: detailRows })
+          : buildListLines(overlayState, width, deps.truncate, fg);
+      }
+      if (mode !== "detail") return contentLines;
+      if (detailRows === undefined) return [...contentLines, ...bottomLines];
+      const fittedContent = contentLines.slice(0, detailRows);
+      while (fittedContent.length < detailRows) fittedContent.push("");
+      return [...fittedContent, ...bottomLines];
     },
     handleInput(data: string) {
       if (closed) return;
@@ -809,10 +890,25 @@ function createOverlayComponent(
         return;
       }
       if (mode === "detail") {
-        if (deps.matchKey(data, "left")) close();
+        if (deps.matchKey(data, "up")) {
+          selectOverlayRow(overlayState.selected - 1);
+          activateSelectedRow();
+        }
+        else if (deps.matchKey(data, "down")) {
+          selectOverlayRow(overlayState.selected + 1);
+          activateSelectedRow();
+        }
+        else if (deps.matchKey(data, "left")) {
+          const mainIdx = overlayState.rows.findIndex((row) => row.parentRow && row.id === "main");
+          if (mainIdx >= 0) selectOverlayRow(mainIdx);
+          close();
+        }
         else if (deps.matchKey(data, "enter")) {
-          const sectionId = firstToggleableSectionId(detail);
-          if (sectionId) {
+          const row = selectedRow();
+          if (row?.parentRow || row?.navigatorId !== detailId) openDetail();
+          else {
+            const sectionId = firstToggleableSectionId(detail);
+            if (!sectionId) return;
             if (expandedSections.has(sectionId)) expandedSections.delete(sectionId);
             else expandedSections.add(sectionId);
             requestRender();
@@ -823,7 +919,10 @@ function createOverlayComponent(
           if (detailId) detail = detailFor(detailId, Date.now(), { logTailLines: logTailRows }) ?? detail;
           requestRender();
         }
-        else if (deps.matchKey(data, "escape")) close();
+        else if (deps.matchKey(data, "escape")) {
+          unfocusMainList();
+          close();
+        }
         return;
       }
       if (deps.matchKey(data, "up")) {
@@ -840,7 +939,7 @@ function createOverlayComponent(
         close();
       }
     },
-    invalidate() {},
+    invalidate() { transcriptComponent?.invalidate(); },
     dispose() {
       clearCloseArm();
       detailScheduler.dispose();
@@ -848,26 +947,61 @@ function createOverlayComponent(
   };
 }
 
+function buildTranscriptDetailLines(
+  detail: BackgroundWorkDetail,
+  transcriptLines: string[],
+  width: number,
+  truncate: (s: string, width: number) => string,
+  fg: (color: string, value: string) => string,
+  options: { minRows?: number } = {},
+): string[] {
+  const actions = [...(detail.footerActions ?? ["x close"]), "Esc close"].join(" · ");
+  const lines: string[] = [
+    fg("accent", rule(detail.title, width)),
+    dim(`   ← main · ${actions}`, fg),
+    "",
+    `   status   ${fg(toneColor(detail.statusTone, detail.status), detail.status)}`,
+  ];
+  if (detail.subtitle) lines.push(`   summary  ${detail.subtitle}`);
+  for (const item of detail.metadata) lines.push(`   ${item.label.padEnd(8, " ").slice(0, 8)} ${item.value}`);
+  lines.push("", dim(section("transcript", width), fg));
+  if (detail.transcriptDiagnostic) lines.push(`   ${dim(detail.transcriptDiagnostic, fg)}`);
+  lines.push(...(transcriptLines.length ? transcriptLines : ["   (no transcript yet)"]));
+  lines.push("");
+  const footerLines = [dim(`   ← main · ${actions}`, fg), dim(rule("", width), fg)];
+  padBeforeFooter(lines, footerLines.length, options.minRows);
+  lines.push(...footerLines);
+  return lines.map((line) => safeTruncate(line, width, truncate));
+}
+
 function detailOverlayOptions() {
-  const navigatorRows = state().lastMainListLines?.length ?? 0;
-  const marginBottom = DETAIL_OVERLAY_FOOTER_MARGIN_ROWS + navigatorRows;
+  const marginBottom = DETAIL_OVERLAY_FOOTER_ROWS;
   return {
     anchor: "top-left" as const,
     width: "100%" as const,
     maxHeight: "100%" as const,
     margin: {
-      top: DETAIL_OVERLAY_HEADER_MARGIN_ROWS,
+      top: 0,
       right: 0,
       bottom: marginBottom,
       left: 0,
     },
     visible: (_termWidth: number, termHeight: number) => {
-      state().detailOverlayRows = Math.max(1, termHeight - DETAIL_OVERLAY_HEADER_MARGIN_ROWS - marginBottom);
+      state().detailOverlayRows = Math.max(1, termHeight - marginBottom);
       return true;
     },
   };
 }
 
+function renderEditorLines(width: number): string[] {
+  try {
+    const lines = state().editorComponent?.render(width);
+    if (lines?.length) return lines;
+  } catch { /* use an empty editor-shaped fallback */ }
+  const border = "─".repeat(Math.max(1, width));
+  return [border, "", border];
+}
+
 function fallbackDetail(row: InternalRow): BackgroundWorkDetail {
   return {
     providerId: row.providerId,
@@ -976,7 +1110,10 @@ function buildDetailLines(
   } else {
     const evidenceLabel = /log/i.test(detail.evidence.label) ? `${detail.evidence.label} · latest ${tailRows} rows` : detail.evidence.label;
     lines.push(dim(section(evidenceLabel, width), fg));
-    for (const raw of body.split(/\r?\n/)) lines.push(raw ? `   ${raw}` : "   ");
+    const wrapped = /log/i.test(detail.evidence.label)
+      ? wrapLogText(body, width - 6)
+      : body.split(/\r?\n/);
+    for (const raw of wrapped) lines.push(raw ? `   ${raw}` : "   ");
   }
   lines.push("");
   const footerLines = [dim(`   ← back · ${actions}`, fg), dim(rule("", width), fg)];
@@ -1042,6 +1179,82 @@ function wrapEvidenceText(text: string, width: number): string[] {
   return rows.length ? rows : ["(no output yet)"];
 }
 
+/**
+ * Wrap terminal log rows without flattening entries together. Continuations
+ * retain the source indentation, and long paths/JSON tokens are hard-wrapped
+ * so the final width guard never has to discard their suffix.
+ */
+export function wrapLogText(text: string, width: number): string[] {
+  const max = Math.max(8, Math.floor(width));
+  const rows: string[] = [];
+  for (const source of String(text ?? "").split(/\r?\n/)) {
+    if (!source) {
+      rows.push("");
+      continue;
+    }
+    const sourceIndent = source.match(/^[ \t]*/)?.[0] ?? "";
+    const indent = sourceIndent.replace(/\t/g, "  ");
+    let remaining = source.slice(sourceIndent.length);
+    const contentWidth = Math.max(1, max - visibleWidth(indent));
+    if (!remaining) {
+      rows.push(indent);
+      continue;
+    }
+    while (visibleWidth(remaining) > contentWidth) {
+      let [head, tail] = splitVisiblePrefix(remaining, contentWidth);
+      const minSoftBreak = Math.floor(contentWidth * 0.45);
+      const delimiterBreak = lastDelimiterBreak(head);
+      const whitespace = head.match(/\s+\S*$/)?.index;
+      if (delimiterBreak > minSoftBreak) {
+        tail = head.slice(delimiterBreak) + tail;
+        head = head.slice(0, delimiterBreak);
+      } else if (whitespace !== undefined && whitespace > minSoftBreak) {
+        tail = head.slice(whitespace).trimStart() + tail;
+        head = head.slice(0, whitespace).trimEnd();
+      }
+      rows.push(indent + head);
+      remaining = tail.trimStart();
+    }
+    rows.push(indent + remaining);
+  }
+  return rows.length ? rows : [""];
+}
+
+function lastDelimiterBreak(value: string): number {
+  let last = -1;
+  for (const match of value.matchAll(/[\/,}:]/g)) last = match.index + 1;
+  return last;
+}
+
+function splitVisiblePrefix(value: string, width: number): [string, string] {
+  const max = Math.max(0, Math.floor(width));
+  let visible = 0;
+  let index = 0;
+  while (index < value.length && visible < max) {
+    if (value[index] === "\u001b" || value[index] === "\u009b") {
+      const match = value.slice(index).match(ANSI_RE);
+      if (match?.index === 0) {
+        index += match[0].length;
+        continue;
+      }
+    }
+    if (value[index] === "<") {
+      const close = value.indexOf(">", index);
+      if (close !== -1) {
+        const tag = value.slice(index, close + 1);
+        if (/^<\/?[a-zA-Z][\w-]*>$/.test(tag) || tag === "</>") {
+          index = close + 1;
+          continue;
+        }
+      }
+    }
+    const codePoint = value.codePointAt(index)!;
+    index += codePoint > 0xFFFF ? 2 : 1;
+    visible += 1;
+  }
+  return [value.slice(0, index), value.slice(index)];
+}
+
 function cycleLogTailRows(current: number): number {
   const idx = LOG_TAIL_ROW_CHOICES.findIndex((value) => value === current);
   return LOG_TAIL_ROW_CHOICES[(idx + 1) % LOG_TAIL_ROW_CHOICES.length];

package/src/tools.ts

@@ -2,6 +2,7 @@ import { Type } from "typebox";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { readLog } from "./logs.js";
 import { refreshBackgroundTasksNavigator } from "./navigator-provider.js";
+import { cancelCallbackBatch } from "./shared-callback-batcher.js";
 import { listMetas, readMeta, writeMeta } from "./registry.js";
 import { resumeRunningTask, spawnTask, startWatchTask, stopTask } from "./runtime.js";
 import type { BackgroundTaskCallbackOrigin, BackgroundTaskMeta } from "./types.js";
@@ -89,9 +90,11 @@ export function registerTools(pi: ExtensionAPI): void {
   });
   pi.on("session_before_switch", () => {
     activeSession = undefined;
+    cancelCallbackBatch(pi);
   });
   pi.on("session_shutdown", () => {
     activeSession = undefined;
+    cancelCallbackBatch(pi);
   });
 
   pi.registerTool({