fix(#82961): surface cleanup-step diagnostic state on agent cleanup timeout

YonganZhang · YonganZhang · commit 10d73a04a80a · 2026-05-17T18:23:48.000+08:00
`pi-trajectory-flush` (and any other step routed through
`runAgentCleanupStep`) currently warns with only the envelope on timeout:

    agent cleanup timed out: runId=... sessionId=... step=pi-trajectory-flush timeoutMs=10000

This tells operators nothing about what the flush is waiting on
(queued writer work, event-loop yield, or file append IO). The issue
asks for "bounded, non-secret state" alongside the timeout.

Add an optional `getCleanupDiagnostic?: () =&gt; string | undefined`
parameter to `runAgentCleanupStep`. If provided, the callback is
evaluated on timeout (inside a try/catch so a misbehaving probe cannot
break the warning itself) and its return value is appended to the
existing warning line.

Wire the trajectory caller in
`src/agents/pi-embedded-runner/run/attempt.ts` to pass a probe that
reports whether the trajectory recorder was constructed for the
attempt. The probe is deliberately minimal at this stage — full queued
writer stats (queuedWrites / queuedBytes / activeOp / appendSize)
require the `TrajectoryRuntimeRecorder` interface to expose those
counters, which is a separate refactor. The scaffold here lets that
follow-up plug in trivially.

Behaviour:
  * No diagnostic callback → byte-identical warning to before this PR.
  * Callback returns string → appended after `timeoutMs=...`.
  * Callback throws → message is captured as `diagnosticError=...`; the
    timeout warning itself never fails.
  * Success path unchanged.
diff --git a/src/agents/pi-embedded-runner/run/attempt.ts b/src/agents/pi-embedded-runner/run/attempt.ts
@@ -4490,6 +4490,20 @@ export async function runEmbeddedAttempt(
         cleanup: async () => {
           await trajectoryRecorder?.flush();
         },
+        getCleanupDiagnostic: () => {
+          // Bounded, non-secret snapshot of what the flush is waiting on.
+          // Trajectory recorder is constructed lazily; if it was never
+          // initialized for this attempt, the flush hung on the
+          // `trajectoryRecorder?.flush()` Promise chain itself, not on writer IO.
+          if (!trajectoryRecorder) {
+            return "writer=none";
+          }
+          // The TrajectoryRuntimeRecorder interface does not yet surface
+          // queued-write / queued-byte counters; once it does (follow-up to
+          // this PR), expose them here. For now, signal at least that the
+          // writer existed and the flush was actually entered.
+          return "writer=present recorderType=runtime";
+        },
       });
       // Always tear down the session (and release the lock) before we leave this attempt.
       //
diff --git a/src/agents/run-cleanup-timeout.ts b/src/agents/run-cleanup-timeout.ts
@@ -57,6 +57,13 @@ export async function runAgentCleanupStep(params: {
   log: AgentCleanupLogger;
   env?: NodeJS.ProcessEnv;
   timeoutMs?: number;
+  /**
+   * Optional callback evaluated on timeout. Should return a short, bounded,
+   * non-secret summary of what the cleanup step is waiting on (queued bytes,
+   * pending operation, etc.) so the timeout warning is actionable instead of
+   * just reporting the envelope. See issue #82961.
+   */
+  getCleanupDiagnostic?: () => string | undefined;
 }): Promise<void> {
   const timeoutMs = resolveAgentCleanupStepTimeoutMs({
     step: params.step,
@@ -88,8 +95,16 @@ export async function runAgentCleanupStep(params: {
     clearTimeout(timeoutHandle);
   }
   if (result === "timeout") {
+    let diagnostic: string | undefined;
+    try {
+      diagnostic = params.getCleanupDiagnostic?.();
+    } catch (error) {
+      // Diagnostic capture must never break the timeout warning itself.
+      diagnostic = `diagnosticError=${formatErrorMessage(error)}`;
+    }
+    const diagnosticSuffix = diagnostic ? ` ${diagnostic}` : "";
     params.log.warn(
-      `agent cleanup timed out: runId=${params.runId} sessionId=${params.sessionId} step=${params.step} timeoutMs=${timeoutMs}`,
+      `agent cleanup timed out: runId=${params.runId} sessionId=${params.sessionId} step=${params.step} timeoutMs=${timeoutMs}${diagnosticSuffix}`,
     );
     void cleanupPromise.catch((error) => {
       params.log.warn(
