Native-Windows verification and qualification procedure

This procedure applies after this source slice is merged into the complete checkout at:

E:\Projects\RoboBuddy_AI\SolU

It deliberately separates four boundaries:

source/offline verification;
native-Windows dependency and bridge verification;
real browser/Android lifecycle verification without claiming robot motion;
separately authorized, supervised physical qualification.

The returned bundle does not authorize Step 4. Its checked-in safety state remains:

"provisional_limits": true,
"hardware": { "enabled": false, "qualified": false }

1. Prerequisites

Use native 64-bit Windows—not WSL, Docker, a VM, or a remote bridge.

Install:

CPython 3.12.10 x64, including the Python launcher;
Git for Windows;
current stable Chrome and Edge;
Node/npm required by the complete SolU checkout;
mkcert 1.4.4 from its official release, or Chocolatey only when you explicitly choose the setup script's install switch;
current stable Chrome on an ARCore-supported physical Android device with Google Play Services for AR.

Open PowerShell in any directory. Scripts resolve paths from their own location, but the examples below use the target root for clarity:

Set-Location E:\Projects\RoboBuddy_AI\SolU
Set-ExecutionPolicy -Scope Process Bypass

Confirm the exact Python baseline:

py -3.12-64 -c "import platform,struct,sys; print(platform.python_version(), 8*struct.calcsize('P'), sys.platform)"

Required output starts with:

3.12.10 64 win32

2. Clean or repaired SolU-local environment

The setup script only accepts SolU\.venv-so101; it rejects junction/reparse-point reuse and verifies the editable bridge source resolves to SolU\bridge.

Clean construction or idempotent verification:

.\tools\setup-so101-windows.ps1

Force a local rebuild after a partial or suspect install:

.\tools\setup-so101-windows.ps1 -ForceRepair

The successful JSON report must say:

"setupStatus": "OFFLINE_RUNTIME_PROBES_PASSED"

That result means dependency, import, phone-protocol, editable-provenance, and real selected-kinematics construction probes passed without enumerating/opening serial ports, starting listeners, or sending motion. It is not the bundle's terminal status.

Repeat the read-only probe directly:

.\.venv-so101\Scripts\python.exe .\bridge\probe_windows_runtime.py `
  --expected-bridge-root .\bridge `
  --require-windows

Required facts in the sanitized result include:

Python 3.12.10, 64-bit, native Windows;
editable robobuddy-bridge provenance matching this SolU\bridge;
LeRobot 0.6.1 at commit 8a74e0ac6d01706d67fddfed682a09d694d9c8c0;
exact dependency versions from bridge\pyproject.toml;
LeRobot SO-101 adapter classes import without serial access;
phone protocol probe passes;
native_dls_v1 constructs and meets its FK/IK software residual;
all serial/listener/motion booleans remain false.

3. Source and offline test commands

Run these in the complete merged checkout:

$env:PYTHONPATH = "$PWD\bridge;$PWD"
.\.venv-so101\Scripts\python.exe -m compileall -q `
  .\bridge\robobuddy_bridge `
  .\bridge\probe_lerobot_compat.py `
  .\bridge\probe_phone_teleop_compat.py `
  .\bridge\probe_tls_material.py `
  .\bridge\probe_windows_runtime.py `
  .\tests\phone_leader `
  .\tests\test_windows_control_source.py

.\.venv-so101\Scripts\python.exe -m unittest discover `
  -s .\tests\phone_leader -p "test_*.py" -v

.\.venv-so101\Scripts\python.exe -m unittest discover `
  -s .\tests -p "test_*.py" -v

Get-ChildItem -Recurse -Filter *.js | ForEach-Object {
  node --check $_.FullName
  if ($LASTEXITCODE -ne 0) { throw "JavaScript syntax failed: $($_.FullName)" }
}

node .\tests\ui-contracts.js
npm test

The source slice alone intentionally lacks unrelated full-application pages such as python.html; run the complete JavaScript suite only after merging into the complete checkout. Do not manufacture missing pages in this patch slice to make that suite pass.

The kinematics corpus includes accepted home/compact, interior-workspace, operating-limit-adjacent, and near-singular cases, plus unreachable, malformed/non-finite, position-only, and weighted soft-orientation tests. The independent oracle uses only the standard library and does not import production kinematics or NumPy.

4. Default-disabled bridge lifecycle

Start a token-protected bridge with every hardware Leader feature disabled:

.\tools\start-so101-bridge.ps1 -Restart

Record the printed local token securely; do not place it in source, screenshots, support exports, or test artifacts. Confirm:

Invoke-RestMethod http://127.0.0.1:8765/health | ConvertTo-Json -Depth 8

Required postconditions:

status is READY;
authRequired is true;
virtualLeader, gamepadLeader, and phoneLeader are disabled;
listener owner is the selected SolU\.venv-so101\Scripts\python.exe running -m robobuddy_bridge --host 127.0.0.1 --port 8765.

Exercise exact ownership-preserving restart and shutdown:

.\tools\start-so101-bridge.ps1 -Restart
.\tools\start-so101-bridge.ps1 -Stop

The helper must refuse to kill or replace an unrelated process on the selected port.

run-app.bat remains the convenience development launcher and must leave all hardware features disabled.

5. Private-LAN HTTPS material

Select one assigned, operational RFC1918 IPv4 address on the Windows machine. Do not use a VPN, virtual adapter, public IP, or an address that is not assigned to an up interface.

Get-NetIPConfiguration | Where-Object {
  $_.IPv4DefaultGateway -and $_.NetAdapter.Status -eq 'Up'
} | Select-Object InterfaceAlias,IPv4Address,IPv4DefaultGateway

$PrivateIPv4 = '192.168.1.25'   # replace with the selected assigned address

Create runtime-only certificate material and, optionally, one narrowly scoped Private-profile firewall rule:

.\tools\setup-phone-leader-tls.ps1 `
  -PrivateIPv4 $PrivateIPv4 `
  -Port 8443 `
  -AddPrivateFirewallRule

When mkcert 1.4.4 is not already installed and Chocolatey is intentionally available, the only script-assisted install path is explicit:

.\tools\setup-phone-leader-tls.ps1 `
  -PrivateIPv4 $PrivateIPv4 `
  -Port 8443 `
  -InstallMkcertWithChocolatey `
  -AddPrivateFirewallRule

All generated files stay under ignored SolU\.runtime-private\phone-leader-tls:

phone-leader-cert.pem — leaf certificate;
phone-leader-key.pem — leaf private key, Windows only;
android-rootCA.pem — public development CA certificate for Android import.

Never copy rootCA-key.pem or phone-leader-key.pem to Android. Never add any generated certificate, key, token, or pairing material to Git or a source ZIP.

Android CA trust and pre-pairing check

Transfer only android-rootCA.pem to the intended Android device through a trusted local method.
Use the device's security settings to install it as a CA certificate. The exact menu name varies by Android/vendor; record the device model, Android version, and chosen trust-store path.
Confirm Windows and Android are on the same trusted private LAN and client isolation is not blocking peer access.
Start the phone HTTPS source only through the qualified Phone Leader bridge path described below.
In Android Chrome, open https://<PrivateIPv4>:8443/ manually before scanning a QR code.
Do not continue if Chrome shows a certificate warning. Confirm window.isSecureContext === true and that navigator.xr exists.

A device without required WebXR/ARCore capability is a device/browser compatibility result; it is not evidence that native Windows is impossible.

6. Browser and Android lifecycle checks

Xbox, Chrome and Edge

Do not enable robot motion for these source-level checks. In each browser:

Connect the intended Xbox controller through the intended Windows transport and press a button after the page has focus.
Confirm Gamepad API exists and the chosen gamepad reports mapping === "standard".
When multiple controllers are visible, verify no automatic selection occurs.
Explicitly select the intended controller and complete neutral qualification.
Verify no startup movement intent; left-stick mapping to Base/Bend/Tool; RT analog deadman; LB Fine override; idle-only D-pad pair selection; X cancel/measured hold; B global STOP/disarm; all other controls no motion/safety action.
Verify monotonic timestamps, poll-gap/stale retirement, unplug/Bluetooth-loss retirement, and explicit re-arm/re-align after STOP.

Run the complete channel test in the full checkout:

npm run test:controller:channels

Android secure source

With the robot still physically disabled, verify the source/session path through approved test/fake facilities:

one-time QR is consumed once and expires;
the secure cookie exchange succeeds without exposing pairing code/token in diagnostics;
only one authorized source WebSocket is accepted;
recenter/alignment creates no motion;
hold-to-move intent exists only while held; release retires to hold;
gripper holds are independent;
tracking-limited/lost, visibility, focus, pointer, transport, WebSocket, and XR-session loss retire intent;
reconnect/reload/restart restores no movement intent, alignment, pairing, or armed state;
stale/non-finite/out-of-workspace/unreachable input fails closed;
STOP remains global and recovery requires explicit re-arm/re-align.

7. Physical verification boundary

No physical motion was run while producing this bundle. Do not run the commands below merely because they are documented.

Before any supervised session:

complete the existing read-only H0/H1 evidence process and replace provisional joint/workspace values through reviewed configuration;
use the exact robot instance, calibration, effective limits, Home metadata, browser/device/controller versions, and release source under test;
clear the workspace, remove payloads, maintain direct line of sight, provide a reachable physical power cutoff, and assign an independent observer;
start at Fine speed;
confirm authentication, connection, calibration, measured feedback freshness, ownership, STOP, hold, and source-loss behavior before task motion;
record exact evidence and abort on any uncommanded motion, stale continuation, owner overlap, limit violation, STOP/hold failure, communication ambiguity, or observer concern.

Only after reviewed physical evidence establishes non-provisional limits and qualification may an authorized maintainer update the config. The checked-in bundle intentionally makes this command fail closed today:

$TlsRoot = Join-Path $PWD '.runtime-private\phone-leader-tls'
.\tools\start-so101-bridge.ps1 `
  -Restart `
  -EnablePhoneLeader `
  -PhoneHttpsHost $PrivateIPv4 `
  -PhoneHttpsPort 8443 `
  -PhoneHttpsCertificate (Join-Path $TlsRoot 'phone-leader-cert.pem') `
  -PhoneHttpsPrivateKey (Join-Path $TlsRoot 'phone-leader-key.pem')

After a genuinely qualified configuration is supplied, the launcher additionally requires /health to report phoneLeader: enabled and phoneLeaderQualified: true; otherwise it stops the process and reports failure.

Xbox physical qualification separately requires the signed Virtual Leader prerequisite and the complete docs/gamepad-qualification.md protocol. The intended explicit launcher shape is:

.\tools\start-so101-bridge.ps1 -Restart -EnableVirtualLeader -EnableGamepadLeader

Use it only under that supervised protocol.

The 1.5 mm IK residual is a software numerical tolerance. It does not predict backlash, calibration, servo resolution, compliance, payload error, collision margin, or physical end-effector accuracy.

8. Rollback and cleanup

Immediately STOP/disarm in the UI and use the physical cutoff when required. Then disable hardware modes with a clean restart:

.\tools\start-so101-bridge.ps1 `
  -Restart `
  -DisableVirtualLeader `
  -DisableGamepadLeader `
  -DisablePhoneLeader

Stop the bridge:

.\tools\start-so101-bridge.ps1 -Stop

Remove the exact firewall rule and runtime certificate material:

.\tools\remove-phone-leader-tls.ps1 -Port 8443

Optionally remove the local mkcert CA from Windows too:

.\tools\remove-phone-leader-tls.ps1 -Port 8443 -UninstallMkcertRootCA

Remove the imported development CA from Android through the same credential settings used to install it.

9. Returned-bundle verification record

The packaging host was Linux with Python 3.13.5 and Node v22.16.0. PowerShell, native Windows networking/process APIs, current Windows Chrome/Edge channels, Android WebXR hardware, a COM port, and the SO-101 were unavailable. Therefore these results are source/offline evidence only and do not upgrade the terminal status.

Commands and exact results run against the returned source before manifest generation:

python3 -m compileall -q bridge/robobuddy_bridge \
  bridge/probe_lerobot_compat.py bridge/probe_phone_teleop_compat.py \
  bridge/probe_tls_material.py bridge/probe_windows_runtime.py \
  tests/phone_leader tests/test_windows_control_source.py
Result: PASS

PYTHONPATH=bridge:tests:. python3 -m unittest -v test_windows_control_source
Result: PASS — 9 tests

PYTHONPATH=bridge:. python3 -m unittest discover \
  -s tests/phone_leader -p 'test_*.py' -v
Result: PASS — 163 tests in 1.396 s

PYTHONPATH=bridge:tests:. python3 tests/test_bridge_gripper_takeover.py
PYTHONPATH=bridge:tests:. python3 tests/test_bridge_connect_handshake.py
PYTHONPATH=bridge:tests:. python3 tests/test_bridge_communication_resilience.py
PYTHONPATH=bridge:tests:. python3 tests/test_bridge_limit_pressure.py
PYTHONPATH=bridge:tests:. python3 tests/test_bridge_virtual_leader.py
PYTHONPATH=bridge:tests:. python3 tests/test_gamepad_qualification_schema.py
Result: PASS — 6 script suites

find . -type f -name '*.js' ... node --check <file>
Result: PASS — 17 JavaScript files

JSON parse over every returned *.json file
Result: PASS — 17 files

The independent native-kinematics timing sample ran 200 successful alternating position-only/soft-orientation IK solves after warm-up:

backend: native_dls_v1
median: 0.969040 ms
p95: 1.148870 ms
maximum: 1.970978 ms
maximum solver iterations observed: 3
configured wall-clock bound: 20 ms

That timing is from the Linux packaging host. It is not native-Windows timing and is not physical-accuracy evidence.

Two expected environment/source-slice blockers were reproduced rather than hidden:

PYTHONPATH=bridge:tests:. python3 tests/test_phone_leader_upstream_compat.py
Result: BLOCKED before tests — ModuleNotFoundError: No module named 'lerobot'
Reason: the packaging host did not contain the selected external LeRobot installation.
Required closure: run after tools/setup-so101-windows.ps1 succeeds on native Windows.

node tests/ui-contracts.js
npm test
Result: BLOCKED — ENOENT for SolU/python.html
Reason: python.html was absent from the received patch-oriented source slice.
Required closure: merge into the complete SolU checkout and rerun; no unrelated replacement page was added.

The final critical review rechecked STOP precedence, ownership, stale/source-loss retirement, authentication, default-disabled hardware gates, local-path/credential redaction, explicit no-fallback kinematics selection, launcher process ownership, and runtime-only TLS material. It also added reparse-point rejection for the TLS runtime parent, runtime directory, and pre-existing output links so setup/cleanup cannot follow an unexpected junction or linked certificate target.