pi-better-background-tasks 0.5.0 → 0.6.0

package/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/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/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/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/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/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] });

package/src/shared-navigator.ts

@@ -95,6 +95,13 @@ type NavigatorState = {
   editorComponent?: Component;
   /** The editor Pi currently has mounted (the wrapper the factory returned last). */
   editorFocusTarget?: unknown;
+  /** How many times that wrapper has rendered, so an overlay can tell whether it is still on screen. */
+  editorRenders?: number;
+  /**
+   * Whether that wrapper rendered between the overlay's last two frames: true while it is on screen,
+   * including inside another extension's editor that wraps it. Undefined until two frames compare.
+   */
+  editorRenderedLastFrame?: boolean;
   detailOverlayRows?: number;
   dispose?: () => void;
   /** The mounted detail overlay, reused instead of stacking a second one. */
@@ -632,7 +639,7 @@ function installNavigatorEditor(ui: any, deps: HostDeps): unknown {
 
 function wrapEditor(inner: any, deps: HostDeps): unknown {
   if (inner && typeof inner.render === "function") state().editorComponent = inner as Component;
-  const proxy = new Proxy(inner, {
+  const proxy: any = new Proxy(inner, {
     get(target, prop) {
       if (prop === "handleInput") {
         return (data: string) => {
@@ -642,6 +649,13 @@ function wrapEditor(inner: any, deps: HostDeps): unknown {
           target.handleInput(data);
         };
       }
+      if (prop === "render" && typeof target.render === "function") {
+        return (...args: unknown[]) => {
+          const s = state();
+          if (s.editorFocusTarget === proxy) s.editorRenders = (s.editorRenders ?? 0) + 1;
+          return target.render(...args);
+        };
+      }
       const value = Reflect.get(target, prop);
       return typeof value === "function" ? value.bind(target) : value;
     },
@@ -709,6 +723,19 @@ function handleMainListInput(data: string, deps: HostDeps): boolean {
   return false;
 }
 
+/**
+ * Whether pi-tui has the editor our wrapper returned mounted (#332). Pi mounts whatever the factory
+ * returns, so another extension's `setEditorComponent` (a foreign factory, or `undefined` for Pi's
+ * default editor) unmounts it, and no key reaches our input handler after that. `undefined` means
+ * the host cannot say (no `isComponentMounted`), and callers keep their earlier behaviour.
+ */
+function liveEditorMounted(tui: unknown): boolean | undefined {
+  const live = state().editorFocusTarget;
+  const check = (tui as { isComponentMounted?: (component: unknown) => boolean } | undefined)?.isComponentMounted;
+  if (!live || typeof check !== "function") return undefined;
+  try { return check.call(tui, live) === true; } catch { return undefined; }
+}
+
 /** Close a detail overlay that is still mounted while the editor has focus. */
 function dismissOverlay(): void {
   const s = state();
@@ -762,6 +789,7 @@ function openNavigator(): void {
   try {
     try { s.dispose?.(); } catch { /* ignore */ }
     s.dispose = undefined;
+    s.editorRenderedLastFrame = undefined;
     let disposeToken: (() => void) | undefined;
     let overlayRef: NavigatorState["overlay"];
     let handle: { focus?(): void; unfocus?(options?: { target: unknown }): void } | undefined;
@@ -774,8 +802,12 @@ function openNavigator(): void {
         // Pi restores focus to the editor that was focused when the overlay opened. If an
         // extension re-installed the editor since, that instance is unmounted and every key
         // would be lost; hand focus to the live editor before closing.
+        // Only an editor on screen can take focus: after another extension replaced ours, Pi already
+        // focused its replacement, and handing focus to our unmounted wrapper would swallow every key.
+        // An extension that wraps ours mounts its own component, so pi-tui does not find ours, but ours
+        // still renders and handles every key through it: that is still the live editor (#332).
         const liveEditor = s.editorFocusTarget;
-        if (liveEditor) {
+        if (liveEditor && (liveEditorMounted(tui) !== false || s.editorRenderedLastFrame !== false)) {
           try { handle?.unfocus?.({ target: liveEditor }); } catch { /* ignore */ }
         }
         done(value);
@@ -952,8 +984,31 @@ function createOverlayComponent(
     requestRender();
   }
 
+  let editorRendersSeen: number | undefined;
+  /**
+   * Our editor wrapper was uninstalled: close, since no key of ours can reach this overlay again and
+   * it would cover the editor that replaced ours (#332). An extension that composes the editor inside
+   * its own non-container component still renders ours, so the wrapper also counts as live while it
+   * rendered since the previous overlay frame (Pi renders the editor before it composites overlays).
+   */
+  function closeIfEditorReplaced(): void {
+    const rendersBefore = editorRendersSeen;
+    const renders = state().editorRenders ?? 0;
+    editorRendersSeen = renders;
+    state().editorRenderedLastFrame = rendersBefore === undefined ? undefined : renders !== rendersBefore;
+    if (closed || liveEditorMounted(tui) !== false || rendersBefore === undefined || renders !== rendersBefore) return;
+    // Not from inside pi-tui's render pass: hiding an overlay there would change the stack it is drawing.
+    queueMicrotask(() => {
+      if (closed) return;
+      unfocusMainList();
+      close();
+      requestRender();
+    });
+  }
+
   return {
     render(width: number) {
+      closeIfEditorReplaced();
       refreshRows();
       const railLines = buildMainListLines(overlayState.rows, width, deps.truncate, fg, {
         selectedId: selectedRow()?.navigatorId,

package/src/shared-sandbox-core.ts

@@ -109,8 +109,12 @@ export type SandboxCommandArgs = SandboxTarget & {
     internalHelperExecutable?: boolean;
 };
 
-/** The wrapper command to spawn: the backend executable and its full argv. */
-export type SandboxCommand = { file: string; fileArgs: string[] };
+/**
+ * The wrapper command to spawn: the backend executable and its full argv.
+ * `notices` are lines the caller shows with the launch output, such as a
+ * placeholder the Linux backend had to leave in the user's files.
+ */
+export type SandboxCommand = { file: string; fileArgs: string[]; notices?: string[] };
 
 /** The caller's default-on / explicit-request / opt-out decision. */
 export type SandboxRequest = {
@@ -131,7 +135,11 @@ export type SandboxSeams = {
     platform?: () => string;
     /** Defaults to a PATH scan that stats and access-checks without executing. */
     lookupExecutable?: (name: string) => string | undefined;
-    /** Defaults to `fs.realpathSync`. Must throw when the path does not exist. */
+    /**
+     * Defaults to `fs.realpathSync.native`, which (unlike the JS `realpathSync`)
+     * returns the on-disk case of every existing component on a case-insensitive
+     * volume, as the kernel sees it. Must throw when the path does not exist.
+     */
     canonicalize?: (path: string) => string;
     /** Defaults to `fs.writeFileSync`. */
     writeProfile?: (path: string, contents: string) => void;
@@ -325,7 +333,7 @@ function currentPlatform(seams: SandboxSeams): string {
  * canonicalizes through its real parent chain.
  */
 export function canonicalizePath(path: string, seams: SandboxSeams = {}): string {
-    const canonicalize = seams.canonicalize ?? realpathSync;
+    const canonicalize = seams.canonicalize ?? realpathSync.native;
     const absolute = resolve(path);
     try {
         const resolved = canonicalize(absolute);
@@ -337,7 +345,7 @@ export function canonicalizePath(path: string, seams: SandboxSeams = {}): string
             try {
                 const source = statSync(resolved);
                 const alias = statSync(candidate);
-                if (source.dev === alias.dev && source.ino === alias.ino) return realpathSync(candidate);
+                if (source.dev === alias.dev && source.ino === alias.ino) return realpathSync.native(candidate);
             } catch { /* An unrelated Data-volume path keeps its original identity. */ }
         }
         return resolved;
@@ -358,7 +366,7 @@ function compile(
     // bind-mounts it; the macOS backend has always tolerated a not-yet-created
     // one. Keep both behaviors rather than unifying them here.
     const writableRoot = strictRoot
-        ? (seams.canonicalize ?? realpathSync)(policy.writableRoot)
+        ? (seams.canonicalize ?? realpathSync.native)(policy.writableRoot)
         : canonicalizePath(policy.writableRoot, seams);
 
     // The broad profile also keeps each literal entry: its removal grants would
@@ -544,6 +552,67 @@ function contains(root: string, target: string): boolean {
     return target.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
 }
 
+/** Per-device answer to "does this volume fold case?" (APFS/HFS+ default). */
+const caseFoldingByDevice = new Map<number, boolean>();
+
+/**
+ * Whether the volume holding `path` (its nearest existing ancestor) ignores
+ * case: an existing component whose case-swapped spelling names the same
+ * inode proves it. macOS only; false whenever it cannot be shown.
+ */
+function caseInsensitiveVolume(path: string): boolean {
+    if (process.platform !== "darwin") return false;
+    let current = path;
+    while (!existsSync(current) && dirname(current) !== current) current = dirname(current);
+    let device: number;
+    try { device = statSync(current).dev; } catch { return false; }
+    const known = caseFoldingByDevice.get(device);
+    if (known !== undefined) return known;
+    for (let probe = current; dirname(probe) !== probe; probe = dirname(probe)) {
+        const name = basename(probe);
+        const swapped = [...name].map((c) => c === c.toLowerCase() ? c.toUpperCase() : c.toLowerCase()).join("");
+        if (swapped === name) continue;
+        try {
+            const original = statSync(probe);
+            if (original.dev !== device) break;
+            let folded = false;
+            try {
+                const other = statSync(join(dirname(probe), swapped));
+                folded = other.dev === original.dev && other.ino === original.ino;
+            } catch { /* The swapped name is absent: case-sensitive. */ }
+            caseFoldingByDevice.set(device, folded);
+            return folded;
+        } catch { return false; }
+    }
+    return false;
+}
+
+/**
+ * Spell `path` the way the policy spells it when they differ only in case on a
+ * case-insensitive volume. `canonicalizePath` fixes the case of every existing
+ * component, but a missing tail (`~/.NPMRC` while `~/.npmrc` is absent) keeps
+ * the caller's case, and the kernel still treats it as the protected name. The
+ * longest policy path that matches case-insensitively wins, so the pre-check
+ * decides as the kernel does (#354).
+ */
+function alignCaseToPolicy(path: string, policy: CompiledSandboxWritePolicy): string {
+    const broad = policy.broad;
+    const candidates = [policy.writableRoot, ...policy.denyWrite, ...(policy.credentialPaths ?? []),
+        ...(policy.runtimeWrite ?? []), ...(policy.compatibilityWrite ?? []),
+        ...(broad ? [broad.home, ...broad.tempRoots, ...broad.deleteRoots, ...broad.codePaths] : [])];
+    const lower = path.toLowerCase();
+    if (lower.length !== path.length) return path;
+    let best: string | undefined;
+    for (const candidate of candidates) {
+        const folded = candidate.toLowerCase();
+        if (folded.length !== candidate.length || !contains(folded, lower)) continue;
+        if (!best || candidate.length > best.length) best = candidate;
+    }
+    // Already spelled as the policy spells it: nothing to probe.
+    if (!best || path.startsWith(best) || !caseInsensitiveVolume(path)) return path;
+    return `${best}${path.slice(best.length)}`;
+}
+
 function isCredential(path: string, policy: CompiledSandboxWritePolicy): boolean {
     return (policy.credentialPaths ?? []).some((credential) => contains(credential, path));
 }
@@ -558,7 +627,7 @@ export function evaluateReadAccess(
     policy: CompiledSandboxWritePolicy,
     seams: SandboxSeams = {},
 ): ReadAccessDecision {
-    const path = canonicalizePath(target, seams);
+    const path = alignCaseToPolicy(canonicalizePath(target, seams), policy);
     const permissions = policy.permissions;
     if (!permissions) return { allowed: true, path };
     if (policy.broad) {
@@ -585,7 +654,7 @@ export function evaluateWriteAccess(
     policy: CompiledSandboxWritePolicy,
     seams: SandboxSeams = {},
 ): WriteAccessDecision {
-    const path = canonicalizePath(target, seams);
+    const path = alignCaseToPolicy(canonicalizePath(target, seams), policy);
     if (policy.broad) return evaluateBroadWrite(path, policy, policy.broad, seams);
     if (!policy.permissions && !contains(policy.writableRoot, path)) {
         return { allowed: false, path, reason: "outside-writable-root" };
@@ -1370,10 +1439,28 @@ function buildLinuxBroadCommand(
     const readOnly = new Set<string>();
     const directoryLocation = (path: string) => [...DIRECTORY_LOCATIONS]
         .some((name) => canonicalizePath(join(broad.home, name), seams) === path);
+    // The literal fixed-list entry (a dangling `~/.ssh` link) or its canonical path.
+    const directoryEntry = (path: string) => directoryLocation(path) ||
+        [...DIRECTORY_LOCATIONS].some((name) => join(broad.home, name) === path);
     // Directories holding a protected symlink: read-only, so the link cannot be
     // replaced, with their existing entries bound writable again below.
     const linkParents = new Set<string>();
-    const danglingTargets = new Set(protectedPaths.flatMap((path) => walkSymlinks(path).unresolved));
+    // Where dangling links would land. Only the first missing component of each
+    // needs a guard: nothing can be created below a read-only mount or a locked
+    // parent. It is a directory when more of the path lies below it, or when the
+    // link is a directory-type entry (`~/.ssh -> ~/work/ssh`).
+    const firstMissing = new Map<string, boolean>();
+    const belowFirstMissing = new Set<string>();
+    for (const path of protectedPaths) {
+        const unresolved = walkSymlinks(path).unresolved;
+        if (!unresolved.length) continue;
+        const first = unresolved[0]!;
+        const full = unresolved.at(-1)!;
+        firstMissing.set(first, firstMissing.get(first) === true || first !== full || directoryEntry(path));
+        if (full !== first) belowFirstMissing.add(full);
+    }
+    const created: string[] = [];
+    const makeDirectory = seams.makeDirectory ?? ((target: string) => mkdirSync(target, { recursive: true, mode: 0o700 }));
     const guard = (path: string, hide: boolean) => {
         let directory: boolean | undefined;
         let link = false;
@@ -1387,21 +1474,39 @@ function buildLinuxBroadCommand(
             if (link && dirname(path) !== broad.home && writableAt(dirname(path))) linkParents.add(dirname(path));
             return;
         }
-        if (danglingTargets.has(path)) {
+        if (belowFirstMissing.has(path) && !firstMissing.has(path)) return; // Its first missing component is guarded.
+        if (firstMissing.has(path)) {
             // Where a dangling link would land: nothing may be created there.
-            // Lock its nearest existing ancestor (entries stay writable, see
-            // below) rather than plant a placeholder in the user's files. Temp
-            // and the workspace root stay open to new entries, so a placeholder
-            // is bound there instead, failing closed if it cannot be made.
+            // A missing directory gets an empty read-only placeholder directory,
+            // so only that one name is taken, not every new entry beside it
+            // (`~/.cache/<tool>/…` would otherwise lock all of `~/.cache`). A
+            // missing file is not planted in the user's files: its parent is
+            // locked instead (entries stay writable, see below), except in the
+            // workspace root and temp, which must keep accepting new entries,
+            // so the file placeholder is bound there. Each placeholder made is
+            // reported, and the workspace and temp fail closed without one.
             if (!writableAt(path)) return;
-            let ancestor = dirname(path);
-            while (!exists(ancestor) && dirname(ancestor) !== ancestor) ancestor = dirname(ancestor);
-            if (ancestor === project || broad.tempRoots.includes(ancestor)) {
-                if (!materialize(path)) throw new Error(`Cannot protect denied path: ${path}`);
-                readOnly.add(path);
-            } else if (ancestor !== broad.home) {
-                linkParents.add(ancestor);
+            const ancestor = dirname(path);
+            if (ancestor === broad.home) return; // Home is read-only already.
+            const failClosed = ancestor === project || broad.tempRoots.includes(ancestor);
+            const directory = firstMissing.get(path)!;
+            if (directory || failClosed) {
+                const existed = exists(path);
+                let made: boolean;
+                if (directory) {
+                    try { makeDirectory(path); } catch { /* Re-checked below. */ }
+                    made = exists(path);
+                } else {
+                    made = materialize(path);
+                }
+                if (made) {
+                    if (!existed) created.push(`${path}${directory ? "/" : ""}`);
+                    readOnly.add(path);
+                    return;
+                }
+                if (failClosed) throw new Error(`Cannot protect denied path: ${path}`);
             }
+            linkParents.add(ancestor);
             return;
         }
         if (!exists(path)) {
@@ -1476,6 +1581,9 @@ function buildLinuxBroadCommand(
         file: bwrap,
         fileArgs: [...fileArgs, ...(!permissions.network ? ["--unshare-net"] : []),
             "--", args.execPath, ...args.execArgs],
+        ...(created.length && { notices: [
+            `Sandbox: created an empty read-only placeholder where a protected symlink points at nothing, and left it in place: ${created.join(", ")}`,
+        ] }),
     };
 }
 

package/src/tools.ts

@@ -14,8 +14,8 @@ import {
 } from "./output.js";
 import { readOutputControls } from "./shared-log-utils.js";
 import { cancelCallbackBatch } from "./shared-callback-batcher.js";
-import { inspectMeta, listMetasForOrigin, writeMeta } from "./registry.js";
-import { resumeRunningTask, spawnTask, startWatchTask, stopTask } from "./runtime.js";
+import { inspectMeta, listMetasForOrigin, readMeta, writeMeta } from "./registry.js";
+import { awaitFirstWatchCheck, FIRST_WATCH_CHECK_WAIT_MS, resumeRunningTask, spawnTask, startWatchTask, stopTask, type WatchTaskParams } from "./runtime.js";
 import { runTaskMaintenance } from "./maintenance.js";
 import { ForegroundSandboxBlockedError } from "./sandbox.js";
 import type { BackgroundTaskCallbackOrigin, BackgroundTaskMeta } from "./types.js";
@@ -91,11 +91,23 @@ const CommandFields = {
 
 const SpawnParams = Type.Object(CommandFields);
 
+const BlindChecksField = Type.Optional(Type.Integer({ minimum: 0, description: "Flag the watch as possibly blind after this many checks in a row exit 0, write stderr, and match neither success_when nor failure_when: one incident that needs action, with the latest stderr line. The watch keeps running; a check with no stderr or a matched condition recovers it. Default 3; 0 turns it off." }));
+
+/**
+ * How to write a watch check (#359): a check that swallows its own errors reports "pending"
+ * forever. Shared by bg_task_watch and the bg_task wrapper.
+ */
+const WATCH_CHECK_GUIDANCE = "Waits up to 15s for the first check and returns its exit code with stdout and stderr tails; if it is still running, says so. "
+  + "Write the check so a broken check is visible: do not end it with `exit 0` or `|| true`, because a check that exits non-zero is recorded and escalates. "
+  + "Map an unknown or unparseable state to failure (exit non-zero), not to pending. Prefer structured output, e.g. `--format=json | jq -er '.status'`, over fragile format strings. "
+  + "A check that exits 0 but writes stderr without matching a condition for blind_checks (default 3) checks in a row is flagged as needing action; if that stderr is expected, redirect it (2>/dev/null) or set blind_checks:0.";
+
 const WatchParams = Type.Object({
   ...CommandFields,
   interval_seconds: Type.Optional(Type.Number({ description: "Polling interval in seconds. Default 30." })),
   success_when: ConditionSchema,
   failure_when: Type.Optional(ConditionSchema),
+  blind_checks: BlindChecksField,
 });
 
 const CursorFields = {
@@ -152,6 +164,7 @@ const ActionParams = Type.Object({
   interval_seconds: Type.Optional(Type.Number()),
   success_when: Type.Optional(ConditionSchema),
   failure_when: Type.Optional(ConditionSchema),
+  blind_checks: BlindChecksField,
   raw: Type.Optional(Type.Boolean()),
   ...HistoryField,
   ...CursorFields,
@@ -215,12 +228,12 @@ export function registerTools(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "bg_task_watch",
     label: "BG Watch",
-    description: "Poll a command in the background until success_when, failure_when, or timeout matches. For remote work, prefer structured ssh: pass ssh:{host,user} and provide the remote command in command; each interval opens a direct one-shot SSH poll without tmux installation. For short synchronous remote commands that should return output now, use remote_bash from pi-better-ssh. Returns immediately with its task id. Default timeout 900 seconds; pass timeout_seconds:0 to disable.",
+    description: `Poll a command in the background until success_when, failure_when, or timeout matches. For remote work, prefer structured ssh: pass ssh:{host,user} and provide the remote command in command; each interval opens a direct one-shot SSH poll without tmux installation. For short synchronous remote commands that should return output now, use remote_bash from pi-better-ssh. Returns its task id once the first check finishes. ${WATCH_CHECK_GUIDANCE} Default timeout 900 seconds; pass timeout_seconds:0 to disable.`,
     promptGuidelines: BACKGROUND_ORCHESTRATION_GUIDELINES,
     parameters: WatchParams,
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       activeSession = getCallbackOrigin(ctx);
-      const launched = reportLaunch(() => startWatchTask(pi, params, ctx.cwd, activeSession, getActiveSession));
+      const launched = await launchWatch(pi, params, ctx.cwd, activeSession, getActiveSession, FIRST_WATCH_CHECK_WAIT_MS, signal);
       refreshBackgroundTasksNavigator(ctx);
       return text(launched);
     },
@@ -278,15 +291,15 @@ export function registerTools(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "bg_task",
     label: "BG Task",
-    description: "Action wrapper for background tasks: spawn, watch, list, status, log, stop, or clear. For remote work, prefer structured ssh: pass ssh:{host,user} and provide the remote command in command. For short synchronous remote commands that should return output now, use remote_bash from pi-better-ssh. SSH spawn defaults to durable tmux; SSH watches use direct one-shot polls without tmux installation; remote.session=direct is a weaker-stop spawn escape hatch. Spawn/watch return immediately; do not poll in foreground. For action:status, default compact output and use verbose:true only for full metadata. For action:log, default compact tail and use lines:0 to page retained raw bytes. Standalone tools and these wrappers share the same output assembler. List/status/log default to the current session; pass all:true to override. Stop and clear change only current-session tasks: clear dismisses every owned terminal task, or one task with id (all:true allows another session's task by id).",
+    description: "Action wrapper for background tasks: spawn, watch, list, status, log, stop, or clear. For remote work, prefer structured ssh: pass ssh:{host,user} and provide the remote command in command. For short synchronous remote commands that should return output now, use remote_bash from pi-better-ssh. SSH spawn defaults to durable tmux; SSH watches use direct one-shot polls without tmux installation; remote.session=direct is a weaker-stop spawn escape hatch. Spawn returns immediately; do not poll in foreground. For action:watch: " + WATCH_CHECK_GUIDANCE + " For action:status, default compact output and use verbose:true only for full metadata. For action:log, default compact tail and use lines:0 to page retained raw bytes. Standalone tools and these wrappers share the same output assembler. List/status/log default to the current session; pass all:true to override. Stop and clear change only current-session tasks: clear dismisses every owned terminal task, or one task with id (all:true allows another session's task by id).",
     promptGuidelines: BACKGROUND_ORCHESTRATION_GUIDELINES,
     parameters: ActionParams,
     renderResult(result: unknown, options: unknown, theme: unknown) {
       return renderBackgroundTaskLogDisplay(result, options, theme);
     },
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       activeSession = getCallbackOrigin(ctx);
-      return actionText(pi, params, ctx, activeSession, getActiveSession);
+      return actionText(pi, params, ctx, activeSession, getActiveSession, signal);
     },
   });
 
@@ -356,11 +369,12 @@ async function actionText(
   ctx: ExtensionContext,
   callbackOrigin: BackgroundTaskCallbackOrigin,
   getActiveSession: () => BackgroundTaskCallbackOrigin | undefined,
+  signal?: AbortSignal,
 ) {
   if (params.action === "log" && params.id) {
     return logText(String(params.id), logOptions(params, callbackOrigin));
   }
-  return text(await runAction(pi, params, ctx, callbackOrigin, getActiveSession));
+  return text(await runAction(pi, params, ctx, callbackOrigin, getActiveSession, signal));
 }
 
 async function runAction(
@@ -369,13 +383,14 @@ async function runAction(
   ctx: ExtensionContext,
   callbackOrigin: BackgroundTaskCallbackOrigin,
   getActiveSession: () => BackgroundTaskCallbackOrigin | undefined,
+  signal?: AbortSignal,
 ): Promise<string> {
   switch (params.action) {
     case "spawn":
       return withNavigatorRefresh(ctx, reportLaunch(() => spawnTask(pi, params, ctx.cwd, callbackOrigin, getActiveSession)));
     case "watch":
       if (!params.success_when) return "Invalid parameters: watch requires success_when.";
-      return withNavigatorRefresh(ctx, reportLaunch(() => startWatchTask(pi, params as never, ctx.cwd, callbackOrigin, getActiveSession)));
+      return withNavigatorRefresh(ctx, await launchWatch(pi, params as unknown as WatchTaskParams, ctx.cwd, callbackOrigin, getActiveSession, FIRST_WATCH_CHECK_WAIT_MS, signal));
     case "list":
       return formatList(listOptions(params, callbackOrigin));
     case "status":
@@ -409,6 +424,33 @@ function reportLaunch(launch: () => BackgroundTaskMeta): string {
   }
 }
 
+/**
+ * Start a watch and wait, bounded by `waitMs`, for its first check, so the launch result
+ * shows what the check really prints (#359). Local and SSH watches share this path.
+ */
+export async function launchWatch(
+  pi: ExtensionAPI,
+  params: WatchTaskParams,
+  cwd: string,
+  callbackOrigin: BackgroundTaskCallbackOrigin | undefined,
+  getActiveSession: () => BackgroundTaskCallbackOrigin | undefined,
+  waitMs = FIRST_WATCH_CHECK_WAIT_MS,
+  signal?: AbortSignal,
+): Promise<string> {
+  let meta: BackgroundTaskMeta;
+  try {
+    meta = startWatchTask(pi, params, cwd, callbackOrigin, getActiveSession);
+  } catch (error) {
+    if (error instanceof ForegroundSandboxBlockedError) return error.message;
+    throw error;
+  }
+  // Esc (the tool's abort signal) ends the wait at once; the watch itself keeps running.
+  const outcome = await awaitFirstWatchCheck(meta.id, waitMs, signal);
+  const latest = readMeta(meta.id) ?? meta;
+  if (outcome && !("pending" in outcome && isTerminalStatus(latest.status))) return formatLaunch(latest, outcome);
+  return formatLaunch(latest);
+}
+
 function withNavigatorRefresh(ctx: ExtensionContext, result: string): string {
   refreshBackgroundTasksNavigator(ctx);
   return result;

package/src/types.ts

@@ -42,6 +42,18 @@ export interface CommandResult {
   captureTruncated?: boolean;
 }
 
+/** A watch's first check, as reported in the launch tool result (#359). */
+export interface FirstWatchCheck {
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  durationMs: number;
+  timedOut?: boolean;
+  stdout: string;
+  stderr: string;
+  /** Set when the check itself could not run (e.g. an SSH runner error). */
+  error?: string;
+}
+
 export interface RemoteTaskParams {
   session?: "tmux" | "direct";
   install_tmux?: boolean;
@@ -124,6 +136,14 @@ export interface BackgroundTaskMeta {
   spawnPidStartTime?: string;
   successWhen?: Condition;
   failureWhen?: Condition;
+  /**
+   * Watch only (#359): consecutive exit-0 checks that write stderr and match neither
+   * condition before the watch is flagged as possibly blind. 0 turns the rule off;
+   * undefined means DEFAULT_BLIND_CHECKS.
+   */
+  blindChecks?: number;
+  /** Current run of such checks; reset by any other check. */
+  blindCheckStreak?: number;
   /**
    * Caller-declared structured intent (#325), validated before launch. A later task of the same
    * kind, cwd, SSH target, and session with the same operationId that succeeds recovers this