pi-gui/specs/bugs/BUG-20260727-widget-toggle.md

bug_id, status, severity, scope, title

bug_id	status	severity	scope	title
BUG-20260727-widget-toggle	fixed	medium	noctalia-v5-launcher	Repeated status-bar clicks cannot hide the Pi Status UI

BUG-20260727-widget-toggle: Repeated status-bar clicks cannot hide the Pi Status UI

Problem

A Noctalia v5 status-bar click launches or focuses Pi Status UI. A second click must hide the same window, so a window that has moved off-screen can be dismissed and restored with a later click. Instead, every click only shows and focuses the existing window.

Reproduce on Noctalia v5:

1. Start Pi Status UI and the v5 status-bar widget.
2. Click the widget once.
3. Click it again while the Pi Status UI window is visible.
4. Observe that the window remains visible instead of hiding.

Security impact: LOW. No security exploit path was identified; the defect affects local window visibility only.

Root Cause Analysis

Reproduce

The v5 launcher invokes Pi Status UI with --show on every widget click. The desktop app's single-instance handler receives the second launch and always shows/focuses the existing window.

Isolate

The v4 adapter uses Noctalia's native panel toggle and is not part of this failure. The v5 launcher and the desktop app's single-instance handler form the complete click-to-window path.

Hypothesize

1. The launcher requests show rather than toggle. Falsification: require --toggle in the v5 launcher test.
2. The desktop app ignores second-instance arguments. Falsification: define and test a pure window-action selector for visible and hidden states.

Verify

The launcher contains --show, and the single-instance handler discards its argument list before unconditionally calling show/focus. This confirms both hypotheses and the root cause.

Follow-up launch regression

After the generated Tauri target directory was cleaned, the configured default release binary did not exist. The launcher detached through setsid, so Noctalia saw a successful launcher process even though env recorded that the binary was missing. Rebuilding the release binary restores the launcher, and the launcher now checks that its configured binary is executable before detaching.

Fix Approach

Replace the v5 launch request with --toggle. Route --toggle in the desktop single-instance handler to hide a visible window or show/focus a hidden window. Preserve --show as an explicit show/focus operation for future callers.

Risk level: Low. The change is confined to local launcher/window behavior and does not affect bridge protocol, worktree routing, or approvals.

TDD Fix Plan

1. RED: Require the v5 launcher test to use --toggle and reject --show. GREEN: Change the launch argument from --show to --toggle. verify: node --test test/noctalia-v5-plugin.test.js

2. RED: Add Rust tests that characterize --toggle for visible and hidden windows and preserve explicit --show behavior. GREEN: Add a pure action selector and invoke it from the single-instance callback. verify: cargo test --manifest-path ui/src-tauri/Cargo.toml

REFACTOR: Keep argument interpretation independent from Tauri window calls so its behavior remains unit-testable.

Acceptance Criteria

• A v5 widget click launches Pi Status UI with --toggle.
• A second click hides a visible Pi Status UI window.
• A later click shows and focuses the hidden window.
• Explicit --show still shows and focuses the window.
• Existing bridge, plugin, and UI tests pass.
• The launcher rejects a missing or non-executable configured binary before detaching.

Resolution

The v5 widget now launches the desktop app with --toggle. The desktop app converts second-instance arguments and current window visibility into an explicit hide or show/focus action. The launcher also verifies its executable before detaching, and the expected release binary has been rebuilt. Focused Node and Rust characterization tests, the full npm test suite, and npm run check pass.