#3365 [GUI] Add Optional Windows Tray For Local Model Control On 0.2.0

本文

## Problem and result

Windows users need quick access to their local Strata server without keeping a console or browser open. This opt-in Tray adds a read-only client and a separately configured managed mode for model profiles, context, idle unload and explicit Preload/Unload. It is not installed or started by the default installer.

## Related discussion

#2034. Continuation of #2035 after the tracker reset: GitHub refused to reopen the closed PR even after restoring its previous head, and the reset bot suggested a replacement. This candidate is rebased onto 0.2.0-beta `main` (`e88ee39d`). **Ready for review. Scope agreement for the managed feature is still requested.** The earlier issue proposed a narrower read-only client. No maintainer agreement on the expanded scope is assumed.

The separate Local Model Extension scope is #3369. This Tray provides its optional single-owner protocol; the Extension UI stays in #3373.

## Approach

All files are isolated under `tools/windows-tray/`. Existing engine, server, frontend, setup and default installation files are byte-identical to the base revision (`git diff e88ee39d -- . ':!tools/windows-tray'` is empty). The Tray forwards client authentication unchanged and owns only the processes in its private Windows Job. Lifecycle changes close admission and drain admitted requests before acting; occupied ports are refused. Startup and restart stay lazy.

Managed mode uses the official context choices (8K, 32K, 64K, 128K, 200K, 256K, 384K, 512K), and Never/5/10/30-minute idle unload, preserving original profiles and saved settings. Selected/effective settings remain distinct. An optional `desktop_app` path adds Open Strata App and a separate App update metadata check using the official feed. App installation and signature verification stay in the App. Legacy engine staging is retained only for legacy assets; signed 0.2 component releases defer to the official component updater.

The current official desktop icon is embedded. Production menu construction is shared with a native fixture renderer so the examples below come from real WinForms controls, not a recreated mockup. No personal configuration, model ID, private path or original user screenshot is included. This generic candidate has no Codex dependency or client-capacity synchronization.

`app_extension` defaults to false and publishes no companion IPC files unless opted in. When enabled, it publishes fresh allowlisted owner metadata and claims one UUID/physical-model-bound context, idle, load or unload command into the existing serial worker. Identity is checked at execution. Durable terminal acknowledgments precede claim removal; interrupted claims are never replayed. The companion has no independent inference process or HTTP lifecycle bypass.

## Examples

**These are anonymous simulated menu states**, rendered offscreen by the production `ManagedMenu` through WinForms `DrawToBitmap`. The fixture starts no Tray controller, server, App, updater or inference. Submenus are placed beside the main menu for readability. Captions and the official icon sit outside the controls. These images do not establish server health, installed updates or GPU behavior.

**Managed Menu**

<img src="https://raw.githubusercontent.com/medking82/Strata/ff69390ecaeb6e130cbe1939d78c64d6fa60a81b/tools/windows-tray/screenshots/managed-menu.png" width="523" alt="Sanitized simulated managed Tray menu with official icon">

**Official Context Choices**

<img src="https://raw.githubusercontent.com/medking82/Strata/ff69390ecaeb6e130cbe1939d78c64d6fa60a81b/tools/windows-tray/screenshots/context-menu.png" width="694" alt="Simulated Tray context submenu with all eight official choices">

**Idle Unload**

<img src="https://raw.githubusercontent.com/medking82/Strata/ff69390ecaeb6e130cbe1939d78c64d6fa60a81b/tools/windows-tray/screenshots/idle-menu.png" width="742" alt="Simulated Never, 5, 10 and 30-minute idle unload choices">

**Engine Updates** — signed component installation belongs to the official updater.

<img src="https://raw.githubusercontent.com/medking82/Strata/ff69390ecaeb6e130cbe1939d78c64d6fa60a81b/tools/windows-tray/screenshots/engine-update-menu.png" width="850" alt="Simulated Engine update submenu deferring to the official component updater">

**App Updates** — checks App metadata and opens the App to install.

<img src="https://raw.githubusercontent.com/medking82/Strata/ff69390ecaeb6e130cbe1939d78c64d6fa60a81b/tools/windows-tray/screenshots/app-update-menu.png" width="850" alt="Simulated separate App update submenu">

The added `screenshots/README.md` and `MenuExamples.cs` document reproducible generation. All five PNGs were visually inspected and have no text/EXIF metadata.

## Validation

Windows x64, .NET Framework compiler v4, Python 3.12; candidate `ff69390e` on base `e88ee39d`. Commands below omit the local windowless-runner wrapper and use a disposable output/dependency directory.

**Passed:**

- Production, test and example WinForms executables compiled from the same production sources, manifest and official icon. `TrayTests.exe`: **81 checks passed**, including actual PerMonitorV2, loopback parsing, auth/redirect boundaries, diagnostic privacy, App metadata checks, menu/control states, all eight context choices and lifecycle disable states.
- `TrayMenuExamples.exe --out <screenshots directory>`: five native PNGs generated and inspected, with anonymous fixture data. No runtime or model launched.
- `python -B tools/windows-tray/managed/test_extension.py`: **15 new tests passed**, covering opt-in defaults, exactly-once file claims, queue/execution identity, all context/idle values, drain behavior, acknowledgment ordering, duplicates, interrupted recovery and truthful loaded/unknown states.
- `python -B -m unittest -v test_managed.ConfigTests test_managed.UpdateTests test_managed.LifecycleTests.test_lazy_start_restart_and_update_do_not_preload test_managed.LifecycleTests.test_development_version_starts_but_update_requires_exact_version` from `tools/windows-tray/managed`: **12 affected existing tests passed**, with no server process launched.
- The separate Extension's cross-language test consumed Node-produced commands through this exact Python IPC and observed terminal state without repeating commands.
- The preceding `d2303a53` revision's full managed suite had **16 tests passed** using the base's unmodified official MockEngine and disposable streaming fixtures. This is prior evidence, not a newly rerun full suite. MockEngine always reports loaded and fixed 32768 context.
- `git diff --check` passed; all changed paths are below `tools/windows-tray/`.

**Failed:**

- None unresolved in the final checks. The preceding full mock run initially needed the base's `jinja2` and `regex` dependencies; that run passed after adding those official dependencies in an isolated test directory, without changing production Python.

**Not run:**

- The four existing cases that launch a mock server were not rerun for this IPC/menu update. Real GPU cold load, generation, unload/idle timing or upgrade; Windows reboot/autostart; cross-monitor transitions; configured-App launch and App installer interaction remain unverified. No inference or model download was submitted.

## Limits

Scope agreement and targeted Windows hardware acceptance remain outstanding. Signed component installation belongs to the official updater. This Tray does not provide a general upstream plugin API or native prepared-model registration. Read-only mode accepts no API key and reports authentication required for protected servers. Optional companion IPC state must remain private; stale running markers block replay until manually inspected.