pi-better-background-tasks 0.4.0 → 0.6.0

package/src/runtime.ts

@@ -19,6 +19,7 @@ import type {
   CommandResult,
   CommandSpec,
   Condition,
+  FirstWatchCheck,
   RemoteTaskParams,
   SshConnectionParams,
   TerminalResult,
@@ -31,16 +32,78 @@ 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;
-const handoffTimers = new Map<string, ReturnType<typeof setInterval>>();
+const handoffTimers = new Map<string, ReturnType<typeof setTimeout>>();
+// The handoff check backs off from 250 ms to 4 s while the task keeps running,
+// and returns to 250 ms once its process is gone so the grace period is timed closely.
 const HANDOFF_CHECK_MS = 250;
+const HANDOFF_MAX_CHECK_MS = 4_000;
 const HANDOFF_LOST_GRACE_MS = 5_000;
 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).
@@ -62,8 +125,9 @@ export const DEFAULT_WATCH_TIMEOUT_SECONDS = 15 * 60;
  * tasks keep running, but their watches do not poll, remote tmux output is not
  * collected, and their `timeout_seconds` deadlines are not enforced until that
  * session is active again; an overdue deadline is enforced immediately on resume.
- * A local process that exits meanwhile is recorded as terminal and its callback
- * is delivered when its session resumes.
+ * A local process that exits meanwhile, while this Pi process is still running,
+ * is recorded as terminal and its callback is delivered when its session resumes;
+ * after Pi quits, a resumed task whose process is gone is marked lost instead.
  */
 export function suspendScheduledWork(): void {
   scheduledWorkSuspended = true;
@@ -71,12 +135,14 @@ export function suspendScheduledWork(): void {
   for (const timer of remoteSessionTimers.values()) clearTimeout(timer);
   for (const timer of processTimeoutTimers.values()) clearTimeout(timer);
   for (const timer of logRetentionTimers.values()) clearInterval(timer);
-  for (const timer of handoffTimers.values()) clearInterval(timer);
+  for (const timer of handoffTimers.values()) clearTimeout(timer);
   handoffTimers.clear();
   watcherTimers.clear();
   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();
 }
 
@@ -90,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;
@@ -103,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;
 }
@@ -153,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).
@@ -165,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) {
@@ -272,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}`;
@@ -292,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,
@@ -400,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();
@@ -417,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,
@@ -443,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,
@@ -450,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;
@@ -528,7 +636,9 @@ function scheduleHandoff(
   stopHandoff(id);
   if (scheduledWorkSuspended) return;
   let deadSince: number | undefined;
-  const timer = setInterval(() => {
+  let delayMs = HANDOFF_CHECK_MS;
+  const check = () => {
+    handoffTimers.delete(id);
     const meta = readMeta(id);
     if (!meta) {
       stopHandoff(id);
@@ -554,16 +664,26 @@ function scheduleHandoff(
         clearProcessTimeout(id);
         stopLogRetention(id);
         markProcessLost(pi, meta, getActiveSession);
+        return;
       }
+      delayMs = HANDOFF_CHECK_MS;
+    } else {
+      delayMs = Math.min(HANDOFF_MAX_CHECK_MS, delayMs * 2);
     }
-  }, HANDOFF_CHECK_MS);
-  timer.unref();
-  handoffTimers.set(id, timer);
+    arm();
+  };
+  const arm = () => {
+    if (scheduledWorkSuspended) return;
+    const timer = setTimeout(check, delayMs);
+    timer.unref();
+    handoffTimers.set(id, timer);
+  };
+  arm();
 }
 
 function stopHandoff(id: string): void {
   const timer = handoffTimers.get(id);
-  if (timer) clearInterval(timer);
+  if (timer) clearTimeout(timer);
   handoffTimers.delete(id);
 }
 
@@ -625,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) {
@@ -713,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;
@@ -725,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);
@@ -777,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 });
@@ -824,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. */
@@ -104,24 +105,60 @@ export interface CommandIntent {
 export type CommandIntentField = keyof CommandIntent;
 const INTENT_FIELDS: readonly CommandIntentField[] = ["operationId", "attemptId", "expectedExitCodes"];
 /**
- * The one normalization of intent-bearing arguments: an explicit `null` intent field means
- * "not declared", exactly like an omitted one. Models routinely send optional fields as null, and
- * Pi's argument validation (0.87+) drops optional nulls before a tool runs, while the process log
- * and session record keep the raw arguments. Every reader of intent, the executing tool and the
- * replay alike, goes through this so both sides see the same declaration from the same input.
+ * Pi's own argument coercion for the intent fields (pi-ai `validateToolArguments` against the confined
+ * bash schema, where each field is `anyOf: [field schema, null]`). Pi applies it before execute, but the
+ * process log and session record keep the raw arguments; mirroring it lets the parent's replay read
+ * the declaration the child executed with (#332).
+ * - ids: a number or boolean becomes its string; `""` fails the pattern and falls through to null.
+ * - exit codes: array items that read as integers become integers (null -> 0, true -> 1);
+ *   a scalar `0`, `""`, or `false` falls through to null.
+ */
+function coerceInteger(value: unknown): unknown {
+  if (value === null) return 0;
+  if (typeof value === "string" && value.trim() !== "" && Number.isInteger(Number(value))) return Number(value);
+  if (typeof value === "boolean") return value ? 1 : 0;
+  return value;
+}
+function normalizeIntentField(key: CommandIntentField, value: unknown): unknown {
+  if (value == null) return undefined;
+  if (key === "expectedExitCodes") {
+    if (value === 0 || value === "" || value === false) return undefined;
+    if (!Array.isArray(value)) return value;
+    // 0 is a no-op declaration: exit 0 is already success. A list of only zeros declares nothing.
+    const codes = value.map(coerceInteger).filter((code) => code !== 0);
+    if (codes.length === 0 && value.length > 0) return undefined;
+    return codes.length === value.length && codes.every((code, index) => code === value[index]) ? value : codes;
+  }
+  if (value === "") return undefined;
+  return typeof value === "number" || typeof value === "boolean" ? String(value) : value;
+}
+/**
+ * The one normalization of intent-bearing arguments. An explicit `null` intent field means "not
+ * declared", exactly like an omitted one: models routinely send optional fields as null, and Pi's
+ * argument validation drops or nulls them before a tool runs, while the process log and session
+ * record keep the raw arguments. Values Pi would coerce are coerced the same way, and `0` is dropped
+ * from `expectedExitCodes`. Every reader of intent, the executing tool and the replay alike, and the
+ * exact operation identity go through this, so all see the same declaration from the same input.
+ * Malformed values are kept as they are for the validator to refuse.
  */
 export function withoutAbsentIntent<T>(args: T): T {
   if (!args || typeof args !== "object" || Array.isArray(args)) return args;
   const input = args as Record<string, unknown>;
-  if (!INTENT_FIELDS.some((key) => key in input && input[key] == null)) return args;
-  const out = { ...input };
-  for (const key of INTENT_FIELDS) if (key in out && out[key] == null) delete out[key];
-  return out as T;
+  let out: Record<string, unknown> | undefined;
+  for (const key of INTENT_FIELDS) {
+    if (!(key in input)) continue;
+    const value = normalizeIntentField(key, input[key]);
+    if (value === input[key]) continue;
+    out ??= { ...input };
+    if (value === undefined) delete out[key];
+    else out[key] = value;
+  }
+  return (out ?? args) as T;
 }
 /**
- * Validate structured intent fields. Absent fields (omitted, undefined, or null) are fine; malformed
+ * Validate structured intent fields after `withoutAbsentIntent`. Absent fields are fine; malformed
  * ones are an error, and the caller must not run the command. `names` renames fields in the error
- * (e.g. snake_case parameters).
+ * (e.g. snake_case parameters). `0` in `expectedExitCodes` is accepted and dropped (#332).
  */
 export function readCommandIntent(args: unknown, names: Partial<Record<CommandIntentField, string>> = {}): { intent: CommandIntent; error?: string } {
   const input = withoutAbsentIntent((args && typeof args === "object" ? args : {}) as Record<string, unknown>);
@@ -138,7 +175,7 @@ export function readCommandIntent(args: unknown, names: Partial<Record<CommandIn
   if (codes !== undefined) {
     if (!Array.isArray(codes) || codes.length === 0 || codes.length > MAX_EXPECTED_EXIT_CODES ||
       !codes.every((code) => Number.isInteger(code) && code >= 1 && code <= 255) || new Set(codes).size !== codes.length) {
-      return { intent: {}, error: `${names.expectedExitCodes ?? "expectedExitCodes"} must be 1-${MAX_EXPECTED_EXIT_CODES} distinct integers from 1 to 255` };
+      return { intent: {}, error: `${names.expectedExitCodes ?? "expectedExitCodes"} must be 1-${MAX_EXPECTED_EXIT_CODES} distinct integers from 1 to 255 (0 is allowed and ignored)` };
     }
     intent.expectedExitCodes = [...codes] as number[];
   }
@@ -481,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,
@@ -494,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);
@@ -607,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.
@@ -725,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 {
@@ -867,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-log-utils.ts

@@ -819,29 +819,22 @@ export interface OutputControls {
   maxBytes?: unknown;
   /** Raw requested line count (canonical `lines`, else deprecated `tail_lines`). */
   lines?: unknown;
-  /** Deprecated alias names the caller used (whether or not the canonical name won). */
-  deprecated: string[];
 }
 
 /**
  * Resolve output-control parameters. Both spellings work; when both are given
- * the canonical name wins. Values are returned unvalidated so each surface
- * keeps its own defaults and hard caps.
+ * the canonical name wins. An explicit `null` is "not given", so a null
+ * canonical value never hides an alias value (#332). Values are returned
+ * unvalidated so each surface keeps its own defaults and hard caps.
  */
 export function readOutputControls(params: unknown): OutputControls {
   const p = (params && typeof params === "object" ? params : {}) as Record<string, unknown>;
-  const deprecated: string[] = [];
-  const pick = (canonical: keyof typeof OUTPUT_CONTROL_ALIASES): unknown => {
-    const alias = OUTPUT_CONTROL_ALIASES[canonical];
-    if (p[alias] !== undefined) deprecated.push(alias);
-    return p[canonical] !== undefined ? p[canonical] : p[alias];
-  };
+  const pick = (canonical: keyof typeof OUTPUT_CONTROL_ALIASES): unknown => p[canonical] ?? p[OUTPUT_CONTROL_ALIASES[canonical]] ?? undefined;
   const maxBytes = pick("max_bytes");
   const lines = pick("lines");
   return {
     ...(maxBytes !== undefined ? { maxBytes } : {}),
     ...(lines !== undefined ? { lines } : {}),
-    deprecated,
   };
 }
 
@@ -851,7 +844,8 @@ export type OutputInclude = (typeof OUTPUT_INCLUDE_VALUES)[number];
 
 /** Parse an `include` request into known values and unknown ones (both deduplicated). */
 export function readOutputInclude(value: unknown): { include: Set<OutputInclude>; unknown: string[] } {
-  const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
+  // Any other non-null value (a number, boolean, or object) is one unknown entry, never silently nothing (#332).
+  const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : value == null ? [] : [value];
   const include = new Set<OutputInclude>();
   const unknown: string[] = [];
   for (const entry of raw) {