pi-better-subagents 0.1.13 → 0.1.15

package/health-observation.ts

@@ -15,6 +15,7 @@ import { DEFAULT_MAX_READ_BYTES, readAppendedLines, type LogCursor } from "./log
 import { logPathFor } from "./registry.ts";
 import type { RunStatus } from "./registry.ts";
 import { loadConfig, type SubagentConfig } from "./config.ts";
+import { observeStall } from "./shared-stall-detector.ts";
 
 // ---- thresholds -----------------------------------------------------------
 
@@ -42,6 +43,13 @@ function positiveMs(n: unknown, fallback: number): number {
     return Number.isFinite(v) && v > 0 ? Math.floor(v) : fallback;
 }
 
+function envDuration(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;
+}
+
 /** Merge partial thresholds / config keys onto defaults. */
 export function resolveHealthThresholds(
     partial?: Partial<HealthThresholds> | Pick<
@@ -63,7 +71,11 @@ export function resolveHealthThresholds(
 
 /** Load thresholds from extension config.json (best-effort). */
 export function loadHealthThresholdsFromConfig(config: SubagentConfig = loadConfig()): HealthThresholds {
-    return resolveHealthThresholds(config);
+    return resolveHealthThresholds({
+        ...config,
+        healthQuietMs: config.healthQuietMs ?? envDuration("PI_BETTER_STALL_QUIET_MS"),
+        healthStaleMs: config.healthStaleMs ?? envDuration("PI_BETTER_STALL_MS"),
+    });
 }
 
 // ---- event facts ----------------------------------------------------------
@@ -703,37 +715,28 @@ export function observeRunHealth(input: ObserveRunHealthInput): HealthObservatio
         || modelState === "retrying"
         || modelState === "error";
 
-    let activity: ActivityHealth = "healthy";
-    if (
-        input.status === "failed"
+    const terminal = input.status === "failed"
         || input.status === "completed"
         || input.status === "killed"
         || input.status === "lost"
-        || input.status === "exited"
-    ) {
-        // Terminal runs are not residual-stale workers.
-        if (meaningfulAgeMs !== undefined && meaningfulAgeMs >= thresholds.quietMs) activity = "quiet";
-        else activity = "healthy";
-    } else if (explainedByPhase) {
-        // Active known phase: never residual stale.
-        if (meaningfulAgeMs !== undefined && meaningfulAgeMs >= thresholds.quietMs) activity = "quiet";
-        else activity = "healthy";
-    } else if (meaningfulAgeMs === undefined) {
-        if (input.startedAt !== undefined) {
-            const age = Math.max(0, now - input.startedAt);
-            if (age >= thresholds.staleMs) activity = "stale";
-            else if (age >= thresholds.quietMs) activity = "quiet";
-            else activity = "healthy";
-        } else {
-            activity = "stale";
-        }
-    } else if (meaningfulAgeMs >= thresholds.staleMs) {
-        activity = "stale";
-    } else if (meaningfulAgeMs >= thresholds.quietMs) {
-        activity = "quiet";
-    } else {
-        activity = "healthy";
-    }
+        || input.status === "exited";
+    const stall = observeStall({
+        now,
+        lastProgressAt: facts.lastMeaningfulAt,
+        startedAt: input.startedAt,
+        // Terminal work and explicit model/tool/compaction phases can be quiet,
+        // but neither is an unexplained stalled worker.
+        exempt: terminal || explainedByPhase,
+        thresholds: { quietMs: thresholds.quietMs, stallMs: thresholds.staleMs },
+    });
+    const activity: ActivityHealth = stall.state === "stalled"
+        ? "stale"
+        : stall.state === "quiet"
+            ? "quiet"
+            // Legacy metadata without any timestamp remains conservative.
+            : stall.state === "unknown" && !terminal && !explainedByPhase
+                ? "stale"
+                : "healthy";
 
     const process: ProcessObservation = {
         liveness: processLiveness(input.status, input.process?.supervised),

package/index.ts

@@ -47,6 +47,7 @@ import {
     writeMeta,
     readMeta,
     listMetas,
+    onMetaChanged,
     effectiveStatus,
     ownedByThisParent,
     navigatorVisibleRuns,
@@ -287,7 +288,7 @@ function spendFor(id: string, now: number): { usage: Usage; tool: string | null
 
 /**
  * Observe health for a widget/navigator row. Best-effort; never throws into the tick.
- * Full log parse is gated by size/mtime so the 1 Hz frame does not re-read and
+ * Full log parse is gated by size/mtime so event/detail refresh does not re-read and
  * reparse every complete log when nothing changed (#67).
  *
  * When `displayStatus` is omitted, uses durable `meta.status`.
@@ -386,7 +387,7 @@ function stopTicker(): void {
 // Reconciliation never kills anything; it only writes truth. The ticker
 // exists only while current-parent running/orphaned work needs monitoring.
 
-/** How often supervision is reconciled. Independent of the 1 Hz widget tick. */
+/** How often supervision is reconciled. Independent of TUI render scheduling. */
 const HEALTH_TICK_MS = 15_000;
 let healthTicker: ReturnType<typeof setInterval> | undefined;
 /** ExtensionAPI retained so health transitions can deliver coordinator follow-ups (#65). */
@@ -710,7 +711,7 @@ function subagentWorkRows(now: number): BackgroundWorkRow[] {
     // One registry scan per rebuild: both the start times and the rows below are
     // built from this snapshot.
     const visible = sessionVisibleNavigatorRuns(now);
-    const startedById = new Map(visible.map((m) => [m.id, m.startedAt]));
+    const metaById = new Map(visible.map((m) => [m.id, m]));
     return navigatorRows(visible, now).map((row) => {
         const bits = [];
         if (row.model) bits.push(row.effort ? `${row.model} ${row.effort}` : row.model);
@@ -730,7 +731,14 @@ function subagentWorkRows(now: number): BackgroundWorkRow[] {
             elapsed: row.elapsed,
             primary: bits.join(" · ") || "subagent run",
             facts: row.healthFacts,
-            sortStartedAt: startedById.get(row.id) ?? now,
+            sortStartedAt: metaById.get(row.id)?.startedAt ?? now,
+            expiresAt: (() => {
+                const meta = metaById.get(row.id);
+                const endedAt = meta?.endedAt ?? meta?.lostAt;
+                return meta && isTerminalNavigatorStatus(effectiveStatus(meta)) && typeof endedAt === "number"
+                    ? endedAt + TERMINAL_NAVIGATOR_RETENTION_MS
+                    : undefined;
+            })(),
         };
     });
 }
@@ -756,7 +764,7 @@ function subagentWorkDetail(id: string, now: number, options?: { logTailLines?:
         statusTone: statusTone(detail.status),
         subtitle: detail.currentTool ? `current tool ${detail.currentTool}` : undefined,
         metadata,
-        // The shared navigator refreshes this provider once a second while the
+        // The shared navigator refreshes this provider on a coarse deadline while the
         // detail overlay is open. Read the selected logical tail rows each
         // time so the evidence behaves like `tail -f`, not a single parsed
         // activity/result snapshot.
@@ -779,6 +787,7 @@ function ensureSubagentProvider(): void {
             const outcome = navigatorCloseRun(id) as { action: string; id: string; status?: string };
             return { ...outcome, providerId: "subagents" };
         },
+        onVisibleChanged: onMetaChanged,
     };
     unregisterSubagentProvider = registerBackgroundWorkProvider(provider);
 }

package/package.json

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

package/registry.ts

@@ -148,6 +148,7 @@ function metaPathFor(id: string): string {
 }
 
 let seq = 0;
+const metaChangedListeners = new Set<() => void>();
 /** Monotonic, readable, collision-free run id: `sa_<base36-time>_<seq>`. */
 export function nextRunId(): string {
     seq += 1;
@@ -157,6 +158,14 @@ export function nextRunId(): string {
 export function writeMeta(meta: RunMeta): void {
     mkdirSync(runDir(meta.id), { recursive: true });
     writeFileSync(metaPathFor(meta.id), JSON.stringify(meta, null, 2));
+    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): RunMeta | undefined {

package/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 = {
@@ -79,7 +81,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 +93,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 +170,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 +191,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 +226,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 +244,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,
@@ -462,7 +461,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 +675,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 +685,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 +709,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 +760,7 @@ function createOverlayComponent(
     if (closed) return;
     closed = true;
     clearCloseArm();
-    stopDetailTimer();
+    detailScheduler.dispose();
     try { done(null); } catch { /* ignore */ }
   }
 
@@ -842,7 +843,7 @@ function createOverlayComponent(
     invalidate() {},
     dispose() {
       clearCloseArm();
-      stopDetailTimer();
+      detailScheduler.dispose();
     },
   };
 }

package/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/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/widget.mjs

@@ -216,7 +216,7 @@ export function isSpendCacheFresh(cached, now, logSize, ttlMs = SPEND_REFRESH_MS
 /**
  * Whether a cached health-log parse is still valid for the widget tick.
  * Invalidates on log size or mtime change so growth/rewrite re-extracts, while
- * unchanged logs skip the synchronous full-log reparse on every 1 Hz frame.
+ * unchanged logs skip synchronous full-log reparses across repeated renders.
  *
  * @param {{ logSize?: number, mtimeMs?: number }|null|undefined} cached
  * @param {number} logSize