pi-better-background-tasks 0.4.0 → 0.6.0

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
@@ -414,13 +422,22 @@ function lexicalAndCanonical(home: string, name: string, seams: SandboxSeams): s
 
 /**
  * Every symlink directory entry met while resolving `path`, component by
- * component (as `readlink` would follow them). A chain such as
+ * component (as `readlink` would follow them), plus where a dangling chain
+ * would land. A chain such as
  * `~/.zshrc -> ~/.dotfiles/zshrc -> ~/dotfiles/zshrc` has an intermediate link
  * in a removable directory; replacing it would retarget the protected entry, so
- * each hop the user could replace is protected too. Bounded: a loop or more
- * than 40 hops stops the walk (such a path resolves to nothing).
+ * each hop the user could replace is protected too. When a followed link
+ * points at something missing, creating it would give the entry content, so
+ * the first missing component (which covers every missing directory below it)
+ * and the full path it would resolve to are protected as well. Bounded: a loop
+ * or more than 40 hops stops the walk (such a path resolves to nothing).
  */
 function symlinkHops(path: string): string[] {
+    const { hops, unresolved } = walkSymlinks(path);
+    return [...hops, ...unresolved];
+}
+
+function walkSymlinks(path: string): { hops: string[]; unresolved: string[] } {
     const hops: string[] = [];
     const seen = new Set<string>();
     let followed = 0;
@@ -433,7 +450,13 @@ function symlinkHops(path: string): string[] {
         if (component === "..") { current = dirname(current); continue; }
         const entry = join(current, component);
         let link: boolean;
-        try { link = lstatSync(entry).isSymbolicLink(); } catch { break; }
+        try {
+            link = lstatSync(entry).isSymbolicLink();
+        } catch {
+            // Missing. Only a followed link makes this a dangling target; a
+            // plain absent path is guarded as it is.
+            return { hops, unresolved: followed ? [...new Set([entry, resolve(entry, ...pending)])] : [] };
+        }
         if (!link) { current = entry; continue; }
         if (++followed > 40 || seen.has(entry)) break;
         seen.add(entry);
@@ -448,7 +471,12 @@ function symlinkHops(path: string): string[] {
             pending = [...target.split(sep), ...pending];
         }
     }
-    return hops;
+    return { hops, unresolved: [] };
+}
+
+/** Whether a symlink resolves to nothing: dangling (ENOENT), or looping or over 40 hops (ELOOP). */
+function unresolvable(path: string): boolean {
+    try { statSync(path); return false; } catch { return true; }
 }
 
 function broadCredentialPaths(home: string, seams: SandboxSeams): string[] {
@@ -524,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));
 }
@@ -538,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) {
@@ -565,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" };
@@ -1296,7 +1385,10 @@ function maskSources(profilePath: string): { directory: string; file: string } {
  * home itself stay read-only, so sibling repositories cannot even be edited in
  * place there. Credentials are masked by empty mode-000 mounts; code that runs
  * later and caller-denied paths are read-only binds. Every writable bind and
- * protected leaf is a mount point, which Linux refuses to rename.
+ * protected leaf is a mount point, which Linux refuses to rename. A protected
+ * symlink inside a writable directory (a stow link in `~/.config`) makes that
+ * directory read-only with each existing entry bound writable again, so only
+ * new top-level entries there are refused.
  */
 function buildLinuxBroadCommand(
     bwrap: string,
@@ -1347,15 +1439,74 @@ 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>();
+    // 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;
-        if (canonicalizePath(path, seams) !== path) {
+        let link = false;
+        try { link = lstatSync(path).isSymbolicLink(); } catch { /* absent or intermediate link */ }
+        if (canonicalizePath(path, seams) !== path || (link && unresolvable(path))) {
             // A literal twin of a canonical deny entry: its target is guarded on
-            // its own. A symlink leaf inside a writable root could be replaced,
-            // so its directory becomes read-only; home itself already is.
-            let link = false;
-            try { link = lstatSync(path).isSymbolicLink(); } catch { /* absent or intermediate link */ }
-            if (link && dirname(path) !== broad.home && writableAt(dirname(path))) readOnly.add(dirname(path));
+            // its own. A looping link resolves to nothing (ELOOP), and a dangling
+            // one's missing target is guarded below, so only the link itself
+            // needs guarding here. A symlink leaf inside a writable root could be
+            // replaced, so its directory is protected; home already is.
+            if (link && dirname(path) !== broad.home && writableAt(dirname(path))) linkParents.add(dirname(path));
+            return;
+        }
+        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.
+            // 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;
+            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)) {
@@ -1384,19 +1535,37 @@ function buildLinuxBroadCommand(
     for (const path of writeDenied) guard(path, false);
     if (permissions.projectFiles === "read") readOnly.add(project);
 
+    // A read-only link parent keeps its existing entries writable: each one is
+    // bound back read-write (a mount point, so it cannot be renamed away either).
+    // Only new top-level entries in that directory are lost. Protected entries
+    // keep their own mounts, and a symlink entry is never bound: a bind follows
+    // it, and writes through it already meet its target's own mounts.
+    const rebound = new Set<string>();
+    for (const parent of linkParents) readOnly.add(parent);
+    for (const parent of linkParents) {
+        for (const entry of list(parent)) {
+            if (entry.symlink) continue;
+            const path = join(parent, entry.name);
+            if (insideProtected(path) || readOnly.has(path) || writable.has(path)) continue;
+            rebound.add(path);
+        }
+    }
+
     // Intermediate directories between a writable root and anything bound
     // inside it become mount points too, so none of them can be renamed away.
     const anchors = new Set<string>();
     for (const target of [...writableRoots, ...readOnly, ...hidden.map((entry) => entry.path)]) {
         for (const parent of protectedAncestors([target])) {
             if (writableRoots.some((root) => root !== parent && contains(root, parent)) &&
-                !readOnly.has(parent) && !writable.has(parent)) anchors.add(parent);
+                !readOnly.has(parent) && !writable.has(parent) && !rebound.has(parent)) anchors.add(parent);
         }
     }
-    type Mount = { option: "--bind" | "--ro-bind"; source: string; path: string; rank: number };
+    type Mount = { option: "--bind" | "--bind-try" | "--ro-bind"; source: string; path: string; rank: number };
     const mounts: Mount[] = [
         ...[...anchors].map((path) => ({ option: "--bind" as const, source: path, path, rank: 0 })),
         ...writableRoots.map((path) => ({ option: "--bind" as const, source: path, path, rank: 1 })),
+        // `-try`: an entry removed before a resumed launch stays read-only instead of failing it.
+        ...[...rebound].map((path) => ({ option: "--bind-try" as const, source: path, path, rank: 1 })),
         ...[...readOnly].map((path) => ({ option: "--ro-bind" as const, source: path, path, rank: 2 })),
         ...hidden.map(({ path, source }) => ({ option: "--ro-bind" as const, source, path, rank: 3 })),
     ].sort((a, b) => a.path.length - b.path.length || a.rank - b.rank);
@@ -1412,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";
@@ -71,7 +71,7 @@ const RemoteSchema = Type.Object({
 // TypeBox union, and a Null-first union reports a malformed array as "must be null".
 const IntentFields = {
   operation_id: Type.Optional(Type.Unsafe<string | null>({ anyOf: [{ type: "null" }, { type: "string" }], description: "Optional stable id (letters, digits, . _ : / -; up to 64) for one logical operation. Reuse it when you retry with a changed command, scope, or timeout: when a later task with the same operation_id succeeds, earlier failures of that operation in this session are recovered." })),
-  expected_exit_codes: Type.Optional(Type.Unsafe<number[] | null>({ anyOf: [{ type: "array", items: { type: "integer", minimum: 1, maximum: 255 }, minItems: 1, maxItems: 16 }, { type: "null" }], description: "Optional distinct non-zero exit codes that are intentional for this command (e.g. [1] for a no-match probe). Declared before launch; recorded as expected failures, not incidents needing action. Signals and timeouts are never expected." })),
+  expected_exit_codes: Type.Optional(Type.Unsafe<number[] | null>({ anyOf: [{ type: "array", items: { type: "integer", minimum: 0, maximum: 255 }, minItems: 1, maxItems: 16 }, { type: "null" }], description: "Optional distinct non-zero exit codes that are intentional for this command (e.g. [1] for a no-match probe). 0 is allowed and ignored: exit 0 is already success. Declared before launch; recorded as expected failures, not incidents needing action. Signals and timeouts are never expected." })),
 };
 
 const CommandFields = {
@@ -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