fix(gates): select a character in connected graphical runs

tools/connected-render-pack-gate-common.ps1

@@ -160,6 +160,63 @@ function Restore-ConnectedRenderPackGateEnvironment {
     }
 }
 
+function New-ConnectedGraphicalSessionConfig {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory = $true)][object]$State,
+        [Parameter(Mandatory = $true)][string]$Account,
+        [string]$HostName = '127.0.0.1',
+        [ValidateRange(1, 65535)][int]$Port = 9000,
+        [ValidateRange(0, [int]::MaxValue)][int]$CharacterIndex = 0,
+        [string]$CredentialEnvironmentVariable = 'ACDREAM_TEST_PASS'
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Account)) {
+        throw 'Connected graphical session account cannot be empty.'
+    }
+    if ([string]::IsNullOrWhiteSpace($HostName)) {
+        throw 'Connected graphical session host cannot be empty.'
+    }
+    if ($CredentialEnvironmentVariable -notmatch '^[A-Za-z_][A-Za-z0-9_]*$') {
+        throw "Unsafe credential environment-variable name '$CredentialEnvironmentVariable'."
+    }
+
+    $path = Assert-ConnectedGateContainedPath $State.StateDirectory (
+        Join-Path $State.StateDirectory 'graphical-session.json')
+    if (Test-Path -LiteralPath $path) {
+        throw "Connected graphical session config already exists: '$path'."
+    }
+
+    [ordered]@{
+        version = 1
+        sessions = @([ordered]@{
+            id = 'connected-gate'
+            endpoint = [ordered]@{ host = $HostName; port = $Port }
+            account = $Account
+            character = [ordered]@{ index = $CharacterIndex }
+            credential = [ordered]@{
+                provider = 'Environment'
+                reference = $CredentialEnvironmentVariable
+            }
+        })
+    } | ConvertTo-Json -Depth 8 |
+        Set-Content -LiteralPath $path -Encoding utf8
+    return $path
+}
+
+function Remove-ConnectedGraphicalSessionConfig {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory = $true)][object]$State,
+        [Parameter(Mandatory = $true)][string]$Path
+    )
+
+    $containedPath = Assert-ConnectedGateContainedPath $State.StateDirectory $Path
+    if (Test-Path -LiteralPath $containedPath -PathType Leaf) {
+        Remove-Item -LiteralPath $containedPath -Force
+    }
+}
+
 function Get-ConnectedGateBinaryIdentity {
     [CmdletBinding()]
     param([Parameter(Mandatory = $true)][string]$Repository,

tools/run-connected-r6-soak.ps1

@@ -730,6 +730,9 @@ $renderPackGate = New-ConnectedRenderPackGateState `
     -Root $artifactDir `
     -Preset $RenderPackPreset `
     -SettingOverrides $RenderPackSettingOverrides
+$sessionConfigPath = New-ConnectedGraphicalSessionConfig `
+    -State $renderPackGate `
+    -Account $Account
 try {
 $binaryIdentity = Get-ConnectedGateBinaryIdentity `
     -Repository $Repository -Executable $exe -SkipBuild:$SkipBuild
@@ -805,6 +808,7 @@ $envDisclosure | ConvertTo-Json -Depth 4 |
 
 try {
     $process = Start-Process -FilePath $exe -WorkingDirectory $Repository `
+        -ArgumentList @('--session-config', ('"' + $sessionConfigPath + '"')) `
         -RedirectStandardOutput $stdoutLog -RedirectStandardError $stderrLog -PassThru
     Write-Marker (
         "launch pid=$($process.Id) binaryCommit=$commit sourceCommit=$sourceCommit " +
@@ -1055,7 +1059,13 @@ finally {
 }
 }
 finally {
-    Restore-ConnectedRenderPackGateEnvironment $renderPackGate
+    try {
+        Remove-ConnectedGraphicalSessionConfig `
+            -State $renderPackGate -Path $sessionConfigPath
+    }
+    finally {
+        Restore-ConnectedRenderPackGateEnvironment $renderPackGate
+    }
 }
 
 if ($failures.Count -gt 0) { exit 1 }

tools/run-connected-world-lifecycle-gate.ps1

@@ -287,6 +287,7 @@ function Invoke-Session(
 
     try {
         $client = Start-Process -FilePath $exe -WorkingDirectory $Repository `
+            -ArgumentList @('--session-config', ('"' + $sessionConfigPath + '"')) `
             -RedirectStandardOutput $stdout -RedirectStandardError $stderr -PassThru
         Wait-ForPattern $client $stdout '[UI-PROBE] UI probe script complete' $SessionTimeoutSeconds
 
@@ -558,6 +559,9 @@ $renderPackGate = New-ConnectedRenderPackGateState `
     -Root $root `
     -Preset $RenderPackPreset `
     -SettingOverrides $RenderPackSettingOverrides
+$sessionConfigPath = New-ConnectedGraphicalSessionConfig `
+    -State $renderPackGate `
+    -Account $Account
 try {
     if (@(Get-Process -Name AcDream.App -ErrorAction SilentlyContinue).Count -gt 0) {
         throw 'an AcDream.App client is already running; close it gracefully before the gate'
@@ -683,7 +687,13 @@ try {
     foreach ($warning in $warnings) { Write-Output "WARNING=$warning" }
 }
 finally {
-    Restore-ConnectedRenderPackGateEnvironment $renderPackGate
+    try {
+        Remove-ConnectedGraphicalSessionConfig `
+            -State $renderPackGate -Path $sessionConfigPath
+    }
+    finally {
+        Restore-ConnectedRenderPackGateEnvironment $renderPackGate
+    }
 }
 
 if ($failures.Count -gt 0) { exit 1 }