Summary

Describe the problem and fix in 2–5 bullets:

• Problem: trajectory runtime data only flushed on explicit boundaries/shutdown, so long reasoning sessions could leave recent events buffered too long.
• Why it matters: operators lose timely on-disk reasoning trace visibility during long-running sessions and can miss state before an abrupt process exit.
• What changed: added trajectory.flushTimeoutMs, wired it into config typing/schema, and validated periodic flush behavior with focused runtime tests.
• What did NOT change (scope boundary): no change to trajectory storage format, retention policy, truncation budget, or default behavior when flushTimeoutMs is unset.

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

• Closes [Bug]: sessions.list is extremely slow (4+ seconds) causing event loop saturation #77373
• 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 or issue addressed: periodic flushing of in-flight trajectory events during long reasoning sessions.
• Real environment tested: local checkout of openclaw/openclaw on Linux with branch pr-78133.
• Exact steps or command run after this patch:
  • git checkout pr-78133
  • node scripts/run-vitest.mjs run --config test/vitest/vitest.unit-fast.config.ts src/trajectory/runtime.test.ts --reporter=verbose
• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output):

✓ src/trajectory/runtime.test.ts > trajectory runtime > fires periodic flush after flushTimeoutMs
Test Files  1 passed (1)
Tests       9 passed (9)

• Observed result after fix: the runtime test that specifically exercises periodic flushing passes, and the config is now registered in OpenClawConfig and the zod schema so the setting is actually usable end-to-end.
• What was not tested: full live multi-hour reasoning run with forced crash/restart while periodic flushing is enabled.
• Before evidence (optional but encouraged): before this branch, there was no registered trajectory.flushTimeoutMs config path and no periodic-flush runtime coverage.

Root Cause (if applicable)

• Root cause: the trajectory runtime had no supported configuration path for periodic flushing, so in practice flushing happened only at explicit lifecycle boundaries.
• Missing detection / guardrail: config typing/schema coverage did not fail when the new trajectory setting was absent from top-level config registration, and there was no focused runtime test covering periodic flush timing.
• Contributing context (if known): review follow-up also tightened timer lifecycle behavior so the periodic timer runs independently and does not reschedule incorrectly after flush.

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/trajectory/runtime.test.ts
• Scenario the test should lock in: when flushTimeoutMs is configured, the runtime periodically flushes buffered events without waiting for shutdown or turn/session end.
• Why this is the smallest reliable guardrail: the timing behavior belongs to the runtime recorder itself, and the focused runtime test covers timer creation, flush execution, and continued runtime semantics without requiring a full gateway boot.
• Existing test that already covers this (if any): src/trajectory/runtime.test.ts now includes fires periodic flush after flushTimeoutMs.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Users/operators can now configure trajectory.flushTimeoutMs to periodically flush in-flight trajectory events to disk during long reasoning sessions. Default behavior remains unchanged when unset.

Diagram (if applicable)

Before:
[reasoning events buffered] -> [flush only on explicit boundary/shutdown]

After:
[reasoning events buffered] -> [periodic timer fires] -> [flush to disk]

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

Repro + Verification

Environment

• OS: Linux
• Runtime/container: local repo checkout
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): trajectory.flushTimeoutMs=<set in test scenario>

Steps

1. Check out pr-78133.
2. Run node scripts/run-vitest.mjs run --config test/vitest/vitest.unit-fast.config.ts src/trajectory/runtime.test.ts --reporter=verbose.
3. Confirm the periodic flush test passes.

Expected

• Runtime accepts configured periodic flush timeout.
• Periodic flush test passes.

Actual

• Passed: Test Files 1 passed, Tests 9 passed, including the periodic flush scenario.

Evidence

Attach at least one:

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

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: config path is present in typing/schema diff; focused runtime test passes on branch pr-78133.
• Edge cases checked: existing runtime tests for sanitization, truncation, pointer writing, and disabled mode still pass.
• What you did not verify: live production trajectory files during a real long-running reasoning session.

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.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) Yes
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: Optional new config trajectory.flushTimeoutMs may be added; otherwise no action required.

Risks and Mitigations

• Risk: too-small flush interval could increase disk I/O.
  • Mitigation: setting is opt-in and defaults to current behavior when unset.
• Risk: timer lifecycle bugs could cause duplicate or missing flushes.
  • Mitigation: focused runtime test coverage locks in periodic flush behavior.

Real behavior proof

$ node scripts/run-vitest.mjs run --config test/vitest/vitest.unit-fast.config.ts src/trajectory/runtime.test.ts --reporter=verbose

 RUN  v4.1.5 /tmp/pincer-openclaw

 ✓  unit-fast  src/trajectory/runtime.test.ts > trajectory runtime > resolves a session-adjacent trajectory file by default 2ms
 ✓  unit-fast  src/trajectory/runtime.test.ts > trajectory runtime > sanitizes session ids when resolving an override directory 1ms
 ✓  unit-fast  src/trajectory/runtime.test.ts > trajectory runtime > records sanitized runtime events by default 5ms
 ✓  unit-fast  src/trajectory/runtime.test.ts > trajectory runtime > bounds large runtime event fields before serialization 2ms
 ✓  unit-fast  src/trajectory/runtime.test.ts > trajectory runtime > stops runtime capture at the file budget and records a truncation event 3ms
 ✓  unit-fast  src/trajectory/runtime.test.ts > trajectory runtime > writes a session-adjacent pointer when using an override directory 1ms
 ✓  unit-fast  src/trajectory/runtime.test.ts > trajectory runtime > keeps pointer write flags usable when O_NOFOLLOW is unavailable 0ms
 ✓  unit-fast  src/trajectory/runtime.test.ts > trajectory runtime > does not record runtime events when explicitly disabled 0ms
 ✓  unit-fast  src/trajectory/runtime.test.ts > trajectory runtime > fires periodic flush after flushTimeoutMs 4ms

 Test Files  1 passed (1)
       Tests  9 passed (9)
    Start at  22:35:51
    Duration  379ms

The updated test advances fake timers through three consecutive 5-second intervals and asserts flushCalls.toHaveLength(3), proving the timer repeats for the lifetime of the recorder. Previously the test only checked one tick.

Behavior or issue addressed: Periodic trajectory flush timer was single-shot — only fired once per session.
Real environment tested: Node.js v24.14.0, vitest v4.1.5, /tmp/pincer-openclaw on Linux.
Exact steps or command run after this patch: node scripts/run-vitest.mjs run --config test/vitest/vitest.unit-fast.config.ts src/trajectory/runtime.test.ts --reporter=verbose
After-fix evidence: Terminal output above — all 9 tests pass including the repeating-interval test.
Observed result after fix: Flush timer reschedules itself after each tick; three consecutive intervals all fire.
What was not tested: Live gateway run with a real long-running session; the timer behavior is covered by the fake-timer integration test.