@join-pantheon/cli 0.33.1 → 0.33.2

package/installer/install.ps1

@@ -190,6 +190,168 @@ function Install-Pantheon {
     return $mine
   }
 
+  # An app package's folder name as a person knows the app: Claude_pzs8sxrjxfjjc
+  # is the Claude desktop app; Publisher.Some.App_8wekyb3d8bbwe is Some.App.
+  function Get-PantheonAppName([string]$Package) {
+    if ($Package -match '^Claude_') { return 'the Claude desktop app' }
+    if ($Package) { return (($Package -replace '_[A-Za-z0-9]+$', '') -replace '^[A-Za-z0-9]+\.', '') }
+    return ''
+  }
+
+  # Copies of Pantheon that only an app could see: an installer before 0.33.1
+  # run from inside an app package (the Claude desktop app's agent) put
+  # Pantheon in %LOCALAPPDATA%\Pantheon, which Windows kept in that app's
+  # private AppData, %LOCALAPPDATA%\Packages\<package>\LocalCache\Local\Pantheon.
+  # Nothing outside the app ever ran it; it only takes space (npm's cache) and
+  # can confuse the app's agent. Pantheon's only by what the installer puts
+  # there (the launcher, the CLI, the install lock), never a folder another app
+  # happens to call Pantheon; and never through a link (junction or symlink) at
+  # any step of the path, which would lead somewhere else. Each as @{ path; package }.
+  function Find-PantheonAppCopies([string]$Local) {
+    $out = @()
+    if (-not $Local) { return , $out }
+    $pk = Join-Path $Local 'Packages'
+    if (-not (Test-Path -LiteralPath $pk -PathType Container)) { return , $out }
+    foreach ($f in @(Get-ChildItem -LiteralPath $pk -Directory -Force -ErrorAction SilentlyContinue)) {
+      $local2 = [IO.Path]::Combine($f.FullName, 'LocalCache', 'Local')
+      if (-not (Test-Path -LiteralPath $local2 -PathType Container)) { continue }
+      # The copy, and what a removal cut off halfway left beside it (named below, so ours by name).
+      $dirs = @()
+      $dir = Join-Path $local2 'Pantheon'
+      if (Test-Path -LiteralPath $dir -PathType Container) {
+        $ours = (Test-Path -LiteralPath ([IO.Path]::Combine($dir, 'bin', 'pantheon.cmd'))) -or
+          (Test-Path -LiteralPath ([IO.Path]::Combine($dir, 'runtime', 'node', 'node_modules', '@join-pantheon'))) -or
+          (Test-Path -LiteralPath ([IO.Path]::Combine($dir, 'runtime', 'install.lock')))
+        if ($ours) { $dirs += $dir }
+      }
+      # One suffix or more: a removal cut off twice by a build before 0.33.2 renamed it again.
+      $dirs += @(Get-ChildItem -LiteralPath $local2 -Directory -Force -ErrorAction SilentlyContinue |
+        Where-Object { $_.Name -match '^Pantheon(\.remove-[0-9a-f]{6})+$' } | ForEach-Object { $_.FullName })
+      foreach ($d in $dirs) {
+        $linked = $false
+        # Every step from the Packages folder down: a link at Packages itself, or
+        # at the package's folder, leads somewhere else just the same.
+        foreach ($step in @($pk, $f.FullName, [IO.Path]::Combine($f.FullName, 'LocalCache'), $local2, $d)) {
+          $item = $null
+          try { $item = Get-Item -LiteralPath $step -Force -ErrorAction Stop } catch { $item = $null }
+          if (-not $item -or ($item.Attributes -band [IO.FileAttributes]::ReparsePoint)) { $linked = $true; break }
+        }
+        if (-not $linked) { $out += , @{ path = $d; package = $f.Name } }
+      }
+    }
+    return , $out
+  }
+
+  # A full path in the \\?\ form, which Windows takes past 260 characters.
+  function ConvertTo-PantheonLongPath([string]$Path) {
+    if ($Path.StartsWith('\\?\')) { return $Path }
+    if ($Path.StartsWith('\\')) { return '\\?\UNC\' + $Path.Substring(2) }
+    return '\\?\' + $Path
+  }
+
+  # rd /s /q by the \\?\ form of the path. Windows PowerShell 5.1's Remove-Item
+  # stops at 260 characters, and npm's cache inside such a copy goes deeper
+  # (removing one by hand took exactly this). The path is in double quotes,
+  # where cmd.exe reads & and ^ as they are. '' when the folder went; otherwise
+  # what rd said.
+  function Remove-PantheonTree([string]$Path) {
+    $psi = New-Object System.Diagnostics.ProcessStartInfo
+    $psi.FileName = Join-Path $env:SystemRoot 'System32\cmd.exe'
+    $psi.Arguments = '/d /c rd /s /q "' + (ConvertTo-PantheonLongPath $Path) + '"'
+    $psi.UseShellExecute = $false
+    $psi.CreateNoWindow = $true
+    $psi.RedirectStandardInput = $true
+    $psi.RedirectStandardOutput = $true
+    $psi.RedirectStandardError = $true
+    $p = [System.Diagnostics.Process]::Start($psi)
+    $p.StandardInput.Close()
+    $out = $p.StandardOutput.ReadToEndAsync()
+    $err = $p.StandardError.ReadToEndAsync()
+    $p.WaitForExit()
+    if (-not (Test-Path -LiteralPath $Path)) { return '' }
+    $said = (($err.Result + ' ' + $out.Result) -replace '\s+', ' ').Trim()
+    if ($said) { return $said }
+    return "rd exited $($p.ExitCode)"
+  }
+
+  # Each copy nothing runs from is removed. First it is renamed beside itself
+  # ($Rename): Windows refuses to rename a folder a running program came from,
+  # however deep, which tells "in use" even where an app's private copy shows a
+  # running program under another path; and a copy cut off halfway is then no
+  # longer one anything starts. Then rd ($Remove: Remove-PantheonTree). A copy
+  # still in use is left as it is, with what runs from it ($Holders:
+  # Get-FolderHolders) when Windows says. Returns @{ removed = @(@{ path; package });
+  # held = @(@{ path; package; holders }); failed = @(@{ path; package; why }) }.
+  function Remove-PantheonAppCopies([object[]]$Copies, [scriptblock]$Holders, [scriptblock]$Remove,
+    [scriptblock]$Rename = { param($from, $to) Move-Item -LiteralPath $from -Destination $to -ErrorAction Stop }, [int]$Tries = 3) {
+    $removed = @(); $held = @(); $failed = @()
+    foreach ($c in @($Copies | Where-Object { $_ })) {
+      $h = @()
+      try { $h = @(& $Holders $c.path | ForEach-Object { $_ }) } catch { $h = @() }
+      # A copy already renamed aside (a removal cut off before) is renamed to a
+      # fresh name of the same form, never given a second suffix the next run
+      # would not know as Pantheon's.
+      $aside = ($c.path -replace '(\.remove-[0-9a-f]{6})+$', '') + '.remove-' + [Guid]::NewGuid().ToString('N').Substring(0, 6)
+      $moved = $false
+      if ($h.Count -eq 0) {
+        for ($i = 1; $i -le $Tries -and -not $moved; $i++) {
+          try { & $Rename $c.path $aside; $moved = $true } catch { if ($i -lt $Tries) { Start-Sleep -Milliseconds 700 } }
+        }
+      }
+      if (-not $moved) { $held += , @{ path = $c.path; package = $c.package; holders = $h }; continue }
+      $why = ''
+      try { $why = [string](& $Remove $aside) } catch { $why = $_.Exception.Message }
+      if (Test-Path -LiteralPath $aside) {
+        if (-not $why) { $why = 'some of it is still there' }
+        $failed += , @{ path = $aside; package = $c.package; why = $why }
+      } else { $removed += , @{ path = $c.path; package = $c.package } }
+    }
+    return @{ removed = $removed; held = $held; failed = $failed }
+  }
+
+  # What a shell is, from its program's name: the syntax its next command
+  # is said in. '' when it cannot be told.
+  function Get-PantheonShellKind([string]$Name) {
+    $n = ([string]$Name).ToLowerInvariant() -replace '\.exe$', ''
+    if ($n -eq 'cmd') { return 'cmd' }
+    if ($n -in @('powershell', 'pwsh', 'powershell_ise')) { return 'powershell' }
+    if ($n -in @('bash', 'sh', 'zsh', 'dash', 'fish', 'mintty', 'git-bash')) { return 'bash' }
+    return ''
+  }
+
+  # The program that started this PowerShell (cmd.exe, when the installer
+  # was run as powershell -Command "..." from Command Prompt). '' when
+  # Windows will not say.
+  function Get-PantheonParentName {
+    try {
+      $me = Get-CimInstance Win32_Process -Filter ('ProcessId=' + $PID) -ErrorAction Stop
+      $up = Get-CimInstance Win32_Process -Filter ('ProcessId=' + [int]$me.ParentProcessId) -ErrorAction Stop
+      return [string]$up.Name
+    } catch { return '' }
+  }
+
+  # A pantheon command line as typed in $Shell: by name ($Launcher '') where
+  # pantheon is already on that window's PATH, otherwise by the launcher's
+  # full path in that shell's own syntax. Arguments are quoted only where
+  # that shell needs it, so the line reads as typed. A bash on Windows (Git
+  # Bash) runs a .cmd only by its full name, and reads C:/ paths, so it gets
+  # one of those.
+  function Format-PantheonCommand([string]$Launcher, [string[]]$Arguments, [string]$Shell) {
+    $plain = '^[A-Za-z0-9_./:=@+,-]+$'
+    $items = @($Arguments | Where-Object { $null -ne $_ })
+    if ($Shell -eq 'cmd') {
+      $head = if ($Launcher) { '"' + $Launcher + '"' } else { 'pantheon' }
+      $rest = @($items | ForEach-Object { if ($_ -match $plain) { $_ } else { '"' + $_ + '"' } })
+    } elseif ($Shell -eq 'bash') {
+      $head = if ($Launcher) { "'" + (($Launcher -replace '\\', '/') -replace "'", "'\''") + "'" } else { 'pantheon' }
+      $rest = @($items | ForEach-Object { if ($_ -match $plain) { $_ } else { "'" + ($_ -replace "'", "'\''") + "'" } })
+    } else {
+      $head = if ($Launcher) { "& '" + ($Launcher -replace "'", "''") + "'" } else { 'pantheon' }
+      $rest = @($items | ForEach-Object { if ($_ -match $plain) { $_ } else { "'" + ($_ -replace "'", "''") + "'" } })
+    }
+    return ((@($head) + @($rest)) -join ' ')
+  }
+
   # The user PATH, set from OUTSIDE this app's package. Inside one, Windows 10
   # keeps HKCU changes private to the app (Windows 11 lets this key through),
   # so a terminal opened from the Start menu would not find pantheon. Task
@@ -390,7 +552,7 @@ function Install-Pantheon {
     param([string]$NodeDir, [string]$HostDir, [string[]]$Tasks, [scriptblock]$Holders, [scriptblock]$EndTask, [int]$WaitSeconds = 15,
       [string]$RunRecord = '', [scriptblock]$RunAlive = { param($p) $null -ne (Get-Process -Id $p -ErrorAction SilentlyContinue) },
       [int]$RunWaitSeconds = 180, [scriptblock]$TaskIsMine = { param($t) $true }, [scriptblock]$Say = { param($m) Write-Host $m })
-    $left = @(& $Holders $NodeDir)
+    $left = @(& $Holders $NodeDir | ForEach-Object { $_ })
     if ($left.Count -eq 0) { return @{ restart = $false; holders = @(); busy = $false; tasks = @() } }
     if (Get-PantheonRunInFlight $RunRecord $RunAlive) {
       & $Say "A teammate's request is running here; waiting for it to finish before updating (up to $([math]::Ceiling($RunWaitSeconds / 60)) minutes)..."
@@ -401,7 +563,7 @@ function Install-Pantheon {
         $running = [bool](Get-PantheonRunInFlight $RunRecord $RunAlive)
       }
       if ($running) { return @{ restart = $false; holders = $left; busy = $true; tasks = @() } }
-      $left = @(& $Holders $NodeDir)
+      $left = @(& $Holders $NodeDir | ForEach-Object { $_ })
       if ($left.Count -eq 0) { return @{ restart = $false; holders = @(); busy = $false; tasks = @() } }
     }
     $hostUp = Test-Path -LiteralPath (Join-Path $HostDir 'state.json')
@@ -411,12 +573,12 @@ function Install-Pantheon {
     $deadline = (Get-Date).AddSeconds($WaitSeconds)
     while ($hostUp -and $left.Count -gt 0 -and (Get-Date) -lt $deadline) {
       Start-Sleep -Milliseconds 500
-      $left = @(& $Holders $NodeDir)
+      $left = @(& $Holders $NodeDir | ForEach-Object { $_ })
     }
     $mine = @($Tasks | Where-Object { $_ } | Where-Object { $ok = $false; try { $ok = [bool](& $TaskIsMine $_) } catch { $ok = $false }; $ok })
     if ($left.Count -gt 0) {
       foreach ($t in $mine) { & $EndTask $t }
-      for ($i = 0; $i -lt 6 -and $left.Count -gt 0; $i++) { Start-Sleep -Milliseconds 500; $left = @(& $Holders $NodeDir) }
+      for ($i = 0; $i -lt 6 -and $left.Count -gt 0; $i++) { Start-Sleep -Milliseconds 500; $left = @(& $Holders $NodeDir | ForEach-Object { $_ }) }
     }
     return @{ restart = $hostUp; holders = $left; busy = $false; tasks = $mine }
   }
@@ -489,11 +651,13 @@ function Install-Pantheon {
         $signedIn = $false
         try { $signedIn = [bool]((Get-Content -LiteralPath (Join-Path $pantheonHome 'config.json') -Raw | ConvertFrom-Json).account) } catch { $signedIn = $false }
         if (-not $signedIn) {
-          # Quoted only where PowerShell needs it, so it reads as typed.
-          $show = ($Arguments | ForEach-Object { if ($_ -match '^[A-Za-z0-9_./:=@+,-]+$') { $_ } else { "'" + ($_ -replace "'", "''") + "'" } }) -join ' '
+          # By the launcher's full path, as typed in PowerShell: whatever runs it
+          # next (an agent's shell, a window opened before this install) may not
+          # have the new PATH yet.
+          $show = Format-PantheonCommand $launcher $Arguments 'powershell'
           $what = if ($Arguments[0] -eq 'join') { 'joining' } else { 'creating your team' }
           Say ''
-          Say "Pantheon is installed. To finish $what, open PowerShell and run: pantheon $show"
+          Say "Pantheon is installed. To finish $what, open PowerShell and run: $show"
         }
       }
     } finally {
@@ -549,7 +713,7 @@ function Install-Pantheon {
     if (-not $profileDir) { Fail 'USERPROFILE is not set, so there is nowhere to install. Run this from your own Windows account.' }
     # Inside an app package (the Claude desktop app): said once, and acted on below.
     $appPackage = Get-PantheonAppPackage $localAppData
-    $appName = if ($appPackage -match '^Claude_') { 'the Claude desktop app' } elseif ($appPackage) { (($appPackage -replace '_[A-Za-z0-9]+$', '') -replace '^[A-Za-z0-9]+\.', '') } else { '' }
+    $appName = Get-PantheonAppName $appPackage
     $where = Select-PantheonRoot $profileDir $localAppData $appPackage
     $root = $where.root
     # A release before 0.33.1 does not know ~\.pantheon (it would not find itself to
@@ -573,6 +737,38 @@ function Install-Pantheon {
     $binDir = Join-Path $root 'bin'
     $launcher = Join-Path $binDir 'pantheon.cmd'
     $log = Join-Path $root 'install.log'
+
+    # The window the person ran this from, and how pantheon is typed there
+    # once this is done. An open PowerShell window running irm | iex is this
+    # very process, whose PATH is set below: pantheon by name. Run as
+    # powershell -Command "..." from another window (Command Prompt, a
+    # PowerShell window, Git Bash, an agent's shell), that window keeps the PATH
+    # it started with, so pantheon is "not recognized" there: by name only if
+    # pantheon already meant this launcher in it (asked now, before this
+    # script changes PATH), otherwise by its full path in that window's syntax.
+    $oneShot = $false
+    try { $oneShot = Test-PantheonOneShot ([Environment]::GetCommandLineArgs()) -OrFile } catch { $oneShot = $false }
+    $shellKind = 'here'
+    $byPath = ''
+    if ($oneShot) {
+      $shellKind = Get-PantheonShellKind (Get-PantheonParentName)
+      $known = $null
+      try { $known = Get-Command pantheon -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1 } catch { $known = $null }
+      if ($shellKind -eq 'bash' -or -not ($known -and $known.Source -ieq $launcher)) { $byPath = $launcher }
+    }
+    # The next command for that window. Where the shell cannot be told, in
+    # PowerShell's syntax, and the note below gives Command Prompt's.
+    $nextFor = {
+      param([string[]]$Items)
+      if ($shellKind -eq 'here') { return Format-PantheonCommand '' $Items 'powershell' }
+      if ($shellKind) { return Format-PantheonCommand $byPath $Items $shellKind }
+      return Format-PantheonCommand $byPath $Items 'powershell'
+    }
+    $byPathNote = {
+      if (-not $byPath) { return }
+      $cmdToo = if ($shellKind) { '' } else { " (in Command Prompt: $(Format-PantheonCommand $byPath @() 'cmd'))" }
+      Say "(This window was open before Pantheon was on your PATH, so that is its full path$cmdToo; a new window finds it as pantheon.)"
+    }
     $pantheonHomeDir = if ($env:PANTHEON_HOME) { $env:PANTHEON_HOME } else { Join-Path ([Environment]::GetFolderPath('UserProfile')) '.pantheon' }
     $hostDir = Join-Path $pantheonHomeDir 'host'
 
@@ -867,6 +1063,28 @@ function Install-Pantheon {
       Where-Object { $_.Source -and -not $_.Source.StartsWith($root + '\', [StringComparison]::OrdinalIgnoreCase) } | Select-Object -First 1
     if ($other) { Note "another pantheon is installed at $($other.Source) and was left as it is. New terminals run $launcher first, unless that one is on the system PATH." }
 
+    # ---- old copies that only an app could see -------------------------------
+
+    # Only from outside an app package: inside one, its private copy is what
+    # this very app may be running, and Select-PantheonRoot already passes it over.
+    if (-not $appPackage) {
+      $State.step = 'removing old copies of Pantheon that only an app could see'
+      $copies = Find-PantheonAppCopies $localAppData
+      if ($copies.Count) {
+        $gone = Remove-PantheonAppCopies $copies { param($d) Get-FolderHolders $d } { param($d) Remove-PantheonTree $d }
+        foreach ($c in $gone.removed) { Say "Removed an old copy of Pantheon that only $(Get-PantheonAppName $c.package) could see: $($c.path)" }
+        foreach ($c in $gone.held) {
+          $n = Get-PantheonAppName $c.package
+          $what = if (@($c.holders).Count) { Format-Holders $c.holders } else { "a program (Windows did not say which; most likely $n)" }
+          Note "an old copy of Pantheon that only $n could see is in $($c.path), and $what runs from it. Quit $n, then run this installer again to remove it."
+        }
+        foreach ($c in $gone.failed) {
+          $n = Get-PantheonAppName $c.package
+          Note "an old copy of Pantheon that only $n could see was only partly removed: $($c.path) ($($c.why)). Quit $n, then run this installer again to finish."
+        }
+      }
+    }
+
     # ---- 5. hand over to pantheon ------------------------------------------
 
     $State.lock.Dispose()
@@ -919,17 +1137,26 @@ function Install-Pantheon {
       Say ''
       if ($member) {
         Say "Pantheon $PantheonVersion is installed, and you are still signed in as $member -- nothing to rejoin."
-        Say 'Open a new terminal (or restart your agent) and carry on; pantheon doctor checks everything.'
+        Say "Restart any agent window that was open and carry on. To check everything, in this window: $(& $nextFor @('doctor'))"
       } else {
-        Say "Pantheon $PantheonVersion is installed. Open a new terminal, then:"
-        Say '  pantheon start                    create a team'
-        Say "  pantheon join '<invite link>'     join a teammate's team"
+        Say "Pantheon $PantheonVersion is installed. Next, in this window:"
+        $startLine = & $nextFor @('start')
+        $joinLine = & $nextFor @('join', '<invite link>')
+        # The start line padded to the join line's width, so the descriptions line up.
+        Say ('  ' + $startLine.PadRight($joinLine.Length) + '     create a team')
+        Say ('  ' + $joinLine + "     join a teammate's team")
       }
+      & $byPathNote
       $State.code = 0
       return
     }
     Say ''
     Invoke-PantheonHandoff $nodeExe $entry $ca $Arguments
+    if ($State.code -eq 0) {
+      Say ''
+      Say "Next, in this window: $(& $nextFor @('doctor'))   (checks that everything works)"
+      & $byPathNote
+    }
   } catch {
     $m = $_.Exception.Message
     if ($m -like 'PANTHEON_BUSY:*') {
@@ -947,6 +1174,11 @@ function Install-Pantheon {
         try {
           Say ''
           Invoke-PantheonHandoff $nodeExe $entry $caNow $Arguments
+          if ($State.code -eq 0 -and $nextFor) {
+            Say ''
+            Say "Next, in this window: $(& $nextFor @('doctor'))   (checks that everything works)"
+            & $byPathNote
+          }
         } catch {
           Write-Host "pantheon install failed: it stopped while starting pantheon ($($_.Exception.Message)). Open a new terminal and run your pantheon command again." -ForegroundColor Red
           $State.code = 1
@@ -1016,15 +1248,19 @@ function Split-PantheonArgs([string]$Line) {
 # (`powershell -Command "... | iex"` from cmd.exe), where the exit code is the
 # result, rather than an open window, which `exit` would close. PowerShell
 # takes any prefix of a parameter's name, after -, -- or /; -NoExit anywhere
-# keeps the window open, so then it is never one-shot.
-function Test-PantheonOneShot([string[]]$CommandLine) {
+# keeps the window open, so then it is never one-shot. -OrFile also counts a
+# script run with -File (or -f): the window it was started from keeps its own
+# PATH, so the next command names the launcher by path there. Only for that
+# line: the script may be someone's own that runs this installer and goes on,
+# which `exit` would end.
+function Test-PantheonOneShot([string[]]$CommandLine, [switch]$OrFile) {
   $flags = @($CommandLine | Select-Object -Skip 1 | Where-Object { $_ -match '^(--?|/)[A-Za-z]+$' } |
     ForEach-Object { ($_ -replace '^(--?|/)', '').ToLowerInvariant() })
   $prefixOf = { param($f, $name, $min) $f.Length -ge $min -and $name.StartsWith($f) }
   if ($flags | Where-Object { & $prefixOf $_ 'noexit' 3 }) { return $false }
   foreach ($f in $flags) {
     if ((& $prefixOf $f 'command' 1) -or (& $prefixOf $f 'commandwithargs' 8) -or $f -eq 'cwa' -or
-      (& $prefixOf $f 'encodedcommand' 1) -or $f -eq 'ec') { return $true }
+      (& $prefixOf $f 'encodedcommand' 1) -or $f -eq 'ec' -or ($OrFile -and (& $prefixOf $f 'file' 1))) { return $true }
   }
   return $false
 }

package/installer/install.sh

@@ -541,7 +541,81 @@ add_block() {
   added="$added ${f#"$HOME"/}"
 }
 
-login_shell=$(basename "${SHELL:-sh}")
+# The shell this account logs in with: what a new terminal starts. $SHELL is
+# only the shell of whatever ran this installer, and an app or an agent passes
+# its own (/bin/sh) or none: on 6 Oct a new Mac (no ~/.zshrc yet) installed
+# from an agent got no zsh block, and a new Terminal said "pantheon: command
+# not found". So the account's own record first: macOS's directory (dscl),
+# Linux's passwd (getent, else /etc/passwd); $SHELL only when neither says.
+account_shell() {
+  me=$(id -un 2>/dev/null || printf '%s' "${USER:-}")
+  s=""
+  if [ -n "$me" ]; then
+    if [ "$node_os" = darwin ]; then
+      s=$(dscl . -read "/Users/$me" UserShell 2>/dev/null | sed -n 's/^UserShell:[[:space:]]*//p' | head -n 1 || true)
+    else
+      s=$(getent passwd "$me" 2>/dev/null | cut -d: -f7 || true)
+      [ -n "$s" ] || s=$(awk -F: -v u="$me" '$1 == u { print $7; exit }' /etc/passwd 2>/dev/null || true)
+    fi
+  fi
+  [ -n "$s" ] || s=${SHELL:-}
+  basename "${s:-sh}"
+}
+login_shell=$(account_shell)
+# zsh reads .zshrc and .zprofile from $ZDOTDIR when that is set (usually in
+# ~/.zshenv), not from HOME: asked of zsh itself, which reads ~/.zshenv as
+# every new zsh does. After a marker, so whatever .zshenv prints is not taken.
+# A .zshenv can wait for input (from the terminal, past a stdin of /dev/null)
+# or block outright, so zsh is asked in the background, into a file (a pipe a
+# leftover child kept open would wait with it), and killed after 5 s; then the
+# answer is this environment's $ZDOTDIR, else HOME. POSIX only: macOS has no
+# `timeout`. The watchdog's own output goes nowhere, so nothing waits on it.
+zdot=$HOME
+z=${ZDOTDIR:-}
+if command -v zsh >/dev/null 2>&1; then
+  : >"$TMP_DIR/zdotdir"
+  zsh -c 'printf "\n__pantheon_zdotdir__%s\n" "${ZDOTDIR:-}"' </dev/null >"$TMP_DIR/zdotdir" 2>/dev/null &
+  zsh_pid=$!
+  (sleep 5; : >"$TMP_DIR/zsh-slow"; kill -9 "$zsh_pid") </dev/null >/dev/null 2>&1 &
+  watch_pid=$!
+  wait "$zsh_pid" 2>/dev/null || true
+  kill "$watch_pid" 2>/dev/null || true
+  if grep -q '^__pantheon_zdotdir__' "$TMP_DIR/zdotdir" 2>/dev/null; then
+    z=$(sed -n 's/^__pantheon_zdotdir__//p' "$TMP_DIR/zdotdir" | tail -n 1)
+  elif [ -f "$TMP_DIR/zsh-slow" ]; then
+    note "zsh did not start within 5 seconds (something in ~/.zshenv waits), so its folder was taken from \$ZDOTDIR here, or the home folder"
+  fi
+fi
+# A folder's real path (cd ... && pwd -P); one not made yet is its nearest existing
+# parent's real path and the rest, which must then hold no . or .. to be judged.
+real_dir() {
+  rd=$1
+  rest=""
+  while [ -n "$rd" ] && [ "$rd" != / ] && [ ! -d "$rd" ]; do
+    rest="/$(basename "$rd")$rest"
+    rd=$(dirname "$rd")
+  done
+  case "$rest" in */. | */./* | */.. | */../*) return 1 ;; esac
+  rd=$(cd "$rd" 2>/dev/null && pwd -P) || return 1
+  printf '%s%s' "${rd%/}" "$rest"
+}
+# Only a folder inside HOME, by its real path: $HOME/../bob, or a link in HOME to
+# a folder elsewhere, is outside, and nothing is written outside the home folder.
+# Named under HOME as given, so the list of files changed reads as the person knows it.
+z=${z%/}
+if [ -n "$z" ] && [ "$z" != "$HOME" ]; then
+  zr=$(real_dir "$z" || true)
+  hr=$(real_dir "$HOME" || true)
+  [ -n "$hr" ] || hr=$HOME
+  case "$zr" in
+    "$hr"/?*) zdot="$HOME${zr#"$hr"}" ;;
+    *)
+      if [ "$zr" != "$hr" ]; then
+        note "zsh reads its startup files from $z (ZDOTDIR), outside your home folder, so nothing was written there; to have pantheon in new zsh terminals, put $BIN_DIR at the front of PATH in $z/.zshrc yourself"
+      fi
+      ;;
+  esac
+fi
 # ~/.profile: read by sh and dash logins, by bash when it has no .bash_profile or .bash_login,
 # and by the `sh -lc` Pantheon itself uses to find programs.
 add_block "$HOME/.profile"
@@ -549,11 +623,23 @@ add_block "$HOME/.profile"
 # bash logins read the first of .bash_profile, .bash_login and .profile: with
 # no .bash_profile, an existing .bash_login is the one read, not .profile.
 [ -f "$HOME/.bash_login" ] && add_block "$HOME/.bash_login"
+# An interactive bash that is not a login (most Linux terminals) reads only .bashrc.
 { [ -f "$HOME/.bashrc" ] || [ "$login_shell" = bash ]; } && add_block "$HOME/.bashrc"
-{ [ -f "$HOME/.zshrc" ] || [ "$login_shell" = zsh ]; } && add_block "$HOME/.zshrc"
-[ -f "$HOME/.zprofile" ] && add_block "$HOME/.zprofile"
+# zsh, login or not, reads .zshrc. A Mac's terminals start zsh unless the
+# person chose otherwise, and a new Mac has no .zshrc: there it is always
+# written (made when missing), whatever this installer was run from.
+if [ -f "$zdot/.zshrc" ] || [ "$login_shell" = zsh ] || [ "$node_os" = darwin ]; then
+  mkdir -p "$zdot" 2>/dev/null || true
+  add_block "$zdot/.zshrc"
+fi
+[ -f "$zdot/.zprofile" ] && add_block "$zdot/.zprofile"
+# With ZDOTDIR elsewhere, a block already in HOME's own zsh files is kept current.
+if [ "$zdot" != "$HOME" ]; then
+  [ -f "$HOME/.zshrc" ] && add_block "$HOME/.zshrc"
+  [ -f "$HOME/.zprofile" ] && add_block "$HOME/.zprofile"
+fi
 # fish reads its own conf.d folder; the file there is ours whole.
-if command -v fish >/dev/null 2>&1 || [ -d "$HOME/.config/fish" ]; then
+if command -v fish >/dev/null 2>&1 || [ -d "$HOME/.config/fish" ] || [ "$login_shell" = fish ]; then
   fish_conf="$HOME/.config/fish/conf.d/pantheon.fish"
   # shellcheck disable=SC2016 # written literally: fish expands it, not this script
   {
@@ -577,6 +663,28 @@ if [ -n "$other" ] && [ "$other" != "$LAUNCHER" ]; then
   note "another pantheon is installed at $other and was left as it is. New terminals run $LAUNCHER first."
 fi
 
+# The next command, for the terminal this was run from. That terminal read its
+# PATH before the profiles above changed, so unless pantheon already meant this
+# launcher there, the line names it by its full path; a new terminal finds it
+# by name. Quoted only where a shell needs it, so it reads as typed.
+shown() {
+  case "$1" in
+    "" | *[!A-Za-z0-9_./:=@%+,-]*) shq "$1" ;;
+    *) printf '%s' "$1" ;;
+  esac
+}
+if [ "$other" = "$LAUNCHER" ]; then PANTHEON_HERE="pantheon"; else PANTHEON_HERE=$(shown "$LAUNCHER"); fi
+next_line() {
+  line="$PANTHEON_HERE"
+  for a in "$@"; do line="$line $(shown "$a")"; done
+  printf '%s' "$line"
+}
+by_path_note() {
+  if [ "$PANTHEON_HERE" != "pantheon" ]; then
+    say "(This terminal was open before Pantheon was on your PATH, so that is its full path; a new terminal finds it as pantheon.)"
+  fi
+}
+
 # ---- 5. hand over to pantheon ----------------------------------------------
 
 rm -rf "$TMP_DIR"
@@ -586,9 +694,14 @@ trap - EXIT INT TERM HUP
 
 if [ "$#" -eq 0 ]; then
   say ""
-  say "Pantheon $PANTHEON_VERSION is installed. Open a new terminal (or run: export PATH=\"$BIN_DIR:\$PATH\"), then:"
-  say "  pantheon start                    create a team"
-  say "  pantheon join '<invite link>'     join a teammate's team"
+  say "Pantheon $PANTHEON_VERSION is installed. Next, in this terminal:"
+  start_line=$(next_line start)
+  join_line="$PANTHEON_HERE join '<invite link>'"
+  # The start line padded to the join line's width, so the descriptions line up.
+  while [ "${#start_line}" -lt "${#join_line}" ]; do start_line="$start_line "; done
+  say "  $start_line     create a team"
+  say "  $join_line     join a teammate's team"
+  by_path_note
   exit 0
 fi
 
@@ -596,12 +709,32 @@ say ""
 # Found first by anything pantheon starts during setup, before any new terminal.
 PATH="$BIN_DIR:$PATH"
 export PATH
+# Once pantheon has done what was asked, the last line is the next command for
+# this terminal. Not exec, so there is a last line; Ctrl-C still reaches
+# pantheon (a trap is reset in a child, where an ignored signal would not be)
+# and this shell waits for it rather than dying first.
+finish() {
+  if [ "$1" -eq 0 ]; then
+    say ""
+    say "Next, in this terminal: $(next_line doctor)   (checks that everything works)"
+    by_path_note
+  fi
+  exit "$1"
+}
 # stdin is the curl pipe; sign-in and setup questions must come from the
 # keyboard.
 if (: </dev/tty) 2>/dev/null; then
-  exec "$LAUNCHER" "$@" </dev/tty
+  trap ':' INT
+  code=0
+  "$LAUNCHER" "$@" </dev/tty || code=$?
+  finish "$code"
+fi
+if [ -t 0 ]; then
+  trap ':' INT
+  code=0
+  "$LAUNCHER" "$@" || code=$?
+  finish "$code"
 fi
-if [ -t 0 ]; then exec "$LAUNCHER" "$@"; fi
 
 # No terminal at all: CI, a pipe, some IDE task runners. pantheon still runs,
 # because it never asks a question without one (every prompt checks
@@ -629,14 +762,10 @@ if [ "$code" -ne 0 ] && [ -n "$said" ] && grep -qE 'sign in first|NOT_SIGNED_IN'
     join | start)
       cfg="${PANTHEON_HOME:-$HOME/.pantheon}/config.json"
       if ! "$NODE" -e 'try { process.exit(JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).account ? 0 : 1) } catch { process.exit(1) }' "$cfg" 2>/dev/null; then
-        line="pantheon"
-        # Quoted only where a shell needs it, so it reads as the person typed it.
-        for a in "$@"; do
-          case "$a" in
-            "" | *[!A-Za-z0-9_./:=@%+,-]*) line="$line $(shq "$a")" ;;
-            *) line="$line $a" ;;
-          esac
-        done
+        # By its full path: whatever runs it next (an agent's shell, a terminal
+        # opened before this install) may not have the new PATH yet.
+        line=$(shown "$LAUNCHER")
+        for a in "$@"; do line="$line $(shown "$a")"; done
         if [ "$1" = join ]; then what="joining"; else what="creating your team"; fi
         printf '\nPantheon is installed. To finish %s, open a terminal and run: %s\n' "$what" "$line" >&2
       fi
@@ -644,4 +773,4 @@ if [ "$code" -ne 0 ] && [ -n "$said" ] && grep -qE 'sign in first|NOT_SIGNED_IN'
   esac
 fi
 if [ -n "$said" ]; then rm -f "$said" "$said.code"; fi
-exit "$code"
+finish "$code"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@join-pantheon/cli",
-  "version": "0.33.1",
+  "version": "0.33.2",
   "description": "Let your coding agent collaborate directly with your teammates' agents — ask, agree an interface, and deliver, without a human relaying messages.",
   "type": "module",
   "bin": {

package/helper/macos/prebuilt/manifest.json

@@ -1,29 +0,0 @@
-{
-  "format": 1,
-  "built_at": "2026-10-05T17:23:08.044Z",
-  "swiftc": "Apple Swift version 6.3.3 (swiftlang-6.3.3.1.3 clang-2100.1.1.101)",
-  "helpers": {
-    "pantheon-tray": {
-      "source": "menubar.swift",
-      "source_sha256": "f079629099a81f9b679ef4133d897ceb09025f675099c5f941951604df3531fa",
-      "sha256": "cc081120555f528c83b38951663d37e8394e3a3e119a19b0bb3b2a737f4d617f",
-      "archs": [
-        "arm64",
-        "x86_64"
-      ],
-      "target": "macos11",
-      "version": "2"
-    },
-    "pantheon-hud": {
-      "source": "main.swift",
-      "source_sha256": "bcf55a19b658d1f09a9d117c76030393ab08a2569062dd7413f884ca05f3a0eb",
-      "sha256": "191f3f18e8212e11ad4438bdbef87a5cc533f5ae2fae208801db01c9a265193b",
-      "archs": [
-        "arm64",
-        "x86_64"
-      ],
-      "target": "macos11",
-      "version": "4"
-    }
-  }
-}