pi-better-background-tasks 0.2.20 → 0.3.0

package/README.md

@@ -125,8 +125,11 @@ an explicitly configured nonzero success exit is treated as expected. Verbose
 status includes observation details and the journal path. Corrupt or unreadable
 evidence is reported as **observation incomplete**.
 
-Unresolved running failures become eligible for attention after 60 seconds;
-observation gaps are eligible immediately. Terminal failures use the normal
+Task failures are labeled **Action required**; the shared labels also include
+**Expected failure** and **Observation incomplete**. Unresolved running failures
+become eligible for attention after 60 seconds; observation gaps are eligible
+immediately. Each notification lists only the incidents it is delivering;
+earlier ones are counted, not repeated. Terminal failures use the normal
 completion notification. A delivery receipt is stored only after handoff;
 notification delivery does not clear the failure. `callback:false` stays quiet
 while all inspection surfaces retain the evidence. Journals follow the task's

package/package.json

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

package/src/failures.ts

@@ -2,7 +2,7 @@ import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
   failureAttentionHandled, failureIdentity, formatFailureSummary, markFailureAttentionDelivered,
-  observeFailures, pendingFailureAttention, readFailureState,
+  observeFailures, pendingAttentionNote, pendingAttentionRows, pendingFailureAttention, readFailureState, type FailureState,
 } from "./shared-failure-observations.js";
 import { getCallbackBatcher } from "./shared-callback-batcher.js";
 import { readMeta, taskDir } from "./registry.js";
@@ -39,6 +39,29 @@ export function stopFailureAttention(id: string): void {
   attentionTimers.delete(id);
 }
 
+/**
+ * Model-facing fields of a running task's failure attention. The notification
+ * identity is per incident set; the inspect target is the real task id.
+ * Only the pending incidents are rows; earlier deliveries are counted, never repeated (#315).
+ */
+export function failureAttentionFields(meta: BackgroundTaskMeta, state: FailureState, pending: { key: string; incidents: string[] }) {
+  const rows = pendingAttentionRows(state, pending.incidents);
+  const note = pendingAttentionNote(state, pending.incidents);
+  const due = pending.incidents.length;
+  return {
+    source: "background-task" as const,
+    id: `failure:${meta.id}:${pending.key}`,
+    inspectId: meta.id,
+    label: meta.name ?? meta.id,
+    status: "failure",
+    customType: "background-task-failure",
+    content: `Background task ${meta.id} is still running with ${due} failure observation${due === 1 ? "" : "s"} that need attention.${note ? ` ${note}` : ""}`,
+    detailTool: "bg_task_status" as const,
+    failureRows: rows,
+    incidentCount: rows.length || undefined,
+  };
+}
+
 /** Running incidents get one grace wake. Terminal incidents ride the completion callback. */
 export function scheduleFailureAttention(pi: ExtensionAPI, id: string, getActiveSession?: ActiveSessionProvider): void {
   stopFailureAttention(id);
@@ -54,9 +77,7 @@ export function scheduleFailureAttention(pi: ExtensionAPI, id: string, getActive
   const pending = pendingFailureAttention(state, Date.now());
   if (pending) {
     const delivery = getCallbackBatcher(pi).deliverUrgent({
-      source: "background-task", id: `failure:${id}:${pending.key}`, label: meta.name ?? id,
-      status: "failure", customType: "background-task-failure",
-      content: `Background task ${id}: ${pending.summary}\nInspect: bg_task_status id=${id}`,
+      ...failureAttentionFields(meta, state, pending),
       isDelivered: () => {
         const current = readMeta(id);
         if (!current) throw new Error("Task metadata is unavailable; defer failure notification");

package/src/logs.ts

@@ -1,8 +1,9 @@
 import { appendFileSync, closeSync, openSync, readSync, statSync, truncateSync } from "node:fs";
 import { dirname } from "node:path";
 import { mkdirSync } from "node:fs";
-import { readBoundedTail, tailTerminalDisplay, terminalDisplayRows } from "./shared-log-utils.js";
-import type { CommandResult } from "./types.js";
+import { pageRetainedFile, readBoundedTail, tailTerminalDisplay, terminalDisplayRows } from "./shared-log-utils.js";
+import type { FilePageRequest, PageResult } from "./shared-log-utils.js";
+import type { BackgroundTaskMeta, CommandResult } from "./types.js";
 
 export const DEFAULT_MAX_LOG_BYTES = 4 * 1024 * 1024;
 export const MAX_LOG_TAIL_READ_BYTES = 512 * 1024;
@@ -10,7 +11,10 @@ const RETAINED_LOG_FRACTION = 0.75;
 
 export function appendWatchResult(logPath: string, result: CommandResult): void {
   mkdirSync(dirname(logPath), { recursive: true });
-  const header = `\n--- check ${new Date(result.startedAt).toISOString()} exit=${result.exitCode ?? "null"} signal=${result.signal ?? "null"} duration_ms=${result.endedAt - result.startedAt} ---\n`;
+  const capture = result.captureTruncated
+    ? ` capture_discarded_stdout=${result.stdoutDiscardedBytes ?? 0} capture_discarded_stderr=${result.stderrDiscardedBytes ?? 0}`
+    : "";
+  const header = `\n--- check ${new Date(result.startedAt).toISOString()} exit=${result.exitCode ?? "null"} signal=${result.signal ?? "null"} duration_ms=${result.endedAt - result.startedAt}${capture} ---\n`;
   appendFileSync(logPath, header);
   if (result.stdout) appendFileSync(logPath, result.stdout.endsWith("\n") ? result.stdout : `${result.stdout}\n`);
   if (result.stderr) appendFileSync(logPath, `[stderr]\n${result.stderr.endsWith("\n") ? result.stderr : `${result.stderr}\n`}`);
@@ -27,18 +31,58 @@ export function appendTaskOutput(logPath: string, output: string): void {
   appendFileSync(logPath, output);
 }
 
-export function readLog(logPath: string, tailLines?: number): { text: string; truncated: boolean } {
+export interface LogRead {
+  text: string;
+  truncated: boolean;
+  totalBytes?: number;
+  error?: string;
+  /** Display rows before the returned tail within the bounded read window. */
+  omittedRows?: number;
+}
+
+export function readLog(logPath: string, tailLines?: number): LogRead {
   const requestedRows = tailLines && tailLines > 0 ? Math.floor(tailLines) : undefined;
   const tail = readBoundedTail(logPath, MAX_LOG_TAIL_READ_BYTES);
-  if (!tail.text) return { text: "", truncated: tail.truncated };
-  if (!requestedRows) return { text: tail.text, truncated: tail.truncated };
+  if (tail.error) {
+    return { text: "", truncated: tail.truncated, totalBytes: tail.totalBytes, error: tail.error };
+  }
+  if (!tail.text) return { text: "", truncated: false, totalBytes: tail.totalBytes };
+  if (!requestedRows) return { text: tail.text, truncated: tail.truncated, totalBytes: tail.totalBytes };
   const rows = terminalDisplayRows(tail.text);
+  const omittedRows = Math.max(0, rows.length - requestedRows);
   return {
     text: tailTerminalDisplay(tail.text, requestedRows),
-    truncated: tail.truncated || rows.length > requestedRows,
+    truncated: tail.truncated || omittedRows > 0,
+    totalBytes: tail.totalBytes,
+    ...(omittedRows > 0 ? { omittedRows } : {}),
   };
 }
 
+export function captureGapsFor(meta: BackgroundTaskMeta): Array<{ bytes: number; detail?: string }> {
+  const gaps: Array<{ bytes: number; detail?: string }> = [];
+  if (meta.stdoutDiscardedBytes) {
+    gaps.push({ bytes: meta.stdoutDiscardedBytes, detail: "stdout capture overflow" });
+  }
+  if (meta.stderrDiscardedBytes) {
+    gaps.push({ bytes: meta.stderrDiscardedBytes, detail: "stderr capture overflow" });
+  }
+  if (!gaps.length && meta.captureDiscardedBytes) {
+    gaps.push({ bytes: meta.captureDiscardedBytes, detail: `${meta.captureOverflowEvents ?? 1} capture overflow(s)` });
+  }
+  return gaps;
+}
+
+/** Page retained raw bytes with this task's generation and disclosed capture/retention loss. */
+export function pageTaskLog(meta: BackgroundTaskMeta, request: FilePageRequest = {}): PageResult {
+  return pageRetainedFile(meta.logPath, {
+    ...request,
+    resource: request.resource ?? meta.id,
+    generation: request.generation ?? meta.logGeneration ?? 0,
+    discardedBytes: request.discardedBytes ?? meta.logDiscardedBytes,
+    captureGaps: request.captureGaps ?? captureGapsFor(meta),
+  });
+}
+
 export function resolveMaxLogBytes(value: number | undefined): number {
   if (value === undefined || !Number.isFinite(value) || value <= 0) return DEFAULT_MAX_LOG_BYTES;
   return Math.max(64 * 1024, Math.floor(value));

package/src/navigator-provider.ts

@@ -9,7 +9,7 @@ import {
 } from "./shared-navigator.ts";
 import { CustomEditor } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
-import { activeFailures, readFailureState } from "./shared-failure-observations.js";
+import { activeFailures, failureLabel, readFailureState } from "./shared-failure-observations.js";
 import { failurePath, failureSummary } from "./failures.js";
 import { readLog } from "./logs.js";
 import { listMetasForOrigin, onMetaChanged, readMeta, writeMeta } from "./registry.js";
@@ -217,7 +217,7 @@ function secondaryLabel(meta: BackgroundTaskMeta): string | undefined {
 function factsForMeta(meta: BackgroundTaskMeta, now: number): string[] {
   const facts: string[] = [];
   const incident = activeFailures(readFailureState(failurePath(meta.id)))[0];
-  if (incident) facts.push(`${incident.category === "observation-incomplete" ? "Observation incomplete" : incident.status === "expected" ? "Expected failure" : "Unresolved failure"}: ${incident.summary}`);
+  if (incident) facts.push(`${failureLabel(incident)}: ${incident.summary}`);
   if (meta.status === "running") {
     const stall = observeBackgroundTaskStall(meta, now);
     if (stall.state === "stalled") facts.push("stalled");