@geekbeer/minion 2.23.0 → 2.32.0

package/win/minion-cli.ps1

@@ -0,0 +1,869 @@
+#Requires -Version 5.1
+# Minion Agent CLI for Windows (@geekbeer/minion)
+# Usage:
+#   minion-cli-win setup --hq-url https://... --minion-id <UUID> --api-token <TOKEN>
+#   minion-cli-win setup --setup-tunnel
+#   minion-cli-win start | stop | restart | status | health | version | help
+
+# Parse arguments manually to avoid issues with npm wrapper passing $args as array
+$Command = 'help'
+$HqUrl = ''
+$MinionId = ''
+$ApiToken = ''
+$SetupTunnel = $false
+
+$i = 0
+while ($i -lt $args.Count) {
+    $arg = [string]$args[$i]
+    switch -Regex ($arg) {
+        '^(setup|reconfigure|start|stop|restart|status|health|version|help)$' { $Command = $arg }
+        '^(-v|--version)$' { $Command = 'version' }
+        '^--hq-url$' { $i++; if ($i -lt $args.Count) { $HqUrl = [string]$args[$i] } }
+        '^--minion-id$' { $i++; if ($i -lt $args.Count) { $MinionId = [string]$args[$i] } }
+        '^--api-token$' { $i++; if ($i -lt $args.Count) { $ApiToken = [string]$args[$i] } }
+        '^--setup-tunnel$' { $SetupTunnel = $true }
+        '^(-h|--help)$' { $Command = 'help' }
+    }
+    $i++
+}
+
+$ErrorActionPreference = 'Stop'
+
+# Constants
+$DataDir = Join-Path $env:USERPROFILE '.minion'
+$EnvFile = Join-Path $DataDir '.env'
+$PidFile = Join-Path $DataDir 'minion-agent.pid'
+$LogDir = Join-Path $DataDir 'logs'
+$StartAgentScript = Join-Path $DataDir 'start-agent.ps1'
+$AgentUrl = if ($env:MINION_AGENT_URL) { $env:MINION_AGENT_URL } else { 'http://localhost:8080' }
+
+# Resolve CLI version from package.json
+$CliDir = Split-Path -Parent $PSScriptRoot
+$CliVersion = try {
+    (Get-Content (Join-Path $CliDir 'package.json') -Raw | ConvertFrom-Json).version
+}
+catch { 'unknown' }
+
+# ============================================================
+# Utility functions
+# ============================================================
+
+function Write-Step {
+    param([int]$Current, [int]$Total, [string]$Message)
+    Write-Host "[$Current/$Total] $Message" -ForegroundColor Cyan
+}
+
+function Write-Detail {
+    param([string]$Message)
+    Write-Host "  -> $Message" -ForegroundColor Green
+}
+
+function Write-Warn {
+    param([string]$Message)
+    Write-Host "  WARNING: $Message" -ForegroundColor Yellow
+}
+
+function Test-CommandExists {
+    param([string]$Name)
+    $null -ne (Get-Command $Name -ErrorAction SilentlyContinue)
+}
+
+function Get-LanIPAddress {
+    try {
+        $ip = (Get-NetIPAddress -AddressFamily IPv4 -ErrorAction SilentlyContinue |
+            Where-Object {
+                ($_.PrefixOrigin -eq 'Dhcp' -or $_.PrefixOrigin -eq 'Manual') -and
+                $_.IPAddress -notlike '169.254.*' -and
+                $_.IPAddress -ne '127.0.0.1' -and
+                $_.InterfaceAlias -notlike 'vEthernet*'
+            } |
+            Select-Object -First 1).IPAddress
+        return $ip
+    }
+    catch { return $null }
+}
+
+function Get-MinionServerJs {
+    $npmRoot = & npm root -g 2>$null
+    return Join-Path $npmRoot '@geekbeer\minion\win\server.js'
+}
+
+function Read-EnvFile {
+    param([string]$Path)
+    $result = @{}
+    if (-not (Test-Path $Path)) { return $result }
+    Get-Content $Path | ForEach-Object {
+        $line = $_.Trim()
+        if ($line -and -not $line.StartsWith('#') -and $line.Contains('=')) {
+            $idx = $line.IndexOf('=')
+            $key = $line.Substring(0, $idx).Trim()
+            $value = $line.Substring($idx + 1).Trim()
+            $result[$key] = $value
+        }
+    }
+    return $result
+}
+
+function Write-EnvFile {
+    param([string]$Path, [hashtable]$Values)
+    $lines = @(
+        '# Minion Agent Configuration',
+        '# Generated by minion-cli.ps1 setup',
+        ''
+    )
+    foreach ($key in ($Values.Keys | Sort-Object)) {
+        $lines += "$key=$($Values[$key])"
+    }
+    $lines += ''
+    New-Item -Path (Split-Path $Path) -ItemType Directory -Force | Out-Null
+    Set-Content -Path $Path -Value ($lines -join "`n") -Encoding UTF8 -NoNewline
+}
+
+function Invoke-HealthCheck {
+    param([int]$Retries = 5, [int]$DelaySeconds = 2)
+    for ($i = 1; $i -le $Retries; $i++) {
+        try {
+            $response = Invoke-RestMethod -Uri "$AgentUrl/api/health" -TimeoutSec 5 -ErrorAction Stop
+            if ($response) { return $true }
+        }
+        catch { }
+        Write-Host "  Waiting for agent to start... (attempt $i/$Retries)"
+        Start-Sleep -Seconds $DelaySeconds
+    }
+    return $false
+}
+
+function Start-MinionProcess {
+    # Check if already running via PID file
+    if (Test-Path $PidFile) {
+        $existingPid = (Get-Content $PidFile -Raw).Trim()
+        $proc = Get-Process -Id $existingPid -ErrorAction SilentlyContinue
+        if ($proc) {
+            Write-Host "minion-agent is already running (PID: $existingPid)"
+            return
+        }
+        Remove-Item $PidFile -Force
+    }
+
+    if (-not (Test-Path $StartAgentScript)) {
+        Write-Error "start-agent.ps1 not found. Run 'minion-cli-win setup' first."
+        exit 1
+    }
+
+    # Launch start-agent.ps1 as a hidden background process
+    Start-Process powershell -ArgumentList "-ExecutionPolicy Bypass -WindowStyle Hidden -File `"$StartAgentScript`"" `
+        -WindowStyle Hidden
+    Start-Sleep -Seconds 2
+
+    if (Test-Path $PidFile) {
+        $newPid = (Get-Content $PidFile -Raw).Trim()
+        Write-Host "minion-agent started (PID: $newPid)"
+    } else {
+        Write-Host "minion-agent starting... (check logs at $LogDir)"
+    }
+}
+
+function Stop-MinionProcess {
+    if (-not (Test-Path $PidFile)) {
+        Write-Host "minion-agent is not running (no PID file)"
+        return
+    }
+    $agentPid = (Get-Content $PidFile -Raw).Trim()
+    $proc = Get-Process -Id $agentPid -ErrorAction SilentlyContinue
+    if ($proc) {
+        # Also stop child processes (node, websockify, cloudflared)
+        Get-CimInstance Win32_Process -Filter "ParentProcessId = $agentPid" -ErrorAction SilentlyContinue |
+            ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }
+        Stop-Process -Id $agentPid -Force
+        Write-Host "minion-agent stopped (PID: $agentPid)"
+    } else {
+        Write-Host "minion-agent was not running (stale PID file)"
+    }
+    Remove-Item $PidFile -Force -ErrorAction SilentlyContinue
+}
+
+function Restart-MinionProcess {
+    Stop-MinionProcess
+    Start-Sleep -Seconds 2
+    Start-MinionProcess
+}
+
+# ============================================================
+# Setup
+# ============================================================
+
+function Invoke-Setup {
+    $totalSteps = 8
+    if ($SetupTunnel) { $totalSteps = 9 }
+
+    # Minionization warning
+    Write-Host ""
+    Write-Host "=========================================" -ForegroundColor Red
+    Write-Host " WARNING: This machine will be minionized" -ForegroundColor Red
+    Write-Host "=========================================" -ForegroundColor Red
+    Write-Host ""
+
+    # Check if current user is in Administrators group
+    $adminGroupMembers = net localgroup Administrators 2>$null
+    if ($adminGroupMembers -match [regex]::Escape($env:USERNAME)) {
+        Write-Host "  SECURITY WARNING: User '$env:USERNAME' has Administrator privileges." -ForegroundColor Yellow
+        Write-Host "  We recommend setting up the minion under a Standard user account." -ForegroundColor Yellow
+        Write-Host "  If this machine is compromised, an Administrator account gives" -ForegroundColor Yellow
+        Write-Host "  the attacker full control over the system." -ForegroundColor Yellow
+        Write-Host ""
+        Write-Host "  To create a Standard user:" -ForegroundColor Gray
+        Write-Host "    net user minion <password> /add" -ForegroundColor Gray
+        Write-Host "  Then log in as that user and run setup again." -ForegroundColor Gray
+        Write-Host ""
+    }
+
+    Write-Host "  This setup will:" -ForegroundColor Yellow
+    Write-Host "    - Install and configure software (Node.js, Claude Code)"
+    Write-Host "    - Register auto-start via Startup folder"
+    Write-Host "    - Overwrite Claude Code settings (permissions, rules, skills)"
+    Write-Host ""
+    Write-Host "  This machine should be DEDICATED to the minion agent." -ForegroundColor Yellow
+    Write-Host "  Do not use it as your daily workstation after setup." -ForegroundColor Yellow
+    Write-Host ""
+    $confirm = Read-Host "  Type 'yes' to continue"
+    if ($confirm -ne 'yes') {
+        Write-Host "Setup cancelled."
+        exit 0
+    }
+    Write-Host ""
+
+    # Load existing .env for redeploy scenario
+    $envValues = @{}
+    if (-not $HqUrl -and -not $MinionId -and -not $ApiToken -and (Test-Path $EnvFile)) {
+        Write-Host "Reading existing .env values (redeploy mode)..."
+        $envValues = Read-EnvFile $EnvFile
+        if (-not $HqUrl -and $envValues['HQ_URL']) { $HqUrl = $envValues['HQ_URL'] }
+        if (-not $MinionId -and $envValues['MINION_ID']) { $MinionId = $envValues['MINION_ID'] }
+        if (-not $ApiToken -and $envValues['API_TOKEN']) { $ApiToken = $envValues['API_TOKEN'] }
+    }
+
+    Write-Host "=========================================" -ForegroundColor Cyan
+    Write-Host " @geekbeer/minion Windows Setup" -ForegroundColor Cyan
+    Write-Host "=========================================" -ForegroundColor Cyan
+    Write-Host "Platform: Windows (no admin required)"
+    Write-Host "User: $env:USERNAME ($env:USERPROFILE)"
+    Write-Host "Data: $DataDir"
+    if ($HqUrl) {
+        Write-Host "Mode: Connected to HQ ($HqUrl)"
+    }
+    else {
+        Write-Host "Mode: Standalone (no HQ connection)"
+    }
+    if ($SetupTunnel) { Write-Host "Tunnel: Enabled" }
+    Write-Host ""
+
+    # Step 1: Check/Install Node.js
+    Write-Step 1 $totalSteps "Checking Node.js..."
+    if (Test-CommandExists 'node') {
+        $nodeVersion = & node --version 2>$null
+        Write-Detail "Node.js $nodeVersion already installed"
+    }
+    else {
+        Write-Host "  Installing Node.js via winget..."
+        try {
+            & winget install --id OpenJS.NodeJS.LTS --accept-package-agreements --accept-source-agreements
+            # Refresh PATH
+            $env:PATH = [System.Environment]::GetEnvironmentVariable('PATH', 'Machine') + ';' + [System.Environment]::GetEnvironmentVariable('PATH', 'User')
+            if (Test-CommandExists 'node') {
+                Write-Detail "Node.js installed successfully"
+            }
+            else {
+                Write-Warn "Node.js installed but not in PATH. Please restart this terminal."
+                exit 1
+            }
+        }
+        catch {
+            Write-Error "Failed to install Node.js. Please install manually from https://nodejs.org/"
+            exit 1
+        }
+    }
+
+    # Step 2: Install Claude Code CLI
+    Write-Step 2 $totalSteps "Installing Claude Code..."
+    if (Test-CommandExists 'claude') {
+        $claudeVersion = & claude --version 2>$null
+        Write-Detail "Claude Code already installed ($claudeVersion)"
+    }
+    else {
+        Write-Host "  Installing Claude Code via npm..."
+        & npm install -g @anthropic-ai/claude-code
+        if (Test-CommandExists 'claude') {
+            Write-Detail "Claude Code installed successfully"
+        }
+        else {
+            Write-Warn "Claude Code installation may have failed"
+            Write-Host "  You can install manually: npm install -g @anthropic-ai/claude-code"
+        }
+    }
+    Write-Host ""
+    Write-Host "  IMPORTANT: Claude Code requires authentication." -ForegroundColor Yellow
+    Write-Host "  Please run 'claude' in a terminal to complete the authentication process." -ForegroundColor Yellow
+    Write-Host ""
+
+    # Step 3: Create config directory and .env
+    Write-Step 3 $totalSteps "Creating config directory and .env..."
+    New-Item -Path $DataDir -ItemType Directory -Force | Out-Null
+    New-Item -Path $LogDir -ItemType Directory -Force | Out-Null
+    $envValues = @{
+        'AGENT_PORT'         = '8080'
+        'HEARTBEAT_INTERVAL' = '30'
+        'MINION_USER'        = $env:USERNAME
+    }
+    if ($HqUrl) { $envValues['HQ_URL'] = $HqUrl }
+    if ($ApiToken) { $envValues['API_TOKEN'] = $ApiToken }
+    if ($MinionId) { $envValues['MINION_ID'] = $MinionId }
+    Write-EnvFile $EnvFile $envValues
+    Write-Detail "$EnvFile generated"
+
+    # Step 4: Install node-pty (required for Windows terminal management)
+    Write-Step 4 $totalSteps "Installing terminal support (node-pty)..."
+    $npmRoot = & npm root -g 2>$null
+    $minionPkgDir = Join-Path $npmRoot '@geekbeer\minion'
+    if (Test-Path $minionPkgDir) {
+        Push-Location $minionPkgDir
+        $ptyInstalled = $false
+
+        # Try prebuilt version first (no Build Tools required)
+        try {
+            & npm install node-pty-prebuilt-multiarch 2>$null
+            Write-Detail "node-pty-prebuilt-multiarch installed (no Build Tools needed)"
+            $ptyInstalled = $true
+        } catch {}
+
+        # Fallback: source-compiled version (requires Visual Studio Build Tools)
+        if (-not $ptyInstalled) {
+            try {
+                & npm install node-pty 2>$null
+                Write-Detail "node-pty installed (compiled from source)"
+                $ptyInstalled = $true
+            } catch {}
+        }
+
+        if (-not $ptyInstalled) {
+            Write-Warn "node-pty installation failed. Terminal/workflow features may not work."
+            Write-Host "  Try manually: cd $minionPkgDir && npm install node-pty-prebuilt-multiarch"
+        }
+        Pop-Location
+    }
+    else {
+        Write-Warn "Minion package not found at $minionPkgDir"
+        Write-Host "  Please run: npm install -g @geekbeer/minion"
+    }
+
+    # Step 5: Generate start-agent.ps1 and register auto-start
+    Write-Step 5 $totalSteps "Registering auto-start..."
+    $serverJs = Join-Path $minionPkgDir 'win\server.js'
+    if (-not (Test-Path $serverJs)) {
+        $serverJs = Join-Path $minionPkgDir 'win' 'server.js'
+    }
+    if (-not (Test-Path $serverJs)) {
+        Write-Error "server.js not found at $serverJs"
+        Write-Host "  Please run: npm install -g @geekbeer/minion"
+        exit 1
+    }
+
+    # Generate start-agent.ps1 (watchdog script)
+    $startAgentContent = @"
+# Auto-generated by minion-cli-win setup
+# Starts minion agent with watchdog (auto-restart on crash)
+
+`$DataDir = '$DataDir'
+`$EnvFile = Join-Path `$DataDir '.env'
+`$PidFile = Join-Path `$DataDir 'minion-agent.pid'
+`$LogDir = Join-Path `$DataDir 'logs'
+`$ServerJs = '$serverJs'
+
+# Load .env
+if (Test-Path `$EnvFile) {
+    Get-Content `$EnvFile | ForEach-Object {
+        `$line = `$_.Trim()
+        if (`$line -and -not `$line.StartsWith('#') -and `$line.Contains('=')) {
+            `$idx = `$line.IndexOf('=')
+            `$key = `$line.Substring(0, `$idx).Trim()
+            `$value = `$line.Substring(`$idx + 1).Trim()
+            [Environment]::SetEnvironmentVariable(`$key, `$value, 'Process')
+        }
+    }
+}
+
+New-Item -Path `$LogDir -ItemType Directory -Force | Out-Null
+
+# Write PID of this watchdog process
+Set-Content -Path `$PidFile -Value `$PID
+
+# Start TightVNC + websockify if available
+`$vncExe = `$null
+if (Test-Path 'C:\Program Files\TightVNC\tvnserver.exe') {
+    `$vncExe = 'C:\Program Files\TightVNC\tvnserver.exe'
+} elseif (Test-Path (Join-Path `$DataDir 'tightvnc\PFiles\TightVNC\tvnserver.exe')) {
+    `$vncExe = Join-Path `$DataDir 'tightvnc\PFiles\TightVNC\tvnserver.exe'
+}
+if (`$vncExe) {
+    # Start VNC server in application mode (no admin, no service registration)
+    `$vncProc = Get-Process -Name tvnserver -ErrorAction SilentlyContinue
+    if (-not `$vncProc) {
+        Start-Process -FilePath `$vncExe -ArgumentList '-run' -WindowStyle Hidden
+        # Wait for VNC server to bind port 5900 before starting websockify
+        Start-Sleep -Seconds 3
+    }
+    # Reload registry config (ensures no-auth settings are applied)
+    & `$vncExe -controlapp -reload 2>`$null
+    if (Get-Command websockify -ErrorAction SilentlyContinue) {
+        `$wsProc = Get-Process -Name websockify -ErrorAction SilentlyContinue
+        if (-not `$wsProc) {
+            Start-Process -FilePath (Get-Command websockify).Source -ArgumentList '6080', 'localhost:5900' -WindowStyle Hidden
+        }
+    }
+}
+
+# Start cloudflared tunnel if configured
+`$cfConfig = Join-Path `$env:USERPROFILE '.cloudflared\config.yml'
+if ((Test-Path `$cfConfig) -and (Get-Command cloudflared -ErrorAction SilentlyContinue)) {
+    Start-Process -FilePath (Get-Command cloudflared).Source -ArgumentList 'tunnel', 'run' -WindowStyle Hidden
+}
+
+# Watchdog loop: restart node if it crashes
+`$nodePath = (Get-Command node).Source
+while (`$true) {
+    `$stdoutLog = Join-Path `$LogDir 'service-stdout.log'
+    `$stderrLog = Join-Path `$LogDir 'service-stderr.log'
+    `$proc = Start-Process -FilePath `$nodePath -ArgumentList `$ServerJs ``
+        -WorkingDirectory `$DataDir ``
+        -RedirectStandardOutput `$stdoutLog ``
+        -RedirectStandardError `$stderrLog ``
+        -WindowStyle Hidden -PassThru
+    `$proc.WaitForExit()
+    if (`$proc.ExitCode -eq 0) { break }
+    Start-Sleep -Seconds 5
+}
+
+# Cleanup PID file on normal exit
+Remove-Item `$PidFile -Force -ErrorAction SilentlyContinue
+"@
+    Set-Content -Path $StartAgentScript -Value $startAgentContent -Encoding UTF8
+    Write-Detail "Generated $StartAgentScript"
+
+    # Create shortcut in Startup folder
+    $startupDir = [Environment]::GetFolderPath('Startup')
+    $shortcutPath = Join-Path $startupDir 'MinionAgent.lnk'
+    $wsShell = New-Object -ComObject WScript.Shell
+    $shortcut = $wsShell.CreateShortcut($shortcutPath)
+    $shortcut.TargetPath = 'powershell.exe'
+    $shortcut.Arguments = "-ExecutionPolicy Bypass -WindowStyle Hidden -File `"$StartAgentScript`""
+    $shortcut.WorkingDirectory = $DataDir
+    $shortcut.WindowStyle = 7  # Minimized
+    $shortcut.Description = 'Minion Agent auto-start'
+    $shortcut.Save()
+    Write-Detail "Startup shortcut created: $shortcutPath"
+
+    # Step 6: Install TightVNC Server
+    Write-Step 6 $totalSteps "Setting up TightVNC Server..."
+    $vncSystemPath = 'C:\Program Files\TightVNC\tvnserver.exe'
+    $vncPortableDir = Join-Path $DataDir 'tightvnc'
+    $vncPortablePath = Join-Path $vncPortableDir 'PFiles\TightVNC\tvnserver.exe'
+
+    if (Test-Path $vncSystemPath) {
+        Write-Detail "TightVNC Server already installed (system)"
+    }
+    elseif (Test-Path $vncPortablePath) {
+        Write-Detail "TightVNC Server already installed (portable)"
+    }
+    else {
+        Write-Host "  Downloading TightVNC portable..."
+        try {
+            $msiUrl = 'https://www.tightvnc.com/download/2.8.85/tightvnc-2.8.85-gpl-setup-64bit.msi'
+            $msiPath = Join-Path $env:TEMP 'tightvnc-setup.msi'
+            Invoke-WebRequest -Uri $msiUrl -OutFile $msiPath -UseBasicParsing
+            New-Item -Path $vncPortableDir -ItemType Directory -Force | Out-Null
+            # Extract MSI without admin (administrative install = extract only)
+            # Creates PFiles\TightVNC\ subdirectory structure
+            Start-Process msiexec -ArgumentList "/a `"$msiPath`" /qn TARGETDIR=`"$vncPortableDir`"" -Wait -NoNewWindow
+            Remove-Item $msiPath -Force -ErrorAction SilentlyContinue
+            if (Test-Path $vncPortablePath) {
+                Write-Detail "TightVNC portable extracted to $vncPortableDir"
+            } else {
+                Write-Warn "TightVNC extraction failed. Check $vncPortableDir"
+            }
+        }
+        catch {
+            Write-Warn "Failed to download TightVNC: $_"
+            Write-Host "  Manual download: https://www.tightvnc.com/download.php" -ForegroundColor Gray
+        }
+    }
+
+    # Configure TightVNC for no-auth localhost-only mode via registry
+    # - LoopbackOnly=1: only accept connections from localhost (security)
+    # - AllowLoopback=1: enable loopback connections
+    # - UseVncAuthentication=0: no password prompt (websockify connects via localhost,
+    #   HQ WebSocket proxy provides its own Supabase session authentication)
+    $vncRegPath = 'HKCU:\Software\TightVNC\Server'
+    if ((Test-Path $vncSystemPath) -or (Test-Path $vncPortablePath)) {
+        if (-not (Test-Path $vncRegPath)) {
+            New-Item -Path $vncRegPath -Force | Out-Null
+        }
+        Set-ItemProperty -Path $vncRegPath -Name 'LoopbackOnly' -Value 1 -Type DWord
+        Set-ItemProperty -Path $vncRegPath -Name 'AllowLoopback' -Value 1 -Type DWord
+        Set-ItemProperty -Path $vncRegPath -Name 'UseVncAuthentication' -Value 0 -Type DWord
+        Set-ItemProperty -Path $vncRegPath -Name 'UseControlAuthentication' -Value 0 -Type DWord
+        Set-ItemProperty -Path $vncRegPath -Name 'RfbPort' -Value 5900 -Type DWord
+        # Reload config if tvnserver is already running (re-setup scenario)
+        $vncProc = Get-Process -Name tvnserver -ErrorAction SilentlyContinue
+        if ($vncProc) {
+            $vncExePath = if (Test-Path $vncSystemPath) { $vncSystemPath } else { $vncPortablePath }
+            & $vncExePath -controlapp -reload 2>$null
+            Write-Detail "TightVNC config reloaded"
+        }
+        Write-Detail "TightVNC configured: localhost-only, no VNC password (auth via HQ proxy)"
+    }
+
+    # Step 7: Setup websockify (WebSocket proxy for VNC)
+    Write-Step 7 $totalSteps "Setting up websockify..."
+    if (Test-CommandExists 'websockify') {
+        Write-Detail "websockify already installed"
+    }
+    else {
+        # Ensure Python is installed (Microsoft Store stub doesn't include pip)
+        $pythonUsable = $false
+        if (Test-CommandExists 'python') {
+            $pyVer = & python --version 2>&1
+            # Microsoft Store stub returns just "Python" with no version number
+            if ($pyVer -match '\d+\.\d+') { $pythonUsable = $true }
+        }
+        if (-not $pythonUsable) {
+            Write-Host "  Python not found. Installing via winget..."
+            try {
+                & winget install --id Python.Python.3.12 --accept-package-agreements --accept-source-agreements
+                $env:PATH = [System.Environment]::GetEnvironmentVariable('PATH', 'Machine') + ';' + [System.Environment]::GetEnvironmentVariable('PATH', 'User')
+                Write-Detail "Python installed"
+            }
+            catch {
+                Write-Warn "Failed to install Python: $_"
+                Write-Host "  Install manually: winget install Python.Python.3.12"
+            }
+        }
+
+        Write-Host "  Installing websockify via pip..."
+        try {
+            if (Test-CommandExists 'pip') {
+                & pip install websockify 2>$null
+                Write-Detail "websockify installed"
+            }
+            elseif (Test-CommandExists 'pip3') {
+                & pip3 install websockify 2>$null
+                Write-Detail "websockify installed"
+            }
+            elseif (Test-CommandExists 'python') {
+                & python -m pip install websockify 2>$null
+                Write-Detail "websockify installed (via python -m pip)"
+            }
+            else {
+                Write-Warn "pip not found. Install Python first, then: pip install websockify"
+            }
+        }
+        catch {
+            Write-Warn "Failed to install websockify: $_"
+        }
+    }
+
+    # Step 8 (optional): Cloudflare Tunnel
+    if ($SetupTunnel) {
+        $currentStep = $totalSteps - 1
+        Write-Step $currentStep $totalSteps "Setting up Cloudflare Tunnel..."
+
+        if (-not $HqUrl -or -not $ApiToken) {
+            Write-Error "--setup-tunnel requires --hq-url and --api-token"
+            exit 1
+        }
+
+        # Install cloudflared
+        if (-not (Test-CommandExists 'cloudflared')) {
+            Write-Host "  Installing cloudflared..."
+            if (Test-CommandExists 'winget') {
+                & winget install --id Cloudflare.cloudflared --accept-package-agreements --accept-source-agreements
+                $env:PATH = [System.Environment]::GetEnvironmentVariable('PATH', 'Machine') + ';' + [System.Environment]::GetEnvironmentVariable('PATH', 'User')
+            }
+            elseif (Test-CommandExists 'choco') {
+                & choco install cloudflared -y
+            }
+            else {
+                Write-Host "  Downloading cloudflared..."
+                $cfUrl = 'https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.exe'
+                $cfPath = Join-Path $DataDir 'cloudflared.exe'
+                Invoke-WebRequest -Uri $cfUrl -OutFile $cfPath
+                Write-Detail "cloudflared downloaded to $cfPath"
+            }
+        }
+        else {
+            Write-Detail "cloudflared already installed"
+        }
+
+        # Fetch tunnel config from HQ
+        Write-Host "  Fetching tunnel configuration from HQ..."
+        try {
+            $headers = @{ 'Authorization' = "Bearer $ApiToken" }
+            $tunnelData = Invoke-RestMethod -Uri "$HqUrl/api/minion/tunnel-credentials" -Headers $headers
+
+            if ($tunnelData.tunnel_id) {
+                $cfConfigDir = Join-Path $env:USERPROFILE '.cloudflared'
+                New-Item -Path $cfConfigDir -ItemType Directory -Force | Out-Null
+
+                # Save credentials
+                $tunnelData.credentials_json | Set-Content (Join-Path $cfConfigDir "$($tunnelData.tunnel_id).json") -Encoding UTF8
+                Write-Detail "Tunnel credentials saved"
+
+                # Save config
+                $tunnelData.config_yml | Set-Content (Join-Path $cfConfigDir 'config.yml') -Encoding UTF8
+                Write-Detail "Tunnel config saved (will run as user process on start)"
+            }
+            else {
+                Write-Warn "Tunnel not configured for this minion"
+            }
+        }
+        catch {
+            Write-Warn "Failed to fetch tunnel credentials: $_"
+        }
+    }
+
+    # Deploy bundled skills
+    Write-Host ""
+    Write-Host "Deploying bundled assets..."
+    $claudeSkillsDir = Join-Path $env:USERPROFILE '.claude\skills'
+    $bundledSkillsDir = Join-Path $minionPkgDir 'skills'
+    if (Test-Path $bundledSkillsDir) {
+        New-Item -Path $claudeSkillsDir -ItemType Directory -Force | Out-Null
+        Get-ChildItem -Path $bundledSkillsDir -Directory | ForEach-Object {
+            Copy-Item $_.FullName -Destination (Join-Path $claudeSkillsDir $_.Name) -Recurse -Force
+            Write-Detail "Deployed skill: $($_.Name)"
+        }
+    }
+
+    # Deploy bundled rules
+    $claudeRulesDir = Join-Path $env:USERPROFILE '.claude\rules'
+    $bundledRulesDir = Join-Path $minionPkgDir 'rules'
+    if (Test-Path $bundledRulesDir) {
+        New-Item -Path $claudeRulesDir -ItemType Directory -Force | Out-Null
+        $coreRule = Join-Path $bundledRulesDir 'core.md'
+        if (Test-Path $coreRule) {
+            Copy-Item $coreRule -Destination (Join-Path $claudeRulesDir 'core.md') -Force
+            Write-Detail "Deployed rules: core.md"
+        }
+    }
+
+    # Start (or restart) agent so updated .env takes effect
+    Write-Step $totalSteps $totalSteps "Starting agent..."
+    Restart-MinionProcess
+
+    # Health check
+    if (Invoke-HealthCheck) {
+        Write-Detail "Health check passed"
+    }
+    else {
+        Write-Warn "Health check failed after 5 attempts"
+        Write-Host "  Check logs at: $LogDir"
+    }
+
+    # Firewall notice
+    Write-Host ""
+    Write-Host "NOTE: Firewall rules are NOT configured automatically (requires admin)." -ForegroundColor Yellow
+    Write-Host "  If you need LAN access without Cloudflare Tunnel, ask an administrator to run:" -ForegroundColor Yellow
+    Write-Host "    New-NetFirewallRule -DisplayName 'Minion Agent' -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow" -ForegroundColor Gray
+    Write-Host "    New-NetFirewallRule -DisplayName 'Minion Terminal' -Direction Inbound -Protocol TCP -LocalPort 7681 -Action Allow" -ForegroundColor Gray
+    Write-Host "    New-NetFirewallRule -DisplayName 'Minion VNC' -Direction Inbound -Protocol TCP -LocalPort 6080 -Action Allow" -ForegroundColor Gray
+    Write-Host "  Or use Cloudflare Tunnel (--setup-tunnel) to avoid firewall configuration." -ForegroundColor Yellow
+
+    # Notify HQ
+    if ($HqUrl -and $ApiToken) {
+        Write-Host ""
+        Write-Host "Notifying HQ of setup completion..."
+        try {
+            $lanIp = Get-LanIPAddress
+            $headers = @{
+                'Authorization' = "Bearer $ApiToken"
+                'Content-Type'  = 'application/json'
+            }
+            $bodyHash = @{}
+            if ($lanIp) {
+                $bodyHash['ip_address'] = $lanIp
+                $bodyHash['internal_ip_address'] = $lanIp
+            } else {
+                $bodyHash['internal_ip_address'] = [System.Net.Dns]::GetHostName()
+            }
+            $body = $bodyHash | ConvertTo-Json
+            Invoke-RestMethod -Uri "$HqUrl/api/minion/setup-complete" -Method Post -Headers $headers -Body $body -ErrorAction Stop | Out-Null
+            if ($lanIp) {
+                Write-Detail "HQ notified successfully (LAN IP: $lanIp)"
+            } else {
+                Write-Detail "HQ notified successfully (LAN IP detection failed, hostname sent)"
+            }
+        }
+        catch {
+            Write-Detail "HQ notification skipped (HQ may not be reachable)"
+        }
+    }
+
+    Write-Host ""
+    Write-Host "=========================================" -ForegroundColor Green
+    Write-Host " Setup Complete!" -ForegroundColor Green
+    Write-Host "=========================================" -ForegroundColor Green
+    Write-Host ""
+    Write-Host "Useful commands:"
+    Write-Host "  minion-cli-win status    # Agent status"
+    Write-Host "  minion-cli-win health    # Health check"
+    Write-Host "  minion-cli-win restart   # Restart agent"
+    Write-Host "  minion-cli-win stop      # Stop agent"
+    Write-Host "  Get-Content $(Join-Path $LogDir 'service-stdout.log') -Tail 50  # View logs"
+}
+
+# ============================================================
+# Reconfigure
+# ============================================================
+
+function Invoke-Reconfigure {
+    if (-not $HqUrl -or -not $MinionId -or -not $ApiToken) {
+        Write-Error "All three parameters are required: --hq-url, --minion-id, --api-token"
+        exit 1
+    }
+    if (-not (Test-Path $EnvFile)) {
+        Write-Error "$EnvFile not found. Run 'setup' first."
+        exit 1
+    }
+
+    Write-Host "=========================================" -ForegroundColor Cyan
+    Write-Host " @geekbeer/minion Reconfigure" -ForegroundColor Cyan
+    Write-Host "=========================================" -ForegroundColor Cyan
+    Write-Host "HQ: $HqUrl"
+    Write-Host "Minion ID: $MinionId"
+    Write-Host ""
+
+    # Step 1: Update .env
+    Write-Step 1 4 "Updating .env credentials..."
+    $existing = Read-EnvFile $EnvFile
+    $existing['HQ_URL'] = $HqUrl
+    $existing['API_TOKEN'] = $ApiToken
+    $existing['MINION_ID'] = $MinionId
+    Write-EnvFile $EnvFile $existing
+    Write-Detail "$EnvFile updated"
+
+    # Step 2: Restart agent process
+    Write-Step 2 4 "Restarting minion-agent..."
+    Restart-MinionProcess
+
+    # Step 3: Health check
+    Write-Step 3 4 "Verifying agent health..."
+    if (Invoke-HealthCheck) {
+        Write-Detail "Agent is healthy"
+    }
+    else {
+        Write-Warn "Agent health check failed after 5 attempts"
+    }
+
+    # Step 4: Notify HQ
+    Write-Step 4 4 "Notifying HQ..."
+    try {
+        $lanIp = Get-LanIPAddress
+        $headers = @{
+            'Authorization' = "Bearer $ApiToken"
+            'Content-Type'  = 'application/json'
+        }
+        $bodyHash = @{}
+        if ($lanIp) {
+            $bodyHash['ip_address'] = $lanIp
+            $bodyHash['internal_ip_address'] = $lanIp
+        } else {
+            $bodyHash['internal_ip_address'] = [System.Net.Dns]::GetHostName()
+        }
+        $body = $bodyHash | ConvertTo-Json
+        Invoke-RestMethod -Uri "$HqUrl/api/minion/setup-complete" -Method Post -Headers $headers -Body $body -ErrorAction Stop | Out-Null
+        if ($lanIp) {
+            Write-Detail "HQ notified successfully (LAN IP: $lanIp)"
+        } else {
+            Write-Detail "HQ notified successfully (LAN IP detection failed, hostname sent)"
+        }
+    }
+    catch {
+        Write-Detail "Skipped (heartbeat will notify HQ within 30s)"
+    }
+
+    Write-Host ""
+    Write-Host "=========================================" -ForegroundColor Green
+    Write-Host " Reconfigure Complete!" -ForegroundColor Green
+    Write-Host "=========================================" -ForegroundColor Green
+    Write-Host "The minion should appear online in HQ shortly."
+}
+
+# ============================================================
+# Main command dispatch
+# ============================================================
+
+switch ($Command) {
+    'setup' {
+        Invoke-Setup
+    }
+    'reconfigure' {
+        Invoke-Reconfigure
+    }
+    'start' {
+        Start-MinionProcess
+    }
+    'stop' {
+        Stop-MinionProcess
+    }
+    'restart' {
+        Restart-MinionProcess
+    }
+    'status' {
+        try {
+            $response = Invoke-RestMethod -Uri "$AgentUrl/api/status" -TimeoutSec 5
+            $response | ConvertTo-Json -Depth 5
+        }
+        catch {
+            Write-Error "Failed to get status. Is the agent running?"
+        }
+    }
+    'health' {
+        try {
+            $response = Invoke-RestMethod -Uri "$AgentUrl/api/health" -TimeoutSec 5
+            $response | ConvertTo-Json -Depth 5
+        }
+        catch {
+            Write-Error "Health check failed. Is the agent running?"
+        }
+    }
+    'version' {
+        Write-Host "@geekbeer/minion v$CliVersion (Windows)"
+    }
+    'help' {
+        Write-Host "Minion Agent CLI (@geekbeer/minion) v$CliVersion (Windows)" -ForegroundColor Cyan
+        Write-Host ""
+        Write-Host "Usage (no admin required):"
+        Write-Host "  minion-cli-win setup [options]          # Set up agent (auto-start on login)"
+        Write-Host "  minion-cli-win reconfigure [options]    # Re-register with new HQ credentials"
+        Write-Host "  minion-cli-win start                    # Start agent process"
+        Write-Host "  minion-cli-win stop                     # Stop agent process"
+        Write-Host "  minion-cli-win restart                  # Restart agent process"
+        Write-Host "  minion-cli-win status                   # Get current status"
+        Write-Host "  minion-cli-win health                   # Health check"
+        Write-Host "  minion-cli-win version                  # Show version"
+        Write-Host ""
+        Write-Host "Setup options:"
+        Write-Host "  --hq-url <URL>        HQ server URL (optional, omit for standalone mode)"
+        Write-Host "  --minion-id <UUID>    Minion ID (optional)"
+        Write-Host "  --api-token <TOKEN>   API token (optional)"
+        Write-Host "  --setup-tunnel        Set up cloudflared tunnel (requires --hq-url and --api-token)"
+        Write-Host ""
+        Write-Host "Reconfigure options:"
+        Write-Host "  --hq-url <URL>        HQ server URL (required)"
+        Write-Host "  --minion-id <UUID>    Minion ID (required)"
+        Write-Host "  --api-token <TOKEN>   API token (required)"
+        Write-Host ""
+        Write-Host "Data directory: $DataDir"
+        Write-Host ""
+        Write-Host "Environment:"
+        Write-Host "  MINION_AGENT_URL  Agent URL (default: http://localhost:8080)"
+    }
+}