@join-pantheon/cli 0.32.1 → 0.33.0-rc.2

package/helper/windows/pantheon-tray.ps1

@@ -0,0 +1,731 @@
+<#
+  Pantheon's tray icon on Windows: the macOS menu bar's job, in a notification-area icon.
+
+  A thin shell, like helper/macos/menubar.swift: everything it knows comes from
+  `pantheon tray-status` (JSON), and everything it does is a pantheon command.
+  It never answers, sends or decides anything itself.
+
+  The Pantheon desktop host (src/win-host.ts trayArgv) runs this file's text as
+  a script block, never with -File: Windows client editions default to the
+  Restricted execution policy, which refuses -File without a Bypass.
+    powershell -NoProfile -NonInteractive -WindowStyle Hidden -Command
+      "& ([scriptblock]::Create([IO.File]::ReadAllText('<this file>'))) -Pantheon '<command>' -Home '<PANTHEON_HOME>'"
+  So it never relies on $PSScriptRoot (a script block has none) or on script
+  scope: everything shared lives in one global table, $PT, and every function is
+  global, so a WinForms event handler finds the same state however it was started.
+
+  -Pantheon      how to run Pantheon, as a command line: "C:\...\node.exe" --use-system-ca "C:\...\cli.js",
+                 or one launcher path
+  -Home          Pantheon's home folder; every command it runs gets it as PANTHEON_HOME
+  -Icon          the .ico to show (the host passes the package's helper\windows\pantheon.ico;
+                 without it, the one beside the cli.js -Pantheon names)
+  -NoticeScript  helper\windows\pantheon-notice.ps1: the tray shows Pantheon's alerts
+                 with its functions (the notifier queues them in <Home>\host\notices)
+  -Poll          seconds between checks (15)
+
+  Quit writes <Home>\host\tray.disabled naming the host's session
+  (PANTHEON_HOST_SESSION), which keeps the host from starting it again until
+  the next logon -- or until `pantheon tray`, `pantheon service start` or setup
+  asks for it -- then exits 0. The host asks it to close by writing
+  <Home>\host\tray.stop (with this process's id): it then takes its icon away
+  itself, rather than leaving a ghost behind as a killed process would.
+#>
+param(
+  [Parameter(Mandatory = $true)][string]$Pantheon,
+  [Parameter(Mandatory = $true)][Alias('Home')][string]$PantheonHome,
+  [string]$Icon = '',
+  [string]$NoticeScript = '',
+  [ValidateRange(5, 3600)][int]$Poll = 15
+)
+
+$ErrorActionPreference = 'Stop'
+
+# ---------------------------------------------------------------- the command
+
+# -Pantheon is a command line: a quoted program and its leading arguments
+# ("node.exe" --use-system-ca "cli.js"), or one bare path (which may hold spaces).
+function global:Split-PantheonCommand([string]$line) {
+  $line = $line.Trim()
+  if ($line.StartsWith('"')) {
+    $end = $line.IndexOf('"', 1)
+    if ($end -lt 0) { return @{ exe = $line.Trim('"'); args = @() } }
+    $exe = $line.Substring(1, $end - 1)
+    $rest = $line.Substring($end + 1)
+  } elseif ((Test-Path -LiteralPath $line -PathType Leaf) -or ($line -notmatch '\s')) {
+    return @{ exe = $line; args = @() }
+  } else {
+    $sp = $line.IndexOfAny([char[]]@(' ', "`t"))
+    $exe = $line.Substring(0, $sp)
+    $rest = $line.Substring($sp + 1)
+  }
+  $words = @()
+  foreach ($m in [regex]::Matches($rest, '"([^"]*)"|(\S+)')) {
+    if ($m.Groups[1].Success) { $words += $m.Groups[1].Value } else { $words += $m.Groups[2].Value }
+  }
+  return @{ exe = $exe; args = $words }
+}
+
+function global:Quote-Arg([string]$a) {
+  # Pantheon's own words (tray-status, stop, worker) as they are; a path quoted whole. Windows paths hold no double quote.
+  if ($a -match '^[A-Za-z0-9._:-]+$') { return $a }
+  return '"' + $a + '"'
+}
+
+# The package's helper\windows\pantheon.ico, found from the cli.js the command names.
+function global:Find-TrayIcon([string[]]$words) {
+  foreach ($w in $words) {
+    if ($w -match '\.js$') {
+      $pkg = Split-Path -Parent (Split-Path -Parent $w)
+      $ico = Join-Path $pkg 'helper\windows\pantheon.ico'
+      if (Test-Path -LiteralPath $ico) { return $ico }
+    }
+  }
+  return ''
+}
+
+$cmd = Split-PantheonCommand $Pantheon
+$global:PT = @{
+  home = $PantheonHome; poll = $Poll; exe = $cmd.exe; pre = @($cmd.args)
+  # What pause and resume run: the same commands as the terminal. `service start`
+  # brings the worker back with the flags it was installed with.
+  pauseArgs = @('stop', 'worker'); resumeArgs = @('service', 'start', 'worker')
+  # How long a check may take, and how many may go missing before it says so:
+  # like the macOS tray, two misses keep what was last known; the third is shown.
+  checkTimeout = 20; missesTolerated = 2
+  misses = 0; check = $null; board = $null; nextCheck = (Get-Date); quit = $false
+  logDir = (Join-Path $PantheonHome 'logs')
+  hostDir = (Join-Path $PantheonHome 'host')
+  noticeDir = (Join-Path (Join-Path $PantheonHome 'host') 'notices')
+  session = [string]$env:PANTHEON_HOST_SESSION
+  # Alerts are shown from here when the alert functions loaded (Show-PantheonToast).
+  notices = $false
+  # An alert older than this when it is found is not news any more: dropped, and said so in the log.
+  noticeMaxAgeSeconds = 600
+  # This file is kept ASCII (Windows PowerShell reads a .ps1 without a BOM in the
+  # system code page); the typography it shows is made from code points.
+  dash = [string][char]0x2014; dot = [string][char]0x00B7; ellipsis = [string][char]0x2026
+  state = @{
+    loaded = $false; reachable = $false; configured = $false; relayOk = $false; decisionsOk = $true
+    member = ''; space = ''; spaces = @(); need = 0; workerRunning = $false; workerInstalled = $false
+  }
+  icons = @{}
+}
+if ($Icon) { $PT.iconPath = $Icon } else { $PT.iconPath = Find-TrayIcon $PT.pre }
+
+function global:Write-TrayLog([string]$line) {
+  try {
+    if (-not (Test-Path -LiteralPath $PT.logDir)) { [void](New-Item -ItemType Directory -Path $PT.logDir -Force) }
+    Add-Content -LiteralPath (Join-Path $PT.logDir 'tray.log') -Value ((Get-Date).ToString('o') + ' ' + $line) -Encoding UTF8
+  } catch { }
+}
+
+# The alert functions (Show-PantheonToast, Write-PantheonAlertLog), from the
+# fixed alert script, loaded the same way this file is: as a script block.
+if ($NoticeScript -and (Test-Path -LiteralPath $NoticeScript)) {
+  try { . ([scriptblock]::Create([IO.File]::ReadAllText($NoticeScript))); $PT.notices = $true }
+  catch { Write-TrayLog ('alerts: could not load ' + $NoticeScript + ': ' + $_.Exception.Message) }
+}
+
+# ---------------------------------------------------------------- alerts the notifier queued
+
+# Nothing in the queue is trusted. A queued alert carries the toast's fields,
+# never XML (src/notice-windows.ts QueuedNotice, version 2); each is checked
+# here, and the XML is built here, with the same escaping as Node's toastXml,
+# so a file someone else drops into the queue cannot inject markup. Every link
+# must be one of the four pantheon:// forms (src/uri-handler.ts parseUri), and
+# the app ids the two the notifier uses. Anything else is dropped and logged.
+$PT.linkForms = @{
+  board = @{ required = @(); optional = @() }
+  done = @{ required = @('decision', 'k'); optional = @('act', 'space') }
+  explain = @{ required = @('decision', 'k'); optional = @('act', 'space') }
+  details = @{ required = @('act', 'k'); optional = @('decision', 'space') }
+}
+$PT.linkValues = @{ decision = '^o_[a-z0-9]{6,48}$'; act = '^a_[A-Za-z0-9]{6,48}$'; space = '^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$'; k = '^[0-9a-f]{32}$' }
+# Pantheon's own app id (uri-handler.ts PANTHEON_AUMID) and Windows PowerShell's (notice-windows.ts POWERSHELL_AUMID).
+$PT.aumids = @('JoinPantheon.Pantheon', '{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\WindowsPowerShell\v1.0\powershell.exe')
+# A queued file that cannot be taken (read and deleted) is tried for this long, then skipped while it is there unchanged.
+$PT.stuck = @{}
+$PT.stuckSeconds = 5
+$PT.skippedFile = Join-Path $PT.hostDir 'notices.skipped'
+
+# One link: pantheon://board, or done/explain/details with each parameter once,
+# every value in the form Pantheon writes it. Strict, as the handler is.
+function global:Test-PantheonLink($uri) {
+  if ($uri -isnot [string] -or -not $uri -or $uri.Length -gt 400) { return $false }
+  if ($uri -cnotmatch '^[A-Za-z0-9:/?&=%._~-]+$') { return $false }
+  $m = [regex]::Match($uri, '^pantheon://([a-z]+)(?:\?(.+))?$')
+  if (-not $m.Success) { return $false }
+  $what = $m.Groups[1].Value
+  if (@($PT.linkForms.Keys) -cnotcontains $what) { return $false }
+  $form = $PT.linkForms[$what]
+  $names = @($form.required) + @($form.optional)
+  $seen = @{}
+  if ($m.Groups[2].Success) {
+    foreach ($part in $m.Groups[2].Value.Split('&')) {
+      $eq = $part.IndexOf('=')
+      if ($eq -le 0) { return $false }
+      $name = $part.Substring(0, $eq)
+      if ($names -cnotcontains $name -or $seen.ContainsKey($name)) { return $false }
+      if ($part.Substring($eq + 1) -cnotmatch $PT.linkValues[$name]) { return $false }
+      $seen[$name] = $true
+    }
+  }
+  foreach ($r in $form.required) { if (-not $seen.ContainsKey($r)) { return $false } }
+  return $true
+}
+
+# Text for the toast or the balloon: a string, no control characters (Node's
+# toastText removes them all), no longer than $max. $null when it is not.
+function global:Test-NoticeText($v, [int]$max, [bool]$empty = $true) {
+  if ($v -isnot [string]) { return $false }
+  if (-not $empty -and -not $v) { return $false }
+  if ($v.Length -gt $max) { return $false }
+  return ($v -cnotmatch '[\x00-\x1F\x7F-\x9F\uFFFE\uFFFF]')
+}
+
+# XML-escaped, for text and attribute values alike (notice-windows.ts xmlEscape).
+function global:ConvertTo-XmlText([string]$s) {
+  return $s.Replace('&', '&amp;').Replace('<', '&lt;').Replace('>', '&gt;').Replace('"', '&quot;').Replace("'", '&apos;')
+}
+
+# The toast XML from its checked fields: the same bytes as notice-windows.ts toastXmlFrom.
+function global:ConvertTo-PantheonToastXml($t) {
+  $attrs = 'activationType="protocol" launch="' + (ConvertTo-XmlText $t.launch) + '"'
+  if ($t.scenario) { $attrs += ' scenario="' + $t.scenario + '"' } elseif ($t.duration) { $attrs += ' duration="' + $t.duration + '"' }
+  $sb = New-Object System.Text.StringBuilder
+  [void]$sb.Append('<toast ' + $attrs + '>')
+  [void]$sb.Append('<visual><binding template="ToastGeneric">')
+  foreach ($l in $t.lines) { [void]$sb.Append('<text>' + (ConvertTo-XmlText $l) + '</text>') }
+  if ($t.who) { [void]$sb.Append('<text placement="attribution">' + (ConvertTo-XmlText $t.who) + '</text>') }
+  [void]$sb.Append('</binding></visual>')
+  if (@($t.buttons).Count -gt 0) {
+    [void]$sb.Append('<actions>')
+    foreach ($b in $t.buttons) { [void]$sb.Append('<action content="' + (ConvertTo-XmlText $b.content) + '" activationType="protocol" arguments="' + (ConvertTo-XmlText $b.uri) + '"/>') }
+    [void]$sb.Append('</actions>')
+  }
+  if ($t.silent) { [void]$sb.Append('<audio silent="true"/>') }
+  [void]$sb.Append('</toast>')
+  return $sb.ToString()
+}
+
+# The last check before a toast is shown: the XML parses, holds only the
+# elements and attributes a Pantheon toast has, each where it belongs, and every
+# activation is a pantheon:// link of the four forms.
+function global:Test-PantheonToastXml([string]$xml) {
+  $doc = New-Object System.Xml.XmlDocument
+  $doc.XmlResolver = $null
+  try { $doc.LoadXml($xml) } catch { return $false }
+  if ($null -ne $doc.DocumentType -or $null -eq $doc.DocumentElement) { return $false }
+  $attrs = @{
+    toast = @('activationType', 'launch', 'scenario', 'duration'); visual = @(); binding = @('template'); text = @('placement')
+    actions = @(); action = @('content', 'activationType', 'arguments'); audio = @('silent')
+  }
+  $parent = @{ toast = '#document'; visual = 'toast'; binding = 'visual'; text = 'binding'; actions = 'toast'; action = 'actions'; audio = 'toast' }
+  foreach ($n in @($doc.SelectNodes('//node()'))) {
+    if ($n.NodeType -eq [System.Xml.XmlNodeType]::Text) { if ($n.ParentNode.LocalName -cne 'text') { return $false }; continue }
+    if ($n.NodeType -ne [System.Xml.XmlNodeType]::Element) { return $false }
+    $name = $n.LocalName
+    if (@($attrs.Keys) -cnotcontains $name -or $n.NamespaceURI -or $n.Name -cne $name) { return $false }
+    if ($n.ParentNode.Name -cne $parent[$name]) { return $false }
+    foreach ($a in @($n.Attributes)) {
+      if ($attrs[$name] -cnotcontains $a.Name) { return $false }
+      if ($a.Name -ceq 'activationType' -and $a.Value -cne 'protocol') { return $false }
+      if (($a.Name -ceq 'launch' -or $a.Name -ceq 'arguments') -and -not (Test-PantheonLink $a.Value)) { return $false }
+    }
+    if ($name -ceq 'toast' -and -not $n.HasAttribute('launch')) { return $false }
+    if ($name -ceq 'action' -and -not $n.HasAttribute('arguments')) { return $false }
+  }
+  return $true
+}
+
+# One queued alert, from its file's text: a table, @{ stale = $true } when it
+# is too old to be news, or $null when it is not one Pantheon writes (and so is
+# never shown).
+function global:Read-QueuedNotice([string]$json, [datetime]$now) {
+  try {
+    $q = $json | ConvertFrom-Json
+    if ($null -eq $q -or $q -isnot [System.Management.Automation.PSCustomObject] -or [string]$q.v -cne '2') { return $null }
+    $about = [string]$q.about
+    if ($about -cnotmatch '^[a-z]{1,24}( [A-Za-z0-9_]{1,64})?$') { $about = 'an alert' }
+    if ([string]$q.at -cnotmatch '^\d{1,16}$') { return $null }
+    $at = [DateTimeOffset]::FromUnixTimeMilliseconds([int64][string]$q.at).UtcDateTime
+    if (($now.ToUniversalTime() - $at).TotalSeconds -gt $PT.noticeMaxAgeSeconds) { return @{ stale = $true; about = $about } }
+    $t = $q.toast
+    if ($null -eq $t -or $t -isnot [System.Management.Automation.PSCustomObject]) { return $null }
+    if ($t.lines -isnot [System.Array] -or @($t.lines).Count -lt 1 -or @($t.lines).Count -gt 3) { return $null }
+    foreach ($l in $t.lines) { if (-not (Test-NoticeText $l 700 $false)) { return $null } }
+    if (-not (Test-NoticeText $t.who 200)) { return $null }
+    if (-not (Test-PantheonLink $t.launch)) { return $null }
+    if ($t.buttons -isnot [System.Array] -or @($t.buttons).Count -gt 3) { return $null }
+    $buttons = @()
+    foreach ($b in $t.buttons) {
+      if ($null -eq $b -or $b -isnot [System.Management.Automation.PSCustomObject] -or -not (Test-NoticeText $b.content 60 $false) -or -not (Test-PantheonLink $b.uri)) { return $null }
+      $buttons += , @{ content = [string]$b.content; uri = [string]$b.uri }
+    }
+    if (@('', 'reminder') -cnotcontains [string]$t.scenario -or $t.scenario -isnot [string]) { return $null }
+    if (@('', 'long') -cnotcontains [string]$t.duration -or $t.duration -isnot [string]) { return $null }
+    if ($t.silent -isnot [bool]) { return $null }
+    if ($q.tag -isnot [string] -or $q.tag -cnotmatch '^[A-Za-z0-9_]{0,60}$') { return $null }
+    if ($q.aumids -isnot [System.Array] -or @($q.aumids).Count -lt 1 -or @($q.aumids).Count -gt 2) { return $null }
+    foreach ($id in $q.aumids) { if ($id -isnot [string] -or $PT.aumids -cnotcontains $id) { return $null } }
+    $balloon = $q.balloon
+    if ($null -eq $balloon -or -not (Test-NoticeText $balloon.title 200) -or -not (Test-NoticeText $balloon.text 600)) { return $null }
+    $xml = ConvertTo-PantheonToastXml @{
+      lines = @($t.lines | ForEach-Object { [string]$_ }); who = [string]$t.who; launch = [string]$t.launch; buttons = $buttons
+      scenario = [string]$t.scenario; duration = [string]$t.duration; silent = [bool]$t.silent
+    }
+    if (-not (Test-PantheonToastXml $xml)) { return $null }
+    # NotifyIcon's own limits (it throws beyond them).
+    $title = [string]$balloon.title; if ($title.Length -gt 63) { $title = $title.Substring(0, 63) }
+    $text = [string]$balloon.text; if ($text.Length -gt 255) { $text = $text.Substring(0, 255) }
+    if (-not $title) { $title = 'Pantheon' }
+    if (-not $text) { $text = 'Open Pantheon' }
+    return @{
+      stale = $false; about = $about; xml = $xml; tag = [string]$q.tag
+      aumids = @($q.aumids | ForEach-Object { [string]$_ }); title = $title; text = $text
+    }
+  } catch { return $null }
+}
+
+# Take one queued file: read it, then delete it. A seam of its own, so the
+# tests can stand in a file that will not go.
+function global:Receive-QueuedFile([string]$f) {
+  $text = [IO.File]::ReadAllText($f, [Text.Encoding]::UTF8)
+  [IO.File]::Delete($f)
+  if ([IO.File]::Exists($f)) { throw 'still there after it was deleted' }
+  return $text
+}
+
+# The skipped files, for the notifier: "<name><TAB><mtime ms>" a line
+# (notice-windows.ts skippedNotices), or no file when nothing is skipped.
+function global:Save-SkippedNotices {
+  $lines = @($PT.stuck.Keys | Sort-Object | Where-Object { $PT.stuck[$_].skip } | ForEach-Object { $_ + "`t" + $PT.stuck[$_].mtime })
+  try {
+    if ($lines.Count) { [IO.File]::WriteAllText($PT.skippedFile, (($lines -join "`n") + "`n")) }
+    elseif ([IO.File]::Exists($PT.skippedFile)) { [IO.File]::Delete($PT.skippedFile) }
+  } catch { Write-TrayLog ('alerts: could not write ' + $PT.skippedFile + ': ' + $_.Exception.Message) }
+}
+
+# What an earlier run of the tray skipped, so it is skipped from the start.
+function global:Read-SkippedNotices([datetime]$now) {
+  try {
+    if (-not [IO.File]::Exists($PT.skippedFile)) { return }
+    foreach ($line in [IO.File]::ReadAllLines($PT.skippedFile)) {
+      $m = [regex]::Match($line.Trim(), '^([0-9A-Za-z._-]+\.json)\t(\d{1,16})$')
+      if ($m.Success) { $PT.stuck[$m.Groups[1].Value] = @{ mtime = [int64]$m.Groups[2].Value; since = $now; skip = $true } }
+    }
+  } catch { }
+}
+
+# The queue, oldest first. Each file is taken (read and deleted) before it is
+# shown, so an alert is shown once. One that cannot be taken (a virus scanner
+# holds a new file for a moment) is tried again for $PT.stuckSeconds, then
+# skipped for as long as it is there unchanged: remembered by name and
+# modification time, said once in tray.log, and listed in host\notices.skipped
+# so the notifier does not take it for a tray that stopped reading
+# (trayTakesNotices). New alerts keep coming through either way.
+function global:Get-QueuedNotices([datetime]$now) {
+  $out = @()
+  if (-not [IO.Directory]::Exists($PT.noticeDir)) { return , $out }
+  $present = @{}
+  $changed = $false
+  foreach ($f in ([IO.Directory]::GetFiles($PT.noticeDir, '*.json') | Sort-Object)) {
+    if (-not $f.EndsWith('.json')) { continue }
+    $name = [IO.Path]::GetFileName($f)
+    $present[$name] = $true
+    $mtime = [int64]0
+    try { $mtime = [DateTimeOffset]::new([IO.File]::GetLastWriteTimeUtc($f)).ToUnixTimeMilliseconds() } catch { continue }
+    $s = $PT.stuck[$name]
+    if ($s -and $s.skip -and $s.mtime -eq $mtime) { continue }
+    $text = $null
+    try { $text = Receive-QueuedFile $f } catch { $text = $null }
+    if ($null -eq $text) {
+      if (-not $s -or $s.mtime -ne $mtime) { $PT.stuck[$name] = @{ mtime = $mtime; since = $now; skip = $false } }
+      elseif (($now - $s.since).TotalSeconds -ge $PT.stuckSeconds) {
+        $s.skip = $true
+        $changed = $true
+        Write-TrayLog ('alerts: skipping ' + $name + ' in the queue: it cannot be deleted; new alerts are still shown')
+      }
+      continue
+    }
+    if ($s) { if ($s.skip) { $changed = $true }; $PT.stuck.Remove($name) }
+    $n = Read-QueuedNotice $text $now
+    if ($null -eq $n) { Write-TrayLog ('alerts: dropped a queued file that is not an alert Pantheon writes: ' + $name); continue }
+    $out += , $n
+  }
+  foreach ($g in @($PT.stuck.Keys | Where-Object { -not $present.ContainsKey($_) })) {
+    if ($PT.stuck[$g].skip) { $changed = $true }
+    $PT.stuck.Remove($g)
+  }
+  if ($changed) { Save-SkippedNotices }
+  return , $out
+}
+Read-SkippedNotices (Get-Date)
+
+# The host asks the tray to close by writing host\tray.stop with this
+# process's id (or nothing): true when that is waiting, and it is taken.
+function global:Test-StopRequest {
+  $f = Join-Path $PT.hostDir 'tray.stop'
+  if (-not [IO.File]::Exists($f)) { return $false }
+  $who = ''
+  try { $who = ([IO.File]::ReadAllText($f)).Trim() } catch { return $false }
+  if ($who -and $who -ne [string]$PID) { return $false }
+  try { [IO.File]::Delete($f) } catch { }
+  return $true
+}
+
+# What Quit writes into host\tray.disabled: the session it holds for.
+function global:Get-QuitText {
+  $s = if ($PT.session) { 'session=' + $PT.session + ' ' } else { '' }
+  return 'quit from the tray ' + $s + 'at=' + (Get-Date).ToUniversalTime().ToString('o')
+}
+
+# Every command started from here reads its program from the environment, so no
+# path is spliced into a command line it did not come in on.
+$env:PANTHEON_HOME = $PantheonHome
+$env:PANTHEON_TRAY_EXE = $PT.exe
+$env:PANTHEON_TRAY_ARGS = ($PT.pre -join "`n")
+
+function global:New-PantheonStart([string[]]$words, [bool]$capture) {
+  $psi = New-Object System.Diagnostics.ProcessStartInfo
+  $psi.FileName = $PT.exe
+  $psi.Arguments = ((@($PT.pre) + @($words) | ForEach-Object { Quote-Arg $_ }) -join ' ')
+  $psi.UseShellExecute = $false
+  $psi.CreateNoWindow = $true
+  if ($capture) {
+    $psi.RedirectStandardOutput = $true
+    $psi.RedirectStandardError = $true
+    $psi.StandardOutputEncoding = [Text.Encoding]::UTF8
+  }
+  return $psi
+}
+
+# A console the person reads: `pantheon <words>` in a new PowerShell window that stays open.
+# The command text is fixed and passed encoded; the program comes from the environment.
+function global:Get-ConsoleCommand([string]$title, [string]$words) {
+  return "`$Host.UI.RawUI.WindowTitle = '$title'; `$pre = @(`$env:PANTHEON_TRAY_ARGS -split ""``n"" | Where-Object { `$_ }); & `$env:PANTHEON_TRAY_EXE @pre $words"
+}
+function global:Open-PantheonConsole([string]$title, [string]$words) {
+  $enc = [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes((Get-ConsoleCommand $title $words)))
+  try {
+    Start-Process -FilePath (Join-Path $env:SystemRoot 'System32\WindowsPowerShell\v1.0\powershell.exe') -ArgumentList @('-NoProfile', '-NoExit', '-EncodedCommand', $enc) | Out-Null
+  } catch { Write-TrayLog ('could not open a console for ' + $words + ': ' + $_.Exception.Message) }
+}
+
+# ---------------------------------------------------------------- status
+
+function global:Read-Status([string]$json) {
+  $j = $json | ConvertFrom-Json
+  $need = 0
+  foreach ($i in @($j.items)) {
+    if ($null -eq $i) { continue }
+    $lane = [string]$i.lane
+    $kind = [string]$i.kind
+    # The board's cards: lane "now", or a row from an older CLI without lanes that is not a wait (menubar.swift effectiveLane).
+    if ($lane -eq 'now' -or (@('now', 'handling', 'waiting', 'older') -notcontains $lane -and $kind -ne 'waiting')) { $need++ }
+  }
+  return @{
+    loaded = $true; reachable = $true
+    configured = [bool]$j.configured; relayOk = [bool]$j.relay_ok
+    decisionsOk = ($null -eq $j.decisions_ok -or [bool]$j.decisions_ok)
+    member = [string]$j.member; space = [string]$j.space; spaces = @($j.spaces | Where-Object { $_ })
+    need = $need; workerRunning = [bool]$j.worker_running; workerInstalled = [bool]$j.worker_installed
+  }
+}
+
+function global:Get-Summary {
+  $s = $PT.state
+  if (-not $s.loaded) { return 'Checking status' + $PT.ellipsis }
+  if (-not $s.reachable) { return 'Unable to check Pantheon status' }
+  if (-not $s.configured) { return 'Not joined to a team yet' }
+  if (-not $s.relayOk) { return 'Connection unavailable' }
+  if (-not $s.decisionsOk) { return 'Unable to check every decision' }
+  if ($s.need -eq 0) { return 'Nothing needs you' }
+  if ($s.need -eq 1) { return '1 needs you' }
+  return "$($s.need) need you"
+}
+
+# A check that did not come back is not news that the relay is down: what was
+# last known stands through two misses; only the third in a row is shown.
+function global:Complete-Check($json) {
+  $PT.check = $null
+  $next = $null
+  if ($json) { try { $next = Read-Status $json } catch { $next = $null } }
+  $s = $PT.state
+  if ($null -eq $next) {
+    $PT.misses++
+    if ($s.loaded -and $s.reachable -and $PT.misses -le $PT.missesTolerated) { return $false }
+    $s.loaded = $true; $s.reachable = $false
+  } else {
+    $PT.misses = 0
+    foreach ($k in $next.Keys) { $s[$k] = $next[$k] }
+  }
+  return $true
+}
+
+# ---------------------------------------------------------------- the desktop (Windows only from here)
+
+function global:Get-TrayIcon([int]$count, [string]$mode) {
+  $shown = [Math]::Min($count, 10)
+  $key = "$mode-$shown"
+  if ($PT.icons.ContainsKey($key)) { return $PT.icons[$key] }
+  $w = $PT.small.Width; $h = $PT.small.Height
+  $bmp = New-Object System.Drawing.Bitmap $w, $h
+  $g = [System.Drawing.Graphics]::FromImage($bmp)
+  $g.SmoothingMode = [System.Drawing.Drawing2D.SmoothingMode]::AntiAlias
+  $g.TextRenderingHint = [System.Drawing.Text.TextRenderingHint]::AntiAliasGridFit
+  $g.Clear([System.Drawing.Color]::Transparent)
+  $base = $PT.baseIcon.ToBitmap()
+  if ($mode -eq 'off') {
+    # Faint with a slash, as the macOS mark is when the relay cannot be reached or no team is joined.
+    $cm = New-Object System.Drawing.Imaging.ColorMatrix
+    $cm.Matrix33 = 0.45
+    $ia = New-Object System.Drawing.Imaging.ImageAttributes
+    $ia.SetColorMatrix($cm)
+    $g.DrawImage($base, (New-Object System.Drawing.Rectangle 0, 0, $w, $h), 0, 0, $base.Width, $base.Height, [System.Drawing.GraphicsUnit]::Pixel, $ia)
+    $pen = New-Object System.Drawing.Pen ([System.Drawing.Color]::FromArgb(230, 200, 60, 60)), ([Math]::Max(2, $w / 8))
+    $g.DrawLine($pen, [int]($w * 0.15), [int]($h * 0.85), [int]($w * 0.85), [int]($h * 0.15))
+    $pen.Dispose()
+  } else {
+    $g.DrawImage($base, 0, 0, $w, $h)
+  }
+  if ($shown -gt 0) {
+    # The count, on a red badge in the corner: what needs the person.
+    $d = [int]([Math]::Ceiling($w * 0.62))
+    $x = $w - $d; $y = $h - $d
+    $brush = New-Object System.Drawing.SolidBrush ([System.Drawing.Color]::FromArgb(255, 214, 48, 49))
+    $g.FillEllipse($brush, $x, $y, $d - 1, $d - 1)
+    $label = if ($shown -ge 10) { '+' } else { [string]$shown }
+    $font = New-Object System.Drawing.Font 'Segoe UI', ([Math]::Max(6, $d * 0.62)), ([System.Drawing.FontStyle]::Bold), ([System.Drawing.GraphicsUnit]::Pixel)
+    $fmt = New-Object System.Drawing.StringFormat
+    $fmt.Alignment = [System.Drawing.StringAlignment]::Center
+    $fmt.LineAlignment = [System.Drawing.StringAlignment]::Center
+    $g.DrawString($label, $font, [System.Drawing.Brushes]::White, (New-Object System.Drawing.RectangleF $x, ($y + 0.5), $d, $d), $fmt)
+    $font.Dispose(); $brush.Dispose(); $fmt.Dispose()
+  }
+  $g.Dispose(); $base.Dispose()
+  # Drawn once per state and kept: there are few (count 0-9, 9+, three modes).
+  $made = [System.Drawing.Icon]::FromHandle($bmp.GetHicon())
+  $PT.icons[$key] = $made
+  return $made
+}
+
+function global:Update-Tray {
+  $s = $PT.state
+  $mode = if (-not $s.loaded) { 'idle' } elseif (-not $s.reachable -or -not $s.configured -or -not $s.relayOk) { 'off' } elseif ($s.workerRunning) { 'full' } else { 'idle' }
+  $count = if ($s.loaded -and $s.reachable) { $s.need } else { 0 }
+  $PT.tray.Icon = Get-TrayIcon $count $mode
+  # The tooltip holds 63 characters at most (it throws beyond that).
+  $tip = 'Pantheon ' + $PT.dash + ' ' + (Get-Summary)
+  if ($tip.Length -gt 63) { $tip = $tip.Substring(0, 62) + $PT.ellipsis }
+  $PT.tray.Text = $tip
+}
+
+function global:Start-Check {
+  try {
+    $p = New-Object System.Diagnostics.Process
+    $p.StartInfo = New-PantheonStart @('tray-status') $true
+    [void]$p.Start()
+    $PT.check = @{ process = $p; out = $p.StandardOutput.ReadToEndAsync(); err = $p.StandardError.ReadToEndAsync(); started = Get-Date }
+  } catch {
+    Write-TrayLog ('tray-status did not start: ' + $_.Exception.Message)
+    if (Complete-Check $null) { Update-Tray }
+  }
+}
+
+function global:Watch-Check {
+  $c = $PT.check
+  if ($null -eq $c) { return }
+  $p = $c.process
+  if ($p.HasExited -and $c.out.IsCompleted) {
+    $code = $p.ExitCode
+    $out = $c.out.Result
+    $p.Dispose()
+    if ($code -ne 0) { Write-TrayLog "tray-status exited $code"; $out = $null }
+    if (Complete-Check $out) { Update-Tray }
+    return
+  }
+  if (((Get-Date) - $c.started).TotalSeconds -gt $PT.checkTimeout) {
+    try { $p.Kill() } catch { }
+    Write-TrayLog ('tray-status took longer than ' + $PT.checkTimeout + ' s')
+    $p.Dispose()
+    if (Complete-Check $null) { Update-Tray }
+  }
+}
+
+function global:Open-Board {
+  # The board (pantheon board --open) starts hidden and opens the browser; a build
+  # without one, or a start that fails at once, falls back to the brief in a console.
+  try {
+    $p = New-Object System.Diagnostics.Process
+    $p.StartInfo = New-PantheonStart @('board', '--open') $false
+    [void]$p.Start()
+    $PT.board = @{ process = $p; started = Get-Date }
+  } catch {
+    Write-TrayLog ('board did not start: ' + $_.Exception.Message)
+    Open-PantheonConsole 'Pantheon brief' 'brief'
+  }
+}
+
+function global:Watch-Board {
+  $b = $PT.board
+  if ($null -eq $b) { return }
+  $p = $b.process
+  if ($p.HasExited) {
+    if ($p.ExitCode -ne 0) { Write-TrayLog ('board exited ' + $p.ExitCode + '; opening the brief'); Open-PantheonConsole 'Pantheon brief' 'brief' }
+    $p.Dispose(); $PT.board = $null
+  } elseif (((Get-Date) - $b.started).TotalSeconds -gt 8) {
+    $PT.board = $null    # still serving: it started
+  }
+}
+
+function global:Invoke-Hidden([string[]]$words, [string]$what) {
+  try {
+    $p = [System.Diagnostics.Process]::Start((New-PantheonStart $words $false))
+    Write-TrayLog ($what + ': started')
+    $p.Dispose()
+  } catch { Write-TrayLog ($what + ' failed: ' + $_.Exception.Message) }
+  $PT.nextCheck = (Get-Date).AddSeconds(3)
+}
+
+# Quit: the host must not start the tray again in this session, so it is told
+# so first. It comes back at the next logon, or with `pantheon tray`.
+function global:Exit-Tray {
+  try {
+    $dir = $PT.hostDir
+    if (-not (Test-Path -LiteralPath $dir)) { [void](New-Item -ItemType Directory -Path $dir -Force) }
+    Set-Content -LiteralPath (Join-Path $dir 'tray.disabled') -Value (Get-QuitText) -Encoding UTF8
+  } catch { Write-TrayLog ('could not record the quit: ' + $_.Exception.Message) }
+  Write-TrayLog 'quit from the menu (until the next logon, or pantheon tray)'
+  $PT.tray.Visible = $false
+  $PT.quit = $true
+  $PT.context.ExitThread()
+}
+
+# Every alert waiting in the queue, shown from this process: a toast, or a
+# balloon from this icon where toasts cannot be shown. What happened to each
+# is said in alerts.log -- shown, a balloon, or not shown, never assumed.
+function global:Show-QueuedNotices {
+  foreach ($n in (Get-QueuedNotices (Get-Date))) {
+    if ($n.stale) { Write-PantheonAlertLog ('tray: dropped ' + $n.about + ' (queued more than ten minutes ago)'); continue }
+    $r = Show-PantheonToast $n.xml $n.tag $n.aumids
+    if ($r.code -eq 0) { Write-PantheonAlertLog ('tray: shown ' + $n.about + ' (' + ($r.said -join ' | ') + ')'); continue }
+    try {
+      $PT.tray.ShowBalloonTip(15000, $n.title, $n.text, [System.Windows.Forms.ToolTipIcon]::Info)
+      Write-PantheonAlertLog ('tray: balloon for ' + $n.about + ' (toast exit ' + $r.code + ': ' + ($r.said -join ' | ') + ')')
+    } catch { Write-PantheonAlertLog ('tray: not shown ' + $n.about + ' (toast exit ' + $r.code + '; balloon: ' + $_.Exception.Message + ')') }
+  }
+}
+
+function global:Add-MenuItem([string]$text, [scriptblock]$onClick, [bool]$bold = $false, [bool]$enabled = $true) {
+  $item = New-Object System.Windows.Forms.ToolStripMenuItem $text
+  $item.Enabled = $enabled
+  if ($bold) { $item.Font = New-Object System.Drawing.Font $item.Font, ([System.Drawing.FontStyle]::Bold) }
+  if ($onClick) {
+    # The action rides on the item itself; one handler runs it.
+    $item.Tag = $onClick
+    $item.add_Click({ param($s, $e) try { & $s.Tag } catch { Write-TrayLog ('menu: ' + $_.Exception.Message) } })
+  }
+  [void]$PT.menu.Items.Add($item)
+}
+
+function global:Build-Menu {
+  $menu = $PT.menu
+  $s = $PT.state
+  $menu.Items.Clear()
+  $who = @()
+  if ($s.member) { $who += $s.member }
+  if (@($s.spaces).Count -gt 1) { $who += "$(@($s.spaces).Count) teams" } elseif ($s.space) { $who += $s.space }
+  $head = Get-Summary
+  if ($who.Count) { $head = $head + ' ' + $PT.dot + ' ' + ($who -join (' ' + $PT.dot + ' ')) }
+  Add-MenuItem $head $null $false $false
+  [void]$menu.Items.Add((New-Object System.Windows.Forms.ToolStripSeparator))
+  Add-MenuItem 'Open board' { Open-Board } $true
+  [void]$menu.Items.Add((New-Object System.Windows.Forms.ToolStripSeparator))
+  if ($s.workerRunning) { Add-MenuItem 'Pause unattended work' { Invoke-Hidden $PT.pauseArgs 'pause worker' } }
+  elseif ($s.workerInstalled) { Add-MenuItem 'Resume unattended work' { Invoke-Hidden $PT.resumeArgs 'resume worker' } }
+  else { Add-MenuItem 'Unattended work is not set up' $null $false $false }
+  Add-MenuItem 'Status' { Open-PantheonConsole 'Pantheon status' 'status' }
+  Add-MenuItem 'Doctor' { Open-PantheonConsole 'Pantheon doctor' 'doctor' }
+  Add-MenuItem 'Refresh now' { $PT.nextCheck = Get-Date }
+  [void]$menu.Items.Add((New-Object System.Windows.Forms.ToolStripSeparator))
+  Add-MenuItem 'Quit tray (until you next log in)' { Exit-Tray }
+}
+
+# A test loads the functions above without a desktop: it stops here.
+if ($env:PANTHEON_TRAY_NO_UI -eq '1') { return }
+
+# No WinForms here (Server Core, a policy that removes it): starting again
+# every minute would fail every minute. Exit 64 tells the host to leave the
+# tray stopped until the next logon (win-host.ts GIVE_UP_CODE).
+try {
+  Add-Type -AssemblyName System.Windows.Forms
+  Add-Type -AssemblyName System.Drawing
+} catch {
+  Write-TrayLog ('no tray here: ' + $_.Exception.Message)
+  exit 64
+}
+[System.Windows.Forms.Application]::EnableVisualStyles()
+
+# One tray per Pantheon home: a second start (a restart racing a login) leaves quietly.
+$sha = [System.Security.Cryptography.SHA256]::Create()
+$homeId = -join ($sha.ComputeHash([Text.Encoding]::UTF8.GetBytes($PantheonHome.ToLowerInvariant())) | Select-Object -First 8 | ForEach-Object { $_.ToString('x2') })
+$createdNew = $false
+$PT.mutex = [System.Threading.Mutex]::new($true, "Local\PantheonTray-$homeId", [ref]$createdNew)
+if (-not $createdNew) { exit 0 }
+
+$PT.small = [System.Windows.Forms.SystemInformation]::SmallIconSize
+if ($PT.iconPath -and (Test-Path -LiteralPath $PT.iconPath)) { $PT.baseIcon = New-Object System.Drawing.Icon -ArgumentList $PT.iconPath, $PT.small }
+else { $PT.baseIcon = [System.Drawing.SystemIcons]::Application }
+
+$PT.tray = New-Object System.Windows.Forms.NotifyIcon
+$PT.tray.Icon = Get-TrayIcon 0 'idle'
+$PT.tray.Text = 'Pantheon'
+$PT.menu = New-Object System.Windows.Forms.ContextMenuStrip
+$PT.menu.add_Opening({ try { Build-Menu } catch { Write-TrayLog ('menu: ' + $_.Exception.Message) } })
+Build-Menu
+$PT.tray.ContextMenuStrip = $PT.menu
+# A left click opens the board; the right click shows the menu.
+$PT.tray.add_MouseClick({
+  param($s, $e)
+  if ($e.Button -eq [System.Windows.Forms.MouseButtons]::Left) { try { Open-Board } catch { Write-TrayLog ('click: ' + $_.Exception.Message) } }
+})
+# A click on an alert's balloon opens the board, as a click on its toast does.
+$PT.tray.add_BalloonTipClicked({ try { Open-Board } catch { Write-TrayLog ('balloon click: ' + $_.Exception.Message) } })
+$PT.timer = New-Object System.Windows.Forms.Timer
+$PT.timer.Interval = 500
+$PT.timer.add_Tick({
+  try {
+    # Asked to close by the host: the icon goes with this process, not after it.
+    if (Test-StopRequest) { Write-TrayLog 'asked to close by the Pantheon host'; $PT.timer.Stop(); $PT.tray.Visible = $false; $PT.context.ExitThread(); return }
+    # Alerts: polled every half second. Not a FileSystemWatcher: its events
+    # arrive on a thread with no PowerShell runspace, which ends the process.
+    if ($PT.notices) { Show-QueuedNotices }
+    Watch-Check
+    Watch-Board
+    if ($null -eq $PT.check -and (Get-Date) -ge $PT.nextCheck) {
+      $PT.nextCheck = (Get-Date).AddSeconds($PT.poll)
+      Start-Check
+    }
+  } catch { Write-TrayLog ('tick: ' + $_.Exception.Message) }
+})
+
+$PT.context = New-Object System.Windows.Forms.ApplicationContext
+$PT.tray.Visible = $true
+Update-Tray
+$PT.timer.Start()
+Write-TrayLog ('tray started (home ' + $PantheonHome + ', every ' + $Poll + ' s)')
+$failed = $false
+try {
+  [System.Windows.Forms.Application]::Run($PT.context)
+} catch {
+  Write-TrayLog ('tray stopped: ' + $_.Exception.Message)
+  $failed = $true
+} finally {
+  $PT.timer.Stop()
+  $PT.tray.Visible = $false
+  $PT.tray.Dispose()
+  try { $PT.mutex.ReleaseMutex() } catch { }
+}
+if ($failed) { exit 1 }
+exit 0