pi-famulus 0.1.0

package/src/tui/message-renderers.ts

@@ -0,0 +1,183 @@
+/**
+ * Custom message renderers for Famulus notifications (Claude-style compact pills).
+ *
+ * Box is `(paddingX, paddingY, bgFn)` — the second argument is vertical padding,
+ * not a child gap. `outputPad` is the horizontal pad (0 or 1), matching pi's
+ * custom-message boxes which use `new Box(1, 1, bg)`.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { FAMULUS_WAKE_CUSTOM_TYPE, FAMULUS_WAKE_LEAD_IN, type FamulusWake, type TaskWake } from "../wake";
+import { fitLines, loadPiTui } from "./pi-tui-load";
+import { statusGlyph } from "./tool-component";
+
+type Theme = {
+  fg(color: string, text: string): string;
+  bg(color: string, text: string): string;
+};
+
+type PillComponent = {
+  render(width: number): string[];
+  invalidate(): void;
+};
+
+const STATUS_ORDER = [
+  "completed",
+  "failed",
+  "interrupted",
+  "killed",
+  "orphaned",
+  "pending",
+  "running",
+  "partial",
+  "timeout",
+  "stopped",
+];
+
+function countStatuses(statuses: string[]): string {
+  const counts = new Map<string, number>();
+  for (const status of statuses) counts.set(status, (counts.get(status) ?? 0) + 1);
+  const parts = STATUS_ORDER.filter((status) => counts.has(status)).map(
+    (status) => `${counts.get(status)} ${status}`,
+  );
+  return parts.join(" · ");
+}
+
+function badExit(status: string | undefined, exitCode?: number | null): boolean {
+  if (exitCode !== undefined && exitCode !== null && exitCode !== 0) return true;
+  return status === "failed" || status === "killed" || status === "orphaned" || status === "interrupted";
+}
+
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${Math.floor(ms / 60_000)}m${Math.round((ms % 60_000) / 1000)}s`;
+}
+
+function taskExit(task: TaskWake): string {
+  if (task.exitCode !== null) return `exit ${task.exitCode}`;
+  return task.signal ?? task.status;
+}
+
+function taskHead(details: Extract<FamulusWake, { kind: "task" }>): string {
+  const taskInfo = details.tasks.length === 1
+    ? `${formatDuration(details.tasks[0].durationMs)} · ${taskExit(details.tasks[0])}`
+    : `${details.tasks.length} tasks · ${countStatuses(details.tasks.map((task) => task.status))}`;
+  const still = details.stillRunning.length > 0 ? ` · ${details.stillRunning.length} still running` : "";
+  const summary = details.tasks.length === 1 ? details.tasks[0].summary : "Background work";
+  return `${summary} · ${taskInfo}${still}`;
+}
+
+function collapsedText(details: FamulusWake, theme: Theme): string {
+  switch (details.kind) {
+    case "task": {
+      const bad = details.tasks.some((task) => badExit(task.status, task.exitCode));
+      const { color, glyph } = statusGlyph(bad ? "failed" : "completed");
+      return `${theme.fg(color, glyph)} ${theme.fg("muted", "task")} ${taskHead(details)}`;
+    }
+    case "monitor": {
+      const preview = details.event.split("\n").find((line) => line.trim().length > 0)?.trim() ?? "(event)";
+      const { color, glyph } = details.status
+        ? statusGlyph(details.status)
+        : { color: "accent", glyph: "›" };
+      const statusBit = details.status ? ` ${theme.fg("dim", `· ${details.status}`)}` : "";
+      const countBit = details.eventCount && details.eventCount > 1
+        ? ` ${theme.fg("dim", `· ${details.eventCount} events`)}`
+        : "";
+      const droppedBit = details.droppedLines
+        ? ` ${theme.fg("warning", `· ${details.droppedLines} lines dropped`)}`
+        : "";
+      return `${theme.fg(color, glyph)} ${theme.fg("muted", "monitor")} ${theme.fg("accent", `"${details.description}"`)}${statusBit}${countBit}${droppedBit}\n${theme.fg("dim", preview)}`;
+    }
+    case "subagent-handover": {
+      const { color, glyph } = statusGlyph(details.status);
+      const snippet = details.result.replace(/\s+/g, " ").trim().slice(0, 72);
+      return `${theme.fg(color, glyph)} ${theme.fg("muted", "handover")} ${details.name} ${details.status}${snippet ? ` · ${snippet}` : ""}`;
+    }
+    case "subagent-done": {
+      const bad = details.children.some((child) => badExit(child.status));
+      const { color, glyph } = statusGlyph(bad ? "failed" : details.status);
+      return `${theme.fg(color, glyph)} ${theme.fg("muted", "subagent")} ${countStatuses(details.children.map((child) => child.status))}`;
+    }
+    case "supervisor-request":
+      return [
+        `${theme.fg("warning", "?")} ${theme.fg("muted", `decision for ${details.name}`)} ${details.message.slice(0, 100)}`,
+        theme.fg("dim", `/reply ${details.from} <decision>`),
+      ].join("\n");
+    case "supervisor-update":
+      return `${theme.fg("muted", "↑")} ${theme.fg("muted", "supervisor update")} ${details.message.slice(0, 100)}`;
+  }
+}
+
+export function expandedWakeText(details: FamulusWake | undefined, content: string): string {
+  if (!details) {
+    return content
+      .replace(FAMULUS_WAKE_LEAD_IN, "")
+      .replace(/<[^>]+>/g, " ")
+      .replace(/&lt;/g, "<")
+      .replace(/&gt;/g, ">")
+      .replace(/&amp;/g, "&")
+      .trim();
+  }
+  switch (details.kind) {
+    case "task":
+      return [
+        `Tasks (${details.tasks.length})`,
+        ...details.tasks.map((task) => [
+          `${task.id} · ${task.taskKind} · ${task.status} · ${formatDuration(task.durationMs)} · ${taskExit(task)}`,
+          `$ ${task.command}`,
+          `Output: ${task.outputPath}`,
+          ...(task.preview ? [`Preview: ${task.preview}`] : []),
+        ].join("\n")),
+        ...(details.stillRunning.length ? [`Still running (${details.stillRunning.length}): ${details.stillRunning.map((item) => `${item.id} ${item.title}`).join(", ")}`] : []),
+      ].join("\n\n");
+    case "monitor":
+      return [`Monitor: ${details.description}`, `Task: ${details.id}`, ...(details.status ? [`Status: ${details.status}`] : []), `Event: ${details.event}`, ...(details.eventCount ? [`Events: ${details.eventCount}`] : []), ...(details.droppedLines ? [`Dropped lines: ${details.droppedLines}`] : [])].join("\n");
+    case "subagent-handover":
+      return [`Subagent handover: ${details.name} (${details.status})`, `Run: ${details.runId}`, `Child: ${details.childId}`, `Task prompt: ${details.prompt}`, `Result: ${details.result}`, ...(details.error ? [`Error: ${details.error}`] : []), ...(details.stillRunning.length ? [`Still running: ${details.stillRunning.map((item) => `${item.id} ${item.title}`).join(", ")}`] : [])].join("\n\n");
+    case "subagent-done":
+      return [`Subagent run: ${details.runId} (${details.status})`, `Duration: ${formatDuration(details.durationMs)}`, ...details.children.map((child) => [`${child.name} (${child.childId}) · ${child.status}`, `Task prompt: ${child.prompt}`, `Result: ${child.result}`, ...(child.error ? [`Error: ${child.error}`] : [])].join("\n"))].join("\n\n");
+    case "supervisor-request":
+      return [`Decision requested by ${details.name} (${details.from})`, `Request: ${details.message}`, `Reply with /reply ${details.from} <decision>`].join("\n");
+    case "supervisor-update":
+      return [`Update from ${details.name} (${details.from})`, details.message].join("\n");
+  }
+}
+
+function wakeDetails(message: { details?: unknown }): FamulusWake | undefined {
+  const details = message.details as FamulusWake | undefined;
+  if (!details || typeof details !== "object" || !("kind" in details)) return undefined;
+  return details;
+}
+
+function makeComponent(pad: number, theme: Theme, text: string): PillComponent {
+  const tui = loadPiTui();
+  if (tui) {
+    // paddingX = outputPad, paddingY = 1 (blank line above/below), then bg.
+    const box = new tui.Box(pad, 1, (s) => theme.bg("customMessageBg", s));
+    box.addChild(new tui.Text(text, 0, 0));
+    const rendered = box as unknown as { render(width: number): string[]; invalidate(): void };
+    if (typeof rendered.invalidate !== "function") {
+      rendered.invalidate = () => {};
+    }
+    return rendered;
+  }
+  return {
+    render(width: number) {
+      const inner = Math.max(1, width - pad * 2);
+      const padStr = " ".repeat(Math.max(0, pad));
+      return fitLines(text, inner).map((line) => padStr + line);
+    },
+    invalidate() {},
+  };
+}
+
+export function registerFamulusMessageRenderers(pi: ExtensionAPI): void {
+  pi.registerMessageRenderer(FAMULUS_WAKE_CUSTOM_TYPE, (message, { expanded, outputPad }, theme) => {
+    const details = wakeDetails(message);
+    const content = typeof message.content === "string" ? message.content : "";
+    const head = details ? collapsedText(details, theme) : theme.fg("muted", "wake");
+    const body = expanded && content ? `\n${theme.fg("dim", expandedWakeText(details, content))}` : "";
+    return makeComponent(outputPad, theme, head + body) as never;
+  });
+}
+

package/src/tui/pi-tui-load.ts

@@ -0,0 +1,186 @@
+/**
+ * Resolve `@earendil-works/pi-tui` from the host pi install.
+ * Typed structurally so this package does not depend on pi-tui's declarations.
+ */
+import * as bundledPiTui from "@earendil-works/pi-tui";
+
+export interface PiTuiText {
+  setText(text: string): void;
+  invalidate(): void;
+}
+
+export interface PiTuiScroll {
+  viewportHeight: number;
+  scrollBy(lines: number): number;
+  scrollToEnd(): void;
+  invalidate(): void;
+}
+
+export interface PiTuiComponent {
+  render(width: number): string[];
+  invalidate(): void;
+}
+
+export interface PiTuiModule {
+  Text: new (text?: string, paddingX?: number, paddingY?: number) => PiTuiText & PiTuiComponent;
+  ScrollView: new (
+    component: PiTuiComponent,
+    options?: {
+      primary?: boolean;
+      scrollbar?: "hidden" | "auto" | "always";
+      follow?: "none" | "end";
+      overscroll?: "chain" | "contain";
+    },
+  ) => PiTuiScroll & PiTuiComponent;
+  VStack: new (
+    children?: Array<
+      | PiTuiComponent
+      | {
+          component: PiTuiComponent;
+          basis?: number | "auto";
+          grow?: number;
+          shrink?: number;
+          minSize?: number;
+        }
+    >,
+    options?: { gap?: number },
+  ) => PiTuiComponent;
+  matchesKey(data: string, key: string): boolean;
+  Box: new (
+    paddingX?: number,
+    paddingY?: number,
+    bgFn?: (text: string) => string,
+  ) => { addChild(component: unknown): void };
+}
+
+export interface PiTuiWidth {
+  visibleWidth(text: string): number;
+  truncateToWidth(text: string, maxWidth: number, ellipsis?: string): string;
+  wrapTextWithAnsi(text: string, width: number): string[];
+}
+
+let fallbackWarningLogged = false;
+
+function warnFallbackOnce(): void {
+  if (fallbackWarningLogged) return;
+  fallbackWarningLogged = true;
+  console.warn(
+    "pi-famulus: pi-tui is unavailable; using the reduced text fallback. " +
+      "Load this extension through pi to enable interactive task views and full-width rendering.",
+  );
+}
+
+export function loadPiTui(): PiTuiModule | null {
+  if (forcedTui !== undefined) {
+    if (forcedTui === null) warnFallbackOnce();
+    return forcedTui;
+  }
+  // pi's extension loader aliases this static specifier to its bundled TUI in
+  // both jiti and compiled-binary modes. Resolving it relative to argv[1] is
+  // incorrect when pi is launched through a package-manager shim.
+  return bundledPiTui as unknown as PiTuiModule;
+}
+
+let widthFns: PiTuiWidth | null | undefined;
+let forcedTui: PiTuiModule | null | undefined;
+
+/** Test hook. `null` forces the no-pi-tui fallback; `undefined` restores normal resolution. */
+export function setPiTuiForTests(mod: PiTuiModule | null | undefined): void {
+  forcedTui = mod;
+  widthFns = undefined;
+}
+
+function widthApi(): PiTuiWidth | null {
+  if (widthFns !== undefined) return widthFns;
+  const tui = (forcedTui !== undefined ? forcedTui : loadPiTui()) as (PiTuiModule & Partial<PiTuiWidth>) | null;
+  if (tui && typeof tui.visibleWidth === "function" && typeof tui.truncateToWidth === "function" && typeof tui.wrapTextWithAnsi === "function") {
+    widthFns = {
+      visibleWidth: tui.visibleWidth.bind(tui),
+      truncateToWidth: tui.truncateToWidth.bind(tui),
+      wrapTextWithAnsi: tui.wrapTextWithAnsi.bind(tui),
+    };
+    return widthFns;
+  }
+  if (!tui) warnFallbackOnce();
+  widthFns = null;
+  return null;
+}
+
+/** Visible columns, ANSI stripped. Falls back to a CJK-aware counter if pi-tui is absent. */
+export function visibleWidth(text: string): number {
+  const api = widthApi();
+  if (api) return api.visibleWidth(text);
+  return fallbackVisibleWidth(text);
+}
+
+export function truncateToWidth(text: string, maxWidth: number, ellipsis = "…"): string {
+  const api = widthApi();
+  if (api) return api.truncateToWidth(text, maxWidth, ellipsis);
+  return fallbackTruncate(text, maxWidth, ellipsis);
+}
+
+export function wrapTextWithAnsi(text: string, width: number): string[] {
+  const api = widthApi();
+  if (api) return api.wrapTextWithAnsi(text, Math.max(1, width));
+  return fallbackWrap(text, Math.max(1, width));
+}
+
+/** Wrap, then hard-truncate any line that is still too wide (ANSI-safe). */
+export function fitLines(text: string, width: number): string[] {
+  const limit = Math.max(1, width);
+  const wrapped = wrapTextWithAnsi(text, limit);
+  return wrapped.map((line) => (visibleWidth(line) > limit ? truncateToWidth(line, limit, "…") : line));
+}
+
+function stripAnsi(text: string): string {
+  return text.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function fallbackVisibleWidth(text: string): number {
+  let n = 0;
+  for (const ch of stripAnsi(text)) {
+    const cp = ch.codePointAt(0) ?? 0;
+    n += cp > 0xff ? 2 : 1;
+  }
+  return n;
+}
+
+function fallbackTruncate(text: string, maxWidth: number, ellipsis: string): string {
+  if (maxWidth <= 0) return "";
+  if (fallbackVisibleWidth(text) <= maxWidth) return text;
+  const ell = fallbackVisibleWidth(ellipsis) >= maxWidth ? "" : ellipsis;
+  const budget = maxWidth - fallbackVisibleWidth(ell);
+  let out = "";
+  let n = 0;
+  for (const ch of stripAnsi(text)) {
+    const w = (ch.codePointAt(0) ?? 0) > 0xff ? 2 : 1;
+    if (n + w > budget) break;
+    out += ch;
+    n += w;
+  }
+  return out + ell;
+}
+
+function fallbackWrap(text: string, width: number): string[] {
+  const out: string[] = [];
+  for (const raw of text.split("\n")) {
+    if (fallbackVisibleWidth(raw) <= width) {
+      out.push(raw);
+      continue;
+    }
+    let cur = "";
+    let n = 0;
+    for (const ch of raw) {
+      const w = (ch.codePointAt(0) ?? 0) > 0xff ? 2 : 1;
+      if (n + w > width && cur) {
+        out.push(cur);
+        cur = "";
+        n = 0;
+      }
+      cur += ch;
+      n += w;
+    }
+    out.push(cur);
+  }
+  return out.length > 0 ? out : [""];
+}

package/src/tui/scroll-detail-view.ts

@@ -0,0 +1,190 @@
+/**
+ * Full-screen detail panel for /tasks.
+ *
+ * pi's `ui.custom()` without `overlay` replaces the editor, and ScrollView only
+ * clips when the chat layout engine owns it. This panel is a full-screen overlay
+ * that slices its own lines, so wheel / page keys scroll and terminal selection
+ * can copy the visible text.
+ */
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { fitLines, loadPiTui, truncateToWidth } from "./pi-tui-load";
+import { realClock, type Clock, type ClockTimer } from "../clock";
+
+export type TaskDetailTab = "output" | "stderr" | "info" | "conversation" | "result";
+
+const TAB_ORDER: TaskDetailTab[] = ["output", "stderr", "info", "conversation", "result"];
+const TAB_LABEL: Record<TaskDetailTab, string> = {
+  output: "output",
+  stderr: "stderr",
+  info: "info",
+  conversation: "conversation",
+  result: "result",
+};
+
+export interface ScrollDetailOptions {
+  title: string;
+  /** Named panes; shortcuts 1/2/3 and Tab cycle through the provided panes. */
+  tabs?: Partial<Record<TaskDetailTab, () => string>>;
+  /** Single-pane content (subagent conversation). */
+  content?: () => string;
+  /** Poll for live updates while the task is running. */
+  pollMs?: number;
+  followEnd?: boolean;
+  clock?: Clock;
+}
+
+/** Wrap on visible width. ANSI is preserved; CJK is not split by JS length. */
+export function wrapLines(text: string, width: number): string[] {
+  return fitLines(text, Math.max(1, width));
+}
+
+export function visibleDetailTabs(tabs: ScrollDetailOptions["tabs"]): TaskDetailTab[] {
+  const order = tabs?.conversation ? ["conversation", "result", "info"] as const : TAB_ORDER;
+  return order.filter((key) => Boolean(tabs?.[key]));
+}
+
+export function fitTitle(title: string, width: number): string {
+  return truncateToWidth(title, Math.max(1, width), "…");
+}
+
+export async function showScrollDetail(ui: ExtensionUIContext, options: ScrollDetailOptions): Promise<void> {
+  const piTui = loadPiTui();
+  if (!piTui) throw new Error("pi-tui is not available");
+  const { matchesKey } = piTui;
+  await ui.custom<void>(
+    (tui, theme, _kb, done) => {
+      const tabKeys = () => visibleDetailTabs(options.tabs);
+      let tab: TaskDetailTab = tabKeys()[0] ?? "output";
+      let follow = options.followEnd !== false;
+      let scroll = 0;
+      let stuckToEnd = follow;
+      let timer: ClockTimer | null = null;
+      const clock = options.clock ?? realClock;
+      let disposed = false;
+      let lastLineCount = 0;
+
+      function source(): string {
+        return options.tabs?.[tab]?.() ?? options.content?.() ?? "";
+      }
+
+      function bodyHeight(width: number): { lines: string[]; height: number } {
+        const rows = Math.max(8, tui.terminal?.rows ?? 24);
+        const chrome = (options.tabs ? 2 : 1) + 1;
+        const height = Math.max(1, rows - chrome - 1);
+        return { lines: wrapLines(source(), Math.max(1, width - 2)), height };
+      }
+
+      function refresh(): void {
+        if (!disposed) tui.requestRender();
+      }
+
+      if (options.pollMs && options.pollMs > 0) {
+        timer = clock.setInterval(refresh, options.pollMs);
+        clock.unref?.(timer);
+      }
+
+      return {
+        render(width: number) {
+          const { lines, height } = bodyHeight(width);
+          const maxScroll = Math.max(0, lines.length - height);
+          if (lines.length !== lastLineCount) {
+            if (stuckToEnd) scroll = maxScroll;
+            lastLineCount = lines.length;
+          }
+          scroll = Math.max(0, Math.min(scroll, maxScroll));
+          stuckToEnd = follow && scroll >= maxScroll;
+
+          const dim = (s: string) => theme.fg("dim", s);
+          const accent = (s: string) => theme.fg("accent", s);
+          const head = accent(fitTitle(options.title, Math.max(1, width - 2)));
+          const keys = tabKeys();
+          const tabLine = keys.length > 0
+            ? `${keys.map((key, index) => tab === key ? accent(`▸ ${index + 1} ${TAB_LABEL[key]}`) : dim(`  ${index + 1} ${TAB_LABEL[key]}`)).join("    ")}  ${dim("· Tab cycle · f follow")}`
+            : "";
+          const visible = lines.slice(scroll, scroll + height);
+          while (visible.length < height) visible.push("");
+          const place =
+            lines.length <= height ? "" : `  ${scroll + 1}–${Math.min(lines.length, scroll + height)}/${lines.length}`;
+          const foot = dim(`↑↓ PgUp PgDn scroll · f follow ${follow ? "on" : "off"} · Esc close${place}`);
+          return [head, ...(tabLine ? [tabLine] : []), ...visible, foot];
+        },
+        invalidate() {},
+        handleInput(data: string) {
+          const width = Math.max(20, tui.terminal?.columns ?? 80);
+          const { lines, height } = bodyHeight(width);
+          const maxScroll = Math.max(0, lines.length - height);
+          const move = (next: number) => {
+            scroll = Math.max(0, Math.min(maxScroll, next));
+            stuckToEnd = follow && scroll >= maxScroll;
+            tui.requestRender();
+          };
+          if (matchesKey(data, "escape") || data === "q") {
+            done();
+            return;
+          }
+          const keys = tabKeys();
+          const shortcut = /^[123]$/.test(data) ? Number(data) - 1 : -1;
+          if (keys.length > 0 && (matchesKey(data, "tab") || data === "\t")) {
+            const current = keys.indexOf(tab);
+            tab = keys[(current + 1) % keys.length];
+            scroll = 0;
+            stuckToEnd = follow;
+            tui.requestRender();
+            return;
+          }
+          if (shortcut >= 0 && shortcut < keys.length) {
+            tab = keys[shortcut];
+            scroll = 0;
+            stuckToEnd = follow;
+            tui.requestRender();
+            return;
+          }
+          if (data === "f" || data === "F") {
+            follow = !follow;
+            if (follow) scroll = Math.max(0, bodyHeight(width).lines.length - bodyHeight(width).height);
+            stuckToEnd = follow;
+            tui.requestRender();
+            return;
+          }
+          if (matchesKey(data, "up")) move(scroll - 1);
+          else if (matchesKey(data, "down")) move(scroll + 1);
+          else if (matchesKey(data, "pageUp")) move(scroll - Math.max(1, height - 1));
+          else if (matchesKey(data, "pageDown")) move(scroll + Math.max(1, height - 1));
+          else if (matchesKey(data, "home")) move(0);
+          else if (matchesKey(data, "end")) move(maxScroll);
+        },
+        handleMouse(event: { type: string; wheelDelta?: number }) {
+          if (event.type !== "wheel" || !event.wheelDelta) return undefined;
+          const width = Math.max(20, tui.terminal?.columns ?? 80);
+          const { lines, height } = bodyHeight(width);
+          const maxScroll = Math.max(0, lines.length - height);
+          scroll = Math.max(0, Math.min(maxScroll, scroll + event.wheelDelta));
+          stuckToEnd = follow && scroll >= maxScroll;
+          return { handled: true };
+        },
+        dispose() {
+          disposed = true;
+          if (timer !== null) clock.clearInterval(timer);
+        },
+      };
+    },
+    {
+      overlay: true,
+      overlayOptions: {
+        anchor: "bottom-left",
+        width: "100%",
+        maxHeight: "100%",
+        margin: 0,
+      },
+    },
+  );
+}
+
+/** Fallback when pi-tui cannot load (should not happen in interactive mode). */
+export function notifyPlainFallback(
+  notify: (message: string, type?: "info" | "warning" | "error") => void,
+  title: string,
+  text: string,
+): void {
+  notify(`${title}\n${text.slice(0, 4000)}`, "info");
+}

package/src/tui/task-output-paths.ts

@@ -0,0 +1,46 @@
+import { statSync } from "node:fs";
+import { readFileTail } from "../file-tail";
+
+/** Sibling stderr file next to `<id>.output` (matches pi-famulus). */
+export function stderrPathFor(outputPath: string): string {
+  if (!outputPath) return "";
+  const dot = outputPath.lastIndexOf(".");
+  if (dot > 0) return `${outputPath.slice(0, dot)}.stderr`;
+  return `${outputPath}.stderr`;
+}
+
+const tailCache = new Map<string, { size: number; mtimeMs: number; text: string }>();
+
+export function readTaskFileTail(path: string, maxBytes = 512_000): string {
+  if (!path) return "(no output path)";
+  const tail = readFileTail(path, maxBytes);
+  if (!tail) return "(empty)";
+  if (tail.size === 0) return "(empty)";
+  if (tail.size <= maxBytes) return tail.text;
+  return `… (${tail.size} bytes total, showing last ${maxBytes})\n${tail.text}`;
+}
+
+/**
+ * Tail read cached by size+mtime. Callers should only ask for the tab they are showing.
+ */
+export function readTaskFileTailCached(path: string, maxBytes = 512_000): string {
+  if (!path) return "(no output path)";
+  let size = 0;
+  let mtimeMs = 0;
+  try {
+    const st = statSync(path);
+    size = st.size;
+    mtimeMs = st.mtimeMs;
+  } catch {
+    return readTaskFileTail(path, maxBytes);
+  }
+  const hit = tailCache.get(path);
+  if (hit && hit.size === size && hit.mtimeMs === mtimeMs) return hit.text;
+  const text = readTaskFileTail(path, maxBytes);
+  tailCache.set(path, { size, mtimeMs, text });
+  return text;
+}
+
+export function clearTaskFileTailCache(): void {
+  tailCache.clear();
+}