docs: propose demand-driven session sidebar collections

[clawsweeper]

Related: openclaw/openclaw#126701
Related: openclaw/openclaw#126708
Discussion: https://discord.com/channels/1456350064065904867/1541083365103370340

What Problem This Solves

The Control UI sidebar currently derives heterogeneous groups from a bounded
global session page. An expanded category can therefore look complete while
omitting sessions that fall beyond the global page, and loading another global
page can redistribute rows into several unrelated groups.

This RFC gives maintainers a concrete architecture to review before replacing
that behavior.

Why This Change Was Made

The proposal models the sidebar as an async tree: a lightweight root manifest
returns authoritative section summaries, while each expanded and visible
collection owns an independent cursor-backed child connection. A single
flattened virtual list controls rendered demand, and collapsed or distant groups
load no child rows.

The RFC also defines exact local counts, a canonical attention summary,
collection membership precedence, filter/cursor fencing, live invalidation,
bounded caching, failure states, migration steps, alternatives, and unresolved
thresholds.

The RFC remains status: draft; its implementation issue stays blank until
maintainer acceptance.

AI-assisted: yes. Jesse Merhi directed the product requirements and is credited
as an RFC author and commit co-author.

User Impact

This PR changes no shipped behavior. If accepted and implemented, operators
will get complete ordinary groups when they open them, accurate collapsed
counts and attention indicators, and no background loading for sidebar groups
they are not viewing.

Evidence

• Started from rfcs/0000-template.md and includes all required frontmatter
  and top-level sections.
• Audited the current OpenClaw sidebar grouping, pagination, catalog, and
  session-attention owners before defining the proposal.
• Compared the design with VS Code Tree Views, MUI lazy tree loading, TanStack
  Virtual, and the Relay cursor connection contract.
• git diff --cached --check passed before commit.
• Direct documentation review found no broken structure, inconsistent
  ownership rule, or unsupported new dependency.
• External-model autoreview was not run because its safety gate did not
  authorize exporting the unpublished RFC before publication.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 24, 2026, 6:58 PM ET / 22:58 UTC.

ClawSweeper review

What this changes

Adds a 412-line draft RFC proposing independently cursor-paged, demand-driven session collections for the Control UI sidebar.

Merge readiness

⚠️ Ready for maintainer review - 3 items remain

Keep open for maintainer design review: this draft RFC follows the repository’s RFC lifecycle and proposes a substantial future Control UI/Gateway direction that current main does not already contain.

Priority: P3
Reviewed head: 04bec7369788586004cf6efbae04503c99b9f166
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, structurally compliant RFC with no discrete patch defect; its remaining gate is product-direction acceptance.
Proof confidence	🌊 off-meta tidepool	Not applicable: This documentation-only draft does not change runnable behavior, so runtime proof is not applicable.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This documentation-only draft does not change runnable behavior, so runtime proof is not applicable.
Evidence reviewed	4 items	RFC lifecycle compliance: The proposed frontmatter keeps the RFC in draft status, leaves the implementation issue blank, and links this RFC PR, matching the documented pre-acceptance lifecycle. Required RFC structure: The repository requires draft RFCs to use the template shape and remain unmerged until accepted; this document supplies the required Summary, Motivation, Goals, Non-Goals, Proposal, Rationale, and Unresolved questions sections. Not implemented on current main: Current main has no RFC 0031 document, so it cannot already contain this exact design proposal.
Findings	None	None.
Security	None	None.

How this fits together

The Control UI sidebar consumes session data from the Gateway and presents it as operator-facing groups. This RFC inserts a collection manifest and per-collection cursor pages between canonical session ownership and the sidebar’s flattened virtual list.

flowchart TD
  A[Gateway session data] --> B[Collection membership rules]
  B --> C[Sidebar collection manifest]
  C --> D[Visible collection demand]
  D --> E[Independent cursor pages]
  E --> F[Flattened virtual sidebar]

Loading

Decision needed

Question	Recommendation
Should OpenClaw adopt the proposed manifest-plus-independent-collection architecture as the direction for fixing sidebar completeness and demand loading?	Accept as the implementation direction: Create the scoped implementation issue, resolve the listed thresholds there, and update this RFC to accepted.

Why: The RFC deliberately introduces a new cross-boundary Gateway/UI contract and leaves performance and provider-policy thresholds unresolved; code review cannot choose those product and ownership policies.

Before merge

• Add real behavior proof - Not applicable: This documentation-only draft does not change runnable behavior, so runtime proof is not applicable.
• Resolve merge risk (P1) - Accepting the RFC commits future work to a Gateway contract, cursor semantics, cache/invalidation behavior, and migration boundaries that need core Control UI owner agreement before implementation.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
RFC scope	412 added lines, 1 Markdown file	The PR is a single design document rather than a runtime or dependency change.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Use this draft to settle the collection contract and migration boundaries, then create the implementation issue and update the RFC to accepted only after maintainer agreement.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Use this draft to settle the collection contract and migration boundaries, then create the implementation issue and update the RFC to accepted only after maintainer agreement.

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

Not applicable: this PR changes only an RFC document and does not patch runnable behavior.

Is this the best way to solve the issue?

Unclear: the async-tree approach is coherent and specifies ownership and migration boundaries, but core maintainers must decide whether this is the preferred product and Gateway contract.

AGENTS.md: not found in the target repository.

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

Labels

Label justifications:

• P3: This draft proposes a future design direction and changes no shipped behavior.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This documentation-only draft does not change runnable behavior, so runtime proof is not applicable.

Evidence

What I checked:

• RFC lifecycle compliance: The proposed frontmatter keeps the RFC in draft status, leaves the implementation issue blank, and links this RFC PR, matching the documented pre-acceptance lifecycle. (rfcs/0031-demand-driven-session-sidebar-collections.md:8, 04bec7369788)
• Required RFC structure: The repository requires draft RFCs to use the template shape and remain unmerged until accepted; this document supplies the required Summary, Motivation, Goals, Non-Goals, Proposal, Rationale, and Unresolved questions sections. (README.md:78, 04bec7369788)
• Not implemented on current main: Current main has no RFC 0031 document, so it cannot already contain this exact design proposal. (af708f0ddb6f)
• RFC process provenance: The current-main RFC history shows Kevin Lin recently authoring an accepted RFC, supporting routing to an established RFC-area contributor. (rfcs/0027-openclaw-enterprise.md:1, af708f0ddb6f)

Likely related people:

• kevinlin-openai: Authored the current-main RFC 0027 merge and earlier RFC template/process history. (role: recent RFC area contributor; confidence: medium; commits: af708f0ddb6f, e366ea9825a4, bbb4058da234; files: rfcs/0027-openclaw-enterprise.md, README.md, rfcs/0000-template.md)

Rank-up moves

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

• Obtain maintainer agreement on the proposed Gateway/UI contract before creating implementation work.

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 (3 earlier review cycles)

• reviewed 2026-08-23T13:59:04.938Z sha 04bec73 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-23T23:09:58.004Z sha 04bec73 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-24T12:00:55.617Z sha 04bec73 :: needs real behavior proof before merge. :: none