pi-better-background-tasks 0.3.0 → 0.4.0

package/src/shared-failure-observations.ts

@@ -1,5 +1,5 @@
 // Generated from packages/failure-observations/index.ts. Do not edit directly.
-import { appendFileSync, closeSync, existsSync, openSync, readFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, closeSync, existsSync, openSync, readFileSync, mkdirSync, statSync } from "node:fs";
 import { dirname } from "node:path";
 import { createHash } from "node:crypto";
 
@@ -85,6 +85,66 @@ export const REJECTED_INTENT_CATEGORY = "rejected-intent";
 /** The same unresolved agent tool operation failing this many times is treated as stuck. */
 export const REPEATED_FAILURE_THRESHOLD = 3;
 
+/** Caller-chosen intent identifiers: short, printable, no whitespace. */
+export const INTENT_ID_PATTERN = "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,63}$";
+const INTENT_ID = new RegExp(INTENT_ID_PATTERN);
+export const MAX_EXPECTED_EXIT_CODES = 16;
+/**
+ * Structured command intent (#315), declared by the caller before a command runs. Shared by the
+ * subagent task runtime's bash and background tasks (#325) so both validate identically.
+ */
+export interface CommandIntent {
+  /** Stable across caller-declared modified retries of one logical operation. */
+  operationId?: string;
+  /** Names one concrete execution; evidence identity, never an operation match. */
+  attemptId?: string;
+  /** Non-zero exit codes declared intentional before execution. */
+  expectedExitCodes?: number[];
+}
+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.
+ */
+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;
+}
+/**
+ * Validate structured intent fields. Absent fields (omitted, undefined, or null) 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).
+ */
+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>);
+  const intent: CommandIntent = {};
+  for (const key of ["operationId", "attemptId"] as const) {
+    const value = input[key];
+    if (value === undefined) continue;
+    if (typeof value !== "string" || !INTENT_ID.test(value)) {
+      return { intent: {}, error: `${names[key] ?? key} must match ${INTENT_ID_PATTERN}` };
+    }
+    intent[key] = value;
+  }
+  const codes = input.expectedExitCodes;
+  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` };
+    }
+    intent.expectedExitCodes = [...codes] as number[];
+  }
+  return { intent };
+}
+
 /** The one current incident with this id, if it is still in the reduced state. */
 export function findIncident(state: FailureState, id: string): FailureObservation | undefined {
   return Object.values(state.observations).find((item) => item.id === id);
@@ -109,6 +169,25 @@ export function failureLabel(x: FailureObservation): string {
   return requiresAction(x) ? "Action required" : "Unclassified failure observation";
 }
 
+/**
+ * Whether an incident needs someone's action now: an unresolved `Action required` incident
+ * (non-tool failure, repeated tool failure, or disposed `open`) or an observation gap. Unclassified
+ * and expected failures are history: counted on every surface, listed only on explicit request.
+ */
+export function needsAction(x: FailureObservation): boolean {
+  return x.status === "unresolved" && (x.category === "observation-incomplete" || requiresAction(x));
+}
+
+/**
+ * Which incidents a surface lists. `actionable` (the default everywhere) is what needs action;
+ * `all` is the explicit history view: every incident ever reduced, actionable first, then unclassified,
+ * expected, and closed (recovered/superseded) incidents.
+ */
+export type IncidentScope = "actionable" | "all";
+/** `compact` rows (the default) unwrap tool-result JSON, cap the excerpt, and shorten evidence paths; `full` keeps them. */
+export type IncidentDetail = "compact" | "full";
+export interface IncidentRowOptions { scope?: IncidentScope; detail?: IncidentDetail }
+
 /** Validate a disposition against the reduced state. Returns the rejection reason, or undefined. */
 export function validateDisposition(state: FailureState, event: FailureEvent): string | undefined {
   if (event.kind !== "disposition") return "Not a disposition event";
@@ -195,6 +274,20 @@ export function activeFailures(state: FailureState): FailureObservation[] {
   return Object.values(state.observations).filter((x) => x.status !== "resolved" && x.status !== "superseded")
     .sort((a, b) => priority(a) - priority(b) || (b.lastSequence ?? 0) - (a.lastSequence ?? 0) || b.lastObservedAt - a.lastObservedAt);
 }
+/** Incidents that need action now, priority order. */
+export function actionableFailures(state: FailureState): FailureObservation[] {
+  return activeFailures(state).filter(needsAction);
+}
+function closedOrder(a: FailureObservation, b: FailureObservation): number {
+  return (b.lastSequence ?? 0) - (a.lastSequence ?? 0) || b.lastObservedAt - a.lastObservedAt;
+}
+/** The incidents a scope lists, in the order rows render. */
+export function scopedFailures(state: FailureState, scope: IncidentScope = "actionable"): FailureObservation[] {
+  if (scope !== "all") return actionableFailures(state);
+  const active = activeFailures(state);
+  const closed = failureHistory(state).filter((x) => x.status === "resolved" || x.status === "superseded").sort(closedOrder);
+  return [...active, ...closed];
+}
 /** Every incident ever reduced, current and closed. Nothing is removed. */
 export function failureHistory(state: FailureState): FailureObservation[] {
   return [...Object.values(state.history ?? {}), ...Object.values(state.observations)];
@@ -220,18 +313,120 @@ export function failureCounts(state: FailureState): FailureCounts {
   }
   return counts;
 }
+function plural(count: number, one: string, many = `${one}s`): string {
+  return `${count} ${count === 1 ? one : many}`;
+}
+/**
+ * Counts of incidents that do not need action, as one short fragment, or undefined when there are
+ * none: e.g. `8 unclassified tool errors · 2 expected · 1 recovered`.
+ */
+export function historyCountsText(state: FailureState): string | undefined {
+  const counts = failureCounts(state);
+  const parts = [
+    counts.unclassified ? plural(counts.unclassified, "unclassified tool error") : "",
+    counts.expected ? `${counts.expected} expected` : "",
+    counts.recovered ? `${counts.recovered} recovered` : "",
+    counts.superseded ? `${counts.superseded} superseded` : "",
+  ].filter(Boolean);
+  return parts.length ? parts.join(" · ") : undefined;
+}
+/** One line for a run where nothing needs action but history exists. No cursor: history is explicit. */
+export function quietFailureLine(state: FailureState): string | undefined {
+  if (actionableFailures(state).length) return undefined;
+  const counts = failureCounts(state);
+  // Closed incidents alone are not worth a line on every surface; they ride along with current ones.
+  if (!counts.unclassified && !counts.expected) return undefined;
+  const history = historyCountsText(state);
+  return history ? `No failures need action · ${history} (history)` : undefined;
+}
+/** Trailing history count after actionable rows, or undefined when there is none. */
+export function historyTailLine(state: FailureState): string | undefined {
+  const history = historyCountsText(state);
+  return history ? `Also in history: ${history}` : undefined;
+}
+
 const INCIDENT_CURSOR_PREFIX = "i1.";
 const encoder = new TextEncoder();
 
-function failureRow(x: FailureObservation): string {
+/** Longest summary or disposition-reason excerpt a compact row shows, in UTF-8 bytes. */
+export const COMPACT_EXCERPT_BYTES = 120;
+const TOOL_RESULT_WRAPPER = /\{"content":\[\{"type":"text","text":"/;
+const JSON_ESCAPES: Record<string, string> = { '"': '"', "\\": "\\", "/": "/", b: " ", f: " ", n: " ", r: " ", t: " " };
+
+/** Remove unpaired UTF-16 surrogates, which would otherwise encode as U+FFFD. */
+function dropLoneSurrogates(value: string): string {
+  return value.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "");
+}
+
+/**
+ * A tool error recorded as its raw result JSON (`{"content":[{"type":"text","text":"…"}]}`, often
+ * already cut mid-string) rendered as the text it carries. Decoding is tolerant of the cut; text
+ * before the wrapper (e.g. `read failed: `) is kept.
+ */
+export function unwrapToolResultText(value: string): string {
+  const match = TOOL_RESULT_WRAPPER.exec(value);
+  if (!match) return value;
+  let out = "";
+  let i = match.index + match[0].length;
+  while (i < value.length) {
+    const ch = value[i]!;
+    if (ch === '"') break;
+    if (ch !== "\\") { out += ch; i += 1; continue; }
+    const next = value[i + 1];
+    if (next === "u") {
+      const hex = value.slice(i + 2, i + 6);
+      if (!/^[0-9a-fA-F]{4}$/.test(hex)) break;
+      out += String.fromCharCode(parseInt(hex, 16));
+      i += 6;
+      continue;
+    }
+    if (next === undefined || !(next in JSON_ESCAPES)) break;
+    out += JSON_ESCAPES[next];
+    i += 2;
+  }
+  // A wrapper cut inside a surrogate pair, or an escape of one half, leaves a lone surrogate
+  // (rendered as U+FFFD); decoded control characters (e.g. an escaped NUL) are not shown either.
+  const decoded = dropLoneSurrogates(out).replace(/[\x00-\x1f\x7f]/g, " ");
+  return `${value.slice(0, match.index)}${decoded}`.replace(/\s+/g, " ").trim();
+}
+
+/** At most `max` UTF-8 bytes of `value`, whole code points, ending in `…` when cut. */
+export function capUtf8(value: string, max: number): string {
+  const bytes = encoder.encode(value);
+  if (bytes.length <= max) return value;
+  const ellipsis = "…";
+  const cut = utf8Prefix(bytes, Math.max(0, max - utf8Length(ellipsis)));
+  return `${Buffer.from(bytes.subarray(0, cut)).toString("utf8").trimEnd()}${ellipsis}`;
+}
+
+/**
+ * Evidence reference as a compact row shows it: an absolute path loses its directories
+ * (`/private/var/…/runs/<id>/output.log#byte=N` → `output.log#byte=N`); the run or task id already
+ * names the log. Full rows and the journal keep the whole reference.
+ */
+export function shortEvidence(evidence: string): string {
+  const match = /^(?:[A-Za-z]:)?[\\/](?:[^#]*[\\/])?([^\\/#]+)(#.*)?$/.exec(evidence);
+  return match ? `${match[1]}${match[2] ?? ""}` : evidence;
+}
+
+function failureRow(x: FailureObservation, detail: IncidentDetail = "compact"): string {
   const time = x.at === undefined ? `observed ${new Date(x.firstObservedAt).toISOString()}` : new Date(x.at).toISOString();
-  const disposition = x.disposition ? ` · ${x.disposition.disposition}: ${text(x.disposition.reason, "")}` : "";
-  return `${failureLabel(x)} · ${time} · ${x.summary}${x.count > 1 ? ` (${x.count} occurrences)` : ""}${disposition}${x.evidence ? ` · evidence: ${text(x.evidence, "")}` : ""}`;
+  const compact = detail !== "full";
+  // Full rows (raw evidence) show the journal summary verbatim; compact rows unwrap and cap it.
+  const summary = compact ? capUtf8(dropLoneSurrogates(unwrapToolResultText(x.summary)).replace(/\s+/g, " ").trim(), COMPACT_EXCERPT_BYTES) : x.summary;
+  const reason = x.disposition ? text(x.disposition.reason, "") : "";
+  const disposition = x.disposition ? ` · ${x.disposition.disposition}: ${compact ? capUtf8(reason, COMPACT_EXCERPT_BYTES) : reason}` : "";
+  const evidence = x.evidence ? text(x.evidence, "") : "";
+  return `${failureLabel(x)} · ${time} · ${summary}${x.count > 1 ? ` (${x.count} occurrences)` : ""}${disposition}${evidence ? ` · evidence: ${compact ? shortEvidence(evidence) : evidence}` : ""}`;
 }
 
-/** Every active incident as a priority row. Consumers page these; they are not a lossy summary. */
-export function formatFailureLines(state: FailureState): string[] {
-  return activeFailures(state).map(failureRow);
+/**
+ * Incident rows in priority order. By default, only incidents that need action, as compact rows;
+ * `scope: "all"` lists history too and `detail: "full"` keeps whole excerpts and evidence paths.
+ * Consumers page these; they are not a lossy summary.
+ */
+export function formatFailureLines(state: FailureState, options: IncidentRowOptions = {}): string[] {
+  return scopedFailures(state, options.scope).map((x) => failureRow(x, options.detail));
 }
 
 function closedHistoryLine(state: FailureState): string | undefined {
@@ -244,10 +439,10 @@ function closedHistoryLine(state: FailureState): string | undefined {
 /** Shared priority text, placed BEFORE assistant progress on every consumer surface. */
 export function formatFailureSummary(state: FailureState): string {
   const lines = formatFailureLines(state);
-  if (!lines.length) return "";
+  if (!lines.length) return quietFailureLine(state) ?? "";
   const rows = lines.slice(0, 5);
   if (lines.length > 5) rows.push(`${lines.length - 5} additional active failure observations retained in the failure journal.`);
-  const history = closedHistoryLine(state);
+  const history = historyTailLine(state);
   if (history) rows.push(history);
   return rows.join("\n");
 }
@@ -257,7 +452,7 @@ export function pendingAttentionRows(state: FailureState, incidents: readonly st
   const wanted = new Set(incidents);
   const rows = activeFailures(state).filter((x) => wanted.has(x.id));
   if (rows.length !== wanted.size) throw new Error("Failure incident evidence is unavailable; defer notification delivery");
-  return rows.map(failureRow);
+  return rows.map((x) => failureRow(x));
 }
 /** Count of other active incidents, which a notification references but never re-lists. */
 export function pendingAttentionNote(state: FailureState, incidents: readonly string[]): string | undefined {
@@ -279,6 +474,8 @@ export function formatPendingAttention(state: FailureState, incidents: readonly
   return lines.join("\n");
 }
 
+/** The terminal fact that lifecycle success is not evidence of correct work. Kept whenever it fits and never cut mid-sentence (#325). */
+export const CORRECTNESS_NOTE: string = "Work correctness was not inferred from lifecycle alone.";
 export interface TerminalFailureParts {
   /** Actionable and observation-incomplete incidents among `incidents`, one row each. */
   rows: string[];
@@ -292,7 +489,7 @@ export interface TerminalFailureParts {
 export function terminalFailureParts(state: FailureState, incidents: readonly string[] = []): TerminalFailureParts {
   const wanted = new Set(incidents);
   const reportable = (x: FailureObservation) => requiresAction(x) || x.category === "observation-incomplete";
-  const rows = activeFailures(state).filter((x) => wanted.has(x.id) && reportable(x)).map(failureRow);
+  const rows = activeFailures(state).filter((x) => wanted.has(x.id) && reportable(x)).map((x) => failureRow(x));
   const notes: string[] = [];
   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.`);
@@ -301,7 +498,7 @@ export function terminalFailureParts(state: FailureState, incidents: readonly st
   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("Work correctness was not inferred from lifecycle alone.");
+  if (counts.unclassified || counts.actionRequired) notes.push(CORRECTNESS_NOTE);
   return { rows, notes };
 }
 export function formatTerminalFailureFacts(state: FailureState, incidents: readonly string[] = []): string {
@@ -339,8 +536,9 @@ export function failureRevision(state: FailureState): string {
     .sort((a, b) => String(a[0]).localeCompare(String(b[0]))));
 }
 
-function incidentRevision(state: FailureState): string {
-  return failureIdentity(activeFailures(state).map((item) => [item.id, item.status, item.count, item.summary, item.evidence ?? ""])).slice(0, 16);
+/** Digest of the rows a cursor pages. Scope and detail are part of it: the same incidents render different bytes. */
+function incidentRevision(state: FailureState, scope: IncidentScope = "actionable", detail: IncidentDetail = "compact"): string {
+  return failureIdentity(scope, detail, scopedFailures(state, scope).map((item) => [item.id, item.status, item.count, item.summary, item.evidence ?? ""])).slice(0, 16);
 }
 
 /** Cursors carry a digest of their resource/scope, not the scope text. */
@@ -348,20 +546,28 @@ function resourceTag(resource: string | undefined): string | undefined {
   return resource === undefined ? undefined : createHash("sha256").update(resource).digest("base64url").slice(0, 16);
 }
 
-interface IncidentCursor { o: number; b: number; v: string; n: number; r?: string }
+/**
+ * Incident cursor format. `x` is the format version: cursors minted before scope and row detail
+ * existed (no `x`) carry byte offsets into full-detail rows of every active incident, so they reset
+ * as stale instead of resuming inside a compact row. `h`: the explicit history view; `f`: full rows.
+ */
+const INCIDENT_CURSOR_FORMAT = 2;
+interface IncidentCursor { o: number; b: number; v: string; n: number; r?: string; h?: 1; f?: 1 }
 
 function encodeIncidentCursor(cursor: IncidentCursor): string {
-  return INCIDENT_CURSOR_PREFIX + Buffer.from(JSON.stringify({ k: "i", o: cursor.o, ...(cursor.b ? { b: cursor.b } : {}),
-    v: cursor.v, n: cursor.n, ...(cursor.r !== undefined ? { r: cursor.r } : {}) }), "utf8").toString("base64url");
+  return INCIDENT_CURSOR_PREFIX + Buffer.from(JSON.stringify({ k: "i", x: INCIDENT_CURSOR_FORMAT, o: cursor.o, ...(cursor.b ? { b: cursor.b } : {}),
+    v: cursor.v, n: cursor.n, ...(cursor.r !== undefined ? { r: cursor.r } : {}), ...(cursor.h ? { h: 1 } : {}),
+    ...(cursor.f ? { f: 1 } : {}) }), "utf8").toString("base64url");
 }
 
 function decodeIncidentCursor(cursor: string | undefined): IncidentCursor | undefined {
   if (!cursor || !cursor.startsWith(INCIDENT_CURSOR_PREFIX)) return undefined;
   try {
-    const parsed = JSON.parse(Buffer.from(cursor.slice(INCIDENT_CURSOR_PREFIX.length), "base64url").toString("utf8")) as { k?: string; o?: number; b?: number; v?: string; n?: number; r?: string };
-    if (parsed?.k === "i" && typeof parsed.v === "string") {
+    const parsed = JSON.parse(Buffer.from(cursor.slice(INCIDENT_CURSOR_PREFIX.length), "base64url").toString("utf8")) as { k?: string; x?: number; o?: number; b?: number; v?: string; n?: number; r?: string; h?: number; f?: number };
+    if (parsed?.k === "i" && parsed.x === INCIDENT_CURSOR_FORMAT && typeof parsed.v === "string") {
       return { o: Math.max(0, Math.floor(parsed.o ?? 0)), b: Math.max(0, Math.floor(parsed.b ?? 0)), v: parsed.v,
-        n: Math.max(0, Math.floor(parsed.n ?? 0)), ...(typeof parsed.r === "string" ? { r: parsed.r } : {}) };
+        n: Math.max(0, Math.floor(parsed.n ?? 0)), ...(typeof parsed.r === "string" ? { r: parsed.r } : {}),
+        ...(parsed.h === 1 ? { h: 1 as const } : {}), ...(parsed.f === 1 ? { f: 1 as const } : {}) };
     }
   } catch { /* stale */ }
   return undefined;
@@ -371,6 +577,12 @@ export function isIncidentCursor(cursor: string | undefined): boolean {
   return Boolean(cursor?.startsWith(INCIDENT_CURSOR_PREFIX));
 }
 
+/** The scope an incident cursor pages, or undefined for anything that is not an incident cursor. */
+export function incidentCursorScope(cursor: string | undefined): IncidentScope | undefined {
+  const parsed = decodeIncidentCursor(cursor);
+  return parsed ? (parsed.h ? "all" : "actionable") : undefined;
+}
+
 function utf8Length(value: string): number {
   return encoder.encode(value).byteLength;
 }
@@ -384,7 +596,7 @@ function utf8Prefix(bytes: Uint8Array, room: number): number {
   return end;
 }
 
-export interface IncidentPageRequest {
+export interface IncidentPageRequest extends IncidentRowOptions {
   cursor?: string;
   maxBytes?: number;
   /** Resource/scope bound into cursors; a cursor minted for another scope resets. */
@@ -398,23 +610,27 @@ export interface IncidentPageRequest {
  * that `endsPartial`). A page never exceeds `maxBytes`.
  */
 export function pageFailureIncidents(state: FailureState, request: IncidentPageRequest = {}): FailureIncidentPage {
-  const lines = formatFailureLines(state);
-  const revision = incidentRevision(state);
+  // A cursor carries its view: following a history cursor stays in history without the flag.
+  const parsed = request.cursor ? decodeIncidentCursor(request.cursor) : undefined;
+  const scope: IncidentScope = request.scope ?? (parsed?.h ? "all" : "actionable");
+  const detail: IncidentDetail = request.detail ?? (parsed?.f ? "full" : "compact");
+  const lines = formatFailureLines(state, { scope, detail });
+  const revision = incidentRevision(state, scope, detail);
   const total = lines.length;
   const resource = resourceTag(request.resource);
   let offset = 0;
   let byte = 0;
   let reset: FailureIncidentPage["reset"];
   if (request.cursor) {
-    const parsed = decodeIncidentCursor(request.cursor);
-    if (!parsed || parsed.r !== resource) reset = "stale-cursor";
+    if (!parsed || parsed.r !== resource || Boolean(parsed.h) !== (scope === "all") || Boolean(parsed.f) !== (detail === "full")) reset = "stale-cursor";
     else if (parsed.v !== revision) reset = "source-replaced";
     else { offset = Math.min(total, parsed.o); byte = offset < total ? parsed.b : 0; }
   }
   const maxBytes = Number.isFinite(request.maxBytes) && (request.maxBytes ?? -1) >= 0
     ? Math.floor(request.maxBytes as number)
     : 2 * 1024;
-  const mint = (o: number, b: number) => encodeIncidentCursor({ o, b, v: revision, n: total, ...(resource !== undefined ? { r: resource } : {}) });
+  const mint = (o: number, b: number) => encodeIncidentCursor({ o, b, v: revision, n: total, ...(resource !== undefined ? { r: resource } : {}),
+    ...(scope === "all" ? { h: 1 as const } : {}), ...(detail === "full" ? { f: 1 as const } : {}) });
   const parts: string[] = [];
   let used = 0;
   let nextRow = offset;
@@ -460,11 +676,72 @@ export function pageFailureIncidents(state: FailureState, request: IncidentPageR
   };
 }
 
-export function incidentCursorAt(state: FailureState, offset: number, resource?: string): string {
-  const lines = formatFailureLines(state);
+/** Cursor resource for one task/run's incidents in one session scope. */
+export function incidentResource(scopeKey: string, id: string): string {
+  return `incidents:${scopeKey}:${id}`;
+}
+
+/** Heading for an explicit incident page. */
+export function incidentPageHeading(total: number, scope: IncidentScope = "actionable"): string {
+  return scope === "all"
+    ? `History page of ${total} failure observation${total === 1 ? "" : "s"} (all, including those that need no action).`
+    : `Incident page of ${total} active failure observation${total === 1 ? "" : "s"}.`;
+}
+
+/**
+ * One explicit incident page shaped as an envelope verbatim page (log-utils
+ * `VerbatimPage`): the shared body of every consumer's `incidentCursor`
+ * response. Omitted counts are rows, never bytes.
+ */
+export function incidentVerbatimPage(state: FailureState, request: IncidentPageRequest = {}): {
+  text: string;
+  hasMore: boolean;
+  cursor: string;
+  nextCursor: string;
+  omittedBytes: number;
+  omittedRows: number;
+  reset?: "stale-cursor" | "source-replaced";
+} {
+  const page = pageFailureIncidents(state, request);
+  const scope = request.scope ?? incidentCursorScope(request.cursor) ?? "actionable";
+  const empty = scope === "all" ? "No failure observations recorded."
+    : [quietFailureLine(state) ? "No failures need action." : "No active failure observations.", historyCountsText(state) ? "Pass history:true to list history." : ""].filter(Boolean).join(" ");
+  return {
+    text: page.text || (page.total === 0 ? empty : ""),
+    hasMore: page.hasMore,
+    cursor: page.cursor,
+    nextCursor: page.nextCursor,
+    omittedBytes: 0,
+    omittedRows: page.omitted,
+    ...(page.reset ? { reset: page.reset } : {}),
+  };
+}
+
+/**
+ * Cheap change fingerprint of a failure journal: the file's identity and size
+ * (or its read error), whether the durable existence marker is present, and
+ * how many records are still awaiting persistence in this process. Every
+ * journal append, truncation, deletion, or pending in-memory record changes
+ * it, so a cache keyed by it never serves stale incident counts.
+ */
+export function failureJournalFingerprint(path: string): string {
+  let file: string;
+  try {
+    const stats = statSync(path, { bigint: true });
+    file = `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeNs}:${stats.ctimeNs}`;
+  } catch (error) {
+    file = `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 {
+  const scope = options.scope ?? "actionable";
+  const detail = options.detail ?? "compact";
+  const lines = formatFailureLines(state, { scope, detail });
   const tag = resourceTag(resource);
-  return encodeIncidentCursor({ o: Math.max(0, Math.floor(offset)), b: 0, v: incidentRevision(state), n: lines.length,
-    ...(tag !== undefined ? { r: tag } : {}) });
+  return encodeIncidentCursor({ o: Math.max(0, Math.floor(offset)), b: 0, v: incidentRevision(state, scope, detail), n: lines.length,
+    ...(tag !== undefined ? { r: tag } : {}), ...(scope === "all" ? { h: 1 as const } : {}), ...(options.detail === "full" ? { f: 1 as const } : {}) });
 }
 
 const MIN_PARTIAL_ROW_BYTES = 96;
@@ -485,9 +762,28 @@ export interface IncidentSummary {
  * total, fully shown, omitted, and the incident cursor that resumes at the
  * first byte not shown. Counts survive any budget that fits the count line.
  */
-export function formatIncidentSummary(state: FailureState, options: { maxBytes: number; resource?: string; retrieval?: string }): IncidentSummary {
+export interface IncidentSummaryOptions {
+  maxBytes: number;
+  resource?: string;
+  retrieval?: string;
+  /** Row detail; cursors minted here page the same detail. Default compact. */
+  detail?: IncidentDetail;
+}
+export function formatIncidentSummary(state: FailureState, options: IncidentSummaryOptions): IncidentSummary {
+  const maxBytes = Math.max(0, Math.floor(options.maxBytes));
+  const summary = actionableIncidentSummary(state, options);
+  // Nothing needs action: one short line, no cursor. History is listed only on request.
+  if (summary.total === 0) {
+    const quiet = quietFailureLine(state);
+    return { text: quiet && utf8Length(quiet) <= maxBytes ? quiet : "", total: 0, represented: 0, omitted: 0 };
+  }
+  const tail = historyTailLine(state);
+  if (tail && summary.text && utf8Length(summary.text) + 1 + utf8Length(tail) <= maxBytes) return { ...summary, text: `${summary.text}\n${tail}` };
+  return summary;
+}
+function actionableIncidentSummary(state: FailureState, options: IncidentSummaryOptions): IncidentSummary {
   const maxBytes = Math.max(0, Math.floor(options.maxBytes));
-  const whole = pageFailureIncidents(state, { maxBytes, resource: options.resource });
+  const whole = pageFailureIncidents(state, { maxBytes, resource: options.resource, detail: options.detail });
   if (whole.total === 0) return { text: "", total: 0, represented: 0, omitted: 0 };
   if (!whole.hasMore) return { text: whole.text, total: whole.total, represented: whole.represented, omitted: 0 };
   const header = (page: FailureIncidentPage): string =>
@@ -495,11 +791,11 @@ export function formatIncidentSummary(state: FailureState, options: { maxBytes:
     ` · incidentCursor=${page.nextCursor}${options.retrieval ? ` (${options.retrieval})` : ""}`;
   let rowBudget = maxBytes - utf8Length(header(whole)) - 1;
   for (let attempt = 0; attempt < 6; attempt += 1) {
-    let page = pageFailureIncidents(state, { maxBytes: Math.max(0, rowBudget), resource: options.resource });
+    let page = pageFailureIncidents(state, { maxBytes: Math.max(0, rowBudget), resource: options.resource, detail: options.detail });
     // A few bytes of a clipped row are noise; show the count line alone and
     // let the cursor start at that row.
     if (page.represented === 0 && page.endsPartial && utf8Length(page.text) < MIN_PARTIAL_ROW_BYTES) {
-      page = pageFailureIncidents(state, { maxBytes: 0, resource: options.resource });
+      page = pageFailureIncidents(state, { maxBytes: 0, resource: options.resource, detail: options.detail });
     }
     const line = header(page);
     const text = page.text ? `${line}\n${page.text}` : line;
@@ -512,7 +808,7 @@ export function formatIncidentSummary(state: FailureState, options: { maxBytes:
   }
   // Not even the count line with its cursor fits. Never emit a clipped cursor:
   // keep the exact counts and drop the cursor token whole, saying so.
-  const empty = pageFailureIncidents(state, { maxBytes: 0, resource: options.resource });
+  const empty = pageFailureIncidents(state, { maxBytes: 0, resource: options.resource, detail: options.detail });
   const withCursor = header(empty);
   if (utf8Length(withCursor) <= maxBytes) {
     return { text: withCursor, total: empty.total, represented: 0, omitted: empty.total, nextCursor: empty.nextCursor };
@@ -532,23 +828,58 @@ export function formatIncidentSummary(state: FailureState, options: { maxBytes:
  * observation-incomplete incidents (which lead the priority order) are shown as whole rows;
  * unclassified, expected, and closed incidents are counts. When any active row is not shown, a
  * count line gives the exact total, shown, omitted, and an incident cursor at the first unshown row.
+ *
+ * The result never exceeds `maxBytes` and is made of whole lines (#325). Under a tight budget it
+ * drops, in order: incident rows; the lower-priority notes (closed history, expected, earlier
+ * reported); the cursor's retrieval hint; the unclassified count; the cursor; the count line.
+ * The correctness note goes last, and only when it alone does not fit: it is never cut mid-sentence.
  */
-export function formatTerminalIncidentSummary(state: FailureState, options: { maxBytes: number; resource?: string; retrieval?: string }): IncidentSummary {
+export function formatTerminalIncidentSummary(state: FailureState, options: IncidentSummaryOptions): IncidentSummary {
   const active = activeFailures(state);
-  const total = active.length;
-  const { notes } = terminalFailureParts(state, active.map((x) => x.id));
+  // Counts, rows, and the cursor cover only incidents that need action; the rest is history.
+  const lines = formatFailureLines(state, { detail: options.detail });
+  const total = lines.length;
+  const parts = terminalFailureParts(state, active.map((x) => x.id));
+  const quiet = quietFailureLine(state);
+  // Nothing needs action: one short history line (no cursor) and, when tool failures stay
+  // unclassified, the correctness note.
+  const notes = total === 0 && quiet ? [quiet, ...parts.notes.filter((x) => x === CORRECTNESS_NOTE)] : parts.notes;
   if (total === 0 && notes.length === 0) return { text: "", total: 0, represented: 0, omitted: 0 };
-  const reportable = active.filter((x) => requiresAction(x) || x.category === "observation-incomplete").length;
-  const lines = formatFailureLines(state).slice(0, reportable);
   const maxBytes = Math.max(0, Math.floor(options.maxBytes));
-  const header = (shown: number): string | undefined => shown >= total ? undefined :
+  const fits = (parts: readonly (string | undefined)[]) => utf8Length(parts.filter(Boolean).join("\n")) <= maxBytes;
+  // "full": cursor and retrieval hint; "bare": cursor only; "none": exact counts, no cursor.
+  type Header = "full" | "bare" | "none";
+  const header = (shown: number, mode: Header): string | undefined => shown >= total ? undefined :
     `${total} active failure observation${total === 1 ? "" : "s"} · ${shown} shown · ${total - shown} omitted` +
-    ` · incidentCursor=${incidentCursorAt(state, shown, options.resource)}${options.retrieval ? ` (${options.retrieval})` : ""}`;
-  const render = (shown: number) => [header(shown), ...lines.slice(0, shown), ...notes].filter((x): x is string => Boolean(x)).join("\n");
-  let shown = lines.length;
-  while (shown > 0 && utf8Length(render(shown)) > maxBytes) shown -= 1;
-  const omitted = total - shown;
-  return { text: render(shown), total, represented: shown, omitted, ...(omitted > 0 ? { nextCursor: incidentCursorAt(state, shown, options.resource) } : {}) };
+    (mode === "none" ? " · incident cursor not shown (page too small)"
+      : ` · incidentCursor=${incidentCursorAt(state, shown, options.resource, { detail: options.detail })}${mode === "full" && options.retrieval ? ` (${options.retrieval})` : ""}`);
+  const done = (parts: readonly (string | undefined)[], shown: number, mode: Header): IncidentSummary => {
+    const omitted = total - shown;
+    return { text: parts.filter((x): x is string => Boolean(x)).join("\n"), total, represented: shown, omitted,
+      ...(omitted > 0 && mode !== "none" ? { nextCursor: incidentCursorAt(state, shown, options.resource, { detail: options.detail }) } : {}) };
+  };
+  // 1. Drop incident rows, lowest priority first, keeping every note and the count line with its cursor.
+  for (let shown = lines.length; shown >= 0; shown -= 1) {
+    const parts = [header(shown, "full"), ...lines.slice(0, shown), ...notes];
+    if (fits(parts)) return done(parts, shown, "full");
+  }
+  // 2. No rows. Then, in order: the lower-priority notes (history, expected, earlier reported), the
+  //    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 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] });
+  ladder.push({ mode: "bare", notes: [...unclassified, ...correctness] });
+  ladder.push({ mode: "bare", notes: correctness });
+  ladder.push({ mode: "none", notes: correctness });
+  ladder.push({ mode: undefined, notes: correctness });
+  for (const step of ladder) {
+    const parts = [step.mode ? header(0, step.mode) : undefined, ...step.notes];
+    if (parts.some(Boolean) && fits(parts)) return done(parts, 0, step.mode ?? "none");
+  }
+  return done([], 0, "none");
 }
 /**
  * Incidents due for a notification. Terminal: every current unresolved incident not yet delivered