The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
import crypto from 'node:crypto'
import zlib from 'node:zlib'
import { resolveReadyTimeoutMs } from './remote-lifecycle'
import { WINDOWS_CHECKOUT_LOCK_PS, WINDOWS_MARKER_JUDGE_PS } from './remote-update-marker-programs'
import { assertBootstrapNotSuperseded, redactSecrets, SSH_ERROR } from './ssh-connection'
import { WINDOWS_NO_REPARSE_PS, windowsHelperArgv } from './windows-runtime-command'
const LOCKFILE_SCHEMA_VERSION = 2
const PROTOCOL_VERSION = 1
const READY_RE = /^HERMES_(?:BACKEND|DASHBOARD)_READY port=(\d+)/gm
const READY_POLL_INTERVAL_MS = 750
function psLiteral(value) {
return `'${String(value).replace(/'/g, "''")}'`
}
function encodedPowerShell(script) {
return Buffer.from(script, 'utf16le').toString('base64')
}
function powerShellCommand(script) {
return `powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -EncodedCommand ${encodedPowerShell(script)}`
}
// Windows OpenSSH may serialize PowerShell's progress stream as
// "#< CLIXML <Objs ...>...</Objs>" blocks into the captured stdout of ANY
// PowerShell exec on the connection (module auto-load / Add-Type cold-start
// racing the read) — not just the platform probe. Every stdout-parsing call
// shares this normalizer: strip a leading BOM, drop every CLIXML block
// (before, after, or on the same line as the payload), and keep only the
// meaningful lines.
function stripPowerShellNoise(stdout) {
return String(stdout || '')
.replace(/^\uFEFF/, '')
.replace(/#< CLIXML[\s\S]*?<\/Objs>/g, '')
.split(/\r?\n/)
.filter(line => line.trim() && !line.trimStart().startsWith('#< CLIXML'))
}
// Long scripts travel inside a self-contained -EncodedCommand, never on stdin:
// Windows OpenSSH does not reliably deliver a stdin payload and its end of input
// to the remote PowerShell, which then blocks past the exec timeout and outlives
// the session. Deflate keeps the command under cmd.exe's 8191-char limit; the
// bytes are packed 15 bits per BMP character, skipping U+2000..U+20FF, where
// PowerShell reads U+2018..U+201B as single quotes.
function compressedPowerShellBootstrap(script) {
const deflated = zlib.deflateRawSync(Buffer.from(script, 'utf8'), { level: 9 })
let chars = ''
let bitBuf = 0
let bitCount = 0
for (const byte of deflated) {
bitBuf |= byte << bitCount
bitCount += 8
while (bitCount >= 15) {
const value = bitBuf & 0x7fff
chars += String.fromCharCode((value < 0x1f00 ? 0x0100 : 0x0200) + value)
bitBuf >>>= 15
bitCount -= 15
}
}
if (bitCount > 0) {
const value = bitBuf & 0x7fff
chars += String.fromCharCode((value < 0x1f00 ? 0x0100 : 0x0200) + value)
}
return `$ProgressPreference="SilentlyContinue";[Console]::OutputEncoding=[Text.UTF8Encoding]::new($false);$m=[IO.MemoryStream]::new();$b=0;$n=0;foreach($c in [char[]]'${chars}'){$v=[int]$c;$v-=if($v-lt8192){256}else{512};$b=$b-bor($v-shl$n);$n+=15;while($n-ge8){$m.WriteByte($b-band255);$b=$b-shr8;$n-=8}};$m.Position=0;& ([ScriptBlock]::Create([IO.StreamReader]::new([IO.Compression.DeflateStream]::new($m,[IO.Compression.CompressionMode]::Decompress),[Text.Encoding]::UTF8).ReadToEnd()))`
}
function compressedPowerShellCommand(script) {
return powerShellCommand(compressedPowerShellBootstrap(script))
}
function decodePowerShellCommand(command) {
const encoded = String(command || '').match(/-EncodedCommand\s+([^\s]+)$/)?.[1]
if (!encoded) {
return ''
}
const outer = Buffer.from(encoded, 'base64').toString('utf16le')
const packed = outer.match(/foreach\(\$c in \[char\[\]\]'([^']+)'\)\{\$v=\[int\]\$c;/)?.[1]
if (!packed) {
return outer
}
const deflated: number[] = []
let bitBuf = 0
let bitCount = 0
for (let index = 0; index < packed.length; index += 1) {
const code = packed.charCodeAt(index)
bitBuf |= (code - (code < 0x2000 ? 0x0100 : 0x0200)) << bitCount
bitCount += 15
while (bitCount >= 8) {
deflated.push(bitBuf & 0xff)
bitBuf >>>= 8
bitCount -= 8
}
}
return zlib.inflateRawSync(Buffer.from(deflated)).toString('utf8')
}
async function probeWindowsFiles(ssh, explicitHermesPath = '') {
const explicit = psLiteral(explicitHermesPath)
const script = [
// Module auto-load / cold-start progress records get serialized by Windows
// OpenSSH as "#< CLIXML <Objs S=\"progress\">..." into the same stdout the
// probe parses; silence the progress stream before anything can emit it.
'$ProgressPreference="SilentlyContinue"',
'$ErrorActionPreference="Stop"',
'function Assert-NoReparse([string]$candidate,[bool]$allowMissing=$false){',
'if([string]::IsNullOrWhiteSpace($candidate)){return}',
'$current=[IO.Path]::GetFullPath($candidate);$first=$true',
'while($true){',
'try{$item=Get-Item -LiteralPath $current -Force -ErrorAction Stop}catch [Management.Automation.ItemNotFoundException]{if(-not $allowMissing -and $first){throw "Path was not found: $candidate"};$parent=[IO.Path]::GetDirectoryName($current);if(-not $parent -or $parent -eq $current){break};$current=$parent;$first=$false;continue}',
'if(($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0){throw "Path contains a link or reparse point: $current"}',
'$parent=[IO.Path]::GetDirectoryName($current);if(-not $parent -or $parent -eq $current){break};$current=$parent;$first=$false',
'}',
'}',
`$explicit=${explicit}`,
'if($explicit){Assert-NoReparse $explicit $false;$explicitPython=[IO.Path]::Combine([IO.Path]::GetDirectoryName($explicit), "python.exe");Assert-NoReparse $explicitPython $true}',
// HERMES_HOME is only trusted when it names a directory on the REMOTE: a stale User-scope
// value (older install.ps1 persisted one) or a client path leaked over SSH otherwise fails
// assertSafeRemoteHome as "Unsafe remote Hermes home" (#118988).
'$hermesHome=$env:HERMES_HOME',
'if(-not $hermesHome -or -not (Test-Path -LiteralPath $hermesHome -PathType Container)){$hermesHome=Join-Path $env:LOCALAPPDATA "hermes"}',
'Assert-NoReparse $hermesHome $true',
'$candidate=[IO.Path]::Combine($hermesHome, "hermes-agent\\venv\\Scripts\\hermes.exe")',
'$candidatePython=[IO.Path]::Combine([IO.Path]::GetDirectoryName($candidate), "python.exe")',
'Assert-NoReparse $candidate $true',
'Assert-NoReparse $candidatePython $true',
'$profileCandidate=[IO.Path]::Combine($HOME, "hermes-agent\\.venv\\Scripts\\hermes.exe")',
'$profileCandidatePython=[IO.Path]::Combine([IO.Path]::GetDirectoryName($profileCandidate), "python.exe")',
'Assert-NoReparse $profileCandidate $true',
'Assert-NoReparse $profileCandidatePython $true',
'$fallbackHomeCandidate=Join-Path $hermesHome "hermes-agent\\venv\\Scripts\\hermes.exe"',
'$fallbackProfileCandidate=Join-Path $HOME "hermes-agent\\.venv\\Scripts\\hermes.exe"',
'$candidates=@()',
'if($explicit){$candidates+=$explicit}',
// A bare `hermes` resolves through PATHEXT, so a published hermes.cmd counts as well as hermes.exe.
'$cmd=@(Get-Command hermes -CommandType Application -ErrorAction SilentlyContinue)|Select-Object -First 1',
'if($cmd){Assert-NoReparse $cmd.Source $true;$cmdPython=[IO.Path]::Combine([IO.Path]::GetDirectoryName($cmd.Source), "python.exe");Assert-NoReparse $cmdPython $true;$candidates+=$cmd.Source}',
// The installer's launchers, for an SSH session whose PATH lacks the user PATH entry.
'$candidates+=Join-Path $hermesHome "bin\\hermes.exe"',
'$candidates+=Join-Path $hermesHome "bin\\hermes.cmd"',
'$candidates+=$fallbackHomeCandidate',
'$candidates+=$fallbackProfileCandidate',
'$hermes=$null',
'foreach($candidate in $candidates){Assert-NoReparse $candidate $true;$candidatePython=[IO.Path]::Combine([IO.Path]::GetDirectoryName($candidate), "python.exe");Assert-NoReparse $candidatePython $true;try{$item=Get-Item -LiteralPath $candidate -Force -ErrorAction Stop;if(($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0 -and -not $item.PSIsContainer){$pair=Test-Path -LiteralPath $candidatePython -PathType Leaf;if($pair -or (Split-Path -Leaf (Split-Path -Parent $candidate)) -ieq "bin"){$hermes=$item.FullName;break}}}catch [Management.Automation.ItemNotFoundException]{continue}}',
'if(-not $hermes){throw "Hermes is not installed on the remote Windows host."}',
'Assert-NoReparse $hermes $false',
'if($explicit -and $hermes -ne $explicit){throw "The configured Hermes path is not an executable file."}',
'$python=[IO.Path]::Combine([IO.Path]::GetDirectoryName($hermes), "python.exe")',
'if(Test-Path -LiteralPath $python -PathType Leaf){Assert-NoReparse $python $false}else{$python=""}',
'[ordered]@{os="Windows";arch=$env:PROCESSOR_ARCHITECTURE;hermesHome=$hermesHome;hermesPath=$hermes;launcherPath=$hermes;python=$python}|ConvertTo-Json -Compress'
].join('\r\n')
// Windows OpenSSH may serialize PowerShell's progress stream as
// "#< CLIXML <Objs ...>...</Objs>" blocks into the same stdout the
// probe parses, ahead of, after, or on the same line as the probe JSON
// (module auto-load racing the exec read). stripPowerShellNoise drops every
// block; the JSON is the last meaningful line.
const lines = stripPowerShellNoise(await ssh.exec(compressedPowerShellCommand(script)))
const parsed = JSON.parse(lines[lines.length - 1] || 'null')
if (!parsed?.os || !parsed?.arch) {
throw new Error(
`Windows probe did not return the expected platform JSON: ${String(lines[lines.length - 1] ?? '').slice(0, 200)}`
)
}
return parsed
}
async function probeWindowsRemote(ssh, explicitHermesPath = '') {
const parsed = await probeWindowsFiles(ssh, explicitHermesPath)
// Resolve only after the OS-only marker gate: never import a changing checkout.
if (parsed.launcherPath) {
await assertWindowsRemoteInstallUpdateClear(ssh, parsed.hermesHome)
return resolveWindowsLauncher(ssh, parsed)
}
return parsed
}
async function resolveWindowsLauncher(ssh: any, runtime: any) {
const script = [
'$ProgressPreference="SilentlyContinue"',
'$ErrorActionPreference="Stop"',
WINDOWS_NO_REPARSE_PS,
`Assert-NoReparse ${psLiteral(runtime.hermesPath)} $false`,
`$lines=@(& ${psLiteral(runtime.hermesPath)} '--print-runtime-command');$code=$LASTEXITCODE`,
'if($code -ne 0){throw "The Hermes launcher does not support --print-runtime-command; refresh the Windows installation launcher."}',
'$command=$lines[-1]|ConvertFrom-Json',
'if($command -isnot [array] -or $command.Count -lt 2 -or -not [IO.Path]::IsPathRooted([string]$command[0])){throw "Invalid Hermes runtime command"}',
'foreach($part in $command){if($part -isnot [string] -or $part.Contains([char]0)){throw "Invalid Hermes runtime argument"}}',
'Assert-NoReparse ([string]$command[0]) $false',
'[ordered]@{python=[string]$command[0];runtimeCommand=@($command)}|ConvertTo-Json -Depth 5 -Compress'
].join('\r\n')
let resolved
try {
const output = await ssh.exec(compressedPowerShellCommand(script))
resolved = JSON.parse(stripPowerShellNoise(output).pop() || 'null')
if (!Array.isArray(resolved?.runtimeCommand) || !resolved.runtimeCommand.every(part => typeof part === 'string' && !part.includes('\0')) || typeof resolved.python !== 'string' || !/^[a-z]:[\\/]/i.test(resolved.python)) {
throw new Error('Invalid Windows launcher runtime response.')
}
} catch (cause: any) {
if (TRANSPORT_KINDS.has(cause?.kind)) {throw cause}
const error: any = new Error('Refresh the remote Windows Hermes launcher: its boot-selecting runtime could not be resolved.')
error.kind = 'update-required'
error.cause = cause
throw error
}
return { ...runtime, ...resolved }
}
// The checkouts whose update lock guards a dead marker (update_lock._reclaim_dead):
// the installer's `<install root>\hermes-agent` and the checkout of the runtime
// python (`<root>\venv\Scripts\python.exe`). Defines $checkoutRoots; needs $installRoot.
function windowsCheckoutRootsScript(python = '') {
const runtimeRoot = python
? `[IO.Path]::GetDirectoryName([IO.Path]::GetDirectoryName([IO.Path]::GetDirectoryName(${psLiteral(python)})))`
: '$null'
return `$checkoutRoots=@([IO.Path]::Combine($installRoot,"hermes-agent"),${runtimeRoot})`
}
// Marker-gate probe script: reads the install-wide update marker fail-closed
// (missing -> CLEAR, unreadable/malformed -> UNCERTAIN) without following
// symlinks on any path level, including the marker file itself.
function windowsUpdateMarkerProbeScript(hermesHome, python = '') {
const script = [
'$ProgressPreference="SilentlyContinue"',
'$ErrorActionPreference="Stop"',
`Add-Type -TypeDefinition @'
using System;
using System.IO;
using System.Runtime.InteropServices;
using Microsoft.Win32.SafeHandles;
public static class HermesMarkerNoFollow {
[DllImport("kernel32.dll", CharSet=CharSet.Unicode, SetLastError=true)]
private static extern SafeFileHandle CreateFile(string name, uint access, uint share, IntPtr security, uint creation, uint flags, IntPtr template);
public static FileStream OpenRead(string name) {
var handle=CreateFile(name, 0x80000000, 0x00000007, IntPtr.Zero, 3, 0x00200000, IntPtr.Zero);
if(handle.IsInvalid) Marshal.ThrowExceptionForHR(Marshal.GetHRForLastWin32Error());
return new FileStream(handle, FileAccess.Read);
}
}
'@
`,
WINDOWS_MARKER_JUDGE_PS,
WINDOWS_CHECKOUT_LOCK_PS,
'function Assert-NoReparse([string]$candidate,[bool]$allowMissing=$false){',
'if([string]::IsNullOrWhiteSpace($candidate)){return}',
'$current=[IO.Path]::GetFullPath($candidate);$first=$true',
'while($true){',
'try{$item=Get-Item -LiteralPath $current -Force -ErrorAction Stop}catch [Management.Automation.ItemNotFoundException]{if(-not $allowMissing -and $first){throw "Path was not found: $candidate"};$parent=[IO.Path]::GetDirectoryName($current);if(-not $parent -or $parent -eq $current){break};$current=$parent;$first=$false;continue}',
'if(($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0){throw "Path contains a link or reparse point: $current"}',
'$parent=[IO.Path]::GetDirectoryName($current);if(-not $parent -or $parent -eq $current){break};$current=$parent;$first=$false',
'}',
'}',
`$hermesHome=${psLiteral(hermesHome)}`,
'$installRoot=$hermesHome',
'$parent=Split-Path -Parent $hermesHome',
'if((Split-Path -Leaf $parent) -ieq "profiles"){$installRoot=Split-Path -Parent $parent}',
'$marker=Join-Path $installRoot ".hermes-update-in-progress"',
windowsCheckoutRootsScript(python),
'$result="UNCERTAIN"',
'$stream=$null;$memory=$null',
'try{',
'Assert-NoReparse $marker $true',
'if(-not (Test-Path -LiteralPath $marker -PathType Leaf)){$result="CLEAR"}else{$stream=[HermesMarkerNoFollow]::OpenRead($marker)',
'Assert-NoReparse $marker $false',
'$memory=New-Object IO.MemoryStream;$stream.CopyTo($memory);$bytes=$memory.ToArray()',
'if($bytes.Length -le 4096){',
'$utf8=[Text.UTF8Encoding]::new($false,$true)',
'$text=$utf8.GetString($bytes)',
'$result=Get-MarkerVerdict $text',
'if($result -eq "CLEAR" -and (Test-CheckoutLockHeld $checkoutRoots)){$result="HELD"}',
'}',
'}}catch [IO.FileNotFoundException]{$result="CLEAR"}catch{$result="UNCERTAIN"}finally{if($memory){$memory.Dispose()};if($stream){$stream.Dispose()}}',
'Write-Output $result'
].join('\r\n')
return script
}
/**
* Fail-closed install marker gate for a fresh/relaunched Desktop process.
* This uses only PowerShell/.NET and therefore never imports the remote
* checkout while an updater may be replacing it.
*/
async function assertWindowsRemoteInstallUpdateClear(ssh, hermesHome, python = '') {
let observation = ''
try {
// Same stdout channel as the probe: a CLIXML progress block after the
// final `Write-Output $result` would otherwise win the .pop() and turn a
// CLEAR gate into a fail-closed 'update-in-progress' verdict.
observation =
stripPowerShellNoise(
await ssh.exec(compressedPowerShellCommand(windowsUpdateMarkerProbeScript(hermesHome, python)))
).pop() || ''
} catch (cause) {
const error: any = new Error('Could not prove that the remote Hermes install is clear for SSH startup.')
error.kind = 'update-in-progress'
error.cause = cause
throw error
}
if (observation === 'CLEAR') {
return
}
const live = /^LIVE:([1-9][0-9]*)$/.exec(observation)
const error: any = new Error(
live
? `Remote Hermes update process ${live[1]} is still running; SSH startup is paused.`
: observation === 'HELD'
? 'A process the remote Hermes update started still holds the install; SSH startup is paused.'
: 'The remote Hermes update marker is unreadable or malformed; refusing SSH startup.'
)
error.kind = 'update-in-progress'
throw error
}
const TRANSPORT_KINDS = new Set([
SSH_ERROR.AUTH_FAILED,
SSH_ERROR.HOST_KEY_CHANGED,
SSH_ERROR.TIMEOUT,
SSH_ERROR.UNREACHABLE
])
function powerShellErrorDetail(value) {
const raw = String(value || '')
const errors = [...raw.matchAll(/<S S="Error">([\s\S]*?)<\/S>/g)].map(match => match[1])
const detail = errors.length ? errors.join(' ') : raw
return detail
.replace(/_x([0-9a-fA-F]{4})_/g, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16)))
.replace(/</g, '<')
.replace(/>/g, '>')
.replace(/"/g, '"')
.replace(/'/g, "'")
.replace(/&/g, '&')
}
async function detectRemotePlatform(ssh, explicitHermesPath = '') {
try {
const output = (await ssh.exec('uname -s; uname -m')).trim().split('\n')
if (output[0] === 'Linux' || output[0] === 'Darwin') {
return { os: output[0], arch: output[1] || '' }
}
} catch (error: any) {
// uname failing is the expected Windows fall-through; a TRANSPORT failure
// (auth/host-key/timeout/unreachable) is not a platform verdict — surface it
// as itself instead of letting the probe chain end in 'unsupported-platform'.
if (TRANSPORT_KINDS.has(error?.kind)) {
throw error
}
}
try {
return await probeWindowsRemote(ssh, explicitHermesPath)
} catch (cause: any) {
if (TRANSPORT_KINDS.has(cause?.kind)) {
throw cause
}
const kind = cause?.kind
// detail is remote-controlled output headed for the UI: redact + strip control chars.
const detail = redactSecrets(powerShellErrorDetail(cause?.message || cause || ''))
// eslint-disable-next-line no-control-regex -- deliberately strip control chars from remote output
.replace(/[\x00-\x1f\x7f]/g, ' ')
.trim()
const error: any = new Error(
`${kind ? 'The Windows remote probe failed.' : 'The remote operating system is not supported by Desktop SSH.'}${detail ? ` (probe: ${detail.slice(0, 300)})` : ''}`
)
error.kind = kind || 'unsupported-platform'
error.cause = cause
throw error
}
}
function helperCommand(runtime, operation, args = []) {
const argv = windowsHelperArgv(runtime, operation, args)
const script = [
'$ProgressPreference="SilentlyContinue"',
'$ErrorActionPreference="Stop"',
`& ${argv.map(psLiteral).join(' ')}`,
'if($LASTEXITCODE -ne 0){exit $LASTEXITCODE}'
].join(';')
return powerShellCommand(script)
}
async function helper(ssh, runtime, operation, args = [], stdinData?) {
const output = await ssh.exec(helperCommand(runtime, operation, args), stdinData == null ? {} : { stdinData })
const lines = stripPowerShellNoise(output)
const parsed = JSON.parse(lines[lines.length - 1] || 'null')
if (parsed?.error) {
throw new Error(parsed.error)
}
return parsed
}
function atomicWindowsSpawnCommand(runtime, reservation: any = {}, payload?: string) {
const argv = windowsHelperArgv(runtime, 'spawn')
const helper = operation => windowsHelperArgv(runtime, operation)
const invokeSpawn = `${payload == null ? '' : `${psLiteral(payload)} | `}& ${argv.map(psLiteral).join(' ')}`
const script = [
'$ProgressPreference="SilentlyContinue"',
'$ErrorActionPreference="Stop"',
'$OutputEncoding=[Text.UTF8Encoding]::new($false)',
WINDOWS_MARKER_JUDGE_PS,
WINDOWS_CHECKOUT_LOCK_PS,
`$hermesHome=${psLiteral(runtime.hermesHome)}`,
'$installRoot=$hermesHome',
'$parent=Split-Path -Parent $hermesHome',
'if((Split-Path -Leaf $parent) -ieq "profiles"){$installRoot=Split-Path -Parent $parent}',
'$marker=Join-Path $installRoot ".hermes-update-in-progress"',
windowsCheckoutRootsScript(runtime.python),
// The updaters' kernel lock (A7 rule 1): `<marker>.lock` opened sharing
// nothing, like marker.ps1 Open-MarkerLock / update_lock.py, bounded 10 s.
// A dead claim is deleted inside the hold, but only while the checkout lock
// is free (a killed updater's child still holding it answers HELD); a
// live/malformed one refuses.
'$clock=[Diagnostics.Stopwatch]::StartNew();$mutex=$null',
'while(-not $mutex){try{$mutex=[IO.File]::Open($marker+".lock",[IO.FileMode]::OpenOrCreate,[IO.FileAccess]::ReadWrite,[IO.FileShare]::None)}catch{if($clock.ElapsedMilliseconds -ge 10000){throw "remote update marker lock is busy"};Start-Sleep -Milliseconds 25}}',
'try{',
' if([IO.File]::Exists($marker)){$verdict=Get-MarkerVerdict ([IO.File]::ReadAllText($marker));if($verdict -eq "CLEAR" -and (Test-CheckoutLockHeld $checkoutRoots)){$verdict="HELD"};if($verdict -ne "CLEAR"){throw "remote update marker is $verdict"};[IO.File]::Delete($marker)}',
reservation.ownershipId
? ` $existingLines=@(& ${helper('read-lock').map(psLiteral).join(' ')} ${psLiteral(reservation.ownershipId)}); $existingExit=$LASTEXITCODE; ` +
' if($existingExit -eq 0 -and $existingLines.Count -gt 0){try{$existing=$existingLines[-1]|ConvertFrom-Json}catch{$existing=$null}; ' +
'if($existing -and [int]$existing.pid -gt 0){try{$p=[Diagnostics.Process]::GetProcessById([int]$existing.pid); ' +
'if(-not $p.HasExited){[ordered]@{existing=$true}|ConvertTo-Json -Compress;exit 0}}catch{}finally{if($p){$p.Dispose()}}}; ' +
`& ${helper('remove-lock').map(psLiteral).join(' ')} ${psLiteral(reservation.ownershipId)}|Out-Null}`
: '',
reservation.ownershipId
? ` $spawnLines=@(${invokeSpawn}); $spawnExit=$LASTEXITCODE`
: ` ${invokeSpawn}`,
reservation.ownershipId
? ' if($spawnExit -ne 0){exit $spawnExit}'
: ' if($LASTEXITCODE -ne 0){exit $LASTEXITCODE}',
reservation.ownershipId
? ` $spawned=$spawnLines[-1]|ConvertFrom-Json; $lock=[ordered]@{schemaVersion=2;protocolVersion=1;ownershipId=${psLiteral(reservation.ownershipId)};spawnNonce=${psLiteral(reservation.spawnNonce)};pid=[int]$spawned.pid;creationTimeNs=[string]$spawned.creationTimeNs;port=0;profile=${psLiteral(reservation.profile)};hermesPath=${psLiteral(reservation.hermesPath)};hermesHome=${psLiteral(reservation.hermesHome)};tokenFingerprint=${psLiteral(reservation.tokenFingerprint)};startedAt=${psLiteral(reservation.startedAt)}}|ConvertTo-Json -Compress; ` +
` $lock | & ${helper('write-lock').map(psLiteral).join(' ')} ${psLiteral(reservation.ownershipId)} | Out-Null; if($LASTEXITCODE -ne 0){exit $LASTEXITCODE}; $spawnLines|Write-Output`
: '',
' if([IO.File]::Exists($marker)){throw "remote update marker claimed during backend spawn"}',
'}finally{$mutex.Dispose()}'
]
.filter(line => line !== '')
.join(';')
return compressedPowerShellCommand(script)
}
async function atomicWindowsSpawn(ssh, runtime, payload, reservation: any = {}) {
const output = await ssh.exec(atomicWindowsSpawnCommand(runtime, reservation, payload))
const lines = stripPowerShellNoise(output)
const parsed = JSON.parse(lines[lines.length - 1] || 'null')
if (parsed?.error) {
const error: any = new Error(parsed.error)
error.kind = parsed.kind || 'remote-helper-error'
throw error
}
return parsed
}
function fingerprintToken(token) {
return crypto
.createHash('sha256')
.update(String(token || ''))
.digest('hex')
.slice(0, 32)
}
function validLock(lock, ownershipId) {
// port 0 = spawn-in-progress record (written before readiness); a valid
// ownership proof for cleanup, but never reusable.
return Boolean(
lock &&
lock.schemaVersion === LOCKFILE_SCHEMA_VERSION &&
lock.protocolVersion === PROTOCOL_VERSION &&
lock.ownershipId === ownershipId &&
/^[0-9a-f]{16}$/.test(lock.spawnNonce || '') &&
Number.isInteger(lock.pid) &&
lock.pid > 0 &&
/^[0-9]{10,20}$/.test(lock.creationTimeNs || '') &&
Number.isInteger(lock.port) &&
lock.port >= 0 &&
lock.port <= 65535 &&
/^[0-9a-f]{32}$/.test(lock.tokenFingerprint || '') &&
typeof lock.hermesPath === 'string' &&
typeof lock.hermesHome === 'string'
)
}
function reusableWindowsLock(lock, state, profile, reuseToken, runtime) {
return Boolean(
state.alive &&
state.owned &&
lock.port > 0 &&
lock.profile === profile &&
reuseToken &&
lock.tokenFingerprint === fingerprintToken(reuseToken) &&
lock.hermesPath === runtime.hermesPath &&
lock.hermesHome === runtime.hermesHome
)
}
async function processState(ssh, runtime, lock) {
return helper(ssh, runtime, 'process-state', [
String(lock.pid),
String(lock.creationTimeNs),
lock.hermesPath,
lock.spawnNonce
])
}
async function cleanupOwned(ssh, runtime, ownershipId, lock) {
const attempt = async fn => {
try {
await fn()
} catch {
void 0
}
}
if (lock) {
const state = await processState(ssh, runtime, lock)
if (state.alive && state.owned) {
// Deliberately not attempt()-wrapped: a thrown terminate must abort before
// remove-lock, or a live backend is orphaned with no lock to reclaim it.
await helper(ssh, runtime, 'terminate', [
String(lock.pid),
String(lock.creationTimeNs),
lock.hermesPath,
lock.spawnNonce
])
}
if (lock.spawnNonce) {
await attempt(() => helper(ssh, runtime, 'remove-token', [ownershipId, lock.spawnNonce]))
await attempt(() => helper(ssh, runtime, 'remove-log', [ownershipId, lock.spawnNonce]))
}
}
await attempt(() => helper(ssh, runtime, 'remove-lock', [ownershipId]))
}
function windowsLockMatchesManagedUpdateScope(lock, expected) {
return Boolean(
lock &&
expected &&
lock.ownershipId === expected.ownershipId &&
lock.pid === expected.pid &&
lock.spawnNonce === expected.spawnNonce &&
lock.creationTimeNs === expected.creationTimeNs &&
lock.profile === expected.profile &&
lock.hermesPath === expected.hermesPath &&
lock.hermesHome === expected.hermesHome
)
}
/**
* Terminate a Windows serve only after the persisted ownership record and the
* kernel creation-time proof still match the exact scope Desktop connected.
* Leave the record in place for the post-update reconnect to reclaim; this
* prevents a delayed cleanup from deleting a replacement owner's record.
*/
async function terminateOwnedWindowsDashboardForUpdate(ssh, runtime, expected) {
let lock = await helper(ssh, runtime, 'read-lock', [expected?.ownershipId || ''])
if (!validLock(lock, expected?.ownershipId) || !windowsLockMatchesManagedUpdateScope(lock, expected)) {
const error: any = new Error('The remote Windows ownership record changed before the managed update.')
error.kind = 'ownership-changed'
throw error
}
let state = await processState(ssh, runtime, lock)
if (state.indeterminate) {
const error: any = new Error('Could not prove the remote Windows process identity for the managed update.')
error.kind = 'transient-transport-error'
throw error
}
if (!state.alive) {
return { pid: lock.pid, terminated: false, alreadyStopped: true }
}
if (!state.owned) {
const error: any = new Error('Refusing to terminate a remote Windows process whose ownership is unproven.')
error.kind = 'foreign-backend'
throw error
}
// Fence the proof against a record replacement before signalling.
lock = await helper(ssh, runtime, 'read-lock', [expected.ownershipId])
if (!validLock(lock, expected.ownershipId) || !windowsLockMatchesManagedUpdateScope(lock, expected)) {
const error: any = new Error('The remote Windows ownership record changed during process verification.')
error.kind = 'ownership-changed'
throw error
}
state = await processState(ssh, runtime, lock)
if (state.indeterminate || !state.alive || !state.owned) {
const error: any = new Error('The remote Windows process identity changed during managed update drain.')
error.kind = state.indeterminate ? 'transient-transport-error' : 'ownership-changed'
throw error
}
await helper(ssh, runtime, 'terminate', [
String(lock.pid),
String(lock.creationTimeNs),
lock.hermesPath,
lock.spawnNonce
])
return { pid: lock.pid, terminated: true, alreadyStopped: false }
}
async function waitReady(ssh, runtime, ownershipId, lock, timeoutMs, signal) {
const deadline = Date.now() + timeoutMs
while (Date.now() < deadline) {
assertBootstrapNotSuperseded(signal)
let state
try {
state = await processState(ssh, runtime, lock)
} catch {
await new Promise(resolve => setTimeout(resolve, READY_POLL_INTERVAL_MS))
continue
}
if (!state.indeterminate && (!state.alive || !state.owned)) {
let detail = ''
try {
detail = (await helper(ssh, runtime, 'read-log', [ownershipId, lock.spawnNonce]))?.content || ''
} catch {
void 0
}
const error: any = new Error(
`Remote Windows backend exited before announcing its port. state=${JSON.stringify(state)} ${detail.slice(-2000)}`
)
error.kind = 'spawn-failed'
throw error
}
let content = ''
try {
content = (await helper(ssh, runtime, 'read-log', [ownershipId, lock.spawnNonce]))?.content || ''
} catch {
void 0
}
let port
for (const match of content.matchAll(READY_RE)) {
port = Number(match[1])
}
if (port) {
return port
}
await new Promise(resolve => setTimeout(resolve, READY_POLL_INTERVAL_MS))
}
const error: any = new Error(`Timed out waiting for the remote Windows backend (${timeoutMs}ms).`)
error.kind = 'ready-timeout'
throw error
}
async function waitForWindowsSpawnCompletion(ssh, runtime, ownershipId, timeoutMs) {
const deadline = Date.now() + timeoutMs
while (Date.now() < deadline) {
const lock = await helper(ssh, runtime, 'read-lock', [ownershipId])
if (!lock) {
return false
}
if (validLock(lock, ownershipId) && lock.port > 0) {
return true
}
await new Promise(resolve => setTimeout(resolve, READY_POLL_INTERVAL_MS))
}
const error: any = new Error('Timed out waiting for the concurrent Windows SSH connection to publish its backend.')
error.kind = 'spawn-failed'
throw error
}
// A backend started through the launcher's boot-selecting runtime is recognised as
// ours only by a helper that advertises it; an older one would orphan or refuse it.
function windowsHelperOwnsRuntime(runtime, inspection) {
return !runtime.runtimeCommand || inspection?.runtimeBootstrapOwnership === 1
}
// Test answers with Connect's own capability bar.
async function inspectWindowsSupport(ssh, runtime) {
const inspection = await helper(ssh, runtime, 'inspect', [runtime.hermesPath])
return { version: inspection.version, supported: inspection.supported && windowsHelperOwnsRuntime(runtime, inspection) }
}
async function connectWindowsRemote(deps) {
const {
ssh,
ownershipId,
profile = '',
remoteHermesPath = '',
reuseToken = '',
signal,
pickLocalPort,
forward,
cancelForward,
waitForHermes,
probeReuseProof,
rememberLog = () => {},
readyTimeoutMs = resolveReadyTimeoutMs()
} = deps
assertBootstrapNotSuperseded(signal)
const runtime = await probeWindowsRemote(ssh, remoteHermesPath)
await assertWindowsRemoteInstallUpdateClear(ssh, runtime.hermesHome, runtime.python)
const inspection = await helper(ssh, runtime, 'inspect', [runtime.hermesPath])
if (!windowsHelperOwnsRuntime(runtime, inspection)) {
const error: any = new Error('The remote Windows SSH helper must be updated with boot-selecting runtime ownership support before connecting.')
error.kind = 'update-required'
throw error
}
if (!inspection.supported) {
const error: any = new Error('Update Hermes on the remote Windows host before connecting with Desktop SSH.')
error.kind = 'update-required'
throw error
}
runtime.hermesPath = inspection.path
const hermesVersion = inspection.version || ''
rememberLog(`[ssh-lifecycle] remote platform Windows/${runtime.arch}`)
rememberLog(`[ssh-lifecycle] located hermes at ${runtime.hermesPath}`)
await assertWindowsRemoteInstallUpdateClear(ssh, runtime.hermesHome, runtime.python)
const lock = await helper(ssh, runtime, 'read-lock', [ownershipId])
if (validLock(lock, ownershipId)) {
const state = await processState(ssh, runtime, lock)
if (state.indeterminate) {
const error: any = new Error('Could not determine the state of the existing remote backend.')
error.kind = 'transient-transport-error'
throw error
}
const reusable = reusableWindowsLock(lock, state, profile, reuseToken, runtime)
if (reusable) {
await assertWindowsRemoteInstallUpdateClear(ssh, runtime.hermesHome, runtime.python)
const localPort = await pickLocalPort()
await forward(localPort, lock.port)
try {
const baseUrl = `http://127.0.0.1:${localPort}`
const classification = await probeReuseProof(baseUrl, reuseToken, lock.spawnNonce)
if (classification === 'authenticated-ok') {
return {
baseUrl,
token: reuseToken,
remotePort: lock.port,
localPort,
pid: lock.pid,
reused: true,
platform: { os: 'Windows', arch: runtime.arch },
hermesPath: runtime.hermesPath,
hermesVersion,
ownershipId,
spawnNonce: lock.spawnNonce,
creationTimeNs: lock.creationTimeNs,
hermesHome: runtime.hermesHome,
pythonPath: runtime.python
}
}
if (classification !== 'authenticated-stale') {
throw new Error('Invalid SSH reuse classification.')
}
await cancelForward(localPort, lock.port)
await assertWindowsRemoteInstallUpdateClear(ssh, runtime.hermesHome, runtime.python)
await cleanupOwned(ssh, runtime, ownershipId, lock)
} catch (error) {
await cancelForward(localPort, lock.port)
throw error
}
} else {
await assertWindowsRemoteInstallUpdateClear(ssh, runtime.hermesHome, runtime.python)
await cleanupOwned(ssh, runtime, ownershipId, lock)
}
} else if (lock) {
await assertWindowsRemoteInstallUpdateClear(ssh, runtime.hermesHome, runtime.python)
await helper(ssh, runtime, 'remove-lock', [ownershipId])
}
assertBootstrapNotSuperseded(signal)
await assertWindowsRemoteInstallUpdateClear(ssh, runtime.hermesHome, runtime.python)
const token = crypto.randomBytes(32).toString('hex')
const spawnNonce = crypto.randomBytes(8).toString('hex')
await helper(ssh, runtime, 'upload-token', [ownershipId, spawnNonce], token)
const startedAt = new Date().toISOString()
const tokenFingerprint = fingerprintToken(token)
let spawned
try {
await assertWindowsRemoteInstallUpdateClear(ssh, runtime.hermesHome, runtime.python)
spawned = await atomicWindowsSpawn(
ssh,
runtime,
JSON.stringify({ ownershipId, spawnNonce, profile, hermesPath: runtime.hermesPath }),
{
ownershipId,
spawnNonce,
profile,
hermesPath: runtime.hermesPath,
hermesHome: runtime.hermesHome,
tokenFingerprint,
startedAt
}
)
} catch (error) {
await helper(ssh, runtime, 'remove-token', [ownershipId, spawnNonce])
throw error
}
if (spawned.existing) {
await helper(ssh, runtime, 'remove-token', [ownershipId, spawnNonce])
if (!reuseToken) {
const error: any = new Error(
'Another SSH connection owns this remote dashboard; a session token is required to reuse it.'
)
error.kind = 'remote-ownership-contended'
throw error
}
const published = await waitForWindowsSpawnCompletion(ssh, runtime, ownershipId, readyTimeoutMs)
if (!published) {
return connectWindowsRemote({ ...deps, reuseToken })
}
return connectWindowsRemote({ ...deps, reuseToken })
}
const owned = {
schemaVersion: LOCKFILE_SCHEMA_VERSION,
protocolVersion: PROTOCOL_VERSION,
ownershipId,
spawnNonce,
pid: spawned.pid,
creationTimeNs: spawned.creationTimeNs,
port: 0,
profile,
hermesPath: runtime.hermesPath,
hermesHome: runtime.hermesHome,
tokenFingerprint,
startedAt
}
let localPort = 0
let remotePort = 0
try {
// Write the ownership record IMMEDIATELY (port=0): if this attempt is
// superseded before readiness and cleanup cannot reach the box, the next
// connect still finds the lock and reaps the process by exact ownership.
// Inside the try: if this write itself fails, the catch still kills the
// just-spawned process via the in-memory record.
await helper(ssh, runtime, 'write-lock', [ownershipId], JSON.stringify(owned))
remotePort = await waitReady(ssh, runtime, ownershipId, owned, readyTimeoutMs, signal)
localPort = await pickLocalPort()
await forward(localPort, remotePort)
const baseUrl = `http://127.0.0.1:${localPort}`
await waitForHermes(baseUrl, token)
assertBootstrapNotSuperseded(signal)
await helper(ssh, runtime, 'write-lock', [ownershipId], JSON.stringify({ ...owned, port: remotePort }))
return {
baseUrl,
token,
remotePort,
localPort,
pid: spawned.pid,
reused: false,
platform: { os: 'Windows', arch: runtime.arch },
hermesPath: runtime.hermesPath,
hermesVersion,
ownershipId,
spawnNonce,
creationTimeNs: spawned.creationTimeNs,
hermesHome: runtime.hermesHome,
pythonPath: runtime.python
}
} catch (error) {
if (localPort && remotePort) {
await cancelForward(localPort, remotePort)
}
await cleanupOwned(ssh, runtime, ownershipId, owned)
throw error
}
}
function buildWindowsInteractiveCommand(remoteCwd = '') {
const cwd = String(remoteCwd || '').trim()
const script = ['$ErrorActionPreference="Stop"']
if (cwd) {
script.push(
`if(Test-Path -LiteralPath ${psLiteral(cwd)} -PathType Container){Set-Location -LiteralPath ${psLiteral(cwd)}}`
)
}
script.push('$host.UI.RawUI.WindowTitle="Hermes SSH"', 'powershell.exe -NoLogo')
return powerShellCommand(script.join(';'))
}
export {
assertWindowsRemoteInstallUpdateClear,
atomicWindowsSpawn,
atomicWindowsSpawnCommand,
buildWindowsInteractiveCommand,
compressedPowerShellCommand,
connectWindowsRemote,
decodePowerShellCommand,
detectRemotePlatform,
encodedPowerShell,
helper,
helperCommand,
inspectWindowsSupport,
powerShellCommand,
probeWindowsFiles,
probeWindowsRemote,
psLiteral,
reusableWindowsLock,
stripPowerShellNoise,
terminateOwnedWindowsDashboardForUpdate,
validLock,
windowsHelperOwnsRuntime
}