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.

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 after accepted parser, privacy, sparse-update, and legacy-alias fixes.
• Native Windows Build and Test workflow 29291054905 — passed, including the required Shared and Tray suites plus downstream connection, CLI, integration, functional UI, SetupEngine, Tray UI, accessibility, E2E, and Release-build lanes.

Real Behavior Proof

Collected on July 15, 2026 with the merged Parallels Windows workflows from openclaw/openclaw#107881 and #992.

• Environment: Parallels Desktop 26.4, Windows 11 ARM64, .NET 10.0.302, Windows SDK 10.0.26100, and WebView2 150.0.4078.65.
• Actual app path: the repository UI proof launches the real OpenClaw.Tray.WinUI.exe in an isolated tray-data directory, navigates the production Hub deep-link path, inspects the rendered WinUI Automation tree, and captures the Hub window.
• Before ref: merge-base 77c42440376e2b8cd503290bb2bfc7ac816bab63.
• After ref: PR head 80dbd80ad7800cdd710fcd007194ba128614f6ce.
• Exact focused command: build tests/OpenClaw.Tray.UITests/OpenClaw.Tray.UITests.csproj for win-arm64, then run SessionTitleBehaviorProofTests with screenshot and proof-output paths enabled.
• Result: both refs built with 0 warnings and 0 errors; the focused real-process UI test passed on both refs.
• Before observation: the second duplicate title exposed the routing-derived qualifier OpenClaw Windows Tray (main/fork).
• After observation: the same row uses the neutral title OpenClaw Windows Tray (2), shows agent main as secondary context, and the Sessions page exposes the new Show background control.
• Routing proof: UI Automation opened both visible rows and confirmed selection still used the original keys agent:main:main and agent:main:fork.
• Scope boundary: this deterministic visual pass proves the real Windows rendering, routing, and older-Gateway fallback path. It does not claim a live integrated sessions.list.presentation response from feat: expose readable session presentation metadata openclaw#106832.
• Artifact store: https://gist.github.com/RomneyDa/a6050959640d02f6e98584c2b39cffb3
• Screenshot or artifact links verified? Yes; both GitHub-hosted PNG downloads matched the captured local SHA-256 hashes.

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 readable session presentation metadata 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 14, 2026, 9:02 AM ET / 13:02 UTC.

Summary
The PR consumes Gateway session-presentation metadata, adds localized legacy title fallbacks, groups sessions by agent, hides background sessions by default with a Sessions-page opt-in, and preserves raw session keys for routing.

Reproducibility: yes. at source level: current main formats and groups sessions from legacy display names and colon-delimited routing-key positions, so generated and background keys predictably surface in Windows UX; no live current-main recording was provided.

Review metrics: 3 noteworthy metrics.

• Diff breadth: 27 files; +1,474 / -172. The change spans protocol parsing, shared models, four Windows UX surfaces, localization, and regression coverage.
• Localization surface: 5 locale resources changed. Generated titles and the background-session toggle must remain consistent across every shipped locale.
• Validation surface: 9 test or protocol-snapshot files changed. Coverage addresses parsing, privacy-safe fallbacks, routing identity, grouping, visibility, and UI title behavior.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #981
Summary: This PR is the candidate implementation for the repository's canonical opaque-session-key UX report; the cross-repository Gateway PR is a dependency rather than 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 requirements implemented here.

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

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🦪 silver shellfish
Patch quality: 🦞 diamond lobster
Result: blocked until real behavior proof from a real setup 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 redacted current-head screenshots or a short recording showing readable titles, duplicate disambiguation, foreground defaults, and the Show background toggle.
• Obtain explicit approval for the upstream presentation contract and per-surface background-session policy.

Proof guidance:

• [P1] Needs real behavior proof before merge: Native CI, UI fixtures, accessibility tests, E2E shards, and release builds are strong supplemental evidence, but this visible WinUI change still needs a redacted current-head screenshot or recording of the Sessions page, picker, and tray behavior; after updating the PR body, review should rerun automatically, or a maintainer can comment @clawsweeper re-review. 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

• [P2] The coordinated Gateway presentation contract remains open upstream; merging the Windows consumer first could lock in field semantics or fallback behavior before the producer contract is accepted.
• [P1] Background sessions that users can currently reach through tray, dashboard, or chat navigation become hidden by default; the opt-in toggle exists only on the Sessions page.
• [P1] No redacted current-head screenshot or recording demonstrates layout, localization, duplicate-title disambiguation, or discoverability of the background toggle.

Maintainer options:

1. Confirm contract and visibility (recommended)
   Approve the upstream field semantics and each surface's background-session default, then collect current-head WinUI proof before landing both sides.
2. Preserve current visibility initially
   Merge readable titles and structured grouping while keeping all currently reachable sessions visible until a separate UX decision changes the defaults.
3. Pause for the Gateway contract
   Keep the draft open or re-propose it after the producer contract is stable if coordinated landing cannot be guaranteed.

Next step before merge

• [P2] A maintainer should approve the upstream contract and default visibility semantics, then require current-head native WinUI proof; no narrow mechanical defect is established for automated repair.

Maintainer decision needed

• Question: Should Windows adopt the proposed Gateway presentation contract and hide background session families by default across chat, tray, dashboard, and Sessions UX, with opt-in visibility only on the Sessions page?
• Rationale: Tests establish mechanics but cannot decide the permanent cross-repository contract or whether removing background sessions from existing navigation is the intended product policy.
• Likely owner: shanselman — This is the strongest available routing candidate from recent Gateway-client and tray history for the cross-repository compatibility choice.
• Options:
  • Approve contract and policy (recommended): Accept the additive Gateway schema and proposed visibility behavior, then require current-head WinUI proof before merge.
  • Split titles from visibility: Land readable structured titles while preserving existing visibility, then review background filtering separately.
  • Defer Windows consumption: Wait until the upstream Gateway contract is merged and released before finalizing the Windows parser and UX.

Security
Cleared: The diff changes session parsing, presentation models, WinUI behavior, resources, and tests without adding permissions, dependencies, secret handling, downloaded code, workflow execution, or a broader data-access boundary.

Review details

Best possible solution:

Approve and land a stable additive Gateway presentation contract with the Windows consumer, retain raw-key routing and the bounded older-Gateway fallback, explicitly confirm each surface's background-session policy, and capture redacted current-head WinUI evidence before merge.

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

Yes at source level: current main formats and groups sessions from legacy display names and colon-delimited routing-key positions, so generated and background keys predictably surface in Windows UX; no live current-main recording was provided.

Is this the best way to solve the issue?

Yes for the implementation shape: structured Gateway presentation with a bounded legacy fallback and separate raw routing identity is the narrowest maintainable approach, but the default visibility policy and rollout still require approval.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

• P2: This is a meaningful session-navigation usability improvement with bounded impact, strong automated coverage, and no urgent workflow outage.
• merge-risk: 🚨 compatibility: Merging intentionally changes which existing sessions appear in ordinary navigation and depends on an upstream presentation contract that remains open.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦪 silver shellfish and patch quality is 🦞 diamond lobster.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: Native CI, UI fixtures, accessibility tests, E2E shards, and release builds are strong supplemental evidence, but this visible WinUI change still needs a redacted current-head screenshot or recording of the Sessions page, picker, and tray behavior; after updating the PR body, review should rerun automatically, or a maintainer can comment @clawsweeper re-review. 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

What I checked:

• Current main still uses legacy presentation logic: The base-to-head patches show main deriving titles from DisplayName or ShortKey and grouping agents through colon-delimited routing keys; the structured resolver exists only on this branch. (src/OpenClaw.Tray.WinUI/Services/SessionTitleFormatter.cs:7, 77c42440376e)
• Structured Gateway contract consumption: The branch adds presentation, lineage, worktree, agent, channel, and background metadata to SessionInfo and projects those fields from sessions.list while retaining Key for routing. (src/OpenClaw.Shared/OpenClawGatewayClient.cs:1777, 80dbd80ad780)
• Compatibility-sensitive visibility policy: Background sessions are removed from chat selection, tray menus, and dashboard active-session selection by default; only the Sessions page adds a Show background toggle. (src/OpenClaw.Tray.WinUI/Pages/SessionsPage.xaml:41, 80dbd80ad780)
• Routing identity remains separate: Chat threads retain the original session key as Id and compose operations use the Gateway-provided main key while presentation metadata is carried separately. (src/OpenClaw.Tray.WinUI/Chat/OpenClawChatDataProvider.cs:5783, 80dbd80ad780)
• Strong automated validation: Native Windows Shared, Tray, connection, CLI, integration, functional UI, SetupEngine, Tray UI, accessibility, three E2E shards, and x64/ARM64 release builds passed on the reviewed head. (80dbd80ad780)
• Visible proof remains absent: The PR states that no manual current-head screenshot was captured and inspection of the running Sessions page was blocked; automated tests do not directly show the changed WinUI experience. (80dbd80ad780)

Likely related people:

• shanselman: Repository release history shows recent merged work in OpenClawGatewayClient and tray behavior, making this person the strongest available routing candidate for the cross-Gateway Windows UX decision. (role: recent gateway and tray area contributor; confidence: medium; files: src/OpenClaw.Shared/OpenClawGatewayClient.cs, src/OpenClaw.Tray.WinUI/Services/SessionTitleFormatter.cs, src/OpenClaw.Tray.WinUI/Pages/SessionsPage.xaml.cs)
• RomneyDa: Beyond proposing the branch, this repository member authored the canonical issue, coordinated the upstream contract, and iterated through parser, sparse-update, legacy-main, localization, and protocol-drift fixes. (role: feature investigator and current area contributor; confidence: high; commits: 3647e6c6aafe, be8030402fc4, d14e30fffe13; 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 (9 earlier review cycles; latest 8 shown)

• reviewed 2026-07-13T22:42:21.004Z sha e532ba0 :: needs maintainer review before merge. :: none
• reviewed 2026-07-13T22:52:11.122Z sha 80dbd80 :: needs maintainer review before merge. :: none
• reviewed 2026-07-13T23:12:59.504Z sha 80dbd80 :: needs maintainer review before merge. :: none
• 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

[RomneyDa]

this was inspired by screenshot: