fix(release): preserve qualification and repair Linux setup

.github/workflows/ci.yml

@@ -57,11 +57,14 @@ on:
     - cron: "0 7 * * 0" # Sundays 07:00 UTC: full compatibility matrix
   workflow_dispatch:
 
-# Cancel any superseded in-flight run for the same ref (e.g. a force-push or a
-# rapid second push to a PR branch) instead of letting both run to completion.
+# Cancel a superseded ordinary run for the same ref (e.g. a force-push or a
+# rapid second push to a PR branch). Release qualification dispatches use the
+# exact candidate SHA as a separate group and are never canceled. A later push
+# to main therefore cannot invalidate a matrix that the release gate is already
+# waiting to inspect.
 concurrency:
-  group: ci-${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+  group: ci-${{ github.workflow }}-${{ github.event_name == 'workflow_dispatch' && github.sha || github.ref }}
+  cancel-in-progress: ${{ github.event_name != 'workflow_dispatch' }}
 
 # GitHub Actions are pinned to full commit SHAs (not mutable tags) as a
 # supply-chain control; the trailing comment records the human-readable

.github/workflows/quickstart-lifecycle.yml

@@ -8,8 +8,11 @@ on:
   workflow_dispatch:
 
 concurrency:
-  group: quickstart-lifecycle-${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+  # Keep an exact-SHA release qualification isolated from scheduled and push
+  # activity on main. The release gate must be able to inspect the dispatched
+  # three-OS result even if main advances while that matrix is still running.
+  group: quickstart-lifecycle-${{ github.workflow }}-${{ github.event_name == 'workflow_dispatch' && github.sha || github.ref }}
+  cancel-in-progress: ${{ github.event_name != 'workflow_dispatch' }}
 
 permissions:
   contents: read
@@ -41,9 +44,8 @@ jobs:
           python -m pip install build
           python -m build --wheel --outdir lifecycle-dist
 
-      # The Linux lane passes --browser-with-deps, so the harness shells out to
-      # `playwright install --with-deps`, and that runs apt on the hosted
-      # runner. Point apt at the canonical archive first, and prove the archive
+      # The Linux lane installs only Chromium's host libraries before the
+      # tutorial. Point apt at the canonical archive first, and prove the archive
       # answers inside a bounded step, so a mirror fault fails here in seconds
       # instead of stalling inside the lifecycle harness.
       - name: Prefer the canonical Ubuntu archive (Linux)
@@ -81,7 +83,7 @@ jobs:
           --wheel "lifecycle-dist/*.whl"
           --work-dir "runs/lifecycle"
           --install-browser
-          --browser-with-deps
+          --browser-system-deps
           --source-revision "${{ github.sha }}"
 
       - name: Full lifecycle (macOS / Windows)

README.md

@@ -479,10 +479,15 @@ episode instead. This package keeps the worker and the HTTP client. See
 ```bash
 git clone https://github.com/OpenAdaptAI/openadapt-flow && cd openadapt-flow
 pip install -e '.[dev]'
-playwright install chromium   # optional; otherwise downloaded on first launch
+python -m playwright install chromium  # optional browser pre-provisioning
 pytest -q
 ```
 
+On Linux, Flow checks the Chromium host libraries before an automatic browser
+download. A minimal host may need a one-time system-library install. Flow stops
+before the download and prints a command for the exact Python environment that
+runs it.
+
 Contributions welcome, see [CONTRIBUTING.md](CONTRIBUTING.md). If you want a
 first one that is genuinely useful: pick a module off the mypy type-debt
 burn-down list (`[[tool.mypy.overrides]]` in `pyproject.toml`), tighten its

docs/TUTORIAL.md

@@ -92,11 +92,14 @@ one-command rollback). See [`REPAIR_LIFECYCLE.md`](REPAIR_LIFECYCLE.md).
 
 The base `openadapt-flow` package stays lightweight for native desktop, RDP,
 and Citrix runners. The `browser` extra adds Playwright only for web workflows;
-the first browser command then downloads its matching Chromium build once
-(about 150 MB), with no separate `playwright install chromium` step. Prefer the
-canonical `pip install 'openadapt[browser]'` launcher path for normal use. In
-air-gapped or CI environments that pre-provision the browser, set
-`OPENADAPT_FLOW_NO_AUTO_INSTALL=1` to disable the auto-download.
+the first browser command checks its Linux host libraries and then downloads
+the matching Chromium build once (about 150 MB). A minimal Linux host may need
+Playwright's one-time system-library install. Flow stops before the browser
+download and prints a command bound to the exact Python environment that runs
+it. Playwright requests administrator access if the system package manager
+needs it. Prefer the canonical `pip install 'openadapt[browser]'` launcher path
+for normal use. In air-gapped or CI environments that pre-provision the
+browser, set `OPENADAPT_FLOW_NO_AUTO_INSTALL=1` to disable the auto-download.
 
 The weekly clean-machine test runs this complete install-to-uninstall journey
 on Linux, macOS, and Windows. See the

openadapt_flow/_browser_setup.py

@@ -32,6 +32,7 @@
 import importlib.util
 import os
 import re
+import shlex
 import subprocess
 import sys
 import threading
@@ -112,6 +113,11 @@ def _opted_out() -> bool:
 )
 
 
+def _playwright_module_command(*args: str) -> str:
+    """Return a copyable Playwright command for this exact Python environment."""
+    return shlex.join([sys.executable, "-m", "playwright", *args])
+
+
 def _missing_chromium_system_libs() -> list[str]:
     """Return the Chromium shared libraries missing on this Linux machine.
 
@@ -139,11 +145,14 @@ def _require_linux_system_libs() -> None:
     if not missing:
         return
     libs = ", ".join(missing)
+    install_deps = _playwright_module_command("install-deps", "chromium")
     raise RuntimeError(
         "Chromium cannot launch on this machine yet: required system "
         f"libraries are missing ({libs}).\n\n"
-        "Install them once with:\n\n"
-        "    sudo python -m playwright install-deps chromium\n\n"
+        "Install them once with the same Python environment that runs "
+        "OpenAdapt. Playwright requests administrator access if the system "
+        "package manager needs it:\n\n"
+        f"    {install_deps}\n\n"
         "or, on Debian/Ubuntu:\n\n"
         f"    sudo apt-get install -y {_LINUX_APT_PACKAGES}\n\n"
         "Then run your command again. Nothing was downloaded."

public-artifacts.json

@@ -93,7 +93,7 @@
     },
     {
       "path": ".github/workflows/ci.yml",
-      "sha256": "f2b9a6cb8fced9af463bf3cd50cedaeafcb928baaeb4fc0bc757a3864298a20f"
+      "sha256": "d1a12b5a5c1a067300893a2f7805988507b435b67bb802140bd43d6a96de8f91"
     },
     {
       "path": ".github/workflows/citrix-workspace-standin.yml",
@@ -113,7 +113,7 @@
     },
     {
       "path": ".github/workflows/quickstart-lifecycle.yml",
-      "sha256": "8eae9755b0ba287c708dd078b996f4b139e949ae375cfc5bb7a6e0f441b38ece"
+      "sha256": "da8017d063f13283f7c257caa4071d07c14e3b99d04a6ae8b246d751766e5f94"
     },
     {
       "path": ".github/workflows/release-health.yml",
@@ -5801,7 +5801,7 @@
     },
     {
       "path": "source-policy.public.json",
-      "sha256": "b03b1f9bb0d3b4631c84db1c7e1dd7f26f1cd04e9b4d4d18f6cab2776eed7eb6"
+      "sha256": "7b16bdc1800a0585c8f966dbce5be6d6d9b2abce4327b1a32d631c2de3c8ef29"
     },
     {
       "path": "tests/fixtures/flow_v1_34_0_terminal_verified.json",