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 review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed September 12, 2026, 6:46 AM ET / 10:46 UTC (Revision 18).

ClawSweeper review

What this changes

Adds a draft RFC proposing authoritative sidebar collection summaries and independently paginated session rows loaded according to visible demand.

Merge readiness

⛔ Blocked before merge - 5 items remain

This remains a distinct, coherent design proposal that is absent from current main. Repository policy reserves acceptance for maintainers, and the prior RFC-only proof exception remains unresolved.

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

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The document is coherent and has no actionable patch findings, but the unresolved proof requirement limits readiness.
Proof confidence	🦪 silver shellfish (2/6)	Needs stronger real behavior proof before merge: The captured evidence validates RFC authoring, not the proposed Gateway collections or sidebar runtime. Resolve the literal rfcs/ exemption gap through an explicit maintainer override; implementing the design first would invert the repository lifecycle. Any voluntarily supplied runtime evidence should redact private details; updating the PR body triggers re-review, with a maintainer able to request @clawsweeper re-review if needed. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs stronger real behavior proof before merge: The captured evidence validates RFC authoring, not the proposed Gateway collections or sidebar runtime. Resolve the literal rfcs/ exemption gap through an explicit maintainer override; implementing the design first would invert the repository lifecycle. Any voluntarily supplied runtime evidence should redact private details; updating the PR body triggers re-review, with a maintainer able to request @clawsweeper re-review if needed. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	7 items	Complete introduced document: Read all 412 lines of the sole added RFC. It defines summaries, membership precedence, demand loading, cursor fencing, migration steps, alternatives, and unresolved questions; it introduces no executable implementation. Current-main necessity check: Current main contains no equivalent sidebar collection RFC. Searching its RFC text found only unrelated collection/sidebar references; the bounded GitHub PR listing likewise identified no replacement proposal. No shipped implementation or release is established by this documentation repository. Acceptance precedes merge: The full README requires draft RFCs to remain unmerged until acceptance, followed by an implementation issue and accepted frontmatter. Keeping issue blank now follows that lifecycle rather than constituting a patch defect.
Findings	None	None.
Security	None	None.

How this fits together

The proposed Control UI sidebar would receive session membership and attention summaries from the Gateway, then request children for expanded, visible collections. A single virtualized list would turn those results into session navigation; this PR only documents that architecture.

flowchart TD
  A[Sessions and attention facts] --> B[Gateway collection summaries]
  C[Global sidebar filters] --> B
  B --> D[Sidebar collection manifest]
  D --> E[Expanded and visible collections]
  E --> F[Independent child pages]
  F --> G[Virtualized session navigation]

Loading

Decision needed

Question	Recommendation
Should this RFC-only PR receive an explicit proof override so design acceptance can precede runtime implementation?	Override proof for this design document: Apply an explicit RFC-only proof override and assess the architecture through the normal acceptance process, reserving runtime proof for implementation.

Why: The repository lifecycle places implementation after acceptance, while the review contract's automatic documentation exemption only covers docs/ paths.

Before merge

• Add real behavior proof - Needs stronger real behavior proof before merge: The captured evidence validates RFC authoring, not the proposed Gateway collections or sidebar runtime. Resolve the literal rfcs/ exemption gap through an explicit maintainer override; implementing the design first would invert the repository lifecycle. Any voluntarily supplied runtime evidence should redact private details; updating the PR body triggers re-review, with a maintainer able to request @clawsweeper re-review if needed. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Resolve merge risk (P1) - Maintainer acceptance of the collection architecture and its unresolved provider/count tradeoffs is not established.
• Resolve merge risk (P1) - The external-PR proof rule excludes rfcs/ from its automatic docs exemption, leaving a policy mismatch for a proposal intentionally awaiting implementation.
• Complete next step (P2) - Resolve the RFC-only proof override and obtain maintainer acceptance; then update accepted status and the implementation-issue link before merge.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Change footprint	1 RFC added; documentation +412 lines; production +0; tests +0	The branch proposes an architecture without changing runtime behavior or persisted data.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Accept a bounded collection-read architecture before implementation, with browser and compatibility evidence attached to subsequent implementation slices.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Accept a bounded collection-read architecture before implementation, with browser and compatibility evidence attached to subsequent implementation slices.

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

Not applicable to this documentation patch; the linked report supplies a concrete motivating scenario, but this review did not execute the OpenClaw sidebar.

Is this the best way to solve the issue?

Yes as a design proposal: independent collection ownership addresses truncated global grouping coherently, while provider contracts and performance budgets appropriately remain acceptance questions.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning medium; reviewed against 967d9aac7472.

Labels

Label justifications:

• P3: This is a design-document proposal with no shipped behavior change.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The captured evidence validates RFC authoring, not the proposed Gateway collections or sidebar runtime. Resolve the literal rfcs/ exemption gap through an explicit maintainer override; implementing the design first would invert the repository lifecycle. Any voluntarily supplied runtime evidence should redact private details; updating the PR body triggers re-review, with a maintainer able to request @clawsweeper re-review if needed. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Complete introduced document: Read all 412 lines of the sole added RFC. It defines summaries, membership precedence, demand loading, cursor fencing, migration steps, alternatives, and unresolved questions; it introduces no executable implementation. (rfcs/0031-demand-driven-session-sidebar-collections.md:1, 04bec7369788)
• Current-main necessity check: Current main contains no equivalent sidebar collection RFC. Searching its RFC text found only unrelated collection/sidebar references; the bounded GitHub PR listing likewise identified no replacement proposal. No shipped implementation or release is established by this documentation repository. (967d9aac7472)
• Acceptance precedes merge: The full README requires draft RFCs to remain unmerged until acceptance, followed by an implementation issue and accepted frontmatter. Keeping issue blank now follows that lifecycle rather than constituting a patch defect. (README.md:88, 967d9aac7472)
• Process-history routing: Current-main path history identifies the RFC-process update, and GitHub commit metadata maps its author to kevinslin. Local blame and historical patch inspection could not complete because required historical objects were unavailable; no source-line introduction attribution is asserted. (README.md:91, e366ea9825a4)
• Linked immediate repair is not a merged replacement: fix(ui): make sidebar session pagination global openclaw#126708 is closed without merging. Its body describes relocating global pagination and explicitly excludes category-scoped queries; it does not establish implementation of this RFC.
• Concrete motivating report: Bug: named session groups omit members beyond the global roster page openclaw#126701 remains open and describes ten category members with only one present in the first global 60-session page. This supports the proposal's motivation but is not a current-runtime reproduction performed by this review.

Likely related people:

• kevinslin: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

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

• Obtain an explicit RFC-only proof override.
• After maintainer acceptance, set status to accepted and link the implementation issue required by README.

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 (17 earlier review cycles; latest 8 shown)

• reviewed 2026-08-27T12:17:14.264Z sha 04bec73 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-29T16:59:06.995Z sha 04bec73 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-29T23:05:16.930Z sha 04bec73 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-30T07:44:19.929Z sha 04bec73 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-31T18:10:45.331Z sha 04bec73 :: needs real behavior proof before merge. :: none
• reviewed 2026-09-01T05:57:15.869Z sha 04bec73 :: needs real behavior proof before merge. :: none
• reviewed 2026-09-03T04:53:26.025Z sha 04bec73 :: needs real behavior proof before merge. :: none
• reviewed 2026-09-05T01:13:53.379Z sha 04bec73 :: needs real behavior proof before merge. :: none