Summary

• Problem: sessions.list latency around 10s and fixed 10s pi-trajectory-flush timeout under moderate session load #75839 still reports pi-trajectory-flush cleanup warnings at exactly 10000 ms under slow or large session stores, and origin/main still hard-codes the generic cleanup default when no per-call timeout is passed.
• Why it matters: operators can already relocate or disable trajectory capture, but they cannot tune the cleanup warning threshold for slower disks or larger trajectory queues without patching source.
• What changed: runAgentCleanupStep now resolves timeouts from explicit params first, then OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS for pi-trajectory-flush, then the general OPENCLAW_AGENT_CLEANUP_TIMEOUT_MS, then the existing 10s default.
• What did NOT change (scope boundary): this does not close the broader sessions.list half of sessions.list latency around 10s and fixed 10s pi-trajectory-flush timeout under moderate session load #75839, does not change trajectory size caps, does not add config-schema surface, and does not alter queued writer flushing semantics already present on origin/main.

Duplicate and related work triage

• sessions.list latency around 10s and fixed 10s pi-trajectory-flush timeout under moderate session load #75839 remains open and is not fully resolved: current origin/main has several sessions.list mitigations plus trajectory writer yielding, but the cleanup timeout remains fixed at 10s by default.
• fix: prevent event loop saturation from trajectory flush (setImmediate yield + 10MB cap + 30s timeout) #77133 is the closest open trajectory PR, but it still proposes a constant bump and cap change; current origin/main already has the writer-yield/docs-cap pieces, while this PR implements the missing configurable timeout as a narrower replacement for that part.
• [Feature]: Configurable trajectory flush timeout for reasoning traces #78126 was closed as duplicate of sessions.list latency around 10s and fixed 10s pi-trajectory-flush timeout under moderate session load #75839 after ClawSweeper confirmed the same OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS ask.
• feat: add configurable trajectory flush timeout for reasoning traces #78133 was closed as superseded/duplicate and targeted periodic trajectory runtime flushing, not the pi-trajectory-flush cleanup timeout path.
• Fix/sessions list resolver cache #77187 remains the closest open sessions-list resolver-cache PR and should stay separate from this cleanup-timeout fix.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Refs sessions.list latency around 10s and fixed 10s pi-trajectory-flush timeout under moderate session load #75839
• Related fix: prevent event loop saturation from trajectory flush (setImmediate yield + 10MB cap + 30s timeout) #77133
• Related [Feature]: Configurable trajectory flush timeout for reasoning traces #78126
• Related feat: add configurable trajectory flush timeout for reasoning traces #78133
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior addressed: pi-trajectory-flush cleanup no longer has an unconfigurable fixed 10000 ms timeout; operators can set OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS while the default remains 10000 ms.
• Real environment tested: local OpenClaw checkout, Node v24.13.0 for the direct tsx runtime proof, pnpm 10.33.2, no secrets or live channel credentials involved.
• Exact steps or command run after this patch:
  1. Ran a direct tsx invocation of runAgentCleanupStep with step: "pi-trajectory-flush", a non-resolving cleanup promise, and env: { OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS: "25" }.
  2. Ran the focused Vitest file for cleanup timeout resolution.
  3. Ran format, docs, changed-lane, type/lint/import-cycle, and diff checks listed below.
• Evidence after fix:

$ pnpm exec tsx -e '<invoke runAgentCleanupStep with OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS=25>'
{
  "elapsedMs": 27,
  "logs": [
    "agent cleanup timed out: runId=proof-run sessionId=proof-session step=pi-trajectory-flush timeoutMs=25"
  ]
}

$ pnpm test src/agents/run-cleanup-timeout.test.ts
Test Files  1 passed (1)
Tests  7 passed (7)
[test] passed 1 Vitest shard in 2.75s

• Observed result after fix: the runtime helper uses the trajectory-specific environment value for the pi-trajectory-flush timeout, while focused tests cover trajectory-specific env, general cleanup env, explicit timeout precedence, explicit zero normalization, invalid env fallback, default timeout, and rejection logging.
• What was not tested: full Raspberry Pi, Windows, or long-running production gateway soak. This PR is scoped to the cleanup timeout resolver; the broader sessions.list latency remains tracked separately by sessions.list latency around 10s and fixed 10s pi-trajectory-flush timeout under moderate session load #75839 and related sessions-list PRs.
• Before evidence (optional but encouraged): origin/main still has AGENT_CLEANUP_STEP_TIMEOUT_MS = 10_000 and runAgentCleanupStep previously used params.timeoutMs ?? AGENT_CLEANUP_STEP_TIMEOUT_MS, so the pi-trajectory-flush call had no env/config-derived override.

Root Cause (if applicable)

• Root cause: runAgentCleanupStep only accepted an explicit timeoutMs or fell back to the 10s constant, and the pi-trajectory-flush call site does not pass an override.
• Missing detection / guardrail: existing coverage only asserted the hard-coded default timeout and cleanup rejection behavior; it did not cover operator-configurable cleanup timeouts.
• Contributing context (if known): current origin/main already added trajectory writer event-loop yielding and 10 MiB live capture bounds, so the remaining source-reproducible timeout issue is the cleanup helper defaulting path.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/run-cleanup-timeout.test.ts
• Scenario the test should lock in: timeout resolution honors trajectory-specific env, falls back to general cleanup env, preserves explicit caller values, and ignores invalid env values.
• Why this is the smallest reliable guardrail: the bug lives in the cleanup timeout resolver, not in gateway startup, channel transport, or trajectory serialization.
• Existing test that already covers this (if any): the pre-existing test covered the default timeout warning only.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

Operators can set OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS to tune the pi-trajectory-flush cleanup timeout warning threshold. Operators can set OPENCLAW_AGENT_CLEANUP_TIMEOUT_MS as a fallback for cleanup steps that do not pass an explicit timeout. Existing default behavior remains 10 seconds.

Diagram (if applicable)

Before:
pi-trajectory-flush -> runAgentCleanupStep -> fixed 10000 ms default

After:
pi-trajectory-flush -> explicit timeout? -> trajectory env? -> general cleanup env? -> 10000 ms default

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A. The new environment values are numeric timeout controls only; invalid values are ignored, and logs include only the resolved numeric timeout.

Repro + Verification

Environment

• OS: macOS local checkout
• Runtime/container: local Node/pnpm workspace; direct runtime proof used Node v24.13.0, repo supports Node 22+
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS=25 for direct runtime proof

Steps

1. Confirm current main has no trajectory cleanup timeout env override.
2. Apply this patch.
3. Run the direct cleanup helper proof with the trajectory env override.
4. Run focused tests and changed-surface gates.

Expected

• pi-trajectory-flush uses the trajectory-specific env timeout when set.
• Invalid or missing env values preserve the 10s default.
• Explicit timeoutMs remains highest precedence.

Actual

• Direct runtime proof logged timeoutMs=25 for pi-trajectory-flush.
• Focused tests and changed checks passed.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Validation run after this patch:

pnpm install
pnpm docs:list
pnpm test src/agents/run-cleanup-timeout.test.ts
pnpm exec oxfmt --check --threads=1 src/agents/run-cleanup-timeout.ts src/agents/run-cleanup-timeout.test.ts
git diff --check
pnpm changed:lanes --json
pnpm check:changed
pnpm format:docs:check docs/tools/trajectory.md

Results:

pnpm changed:lanes --json -> lanes=core, coreTests, docs; all=false
pnpm check:changed -> lanes=core, coreTests, docs; passed
pnpm format:docs:check docs/tools/trajectory.md -> Docs formatting clean

Human Verification (required)

• Verified scenarios: direct runtime proof of the env override, focused fake-timer coverage for timeout precedence/fallbacks, docs updated for the new operator knobs.
• Edge cases checked: explicit timeout beats env, explicit zero still normalizes to 1 ms for backward compatibility, invalid env values fall back to default, general cleanup env applies to non-trajectory cleanup steps.
• What you did not verify: live production deployment under the reported Raspberry Pi/Windows stores; this PR avoids claiming the broader sessions.list half is fixed.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

No bot review conversations exist on this PR yet.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) Yes
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: Optional only. Set OPENCLAW_TRAJECTORY_FLUSH_TIMEOUT_MS=<milliseconds> before starting OpenClaw to tune trajectory flush cleanup warnings; otherwise no action required.

Risks and Mitigations

• Risk: operators can set an excessively high timeout and delay timeout warnings for stuck cleanup work.
  • Mitigation: default remains 10000 ms; the knob is opt-in and explicit per-call timeouts still win.
• Risk: invalid environment values could accidentally change cleanup behavior.
  • Mitigation: invalid, empty, zero, negative, or non-finite env values are ignored and fall back to the existing default.