Summary

Addresses #82961.

Current runAgentCleanupStep timeout warning is just the envelope:

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

It 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.

Fix

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

let diagnostic: string | undefined;
try {
  diagnostic = params.getCleanupDiagnostic?.();
} catch (error) {
  diagnostic = `diagnosticError=${formatErrorMessage(error)}`;
}
const diagnosticSuffix = diagnostic ? ` ${diagnostic}` : "";
params.log.warn(`agent cleanup timed out: ... timeoutMs=${timeoutMs}${diagnosticSuffix}`);

Wire the trajectory caller (src/agents/pi-embedded-runner/run/attempt.ts:4485) to pass a probe that reports whether the trajectory recorder was constructed for the attempt — minimal at this stage; full queued-writer counters (queuedWrites / queuedBytes / activeOp / appendSize) require TrajectoryRuntimeRecorder to expose those fields, which is a follow-up refactor that plugs into the new hook trivially.

Real behavior proof

--- OLD warning (no diagnostic):
  warn> agent cleanup timed out: runId=run-123 sessionId=sess-456 step=pi-trajectory-flush timeoutMs=10000

--- NEW warning (no recorder constructed):
  warn> agent cleanup timed out: runId=run-123 sessionId=sess-456 step=pi-trajectory-flush timeoutMs=10000 writer=none

--- NEW warning (recorder present):
  warn> agent cleanup timed out: runId=run-123 sessionId=sess-456 step=pi-trajectory-flush timeoutMs=10000 writer=present recorderType=runtime

--- NEW warning (probe itself threw):
  warn> agent cleanup timed out: runId=run-123 sessionId=sess-456 step=pi-trajectory-flush timeoutMs=10000 diagnosticError=boom

Behaviour

• No callback → byte-identical warning to before this PR (full backward compat for every other runAgentCleanupStep caller).
• Callback returns string → appended after timeoutMs=....
• Callback throws → message is captured as diagnosticError=...; the timeout warning itself never fails.
• Success path unchanged.

Scope

Two-file diff. The hook is general enough for any future cleanup step (bundle-mcp-retire, etc.) to plug into; only pi-trajectory-flush is wired now per the issue's scope.

Follow-up (out of scope)

TrajectoryRuntimeRecorder.diagnosticString?(): string to expose queuedBytes / queuedWrites / activeOp / appendSize / acceptedRuntimeBytes / droppedEvents. Trivial to plug in once that interface lands — just call the recorder method inside the existing getCleanupDiagnostic closure in attempt.ts. Happy to do that as a separate PR.