feat(ssh): establish desktop controller foundation

[Tutitoos]

Related issue

Closes #151

Result

Draft foundation for the multi-PC Atenea SSH desktop: a fixture-only Wails v2.15.0 window, a separate per-user Go controller, versioned and OS-authenticated local IPC, and a React/TypeScript reference UI. The host list, detail, chat visibility selector and history contain synthetic data. This branch does not read SSH config, store credentials, connect remotely or run prompts.

The window starts its sibling controller on demand. Closing the window leaves the controller running; --stop terminates it. The installation ID is published atomically so simultaneous first launches cannot read a partial UUID. Only one controller can own the local endpoint. The latest process-level test checks that a second controller cannot take a live endpoint and that a killed owner can be restarted before an explicit stop.

A guarded build verifies exact Wails source hashes and applies a temporary host-side patch to the dispatcher and native message entry points on macOS, Windows and Linux. The app fails to compile without that guard. Only the zero-argument ControllerStatus binding, native quit and framework readiness signals are permitted. The frontend uses packaged assets and a restrictive CSP. macOS, Linux and Windows now apply native navigation policies that keep the WebView on the packaged page and cancel new windows. The Windows hook uses a pinned temporary go-webview2 copy, and the guarded Wails copy denies WebView2 browser permissions. No modified dependency is committed.

Plan and evidence

• Native Wails shell, controller and guard tests passed on macOS 15, Windows 2025 and Ubuntu 24.04 at d0ab8c4. The macOS/Linux navigation-policy head 0e6868d passed the native macOS, Windows and Ubuntu matrix. The first Windows navigation attempt at b1609d4 failed its Windows native test process: an imported upstream callback package panicked during initialization under Go 1.26. Current head 3b111b9 keeps its callbacks in the existing edge package; the macOS, Windows and Ubuntu native matrix passed, including the Windows URL-policy unit test and guarded shell build.

• A rendered macOS 26.6.2 arm64 window showed fixture data and a running controller. A separate local navigation-probe build attempted a loopback page; an inspected window-only capture still showed the fixture UI and available controller after the attempt. Native window close left the controller running; explicit stop terminated it. A locally signed user-level copy launched with its sibling controller, then was removed. This is not clean-system installation evidence.

• A Windows 11 Pro build 26200 user-session trial launched transferred binaries whose hashes matched the local build. A window-only capture showed the fixture UI and available controller. A separate navigation-probe build attempted a loopback page; the inspected window-only capture still showed fixture UI and the probe survival message seven seconds later. The exact temporary processes, task and files were removed afterward. A second user-session trial of the normal build at 3091594, with browser permissions denied, rendered the fixture UI and available controller; its transferred EXE hashes matched and its temporary resources were removed. This is not an installer test.

• Ubuntu 24.04 CI launched the packaged window in virtual X11. I inspected the normal, bridge diagnostic and navigation-probe artifacts: each rendered fixture UI with an available controller. The navigation artifact showed the packaged page after the loopback attempt. This does not verify a real desktop session. At b31c28d, a separate Ubuntu CI step passed under headless Weston with GDK_BACKEND=wayland and no X11 display: two shell processes shared one controller, which survived shell termination until explicit stop. The later 5a9235b run captured pixels, inspected separately; it still did not verify user interaction or a real Linux desktop.

• Diagnostic WebView calls to screen and clipboard methods did not return data in the tested macOS, Windows and virtual X11 sessions. The revised Windows and Linux probes classify both calls as timed out after 1.5 seconds; timeout is not explicit rejection and does not exclude a later response. Direct dispatcher and ingress tests assert the host guard rejects unauthorized messages. No returned screen or clipboard data was displayed or logged.

• At code head 9a0ceca, a locally signed macOS app with synthetic data was launched twice in one graphical session with an isolated temporary user-state root. Window-only captures were inspected: both showed the fixture UI and available controller. Process inspection showed two GUI processes sharing one controller. Closing one with its native close button left the other and controller running; reopening rendered the same available state and reused the controller. Closing both left the controller running until explicit --stop. Temporary state and processes were removed. This is one macOS session, not a clean-system installation or cross-user/Linux lifecycle proof. The evidence is documented in desktop/ssh/README.md.

• At code head c33e94f (documentation only after 9a0ceca), a guarded Windows build and sibling controller with matching transfer hashes ran in the logged-in console session with isolated temporary state. An inspected window-only capture for each of two simultaneous windows and a reopened third showed synthetic data and an available controller. The task report confirmed one controller reused across launches, native close of one window leaving the other active, controller survival after all windows closed, and successful explicit stop. The temporary task, processes and files were removed. This is one Windows session, not another-user, Linux desktop, logout, sleep or clean-system installation evidence. It is recorded in desktop/ssh/README.md; all 19 applicable CI checks passed on c81e21a, including native macOS, Windows and Ubuntu; two opt-in checks were skipped.

Validation

• Locally on macOS arm64 with Go 1.26.7: go test -race -count=1 ./... through the pre-push hook, focused controller and IPC race tests, go vet ./..., golangci-lint run with 0 issues, frontend TypeScript check and Vite build, guarded Wails tests/build, and Hugo build passed. The new process-level controller test passed locally with five repetitions.

• The earlier concurrent-ID test reproduced the partial-read failure before the atomic publication fix, then passed 30 race-enabled repetitions after it. Native controller tests, including this test, passed on macOS, Windows and Ubuntu at d0ab8c4.

• Head 3b111b9 passed all checks, including the native three-OS matrix. Head 0013f86 added the opt-in navigation probe and Linux virtual X11 capture; the Linux native job passed and its artifact was inspected. Head 3091594 denied WebView2 browser permissions; its Windows CI job failed because the test script ran upstream graphical cookie tests without COM in the headless runner. Head 4465243 limits that step to the Atenea URL-policy test, while retaining the full guarded shell build; all 19 non-opt-in checks passed on this SHA (two opt-in checks were skipped). The normal Windows build launched and rendered in the active user session with the new setting, which does not independently prove every denied permission. The guarded Windows cross-build passed locally at 4465243, and user-session navigation behavior was observed earlier as described above. The captures show the window remaining on the packaged page; they do not independently identify which layer blocked navigation. A check applies only to the SHA it ran against.

• Review of 3091594 found that the pinned Wails dispatcher logged rejected bridge messages verbatim. Head 4465243 drops them without returning an error, redacts dispatcher error logs and bounds callback IDs to the numeric shape generated by Wails. Synthetic direct-dispatch tests cover rejected calls. The guarded Mac tests/build, Windows cross-build, full Go race suite, vet, lint and module tidy diff passed locally at 4465243; the macOS, Windows and Ubuntu native CI jobs passed on this SHA.

• Head 9a0ceca adds a process-level installation race across eight independent callers and rejects mismatched installation IDs and protocol majors against a running controller before checking that its legitimate client still works. Five focused race repetitions, the full local Go race suite, vet, lint, module tidy diff and Hugo docs build passed. All 19 applicable CI checks passed on this SHA, including native macOS, Windows and Ubuntu; two opt-in checks were skipped. These tests do not replace GUI, another-user/session, logout or sleep/resume observations.

• Head b31c28d added a virtual Wayland lifecycle test. The Ubuntu 24.04 CI job passed; its log confirms two live shell processes with one controller, controller survival after shell termination, and successful explicit stop. The macOS and Windows native jobs also passed. Documentation head 6123965 records the evidence and limits; Hugo built locally. All 19 applicable CI checks passed on 6123965, including native macOS, Windows and Ubuntu; two opt-in checks were skipped.

• Head 5e19990 removes a trailing blank line from the guarded macOS navigation patch. The complete branch diff now passes git diff --check; local guarded Wails tests and the macOS arm64 production build passed. All 19 applicable CI checks passed on this exact SHA, including the macOS, Windows and Ubuntu native matrix and virtual Wayland lifecycle; two opt-in checks were skipped.

• Head 5a9235b added an isolated headless Weston output capture. Ubuntu 24.04 native CI passed, and the downloaded 1024×640 PNG from run 35472421592 was visually inspected: it showed the synthetic device list, example-data badge and Controlador disponible. The CI assertion checks one nonempty PNG; visual content was confirmed separately. Documentation head e97ce06 records this virtual-session evidence and its limits. Hugo built locally. All 19 applicable CI checks passed on e97ce06, including native macOS, Windows and Ubuntu and the virtual Wayland capture; two opt-in checks were skipped.

• Head 2758583 ran the loopback navigation probe under virtual Wayland. The Ubuntu 24.04 native job passed; the downloaded 1024×640 PNG from run 35473466233 was inspected and showed the packaged fixture page, available controller and survival message seven seconds after the attempt. This does not identify the blocking layer or cover real desktop Wayland. Documentation head abcae29 records the observation; Hugo built locally. All 19 applicable CI checks passed on abcae29, including native macOS, Windows and Ubuntu and the virtual Wayland navigation capture; two opt-in checks were skipped.

• Head 8448576 adds a Linux launcher that checks for a graphical session and reports missing linked libraries before starting the native window. The packaged layout now includes the launcher, native binary and sibling controller. Local shell diagnostics, Python syntax check, git diff --check, Hugo build and the pre-push Go suite passed. Ubuntu CI passed its native build, launcher diagnostics, virtual X11 render and virtual Wayland lifecycle steps on this SHA. These checks do not establish installation or behavior in a real Linux desktop session. All 19 applicable checks passed on this exact SHA, including native macOS, Windows and Ubuntu; two opt-in checks were skipped.

• Head 1d6e569 resolves a Terminal symlink to the packaged Linux launcher before finding its sibling window binary. Local diagnostics cover a relative PATH link and an excessive link chain; shell syntax, Hugo, git diff --check, commit and pre-push checks passed. All 19 applicable CI checks passed on that exact SHA, including native Ubuntu launcher and desktop jobs; two opt-in checks were skipped. This change does not establish real Linux desktop installation or session behavior.

• Head 0f9cc34 adds an Ubuntu CI render from a copied three-executable package through a relative Terminal link under virtual X11, using isolated temporary user state. Local launcher diagnostics, shell syntax, workflow YAML parse, Hugo build, git diff --check and the pre-push Go suite passed. The Ubuntu native job passed on this exact head; I inspected linux-installed-link.png from run 35524939038, which visibly shows the fixture device list, example-data badge and Controlador disponible. All 19 applicable CI checks passed on 0f9cc34, including native macOS, Windows and Ubuntu; two opt-in checks were skipped. This is not a clean installation or a real Linux desktop session.

• Head 9cfc896 rejects oversized bound-call messages at the macOS, Linux and Windows native ingress, including the Windows additional-objects path, before dispatcher handling. The 4096-byte boundary and rejection at 4097 bytes have focused tests. Local guarded Wails tests, macOS production build, Go vet, lint, Hugo, Python syntax and the pre-push Go suite passed. All 19 applicable CI checks passed on this exact head, including native macOS, Windows and Ubuntu; two opt-in checks were skipped. No real SSH data was used.

• Head 0073317 restores a visible focus ring around the fixture search and makes the history shortcut honor reduced-motion settings. The frontend TypeScript check, production build, guarded macOS Wails build, Hugo and pre-push Go suite passed locally. All 19 applicable CI checks passed on this exact head; two opt-in checks were skipped. Native keyboard and assistive-technology acceptance remains open.

• Head 865f70b adds a probe-only direct WT framework message that would change the native window title if the Wails ingress guard allowed it. The Ubuntu virtual X11 smoke step now checks the title remains Atenea SSH after the WebView loads. Local frontend check/build, Hugo, shell/Python syntax, guarded macOS normal and probe builds, and pre-push Go suite passed. The build script confirms the probe is present only in the diagnostic bundle. The Ubuntu native job passed on this exact head, including the virtual X11 title assertion. I inspected linux-bridge-probe.png from run 35527530629: the fixture page and available controller remain visible, with screen and clipboard probes reporting no response after 1.5 seconds. All 19 applicable CI checks passed on this exact head; two opt-in checks were skipped. A separate local macOS 26.6.2 arm64 synthetic-data probe confirmed that the native title remained Atenea SSH after the direct message. This does not establish behavior in a real Linux desktop or on Windows WebViews.

• Head 90063fa detects a Unix controller socket path that exceeds the platform limit before the desktop window starts the controller. The window now reports a specific path-length error instead of a timeout. A native macOS 26.6.2 arm64 synthetic-data trial reproduced the failure with a 107-byte endpoint, then showed the corrected message and no desktop user-state files. Focused IPC and desktop tests, the full Go race suite, vet, lint, module tidy diff, guarded macOS production build, Hugo and the pre-push Go suite passed locally. All 19 applicable CI checks passed on this exact head, including native macOS, Windows and Ubuntu; two opt-in checks were skipped. The macOS trial does not establish Windows or real Linux desktop behavior.

• Head 415ce0d marks the active sidebar destination and selected synthetic host for assistive technology, and labels the icon-only navigation at narrow window widths. Frontend TypeScript check/build, guarded macOS Wails production build and pre-push Go race suite passed locally. All 19 applicable CI checks passed on this exact head, including native macOS, Windows and Ubuntu; two opt-in integrations were skipped. In a locally signed macOS 26.6.2 arm64 fixture window at 800×600, the native accessibility tree exposed named sidebar buttons and help text. The selected synthetic host appeared as a checked control; pressing another through the accessibility action switched its checked value from 0 to 1 and cleared the previous one. The isolated trial was removed. VoiceOver interaction, additional scaling, Windows/Linux accessibility and keyboard acceptance remain open.

• Head b0d3c52 hides the brand text when the sidebar becomes icon-only. A native Windows 11 Pro console-session trial of a checksum-matched synthetic package at 800×600 first showed the brand text overflowing into the workspace; a window-only capture from the corrected build showed the compact icon rail without that overlap, with fixture hosts and an available controller still visible. The temporary interactive task, isolated state and processes were removed. Windows UI Automation from that task exposed only WebView pane nodes and could not enumerate the controls, so this does not establish Windows assistive-technology acceptance. Frontend TypeScript check, guarded Windows and macOS production builds, git diff --check and the pre-push Go race suite passed locally. All 19 applicable CI checks passed on this exact head, including native macOS, Windows and Ubuntu; two opt-in integrations were skipped.

Risks and rollback

Issue #151 remains open and this PR remains draft. Still open: clean installation on supported systems, actual Linux desktop X11 and Wayland sessions, other-user/session checks, sleep/logout behavior, broader hostile navigation trials and broader direct WebView probes. Simultaneous GUI activation has been observed on macOS and Windows, plus process lifecycle under virtual Wayland; the Linux X11 captures were inspected. Do not connect real SSH data or credentials to this shell until the security and platform gates pass. Rollback removes the new desktop module and controller packages; no production state migration occurred.