#21544: Gateway: include diagnostics state in sessions.list
docs
app: web-ui
gateway
size: S
Cluster:
Session Management Enhancements
Closes #21537.
### What
- Extends `sessions.list` rows with best-effort diagnostics-derived fields:
- `diagnosticsState`: `idle|waiting|processing`
- `diagnosticsStateTs`: epoch ms
- `processingConfirmed`: boolean convenience (`diagnosticsState === "processing"`)
- `diagnosticsQueueDepth` + `diagnosticsReason` when available
- Does **not** create diagnostic entries as a side-effect of listing sessions.
### Tests
- `OPENCLAW_PROFILE= OPENCLAW_GATEWAY_TOKEN= pnpm vitest run --config vitest.gateway.config.ts
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Extended `sessions.list` to include diagnostics-derived fields (`diagnosticsState`, `diagnosticsStateTs`, `processingConfirmed`, `diagnosticsQueueDepth`, `diagnosticsReason`) by introducing `peekDiagnosticSessionState` which reads existing diagnostic state without creating new entries.
- Added `peekDiagnosticSessionState` function in `src/logging/diagnostic-session-state.ts:80` that looks up existing diagnostic state without side-effect creation
- Modified `listSessionsFromStore` in `src/gateway/session-utils.ts:792-818` to call `peekDiagnosticSessionState` and populate new fields
- Updated type definitions in both `src/gateway/session-utils.types.ts:28-37` and `ui/src/ui/types.ts:395-399` with matching field types
- Added `lastReason` tracking to `SessionState` type and `logSessionStateChange` function
- Included comprehensive test coverage for all scenarios (state present, absent, sessionId-only lookup)
- Updated documentation to describe the new best-effort fields
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk
- The implementation is clean, well-tested, and follows the stated goal of not creating diagnostic entries as a side-effect. The new `peekDiagnosticSessionState` function correctly returns undefined for non-existent states rather than creating them. Type definitions are consistently updated across both gateway and UI. Comprehensive tests cover all key scenarios including the critical behavior of not creating entries when none exist.
- No files require special attention
<sub>Last reviewed commit: de25216</sub>
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#18179: CLI: add sessions --json-debug diagnostics
by p6l-richard · 2026-02-16
77.2%
#17530: refactor(sessions): centralize session status field extraction
by Facens · 2026-02-15
73.5%
#12234: gateway: incident tracking, recover command, and ciao ERR_SERVER_CL...
by levineam · 2026-02-09
72.8%
#16865: fix(diagnostics-otel): share listeners/transports across module bun...
by leonnardo · 2026-02-15
72.2%
#22469: fix(gateway): avoid stale whatsapp labels on direct sessions
by loganprit · 2026-02-21
71.9%
#20431: fix(sessions): add session contamination guards and self-leak lock ...
by marcomarandiz · 2026-02-18
71.0%
#20148: fix(memory): persist session dirty state and fix reindex gate
by togotago · 2026-02-18
71.0%
#17132: fix: filter out invalid session entries with empty sessionFile
by Limitless2023 · 2026-02-15
70.7%
#13412: fix(sessions): refresh allowAgents permissions after gateway restart
by arun-dev-des · 2026-02-10
70.5%
#4154: fix(control-ui): preserve URL session parameter over localStorage d...
by joeyfrasier · 2026-01-29
70.5%