pi-better-harness 0.7.0 → 0.9.0

package/node_modules/pi-better-background-tasks/README.md

@@ -99,9 +99,11 @@ 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.
+soon as the session resumes, so a timeout can land late but is never skipped.
+While the same Pi process stays open, a local process that exits in the meantime
+is recorded as finished, and its callback is delivered when its session resumes.
+If you quit Pi first, nothing records that exit: when the session is resumed in a
+new Pi process, a task whose process is gone is marked lost.
 
 ## Watch conditions
 
@@ -122,6 +124,57 @@ 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.
 
+### Writing a watch check
+
+A check that swallows its own errors reports "still pending" forever. Keep
+failures visible:
+
+- Do not end the check with `exit 0` or `|| true`. A check that exits non-zero
+  is recorded as a failure and escalates to the parent session.
+- Map an unknown or unparseable state to failure (a non-zero exit), not to
+  pending.
+- Prefer structured output parsed with `jq -e` over hand-written format
+  strings. `jq -e` exits non-zero when the field is missing, so a broken query
+  shows up at once.
+
+For example, a Cloud Run job execution:
+
+```sh
+status=$(gcloud run jobs executions describe "$EXECUTION" --region="$REGION" --format=json \
+  | jq -er '.status.conditions[] | select(.type == "Completed") | .status') || exit 2
+case "$status" in
+  True) echo TERMINAL_SUCCESS ;;
+  False) echo TERMINAL_FAILURE ;;
+  Unknown) echo STILL_RUNNING ;;
+  *) echo "unexpected Completed status: $status" >&2; exit 2 ;;
+esac
+```
+
+with `success_when: {type: "stdout_contains", value: "TERMINAL_SUCCESS"}` and
+`failure_when: {type: "stdout_contains", value: "TERMINAL_FAILURE"}`.
+
+`bg_task_watch` (and `bg_task` with `action: "watch"`) waits up to 15 seconds
+for the first check and puts its exit code, the newest few lines of stderr and
+of stdout in the tool result, so a broken check is visible at launch. When the
+result is short on room, stdout is cut first. If the first check is still
+running after 15 seconds, or you press Esc during the wait, the result says so
+at once and the watch continues.
+
+A running watch also guards against a blind check. When 3 checks in a row exit
+0, write to stderr, and match neither `success_when` nor `failure_when`, the
+watch records one incident that needs action, with the latest stderr line, and
+wakes the parent session once. The watch keeps running. A later check with
+empty stderr recovers the incident whatever its exit code (a non-zero or
+failed check is then recorded as its own incident), and so does a check that
+matches a condition. A non-zero check that writes stderr restarts the count but
+leaves the incident open. A clean pending check (exit 0, no stderr) never
+counts.
+
+Some tools write to stderr on success (`gcloud … list` prints "Listed 0
+items.", and kubectl and npm print warnings), which can raise a false alarm.
+If the stderr is expected, redirect it (`2>/dev/null`) or set
+`blind_checks: 0`. Set `blind_checks` to another number to change the count.
+
 ## Install
 
 ```sh
@@ -151,7 +204,7 @@ evidence is reported as **observation incomplete**.
 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
+`[1]` for a no-match probe; a `0` is ignored) 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

package/node_modules/pi-better-background-tasks/package.json

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

package/node_modules/pi-better-background-tasks/src/failures.ts

@@ -1,7 +1,7 @@
 import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
-  activeFailures, failureAttentionHandled, failureIdentity, formatFailureSummary, markFailureAttentionDelivered,
+  actionableFailures, activeFailures, failureAttentionHandled, failureIdentity, formatFailureSummary, markFailureAttentionDelivered,
   observeFailures, pendingAttentionNote, pendingAttentionRows, pendingFailureAttention, readCommandIntent, readFailureState,
   type FailureEvent, type FailureState,
 } from "./shared-failure-observations.js";
@@ -12,6 +12,14 @@ 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)));
+/**
+ * The failure summary plus whether anything needs action. A navigator row leads with failure text
+ * only when something does; the quiet history line never displaces the command (#332).
+ */
+export function failureView(id: string): { text: string; actionable: boolean } {
+  const state = readFailureState(failurePath(id));
+  return { text: formatFailureSummary(state), actionable: actionableFailures(state).length > 0 };
+}
 
 export function recordFailure(meta: BackgroundTaskMeta, operation: string, summary: string, eventKey: unknown,
   options: { category?: string; expected?: boolean; incomplete?: boolean; evidence?: string; at?: number } = {}): void {

package/node_modules/pi-better-background-tasks/src/navigator-provider.ts

@@ -10,8 +10,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, failureLabel, readFailureState } from "./shared-failure-observations.js";
-import { failurePath, failureSummary } from "./failures.js";
+import { actionableFailures, failureLabel, readFailureState } from "./shared-failure-observations.js";
+import { failurePath, failureView } from "./failures.js";
 import { readLog } from "./logs.js";
 import { listMetasForOrigin, onMetaChanged, readMeta, writeMeta } from "./registry.js";
 import { stopTask } from "./runtime.js";
@@ -105,7 +105,9 @@ function isExpiredTerminalNavigatorRow(meta: BackgroundTaskMeta, now: number): b
 }
 
 function rowFromMeta(meta: BackgroundTaskMeta, now: number): BackgroundWorkRow {
-  const failure = failureSummary(meta.id);
+  // Only a failure that needs action replaces the row's command; history stays in the detail view (#332).
+  const view = failureView(meta.id);
+  const failure = view.actionable ? view.text : "";
   const elapsed = formatDuration((meta.endedAt ?? now) - meta.startedAt);
   return {
     providerId: "background-tasks",
@@ -129,7 +131,8 @@ 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 view = failureView(meta.id);
+  const failure = view.text;
   const log = readLog(meta.logPath, options?.logTailLines ?? NAVIGATOR_DETAIL_ROWS);
   const command = commandLabel(meta);
   const metadata = [
@@ -164,7 +167,7 @@ function detailFromMeta(meta: BackgroundTaskMeta | undefined, now: number, optio
     title: meta.name || meta.id,
     status: meta.status,
     statusTone: toneForStatus(meta.status),
-    subtitle: failure ? failure.split("\n")[0]! : compactCommandLabel(meta),
+    subtitle: view.actionable ? failure.split("\n")[0]! : compactCommandLabel(meta),
     metadata,
     foldedSections: [{
       id: "command",
@@ -217,7 +220,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];
+  const incident = actionableFailures(readFailureState(failurePath(meta.id)))[0];
   if (incident) facts.push(`${failureLabel(incident)}: ${incident.summary}`);
   if (meta.status === "running") {
     const stall = observeBackgroundTaskStall(meta, now);

package/node_modules/pi-better-background-tasks/src/output.ts

@@ -40,7 +40,10 @@ import {
 import { failurePath } from "./failures.js";
 import { captureGapsFor, pageTaskLog, readLog, type LogRead } from "./logs.js";
 import { belongsToOrigin, inspectMeta, listTaskRecords, originOf, type MetaInspection } from "./registry.js";
-import type { BackgroundTaskCallbackOrigin, BackgroundTaskMeta, Condition } from "./types.js";
+import type { BackgroundTaskCallbackOrigin, BackgroundTaskMeta, Condition, FirstWatchCheck } from "./types.js";
+
+/** The launch tool stopped waiting while a watch's first check was still running (#359). */
+export type FirstCheckPending = { pending: "timeout" | "aborted" | "suspended"; waitedMs: number };
 
 /**
  * Issue #312 consumer budgets. Defaults follow OUTPUT-POLICY / shared
@@ -240,9 +243,10 @@ export function formatCallbackFacts(meta: BackgroundTaskMeta): {
     meta.captureDiscardedBytes ? `capture overflow discarded ${meta.captureDiscardedBytes} bytes; not full history` : undefined,
   ].filter((line): line is string => Boolean(line));
   // History (expected and closed incidents) is not a row, but the callback still says it exists, so a
-  // declared expected exit is not read as a plain failure.
+  // declared expected exit is not read as a plain failure. It leads the decision: a tight callback
+  // budget keeps a prefix of the decision, and this short line must survive it (#332).
   const history = rows.length ? historyTailLine(state) : quietFailureLine(state);
-  const decision = [formatDecision(meta), ...gapLines, history].filter(Boolean).join("\n") || undefined;
+  const decision = [history, formatDecision(meta), ...gapLines].filter(Boolean).join("\n") || undefined;
   return {
     outcome: meta.status,
     ...(rows.length ? { failureRows: rows, incidentCount: rows.length } : {}),
@@ -434,24 +438,109 @@ function asInspection(inspection: MetaInspection | BackgroundTaskMeta | undefine
   return { id: meta.id, meta, found: true, readable: true };
 }
 
-export function formatLaunch(meta: BackgroundTaskMeta): string {
+/**
+ * Launch result. For a watch, `firstCheck` reports its first check (#359): the check's result,
+ * or why the launch stopped waiting while it was still running.
+ *
+ * The first check gets whatever the status budget leaves after the rest of the launch text, so
+ * nothing else is clipped for it. The log path is kept whole or dropped whole: a clipped path
+ * looks valid but points nowhere.
+ */
+export function formatLaunch(meta: BackgroundTaskMeta, firstCheck?: FirstWatchCheck | FirstCheckPending): string {
   const label = meta.name ? `${meta.name} (${meta.id})` : meta.id;
   const remoteLines = [
     ...(meta.ssh ? [`Remote: ${meta.ssh.target}${meta.remote?.session ? ` mode=${meta.remote.session}` : ""}${meta.remote?.sessionName ? ` session=${meta.remote.sessionName}` : ""}.`] : []),
     ...(meta.remote?.bootstrapMessage ? [`Remote setup: ${meta.remote.bootstrapMessage}`] : []),
     ...(meta.remote?.warning ? [`Warning: ${meta.remote.warning}`] : []),
   ];
-  return assembleBackgroundContent({
+  const logLine = `Log: ${meta.logPath}`;
+  const build = (checkText: string | undefined, withLog: boolean) => assembleBackgroundContent({
     surface: "status",
     sections: {
       identity: `Started background ${meta.kind} ${label}. Status: ${meta.status}.`,
       failure: incidentSection(meta.id, {}),
       decision: formatDecision(meta),
-      diagnostics: remoteLines.join("\n") || undefined,
-      progress: `Log: ${meta.logPath}`,
+      diagnostics: [...remoteLines, ...(checkText ? [checkText] : [])].join("\n") || undefined,
+      progress: withLog ? logLine : undefined,
     },
     gaps: taskGaps(meta),
   });
+  let checkText: string | undefined;
+  if (firstCheck) {
+    const room = backgroundBudget("status") - utf8ByteLength(build(undefined, true)) - 1;
+    checkText = formatFirstWatchCheck(meta, firstCheck, room);
+  }
+  const text = build(checkText, true);
+  return text.includes(logLine) ? text : build(checkText, false);
+}
+
+const FIRST_CHECK_TAIL_LINES = 3;
+const FIRST_CHECK_LINE_CHARS = 200;
+
+function tailLines(text: string): string[] {
+  return text.split(/\r?\n/).map((line) => line.replace(/\s+/g, " ").trim()).filter(Boolean)
+    .slice(-FIRST_CHECK_TAIL_LINES)
+    .map((line) => line.length > FIRST_CHECK_LINE_CHARS ? `${line.slice(0, FIRST_CHECK_LINE_CHARS - 1)}…` : line);
+}
+
+function pendingFirstCheckText(check: FirstCheckPending): string {
+  switch (check.pending) {
+    case "aborted":
+      return "First check still running; stopped waiting because the tool call was cancelled. The watch continues in the background; check it later with bg_task_status.";
+    case "suspended":
+      return "First check still running when the session shut down. The watch continues when its session resumes; check it later with bg_task_status.";
+    default:
+      return `First check still running after ${formatDuration(check.waitedMs)}; the watch continues in the background. Check it later with bg_task_status.`;
+  }
+}
+
+/**
+ * The first check of a watch in at most `maxBytes` (#359). What matters most is kept first: the
+ * outcome, the exit-0-with-stderr warning, the newest stderr lines, then the newest stdout lines,
+ * so stdout is cut first. Lines are shown oldest to newest.
+ */
+export function formatFirstWatchCheck(meta: BackgroundTaskMeta, check: FirstWatchCheck | FirstCheckPending, maxBytes = Number.MAX_SAFE_INTEGER): string {
+  if ("pending" in check) return pendingFirstCheckText(check);
+  if (check.error) return `First check could not run: ${oneLine(check.error, 300)}`;
+  const outcome = check.timedOut ? "timed out" : check.signal ? `signal ${check.signal}` : `exit ${check.exitCode ?? "unknown"}`;
+  const took = check.durationMs < 1000 ? `${check.durationMs}ms` : formatDuration(check.durationMs);
+  const header = `First check: ${outcome} in ${took}.`;
+  const stdout = tailLines(check.stdout);
+  const stderr = tailLines(check.stderr);
+  const warning = check.exitCode === 0 && stderr.length && meta.status === "running"
+    ? "The check exited 0 but wrote stderr: if it is broken, the watch cannot tell. Let errors exit non-zero."
+    : undefined;
+  const keptErr: string[] = [];
+  const keptOut: string[] = [];
+  let keptEmptyStdout = false;
+  const render = () => [
+    header,
+    ...(warning ? [warning] : []),
+    ...(keptErr.length ? [`stderr tail:\n${keptErr.map((line) => `  ${line}`).join("\n")}`] : []),
+    ...(keptOut.length ? [`stdout tail:\n${keptOut.map((line) => `  ${line}`).join("\n")}`] : []),
+    ...(keptEmptyStdout ? ["stdout: (empty)"] : []),
+  ].join("\n");
+  const fits = () => utf8ByteLength(render()) <= maxBytes;
+  // Newest first within each stream; each kept line goes in front to stay in order.
+  for (const line of [...stderr].reverse()) {
+    keptErr.unshift(line);
+    if (!fits()) { keptErr.shift(); break; }
+  }
+  for (const line of [...stdout].reverse()) {
+    keptOut.unshift(line);
+    if (!fits()) { keptOut.shift(); break; }
+  }
+  if (!stdout.length) {
+    keptEmptyStdout = true;
+    if (!fits()) keptEmptyStdout = false;
+  }
+  const omitted = (stderr.length - keptErr.length) + (stdout.length - keptOut.length);
+  if (omitted > 0) {
+    const note = `(${omitted} output line${omitted === 1 ? "" : "s"} omitted; see bg_task_log)`;
+    const text = `${render()}\n${note}`;
+    if (utf8ByteLength(text) <= maxBytes) return text;
+  }
+  return render();
 }
 
 function redactedVerbose(meta: BackgroundTaskMeta): unknown {
@@ -548,13 +637,16 @@ export function formatStatus(
   if (pageKind === "f") return formatLog(meta.id, { ...options, raw: true });
   if (pageKind === "t") return formatVerbose(meta, options);
   if (options.verbose) return formatVerbose(meta, options);
+  // A bg_task_list page cursor pages the list, not this task: say so rather than report it as a
+  // stale status cursor (#332).
+  const listCursor = pageKind === "l";
   const state = failureStateFor(meta.id);
   const resource = `status:${scopeKey(options)}:${meta.id}`;
   const revision = inspectStatusRevision({
     resource,
     contentRevision: contentRevision(meta),
     failureRevision: failureRevision(state),
-    cursor: options.cursor,
+    cursor: listCursor ? undefined : options.cursor,
   });
   if (options.cursor && revision.change === "none") {
     return assembleBackgroundContent({
@@ -574,6 +666,7 @@ export function formatStatus(
   // Change/reset and read-gap facts are short and decision-relevant: they are
   // budgeted with the decision section, ahead of long incident rows.
   const changeFacts = [
+    ...(listCursor ? ["cursor ignored: it is a bg_task_list page cursor; pass it to bg_task_list, or pass this status's statusCursor here."] : []),
     ...(revision.change === "failure" ? ["change=failure"] : []),
     ...(revision.reset ? [`reset=${revision.reset}`] : []),
     ...(log.error ? [`log unreadable: ${oneLine(log.error, 200)}; cannot treat this as an empty healthy log.`] : []),