pi-better-harness 0.31.1 → 0.32.0

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

@@ -17,47 +17,45 @@ Use `pi-better-background-tasks` when a command should keep running while the fo
 - Keep task metadata and logs available across reloads.
 - Retain completed task artifacts for seven days, then remove them during rate-limited maintenance.
 - Show active work in Pi's background-work navigator.
-- Flag running tasks with no observable output or completed poll as stalled.
+- Report quiet work and suspected stalls separately from task lifecycle.
 - Confine local task writes to the project directory when `pi-better-sandbox` is enabled.
 
 ## Write Sandbox
 
 When [`pi-better-sandbox`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-sandbox#readme)
-is installed and enabled, every **local** task captures
-the effective foreground policy at launch and runs under the platform's write
-sandbox: reads and network stay unrestricted, writes are confined to the
-canonical project directory, and denied paths stay denied.
-
-The policy is captured once, when the task starts. The foreground sandbox is
-inactive by default, so local tasks ordinarily launch unconfined. A later
-`/sandbox on`, `/sandbox off`, `/sandbox default on|off`, or a deny-rule change
-reaches tasks launched after it; a task
-already running — including a watcher resumed in a later Pi session — keeps the
-policy it started with.
-
-If the foreground sandbox reports `unavailable` or `failed`, a local launch is
-refused with an explanation instead of running unconfined. `/sandbox off` is the
-deliberate way to run local tasks unsandboxed.
-
-A task follows Main's permission profile. With Main's Outside project = Write, the
-task writes across home and temp but can remove files outside the project only in
-temp, hidden home directories, and worktree folders (see
+is installed, local tasks follow the independent **Background tasks** column in
+`/sandbox`. Its Sandbox switch starts Off for fresh settings. When enabled,
+commands run under macOS Seatbelt or Linux Bubblewrap with that column's project,
+outside-project, credential-file, command and network permissions. Protected
+paths remain denied.
+
+The policy is captured once at launch. Later settings changes affect only new
+tasks. An existing process, including a watcher resumed in a later Pi session,
+keeps its launch policy. `/sandbox on|off` and `/sandbox default on|off` now
+change Main only; use the Background tasks column to change new task launches.
+Older settings migrate by copying Main's values into Background tasks once.
+
+If the Background policy is `unavailable` or `failed`, launch is refused rather
+than retried unconfined. Turning its Sandbox switch Off deliberately permits
+unconfined local launches.
+
+With Background tasks' Outside project = Write, the task can write across home
+and temp but can remove files outside the project only in temp, hidden home
+directories, and worktree folders (see
 [pi-better-sandbox](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-sandbox#readme)).
-On macOS, a task launched with Outside project = Write or Write & delete starts an
-APFS local snapshot (`tmutil localsnapshot`) in the background as a recovery aid.
-A failed snapshot is noted in the task log and never blocks the task.
-
-Structured remote SSH tasks are unaffected: the foreground sandbox describes this
-machine, and remote work keeps its existing remote semantics. Without
-`pi-better-sandbox` installed, local tasks behave exactly as they always have.
-
-Reads and network access are never restricted; only writes are. Pi's own
-process, `pi.exec` calls, and unrelated third-party extension code stay outside
-the guarantee, and confinement is per surface: a confined process on another
-first-party surface can still write this one's task registry. Installing
-[`pi-better-harness`](https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-harness#readme)
-installs the sandbox extension, but leaves foreground tools and local background
-tasks inactive until a human opts in.
+On macOS, Outside project = Write or Write & delete starts an APFS local snapshot
+(`tmutil localsnapshot`) as a recovery aid. A failed snapshot is noted in the log
+and never blocks execution.
+
+Structured SSH cannot apply local file and credential permissions remotely, so
+an enabled permission-aware Background profile refuses those launches. When
+unconfined, SSH retains its documented remote behavior; local policy never
+establishes remote confinement. Without the sandbox extension, local tasks
+retain their historical unconfined behavior.
+
+Pi's own process, provider transport, `pi.exec` calls, and unrelated runtime
+extensions remain outside the task boundary. Installing the harness does not
+activate Main or Background confinement by default.
 
 ## Remote SSH
 
@@ -105,6 +103,61 @@ is recorded as finished, and its callback is delivered when its session resumes.
 If you quit Pi first, nothing records that exit: when the session is resumed in a
 new Pi process, a task whose process is gone is marked lost.
 
+## Progress And Suspected Stalls
+
+A task can remain `running` without recent progress evidence. Compact status and
+navigator use the same observation. Process tasks use recorded progress and the
+log's modification time. Watches use recorded progress and completed polls. Before
+any progress, the task's launch time anchors the silence duration. This does not
+measure CPU activity, network waits, or useful application work.
+
+At 60 seconds without observed progress, work is `quiet`. At 5 minutes, it has a
+`suspected stall`. Both thresholds are inclusive. Set `PI_BETTER_STALL_QUIET_MS`
+and `PI_BETTER_STALL_MS` to positive millisecond durations to override them.
+Compact status shows the last observed time, silence duration, and a warning:
+silence alone does not prove the task is hung. Terminal tasks are not reported as
+suspected stalls. New output or a completed watch poll refreshes the observation.
+
+A status cursor changes when the observation crosses either threshold, even if
+metadata and log bytes have not changed. Within the same observation state,
+unchanged status still shows the current silence duration. A suspected stall
+records an observation, not a process failure. After the existing 60-second
+attention grace, callback-enabled tasks wake the parent once per silent spell.
+New progress closes the observation and a later spell can notify again. Quiet
+work does not alert, `callback:false` suppresses notification, and no silence
+threshold stops a task or changes its lifecycle. The active session's runtime
+checks observations once per second, including an in-flight watch poll. Reload
+restores monitoring and the persisted attention receipts. Log-retention writes
+are excluded from task progress.
+
+## Launch Policy And Diagnostics
+
+`/sandbox` has an independent **Background tasks** column. New tasks capture
+that column at launch; subsequent changes do not alter an existing process or
+its future watch polls. Older saved settings copy Main into Background tasks
+once so the migration preserves behavior. Older sandbox publishers without the
+Background field retain their Main-policy behavior.
+
+Launch and status show `confined`, `unconfined`, or `unknown`, plus the backend
+when known and the policy source. `verbose:true` includes the persisted policy
+summary. Restored tasks without recorded launch evidence report `unknown`;
+missing profile files or current process-tool denials are not confinement proof.
+Remote execution also reports unknown remote confinement.
+
+Use `bg_task_status` with `diagnostics:true` (or either wrapper's `status`
+action) for a bounded, current process snapshot. Both Main and Background tasks
+must currently permit **Process access: Read**, even when sandbox switches are
+Off. The result checks the recorded PID and start identity, then reports process
+state, accumulated CPU time, and available wait evidence. It never reads command
+arguments or environment values and never probes a remote host or descendants.
+A snapshot cannot establish useful work or a hang. Watch poll PIDs are not
+retained, so their activity evidence is explicitly unavailable.
+
+The process-activity adapter is unavailable under Main confinement; it never
+retries `ps` unconfined. Unsupported systems, absent launch identities, reused
+PIDs, and blocked diagnostics each receive a separate explanation. Diagnostics
+permissions do not change or describe the task's launch-time confinement.
+
 ## Watch conditions
 
 JSON conditions require a root-prefixed path, such as `$.status` or

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",

package/node_modules/pi-better-background-tasks/src/adapter-contract.ts

@@ -0,0 +1,55 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { inspectMeta } from "./registry.js";
+
+/** Optional-peer contract, mirrored by pi-better-sandbox/background-admission.ts. */
+export const BACKGROUND_ADAPTER_REQUEST = "pi-better-background-tasks:adapter-request";
+export const BACKGROUND_ADAPTER_VERSION = 1;
+
+type Admission = "local-launch" | "registry";
+type Request = {
+  version: number;
+  name: string;
+  input: unknown;
+  reply(value: { version: number; parameters: object; admission: Admission }): void;
+};
+
+/** The schemas belong to one registerTools invocation, never to a module singleton. */
+export function advertiseBackgroundAdapter(pi: ExtensionAPI, schemas: ReadonlyMap<string, object>): void {
+  const unsubscribe = pi.events?.on(BACKGROUND_ADAPTER_REQUEST, (data: unknown) => {
+    const request = data as Partial<Request> | undefined;
+    if (request?.version !== BACKGROUND_ADAPTER_VERSION || typeof request.name !== "string" ||
+        typeof request.reply !== "function") return;
+    const parameters = schemas.get(request.name);
+    if (!parameters) return;
+    const admission = classify(request.name, request.input);
+    if (admission) request.reply({ version: BACKGROUND_ADAPTER_VERSION, parameters, admission });
+  });
+  pi.on("session_shutdown", () => { if (typeof unsubscribe === "function") unsubscribe(); });
+}
+
+function classify(name: string, input: unknown): Admission | undefined {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return;
+  const params = input as Record<string, unknown>;
+  let action: unknown;
+  switch (name) {
+    case "bg_task_spawn": action = "spawn"; break;
+    case "bg_task_watch": action = "watch"; break;
+    case "bg_task_list": action = "list"; break;
+    case "bg_task_status": action = "status"; break;
+    case "bg_task_log": action = "log"; break;
+    case "bg_task_stop": action = "stop"; break;
+    case "bg_task": action = params.action; break;
+    case "bg_status":
+      if (params.action === "spawn" || params.action === "watch") return;
+      action = params.action;
+      break;
+    default: return;
+  }
+  if (action === "spawn" || action === "watch") return params.ssh ? undefined : "local-launch";
+  if (action === "list" || action === "status" || action === "log" || action === "clear") return "registry";
+  if (action !== "stop" || typeof params.id !== "string" || !params.id) return;
+  // Never trust caller flags about locality. Missing/corrupt metadata is not proof
+  // of a local stop; a remote stop can execute SSH in the trusted Pi process.
+  const meta = inspectMeta(params.id).meta;
+  if (meta && !meta.ssh && !meta.remote && (meta.kind === "process" || meta.kind === "command_watch")) return "registry";
+}

package/node_modules/pi-better-background-tasks/src/navigator-provider.ts

@@ -15,7 +15,7 @@ import { failurePath, failureView } from "./failures.js";
 import { readLog } from "./logs.js";
 import { listMetasForOrigin, onMetaChanged, readMeta, writeMeta } from "./registry.js";
 import { stopTask } from "./runtime.js";
-import { observeBackgroundTaskStall } from "./stall.js";
+import { formatBackgroundTaskStall, observeBackgroundTaskStall } from "./stall.js";
 import type { BackgroundTaskCallbackOrigin, BackgroundTaskMeta, BackgroundTaskStatus } from "./types.js";
 
 let unregister: (() => void) | undefined;
@@ -152,8 +152,8 @@ function detailFromMeta(meta: BackgroundTaskMeta | undefined, now: number, optio
   if (meta.deadlineAt) metadata.push({ label: "deadline", value: formatDuration(meta.deadlineAt - now) });
   if (meta.lastCheckedAt) metadata.push({ label: "checked", value: `${formatDuration(now - meta.lastCheckedAt)} ago` });
   if (meta.status === "running") {
-    const stall = observeBackgroundTaskStall(meta, now);
-    if (stall.state !== "healthy") metadata.push({ label: "activity", value: stall.state });
+    const activity = formatBackgroundTaskStall(observeBackgroundTaskStall(meta, now));
+    if (activity) metadata.push({ label: "activity", value: activity });
   }
   if (meta.lastExitCode !== undefined) metadata.push({ label: "exit", value: String(meta.lastExitCode) });
   if (meta.error) metadata.push({ label: "error", value: meta.error });
@@ -223,9 +223,8 @@ function factsForMeta(meta: BackgroundTaskMeta, now: number): string[] {
   const incident = actionableFailures(readFailureState(failurePath(meta.id)))[0];
   if (incident) facts.push(`${failureLabel(incident)}: ${incident.summary}`);
   if (meta.status === "running") {
-    const stall = observeBackgroundTaskStall(meta, now);
-    if (stall.state === "stalled") facts.push("stalled");
-    else if (stall.state === "quiet") facts.push("quiet");
+    const activity = formatBackgroundTaskStall(observeBackgroundTaskStall(meta, now));
+    if (activity) facts.push(activity);
   }
   if (meta.kind === "command_watch" && meta.intervalMs) facts.push(`every ${formatDuration(meta.intervalMs)}`);
   if (meta.deadlineAt && meta.status === "running") facts.push(`${formatDuration(meta.deadlineAt - now)} left`);

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

@@ -10,8 +10,11 @@ import {
   incidentResource,
   incidentVerbatimPage,
   isIncidentCursor,
+  pendingAttentionNote,
+  pendingFailureAttention,
   quietFailureLine,
   readFailureState,
+  terminalFailureParts,
   scopedFailures,
   type FailureState,
   type IncidentDetail,
@@ -40,6 +43,9 @@ import {
 import { failurePath } from "./failures.js";
 import { captureGapsFor, pageTaskLog, readLog, type LogRead } from "./logs.js";
 import { belongsToOrigin, inspectMeta, listTaskRecords, originOf, type MetaInspection } from "./registry.js";
+import { formatBackgroundTaskStall, observeBackgroundTaskStall } from "./stall.js";
+import type { TaskProcessDiagnostics } from "./task-diagnostics.js";
+import type { StallObservation } from "./shared-stall-detector.js";
 import type { BackgroundTaskCallbackOrigin, BackgroundTaskMeta, Condition, FirstWatchCheck } from "./types.js";
 
 /** The launch tool stopped waiting while a watch's first check was still running (#359). */
@@ -75,6 +81,7 @@ const LIST_LEAD_PREVIEW_BYTES = 200;
 export type BackgroundOutputSurface = keyof typeof BACKGROUND_OUTPUT_BUDGET_BYTES;
 
 export interface OutputOptions {
+  processDiagnostics?: TaskProcessDiagnostics;
   cursor?: string;
   maxBytes?: number;
   verbose?: boolean;
@@ -237,7 +244,9 @@ export function formatCallbackFacts(meta: BackgroundTaskMeta): {
   incidentCount?: number;
 } {
   const state = failureStateFor(meta.id);
-  const rows = formatFailureLines(state);
+  const pending = pendingFailureAttention(state, Date.now(), { terminal: true });
+  const incidents = pending?.incidents ?? [];
+  const rows = terminalFailureParts(state, incidents).rows;
   const gapLines = [
     meta.logDiscardedBytes ? `retention discarded ${meta.logDiscardedBytes} bytes; not recoverable` : undefined,
     meta.captureDiscardedBytes ? `capture overflow discarded ${meta.captureDiscardedBytes} bytes; not full history` : undefined,
@@ -245,8 +254,8 @@ export function formatCallbackFacts(meta: BackgroundTaskMeta): {
   // History (expected and closed incidents) is not a row, but the callback still says it exists, so a
   // declared expected exit is not read as a plain failure. It leads the decision: a tight callback
   // budget keeps a prefix of the decision, and this short line must survive it (#332).
-  const history = rows.length ? historyTailLine(state) : quietFailureLine(state);
-  const decision = [history, formatDecision(meta), ...gapLines].filter(Boolean).join("\n") || undefined;
+  const history = actionableFailures(state).length ? historyTailLine(state) : quietFailureLine(state);
+  const decision = [history, pendingAttentionNote(state, incidents), formatDecision(meta), ...gapLines].filter(Boolean).join("\n") || undefined;
   return {
     outcome: meta.status,
     ...(rows.length ? { failureRows: rows, incidentCount: rows.length } : {}),
@@ -271,6 +280,28 @@ function formatDiagnostics(meta: BackgroundTaskMeta, extra: string[] = []): stri
   return lines.length ? lines.join("\n") : undefined;
 }
 
+function formatProcessDiagnostics(diagnostics: TaskProcessDiagnostics | undefined): string | undefined {
+  if (!diagnostics) return undefined;
+  const facts = diagnostics.availability === "available" && diagnostics.identity === "matches"
+    ? `identity matches; state=${diagnostics.state}; CPU=${diagnostics.cpuTime}; wait=${diagnostics.waitChannel}`
+    : diagnostics.reason ?? diagnostics.availability;
+  return `process diagnostics: ${facts}\nA snapshot cannot prove useful work or a hang.`;
+}
+
+function formatLaunchSandbox(meta: BackgroundTaskMeta): string | undefined {
+  const sandbox = meta.sandbox;
+  if (!sandbox) return "sandbox: unknown; launch-time policy was not recorded.";
+  const backend = sandbox.backend ? `; ${oneLine(sandbox.backend, 40)}` : "";
+  return `sandbox: ${sandbox.confinement}${backend}; source: ${oneLine(sandbox.policySource, 80)}; later changes do not affect this task.`;
+}
+
+function formatStaleProgress(stall: StallObservation | undefined): string | undefined {
+  if (!stall) return undefined;
+  const summary = formatBackgroundTaskStall(stall);
+  if (!summary) return undefined;
+  return `progress: ${summary}; last observed: ${new Date(stall.observedAt!).toISOString()}.\nSilence alone does not prove the task is hung.`;
+}
+
 function formatProgress(meta: BackgroundTaskMeta): string | undefined {
   const lines = [`kind: ${meta.kind}`];
   if (meta.name) lines.push(`name: ${oneLine(meta.name, 80)}`);
@@ -289,8 +320,10 @@ function identityLine(meta: BackgroundTaskMeta): string {
 }
 
 /** Lifecycle, result, and retained-log facts. A deleted or rewritten log is a change. */
-function contentRevision(meta: BackgroundTaskMeta): string {
+function contentRevision(meta: BackgroundTaskMeta, stall?: StallObservation): string {
   return lifecycleContentRevision([
+    stall ? [stall.state, stall.observedAt ?? null] : null,
+    meta.sandbox ?? null,
     meta.status,
     meta.endedAt ?? null,
     meta.lastCheckedAt ?? null,
@@ -460,7 +493,7 @@ export function formatLaunch(meta: BackgroundTaskMeta, firstCheck?: FirstWatchCh
       identity: `Started background ${meta.kind} ${label}. Status: ${meta.status}.`,
       failure: incidentSection(meta.id, {}),
       decision: formatDecision(meta),
-      diagnostics: [...remoteLines, ...(checkText ? [checkText] : [])].join("\n") || undefined,
+      diagnostics: [formatLaunchSandbox(meta), ...remoteLines, ...(checkText ? [checkText] : [])].filter(Boolean).join("\n") || undefined,
       progress: withLog ? logLine : undefined,
     },
     gaps: taskGaps(meta),
@@ -520,7 +553,11 @@ export function formatFirstWatchCheck(meta: BackgroundTaskMeta, check: FirstWatc
     ...(keptOut.length ? [`stdout tail:\n${keptOut.map((line) => `  ${line}`).join("\n")}`] : []),
     ...(keptEmptyStdout ? ["stdout: (empty)"] : []),
   ].join("\n");
-  const fits = () => utf8ByteLength(render()) <= maxBytes;
+  const omissionNote = () => {
+    const omitted = (stderr.length - keptErr.length) + (stdout.length - keptOut.length);
+    return omitted > 0 ? `(${omitted} output line${omitted === 1 ? "" : "s"} omitted; see bg_task_log)` : undefined;
+  };
+  const fits = () => utf8ByteLength([render(), omissionNote()].filter(Boolean).join("\n")) <= maxBytes;
   // Newest first within each stream; each kept line goes in front to stay in order.
   for (const line of [...stderr].reverse()) {
     keptErr.unshift(line);
@@ -534,21 +571,17 @@ export function formatFirstWatchCheck(meta: BackgroundTaskMeta, check: FirstWatc
     keptEmptyStdout = true;
     if (!fits()) keptEmptyStdout = false;
   }
-  const omitted = (stderr.length - keptErr.length) + (stdout.length - keptOut.length);
-  if (omitted > 0) {
-    const note = `(${omitted} output line${omitted === 1 ? "" : "s"} omitted; see bg_task_log)`;
-    const text = `${render()}\n${note}`;
-    if (utf8ByteLength(text) <= maxBytes) return text;
-  }
-  return render();
+  return [render(), omissionNote()].filter(Boolean).join("\n");
 }
 
-function redactedVerbose(meta: BackgroundTaskMeta): unknown {
+function redactedVerbose(meta: BackgroundTaskMeta, options: OutputOptions): unknown {
   const { env, ...rest } = meta;
   const state = failureStateFor(meta.id);
   const observations = Object.values(state.observations);
   const body = {
     ...rest,
+    sandbox: meta.sandbox ?? { confinement: "unknown", policySummary: "Launch-time policy was not recorded." },
+    ...(options.processDiagnostics ? { processDiagnostics: options.processDiagnostics } : {}),
     ...(env ? { env: { omitted: true, keyCount: Object.keys(env).length } } : {}),
   };
   if (!observations.length) return body;
@@ -569,16 +602,20 @@ function redactedVerbose(meta: BackgroundTaskMeta): unknown {
  * with a caller cursor like any other retained evidence.
  */
 function formatVerbose(meta: BackgroundTaskMeta, options: OutputOptions): string {
-  const json = JSON.stringify(redactedVerbose(meta), null, 2);
+  const json = JSON.stringify(redactedVerbose(meta, options), null, 2);
   const resource = `verbose:${scopeKey(options)}:${meta.id}`;
   if (!options.cursor && utf8ByteLength(json) <= backgroundBudget("rawPage", options.maxBytes)) return json;
+  // Live process samples are not part of the paged document: CPU/state changes
+  // must not invalidate continuation, even when diagnostics is omitted next time.
+  const stableJson = JSON.stringify(redactedVerbose(meta, { ...options, processDiagnostics: undefined }), null, 2);
   return assembleBackgroundContent({
     surface: "rawPage",
     maxBytes: options.maxBytes,
     sections: {
       identity: `Background task ${meta.id} metadata (environment values omitted).`,
+      diagnostics: formatProcessDiagnostics(options.processDiagnostics),
     },
-    verbatim: (budget) => pageVerbatimText(json, { cursor: options.cursor, maxBytes: budget, resource }),
+    verbatim: (budget) => pageVerbatimText(stableJson, { cursor: options.cursor, maxBytes: budget, resource }),
   });
 }
 
@@ -641,10 +678,13 @@ export function formatStatus(
   // stale status cursor (#332).
   const listCursor = pageKind === "l";
   const state = failureStateFor(meta.id);
+  const stall = meta.status === "running" ? observeBackgroundTaskStall(meta) : undefined;
+  const staleProgress = formatStaleProgress(stall);
+  const sandbox = formatLaunchSandbox(meta);
   const resource = `status:${scopeKey(options)}:${meta.id}`;
   const revision = inspectStatusRevision({
     resource,
-    contentRevision: contentRevision(meta),
+    contentRevision: contentRevision(meta, stall),
     failureRevision: failureRevision(state),
     cursor: listCursor ? undefined : options.cursor,
   });
@@ -657,7 +697,8 @@ export function formatStatus(
         failure: actionableFailures(state).length
           ? `${actionableFailures(state).length} active failure observation(s), unchanged.`
           : undefined,
-        decision: formatUnchangedEvidence(options.cursor),
+        decision: [staleProgress, formatUnchangedEvidence(options.cursor)].filter(Boolean).join("\n"),
+        diagnostics: sandbox,
       },
       statusCursor: revision.nextCursor,
     });
@@ -677,8 +718,8 @@ export function formatStatus(
     sections: {
       identity: identityLine(meta),
       failure: incidentSection(meta.id, options, state),
-      decision: [...changeFacts, formatDecision(meta)].filter(Boolean).join("\n") || undefined,
-      diagnostics: formatDiagnostics(meta),
+      decision: [...changeFacts, formatDecision(meta), staleProgress].filter(Boolean).join("\n") || undefined,
+      diagnostics: formatDiagnostics(meta, [formatProcessDiagnostics(options.processDiagnostics), sandbox].filter((line): line is string => !!line)),
       progress: formatProgress(meta),
     },
     verbatim: log.error ? undefined : (budget) => excerptPage(meta, options, log, budget),

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

@@ -7,7 +7,7 @@ import { currentProcessStartToken, readProcessStartToken } from "./process-ident
 import { DEFAULT_TMUX_BOOTSTRAP_TIMEOUT_MS, expandSshRemoteTaskPreset } from "./remote-task-preset.js";
 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 { confineCommandSpec, resolveForegroundSandboxPlan, sandboxProvenance } from "./sandbox.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";
@@ -24,6 +24,7 @@ import type {
   SshConnectionParams,
   TerminalResult,
 } from "./types.js";
+import { observeTaskStallAttention } from "./stall-attention.js";
 import { isTerminalStatus } from "./types.js";
 
 const watcherTimers = new Map<string, ReturnType<typeof setTimeout>>();
@@ -262,6 +263,7 @@ export function spawnTask(
     cwd,
     env: params.env,
     launchArgv: launchArgvOf(commandSpec, launchSpec),
+    sandbox: sandboxProvenance(sandboxPlan, !!remoteTask),
     maxLogBytes: resolveMaxLogBytes(params.max_log_bytes),
     pid: spawned?.child.pid,
     pidStartTime: spawned?.child.pid ? readProcessStartToken(spawned.child.pid) : undefined,
@@ -273,7 +275,7 @@ export function spawnTask(
     ...intent,
   };
   writeMeta(meta);
-  scheduleLogRetention(id);
+  scheduleLogRetention(pi, id, getActiveSession);
   if (tmuxBacked && remoteTask) {
     activeRemoteTasks.set(id, remoteTask);
     appendLine(logPath, `--- remote tmux bootstrap ${new Date(now).toISOString()} target=${remoteTask.metadata.ssh.target} session=${remoteTask.metadata.remote.sessionName} ---`);
@@ -533,6 +535,7 @@ export function startWatchTask(
     cwd,
     env: params.env,
     launchArgv: launchArgvOf(commandSpec, launchSpec),
+    sandbox: sandboxProvenance(sandboxPlan, !!remoteTask),
     maxLogBytes: resolveMaxLogBytes(params.max_log_bytes),
     spawnPid: process.pid,
     spawnPidStartTime: currentProcessStartToken(),
@@ -548,6 +551,7 @@ export function startWatchTask(
   appendLine(meta.logPath, `--- watch ${new Date(now).toISOString()} interval_ms=${meta.intervalMs} ---`);
   for (const line of sandboxNotices) appendLine(meta.logPath, `--- ${line} ---`);
   writeMeta(meta);
+  scheduleLogRetention(pi, meta.id, getActiveSession);
   let resolveFirst!: (check: FirstWatchCheck | "suspended" | undefined) => void;
   const firstCheck = new Promise<FirstWatchCheck | "suspended" | undefined>((resolve) => { resolveFirst = resolve; });
   firstCheckWaiters.set(id, { promise: firstCheck, resolve: resolveFirst });
@@ -592,6 +596,7 @@ export function resumeRunningTask(
     writeMeta(meta);
   }
 
+  scheduleLogRetention(pi, meta.id, getActiveSession);
   const remoteTask = resolvePersistedRemoteTask(meta, dependencies.remoteRunner);
   if (meta.kind === "command_watch") {
     scheduleWatch(pi, meta.id, 0, getActiveSession, remoteTask
@@ -600,7 +605,6 @@ export function resumeRunningTask(
     return meta;
   }
 
-  scheduleLogRetention(meta.id);
   if (meta.remote?.session === "tmux" && meta.remote.sessionStarted !== false && remoteTask) {
     activeRemoteTasks.set(meta.id, remoteTask);
     scheduleRemoteSessionPoll(pi, meta.id, 0, getActiveSession);
@@ -1155,6 +1159,7 @@ async function notifyTerminal(
   meta: BackgroundTaskMeta,
   getActiveSession?: ActiveSessionProvider,
 ): Promise<void> {
+  observeTaskStallAttention(readMeta(meta.id) ?? meta);
   // 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;
@@ -1260,16 +1265,17 @@ function launchArgvOf(commandSpec: CommandSpec, launchSpec: CommandSpec): string
   return launchSpec === commandSpec ? undefined : launchSpec.argv;
 }
 
-function scheduleLogRetention(id: string): void {
+function scheduleLogRetention(pi: ExtensionAPI, id: string, getActiveSession?: ActiveSessionProvider): void {
   stopLogRetention(id);
   if (scheduledWorkSuspended) return;
   const timer = setInterval(() => {
     const meta = readMeta(id);
-    if (!meta || meta.status !== "running" || meta.kind !== "process") {
+    if (!meta || meta.status !== "running") {
       stopLogRetention(id);
       return;
     }
-    enforceLogRetention(meta);
+    if (meta.kind === "process") enforceLogRetention(meta);
+    if (observeTaskStallAttention(meta)) scheduleFailureAttention(pi, id, getActiveSession);
   }, LOG_RETENTION_CHECK_MS);
   timer.unref();
   logRetentionTimers.set(id, timer);
@@ -1283,8 +1289,10 @@ function stopLogRetention(id: string): void {
 
 function enforceLogRetention(meta: BackgroundTaskMeta): void {
   try {
-    const mtimeMs = Math.trunc(statSync(meta.logPath).mtimeMs);
-    if (mtimeMs > (meta.lastProgressAt ?? meta.startedAt)) {
+    const log = statSync(meta.logPath);
+    const mtimeMs = Math.trunc(log.mtimeMs);
+    const maintenance = meta.logMaintenance?.mtimeMs === mtimeMs && meta.logMaintenance.size === log.size;
+    if (!maintenance && mtimeMs > (meta.lastProgressAt ?? meta.startedAt)) {
       meta.lastProgressAt = mtimeMs;
       writeMeta(meta);
     }
@@ -1296,6 +1304,10 @@ function enforceLogRetention(meta: BackgroundTaskMeta): void {
   meta.logDiscardedBytes = (meta.logDiscardedBytes ?? 0) + compacted.discardedBytes;
   meta.logRetentionEvents = (meta.logRetentionEvents ?? 0) + 1;
   meta.logGeneration = (meta.logGeneration ?? 0) + 1;
+  try {
+    const log = statSync(meta.logPath);
+    meta.logMaintenance = { mtimeMs: Math.trunc(log.mtimeMs), size: log.size };
+  } catch { /* Missing log remains an evidence gap. */ }
   writeMeta(meta);
 }