pi-better-subagents 0.5.0 → 0.6.0

package/docs/failure-observations.md

@@ -14,7 +14,7 @@ Each run retains an append-only `failures.jsonl` journal. Nothing is deleted fro
 | `Observation incomplete` | Missing, corrupt, truncated, or unreadable evidence. |
 | `Recovered` / `Superseded` | Closed. Counted in history, never shown as active. |
 
-A completed run reports lifecycle and incidents as separate facts, for example:
+A completed run reports lifecycle and incidents as separate facts. When a page is small, incident rows are dropped before notes, and the correctness note is kept whole whenever it fits. For example:
 
 ```text
 status=completed
@@ -22,11 +22,22 @@ status=completed
 Work correctness was not inferred from lifecycle alone.
 ```
 
+## What the parent sees by default
+
+Only incidents that need action are listed: `Action required` and `Observation incomplete`. Unclassified and expected failures are counted as history, never listed or paged by default. A completed run with nothing to act on says so in one line, with no incident cursor:
+
+```text
+No failures need action · 8 unclassified tool errors · 2 expected (history)
+Work correctness was not inferred from lifecycle alone.
+```
+
+Pass `history: true` to `subagent_result` or `subagent_output` to page every incident, including recovered and superseded ones. Rows are compact: a tool's result JSON is shown as its text, the excerpt is capped at 120 bytes, and evidence reads `output.log#byte=N`. `mode: "raw"` keeps the whole excerpt and the full log path.
+
 ## When the parent is notified
 
 - **While the child runs**, a single tool error does not wake the parent; the child owns it. The parent is woken, after a 60-second grace period, only for non-tool failures, for an operation that failed three times with no recovery, and for incidents the child marked `open`. Each incident is delivered once. Observation gaps (for example an oversized log record) stay visible on every surface and are delivered with the completion or health callback, since the parent cannot act on them mid-run.
 - **At completion**, every still-unresolved incident is reported once in the ordinary completion callback: actionable incidents in full, unclassified tool failures as a count. Incidents a running notification already delivered are counted, not repeated.
-- **Orphaned and lost** health callbacks carry the same facts once.
+- **Orphaned and lost** health callbacks carry the same facts once. After an orphaned or lost run's health callback, observation gaps found later are delivered promptly, once, since no further callback may follow.
 
 Every notification renders only its pending incidents. Delivery receipts are independent of recovery and are written after handoff; `callback:false` suppresses notifications without hiding inspection evidence.
 
@@ -34,7 +45,7 @@ Every notification renders only its pending incidents. Delivery receipts are ind
 
 Automatic recovery still requires an exact retry: the same tool name, arguments, and working directory, started after the failure. Parallel or unrelated successes cannot clear an incident, and neither can exit 0 of another command or anything an assistant writes.
 
-Sandboxed children (the task runtime) get two structured additions. The parent honours them only for runs whose metadata it wrote as launched on the task runtime; for any other run, intent-looking arguments are ordinary arguments and `failure_disposition` calls are ignored.
+Sandboxed children (the task runtime) get two structured additions. The parent honours them only for runs it launched on the task runtime: `meta.taskRuntime` and a parent-authored provenance record written before the child starts, outside the run directory, where the confined child cannot write. For any other run, intent-looking arguments are ordinary arguments and `failure_disposition` calls are ignored. If the metadata cannot be read for a moment, the parent waits and reads it again rather than falling back to the exact rule for the rest of the run. The wait is bounded: when the run ends, or after 30 seconds, the log is scanned under the exact-retry rule so real failures stay visible, with an `Observation incomplete` note that the metadata could not be read.
 
 - `bash` accepts optional `operationId`, `attemptId`, and `expectedExitCodes`, validated before the command runs.
   - `operationId` names one logical operation across modified retries. A later success with the same `operationId` (a changed scope, timeout, or flag) recovers the earlier failure automatically. Without it, the exact rule applies. `attemptId` names one execution for use as evidence and never changes operation identity.
@@ -47,9 +58,11 @@ Sandboxed children (the task runtime) get two structured additions. The parent h
 
   A `bash` call whose intent is rejected (malformed fields, or a reused `attemptId`) never runs. It is recorded as its own unclassified observation, not as a failure of the command it named, so it cannot make that operation look stuck.
 
+  Reuse is checked against the child's whole session record, every branch, which is also what the parent scans (the whole log). A reuse the parent sees is always one the child refused, so a real failed run is never filed as a rejected intent.
+
   Targets may be incident ids, the `attemptId` or `operationId` the child declared, or tool call ids. Unknown, already-disposed, evidence-free, or partially invalid requests are rejected whole, with the open incidents listed, and nothing is written. The parent replays the same validation from the child's log before it appends the disposition to the journal, so dispositions survive reload and replay exactly once.
 
-Unconfined children keep the exact-retry rule and do not yet have these additions.
+Unconfined children keep the exact-retry rule, and this is intentional: an unconfined child can rewrite its own log and metadata, so the parent cannot trust intent or dispositions it reports. Background tasks, which the parent agent launches itself, accept `operation_id` and `expected_exit_codes` directly (see the background-tasks README).
 
 ## Evidence health
 

package/failures.ts

@@ -1,6 +1,6 @@
 import { closeSync, fstatSync, openSync, readSync } from "node:fs";
 import { join } from "node:path";
-import { logPathFor, readMeta, runDir } from "./registry.ts";
+import { logPathFor, runDir, taskRuntimeTrust } from "./registry.ts";
 import { activeFailures, disposeIncidents, failureIdentity, formatFailureSummary, formatTerminalFailureFacts, markFailureAttentionDelivered,
     observeFailures, pendingFailureAttention, readFailureState, type FailureState } from "./shared-failure-observations.ts";
 import { evidenceText, foldToolEnd, foldToolStart, newIncidentModel, toolOperation, type IncidentModel, type IncidentSink } from "./incident-model.ts";
@@ -10,10 +10,14 @@ export const failurePath = (id: string) => join(runDir(id), "failures.jsonl");
 export const readRunFailures = (id: string): FailureState => readFailureState(failurePath(id));
 interface Scan { offset: number; head: string; identity: string; model: IncidentModel; retry?: number }
 const scans = new Map<string, Scan>();
+/** When each run's trust first could not be read, for the bounded wait (#325). */
+const trustUnknownSince = new Map<string, number>();
+/** How long a running scan waits for unreadable trust before scanning under the exact-retry rule. */
+export const TRUST_WAIT_MS = 30_000;
 /** Drop an in-memory scan cursor (e.g. on reload); the journal remains authoritative. */
 export function resetFailureScanCursor(id?: string): void {
-    if (id === undefined) scans.clear();
-    else scans.delete(id);
+    if (id === undefined) { scans.clear(); trustUnknownSince.clear(); }
+    else { scans.delete(id); trustUnknownSince.delete(id); }
 }
 const CHUNK = 64 * 1024;
 const MAX_LINE = 2 * 1024 * 1024;
@@ -97,8 +101,37 @@ export function collectRunFailures(id: string, cwd: string, terminal = false): F
             scan = undefined;
         }
         // Structured intent and dispositions are honoured only for runs launched on the trusted task
-        // runtime, whose bash and failure_disposition tools are the guarded ones (parent-written metadata).
-        if (!scan) scan = { offset: 0, head, identity, model: newIncidentModel(readMeta(id)?.taskRuntime === true) };
+        // runtime, whose bash and failure_disposition tools are the guarded ones. Trust needs the
+        // parent-authored provenance record as well as `meta.taskRuntime` (#325). It is decided once
+        // per scan model, and only from a definite answer: while metadata or provenance cannot be read
+        // the scan waits (nothing is folded, so a brief read failure pins nothing to the exact rule).
+        // The wait is bounded: at a terminal read, or once trust has been unreadable for
+        // TRUST_WAIT_MS, the log is scanned under the exact-retry rule (untrusted) so real failures
+        // stay visible, and an observation gap says the metadata could not be read.
+        if (!scan) {
+            const trust = taskRuntimeTrust(id);
+            if (trust === "unknown") {
+                const now = Date.now();
+                const since = trustUnknownSince.get(id) ?? now;
+                trustUnknownSince.set(id, since);
+                while (trustUnknownSince.size > 256) trustUnknownSince.delete(trustUnknownSince.keys().next().value!);
+                const prior = readRunFailures(id);
+                const gap = prior.observations[failureIdentity("run-metadata")];
+                const waited = terminal || now - since >= TRUST_WAIT_MS;
+                if (waited && !(gap && gap.status === "unresolved")) {
+                    observeFailures(path, [{ id: failureIdentity("run-metadata-unreadable", gap?.id ?? "initial"), operation: "run-metadata", kind: "incomplete",
+                        summary: "Run metadata could not be read; tool failures are scanned under the exact-retry rule" }]);
+                }
+                if (!waited) return prior;
+                scan = { offset: 0, head, identity, model: newIncidentModel(false) };
+            } else {
+                trustUnknownSince.delete(id);
+                scan = { offset: 0, head, identity, model: newIncidentModel(trust === "trusted") };
+                const deferred = readRunFailures(id).observations[failureIdentity("run-metadata")];
+                if (deferred && deferred.status === "unresolved") observeFailures(path, [{ id: `run-metadata-readable:${deferred.id}`,
+                    operation: "run-metadata", kind: "recovered", incidents: [deferred.id] }]);
+            }
+        }
         scan.head = head;
         let position = scan.offset;
         let start = position;

package/incident-model.ts

@@ -8,46 +8,12 @@
  * `operationId` or the exact tool/arguments/cwd hash; expected exits require a code
  * declared on the attempt before it ran and a structured exit code from the tool.
  */
-import { failureIdentity, findIncident, validateDisposition, INCIDENT_DISPOSITIONS, REJECTED_INTENT_CATEGORY,
-    type FailureEvent, type FailureState, type IncidentDisposition } from "./shared-failure-observations.ts";
+import { failureIdentity, findIncident, validateDisposition, INCIDENT_DISPOSITIONS, INTENT_ID_PATTERN, MAX_EXPECTED_EXIT_CODES,
+    REJECTED_INTENT_CATEGORY, readCommandIntent, withoutAbsentIntent, type CommandIntent, type FailureEvent, type FailureState, type IncidentDisposition } from "./shared-failure-observations.ts";
 
 export const DISPOSITION_TOOL = "failure_disposition";
-/** Caller-chosen 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;
-
-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[];
-}
-
-/** Validate structured intent fields. Absent fields are fine; malformed ones are an error. */
-export function readCommandIntent(args: unknown): { intent: CommandIntent; error?: string } {
-    const input = (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: `${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: `expectedExitCodes must be 1-${MAX_EXPECTED_EXIT_CODES} distinct integers from 1 to 255` };
-        }
-        intent.expectedExitCodes = [...codes] as number[];
-    }
-    return { intent };
-}
+// The intent validator is shared with background tasks through the vendored failure-observations module (#325).
+export { INTENT_ID_PATTERN, MAX_EXPECTED_EXIT_CODES, readCommandIntent, withoutAbsentIntent, type CommandIntent };
 
 function stable(value: unknown): unknown {
     if (Array.isArray(value)) return value.map(stable);
@@ -61,6 +27,8 @@ export function toolOperation(name: string, args: unknown, cwd: string): string
 /** Declared identity when an operationId is present, otherwise the exact rule. attemptId never affects identity. */
 export function attemptOperation(name: string, args: unknown, cwd: string, intent: CommandIntent): string {
     if (intent.operationId) return failureIdentity("operation", name, intent.operationId, cwd);
+    // An explicit-null intent field is an undeclared one: `{expectedExitCodes: null}` and `{}` are the same command.
+    args = withoutAbsentIntent(args);
     if (args && typeof args === "object" && !Array.isArray(args) && "attemptId" in args) {
         const { attemptId: _attemptId, ...rest } = args as Record<string, unknown>;
         return toolOperation(name, rest, cwd);
@@ -73,10 +41,12 @@ export function evidenceText(value: unknown): string | undefined {
     const raw = typeof value === "string" ? value : JSON.stringify(value);
     return raw?.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 300);
 }
+/** The text a tool result carries (its first text part, stderr, or error), not its JSON wrapper. */
+function resultText(result: any): string | undefined {
+    return evidenceText(result?.content?.find?.((x: any) => x?.type === "text")?.text ?? result?.stderr ?? result?.error ?? result);
+}
 function resultError(result: any): string | undefined {
-    if (result?.isError === true || (typeof result?.exitCode === "number" && result.exitCode !== 0)) {
-        return evidenceText(result?.content?.find?.((x: any) => x?.type === "text")?.text ?? result?.stderr ?? result?.error ?? result);
-    }
+    if (result?.isError === true || (typeof result?.exitCode === "number" && result.exitCode !== 0)) return resultText(result);
     return undefined;
 }
 function time(row: any): number | undefined {
@@ -90,8 +60,13 @@ interface Attempt {
     operation: string;
     intent: CommandIntent;
     startSequence: number;
-    /** The confined intent bash refused this attempt before running anything. */
-    rejectedIntent?: string;
+    /**
+     * Why the confined intent bash is expected to refuse this attempt. A prediction only: the
+     * attempt is filed as a rejected intent when its end row carries the child's own refusal.
+     */
+    predictedRejection?: string;
+    /** Intent names this start registered, undone if the child refused it after all. */
+    registered?: { attemptId?: string; operationId?: string };
 }
 interface Finished extends Attempt {
     ok: boolean;
@@ -236,13 +211,23 @@ export function foldToolStart(model: IncidentModel, row: any, cwd: string, sink:
     const rawAttemptId = toolName === "bash" && typeof row.args?.attemptId === "string" ? row.args.attemptId as string : undefined;
     const reused = rawAttemptId !== undefined && model.namedAttempts.has(rawAttemptId);
     if (rawAttemptId !== undefined) model.namedAttempts.add(rawAttemptId);
-    const rejectedIntent = parsed.error ?? (reused ? `attemptId ${intent.attemptId} was already used` : undefined);
-    const operation = attemptOperation(toolName, row.args, cwd, intent);
-    model.open.set(toolCallId, { toolCallId, toolName, operation, intent: rejectedIntent ? {} : intent, startSequence: seq,
-        ...(rejectedIntent ? { rejectedIntent } : {}) });
-    if (rejectedIntent) return;
-    if (intent.attemptId) model.attemptIds.set(intent.attemptId, toolCallId);
-    if (intent.operationId && !model.operationIds.has(intent.operationId)) model.operationIds.set(intent.operationId, operation);
+    const predictedRejection = parsed.error ?? (reused ? `attemptId ${intent.attemptId} was already used` : undefined);
+    // A predicted refusal falls back to exact identity: if the child ran the command after all, it is
+    // an ordinary failure of exactly that command, never a failure of the operation it named.
+    const effective = predictedRejection ? {} : intent;
+    const operation = attemptOperation(toolName, row.args, cwd, effective);
+    const attempt: Attempt = { toolCallId, toolName, operation, intent: effective, startSequence: seq,
+        ...(predictedRejection ? { predictedRejection } : {}) };
+    model.open.set(toolCallId, attempt);
+    if (predictedRejection) return;
+    if (intent.attemptId) {
+        model.attemptIds.set(intent.attemptId, toolCallId);
+        attempt.registered = { attemptId: intent.attemptId };
+    }
+    if (intent.operationId && !model.operationIds.has(intent.operationId)) {
+        model.operationIds.set(intent.operationId, operation);
+        attempt.registered = { ...attempt.registered, operationId: intent.operationId };
+    }
     if (toolName === DISPOSITION_TOOL) {
         const parsed = readDispositionRequest(row.args);
         model.pendingDispositions.set(toolCallId, parsed.request
@@ -251,6 +236,28 @@ export function foldToolStart(model: IncidentModel, row: any, cwd: string, sink:
     }
 }
 
+/** The confined intent bash's own pre-run refusal (child-incidents.ts), matched as the whole result text. */
+const INTENT_REFUSAL = /^Invalid command intent: ([\s\S]+)\. The command was not run\.$/;
+/** Pi's pre-execution schema rejection; it names the tool, and nothing ran. */
+const SCHEMA_REFUSAL = /^Validation failed for tool "/;
+
+/**
+ * Why the child refused this bash call before running it, read from the end row the child
+ * produced, never re-derived from the arguments. A command that ran and failed returns undefined.
+ */
+function preRunRefusal(model: IncidentModel, attempt: Attempt | undefined, toolName: string, row: any): string | undefined {
+    if (!model.structuredIntent || toolName !== "bash" || row.isError !== true) return undefined;
+    const content = row.result?.content;
+    const text = Array.isArray(content) && content.length === 1 && typeof content[0]?.text === "string" ? content[0].text.trim() : undefined;
+    if (text === undefined) return undefined;
+    const refused = INTENT_REFUSAL.exec(text);
+    if (refused) return refused[1];
+    // Pi validates arguments against the intent schema before execute; that refusal is ours only
+    // when the intent fields themselves are what the shared validator rejects.
+    if (attempt?.predictedRejection && !attempt.predictedRejection.includes("already used") && SCHEMA_REFUSAL.test(text)) return attempt.predictedRejection;
+    return undefined;
+}
+
 /** Fold one tool execution end: failures, declared expected exits, exact retry recovery, dispositions. */
 export function foldToolEnd(model: IncidentModel, row: any, cwd: string, evidence: string, sink: IncidentSink): void {
     const toolCallId = String(row.toolCallId);
@@ -263,15 +270,19 @@ export function foldToolEnd(model: IncidentModel, row: any, cwd: string, evidenc
     const details = row.result?.details;
     const declaredExit = row.isError === false && details?.expectedExit === true && typeof details.exitCode === "number" &&
         (intent.expectedExitCodes ?? []).includes(details.exitCode) ? details.exitCode as number : undefined;
-    const error = row.isError === true ? evidenceText(row.result) ?? "Tool returned an error" : resultError(row.result);
+    const error = row.isError === true ? resultText(row.result) ?? "Tool returned an error" : resultError(row.result);
     const finished: Finished = { ...(attempt ?? { toolCallId, toolName, operation, intent, startSequence: seq }),
         ok: !error && declaredExit === undefined, endSequence: seq, evidence };
     model.finished.set(toolCallId, finished);
-    if (attempt?.rejectedIntent && (row.isError === true || error)) {
+    const refusal = preRunRefusal(model, attempt, toolName, row);
+    if (refusal !== undefined) {
         // Nothing ran: visible, but never grouped with (or escalating) the operation it named.
+        if (attempt?.registered?.attemptId && model.attemptIds.get(attempt.registered.attemptId) === toolCallId) model.attemptIds.delete(attempt.registered.attemptId);
+        if (attempt?.registered?.operationId) model.operationIds.delete(attempt.registered.operationId);
+        finished.intent = {};
         const failureId = `tool:${toolCallId}`;
         sink.observe([{ id: failureId, operation: failureIdentity("rejected-intent", toolCallId), kind: "failure", at: time(row),
-            category: REJECTED_INTENT_CATEGORY, evidence, summary: `${toolName} not run: invalid command intent (${attempt.rejectedIntent})` }]);
+            category: REJECTED_INTENT_CATEGORY, evidence, summary: `${toolName} not run: invalid command intent (${refusal})` }]);
         finished.incident = failureId;
         return;
     }