pi-better-harness 0.6.1 → 0.8.0

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

@@ -39,6 +39,14 @@ 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
+[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.
@@ -80,6 +88,23 @@ timeout can terminate the local SSH client but the remote process may still be
 running. See the detailed usage notes for bootstrap policy, watch conditions,
 timeouts, and v1 non-goals.
 
+## Reloads and session switches
+
+Tasks belong to the Pi session that started them. After `/reload`, the same
+session picks every task back up: watches keep polling, remote tmux output keeps
+being collected, and a task that finished during the reload (or exits later) gets
+its completion callback exactly once.
+
+After `/new`, `/resume`, fork, or switching to another session, the previous
+session's tasks keep running but are paused from Pi's side: watches do not poll,
+remote tmux output is not collected, and `timeout_seconds` deadlines are not
+enforced until that session is active again. An overdue deadline is enforced as
+soon as the session resumes, so a timeout can land late but is never skipped.
+While the same Pi process stays open, a local process that exits in the meantime
+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.
+
 ## Watch conditions
 
 JSON conditions require a root-prefixed path, such as `$.status` or
@@ -125,6 +150,17 @@ an explicitly configured nonzero success exit is treated as expected. Verbose
 status includes observation details and the journal path. Corrupt or unreadable
 evidence is reported as **observation incomplete**.
 
+Pass `operation_id` and `expected_exit_codes` on `bg_task_spawn`, `bg_task_watch`,
+or `bg_task` to declare intent before launch; a malformed declaration starts
+nothing. An exit code in `expected_exit_codes` (distinct integers 1-255, such as
+`[1]` for a no-match probe; a `0` is ignored) is recorded as an **Expected failure** that needs no
+action; signals and timeouts never are. When a task with an `operation_id`
+succeeds, earlier failed tasks with the same `operation_id`, kind, cwd, SSH
+target, and owner (the same session id, or for sessionless tasks the same Pi
+process) recover, so a retry with a changed command or timeout
+closes the original incident. Observation gaps are never recovered this way, and
+no command text is compared.
+
 Task failures are labeled **Action required**; the shared labels also include
 **Expected failure** and **Observation incomplete**. Unresolved running failures
 become eligible for attention after 60 seconds; observation gaps are eligible
@@ -135,6 +171,13 @@ notification delivery does not clear the failure. `callback:false` stays quiet
 while all inspection surfaces retain the evidence. Journals follow the task's
 existing retention and explicit-clear behavior.
 
+Status, log, and list count and list only failures that need action (**Action
+required** and **Observation incomplete**). Expected and closed failures are one
+history count line with no incident cursor; pass `history: true` to
+`bg_task_status` (or `action:status`) to page them. Incident rows are compact
+(120-byte excerpt, evidence such as `output.log#poll=3`); the raw log keeps the
+full evidence path.
+
 ## When To Use
 
 Use this package for shell commands that need logs, status, cancellation, or completion notifications across a Pi turn.

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.3.0",
+  "version": "0.5.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/failures.ts

@@ -1,16 +1,25 @@
 import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
-  failureAttentionHandled, failureIdentity, formatFailureSummary, markFailureAttentionDelivered,
-  observeFailures, pendingAttentionNote, pendingAttentionRows, pendingFailureAttention, readFailureState, type FailureState,
+  actionableFailures, activeFailures, failureAttentionHandled, failureIdentity, formatFailureSummary, markFailureAttentionDelivered,
+  observeFailures, pendingAttentionNote, pendingAttentionRows, pendingFailureAttention, readCommandIntent, readFailureState,
+  type FailureEvent, type FailureState,
 } from "./shared-failure-observations.js";
 import { getCallbackBatcher } from "./shared-callback-batcher.js";
-import { readMeta, taskDir } from "./registry.js";
+import { listMetasForOrigin, originOf, readMeta, taskDir } from "./registry.js";
 import type { ActiveSessionProvider } from "./runtime.js";
 import type { BackgroundTaskMeta } from "./types.js";
 
 export const failurePath = (id: string): string => join(taskDir(id), "failures.jsonl");
 export const failureSummary = (id: string): string => formatFailureSummary(readFailureState(failurePath(id)));
+/**
+ * The failure summary plus whether anything needs action. A navigator row leads with failure text
+ * only when something does; the quiet history line never displaces the command (#332).
+ */
+export function failureView(id: string): { text: string; actionable: boolean } {
+  const state = readFailureState(failurePath(id));
+  return { text: formatFailureSummary(state), actionable: actionableFailures(state).length > 0 };
+}
 
 export function recordFailure(meta: BackgroundTaskMeta, operation: string, summary: string, eventKey: unknown,
   options: { category?: string; expected?: boolean; incomplete?: boolean; evidence?: string; at?: number } = {}): void {
@@ -32,7 +41,79 @@ export function recoverFailure(meta: BackgroundTaskMeta, operation: string, even
   }]);
 }
 
+/**
+ * Validate `operation_id` / `expected_exit_codes` before anything is launched (#325), with the same
+ * validator the subagent task runtime's bash uses. Background commands are launched by the parent
+ * agent itself, so the declaration is trusted; a malformed one refuses the launch.
+ */
+export function readTaskIntent(params: { operation_id?: unknown; expected_exit_codes?: unknown }): Pick<BackgroundTaskMeta, "operationId" | "expectedExitCodes"> {
+  const { intent, error } = readCommandIntent({ operationId: params.operation_id, expectedExitCodes: params.expected_exit_codes },
+    { operationId: "operation_id", expectedExitCodes: "expected_exit_codes" });
+  if (error) throw new Error(`Invalid command intent: ${error}. The task was not started.`);
+  return { ...(intent.operationId ? { operationId: intent.operationId } : {}), ...(intent.expectedExitCodes ? { expectedExitCodes: intent.expectedExitCodes } : {}) };
+}
+
+/** A structured exit code the caller declared intentional before launch. Signals and timeouts never are. */
+export function isDeclaredExpectedExit(meta: BackgroundTaskMeta, exitCode: number | null | undefined): exitCode is number {
+  return typeof exitCode === "number" && exitCode !== 0 && (meta.expectedExitCodes ?? []).includes(exitCode);
+}
+
+/** Record a non-zero command exit, classified as expected only when its code was declared before launch. */
+export function recordExitFailure(meta: BackgroundTaskMeta, operation: string, summary: string, exitCode: number | null | undefined, eventKey: unknown,
+  options: { at?: number; expected?: boolean } = {}): void {
+  const declared = isDeclaredExpectedExit(meta, exitCode);
+  recordFailure(meta, operation, declared ? `${summary} (declared expected)` : summary, eventKey,
+    { category: "exit", expected: declared || options.expected === true, at: options.at });
+}
+
+function declaredOperation(meta: BackgroundTaskMeta): string | undefined {
+  return meta.operationId ? failureIdentity("bg-operation", meta.kind, meta.operationId, meta.cwd, meta.ssh?.target ?? null) : undefined;
+}
+
+/**
+ * Recovery crosses tasks only within one owner (#325): the same non-empty session id, or, for
+ * sessionless tasks, the same spawning process (#312's sessionless ownership rule). The origin
+ * index alone treats two sessionless sessions in one cwd as one origin.
+ */
+function sameRecoveryOwner(a: BackgroundTaskMeta, b: BackgroundTaskMeta): boolean {
+  const sa = a.callbackOrigin?.sessionId, sb = b.callbackOrigin?.sessionId;
+  if (sa || sb) return Boolean(sa) && sa === sb;
+  return a.spawnPid === b.spawnPid && a.spawnPidStartTime === b.spawnPidStartTime;
+}
+
+/**
+ * A task that succeeded with a declared `operationId` recovers the unresolved failures of earlier
+ * tasks of the same owner (session, or spawning process when sessionless) that declared the same operation (same kind, cwd, and SSH target) and
+ * failed before this task started: a modified retry as a new task. Observation gaps and expected
+ * failures are left alone; nothing is matched on command text.
+ */
+export function recoverDeclaredOperation(meta: BackgroundTaskMeta, at = Date.now()): void {
+  const operation = declaredOperation(meta);
+  if (!operation) return;
+  let earlier: BackgroundTaskMeta[];
+  try { earlier = listMetasForOrigin(originOf(meta)); } catch { return; }
+  for (const task of earlier) {
+    if (task.id === meta.id || task.startedAt >= meta.startedAt || declaredOperation(task) !== operation || !sameRecoveryOwner(task, meta)) continue;
+    const path = failurePath(task.id);
+    const events: FailureEvent[] = activeFailures(readFailureState(path))
+      .filter((x) => x.status === "unresolved" && x.category !== "observation-incomplete" && x.lastObservedAt <= meta.startedAt)
+      .map((x) => ({ id: failureIdentity(task.id, x.id, "recovered-by", meta.id), operation: x.operation, kind: "recovered", incidents: [x.id], at,
+        evidence: `task ${meta.id} (operation ${meta.operationId}) succeeded` }));
+    if (events.length) observeFailures(path, events);
+  }
+}
+
 const attentionTimers = new Map<string, ReturnType<typeof setTimeout>>();
+let attentionSuspended = false;
+/** Session shutdown: stop this instance's attention timers; the next session_start reschedules (#324). */
+export function suspendFailureAttention(): void {
+  attentionSuspended = true;
+  for (const timer of attentionTimers.values()) clearTimeout(timer);
+  attentionTimers.clear();
+}
+export function resumeFailureAttention(): void {
+  attentionSuspended = false;
+}
 export function stopFailureAttention(id: string): void {
   const timer = attentionTimers.get(id);
   if (timer) clearTimeout(timer);
@@ -65,6 +146,7 @@ export function failureAttentionFields(meta: BackgroundTaskMeta, state: FailureS
 /** Running incidents get one grace wake. Terminal incidents ride the completion callback. */
 export function scheduleFailureAttention(pi: ExtensionAPI, id: string, getActiveSession?: ActiveSessionProvider): void {
   stopFailureAttention(id);
+  if (attentionSuspended) return;
   const meta = readMeta(id);
   if (!meta) {
     const timer = setTimeout(() => scheduleFailureAttention(pi, id, getActiveSession), 1_000);

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

@@ -2,6 +2,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { disposeBackgroundWorkNavigator } from "./shared-navigator.ts";
 import { registerBackgroundTasksGoalProvider } from "./goal-provider.js";
 import { clearBackgroundTasksNavigatorSession, ensureBackgroundTasksNavigator, ensureBackgroundTasksNavigatorProvider } from "./navigator-provider.js";
+import { resumeScheduledWork, suspendScheduledWork } from "./runtime.js";
 import { observeForegroundSandboxPolicy } from "./sandbox.js";
 import { registerTools } from "./tools.js";
 
@@ -11,7 +12,9 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
   // Subscribed at load so a sandbox extension that publishes later is heard, and
   // asked for a snapshot in case one published before this extension existed.
   observeForegroundSandboxPolicy(pi);
+  // Registered before registerTools(pi), so this runs before running tasks are resumed.
   pi.on("session_start", async (_event, ctx) => {
+    resumeScheduledWork();
     registerBackgroundTasksGoalProvider(pi);
     ensureBackgroundTasksNavigator(ctx);
   });
@@ -20,6 +23,8 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
     disposeBackgroundWorkNavigator();
   });
   pi.on("session_shutdown", async (_event, ctx) => {
+    // /reload, session replacement, and quit load a fresh instance; stop this one's timers (#324).
+    suspendScheduledWork();
     clearBackgroundTasksNavigatorSession();
     disposeBackgroundWorkNavigator(ctx);
   });

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

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
+  DEFAULT_LOG_TAIL_ROWS as NAVIGATOR_DETAIL_ROWS,
   ensureBackgroundWorkNavigator,
   refreshBackgroundWorkNavigator,
   registerBackgroundWorkProvider,
@@ -9,8 +10,8 @@ import {
 } from "./shared-navigator.ts";
 import { CustomEditor } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
-import { activeFailures, failureLabel, readFailureState } from "./shared-failure-observations.js";
-import { failurePath, failureSummary } from "./failures.js";
+import { actionableFailures, failureLabel, readFailureState } from "./shared-failure-observations.js";
+import { failurePath, failureView } from "./failures.js";
 import { readLog } from "./logs.js";
 import { listMetasForOrigin, onMetaChanged, readMeta, writeMeta } from "./registry.js";
 import { stopTask } from "./runtime.js";
@@ -104,7 +105,9 @@ function isExpiredTerminalNavigatorRow(meta: BackgroundTaskMeta, now: number): b
 }
 
 function rowFromMeta(meta: BackgroundTaskMeta, now: number): BackgroundWorkRow {
-  const failure = failureSummary(meta.id);
+  // Only a failure that needs action replaces the row's command; history stays in the detail view (#332).
+  const view = failureView(meta.id);
+  const failure = view.actionable ? view.text : "";
   const elapsed = formatDuration((meta.endedAt ?? now) - meta.startedAt);
   return {
     providerId: "background-tasks",
@@ -128,8 +131,9 @@ function rowFromMeta(meta: BackgroundTaskMeta, now: number): BackgroundWorkRow {
 
 function detailFromMeta(meta: BackgroundTaskMeta | undefined, now: number, options?: { logTailLines?: number }): BackgroundWorkDetail | null {
   if (!meta) return null;
-  const failure = failureSummary(meta.id);
-  const log = readLog(meta.logPath, options?.logTailLines ?? 10);
+  const view = failureView(meta.id);
+  const failure = view.text;
+  const log = readLog(meta.logPath, options?.logTailLines ?? NAVIGATOR_DETAIL_ROWS);
   const command = commandLabel(meta);
   const metadata = [
     { label: "provider", value: "Background Tasks" },
@@ -163,7 +167,7 @@ function detailFromMeta(meta: BackgroundTaskMeta | undefined, now: number, optio
     title: meta.name || meta.id,
     status: meta.status,
     statusTone: toneForStatus(meta.status),
-    subtitle: failure ? failure.split("\n")[0]! : compactCommandLabel(meta),
+    subtitle: view.actionable ? failure.split("\n")[0]! : compactCommandLabel(meta),
     metadata,
     foldedSections: [{
       id: "command",
@@ -216,7 +220,7 @@ function secondaryLabel(meta: BackgroundTaskMeta): string | undefined {
 
 function factsForMeta(meta: BackgroundTaskMeta, now: number): string[] {
   const facts: string[] = [];
-  const incident = activeFailures(readFailureState(failurePath(meta.id)))[0];
+  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);

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

@@ -1,14 +1,21 @@
-import { statSync } from "node:fs";
 import {
-  activeFailures,
+  actionableFailures,
   failureRevision,
   formatFailureLines,
   formatFailureSummary,
   formatIncidentSummary,
+  historyTailLine,
+  incidentCursorScope,
+  incidentPageHeading,
+  incidentResource,
+  incidentVerbatimPage,
   isIncidentCursor,
-  pageFailureIncidents,
+  quietFailureLine,
   readFailureState,
+  scopedFailures,
   type FailureState,
+  type IncidentDetail,
+  type IncidentScope,
 } from "./shared-failure-observations.js";
 import {
   assemblePriorityEnvelope,
@@ -16,9 +23,11 @@ import {
   cursorKind,
   formatUnchangedEvidence,
   inspectStatusRevision,
+  lifecycleContentRevision,
   pageRows,
   pageVerbatimText,
   revisionOf,
+  sessionScopeKey,
   sliceUtf8Bytes,
   utf8ByteLength,
   OUTPUT_BUDGET_BYTES,
@@ -66,6 +75,8 @@ export interface OutputOptions {
   cursor?: string;
   maxBytes?: number;
   verbose?: boolean;
+  /** Status: return an incident page that also lists failure history (expected and closed incidents). */
+  history?: boolean;
   tailLines?: number;
   raw?: boolean;
   statuses?: string[];
@@ -112,11 +123,7 @@ function stringifyObserved(value: unknown): string {
 
 /** Cursor scope: pagination and revision cursors never cross session scopes. */
 function scopeKey(options: OutputOptions): string {
-  if (options.all) return "all";
-  if (options.sessionUnavailable) return "unavailable";
-  const origin = options.origin;
-  if (!origin) return "none";
-  return revisionOf([origin.cwd, origin.sessionId ?? ""]);
+  return sessionScopeKey({ all: options.all, unavailable: options.sessionUnavailable, origin: options.origin });
 }
 
 function taskGaps(meta: BackgroundTaskMeta): EvidenceGap[] {
@@ -143,39 +150,31 @@ function failureStateFor(id: string): FailureState {
  * incident rows when they fit, otherwise a count line (total / shown /
  * omitted) with an incident cursor that resumes at the first byte not shown.
  */
-function incidentSection(id: string, options: OutputOptions, state = failureStateFor(id)): ((budget: number) => string | undefined) | undefined {
-  if (activeFailures(state).length === 0) return undefined;
-  const resource = `incidents:${scopeKey(options)}:${id}`;
+function incidentSection(id: string, options: OutputOptions, state = failureStateFor(id), detail: IncidentDetail = "compact"): ((budget: number) => string | undefined) | undefined {
+  // Only what needs action is listed; history (expected, closed) is one count line without a cursor.
+  if (!formatIncidentSummary(state, { maxBytes: Number.MAX_SAFE_INTEGER }).text) return undefined;
+  const resource = incidentResource(scopeKey(options), id);
   return (budget) => formatIncidentSummary(state, {
     maxBytes: budget,
     resource,
     retrieval: `pass as cursor to bg_task_status id=${id}`,
+    detail,
   }).text || undefined;
 }
 
 function assembleIncidentPage(meta: BackgroundTaskMeta, options: OutputOptions): string {
   const state = failureStateFor(meta.id);
-  const resource = `incidents:${scopeKey(options)}:${meta.id}`;
-  const total = activeFailures(state).length;
+  const resource = incidentResource(scopeKey(options), meta.id);
+  const cursor = isIncidentCursor(options.cursor) ? options.cursor : undefined;
+  const scope: IncidentScope = options.history ? "all" : incidentCursorScope(cursor) ?? "actionable";
   return assembleBackgroundContent({
     surface: "status",
     maxBytes: options.maxBytes,
     sections: {
-      identity: `${identityLine(meta)} Incident page of ${total} active failure observation${total === 1 ? "" : "s"}.`,
+      identity: `${identityLine(meta)} ${incidentPageHeading(scopedFailures(state, scope).length, scope)}`,
       decision: formatDecision(meta),
     },
-    verbatim: (budget) => {
-      const page = pageFailureIncidents(state, { cursor: options.cursor, maxBytes: budget, resource });
-      return {
-        text: page.text || (page.total === 0 ? "No active failure observations." : ""),
-        hasMore: page.hasMore,
-        cursor: page.cursor,
-        nextCursor: page.nextCursor,
-        omittedBytes: 0,
-        omittedRows: page.omitted,
-        reset: page.reset,
-      };
-    },
+    verbatim: (budget) => incidentVerbatimPage(state, { cursor, scope, maxBytes: budget, resource }),
   });
 }
 
@@ -240,7 +239,10 @@ export function formatCallbackFacts(meta: BackgroundTaskMeta): {
     meta.logDiscardedBytes ? `retention discarded ${meta.logDiscardedBytes} bytes; not recoverable` : undefined,
     meta.captureDiscardedBytes ? `capture overflow discarded ${meta.captureDiscardedBytes} bytes; not full history` : undefined,
   ].filter((line): line is string => Boolean(line));
-  const decision = [formatDecision(meta), ...gapLines].filter(Boolean).join("\n") || undefined;
+  // 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.
+  const history = rows.length ? historyTailLine(state) : quietFailureLine(state);
+  const decision = [formatDecision(meta), ...gapLines, history].filter(Boolean).join("\n") || undefined;
   return {
     outcome: meta.status,
     ...(rows.length ? { failureRows: rows, incidentCount: rows.length } : {}),
@@ -284,14 +286,7 @@ function identityLine(meta: BackgroundTaskMeta): string {
 
 /** Lifecycle, result, and retained-log facts. A deleted or rewritten log is a change. */
 function contentRevision(meta: BackgroundTaskMeta): string {
-  let log: unknown;
-  try {
-    const stats = statSync(meta.logPath);
-    log = [stats.dev, stats.ino, stats.size, Math.trunc(stats.mtimeMs)];
-  } catch (error) {
-    log = ["unreadable", (error as NodeJS.ErrnoException).code ?? String(error)];
-  }
-  return revisionOf([
+  return lifecycleContentRevision([
     meta.status,
     meta.endedAt ?? null,
     meta.lastCheckedAt ?? null,
@@ -307,8 +302,7 @@ function contentRevision(meta: BackgroundTaskMeta): string {
     meta.lastState ?? null,
     meta.remote?.bootstrapStatus ?? null,
     meta.remote?.stopMessage ?? null,
-    log,
-  ]);
+  ], meta.logPath);
 }
 
 export function assembleBackgroundContent(input: {
@@ -376,14 +370,43 @@ function formatOwnershipGap(id: string, kind: "foreign" | "unknown", options: Ou
   });
 }
 
-type Ownership = "allow" | "foreign" | "unknown";
+export type Ownership = "allow" | "foreign" | "unknown";
+
+/**
+ * Refusal for a mutation (stop, clear) of a task outside the current session
+ * scope. Mutations use the same ownership rule as reads (#322): only an owned
+ * task changes; nothing about a foreign or unverifiable task is disclosed.
+ */
+export function formatMutationRefusal(
+  id: string,
+  kind: Exclude<Ownership, "allow">,
+  action: "stop" | "clear",
+  options: OutputOptions,
+): string {
+  const verb = action === "stop" ? "stopped" : "dismissed";
+  const detail = kind === "foreign"
+    ? `This task belongs to another session, so it was not ${verb}. Pass all:true to ${action} it explicitly.`
+    : options.sessionUnavailable
+      ? `The current session identity is unavailable, so ownership cannot be verified and the task was not ${verb}. Pass all:true to ${action} it explicitly.`
+      : `Task ownership is unavailable or unreadable, so the task was not ${verb}. Pass all:true to ${action} it explicitly.`;
+  return assembleBackgroundContent({
+    surface: "status",
+    maxBytes: options.maxBytes,
+    sections: {
+      identity: `Background task ${id} is outside the current session scope; not ${verb}.`,
+      diagnostics: detail,
+    },
+    gaps: [{ kind: "read", detail: kind === "foreign" ? "foreign-session" : "ownership-unavailable" }],
+  });
+}
 
 /**
- * Current-session ownership. Without a current session id, ownership is only
- * verified for a task this process launched with the same sessionless origin;
- * a legacy task with no recorded origin is never assumed to be ours.
+ * Current-session ownership, shared by reads and mutations. Without a current
+ * session id, ownership is only verified for a task this process launched with
+ * the same sessionless origin; a legacy task with no recorded origin is never
+ * assumed to be ours.
  */
-function classifyOwnership(meta: BackgroundTaskMeta, options: OutputOptions): Ownership {
+export function classifyOwnership(meta: BackgroundTaskMeta, options: OutputOptions): Ownership {
   if (options.all === true) return "allow";
   if (options.sessionUnavailable) return "unknown";
   const origin = options.origin;
@@ -517,15 +540,24 @@ export function formatStatus(
   const meta = inspectionValue.meta;
   const ownership = classifyOwnership(meta, options);
   if (ownership !== "allow") return formatOwnershipGap(meta.id, ownership, options);
-  if (isIncidentCursor(options.cursor)) return assembleIncidentPage(meta, options);
+  if (isIncidentCursor(options.cursor) || options.history) return assembleIncidentPage(meta, options);
+  // A page cursor from another view of this task continues that view instead
+  // of resetting a status revision (#323): a raw/file cursor pages the log,
+  // a text cursor pages verbose metadata.
+  const pageKind = cursorKind(options.cursor);
+  if (pageKind === "f") return formatLog(meta.id, { ...options, raw: true });
+  if (pageKind === "t") return formatVerbose(meta, options);
   if (options.verbose) return formatVerbose(meta, options);
+  // A bg_task_list page cursor pages the list, not this task: say so rather than report it as a
+  // stale status cursor (#332).
+  const listCursor = pageKind === "l";
   const state = failureStateFor(meta.id);
   const resource = `status:${scopeKey(options)}:${meta.id}`;
   const revision = inspectStatusRevision({
     resource,
     contentRevision: contentRevision(meta),
     failureRevision: failureRevision(state),
-    cursor: options.cursor,
+    cursor: listCursor ? undefined : options.cursor,
   });
   if (options.cursor && revision.change === "none") {
     return assembleBackgroundContent({
@@ -533,8 +565,8 @@ export function formatStatus(
       maxBytes: options.maxBytes,
       sections: {
         identity: `${identityLine(meta)} · unchanged`,
-        failure: activeFailures(state).length
-          ? `${activeFailures(state).length} active failure observation(s), unchanged.`
+        failure: actionableFailures(state).length
+          ? `${actionableFailures(state).length} active failure observation(s), unchanged.`
           : undefined,
         decision: formatUnchangedEvidence(options.cursor),
       },
@@ -545,6 +577,7 @@ export function formatStatus(
   // Change/reset and read-gap facts are short and decision-relevant: they are
   // budgeted with the decision section, ahead of long incident rows.
   const changeFacts = [
+    ...(listCursor ? ["cursor ignored: it is a bg_task_list page cursor; pass it to bg_task_list, or pass this status's statusCursor here."] : []),
     ...(revision.change === "failure" ? ["change=failure"] : []),
     ...(revision.reset ? [`reset=${revision.reset}`] : []),
     ...(log.error ? [`log unreadable: ${oneLine(log.error, 200)}; cannot treat this as an empty healthy log.`] : []),
@@ -576,7 +609,8 @@ export function formatLog(id: string, options: OutputOptions = {}): string {
   if (ownership !== "allow") return formatOwnershipGap(meta.id, ownership, options);
   const fileCursor = cursorKind(options.cursor) === "f";
   const raw = options.raw === true || options.tailLines === 0 || fileCursor;
-  const failure = incidentSection(id, options);
+  // Raw evidence keeps whole excerpts and evidence paths.
+  const failure = incidentSection(id, options, undefined, raw ? "full" : "compact");
   if (raw) {
     return assembleBackgroundContent({
       surface: "rawPage",
@@ -594,7 +628,7 @@ export function formatLog(id: string, options: OutputOptions = {}): string {
   }
   const tailLines = options.tailLines && options.tailLines > 0 ? Math.floor(options.tailLines) : DEFAULT_LOG_TAIL_ROWS;
   const log = readLog(meta.logPath, tailLines);
-  const staleCursor = options.cursor ? ["reset=stale-cursor (compact tails have no cursor; pass a raw nextCursor or tail_lines:0)"] : [];
+  const staleCursor = options.cursor ? ["reset=stale-cursor (compact tails have no cursor; pass a raw nextCursor or lines:0)"] : [];
   if (log.error) {
     return assembleBackgroundContent({
       surface: "log",
@@ -674,7 +708,7 @@ export function formatList(options: OutputOptions = {}): string {
   const resource = `list:${scope}:${statusesKey}`;
   const limit = Math.max(1, Math.min(Math.floor(options.limit ?? DEFAULT_LIST_ENTRIES), MAX_LIST_ENTRIES));
   const states = new Map(allowed.map((meta) => [meta.id, failureStateFor(meta.id)] as const));
-  const incidentsOf = (id: string) => activeFailures(states.get(id)!).length;
+  const incidentsOf = (id: string) => actionableFailures(states.get(id)!).length;
   const revision = inspectStatusRevision({
     resource,
     contentRevision: revisionOf(allowed.map((meta) => [meta.id, meta.status, meta.endedAt ?? null])),