@tonyclaw/agent-inspector 3.1.4 → 3.1.5

package/src/components/proxy-viewer/LogEntry.tsx

@@ -85,6 +85,7 @@ const FULL_LOG_HYDRATION_TIMEOUT_MS = 15_000;
 const BODY_CHUNK_TIMEOUT_MS = 15_000;
 const BODY_CHUNK_BYTES = 256 * 1024;
 const CHUNKED_BODY_THRESHOLD_BYTES = 1024 * 1024;
+const COLLAPSED_BODY_ANALYSIS_THRESHOLD_BYTES = 256 * 1024;
 
 const TAB_TRIGGER_CLASS =
   "h-9 flex-none rounded-md border border-transparent bg-transparent px-3 text-xs font-semibold text-muted-foreground shadow-none transition-colors hover:bg-white/[0.045] hover:text-foreground data-[state=active]:bg-cyan-300/[0.08] data-[state=active]:text-cyan-100 data-[state=active]:shadow-none";
@@ -104,6 +105,10 @@ function bodyByteCount(value: number | null | undefined): number {
   return value ?? 0;
 }
 
+function bodySizeForAnalysis(body: string | null, byteCount: number | null | undefined): number {
+  return byteCount ?? body?.length ?? 0;
+}
+
 function isCompactBody(log: CapturedLog): boolean {
   return log.bodyContentMode === "compact" || log.bodyContentMode === "truncated";
 }
@@ -120,6 +125,51 @@ function shouldHydrateLogBody(log: CapturedLog): boolean {
   return isCompactBody(log) && !shouldUseChunkedBodyLoading(log);
 }
 
+function shouldAnalyzeLogBodies(log: CapturedLog, expanded: boolean): boolean {
+  if (expanded) return true;
+  if (isCompactBody(log)) return false;
+  return (
+    bodySizeForAnalysis(log.rawRequestBody, log.rawRequestBodyBytes) <=
+      COLLAPSED_BODY_ANALYSIS_THRESHOLD_BYTES &&
+    bodySizeForAnalysis(log.responseText, log.responseTextBytes) <=
+      COLLAPSED_BODY_ANALYSIS_THRESHOLD_BYTES
+  );
+}
+
+function tabNeedsBodyHydration(tab: string): boolean {
+  switch (tab) {
+    case "request":
+    case "raw-request":
+    case "anatomy":
+    case "raw":
+    case "parsed":
+      return true;
+    case "headers":
+    case "raw-headers":
+    case "sse":
+      return false;
+    default:
+      return false;
+  }
+}
+
+function tabNeedsParsedRequest(tab: string): boolean {
+  switch (tab) {
+    case "request":
+    case "anatomy":
+      return true;
+    case "headers":
+    case "raw-headers":
+    case "raw-request":
+    case "raw":
+    case "parsed":
+    case "sse":
+      return false;
+    default:
+      return false;
+  }
+}
+
 function bodyPreviewErrorMessage(error: unknown): string {
   if (error instanceof ApiTimeoutError) {
     return "Body preview timed out. The log is still available on disk; try loading again.";
@@ -298,6 +348,51 @@ function BodyPreviewNotice({
   );
 }
 
+function SseInlineNotice({
+  error,
+  onOpenSse,
+}: {
+  error: string | null | undefined;
+  onOpenSse: () => void;
+}): JSX.Element | null {
+  if (error === undefined || error === null) return null;
+  return (
+    <NoticeBlock tone="danger" title="SSE Error">
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <span className="font-mono">{error}</span>
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          className="border border-input bg-background hover:bg-accent hover:text-accent-foreground h-7 text-xs text-rose-100"
+          onClick={onOpenSse}
+        >
+          View SSE
+        </Button>
+      </div>
+    </NoticeBlock>
+  );
+}
+
+function SseChunksNotice({ onOpenSse }: { onOpenSse: () => void }): JSX.Element {
+  return (
+    <NoticeBlock tone="loading" title="SSE chunks">
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <span>Streaming chunks are available in the SSE tab.</span>
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          className="border border-input bg-background hover:bg-accent hover:text-accent-foreground h-7 text-xs text-cyan-100"
+          onClick={onOpenSse}
+        >
+          View SSE
+        </Button>
+      </div>
+    </NoticeBlock>
+  );
+}
+
 function HeaderRows({
   headers,
   emptyLabel,
@@ -454,6 +549,7 @@ export const LogEntry = memo(function ({
   const requestJsonRef = useRef<HTMLDivElement | null>(null);
   const logIdRef = useRef(log.id);
   const bodyHydrationInFlightRef = useRef(false);
+  const userSelectedTabRef = useRef(false);
   const displayLog = hydratedLog ?? log;
   const useChunkedBody = hydratedLog === null && shouldUseChunkedBodyLoading(log);
   const fullBodyHydrationFootprint = useMemo(
@@ -476,13 +572,14 @@ export const LogEntry = memo(function ({
       bodyByteCount(responsePreview.totalBytes) <= CHUNKED_BODY_THRESHOLD_BYTES);
   const resolvedFormat = resolveLogFormat(displayLog);
   const adapter = getLogFormatAdapter(resolvedFormat);
+  const analyzeBodies = shouldAnalyzeLogBodies(displayLog, expanded);
   const requestAnalysis = useMemo(
-    () => adapter.analyzeRequest(displayLog.rawRequestBody),
-    [adapter, displayLog.rawRequestBody],
+    () => adapter.analyzeRequest(analyzeBodies ? displayLog.rawRequestBody : null),
+    [adapter, analyzeBodies, displayLog.rawRequestBody],
   );
   const responseAnalysis = useMemo(
-    () => adapter.analyzeResponse(displayLog.responseText),
-    [adapter, displayLog.responseText],
+    () => adapter.analyzeResponse(analyzeBodies ? displayLog.responseText : null),
+    [adapter, analyzeBodies, displayLog.responseText],
   );
   const strippedRequestBody = useMemo(() => {
     if (!strip || resolvedFormat !== "anthropic" || displayLog.rawRequestBody === null) {
@@ -492,7 +589,9 @@ export const LogEntry = memo(function ({
   }, [displayLog.rawRequestBody, resolvedFormat, strip]);
   const displayedRequestBody = strippedRequestBody ?? rawRequestBodyForView;
   const requestExpansion = useJsonBulkExpansion(
-    requestPreviewShouldParse ? displayedRequestBody : null,
+    expanded && tabNeedsParsedRequest(activeTab) && requestPreviewShouldParse
+      ? displayedRequestBody
+      : null,
   );
   const rawRequestExpansion = useJsonBulkExpansion(
     activeTab === "raw-request" && requestPreviewShouldParse ? rawRequestBodyForView : null,
@@ -500,6 +599,7 @@ export const LogEntry = memo(function ({
   const responseExpansion = useJsonBulkExpansion(
     activeTab === "raw" && responsePreviewShouldParse ? responseTextForView : null,
   );
+  const parsedRequestForSummary = requestExpansion.parsedData ?? requestAnalysis.parsed;
 
   // Headers are rendered as a flat list, so we copy them as pretty-printed JSON.
   // Only build the string when there's at least one entry; empty headers would
@@ -653,14 +753,12 @@ export const LogEntry = memo(function ({
   );
   const anatomySegments = useMemo(
     () =>
-      requestExpansion.parsedData !== null
-        ? adapter.anatomySegments(requestExpansion.parsedData)
-        : null,
-    [adapter, requestExpansion.parsedData],
+      parsedRequestForSummary !== null ? adapter.anatomySegments(parsedRequestForSummary) : null,
+    [adapter, parsedRequestForSummary],
   );
   const requestTools = useMemo(
-    () => parseRequestTools(requestExpansion.parsedData),
-    [requestExpansion.parsedData],
+    () => parseRequestTools(parsedRequestForSummary),
+    [parsedRequestForSummary],
   );
   const warnings = displayLog.warnings ?? [];
   const anatomyPaths = useMemo(() => {
@@ -671,7 +769,10 @@ export const LogEntry = memo(function ({
     containerRef: requestJsonRef,
     setExpandToPath,
     ensureTabActive: () => {
-      if (activeTab !== "request") setActiveTab("request");
+      if (activeTab !== "request") {
+        userSelectedTabRef.current = true;
+        setActiveTab("request");
+      }
     },
   });
   const loadBodyChunk = useCallback(
@@ -728,11 +829,22 @@ export const LogEntry = memo(function ({
   const handleToggleExpanded = useCallback(() => {
     const nextExpanded = !expanded;
     if (nextExpanded) {
+      userSelectedTabRef.current = false;
       setActiveTab(anatomySegments !== null ? "anatomy" : "request");
     }
     setExpanded(nextExpanded);
   }, [anatomySegments, expanded]);
 
+  const openSseTab = useCallback(() => {
+    userSelectedTabRef.current = true;
+    setActiveTab("sse");
+  }, []);
+
+  const handleTabChange = useCallback((value: string) => {
+    userSelectedTabRef.current = true;
+    setActiveTab(value);
+  }, []);
+
   useEffect(() => {
     logIdRef.current = log.id;
     bodyHydrationInFlightRef.current = false;
@@ -740,12 +852,22 @@ export const LogEntry = memo(function ({
     setBodyHydrationStatus("idle");
     setBodyHydrationError(null);
     setBodyHydrationRetryNonce(0);
+    userSelectedTabRef.current = false;
     setRequestPreview(createEmptyBodyPreviewState(log.rawRequestBodyBytes ?? null));
     setResponsePreview(createEmptyBodyPreviewState(log.responseTextBytes ?? null));
   }, [log.id, log.rawRequestBodyBytes, log.responseTextBytes]);
 
   useEffect(() => {
     if (!expanded) return;
+    if (userSelectedTabRef.current) return;
+    if (activeTab !== "request") return;
+    if (anatomySegments === null) return;
+    setActiveTab("anatomy");
+  }, [activeTab, anatomySegments, expanded]);
+
+  useEffect(() => {
+    if (!expanded) return;
+    if (!tabNeedsBodyHydration(activeTab)) return;
     if (!shouldHydrateLogBody(log)) return;
     if (hydratedLog !== null || bodyHydrationInFlightRef.current) return;
 
@@ -777,6 +899,7 @@ export const LogEntry = memo(function ({
       bodyHydrationInFlightRef.current = false;
     };
   }, [
+    activeTab,
     expanded,
     hydratedLog,
     log.bodyContentMode,
@@ -808,6 +931,7 @@ export const LogEntry = memo(function ({
       if (request === null) return;
       if (request.logId !== log.id) return;
       setExpanded(true);
+      userSelectedTabRef.current = true;
       setActiveTab(resolveFocusedTab(request.tab, anatomySegments));
       if (request.tab === "response" && request.toolCallIndex !== undefined) {
         setFocusedToolIndex(request.toolCallIndex);
@@ -865,7 +989,7 @@ export const LogEntry = memo(function ({
               aria-hidden="true"
             />
             <LazyFeatureBoundary feature="Log details">
-              <Tabs value={activeTab} onValueChange={setActiveTab} className="gap-2">
+              <Tabs value={activeTab} onValueChange={handleTabChange} className="gap-2">
                 <TabsList
                   variant="line"
                   className="bg-white/[0.04] inspector-scrollbar relative mx-3 h-auto w-[calc(100%-1.5rem)] justify-start overflow-x-auto rounded-[8px] p-1"
@@ -908,6 +1032,11 @@ export const LogEntry = memo(function ({
                   <TabsTrigger className={TAB_TRIGGER_CLASS} value="parsed">
                     Response
                   </TabsTrigger>
+                  {displayLog.streaming === true && (
+                    <TabsTrigger className={TAB_TRIGGER_CLASS} value="sse">
+                      SSE
+                    </TabsTrigger>
+                  )}
                 </TabsList>
 
                 {shouldShowRawRequestTab(resolvedFormat, viewMode, strip) && (
@@ -1109,11 +1238,7 @@ export const LogEntry = memo(function ({
                           onLoadMore={() => loadBodyChunk("response", responsePreview.offset)}
                         />
                       )}
-                      {displayLog.error !== undefined && displayLog.error !== null && (
-                        <NoticeBlock tone="danger" title="SSE Error">
-                          <span className="font-mono">{displayLog.error}</span>
-                        </NoticeBlock>
-                      )}
+                      <SseInlineNotice error={displayLog.error} onOpenSse={openSseTab} />
                       {responseTextForView !== null && responsePreviewShouldParse ? (
                         <Suspense fallback={<TabFallback />}>
                           <LazyJsonViewerFromString
@@ -1130,17 +1255,30 @@ export const LogEntry = memo(function ({
                           {useChunkedBody ? "Response preview is loading" : "No response"}
                         </EmptyState>
                       )}
-                      {displayLog.streaming === true && (
+                      {displayLog.streaming === true && <SseChunksNotice onOpenSse={openSseTab} />}
+                    </ExpandedPanel>
+                  )}
+                </TabsContent>
+
+                {displayLog.streaming === true && (
+                  <TabsContent value="sse">
+                    {activeTab === "sse" && (
+                      <ExpandedPanel className="space-y-3">
+                        {displayLog.error !== undefined && displayLog.error !== null && (
+                          <NoticeBlock tone="danger" title="SSE Error">
+                            <span className="font-mono">{displayLog.error}</span>
+                          </NoticeBlock>
+                        )}
                         <Suspense fallback={<TabFallback />}>
                           <LazyStreamingChunkSequence
                             logId={displayLog.id}
                             truncated={displayLog.streamingChunksPath !== null}
                           />
                         </Suspense>
-                      )}
-                    </ExpandedPanel>
-                  )}
-                </TabsContent>
+                      </ExpandedPanel>
+                    )}
+                  </TabsContent>
+                )}
 
                 <TabsContent value="parsed">
                   {activeTab === "parsed" && (
@@ -1159,6 +1297,7 @@ export const LogEntry = memo(function ({
                           onLoadMore={() => loadBodyChunk("response", responsePreview.offset)}
                         />
                       )}
+                      <SseInlineNotice error={displayLog.error} onOpenSse={openSseTab} />
                       {responsePreviewIsActive && !responsePreviewShouldParse ? (
                         <RawTextBlock>{responseTextForView}</RawTextBlock>
                       ) : (
@@ -1172,7 +1311,6 @@ export const LogEntry = memo(function ({
                             cacheCreationInputTokens={displayLog.cacheCreationInputTokens}
                             cacheReadInputTokens={displayLog.cacheReadInputTokens}
                             apiFormat={resolvedFormat}
-                            error={displayLog.error}
                             focusedToolIndex={focusedToolIndex}
                             toolFocusNonce={toolFocusNonce}
                           />

package/src/contracts/log.ts

@@ -23,6 +23,7 @@ export const CaptureIncompleteReasonSchema = z.enum([
   "pipeline-closed",
   "write-failed",
   "finalize-failed",
+  "finalize-timeout",
   "upstream-stream-error",
   "shutdown",
 ]);

package/src/proxy/handler.ts

@@ -27,6 +27,8 @@ import { safeFetch } from "../lib/safeFetch";
 const ALLOW_LOOPBACK = process.env["AGENT_INSPECTOR_ALLOW_LOOPBACK"] === "1";
 const EMPTY_UPSTREAM_BODY_ERROR = "Upstream response did not include a body";
 const UPSTREAM_STREAM_ERROR = "Upstream stream terminated unexpectedly";
+const UPSTREAM_REQUEST_FAILED = "Proxy error: upstream request failed";
+const HEADER_ERROR_CODE = "x-agent-inspector-error-code";
 import { stripClaudeCodeBillingHeader } from "../lib/claudeCodeStrip";
 import { stripOpenAIOrphanToolMessages } from "./openaiOrphanToolStrip";
 import { maskApiKey } from "../lib/mask";
@@ -140,29 +142,37 @@ function configuredProviderUrlFields(provider: ProviderConfig): string[] {
   return fields;
 }
 
-function logUnsupportedProviderRoute(
+type UnsupportedProviderRoute = {
+  code: "request-model-missing" | "provider-not-found" | "provider-route-mismatch";
+  detail: string;
+};
+
+function unsupportedProviderRoute(
   model: string | null,
   route: ReturnType<typeof describeApiRoute>,
   provider: ProviderConfig | null,
-): void {
+): UnsupportedProviderRoute {
   if (model === null) {
-    logger.warn(
-      `[handler] Unsupported provider route: model could not be extracted; path=${route.normalizedPath}; protocol=${protocolLabel(route)}`,
-    );
-    return;
+    const detail = `model could not be extracted; path=${route.normalizedPath}; protocol=${protocolLabel(route)}`;
+    logger.warn(`[handler] Unsupported provider route: code=request-model-missing; ${detail}`);
+    return { code: "request-model-missing", detail };
   }
 
   if (provider === null) {
-    logger.warn(
-      `[handler] Unsupported provider route: no Provider matched model=${model}; path=${route.normalizedPath}; protocol=${protocolLabel(route)}`,
-    );
-    return;
+    const detail = `no Provider matched model=${model}; path=${route.normalizedPath}; protocol=${protocolLabel(route)}`;
+    logger.warn(`[handler] Unsupported provider route: code=provider-not-found; ${detail}`);
+    return { code: "provider-not-found", detail };
   }
 
   const configuredFields = configuredProviderUrlFields(provider);
-  logger.warn(
-    `[handler] Unsupported provider route: Provider "${provider.name}" (${provider.id}) matched model=${model}, but request path ${route.normalizedPath} requires ${protocolLabel(route)} via ${requiredProviderUrlField(route)}; configured URL fields=${configuredFields.length > 0 ? configuredFields.join(",") : "none"}`,
-  );
+  const detail =
+    `Provider "${provider.name}" (${provider.id}) matched model=${model}, ` +
+    `but request path ${route.normalizedPath} requires ${protocolLabel(route)} via ` +
+    `${requiredProviderUrlField(route)}; configured URL fields=${
+      configuredFields.length > 0 ? configuredFields.join(",") : "none"
+    }`;
+  logger.warn(`[handler] Unsupported provider route: code=provider-route-mismatch; ${detail}`);
+  return { code: "provider-route-mismatch", detail };
 }
 
 type BodyReadResult = { ok: true; body: string | null } | { ok: false; reason: "too-large" };
@@ -510,8 +520,13 @@ async function handleAdmittedProxy(req: Request): Promise<Response> {
     matchedProviderConfig === null ||
     !providerSupportsApiRoute(route, matchedProviderConfig)
   ) {
-    logUnsupportedProviderRoute(model, route, matchedProviderConfig);
-    return new Response("Forbidden: unsupported provider", { status: STATUS_FORBIDDEN });
+    const unsupported = unsupportedProviderRoute(model, route, matchedProviderConfig);
+    return new Response("Forbidden: unsupported provider", {
+      status: STATUS_FORBIDDEN,
+      headers: {
+        [HEADER_ERROR_CODE]: unsupported.code,
+      },
+    });
   }
 
   const upstreamBase = selectUpstreamBase(route, matchedProviderConfig);
@@ -606,12 +621,14 @@ async function handleAdmittedProxy(req: Request): Promise<Response> {
       await persistFinalizedLogUpdate(log);
       return new Response("Client aborted", { status: 499 });
     }
-    logger.error(`[handler] Proxy error: ${req.method} ${parsed.apiPath}`, String(err));
+    const upstreamError = errorMessage(err);
+    logger.error(`[handler] Proxy error: ${req.method} ${parsed.apiPath}`, upstreamError);
     log.responseStatus = STATUS_BAD_GATEWAY;
-    log.responseText = String(err);
-    appendLogEntry({ ...buildFileLogEntry(log, upstreamUrl), error: String(err) });
+    log.responseText = upstreamError;
+    log.error = upstreamError;
+    appendLogEntry({ ...buildFileLogEntry(log, upstreamUrl), error: upstreamError });
     await persistFinalizedLogUpdate(log);
-    return new Response(`Proxy error: ${err}`, { status: STATUS_BAD_GATEWAY });
+    return new Response(UPSTREAM_REQUEST_FAILED, { status: STATUS_BAD_GATEWAY });
   }
 
   const isStream =

package/src/proxy/logFinalizer.ts

@@ -62,6 +62,7 @@ export type FinalizeLogResult = {
 };
 
 const DEFAULT_MAX_FINALIZE_STREAM_BYTES = 20 * 1024 * 1024;
+const DEFAULT_FINALIZE_JOB_TIMEOUT_MS = 15_000;
 
 function resolveMaxFinalizeStreamBytes(): number {
   const raw = process.env["AGENT_INSPECTOR_MAX_FINALIZE_STREAM_BYTES"];
@@ -71,6 +72,14 @@ function resolveMaxFinalizeStreamBytes(): number {
   return Math.floor(parsed);
 }
 
+function resolveFinalizeJobTimeoutMs(): number {
+  const raw = process.env["AGENT_INSPECTOR_FINALIZE_JOB_TIMEOUT_MS"];
+  if (raw === undefined || raw === "") return DEFAULT_FINALIZE_JOB_TIMEOUT_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 100) return DEFAULT_FINALIZE_JOB_TIMEOUT_MS;
+  return Math.floor(parsed);
+}
+
 export function buildFileLogEntry(log: CapturedLog, upstreamUrl: string): Record<string, unknown> {
   return {
     timestamp: log.timestamp,
@@ -482,6 +491,44 @@ export function buildFinalizeLogResult(job: FinalizeLogJob): FinalizeLogResult {
   }
 }
 
+export function buildFinalizeTimeoutResult(
+  job: FinalizeLogJob,
+  timeoutMs: number,
+): FinalizeLogResult {
+  const log = cloneLog(job.log);
+  const message = `Log finalization timed out after ${String(timeoutMs)}ms`;
+  log.elapsedMs = job.elapsedMs;
+  applyOptionalStreamingTiming(log, job);
+  let fallbackStatus = 499;
+  let cleanupRawStreamPath: string | null = null;
+  switch (job.type) {
+    case "non-streaming":
+    case "streaming":
+      fallbackStatus = job.responseStatus;
+      cleanupRawStreamPath =
+        job.type === "streaming" ? cleanupPathForRawStream(job.rawStream) : null;
+      break;
+    case "stream-abort":
+      cleanupRawStreamPath = cleanupPathForRawStream(job.rawStream);
+      break;
+    default: {
+      const _exhaustive: never = job;
+      logger.error(`[logFinalizer] Unhandled timeout job type: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+  log.responseStatus = log.responseStatus ?? fallbackStatus;
+  log.responseText = log.responseText ?? message;
+  log.captureIncomplete = true;
+  log.captureIncompleteReason = "finalize-timeout";
+  log.error = message;
+  return {
+    log,
+    upstreamUrl: job.upstreamUrl,
+    error: message,
+    cleanupRawStreamPath,
+  };
+}
+
 export async function commitFinalizeLogResult(result: FinalizeLogResult): Promise<void> {
   const persistedError =
     result.log.captureIncompleteReason === "upstream-stream-error"
@@ -680,7 +727,26 @@ export function executeBuildInWorker(job: FinalizeLogJob): Promise<FinalizeLogRe
 }
 
 export function executeFinalizeLogJob(job: FinalizeLogJob): Promise<void> {
-  return resolveBuildPromise(job).then(async (result) => {
+  const timeoutMs = resolveFinalizeJobTimeoutMs();
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+  const buildPromise = resolveBuildPromise(job);
+  const timeoutPromise = new Promise<FinalizeLogResult>((resolve) => {
+    timeout = setTimeout(() => {
+      logger.error(
+        `[logFinalizer] Finalize job timed out for log #${job.log.id} after ${String(timeoutMs)}ms`,
+      );
+      resolve(buildFinalizeTimeoutResult(job, timeoutMs));
+    }, timeoutMs);
+  });
+  void buildPromise.catch((err: unknown) => {
+    logger.error(
+      `[logFinalizer] Late finalize build failure for log #${job.log.id}:`,
+      errorMessage(err),
+    );
+  });
+
+  return Promise.race([buildPromise, timeoutPromise]).then(async (result) => {
+    if (timeout !== null) clearTimeout(timeout);
     await commitFinalizeLogResult(result);
     if (result.error !== null && result.error !== "Client aborted") {
       return Promise.reject(new Error(result.error));

package/src/proxy/logger.ts

@@ -281,6 +281,9 @@ export async function initLogger(): Promise<void> {
 // File-based logger for application logs (not log entries)
 let loggerInitialization: Promise<void> | null = null;
 let applicationLogWriteQueue: Promise<void> = Promise.resolve();
+let lastApplicationLogWriteFailureKey: string | null = null;
+let lastApplicationLogWriteFailureAt = 0;
+const APPLICATION_LOG_WRITE_FAILURE_SUPPRESS_MS = 5_000;
 
 type ApplicationLogWriteResult = { ok: true } | { ok: false; reason: unknown };
 
@@ -334,7 +337,24 @@ async function writeAppLog(message: string): Promise<void> {
   const write = async (): Promise<void> => {
     await initialization;
     const result = await appendApplicationLogLine(logPath, line, getApplicationLogPolicy());
-    if (!result.ok) writeStderrFallback(`[logger] Failed to write to ${logPath}:`, result.reason);
+    if (!result.ok) {
+      const key = `${logPath}:${String(result.reason)}`;
+      const now = Date.now();
+      if (
+        key !== lastApplicationLogWriteFailureKey ||
+        now - lastApplicationLogWriteFailureAt >= APPLICATION_LOG_WRITE_FAILURE_SUPPRESS_MS
+      ) {
+        lastApplicationLogWriteFailureKey = key;
+        lastApplicationLogWriteFailureAt = now;
+        writeStderrFallback(`[logger] Failed to write to ${logPath}:`, result.reason);
+      }
+      return;
+    }
+    if (lastApplicationLogWriteFailureKey !== null) {
+      writeStderrFallback(`[logger] Application log writes recovered for ${logPath}:`, "ok");
+      lastApplicationLogWriteFailureKey = null;
+      lastApplicationLogWriteFailureAt = 0;
+    }
   };
 
   applicationLogWriteQueue = applicationLogWriteQueue.then(write, write);