fix(gateway): cover delayed and owner-side terminal persistence failure logs

hanZeng-08 · hanZeng-08 · commit 9aa0b9251acc · 2026-06-30T00:35:00.000+08:00
Extends the previous chat-abort fix to also log terminal persistence
rejections in the remaining two boundaries ClawSweeper identified:

- src/gateway/server-runtime-subscriptions.ts: delayed cleanup ordering
  when persistence is attached after cleanup() was requested.
- src/gateway/server-chat.ts: owner-side terminal lifecycle persistence
  fallback catch.

Both boundaries receive the injected SubsystemLogger. The existing
server-chat.agent-events test now asserts log.error is called on
persistence failure.
diff --git a/src/gateway/server-chat.agent-events.test.ts b/src/gateway/server-chat.agent-events.test.ts
@@ -105,6 +105,7 @@ describe("agent event handler", () => {
     const toolEventRecipients = createToolEventRecipientRegistry();
     const sessionEventSubscribers = createSessionEventSubscriberRegistry();
     const sessionMessageSubscribers = createSessionMessageSubscriberRegistry();
+    const log = { error: vi.fn() } as unknown as import("../logging/subsystem.js").SubsystemLogger;
 
     const handler = createAgentEventHandler({
       broadcast,
@@ -124,6 +125,7 @@ describe("agent event handler", () => {
       markTrackedRunTerminalPersisted: params?.markTrackedRunTerminalPersisted,
       trackTrackedRunTerminalPersistence: params?.trackTrackedRunTerminalPersistence,
       resolveActiveLifecycleGenerationForRun: params?.resolveActiveLifecycleGenerationForRun,
+      log,
     });
 
     return {
@@ -139,6 +141,7 @@ describe("agent event handler", () => {
       sessionEventSubscribers,
       sessionMessageSubscribers,
       handler,
+      log,
     };
   }
 
@@ -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, log, sessionEventSubscribers } = createHarness({
       resolveSessionKeyForRun: () => "session-failed-write",
       lifecycleErrorRetryGraceMs: 0,
       markTrackedRunTerminalPersisted,
@@ -2533,6 +2536,13 @@ describe("agent event handler", () => {
       abortedLastRun: false,
     });
     expect(markTrackedRunTerminalPersisted).not.toHaveBeenCalled();
+    expect(log.error).toHaveBeenCalledOnce();
+    expect(log.error).toHaveBeenCalledWith(
+      expect.stringContaining(
+        "Failed to persist terminal lifecycle event for run run-failed-write",
+      ),
+      expect.objectContaining({ runId: "run-failed-write" }),
+    );
   });
 
   it("does not clear a same-id retry when an old restart terminal arrives", () => {
diff --git a/src/gateway/server-chat.ts b/src/gateway/server-chat.ts
@@ -7,8 +7,9 @@ import { DEFAULT_HEARTBEAT_ACK_MAX_CHARS, stripHeartbeatToken } from "../auto-re
 import { normalizeVerboseLevel } from "../auto-reply/thinking.js";
 import { getRuntimeConfig } from "../config/io.js";
 import { type AgentEventPayload, getAgentRunContext } from "../infra/agent-events.js";
-import { detectErrorKind, type ErrorKind } from "../infra/errors.js";
+import { detectErrorKind, formatErrorMessage, 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";
@@ -290,6 +291,7 @@ export type AgentEventHandlerOptions = {
     persistence: Promise<void>;
   }) => void;
   resolveActiveLifecycleGenerationForRun?: (runId: string) => string | undefined;
+  log?: SubsystemLogger;
 };
 
 function roundedChatSendTimingMs(value: number): number {
@@ -314,6 +316,7 @@ export function createAgentEventHandler({
   markTrackedRunTerminalPersisted,
   trackTrackedRunTerminalPersistence,
   resolveActiveLifecycleGenerationForRun = () => undefined,
+  log,
 }: AgentEventHandlerOptions) {
   type TerminalLifecycleOptions = {
     skipChatErrorFinal?: boolean;
@@ -716,7 +719,11 @@ export function createAgentEventHandler({
             markPersisted();
             broadcastSessionChange();
           })
-          .catch(() => {
+          .catch((err) => {
+            log?.error(
+              `Failed to persist terminal lifecycle event for run ${evt.runId}: ${formatErrorMessage(err)}`,
+              { error: err, runId: evt.runId },
+            );
             // 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,8 @@
 // Gateway event subscription wiring for agent, heartbeat, transcript, and lifecycle broadcasts.
 import { clearAgentRunContext, onAgentEvent } from "../infra/agent-events.js";
+import { formatErrorMessage } from "../infra/errors.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 +30,7 @@ export function startGatewayEventSubscriptions(params: {
   sessionMessageSubscribers: SessionMessageSubscriberRegistry;
   chatAbortControllers: Map<string, ChatAbortControllerEntry>;
   restartRecoveryCandidates: Map<string, RestartRecoveryCandidate>;
+  log?: SubsystemLogger;
 }) {
   let agentEventHandlerPromise: Promise<
     ReturnType<typeof import("./server-chat.js").createAgentEventHandler>
@@ -49,6 +52,7 @@ export function startGatewayEventSubscriptions(params: {
         toolEventRecipients: params.toolEventRecipients,
         sessionEventSubscribers: params.sessionEventSubscribers,
         sessionMessageSubscribers: params.sessionMessageSubscribers,
+        log: params.log,
         clearTrackedActiveRun: ({ runId, clientRunId }) => {
           const candidateRunIds = runId === clientRunId ? [runId] : [runId, clientRunId];
           for (const candidateRunId of candidateRunIds) {
@@ -99,7 +103,13 @@ export function startGatewayEventSubscriptions(params: {
               entry.projectSessionTerminalPersistence = persistence;
               if (entry.registrationCleanupRequested === true) {
                 void persistence
-                  .catch(() => undefined)
+                  .catch((err) => {
+                    params.log?.error(
+                      `Failed to persist tracked terminal state for run ${candidateRunId}: ${formatErrorMessage(err)}`,
+                      { error: err, runId: candidateRunId },
+                    );
+                    return undefined;
+                  })
                   .then(() => {
                     if (params.chatAbortControllers.get(candidateRunId) === entry) {
                       params.chatAbortControllers.delete(candidateRunId);
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,
+        log,
       }),
     );
     Object.assign(runtimeState, runtimeSubscriptions);
