Summary

• Problem: gateway diagnostic heartbeats can keep reporting queued work during CPU/event-loop pressure while low-priority session tool mirrors continue at normal priority.
• Solution: record a bounded diagnostic queue-pressure backoff window and use it to suppress non-terminal session-scoped tool mirrors.
• What changed: diagnostic heartbeat state now exposes an active queue-pressure backoff, and gateway tool event fanout keeps run-scoped and terminal tool updates flowing while backing off lower-priority session mirrors.
• What did NOT change (scope boundary): this does not change core tool execution, provider behavior, run-scoped tool subscribers, or terminal session tool events.

Motivation

• The linked bug has a 60s CPU sample where gateway CPU averaged 83.66% with 42/60 samples at or above 100%, while heartbeats still reported active=1 queued=3 and a fetch timeout drifted by 7175ms. Backing off lower-priority mirror traffic during that condition reduces avoidable websocket work while preserving completion signals.

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]: Gateway scheduler keeps work queued while CPU is saturated #84844
• Related #
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: Gateway scheduler pressure from [Bug]: Gateway scheduler keeps work queued while CPU is saturated #84844. During sustained gateway CPU pressure with queued work, lower-priority session tool mirror events should back off while terminal and run-scoped tool events still flow.
• Real environment tested: Local Linux OpenClaw worktree on Node 24, using the repo Vitest wrapper plus the redacted runtime/pidstat log evidence from the affected gateway run.
• Exact steps or command run after this patch: node scripts/run-vitest.mjs src/logging/diagnostic.test.ts src/gateway/server-chat.agent-events.test.ts and git diff --check.
• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output): Copied terminal capture from the patched worktree:

$ node scripts/run-vitest.mjs src/logging/diagnostic.test.ts src/gateway/server-chat.agent-events.test.ts

Test Files  2 passed (2)
     Tests  118 passed (118)

$ git diff --check
(no output; exit 0)

• Observed result after fix: The regression coverage now proves diagnostic queue-pressure backoff is recorded and cleared, non-terminal session-scoped tool mirrors are suppressed during the active backoff window, run-scoped tool recipients still receive tool events, and terminal session tool events (end, error, result) are preserved so UI tool cards can complete.
• What was not tested: I did not rerun the private 60s live CPU-saturation gateway session because the original setup/session details are local and redacted; the fix was verified at the diagnostic and gateway fanout seams that own this behavior.
• Before evidence (optional but encouraged): Redacted source evidence from the affected run:

pidstat summary:
rows=60
avg_cpu=83.66
avg_usr=79.42
avg_sys=4.25
cpu_ge_100_count=42
max_cpu=190.0 at 05:07:47
avg_rd=0.00

Gateway log correlation:
2026-05-21T05:07:27.790+00:00 diagnostic heartbeat: webhooks=0/0/0 active=1 waiting=0 queued=3
2026-05-21T05:08:04.306+00:00 fetch-timeout timeoutMs=10000 elapsedMs=17175 timerDelayMs=7175 eventLoopDelayHint="timer delayed 7175ms, likely event-loop starvation"
2026-05-21T05:08:04.316+00:00 diagnostic heartbeat: webhooks=0/0/0 active=1 waiting=0 queued=3

Root Cause (if applicable)

• Root cause: diagnostic heartbeat liveness already identified pressure reasons and queued work, but gateway session tool mirror fanout did not use that pressure signal to reduce lower-priority websocket work.
• Missing detection / guardrail: there was no test covering queue-pressure backoff state or session tool mirror suppression during that state.
• Contributing context (if known): terminal session tool events still need to be delivered even under pressure so clients do not leave tool cards stale.

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/logging/diagnostic.test.ts, src/gateway/server-chat.agent-events.test.ts
• Scenario the test should lock in: heartbeat queue pressure activates and clears the backoff state; active backoff suppresses non-terminal session tool mirrors but preserves run-scoped and terminal events.
• Why this is the smallest reliable guardrail: the behavior is owned by the diagnostic heartbeat state and gateway websocket fanout seam, without needing a provider or live channel.
• Existing test that already covers this (if any): none before this patch.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

During diagnostic queue pressure, lower-priority session tool mirror updates may be dropped temporarily; terminal session tool events and run-scoped tool events are still delivered.

Diagram (if applicable)

Before:
[diagnostic pressure + queued work] -> [all session tool mirrors continue]

After:
[diagnostic pressure + queued work] -> [non-terminal session mirrors back off] -> [terminal/run-scoped tool events still flow]

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: Node 24 local worktree
• Model/provider: NOT_ENOUGH_INFO for the original runtime sample; tests do not require provider credentials.
• Integration/channel (if any): Gateway websocket/tool event fanout
• Relevant config (redacted): Original private session details were redacted.

Steps

1. Run node scripts/run-vitest.mjs src/logging/diagnostic.test.ts src/gateway/server-chat.agent-events.test.ts.
2. Run git diff --check.
3. Compare coverage to the redacted before evidence from [Bug]: Gateway scheduler keeps work queued while CPU is saturated #84844.

Expected

• Queue pressure activates a bounded diagnostic backoff when the heartbeat reports pressure reasons and queued work.
• Non-terminal session tool mirrors are skipped during that backoff.
• Run-scoped tool listeners and terminal session events still receive updates.

Actual

• Both targeted test files passed, 118 tests total.
• git diff --check passed with no output.

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: diagnostic queue-pressure backoff state activation/clearing; non-terminal session mirror suppression; terminal and run-scoped event preservation.
• Edge cases checked: diagnostics disabled/stopped clears backoff; terminal tool phases still reach session clients.
• What you did not verify: private live 60s CPU-saturation rerun from the original affected setup.

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): No
• Migration needed? (Yes/No): No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: Suppressing session mirrors too broadly could leave clients with stale tool cards.
  • Mitigation: terminal session tool events are explicitly preserved and covered by regression tests.