fix(agents): make trajectory cleanup timeout configurable

BunsDev · web-flow · commit 5d4a8b00721a · 2026-05-13T23:09:56.000-05:00
Refs #75839.\n\nAdds OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS and OPENCLAW_AGENT_CLEANUP_TIMEOUT_MS for agent cleanup steps while preserving the 10s default. Includes focused timeout precedence tests, trajectory docs, and changelog coverage.\n\nVerification:\n- pnpm test src/agents/run-cleanup-timeout.test.ts\n- pnpm exec oxfmt --check --threads=1 src/agents/run-cleanup-timeout.ts src/agents/run-cleanup-timeout.test.ts\n- pnpm format:docs:check docs/tools/trajectory.md\n- git diff --check\n- pnpm check:changed\n- GitHub PR checks: 88 passing, CodeQL neutral, 21 skipped
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,7 @@ Docs: https://docs.openclaw.ai
 - Maintainer tooling: clarify which pnpm test/check commands are safe locally versus inside Codex worktrees, routing linked-worktree gates through node wrappers and Crabbox/Testbox.
 - iOS/chat: resize PhotosPicker image attachments to capped JPEGs before staging and sending, stripping source metadata and keeping oversized camera photos under the chat upload budget. Fixes #68524. Thanks @BunsDev.
 - Codex harness: classify native app-server token-refresh logout and relogin failures as authentication refresh errors, so users get re-authentication guidance instead of a raw runtime failure.
+- Agents/trajectory: make the trajectory flush cleanup timeout configurable with `OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS`, preserving the 10s default while slower stores drain. Refs #75839. Thanks @BunsDev.
 - Codex startup: treat selectable configured OpenAI agent models as Codex runtime requirements during plugin auto-enable, startup planning, and doctor install repair, so Anthropic-primary configs can still switch to OpenAI/Codex cleanly.
 - Agents: preserve source-reply delivery metadata when merging tool-returned media into the final reply, keeping message-tool-only replies deliverable and mirrored. Thanks @pashpashpash and @vincentkoc.
 - macOS/companion: require system TLS trust before pinning a first-use direct `wss://` gateway certificate and honor `gateway.remote.tlsFingerprint` as the explicit pin for remote node-mode sessions, so fresh endpoints fail closed when macOS cannot trust the certificate unless configured out of band. Fixes #50642. Thanks @BunsDev.
diff --git a/docs/tools/trajectory.md b/docs/tools/trajectory.md
@@ -168,6 +168,20 @@ This disables runtime trajectory capture. `/export-trajectory` can still export
 the transcript branch, but runtime-only files such as compiled context,
 provider artifacts, and prompt metadata may be missing.
 
+## Tune flush timeout
+
+OpenClaw flushes runtime trajectory sidecars during agent cleanup. The default
+cleanup timeout is 10,000 ms. On slow disks or large stores, set
+`OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS` before starting OpenClaw:
+
+```bash
+export OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS=30000
+```
+
+This controls when OpenClaw logs a `pi-trajectory-flush` timeout and continues.
+It does not change the trajectory size caps. To tune all agent cleanup steps
+that do not pass an explicit timeout, set `OPENCLAW_AGENT_CLEANUP_TIMEOUT_MS`.
+
 ## Privacy and limits
 
 Trajectory bundles are designed for support and debugging, not public posting.
diff --git a/src/agents/run-cleanup-timeout.test.ts b/src/agents/run-cleanup-timeout.test.ts
@@ -1,5 +1,9 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { AGENT_CLEANUP_STEP_TIMEOUT_MS, runAgentCleanupStep } from "./run-cleanup-timeout.js";
+import {
+  AGENT_CLEANUP_STEP_TIMEOUT_MS,
+  resolveAgentCleanupStepTimeoutMs,
+  runAgentCleanupStep,
+} from "./run-cleanup-timeout.js";
 
 describe("agent cleanup timeout", () => {
   const log = {
@@ -35,6 +39,91 @@ describe("agent cleanup timeout", () => {
     );
   });
 
+  it("uses the trajectory flush timeout environment override for trajectory cleanup", async () => {
+    const cleanup = vi.fn(async () => new Promise<never>(() => {}));
+
+    const result = runAgentCleanupStep({
+      runId: "run-trajectory",
+      sessionId: "session-trajectory",
+      step: "pi-trajectory-flush",
+      cleanup,
+      log,
+      env: {
+        OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS: "25000",
+      },
+    });
+
+    await vi.advanceTimersByTimeAsync(24_999);
+    expect(log.warn).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(1);
+    await expect(result).resolves.toBeUndefined();
+
+    expect(cleanup).toHaveBeenCalledTimes(1);
+    expect(log.warn).toHaveBeenCalledWith(
+      "agent cleanup timed out: runId=run-trajectory sessionId=session-trajectory step=pi-trajectory-flush timeoutMs=25000",
+    );
+  });
+
+  it("uses the general cleanup timeout environment override for other cleanup steps", async () => {
+    const cleanup = vi.fn(async () => new Promise<never>(() => {}));
+
+    const result = runAgentCleanupStep({
+      runId: "run-general",
+      sessionId: "session-general",
+      step: "bundle-mcp-retire",
+      cleanup,
+      log,
+      env: {
+        OPENCLAW_AGENT_CLEANUP_TIMEOUT_MS: "1500",
+      },
+    });
+
+    await vi.advanceTimersByTimeAsync(1_500);
+    await expect(result).resolves.toBeUndefined();
+
+    expect(log.warn).toHaveBeenCalledWith(
+      "agent cleanup timed out: runId=run-general sessionId=session-general step=bundle-mcp-retire timeoutMs=1500",
+    );
+  });
+
+  it("prefers explicit cleanup timeout values over environment overrides", () => {
+    expect(
+      resolveAgentCleanupStepTimeoutMs({
+        step: "pi-trajectory-flush",
+        timeoutMs: 2_000,
+        env: {
+          OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS: "25000",
+          OPENCLAW_AGENT_CLEANUP_TIMEOUT_MS: "15000",
+        },
+      }),
+    ).toBe(2_000);
+  });
+
+  it("keeps explicit zero cleanup timeouts as a one millisecond timeout", () => {
+    expect(
+      resolveAgentCleanupStepTimeoutMs({
+        step: "pi-trajectory-flush",
+        timeoutMs: 0,
+        env: {
+          OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS: "25000",
+        },
+      }),
+    ).toBe(1);
+  });
+
+  it("ignores invalid cleanup timeout environment values", () => {
+    expect(
+      resolveAgentCleanupStepTimeoutMs({
+        step: "pi-trajectory-flush",
+        env: {
+          OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS: "0",
+          OPENCLAW_AGENT_CLEANUP_TIMEOUT_MS: "not-a-number",
+        },
+      }),
+    ).toBe(AGENT_CLEANUP_STEP_TIMEOUT_MS);
+  });
+
   it("logs cleanup rejection without throwing", async () => {
     await expect(
       runAgentCleanupStep({
diff --git a/src/agents/run-cleanup-timeout.ts b/src/agents/run-cleanup-timeout.ts
@@ -1,20 +1,68 @@
 import { formatErrorMessage } from "../infra/errors.js";
 
 export const AGENT_CLEANUP_STEP_TIMEOUT_MS = 10_000;
+export const AGENT_CLEANUP_STEP_TIMEOUT_ENV = "OPENCLAW_AGENT_CLEANUP_TIMEOUT_MS";
+export const TRAJECTORY_FLUSH_TIMEOUT_ENV = "OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS";
 
 type AgentCleanupLogger = {
   warn: (message: string) => void;
 };
 
+function normalizeExplicitTimeoutMs(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return undefined;
+  }
+  return Math.max(1, Math.floor(value));
+}
+
+function parseTimeoutEnvValue(value: string | undefined): number | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  const timeoutMs = Number(trimmed);
+  if (!Number.isFinite(timeoutMs)) {
+    return undefined;
+  }
+  const normalized = Math.floor(timeoutMs);
+  return normalized > 0 ? normalized : undefined;
+}
+
+export function resolveAgentCleanupStepTimeoutMs(params: {
+  step: string;
+  timeoutMs?: number;
+  env?: NodeJS.ProcessEnv;
+}): number {
+  const explicitTimeoutMs = normalizeExplicitTimeoutMs(params.timeoutMs);
+  if (explicitTimeoutMs !== undefined) {
+    return explicitTimeoutMs;
+  }
+
+  const env = params.env ?? process.env;
+  if (params.step === "pi-trajectory-flush") {
+    const trajectoryTimeoutMs = parseTimeoutEnvValue(env[TRAJECTORY_FLUSH_TIMEOUT_ENV]);
+    if (trajectoryTimeoutMs !== undefined) {
+      return trajectoryTimeoutMs;
+    }
+  }
+
+  return parseTimeoutEnvValue(env[AGENT_CLEANUP_STEP_TIMEOUT_ENV]) ?? AGENT_CLEANUP_STEP_TIMEOUT_MS;
+}
+
 export async function runAgentCleanupStep(params: {
   runId: string;
   sessionId: string;
   step: string;
   cleanup: () => Promise<void>;
   log: AgentCleanupLogger;
+  env?: NodeJS.ProcessEnv;
   timeoutMs?: number;
 }): Promise<void> {
-  const timeoutMs = Math.max(1, Math.floor(params.timeoutMs ?? AGENT_CLEANUP_STEP_TIMEOUT_MS));
+  const timeoutMs = resolveAgentCleanupStepTimeoutMs({
+    step: params.step,
+    timeoutMs: params.timeoutMs,
+    env: params.env,
+  });
   let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
   let timedOut = false;
   const cleanupPromise = Promise.resolve().then(params.cleanup);
