pi-better-background-tasks 0.1.14 → 0.1.16

package/README.md

@@ -16,6 +16,7 @@ Use `pi-better-background-tasks` when a command should keep running while the fo
 - Watch commands until success, failure, or timeout.
 - Keep task metadata and logs available across reloads.
 - Show active work in Pi's background-work navigator.
+- Flag running tasks with no observable output or completed poll as stalled.
 
 ## Install
 

package/package.json

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

package/src/goal-provider.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { listMetas } from "./registry.js";
 import type { BackgroundTaskMeta } from "./types.js";
 import { isTerminalStatus } from "./types.js";
+import { backgroundTaskProgressAt, observeBackgroundTaskStall } from "./stall.js";
 
 const GOAL_READY_EVENT = "pi-better-goal:ready";
 const GOAL_REGISTER_PROVIDER_EVENT = "pi-better-goal:register-provider";
@@ -92,11 +93,14 @@ function getGoalActivityOrigin(ctx: ExtensionContext) {
 function backgroundTaskToGoalItem(meta: BackgroundTaskMeta): GoalBackgroundWorkItem {
   const active = meta.status === "running";
   const terminal = isTerminalStatus(meta.status);
-  const attention = terminal && meta.status !== "succeeded";
+  const stall = observeBackgroundTaskStall(meta);
+  const unhealthy = active && stall.state === "stalled";
+  const attention = (terminal && meta.status !== "succeeded") || unhealthy;
   const item: GoalBackgroundWorkItem = {
     id: meta.id,
     status: meta.status,
     active,
+    unhealthy,
     terminal,
     attention,
     startedAt: meta.startedAt,
@@ -108,6 +112,8 @@ function backgroundTaskToGoalItem(meta: BackgroundTaskMeta): GoalBackgroundWorkI
       argv: meta.argv,
       logPath: meta.logPath,
       spawnPid: meta.spawnPid,
+      lastProgressAt: backgroundTaskProgressAt(meta),
+      stall: stall.state,
     },
   };
   if (meta.name !== undefined) item.label = meta.name;

package/src/navigator-provider.ts

@@ -10,8 +10,9 @@ import {
 import { CustomEditor } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
 import { readLog } from "./logs.js";
-import { listMetas, readMeta, writeMeta } from "./registry.js";
+import { listMetas, onMetaChanged, readMeta, writeMeta } from "./registry.js";
 import { stopTask } from "./runtime.js";
+import { observeBackgroundTaskStall } from "./stall.js";
 import type { BackgroundTaskCallbackOrigin, BackgroundTaskMeta, BackgroundTaskStatus } from "./types.js";
 
 let unregister: (() => void) | undefined;
@@ -62,6 +63,7 @@ const provider: BackgroundWorkProvider = {
     writeMeta(meta);
     return { action: "dismissed", providerId: "background-tasks", id, status: meta.status };
   },
+  onVisibleChanged: onMetaChanged,
 };
 
 function visibleMetas(now = Date.now()): BackgroundTaskMeta[] {
@@ -113,6 +115,9 @@ function rowFromMeta(meta: BackgroundTaskMeta, now: number): BackgroundWorkRow {
     secondary: secondaryLabel(meta),
     facts: factsForMeta(meta, now),
     sortStartedAt: meta.startedAt,
+    expiresAt: meta.status === "running" || meta.endedAt === undefined
+      ? undefined
+      : meta.endedAt + TERMINAL_NAVIGATOR_RETENTION_MS,
   };
 }
 
@@ -131,6 +136,10 @@ function detailFromMeta(meta: BackgroundTaskMeta | undefined, now: number, optio
   ];
   if (meta.deadlineAt) metadata.push({ label: "deadline", value: formatDuration(meta.deadlineAt - now) });
   if (meta.lastCheckedAt) metadata.push({ label: "checked", value: `${formatDuration(now - meta.lastCheckedAt)} ago` });
+  if (meta.status === "running") {
+    const stall = observeBackgroundTaskStall(meta, now);
+    if (stall.state !== "healthy") metadata.push({ label: "activity", value: stall.state });
+  }
   if (meta.lastExitCode !== undefined) metadata.push({ label: "exit", value: String(meta.lastExitCode) });
   if (meta.error) metadata.push({ label: "error", value: meta.error });
   if (meta.logDiscardedBytes) {
@@ -194,6 +203,11 @@ function secondaryLabel(meta: BackgroundTaskMeta): string | undefined {
 
 function factsForMeta(meta: BackgroundTaskMeta, now: number): string[] {
   const facts: string[] = [];
+  if (meta.status === "running") {
+    const stall = observeBackgroundTaskStall(meta, now);
+    if (stall.state === "stalled") facts.push("stalled");
+    else if (stall.state === "quiet") facts.push("quiet");
+  }
   if (meta.kind === "command_watch" && meta.intervalMs) facts.push(`every ${formatDuration(meta.intervalMs)}`);
   if (meta.deadlineAt && meta.status === "running") facts.push(`${formatDuration(meta.deadlineAt - now)} left`);
   if (meta.result && meta.status !== "running") {

package/src/registry.ts

@@ -6,6 +6,7 @@ import { isTerminalStatus } from "./types.js";
 
 let seq = 0;
 const metaCache = new Map<string, BackgroundTaskMeta>();
+const metaChangedListeners = new Set<() => void>();
 
 export function baseDir(): string {
   return join(tmpdir(), "pi-better-background-tasks");
@@ -40,6 +41,14 @@ export function writeMeta(meta: BackgroundTaskMeta): void {
   ensureTaskDir(meta.id);
   writeFileSync(metaPathFor(meta.id), JSON.stringify(meta, null, 2));
   metaCache.set(meta.id, meta);
+  for (const listener of metaChangedListeners) {
+    try { listener(); } catch { /* best effort */ }
+  }
+}
+
+export function onMetaChanged(listener: () => void): () => void {
+  metaChangedListeners.add(listener);
+  return () => metaChangedListeners.delete(listener);
 }
 
 export function readMeta(id: string): BackgroundTaskMeta | undefined {

package/src/runtime.ts

@@ -1,8 +1,10 @@
+import { statSync } from "node:fs";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { appendLine, appendWatchResult, retainLogTail, resolveMaxLogBytes } from "./logs.js";
 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";
 
@@ -51,6 +53,7 @@ export function spawnTask(
     kind: "process",
     status: "running",
     startedAt: now,
+    lastProgressAt: now,
     deadlineAt: params.timeout_seconds ? now + params.timeout_seconds * 1000 : undefined,
     logPath,
     callback: params.callback,
@@ -103,6 +106,7 @@ export function startWatchTask(
     kind: "command_watch",
     status: "running",
     startedAt: now,
+    lastProgressAt: now,
     deadlineAt: timeoutSeconds ? now + timeoutSeconds * 1000 : undefined,
     intervalMs: Math.max(1, params.interval_seconds ?? 30) * 1000,
     logPath: logPathFor(id),
@@ -212,6 +216,7 @@ async function pollWatch(pi: ExtensionAPI, id: string, getActiveSession?: Active
     if (!latest || latest.status !== "running") return;
     enforceLogRetention(latest);
     latest.lastCheckedAt = Date.now();
+    latest.lastProgressAt = latest.lastCheckedAt;
     latest.lastExitCode = result.exitCode;
     latest.lastSignal = result.signal;
     latest.lastState = extractLastState(result);
@@ -300,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(
@@ -371,6 +389,15 @@ function stopLogRetention(id: string): void {
 }
 
 function enforceLogRetention(meta: BackgroundTaskMeta): void {
+  try {
+    const mtimeMs = Math.trunc(statSync(meta.logPath).mtimeMs);
+    if (mtimeMs > (meta.lastProgressAt ?? meta.startedAt)) {
+      meta.lastProgressAt = mtimeMs;
+      writeMeta(meta);
+    }
+  } catch {
+    // Logs are optional progress evidence; retention still proceeds if absent.
+  }
   const compacted = retainLogTail(meta.logPath, resolveMaxLogBytes(meta.maxLogBytes));
   if (!compacted) return;
   meta.logDiscardedBytes = (meta.logDiscardedBytes ?? 0) + compacted.discardedBytes;

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

@@ -1,5 +1,6 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { Component } from "@earendil-works/pi-tui";
+import { createRenderScheduler, type RenderScheduler } from "./shared-render-scheduler.ts";
 
 export default function navigatorExtension(): void {
   // Internal shared package. Pi may scan its symlink in the extension directory
@@ -25,6 +26,7 @@ export type BackgroundWorkRow = {
   secondary?: string;
   facts?: string[];
   sortStartedAt: number;
+  expiresAt?: number;
 };
 
 export type BackgroundWorkDetail = {
@@ -52,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;
@@ -79,7 +82,7 @@ type NavigatorState = {
   mainListFocused?: boolean;
   mainListCloseArm?: { id: string; armedAt: number };
   mainListCloseArmTimer?: ReturnType<typeof setTimeout>;
-  mainListTimer?: ReturnType<typeof setInterval>;
+  mainListDeadlineScheduler?: RenderScheduler;
   detailOverlayRows?: number;
   dispose?: () => void;
 };
@@ -91,15 +94,10 @@ const FACTORY_REFRESH = "__piBetterHarnessNavigatorRefresh";
 export const NAVIGATOR_STATUS_KEY = "background-work-nav";
 export const CLOSE_CONFIRM_STATUS_KEY = "background-work-close";
 export const MAIN_LIST_WIDGET_KEY = "background-work-list";
-export const DETAIL_TICK_MS = 1000;
+export const DETAIL_TICK_MS = 10_000;
 export const CLOSE_ARM_MS = 3000;
 export const DEFAULT_LOG_TAIL_ROWS = 10;
 export const LOG_TAIL_ROW_CHOICES = [10, 25] as const;
-// Row rebuild cadence. Each tick asks every provider for rows, which stats and
-// parses run logs, so this is a per-provider I/O cadence and not a paint rate:
-// the widget repaints from render() whenever the TUI asks. 1 Hz matches
-// DETAIL_TICK_MS and the elapsed/spinner resolution the rows can actually show.
-const MAIN_LIST_TICK_MS = 1000;
 const MAIN_LIST_FALLBACK_WIDTH = 100;
 const DETAIL_OVERLAY_HEADER_MARGIN_ROWS = 5;
 const DETAIL_OVERLAY_FOOTER_MARGIN_ROWS = 3;
@@ -173,9 +171,10 @@ export function ensureBackgroundWorkNavigator(ctx: ExtensionContext, deps: HostD
   try { (ctx.ui as any).setWidget?.(MAIN_LIST_WIDGET_KEY, undefined); } catch { /* ignore */ }
   s.mainListWidgetInstalled = false;
   s.mainListRequestRender = undefined;
+  s.mainListDeadlineScheduler?.dispose();
+  s.mainListDeadlineScheduler = createRenderScheduler(() => refreshMainListWidget());
   installNavigatorEditor(ctx.ui as any, deps);
   s.lastHint = undefined;
-  startMainListWidget(ctx);
   refreshBackgroundWorkNavigator(ctx);
   refreshMainListWidget();
 }
@@ -193,6 +192,8 @@ export function disposeBackgroundWorkNavigator(ctx?: ExtensionContext): void {
   }
   s.lastHint = undefined;
   s.lastMainListLines = undefined;
+  s.mainListDeadlineScheduler?.dispose();
+  s.mainListDeadlineScheduler = undefined;
   s.mainListWidgetInstalled = false;
   s.mainListRequestRender = undefined;
   s.detailOverlayRows = undefined;
@@ -226,17 +227,7 @@ function visibleCount(): number {
   }, 0);
 }
 
-function startMainListWidget(ctx: ExtensionContext): void {
-  const s = state();
-  if (s.mainListTimer || !isNavigatorUiAvailable(ctx)) return;
-  s.mainListTimer = setInterval(() => refreshMainListWidget(), MAIN_LIST_TICK_MS);
-  s.mainListTimer.unref?.();
-}
-
 function stopMainListWidget(): void {
-  const s = state();
-  if (s.mainListTimer) clearInterval(s.mainListTimer);
-  s.mainListTimer = undefined;
   clearMainListCloseArm();
 }
 
@@ -254,7 +245,16 @@ function refreshMainListWidget(): void {
   const ctx = s.uiCtx;
   const deps = s.deps;
   if (!ctx || !deps || !isNavigatorUiAvailable(ctx)) return;
-  const rows = listRows();
+  const now = Date.now();
+  const rows = listRows(now);
+  s.mainListDeadlineScheduler?.cancel();
+  const nextExpiry = rows.reduce<number | undefined>((next, row) => {
+    if (row.expiresAt === undefined || row.expiresAt <= now) return next;
+    return next === undefined ? row.expiresAt : Math.min(next, row.expiresAt);
+  }, undefined);
+  if (nextExpiry !== undefined) {
+    s.mainListDeadlineScheduler?.schedule(nextExpiry - now);
+  }
   syncMainListSelection(rows);
   s.lastMainListLines = rows.length ? buildMainListLines(rows, MAIN_LIST_FALLBACK_WIDTH, deps.truncate, themeFg(ctx), {
     selectedId: s.mainListFocused ? s.mainListSelectedId : undefined,
@@ -412,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));
@@ -462,7 +472,7 @@ function statusGlyph(row: InternalRow): string {
 
 function statusIndicator(row: InternalRow, now = Date.now()): { glyph: string; color: string } {
   if (row.statusTone !== "running") return { glyph: statusGlyph(row), color: toneColor(row.statusTone, row.status) };
-  const frame = Math.floor(now / MAIN_LIST_TICK_MS) % RUNNING_DOT_FRAMES.length;
+  const frame = Math.floor(now / DETAIL_TICK_MS) % RUNNING_DOT_FRAMES.length;
   return { glyph: RUNNING_DOT_GLYPH, color: RUNNING_DOT_FRAMES[frame]! };
 }
 
@@ -676,7 +686,6 @@ function createOverlayComponent(
     const idx = overlayState.rows.findIndex((row) => row.navigatorId === detailId);
     if (idx >= 0) overlayState.selected = idx;
   }
-  let detailTimer: ReturnType<typeof setInterval> | undefined;
   let closeArm: { id: string; armedAt: number } | undefined;
   let closeArmTimer: ReturnType<typeof setTimeout> | undefined;
   let closed = false;
@@ -687,6 +696,13 @@ function createOverlayComponent(
     try { tui.requestRender(); } catch { /* ignore */ }
   }
 
+  const detailScheduler = createRenderScheduler(() => {
+    if (!detailId || mode !== "detail" || closed) return;
+    detail = detailFor(detailId, Date.now(), { logTailLines: logTailRows }) ?? detail;
+    requestRender();
+    startDetailTimer();
+  });
+
   function refreshRows(): void {
     const selectedId = overlayState.rows[overlayState.selected]?.navigatorId;
     overlayState.rows = listRows();
@@ -704,18 +720,14 @@ function createOverlayComponent(
   }
 
   function stopDetailTimer(): void {
-    if (detailTimer) clearInterval(detailTimer);
-    detailTimer = undefined;
+    detailScheduler.cancel();
   }
 
   function startDetailTimer(): void {
-    stopDetailTimer();
-    detailTimer = setInterval(() => {
-      if (!detailId || mode !== "detail") return;
-      detail = detailFor(detailId, Date.now(), { logTailLines: logTailRows }) ?? detail;
-      requestRender();
-    }, DETAIL_TICK_MS);
-    detailTimer.unref?.();
+    detailScheduler.cancel();
+    if (detail?.status === "running" || detail?.status === "orphaned") {
+      detailScheduler.schedule(DETAIL_TICK_MS);
+    }
   }
 
   function selectedRow(): InternalRow | undefined {
@@ -759,7 +771,7 @@ function createOverlayComponent(
     if (closed) return;
     closed = true;
     clearCloseArm();
-    stopDetailTimer();
+    detailScheduler.dispose();
     try { done(null); } catch { /* ignore */ }
   }
 
@@ -842,7 +854,7 @@ function createOverlayComponent(
     invalidate() {},
     dispose() {
       clearCloseArm();
-      stopDetailTimer();
+      detailScheduler.dispose();
     },
   };
 }
@@ -975,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)];
@@ -1041,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];

package/src/shared-render-scheduler.ts

@@ -0,0 +1,47 @@
+// Generated from packages/render-scheduler/index.ts. Do not edit directly.
+export interface RenderScheduler {
+  request(): void;
+  schedule(delayMs: number): void;
+  cancel(): void;
+  dispose(): void;
+  pending(): boolean;
+}
+
+/**
+ * Schedule TUI paints as replaceable one-shot deadlines. Callers reschedule
+ * only while visible state still changes; static and hidden UI stays idle.
+ */
+export function createRenderScheduler(requestRender: () => void): RenderScheduler {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let disposed = false;
+
+  const cancel = (): void => {
+    if (timer) clearTimeout(timer);
+    timer = undefined;
+  };
+
+  return {
+    request() {
+      if (disposed) return;
+      cancel();
+      requestRender();
+    },
+    schedule(delayMs: number) {
+      if (disposed) return;
+      cancel();
+      timer = setTimeout(() => {
+        timer = undefined;
+        if (!disposed) requestRender();
+      }, Math.max(0, delayMs));
+      timer.unref?.();
+    },
+    cancel,
+    dispose() {
+      disposed = true;
+      cancel();
+    },
+    pending() {
+      return timer !== undefined;
+    },
+  };
+}

package/src/shared-stall-detector.ts

@@ -0,0 +1,69 @@
+// Generated from packages/stall-detector/index.ts. Do not edit directly.
+export interface StallThresholds {
+  /** Age of observable progress before work becomes quiet. */
+  quietMs: number;
+  /** Age of observable progress before work becomes stalled. */
+  stallMs: number;
+}
+
+export type StallState = "healthy" | "quiet" | "stalled" | "unknown";
+
+export interface StallObservation {
+  state: StallState;
+  /** Most recent meaningful evidence, falling back to the start time. */
+  observedAt?: number;
+  ageMs?: number;
+  thresholds: StallThresholds;
+}
+
+export interface ObserveStallInput {
+  now: number;
+  /** Explicit meaningful progress, never a timer tick or metadata write. */
+  lastProgressAt?: number;
+  /** Fallback anchor for work that has not produced progress yet. */
+  startedAt?: number;
+  /** Known active phases that explain a lack of observable progress. */
+  exempt?: boolean;
+  thresholds?: Partial<StallThresholds>;
+}
+
+export const DEFAULT_STALL_THRESHOLDS: Readonly<StallThresholds> = Object.freeze({
+  quietMs: 60_000,
+  stallMs: 5 * 60_000,
+});
+
+function positiveMs(value: unknown, fallback: number): number {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+
+/** Normalize caller config and ensure quiet never exceeds the stall threshold. */
+export function resolveStallThresholds(partial?: Partial<StallThresholds> | null): StallThresholds {
+  const quietMs = positiveMs(partial?.quietMs, DEFAULT_STALL_THRESHOLDS.quietMs);
+  const stallMs = positiveMs(partial?.stallMs, DEFAULT_STALL_THRESHOLDS.stallMs);
+  return { quietMs: Math.min(quietMs, stallMs), stallMs: Math.max(quietMs, stallMs) };
+}
+
+/**
+ * Classify the age of observable progress. This is deliberately observational:
+ * it does not claim a live process is broken and never performs recovery.
+ */
+export function observeStall(input: ObserveStallInput): StallObservation {
+  const thresholds = resolveStallThresholds(input.thresholds);
+  const observedAt = input.lastProgressAt ?? input.startedAt;
+  if (typeof observedAt !== "number" || !Number.isFinite(observedAt)) {
+    return { state: "unknown", thresholds };
+  }
+
+  const ageMs = Math.max(0, input.now - observedAt);
+  if (input.exempt) {
+    return { state: ageMs >= thresholds.quietMs ? "quiet" : "healthy", observedAt, ageMs, thresholds };
+  }
+  if (ageMs >= thresholds.stallMs) {
+    return { state: "stalled", observedAt, ageMs, thresholds };
+  }
+  if (ageMs >= thresholds.quietMs) {
+    return { state: "quiet", observedAt, ageMs, thresholds };
+  }
+  return { state: "healthy", observedAt, ageMs, thresholds };
+}

package/src/stall.ts

@@ -0,0 +1,42 @@
+import { statSync } from "node:fs";
+
+import { observeStall, type StallObservation, type StallThresholds } from "./shared-stall-detector.js";
+import type { BackgroundTaskMeta } from "./types.js";
+
+function durationEnv(name: string): number | undefined {
+  const raw = process.env[name];
+  if (!raw || raw.trim() === "") return undefined;
+  const value = Number(raw);
+  return Number.isFinite(value) && value > 0 ? Math.floor(value) : undefined;
+}
+
+export function backgroundTaskStallThresholds(): Partial<StallThresholds> {
+  return {
+    quietMs: durationEnv("PI_BETTER_STALL_QUIET_MS"),
+    stallMs: durationEnv("PI_BETTER_STALL_MS"),
+  };
+}
+
+/**
+ * Process logs are the only external progress evidence available for detached
+ * commands. Watchers instead advance after a completed poll command.
+ */
+export function backgroundTaskProgressAt(meta: BackgroundTaskMeta): number | undefined {
+  const recorded = Math.max(meta.lastProgressAt ?? 0, meta.lastCheckedAt ?? 0, meta.startedAt);
+  if (meta.kind !== "process") return recorded;
+  try {
+    return Math.max(recorded, Math.trunc(statSync(meta.logPath).mtimeMs));
+  } catch {
+    return recorded;
+  }
+}
+
+export function observeBackgroundTaskStall(meta: BackgroundTaskMeta, now = Date.now()): StallObservation {
+  return observeStall({
+    now,
+    lastProgressAt: backgroundTaskProgressAt(meta),
+    startedAt: meta.startedAt,
+    exempt: meta.status !== "running",
+    thresholds: backgroundTaskStallThresholds(),
+  });
+}

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({

package/src/types.ts

@@ -46,6 +46,8 @@ export interface BackgroundTaskMeta {
   deadlineAt?: number;
   intervalMs?: number;
   lastCheckedAt?: number;
+  /** Latest command completion or observed process log output. */
+  lastProgressAt?: number;
   lastExitCode?: number | null;
   lastSignal?: NodeJS.Signals | null;
   lastState?: unknown;