pi-better-background-tasks 0.2.20 → 0.4.0

package/src/runtime.ts

@@ -8,9 +8,11 @@ import { DEFAULT_TMUX_BOOTSTRAP_TIMEOUT_MS, expandSshRemoteTaskPreset } from "./
 import type { RemoteRunner, ResolvedSshRemoteTask } from "./remote-task-preset.js";
 import { ensureTaskDir, logPathFor, nextTaskId, readMeta, sandboxProfilePathFor, writeMeta } from "./registry.js";
 import { confineCommandSpec, resolveForegroundSandboxPlan } from "./sandbox.js";
-import { failurePath, recordFailure, recoverFailure, scheduleFailureAttention, stopFailureAttention, terminalFailureAttention } from "./failures.js";
+import { takeRecoverySnapshot } from "./shared-sandbox-core.js";
+import { failurePath, readTaskIntent, recordExitFailure, recordFailure, recoverDeclaredOperation, recoverFailure, resumeFailureAttention, scheduleFailureAttention, stopFailureAttention, suspendFailureAttention, terminalFailureAttention } from "./failures.js";
 import { markFailureAttentionDelivered } from "./shared-failure-observations.js";
 import { getCallbackBatcher } from "./shared-callback-batcher.js";
+import { formatCallbackFacts } from "./output.js";
 import type {
   BackgroundTaskCallbackOrigin,
   BackgroundTaskMeta,
@@ -32,16 +34,68 @@ const remoteSessionStarts = new Map<string, Promise<CommandResult>>();
 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 HANDOFF_CHECK_MS = 250;
+const HANDOFF_LOST_GRACE_MS = 5_000;
+let scheduledWorkSuspended = false;
 const REMOTE_SESSION_POLL_MS = 100;
 
 export const DEFAULT_WATCH_TIMEOUT_SECONDS = 15 * 60;
 
+/**
+ * Stop this extension instance's scheduled work when its session shuts down (#324).
+ *
+ * Pi emits session_shutdown for /reload, /new, /resume, fork, session switch,
+ * and quit, and the next session loads a fresh extension instance. Work left in
+ * the old instance runs with no active session, so a task finishing there used to
+ * have its completion callback durably suppressed ("active session identity is
+ * unavailable") and the next session never heard about it.
+ *
+ * After suspension this instance schedules nothing and notifies nothing. Work
+ * already in flight (a child's close listener, a remote tmux bootstrap/start, a
+ * timeout kill) still records its result in metadata, but leaves the callback to
+ * the instance that resumes the task. Processes are not stopped.
+ *
+ * Resume is per callback origin: session_start resumes only tasks whose origin
+ * (cwd and session id) matches the new session. After /reload that is every task
+ * of the session. After switching to another session, the previous session's
+ * 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.
+ */
+export function suspendScheduledWork(): void {
+  scheduledWorkSuspended = true;
+  for (const timer of watcherTimers.values()) clearTimeout(timer);
+  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);
+  handoffTimers.clear();
+  watcherTimers.clear();
+  remoteSessionTimers.clear();
+  processTimeoutTimers.clear();
+  logRetentionTimers.clear();
+  suspendFailureAttention();
+}
+
+/** Allow scheduling again; called at session_start before running tasks are resumed. */
+export function resumeScheduledWork(): void {
+  scheduledWorkSuspended = false;
+  resumeFailureAttention();
+}
+
 
 
 export type ActiveSessionProvider = () => BackgroundTaskCallbackOrigin | undefined;
 
 export interface SpawnTaskParams extends CommandSpec {
   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;
   timeout_seconds?: number;
   max_log_bytes?: number;
@@ -51,6 +105,10 @@ export interface SpawnTaskParams extends CommandSpec {
 
 export interface WatchTaskParams extends CommandSpec {
   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;
@@ -77,6 +135,7 @@ export function spawnTask(
 ): BackgroundTaskMeta {
   // Resolved before any task directory, log, or metadata exists so a blocked
   // launch leaves nothing behind. Structured SSH must also honor launch restrictions.
+  const intent = readTaskIntent(params);
   const sandboxPlan = resolveForegroundSandboxPlan(pi, !!params.ssh);
   const id = nextTaskId();
   const cwd = params.cwd ?? defaultCwd;
@@ -98,11 +157,21 @@ export function spawnTask(
     ? commandSpec
     : confineCommandSpec(commandSpec, sandboxPlan, sandboxProfilePathFor(id));
   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).
+  const snapshot = !remoteTask && sandboxPlan.confined ? takeRecoverySnapshot(sandboxPlan.permissions) : undefined;
   const spawned = tmuxBacked
     ? undefined
     : remoteTask
       ? remoteTask.spawn(logPath, true)
       : spawnCommand(launchSpec, logPath, true);
+  if (snapshot?.started) {
+    void snapshot.done.then((outcome) => {
+      if (!outcome.ok) {
+        try { appendLine(logPath, `--- recovery snapshot failed (task continues): ${outcome.detail} ---`); } catch { /* log gone */ }
+      }
+    });
+  }
   const now = Date.now();
   const meta: BackgroundTaskMeta = {
     id,
@@ -129,6 +198,7 @@ export function spawnTask(
     spawnPidStartTime: currentProcessStartToken(),
     ssh: remoteTask?.metadata.ssh,
     remote: remoteTask?.metadata.remote,
+    ...intent,
   };
   writeMeta(meta);
   scheduleLogRetention(id);
@@ -145,8 +215,11 @@ export function spawnTask(
       if (!latest) return;
       enforceLogRetention(latest);
       if (isTerminalStatus(latest.status)) return;
-      if (exitCode !== 0) recordFailure(latest, "execution", `Process exited with code ${exitCode ?? "unknown"}${signal ? ` (${signal})` : ""}`, "close", { category: "exit", at: Date.now() });
-      else recoverFailure(latest, "execution", "close");
+      if (exitCode !== 0) recordExitFailure(latest, "execution", `Process exited with code ${exitCode ?? "unknown"}${signal ? ` (${signal})` : ""}`, exitCode, "close", { at: Date.now() });
+      else {
+        recoverFailure(latest, "execution", "close");
+        recoverDeclaredOperation(latest);
+      }
       latest.status = exitCode === 0 ? "succeeded" : "failed";
       latest.endedAt = Date.now();
       latest.lastExitCode = exitCode;
@@ -226,6 +299,7 @@ function scheduleRemoteSessionPoll(
   getActiveSession?: ActiveSessionProvider,
 ): void {
   clearRemoteSessionTimer(id);
+  if (scheduledWorkSuspended) return;
   const timer = setTimeout(() => void pollRemoteSession(pi, id, getActiveSession), delayMs);
   timer.unref();
   remoteSessionTimers.set(id, timer);
@@ -249,6 +323,7 @@ async function pollRemoteSession(
     const remoteTask = activeRemoteTasks.get(id);
     if (!meta || meta.status !== "running" || meta.remote?.session !== "tmux" || !remoteTask) return;
     const poll = await remoteTask.pollTmuxSession(meta.remote.logOffset ?? 0, remainingDeadlineMs(meta.deadlineAt));
+    if (scheduledWorkSuspended) return;
     appendTaskOutput(meta.logPath, poll.output);
     if (poll.status === "timed_out") {
       clearProcessTimeout(id);
@@ -279,7 +354,7 @@ async function pollRemoteSession(
     }
     const commandResult = { ...poll.commandResult, exitCode: poll.status, stdout: poll.output };
     latest.lastExitCode = poll.status;
-    if (poll.status !== 0) recordFailure(latest, "execution", `Remote command exited with code ${poll.status}`, "exit", { category: "exit" });
+    if (poll.status !== 0) recordExitFailure(latest, "execution", `Remote command exited with code ${poll.status}`, poll.status, "exit");
     else recoverFailure(latest, "execution", "exit");
     finalize(latest, {
       status: poll.status === 0 ? "succeeded" : "failed",
@@ -325,6 +400,7 @@ export function startWatchTask(
     const error = condition && validateCondition(condition);
     if (error) throw new Error(`${name}: ${error}`);
   }
+  const intent = readTaskIntent(params);
   const sandboxPlan = resolveForegroundSandboxPlan(pi, !!params.ssh);
   const id = nextTaskId();
   const cwd = params.cwd ?? defaultCwd;
@@ -370,6 +446,7 @@ export function startWatchTask(
     notifyOn: "terminal",
     ssh: remoteTask?.metadata.ssh,
     remote: remoteTask?.metadata.remote,
+    ...intent,
   };
   ensureTaskDir(id);
   appendLine(meta.logPath, `--- watch ${new Date(now).toISOString()} interval_ms=${meta.intervalMs} ---`);
@@ -398,6 +475,9 @@ export function resumeRunningTask(
   }
   scheduleFailureAttention(pi, meta.id, getActiveSession);
 
+  // Same Pi process: an earlier (reloaded or switched-away) extension instance may
+  // still hold this task's child or in-flight remote work and record its result.
+  const ownedByThisProcess = meta.spawnPid === process.pid && meta.spawnPidStartTime === currentProcessStartToken();
   if (meta.spawnPid !== process.pid || meta.spawnPidStartTime !== currentProcessStartToken()) {
     meta.spawnPid = process.pid;
     meta.spawnPidStartTime = currentProcessStartToken();
@@ -417,22 +497,86 @@ export function resumeRunningTask(
     activeRemoteTasks.set(meta.id, remoteTask);
     scheduleRemoteSessionPoll(pi, meta.id, 0, getActiveSession);
     if (meta.deadlineAt) scheduleProcessTimeout(pi, meta.id, meta.deadlineAt, getActiveSession);
+    // An earlier instance's in-flight timeout kill may still finalize it.
+    if (ownedByThisProcess) scheduleHandoff(pi, meta.id, getActiveSession);
     return meta;
   }
-  if (meta.pid && !processExists(meta.pid)) {
-    meta.status = "failed";
-    meta.endedAt = Date.now();
-    meta.error = "process is no longer alive; exit result was not captured by this pi session";
-    meta.result = { reason: meta.error };
-    recordFailure(meta, "execution", meta.error, "lost", { incomplete: true });
-    writeMeta(meta);
-    void notifyTerminal(pi, meta, getActiveSession);
+  if (ownedByThisProcess) {
+    // A dead pid is not yet "lost" here: the earlier instance's close listener may
+    // still record the real exit. The handoff marks it lost after a grace period.
+    scheduleHandoff(pi, meta.id, getActiveSession, remoteTask);
+  } else if (meta.pid && !processExists(meta.pid)) {
+    markProcessLost(pi, meta, getActiveSession);
     return meta;
   }
   if (meta.deadlineAt) scheduleProcessTimeout(pi, meta.id, meta.deadlineAt, getActiveSession);
   return meta;
 }
 
+/**
+ * Watch a task whose driver may still be an earlier instance in this process: a
+ * local child's close listener, or a remote tmux launch that was mid-bootstrap.
+ * Deliver the completion once it is recorded terminal, and take over remote
+ * polling once the tmux session is recorded as started (#324).
+ */
+function scheduleHandoff(
+  pi: ExtensionAPI,
+  id: string,
+  getActiveSession?: ActiveSessionProvider,
+  remoteTask?: ResolvedSshRemoteTask,
+): void {
+  stopHandoff(id);
+  if (scheduledWorkSuspended) return;
+  let deadSince: number | undefined;
+  const timer = setInterval(() => {
+    const meta = readMeta(id);
+    if (!meta) {
+      stopHandoff(id);
+      return;
+    }
+    if (meta.status !== "running") {
+      stopHandoff(id);
+      clearProcessTimeout(id);
+      stopLogRetention(id);
+      void notifyTerminal(pi, meta, getActiveSession);
+      return;
+    }
+    if (meta.remote?.session === "tmux" && meta.remote.sessionStarted === true && remoteTask && !activeRemoteTasks.has(id)) {
+      stopHandoff(id);
+      activeRemoteTasks.set(id, remoteTask);
+      scheduleRemoteSessionPoll(pi, id, 0, getActiveSession);
+      return;
+    }
+    if (meta.remote?.session !== "tmux" && meta.pid && !processExists(meta.pid)) {
+      deadSince ??= Date.now();
+      if (Date.now() - deadSince >= HANDOFF_LOST_GRACE_MS) {
+        stopHandoff(id);
+        clearProcessTimeout(id);
+        stopLogRetention(id);
+        markProcessLost(pi, meta, getActiveSession);
+      }
+    }
+  }, HANDOFF_CHECK_MS);
+  timer.unref();
+  handoffTimers.set(id, timer);
+}
+
+function stopHandoff(id: string): void {
+  const timer = handoffTimers.get(id);
+  if (timer) clearInterval(timer);
+  handoffTimers.delete(id);
+}
+
+function markProcessLost(pi: ExtensionAPI, meta: BackgroundTaskMeta, getActiveSession?: ActiveSessionProvider): void {
+  meta.status = "failed";
+  meta.endedAt = Date.now();
+  meta.error = "process is no longer alive; exit result was not captured by this pi session";
+  meta.result = { reason: meta.error };
+  recordFailure(meta, "execution", meta.error, "lost", { incomplete: true });
+  writeMeta(meta);
+  void notifyTerminal(pi, meta, getActiveSession);
+}
+
 function resolvePersistedRemoteTask(
   meta: BackgroundTaskMeta,
   remoteRunner?: RemoteRunner,
@@ -487,9 +631,7 @@ export async function stopTask(
   if (remoteSessionMayExist) {
     const remoteTask = activeRemoteTasks.get(id);
     if (!remoteTask) {
-      meta.stopRequestedAt = undefined;
-      meta.error = `Cannot stop remote tmux session ${remote.sessionName}: its active SSH controller is unavailable.`;
-      writeMeta(meta);
+      recordStopError(meta, `Cannot stop remote tmux session ${remote.sessionName}: its active SSH controller is unavailable.`);
       scheduleRemoteSessionPoll(pi, id, REMOTE_SESSION_POLL_MS, getActiveSession);
       return meta;
     }
@@ -497,18 +639,14 @@ export async function stopTask(
       const stopped = await remoteTask.killTmuxSession();
       if (stopped.exitCode !== 0) {
         const detail = stopped.stderr.trim() || stopped.stdout.trim() || "remote tmux returned no diagnostic";
-        meta.stopRequestedAt = undefined;
-        meta.error = `Could not kill remote tmux session ${remote.sessionName} on ${meta.ssh?.target} (exit ${stopped.exitCode ?? "unknown"}): ${detail}`;
-        writeMeta(meta);
+        recordStopError(meta, `Could not kill remote tmux session ${remote.sessionName} on ${meta.ssh?.target} (exit ${stopped.exitCode ?? "unknown"}): ${detail}`);
         scheduleRemoteSessionPoll(pi, id, REMOTE_SESSION_POLL_MS, getActiveSession);
         return meta;
       }
       remote.stopMessage = `Killed remote tmux session ${remote.sessionName} on ${meta.ssh?.target}.`;
       appendLine(meta.logPath, `--- ${remote.stopMessage} ---`);
     } catch (error) {
-      meta.stopRequestedAt = undefined;
-      meta.error = error instanceof Error ? error.message : String(error);
-      writeMeta(meta);
+      recordStopError(meta, error instanceof Error ? error.message : String(error));
       scheduleRemoteSessionPoll(pi, id, REMOTE_SESSION_POLL_MS, getActiveSession);
       return meta;
     }
@@ -516,9 +654,7 @@ export async function stopTask(
     try {
       stopProcessGroup(meta.pid, meta.pgid);
     } catch (error) {
-      meta.stopRequestedAt = undefined;
-      meta.error = error instanceof Error ? error.message : String(error);
-      writeMeta(meta);
+      recordStopError(meta, error instanceof Error ? error.message : String(error));
       if (meta.deadlineAt && meta.deadlineAt > Date.now()) {
         scheduleProcessTimeout(pi, id, meta.deadlineAt, getActiveSession);
       }
@@ -528,6 +664,7 @@ export async function stopTask(
 
   stopFailureAttention(id);
   meta.status = "cancelled";
+  meta.stopError = undefined;
   meta.endedAt = Date.now();
   meta.result = {
     reason: meta.remote?.session === "direct"
@@ -541,6 +678,13 @@ export async function stopTask(
   return meta;
 }
 
+function recordStopError(meta: BackgroundTaskMeta, message: string): void {
+  meta.stopRequestedAt = undefined;
+  meta.stopError = message;
+  meta.error = message;
+  writeMeta(meta);
+}
+
 function scheduleWatch(
   pi: ExtensionAPI,
   id: string,
@@ -549,6 +693,7 @@ function scheduleWatch(
   runOnce?: WatchPollRunner,
 ): void {
   clearWatchTimer(id);
+  if (scheduledWorkSuspended) return;
   const timer = setTimeout(() => void pollWatch(pi, id, getActiveSession, runOnce), delayMs);
   timer.unref();
   watcherTimers.set(id, timer);
@@ -580,9 +725,12 @@ async function pollWatch(
     const result = runOnce
       ? await runOnce(timeoutMs)
       : await runCommandOnce(commandSpecFromMeta(meta), undefined, timeoutMs);
+    // A poll that was in flight when the session shut down belongs to a stale instance.
+    if (scheduledWorkSuspended) return;
     appendWatchResult(meta.logPath, result);
     const latest = readMeta(id);
     if (!latest || latest.status !== "running") return;
+    applyCaptureOverflow(latest, result);
     enforceLogRetention(latest);
     latest.lastCheckedAt = Date.now();
     latest.lastProgressAt = latest.lastCheckedAt;
@@ -602,8 +750,8 @@ async function pollWatch(
       const error = condition && validateCondition(condition);
       if (error) {
         latest.error = `${name}: ${error}`;
-        if (result.exitCode !== 0) recordFailure(latest, "watch-poll", `Watch poll exited with code ${result.exitCode ?? "unknown"}`, pollKey,
-          { category: "exit", at: result.endedAt });
+        if (result.exitCode !== 0) recordExitFailure(latest, "watch-poll", `Watch poll exited with code ${result.exitCode ?? "unknown"}`, result.exitCode, pollKey,
+          { at: result.endedAt });
         recordFailure(latest, name, latest.error, pollKey, { incomplete: true, at: result.endedAt });
         finalize(latest, { status: "failed", reason: latest.error, commandResult: result }, pi, getActiveSession);
         return;
@@ -626,13 +774,19 @@ async function pollWatch(
       success?.matched === true && latest.successWhen?.type === "exit_code";
     if (expectedPollExit) recoverFailure(latest, "watch-poll", pollKey, result.endedAt);
     if (transportFailure) recordFailure(latest, "watch-poll", transportFailure, pollKey, { category: "ssh", at: result.endedAt });
-    else if (result.exitCode !== 0) recordFailure(latest, "watch-poll", `Watch poll exited with code ${result.exitCode ?? "unknown"}`, pollKey,
-      { category: "exit", expected: expectedPollExit, at: result.endedAt });
+    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);
     if (conditionErrors.length) latest.error = conditionErrors.join("; ");
     if (failure?.matched) {
       recordFailure(latest, "failure_when", "failure condition matched", pollKey, { category: "condition", at: result.endedAt });
-      finalize(latest, { status: "failed", reason: "failure condition matched", matchedCondition: latest.failureWhen, commandResult: result }, pi, getActiveSession);
+      finalize(latest, {
+        status: "failed",
+        reason: "failure condition matched",
+        matchedCondition: latest.failureWhen,
+        matchedValue: failure.value,
+        commandResult: result,
+      }, pi, getActiveSession);
       return;
     }
     if (transportFailure) {
@@ -647,7 +801,13 @@ async function pollWatch(
       return;
     }
     if (success?.matched) {
-      finalize(latest, { status: "succeeded", reason: "success condition matched", matchedCondition: latest.successWhen, commandResult: result }, pi, getActiveSession);
+      finalize(latest, {
+        status: "succeeded",
+        reason: "success condition matched",
+        matchedCondition: latest.successWhen,
+        matchedValue: success.value,
+        commandResult: result,
+      }, pi, getActiveSession);
       return;
     }
     writeMeta(latest);
@@ -678,15 +838,18 @@ function finalize(
 ): void {
   stopFailureAttention(meta.id);
   if (terminal.status === "timed_out") recordFailure(meta, "timeout", terminal.reason, "deadline", { category: "timeout" });
+  if (terminal.status === "succeeded") recoverDeclaredOperation(meta);
   meta.status = terminal.status;
   meta.endedAt = Date.now();
   meta.result = {
     reason: terminal.reason,
     matchedCondition: terminal.matchedCondition,
+    matchedValue: terminal.matchedValue,
     exitCode: terminal.commandResult?.exitCode,
     signal: terminal.commandResult?.signal,
   };
   if (terminal.commandResult) {
+    applyCaptureOverflow(meta, terminal.commandResult);
     meta.lastExitCode = terminal.commandResult.exitCode;
     meta.lastSignal = terminal.commandResult.signal;
     meta.lastCheckedAt = terminal.commandResult.endedAt;
@@ -734,6 +897,7 @@ function scheduleProcessTimeout(
   getActiveSession?: ActiveSessionProvider,
 ): void {
   clearProcessTimeout(id);
+  if (scheduledWorkSuspended) return;
   const delay = Math.max(0, deadlineAt - Date.now());
   const timer = setTimeout(() => void timeoutProcess(pi, id, getActiveSession), delay);
   timer.unref();
@@ -799,8 +963,8 @@ async function finalizeProcessTimeout(
         stopProcessGroup(meta.pid, meta.pgid);
       } catch (error) {
         reason = `timeout; could not terminate local process tree: ${readableError(error)}`;
-        meta.error = reason;
-        writeMeta(meta);
+        // The task is still running: this is a stop failure, reported as such.
+        recordStopError(meta, reason);
         return;
       }
     }
@@ -823,6 +987,9 @@ async function notifyTerminal(
   meta: BackgroundTaskMeta,
   getActiveSession?: ActiveSessionProvider,
 ): Promise<void> {
+  // A suspended instance has no active session: delivering or suppressing here would
+  // be wrong either way. The instance that resumes the task delivers it (#324).
+  if (scheduledWorkSuspended) return;
   if (meta.callback === false || meta.callbackSentAt || meta.callbackSuppressedAt) return;
   const latest = readMeta(meta.id) ?? meta;
   if (latest.callback === false || latest.callbackSentAt || latest.callbackSuppressedAt) return;
@@ -837,12 +1004,21 @@ async function notifyTerminal(
   }
   const pending = terminalFailureAttention(latest.id);
   const label = latest.name ? `${latest.name} (${latest.id})` : latest.id;
+  const facts = formatCallbackFacts(latest);
   getCallbackBatcher(pi).enqueue({
     source: "background-task",
     id: latest.id,
     label,
-    status: pending ? `${latest.status}: ${pending.summary}` : latest.status,
+    // Lifecycle plus an attention count; the incident text rides failureRows
+    // with exact counts, so the status field is never a clipped summary (#323).
+    status: pending
+      ? `${latest.status}; ${pending.incidents.length} incident${pending.incidents.length === 1 ? "" : "s"} need${pending.incidents.length === 1 ? "s" : ""} attention`
+      : latest.status,
     detailTool: "bg_task_status",
+    outcome: facts.outcome,
+    failureRows: facts.failureRows,
+    decision: facts.decision,
+    incidentCount: facts.incidentCount,
     callback: true,
     isDelivered: () => {
       const current = readMeta(latest.id);
@@ -918,6 +1094,7 @@ function launchArgvOf(commandSpec: CommandSpec, launchSpec: CommandSpec): string
 
 function scheduleLogRetention(id: string): void {
   stopLogRetention(id);
+  if (scheduledWorkSuspended) return;
   const timer = setInterval(() => {
     const meta = readMeta(id);
     if (!meta || meta.status !== "running" || meta.kind !== "process") {
@@ -950,9 +1127,27 @@ function enforceLogRetention(meta: BackgroundTaskMeta): void {
   if (!compacted) return;
   meta.logDiscardedBytes = (meta.logDiscardedBytes ?? 0) + compacted.discardedBytes;
   meta.logRetentionEvents = (meta.logRetentionEvents ?? 0) + 1;
+  meta.logGeneration = (meta.logGeneration ?? 0) + 1;
   writeMeta(meta);
 }
 
+/** Results whose capture loss is already counted; one poll result is counted once. */
+const countedCaptureResults = new WeakSet<CommandResult>();
+
+function applyCaptureOverflow(meta: BackgroundTaskMeta, result: CommandResult): void {
+  const stdout = result.stdoutDiscardedBytes ?? 0;
+  const stderr = result.stderrDiscardedBytes ?? 0;
+  if (!result.captureTruncated && stdout === 0 && stderr === 0) return;
+  // pollWatch counts a result before evaluating conditions, and finalize sees
+  // the same result again when that poll ends the watch.
+  if (countedCaptureResults.has(result)) return;
+  countedCaptureResults.add(result);
+  meta.stdoutDiscardedBytes = (meta.stdoutDiscardedBytes ?? 0) + stdout;
+  meta.stderrDiscardedBytes = (meta.stderrDiscardedBytes ?? 0) + stderr;
+  meta.captureDiscardedBytes = (meta.captureDiscardedBytes ?? 0) + stdout + stderr;
+  meta.captureOverflowEvents = (meta.captureOverflowEvents ?? 0) + 1;
+}
+
 function extractLastState(result: { stdout: string }): unknown {
   try {
     return JSON.parse(result.stdout);

package/src/sandbox.ts

@@ -32,8 +32,9 @@ import { baseDir } from "./registry.js";
 import { compileWritePolicy, maybeBuildSandboxCommand, type SandboxSeams } from "./shared-sandbox-core.js";
 
 type SandboxPermissions = {
-  projectFiles: "off" | "read" | "read-write";
-  outsideProject: "off" | "read" | "read-write";
+  /** `write` = read, create and overwrite in place; `read-write` = Write & delete. */
+  projectFiles: "off" | "read" | "write" | "read-write";
+  outsideProject: "off" | "read" | "write" | "read-write";
   storedCredentials: "off" | "read" | "read-write";
   commands: boolean;
   network: boolean;
@@ -160,10 +161,11 @@ function readPolicy(data: unknown): ForegroundSandboxPolicy | undefined {
 function readPermissions(value: unknown): ForegroundSandboxPolicy["permissions"] | undefined {
   if (!value || typeof value !== "object") return undefined;
   const p = value as Record<string, unknown>;
-  const access = (v: unknown) => v === "off" || v === "read" || v === "read-write";
+  const credential = (v: unknown) => v === "off" || v === "read" || v === "read-write";
+  const access = (v: unknown) => credential(v) || v === "write";
   if (typeof p.enabled !== "boolean" || typeof p.commands !== "boolean" ||
       typeof p.network !== "boolean" || !access(p.projectFiles) ||
-      !access(p.outsideProject) || !access(p.storedCredentials)) return undefined;
+      !access(p.outsideProject) || !credential(p.storedCredentials)) return undefined;
   return Object.freeze({
     enabled: p.enabled, commands: p.commands, network: p.network,
     projectFiles: p.projectFiles as SandboxPermissions["projectFiles"],