Add bounded session paging and search

[bkudiess]

Related to #953

Stack: 1 of 2. The virtualized/searchable picker will follow as a dependent PR.

Root cause

Windows sent an agentId-only sessions.list request, consumed the stable core default first 100 sessions, and discarded the paging metadata. A user with 1,000 sessions therefore saw only the first 100 and could not discover a matching session on row 900.

Core already owns this server contract through openclaw/openclaw#85237 and the hidden-page paging precedent in openclaw/openclaw#89323. The stable request/result shape is available from v2026.5.22. This PR requires no core change and does not use beta/main-only fields.

What changed

• Added typed stable-safe request/result DTOs for agentId, limit, offset, search, configuredAgentsOnly, and the returned count/cursor metadata.
• Added a focused Shared coordinator that accumulates coherent snapshots in 100-row pages, bounded to 20 pages and 2,000 materialized sessions.
• Added key dedupe, strict cursor progress guards, hidden-only-page continuation, generation-aware cancellation, and stale-response rejection.
• Added approximately 250 ms debounced server search with latest-query ownership, bounded results, current-session pinning, and coherent clear-search restore.
• Added exact per-connection INVALID_REQUEST compatibility fallback. Legacy servers receive the old request exactly once and use bounded local search over only the authoritative visible title/subtitle.
• Preserved existing public request/event APIs and chat-provider behavior while exposing a narrow typed query API for the dependent picker PR.
• Subscribed to session changes before catch-up, while running slow paging concurrently with unrelated usage/node/agent startup reads.
• Closed late/duplicate response ownership paths so canceled typed pages cannot publish stale data.

Scope

This is the lower protocol/query foundation only. It contains no picker UI, Reactor, localization, copy, or design changes.

Validation

Current head: 48d55f6c

$env:OPENCLAW_REPO_ROOT = (Get-Location).Path
.\build.ps1
dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj --no-restore
dotnet test .\tests\OpenClaw.Tray.Tests\OpenClaw.Tray.Tests.csproj --no-restore
dotnet test .\tests\OpenClaw.Connection.Tests\OpenClaw.Connection.Tests.csproj --no-restore
dotnet test .\tests\OpenClaw.SetupEngine.Tests\OpenClaw.SetupEngine.Tests.csproj --no-restore
dotnet test .\tests\OpenClaw.WinNode.Cli.Tests\OpenClaw.WinNode.Cli.Tests.csproj --no-restore

Validation	Result
Build	Passed
Shared	3,459 passed, 32 skipped
Tray	2,037 passed
Connection	535 passed
SetupEngine	703 passed
WinNode CLI	126 passed
Focused protocol/coordinator/client/loopback	253 passed
Focused chat-provider compatibility	284 passed
Exact current-head behavior proof	12/12 passed
Bootstrap paging/race repetition	10/10 invocations, 4/4 each
Debounce latest-wins stress	50/50 passed
git diff --check	Passed
GitHub CI run 30886085792	All required checks passed

Real behavior proof

The redacted current-head live proof ran the real OpenClawGatewayClient.QuerySessionsAsync against OpenClaw Gateway 2026.7.1-beta.2 with an isolated temporary home and exactly 1,000 synthetic sessions. It proves:

• bootstrap published all 1,000 sessions;
• the explicit recent query accumulated all 1,000 sessions in 10 pages of 100;
• server search for proof-session-0900 returned exactly agent:main:proof-session-0900;
• the client retained its 20-page/2,000-session bound.

The isolated Gateway, synthetic store, pairing state, and proof identity were destroyed after capture. The credential-free loopback Gateway test separately exercises the real OpenClawGatewayClient WebSocket path. Its current-head proof source materializes 1,000 sessions through 10 paged request frames and proves server search returns agent:main:900.

The focused 12/12 proof also verifies:

• exact stable request fields, response metadata, and pinned protocol provenance;
• exact legacy fallback and bounded visible-presentation local search;
• subscribe-before-catch-up ordering and mutation supersession during slow paging;
• unrelated startup requests before a 20-page catch-up completes;
• disconnect cancellation, paging-failure isolation, health ownership, and late typed-response rejection;
• operator-read scope suppression, unrelated-error propagation, reconnect reset, and rejection of late old-connection scope failures.

No tokens, credentials, raw session keys, or user content are logged by the proof.

Review

• All independent-review findings were fixed, including cache identity/pin projection, visible-only legacy search, subscribe/catch-up ordering, nonblocking startup, and awaited-response ownership.
• ClawSweeper's operator-read compatibility finding was fixed with generation-owned scope state and deterministic late-response/reconnect coverage.
• Final independent GPT-5.6 Sol re-review: clean, 96% confidence.
• Structured autoreview was attempted on both the full change and final focused fix. It failed closed before model invocation because the bundles exceeded the helper's 180,000-byte safety limit (1,107,199 bytes for the full change and 542,801 bytes for the focused fix), so it produced no findings.
• Final current-head ClawSweeper re-review: ready for maintainer look, proof sufficient, zero findings, zero security issues, and 4/6 Platinum Hermit for overall readiness, proof confidence, and patch quality.
• The remaining hard-gate gap to the requested 5/6 score is live proof against an older Gateway binary. ClawSweeper recommends accepting the exact deterministic fallback coverage, but leaves that compatibility decision to maintainers.

Residual proof gap

The live proof covers the stable expanded paging/search path. Exact legacy fallback and bounded local search are covered deterministically in the current-head test suite, but are not claimed as live proof against an older Gateway binary because no older compatible launcher was available. No UI screenshot is applicable because this PR intentionally has no UI changes.

[clawsweeper]

Codex review: found issues before merge. Reviewed August 5, 2026, 4:14 AM ET / 08:14 UTC.

ClawSweeper review

What this changes

The PR adds bounded paged session retrieval and debounced server-side session search, with a per-connection fallback for older Gateway request shapes.

Merge readiness

⚠️ Needs maintainer review before merge - 5 items remain

Keep open. The paging protocol is well exercised, but this draft changes the existing session-update path to publish up to 2,000 sessions into a current nonvirtualized composer menu; it should not land alone before that UI path is bounded or virtualized.

Priority: P2
Reviewed head: 48d55f6cfd36a83f6e2f3b0b364a68b25e40f6fd
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The live Gateway proof and focused protocol coverage are strong, but the patch is not merge-ready while it exposes the current nonvirtualized picker to full paged snapshots.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (live_output): The PR provides redacted current-head live Gateway proof for 1,000-session paging and search; the finding concerns the untouched downstream picker path rather than absence of protocol proof.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (live_output): The PR provides redacted current-head live Gateway proof for 1,000-session paging and search; the finding concerns the untouched downstream picker path rather than absence of protocol proof.
Evidence reviewed	5 items	Current main behavior: Current main sends sessions.list with only an optional agent identifier, so it relies on the Gateway default page rather than requesting bounded pages. Changed publication path: The PR routes RequestSessionsAsync through the 20-page coordinator and publishes its full coherent snapshot through SessionsUpdated. Current UI fanout: The chat provider rebuilds its session and thread state from every SessionsUpdated payload, and the Reactor composer eagerly creates one RadioMenuItem per available session.
Findings	1 actionable finding	[P1] Keep full snapshots out of the current nonvirtualized picker
Security	None	None.

How this fits together

The Windows gateway client retrieves session metadata from an OpenClaw Gateway and publishes it to chat consumers. This change adds paging, search, cancellation, and legacy compatibility between Gateway RPC responses and the tray’s session list.

flowchart LR
  Gateway[OpenClaw Gateway]
  Client[Windows gateway client]
  Fallback[Compatibility fallback]
  Paging[Bounded paging and search]
  Events[Session update event]
  Picker[Chat session picker]
  Gateway --> Client --> Fallback --> Paging --> Events --> Picker

Loading

Decision needed

Question	Recommendation
Should this foundation preserve the current picker’s bounded event payload until the virtualized picker is ready, or be landed only together with that dependent UI work?	Preserve the current picker bound: Keep the new paged query API, but do not publish its full snapshot through the existing session-update event until the picker consumes it safely.

Why: The safe merge boundary determines whether existing high-session users receive thousands of eagerly materialized menu items, which cannot be resolved by protocol tests alone.

Before merge

• Keep full snapshots out of the current nonvirtualized picker (P1) - RequestSessionsAsync now publishes the coordinator’s full paged snapshot through SessionsUpdated. Current chat state rebuilds from that payload, and the Reactor composer eagerly creates one RadioMenuItem per session, while this PR intentionally omits the dependent virtualized picker. A 1,000-session account therefore moves from the Gateway default page to 1,000 materialized menu entries. Preserve the existing event bound until the new picker lands, or include that picker and a high-session UI proof in the same landing unit.
• Resolve merge risk (P1) - Accounts with hundreds or thousands of sessions would receive up to 2,000 entries through the existing event path, whose current composer eagerly creates every menu item before the dependent virtualized picker exists.
• Resolve merge risk (P2) - The exact legacy fallback is deterministically covered, but the supplied live proof does not exercise an older Gateway binary.
• Complete next step (P2) - A maintainer must choose the safe landing boundary between the new query foundation and the dependent virtualized UI.

Findings

• [P1] Keep full snapshots out of the current nonvirtualized picker — src/OpenClaw.Shared/OpenClawGatewayClient.cs:739-749

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Change size	production +1,097/-43; tests +1,955/-10 across 13 files	The foundation is substantially tested, but its changed session event behavior crosses into an untouched chat UI path.

Merge-risk options

Maintainer options:

1. Keep the existing picker bounded (recommended)
   Revise the event publication path so existing chat consumers do not receive the full paged snapshot before a virtualized picker is available.
2. Merge only with the UI companion
   Treat the protocol and virtualized picker as one landing unit and require a current-head 1,000-session responsiveness proof.

Technical review

Best possible solution:

Keep the existing event-driven picker bounded until a virtualized, searchable picker consumes the new query API, or land both parts as one proven stack with a high-session UI proof.

Do we have a high-confidence way to reproduce the issue?

Yes, from source: current main sends the default session-list request, while the PR changes that same event path to publish the coordinator’s multi-page snapshot; the current picker eagerly maps every available session to a menu item.

Is this the best way to solve the issue?

No. The protocol coordinator is a viable foundation, but publishing its full result through the existing nonvirtualized picker before the dependent UI arrives is not the narrowest safe landing path.

Full review comments:

• [P1] Keep full snapshots out of the current nonvirtualized picker — src/OpenClaw.Shared/OpenClawGatewayClient.cs:739-749
RequestSessionsAsync now publishes the coordinator’s full paged snapshot through SessionsUpdated. Current chat state rebuilds from that payload, and the Reactor composer eagerly creates one RadioMenuItem per session, while this PR intentionally omits the dependent virtualized picker. A 1,000-session account therefore moves from the Gateway default page to 1,000 materialized menu entries. Preserve the existing event bound until the new picker lands, or include that picker and a high-session UI proof in the same landing unit.
  Confidence: 0.98

Overall correctness: patch is incorrect
Overall confidence: 0.96

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against d2de6150753b.

Labels

Label changes:

• add merge-risk: 🚨 availability: The changed event path can feed up to 2,000 sessions into a picker that eagerly constructs every menu item.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (live_output): The PR provides redacted current-head live Gateway proof for 1,000-session paging and search; the finding concerns the untouched downstream picker path rather than absence of protocol proof.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.
• remove status: 👀 ready for maintainer look: Current PR status label is status: ⏳ waiting on author.

Label justifications:

• P2: This is a significant session-scale improvement with a concrete pre-merge UX regression risk, but not an emergency current-main outage.
• merge-risk: 🚨 compatibility: Older Gateways may reject expanded sessions.list fields, making the fallback contract upgrade-sensitive.
• merge-risk: 🚨 availability: The changed event path can feed up to 2,000 sessions into a picker that eagerly constructs every menu item.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (live_output): The PR provides redacted current-head live Gateway proof for 1,000-session paging and search; the finding concerns the untouched downstream picker path rather than absence of protocol proof.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR provides redacted current-head live Gateway proof for 1,000-session paging and search; the finding concerns the untouched downstream picker path rather than absence of protocol proof.

Evidence

What I checked:

• Current main behavior: Current main sends sessions.list with only an optional agent identifier, so it relies on the Gateway default page rather than requesting bounded pages. (src/OpenClaw.Shared/OpenClawGatewayClient.cs:700, d2de6150753b)
• Changed publication path: The PR routes RequestSessionsAsync through the 20-page coordinator and publishes its full coherent snapshot through SessionsUpdated. (src/OpenClaw.Shared/OpenClawGatewayClient.cs:739, 48d55f6cfd36)
• Current UI fanout: The chat provider rebuilds its session and thread state from every SessionsUpdated payload, and the Reactor composer eagerly creates one RadioMenuItem per available session. (src/OpenClaw.Tray.WinUI/Chat/OpenClawReactorChatRoot.cs:1161, d2de6150753b)
• Live protocol proof: The provided current-head live proof demonstrates 1,000-session paging and server search against a real Gateway; it does not demonstrate the existing chat picker after receiving that full snapshot. (48d55f6cfd36)
• Feature history: Recent gateway-client maintenance includes local gateway recovery work, while the current chat surface history includes the Reactor migration and readable-session-name work. (src/OpenClaw.Shared/OpenClawGatewayClient.cs:700, bc210e048aa9)

Likely related people:

• bkudiess: Authored the PR and previously landed current-main gateway recovery work in the same client. (role: recent gateway-client contributor; confidence: high; commits: bc210e048aa9; files: src/OpenClaw.Shared/OpenClawGatewayClient.cs)
• Karen: Recent history attributes the Reactor chat migration, which owns the eager session-menu rendering affected by this change. (role: recent chat-surface contributor; confidence: medium; commits: 9acafa606a4d; files: src/OpenClaw.Tray.WinUI/Chat/OpenClawReactorChatRoot.cs)
• Dallin Romney: Introduced readable session names across the Windows UX, adjacent to the picker’s session presentation path. (role: session-presentation contributor; confidence: medium; commits: 959b3527ac7b; files: src/OpenClaw.Tray.WinUI/Chat/OpenClawChatRoot.cs)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Keep the existing event route bounded or include the virtualized picker in the same stack.
• Add current-head proof that the chat picker remains responsive with 1,000 sessions.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (10 earlier review cycles; latest 8 shown)

• reviewed 2026-08-04T07:05:41.109Z sha 48d55f6 :: needs maintainer review before merge. :: none
• reviewed 2026-08-04T08:02:54.879Z sha 48d55f6 :: needs maintainer review before merge. :: none
• reviewed 2026-08-04T08:10:36.727Z sha 48d55f6 :: needs maintainer review before merge. :: none
• reviewed 2026-08-04T08:20:08.695Z sha 48d55f6 :: needs maintainer review before merge. :: none
• reviewed 2026-08-04T11:09:19.765Z sha 48d55f6 :: needs maintainer review before merge. :: none
• reviewed 2026-08-04T16:02:49.523Z sha 48d55f6 :: needs maintainer review before merge. :: none
• reviewed 2026-08-04T22:04:27.128Z sha 48d55f6 :: needs maintainer review before merge. :: none
• reviewed 2026-08-05T06:27:27.314Z sha 48d55f6 :: needs maintainer review before merge. :: none

[bkudiess]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/30884464991
• Updated: 2026-08-04T06:34:48.912Z

[bkudiess]

@clawsweeper re-review

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.

[bkudiess]

Live Gateway proof on current head

Current head: 48d55f6c

This proof ran the current-head OpenClawGatewayClient.QuerySessionsAsync against a real OpenClaw Gateway 2026.7.1-beta.2, listening on an isolated WSL port with an isolated temporary home. The Gateway store contained exactly 1,000 synthetic sessions and no user data. The proof harness referenced the current-head OpenClaw.Shared.csproj directly.

PROOF_HEAD=48d55f6cfd36a83f6e2f3b0b364a68b25e40f6fd
GATEWAY_VERSION=2026.7.1-beta.2
GATEWAY_KIND=real OpenClaw Gateway with isolated synthetic state
CLIENT_PATH=current-head OpenClawGatewayClient.QuerySessionsAsync
BOOTSTRAP_COUNT=1000
RECENT_COUNT=1000
RECENT_PAGES=10
PAGE_SIZE=100
SEARCH_QUERY=proof-session-0900
SEARCH_COUNT=1
SEARCH_KEY=agent:main:proof-session-0900
SEARCH_MODE=Server
CLIENT_BOUNDS=20 pages / 2000 materialized sessions
RESULT=PASS

The isolated Gateway, synthetic store, pairing state, and proof identity were destroyed after capture. No token, credential, user session, prompt, transcript, or file content is included.

This live proof covers the stable expanded paging/search path. The exact legacy fallback remains deterministic compatibility-test coverage only; this PR does not claim live proof against an older Gateway binary.

[bkudiess]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/30891839466
• Updated: 2026-08-04T08:24:59.002Z