pi-better-harness 0.8.0 → 0.9.0

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

@@ -124,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

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.5.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/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 {

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

@@ -19,6 +19,7 @@ import type {
   CommandResult,
   CommandSpec,
   Condition,
+  FirstWatchCheck,
   RemoteTaskParams,
   SshConnectionParams,
   TerminalResult,
@@ -31,6 +32,8 @@ const processTimeoutTimers = new Map<string, ReturnType<typeof setTimeout>>();
 const activeProcessTimeouts = new Set<string>();
 const activeRemoteTasks = new Map<string, ResolvedSshRemoteTask>();
 const remoteSessionStarts = new Map<string, Promise<CommandResult>>();
+/** Tasks whose stop in this instance is waiting on an in-flight tmux start, and kills the session itself. */
+const remoteStopsAwaitingStart = new Set<string>();
 const activePolls = new Set<string>();
 const logRetentionTimers = new Map<string, ReturnType<typeof setInterval>>();
 const LOG_RETENTION_CHECK_MS = 1000;
@@ -44,6 +47,63 @@ let scheduledWorkSuspended = false;
 const REMOTE_SESSION_POLL_MS = 100;
 
 export const DEFAULT_WATCH_TIMEOUT_SECONDS = 15 * 60;
+/** Consecutive blind checks (exit 0, stderr, no condition matched) before a watch is flagged (#359). */
+export const DEFAULT_BLIND_CHECKS = 3;
+/** How long bg_task_watch waits for the first check before returning (#359). */
+export const FIRST_WATCH_CHECK_WAIT_MS = 15_000;
+const BLIND_OPERATION = "watch-blind";
+/** How to fix a false alarm: some tools write progress or warnings to stderr on success. */
+export const BLIND_CHECK_HINT = "If the stderr is expected (progress or warnings), redirect it (2>/dev/null) or set blind_checks:0.";
+
+/**
+ * Why the launch stopped waiting before the first check finished (#359): the bounded wait
+ * ran out, the tool call was aborted (Esc), or the session shut down.
+ */
+export type FirstCheckWaitEnd = "timeout" | "aborted" | "suspended";
+/** A first check's outcome, or why it is not known yet; undefined when the watch ended without one. */
+export type FirstCheckOutcome = FirstWatchCheck | { pending: FirstCheckWaitEnd; waitedMs: number } | undefined;
+
+/** In-flight first checks of watches launched by this instance, keyed by task id. */
+const firstCheckWaiters = new Map<string, { promise: Promise<FirstWatchCheck | "suspended" | undefined>; resolve: (check: FirstWatchCheck | "suspended" | undefined) => void }>();
+
+/**
+ * Wait for a watch's first check, bounded by `timeoutMs` and `signal` (#359). Resolves a pending
+ * outcome when the wait ends first, and undefined when this instance did not launch the watch
+ * or the watch ended without a check.
+ */
+export async function awaitFirstWatchCheck(id: string, timeoutMs = FIRST_WATCH_CHECK_WAIT_MS, signal?: AbortSignal): Promise<FirstCheckOutcome> {
+  const waiter = firstCheckWaiters.get(id);
+  if (!waiter) return undefined;
+  const started = Date.now();
+  const pending = (reason: FirstCheckWaitEnd) => ({ pending: reason, waitedMs: Date.now() - started });
+  if (signal?.aborted) return pending("aborted");
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let onAbort: (() => void) | undefined;
+  const timeout = new Promise<"timeout">((resolve) => {
+    // Kept referenced: the launching tool call is waiting on it, and the watch timers are
+    // unref'd, so an unref'd wait could let the event loop drain before the first check.
+    timer = setTimeout(() => resolve("timeout"), Math.max(0, timeoutMs));
+  });
+  const aborted = new Promise<"aborted">((resolve) => {
+    onAbort = () => resolve("aborted");
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    const outcome = await Promise.race([waiter.promise, timeout, aborted]);
+    if (outcome === "timeout" || outcome === "aborted" || outcome === "suspended") return pending(outcome);
+    return outcome;
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (onAbort) signal?.removeEventListener("abort", onAbort);
+  }
+}
+
+function settleFirstCheck(id: string, check: FirstWatchCheck | "suspended" | undefined): void {
+  const waiter = firstCheckWaiters.get(id);
+  if (!waiter) return;
+  firstCheckWaiters.delete(id);
+  waiter.resolve(check);
+}
 
 /**
  * Stop this extension instance's scheduled work when its session shuts down (#324).
@@ -81,6 +141,8 @@ export function suspendScheduledWork(): void {
   remoteSessionTimers.clear();
   processTimeoutTimers.clear();
   logRetentionTimers.clear();
+  // A launch still waiting on a first check that will not run here reports it as still running.
+  for (const id of [...firstCheckWaiters.keys()]) settleFirstCheck(id, "suspended");
   suspendFailureAttention();
 }
 
@@ -94,12 +156,16 @@ export function resumeScheduledWork(): void {
 
 export type ActiveSessionProvider = () => BackgroundTaskCallbackOrigin | undefined;
 
-export interface SpawnTaskParams extends CommandSpec {
-  name?: string;
-  /** Structured intent (#325): stable id shared by modified retries of one operation. */
+/** Structured intent (#325), declared by the launching agent and shared by spawns and watchers. */
+export interface TaskIntentParams {
+  /** Stable id shared by modified retries of one operation. */
   operation_id?: string | null;
-  /** Structured intent (#325): non-zero exit codes declared intentional before launch. */
+  /** Non-zero exit codes declared intentional before launch. */
   expected_exit_codes?: number[] | null;
+}
+
+export interface SpawnTaskParams extends CommandSpec, TaskIntentParams {
+  name?: string;
   callback?: boolean;
   timeout_seconds?: number;
   max_log_bytes?: number;
@@ -107,18 +173,16 @@ export interface SpawnTaskParams extends CommandSpec {
   remote?: RemoteTaskParams;
 }
 
-export interface WatchTaskParams extends CommandSpec {
+export interface WatchTaskParams extends CommandSpec, TaskIntentParams {
   name?: string;
-  /** Structured intent (#325): stable id shared by modified retries of one operation. */
-  operation_id?: string | null;
-  /** Structured intent (#325): non-zero exit codes declared intentional before launch. */
-  expected_exit_codes?: number[] | null;
   callback?: boolean;
   interval_seconds?: number;
   timeout_seconds?: number;
   max_log_bytes?: number;
   success_when: Condition;
   failure_when?: Condition;
+  /** Consecutive blind checks before the watch is flagged (#359). Default 3; 0 turns it off. */
+  blind_checks?: number;
   ssh?: SshConnectionParams;
   remote?: RemoteTaskParams;
 }
@@ -157,9 +221,10 @@ export function spawnTask(
     }, dependencies.remoteRunner)
     : undefined;
   const commandSpec: CommandSpec = remoteTask?.commandSpec ?? { ...params, cwd, shell: params.shell ?? true };
+  const sandboxNotices: string[] = [];
   const launchSpec = remoteTask
     ? commandSpec
-    : confineCommandSpec(commandSpec, sandboxPlan, sandboxProfilePathFor(id));
+    : confineCommandSpec(commandSpec, sandboxPlan, sandboxProfilePathFor(id), {}, (line) => sandboxNotices.push(line));
   const tmuxBacked = remoteTask?.metadata.remote.session === "tmux";
   // Outside project = Write or Write & delete can change files outside the
   // project: start an APFS local snapshot (macOS, background, never blocks).
@@ -169,6 +234,9 @@ export function spawnTask(
     : remoteTask
       ? remoteTask.spawn(logPath, true)
       : spawnCommand(launchSpec, logPath, true);
+  for (const line of sandboxNotices) {
+    try { appendLine(logPath, `--- ${line} ---`); } catch { /* log gone */ }
+  }
   if (snapshot?.started) {
     void snapshot.done.then((outcome) => {
       if (!outcome.ok) {
@@ -276,7 +344,15 @@ async function launchRemoteTmux(
       if (remoteSessionStarts.get(id) === startAttempt) remoteSessionStarts.delete(id);
     }
     const afterStart = readMeta(id);
-    if (!afterStart || afterStart.status !== "running" || afterStart.stopRequestedAt) return;
+    if (!afterStart) return;
+    if (afterStart.status !== "running" || afterStart.stopRequestedAt) {
+      // Stopped (or timed out) while the start was in flight. A stop in this instance awaited the
+      // attempt and kills the session itself. Anything else could not see the attempt: a stop from
+      // an instance loaded by /reload, or a deadline that found the session not yet started. Only
+      // this launch can still reach the session it may just have created, so it kills it (#332).
+      if (!remoteStopsAwaitingStart.has(id)) await killSessionStartedAfterStop(afterStart, remoteTask);
+      return;
+    }
     if (started.exitCode !== 0) {
       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}`;
@@ -296,6 +372,19 @@ async function launchRemoteTmux(
   }
 }
 
+/** Kill a tmux session whose start completed after its task stopped; a failed start may still have left it running. */
+async function killSessionStartedAfterStop(meta: BackgroundTaskMeta, remoteTask: ResolvedSshRemoteTask): Promise<void> {
+  const session = `remote tmux session ${meta.remote?.sessionName} on ${meta.ssh?.target}`;
+  try {
+    const stopped = await remoteTask.killTmuxSession();
+    appendLine(meta.logPath, stopped.exitCode === 0
+      ? `--- Killed ${session}: it started after the task was ${meta.status === "running" ? "stopped" : meta.status} ---`
+      : `--- Could not kill ${session} that started after the task stopped (exit ${stopped.exitCode ?? "unknown"}) ---`);
+  } catch (error) {
+    appendLine(meta.logPath, `--- Could not kill ${session} that started after the task stopped: ${error instanceof Error ? error.message : String(error)} ---`);
+  }
+}
+
 function scheduleRemoteSessionPoll(
   pi: ExtensionAPI,
   id: string,
@@ -404,6 +493,7 @@ export function startWatchTask(
     const error = condition && validateCondition(condition);
     if (error) throw new Error(`${name}: ${error}`);
   }
+  const blindChecks = readBlindChecks(params.blind_checks);
   const intent = readTaskIntent(params);
   const sandboxPlan = resolveForegroundSandboxPlan(pi, !!params.ssh);
   const id = nextTaskId();
@@ -421,9 +511,10 @@ export function startWatchTask(
     }, dependencies.remoteRunner)
     : undefined;
   const commandSpec: CommandSpec = remoteTask?.commandSpec ?? { ...params, cwd, shell: params.shell ?? true };
+  const sandboxNotices: string[] = [];
   const launchSpec = remoteTask
     ? commandSpec
-    : confineCommandSpec(commandSpec, sandboxPlan, sandboxProfilePathFor(id));
+    : confineCommandSpec(commandSpec, sandboxPlan, sandboxProfilePathFor(id), {}, (line) => sandboxNotices.push(line));
   const meta: BackgroundTaskMeta = {
     id,
     name: params.name,
@@ -447,6 +538,7 @@ export function startWatchTask(
     spawnPidStartTime: currentProcessStartToken(),
     successWhen: params.success_when,
     failureWhen: params.failure_when,
+    ...(blindChecks !== undefined ? { blindChecks } : {}),
     notifyOn: "terminal",
     ssh: remoteTask?.metadata.ssh,
     remote: remoteTask?.metadata.remote,
@@ -454,13 +546,25 @@ export function startWatchTask(
   };
   ensureTaskDir(id);
   appendLine(meta.logPath, `--- watch ${new Date(now).toISOString()} interval_ms=${meta.intervalMs} ---`);
+  for (const line of sandboxNotices) appendLine(meta.logPath, `--- ${line} ---`);
   writeMeta(meta);
+  let resolveFirst!: (check: FirstWatchCheck | "suspended" | undefined) => void;
+  const firstCheck = new Promise<FirstWatchCheck | "suspended" | undefined>((resolve) => { resolveFirst = resolve; });
+  firstCheckWaiters.set(id, { promise: firstCheck, resolve: resolveFirst });
   scheduleWatch(pi, id, 0, getActiveSession, remoteTask
     ? (timeoutMs) => remoteTask.runOnce(undefined, timeoutMs)
     : undefined);
   return meta;
 }
 
+function readBlindChecks(value: unknown): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    throw new Error("blind_checks must be a non-negative integer (0 turns the blind-check rule off).");
+  }
+  return value;
+}
+
 function resolveWatchTimeoutSeconds(timeoutSeconds: number | undefined): number | undefined {
   if (timeoutSeconds === undefined) return DEFAULT_WATCH_TIMEOUT_SECONDS;
   if (timeoutSeconds <= 0) return undefined;
@@ -641,7 +745,9 @@ export async function stopTask(
   const remoteSessionMayExist = remote?.session === "tmux"
     && (remote.sessionStarted !== false || remoteStartAttempt !== undefined);
   if (remoteStartAttempt) {
+    remoteStopsAwaitingStart.add(id);
     try { await remoteStartAttempt; } catch { /* A failed SSH result can still leave the detached session running. */ }
+    finally { remoteStopsAwaitingStart.delete(id); }
   }
 
   if (remoteSessionMayExist) {
@@ -729,6 +835,7 @@ async function pollWatch(
 ): Promise<void> {
   if (activePolls.has(id)) return;
   activePolls.add(id);
+  let checked: FirstWatchCheck | undefined;
   try {
     const meta = readMeta(id);
     if (!meta || meta.status !== "running" || meta.kind !== "command_watch") return;
@@ -741,6 +848,10 @@ async function pollWatch(
     const result = runOnce
       ? await runOnce(timeoutMs)
       : await runCommandOnce(commandSpecFromMeta(meta), undefined, timeoutMs);
+    checked = {
+      exitCode: result.exitCode, signal: result.signal, durationMs: Math.max(0, result.endedAt - result.startedAt),
+      ...(result.timedOut ? { timedOut: true } : {}), stdout: result.stdout, stderr: result.stderr,
+    };
     // A poll that was in flight when the session shut down belongs to a stale instance.
     if (scheduledWorkSuspended) return;
     appendWatchResult(meta.logPath, result);
@@ -793,6 +904,10 @@ async function pollWatch(
     else if (result.exitCode !== 0) recordExitFailure(latest, "watch-poll", `Watch poll exited with code ${result.exitCode ?? "unknown"}`, result.exitCode, pollKey,
       { expected: expectedPollExit, at: result.endedAt });
     else recoverFailure(latest, "watch-poll", pollKey, result.endedAt);
+    observeBlindCheck(latest, result, pollKey, {
+      clean: !transportFailure && !conditionErrors.length,
+      matched: failure?.matched === true || success?.matched === true,
+    });
     if (conditionErrors.length) latest.error = conditionErrors.join("; ");
     if (failure?.matched) {
       recordFailure(latest, "failure_when", "failure condition matched", pollKey, { category: "condition", at: result.endedAt });
@@ -840,10 +955,47 @@ async function pollWatch(
       }
       recordFailure(meta, "watch-poll", reason, `throw:${meta.lastCheckedAt ?? meta.startedAt}`, { category: meta.ssh ? "ssh" : "execution" });
       finalize(meta, { status: "failed", reason }, pi, getActiveSession);
+      checked ??= { exitCode: null, signal: null, durationMs: 0, stdout: "", stderr: "", error: reason };
     }
   } finally {
     activePolls.delete(id);
+    if (firstCheckWaiters.has(id)) {
+      if (checked) settleFirstCheck(id, checked);
+      else if (readMeta(id)?.status !== "running") settleFirstCheck(id, undefined);
+    }
+  }
+}
+
+/**
+ * Blind-check rule (#359). A check that exits 0, writes stderr, and matches neither condition
+ * is probably broken: it prints an error and then reports "still pending" forever (the real
+ * incident was a gcloud --format error followed by `exit 0`). After `blindChecks` such checks
+ * in a row, record one actionable incident; the existing attention path wakes the parent once.
+ * The watch keeps running. A later check with empty stderr, whatever its exit code (including a
+ * non-zero, SSH-transport-failed or condition-error check), or one matching a condition,
+ * recovers it; those failures are recorded as their own incidents. Any other check (non-zero
+ * with stderr) resets the count and leaves the incident open. A clean pending check (exit 0,
+ * no stderr) never counts.
+ */
+function observeBlindCheck(meta: BackgroundTaskMeta, result: CommandResult, pollKey: unknown,
+  check: { clean: boolean; matched: boolean }): void {
+  const threshold = meta.blindChecks ?? DEFAULT_BLIND_CHECKS;
+  const stderr = result.stderr.trim();
+  const blind = threshold > 0 && check.clean && !check.matched && result.exitCode === 0 && stderr.length > 0;
+  if (!blind) {
+    meta.blindCheckStreak = 0;
+    if (!stderr || check.matched) recoverFailure(meta, BLIND_OPERATION, pollKey, result.endedAt);
+    return;
   }
+  const streak = (meta.blindCheckStreak ?? 0) + 1;
+  meta.blindCheckStreak = streak;
+  if (streak !== threshold) return;
+  const lastLine = stderr.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).at(-1) ?? "";
+  const clipped = lastLine.length > 240 ? `${lastLine.slice(0, 239)}…` : lastLine;
+  // The summary is capped in compact rows; the stderr line rides as evidence, which rows show whole.
+  recordFailure(meta, BLIND_OPERATION,
+    `Blind watch check: ${streak} checks in a row exited 0 with stderr and matched no condition; the check may be broken. The watch keeps running.`,
+    pollKey, { category: "blind-check", at: result.endedAt, evidence: `latest stderr: ${clipped} · ${BLIND_CHECK_HINT}` });
 }
 
 function finalize(

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

@@ -279,6 +279,8 @@ export function confineCommandSpec(
   plan: ForegroundSandboxPlan,
   profilePath: string,
   seams: SandboxSeams = {},
+  /** Receives lines to show with the launch (e.g. a placeholder left in the user's files). */
+  onNotice: (line: string) => void = () => {},
 ): CommandSpec {
   if (!plan.confined) return spec;
 
@@ -331,6 +333,7 @@ export function confineCommandSpec(
     throw blocked(plan, error instanceof Error ? error.message : String(error));
   }
   if (!command) throw blocked(plan, "no sandbox backend was applied");
+  for (const line of command.notices ?? []) onNotice(line);
 
   return { ...spec, argv: [command.file, ...command.fileArgs], shell: false };
 }

package/node_modules/pi-better-background-tasks/src/shared-failure-observations.ts

@@ -75,7 +75,8 @@ export function failureIdentity(...parts: unknown[]): string {
   return createHash("sha256").update(JSON.stringify(parts)).digest("hex").slice(0, 32);
 }
 function text(value: string | undefined, fallback: string): string {
-  return (value || fallback).replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 400);
+  // The 400-unit cut can split a surrogate pair; a lone half would render as U+FFFD (#332).
+  return dropLoneSurrogates((value || fallback).replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 400));
 }
 
 /** Agent tool attempts: the agent handles its own tool errors, so one failure is not yet actionable. */
@@ -517,6 +518,8 @@ export interface TerminalFailureParts {
   rows: string[];
   /** Counts and separate facts: earlier-reported, unclassified, expected, closed history, correctness. */
   notes: string[];
+  /** The unclassified-count note, when it is among `notes`: a byte budget keeps it longer than the others. */
+  unclassifiedNote?: string;
 }
 /**
  * Terminal/completion facts: actionable and incomplete incidents from `incidents` as rows,
@@ -530,12 +533,14 @@ export function terminalFailureParts(state: FailureState, incidents: readonly st
   const earlier = activeFailures(state).filter((x) => !wanted.has(x.id) && reportable(x)).length;
   if (earlier) notes.push(`${earlier} actionable incident${earlier === 1 ? " was" : "s were"} reported earlier; not repeated here.`);
   const counts = failureCounts(state);
-  if (counts.unclassified) notes.push(`${counts.unclassified} earlier tool failure${counts.unclassified === 1 ? "" : "s"} remain${counts.unclassified === 1 ? "s" : ""} unclassified.`);
+  const unclassifiedNote = counts.unclassified
+    ? `${counts.unclassified} earlier tool failure${counts.unclassified === 1 ? "" : "s"} remain${counts.unclassified === 1 ? "s" : ""} unclassified.` : undefined;
+  if (unclassifiedNote) notes.push(unclassifiedNote);
   if (counts.expected) notes.push(`${counts.expected} expected failure${counts.expected === 1 ? "" : "s"} recorded.`);
   const history = closedHistoryLine(state);
   if (history) notes.push(history);
   if (counts.unclassified || counts.actionRequired) notes.push(CORRECTNESS_NOTE);
-  return { rows, notes };
+  return { rows, notes, ...(unclassifiedNote ? { unclassifiedNote } : {}) };
 }
 export function formatTerminalFailureFacts(state: FailureState, incidents: readonly string[] = []): string {
   const { rows, notes } = terminalFailureParts(state, incidents);
@@ -643,7 +648,10 @@ export interface IncidentPageRequest extends IncidentRowOptions {
  * Caller-owned incident pages. Whole rows are preferred; a row larger than the
  * page is split at a code-point boundary and resumes at that byte, so pages
  * reconstruct formatFailureLines() exactly (join with "\n" except after a page
- * that `endsPartial`). A page never exceeds `maxBytes`.
+ * that `endsPartial`). A page never exceeds `maxBytes`, so one smaller than the
+ * next code point (up to 4 bytes) returns no text, `hasMore`, and a `nextCursor`
+ * equal to `cursor`: the caller retries with a larger page, as with
+ * pageVerbatimText. Consumers never ask for fewer than 4 bytes.
  */
 export function pageFailureIncidents(state: FailureState, request: IncidentPageRequest = {}): FailureIncidentPage {
   // A cursor carries its view: following a history cursor stays in history without the flag.
@@ -761,14 +769,19 @@ export function incidentVerbatimPage(state: FailureState, request: IncidentPageR
  * it, so a cache keyed by it never serves stale incident counts.
  */
 export function failureJournalFingerprint(path: string): string {
-  let file: string;
+  return `${fileChangeIdentity(path)}|${existsSync(`${path}.observed`) ? 1 : 0}|${pendingWrites.get(path)?.length ?? 0}`;
+}
+/**
+ * A file's identity and change stamp (device, inode, size, and nanosecond mtime/ctime), or its read
+ * error. Any append, rewrite, replacement, or deletion changes it; for cache keys, never for trust.
+ */
+export function fileChangeIdentity(path: string): string {
   try {
     const stats = statSync(path, { bigint: true });
-    file = `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeNs}:${stats.ctimeNs}`;
+    return `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeNs}:${stats.ctimeNs}`;
   } catch (error) {
-    file = `unreadable:${(error as NodeJS.ErrnoException).code ?? "error"}`;
+    return `unreadable:${(error as NodeJS.ErrnoException).code ?? "error"}`;
   }
-  return `${file}|${existsSync(`${path}.observed`) ? 1 : 0}|${pendingWrites.get(path)?.length ?? 0}`;
 }
 
 export function incidentCursorAt(state: FailureState, offset: number, resource?: string, options: IncidentRowOptions = {}): string {
@@ -903,7 +916,7 @@ export function formatTerminalIncidentSummary(state: FailureState, options: Inci
   //    cursor's retrieval hint, the unclassified count, the cursor, and the count line. The
   //    correctness note goes last, and only when it alone does not fit.
   const correctness: string[] = notes.filter((x) => x === CORRECTNESS_NOTE);
-  const unclassified = notes.filter((x) => x !== CORRECTNESS_NOTE && /remains? unclassified\.$/.test(x));
+  const unclassified = notes.filter((x) => x === parts.unclassifiedNote);
   const low = notes.filter((x) => !correctness.includes(x) && !unclassified.includes(x));
   const ladder: Array<{ mode: Header | undefined; notes: string[] }> = [];
   for (let keep = low.length - 1; keep >= 0; keep -= 1) ladder.push({ mode: "full", notes: [...low.slice(0, keep), ...unclassified, ...correctness] });