diff --git a/docs/implementation-plan.v1.md b/docs/implementation-plan.v1.md
index 558c7d9..ca2720d 100644
--- a/docs/implementation-plan.v1.md
+++ b/docs/implementation-plan.v1.md
@@ -842,7 +842,7 @@ mirror; update both documents when the fixture is reprovisioned.
| Host access | SSH alias `helium-remote` (`192.168.50.162`), host user `cabbage`; lifecycle commands execute on this host |
| VM name / UUID | `rvbox-win10-test` / `6cdc114f-71e5-4167-a394-e922e14e6f5c` |
| VM group / config | `/RVBox/Tests`; `/home/cabbage/VirtualBox VMs/RVBox/Tests/rvbox-win10-test/rvbox-win10-test.vbox` |
-| Guest OS | Windows 10 Pro 22H2, build `19045.2006`, en-US, BIOS boot |
+| Guest OS | Windows 10 Pro 22H2, build `19045.6456` verified after the baseline's pending Windows servicing restart; en-US, BIOS boot (original install build `19045.2006`) |
| Guest Additions | `7.2.16r174877`; readiness requires published Guest Additions version and Windows OS-release properties (this build does not publish a RunLevel property) |
| Resources | 2 vCPU, 4096 MiB RAM, 64 MiB VRAM, `VBoxSVGA`, 3D acceleration disabled, 40 GiB dynamically allocated VDI |
| Disk / source media | `/home/cabbage/VMs/rvbox-win10-test.vdi`; source ISO `/media/Data2/Downloaded/Win10_22H2_English_x64.iso` (Windows image index 6) |
@@ -851,8 +851,19 @@ mirror; update both documents when the fixture is reprovisioned.
| Diagnostic VRDE | Enabled only on Helium loopback at `127.0.0.1:3389`, external/`VBoxAuthSimple` authentication, input/display enabled, audio/USB/clipboard/RDPDR disabled; reach it only through an explicitly temporary, private SSH forward, and treat it as diagnostic-only because client compatibility is unreliable |
| Native Windows RDP | Disabled in baseline (`TermService` stopped, `fDenyTSConnections=1`); port 3390 must not be treated as a usable control endpoint |
| Test account | Local `rvboxtest`; split-token local administrator; console session 1 observed; Guest Control verified with `whoami`, `whoami /groups`, and `query user` |
-| Baseline | Reset target `baseline-clean-administrator` (UUID `ba5ce5f1-77e3-44b0-8d91-534becce27ff`): no RVBox service, tray registration, state, logs, or staged binary; built-in `Administrator` is enabled only for the fixture's high-token Guest Control installation path. Retain `baseline-clean` (UUID `5e79176a-3e56-4c5d-bb61-a405a6dcdd59`) and child `baseline-disk-first` (UUID `9430a9a4-754a-4b22-beaa-8dfd90043f5b`) as pristine diagnostics. |
-| Last checked state | `poweroff`, current snapshot `baseline-clean-administrator`; restore that reset target before native runs, and leave it selected after cleanup |
+| Baseline | Reset target `baseline-clean-python-ready` (UUID `dfadee95-156f-43ee-bdab-a10a44be4070`): no RVBox service, tray registration, state, logs, or staged binary; built-in `Administrator` is enabled only for the fixture's high-token Guest Control installation path; all-users Python 3.13.16 amd64, pip, venv and launcher installed at `C:\Python313` on machine PATH; pending Windows servicing restart completed before final capture. Retain the initial Python snapshot `baseline-clean-python` (UUID `2d00a8a2-a7cf-4f7b-bee2-80bd71574e89`), pre-Python parent `baseline-clean-administrator` (UUID `ba5ce5f1-77e3-44b0-8d91-534becce27ff`), `baseline-clean` (UUID `5e79176a-3e56-4c5d-bb61-a405a6dcdd59`) and `baseline-disk-first` (UUID `9430a9a4-754a-4b22-beaa-8dfd90043f5b`) as diagnostics. |
+| Last checked state | Clean powered-off snapshot captured 2026-10-08, then restored/boot-verified and left running for interactive access; current snapshot `baseline-clean-python-ready`; restore that reset target before native runs, and leave it selected/powered off after normal test cleanup |
+
+Python is a baseline fixture dependency, not a production RVBox dependency or
+per-run bootstrap. The repeatable `test-host provision-python` and
+`capture-python-baseline --snapshot-name NAME` flow is documented in
+[testing-vm.md](testing-vm.md#python-enabled-baseline): pinned official installer,
+SHA-256 plus Authenticode checks, offline Guest Control staging, all-users
+interpreter/PATH/pip/venv/launcher, ordinary-user verification, RVBox-cleanliness
+checks (including no Windows servicing reboot pending), graceful powered-off capture, retained parents, and fresh restore/boot
+verification. Direct Helium download is the default; the metered SOCKS route
+requires an explicit `RVBOX_TEST_PYTHON_DOWNLOAD_PROXY`. A new capture's UUID
+must replace the controller defaults and document mirrors before another run.
The isolated disposable fixture deliberately uses one fixed test-only password
for both local test accounts, `rvboxtest` and `Administrator`. Its value is
@@ -934,8 +945,8 @@ identity in the run manifest:
```sh
export RVBOX_TEST_VBOX_HOST=helium-remote
export RVBOX_TEST_VBOX_VM=rvbox-win10-test
-export RVBOX_TEST_VBOX_SNAPSHOT=baseline-clean-administrator
-export RVBOX_TEST_VBOX_SNAPSHOT_UUID=ba5ce5f1-77e3-44b0-8d91-534becce27ff
+export RVBOX_TEST_VBOX_SNAPSHOT=baseline-clean-python-ready
+export RVBOX_TEST_VBOX_SNAPSHOT_UUID=dfadee95-156f-43ee-bdab-a10a44be4070
export RVBOX_TEST_GUEST_USER=rvboxtest
export RVBOX_TEST_GUEST_PASSWORD_FILE=/secure/outside-repo/rvbox-win10-test.password
```
@@ -954,7 +965,7 @@ ssh "$RVBOX_TEST_VBOX_HOST" \
# Restore only while powered off, then boot without a GUI.
ssh "$RVBOX_TEST_VBOX_HOST" \
- 'VBoxManage snapshot "rvbox-win10-test" restore "baseline-clean-administrator"'
+ 'VBoxManage snapshot "rvbox-win10-test" restore "baseline-clean-python-ready"'
ssh "$RVBOX_TEST_VBOX_HOST" \
'VBoxManage startvm "rvbox-win10-test" --type headless'
@@ -1002,7 +1013,7 @@ Use this shutdown/reset sequence for every native run:
acpipowerbutton` and poll. Use `controlvm ... poweroff` only for a hung,
disposable test; it intentionally loses guest state.
3. Collect diagnostics while the VM is still available, then restore
- `baseline-clean-administrator` and verify the snapshot UUID/current marker.
+ `baseline-clean-python-ready` and verify the snapshot UUID/current marker.
4. Leave the VM powered off after cleanup. Never delete any baseline
snapshot, unregister the VM, or modify `win10_dev` (that name refers to a
stale unregistered configuration with a missing disk on this host).
diff --git a/docs/testing-vm.md b/docs/testing-vm.md
index eed7005..4cc8fdc 100644
--- a/docs/testing-vm.md
+++ b/docs/testing-vm.md
@@ -5,8 +5,9 @@ It describes the machine that is available today; it is not the complete
Windows release matrix. Keep the values here in sync with the VM before adding
or changing native test automation.
-Last configuration check: 2026-09-09 UTC. The VM was observed powered off with
-`baseline-clean-administrator` selected. The native harness targets that snapshot;
+Last configuration check: 2026-10-08 UTC. A powered-off clean
+`baseline-clean-python-ready` snapshot was captured, restored, and boot-verified.
+The native harness targets that snapshot;
the fixture is ready for native runs. A test run must still perform its own identity,
snapshot, readiness, and exclusive-lease checks rather than relying on that
observation.
@@ -23,10 +24,11 @@ observation.
| VM configuration | `/home/cabbage/VirtualBox VMs/RVBox/Tests/rvbox-win10-test/rvbox-win10-test.vbox` |
| VM logs | `/home/cabbage/VirtualBox VMs/RVBox/Tests/rvbox-win10-test/Logs` |
| Snapshot folder | `/home/cabbage/VirtualBox VMs/RVBox/Tests/rvbox-win10-test/Snapshots` |
-| Guest OS | Windows 10 Pro 22H2, build `19045.2006`, en-US, BIOS boot |
+| Guest OS | Windows 10 Pro 22H2, build `19045.6456` verified after the baseline's pending Windows servicing restart; en-US, BIOS boot (original install build `19045.2006`) |
| Guest account | Local `rvboxtest`; split-token local administrator; console session 1 was observed during provisioning |
| Guest Additions | `7.2.16r174877`; readiness requires published Guest Additions version and Windows OS-release properties (this build does not publish a RunLevel property) |
-| Last observed state | `poweroff`; current snapshot `baseline-clean-administrator`, the reset target for native runs |
+| Last observed state | `running` for interactive access; current snapshot `baseline-clean-python-ready`, the reset target for native runs; verify live state and lease before mutations |
+| Baseline Python | Python `3.13.16` amd64 at `C:\Python313`; machine PATH, `py` launcher, bundled pip and venv; no third-party packages |
The two fixture accounts deliberately share one fixed test-only password for
reproducible native runs. The value is provisioned only in the Helium host's
@@ -101,24 +103,30 @@ copy/paste example and explains the native-host lease boundary.
## Snapshots and reset contract
-Three clean snapshots exist and must be retained. `baseline-clean-administrator`
+Five snapshots are retained. `baseline-clean-python-ready`
is the only reset target: it contains no `RVBoxClient` SCM service, RVBox tray
Run-key registration, RVBox state, logs, or staged binaries; it also has the
fixture-only built-in `Administrator` account enabled for high-token Guest
-Control installation.
+Control installation, plus Python, pip, and venv for repeatable interactive tests.
+It is a powered-off descendant of `baseline-clean-administrator`, captured after
+the first Python snapshot's pending Windows servicing restart completed; the
+original parent and both older diagnostic snapshots remain unchanged.
| Snapshot | UUID | Description |
| --- | --- | --- |
| `baseline-clean` | `5e79176a-3e56-4c5d-bb61-a405a6dcdd59` | `baseline-windows10-pro-22h2-rvboxtest-guest-additions` |
| `baseline-disk-first` | `9430a9a4-754a-4b22-beaa-8dfd90043f5b` | `baseline-windows10-pro-22h2-disk-first`; retained diagnostic snapshot |
-| `baseline-clean-administrator` | `ba5ce5f1-77e3-44b0-8d91-534becce27ff` | `baseline-windows10-pro-22h2-administrator-enabled-full-token`; current reset target |
+| `baseline-clean-administrator` | `ba5ce5f1-77e3-44b0-8d91-534becce27ff` | `baseline-windows10-pro-22h2-administrator-enabled-full-token`; retained pre-Python parent |
+| `baseline-clean-python` | `2d00a8a2-a7cf-4f7b-bee2-80bd71574e89` | Retained initial Python capture, before its first-restore Windows servicing restart completed; diagnostic only |
+| `baseline-clean-python-ready` | `dfadee95-156f-43ee-bdab-a10a44be4070` | Clean RVBox fixture; full-token Administrator; Python 3.13.16 amd64, pip and venv; no RVBox installation or pending Windows servicing reboot; current reset target |
Restore only while the VM is powered off. Every destructive or potentially
stateful run must:
1. Acquire the run lease and verify the VM name, UUID, and snapshot UUID.
-2. Restore `baseline-clean-administrator` if the current state is not the baseline.
-3. Start headless and wait for `VMState=running` plus Guest Additions readiness.
+2. Restore `baseline-clean-python-ready` if the current state is not the baseline.
+3. Start headless and wait for `VMState=running` plus Guest Additions readiness
+ (bounded 240-second window for cold boots/servicing restarts).
4. Apply the disposable display/sleep keepalive (`monitor-timeout`, standby,
and hibernate timers set to zero) so VirtualBox VRDE cannot expose a
zero-bpp framebuffer after Windows idle timeout. This is recorded as
@@ -126,7 +134,7 @@ stateful run must:
5. Run the bounded test, collect redacted artifacts, and close every Guest
Control process that was opened by the run.
6. Request a graceful guest shutdown and wait for `VMState=poweroff`.
-7. Restore `baseline-clean-administrator` again and leave the VM powered off.
+7. Restore `baseline-clean-python-ready` again and leave the VM powered off.
Use `controlvm ... poweroff` only for a hung, disposable test; it can lose
guest state. Never delete any clean snapshot, unregister the VM, or alter
@@ -134,11 +142,93 @@ the stale unregistered `win10_dev` configuration (its disk is missing).
## Harness contract
+### Python-enabled baseline
+
+Python is part of `baseline-clean-python-ready`, not a per-run installation. Every
+normal `test-host prepare`/`reset` restores it together with the clean Windows
+fixture. No Python installer, bootstrap script, verification venv, or RVBox
+installation is retained in that snapshot. Both accounts can run `python`,
+`py -3.13`, and `python -m pip`; create project venvs under the ordinary user's
+profile rather than installing packages into the all-users interpreter.
+
+The pinned [Python 3.13.16 Windows amd64 release](https://www.python.org/downloads/release/python-31316/)
+installer has SHA-256
+`fb4f9f5d438b2396da0086dc70b935c530cb578e37adc6d354f7ad2037fee83b`.
+[`provision-python.ps1`](../scripts/windows/provision-python.ps1) verifies that
+digest and its Python Software Foundation Authenticode signature before using
+the [official unattended installer options](https://docs.python.org/3.13/using/windows.html#installing-without-ui).
+It installs the interpreter, standard library, pip, launcher, and machine PATH;
+documentation, regression-test data, Tcl/Tk/IDLE, shortcuts, debug binaries,
+and symbols are omitted. No third-party packages are preinstalled.
+
+To recreate or validate a replacement baseline from the currently declared
+clean fixture (use a new, unique snapshot name; existing snapshots are never
+overwritten):
+
+```sh
+# Check state/lease first; prepare only when no other run owns the fixture.
+scripts/windows/test-host status
+scripts/windows/test-host prepare --run-id python-baseline
+scripts/windows/test-host provision-python --run-id python-baseline
+# Close any interactive desktop connection before shutdown/capture.
+test/rdp-access/rdp-access down
+scripts/windows/test-host capture-python-baseline \
+ --run-id python-baseline --snapshot-name baseline-clean-python-next
+```
+
+The controller downloads the 28.5 MiB installer over HTTPS **on Helium**,
+validates SHA-256, and uses Guest Control to copy it into the VM. It does not
+depend on the guest's network route. Completed installers are cached and
+partial `.exe.new` files are retained under the owning host-stage run directory
+for resumable retries. Direct download is the default. If that route stalls,
+explicitly opt into the established, metered host proxy for this one-time
+download:
+
+```sh
+RVBOX_TEST_PYTHON_DOWNLOAD_PROXY=socks5h://127.0.0.1:1085 \
+ scripts/windows/test-host provision-python --run-id python-baseline
+```
+
+Provisioning verifies the pinned version, SSL/SQLite imports, pip, machine PATH,
+and successful venv creation with bundled pip under both Administrator and
+`rvboxtest`. Capture additionally refuses an installed RVBox service, normal
+installation/state directories, or tray Run-key registration; requires no
+logged-on provisioning Administrator and no Windows servicing reboot pending;
+deletes only `C:\ProgramData\RVBoxFixture`
+bootstrap data; requests graceful shutdown; and takes a **powered-off** snapshot.
+It prints the new snapshot name and UUID and releases the lease. It never
+forces shutdown just to obtain a baseline and never blindly retries capture.
+
+After successful capture, update the snapshot name/UUID defaults in `test-host`
+and their mirrors in this document and `implementation-plan.v1.md` before
+running `prepare` again. That fresh restore/boot must recheck `python --version`,
+`py -3.13 --version`, pip and a disposable user-owned venv, plus absence of RVBox.
+If an installation/capture SSH call is interrupted, inspect the actual guest
+process and VM/snapshot state before retrying; do not assume that its mutation
+did not occur. Capture preserves every existing baseline. Ordinary test cleanup
+must not delete snapshots or any shared host cache.
+
+For lowest-bandwidth interactive access after `prepare`, use:
+
+```sh
+test/rdp-access/rdp-access up --bind 0.0.0.0 \
+ --public-host x1.xcel.me --graphics minimal
+```
+
+That requests 800×600/8-bit graphics and saves the selection per gateway
+profile. Disconnect/reconnect to apply a profile change; it does not modify
+the Windows baseline. See the [gateway quality settings](../test/rdp-access/README.md#network-and-graphics-quality)
+for all levels and server-negotiation caveats.
+
+### Native controller
+
The canonical adapter is the POSIX controller script
[`scripts/windows/test-host`](../scripts/windows/test-host). It runs from the
Linux controller and invokes `VBoxManage` only through SSH on Helium; the
-fixture host is Arch Linux and does not provide PowerShell. Its actions are
-`status`, `prepare`, `stage`, `install`, `run`, `collect`, `stop`, `reset`, and `recover`.
+fixture host is Arch Linux and does not provide PowerShell. Its native-test
+actions are `status`, `prepare`, `stage`, `install`, `run`, `logoff`, `collect`,
+`inspect`, `logs`, `stop`, `reset`, and `recover`. Baseline maintenance uses
+`provision-python` and `capture-python-baseline` as described above.
The legacy [`test-host.ps1`](../scripts/windows/test-host.ps1) is retained only
as a reference for a future Windows-hosted fixture and is not the Helium lane.
@@ -148,8 +238,8 @@ The adapter takes identity and credentials only from its environment:
export RVBOX_TEST_VBOX_HOST=helium-remote
export RVBOX_TEST_VBOX_VM=rvbox-win10-test
export RVBOX_TEST_VBOX_VM_UUID=6cdc114f-71e5-4167-a394-e922e14e6f5c
-export RVBOX_TEST_VBOX_SNAPSHOT=baseline-clean-administrator
-export RVBOX_TEST_VBOX_SNAPSHOT_UUID=ba5ce5f1-77e3-44b0-8d91-534becce27ff
+export RVBOX_TEST_VBOX_SNAPSHOT=baseline-clean-python-ready
+export RVBOX_TEST_VBOX_SNAPSHOT_UUID=dfadee95-156f-43ee-bdab-a10a44be4070
export RVBOX_TEST_GUEST_USER=rvboxtest
export RVBOX_TEST_GUEST_PASSWORD_FILE=/home/cabbage/.local/share/rvbox-secrets/rvbox-win10-test.password
# Defaults to Administrator and the same password file; overrides are optional.
diff --git a/docs/testing.md b/docs/testing.md
index 5024f3a..6a7b796 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -197,8 +197,9 @@ test reference against source. A resettable Windows smoke VM is now available.
The authoritative fixture record is
[testing-vm.md](testing-vm.md): it lists the VM/host UUIDs, Windows build,
hardware and device profile, NAT and VRDE endpoints, snapshot UUIDs,
-credential-file contract, and the required reset sequence. At the last check
-the VM was powered off with `baseline-clean-administrator` selected. The guest address
+credential-file contract, and the required reset sequence. The reset target is
+`baseline-clean-python-ready`, which includes all-users Python 3.13.16, pip and venv
+but no installed RVBox client. The guest address
`10.0.2.15` is DHCP state only; use SSH plus VirtualBox Guest Control rather
than treating it as a stable endpoint. VRDE is enabled only on Helium loopback
at `127.0.0.1:3389` for diagnostics, while native Windows RDP is disabled in
diff --git a/scripts/windows/provision-python.ps1 b/scripts/windows/provision-python.ps1
new file mode 100644
index 0000000..b35ff71
--- /dev/null
+++ b/scripts/windows/provision-python.ps1
@@ -0,0 +1,75 @@
+# Fixture-only Python bootstrap. No dependencies are installed on the Linux host.
+param([ValidateSet('Install', 'Verify', 'VerifyClean')][string] $Mode = 'Install')
+$ErrorActionPreference = 'Stop'
+$Version = '3.13.16'
+$Digest = 'fb4f9f5d438b2396da0086dc70b935c530cb578e37adc6d354f7ad2037fee83b'
+$Python = 'C:\Python313\python.exe'
+$Stage = 'C:\ProgramData\RVBoxFixture\python'
+
+if ($Mode -eq 'VerifyClean') {
+ foreach ($rebootKey in @('HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Component Based Servicing\RebootPending', 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\WindowsUpdate\Auto Update\RebootRequired')) {
+ if (Test-Path -LiteralPath $rebootKey) { throw 'Windows servicing still requires a reboot; finish it before capturing the baseline.' }
+ }
+ if (Get-Service -Name RVBoxClient -ErrorAction SilentlyContinue) { throw 'RVBox is installed; refuse to capture a dirty baseline.' }
+ foreach ($path in @('C:\ProgramData\RVBox', 'C:\Program Files\RVBox', 'C:\Program Files (x86)\RVBox')) {
+ if (Test-Path -LiteralPath $path) { throw "RVBox artifacts remain at $path; restore a clean baseline first." }
+ }
+ foreach ($runKey in @('HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Run', 'HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Run')) {
+ if (Get-ItemProperty -LiteralPath $runKey -Name RVBoxTray -ErrorAction SilentlyContinue) {
+ throw 'RVBox tray registration remains; restore a clean baseline first.'
+ }
+ }
+}
+
+function Invoke-Python([string[]] $Arguments) {
+ & $Python @Arguments
+ if ($LASTEXITCODE -ne 0) { throw "Python verification failed ($LASTEXITCODE)" }
+}
+
+if ($Mode -eq 'Install' -and -not (Test-Path -LiteralPath $Python)) {
+ $principal = New-Object Security.Principal.WindowsPrincipal([Security.Principal.WindowsIdentity]::GetCurrent())
+ if (-not $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
+ throw 'The fixture Python installer requires the high-token provisioning account.'
+ }
+ New-Item -ItemType Directory -Force -Path $Stage | Out-Null
+ $installer = Join-Path $Stage "python-$Version-amd64.exe"
+ # test-host downloads on Helium and copies the pinned offline installer.
+ # Never depend on the guest's HTTPS/proxy/certificate configuration.
+ if (-not (Test-Path -LiteralPath $installer)) { throw 'Staged offline Python installer is missing; rerun test-host provision-python.' }
+ if ((Get-FileHash -LiteralPath $installer -Algorithm SHA256).Hash.ToLowerInvariant() -ne $Digest) {
+ throw 'Python installer SHA-256 does not match the pinned python.org release.'
+ }
+ $signature = Get-AuthenticodeSignature -FilePath $installer
+ if ($signature.Status -ne 'Valid' -or $signature.SignerCertificate.Subject -notlike '*Python Software Foundation*') {
+ throw "Python installer Authenticode verification failed: $($signature.Status)"
+ }
+ $arguments = @('/quiet', '/norestart', '/log', (Join-Path $Stage 'install.log'),
+ 'InstallAllUsers=1', 'TargetDir=C:\Python313', 'PrependPath=1',
+ 'Include_pip=1', 'Include_launcher=1', 'InstallLauncherAllUsers=1',
+ 'Include_test=0', 'Include_doc=0', 'Include_tcltk=0', 'Shortcuts=0',
+ 'Include_debug=0', 'Include_symbols=0')
+ $process = Start-Process -FilePath $installer -ArgumentList $arguments -PassThru
+ if (-not $process.WaitForExit(600000)) { throw 'Python installer exceeded its ten-minute deadline; inspect fixture logs before retrying.' }
+ if ($process.ExitCode -notin @(0, 3010)) { throw "Python installer failed ($($process.ExitCode)); see $Stage\install.log" }
+}
+
+if (-not (Test-Path -LiteralPath $Python)) { throw 'Pinned Python interpreter is missing.' }
+Invoke-Python -Arguments @('-c', "import sys,ssl,sqlite3,json,venv; assert sys.version.split()[0] == '$Version'; print('python_version=' + sys.version.split()[0]); print('python_executable=' + sys.executable)")
+Invoke-Python -Arguments @('-m', 'pip', '--version')
+$machinePath = [Environment]::GetEnvironmentVariable('Path', 'Machine')
+$machinePathEntries = @($machinePath -split ';' | ForEach-Object { $_.Trim().TrimEnd('\') })
+if ($machinePathEntries -notcontains 'C:\Python313' -or $machinePathEntries -notcontains 'C:\Python313\Scripts') {
+ throw 'Python and Scripts directories are missing from machine PATH.'
+}
+
+# Prove venv and its bundled pip under the invoking identity. Remove the exact
+# newly-created test directory even if verification fails; retain install logs.
+$venvPath = Join-Path ([Environment]::GetFolderPath('LocalApplicationData')) ('RVBoxFixture-python-verify-' + [Guid]::NewGuid().ToString('N'))
+try {
+ Invoke-Python -Arguments @('-m', 'venv', $venvPath)
+ & (Join-Path $venvPath 'Scripts\python.exe') -m pip --version
+ if ($LASTEXITCODE -ne 0) { throw 'venv pip verification failed.' }
+} finally {
+ if (Test-Path -LiteralPath $venvPath) { Remove-Item -LiteralPath $venvPath -Recurse -Force }
+}
+Write-Output 'RVBOX_GUEST_OK'
diff --git a/scripts/windows/test-host b/scripts/windows/test-host
index 97bba33..0c4f725 100755
--- a/scripts/windows/test-host
+++ b/scripts/windows/test-host
@@ -12,7 +12,7 @@ repo_root=$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)
usage() {
cat <<'EOF'
-usage: scripts/windows/test-host ACTION [--run-id ID] [--bundle DIRECTORY] [--endpoint HOST:PORT] [--fail-contexts LIST]
+usage: scripts/windows/test-host ACTION [--run-id ID] [--bundle DIRECTORY] [--endpoint HOST:PORT] [--fail-contexts LIST] [--snapshot-name NAME]
Actions:
status read-only VM/snapshot identity and state check
@@ -27,6 +27,9 @@ Actions:
stop stop RVBox through SCM and request a graceful guest shutdown
reset stop the guest if necessary, restore the declared baseline, and leave it off
recover read-only fixture/run-state check for a stopped-resumable run
+ provision-python install/verify pinned Python, pip, and venv in the clean leased VM
+ capture-python-baseline verify the clean Python fixture, shut it down, take a
+ new snapshot (--snapshot-name NAME), and release the run lease
Optional environment:
The documented Helium fixture identity and password-file path are defaults.
@@ -37,6 +40,7 @@ Optional environment:
(default Administrator and the documented fixture password file)
RVBOX_TEST_HOST_STAGE_ROOT (default /home/cabbage/.local/state/rvbox-test-runs)
RVBOX_TEST_RUN_ROOT (default .test-runs/windows-vm)
+ RVBOX_TEST_PYTHON_DOWNLOAD_PROXY (default empty/direct; optional host SOCKS5)
RVBOX_TEST_ACCEL_HTTP_URL, RVBOX_TEST_ACCEL_HTTP_AUTH,
RVBOX_TEST_ACCEL_HTTP_PUBLISH_DIR, RVBOX_TEST_ACCEL_SOCKS5
(documented accelerated HTTP stage route; empty URL disables it)
@@ -77,18 +81,26 @@ run_id=
bundle=
endpoint=
fail_contexts=
+snapshot_name=
while [ "$#" -gt 0 ]; do
case $1 in
--run-id) [ "$#" -ge 2 ] || fail "--run-id needs a value"; run_id=$2; shift 2 ;;
--bundle) [ "$#" -ge 2 ] || fail "--bundle needs a value"; bundle=$2; shift 2 ;;
--endpoint) [ "$#" -ge 2 ] || fail "--endpoint needs a value"; endpoint=$2; shift 2 ;;
--fail-contexts) [ "$#" -ge 2 ] || fail "--fail-contexts needs a value"; fail_contexts=$2; shift 2 ;;
+ --snapshot-name) [ "$#" -ge 2 ] || fail "--snapshot-name needs a value"; snapshot_name=$2; shift 2 ;;
--help|-h) usage; exit 0 ;;
*) fail "unknown argument $1" ;;
esac
done
-case $action in status|prepare|stage|install|run|logoff|collect|inspect|logs|stop|reset|recover) ;; *) usage >&2; fail "unknown action $action" ;; esac
+case $action in status|prepare|stage|install|run|logoff|collect|inspect|logs|stop|reset|recover|provision-python|capture-python-baseline) ;; *) usage >&2; fail "unknown action $action" ;; esac
+if [ "$action" = capture-python-baseline ]; then
+ [ -n "$snapshot_name" ] || fail "capture-python-baseline requires --snapshot-name"
+ safe_id "$snapshot_name"
+else
+ [ -z "$snapshot_name" ] || fail "--snapshot-name is valid only with capture-python-baseline"
+fi
if [ "$action" != status ]; then
[ -n "$run_id" ] || fail "$action requires --run-id"
safe_id "$run_id"
@@ -109,12 +121,17 @@ if [ -n "$fail_contexts" ]; then safe_word fail_contexts "$fail_contexts"; fi
: "${RVBOX_TEST_VBOX_HOST:=helium-remote}"
: "${RVBOX_TEST_VBOX_VM:=rvbox-win10-test}"
: "${RVBOX_TEST_VBOX_VM_UUID:=6cdc114f-71e5-4167-a394-e922e14e6f5c}"
-: "${RVBOX_TEST_VBOX_SNAPSHOT:=baseline-clean-administrator}"
-: "${RVBOX_TEST_VBOX_SNAPSHOT_UUID:=ba5ce5f1-77e3-44b0-8d91-534becce27ff}"
+: "${RVBOX_TEST_VBOX_SNAPSHOT:=baseline-clean-python-ready}"
+: "${RVBOX_TEST_VBOX_SNAPSHOT_UUID:=dfadee95-156f-43ee-bdab-a10a44be4070}"
: "${RVBOX_TEST_GUEST_USER:=rvboxtest}"
: "${RVBOX_TEST_GUEST_PASSWORD_FILE:=/home/cabbage/.local/share/rvbox-secrets/rvbox-win10-test.password}"
: "${RVBOX_TEST_PROVISIONER_USER:=Administrator}"
: "${RVBOX_TEST_PROVISIONER_PASSWORD_FILE:=$RVBOX_TEST_GUEST_PASSWORD_FILE}"
+: "${RVBOX_TEST_PYTHON_DOWNLOAD_PROXY:=}"
+if [ -n "$RVBOX_TEST_PYTHON_DOWNLOAD_PROXY" ]; then
+ safe_word RVBOX_TEST_PYTHON_DOWNLOAD_PROXY "$RVBOX_TEST_PYTHON_DOWNLOAD_PROXY"
+ case $RVBOX_TEST_PYTHON_DOWNLOAD_PROXY in socks5://*|socks5h://*) ;; *) fail "Python download proxy must use socks5" ;; esac
+fi
: "${RVBOX_TEST_ACCEL_HTTP_URL:=http://x1.xcel.me:9124}"
: "${RVBOX_TEST_ACCEL_HTTP_AUTH:=x1:x1}"
: "${RVBOX_TEST_ACCEL_HTTP_PUBLISH_DIR:=/home/ubuntu/Downloads}"
@@ -170,7 +187,7 @@ remote() {
# retry. Lifecycle transitions remain single-attempt: their caller must
# inspect/recover rather than risk a duplicate reset, shutdown, or logoff.
case $remote_action in
- status|recover|prepare-stage|stage|stage-create-root|stage-copy-exe|stage-copy-config|stage-copy-ca|collect|inspect|logs|install|run)
+ status|recover|prepare-stage|provision-python-stage|stage|stage-create-root|stage-copy-exe|stage-copy-config|stage-copy-ca|collect|inspect|logs|install|run)
retry_limit=4
;;
esac
@@ -179,7 +196,7 @@ remote() {
retry_attempt=1
while [ "$retry_attempt" -le "$retry_limit" ]; do
if ssh -o BatchMode=yes -o ConnectTimeout=10 -o ServerAliveInterval=10 -o ServerAliveCountMax=2 "$RVBOX_TEST_VBOX_HOST" \
- "sh -s -- '$1' '$RVBOX_TEST_VBOX_VM' '$RVBOX_TEST_VBOX_VM_UUID' '$RVBOX_TEST_VBOX_SNAPSHOT' '$RVBOX_TEST_VBOX_SNAPSHOT_UUID' '$RVBOX_TEST_GUEST_USER' '$RVBOX_TEST_GUEST_PASSWORD_FILE' '$host_stage' '$guest_root' '$remote_endpoint' '$provisioner_user' '$provisioner_password_file' '$remote_fail_contexts'" <<'REMOTE'
+ "sh -s -- '$1' '$RVBOX_TEST_VBOX_VM' '$RVBOX_TEST_VBOX_VM_UUID' '$RVBOX_TEST_VBOX_SNAPSHOT' '$RVBOX_TEST_VBOX_SNAPSHOT_UUID' '$RVBOX_TEST_GUEST_USER' '$RVBOX_TEST_GUEST_PASSWORD_FILE' '$host_stage' '$guest_root' '$remote_endpoint' '$provisioner_user' '$provisioner_password_file' '$remote_fail_contexts' '$snapshot_name' '$RVBOX_TEST_PYTHON_DOWNLOAD_PROXY'" <<'REMOTE'
set -eu
action=$1
@@ -196,6 +213,8 @@ endpoint=$1
provisioner_user=$2
provisioner_password_file=$3
fail_contexts=$4
+snapshot_name=$5
+python_download_proxy=$6
[ "$endpoint" = - ] && endpoint=
[ "$fail_contexts" = - ] && fail_contexts=
@@ -304,7 +323,7 @@ assert_provisioner_absent() {
wait_guest_additions() {
attempt=0
- while [ "$attempt" -lt 60 ]; do
+ while [ "$attempt" -lt 240 ]; do
properties=$(VBoxManage guestproperty enumerate "$vm" 2>/dev/null || true)
if printf '%s\n' "$properties" | grep -q '/VirtualBox/GuestAdd/Version' && \
printf '%s\n' "$properties" | grep -q '/VirtualBox/GuestInfo/OS/Release'; then
@@ -313,7 +332,7 @@ wait_guest_additions() {
attempt=$((attempt + 1))
sleep 1
done
- fail "Guest Additions did not publish version and Windows OS-release properties"
+ fail "Guest Additions did not publish version and Windows OS-release properties within 240 seconds"
}
configure_display_keepalive() {
@@ -390,6 +409,77 @@ case "$action" in
guest_run --exe 'C:\Windows\System32\cmd.exe' --wait-stdout --wait-stderr --unquoted-args -- \
/d /s /c 'whoami /groups & query user & echo RVBOX_GUEST_OK' >/dev/null
;;
+ provision-python-stage)
+ assert_identity
+ require_lease
+ [ "$(state)" = running ] || fail "Python provisioning requires a running prepared VM"
+ assert_clean_guest
+ assert_provisioner_elevated
+ install -d -m 700 "$host_stage"
+ provisioner_run --exe 'C:\Windows\System32\cmd.exe' --wait-stdout --wait-stderr --unquoted-args -- \
+ /d /s /c 'mkdir C:\ProgramData\RVBoxFixture\python >NUL 2>&1 & if exist C:\ProgramData\RVBoxFixture\python echo RVBOX_GUEST_OK' || fail "Python staging directory is unavailable"
+ ;;
+ provision-python)
+ assert_identity
+ require_lease
+ [ "$(state)" = running ] || fail "Python provisioning requires a running prepared VM"
+ assert_clean_guest
+ assert_provisioner_elevated
+ # Pin must match provision-python.ps1. Default to direct HTTPS on
+ # Helium; only use its metered proxy when explicitly configured.
+ # Retain partial bytes for explicit resumable retries.
+ python_version=3.13.16
+ python_digest=fb4f9f5d438b2396da0086dc70b935c530cb578e37adc6d354f7ad2037fee83b
+ python_installer=$host_stage/python-$python_version-amd64.exe
+ if [ ! -f "$python_installer" ] || [ "$(sha256sum "$python_installer" | awk '{print $1}')" != "$python_digest" ]; then
+ set --
+ if [ -n "$python_download_proxy" ]; then set -- --proxy "$python_download_proxy"; fi
+ curl --fail --silent --show-error --continue-at - --retry 2 --retry-all-errors \
+ --connect-timeout 15 --max-time 120 "$@" --output "$python_installer.new" \
+ "https://www.python.org/ftp/python/$python_version/python-$python_version-amd64.exe"
+ [ "$(sha256sum "$python_installer.new" | awk '{print $1}')" = "$python_digest" ] || fail "Python installer digest mismatch; inspect retained host-stage bytes"
+ mv "$python_installer.new" "$python_installer"
+ fi
+ VBoxManage guestcontrol "$vm" --username "$provisioner_user" --passwordfile "$provisioner_password_file" \
+ copyto "$host_stage/provision-python.ps1" 'C:\ProgramData\RVBoxFixture\provision-python.ps1' /dev/null || fail "could not remove Python provisioning files"
+ VBoxManage controlvm "$vm" acpipowerbutton >/dev/null
+ attempt=0
+ while [ "$attempt" -lt 90 ]; do
+ [ "$(state)" = poweroff ] && break
+ attempt=$((attempt + 1))
+ sleep 1
+ done
+ [ "$(state)" = poweroff ] || fail "VM did not shut down cleanly; baseline was not captured"
+ VBoxManage snapshot "$vm" take "$snapshot_name" --description 'Clean RVBox fixture; full-token Administrator; Python 3.13.16 amd64, pip and venv; no RVBox installation' >/dev/null
+ new_snapshot_uuid=$(vm_field CurrentSnapshotUUID)
+ [ "$(vm_field CurrentSnapshotName)" = "$snapshot_name" ] && [ -n "$new_snapshot_uuid" ] || fail "new snapshot identity could not be verified"
+ release_lease
+ step capture-python-baseline-complete
+ printf 'python_baseline=%s uuid=%s state=poweroff\n' "$snapshot_name" "$new_snapshot_uuid"
+ ;;
stage)
assert_identity
require_lease
@@ -671,6 +761,11 @@ case $action in
remote prepare
printf 'prepared vm=%s stage=%s\n' "$RVBOX_TEST_VBOX_VM" "$host_stage"
;;
+ provision-python)
+ remote provision-python-stage
+ copy_stage_file "$repo_root/scripts/windows/provision-python.ps1" provision-python.ps1
+ remote provision-python
+ ;;
stage)
printf 'stage: verify prepared VM and lease\n'
remote prepare-stage
diff --git a/test/rdp-access/README.md b/test/rdp-access/README.md
index 9ef52b6..352059f 100644
--- a/test/rdp-access/README.md
+++ b/test/rdp-access/README.md
@@ -24,11 +24,47 @@ password to the VM. Clipboard, drives, printing, audio, microphone input, GFX,
and display-resize extensions are disabled because the fixture's VirtualBox
RDP4 server does not handle them reliably.
+## Network and graphics quality
+
+Use `--graphics minimal|low|normal|high` on `up`, or set `RDP_ACCESS_GRAPHICS`:
+
+| Mode | Requested display | Color | Intended use |
+| --- | --- | --- | --- |
+| `minimal` | 800×600, 96 DPI | 8-bit / 256 colors | Lowest pixel/color budget; substantial color loss |
+| `low` | 1024×768, 96 DPI | 16-bit | Slow/metered networks, terminal work |
+| `normal` | Browser dimensions/DPI | 24-bit | Default, same behavior as the original helper |
+| `high` | 1920×1080, 96 DPI | 24-bit | Fast connections and larger desktops |
+
+```sh
+test/rdp-access/rdp-access up --bind 0.0.0.0 --public-host x1.xcel.me --graphics minimal
+test/rdp-access/rdp-access up --bind 0.0.0.0 --public-host x1.xcel.me --graphics low
+test/rdp-access/rdp-access up --bind 0.0.0.0 --public-host x1.xcel.me --graphics normal
+```
+
+The choice is saved per gateway profile and reused when omitted. `status`
+prints the saved `graphics` mode. A change rewrites the connection mapping
+while retaining the gateway and tunnels; disconnect/reconnect the desktop to
+apply it. Existing sessions continue with their original display settings.
+If an old browser connection holds the single VRDE slot, close it or use the
+documented `repair` action before reconnecting.
+
+All modes keep wallpaper, themes, font smoothing, menu animation, full-window
+drag, audio/device redirection, and GFX disabled. Lossy compression remains
+available to Guacamole's normal heuristics. Display dimensions/color depth are
+requests to the RDP server; the negotiated framebuffer can differ if the
+server restricts them. A smaller display reduces pixel traffic; it cannot
+eliminate network latency. See the [Guacamole 1.6 display settings](https://guacamole.apache.org/doc/1.6.0/gug/configuring-guacamole.html#display-settings).
+There is no RDP black-and-white/grayscale parameter: `minimal` requests a
+256-color palette. Static terminal work and smaller windows generally cost
+less than scrolling images or video. The RDP backend does not provide VNC's
+`quality-level`/`compress-level` knobs; those must not be added to this RDP
+mapping as if they controlled its encoding.
+
## Current fixture quick start
The following is the copy/paste path for the documented `rvbox-win10-test`
fixture. Run it from the repository root. The first command acquires the
-exclusive VM lease, restores the clean administrator-enabled snapshot, starts
+exclusive VM lease, restores the clean Python/administrator-enabled snapshot, starts
the VM, and applies the VRDE display keepalive. The second command starts the
Docker-only gateway at the currently published endpoint:
diff --git a/test/rdp-access/rdp-access b/test/rdp-access/rdp-access
index 42cb8e4..a918dd5 100755
--- a/test/rdp-access/rdp-access
+++ b/test/rdp-access/rdp-access
@@ -46,6 +46,9 @@ up options:
--tunnel-port PORT private VRDE tunnel port (default 54001)
--public-host NAME browser-visible hostname or IP for the URL and cert SAN
--web-user USER Guacamole and Windows account (default rvboxtest)
+ --graphics MODE minimal (800x600/8-bit), low (1024x768/16-bit),
+ normal (browser size/24-bit),
+ or high (1920x1080/24-bit); saved per profile
--reset-auth discard the saved password hash and prompt again
--web-password-stdin read the password once from stdin instead of prompting
@@ -56,6 +59,9 @@ RDP_ACCESS_VRDE_PORT. In public mode, RDP_ACCESS_IPV6_BIND and
RDP_ACCESS_IPV6_FORWARD (auto, always, or never) control the reversible
IPv6-to-IPv4 listener for dual-stack hostnames. Set
RDP_ACCESS_GUACD_LOG_LEVEL=debug for temporary protocol diagnostics.
+RDP_ACCESS_GRAPHICS is equivalent to --graphics; omitted values reuse the
+saved profile setting (normal for a first start). Reconnect the desktop after
+changing graphics; existing connections retain their original settings.
EOF
}
@@ -305,8 +311,13 @@ render_mapping() {
-e "s/@DOCKER_GATEWAY@/$docker_gateway/g" \
-e "s/@TUNNEL_PORT@/$RDP_ACCESS_TUNNEL_PORT/g" \
-e "s/@RDP_USER@/$RDP_ACCESS_RDP_USER/g" \
- "$mapping_template" >"$runtime_dir/config/user-mapping.xml"
- chmod 600 "$runtime_dir/config/user-mapping.xml"
+ -e "s/@COLOR_DEPTH@/$graphics_depth/g" \
+ -e "s/@DISPLAY_WIDTH@/$graphics_width/g" \
+ -e "s/@DISPLAY_HEIGHT@/$graphics_height/g" \
+ -e "s/@DISPLAY_DPI@/$graphics_dpi/g" \
+ "$mapping_template" >"$runtime_dir/config/user-mapping.xml.new"
+ chmod 600 "$runtime_dir/config/user-mapping.xml.new"
+ mv "$runtime_dir/config/user-mapping.xml.new" "$runtime_dir/config/user-mapping.xml"
if [ -f "$cert_name_file" ] && [ "$(cat "$cert_name_file")" != "$RDP_ACCESS_PUBLIC_HOST" ]; then
rm -f "$runtime_dir/tls/cert.pem" "$runtime_dir/tls/key.pem"
fi
@@ -320,6 +331,7 @@ render_mapping() {
printf 'public_host=%s\n' "$RDP_ACCESS_PUBLIC_HOST" >>"$session_file"
printf 'web_user=%s\n' "$RDP_ACCESS_WEB_USER" >>"$session_file"
printf 'rdp_user=%s\n' "$RDP_ACCESS_RDP_USER" >>"$session_file"
+ printf 'graphics=%s\n' "$RDP_ACCESS_GRAPHICS" >>"$session_file"
chmod 600 "$session_file"
}
@@ -438,6 +450,7 @@ while [ "$#" -gt 0 ]; do
--tunnel-port) [ "$#" -ge 2 ] || fail "--tunnel-port needs a value"; RDP_ACCESS_TUNNEL_PORT=$2; shift 2 ;;
--public-host) [ "$#" -ge 2 ] || fail "--public-host needs a value"; RDP_ACCESS_PUBLIC_HOST=$2; shift 2 ;;
--web-user) [ "$#" -ge 2 ] || fail "--web-user needs a value"; RDP_ACCESS_WEB_USER=$2; RDP_ACCESS_RDP_USER=$2; shift 2 ;;
+ --graphics) [ "$#" -ge 2 ] || fail "--graphics needs a value"; RDP_ACCESS_GRAPHICS=$2; shift 2 ;;
--reset-auth) reset_auth=true; shift ;;
--web-password-stdin) password_stdin=true; shift ;;
--images) remove_images=true; shift ;;
@@ -465,6 +478,19 @@ tunnel_pid_file=$runtime_dir/tunnel-watchdog.pid
tunnel_log_file=$runtime_dir/tunnel.log
ipv6_pid_file=$runtime_dir/ipv6-forward.pid
ipv6_log_file=$runtime_dir/ipv6-forward.log
+saved_graphics=normal
+if [ -f "$session_file" ]; then
+ stored_graphics=$(sed -n 's/^graphics=//p' "$session_file")
+ [ -z "$stored_graphics" ] || saved_graphics=$stored_graphics
+fi
+RDP_ACCESS_GRAPHICS=${RDP_ACCESS_GRAPHICS-$saved_graphics}
+case $RDP_ACCESS_GRAPHICS in
+ minimal) graphics_depth=8; graphics_width=800; graphics_height=600; graphics_dpi=96 ;;
+ low) graphics_depth=16; graphics_width=1024; graphics_height=768; graphics_dpi=96 ;;
+ normal) graphics_depth=24; graphics_width=; graphics_height=; graphics_dpi= ;;
+ high) graphics_depth=24; graphics_width=1920; graphics_height=1080; graphics_dpi=96 ;;
+ *) fail "--graphics / RDP_ACCESS_GRAPHICS must be minimal, low, normal, or high" ;;
+esac
safe_bind "$RDP_ACCESS_BIND"
safe_port RDP_ACCESS_HTTP_PORT "$RDP_ACCESS_HTTP_PORT"
@@ -505,6 +531,10 @@ case $action in
mkdir -p "$runtime_dir"
docker_gateway=$(gateway_for_network) || fail "could not determine private Docker gateway"
session_matches_current || fail "gateway already exists with a different configuration; run down first, then run up with the desired options"
+ if [ "$saved_graphics" != "$RDP_ACCESS_GRAPHICS" ]; then
+ render_mapping
+ printf 'Graphics changed to %s. Disconnect/reconnect the desktop to apply.\n' "$RDP_ACCESS_GRAPHICS"
+ fi
if tunnel_active; then
printf 'Guacamole stack and private VRDE tunnel are already active.\n'
elif start_tunnel; then
@@ -545,6 +575,7 @@ case $action in
status)
[ "$#" -eq 0 ] || { usage >&2; fail "status accepts no options"; }
printf 'profile=%s project=%s runtime=%s\n' "$profile" "$project" "$runtime_dir"
+ printf 'graphics=%s\n' "$saved_graphics"
"$repo_root/scripts/windows/test-host" status || true
if [ -f "$session_file" ]; then sed -n '1p' "$session_file"; fi
compose ps
diff --git a/test/rdp-access/user-mapping.xml.in b/test/rdp-access/user-mapping.xml.in
index 060848d..676a051 100644
--- a/test/rdp-access/user-mapping.xml.in
+++ b/test/rdp-access/user-mapping.xml.in
@@ -15,7 +15,13 @@
false
false
false
- 24
+ @COLOR_DEPTH@
+ @DISPLAY_WIDTH@
+ @DISPLAY_HEIGHT@
+ @DISPLAY_DPI@
+ false
+ false
+ false
true