pixelremotecontrol 0.0.0-stage → 0.2.0

package/DISCLOSURE

@@ -0,0 +1,5 @@
+# Authorized remote device control
+
+This package mirrors and controls an Android device that its owner has deliberately paired for ADB Wireless debugging and connected to a trusted SSH relay. It can wake, lock, and restart that device. The phone holder starts sharing from Termux and can stop the session at any time. A viewer must authenticate to the relay and have access through its private network.
+
+The commands are intended for development, support, and access to devices owned by the operator or used with the owner's permission. They do not bypass Android's lock screen, ADB pairing, SSH authentication, or Tailscale authorization. The package does not collect credentials or device data.

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# pixelremotecontrol
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command line launcher for a paired Pixel 8 and a private SSH relay. Use it only
+with a device you own or are authorized to control.
+
+On a Windows viewer PC:
+
+```powershell
+npm.cmd install -g pixelremotecontrol
+pixelremotecontrol setup --host YOUR_RELAY_TAILSCALE_IP --user YOUR_SSH_USERNAME
+pixelremotecontrol control local pixel8
+```
+
+`setup` saves the relay address for this viewer and downloads the official
+scrcpy Windows bundle (including `adb`). A later `control` run downloads it if
+needed. Windows OpenSSH Client and Tailscale access to the relay are required.
+SSH authentication is interactive; no password is stored by this package.
+Use `npm.cmd` in PowerShell because Windows execution policy may block
+`npm.ps1`. The `pixelremotecontrol` command uses a `.cmd` launcher and works
+under a Restricted PowerShell execution policy.
+If an older manual installation is still on `PATH`, check which launcher wins
+with `Get-Command pixelremotecontrol -All`. Move the old launcher out of `PATH`
+so the npm `.cmd` is selected.
+
+On an Apple Silicon or Intel Mac:
+
+```sh
+npm install -g pixelremotecontrol
+pixelremotecontrol setup --host YOUR_RELAY_TAILSCALE_IP --user YOUR_SSH_USERNAME
+pixelremotecontrol control local pixel8
+```
+
+Mac `setup` downloads the official macOS scrcpy bundle for the Mac's processor,
+verifies its SHA-256 checksum, and caches its `scrcpy` and `adb` executables.
+The Mac needs an SSH client and Tailscale access to the relay. SSH prompts for
+authentication when needed; this package does not save an SSH password.
+`pixelremotecontrol status local pixel8`, `wake`, `lock`, and `restart` also
+work from the Mac. `control asml pixel8` must be run in ASML's interactive
+Windows desktop to put the window there.
+
+In Termux on the configured Pixel:
+
+```sh
+pkg install nodejs npm
+npm install -g pixelremotecontrol
+pixelremotecontrol setup
+pixelremotecontrol startservice pixel8 asml
+```
+
+If an older standalone `pixelremotecontrol` launcher is already in Termux's
+`$PREFIX/bin`, save it before installing the npm package:
+
+```sh
+mv "$PREFIX/bin/pixelremotecontrol" "$PREFIX/bin/pixelremotecontrol.pre-npm"
+npm install -g pixelremotecontrol
+```
+
+The command installs missing Termux `openssh`, `coreutils`, and `procps`
+packages. It
+uses the phone's existing relay config at `~/.config/pixel-connect/config`
+and key at `~/.ssh/central_tunnel`; it never writes or replaces them. Android
+Wireless debugging and relay ADB pairing must already be enabled. The command
+prompts for the Android connection port when Termux cannot discover it.
+The central machine must already have `pixelctl.cmd` provisioned, its ADB
+service paired with the Pixel, and a restricted SSH tunnel account that the
+phone's key can use. This package cannot complete Tailscale sign-in or
+Android's first-time ADB pairing for you.
+
+`pixelremotecontrol wake local pixel8`, `lock`, `restart`, and `status` work on
+Windows and macOS viewers. `control asml pixel8` opens a window on the ASML desktop
+when run there. The current relay scripts support one configured Pixel 8.
+
+The mirror can show and control ordinary Android screens, including Settings
+and the lock screen, while Android, Wireless debugging, and the phone's Termux
+relay stay active. Enter the phone's passcode in the scrcpy window when Android
+allows input there; the package does not know or bypass it. Some protected
+screens may be blank. After a reboot, a person must perform the first local
+unlock and restart the Termux service. The bootloader and fastboot screens do
+not run Android or scrcpy, so they require a separate USB host and an external
+way to see the physical display.

package/assets/phone/pixel-connect

@@ -0,0 +1,68 @@
+#!/data/data/com.termux/files/usr/bin/bash
+set -euo pipefail
+
+config="${PIXEL_CONNECT_CONFIG:-$HOME/.config/pixel-connect/config}"
+if [[ ! -r "$config" ]]; then
+  printf 'Missing %s. Copy config.example there and set CENTRAL_HOST and CENTRAL_USER.\n' "$config" >&2
+  exit 2
+fi
+# The config is owned and edited by the phone's Termux user.
+# shellcheck source=/dev/null
+source "$config"
+
+CENTRAL_HOST="${CENTRAL_HOST:-}"
+CENTRAL_USER="${CENTRAL_USER:-}"
+CENTRAL_SSH_PORT="${CENTRAL_SSH_PORT:-22}"
+CENTRAL_ADB_PORT="${CENTRAL_ADB_PORT:-15555}"
+CENTRAL_PAIR_PORT="${CENTRAL_PAIR_PORT:-15556}"
+
+usage() {
+  cat >&2 <<'USAGE'
+Usage: pixel-connect CONNECT_PORT [PAIR_PORT]
+
+Read CONNECT_PORT from Android Settings > Developer options > Wireless debugging
+("IP address & Port"). For first-time pairing, also open "Pair device with
+pairing code" and pass that separate PAIR_PORT. Press Ctrl+C to disconnect.
+USAGE
+  exit 2
+}
+
+valid_port() {
+  [[ "$1" =~ ^[0-9]{1,5}$ ]] && (( 10#$1 >= 1 && 10#$1 <= 65535 ))
+}
+
+[[ $# -ge 1 && $# -le 2 ]] || usage
+connect_port="$1"
+valid_port "$connect_port" || usage
+if [[ $# -eq 2 ]]; then
+  pair_port="$2"
+  valid_port "$pair_port" || usage
+fi
+if [[ -z "$CENTRAL_HOST" || -z "$CENTRAL_USER" ]]; then
+  printf 'Set CENTRAL_HOST and CENTRAL_USER in %s.\n' "$config" >&2
+  exit 2
+fi
+for port in "$CENTRAL_SSH_PORT" "$CENTRAL_ADB_PORT" "$CENTRAL_PAIR_PORT"; do
+  valid_port "$port" || { printf 'Invalid port in %s.\n' "$config" >&2; exit 2; }
+done
+
+key="$HOME/.ssh/central_tunnel"
+[[ -r "$key" ]] || { printf 'Missing SSH key: %s\n' "$key" >&2; exit 2; }
+
+ssh_args=(
+  -N -T -i "$key" -p "$CENTRAL_SSH_PORT"
+  -o BatchMode=yes
+  -o ExitOnForwardFailure=yes
+  -o ServerAliveInterval=20
+  -o ServerAliveCountMax=3
+  -o StrictHostKeyChecking=yes
+  -R "127.0.0.1:${CENTRAL_ADB_PORT}:127.0.0.1:${connect_port}"
+)
+if [[ -n "${pair_port:-}" ]]; then
+  ssh_args+=( -R "127.0.0.1:${CENTRAL_PAIR_PORT}:127.0.0.1:${pair_port}" )
+fi
+
+printf 'Connecting Pixel ADB to %s:%s (central loopback port %s).\n' \
+  "$CENTRAL_HOST" "$CENTRAL_SSH_PORT" "$CENTRAL_ADB_PORT"
+printf 'Keep this Termux session open. Press Ctrl+C or run pixel-disconnect to stop sharing.\n'
+exec ssh "${ssh_args[@]}" "${CENTRAL_USER}@${CENTRAL_HOST}"

package/assets/phone/pixelremotecontrol

@@ -0,0 +1,143 @@
+#!/data/data/com.termux/files/usr/bin/bash
+set -euo pipefail
+
+usage() {
+  cat >&2 <<'USAGE'
+Usage: pixelremotecontrol startservice <mobiledevice> <destination> [CONNECT_PORT]
+
+  mobiledevice: pixel8, pixel, thisdevice, or thismachine
+  destination:  asml (or the host configured for pixel-connect)
+
+Run this in Termux on the Pixel. Wireless debugging must be enabled. If its
+connection port cannot be found automatically, this command asks for the
+"IP address & Port" shown in Android's Wireless debugging settings.
+USAGE
+  exit 2
+}
+
+valid_port() {
+  [[ "$1" =~ ^[0-9]{1,5}$ ]] && (( 10#$1 >= 1 && 10#$1 <= 65535 ))
+}
+
+port_open() {
+  # The reverse tunnel connects to the phone's own loopback ADB listener.
+  # A two-second limit avoids hanging if the listener is unavailable.
+  timeout 2 bash -c 'exec 3<>"/dev/tcp/127.0.0.1/$1"' _ "$1" >/dev/null 2>&1
+}
+
+[[ $# -ge 3 && $# -le 4 && "$1" == startservice ]] || usage
+device="${2,,}"
+destination="${3,,}"
+case "$device" in
+  pixel8|pixel|thisdevice|thismachine) ;;
+  *) printf 'Unknown mobile device: %s\n' "$2" >&2; usage ;;
+esac
+
+config="${PIXEL_CONNECT_CONFIG:-$HOME/.config/pixel-connect/config}"
+cache="$(dirname "$config")/last-connect-port"
+if [[ ! -r "$config" ]]; then
+  printf 'Missing pixel-connect configuration: %s\n' "$config" >&2
+  exit 2
+fi
+# The config is owned and edited by the phone's Termux user.
+# shellcheck source=/dev/null
+source "$config"
+CENTRAL_HOST="${CENTRAL_HOST:-}"
+CENTRAL_USER="${CENTRAL_USER:-}"
+CENTRAL_ADB_PORT="${CENTRAL_ADB_PORT:-15555}"
+if [[ -z "$CENTRAL_HOST" || -z "$CENTRAL_USER" ]] || ! valid_port "$CENTRAL_ADB_PORT"; then
+  printf 'Set a valid CENTRAL_HOST, CENTRAL_USER, and CENTRAL_ADB_PORT in %s.\n' "$config" >&2
+  exit 2
+fi
+case "$destination" in
+  asml|"${CENTRAL_HOST,,}"|"${CENTRAL_USER,,}@${CENTRAL_HOST,,}") ;;
+  *) printf 'Destination %s does not match the configured central machine (%s).\n' "$3" "$CENTRAL_HOST" >&2; exit 2 ;;
+esac
+command -v pixel-connect >/dev/null 2>&1 || {
+  printf 'pixel-connect is not installed in Termux. Install the Pixel phone tools first.\n' >&2
+  exit 2
+}
+command -v timeout >/dev/null 2>&1 || {
+  printf 'The Termux coreutils package is required (pkg install coreutils).\n' >&2
+  exit 2
+}
+
+# Find only this phone's existing reverse tunnel to the configured machine.
+pattern="^ssh -N -T -i .*/central_tunnel .* -R 127\\.0\\.0\\.1:${CENTRAL_ADB_PORT}:"
+mapfile -t tunnel_pids < <(pgrep -f "$pattern" || true)
+active_port=''
+if ((${#tunnel_pids[@]})); then
+  for pid in "${tunnel_pids[@]}"; do
+    [[ -r "/proc/$pid/cmdline" ]] || continue
+    cmdline="$(tr '\0' ' ' < "/proc/$pid/cmdline")"
+    [[ "$cmdline" == *" ${CENTRAL_USER}@${CENTRAL_HOST} "* ]] || continue
+    if [[ "$cmdline" =~ 127\.0\.0\.1:${CENTRAL_ADB_PORT}:127\.0\.0\.1:([0-9]+) ]]; then
+      active_port="${BASH_REMATCH[1]}"
+      active_pid="$pid"
+      break
+    fi
+  done
+fi
+
+connect_port=''
+if [[ $# -eq 4 ]]; then
+  connect_port="$4"
+elif [[ -n "${PIXEL_CONNECT_PORT:-}" ]]; then
+  connect_port="$PIXEL_CONNECT_PORT"
+else
+  # This Android system property may be hidden from Termux on some builds.
+  if command -v getprop >/dev/null 2>&1; then
+    property_port="$(getprop service.adb.tls.port 2>/dev/null || true)"
+    if valid_port "$property_port" && port_open "$property_port"; then
+      connect_port="$property_port"
+    fi
+  fi
+  if [[ -z "$connect_port" && -n "$active_port" ]] && port_open "$active_port"; then
+    connect_port="$active_port"
+  fi
+  if [[ -z "$connect_port" && -r "$cache" ]]; then
+    IFS= read -r cached_port < "$cache" || true
+    if valid_port "${cached_port:-}" && port_open "$cached_port"; then
+      connect_port="$cached_port"
+    fi
+  fi
+fi
+
+if [[ -z "$connect_port" ]]; then
+  if [[ ! -t 0 ]]; then
+    printf 'Wireless debugging port unknown. Run interactively or pass CONNECT_PORT from Settings > System > Developer options > Wireless debugging > IP address & Port.\n' >&2
+    exit 2
+  fi
+  printf 'Open Settings > System > Developer options > Wireless debugging.\n'
+  printf 'Enable Wireless debugging and read the port under "IP address & Port".\n'
+  while :; do
+    printf 'Connection port: '
+    IFS= read -r connect_port || exit 2
+    if valid_port "$connect_port" && port_open "$connect_port"; then
+      break
+    fi
+    printf 'That port is invalid or not listening on this phone. Check Wireless debugging and try again.\n' >&2
+  done
+elif ! valid_port "$connect_port" || ! port_open "$connect_port"; then
+  printf 'Wireless debugging is not listening on port %s. Check its "IP address & Port" in Android Settings.\n' "$connect_port" >&2
+  exit 2
+fi
+
+if [[ -n "$active_port" ]]; then
+  if [[ "$active_port" == "$connect_port" ]]; then
+    printf 'Pixel service is already connected to %s using wireless debugging port %s.\n' "$CENTRAL_HOST" "$connect_port"
+    exit 0
+  fi
+  printf 'Replacing the stale Pixel tunnel (port %s) with port %s.\n' "$active_port" "$connect_port"
+  kill "$active_pid" 2>/dev/null || true
+  # Give sshd time to release the existing reverse-forwarded port.
+  for ((attempt=0; attempt<20; attempt++)); do
+    kill -0 "$active_pid" 2>/dev/null || break
+    sleep 0.1
+  done
+fi
+
+mkdir -p "$(dirname "$cache")"
+umask 077
+printf '%s\n' "$connect_port" > "$cache"
+exec pixel-connect "$connect_port"

package/assets/viewer/pixelremotecontrol-core.ps1

@@ -0,0 +1,207 @@
+[CmdletBinding()]
+param(
+    [Parameter(Position = 0)]
+    [string]$Action = 'control',
+    [Parameter(Position = 1)]
+    [string]$Display = 'local',
+    [Parameter(Position = 2)]
+    [string]$DeviceId = 'pixel8',
+    [string]$CentralHost = '',
+    [string]$CentralUser = '',
+    [ValidateRange(1, 65535)]
+    [int]$SshPort = 22,
+    [ValidateRange(1024, 65535)]
+    [int]$AdbForwardPort = 5038,
+    [ValidateRange(1024, 65535)]
+    [int]$VideoPort = 27183,
+    [string]$ScrcpyPath = '',
+    [string]$AdbPath = '',
+    [ValidateRange(0, 86400)]
+    [int]$TimeLimitSeconds = 0,
+    [switch]$Help
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Show-Usage {
+    Write-Host 'Usage: pixelremotecontrol control <local|asml> <pixel8|Pixel_8> [options]'
+    Write-Host '       pixelremotecontrol <wake|lock|restart|status> <local|asml> <pixel8|Pixel_8>'
+    Write-Host 'Options: -CentralHost HOST -CentralUser USER -SshPort PORT -ScrcpyPath PATH -AdbPath PATH'
+    Write-Host 'Run "control local" on a Windows viewer to see and control the Pixel here.'
+    Write-Host 'Run "control asml" only in an interactive desktop session on ASML.'
+}
+
+function Resolve-Program {
+    param([string]$Name, [string]$ExplicitPath, [string]$SiblingPath)
+    if ($ExplicitPath) {
+        if (-not (Test-Path -LiteralPath $ExplicitPath -PathType Leaf)) {
+            throw "$Name was not found at '$ExplicitPath'."
+        }
+        return (Resolve-Path -LiteralPath $ExplicitPath).Path
+    }
+    if ($SiblingPath -and (Test-Path -LiteralPath $SiblingPath -PathType Leaf)) {
+        return (Resolve-Path -LiteralPath $SiblingPath).Path
+    }
+    $besideScript = Join-Path $PSScriptRoot $Name
+    if (Test-Path -LiteralPath $besideScript -PathType Leaf) {
+        return (Resolve-Path -LiteralPath $besideScript).Path
+    }
+    $command = Get-Command $Name -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
+    if ($command) { return $command.Source }
+    if ($env:LOCALAPPDATA) {
+        $packages = Join-Path $env:LOCALAPPDATA 'Microsoft\WinGet\Packages'
+        if (Test-Path -LiteralPath $packages -PathType Container) {
+            $found = Get-ChildItem -LiteralPath $packages -Directory -Filter 'Genymobile.scrcpy*' -ErrorAction SilentlyContinue |
+                ForEach-Object { Get-ChildItem -LiteralPath $_.FullName -Directory -Filter 'scrcpy-win64-*' -ErrorAction SilentlyContinue } |
+                Sort-Object Name -Descending |
+                ForEach-Object { Join-Path $_.FullName $Name } |
+                Where-Object { Test-Path -LiteralPath $_ -PathType Leaf } |
+                Select-Object -First 1
+            if ($found) { return $found }
+        }
+    }
+    throw "$Name was not found. Extract the scrcpy Windows ZIP or pass the corresponding path option."
+}
+
+function Test-PortFree {
+    param([int]$Port)
+    $listener = [System.Net.Sockets.TcpListener]::new([System.Net.IPAddress]::Loopback, $Port)
+    try { $listener.Start() }
+    catch { throw "Local port $Port is already in use. Close the other viewer or choose another forward port." }
+    finally { $listener.Stop() }
+}
+
+function Test-PortOpen {
+    param([int]$Port)
+    $client = New-Object System.Net.Sockets.TcpClient
+    try {
+        $pending = $client.BeginConnect('127.0.0.1', $Port, $null, $null)
+        if (-not $pending.AsyncWaitHandle.WaitOne(200)) { return $false }
+        $client.EndConnect($pending)
+        return $true
+    } catch { return $false }
+    finally { $client.Dispose() }
+}
+
+function Invoke-Adb {
+    param([string]$Program, [string[]]$Arguments)
+    # Windows PowerShell 5.1 may turn a native stderr line into a terminating
+    # NativeCommandError when ErrorActionPreference is Stop.
+    $oldPreference = $ErrorActionPreference
+    $ErrorActionPreference = 'Continue'
+    try {
+        $output = @(& $Program @Arguments 2>&1 | ForEach-Object { $_.ToString() })
+        $exitCode = $LASTEXITCODE
+        return [pscustomobject]@{ Output = $output; ExitCode = $exitCode }
+    } finally { $ErrorActionPreference = $oldPreference }
+}
+
+try {
+    if ($Help -or $Action -in @('help', '--help', '-help', '/?')) { Show-Usage; exit 0 }
+
+    if ($Display -eq 'thismachine') { $Display = 'local' }
+    if ($Action -notin @('control', 'wake', 'lock', 'restart', 'status')) {
+        throw "Unknown action '$Action'. Run pixelremotecontrol --help."
+    }
+    if ($Display -notin @('local', 'asml')) {
+        throw "Unknown display '$Display'. Use local or asml."
+    }
+    if ($DeviceId -notin @('pixel8', 'pixel_8', 'pixel-8', '127.0.0.1:15555')) {
+        throw "Unknown device '$DeviceId'. This relay currently has one registered device: pixel8 (Pixel_8)."
+    }
+    if ($CentralUser -notmatch '^[A-Za-z0-9._-]+$') { throw 'CentralUser contains invalid SSH username characters.' }
+    if ($CentralHost -notmatch '^[A-Za-z0-9.:-]+$') { throw 'CentralHost contains invalid SSH host characters.' }
+    if ($AdbForwardPort -eq $VideoPort) { throw 'AdbForwardPort and VideoPort must differ.' }
+
+    $ssh = (Get-Command ssh.exe -CommandType Application -ErrorAction Stop | Select-Object -First 1).Source
+    $destination = "$CentralUser@$CentralHost"
+
+    if ($Action -ne 'control') {
+        $remoteArgs = @('-T', '-p', [string]$SshPort, $destination, "pixelctl.cmd $Action")
+        $remote = Start-Process -FilePath $ssh -ArgumentList $remoteArgs -NoNewWindow -PassThru -Wait
+        exit $remote.ExitCode
+    }
+
+    if ($Display -eq 'asml') {
+        if ($env:COMPUTERNAME -ine 'ASML' -or -not [Environment]::UserInteractive) {
+            throw 'ASML screen mode needs an interactive desktop login on ASML. Use "control local pixel8" here, or open an ASML desktop through Remote Desktop.'
+        }
+        $pixelctl = Join-Path $env:USERPROFILE 'pixelctl.cmd'
+        if (-not (Test-Path -LiteralPath $pixelctl -PathType Leaf)) {
+            throw "pixelctl.cmd was not found in $env:USERPROFILE."
+        }
+        & $pixelctl view
+        exit $LASTEXITCODE
+    }
+
+    $scrcpy = Resolve-Program -Name 'scrcpy.exe' -ExplicitPath $ScrcpyPath
+    $adb = Resolve-Program -Name 'adb.exe' -ExplicitPath $AdbPath -SiblingPath (Join-Path (Split-Path -Parent $scrcpy) 'adb.exe')
+    Test-PortFree -Port $AdbForwardPort
+    Test-PortFree -Port $VideoPort
+
+    $previousAdbSocket = $env:ADB_SERVER_SOCKET
+    $previousAdb = $env:ADB
+    $sshProcess = $null
+    try {
+        $sshArgs = @(
+            '-T', '-o', 'ExitOnForwardFailure=yes', '-o', 'ServerAliveInterval=15',
+            '-o', 'ServerAliveCountMax=3', '-p', [string]$SshPort,
+            '-L', "127.0.0.1:${AdbForwardPort}:127.0.0.1:5039",
+            '-L', "127.0.0.1:${VideoPort}:127.0.0.1:${VideoPort}",
+            $destination, 'pixelctl.cmd serve'
+        )
+        Write-Host "Opening SSH to $destination. Complete any host key or password prompt in this window."
+        $sshProcess = Start-Process -FilePath $ssh -ArgumentList $sshArgs -NoNewWindow -PassThru
+
+        $tunnelReady = $false
+        for ($attempt = 0; $attempt -lt 600; $attempt++) {
+            if ($sshProcess.HasExited) { throw "SSH exited with code $($sshProcess.ExitCode). Check the address, login, host key, and password." }
+            if (Test-PortOpen -Port $AdbForwardPort) { $tunnelReady = $true; break }
+            Start-Sleep -Milliseconds 200
+        }
+        if (-not $tunnelReady) { throw 'SSH forwarding did not open within two minutes.' }
+
+        $env:ADB_SERVER_SOCKET = "tcp:127.0.0.1:$AdbForwardPort"
+        $env:ADB = $adb
+        $serial = '127.0.0.1:15555'
+        $deviceReady = $false
+        $lastMessage = ''
+        for ($attempt = 0; $attempt -lt 60; $attempt++) {
+            if ($sshProcess.HasExited) { throw "SSH ended while waiting for the Pixel (exit $($sshProcess.ExitCode))." }
+            $connect = Invoke-Adb -Program $adb -Arguments @('connect', $serial)
+            $lastMessage = ($connect.Output -join ' ')
+            if ($connect.ExitCode -eq 0) {
+                $devices = Invoke-Adb -Program $adb -Arguments @('devices', '-l')
+                if ($devices.ExitCode -eq 0 -and (($devices.Output -join "`n") -match '(?m)^127\.0\.0\.1:15555\s+device\b')) {
+                    $deviceReady = $true
+                    break
+                }
+                $lastMessage = ($devices.Output -join ' ')
+            }
+            Start-Sleep -Seconds 1
+        }
+        if (-not $deviceReady) {
+            throw "The Pixel did not become available through ASML. Ask the holder to run 'pixelremotecontrol startservice pixel8 asml' in Termux. $lastMessage"
+        }
+
+        Write-Host 'Pixel connected. Opening screen control; close the scrcpy window to end this session.'
+        $scrcpyArgs = @('--force-adb-forward', "--port=$VideoPort", '--serial', $serial)
+        if ($TimeLimitSeconds -gt 0) { $scrcpyArgs += "--time-limit=$TimeLimitSeconds" }
+        $oldPreference = $ErrorActionPreference
+        $ErrorActionPreference = 'Continue'
+        try {
+            & $scrcpy @scrcpyArgs
+            $scrcpyExit = $LASTEXITCODE
+        } finally { $ErrorActionPreference = $oldPreference }
+        if ($scrcpyExit -ne 0) { throw "scrcpy exited with code $scrcpyExit." }
+    } finally {
+        $env:ADB_SERVER_SOCKET = $previousAdbSocket
+        $env:ADB = $previousAdb
+        if ($sshProcess -and -not $sshProcess.HasExited) {
+            Stop-Process -Id $sshProcess.Id -Force -ErrorAction SilentlyContinue
+        }
+    }
+} catch {
+    [Console]::Error.WriteLine("pixelremotecontrol: $($_.Exception.Message)")
+    exit 1
+}