fix(gateway): log swallowed background-task finalization errors (#92033)

hansraj316 · web-flow · commit b9e1099f5e5b · 2026-06-11T08:28:03.000+09:00
Background-task finalization swallowed all errors. Log via formatForLog at
warn so non-transient failures are observable, staying non-blocking.
diff --git a/src/gateway/server-methods/agent.test.ts b/src/gateway/server-methods/agent.test.ts
@@ -4470,6 +4470,54 @@ describe("gateway agent handler", () => {
     });
   });
 
+  it("logs a swallowed finalize error without blocking the background run", async () => {
+    await withTempDir({ prefix: "openclaw-gateway-agent-finalize-throw-" }, async (root) => {
+      process.env.OPENCLAW_STATE_DIR = root;
+      resetTaskRegistryForTests();
+      primeMainAgentRun();
+
+      const defaultRuntime = getDetachedTaskLifecycleRuntime();
+      const finalizeError = new Error("finalize boom");
+      const finalizeTaskRunByRunIdSpy = vi.fn(() => {
+        throw finalizeError;
+      });
+      setDetachedTaskLifecycleRuntime({
+        ...defaultRuntime,
+        finalizeTaskRunByRunId: finalizeTaskRunByRunIdSpy,
+      });
+
+      const context = makeContext();
+      const respond = vi.fn();
+
+      await invokeAgent(
+        {
+          message: "finalize throw seam task",
+          sessionKey: "agent:main:main",
+          idempotencyKey: "task-registry-finalize-throw",
+        },
+        { context, respond, reqId: "task-registry-finalize-throw" },
+      );
+
+      // Finalize threw, but the run must still complete (second res frame with ok status).
+      expect(finalizeTaskRunByRunIdSpy).toHaveBeenCalledTimes(1);
+      const completed = respond.mock.calls.some(([ok, payload]) => {
+        return ok === true && (payload as { status?: string } | undefined)?.status === "ok";
+      });
+      expect(completed).toBe(true);
+
+      // The swallowed finalize error stays observable via a warn log.
+      const warnMock = context.logGateway.warn as ReturnType<typeof vi.fn>;
+      const loggedFinalizeError = warnMock.mock.calls.some(([message]) => {
+        return (
+          typeof message === "string" &&
+          message.includes("failed to finalize tracked agent task") &&
+          message.includes("finalize boom")
+        );
+      });
+      expect(loggedFinalizeError).toBe(true);
+    });
+  });
+
   it("routes voice wake trigger to configured session target", async () => {
     mocks.loadVoiceWakeRoutingConfig.mockResolvedValue({
       version: 1,
diff --git a/src/gateway/server-methods/agent.ts b/src/gateway/server-methods/agent.ts
@@ -682,6 +682,7 @@ function tryFinalizeTrackedAgentTask(params: {
   status: GatewayAgentTaskTerminalStatus;
   error?: string;
   terminalSummary?: string;
+  log: Pick<GatewayRequestContext["logGateway"], "warn">;
 }): void {
   try {
     finalizeTaskRunByRunId({
@@ -692,8 +693,10 @@ function tryFinalizeTrackedAgentTask(params: {
       ...(params.error !== undefined ? { error: params.error } : {}),
       ...(params.terminalSummary !== undefined ? { terminalSummary: params.terminalSummary } : {}),
     });
-  } catch {
+  } catch (err) {
     // Best-effort only: background task tracking must not block agent runs.
+    // Still surface the swallowed error so non-transient finalize failures stay observable.
+    params.log.warn(`failed to finalize tracked agent task ${params.runId}: ${formatForLog(err)}`);
   }
 }
 
@@ -908,8 +911,12 @@ function dispatchAgentRunFromGateway(params: {
           startedAt: Date.now(),
         }),
       );
-    } catch {
+    } catch (err) {
       // Best-effort only: background task tracking must not block agent runs.
+      // Still surface the swallowed error so non-transient tracking failures stay observable.
+      params.context.logGateway.warn(
+        `failed to start tracked agent task ${params.runId}: ${formatForLog(err)}`,
+      );
     }
   }
   void agentCommandFromIngress(params.ingressOpts, defaultRuntime, params.context.deps)
@@ -921,6 +928,7 @@ function dispatchAgentRunFromGateway(params: {
           runId: params.runId,
           status: aborted ? "timed_out" : "succeeded",
           terminalSummary: aborted ? "aborted" : "completed",
+          log: params.context.logGateway,
         });
       }
       const payload = {
@@ -958,6 +966,7 @@ function dispatchAgentRunFromGateway(params: {
           status: aborted ? "timed_out" : resolveFailedTrackedAgentTaskStatus(err),
           error: renderedErr,
           terminalSummary: renderedErr,
+          log: params.context.logGateway,
         });
       }
       const error = errorShape(ErrorCodes.UNAVAILABLE, renderedErr);
