Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

6.9 KB
Raw Blame
# serial-check.ps1 [-Port COM3] [-Seconds 10] [-WatchOnly]: does opening the dial reset it? (E1.3, spec 1.2)
# Watch the attachment session, read the open port, then watch again. A reset must not change the session,
# end the open, or send an ESP-ROM banner. -WatchOnly opens nothing (E5 scenarios 4 and 7).
# Run as administrator with nothing else holding the port. Never print raw watch/error/device bytes.
param([string]$Port = 'COM3', [int]$Seconds = 10, [switch]$WatchOnly)
$ErrorActionPreference = 'Stop'
$ProgressPreference = 'SilentlyContinue'
$exe = Join-Path $PSScriptRoot 'harness-serial.exe'
$p = $null
$failure = 'serial check failed'

function Start-Serial([string]$Arguments) {
  $info = New-Object Diagnostics.ProcessStartInfo
  $info.FileName = $exe
  $info.Arguments = $Arguments # Only fixed keywords and a validated COM name.
  $info.UseShellExecute = $false
  $info.RedirectStandardInput = $true
  $info.RedirectStandardOutput = $true
  $info.RedirectStandardError = $true
  $info.CreateNoWindow = $true
  [Diagnostics.Process]::Start($info)
}

function Stop-Serial([Diagnostics.Process]$Child) {
  if ($null -eq $Child) { return }
  try {
    if (-not $Child.HasExited) {
      $Child.Kill()
      if (-not $Child.WaitForExit(5000)) { throw 'serial child did not stop' }
    }
  } finally { $Child.Dispose() }
}

function Get-Dial {
  $watch = $null
  try {
    $watch = Start-Serial 'watch'
    # Drain stderr concurrently; a failing helper must not fill its pipe and deadlock startup/exit.
    $errors = $watch.StandardError.ReadToEndAsync()
    $line = $watch.StandardOutput.ReadLineAsync()
    if (-not $line.Wait(5000)) { throw 'watch startup deadline exceeded' }
    $watch.StandardInput.Close()
    if (-not $watch.WaitForExit(5000)) { throw 'watch did not end at end of stdin' }
    if (-not $errors.Wait(5000)) { throw 'watch stderr deadline exceeded' }
    if ($watch.ExitCode -ne 0 -or $errors.Result.Trim()) { throw 'watch failed' }
    # Parsing and all later errors are caught below without printing the raw line or exception text.
    $state = $line.Result | ConvertFrom-Json
    $dial = @($state.ports | Where-Object { $_.path -ceq $Port })
    if ($state.console -isnot [bool] -or $dial.Count -ne 1) { throw 'watch did not list one dial' }
    if ($dial[0].session -isnot [string] -or [string]::IsNullOrWhiteSpace($dial[0].session)) {
      throw 'watch did not supply an attachment session'
    }
    [pscustomobject]@{ console = $state.console; session = $dial[0].session; serial = $dial[0].serialNumber }
  } finally { Stop-Serial $watch }
}

try {
  $failure = 'invalid input or missing harness-serial.exe; put-admin the binary first'
  if (-not (Test-Path -LiteralPath $exe -PathType Leaf)) { throw 'missing binary' }
  if ($Port -cnotmatch '^COM[1-9][0-9]{0,2}$') { throw 'invalid COM port' }
  if ($Seconds -lt 1 -or $Seconds -gt 300) { throw 'Seconds must be between 1 and 300' }

  $failure = 'watch failed before opening the dial (missing dial/session, helper error or timeout)'
  $before = Get-Dial
  if ($WatchOnly) {
    $session = $before.session
    if ($before.serial) { $session = $session.Replace([string]$before.serial, '(redacted)') }
    "session: $session"
    "console session: $($before.console)"
    exit 0
  }

  $failure = 'open failed (helper error or startup/read/exit timeout)'
  $p = Start-Serial "open $Port"
  $firstRead = $p.StandardError.ReadLineAsync()
  $buffer = New-Object byte[] 65536
  $stream = $p.StandardOutput.BaseStream
  $read = $stream.ReadAsync($buffer, 0, $buffer.Length)
  if (-not $firstRead.Wait(5000)) { throw 'open startup deadline exceeded' }
  $first = $firstRead.Result
  $rest = $p.StandardError.ReadToEndAsync()
  $opened = $first -ceq 'open'
  $bytes = [long]0
  $banner = $false
  $tail = ''
  $eof = $false
  $clock = [Diagnostics.Stopwatch]::StartNew()
  while ($opened -and $clock.Elapsed.TotalSeconds -lt $Seconds -and -not $p.HasExited) {
    if ($read.Wait(200)) {
      if ($read.Result -eq 0) { $eof = $true; break }
      $bytes += $read.Result
      # Keep only the banner overlap, so split reads are detected without retaining raw device output.
      $text = $tail + [Text.Encoding]::ASCII.GetString($buffer, 0, $read.Result)
      $banner = $banner -or $text.Contains('ESP-ROM:')
      $tail = $text.Substring([Math]::Max(0, $text.Length - 7))
      $read = $stream.ReadAsync($buffer, 0, $buffer.Length)
    }
  }
  $stayedOpen = $opened -and -not $eof -and -not $p.HasExited -and $clock.Elapsed.TotalSeconds -ge $Seconds
  $p.StandardInput.Close()
  # E1.3 must inspect the pending read and trailing bytes, including a banner split across stdin EOF.
  # Drain while the helper exits so a full stdout pipe cannot prevent its bounded shutdown.
  $shutdown = [Diagnostics.Stopwatch]::StartNew()
  while (-not $eof -and $shutdown.ElapsedMilliseconds -lt 5000) {
    if (-not $read.Wait([int][Math]::Max(1, 5000 - $shutdown.ElapsedMilliseconds))) { break }
    if ($read.Result -eq 0) { $eof = $true; break }
    $bytes += $read.Result
    $text = $tail + [Text.Encoding]::ASCII.GetString($buffer, 0, $read.Result)
    $banner = $banner -or $text.Contains('ESP-ROM:')
    $tail = $text.Substring([Math]::Max(0, $text.Length - 7))
    $read = $stream.ReadAsync($buffer, 0, $buffer.Length)
  }
  $ended = $p.WaitForExit([int][Math]::Max(1, 5000 - $shutdown.ElapsedMilliseconds))
  $exitCode = if ($ended) { $p.ExitCode } else { 'did not end' }
  if (-not $ended) { $p.Kill(); if (-not $p.WaitForExit(5000)) { throw 'open did not stop' } }
  if (-not $eof) { throw 'open stdout deadline exceeded' }
  if (-not $rest.Wait(5000)) { throw 'open stderr deadline exceeded' }
  $quietExit = [string]::IsNullOrWhiteSpace($rest.Result)
  Stop-Serial $p
  $p = $null

  $failure = 'watch failed after opening the dial (missing dial/session, helper error or timeout)'
  $after = Get-Dial
  $unchanged = $before.session -ceq $after.session
  $short = '(none)'
  if ($before.serial) {
    # Never reveal an entire short serial or arbitrary diagnostic/control characters from the helper.
    $serial = [string]$before.serial
    $short = if ($serial.Length -gt 8 -and $serial.Substring(0, 8) -cmatch '^[0-9a-fA-F:]+$') {
      $serial.Substring(0, 8) + '...'
    } else { '(redacted)' }
  }
  $status = if ($first -cin @('open', 'busy', 'gone')) { $first } else { '(diagnostics redacted)' }
  "dial: $Port, serial $short, console session: $($before.console)"
  "opened: $opened ($status)"
  "stayed open for $Seconds s: $stayedOpen"
  "bytes read: $bytes"
  "ESP-ROM banner seen: $banner"
  "exit at end of stdin: $exitCode $(if (-not $quietExit) { '(diagnostics redacted)' })"
  "session unchanged: $unchanged"
  if (-not ($opened -and $stayedOpen -and -not $banner -and $ended -and $exitCode -eq 0 -and $quietExit -and $unchanged)) {
    exit 1
  }
} catch {
  # Exceptions can embed an entire JSON watch line or native stderr, including the device's full serial.
  Write-Output "error: $failure"
  exit 1
} finally {
  try { Stop-Serial $p } catch { Write-Output 'error: serial child cleanup failed'; exit 1 }
}