@mrclrchtr/supi-review 2.6.1 → 2.7.0

package/src/tool/session-lifecycle.ts

@@ -1,5 +1,12 @@
 import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
-import type { ReviewProgress } from "../types.ts";
+import type { ChildFailureCode, ChildFailureDiagnostics, ReviewProgress } from "../types.ts";
+import { buildChildFailureDiagnostics } from "./child-failure-diagnostics.ts";
+import {
+  type ChildLifecycleHostMarker,
+  type ChildLifecycleTrace,
+  ChildLifecycleTraceCollector,
+  getRegisteredToolNames,
+} from "./child-lifecycle-trace.ts";
 
 /**
  * Context passed to event handlers, timeout callbacks, and result factories.
@@ -22,6 +29,12 @@ export interface LifecycleCtx<TResult> {
   state: { settled: boolean; aborting: boolean };
   /** The managed agent session. */
   session: AgentSession;
+  /** Snapshot the bounded Child Lifecycle Trace observed so far. */
+  getLifecycleTrace: () => ChildLifecycleTrace;
+  /** Build a safe non-success diagnostic artifact from the observed child run. */
+  getFailureDiagnostics: () => ChildFailureDiagnostics;
+  /** Add one allowlisted runner-control marker to the Child Lifecycle Trace. */
+  recordHostMarker: (marker: ChildLifecycleHostMarker) => void;
   /**
    * Register a teardown function that runs when cleanup is called.
    * Useful for custom timers or resources set up by `onTimeout`.
@@ -55,12 +68,35 @@ export interface RunWithLifecycleConfig<TResult> {
   onTimeout?: (ctx: LifecycleCtx<TResult>) => void;
   /** Factory for the result produced when the abort signal fires. */
   canceledResult: (ctx: LifecycleCtx<TResult>) => TResult;
-  /** Factory for the result produced when `session.prompt()` throws. */
-  failedResult: (reason: string, ctx: LifecycleCtx<TResult>) => TResult;
+  /** Factory for the result produced when prompt preflight or execution fails. */
+  failedResult: (
+    code: Extract<ChildFailureCode, "prompt-rejected" | "unexpected-runner-failure">,
+    ctx: LifecycleCtx<TResult>,
+  ) => TResult;
   /** Factory for the result produced when the timeout expires (default hard abort). */
   timeoutResult: (timeoutMs: number, ctx: LifecycleCtx<TResult>) => TResult;
 }
 
+interface StartPromptOptions {
+  session: AgentSession;
+  prompt: string;
+  onPreflightRejected: () => void;
+  onFulfilled: () => void;
+  onUnexpectedFailure: () => void;
+}
+
+function startPrompt(options: StartPromptOptions): void {
+  const { session, prompt, onPreflightRejected, onFulfilled, onUnexpectedFailure } = options;
+  try {
+    const promptPromise = session.prompt(prompt, {
+      preflightResult: (accepted) => !accepted && onPreflightRejected(),
+    });
+    void promptPromise.then(onFulfilled, onUnexpectedFailure);
+  } catch {
+    onUnexpectedFailure();
+  }
+}
+
 /**
  * Manages the lifecycle of a child agent session: subscribes to events,
  * wires abort-signal handling, enforces a timeout, and provides idempotent
@@ -74,6 +110,7 @@ export interface RunWithLifecycleConfig<TResult> {
  *   it by calling `ctx.resolve(ctx.cleanup(...))` itself)
  * - `session.prompt()` rejects (resolves via `failedResult`)
  */
+// biome-ignore lint/complexity/noExcessiveLinesPerFunction: lifecycle ownership must remain in one state-machine closure
 export function runWithLifecycle<TResult>(
   config: RunWithLifecycleConfig<TResult>,
 ): Promise<TResult> {
@@ -99,6 +136,7 @@ export function runWithLifecycle<TResult>(
     aborting: false,
   };
   const teardownFns: (() => void)[] = [];
+  const lifecycleTrace = new ChildLifecycleTraceCollector(getRegisteredToolNames(session));
 
   const cancelTeardown = (): void => {
     for (const fn of teardownFns) {
@@ -132,18 +170,53 @@ export function runWithLifecycle<TResult>(
       progress,
       state,
       session,
+      getLifecycleTrace: () => lifecycleTrace.snapshot(),
+      getFailureDiagnostics: () =>
+        buildChildFailureDiagnostics({
+          progress,
+          session,
+          lifecycleTrace: lifecycleTrace.snapshot(),
+          recentActivity: lifecycleTrace.recentActivitySnapshot(),
+        }),
+      recordHostMarker: (marker) => lifecycleTrace.recordHostMarker(marker),
       addTeardown,
       startTime,
     };
 
+    let promptSettled = false;
+    let deferredAgentSettled: Extract<AgentSessionEvent, { type: "agent_settled" }> | undefined;
+
+    const dispatchEvent = (event: AgentSessionEvent): void => {
+      try {
+        onEvent(event, ctx);
+      } catch {
+        if (!state.settled && !state.aborting) {
+          resolve(cleanup(failedResult("unexpected-runner-failure", ctx)));
+        }
+      }
+    };
+
+    const flushDeferredSettlement = (): void => {
+      if (!deferredAgentSettled || state.settled || state.aborting) return;
+      const event = deferredAgentSettled;
+      deferredAgentSettled = undefined;
+      dispatchEvent(event);
+    };
+
     session.subscribe((event: AgentSessionEvent) => {
-      onEvent(event, ctx);
+      lifecycleTrace.observe(event);
+      if (event.type === "agent_settled" && !promptSettled) {
+        deferredAgentSettled = event;
+        return;
+      }
+      dispatchEvent(event);
     });
 
     // Abort signal handler
     const onAbort = () => {
       if (state.settled || state.aborting) return;
       state.aborting = true;
+      ctx.recordHostMarker({ type: "abort_requested", reason: "canceled" });
       void session
         .abort()
         .catch(() => {})
@@ -163,12 +236,18 @@ export function runWithLifecycle<TResult>(
     // Timeout handler
     const onTimeoutExpired = () => {
       if (state.settled || state.aborting) return;
+      ctx.recordHostMarker({ type: "timeout_expired" });
 
       if (onTimeout) {
-        onTimeout(ctx);
+        try {
+          onTimeout(ctx);
+        } catch {
+          resolve(cleanup(failedResult("unexpected-runner-failure", ctx)));
+        }
       } else {
         // Default: hard abort
         state.aborting = true;
+        ctx.recordHostMarker({ type: "abort_requested", reason: "timeout" });
         void session
           .abort()
           .catch(() => {})
@@ -181,11 +260,27 @@ export function runWithLifecycle<TResult>(
     timeoutId.unref?.();
     addTeardown(() => clearTimeout(timeoutId));
 
-    // Start the session
-    session.prompt(prompt).catch((error: unknown) => {
-      if (!state.settled) {
-        resolve(cleanup(failedResult(error instanceof Error ? error.message : String(error), ctx)));
-      }
+    // Start the session. Prompt rejection is a distinct host-owned outcome;
+    // caught provider or runner errors are intentionally never retained.
+    const rejectPrompt = () => {
+      if (state.settled || state.aborting) return;
+      ctx.recordHostMarker({ type: "prompt_rejected" });
+      resolve(cleanup(failedResult("prompt-rejected", ctx)));
+    };
+    const failUnexpectedly = () => {
+      promptSettled = true;
+      if (state.settled || state.aborting) return;
+      resolve(cleanup(failedResult("unexpected-runner-failure", ctx)));
+    };
+    startPrompt({
+      session,
+      prompt,
+      onPreflightRejected: rejectPrompt,
+      onUnexpectedFailure: failUnexpectedly,
+      onFulfilled: () => {
+        promptSettled = true;
+        flushDeferredSettlement();
+      },
     });
   });
 }

package/src/types.ts

@@ -1,4 +1,23 @@
 import type { Model } from "@earendil-works/pi-ai";
+import type { ChildLifecycleTrace } from "./tool/child-lifecycle-trace.ts";
+
+/** Closed, host-owned classification for a managed child failure. */
+export type ChildFailureCode =
+  | "session-creation-failed"
+  | "prompt-rejected"
+  | "missing-structured-output"
+  | "unexpected-runner-failure";
+
+/** Managed child role used for host-owned failure copy. */
+export type ChildStage = "brief-synthesis" | "reviewer";
+
+/** Failed child result fields with diagnostics required exactly when a child was observed. */
+export type ChildFailedResult =
+  | { failureCode: "session-creation-failed"; diagnostics?: never }
+  | {
+      failureCode: Exclude<ChildFailureCode, "session-creation-failed">;
+      diagnostics: ChildFailureDiagnostics;
+    };
 
 /** Inclusive 1-based line range reported by the reviewer. */
 export interface ReviewLineRange {
@@ -166,23 +185,17 @@ export type AgentReviewerResult =
       output: NormalizedReviewOutput;
       modelId: string;
     }
-  | {
-      kind: "failed";
-      reason: string;
-      modelId: string;
-      debug?: ReviewFailureDebugInfo;
-    }
+  | ({ kind: "failed"; modelId: string } & ChildFailedResult)
   | {
       kind: "canceled";
       modelId: string;
-      debug?: ReviewFailureDebugInfo;
+      diagnostics: ChildFailureDiagnostics;
     }
   | {
       kind: "timeout";
       timeoutMs: number;
-      partialOutput?: string;
       modelId: string;
-      debug?: ReviewFailureDebugInfo;
+      diagnostics: ChildFailureDiagnostics;
     };
 
 /** One normalized result from a focused reviewer child session. */
@@ -218,24 +231,6 @@ export interface ReviewPacket {
   charBudget: number;
 }
 
-/** Lightweight diagnostics attached to non-success review runs. */
-export interface ReviewFailureDebugInfo {
-  turns: number;
-  toolUses: number;
-  tokens?: {
-    input: number;
-    output: number;
-    total: number;
-    cacheRead?: number;
-    cacheWrite?: number;
-  };
-  recentEvents?: string[];
-  lastAssistantText?: string;
-  lastAssistantStopReason?: string;
-  lastAssistantErrorMessage?: string;
-  lastAssistantToolCalls?: string[];
-}
-
 /** Fully prepared review run. */
 export interface ReviewPlan {
   model: ReviewModelSelection;
@@ -253,29 +248,26 @@ export type RawReviewResult =
       brief?: SynthesizedReviewBrief;
       modelId: string;
     }
-  | {
+  | ({
       kind: "failed";
-      reason: string;
       snapshot: ReviewSnapshot;
       brief?: SynthesizedReviewBrief;
       modelId: string;
-      debug?: ReviewFailureDebugInfo;
-    }
+    } & ChildFailedResult)
   | {
       kind: "canceled";
       snapshot: ReviewSnapshot;
       brief?: SynthesizedReviewBrief;
       modelId: string;
-      debug?: ReviewFailureDebugInfo;
+      diagnostics: ChildFailureDiagnostics;
     }
   | {
       kind: "timeout";
       snapshot: ReviewSnapshot;
       timeoutMs: number;
-      partialOutput?: string;
       brief?: SynthesizedReviewBrief;
       modelId: string;
-      debug?: ReviewFailureDebugInfo;
+      diagnostics: ChildFailureDiagnostics;
     };
 
 /** Normalized result used by rendering and follow-up logic. */
@@ -289,6 +281,28 @@ export type ReviewResult =
     }
   | Extract<RawReviewResult, { kind: "failed" | "canceled" | "timeout" }>;
 
+/**
+ * Safe bounded diagnostics attached only to a non-success managed child run.
+ *
+ * The trace and Recent Activity lane contain only allowlisted control metadata;
+ * no child-generated text, caught error, or raw SDK event is retained.
+ */
+export interface ChildFailureDiagnostics {
+  lifecycleTrace: ChildLifecycleTrace;
+  turns: number;
+  toolUses: number;
+  tokens?: {
+    input: number;
+    output: number;
+    total: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+  };
+  recentActivity?: string[];
+  lastAssistantStopReason?: string;
+  lastAssistantToolCalls?: string[];
+}
+
 /** Progress state exposed by review/synthesis runners for widget integration. */
 export interface ReviewProgress {
   /** Number of agent turns completed. */
@@ -317,9 +331,9 @@ export interface ReviewProgress {
 
 export type BriefSynthesisRunResult =
   | { kind: "success"; brief: SynthesizedReviewBrief }
-  | { kind: "failed"; reason: string }
-  | { kind: "canceled" }
-  | { kind: "timeout"; timeoutMs: number };
+  | ({ kind: "failed" } & ChildFailedResult)
+  | { kind: "canceled"; diagnostics: ChildFailureDiagnostics }
+  | { kind: "timeout"; timeoutMs: number; diagnostics: ChildFailureDiagnostics };
 
 export interface BriefSynthesisInvocation {
   prompt: string;

package/src/ui/format-content.ts

@@ -1,4 +1,13 @@
-import type { ReviewFailureDebugInfo, ReviewItem, ReviewResult } from "../types.ts";
+import {
+  formatChildFailureCopy,
+  formatChildFailureDiagnostics,
+} from "../tool/child-failure-diagnostics.ts";
+import type {
+  BriefSynthesisRunResult,
+  ChildFailureDiagnostics,
+  ReviewItem,
+  ReviewResult,
+} from "../types.ts";
 
 /** Format a `impact` or `effort` level value. */
 export function formatLevel(value: ReviewItem["impact"] | ReviewItem["effort"]): string {
@@ -10,6 +19,29 @@ export function formatLocation(file: string, startLine: number, endLine: number)
   return `${file}:${startLine === endLine ? startLine : `${startLine}-${endLine}`}`;
 }
 
+/** Format one non-success brief-synthesis result for parent-facing custom-message content. */
+export function formatBriefSynthesisFailureContent(
+  result: Exclude<BriefSynthesisRunResult, { kind: "success" }>,
+): string {
+  const parts = [formatBriefSynthesisFailureCopy(result)];
+  appendChildFailureDiagnostics(parts, result.diagnostics);
+  return parts.join("\n");
+}
+
+/** Generate short static parent-facing copy for a brief-synthesis outcome. */
+export function formatBriefSynthesisFailureCopy(
+  result: Exclude<BriefSynthesisRunResult, { kind: "success" }>,
+): string {
+  switch (result.kind) {
+    case "failed":
+      return formatChildFailureCopy("brief-synthesis", result.failureCode);
+    case "canceled":
+      return "Brief synthesis was canceled.";
+    case "timeout":
+      return "Brief synthesis timed out.";
+  }
+}
+
 /** Format review results for the LLM-visible custom message content. */
 export function formatReviewContent(result: ReviewResult): string {
   switch (result.kind) {
@@ -25,26 +57,31 @@ export function formatReviewContent(result: ReviewResult): string {
 }
 
 function formatFailureContent(result: Extract<ReviewResult, { kind: "failed" }>): string {
-  const parts = [`Review failed: ${result.reason}`];
-  appendDebugContent(parts, result.debug);
+  const parts = [formatChildFailureCopy("reviewer", result.failureCode)];
+  appendChildFailureDiagnostics(parts, result.diagnostics);
   return parts.join("\n");
 }
 
 function formatCanceledContent(result: Extract<ReviewResult, { kind: "canceled" }>): string {
-  const parts = ["Review canceled"];
-  appendDebugContent(parts, result.debug);
+  const parts = ["Reviewer was canceled."];
+  appendChildFailureDiagnostics(parts, result.diagnostics);
   return parts.join("\n");
 }
 
 function formatTimeoutContent(result: Extract<ReviewResult, { kind: "timeout" }>): string {
-  const parts = [`Review timed out (exceeded ${(result.timeoutMs / 1000).toFixed(0)}s)`];
-  if (result.partialOutput) {
-    parts.push("", "Partial output:", result.partialOutput);
-  }
-  appendDebugContent(parts, result.debug);
+  const parts = ["Reviewer timed out."];
+  appendChildFailureDiagnostics(parts, result.diagnostics);
   return parts.join("\n");
 }
 
+function appendChildFailureDiagnostics(
+  parts: string[],
+  diagnostics: ChildFailureDiagnostics | undefined,
+): void {
+  if (!diagnostics) return;
+  parts.push("", "Diagnostics:", ...formatChildFailureDiagnostics(diagnostics));
+}
+
 function formatSuccessContent(result: Extract<ReviewResult, { kind: "success" }>): string {
   const { output } = result;
   const confidencePercent = Math.round(output.overall_confidence_score * 100);
@@ -81,34 +118,6 @@ function formatSuccessContent(result: Extract<ReviewResult, { kind: "success" }>
   return lines.join("\n");
 }
 
-function appendDebugContent(parts: string[], debug: ReviewFailureDebugInfo | undefined): void {
-  if (!debug) return;
-
-  const lines = [
-    `- Turns: ${debug.turns}`,
-    `- Tool uses: ${debug.toolUses}`,
-    debug.tokens
-      ? `- Tokens: ${debug.tokens.input} in / ${debug.tokens.output} out / ${debug.tokens.total} total`
-      : undefined,
-    debug.recentEvents && debug.recentEvents.length > 0
-      ? `- Recent events: ${debug.recentEvents.join(" → ")}`
-      : undefined,
-    debug.lastAssistantStopReason
-      ? `- Last assistant stop: ${debug.lastAssistantStopReason}`
-      : undefined,
-    debug.lastAssistantToolCalls && debug.lastAssistantToolCalls.length > 0
-      ? `- Last assistant tools: ${debug.lastAssistantToolCalls.join(", ")}`
-      : undefined,
-    debug.lastAssistantErrorMessage
-      ? `- Last assistant error: ${debug.lastAssistantErrorMessage}`
-      : undefined,
-  ].filter((line): line is string => !!line);
-
-  if (lines.length === 0) return;
-
-  parts.push("", "Debug:", ...lines);
-}
-
 function formatReviewItems(items: ReviewItem[]): string[] {
   return items.flatMap((item, index) => {
     const location = item.code_location

package/src/ui/renderer.ts

@@ -1,12 +1,38 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Box, Container, Spacer, Text } from "@earendil-works/pi-tui";
-import type { ReviewFailureDebugInfo, ReviewItem, ReviewResult } from "../types.ts";
-import { formatLevel, formatLocation } from "./format-content.ts";
+import {
+  formatChildFailureCopy,
+  formatChildFailureDiagnostics,
+} from "../tool/child-failure-diagnostics.ts";
+import type {
+  BriefSynthesisRunResult,
+  ChildFailureDiagnostics,
+  ReviewItem,
+  ReviewResult,
+  ReviewSnapshot,
+} from "../types.ts";
+import { formatBriefSynthesisFailureCopy, formatLevel, formatLocation } from "./format-content.ts";
 
 /** Register the custom TUI renderer for `supi-review` messages. */
+interface BriefSynthesisFailureMessage {
+  result: Exclude<BriefSynthesisRunResult, { kind: "success" }>;
+  snapshot: ReviewSnapshot;
+  modelId: string;
+}
+
+interface ReviewMessageDetails {
+  result?: ReviewResult;
+  briefSynthesisFailure?: BriefSynthesisFailureMessage;
+}
+
 export function registerReviewRenderer(pi: ExtensionAPI): void {
   pi.registerMessageRenderer("supi-review", (message, { expanded }, theme) => {
-    const result = (message.details as { result?: ReviewResult } | undefined)?.result;
+    const details = message.details as ReviewMessageDetails | undefined;
+    if (details?.briefSynthesisFailure) {
+      return renderBriefSynthesisFailure(details.briefSynthesisFailure, theme);
+    }
+
+    const result = details?.result;
     if (!result) {
       return new Text(theme.fg("dim", "No review data"), 1, 0);
     }
@@ -26,6 +52,31 @@ export function registerReviewRenderer(pi: ExtensionAPI): void {
   });
 }
 
+function renderBriefSynthesisFailure(
+  failure: BriefSynthesisFailureMessage,
+  theme: Parameters<Parameters<ExtensionAPI["registerMessageRenderer"]>[1]>[2],
+): Container {
+  const container = new Container();
+  const title =
+    failure.result.kind === "failed"
+      ? "◆ Brief Synthesis Failed"
+      : failure.result.kind === "timeout"
+        ? "◆ Brief Synthesis Timed Out"
+        : "◆ Brief Synthesis Canceled";
+  const color = failure.result.kind === "failed" ? "error" : "warning";
+
+  container.addChild(new Text(theme.fg(color, title), 1, 0));
+  container.addChild(new Spacer(1));
+  container.addChild(new Text(theme.fg("muted", `Model: ${failure.modelId}`), 1, 0));
+  container.addChild(new Text(theme.fg("muted", `Snapshot: ${failure.snapshot.title}`), 1, 0));
+  container.addChild(new Spacer(1));
+  container.addChild(
+    new Text(theme.fg(color, formatBriefSynthesisFailureCopy(failure.result)), 1, 0),
+  );
+  renderChildFailureDiagnostics(container, failure.result.diagnostics, theme);
+  return container;
+}
+
 function renderSuccess(
   result: Extract<ReviewResult, { kind: "success" }>,
   theme: Parameters<Parameters<ExtensionAPI["registerMessageRenderer"]>[1]>[2],
@@ -160,8 +211,10 @@ function renderFailed(
   container.addChild(new Text(theme.fg("muted", `Model: ${result.modelId}`), 1, 0));
   container.addChild(new Text(theme.fg("muted", `Snapshot: ${result.snapshot.title}`), 1, 0));
   container.addChild(new Spacer(1));
-  container.addChild(new Text(theme.fg("error", result.reason), 1, 0));
-  renderFailureDebug(container, result.debug, theme);
+  container.addChild(
+    new Text(theme.fg("error", formatChildFailureCopy("reviewer", result.failureCode)), 1, 0),
+  );
+  renderChildFailureDiagnostics(container, result.diagnostics, theme);
   return container;
 }
 
@@ -175,19 +228,8 @@ function renderTimeout(
   container.addChild(new Text(theme.fg("muted", `Model: ${result.modelId}`), 1, 0));
   container.addChild(new Text(theme.fg("muted", `Snapshot: ${result.snapshot.title}`), 1, 0));
   container.addChild(new Spacer(1));
-  container.addChild(
-    new Text(
-      theme.fg("warning", `Reviewer exceeded the ${(result.timeoutMs / 1000).toFixed(0)}s timeout`),
-      1,
-      0,
-    ),
-  );
-  if (result.partialOutput) {
-    container.addChild(new Spacer(1));
-    container.addChild(new Text(theme.fg("dim", "Partial output:"), 1, 0));
-    container.addChild(new Text(theme.fg("dim", result.partialOutput.slice(0, 500)), 1, 0));
-  }
-  renderFailureDebug(container, result.debug, theme);
+  container.addChild(new Text(theme.fg("warning", "Reviewer timed out."), 1, 0));
+  renderChildFailureDiagnostics(container, result.diagnostics, theme);
   return container;
 }
 
@@ -197,41 +239,21 @@ function renderCanceled(
 ): Container {
   const container = new Container();
   container.addChild(new Text(theme.fg("warning", "◆ Review Canceled"), 1, 0));
-  renderFailureDebug(container, result.debug, theme);
+  container.addChild(new Text(theme.fg("warning", "Reviewer was canceled."), 1, 0));
+  renderChildFailureDiagnostics(container, result.diagnostics, theme);
   return container;
 }
 
-function renderFailureDebug(
+function renderChildFailureDiagnostics(
   container: Container,
-  debug: ReviewFailureDebugInfo | undefined,
+  diagnostics: ChildFailureDiagnostics | undefined,
   theme: Parameters<Parameters<ExtensionAPI["registerMessageRenderer"]>[1]>[2],
 ): void {
-  if (!debug) return;
-
-  const lines = [
-    `Turns: ${debug.turns} · Tool uses: ${debug.toolUses}`,
-    debug.tokens
-      ? `Tokens: ${debug.tokens.input} in / ${debug.tokens.output} out / ${debug.tokens.total} total`
-      : undefined,
-    debug.recentEvents && debug.recentEvents.length > 0
-      ? `Recent events: ${debug.recentEvents.join(" → ")}`
-      : undefined,
-    debug.lastAssistantStopReason
-      ? `Last assistant stop: ${debug.lastAssistantStopReason}`
-      : undefined,
-    debug.lastAssistantToolCalls && debug.lastAssistantToolCalls.length > 0
-      ? `Last assistant tools: ${debug.lastAssistantToolCalls.join(", ")}`
-      : undefined,
-    debug.lastAssistantErrorMessage
-      ? `Last assistant error: ${debug.lastAssistantErrorMessage}`
-      : undefined,
-  ].filter((line): line is string => !!line);
-
-  if (lines.length === 0) return;
+  if (!diagnostics) return;
 
   container.addChild(new Spacer(1));
-  container.addChild(new Text(theme.fg("dim", "Debug:"), 1, 0));
-  for (const line of lines) {
+  container.addChild(new Text(theme.fg("dim", "Diagnostics:"), 1, 0));
+  for (const line of formatChildFailureDiagnostics(diagnostics)) {
     container.addChild(new Text(theme.fg("dim", line), 1, 0));
   }
 }

package/src/ui/review-tool-renderer.ts

@@ -1,6 +1,10 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Container, Spacer, Text } from "@earendil-works/pi-tui";
 import type { PrepareAgentReviewInput, RunAgentReviewInput } from "../tool/agent-review-schemas.ts";
+import {
+  formatChildFailureCopy,
+  formatChildFailureDiagnostics,
+} from "../tool/child-failure-diagnostics.ts";
 import type {
   AgentReviewBatchDetails,
   PreparedAgentReviewDetails,
@@ -150,6 +154,7 @@ export function renderRunReviewResult(
   }
 
   if (expanded) {
+    renderReviewerDiagnostics(container, details, theme);
     container.addChild(new Spacer(1));
     for (const line of formatCritique(details.evaluation.critique)) {
       container.addChild(new Text(theme.fg("dim", line), 0, 0));
@@ -165,6 +170,28 @@ export function renderRunReviewResult(
   return container;
 }
 
+function renderReviewerDiagnostics(
+  container: Container,
+  details: AgentReviewBatchDetails,
+  theme: ReviewTheme,
+): void {
+  if (
+    !details.results.some((entry) => entry.result.kind !== "success" && entry.result.diagnostics)
+  ) {
+    return;
+  }
+
+  container.addChild(new Spacer(1));
+  container.addChild(new Text(theme.fg("accent", "Reviewer diagnostics"), 0, 0));
+  for (const { assignment, result } of details.results) {
+    if (result.kind === "success" || !result.diagnostics) continue;
+    container.addChild(new Text(theme.fg("muted", `${assignment.id}:`), 0, 0));
+    for (const line of formatChildFailureDiagnostics(result.diagnostics)) {
+      container.addChild(new Text(theme.fg("dim", line), 0, 0));
+    }
+  }
+}
+
 function renderProgress(details: AgentReviewProgressDetails, theme: ReviewTheme): Text {
   if (details.phase === "prepare") {
     return new Text(theme.fg("warning", "Synthesizing review brief…"), 0, 0);
@@ -189,7 +216,11 @@ function summarizeResult(result: AgentReviewBatchDetails["results"][number]["res
         text: `${result.output.items.length} item(s), ${result.output.overall_correctness}`,
       };
     case "failed":
-      return { icon: "✗", color: "error", text: result.reason };
+      return {
+        icon: "✗",
+        color: "error",
+        text: formatChildFailureCopy("reviewer", result.failureCode),
+      };
     case "canceled":
       return { icon: "○", color: "warning", text: "canceled" };
     case "timeout":