pi-better-subagents 0.1.16 → 0.1.18

package/finalization.ts

@@ -62,6 +62,13 @@ export function finalizeRun(
     if (outcome.incomplete) meta.failureReason = "incomplete-stream";
     meta.exitCode = code;
     meta.endedAt = Date.now();
+    const callback = meta.callback !== false;
+    if (callback
+        && meta.completionCallbackPendingAt === undefined
+        && meta.completionCallbackSentAt === undefined
+        && meta.completionCallbackSuppressedAt === undefined) {
+        meta.completionCallbackPendingAt = meta.endedAt;
+    }
     writeMeta(meta);
 
     const label = meta.name ? `${meta.name} (${id})` : id;
@@ -84,10 +91,9 @@ export function finalizeRun(
         /* ignore */
     }
 
-    const callback = meta.callback !== false; // default: trigger completion
-    // buildCompletionDelivery is the single place sendMessage content/options are
-    // assembled. resultText is accepted here so callers/tests can pass it without
-    // breaking, but it is NEVER put into content — the result lives in subagent_result.
+    // buildCompletionDelivery remains the compatibility formatter for callers and
+    // direct finalizer tests. Production callback:true delivery is coalesced by the
+    // host wrapper; callback:false never invokes a model-message hook.
     const delivery = buildCompletionDelivery({
         id,
         label,
@@ -98,10 +104,12 @@ export function finalizeRun(
         lifecycleClassification: outcome.classification,
         resultText: r.finalText || r.lastActivity || "",
     });
-    hooks.sendMessage?.(
-        { customType: "subagent-complete", content: delivery.content, display: true },
-        delivery.options,
-    );
+    if (callback) {
+        hooks.sendMessage?.(
+            { customType: "subagent-complete", content: delivery.content, display: true },
+            delivery.options,
+        );
+    }
 
     return {
         applied: true,

package/index.ts

@@ -84,6 +84,7 @@ import {
     getSharedCapacityGate,
 } from "./capacity.mjs";
 import { buildHealthCallbackDelivery } from "./completion.ts";
+import { cancelCallbackBatch, getCallbackBatcher } from "./shared-callback-batcher.ts";
 import {
     text,
     subagentListTool,
@@ -96,6 +97,7 @@ import {
     WIDGET_CLEAR,
     fmtElapsed,
     fmtSpend,
+    fmtTokens,
     shortModel,
     isSpendCacheFresh,
     resolveHealthLogExtraction,
@@ -236,12 +238,58 @@ function stopCurrentSessionSubagents(ctx: ExtensionContext): void {
 
 function markCompletionCallbackSuppressed(id: string, reason: string, now: number = Date.now()): void {
     const meta = readMeta(id);
-    if (!meta || meta.completionCallbackSuppressedAt !== undefined) return;
+    if (!meta || meta.completionCallbackSentAt !== undefined || meta.completionCallbackSuppressedAt !== undefined) return;
     meta.completionCallbackSuppressedAt = now;
     meta.completionCallbackSuppressedReason = reason;
     writeMeta(meta);
 }
 
+function markCompletionCallbackSent(id: string, now: number): void {
+    const meta = readMeta(id);
+    if (!meta || meta.completionCallbackSentAt !== undefined || meta.completionCallbackSuppressedAt !== undefined) return;
+    meta.completionCallbackSentAt = now;
+    writeMeta(meta);
+}
+
+/** Queue one durable ordinary terminal event on the host-shared batch. */
+function enqueueCompletionCallback(pi: ExtensionAPI, id: string): void {
+    const meta = readMeta(id);
+    if (!meta
+        || meta.callback === false
+        || meta.completionCallbackPendingAt === undefined
+        || meta.completionCallbackSentAt !== undefined
+        || meta.completionCallbackSuppressedAt !== undefined) return;
+    const label = meta.name ? `${meta.name} (${id})` : id;
+    getCallbackBatcher(pi).enqueue({
+        source: "subagent",
+        id,
+        label,
+        status: meta.status,
+        detailTool: "subagent_result",
+        callback: true,
+        isDelivered: () => {
+            const current = readMeta(id);
+            return current?.completionCallbackSentAt !== undefined
+                || current?.completionCallbackSuppressedAt !== undefined;
+        },
+        getSuppressionReason: () => {
+            const current = readMeta(id);
+            if (!current) return "subagent metadata is unavailable";
+            return callbackSuppressionReason(current);
+        },
+        onDelivered: (at) => markCompletionCallbackSent(id, at),
+        onSuppressed: (reason, at) => markCompletionCallbackSuppressed(id, reason, at),
+    });
+}
+
+/** Recover only records explicitly marked pending; legacy terminal runs never replay. */
+function recoverCompletionCallbacks(pi: ExtensionAPI): void {
+    for (const meta of listMetas()) {
+        if (!ownedByThisParent(meta)) continue;
+        enqueueCompletionCallback(pi, meta.id);
+    }
+}
+
 function markHealthCallbackSuppressed(meta: RunMeta, status: "orphaned" | "lost", reason: string, now: number): void {
     if (status === "orphaned") {
         if (meta.orphanedCallbackSuppressedAt !== undefined) return;
@@ -408,12 +456,6 @@ function deliverHealthCallback(pi: ExtensionAPI | undefined, meta: RunMeta, stat
     if (!pi) return;
     if (isHealthCallbackHandled(meta, status)) return;
 
-    const suppressionReason = callbackSuppressionReason(meta);
-    if (suppressionReason) {
-        markHealthCallbackSuppressed(meta, status, suppressionReason, now);
-        return;
-    }
-
     const callback = meta.callback !== false;
     const label = meta.name ? `${meta.name} (${meta.id})` : meta.id;
     const delivery = buildHealthCallbackDelivery({ id: meta.id, label, status, callback });
@@ -425,20 +467,35 @@ function deliverHealthCallback(pi: ExtensionAPI | undefined, meta: RunMeta, stat
         writeMeta(meta);
         return;
     }
-    try {
-        pi.sendMessage(
-            { customType: "subagent-health", content: delivery.content, display: true },
-            delivery.options,
-        );
-    } catch {
-        // Handoff failed — leave marker unset so a later tick/reload can retry.
-        // Never let a delivery failure break the health ticker.
-        return;
-    }
-    // Marker = successful handoff (sendMessage returned), not mere attempt.
-    if (status === "orphaned") meta.orphanedCallbackSentAt = now;
-    else meta.lostCallbackSentAt = now;
-    writeMeta(meta);
+    void getCallbackBatcher(pi).deliverUrgent({
+        source: "subagent",
+        id: meta.id,
+        label,
+        status,
+        customType: "subagent-health",
+        content: delivery.content,
+        isDelivered: () => {
+            const current = readMeta(meta.id);
+            return current ? isHealthCallbackHandled(current, status) : true;
+        },
+        getSuppressionReason: () => {
+            const current = readMeta(meta.id);
+            if (!current) return "subagent metadata is unavailable";
+            return callbackSuppressionReason(current);
+        },
+        onDelivered: (at) => {
+            const current = readMeta(meta.id);
+            if (!current || isHealthCallbackHandled(current, status)) return;
+            if (status === "orphaned") current.orphanedCallbackSentAt = at;
+            else current.lostCallbackSentAt = at;
+            writeMeta(current);
+        },
+        onSuppressed: (reason, at) => {
+            const current = readMeta(meta.id);
+            if (!current || isHealthCallbackHandled(current, status)) return;
+            markHealthCallbackSuppressed(current, status, reason, at);
+        },
+    });
 }
 
 /** One reconciliation + durable health-callback recovery pass. */
@@ -587,6 +644,8 @@ export function setIdentityProbeForTests(probe: ProcessProbe | undefined): void
 
 let unregisterSubagentProvider: (() => void) | undefined;
 const TERMINAL_NAVIGATOR_RETENTION_MS = 30_000;
+let mainAgentStartedAt: number | undefined;
+const mainAgentTools = new Map<string, string>();
 
 /**
  * Observe health for a navigator row/detail (#69). Reuses the size/mtime-gated
@@ -743,6 +802,37 @@ function subagentWorkRows(now: number): BackgroundWorkRow[] {
     });
 }
 
+function mainAgentWorkRow(now: number): BackgroundWorkRow {
+    let running = mainAgentStartedAt !== undefined;
+    try { running ||= uiCtx?.isIdle() === false; } catch { /* use event state */ }
+    const model = shortModel(uiCtx?.model?.id);
+    const effort = uiCtx?.thinkingLevel;
+    const tool = [...mainAgentTools.values()].at(-1);
+    let contextTokens: number | null | undefined;
+    try { contextTokens = uiCtx?.getContextUsage()?.tokens; } catch { contextTokens = undefined; }
+    const tokens = typeof contextTokens === "number" ? `${fmtTokens(contextTokens)} tok` : undefined;
+    const bits = [
+        effort ? `${model} ${effort}` : model,
+        tool ? `tool ${tool}` : undefined,
+        tokens,
+    ].filter((bit): bit is string => Boolean(bit));
+    return {
+        providerId: "subagents",
+        id: "main",
+        name: "main",
+        model,
+        effort,
+        tool,
+        tokens,
+        status: running ? "running" : "idle",
+        statusTone: running ? "running" : "muted",
+        kind: "main agent",
+        elapsed: running && mainAgentStartedAt !== undefined ? fmtElapsed(now - mainAgentStartedAt) : "idle",
+        primary: bits.join(" · "),
+        sortStartedAt: mainAgentStartedAt ?? now,
+    };
+}
+
 function subagentWorkDetail(id: string, now: number, options?: { logTailLines?: number }): BackgroundWorkDetail | null {
     const detail = navigatorDetail(id, now);
     if (!detail) return null;
@@ -780,6 +870,7 @@ function ensureSubagentProvider(): void {
         label: "Subagents",
         priority: 10,
         visibleCount: () => navigatorRunningCount(),
+        parentRow: (now) => mainAgentWorkRow(now),
         listRows: (now) => subagentWorkRows(now),
         detail: (id, now, options) => subagentWorkDetail(id, now, options),
         armCloseLabel: (row) => row.status === "running" || row.status === "orphaned" ? "x again to stop" : "x again to dismiss",
@@ -900,16 +991,7 @@ function finalizeRun(pi: ExtensionAPI, ctx: ExtensionContext, id: string, code:
         notify: (message, level) => {
             try { ctx.ui.notify(message, level); } catch { /* ignore */ }
         },
-        sendMessage: (message, options) => {
-            const meta = readMeta(id);
-            if (!meta) return;
-            const suppressionReason = callbackSuppressionReason(meta);
-            if (suppressionReason) {
-                markCompletionCallbackSuppressed(id, suppressionReason);
-                return;
-            }
-            pi.sendMessage(message, options);
-        },
+        sendMessage: () => enqueueCompletionCallback(pi, id),
     });
 }
 
@@ -1322,12 +1404,51 @@ export default function (pi: ExtensionAPI) {
     pi.registerTool(subagentStopTool(Type, { onStopped: renderWidget }));
 
     // ---- live-status lifecycle -----------------------------------------
+    pi.on("agent_start", async (_event, ctx) => {
+        uiCtx = ctx;
+        mainAgentStartedAt = Date.now();
+        mainAgentTools.clear();
+        refreshBackgroundWorkNavigator(ctx);
+    });
+
+    pi.on("tool_execution_start", async (event, ctx) => {
+        mainAgentTools.set(event.toolCallId, event.toolName);
+        refreshBackgroundWorkNavigator(ctx);
+    });
+
+    pi.on("tool_execution_end", async (event, ctx) => {
+        mainAgentTools.delete(event.toolCallId);
+        refreshBackgroundWorkNavigator(ctx);
+    });
+
+    pi.on("message_end", async (event, ctx) => {
+        if (event.message.role === "assistant") refreshBackgroundWorkNavigator(ctx);
+    });
+
+    pi.on("model_select", async (_event, ctx) => {
+        refreshBackgroundWorkNavigator(ctx);
+    });
+
+    pi.on("thinking_level_select", async (_event, ctx) => {
+        refreshBackgroundWorkNavigator(ctx);
+    });
+
+    pi.on("agent_settled", async (_event, ctx) => {
+        mainAgentStartedAt = undefined;
+        mainAgentTools.clear();
+        refreshBackgroundWorkNavigator(ctx);
+    });
+
     // Capture a UI-bearing context and, if runs from a prior session are still
     // alive, resume the ticking widget. Deferred out of the factory per pi's
     // "no background resources at load" rule.
     pi.on("session_start", async (_event, ctx) => {
         uiCtx = ctx;
+        try { mainAgentStartedAt = ctx.isIdle() ? undefined : Date.now(); }
+        catch { mainAgentStartedAt = undefined; }
+        mainAgentTools.clear();
         activeCallbackOrigin = callbackOriginFromContext(ctx);
+        recoverCompletionCallbacks(pi);
         // Reload / session switch hardening (#48):
         // - Drop any leftover overlay timers/confirm state from a prior session
         //   (defensive if the host skipped session_shutdown before re-start).
@@ -1359,6 +1480,9 @@ export default function (pi: ExtensionAPI) {
 
     pi.on("session_before_switch", () => {
         activeCallbackOrigin = undefined;
+        cancelCallbackBatch(pi);
+        mainAgentStartedAt = undefined;
+        mainAgentTools.clear();
         disposeBackgroundWorkNavigator();
     });
 
@@ -1369,6 +1493,9 @@ export default function (pi: ExtensionAPI) {
         // cannot become live process groups with no coordinator.
         stopCurrentSessionSubagents(ctx);
         activeCallbackOrigin = undefined;
+        cancelCallbackBatch(pi);
+        mainAgentStartedAt = undefined;
+        mainAgentTools.clear();
         stopTicker();
         stopHealthTicker();
         spendCache.clear();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
   "license": "MIT",
   "type": "module",

package/registry.ts

@@ -102,6 +102,9 @@ export interface RunMeta {
     sessionId: string;
     /** Foreground session that is allowed to receive unsolicited callbacks. */
     callbackOrigin?: RunCallbackOrigin;
+    /** Durable ordinary-completion callback recovery and successful-handoff markers. */
+    completionCallbackPendingAt?: number;
+    completionCallbackSentAt?: number;
     completionCallbackSuppressedAt?: number;
     completionCallbackSuppressedReason?: string;
     orphanedCallbackSuppressedAt?: number;

package/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/shared-navigator.ts

@@ -54,6 +54,7 @@ export type BackgroundWorkProvider = {
   label: string;
   priority: number;
   visibleCount(): number;
+  parentRow?(now: number): BackgroundWorkRow | null;
   listRows(now: number): BackgroundWorkRow[];
   detail(id: string, now: number, options?: { logTailLines?: number }): BackgroundWorkDetail | null;
   armCloseLabel(row: BackgroundWorkRow): string;
@@ -411,6 +412,16 @@ function buildMainListLines(
     const group = grouped.get(label)!;
     if (i > 0) lines.push("");
     lines.push(providerGroupLabel(label, fg));
+    const provider = state().providers.get(group[0]!.providerId);
+    let parentRow: BackgroundWorkRow | null = null;
+    try { parentRow = provider?.parentRow?.(Date.now()) ?? null; } catch { parentRow = null; }
+    if (parentRow) {
+      lines.push(formatMainListRow({
+        ...parentRow,
+        navigatorId: rowKey(parentRow.providerId, parentRow.id),
+        providerLabel: label,
+      }, false, fg, width));
+    }
     for (const row of group) {
       const selected = options.focused && row.navigatorId === options.selectedId;
       lines.push(formatMainListRow(row, selected === true, fg, width));
@@ -976,7 +987,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 +1056,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];