Spec: add a discoverable return to Harness below Control Rail settings #2289

Problem Statement

Humans in Bot mode cannot readily discover how to return to the standard Harness workspace. The top Bot logo can look like branding rather than navigation, so users can believe the previous Harness interface is gone.

Bot mode intentionally remembers whether the Human last had it open and restores that view on the next launch. Installation does not automatically enter Bot mode. The maintainer clarified this on 2026-10-19. Last-opened-mode restoration is expected behavior and must remain intact.

The original report did not record product version or platform and was not independently reproduced in that original environment. Current main's qualified wide workspace presents its exit as a Bot logo that changes to an exit icon on hover or keyboard focus. Existing earlier onboarding work does not fully address this surface: #1496 shipped a checklist and exit walkthrough, while #2200 later replaced the current Desktop first-use journey with Tob + Home and four short layout tips.

Solution

For the qualified wide Desktop/Web workspace, keep the existing top Bot-logo exit behavior and add a second, clearly recognizable, always-visible return icon at the bottom of the Control Rail, immediately below Bot settings.

The new icon's accessible name and tooltip are Back to Harness / 返回 Harness. Clicking it returns to the ordinary Harness workspace immediately through the existing mode-exit operation. It does not stop PersonaBots or reset the Bot-mode layout.

The Human confirmed this solution, first-slice scope and testing seam on 2026-10-19. This issue is the executable specification; publishing it authorizes no implementation, merge or release by this specification task.

User Stories

1. As a Human unfamiliar with Bot mode, I want a recognizable return icon, so that I can discover how to reach the ordinary Harness workspace.
2. As a Human reopening the app in Bot mode, I want the same return control available immediately, so that restored state does not leave me searching for a way out.
3. As a Human entering Bot mode deliberately, I want its return control available without completing onboarding, so that navigation is independent of setup.
4. As a returning Human who skips or pauses onboarding, I want the return icon to remain visible, so that I do not have to replay a tutorial.
5. As a Human scanning the Control Rail, I want the return icon immediately below Bot settings, so that it has a stable place at the bottom.
6. As a Human using the existing top logo, I want it to retain its current exit behavior, so that an established interaction continues to work.
7. As a Human unsure what the new icon does, I want a tooltip naming Harness, so that I understand its destination before clicking.
8. As a keyboard user, I want to focus and activate the return control, so that leaving Bot mode does not require a pointer.
9. As a Human using English or Chinese, I want a localized accessible name and tooltip, so that the destination is understandable.
10. As a Human using either theme, I want a readable icon and visible focus state, so that the return action remains usable.
11. As a Human with Home open or no selected Channel, I want the return control available, so that it does not depend on a conversation.
12. As a Human moving the Control Rail, I want the return control to move with it and stay below settings, so that rearranging panels preserves navigation.
13. As a Human returning to Harness and refreshing, I want Harness to remain selected, so that my explicit exit is remembered.
14. As a Human who later chooses Bot mode again, I want my existing chats, unsent drafts and saved panel layout retained, so that switching views does not erase work.
15. As a Human with running PersonaBot work, I want leaving Bot mode to change the displayed view only, so that an exit control is not mistaken for stopping or logging out.

Implementation Decisions

1. Bounded surface. Implement only the qualified wide Desktop/Web workspace Control Rail. Use the existing workspace eligibility and lifecycle, including its responsive cutoff; do not broaden native-shell qualification or force the wide workspace into an unsupported shell. Narrow responsive Web, mobile Web, the independent Expo app and the legacy sidebar fallback are outside this slice.
2. Two deliberate entry points, one operation. Preserve the top logo's current behavior, including its hover/focus presentation. Add the bottom return control as explicitly requested by the Human. Both invoke the same existing application-defined exit callback. Do not create another mode store, navigation owner or exit lifecycle.
3. Placement and visibility. Place the new icon button immediately after Bot settings at the bottom of the Control Rail, outside the scrolling panel-switch list. Keep it visible without hover, selection or onboarding completion. Moving the Control Rail preserves this order. Do not add a text row or widen the rail for this slice.
4. Label and styling. Use Back to Harness in English and 返回 Harness in Chinese for both the accessible name and tooltip. Reuse the existing exit/return glyph and established Control Rail icon-button and tooltip patterns with DSH tokens. Support hover, focus-visible and ordinary keyboard button activation. The icon must express return in its resting state; it must not show a Bot logo until hover.
5. DSH-native navigation seam. Keep the existing Client Plugin's Slots/layout ownership. The current callback selects the DSH-native Conversation via the public layout operation with a null panel selection. Upstream documents this as changing the selected panel without changing the current Session. BotHarness mode persistence and workspace cleanup remain the existing application-defined behavior. No new Host bridge, API Gateway route, Bot tool or Host persistence is needed.
6. Restoration. Keep the existing last-view preference as the sole mode-restoration authority. A manual exit through either entry point records the ordinary Harness view. Re-entry or a later refresh while Bot mode is active continues to restore Bot mode normally. This work must not alter install defaults or onboarding triggers.
7. Preservation. Reuse current workspace disposal/restoration and native shell recovery. Do not reset panel geometry, create or delete PersonaBots, clear drafts, send messages, stop executions, sign out or add an exit confirmation dialog.
8. Onboarding boundary. Do not restore the old mandatory checklist or introduce a separate first-run hint, new walkthrough step, progress receipt or tutorial reset in this slice. The permanent control works independently of all guide participation states.
9. Delivery records. Implementation updates the maintained Control Rail/mode-exit verification journey and feature map, adds a bilingual release fragment and records any necessary current UI documentation changes. With no new Host operation, there is no new CLI command; existing CLI parity requirements still apply if implementation unexpectedly expands the boundary.

Testing Decisions

1. Human-confirmed highest seam. Acceptance is a real isolated DSH Host operated through the actual Client: enter or restore Bot mode → activate the bottom Back to Harness control → observe ordinary Harness → refresh and remain in Harness → deliberately enter Bot mode again. Use the repository's isolated Host verification workflow. A direct state mutation or mocked layout call alone does not qualify the user path. No model response is required.
2. Observable success. The resting screenshot visibly includes the return icon beneath settings, with no pointer over it. Activation restores native Harness navigation and removes Bot-mode workspace chrome. Re-entry preserves the same PersonaBot/Channel identities, available history, unsent draft and saved panel geometry. Verify canonical identities/history through existing read APIs after the visible actions.
3. Existing test seams. Prefer mounted Client interaction coverage using the existing exit callback and real mode lifecycle over a new Service or reducer. Reuse the sidebar/panel-entry interaction tests, last-view restoration tests, workspace-shell cleanup tests and the maintained panel-workspace browser journey as prior art. Test the new button's click and keyboard behavior, localized accessible label and position relative to settings. Do not use a private state enum or generated CSS snapshot as the acceptance condition.
4. Restoration regression. Cover both deliberate entry and a reload restoring a previously active Bot view. Verify manual exit persists across reload, and explicit subsequent Bot entry still persists normally. Starting with no prior Bot-mode preference must not introduce automatic entry.
5. Presentation matrix. Inspect light/dark and English/Chinese, pointer and keyboard activation, fresh/Home and existing-conversation states, skipped/paused/completed guides, moved Control Rail and a constrained window height. The exit stays reachable when the panel-switch list scrolls. Existing top-logo exit remains functional. Crossing to the narrow fallback must remove the wide-only control and return without losing saved wide layout.
6. Evidence boundaries. Save screenshots, accessible snapshots and console/Client diagnostic output with the exact source revision and runtime version. Browser verification and genuine native Desktop verification are separate results; never label a Web run as Desktop QA. Implementation must record native Desktop review according to the repository UI gate and keep unrun platforms explicit. Before/after PR screenshots must satisfy repository publication rules.

Out of Scope

• Changing last-opened-mode restoration, installation behavior, startup defaults or first-entry triggers.
• Replacing or removing the existing top-logo exit.
• Widening the Control Rail or adding a permanent text row.
• New onboarding flows, mandatory tutorials, extra first-run prompts or restoring the old checklist.
• Narrow/mobile Web, the Expo app or legacy sidebar-fallback redesign.
• The collapsed legacy-rail progress ring and entry hint owned by Onboarding: show the progress ring and "Try it" hint on the collapsed sidebar rail #1519.
• Host APIs, new CLI commands, credentials, model setup, PersonaBot execution controls or production Bot changes.
• [Bug] 工作区写权限授权链路失效：UI 批准后 orchestrator_write 不落盘；grant-write-set 在线/离线均不可用（1.3.1） #2080, Cloud channel UX: source marks, organization navigation and scoped sharing #2161 or 1.4.0: forward-compatible DSH 0.2.x admission and release qualification #2167.
• Implementing code, merging, publishing a release or changing production as part of this specification task.

Further Notes

• Baseline: latest origin/main verified at 99a224faf3d22e7e60e7420b6e410f89f90bad29 on 2026-10-19. This task uses its own codex/2289-bot-mode-discovery branch/worktree and does not carry existing shared-checkout changes.
• Related completed work: Spec: Bot-mode onboarding from the default DeepSeek Bot to a first real conversation #1174, Onboarding: getting-started checklist launched from a progress ring in the Bot-mode row #1496 and feat: simplify Desktop onboarding around Tob and real Home dismissal #2200. Keep this issue focused on the currently agreed permanent bottom return entry rather than reopening their scope.
• Existing startup restoration is supported by current source inspection and the maintainer's correction. The original platform/version remains unknown; this specification does not claim reproduction of that original environment.
• Upstream navigation contract: DSH UI layout. Verify the implementation against the task's installed pinned DSH generation as well as official sources.
• Task reference: codex/local/01a152fa-e500-7cf1-a044-47574cae8cd0 (not a DSH Session). Scope: investigation and specification only. Product code and the new bottom return button are not implemented by this task.
• Specification task claim.
• Baseline verification limit: the unchanged main build completed. The isolated verification launcher then refused before Host launch because the machine-local selected OpenCode Go model is absent from the pinned native catalog. No live Client reproduction, screenshot or native Desktop acceptance was obtained by this specification task. Shared model configuration was not changed; the real UI round trip above remains an implementation acceptance requirement.