pi-better-harness 0.38.0 → 0.38.1

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

@@ -116,16 +116,32 @@ new Pi process, a task whose process is gone is marked lost.
 
 A task can remain `running` without recent progress evidence. Compact status and
 navigator use the same observation. Process tasks use recorded progress and the
-log's modification time. Watches use recorded progress and completed polls. Before
-any progress, the task's launch time anchors the silence duration. This does not
-measure CPU activity, network waits, or useful application work.
+log's modification time. A watch advances only when a poll observes a changed
+outcome: running a poll, appending its result to the watch log, or polling on
+schedule is activity, not progress. Before any progress, the task's launch time
+anchors the silence duration. This does not measure CPU activity, network waits,
+or useful application work.
 
 At 60 seconds without observed progress, work is `quiet`. At 5 minutes, it has a
 `suspected stall`. Both thresholds are inclusive. Set `PI_BETTER_STALL_QUIET_MS`
 and `PI_BETTER_STALL_MS` to positive millisecond durations to override them.
 Compact status shows the last observed time, silence duration, and a warning:
 silence alone does not prove the task is hung. Terminal tasks are not reported as
-suspected stalls. New output or a completed watch poll refreshes the observation.
+suspected stalls. New process output or a changed watch outcome refreshes the
+observation, so a watch that keeps reporting the same thing becomes quiet and
+then a suspected stall while it keeps polling on schedule.
+
+A watch's outcome is compared by content, not by when it ran. JSON stdout is
+compared with sorted keys and without insignificant whitespace, terminal control
+sequences and carriage-return redraws are ignored, and the poll's start time, end
+time, duration, and check count are never compared. Exit status, signal, error,
+stdout, and stderr content are compared. A watch whose output carries its own
+changing timestamps or elapsed durations will therefore read as progress: project
+the fields that matter into stdout JSON (for example with `jq`) instead of
+printing a whole status page. The comparison is stored with the task, so it
+survives `/reload` and session resume; a watch restored from an older record
+adopts a comparison without resetting its silence, so reloads cannot hide a
+stationary watch.
 
 A status cursor changes when the observation crosses either threshold, even if
 metadata and log bytes have not changed. Within the same observation state,
@@ -293,6 +309,50 @@ history count line with no incident cursor; pass `history: true` to
 (120-byte excerpt, evidence such as `output.log#poll=3`); the raw log keeps the
 full evidence path.
 
+## Chained commands and the step gate
+
+A shell command that chains steps with `;` or newlines reports only its last
+command's exit status. `ctest; write-summary` therefore reads as success when
+`ctest` fails and the summary exits 0. That is ordinary shell behavior, and it
+stays the default.
+
+Pass `require_successful_steps: true` on `bg_task_spawn` (or `bg_task` with
+`action:spawn`) to opt into a step gate:
+
+```json
+{ "command": "ctest --output-on-failure\nnpm run report", "require_successful_steps": true }
+```
+
+The gate is a bash `errexit` contract, not shell parsing: the command runs under
+`set -e`, so its first unhandled failing step ends the task with that step's
+exit code and the remaining steps do not run. That covers the same list, shell
+functions and subshells, and it is why a summary command
+after a failed `ctest` can no longer turn the task green. A failure the command
+handles itself (`|| true`, `if`/`while`/`until` conditions, `!`, `&&`/`||`
+lists) is not a gate failure, and neither is a failing process substitution
+whose status bash discards. Status reports the real process exit with
+`(step gate)` plus the failing step:
+
+```text
+exit=8 (step gate)
+step gate: ctest --output-on-failure exited 8; the shell stopped at that step
+```
+
+A command that switches errexit off (`set +e`) keeps a different own exit; when
+that exit is 0 the gate still fails the task with the failing step's code and
+the status says so (`the shell's own exit was 0`).
+
+The gate is refused (and the task is not started) with `shell:false`, whose
+argv already reports the real exit code, and with structured `ssh`, whose
+command runs under remote semantics the local gate cannot observe. It applies
+to spawns, not to watch checks: a check is one polled command whose own exit
+code is the outcome. Limits inherited from bash's own errexit rules: assignment
+builtins such as `local` and `export` mask a command substitution's status.
+Bash also clears errexit inside command substitutions by default, so
+`x=$(false; echo summary)` can still succeed. A command that disables errexit
+and clears the ERR trap can bypass the gate, and
+`exec` replaces the shell before the gate can decide.
+
 ## When To Use
 
 Use this package for shell commands that need logs, status, cancellation, or completion notifications across a Pi turn.

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

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

@@ -224,7 +224,20 @@ function formatDecision(meta: BackgroundTaskMeta): string | undefined {
     lines.push(formatCondition(result.matchedCondition, result.matchedValue));
   }
   if (meta.lastExitCode !== undefined || meta.lastSignal) {
-    lines.push(`exit=${meta.lastExitCode ?? "null"}${meta.lastSignal ? ` signal=${meta.lastSignal}` : ""}`);
+    // A gated task's exit can be a failing step's code rather than the last command's (#619).
+    const gate = meta.stepGateFailure ? " (step gate)" : "";
+    lines.push(`exit=${meta.lastExitCode ?? "null"}${meta.lastSignal ? ` signal=${meta.lastSignal}` : ""}${gate}`);
+  }
+  if (meta.stepGateFailure) {
+    // "stopped at that step" is the usual errexit case; a differing shell exit means the
+    // command disabled errexit and the gate's EXIT override or the command decided the exit.
+    const gate = meta.stepGateFailure;
+    const ending = gate.shellExitCode === null
+      ? "the shell exit is unknown"
+      : gate.shellExitCode === gate.stepExitCode
+        ? "the shell stopped at that step"
+        : `the shell's own exit was ${gate.shellExitCode}`;
+    lines.push(`step gate: ${oneLine(gate.command || "a chained step", 120)} exited ${gate.stepExitCode}; ${ending}`);
   }
   if (result.reason && !result.matchedCondition) lines.push(oneLine(result.reason, 240));
   if (meta.error && meta.error !== meta.stopError && meta.error !== result.reason) {
@@ -288,6 +301,11 @@ function formatProcessDiagnostics(diagnostics: TaskProcessDiagnostics | undefine
   return `process diagnostics: ${facts}\nA snapshot cannot prove useful work or a hang.`;
 }
 
+function formatStepGate(meta: BackgroundTaskMeta): string | undefined {
+  if (!meta.requireSuccessfulSteps) return undefined;
+  return "step gate: on; the command runs under bash errexit, so its first unhandled failing step ends the task.";
+}
+
 function formatLaunchSandbox(meta: BackgroundTaskMeta): string | undefined {
   const sandbox = meta.sandbox;
   if (!sandbox) return "sandbox: unknown; launch-time policy was not recorded.";
@@ -330,6 +348,8 @@ function contentRevision(meta: BackgroundTaskMeta, stall?: StallObservation): st
     meta.lastProgressAt ?? null,
     meta.lastExitCode ?? null,
     meta.lastSignal ?? null,
+    meta.requireSuccessfulSteps ?? null,
+    meta.stepGateFailure ?? null,
     meta.error ?? null,
     meta.stopError ?? null,
     meta.logGeneration ?? 0,
@@ -493,7 +513,7 @@ export function formatLaunch(meta: BackgroundTaskMeta, firstCheck?: FirstWatchCh
       identity: `Started background ${meta.kind} ${label}. Status: ${meta.status}.`,
       failure: incidentSection(meta.id, {}),
       decision: formatDecision(meta),
-      diagnostics: [formatLaunchSandbox(meta), ...remoteLines, ...(checkText ? [checkText] : [])].filter(Boolean).join("\n") || undefined,
+      diagnostics: [formatLaunchSandbox(meta), formatStepGate(meta), ...remoteLines, ...(checkText ? [checkText] : [])].filter(Boolean).join("\n") || undefined,
       progress: withLog ? logLine : undefined,
     },
     gaps: taskGaps(meta),

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

@@ -2,7 +2,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, writeSync } from "node:fs";
 import { dirname, join } from "node:path";
 import type { ChildProcess } from "node:child_process";
-import type { CommandResult, CommandSpec } from "./types.js";
+import type { CommandResult, CommandSpec, StepGateFailure } from "./types.js";
 
 /** Known Git for Windows locations; `bash -lc` needs a real bash, not the WSL shim. */
 const WINDOWS_BASH_CANDIDATES = [
@@ -75,6 +75,105 @@ export function bashSingleQuote(value: string): string {
   return `'${value.replace(/'/g, "'\\''")}'`;
 }
 
+/**
+ * Env var carrying the operator's own command into a gated launch (#619).
+ *
+ * The gate script `eval`s this value instead of concatenating it, so a command
+ * containing quotes, heredocs, or multiple lines is parsed exactly as bash would
+ * parse it alone. The value is also kept out of the spawned argv.
+ */
+export const STEP_GATE_COMMAND_ENV = "PI_BG_STEP_GATE_COMMAND";
+
+/** Longest failing-step text recorded in task metadata; the log keeps it whole. */
+export const STEP_GATE_COMMAND_CHARS = 160;
+
+/**
+ * Bash script that runs an opt-in step gate around the operator's command (#619).
+ *
+ * The gate is a bash `errexit` contract, not shell parsing: `set -e` ends the
+ * command at the first unhandled failing step with that step's exit code, so a
+ * later command — in the same list, a function, a subshell, or a command
+ * substitution — can no longer turn a red gate green. A failure the command
+ * handles itself (`|| true`, `if`/`while`/`until` conditions, `!`, `&&`/`||`
+ * lists) is not a gate failure, and a discarded process-substitution status is
+ * not one either. `set -E` lets the ERR trap name a failure inside a shell
+ * function (functions run in the main shell); the trap records only main-shell
+ * failures (`BASH_SUBSHELL` 0), so a status bash itself discards is never claimed
+ * as the verdict — an unhandled command substitution still fails its assignment
+ * in the main shell. The EXIT trap writes the verdict to stderr, where the
+ * harness reads it back, and forces a failing step's code when the command
+ * disabled errexit and would have exited 0.
+ *
+ * Exposed for tests and reuse.
+ */
+export function stepGateScript(id: string): string {
+  return [
+    "# Step gate (#619) from pi-better-background-tasks: bash errexit ends the command at its first unhandled failing step.",
+    "set -E",
+    "set -e",
+    `__pi_step_gate_id=${bashSingleQuote(id)}`,
+    "__pi_step_gate_first=0",
+    "__pi_step_gate_command=",
+    "__pi_step_gate_record() {",
+    "  __pi_step_gate_status=$?",
+    "  if [ \"${BASH_SUBSHELL:-0}\" -eq 0 ] && [ \"${__pi_step_gate_first:-0}\" -eq 0 ] && [ \"$__pi_step_gate_status\" -ne 0 ]; then",
+    "    __pi_step_gate_first=$__pi_step_gate_status",
+    "    __pi_step_gate_command=${BASH_COMMAND:-}",
+    "  fi",
+    "  return 0",
+    "}",
+    "__pi_step_gate_finish() {",
+    "  __pi_step_gate_status=$?",
+    "  if [ \"${__pi_step_gate_first:-0}\" -ne 0 ]; then",
+    "    __pi_step_gate_text=${__pi_step_gate_command//$'\\n'/ }",
+    "    printf '\\n--- step gate [%s]: first failing step exit=%s; shell exit=%s: %s ---\\n' \"$__pi_step_gate_id\" \"$__pi_step_gate_first\" \"$__pi_step_gate_status\" \"$__pi_step_gate_text\" >&2",
+    "    if [ \"$__pi_step_gate_status\" -eq 0 ]; then exit \"$__pi_step_gate_first\"; fi",
+    "  fi",
+    "  exit \"$__pi_step_gate_status\"",
+    "}",
+    "trap '__pi_step_gate_record' ERR",
+    "trap '__pi_step_gate_finish' EXIT",
+    `if [ -z "\${${STEP_GATE_COMMAND_ENV}:-}" ]; then`,
+    "  printf '\\n--- step gate [%s]: the gated command was not provided; nothing ran ---\\n' \"$__pi_step_gate_id\" >&2",
+    "  exit 125",
+    "fi",
+    `eval "\${${STEP_GATE_COMMAND_ENV}}"`,
+  ].join("\n");
+}
+
+/**
+ * Read the gate's verdict marker from a task log (#619). Bash writes it as the last
+ * line of stderr, so log retention cannot turn a red gate green; a missing marker
+ * only costs the failing command's name, never the verdict carried by the exit code.
+ *
+ * Exposed for tests and reuse.
+ */
+export function parseStepGateFailure(logText: string, id: string): StepGateFailure | undefined {
+  const marker = `--- step gate [${id}]: first failing step exit=`;
+  let found: StepGateFailure | undefined;
+  for (const rawLine of logText.split("\n")) {
+    const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+    if (!line.startsWith(marker) || !line.endsWith(" ---")) continue;
+    const match = /^--- step gate \[[^\]]+\]: first failing step exit=(-?\d+); shell exit=(-?\d+): (.*) ---$/.exec(line);
+    if (!match) continue;
+    const stepExitCode = Number(match[1]);
+    const shellExitCode = Number(match[2]);
+    if (!Number.isInteger(stepExitCode) || stepExitCode === 0) continue;
+    // The marker is the newest evidence, and the shell writes only the first failing step.
+    found = {
+      stepExitCode,
+      shellExitCode: Number.isInteger(shellExitCode) ? shellExitCode : null,
+      command: boundedStepCommand(match[3]),
+    };
+  }
+  return found;
+}
+
+function boundedStepCommand(value: string): string {
+  const oneLine = value.replace(/\s+/g, " ").trim();
+  return oneLine.length > STEP_GATE_COMMAND_CHARS ? `${oneLine.slice(0, STEP_GATE_COMMAND_CHARS - 1)}…` : oneLine;
+}
+
 /**
  * On Windows, numeric fds above 2 are unusable as child stdio: Node spawns the
  * process, but its output handles end up broken, every write fails, and shell

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

@@ -1,8 +1,9 @@
-import { statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { appendLine, appendTaskOutput, appendWatchResult, retainLogTail, resolveMaxLogBytes } from "./logs.js";
 import { evaluateCondition, validateCondition } from "./conditions.js";
-import { processExists, runCommandOnce, spawnCommand, stopProcessGroup } from "./process.js";
+import { parseStepGateFailure, processExists, runCommandOnce, spawnCommand, STEP_GATE_COMMAND_ENV, stepGateScript, 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";
@@ -22,6 +23,7 @@ import type {
   FirstWatchCheck,
   RemoteTaskParams,
   SshConnectionParams,
+  StepGateFailure,
   TerminalResult,
 } from "./types.js";
 import { observeTaskStallAttention } from "./stall-attention.js";
@@ -170,6 +172,12 @@ export interface SpawnTaskParams extends CommandSpec, TaskIntentParams {
   callback?: boolean;
   timeout_seconds?: number;
   max_log_bytes?: number;
+  /**
+   * Opt-in step gate (#619): run the command under bash errexit, so the first
+   * unhandled failing step ends the task with that step's exit code and a later
+   * command cannot mask it.
+   */
+  require_successful_steps?: boolean;
   ssh?: SshConnectionParams;
   remote?: RemoteTaskParams;
 }
@@ -182,6 +190,12 @@ export interface WatchTaskParams extends CommandSpec, TaskIntentParams {
   max_log_bytes?: number;
   success_when: Condition;
   failure_when?: Condition;
+  /**
+   * Rejected (#619): a watch check is one polled command whose own exit code is the
+   * outcome, so the step gate cannot apply. Accepted in the shared schema only where
+   * the same wrapper also spawns.
+   */
+  require_successful_steps?: boolean;
   /** Consecutive blind checks before the watch is flagged (#359). Default 3; 0 turns it off. */
   blind_checks?: number;
   ssh?: SshConnectionParams;
@@ -190,6 +204,12 @@ export interface WatchTaskParams extends CommandSpec, TaskIntentParams {
 
 export interface TaskRuntimeDependencies {
   remoteRunner?: RemoteRunner;
+  /**
+   * Embedding/test seam for a local watch's poll command. Production polls run
+   * the persisted command through `runCommandOnce`; a remote watch keeps using
+   * its SSH runner instead.
+   */
+  watchPollRunner?: WatchPollRunner;
 }
 
 /**
@@ -201,6 +221,46 @@ function withCommandPolicy(meta: BackgroundTaskMeta, seconds: number | undefined
   return seconds === undefined ? meta : { ...meta, commandTimeoutSeconds: seconds };
 }
 
+/**
+ * The step gate applies to a shell command only (#619). A direct argv launch already
+ * reports the real exit code, and a structured SSH command runs under remote
+ * semantics the local gate cannot observe, so both are refused rather than silently
+ * ignored: a gate that quietly does nothing is the masking bug it exists to fix.
+ */
+function stepGateRefusal(params: SpawnTaskParams): string | undefined {
+  if (params.require_successful_steps !== true) return undefined;
+  if (params.shell === false) {
+    return "Invalid step gate: require_successful_steps needs a shell command; argv with shell:false already reports the real exit code. The task was not started.";
+  }
+  if (!params.command || params.command.trim().length === 0) {
+    return "Invalid step gate: require_successful_steps needs a non-empty shell command. The task was not started.";
+  }
+  if (params.ssh) {
+    return "Invalid step gate: require_successful_steps is local-only and cannot observe a structured ssh command. The task was not started.";
+  }
+  return undefined;
+}
+
+/** Read the gate verdict bash wrote at the end of the task log (#619). */
+function readStepGateFailure(meta: BackgroundTaskMeta): StepGateFailure | undefined {
+  try {
+    return parseStepGateFailure(readFileSync(meta.logPath, "utf8"), meta.id);
+  } catch {
+    // A swept temp dir or an unreadable log costs the reason, never the verdict.
+    return undefined;
+  }
+}
+
+/**
+ * The command actually spawned for a gated task: bash runs the gate script and
+ * `eval`s the operator's own command from `STEP_GATE_COMMAND_ENV`. Meta keeps the
+ * operator's command verbatim, so status, log, and recovery never show the wrapper.
+ */
+function withStepGate(spec: CommandSpec, id: string, gated: boolean): CommandSpec {
+  if (!gated) return spec;
+  return { ...spec, command: stepGateScript(id), env: { ...spec.env, [STEP_GATE_COMMAND_ENV]: spec.command! } };
+}
+
 function persistedCommandCapSeconds(meta: BackgroundTaskMeta): number | undefined {
   const value = meta.commandTimeoutSeconds;
   return isCommandTimeoutSeconds(value) ? value : undefined;
@@ -231,6 +291,10 @@ export function spawnTask(
   // Resolved before any task directory, log, or metadata exists so a blocked
   // launch leaves nothing behind. Structured SSH must also honor launch restrictions.
   const intent = readTaskIntent(params);
+  // A gate that could only be silently ignored is refused before any task state exists (#619).
+  const stepGateRefused = stepGateRefusal(params);
+  if (stepGateRefused) throw new Error(stepGateRefused);
+  const stepGated = params.require_successful_steps === true;
   const cwd = params.cwd ?? defaultCwd;
   const sandboxPlan = resolveForegroundSandboxPlan(pi, !!params.ssh, params);
   // The application/shell switches apply before any task state exists, so a
@@ -253,7 +317,8 @@ export function spawnTask(
       remote: params.remote,
     }, dependencies.remoteRunner)
     : undefined;
-  const commandSpec: CommandSpec = remoteTask?.commandSpec ?? { ...params, cwd, shell: params.shell ?? true };
+  const operatorSpec: CommandSpec = remoteTask?.commandSpec ?? { ...params, cwd, shell: params.shell ?? true };
+  const commandSpec = withStepGate(operatorSpec, id, stepGated);
   const sandboxNotices: string[] = [];
   const launchSpec = remoteTask
     ? commandSpec
@@ -292,6 +357,7 @@ export function spawnTask(
     command: params.command,
     argv: commandSpec.argv,
     shell: commandSpec.shell,
+    ...(stepGated ? { requireSuccessfulSteps: true } : {}),
     cwd,
     env: params.env,
     launchArgv: launchArgvOf(commandSpec, launchSpec),
@@ -321,8 +387,17 @@ export function spawnTask(
       if (!latest) return;
       enforceLogRetention(latest);
       if (isTerminalStatus(latest.status)) return;
-      if (exitCode !== 0) recordExitFailure(latest, "execution", `Process exited with code ${exitCode ?? "unknown"}${signal ? ` (${signal})` : ""}`, exitCode, "close", { at: Date.now() });
-      else {
+      // The gate's own marker names the failing step (#619). It never decides the
+      // verdict: bash errexit already exits with that step's code (and the gate's EXIT
+      // trap forces it when a command disabled errexit), so a missing marker loses the
+      // reason, not the failure.
+      const stepGateFailure = latest.requireSuccessfulSteps ? readStepGateFailure(latest) : undefined;
+      const detail = `Process exited with code ${exitCode ?? "unknown"}${signal ? ` (${signal})` : ""}`;
+      if (exitCode !== 0) {
+        recordExitFailure(latest, "execution", stepGateFailure
+          ? `${detail}; step gate: ${stepGateFailure.command || "a chained step"} exited ${stepGateFailure.stepExitCode}`
+          : detail, exitCode, "close", { at: Date.now() });
+      } else {
         recoverFailure(latest, "execution", "close");
         recoverDeclaredOperation(latest);
       }
@@ -330,6 +405,7 @@ export function spawnTask(
       latest.endedAt = Date.now();
       latest.lastExitCode = exitCode;
       latest.lastSignal = signal;
+      if (stepGateFailure) latest.stepGateFailure = stepGateFailure;
       latest.result = { exitCode, signal };
       writeMeta(latest);
       void notifyTerminal(pi, latest, getActiveSession);
@@ -527,6 +603,9 @@ export function startWatchTask(
     const error = condition && validateCondition(condition);
     if (error) throw new Error(`${name}: ${error}`);
   }
+  if (params.require_successful_steps === true) {
+    throw new Error("Invalid step gate: require_successful_steps is for a spawned shell command; a watch poll reports its own exit code as the outcome. The task was not started.");
+  }
   const blindChecks = readBlindChecks(params.blind_checks);
   const intent = readTaskIntent(params);
   const cwd = params.cwd ?? defaultCwd;
@@ -591,7 +670,7 @@ export function startWatchTask(
   firstCheckWaiters.set(id, { promise: firstCheck, resolve: resolveFirst });
   scheduleWatch(pi, id, 0, getActiveSession, remoteTask
     ? (timeoutMs) => remoteTask.runOnce(undefined, timeoutMs)
-    : undefined);
+    : dependencies.watchPollRunner);
   return meta;
 }
 
@@ -642,7 +721,7 @@ export function resumeRunningTask(
   if (meta.kind === "command_watch") {
     scheduleWatch(pi, meta.id, 0, getActiveSession, remoteTask
       ? (timeoutMs) => remoteTask.runOnce(undefined, timeoutMs)
-      : undefined);
+      : dependencies.watchPollRunner);
     return meta;
   }
 
@@ -912,10 +991,10 @@ async function pollWatch(
     applyCaptureOverflow(latest, result);
     enforceLogRetention(latest);
     latest.lastCheckedAt = Date.now();
-    latest.lastProgressAt = latest.lastCheckedAt;
     latest.lastExitCode = result.exitCode;
     latest.lastSignal = result.signal;
     latest.lastState = extractLastState(result);
+    observeWatchOutcome(latest, result);
 
     const pollKey = result.startedAt;
     if (result.timedOut) {
@@ -1386,7 +1465,10 @@ function enforceLogRetention(meta: BackgroundTaskMeta): void {
     const log = statSync(meta.logPath);
     const mtimeMs = Math.trunc(log.mtimeMs);
     const maintenance = meta.logMaintenance?.mtimeMs === mtimeMs && meta.logMaintenance.size === log.size;
-    if (!maintenance && mtimeMs > (meta.lastProgressAt ?? meta.startedAt)) {
+    // A watch's log only records its own polls, so its mtime is poll activity and
+    // never evidence that the watch's observed outcome moved. Spawned processes
+    // keep taking real log writes as progress.
+    if (meta.kind !== "command_watch" && !maintenance && mtimeMs > (meta.lastProgressAt ?? meta.startedAt)) {
       meta.lastProgressAt = mtimeMs;
       writeMeta(meta);
     }
@@ -1428,4 +1510,91 @@ function extractLastState(result: { stdout: string }): unknown {
   } catch {
     return result.stdout.slice(0, 4000);
   }
-}
+}
+
+/** Version tag of the watch outcome fingerprint. A value from another version is adopted, never compared. */
+const WATCH_FINGERPRINT_VERSION = "v1";
+/** OSC and CSI control sequences are display markup, not content. */
+const TERMINAL_ESCAPE = /\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b\[[0-?]*[ -/]*[@-~]/g;
+
+/**
+ * Text as the terminal would settle it. Redraw frames and control sequences are
+ * display churn: repainting the same visible line is not a new observation.
+ */
+function settledTerminalText(text: string): string {
+  return text
+    .replace(TERMINAL_ESCAPE, "")
+    .split("\n")
+    .map((line) => {
+      // A CR immediately before LF ends the line; any other CR overwrites it in place.
+      const body = line.endsWith("\r") ? line.slice(0, -1) : line;
+      return (body.split("\r").at(-1) ?? "").replace(/[ \t]+$/, "");
+    })
+    .join("\n")
+    .replace(/\n+$/, "");
+}
+
+/** Objects compare by content regardless of key order, so reordered keys are not progress. */
+function canonicalJsonText(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJsonText).join(",")}]`;
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    const entries = Object.keys(record).sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJsonText(record[key])}`);
+    return `{${entries.join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+/** stdout compares as JSON content when it parses, and as settled text otherwise. */
+function canonicalWatchStdout(stdout: string): string {
+  const settled = settledTerminalText(stdout);
+  try {
+    return `json:${canonicalJsonText(JSON.parse(settled))}`;
+  } catch {
+    return `text:${settled}`;
+  }
+}
+
+/**
+ * What a poll observed, independent of when it ran. Exit status, signal, error,
+ * stdout content, and stderr content are included; poll metadata (start time,
+ * end time, duration, check count) is deliberately not, so it can never hide a
+ * watch that reports the same outcome forever. Watch stdout may carry its own
+ * timestamps: projecting meaningful fields is the caller's job, not this
+ * fingerprint's guess.
+ */
+function watchOutcomeFingerprint(result: CommandResult): string {
+  // A runner may report why the check itself could not run; that is part of the
+  // observed outcome, not poll metadata.
+  const reported = (result as CommandResult & { error?: unknown }).error;
+  const error = typeof reported === "string" ? settledTerminalText(reported) : null;
+  const payload = JSON.stringify([
+    result.exitCode,
+    result.signal ?? null,
+    result.timedOut === true,
+    error,
+    canonicalWatchStdout(result.stdout),
+    settledTerminalText(result.stderr),
+  ]);
+  return `${WATCH_FINGERPRINT_VERSION}:${createHash("sha256").update(payload).digest("hex")}`;
+}
+
+/**
+ * A watch's state clock advances only when its observed outcome changes. The
+ * poll itself is activity (`lastCheckedAt`), not progress, so a stationary
+ * watch still becomes quiet and then a suspected stall while it keeps polling.
+ * A record with no current fingerprint is adopted without moving the clock, so
+ * an upgrade or reload cannot keep resetting that silence.
+ */
+function observeWatchOutcome(meta: BackgroundTaskMeta, result: CommandResult): void {
+  const fingerprint = watchOutcomeFingerprint(result);
+  const prior = meta.watchFingerprint;
+  meta.watchFingerprint = fingerprint;
+  const comparable = typeof prior === "string" && prior.startsWith(`${WATCH_FINGERPRINT_VERSION}:`);
+  if (!comparable) {
+    if (meta.lastProgressAt === undefined) meta.lastProgressAt = meta.startedAt;
+    return;
+  }
+  if (prior !== fingerprint) meta.lastProgressAt = meta.lastCheckedAt ?? Date.now();
+}

package/node_modules/pi-better-background-tasks/src/shared-callback-batcher.ts

@@ -604,7 +604,7 @@ export function createCallbackBatcher(
 
   const enqueue = (event: CallbackBatchEvent): boolean => {
     if (event.callback === false) return false;
-    const key = eventKey(event);
+    const key = completionKey(event);
     if (pending.has(key) || inFlight.has(key)) return false;
     pending.set(key, { event, sequence: sequence++ });
     schedule(windowMs);
@@ -884,6 +884,23 @@ function eventKey(event: Pick<CallbackBatchEvent, "source" | "id" | "status">):
   return `${event.source}\u0000${event.id}\u0000${event.status}`;
 }
 
+/**
+ * Ordinary completion identity is the run/task id, not the status wording (#624).
+ *
+ * The status field is a snapshot taken when a notification is enqueued (failure
+ * notes, observation gaps, timing reason). Including it in the key meant a
+ * not-yet-delivered run whose status changed between enqueues entered the
+ * pending map twice; one flush then rendered both rows and the caller saw one
+ * completion twice. Urgent events keep the status in their key: those are
+ * distinct transitions (orphaned, lost, a timing wake, a failure key), not
+ * restatements of a single ordinary completion. The first queued snapshot is the
+ * one delivered; a later status wording for the same id is dropped rather than
+ * re-queued, and the durable result stays the authority for failure detail.
+ */
+function completionKey(event: Pick<CallbackBatchEvent, "source" | "id">): string {
+  return `${event.source}\u0000${event.id}`;
+}
+
 function eventDisposition(
   event: Pick<CallbackBatchEvent, "isDelivered" | "getSuppressionReason">,
 ):   | { kind: "deliver" } | { kind: "delivered" } | { kind: "deferred" } | { kind: "suppressed"; reason: string } {