ci(lint): use CI_PYTHON_LAUNCHER from runner config as single source of truth

Configure system Python path once in runner/config.yaml (runner.envs) instead of probing N candidate locations in the workflow. Workflow now fails fast with a clear error if the env is unset or points to a missing file. Document the new env in AGENTS.md.

.gitea/workflows/lint.yml

@@ -80,11 +80,16 @@ jobs:
         run: |
           $ErrorActionPreference = 'Stop'
 
-          # Production venv lives at F:\CI\python\venv (per AGENTS.md).
-          # If missing or broken (pyvenv.cfg points to a deleted base interpreter,
-          # e.g. a stale actions/setup-python tool_cache), rebuild it via the
-          # Windows Python launcher (py -3.11). The act_runner SYSTEM service
-          # does NOT have plain "python" in PATH, but py.exe is installed system-wide.
+          # Production venv lives at $env:VENV_DIR (F:\CI\python\venv per AGENTS.md).
+          # The system Python used to bootstrap it is configured once in
+          # runner/config.yaml as CI_PYTHON_LAUNCHER (single source of truth).
+          if (-not $env:CI_PYTHON_LAUNCHER) {
+            throw "CI_PYTHON_LAUNCHER not set. Configure it in runner/config.yaml (runner.envs) and restart act_runner."
+          }
+          if (-not (Test-Path $env:CI_PYTHON_LAUNCHER)) {
+            throw "CI_PYTHON_LAUNCHER points to '$env:CI_PYTHON_LAUNCHER' which does not exist."
+          }
+
           $venvPy = Join-Path $env:VENV_DIR 'Scripts\python.exe'
 
           # Probe: a broken venv (pyvenv.cfg pointing to a deleted base interpreter)
@@ -104,48 +109,11 @@ jobs:
           }
 
           if (-not $venvOk) {
-            Write-Host "Venv missing or broken, (re)bootstrapping at $env:VENV_DIR"
+            Write-Host "Venv missing or broken, (re)bootstrapping at $env:VENV_DIR with $env:CI_PYTHON_LAUNCHER"
             if (Test-Path $env:VENV_DIR) {
               Remove-Item $env:VENV_DIR -Recurse -Force
             }
-
-            # Find a usable Python launcher. act_runner runs as SYSTEM and may
-            # not have py.exe / python.exe in PATH; try common locations.
-            # Override via $env:CI_PYTHON_LAUNCHER if installed elsewhere.
-            $candidates = @()
-            if ($env:CI_PYTHON_LAUNCHER) { $candidates += $env:CI_PYTHON_LAUNCHER }
-            $candidates += @(
-              'py.exe',
-              'python.exe',
-              'C:\Program Files\Python314\python.exe',
-              'C:\Program Files\Python313\python.exe',
-              'C:\Program Files\Python312\python.exe',
-              'C:\Program Files\Python311\python.exe',
-              'C:\Python314\python.exe',
-              'C:\Python313\python.exe',
-              'C:\Python312\python.exe',
-              'C:\Python311\python.exe',
-              "$env:LOCALAPPDATA\Programs\Python\Python314\python.exe",
-              "$env:LOCALAPPDATA\Programs\Python\Python313\python.exe",
-              "$env:LOCALAPPDATA\Programs\Python\Python312\python.exe",
-              "$env:LOCALAPPDATA\Programs\Python\Python311\python.exe"
-            )
-            $launcher = $null
-            foreach ($c in $candidates) {
-              $cmd = Get-Command $c -ErrorAction SilentlyContinue
-              if ($cmd) { $launcher = $cmd.Source; break }
-            }
-            if (-not $launcher) {
-              throw "No Python launcher found. Install Python 3.11+ system-wide or set CI_PYTHON_LAUNCHER. Tried: $($candidates -join ', ')"
-            }
-            Write-Host "Bootstrapping venv with: $launcher"
-
-            if ($launcher -like '*py.exe') {
-              & $launcher -3 -m venv $env:VENV_DIR
-            }
-            else {
-              & $launcher -m venv $env:VENV_DIR
-            }
+            & $env:CI_PYTHON_LAUNCHER -m venv $env:VENV_DIR
             if ($LASTEXITCODE -ne 0) { throw "venv creation failed" }
           }
 

AGENTS.md

@@ -191,6 +191,11 @@ NON modificare il branch WinRM esistente quando si lavora sul branch Linux e vic
   - `GITEA_CI_ARTIFACT_DIR` — `F:\CI\Artifacts`
   - `GITEA_CI_GUEST_CRED_TARGET` — `BuildVMGuest`
   - `GITEA_CI_SSH_KEY_PATH` — `F:\CI\keys\ci_linux`
+  - `CI_PYTHON_LAUNCHER` — absolute path al Python di sistema usato per
+    bootstrap del venv produzione (`F:\CI\python\venv`). act_runner gira come
+    SYSTEM con PATH sanitizzato (no `python`/`py.exe` risolvibili), quindi i
+    workflow Python leggono questo env come single source of truth. Aggiornare
+    solo quando si fa upgrade dell'interprete.
 
 ---
 

runner/config.yaml

@@ -38,6 +38,11 @@ runner:
     # Force UTF-8 stdio for the Python orchestrator (Phase A4) so non-ASCII
     # characters in build logs survive the act_runner -> Gitea round-trip.
     PYTHONIOENCODING: "utf-8"
+    # Absolute path to the system Python interpreter used to bootstrap the
+    # production venv (F:\CI\python\venv). act_runner runs as SYSTEM with a
+    # sanitized PATH where neither `python` nor `py.exe` resolve, so workflows
+    # rely on this single source of truth. Update only when upgrading Python.
+    CI_PYTHON_LAUNCHER: "C:\\Program Files\\Python314\\python.exe"
 
   # Optional: load additional env vars from a file (one KEY=VALUE per line)
   # env_file: "F:\\CI\\runner.env"