Skip to content

feat: hide the desktop lobster while other OpenClaw windows are open - #2340

Merged
karkarl merged 3 commits into
openclaw:mainfrom
karkarl:karkarl-desktop-lobster-visibility
Nov 20, 2026
Merged

karkarl merged 3 commits into
openclaw:mainfrom
karkarl:karkarl-desktop-lobster-visibility

Conversation

@karkarl

@karkarl karkarl commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

What Problem This Solves

The desktop lobster competes with Setup and the main chat/dashboard window for screen space while those windows are open. Users want it to return when those windows are minimized, without repeatedly switching the lobster off and on.

User Impact

User impact: Desktop lobster now has a default-on "Only show when other OpenClaw windows are minimized" preference. Both lobster preferences default on when absent, while explicitly saved choices are preserved.

The lobster rises into view and tucks away over 180 ms, without bounce or activation. Windows animations off makes the transition immediate. The preference observes app-owned Workspace and setup windows, not external browser dashboards.

Why This Change Was Made

WindowManager remains the owner of main-window visibility. DesktopCompanionController applies the preference and hides the existing lobster instead of destroying it, retaining its desktop anchor and quick-chat state without replaying notifications received while hidden. DesktopCompanionWindow owns the reversible native animation and reduced-motion handling.

The Settings row is localized in all six supported locales. Motion follows the native design contract, with inspiration from upstream motion guidance, rather than importing a separate pet-animation system.

Evidence

Focused managed coverage passed for defaulting, explicit opt-out persistence, hide/restore reuse, and notification suppression. Seven focused native ARM64 cases now pass, including a genuinely progressed exit reversal, shutdown visibility suppression, and the new independent Settings toggle.

Live UI Automation against the isolated mock Gateway showed both preferences on and the task-owned mascot after minimizing Workspace. Screenshot capture returned blank images, so visible animation quality is not claimed.

The Hanselman review used claude-opus-5.5 (default context) and gpt-6-astra (long context), both at high reasoning effort. Both reviewed the complete initial head c63a08de306777915c411eb3ebadbd4ffd2292fe and the repair deltas through b722579b00a96bbb21c7c7cd4b3a9fc151489d20. The observed main tip is 8ffe470e7d505aec19b6e59593f982c8ac6893ca; the PR comparison base is a912363c971a3ddf79a6f91a8dcf81c486fbb650. These were app-native, read-only source reviews, not helper-isolated runs or independent runtime validation.

Both reviewers found weak reversal coverage. Opus alone found shutdown visibility callbacks could reopen the lobster; a new native negative control reproduced the unwanted false publication. Both issues are repaired, with cleanup retained. CI also exposed an existing Settings test's single-row assumption, repaired without weakening the size-picker check. Both reviewers found no new verified defects in the final delta. Opus's speculative animation-snap concern did not justify a production change; the native test now requires an intermediate translation, but visible smoothness remains unproven.

Draft / blocked: Final-head build, Shared and Tray checks pass. A wider native attempt failed an untouched shell geometry assertion (64 versus 63.999996185302734) and then the test host crashed. That attempt is not passed, and no merge-base reproduction was performed. Visible animation quality, runtime reduced-motion proof and final-head hosted CI remain unverified.

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

Required proof pools

  • windows-winui-interactive: Verify aggregate minimize/restore behavior, visible entrance/exit and reversal, and Windows reduced-motion behavior in the isolated native app.
  • windows-11-arm64: Native ARM64 build and selected window behavior were exercised locally; this is not complete pool or release proof.

Validation

Final-head ARM64 build and the required Shared and Tray suites passed. $artifacts in the commands below names the task-owned session artifact directory. Earlier failures and the wider native failure remain disclosed.

  • .\build.ps1: passed, including documentation validation.
  • dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj --no-restore --logger 'trx;LogFileName=shared.trx' --results-directory $artifacts --verbosity quiet: passed, 5,911 passed / 0 failed / 28 ordinary opt-in skips.
  • dotnet test .\tests\OpenClaw.Tray.Tests\OpenClaw.Tray.Tests.csproj --no-restore --logger 'trx;LogFileName=tray.trx' --results-directory $artifacts --verbosity quiet: passed, 6,758 passed / 0 failed / 0 skipped.
  • dotnet test .\tests\OpenClaw.Tray.UITests\OpenClaw.Tray.UITests.csproj --no-build --no-restore -r win-arm64 --filter 'FullyQualifiedName~WindowManagerRuntimeAnchorTests|FullyQualifiedName~AutomaticHide_ClosesBubbleButRetainsMountedMascotAndDesktopAnchor|FullyQualifiedName~AnimatedRestore_ReversesAProgressedExitWithoutALateHide|FullyQualifiedName~DesktopLobster_HasNamedDisclosureAndIndependentToggleWithNoneditableSizePicker' --logger 'trx;LogFileName=review-final-focused.trx' --results-directory $artifacts --verbosity quiet: passed, 7 passed / 0 failed / 0 skipped. Tests were compiled from the source committed unchanged to the final head.
  • The shutdown regression failed before repair at Assert.Empty, with visibility publications [False]; it passes after the repair.
  • .\scripts\validate-test-timing-patterns.ps1: passed; unrelated baseline-lowering warnings were not changed.
  • Focused DesktopCompanionTests: 28 passed / 0 failed / 0 skipped in the earlier recorded owner run.
  • git -c core.whitespace=cr-at-eol diff --check: passed before committing.

A wider native attempt that also selected SettingsPageInsetTests.Shell_DeliversFullAndEmbeddedInsetsWithoutMovingBackdropOrReplacingContent aborted. Its unchanged exact-double assertion expected 64, received 63.999996185302734, and the host subsequently failed. The focused seven-case result does not replace that failed attempt. An initial assertion on the newly expanded toggle also ran before its name binding resolved; the test now waits for loaded/named readiness and retains the strict accessible-name assertion.

Earlier Shared attempts at the initial candidate failed: 5,909 passed / 2 failed / 28 skipped (ConnectAsync_TimedOutRetry_DoesNotDisposeNewerConnectionDuringBackoff, ConnectAsync_ManualFailureBeforeHeaders_CannotSatisfyHeldRetryHealthyPrerequisite); an isolated WebSocket selection failed with 63 passed / 1 failed / 0 skipped (ConnectAsync_NewerFailedAttempt_DoesNotAbandonActiveReconnectLoop). The first full motion attempt had 5,908 passed / 3 failed / 28 skipped (ConnectAsync_TimedOutRetry_DoesNotReplaceNewerConnectionAfterAuthorization, ConnectAsync_WhenUpgradeResponseStalls_TimesOutAndRetries, ConnectAsync_StaleAuthorizationDenial_DoesNotFailNewerConnection). No WebSocket code or tests were changed. These attempts are retained, not treated as passing; the latest full suites above ran freshly at the final head.

Real Behavior Proof

  • Environment tested: Windows ARM64, native Debug WinUI tests with isolated profile overrides. Earlier manual observation used the isolated synthetic chat-interactive Gateway and disposable profile. No real Gateway/provider or normal user profile was used.

  • PR head or commit tested: b722579b00a96bbb21c7c7cd4b3a9fc151489d20 for the latest full build/Shared/Tray checks. The seven-case native run used candidate-equivalent source compiled before the commit; the recorded patch SHA256 7AC6F2E1FED25BEFFCA8AF96AC071CD77D8E0CA7C5D0BE83D7CD481AD43EE7B8 matches the committed final test delta. The earlier live mock observation below used c63a08de306777915c411eb3ebadbd4ffd2292fe, not a fresh final-head launch. No binary provenance attestation is claimed.

  • Exact steps or command run: Run the seven-case native filter in Validation. It hides/closes an owned setup window after BeginShutdown, reverses a visible exit with strict intermediate mascot translation, observes the restored window for a bounded late hide, and mounts/invokes the named Settings toggle. Earlier manual steps were to enable the master lobster toggle in the synthetic fixture, confirm minimized-only was already on, and minimize Workspace.

  • Evidence after fix: Native TRX reports 7 passed / 0 failed / 0 skipped, including the explicitly animation-enabled reversal case. Historical copied live UI Automation output:

    AXButton Desktop lobster Value: on ID: SettingsPageDesktopCompanion
    AXButton Only show when other OpenClaw windows are minimized Value: on ID: SettingsPageDesktopCompanionOnlyWhenMinimized
    [after minimizing Workspace]
    AXGroup OpenClaw desktop lobster
      AXButton OpenClaw desktop lobster ID: DesktopCompanionMascot
    
  • Observed result: Current-source native tests confirm no shutdown visibility publications, a progressed reversal with no later hide, mounted-control/anchor retention, aggregate setup-window visibility, and the mounted Settings toggle. The historical mock observation exposed the task-owned mascot after minimizing Workspace. Native state is not rendered pixel or smoothness proof.

  • Screenshot or artifact links verified? (Yes/No/N/A): N/A. No public media or local-only artifact links are presented as reviewable evidence.

  • Not verified or blocked: Visible animation quality (earlier computer-use captures were blank), runtime reduced-motion changes, complete accessibility/pool proof, and final-head hosted CI. Native Settings assertions do not prove view-model persistence; managed coverage owns that boundary. The wider shell-geometry failure and subsequent host crash remain disclosed, without a merge-base comparison. The earlier private-desktop lobster test could not initialize because existing IsShownInSwitchers behavior returned E_NOTIMPL; normal-desktop selected native cases passed. The two independent source reviews do not satisfy these runtime gaps.

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): Yes. Adds persisted DesktopCompanionOnlyWhenMinimized, defaulting to true when absent.
  • Migration needed? (Yes/No): No
  • If yes, list the exact upgrade steps: N/A. Existing saved master-toggle and minimized-only choices are preserved; the master toggle already defaults to true.

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.

Add a default-on minimized-window preference and reversible native entrance and exit motion. Preserve saved choices, desktop position, quick-chat state, and notification suppression across automatic hiding.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@clawsweeper

clawsweeper Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

🦞👀
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 clawsweeper Bot added P3 Low-risk cleanup, docs, polish, ergonomics, or speculative feature. rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. labels Nov 19, 2026
@clawsweeper

clawsweeper Bot commented Nov 19, 2026

Copy link
Copy Markdown

Codex review: blocked before merge.

What this changes

Adds a default-on preference that hides the desktop lobster while app-owned Workspace or setup windows are visible, with animated hide and restore transitions.

Example: Desktop lobster is enabled and Workspace is restored.

  • Before: The lobster remains visible beside Workspace.
  • After: The lobster tucks away and returns when all tracked windows are minimized, hidden, or closed.

Review scores

Measure Result What it means
Overall readiness 🦪 silver shellfish (2/6) The patch is coherent and source review found no actionable defect, but the supplied evidence does not yet cover the complete visible behavior or upgrade boundary.
Proof confidence 🦪 silver shellfish (2/6) Real behavior proof is not required for maintainer- or bot-authored pull requests.
Patch quality 🐚 platinum hermit (4/6) No actionable review findings were identified.

Product

Kind: Feature · Worth it: Yes · Fix scope: Complete
User problem: The desktop lobster occupies screen space while users work in Workspace or setup, requiring repeated manual toggling.
Reason: The maintainer-authored direction provides reversible automatic behavior with an in-product opt-out and retains the existing master preference.

Merge readiness

⛔ Blocked before merge - 1 item remains

Keep this maintainer-authored draft open: current main lacks the feature, and source review found no definite introduced defect.

Priority: P3
Reviewed head: c63a08de306777915c411eb3ebadbd4ffd2292fe

Before merge

  • Add data-model compatibility proof - The review found that existing stored data may not work after upgrade. Show that existing data still loads and works with this change.

Findings

None.

Tests

  • Missing end-to-end proof: Supply current-head visible entrance, exit, reversal, and runtime reduced-motion evidence, plus a latest-stable-to-head run preserving existing settings; redact private endpoints and credentials.
Agent review details

How this fits together

WindowManager reports aggregate window visibility to DesktopCompanionController, which combines it with saved preferences and notification state to control the existing native lobster window.

flowchart TD
  A[Workspace and setup windows] --> B[WindowManager]
  B --> C[DesktopCompanionController]
  D[Saved preferences] --> C
  E[Notification service] --> C
  C --> F[Native lobster window]
Loading

Technical review

Best possible solution:

Complete the existing-owner implementation with demonstrated native transitions and preservation of saved settings across upgrade.

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

This is a feature request rather than a broken-contract report; current-main source confirms that other windows do not currently control lobster visibility.

Is this the best way to solve the issue?

The implementation uses the appropriate existing owners, preserves explicit settings choices and retained chat state, and adds distinct persistence, controller, and native-window coverage without unnecessary architecture.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 8ffe470e7d50.

Provenance checked

  • Desktop companion visibility and notification admission changes intended behavior with a stated reason (fbc0287: The original feature provides a desktop companion for background notifications while keeping notification history with AppNotificationService.)
  • Native lobster show and placement lifetime changes intended behavior with a stated reason (fbc0287: The original native adapter owns nonactivating presentation and placement; retaining the window now requires initial placement only once and reversible hide/show.)
  • App-owned window lifetime keeps the original intent (3a097bc: refactor(tray): extract App-owned surface lifetimes #1085 places concrete window lifetime in WindowManager and leaves App as the composition root.)
  • Settings persistence and binding keeps the original intent (d2638dd: refactor(tray): extract Settings page into a WinUI-free view model over a settings store #1043 establishes the settings-store and view-model save, reload, and echo-suppression contract.)

Testing

Proof path: shipped entry point.

Security

None.

Evidence

What I checked:

  • Introduced change and current-main boundary: The pinned introduction adds the minimized-only preference, aggregate window observation, and native transitions; fetched main still shows the lobster without consulting other windows. (src/OpenClaw.Tray.WinUI/Presentation/DesktopCompanionController.cs:68, c63a08de3067)
  • Preserved ownership and notification contract: Visibility aggregation stays in WindowManager, admission stays in DesktopCompanionController, and native animation stays in DesktopCompanionWindow; hiding clears bubble presentation while retaining the chat mounts and suppressing hidden notification arrivals. (src/OpenClaw.Tray.WinUI/Windows/DesktopCompanionWindow.cs:118, c63a08de3067)
  • Original feature intent: feat: add an animated desktop lobster with notification bubbles #1681 introduced the background desktop companion and retained notification ownership in AppNotificationService; this PR extends that design with an explicit visibility preference. (src/OpenClaw.Tray.WinUI/Presentation/DesktopCompanionController.cs:39, fbc02870795c)
  • Supplied behavior evidence: The complete PR body associates its evidence with the reviewed head and supplies live ARM64 app UI Automation showing both preferences enabled and the mascot exposed after Workspace minimization; it explicitly leaves visible motion and runtime reduced-motion behavior unverified. (c63a08de3067)
  • Persisted setting compatibility: DesktopCompanionOnlyWhenMinimized is added to settings.json through the existing settings owner; tests cover absent-field defaulting and explicit false round trips, but supplied evidence contains no latest-stable-to-head upgrade run. (src/OpenClaw.Shared/SettingsData.cs:36, c63a08de3067)
  • Validation status: Current-head Core and CLI tests, Tray/setup/integration tests, and changed-test soak have passed; UI and E2E checks remain in progress. Reported local Shared timing failures are not established as caused by this diff. (c63a08de3067)

Likely related people:

  • Karen: Raw commit fbc0287 adds src/OpenClaw.Tray.WinUI/Presentation/DesktopCompanionController.cs:37 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: fbc02870795c; files: src/OpenClaw.Tray.WinUI/Presentation/DesktopCompanionController.cs)
  • Barbara Kudiess: Raw commit 3a097bc adds src/OpenClaw.Tray.WinUI/Services/WindowManager.cs:49 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 3a097bc85f7b; files: src/OpenClaw.Tray.WinUI/Services/WindowManager.cs)

Preflight source

Source unknown. Source comparison at the observed PR snapshot only. Completion is self-reported; body, policy, tests, execution, and report bytes are not verified.

Labels

Label changes:

  • add P3: This is optional desktop presentation polish with an existing in-product master toggle.
  • add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.

Label justifications:

  • P3: This is optional desktop presentation polish with an existing in-product master toggle.
  • rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.

Rank-up moves

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

  • Show the native transitions and Windows animation-setting changes in the running app.
  • Demonstrate upgrade from the latest stable release with existing preferences retained.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed November 19, 2026, 3:35 PM ET / 20:35 UTC.

karkarl and others added 2 commits November 19, 2026 15:43
Gate visibility callbacks during shutdown while retaining window observation cleanup. Cover shutdown events and a progressed animation reversal with native regressions.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Require a visible, partly translated mascot immediately before reversal. Locate the size picker among expander rows and wait for the new independent toggle to mount before inspecting its accessible name and action.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@karkarl
karkarl marked this pull request as ready for review November 19, 2026 22:11
@karkarl
karkarl merged commit 794f530 into openclaw:main Nov 20, 2026
57 of 59 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

P3 Low-risk cleanup, docs, polish, ergonomics, or speculative feature. rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant