pi-better-subagents 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
   "license": "MIT",
   "type": "module",
@@ -51,7 +51,8 @@
     "docs/agent-catalog-operations.md",
     "docs/agent-model-resolution.md",
     "docs/agent-catalog-lifecycle.md",
-    "docs/agent-catalog-acceptance.md"
+    "docs/agent-catalog-acceptance.md",
+    "docs/failure-observations.md"
   ],
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

package/permission-policy.ts

@@ -0,0 +1,106 @@
+/** Optional sandbox-extension policy, mirrored per Pi event bus at launch time. */
+export const SANDBOX_POLICY_CHANNEL = "pi-better-sandbox:policy";
+export const SANDBOX_POLICY_REQUEST_CHANNEL = "pi-better-sandbox:policy-request";
+
+type Access = "off" | "read" | "read-write";
+export type PermissionProfile = Readonly<{
+    enabled: boolean;
+    projectFiles: Access;
+    outsideProject: Access;
+    storedCredentials: Access;
+    commands: boolean;
+    network: boolean;
+}>;
+export type PermissionSnapshot = Readonly<{
+    permissions?: PermissionProfile;
+    subagentPermissions?: PermissionProfile;
+}>;
+
+type EventBus = {
+    on(channel: string, handler: (data: unknown) => void): unknown;
+    emit(channel: string, data: unknown): void;
+};
+const mirrors = new WeakMap<EventBus, { policy?: PermissionSnapshot; error?: Error }>();
+
+function busOf(pi: unknown): EventBus | undefined {
+    const bus = (pi as { events?: unknown } | undefined)?.events;
+    if (!bus || typeof bus !== "object") return undefined;
+    const candidate = bus as Partial<EventBus>;
+    return typeof candidate.on === "function" && typeof candidate.emit === "function" ? candidate as EventBus : undefined;
+}
+
+function profile(value: unknown): PermissionProfile {
+    if (!value || typeof value !== "object") throw new Error("Invalid sandbox permission profile.");
+    const p = value as Record<string, unknown>;
+    const access = (v: unknown): v is Access => v === "off" || v === "read" || v === "read-write";
+    if (typeof p.enabled !== "boolean" || typeof p.commands !== "boolean" || typeof p.network !== "boolean" ||
+        !access(p.projectFiles) || !access(p.outsideProject) || !access(p.storedCredentials)) {
+        throw new Error("Invalid sandbox permission profile; update permissions in the sandbox UI.");
+    }
+    return Object.freeze({
+        enabled: p.enabled, commands: p.commands, network: p.network,
+        projectFiles: p.projectFiles, outsideProject: p.outsideProject, storedCredentials: p.storedCredentials,
+    });
+}
+
+function readPolicy(data: unknown): PermissionSnapshot | undefined {
+    if (!data || typeof data !== "object") return undefined;
+    const p = data as Record<string, unknown>;
+    if (!["inactive", "enabled", "disabled", "unavailable", "failed"].includes(String(p.state))) return undefined;
+    return Object.freeze({
+        ...(p.permissions === undefined ? {} : { permissions: profile(p.permissions) }),
+        ...(p.subagentPermissions === undefined ? {} : { subagentPermissions: profile(p.subagentPermissions) }),
+    });
+}
+
+/** Subscribe before launching; request a replay for either extension load order. */
+export function observeSandboxPermissions(pi: unknown): void {
+    const bus = busOf(pi);
+    if (!bus || mirrors.has(bus)) return;
+    const mirror: { policy?: PermissionSnapshot; error?: Error } = {};
+    mirrors.set(bus, mirror);
+    bus.on(SANDBOX_POLICY_CHANNEL, (data) => {
+        try {
+            const next = readPolicy(data);
+            if (next) { mirror.policy = next; mirror.error = undefined; }
+        } catch (error) {
+            mirror.error = error as Error;
+        }
+    });
+    bus.emit(SANDBOX_POLICY_REQUEST_CHANNEL, undefined);
+}
+
+export function currentSandboxPermissions(pi: unknown): PermissionSnapshot | undefined {
+    observeSandboxPermissions(pi);
+    const bus = busOf(pi);
+    if (!bus) return undefined;
+    bus.emit(SANDBOX_POLICY_REQUEST_CHANNEL, undefined);
+    const mirror = mirrors.get(bus);
+    if (mirror?.error) throw mirror.error;
+    return mirror?.policy;
+}
+
+/** Resolve before allocating a run. Absent settings retain the legacy default-on policy. */
+export function resolveSubagentPermissions(pi: unknown, requestedSandbox: boolean | undefined): {
+    sandboxEnabled: boolean;
+    enforced: boolean;
+    permissions?: Omit<PermissionProfile, "enabled">;
+} {
+    const snapshot = currentSandboxPermissions(pi);
+    if (snapshot?.permissions?.enabled && !snapshot.permissions.commands) {
+        throw new Error("Main sandbox profile disables commands. Enable commands in the sandbox UI before launching a subagent.");
+    }
+    const child = snapshot?.subagentPermissions;
+    if (!child) return { sandboxEnabled: requestedSandbox !== false, enforced: false };
+    if (child.enabled && requestedSandbox === false) {
+        throw new Error("Subagent sandbox is enforced by the human-enabled profile; sandbox:false cannot bypass it. Change Subagents permissions in the sandbox UI.");
+    }
+    const sandboxEnabled = child.enabled || requestedSandbox === true;
+    if (!sandboxEnabled) return { sandboxEnabled: false, enforced: false };
+    if (!child.commands) throw new Error("Subagents profile disables commands. Enable commands in the sandbox UI before launching a subagent.");
+    if (!child.network) {
+        throw new Error("Subagents profile disables network, including model requests. Child provider isolation is not available; enable network in the sandbox UI before launching a subagent.");
+    }
+    const { enabled: _enabled, ...permissions } = child;
+    return { sandboxEnabled: true, enforced: true, permissions };
+}

package/sandbox.ts

@@ -10,8 +10,10 @@
  * is passed through unchanged.
  */
 
+import type { PermissionProfile } from "./permission-policy.ts";
 import {
     buildSandboxCommand as buildSharedSandboxCommand,
+    compileWritePolicy,
     maybeBuildSandboxCommand as maybeBuildSharedSandboxCommand,
     sandboxSupported as sharedSandboxSupported,
     type SandboxCommand,
@@ -25,19 +27,34 @@ type SandboxCommandArgs = {
     home: string;
     piBin: string;
     piArgs: string[];
+    permissions?: Omit<PermissionProfile, "enabled">;
+    denyWrite?: readonly string[];
+    runtimeDir?: string;
 };
 
 /** Map the subagent's single-writable-directory shape onto the shared policy. */
 function sharedArgs(args: SandboxCommandArgs): SharedSandboxCommandArgs {
     return {
         profilePath: args.profilePath,
-        // Subagents have no write-deny list: the run directory is the policy.
-        policy: { writableRoot: args.writableDir, home: args.home },
-        execPath: args.piBin,
-        execArgs: args.piArgs,
+        // Parent-owned run artifacts must never be writable by the child.
+        policy: { writableRoot: args.writableDir, home: args.home,
+            ...(args.permissions ? { permissions: args.permissions } : {}),
+            ...(args.denyWrite ? { denyWrite: args.denyWrite } : {}),
+            ...(args.runtimeDir ? { runtimeWrite: [args.runtimeDir] } : {}),
+        },
+        execPath: args.runtimeDir ? "/usr/bin/env" : args.piBin,
+        execArgs: args.runtimeDir
+            ? [`TMPDIR=${args.runtimeDir}`, `TMP=${args.runtimeDir}`, `TEMP=${args.runtimeDir}`, args.piBin, ...args.piArgs]
+            : args.piArgs,
     };
 }
 
+function assertPermissionCore(args: SandboxCommandArgs): void {
+    if (args.permissions && !("permissions" in compileWritePolicy(sharedArgs(args).policy))) {
+        throw new Error("Permission-aware sandbox core is unavailable; update the sandbox packages before launching a subagent.");
+    }
+}
+
 /** True when an OS write-sandbox backend can be applied on this platform. */
 export function sandboxSupported(): boolean {
     return sharedSandboxSupported();
@@ -55,9 +72,12 @@ export function maybeBuildSandboxCommand(
     // `sandbox:false` is this surface's opt-out, and the only one its operator
     // has: a subagent has no slash commands. A caller that states its own remedy
     // keeps it.
+    assertPermissionCore(args);
     return maybeBuildSharedSandboxCommand(sharedArgs(args), {
         ...request,
-        remedy: request.remedy ?? "Pass sandbox:false to run this subagent unconfined.",
+        remedy: request.remedy ?? (args.permissions
+            ? "Change the Subagents permissions in /sandbox."
+            : "Pass sandbox:false to run this subagent unconfined."),
     });
 }
 
@@ -67,5 +87,6 @@ export function maybeBuildSandboxCommand(
  * bypass the request-policy helper above.
  */
 export function buildSandboxCommand(args: SandboxCommandArgs): SandboxCommand {
+    assertPermissionCore(args);
     return buildSharedSandboxCommand(sharedArgs(args));
 }

package/shared-callback-batcher.ts

@@ -105,6 +105,7 @@ export function createCallbackBatcher(
   const pending = new Map<string, PendingEvent>();
   const inFlight = new Set<string>();
   const urgentInFlight = new Set<string>();
+  const handedOff = new Map<string, number>();
   let sequence = 0;
   let timer: ReturnType<typeof setTimeout> | undefined;
   let flushPromise: Promise<boolean> | undefined;
@@ -140,9 +141,25 @@ export function createCallbackBatcher(
     for (const [key] of snapshot) inFlight.add(key);
 
     const deliverable: Array<[string, PendingEvent]> = [];
+    let deferred = false;
     for (const item of snapshot) {
       const [key, pendingEvent] = item;
+      const priorHandoff = handedOff.get(key);
+      if (priorHandoff !== undefined) {
+        if (!invokeDelivered(pendingEvent.event, priorHandoff)) {
+          deferred = true;
+          pending.set(key, pendingEvent);
+        }
+        inFlight.delete(key);
+        continue;
+      }
       const disposition = eventDisposition(pendingEvent.event);
+      if (disposition.kind === "deferred") {
+        deferred = true;
+        pending.set(key, pendingEvent);
+        inFlight.delete(key);
+        continue;
+      }
       if (disposition.kind === "delivered") {
         inFlight.delete(key);
         continue;
@@ -156,8 +173,8 @@ export function createCallbackBatcher(
     }
 
     if (deliverable.length === 0) {
-      if (pending.size > 0) schedule(windowMs);
-      return true;
+      if (pending.size > 0) schedule(deferred ? retryMs : windowMs);
+      return !deferred;
     }
 
     try {
@@ -183,11 +200,15 @@ export function createCallbackBatcher(
 
     const deliveredAt = Date.now();
     for (const [key, item] of deliverable) {
-      invokeDelivered(item.event, deliveredAt);
+      handedOff.set(key, deliveredAt);
+      if (!invokeDelivered(item.event, deliveredAt)) {
+        deferred = true;
+        pending.set(key, item);
+      }
       inFlight.delete(key);
     }
-    if (pending.size > 0) schedule(windowMs);
-    return true;
+    if (pending.size > 0) schedule(deferred ? retryMs : windowMs);
+    return !deferred;
   };
 
   const flush = (): Promise<boolean> => {
@@ -201,7 +222,15 @@ export function createCallbackBatcher(
   const deliverUrgent = (event: UrgentCallbackEvent): boolean | Promise<boolean> => {
     const key = eventKey(event);
     if (urgentInFlight.has(key)) return false;
+    const priorHandoff = handedOff.get(key);
+    if (priorHandoff !== undefined) return invokeDelivered(event, priorHandoff);
+    const acknowledge = (): boolean => {
+      const at = Date.now();
+      handedOff.set(key, at);
+      return invokeDelivered(event, at);
+    };
     const disposition = eventDisposition(event);
+    if (disposition.kind === "deferred") return false;
     if (disposition.kind === "delivered") return true;
     if (disposition.kind === "suppressed") {
       invokeSuppressed(event, disposition.reason, Date.now());
@@ -216,16 +245,13 @@ export function createCallbackBatcher(
       );
       if (isPromiseLike(handoff)) {
         return Promise.resolve(handoff).then(
-          () => {
-            invokeDelivered(event, Date.now());
-            return true;
-          },
+          () => acknowledge(),
           () => false,
         ).finally(() => urgentInFlight.delete(key));
       }
-      invokeDelivered(event, Date.now());
+      const acknowledged = acknowledge();
       urgentInFlight.delete(key);
-      return true;
+      return acknowledged;
     } catch {
       urgentInFlight.delete(key);
       return false;
@@ -278,25 +304,25 @@ function eventKey(event: Pick<CallbackBatchEvent, "source" | "id" | "status">):
 
 function eventDisposition(
   event: Pick<CallbackBatchEvent, "isDelivered" | "getSuppressionReason">,
-): { kind: "deliver" } | { kind: "delivered" } | { kind: "suppressed"; reason: string } {
+):   | { kind: "deliver" } | { kind: "delivered" } | { kind: "deferred" } | { kind: "suppressed"; reason: string } {
   try {
     if (event.isDelivered?.()) return { kind: "delivered" };
   } catch {
-    return { kind: "suppressed", reason: "durable delivery state could not be verified" };
+    return { kind: "deferred" };
   }
   try {
     const reason = event.getSuppressionReason?.();
     return reason ? { kind: "suppressed", reason } : { kind: "deliver" };
   } catch {
-    return { kind: "suppressed", reason: "callback ownership could not be verified" };
+    return { kind: "deferred" };
   }
 }
 
 function invokeDelivered(
   event: Pick<CallbackBatchEvent, "onDelivered">,
   at: number,
-): void {
-  try { event.onDelivered?.(at); } catch { /* handoff already succeeded */ }
+): boolean {
+  try { event.onDelivered?.(at); return true; } catch { return false; }
 }
 
 function invokeSuppressed(

package/shared-failure-observations.ts

@@ -0,0 +1,205 @@
+// Generated from packages/failure-observations/index.ts. Do not edit directly.
+import { appendFileSync, closeSync, existsSync, openSync, readFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { createHash } from "node:crypto";
+
+export interface FailureEvent {
+  /** Stable source event identity: replay must reuse this id. */
+  id: string;
+  operation: string;
+  kind: "failure" | "recovered" | "incomplete" | "delivered";
+  /** Event time when known; never fabricate it from log mtime. */
+  at?: number;
+  summary?: string;
+  category?: string;
+  evidence?: string;
+  expected?: boolean;
+  /** Recovery/delivery must name the incidents it resolves/delivers. */
+  incidents?: string[];
+}
+export interface FailureObservation {
+  id: string;
+  operation: string;
+  status: "unresolved" | "expected" | "resolved";
+  category: string;
+  summary: string;
+  evidence?: string;
+  firstObservedAt: number;
+  lastObservedAt: number;
+  /** Journal order breaks timestamp ties without inventing an event time. */
+  lastSequence?: number;
+  at?: number;
+  count: number;
+  resolvedAt?: number;
+}
+export interface FailureState {
+  version: 1;
+  seen: string[];
+  observations: Record<string, FailureObservation>;
+  delivered: Record<string, number>;
+  resolved?: Record<string, number>;
+}
+export function emptyFailureState(): FailureState {
+  return { version: 1, seen: [], observations: {}, delivered: {} };
+}
+export function failureIdentity(...parts: unknown[]): string {
+  return createHash("sha256").update(JSON.stringify(parts)).digest("hex").slice(0, 32);
+}
+function text(value: string | undefined, fallback: string): string {
+  return (value || fallback).replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 400);
+}
+/** Pure transition. Lifecycle is deliberately not an input or an output. */
+export function reduceFailure(state: FailureState, event: FailureEvent, observedAt: number): FailureState {
+  if (state.seen.includes(event.id)) return state;
+  const next: FailureState = { ...state, seen: [...state.seen, event.id],
+    observations: { ...state.observations }, delivered: { ...state.delivered } };
+  if (event.kind === "delivered") {
+    for (const id of event.incidents ?? []) next.delivered = { ...next.delivered, [id]: observedAt };
+    return next;
+  }
+  const key = failureIdentity(event.operation);
+  const previous = state.observations[key];
+  if (event.kind === "recovered") {
+    if (previous && event.incidents?.includes(previous.id)) {
+      next.observations[key] = { ...previous, status: "resolved", resolvedAt: event.at ?? observedAt };
+      next.resolved = { ...state.resolved, [previous.id]: event.at ?? observedAt };
+    }
+    return next;
+  }
+  const active = previous && previous.status !== "resolved" &&
+    !(previous.status === "expected" && !event.expected);
+  next.observations[key] = {
+    id: active ? previous.id : event.id, operation: event.operation,
+    status: active ? previous.status : event.expected ? "expected" : "unresolved",
+    category: event.kind === "incomplete" ? "observation-incomplete" : event.category ?? "operation",
+    summary: text(event.summary, "Operation failed"), evidence: event.evidence,
+    firstObservedAt: active ? previous.firstObservedAt : observedAt,
+    lastObservedAt: observedAt, lastSequence: next.seen.length, at: event.at,
+    count: active ? previous.count + 1 : 1,
+  };
+  return next;
+}
+export function activeFailures(state: FailureState): FailureObservation[] {
+  const priority = (x: FailureObservation) => x.status === "expected" ? 2 : x.category === "observation-incomplete" ? 0 : 1;
+  return Object.values(state.observations).filter((x) => x.status !== "resolved")
+    .sort((a, b) => priority(a) - priority(b) || (b.lastSequence ?? 0) - (a.lastSequence ?? 0) || b.lastObservedAt - a.lastObservedAt);
+}
+/** Shared priority text, placed BEFORE assistant progress on every consumer surface. */
+export function formatFailureSummary(state: FailureState): string {
+  const failures = activeFailures(state);
+  if (!failures.length) return "";
+  const rows = failures.slice(0, 5).map((x) => {
+    const label = x.status === "expected" ? "Expected failure" :
+      x.category === "observation-incomplete" ? "Observation incomplete" : "Unresolved failure";
+    const time = x.at === undefined ? `observed ${new Date(x.firstObservedAt).toISOString()}` : new Date(x.at).toISOString();
+    return `${label} · ${time} · ${x.summary}${x.count > 1 ? ` (${x.count} occurrences)` : ""}${x.evidence ? ` · evidence: ${text(x.evidence, "")}` : ""}`;
+  });
+  if (failures.length > 5) rows.push(`${failures.length - 5} additional active failure observations retained in the failure journal.`);
+  return rows.join("\n");
+}
+export function pendingFailureAttention(state: FailureState, now: number, options: { terminal?: boolean; graceMs?: number } = {}): { key: string; incidents: string[]; summary: string } | undefined {
+  const due = activeFailures(state).filter((x) => x.status === "unresolved" && !Object.hasOwn(state.delivered, x.id) &&
+    (options.terminal || x.category === "observation-incomplete" || now - x.firstObservedAt >= (options.graceMs ?? 60_000)));
+  if (!due.length) return undefined;
+  const incidents = due.map((x) => x.id).sort();
+  return { key: failureIdentity(incidents), incidents,
+    summary: due.map((x) => x.summary).join("; ").slice(0, 800) };
+}
+function storageProblem(state: FailureState, summary: string): FailureState {
+  return reduceFailure(state, { id: failureIdentity("storage", summary), operation: "failure-observation-storage",
+    kind: "incomplete", summary }, Date.now());
+}
+/** Append-only journal: individual bounded writes avoid lost read/modify/write snapshots. */
+interface PendingRecord { event: FailureEvent; observedAt: number }
+const pendingWrites = new Map<string, PendingRecord[]>();
+const knownJournals = new Map<string, number>();
+function appendRecord(path: string, record: PendingRecord): void {
+  mkdirSync(dirname(path), { recursive: true });
+  // A durable existence marker distinguishes a lost journal from a run that has
+  // never observed a failure, including after a process restart.
+  try { closeSync(openSync(`${path}.observed`, "wx", 0o600)); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+  appendFileSync(path, "\n" + JSON.stringify(record) + "\n", { mode: 0o600 });
+}
+/** Retry unpersisted evidence and receipts on every observation/read. Pending
+ * receipts count as handed off in this process, preventing notification storms. */
+export function readFailureState(path: string): FailureState {
+  const pending = pendingWrites.get(path);
+  while (pending?.length) {
+    try { appendRecord(path, pending[0]!); pending.shift(); }
+    catch { break; }
+  }
+  if (!pending?.length) pendingWrites.delete(path);
+  let state = readStoredState(path);
+  const remaining = pendingWrites.get(path);
+  for (const record of remaining ?? []) state = reduceFailure(state, record.event, record.observedAt);
+  return remaining?.length ? storageProblem(state, "Failure evidence could not be persisted") : state;
+}
+function readStoredState(path: string): FailureState {
+  let source: string;
+  try { source = readFileSync(path, "utf8"); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT" && !knownJournals.has(path) && !existsSync(`${path}.observed`)) return emptyFailureState();
+    return storageProblem(emptyFailureState(), "Failure journal could not be read");
+  }
+  const bytes = Buffer.byteLength(source);
+  const truncated = bytes < (knownJournals.get(path) ?? 0);
+  if (bytes || knownJournals.has(path)) knownJournals.set(path, bytes);
+  let state = truncated ? storageProblem(emptyFailureState(), "Failure journal was truncated; observations may be incomplete") : emptyFailureState();
+  for (const line of source.split("\n")) {
+    if (!line) continue;
+    try {
+      const row = JSON.parse(line);
+      const e = row.event;
+      if (!e || typeof e.id !== "string" || !e.id || typeof e.operation !== "string" || !e.operation ||
+          (e.expected !== undefined && typeof e.expected !== "boolean") ||
+          !["failure", "incomplete", "recovered", "delivered"].includes(e.kind) ||
+          !Number.isFinite(row.observedAt) || Math.abs(row.observedAt) > 8.64e15 ||
+          (e.at !== undefined && (!Number.isFinite(e.at) || Math.abs(e.at) > 8.64e15)) ||
+          (e.incidents !== undefined && (!Array.isArray(e.incidents) || !e.incidents.every((id: unknown) => typeof id === "string"))) ||
+          [e.summary, e.category, e.evidence].some((v) => v !== undefined && typeof v !== "string")) throw new Error("invalid record");
+      state = reduceFailure(state, e, row.observedAt);
+    } catch { state = storageProblem(state, "Failure journal contains unreadable records; observations may be incomplete"); }
+  }
+  if (truncated) {
+    const summary = "Failure journal was truncated; observations may be incomplete";
+    const record: PendingRecord = { event: { id: failureIdentity("storage", summary), operation: "failure-observation-storage", kind: "incomplete", summary }, observedAt: Date.now() };
+    try { appendRecord(path, record); }
+    catch { pendingWrites.set(path, [...(pendingWrites.get(path) ?? []), record]); }
+  }
+  return state;
+}
+export function observeFailures(path: string, events: readonly FailureEvent[], now = Date.now()): FailureState {
+  let state = readFailureState(path);
+  for (const raw of events) {
+    if (state.seen.includes(raw.id)) continue;
+    if (raw.kind === "recovered") {
+      const prior = state.observations[failureIdentity(raw.operation)];
+      if (!prior || prior.status === "resolved" || !raw.incidents?.includes(prior.id)) continue;
+    }
+    const event = { ...raw, ...(raw.summary ? { summary: text(raw.summary, "") } : {}),
+      ...(raw.evidence ? { evidence: text(raw.evidence, "") } : {}) };
+    try {
+      if (pendingWrites.has(path)) throw new Error("Earlier evidence is awaiting persistence");
+      appendRecord(path, { event, observedAt: now });
+      state = reduceFailure(state, event, now);
+    } catch {
+      const pending = pendingWrites.get(path) ?? [];
+      pending.push({ event, observedAt: now });
+      pendingWrites.set(path, pending);
+      state = storageProblem(reduceFailure(state, event, now), "Failure evidence could not be persisted");
+    }
+  }
+  return state;
+}
+export function failureAttentionHandled(state: FailureState, incidents: readonly string[]): boolean {
+  return incidents.every((id) => {
+    if (Object.hasOwn(state.delivered, id) || Object.hasOwn(state.resolved ?? {}, id)) return true;
+    const observation = Object.values(state.observations).find((item) => item.id === id);
+    if (!observation) throw new Error("Failure incident evidence is unavailable; defer notification delivery");
+    return observation.status !== "unresolved";
+  });
+}
+export function markFailureAttentionDelivered(path: string, pending: { key: string; incidents: string[] }, at = Date.now()): FailureState {
+  return observeFailures(path, [{ id: `delivered:${pending.key}`, operation: "attention-delivery", kind: "delivered", incidents: pending.incidents }], at);
+}