pi-better-background-tasks 0.2.16 → 0.2.17

package/README.md

@@ -80,6 +80,25 @@ 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.
 
+## Watch conditions
+
+JSON conditions require a root-prefixed path, such as `$.status` or
+`$.terminalFailure`; bare keys such as `status` are rejected before the command
+starts. For a command that emits `{"status":"FAILURE","terminalFailure":true}`,
+use:
+
+```json
+{
+  "success_when": { "type": "json_path_equals", "path": "$.status", "value": "SUCCESS" },
+  "failure_when": { "type": "json_path_equals", "path": "$.terminalFailure", "value": true }
+}
+```
+
+Persisted watchers with unsupported paths fail explicitly on their next poll.
+Missing JSON fields or invalid JSON output remain retryable; task status shows
+the condition evaluation error until a subsequent poll recovers. Keep a finite
+timeout to bound watches whose output never becomes evaluable.
+
 ## Install
 
 ```sh
@@ -92,6 +111,27 @@ Try it for one run:
 pi -e npm:pi-better-background-tasks
 ```
 
+## Failure observations
+
+Task lifecycle and failure evidence are reported separately. A watch can remain
+`running` while a poll or condition evaluator has failed. Status, list, log, and
+navigator views show unresolved observations before ordinary progress. A success
+match cannot finish a watch while evaluation of its failure condition is broken;
+a definite failure match still terminates it.
+
+Observations live in `failures.jsonl` beside task metadata. Recovery requires a
+successful evaluation of the same operation. Repeated failures are grouped, and
+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
+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.
+
 ## 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.16",
+  "version": "0.2.17",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",

package/src/conditions.ts

@@ -6,6 +6,13 @@ export interface ConditionMatch {
   error?: string;
 }
 
+export function validateCondition(condition: Condition): string | undefined {
+  if ((condition.type === "json_path_equals" || condition.type === "json_path_exists") && !parseJsonPath(condition.path)) {
+    return `unsupported JSON path: ${condition.path}. Use a root-prefixed path such as $.status or $.terminalFailure.`;
+  }
+  return undefined;
+}
+
 export function evaluateCondition(condition: Condition, result: CommandResult): ConditionMatch {
   switch (condition.type) {
     case "exit_code":

package/src/failures.ts

@@ -0,0 +1,99 @@
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  failureAttentionHandled, failureIdentity, formatFailureSummary, markFailureAttentionDelivered,
+  observeFailures, pendingFailureAttention, readFailureState,
+} from "./shared-failure-observations.js";
+import { getCallbackBatcher } from "./shared-callback-batcher.js";
+import { readMeta, taskDir } from "./registry.js";
+import type { ActiveSessionProvider } from "./runtime.js";
+import type { BackgroundTaskMeta } from "./types.js";
+
+export const failurePath = (id: string): string => join(taskDir(id), "failures.jsonl");
+export const failureSummary = (id: string): string => formatFailureSummary(readFailureState(failurePath(id)));
+
+export function recordFailure(meta: BackgroundTaskMeta, operation: string, summary: string, eventKey: unknown,
+  options: { category?: string; expected?: boolean; incomplete?: boolean; evidence?: string; at?: number } = {}): void {
+  observeFailures(failurePath(meta.id), [{
+    id: failureIdentity(meta.id, operation, eventKey), operation,
+    kind: options.incomplete ? "incomplete" : "failure", summary,
+    category: options.category, expected: options.expected, evidence: options.evidence,
+    at: options.at,
+  }]);
+}
+
+export function recoverFailure(meta: BackgroundTaskMeta, operation: string, eventKey: unknown, at = Date.now()): void {
+  const path = failurePath(meta.id);
+  const active = readFailureState(path).observations[failureIdentity(operation)];
+  if (!active || active.status === "resolved") return;
+  observeFailures(path, [{
+    id: failureIdentity(meta.id, operation, "recovered", eventKey), operation,
+    kind: "recovered", incidents: [active.id], at,
+  }]);
+}
+
+const attentionTimers = new Map<string, ReturnType<typeof setTimeout>>();
+export function stopFailureAttention(id: string): void {
+  const timer = attentionTimers.get(id);
+  if (timer) clearTimeout(timer);
+  attentionTimers.delete(id);
+}
+
+/** Running incidents get one grace wake. Terminal incidents ride the completion callback. */
+export function scheduleFailureAttention(pi: ExtensionAPI, id: string, getActiveSession?: ActiveSessionProvider): void {
+  stopFailureAttention(id);
+  const meta = readMeta(id);
+  if (!meta) {
+    const timer = setTimeout(() => scheduleFailureAttention(pi, id, getActiveSession), 1_000);
+    timer.unref();
+    attentionTimers.set(id, timer);
+    return;
+  }
+  if (meta.status !== "running" || meta.callback === false || meta.stopRequestedAt) return;
+  const state = readFailureState(failurePath(id));
+  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}`,
+      isDelivered: () => {
+        const current = readMeta(id);
+        if (!current) throw new Error("Task metadata is unavailable; defer failure notification");
+        const now = readFailureState(failurePath(id));
+        return current.status !== "running" || failureAttentionHandled(now, pending.incidents);
+      },
+      getSuppressionReason: () => {
+        const current = readMeta(id);
+        if (!current) throw new Error("Task metadata is unavailable; defer failure notification");
+        if (current.status !== "running" || current.callback === false || current.stopRequestedAt) return "task is no longer running";
+        const origin = current.callbackOrigin;
+        const active = getActiveSession?.();
+        if (origin && (!active || origin.cwd !== active.cwd || (origin.sessionId && origin.sessionId !== active.sessionId))) return "callback origin is not active";
+        if (!origin && active && active.cwd !== current.cwd) return "callback cwd is not active";
+        return undefined;
+      },
+      onDelivered: (at) => { markFailureAttentionDelivered(failurePath(id), pending, at); },
+    });
+    void Promise.resolve(delivery).then((sent) => {
+      if (!sent && (!readMeta(id) || readMeta(id)?.status === "running")) {
+        const timer = setTimeout(() => scheduleFailureAttention(pi, id, getActiveSession), 1_000);
+        timer.unref();
+        attentionTimers.set(id, timer);
+      }
+    });
+    return;
+  }
+  const due = Object.values(state.observations)
+    .filter((x) => x.status === "unresolved" && state.delivered[x.id] === undefined)
+    .map((x) => x.firstObservedAt + 60_000 - Date.now());
+  if (due.length) {
+    const timer = setTimeout(() => scheduleFailureAttention(pi, id, getActiveSession), Math.max(1, Math.min(...due)));
+    timer.unref();
+    attentionTimers.set(id, timer);
+  }
+}
+
+export function terminalFailureAttention(id: string) {
+  return pendingFailureAttention(readFailureState(failurePath(id)), Date.now(), { terminal: true });
+}

package/src/maintenance.ts

@@ -1,5 +1,6 @@
 import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { recordFailure } from "./failures.js";
 import { baseDir, listMetas, removeMeta, writeMeta } from "./registry.js";
 import { processIdentityAlive as defaultProcessIdentityAlive } from "./process-identity.js";
 import type { BackgroundTaskCallbackOrigin, BackgroundTaskMeta } from "./types.js";
@@ -49,6 +50,7 @@ export function runTaskMaintenance(options: TaskMaintenanceOptions = {}): TaskMa
       meta.endedAt = now;
       meta.error = "task supervisor is no longer alive; execution result is unavailable";
       meta.result = { reason: meta.error };
+      recordFailure(meta, "execution", meta.error, "supervisor-lost", { incomplete: true, at: now });
       writeMeta(meta);
       reconciled += 1;
     }

package/src/navigator-provider.ts

@@ -9,6 +9,8 @@ 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 { failurePath, failureSummary } from "./failures.js";
 import { readLog } from "./logs.js";
 import { listMetasForOrigin, onMetaChanged, readMeta, writeMeta } from "./registry.js";
 import { stopTask } from "./runtime.js";
@@ -102,6 +104,7 @@ function isExpiredTerminalNavigatorRow(meta: BackgroundTaskMeta, now: number): b
 }
 
 function rowFromMeta(meta: BackgroundTaskMeta, now: number): BackgroundWorkRow {
+  const failure = failureSummary(meta.id);
   const elapsed = formatDuration((meta.endedAt ?? now) - meta.startedAt);
   return {
     providerId: "background-tasks",
@@ -111,7 +114,7 @@ function rowFromMeta(meta: BackgroundTaskMeta, now: number): BackgroundWorkRow {
     statusTone: toneForStatus(meta.status),
     kind: meta.kind === "command_watch" ? "watch" : "process",
     elapsed,
-    primary: compactCommandLabel(meta),
+    primary: failure ? failure.split("\n")[0]! : compactCommandLabel(meta),
     command: commandLabel(meta),
     tool: compactCommandLabel(meta),
     secondary: secondaryLabel(meta),
@@ -125,6 +128,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 command = commandLabel(meta);
   const metadata = [
@@ -159,7 +163,7 @@ function detailFromMeta(meta: BackgroundTaskMeta | undefined, now: number, optio
     title: meta.name || meta.id,
     status: meta.status,
     statusTone: toneForStatus(meta.status),
-    subtitle: compactCommandLabel(meta),
+    subtitle: failure ? failure.split("\n")[0]! : compactCommandLabel(meta),
     metadata,
     foldedSections: [{
       id: "command",
@@ -170,7 +174,7 @@ function detailFromMeta(meta: BackgroundTaskMeta | undefined, now: number, optio
     }],
     evidence: {
       label: log.truncated ? "log tail" : "log",
-      text: log.text || "(log is empty)",
+      text: [failure, log.text || "(log is empty)"].filter(Boolean).join("\n"),
     },
     footerActions: [meta.status === "running" ? "x stop" : "x dismiss"],
   };
@@ -212,6 +216,8 @@ 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 (meta.status === "running") {
     const stall = observeBackgroundTaskStall(meta, now);
     if (stall.state === "stalled") facts.push("stalled");

package/src/runtime.ts

@@ -1,13 +1,15 @@
 import { statSync } from "node:fs";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { appendLine, appendTaskOutput, appendWatchResult, retainLogTail, resolveMaxLogBytes } from "./logs.js";
-import { evaluateCondition } from "./conditions.js";
+import { evaluateCondition, validateCondition } from "./conditions.js";
 import { processExists, runCommandOnce, spawnCommand, stopProcessGroup } from "./process.js";
 import { currentProcessStartToken, readProcessStartToken } from "./process-identity.js";
 import { DEFAULT_TMUX_BOOTSTRAP_TIMEOUT_MS, expandSshRemoteTaskPreset } from "./remote-task-preset.js";
 import type { RemoteRunner, ResolvedSshRemoteTask } from "./remote-task-preset.js";
 import { ensureTaskDir, logPathFor, nextTaskId, readMeta, sandboxProfilePathFor, writeMeta } from "./registry.js";
 import { confineCommandSpec, resolveForegroundSandboxPlan } from "./sandbox.js";
+import { failurePath, recordFailure, recoverFailure, scheduleFailureAttention, stopFailureAttention, terminalFailureAttention } from "./failures.js";
+import { markFailureAttentionDelivered } from "./shared-failure-observations.js";
 import { getCallbackBatcher } from "./shared-callback-batcher.js";
 import type {
   BackgroundTaskCallbackOrigin,
@@ -34,8 +36,7 @@ const REMOTE_SESSION_POLL_MS = 100;
 
 export const DEFAULT_WATCH_TIMEOUT_SECONDS = 15 * 60;
 
-/** Remote SSH launches never consult the local foreground sandbox policy. */
-const UNCONFINED_LAUNCH = { confined: false } as const;
+
 
 export type ActiveSessionProvider = () => BackgroundTaskCallbackOrigin | undefined;
 
@@ -75,9 +76,8 @@ export function spawnTask(
   dependencies: TaskRuntimeDependencies = {},
 ): BackgroundTaskMeta {
   // Resolved before any task directory, log, or metadata exists so a blocked
-  // launch leaves nothing behind. Remote SSH work is not a local execution path
-  // and keeps its existing remote semantics untouched.
-  const sandboxPlan = params.ssh ? UNCONFINED_LAUNCH : resolveForegroundSandboxPlan(pi);
+  // launch leaves nothing behind. Structured SSH must also honor launch restrictions.
+  const sandboxPlan = resolveForegroundSandboxPlan(pi, !!params.ssh);
   const id = nextTaskId();
   const cwd = params.cwd ?? defaultCwd;
   const logPath = logPathFor(id);
@@ -145,6 +145,8 @@ export function spawnTask(
       if (!latest) return;
       enforceLogRetention(latest);
       if (isTerminalStatus(latest.status)) return;
+      if (exitCode !== 0) recordFailure(latest, "execution", `Process exited with code ${exitCode ?? "unknown"}${signal ? ` (${signal})` : ""}`, "close", { category: "exit", at: Date.now() });
+      else recoverFailure(latest, "execution", "close");
       latest.status = exitCode === 0 ? "succeeded" : "failed";
       latest.endedAt = Date.now();
       latest.lastExitCode = exitCode;
@@ -181,11 +183,13 @@ async function launchRemoteTmux(
     appendLine(latest.logPath, `--- remote setup: ${bootstrap.message} ---`);
     writeMeta(latest);
     if (bootstrap.status !== "present" && bootstrap.status !== "installed") {
+      recordFailure(latest, "remote-bootstrap", bootstrap.message, "bootstrap", { category: "ssh" });
       latest.error = bootstrap.message;
       finalize(latest, { status: "failed", reason: bootstrap.message }, pi, getActiveSession);
       return;
     }
 
+    recoverFailure(latest, "remote-bootstrap", "bootstrap");
     const startAttempt = remoteTask.startTmuxSession(bootstrap.tmuxPath);
     remoteSessionStarts.set(id, startAttempt);
     let started: CommandResult;
@@ -200,9 +204,11 @@ async function launchRemoteTmux(
       const detail = started.stderr.trim() || started.stdout.trim() || "remote tmux returned no diagnostic";
       const reason = `Could not create remote tmux session ${afterStart.remote?.sessionName} on ${afterStart.ssh?.target} (exit ${started.exitCode ?? "unknown"}): ${detail}`;
       afterStart.error = reason;
+      recordFailure(afterStart, "remote-start", reason, "start", { category: "ssh", at: started.endedAt });
       finalize(afterStart, { status: "failed", reason, commandResult: started }, pi, getActiveSession);
       return;
     }
+    recoverFailure(afterStart, "remote-start", "start");
     appendLine(afterStart.logPath, `--- remote tmux session ${afterStart.remote?.sessionName} started on ${afterStart.ssh?.target} ---`);
     afterStart.remote = { ...afterStart.remote!, sessionStarted: true };
     afterStart.lastProgressAt = Date.now();
@@ -266,12 +272,15 @@ async function pollRemoteSession(
     }
     if (poll.status === "missing") {
       const reason = `Remote tmux session ${latest.remote?.sessionName} disappeared on ${latest.ssh?.target} before an exit status was captured.`;
+      recordFailure(latest, "remote-session", reason, "missing", { incomplete: true });
       latest.error = reason;
       finalize(latest, { status: "failed", reason }, pi, getActiveSession);
       return;
     }
     const commandResult = { ...poll.commandResult, exitCode: poll.status, stdout: poll.output };
     latest.lastExitCode = poll.status;
+    if (poll.status !== 0) recordFailure(latest, "execution", `Remote command exited with code ${poll.status}`, "exit", { category: "exit" });
+    else recoverFailure(latest, "execution", "exit");
     finalize(latest, {
       status: poll.status === 0 ? "succeeded" : "failed",
       reason: `remote command exited with code ${poll.status}`,
@@ -300,6 +309,7 @@ function failRemoteTask(
   if (!meta || meta.status !== "running" || meta.stopRequestedAt) return;
   const reason = error instanceof Error ? error.message : String(error);
   meta.error = reason;
+  recordFailure(meta, "remote-control", reason, "error", { category: "ssh" });
   finalize(meta, { status: "failed", reason }, pi, getActiveSession);
 }
 
@@ -311,7 +321,11 @@ export function startWatchTask(
   getActiveSession?: ActiveSessionProvider,
   dependencies: TaskRuntimeDependencies = {},
 ): BackgroundTaskMeta {
-  const sandboxPlan = params.ssh ? UNCONFINED_LAUNCH : resolveForegroundSandboxPlan(pi);
+  for (const [name, condition] of [["success_when", params.success_when], ["failure_when", params.failure_when]] as const) {
+    const error = condition && validateCondition(condition);
+    if (error) throw new Error(`${name}: ${error}`);
+  }
+  const sandboxPlan = resolveForegroundSandboxPlan(pi, !!params.ssh);
   const id = nextTaskId();
   const cwd = params.cwd ?? defaultCwd;
   const now = Date.now();
@@ -382,6 +396,7 @@ export function resumeRunningTask(
     void notifyTerminal(pi, meta, getActiveSession);
     return meta;
   }
+  scheduleFailureAttention(pi, meta.id, getActiveSession);
 
   if (meta.spawnPid !== process.pid || meta.spawnPidStartTime !== currentProcessStartToken()) {
     meta.spawnPid = process.pid;
@@ -409,6 +424,7 @@ export function resumeRunningTask(
     meta.endedAt = Date.now();
     meta.error = "process is no longer alive; exit result was not captured by this pi session";
     meta.result = { reason: meta.error };
+    recordFailure(meta, "execution", meta.error, "lost", { incomplete: true });
     writeMeta(meta);
     void notifyTerminal(pi, meta, getActiveSession);
     return meta;
@@ -510,6 +526,7 @@ export async function stopTask(
     }
   }
 
+  stopFailureAttention(id);
   meta.status = "cancelled";
   meta.endedAt = Date.now();
   meta.result = {
@@ -573,35 +590,68 @@ async function pollWatch(
     latest.lastSignal = result.signal;
     latest.lastState = extractLastState(result);
 
+    const pollKey = result.startedAt;
     if (result.timedOut) {
       finalize(latest, { status: "timed_out", reason: watchTimeoutReason(latest), commandResult: result }, pi, getActiveSession);
       return;
     }
 
-    if (latest.failureWhen) {
-      const failure = evaluateCondition(latest.failureWhen, result);
-      if (failure.matched) {
-        finalize(latest, { status: "failed", reason: "failure condition matched", matchedCondition: latest.failureWhen, commandResult: result }, pi, getActiveSession);
+    const conditionErrors: string[] = [];
+    delete latest.error;
+    for (const [name, condition] of [["success_when", latest.successWhen], ["failure_when", latest.failureWhen]] as const) {
+      const error = condition && validateCondition(condition);
+      if (error) {
+        latest.error = `${name}: ${error}`;
+        if (result.exitCode !== 0) recordFailure(latest, "watch-poll", `Watch poll exited with code ${result.exitCode ?? "unknown"}`, pollKey,
+          { category: "exit", at: result.endedAt });
+        recordFailure(latest, name, latest.error, pollKey, { incomplete: true, at: result.endedAt });
+        finalize(latest, { status: "failed", reason: latest.error, commandResult: result }, pi, getActiveSession);
         return;
       }
     }
 
+    // Evaluate both conditions before deciding whether either can terminate the watch.
+    const failure = latest.failureWhen ? evaluateCondition(latest.failureWhen, result) : undefined;
+    const success = latest.successWhen ? evaluateCondition(latest.successWhen, result) : undefined;
+    for (const [name, match] of [["failure_when", failure], ["success_when", success]] as const) {
+      if (match?.error) {
+        conditionErrors.push(`${name}: ${match.error}`);
+        recordFailure(latest, name, `${name}: ${match.error}`, pollKey, { incomplete: true, at: result.endedAt });
+      } else if (match) {
+        recoverFailure(latest, name, pollKey, result.endedAt);
+      }
+    }
     const transportFailure = sshTransportFailure(latest, result);
+    const expectedPollExit = !transportFailure && !conditionErrors.length && failure?.matched !== true &&
+      success?.matched === true && latest.successWhen?.type === "exit_code";
+    if (expectedPollExit) recoverFailure(latest, "watch-poll", pollKey, result.endedAt);
+    if (transportFailure) recordFailure(latest, "watch-poll", transportFailure, pollKey, { category: "ssh", at: result.endedAt });
+    else if (result.exitCode !== 0) recordFailure(latest, "watch-poll", `Watch poll exited with code ${result.exitCode ?? "unknown"}`, pollKey,
+      { category: "exit", expected: expectedPollExit, at: result.endedAt });
+    else recoverFailure(latest, "watch-poll", pollKey, result.endedAt);
+    if (conditionErrors.length) latest.error = conditionErrors.join("; ");
+    if (failure?.matched) {
+      recordFailure(latest, "failure_when", "failure condition matched", pollKey, { category: "condition", at: result.endedAt });
+      finalize(latest, { status: "failed", reason: "failure condition matched", matchedCondition: latest.failureWhen, commandResult: result }, pi, getActiveSession);
+      return;
+    }
     if (transportFailure) {
       latest.error = transportFailure;
       finalize(latest, { status: "failed", reason: transportFailure, commandResult: result }, pi, getActiveSession);
       return;
     }
-
-    if (latest.successWhen) {
-      const success = evaluateCondition(latest.successWhen, result);
-      if (success.matched) {
-        finalize(latest, { status: "succeeded", reason: "success condition matched", matchedCondition: latest.successWhen, commandResult: result }, pi, getActiveSession);
-        return;
-      }
+    if (conditionErrors.length) {
+      writeMeta(latest);
+      scheduleFailureAttention(pi, id, getActiveSession);
+      scheduleWatch(pi, id, nextWatchDelayMs(latest), getActiveSession, runOnce);
+      return;
+    }
+    if (success?.matched) {
+      finalize(latest, { status: "succeeded", reason: "success condition matched", matchedCondition: latest.successWhen, commandResult: result }, pi, getActiveSession);
+      return;
     }
-
     writeMeta(latest);
+    scheduleFailureAttention(pi, id, getActiveSession);
     scheduleWatch(pi, id, nextWatchDelayMs(latest), getActiveSession, runOnce);
   } catch (error) {
     const meta = readMeta(id);
@@ -612,6 +662,7 @@ async function pollWatch(
         meta.error = reason;
         appendLine(meta.logPath, `--- poll error ${new Date().toISOString()} ---\n${reason}`);
       }
+      recordFailure(meta, "watch-poll", reason, `throw:${meta.lastCheckedAt ?? meta.startedAt}`, { category: meta.ssh ? "ssh" : "execution" });
       finalize(meta, { status: "failed", reason }, pi, getActiveSession);
     }
   } finally {
@@ -625,6 +676,8 @@ function finalize(
   pi: ExtensionAPI,
   getActiveSession?: ActiveSessionProvider,
 ): void {
+  stopFailureAttention(meta.id);
+  if (terminal.status === "timed_out") recordFailure(meta, "timeout", terminal.reason, "deadline", { category: "timeout" });
   meta.status = terminal.status;
   meta.endedAt = Date.now();
   meta.result = {
@@ -782,12 +835,13 @@ async function notifyTerminal(
     writeMeta(latest);
     return;
   }
+  const pending = terminalFailureAttention(latest.id);
   const label = latest.name ? `${latest.name} (${latest.id})` : latest.id;
   getCallbackBatcher(pi).enqueue({
     source: "background-task",
     id: latest.id,
     label,
-    status: latest.status,
+    status: pending ? `${latest.status}: ${pending.summary}` : latest.status,
     detailTool: "bg_task_status",
     callback: true,
     isDelivered: () => {
@@ -796,7 +850,7 @@ async function notifyTerminal(
     },
     getSuppressionReason: () => {
       const current = readMeta(latest.id);
-      if (!current) return "background task metadata is unavailable";
+      if (!current) throw new Error("Background task metadata is unavailable; defer completion");
       return getCallbackSuppressionReason(current, getActiveSession?.());
     },
     onDelivered: (at) => {
@@ -804,6 +858,7 @@ async function notifyTerminal(
       if (!current || current.callbackSentAt !== undefined || current.callbackSuppressedAt !== undefined) return;
       current.callbackSentAt = at;
       writeMeta(current);
+      if (pending) markFailureAttentionDelivered(failurePath(latest.id), pending, at);
     },
     onSuppressed: (reason, at) => {
       const current = readMeta(latest.id);