@mrclrchtr/supi-review 2.6.1 → 2.8.0

package/src/tool/review-runner.ts

@@ -6,7 +6,7 @@ import {
   SessionManager,
 } from "@earendil-works/pi-coding-agent";
 import type { RawReviewResult, ReviewInvocation, ReviewOutputEvent } from "../types.ts";
-import { buildFailureDebug, extractLastAssistantDebug } from "./review-debug.ts";
+import { createEarlyCancellationDiagnostics } from "./child-failure-diagnostics.ts";
 import {
   createSubmitReviewTool,
   handleSessionEvent,
@@ -69,16 +69,12 @@ function buildTimeoutResult(
   runner: ReviewerRunnerState,
 ): RawReviewResult {
   return {
-    kind: "timeout" as const,
+    kind: "timeout",
     snapshot: runner.invocation.snapshot,
     timeoutMs: runner.invocation.timeoutMs ?? DEFAULT_TIMEOUT_MS,
     brief: runner.invocation.brief,
     modelId: runner.invocation.model.canonicalId,
-    debug: buildFailureDebug({
-      progress: lcCtx.progress,
-      session: lcCtx.session,
-      recentEvents: runner.debug.recentEvents,
-    }),
+    diagnostics: lcCtx.getFailureDiagnostics(),
   };
 }
 
@@ -87,34 +83,26 @@ function buildCanceledResult(
   runner: ReviewerRunnerState,
 ): RawReviewResult {
   return {
-    kind: "canceled" as const,
+    kind: "canceled",
     snapshot: runner.invocation.snapshot,
     brief: runner.invocation.brief,
     modelId: runner.invocation.model.canonicalId,
-    debug: buildFailureDebug({
-      progress: lcCtx.progress,
-      session: lcCtx.session,
-      recentEvents: runner.debug.recentEvents,
-    }),
+    diagnostics: lcCtx.getFailureDiagnostics(),
   };
 }
 
 function buildFailedResult(
-  reason: string,
+  failureCode: "prompt-rejected" | "unexpected-runner-failure",
   lcCtx: LifecycleCtx<RawReviewResult>,
   runner: ReviewerRunnerState,
 ): RawReviewResult {
   return {
-    kind: "failed" as const,
-    reason,
+    kind: "failed",
+    failureCode,
     snapshot: runner.invocation.snapshot,
     brief: runner.invocation.brief,
     modelId: runner.invocation.model.canonicalId,
-    debug: buildFailureDebug({
-      progress: lcCtx.progress,
-      session: lcCtx.session,
-      recentEvents: runner.debug.recentEvents,
-    }),
+    diagnostics: lcCtx.getFailureDiagnostics(),
   };
 }
 
@@ -124,49 +112,43 @@ interface ReviewerRunnerState {
   submitSteered: boolean;
   timeoutSteered: boolean;
   graceTurnsRemaining: number | undefined;
-  debug: { recentEvents: string[] };
 }
 
 // ---------------------------------------------------------------------------
 // Steer / abort helpers
 // ---------------------------------------------------------------------------
 
-/** Abort the session and resolve with a timeout result (from lifecycle context). */
+/** Abort the session and resolve with a timeout result from the lifecycle context. */
 function doFinalAbortFromLifecycle(
   lcCtx: LifecycleCtx<RawReviewResult>,
   runner: ReviewerRunnerState,
 ): void {
+  if (lcCtx.state.settled || lcCtx.state.aborting) return;
+
   lcCtx.state.aborting = true;
+  lcCtx.recordHostMarker({ type: "abort_requested", reason: "timeout" });
   void lcCtx.session
     .abort()
     .catch(() => {})
     .finally(() => {
-      const partialText = extractLastAssistantDebug(lcCtx.session)?.text;
       lcCtx.resolve(
         lcCtx.cleanup({
-          kind: "timeout" as const,
+          kind: "timeout",
           snapshot: runner.invocation.snapshot,
           timeoutMs: runner.invocation.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-          partialOutput: partialText,
           brief: runner.invocation.brief,
           modelId: runner.invocation.model.canonicalId,
-          debug: buildFailureDebug({
-            progress: lcCtx.progress,
-            session: lcCtx.session,
-            recentEvents: runner.debug.recentEvents,
-          }),
+          diagnostics: lcCtx.getFailureDiagnostics(),
         }),
       );
     });
 }
 
 /**
- * Build the custom `onTimeout` handler for the review runner.
+ * Build the custom soft-timeout behavior for reviewer sessions.
  *
- * When the soft timeout fires, the handler:
- * 1. Steers the reviewer session to wrap up
- * 2. Starts a grace timer (hard abort after GRACE_TURNS or HARD_ABORT_GRACE_MS)
- * 3. If steer fails, immediately hard-aborts
+ * The shared lifecycle runner records `timeout_expired`; this runner adds a
+ * timeout steering marker and later records the hard-abort marker if needed.
  */
 function buildReviewTimeoutHandler(
   runner: ReviewerRunnerState,
@@ -174,9 +156,9 @@ function buildReviewTimeoutHandler(
 ): void {
   runner.timeoutSteered = true;
   runner.graceTurnsRemaining = GRACE_TURNS;
+  lcCtx.recordHostMarker({ type: "steer_requested", reason: "timeout" });
 
   const hardAbortTimer = setTimeout(() => {
-    if (lcCtx.state.settled) return;
     doFinalAbortFromLifecycle(lcCtx, runner);
   }, HARD_ABORT_GRACE_MS);
   hardAbortTimer.unref?.();
@@ -199,7 +181,6 @@ function buildRunnerCtx(runner: ReviewerRunnerState): RunnerContext {
   ctx.submitSteered = runner.submitSteered;
   ctx.timeoutSteered = runner.timeoutSteered;
   ctx.graceTurnsRemaining = runner.graceTurnsRemaining;
-  ctx.debug = runner.debug;
   ctx.toolCounts = {};
   ctx.inspectedFiles = new Set();
   return ctx;
@@ -216,6 +197,8 @@ function syncCtxFromLifecycle(
   ctx.cleanup = lcCtx.cleanup;
   ctx.state = lcCtx.state;
   ctx.startTime = lcCtx.startTime;
+  ctx.getFailureDiagnostics = lcCtx.getFailureDiagnostics;
+  ctx.recordHostMarker = lcCtx.recordHostMarker;
   ctx.submitSteered = runner.submitSteered;
   ctx.timeoutSteered = runner.timeoutSteered;
   ctx.graceTurnsRemaining = runner.graceTurnsRemaining;
@@ -239,6 +222,7 @@ export async function runReviewer(invocation: ReviewInvocation): Promise<RawRevi
       snapshot: invocation.snapshot,
       brief: invocation.brief,
       modelId: invocation.model.canonicalId,
+      diagnostics: createEarlyCancellationDiagnostics(),
     };
   }
 
@@ -255,10 +239,10 @@ export async function runReviewer(invocation: ReviewInvocation): Promise<RawRevi
       snapshotDiffTool,
       snapshotFileTool,
     );
-  } catch (error) {
+  } catch {
     return {
       kind: "failed",
-      reason: `Failed to create reviewer session: ${error instanceof Error ? error.message : String(error)}`,
+      failureCode: "session-creation-failed",
       snapshot: invocation.snapshot,
       brief: invocation.brief,
       modelId: invocation.model.canonicalId,
@@ -271,9 +255,7 @@ export async function runReviewer(invocation: ReviewInvocation): Promise<RawRevi
     submitSteered: false,
     timeoutSteered: false,
     graceTurnsRemaining: undefined,
-    debug: { recentEvents: [] },
   };
-
   const ctx = buildRunnerCtx(runner);
 
   return runWithLifecycle<RawReviewResult>({
@@ -288,7 +270,7 @@ export async function runReviewer(invocation: ReviewInvocation): Promise<RawRevi
     },
     onTimeout: (lcCtx) => buildReviewTimeoutHandler(runner, lcCtx),
     canceledResult: (lcCtx) => buildCanceledResult(lcCtx, runner),
-    failedResult: (reason, lcCtx) => buildFailedResult(reason, lcCtx, runner),
+    failedResult: (failureCode, lcCtx) => buildFailedResult(failureCode, lcCtx, runner),
     timeoutResult: (_, lcCtx) => buildTimeoutResult(lcCtx, runner),
   });
 }

package/src/tool/runner-helpers.ts

@@ -5,20 +5,6 @@
  * eliminate duplication.
  */
 
-/** Extract the last assistant text from a session's message history. */
-export function extractLastAssistantText(
-  messages: ArrayLike<unknown> | undefined,
-): string | undefined {
-  if (!messages) return undefined;
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const message = messages[i] as { role?: string; content?: unknown } | undefined;
-    if (message?.role !== "assistant") continue;
-    const text = extractAssistantText(message.content);
-    if (text) return text;
-  }
-  return undefined;
-}
-
 /** Extract text content from a message content value (string | content-part[]). */
 export function extractAssistantText(content: unknown): string | undefined {
   if (typeof content === "string") {

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