From cb707395a1f1c687da9e7be53504847fb07b1da0 Mon Sep 17 00:00:00 2001
From: Tristan Simas <tristan.simas@mail.mcgill.ca>
Date: Thu, 30 Jul 2026 20:41:49 -0400
Subject: [PATCH] Launch Windows desktop without a console window

---
 .github/workflows/integration-tests.yml       | 26 ++++++++++++++-----
 packaging/installers/installer_contract.json  |  1 +
 .../installers/windows/Install-OpenHCS.ps1    | 25 ++++++++++++++----
 pyproject.toml                                |  4 ++-
 scripts/render_installer_contract.py          |  8 ++++++
 tests/installer/test_installer_contract.py    |  6 +++++
 .../test_windows_simple_installer.py          |  7 +++++
 7 files changed, 65 insertions(+), 12 deletions(-)

diff --git a/.github/workflows/integration-tests.yml b/.github/workflows/integration-tests.yml
index 74e8941e4..3ae61dd9a 100644
--- a/.github/workflows/integration-tests.yml
+++ b/.github/workflows/integration-tests.yml
@@ -631,19 +631,33 @@ jobs:
           try {
             $shortcut = $shell.CreateShortcut($summary.shortcut_path)
             try {
-              $expectedArguments = (
-                '-NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File "{0}"' -f
-                $summary.launcher_path
+              $contract = Get-Content -LiteralPath $contractPath -Raw |
+                ConvertFrom-Json
+              $environment = @(
+                Get-ChildItem `
+                  -LiteralPath (Join-Path $installRoot "environments") `
+                  -Directory
               )
-              if ($shortcut.TargetPath -ne $powerShellExecutable) {
+              if ($environment.Count -ne 1) {
+                throw "Windows install did not retain exactly one environment."
+              }
+              $expectedGuiExecutable = Join-Path `
+                $environment[0].FullName `
+                ("Scripts\{0}.exe" -f $contract.gui_entry_point)
+              if ($shortcut.TargetPath -ne $expectedGuiExecutable) {
                 throw "Desktop shortcut targets '$($shortcut.TargetPath)'."
               }
-              if ($shortcut.Arguments -ne $expectedArguments) {
-                throw "Desktop shortcut arguments do not target the launch adapter."
+              if (-not [string]::IsNullOrEmpty($shortcut.Arguments)) {
+                throw "Desktop shortcut unexpectedly supplies console arguments."
               }
               if ($shortcut.WorkingDirectory -ne $installRoot) {
                 throw "Desktop shortcut working directory is not the install root."
               }
+              $guiSubsystem = python -c "import struct,sys; from pathlib import Path; data=Path(sys.argv[1]).read_bytes(); pe=struct.unpack_from('<I',data,0x3c)[0]; assert data[pe:pe+4]==b'PE\0\0'; print(struct.unpack_from('<H',data,pe+24+68)[0])" `
+                $shortcut.TargetPath
+              if ($guiSubsystem.Trim() -ne "2") {
+                throw "Desktop shortcut target is not a GUI-subsystem executable."
+              }
             }
             finally {
               [Runtime.InteropServices.Marshal]::FinalReleaseComObject($shortcut) |
diff --git a/packaging/installers/installer_contract.json b/packaging/installers/installer_contract.json
index ea6d1a2df..b78084234 100644
--- a/packaging/installers/installer_contract.json
+++ b/packaging/installers/installer_contract.json
@@ -4,6 +4,7 @@
   "python_version": "3.12",
   "package_requirement": "openhcs[gui,viz,bioformats,mcp,cellprofiler-compat]",
   "entry_point": "openhcs",
+  "gui_entry_point": "openhcs-gui",
   "uv_release": {
     "version": "0.11.28",
     "base_url": "https://astral.sh/uv"
diff --git a/packaging/installers/windows/Install-OpenHCS.ps1 b/packaging/installers/windows/Install-OpenHCS.ps1
index 5d3981f0b..0e649300f 100644
--- a/packaging/installers/windows/Install-OpenHCS.ps1
+++ b/packaging/installers/windows/Install-OpenHCS.ps1
@@ -131,6 +131,7 @@ function Read-InstallerContract {
     $pythonVersion = Get-RequiredTextProperty $contract "python_version"
     $packageRequirement = Get-RequiredTextProperty $contract "package_requirement"
     $entryPoint = Get-RequiredTextProperty $contract "entry_point"
+    $guiEntryPoint = Get-RequiredTextProperty $contract "gui_entry_point"
 
     if ($schemaVersion -ne $script:SupportedContractSchema) {
         throw "Unsupported installer contract schema '$schemaVersion'."
@@ -152,6 +153,12 @@ function Read-InstallerContract {
     if ($entryPoint -notmatch "^[A-Za-z0-9][A-Za-z0-9_.-]*$") {
         throw "Installer contract entry_point has an unsafe executable-name format."
     }
+    if ($guiEntryPoint -notmatch "^[A-Za-z0-9][A-Za-z0-9_.-]*$") {
+        throw (
+            "Installer contract gui_entry_point has an unsafe " +
+            "executable-name format."
+        )
+    }
 
     $uvReleaseProperty = $contract.PSObject.Properties["uv_release"]
     if ($null -eq $uvReleaseProperty -or $null -eq $uvReleaseProperty.Value) {
@@ -192,6 +199,7 @@ function Read-InstallerContract {
         PythonVersion = $pythonVersion
         PackageRequirement = $packageRequirement
         EntryPoint = $entryPoint
+        GuiEntryPoint = $guiEntryPoint
         UvVersion = $uvVersion
         UvInstallerUrl = $uvInstallerUrl
     }
@@ -611,6 +619,16 @@ function Publish-LaunchAdapterAndShortcut {
 
     $launcherPath = Get-StableLauncherPath $Contract $ResolvedInstallRoot
     $powerShellExecutable = Get-WindowsPowerShellExecutable
+    $guiExecutable = [IO.Path]::Combine(
+        $ResolvedInstallRoot,
+        "environments",
+        $EnvironmentName,
+        "Scripts",
+        "$($Contract.GuiEntryPoint).exe"
+    )
+    if (-not (Test-Path -LiteralPath $guiExecutable -PathType Leaf)) {
+        throw "Installed GUI entry point is unavailable: $guiExecutable"
+    }
     $stableLaunchCommandJson = ConvertTo-Json -Compress -InputObject @(
         $powerShellExecutable,
         "-NoProfile",
@@ -652,11 +670,8 @@ function Publish-LaunchAdapterAndShortcut {
     try {
         $shortcut = $shell.CreateShortcut($shortcutCandidate)
         try {
-            $shortcut.TargetPath = $powerShellExecutable
-            $shortcut.Arguments = (
-                '-NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File "{0}"' -f
-                $launcherPath
-            )
+            $shortcut.TargetPath = $guiExecutable
+            $shortcut.Arguments = ""
             $shortcut.WorkingDirectory = $ResolvedInstallRoot
             $shortcut.Description = "Launch $($Contract.ProductName)"
             $shortcut.IconLocation = "$powerShellExecutable,0"
diff --git a/pyproject.toml b/pyproject.toml
index 65542bd12..8eb1cc377 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -290,7 +290,6 @@ Documentation = "https://openhcs.readthedocs.io/"
 # Main interfaces - the top-level dispatcher defaults to the GUI and exposes
 # stable named commands such as `openhcs mcp` for package registries.
 openhcs = "openhcs.cli:main"
-openhcs-gui = "openhcs.pyqt_gui.__main__:main"
 # openhcs-tui = "openhcs.textual_tui.__main__:main"  # TUI deprecated, not in PyPI
 
 # Utility scripts
@@ -301,6 +300,9 @@ openhcs-mcp-http = "openhcs.mcp.http:main"
 openhcs-mcp-dev = "openhcs.mcp.dev_client:main"
 openhcs-mcp-demo = "openhcs.mcp.installed_demo:main"
 
+[project.gui-scripts]
+openhcs-gui = "openhcs.pyqt_gui.__main__:main"
+
 [project.entry-points."napari.manifest"]
 openhcs = "openhcs:napari.yaml"
 
diff --git a/scripts/render_installer_contract.py b/scripts/render_installer_contract.py
index d127070ea..2053465cf 100644
--- a/scripts/render_installer_contract.py
+++ b/scripts/render_installer_contract.py
@@ -55,6 +55,14 @@ def validate_contract(contract: object) -> dict[str, object]:
     ):
         raise ValueError("Installer contract entry_point has an invalid format")
 
+    gui_entry_point = contract.get("gui_entry_point")
+    if not isinstance(gui_entry_point, str) or not re.fullmatch(
+        r"[A-Za-z0-9][A-Za-z0-9._-]*", gui_entry_point
+    ):
+        raise ValueError(
+            "Installer contract gui_entry_point has an invalid format"
+        )
+
     uv_release = contract.get("uv_release")
     if not isinstance(uv_release, dict) or set(uv_release) != {
         "version",
diff --git a/tests/installer/test_installer_contract.py b/tests/installer/test_installer_contract.py
index 6d4e0ee3b..782910dad 100644
--- a/tests/installer/test_installer_contract.py
+++ b/tests/installer/test_installer_contract.py
@@ -47,6 +47,11 @@ def test_installer_contract_queries_published_project_authorities() -> None:
     assert requirement.extras <= project["optional-dependencies"].keys()
     assert contract["entry_point"] == project["name"]
     assert contract["entry_point"] in project["scripts"]
+    assert contract["gui_entry_point"] in project["gui-scripts"]
+    assert (
+        project["gui-scripts"][contract["gui_entry_point"]]
+        == "openhcs.pyqt_gui.__main__:main"
+    )
     assert python_version in SpecifierSet(project["requires-python"])
     uv_release = contract["uv_release"]
     assert set(uv_release) == {"version", "base_url"}
@@ -135,6 +140,7 @@ def test_render_contract_changes_only_the_package_requirement(tmp_path: Path) ->
         ("python_version", "python3"),
         ("package_requirement", "openhcs @ https://example.invalid/pkg.whl"),
         ("entry_point", "openhcs-gui && nope"),
+        ("gui_entry_point", "openhcs-gui && nope"),
         (
             "uv_release",
             {"version": "latest", "base_url": "http://example.invalid/uv"},
diff --git a/tests/installer/test_windows_simple_installer.py b/tests/installer/test_windows_simple_installer.py
index 84f3e89f4..af6f1d13f 100644
--- a/tests/installer/test_windows_simple_installer.py
+++ b/tests/installer/test_windows_simple_installer.py
@@ -99,6 +99,7 @@ def test_windows_installer_fails_closed_on_validated_shared_contract() -> None:
     assert '"installer_contract.json"' in source
     assert "ConvertFrom-Json" in source
     assert 'Get-RequiredTextProperty $contract "entry_point"' in source
+    assert 'Get-RequiredTextProperty $contract "gui_entry_point"' in source
     assert '"openhcs.installer.v2"' in source
     assert "Expected exactly one installer_contract.json" in source
     assert "Uri]::TryCreate" in source
@@ -176,8 +177,11 @@ def test_windows_installer_delegates_runtime_to_declared_entrypoint() -> None:
 
     assert '"Scripts"' in source
     assert '"$($Contract.EntryPoint).exe"' in source
+    assert '"$($Contract.GuiEntryPoint).exe"' in source
     assert "WScript.Shell" in source
     assert "CreateShortcut" in source
+    assert "$shortcut.TargetPath = $guiExecutable" in source
+    assert '$shortcut.Arguments = ""' in source
     assert '$env:OPENHCS_CPU_ONLY = "true"' in source
     assert (
         '"environments\\{0}\\Scripts\\{1}.exe") @args' in source
@@ -494,6 +498,9 @@ def test_windows_installer_ci_has_an_absolute_safety_ceiling() -> None:
     assert '"openhcs-installer-cancel-{0}.marker"' in smoke_step
     assert '"-CancellationPath", $CancellationMarker' in smoke_step
     assert '"-RegisterMcpClients"' in smoke_step
+    assert "$contract.gui_entry_point" in smoke_step
+    assert "$shortcut.TargetPath -ne $expectedGuiExecutable" in smoke_step
+    assert "Desktop shortcut target is not a GUI-subsystem executable." in smoke_step
     assert '$env:CODEX_HOME = Join-Path $env:RUNNER_TEMP "codex-home"' in smoke_step
     assert "Windows installer did not register the stable OpenHCS MCP launcher." in (
         smoke_step