pi-better-background-tasks 0.2.20 → 0.4.0

package/README.md

@@ -39,6 +39,14 @@ If the foreground sandbox reports `unavailable` or `failed`, a local launch is
 refused with an explanation instead of running unconfined. `/sandbox off` is the
 deliberate way to run local tasks unsandboxed.
 
+A task follows Main's permission profile. With Main's Outside project = Write, the
+task writes across home and temp but can remove files outside the project only in
+temp, hidden home directories, and worktree folders (see
+[pi-better-sandbox](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-sandbox#readme)).
+On macOS, a task launched with Outside project = Write or Write & delete starts an
+APFS local snapshot (`tmutil localsnapshot`) in the background as a recovery aid.
+A failed snapshot is noted in the task log and never blocks the task.
+
 Structured remote SSH tasks are unaffected: the foreground sandbox describes this
 machine, and remote work keeps its existing remote semantics. Without
 `pi-better-sandbox` installed, local tasks behave exactly as they always have.
@@ -80,6 +88,21 @@ timeout can terminate the local SSH client but the remote process may still be
 running. See the detailed usage notes for bootstrap policy, watch conditions,
 timeouts, and v1 non-goals.
 
+## Reloads and session switches
+
+Tasks belong to the Pi session that started them. After `/reload`, the same
+session picks every task back up: watches keep polling, remote tmux output keeps
+being collected, and a task that finished during the reload (or exits later) gets
+its completion callback exactly once.
+
+After `/new`, `/resume`, fork, or switching to another session, the previous
+session's tasks keep running but are paused from Pi's side: watches do not poll,
+remote tmux output is not collected, and `timeout_seconds` deadlines are not
+enforced until that session is active again. An overdue deadline is enforced as
+soon as the session resumes, so a timeout can land late but is never skipped. A
+local process that exits in the meantime is recorded as finished, and its
+callback is delivered when its session resumes.
+
 ## Watch conditions
 
 JSON conditions require a root-prefixed path, such as `$.status` or
@@ -125,13 +148,34 @@ 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
+Pass `operation_id` and `expected_exit_codes` on `bg_task_spawn`, `bg_task_watch`,
+or `bg_task` to declare intent before launch; a malformed declaration starts
+nothing. An exit code in `expected_exit_codes` (distinct integers 1-255, such as
+`[1]` for a no-match probe) is recorded as an **Expected failure** that needs no
+action; signals and timeouts never are. When a task with an `operation_id`
+succeeds, earlier failed tasks with the same `operation_id`, kind, cwd, SSH
+target, and owner (the same session id, or for sessionless tasks the same Pi
+process) recover, so a retry with a changed command or timeout
+closes the original incident. Observation gaps are never recovered this way, and
+no command text is compared.
+
+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
 existing retention and explicit-clear behavior.
 
+Status, log, and list count and list only failures that need action (**Action
+required** and **Observation incomplete**). Expected and closed failures are one
+history count line with no incident cursor; pass `history: true` to
+`bg_task_status` (or `action:status`) to page them. Incident rows are compact
+(120-byte excerpt, evidence such as `output.log#poll=3`); the raw log keeps the
+full evidence path.
+
 ## When To Use
 
 Use this package for shell commands that need logs, status, cancellation, or completion notifications across a Pi turn.

package/package.json

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

package/src/failures.ts

@@ -1,11 +1,12 @@
 import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
-  failureAttentionHandled, failureIdentity, formatFailureSummary, markFailureAttentionDelivered,
-  observeFailures, pendingFailureAttention, readFailureState,
+  activeFailures, failureAttentionHandled, failureIdentity, formatFailureSummary, markFailureAttentionDelivered,
+  observeFailures, pendingAttentionNote, pendingAttentionRows, pendingFailureAttention, readCommandIntent, readFailureState,
+  type FailureEvent, type FailureState,
 } from "./shared-failure-observations.js";
 import { getCallbackBatcher } from "./shared-callback-batcher.js";
-import { readMeta, taskDir } from "./registry.js";
+import { listMetasForOrigin, originOf, readMeta, taskDir } from "./registry.js";
 import type { ActiveSessionProvider } from "./runtime.js";
 import type { BackgroundTaskMeta } from "./types.js";
 
@@ -32,16 +33,112 @@ export function recoverFailure(meta: BackgroundTaskMeta, operation: string, even
   }]);
 }
 
+/**
+ * Validate `operation_id` / `expected_exit_codes` before anything is launched (#325), with the same
+ * validator the subagent task runtime's bash uses. Background commands are launched by the parent
+ * agent itself, so the declaration is trusted; a malformed one refuses the launch.
+ */
+export function readTaskIntent(params: { operation_id?: unknown; expected_exit_codes?: unknown }): Pick<BackgroundTaskMeta, "operationId" | "expectedExitCodes"> {
+  const { intent, error } = readCommandIntent({ operationId: params.operation_id, expectedExitCodes: params.expected_exit_codes },
+    { operationId: "operation_id", expectedExitCodes: "expected_exit_codes" });
+  if (error) throw new Error(`Invalid command intent: ${error}. The task was not started.`);
+  return { ...(intent.operationId ? { operationId: intent.operationId } : {}), ...(intent.expectedExitCodes ? { expectedExitCodes: intent.expectedExitCodes } : {}) };
+}
+
+/** A structured exit code the caller declared intentional before launch. Signals and timeouts never are. */
+export function isDeclaredExpectedExit(meta: BackgroundTaskMeta, exitCode: number | null | undefined): exitCode is number {
+  return typeof exitCode === "number" && exitCode !== 0 && (meta.expectedExitCodes ?? []).includes(exitCode);
+}
+
+/** Record a non-zero command exit, classified as expected only when its code was declared before launch. */
+export function recordExitFailure(meta: BackgroundTaskMeta, operation: string, summary: string, exitCode: number | null | undefined, eventKey: unknown,
+  options: { at?: number; expected?: boolean } = {}): void {
+  const declared = isDeclaredExpectedExit(meta, exitCode);
+  recordFailure(meta, operation, declared ? `${summary} (declared expected)` : summary, eventKey,
+    { category: "exit", expected: declared || options.expected === true, at: options.at });
+}
+
+function declaredOperation(meta: BackgroundTaskMeta): string | undefined {
+  return meta.operationId ? failureIdentity("bg-operation", meta.kind, meta.operationId, meta.cwd, meta.ssh?.target ?? null) : undefined;
+}
+
+/**
+ * Recovery crosses tasks only within one owner (#325): the same non-empty session id, or, for
+ * sessionless tasks, the same spawning process (#312's sessionless ownership rule). The origin
+ * index alone treats two sessionless sessions in one cwd as one origin.
+ */
+function sameRecoveryOwner(a: BackgroundTaskMeta, b: BackgroundTaskMeta): boolean {
+  const sa = a.callbackOrigin?.sessionId, sb = b.callbackOrigin?.sessionId;
+  if (sa || sb) return Boolean(sa) && sa === sb;
+  return a.spawnPid === b.spawnPid && a.spawnPidStartTime === b.spawnPidStartTime;
+}
+
+/**
+ * A task that succeeded with a declared `operationId` recovers the unresolved failures of earlier
+ * tasks of the same owner (session, or spawning process when sessionless) that declared the same operation (same kind, cwd, and SSH target) and
+ * failed before this task started: a modified retry as a new task. Observation gaps and expected
+ * failures are left alone; nothing is matched on command text.
+ */
+export function recoverDeclaredOperation(meta: BackgroundTaskMeta, at = Date.now()): void {
+  const operation = declaredOperation(meta);
+  if (!operation) return;
+  let earlier: BackgroundTaskMeta[];
+  try { earlier = listMetasForOrigin(originOf(meta)); } catch { return; }
+  for (const task of earlier) {
+    if (task.id === meta.id || task.startedAt >= meta.startedAt || declaredOperation(task) !== operation || !sameRecoveryOwner(task, meta)) continue;
+    const path = failurePath(task.id);
+    const events: FailureEvent[] = activeFailures(readFailureState(path))
+      .filter((x) => x.status === "unresolved" && x.category !== "observation-incomplete" && x.lastObservedAt <= meta.startedAt)
+      .map((x) => ({ id: failureIdentity(task.id, x.id, "recovered-by", meta.id), operation: x.operation, kind: "recovered", incidents: [x.id], at,
+        evidence: `task ${meta.id} (operation ${meta.operationId}) succeeded` }));
+    if (events.length) observeFailures(path, events);
+  }
+}
+
 const attentionTimers = new Map<string, ReturnType<typeof setTimeout>>();
+let attentionSuspended = false;
+/** Session shutdown: stop this instance's attention timers; the next session_start reschedules (#324). */
+export function suspendFailureAttention(): void {
+  attentionSuspended = true;
+  for (const timer of attentionTimers.values()) clearTimeout(timer);
+  attentionTimers.clear();
+}
+export function resumeFailureAttention(): void {
+  attentionSuspended = false;
+}
 export function stopFailureAttention(id: string): void {
   const timer = attentionTimers.get(id);
   if (timer) clearTimeout(timer);
   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);
+  if (attentionSuspended) return;
   const meta = readMeta(id);
   if (!meta) {
     const timer = setTimeout(() => scheduleFailureAttention(pi, id, getActiveSession), 1_000);
@@ -54,9 +151,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/index.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { disposeBackgroundWorkNavigator } from "./shared-navigator.ts";
 import { registerBackgroundTasksGoalProvider } from "./goal-provider.js";
 import { clearBackgroundTasksNavigatorSession, ensureBackgroundTasksNavigator, ensureBackgroundTasksNavigatorProvider } from "./navigator-provider.js";
+import { resumeScheduledWork, suspendScheduledWork } from "./runtime.js";
 import { observeForegroundSandboxPolicy } from "./sandbox.js";
 import { registerTools } from "./tools.js";
 
@@ -11,7 +12,9 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
   // Subscribed at load so a sandbox extension that publishes later is heard, and
   // asked for a snapshot in case one published before this extension existed.
   observeForegroundSandboxPolicy(pi);
+  // Registered before registerTools(pi), so this runs before running tasks are resumed.
   pi.on("session_start", async (_event, ctx) => {
+    resumeScheduledWork();
     registerBackgroundTasksGoalProvider(pi);
     ensureBackgroundTasksNavigator(ctx);
   });
@@ -20,6 +23,8 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
     disposeBackgroundWorkNavigator();
   });
   pi.on("session_shutdown", async (_event, ctx) => {
+    // /reload, session replacement, and quit load a fresh instance; stop this one's timers (#324).
+    suspendScheduledWork();
     clearBackgroundTasksNavigatorSession();
     disposeBackgroundWorkNavigator(ctx);
   });

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

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
+  DEFAULT_LOG_TAIL_ROWS as NAVIGATOR_DETAIL_ROWS,
   ensureBackgroundWorkNavigator,
   refreshBackgroundWorkNavigator,
   registerBackgroundWorkProvider,
@@ -9,7 +10,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";
@@ -129,7 +130,7 @@ function rowFromMeta(meta: BackgroundTaskMeta, now: number): BackgroundWorkRow {
 function detailFromMeta(meta: BackgroundTaskMeta | undefined, now: number, options?: { logTailLines?: number }): BackgroundWorkDetail | null {
   if (!meta) return null;
   const failure = failureSummary(meta.id);
-  const log = readLog(meta.logPath, options?.logTailLines ?? 10);
+  const log = readLog(meta.logPath, options?.logTailLines ?? NAVIGATOR_DETAIL_ROWS);
   const command = commandLabel(meta);
   const metadata = [
     { label: "provider", value: "Background Tasks" },
@@ -217,7 +218,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");