Fix devcontainer reliability and enable one-click full-stack desktop GUI launch

[rwilliamspbg-ops]

Summary

This PR delivers two connected improvements:

1. Hardens the devcontainer setup so dependencies and tooling install reliably in Codespaces/devcontainer environments.
2. Completes one-click full-stack launch behavior so launch scripts and compose flows can auto-start the desktop GUI when supported.

What Changed

Devcontainer reliability

• Updated .devcontainer/devcontainer.json

  • Corrected workspace folder to /workspaces/${localWorkspaceFolderBasename} for Codespaces compatibility.
  • Added Docker access feature: ghcr.io/devcontainers/features/docker-outside-of-docker:1.
  • Added useful extensions for this repo workflow (ms-python.python, ms-python.vscode-pylance, ms-azuretools.vscode-docker).
  • Ensured postCreateCommand runs via bash .devcontainer/post_create.sh.

• Updated .devcontainer/Dockerfile

  • Added missing runtime/tooling packages used by launch and diagnostics (python-is-python3, sudo, lsof, net-tools).
  • Added desktop GUI runtime dependencies (libgl1, libegl1, libxkbcommon-x11-0, libdbus-1-3, xauth).
  • Added ldconfig after liboqs install.

• Reworked .devcontainer/post_create.sh

  • Made setup idempotent and root-safe (run_as_root helper for root/sudo execution).
  • Added dual package-manager support paths (apt and apk) for broader compatibility.
  • Added liboqs detection to skip rebuild when already installed.
  • Added .venv bootstrap and Python dependency install from requirements.txt.
  • Added optional fast-path flags for constrained validation runs:
    • MOHAWK_SKIP_LIBOQS_BUILD=1
    • MOHAWK_SKIP_PY_DEPS=1
  • Added a core import sanity check at the end of Python setup.

Full-stack GUI launch wiring

• Updated mohawk_gui/main_window.py

  • Fixed startup-order crash path by creating QStatusBar before tab construction / refresh logic.
  • Deferred health thread startup until UI widgets are fully initialized.
  • Added env-based service URL overrides:
    • MOHAWK_GUI_SERVICE_URL
    • MOHAWK_WORKER_SERVICE_URL

• Updated launch.py

  • Added reusable launch_desktop_gui() helper.
  • Native launch now auto-opens desktop GUI when environment supports it.
  • Docker launch now:
    • sets MOHAWK_SKIP_DESKTOP_GUI=1 when calling compose (prevents duplicate GUI starts),
    • auto-opens host desktop GUI after backend/worker health comes up.

• Updated launch.sh

  • Dependency probe now includes PyQt6, ensuring GUI dependencies are installed in one-click flows.

• Updated docker-compose.yml

  • Added mohawk-desktop-gui service that waits for backend health and launches desktop GUI when DISPLAY is available.
  • Supports skip flag via MOHAWK_SKIP_DESKTOP_GUI.

• Updated docker-compose.dev.yml

  • Added dev equivalents of mohawk-gui, mohawk-worker, and mohawk-desktop-gui for full-stack parity.
  • Adjusted legacy worker_secure host mapping from 8003:8000 to 8005:8000 to avoid port collision.

Validation Performed

Static and syntax validation

• No VS Code Problems in touched files.
• python3 -m py_compile launch.py mohawk_gui/main_window.py mohawk_gui/main.py succeeds.
• bash -n .devcontainer/post_create.sh succeeds.
• JSON validation of .devcontainer/devcontainer.json succeeds.

Devcontainer post-create smoke test

• MOHAWK_SKIP_LIBOQS_BUILD=1 MOHAWK_SKIP_PY_DEPS=1 bash .devcontainer/post_create.sh succeeds.

Environment cleanup

• Removed local caches and bytecode artifacts.
• Cleared package caches where available.
• Stopped test services after validation and restored tracked cache artifacts to keep repo state clean.

Full functional validation (inference + model flows)

• Started local backend and worker on 127.0.0.1:8003 and 127.0.0.1:8004.
• Ran python test_user_functions.py.
• Result: 33/33 passed (100.0%).
• Explicitly validated:
  • model listing (/api/models),
  • model selection/load (/api/models/load),
  • chat inference (/api/inference/chat, 3/3 requests passed).

Notes

• Full desktop GUI visual runtime in a headful host still depends on display availability (DISPLAY/X11).
• API-level and orchestration behavior for model selection + chat inference is validated end-to-end in this run.

Documentation Update (2026-07-11)

Additional docs commit pushed to this PR: 17c1080.

Updated:

• README.md
• QUICKSTART.md
• DOCKER_SETUP.md
• INSTALL.md (new)
• SETUP.md (new)
• CHANGELOG.md

This adds clear install/setup instructions for launcher, Docker, native, and devcontainer flows, plus explicit model-select/chat-inference validation commands.