fix: show readable session names across Windows UX

[RomneyDa]

Closes #981

What Problem This Solves

Fixes an issue where Windows users opening session pickers, the Sessions page, or tray menus would see opaque Gateway routing keys and machine-like IDs, especially for channel, heartbeat, subagent, cron, and TUI sessions.

Why This Change Was Made

Consumes the Gateway's additive session presentation contract, preserves the raw key only for routing, and keeps a conservative fallback for older Gateways. Friendly titles now use explicit labels and Gateway presentation metadata; background sessions are hidden by default with an opt-in toggle, while an explicitly active background chat remains selectable.

The fallback recognizes only established built-in key families and treats the remaining key tail as opaque text, shortening UUID/hash runs instead of teaching WinUI every Gateway routing grammar.

User Impact

Session surfaces show useful names instead of values such as agent:main:tui-847241c7-…:heartbeat. Foreground chats are easier to find, duplicate friendly names remain distinguishable, account/agent/node context appears as secondary text, and routing continues to use the exact original session key.

Evidence

• Shared resolver and parser tests cover Gateway presentation precedence, configured main-session keys, all built-in fallback families, opaque-ID redaction, and default/opt-in background visibility.
• Tray tests cover duplicate-title stability, Gateway agent grouping, background picker behavior, dashboard/tray foreground selection, and unchanged routing IDs.
• git diff --check passed.
• Native Windows CI passed on commit 80dbd80a: 2,815 Shared, 1,716 Tray, 422 Connection, 126 WinNode CLI, 18 Tray integration, 10 functional UI, 423 SetupEngine, 78 Tray UI, and 19 accessibility tests.
• All three native E2E shards passed: 16 setup/connect, 1 revocation/recovery, and 2 network/recovery tests executed successfully.
• Release builds and uploaded artifacts passed for both win-x64 and win-arm64.
• Build and Test run: https://github.com/openclaw/openclaw-windows-node/actions/runs/29291054905
• Fresh full-branch Codex autoreview completed with no accepted/actionable findings.

Post-merge-and-fix validation (head 43688024)

• Build: All 5 projects built successfully (Shared, Cli, WinNodeCli, SetupEngine, WinUI).
• Shared.Tests: 2961 passed, 31 skipped (+4 new clone isolation tests).
• Tray.Tests: 1851 passed (+3 new ChatDataProvider routing/visibility tests, +3 new dashboard ended-session tests).
• UITests: 108 passed (SessionTitleBehaviorProofTests green at this exact head).
• Merge conflicts (from 75c6a1a4): 2 files resolved surgically — ChatDataProvider and ChatRoot.
  • Kept PR's AgentId/IsBackground from SessionPresentationResolver.
  • Kept main's SessionVisibilityFilter.ToChatThreadStatus (ended-session classification from fix(chat): hide completed sessions from picker #1016/fix(sessions): classify terminal sessions as ended #1017).
  • Kept main's VisibleChatPickerThreads and IsVisibleInChatPicker guards.
  • Both background-filter and ended-filter applied in sequence.
• Review fixes (in 43688024):
  • SessionInfo.Clone() now deep-copies Presentation and Worktree (snapshot isolation, fix(gateway): isolate the SessionsUpdated snapshot from live tracked state #1012 invariant).
  • TrayDashboardSummary.SelectActiveSession deprioritizes ended sessions as fallback display.
  • Added runtime behavior tests for routing-key preservation, ended+background filter composition, and AgentId precedence.

Change Type

• Bug fix
• Feature
• Refactor
• Docs or instructions
• Tests or validation
• Security hardening
• Chore or infrastructure

Scope

• Tray or WinUI UX
• Windows node capability
• Local MCP or winnode
• Gateway, connection, or pairing
• Setup or onboarding
• Permissions, privacy, or security
• Tests, CI, or docs

Validation

• git diff --check — passed.
• xmllint --noout on all five changed locale resources — passed.
• Fresh Codex autoreview/rubber-duck review — clean; clone isolation and ended-surface findings addressed.
• Post-fix local validation (head 43688024): build ✅, Shared 2961/31skipped ✅, Tray 1851 ✅, UITests 108 ✅.
• SessionTitleBehaviorProofTests (real-process UIA) passed at head 43688024: duplicate titles render distinctly, routing uses original raw keys.

Real Behavior Proof

Fresh current-head proof (head 43688024)

SessionTitleBehaviorProofTests at commit 43688024 (July 20, 2026):

• Environment: Windows 11 x64, .NET 10.0.302, WinAppSDK 2.3.1.
• The test launches the real OpenClaw.Tray.WinUI.exe in an isolated data directory.
• Navigates to Sessions page, verifies two sessions with duplicate DisplayName="OpenClaw Windows Tray" render as distinct titles ("OpenClaw Windows Tray" and "OpenClaw Windows Tray (2)").
• Clicks "Open in chat" on each and verifies the route target uses the original raw keys (agent:main:main and agent:main:fork).
• Result: PASS — routing IDs preserved, presentation titles derived, no colon-splitting heuristic.

Earlier ARM64 proof (head 80dbd80a)

Collected on July 15, 2026 with Parallels Windows workflows.

• Before ref: merge-base 77c42440376e.
• After ref: PR head 80dbd80ad780.
• Before observation: routing-derived qualifier OpenClaw Windows Tray (main/fork).
• After observation: neutral title OpenClaw Windows Tray (2), agent main as context, and Show background control visible.
• Artifact store: https://gist.github.com/RomneyDa/a6050959640d02f6e98584c2b39cffb3

Before — merge-base 77c42440376e

After — PR head 80dbd80ad780

Security Impact

• New permissions or capabilities? (Yes/No): No
• Secrets or tokens handling changed? (Yes/No): No
• New or changed network calls? (Yes/No): No
• Command or tool execution surface changed? (Yes/No): No
• Data access scope changed? (Yes/No): No
• If any answer is Yes, explain the risk and mitigation: N/A

Compatibility and Migration

• Backward compatible? (Yes/No): Yes
• Config or environment changes? (Yes/No): No
• Migration needed? (Yes/No): No
• Hard merge dependency on the coordinated Gateway PR? No. Gateway presentation metadata is optional, and older Gateways use the bounded client fallback.
• Preferred rollout: Gateway PR feat: expose session classification facts openclaw#106832 first, then this Windows consumer, so titles, families, and background state come from the authoritative producer rather than fallback parsing.
• The coordinated Gateway contract is additive and wire-only; it does not change SQLite or require a data migration. Its current draft head is 63ff2e8bd6eeadc3dd56d2f2f1237f30e101a529.

Review Conversations

• I replied to or resolved every bot review conversation addressed by this PR.
• I left unresolved only conversations that still need maintainer judgment.

Coordinated Gateway contract PR: openclaw/openclaw#106832

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 17, 2026, 9:33 PM ET / July 18, 2026, 01:33 UTC.

Summary
The branch adds structured Gateway session-presentation parsing, localized readable session titles, background-session filtering, and raw-key-preserving routing across Windows chat, tray, dashboard, and Sessions UX.

Reproducibility: yes. at source level: current main derives titles and grouping from legacy fields and colon-delimited routing keys, so generated and background sessions can surface as opaque identifiers. A current-main live recording is not needed to establish the affected code path, but would strengthen the user-visible baseline.

Review metrics: 3 noteworthy metrics.

• Diff breadth: 27 files; 1,474 added, 172 removed. The change spans protocol parsing, shared models, four user-facing Windows surfaces, five locale resources, and regression coverage.
• Localization surface: 5 resource files changed. Generated titles and the Show background control must remain consistent across all shipped locales.
• Validation scope: 9 test/protocol files changed. The patch adds coverage for presentation parsing, routing identity, title uniqueness, visibility, and native UI behavior.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #981
Summary: This PR is the candidate implementation for the canonical opaque-session-key Windows UX report; the upstream Gateway PR is a cross-repository dependency, not a same-repository cluster member.

Members:

• canonical: Render sessions without opaque routing keys #981 - The issue defines the same presentation metadata, privacy-safe fallback, structured grouping, and background visibility behavior that this PR implements.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🦐 gold shrimp
Patch quality: 🐚 platinum hermit
Result: blocked until stronger real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P1] Add a redacted current-head native WinUI capture or equivalent UI Automation artifact that includes the tooltip and the changed session views.
• Obtain a maintainer decision on default background-session visibility and the upstream contract rollout.

Proof guidance:

• [P1] Needs stronger real behavior proof before merge: The linked screenshots and real-process UI evidence convincingly cover the larger title and visibility change at 80dbd80a, but the current 6c679e00 head adds a visible tooltip behavior that is not directly proven from the current revision; add a redacted current-head capture or UI Automation/live-output artifact. 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.

Risk before merge

• [P1] Merging changes existing navigation defaults: background sessions disappear from chat, tray, and dashboard flows, while only the Sessions page offers an opt-in visibility control.
• [P2] The optional upstream Gateway presentation contract is still open, so its field semantics and fallback precedence need explicit cross-repository ownership before Windows treats them as durable UX behavior.
• [P1] The posted visual proof covers the earlier 80dbd80a revision, not the current 6c679e00 tooltip addition; current-head UI proof is still needed.

Maintainer options:

1. Preserve existing session visibility (recommended)
   Keep all existing session rows reachable by default and defer background filtering until maintainers choose a consistent cross-surface policy.
2. Accept the new default explicitly
   Approve hiding background families across chat, tray, and dashboard, with the Sessions-page control as the intended recovery path.
3. Pause for Gateway contract alignment
   Hold the Windows consumer until the coordinated upstream presentation schema is accepted and its fallback semantics are stable.

Next step before merge

• [P2] A maintainer must choose the durable session-visibility and upstream-contract policy; no narrow mechanical repair is established without that choice.

Maintainer decision needed

• Question: Should Windows hide background session families by default in chat, tray, dashboard, and Sessions UX while adopting the still-open Gateway presentation contract?
• Rationale: Tests establish that the mechanics work, but they cannot decide whether removing currently visible session rows from several existing navigation surfaces is the intended permanent user policy or whether the producer contract is ready to anchor it.
• Likely owner: shanselman — Recent gateway and tray history makes this person the strongest available routing candidate for the cross-repository compatibility and UX-policy choice.
• Options:
  • Confirm contract and visibility policy: Approve the additive Gateway field semantics and the per-surface background-session defaults, then require refreshed current-head WinUI proof before merge.
  • Preserve existing visibility first (recommended): Land readable titles and structured grouping while keeping background sessions visible by default until a separate UX decision defines a consistent opt-in path across all surfaces.
  • Defer coordinated consumption: Keep this draft open until the upstream Gateway contract merges and its field semantics can be reviewed as a stable producer-consumer interface.

Security
Cleared: The diff changes session parsing, presentation models, resources, WinUI behavior, and tests without adding dependencies, workflows, permissions, secret handling, artifact downloads, or an execution boundary.

Review details

Best possible solution:

Confirm the upstream presentation contract and the intended default visibility policy, then retain the raw-key routing boundary and bounded fallback while refreshing redacted native WinUI proof from the current head.

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

Yes, at source level: current main derives titles and grouping from legacy fields and colon-delimited routing keys, so generated and background sessions can surface as opaque identifiers. A current-main live recording is not needed to establish the affected code path, but would strengthen the user-visible baseline.

Is this the best way to solve the issue?

Yes for the resolver shape: structured producer metadata plus a bounded older-Gateway fallback and separate raw routing key is maintainable. No for the unapproved visibility default: that policy should be confirmed or split before merge.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🐚 platinum hermit.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The linked screenshots and real-process UI evidence convincingly cover the larger title and visibility change at 80dbd80a, but the current 6c679e00 head adds a visible tooltip behavior that is not directly proven from the current revision; add a redacted current-head capture or UI Automation/live-output artifact. 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.
• 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: 📣 needs proof.

Label justifications:

• P2: This is a meaningful but bounded Windows session-navigation improvement without evidence of an urgent runtime or delivery outage.
• merge-risk: 🚨 compatibility: The PR intentionally changes which existing sessions appear in ordinary navigation and introduces a still-unsettled producer-consumer presentation contract.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp 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 linked screenshots and real-process UI evidence convincingly cover the larger title and visibility change at 80dbd80a, but the current 6c679e00 head adds a visible tooltip behavior that is not directly proven from the current revision; add a redacted current-head capture or UI Automation/live-output artifact. 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.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The linked screenshots and real-process UI evidence convincingly cover the larger title and visibility change at 80dbd80a, but the current 6c679e00 head adds a visible tooltip behavior that is not directly proven from the current revision; add a redacted current-head capture or UI Automation/live-output artifact.

Evidence reviewed

What I checked:

• Current main does not already solve it: The PR introduces the new SessionPresentationResolver, structured SessionInfo.Presentation projection, and title/visibility consumers; the supplied base-to-head diff shows these capabilities are absent from current main. (src/OpenClaw.Shared/Sessions/SessionPresentationResolver.cs:1, 6c679e002649)
• Compatibility-sensitive default change: Chat selection, tray menus, and dashboard selection filter sessions marked background, while the explicit Show background control is provided only on the Sessions page. Existing users can therefore lose ordinary navigation paths to sessions they previously saw. (src/OpenClaw.Tray.WinUI/Pages/SessionsPage.xaml.cs:128, 6c679e002649)
• Routing identity remains separate: The branch keeps the exact session key as the chat thread ID and carries title, agent, and background information separately, which is the appropriate boundary for a presentation-only change. (src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs:6017, 6c679e002649)
• Current-head proof gap: The posted before/after proof identifies 80dbd80ad7800cdd710fcd007194ba128614f6ce as its after revision, while the current head is 6c679e0026492930c3e00e3cc917dfb25d09d181, whose added tooltip behavior is not directly shown by that evidence. Repository policy requires UI proof from the current head. (src/OpenClaw.Tray.WinUI/Chat/OpenClawComposer.cs:426, 6c679e002649)
• Repository UI-proof policy: AGENTS.md requires current-head visible proof for tray and chat UX changes, along with required automated validation and a rubber-duck review for non-trivial UI work. (AGENTS.md:278, 4518dd87ed2b)
• Canonical same-repository work: The PR explicitly closes the still-open canonical Windows report, which requests presentation metadata, bounded older-Gateway fallbacks, structured grouping, and background-session handling. The linked upstream Gateway PR remains open, so it is a coordinated dependency rather than proof that this PR is obsolete. (src/OpenClaw.Shared/OpenClawGatewayClient.cs:1777, 6c679e002649)

Likely related people:

• shanselman: Prior feature-history review connects recent Gateway client and tray behavior work to the cross-repository compatibility decision this PR introduces. (role: recent gateway and tray area contributor; confidence: medium; commits: 2cae69ba; files: src/OpenClaw.Shared/OpenClawGatewayClient.cs, src/OpenClaw.Tray.WinUI/Services/SessionTitleFormatter.cs, src/OpenClaw.Tray.WinUI/Pages/SessionsPage.xaml.cs)
• RomneyDa: Authored the canonical session-UX report, coordinated the upstream presentation proposal, and iterated through parser, sparse-update, compatibility, localization, and drift-guard changes in this area. (role: feature investigator and current area contributor; confidence: high; commits: d1703c7c48cb, daf8d0b92795, 9c0ee129d732; files: src/OpenClaw.Shared/Sessions/SessionPresentationResolver.cs, src/OpenClaw.Shared/OpenClawGatewayClient.cs, src/OpenClaw.Tray.WinUI/Services/SessionTitleFormatter.cs)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

• 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.

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

• reviewed 2026-07-14T11:12:26.927Z sha 80dbd80 :: needs maintainer review before merge. :: none
• reviewed 2026-07-14T11:31:30.091Z sha 80dbd80 :: needs maintainer review before merge. :: none
• reviewed 2026-07-14T11:51:05.109Z sha 80dbd80 :: needs maintainer review before merge. :: none
• reviewed 2026-07-14T12:12:46.119Z sha 80dbd80 :: needs maintainer review before merge. :: none
• reviewed 2026-07-14T12:37:31.762Z sha 80dbd80 :: needs maintainer review before merge. :: none
• reviewed 2026-07-14T13:02:47.644Z sha 80dbd80 :: needs maintainer review before merge. :: none
• reviewed 2026-07-16T02:01:03.952Z sha 80dbd80 :: needs maintainer review before merge. :: none
• reviewed 2026-07-18T01:26:49.528Z sha 1481659 :: needs maintainer review before merge. :: none

[RomneyDa]

this was inspired by screenshot: