fix: log terminal session persistence failures

aditya-vithaldas · aditya-vithaldas · commit b81d7ef91d8a · 2026-06-29T18:35:47.000+02:00
diff --git a/src/gateway/server-chat.agent-events.test.ts b/src/gateway/server-chat.agent-events.test.ts
@@ -97,6 +97,7 @@ describe("agent event handler", () => {
     const broadcast = vi.fn();
     const broadcastToConnIds = vi.fn();
     const nodeSendToSession = vi.fn();
+    const logGateway = { error: vi.fn() };
     const clearAgentRunContext = vi.fn();
     const clearTrackedActiveRun =
       vi.fn<NonNullable<AgentEventHandlerOptions["clearTrackedActiveRun"]>>();
@@ -117,6 +118,7 @@ describe("agent event handler", () => {
       toolEventRecipients,
       sessionEventSubscribers,
       sessionMessageSubscribers,
+      logGateway,
       loadGatewaySessionRowForSnapshot: loadGatewaySessionRow,
       lifecycleErrorRetryGraceMs: params?.lifecycleErrorRetryGraceMs,
       isChatSendRunActive: params?.isChatSendRunActive,
@@ -131,6 +133,7 @@ describe("agent event handler", () => {
       broadcast,
       broadcastToConnIds,
       nodeSendToSession,
+      logGateway,
       clearAgentRunContext,
       clearTrackedActiveRun,
       agentRunSeq,
@@ -2502,7 +2505,7 @@ describe("agent event handler", () => {
     });
     persistGatewaySessionLifecycleEventMock.mockRejectedValueOnce(new Error("disk full"));
     const markTrackedRunTerminalPersisted = vi.fn();
-    const { broadcastToConnIds, handler, sessionEventSubscribers } = createHarness({
+    const { broadcastToConnIds, handler, logGateway, sessionEventSubscribers } = createHarness({
       resolveSessionKeyForRun: () => "session-failed-write",
       lifecycleErrorRetryGraceMs: 0,
       markTrackedRunTerminalPersisted,
@@ -2532,6 +2535,15 @@ describe("agent event handler", () => {
       updatedAt: 2_100,
       abortedLastRun: false,
     });
+    expect(logGateway.error).toHaveBeenCalledWith(
+      "terminal session persistence failed",
+      expect.objectContaining({
+        runId: "run-failed-write",
+        clientRunId: "run-failed-write",
+        sessionKey: "session-failed-write",
+        error: expect.stringContaining("disk full"),
+      }),
+    );
     expect(markTrackedRunTerminalPersisted).not.toHaveBeenCalled();
   });
 
diff --git a/src/gateway/server-chat.ts b/src/gateway/server-chat.ts
@@ -9,6 +9,7 @@ import { getRuntimeConfig } from "../config/io.js";
 import { type AgentEventPayload, getAgentRunContext } from "../infra/agent-events.js";
 import { detectErrorKind, type ErrorKind } from "../infra/errors.js";
 import { resolveHeartbeatVisibility } from "../infra/heartbeat-visibility.js";
+import type { SubsystemLogger } from "../logging/subsystem.js";
 import { isAcpSessionKey, isSubagentSessionKey } from "../sessions/session-key-utils.js";
 import { resolveAssistantEventPhase } from "../shared/chat-message-content.js";
 import { setSafeTimeout } from "../utils/timer-delay.js";
@@ -268,6 +269,7 @@ export type AgentEventHandlerOptions = {
   toolEventRecipients: ToolEventRecipientRegistry;
   sessionEventSubscribers: SessionEventSubscriberRegistry;
   sessionMessageSubscribers: SessionMessageSubscriberRegistry;
+  logGateway?: Pick<SubsystemLogger, "error">;
   loadGatewaySessionRowForSnapshot?: typeof loadGatewaySessionRow;
   lifecycleErrorRetryGraceMs?: number;
   isChatSendRunActive?: (runId: string) => boolean;
@@ -307,6 +309,7 @@ export function createAgentEventHandler({
   toolEventRecipients,
   sessionEventSubscribers,
   sessionMessageSubscribers,
+  logGateway,
   loadGatewaySessionRowForSnapshot = loadGatewaySessionRow,
   lifecycleErrorRetryGraceMs = AGENT_LIFECYCLE_ERROR_RETRY_GRACE_MS,
   isChatSendRunActive = () => false,
@@ -716,7 +719,13 @@ export function createAgentEventHandler({
             markPersisted();
             broadcastSessionChange();
           })
-          .catch(() => {
+          .catch((err: unknown) => {
+            logGateway?.error("terminal session persistence failed", {
+              runId: evt.runId,
+              clientRunId,
+              sessionKey,
+              error: formatForLog(err),
+            });
             // Persistence recovery remains tracked by the controller entry, but
             // subscribers still need a terminal projection instead of hanging.
             broadcastSessionChange(evt);
diff --git a/src/gateway/server-runtime-subscriptions.ts b/src/gateway/server-runtime-subscriptions.ts
@@ -1,6 +1,7 @@
 // Gateway event subscription wiring for agent, heartbeat, transcript, and lifecycle broadcasts.
 import { clearAgentRunContext, onAgentEvent } from "../infra/agent-events.js";
 import { onHeartbeatEvent } from "../infra/heartbeat-events.js";
+import type { SubsystemLogger } from "../logging/subsystem.js";
 import { onSessionLifecycleEvent } from "../sessions/session-lifecycle-events.js";
 import { onInternalSessionTranscriptUpdate } from "../sessions/transcript-events.js";
 import type { ChatAbortControllerEntry, RestartRecoveryCandidate } from "./chat-abort.js";
@@ -28,6 +29,7 @@ export function startGatewayEventSubscriptions(params: {
   sessionMessageSubscribers: SessionMessageSubscriberRegistry;
   chatAbortControllers: Map<string, ChatAbortControllerEntry>;
   restartRecoveryCandidates: Map<string, RestartRecoveryCandidate>;
+  logGateway?: Pick<SubsystemLogger, "error">;
 }) {
   let agentEventHandlerPromise: Promise<
     ReturnType<typeof import("./server-chat.js").createAgentEventHandler>
@@ -49,6 +51,7 @@ export function startGatewayEventSubscriptions(params: {
         toolEventRecipients: params.toolEventRecipients,
         sessionEventSubscribers: params.sessionEventSubscribers,
         sessionMessageSubscribers: params.sessionMessageSubscribers,
+        logGateway: params.logGateway,
         clearTrackedActiveRun: ({ runId, clientRunId }) => {
           const candidateRunIds = runId === clientRunId ? [runId] : [runId, clientRunId];
           for (const candidateRunId of candidateRunIds) {
diff --git a/src/gateway/server.impl.ts b/src/gateway/server.impl.ts
@@ -1195,6 +1195,7 @@ export async function startGatewayServer(
         sessionMessageSubscribers,
         chatAbortControllers,
         restartRecoveryCandidates,
+        logGateway: log,
       }),
     );
     Object.assign(runtimeState, runtimeSubscriptions);
