@geekbeer/minion 3.5.1 → 3.5.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekbeer/minion",
-  "version": "3.5.1",
+  "version": "3.5.30",
   "description": "AI Agent runtime for Minion - manages status and skill deployment on VPS",
   "main": "linux/server.js",
   "bin": {
@@ -10,6 +10,7 @@
     "hq-win": "./win/bin/hq-win.js"
   },
   "files": [
+    "postinstall.js",
     "core/",
     "linux/",
     "win/",
@@ -22,7 +23,8 @@
   ],
   "scripts": {
     "start": "node linux/server.js",
-    "start:win": "node win/server.js"
+    "start:win": "node win/server.js",
+    "postinstall": "node postinstall.js"
   },
   "dependencies": {
     "better-sqlite3": "^11.0.0",

package/postinstall.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// postinstall.js — Re-apply file ACLs on Windows after npm install -g.
+// On Linux this is a no-op (permissions are not affected by reinstall).
+
+if (process.platform !== 'win32') process.exit(0);
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const ps1 = path.join(__dirname, 'win', 'postinstall.ps1');
+const result = spawnSync('powershell.exe', [
+  '-ExecutionPolicy', 'Bypass',
+  '-NoProfile',
+  '-NoLogo',
+  '-File', ps1,
+], { stdio: 'inherit', timeout: 30_000 });
+
+process.exit(result.status || 0);

package/win/lib/process-manager.js

@@ -35,6 +35,20 @@ function getNssmPath() {
   return vendorNssm
 }
 
+/**
+ * Derive the npm global prefix from the nssm.exe path.
+ * nssm is bundled at: <npm-prefix>/node_modules/@geekbeer/minion/win/vendor/nssm.exe
+ * So the prefix is the ancestor directory containing node_modules.
+ * @param {string} nssmPath - Absolute path to nssm.exe
+ * @returns {string|null} npm global prefix, or null if not derivable
+ */
+function getNpmPrefix(nssmPath) {
+  const parts = nssmPath.split(path.sep)
+  const nmIndex = parts.lastIndexOf('node_modules')
+  if (nmIndex > 0) return parts.slice(0, nmIndex).join(path.sep)
+  return null
+}
+
 /**
  * Detect Windows process manager. Always returns 'nssm'.
  * @returns {'nssm'}
@@ -56,7 +70,7 @@ function buildGracefulStopBlock(agentPort, apiToken) {
   return [
     `  try {`,
     `    Invoke-RestMethod -Uri 'http://localhost:${agentPort}/api/shutdown' -Method POST ` +
-         `-ContentType 'application/json' -Headers @{ Authorization = 'Bearer ${apiToken}' } -TimeoutSec 5 | Out-Null`,
+         `-Body '{}' -ContentType 'application/json' -Headers @{ Authorization = 'Bearer ${apiToken}' } -TimeoutSec 5 | Out-Null`,
     `    Log 'Graceful shutdown requested, waiting for offline heartbeat...'`,
     `    Start-Sleep -Seconds 4`,
     `  } catch {`,
@@ -71,6 +85,11 @@ function buildGracefulStopBlock(agentPort, apiToken) {
  * 2. Stop service via NSSM
  * 3. Run npm install -g
  * 4. Start service via NSSM
+ * 5. Remove the temporary updater service (self-cleanup)
+ *
+ * This script is registered as a temporary NSSM service ("minion-update")
+ * so it runs independently of the minion-agent service and survives
+ * the agent's stop/restart cycle.
  *
  * @param {string} npmInstallCmd - The npm install command to run
  * @param {string} nssmPath - Absolute path to nssm.exe
@@ -81,34 +100,63 @@ function buildGracefulStopBlock(agentPort, apiToken) {
  */
 function buildUpdateScript(npmInstallCmd, nssmPath, scriptName = 'update-agent', agentPort = 8080, apiToken = '') {
   const dataDir = path.join(os.homedir(), '.minion')
+  const homeDir = os.homedir()
+  const npmPrefix = getNpmPrefix(nssmPath)
   const scriptPath = path.join(dataDir, `${scriptName}.ps1`)
-  const logPath = path.join(dataDir, `${scriptName}.log`)
-  const nssm = nssmPath.replace(/\\/g, '\\\\')
+  const logDir = path.join(dataDir, 'logs')
+  const logPath = path.join(logDir, `${scriptName}.log`)
+
+  // Append --prefix to npm command so it installs to the correct global directory
+  const fullNpmCmd = npmPrefix
+    ? `${npmInstallCmd} --prefix "${npmPrefix}"`
+    : npmInstallCmd
 
   const gracefulStop = buildGracefulStopBlock(agentPort, apiToken)
 
   const ps1 = [
+    `# Override LocalSystem's default profile so npm uses the correct paths`,
+    `$env:USERPROFILE = '${homeDir}'`,
+    `$env:HOME = '${homeDir}'`,
     `$ErrorActionPreference = 'Stop'`,
-    `$logFile = '${logPath.replace(/\\/g, '\\\\')}'`,
+    `# Use nssm.exe from data dir (copied there to avoid EBUSY on package files)`,
+    `$nssm = '${path.join(dataDir, 'nssm.exe')}'`,
+    `$logFile = '${logPath}'`,
     `function Log($msg) { "$(Get-Date -Format o) $msg" | Out-File -Append $logFile }`,
     `Log 'Update started'`,
     `try {`,
     `  Log 'Requesting graceful shutdown...'`,
     gracefulStop,
     `  Log 'Stopping service via NSSM...'`,
-    `  & '${nssm}' stop minion-agent`,
+    `  & $nssm stop minion-agent`,
     `  Start-Sleep -Seconds 3`,
+    `  # Retry npm install up to 5 times (Windows may hold file locks briefly after service stop)`,
     `  Log 'Installing package...'`,
-    `  $out = & cmd /c "${npmInstallCmd} 2>&1"`,
-    `  Log "npm output: $out"`,
-    `  if ($LASTEXITCODE -ne 0) { throw "npm install failed (exit code $LASTEXITCODE)" }`,
+    `  $installed = $false`,
+    `  for ($attempt = 1; $attempt -le 5; $attempt++) {`,
+    `    $out = & cmd /c "${fullNpmCmd} 2>&1"`,
+    `    if ($LASTEXITCODE -eq 0) {`,
+    `      Log "npm output: $out"`,
+    `      $installed = $true`,
+    `      break`,
+    `    }`,
+    `    Log "npm install attempt $attempt failed (exit $LASTEXITCODE): $out"`,
+    `    if ($attempt -lt 5) {`,
+    `      Log "Retrying in 10 seconds..."`,
+    `      Start-Sleep -Seconds 10`,
+    `    }`,
+    `  }`,
+    `  if (-not $installed) { throw "npm install failed after 5 attempts" }`,
     `  Log 'Starting service...'`,
-    `  & '${nssm}' start minion-agent`,
+    `  & $nssm start minion-agent`,
     `  Log 'Update completed successfully'`,
     `} catch {`,
     `  Log "Update failed: $_"`,
     `  Log 'Attempting to start service anyway...'`,
-    `  & '${nssm}' start minion-agent`,
+    `  & $nssm start minion-agent`,
+    `} finally {`,
+    `  Log 'Cleaning up updater service...'`,
+    `  & $nssm stop minion-update confirm 2>$null`,
+    `  & $nssm remove minion-update confirm 2>$null`,
     `}`,
   ].join('\n')
 
@@ -122,35 +170,47 @@ function buildUpdateScript(npmInstallCmd, nssmPath, scriptName = 'update-agent',
  * Generate a temporary PowerShell restart script:
  * 1. Graceful shutdown via HTTP API (offline heartbeat)
  * 2. Restart service via NSSM
+ * 3. Remove the temporary updater service (self-cleanup)
+ *
+ * Registered as a temporary NSSM service ("minion-update") so the restart
+ * process is independent of the minion-agent service.
  *
  * @param {string} nssmPath - Absolute path to nssm.exe
  * @param {number} agentPort - The agent's HTTP port
  * @param {string} apiToken - The agent's API token
  * @returns {string} - Path to the generated restart script (.ps1)
  */
-function buildRestartScript(nssmPath, agentPort, apiToken) {
+function buildRestartScript(_nssmPath, agentPort, apiToken) {
   const dataDir = path.join(os.homedir(), '.minion')
+  const homeDir = os.homedir()
   const scriptPath = path.join(dataDir, 'restart-agent.ps1')
-  const logPath = path.join(dataDir, 'restart-agent.log')
-  const nssm = nssmPath.replace(/\\/g, '\\\\')
+  const logDir = path.join(dataDir, 'logs')
+  const logPath = path.join(logDir, 'restart-agent.log')
 
   const gracefulStop = buildGracefulStopBlock(agentPort, apiToken)
 
   const ps1 = [
+    `$env:USERPROFILE = '${homeDir}'`,
+    `$env:HOME = '${homeDir}'`,
     `$ErrorActionPreference = 'Stop'`,
-    `$logFile = '${logPath.replace(/\\/g, '\\\\')}'`,
+    `$nssm = '${path.join(dataDir, 'nssm.exe')}'`,
+    `$logFile = '${logPath}'`,
     `function Log($msg) { "$(Get-Date -Format o) $msg" | Out-File -Append $logFile }`,
     `Log 'Restart started'`,
     `try {`,
     `  Log 'Requesting graceful shutdown...'`,
     gracefulStop,
     `  Log 'Restarting service via NSSM...'`,
-    `  & '${nssm}' restart minion-agent`,
+    `  & $nssm restart minion-agent`,
     `  Log 'Restart completed successfully'`,
     `} catch {`,
     `  Log "Restart failed: $_"`,
     `  Log 'Attempting to start service...'`,
-    `  & '${nssm}' start minion-agent`,
+    `  & $nssm start minion-agent`,
+    `} finally {`,
+    `  Log 'Cleaning up updater service...'`,
+    `  & $nssm stop minion-update confirm 2>$null`,
+    `  & $nssm remove minion-update confirm 2>$null`,
     `}`,
   ].join('\n')
 
@@ -162,9 +222,15 @@ function buildRestartScript(nssmPath, agentPort, apiToken) {
 
 /**
  * Build allowed commands for NSSM-based service management.
+ *
+ * Deferred commands (update/restart) use a temporary NSSM service
+ * ("minion-update") to run PowerShell scripts independently of the
+ * minion-agent service. This allows the script to stop, update, and
+ * restart minion-agent without being killed in the process.
+ *
  * @param {string} _procMgr - Ignored (always 'nssm')
  * @param {{ AGENT_PORT?: number, API_TOKEN?: string }} [agentConfig] - Agent config
- * @returns {Record<string, { description: string; command?: string; spawnArgs?: [string, string[]]; deferred?: boolean }>}
+ * @returns {Record<string, { description: string; command?: string; nssmService?: { scriptPath: string }; deferred?: boolean }>}
  */
 function buildAllowedCommands(_procMgr, agentConfig = {}) {
   const commands = {}
@@ -174,28 +240,29 @@ function buildAllowedCommands(_procMgr, agentConfig = {}) {
 
   commands['restart-agent'] = {
     description: 'Restart the minion agent service',
-    spawnArgs: ['powershell', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command',
-      `& '${buildRestartScript(nssmPath, agentPort, apiToken)}'`]],
+    nssmService: { scriptPath: buildRestartScript(nssmPath, agentPort, apiToken) },
     deferred: true,
   }
 
   commands['update-agent'] = {
     description: 'Update @geekbeer/minion to latest version and restart',
-    spawnArgs: ['powershell', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command',
-      `& '${buildUpdateScript(
+    nssmService: {
+      scriptPath: buildUpdateScript(
         'npm install -g @geekbeer/minion@latest',
         nssmPath, 'update-agent', agentPort, apiToken,
-      )}'`]],
+      ),
+    },
     deferred: true,
   }
 
   commands['update-agent-dev'] = {
     description: 'Update @geekbeer/minion from Verdaccio (dev) and restart',
-    spawnArgs: ['powershell', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command',
-      `& '${buildUpdateScript(
+    nssmService: {
+      scriptPath: buildUpdateScript(
         'npm install -g @geekbeer/minion@latest --registry http://verdaccio:4873',
         nssmPath, 'update-agent-dev', agentPort, apiToken,
-      )}'`]],
+      ),
+    },
     deferred: true,
   }
 

package/win/minion-cli.ps1

@@ -35,8 +35,6 @@ while ($i -lt $args.Count) {
 
 $ErrorActionPreference = 'Stop'
 
-# Load System.Web for password generation (used in setup)
-Add-Type -AssemblyName System.Web -ErrorAction SilentlyContinue
 
 # ============================================================
 # Require Administrator for service management commands
@@ -280,7 +278,7 @@ function Invoke-HealthCheck {
 function Assert-NssmAvailable {
     if (-not $NssmPath -or -not (Test-Path $NssmPath)) {
         Write-Error "NSSM not found. Expected at: $vendorNssm"
-        Write-Host "  Reinstall the package: npm install -g @geekbeer/minion" -ForegroundColor Yellow
+        Write-Host "  Reinstall the package (admin PowerShell): npm install -g @geekbeer/minion" -ForegroundColor Yellow
         exit 1
     }
 }
@@ -362,7 +360,13 @@ function Stop-MinionService {
         Write-Host "minion-agent: not installed" -ForegroundColor Red
         return
     }
-    # Graceful shutdown via HTTP API first (sends offline heartbeat to HQ)
+    if ($state -eq 'STOPPED') {
+        Write-Host "minion-agent service is already stopped"
+        return
+    }
+    # Trigger graceful shutdown (sends offline heartbeat to HQ) but do NOT wait
+    # for the process to exit — otherwise NSSM sees the exit as a crash and
+    # restarts the process before sc.exe stop can run.
     $token = ''
     if (Test-Path $EnvFile) {
         $envVars = Read-EnvFile $EnvFile
@@ -371,13 +375,18 @@ function Stop-MinionService {
     try {
         $headers = @{}
         if ($token) { $headers['Authorization'] = "Bearer $token" }
-        Invoke-RestMethod -Uri "$AgentUrl/api/shutdown" -Method POST -ContentType 'application/json' -Headers $headers -TimeoutSec 5 | Out-Null
-        Write-Host "Graceful shutdown requested, waiting..."
-        Start-Sleep -Seconds 4
+        Invoke-RestMethod -Uri "$AgentUrl/api/shutdown" -Method POST -ContentType 'application/json' -Headers $headers -TimeoutSec 3 | Out-Null
     } catch {
-        Write-Host "Graceful shutdown skipped (agent may not be running)"
+        # Agent may not be responding — sc.exe stop will handle it
     }
+    # Immediately stop via NSSM (prevents auto-restart, sends kill if still alive)
     sc.exe stop minion-agent 2>&1 | Out-Null
+    # Wait for service to fully stop (up to 10 seconds)
+    for ($i = 0; $i -lt 10; $i++) {
+        $s = Get-ServiceState 'minion-agent'
+        if ($s -eq 'STOPPED') { break }
+        Start-Sleep -Seconds 1
+    }
     Write-Host "minion-agent service stopped"
 }
 
@@ -392,7 +401,7 @@ function Restart-MinionService {
 # ============================================================
 
 function Invoke-Setup {
-    $totalSteps = 10
+    $totalSteps = 11
 
     # Minionization warning
     Write-Host ""
@@ -403,7 +412,6 @@ function Invoke-Setup {
 
     Write-Host "  This setup will:" -ForegroundColor Yellow
     Write-Host "    - Install and configure software (Node.js, Claude Code, VNC)"
-    Write-Host "    - Create dedicated 'minion' service account"
     Write-Host "    - Register Windows Services via NSSM"
     Write-Host "    - Configure firewall rules"
     Write-Host ""
@@ -431,6 +439,14 @@ function Invoke-Setup {
 
     # Save setup user's SID for SDDL grants (so non-admin can control services later)
     $setupUserSid = ([System.Security.Principal.WindowsIdentity]::GetCurrent().User).Value
+    # Also resolve target user's SID (may differ from setup user when run from admin account)
+    $targetUserName = Split-Path $TargetUserProfile -Leaf
+    try {
+        $targetUserSid = (New-Object System.Security.Principal.NTAccount($targetUserName)).Translate(
+            [System.Security.Principal.SecurityIdentifier]).Value
+    } catch {
+        $targetUserSid = $null
+    }
     New-Item -Path $DataDir -ItemType Directory -Force | Out-Null
     [System.IO.File]::WriteAllText((Join-Path $DataDir '.setup-user-sid'), $setupUserSid)
     # Save target user profile so configure/uninstall can find it
@@ -571,74 +587,8 @@ function Invoke-Setup {
     Write-Host "  Please run 'claude' in a terminal to complete the authentication process." -ForegroundColor Yellow
     Write-Host ""
 
-    # Step 4: Create dedicated 'minion' service account
-    Write-Step 4 $totalSteps "Creating dedicated service account..."
-    $MinionSvcUser = 'minion'
-    $MinionSvcUserFull = ".\$MinionSvcUser"
-    $minionUserExists = [bool](Get-LocalUser -Name $MinionSvcUser -ErrorAction SilentlyContinue)
-    if ($minionUserExists) {
-        Write-Detail "Service account '$MinionSvcUser' already exists"
-    } else {
-        # Generate a random password (service account — not used interactively)
-        $svcPassword = [System.Web.Security.Membership]::GeneratePassword(24, 4)
-        $securePassword = ConvertTo-SecureString $svcPassword -AsPlainText -Force
-        New-LocalUser -Name $MinionSvcUser -Password $securePassword -Description 'Minion Agent Service Account' -PasswordNeverExpires -UserMayNotChangePassword -AccountNeverExpires | Out-Null
-        # Deny interactive/remote logon (service-only account)
-        & net localgroup "Users" $MinionSvcUser /delete 2>$null
-        Write-Detail "Service account '$MinionSvcUser' created (non-interactive)"
-    }
-    # Store password for NSSM ObjectName configuration
-    if (-not $minionUserExists) {
-        # Save password to a protected file for NSSM service registration
-        $svcPasswordFile = Join-Path $DataDir '.svc-password'
-        New-Item -Path (Split-Path $svcPasswordFile) -ItemType Directory -Force | Out-Null
-        [System.IO.File]::WriteAllText($svcPasswordFile, $svcPassword)
-        # Restrict file access to current user only
-        $acl = Get-Acl $svcPasswordFile
-        $acl.SetAccessRuleProtection($true, $false)
-        $adminRule = New-Object System.Security.AccessControl.FileSystemAccessRule(
-            [System.Security.Principal.WindowsIdentity]::GetCurrent().Name, 'FullControl', 'Allow')
-        $acl.AddAccessRule($adminRule)
-        Set-Acl $svcPasswordFile $acl
-        Write-Detail "Service account credentials stored"
-    } else {
-        $svcPasswordFile = Join-Path $DataDir '.svc-password'
-        if (Test-Path $svcPasswordFile) {
-            $svcPassword = [System.IO.File]::ReadAllText($svcPasswordFile).Trim()
-        } else {
-            # Re-generate password for existing account (reset)
-            $svcPassword = [System.Web.Security.Membership]::GeneratePassword(24, 4)
-            $securePassword = ConvertTo-SecureString $svcPassword -AsPlainText -Force
-            Set-LocalUser -Name $MinionSvcUser -Password $securePassword
-            New-Item -Path (Split-Path $svcPasswordFile) -ItemType Directory -Force | Out-Null
-            [System.IO.File]::WriteAllText($svcPasswordFile, $svcPassword)
-            $acl = Get-Acl $svcPasswordFile
-            $acl.SetAccessRuleProtection($true, $false)
-            $adminRule = New-Object System.Security.AccessControl.FileSystemAccessRule(
-                [System.Security.Principal.WindowsIdentity]::GetCurrent().Name, 'FullControl', 'Allow')
-            $acl.AddAccessRule($adminRule)
-            Set-Acl $svcPasswordFile $acl
-            Write-Detail "Service account password reset and stored"
-        }
-    }
-    # Grant 'Log on as a service' right to the minion user
-    $tempCfg = Join-Path $env:TEMP 'minion-secedit.cfg'
-    $tempDb = Join-Path $env:TEMP 'minion-secedit.sdb'
-    & secedit /export /cfg $tempCfg /areas USER_RIGHTS 2>$null
-    $cfgContent = Get-Content $tempCfg -Raw
-    if ($cfgContent -match 'SeServiceLogonRight\s*=\s*(.*)') {
-        $existing = $Matches[1]
-        if ($existing -notmatch $MinionSvcUser) {
-            $cfgContent = $cfgContent -replace "(SeServiceLogonRight\s*=\s*)(.*)", "`$1`$2,$MinionSvcUser"
-            [System.IO.File]::WriteAllText($tempCfg, $cfgContent)
-            & secedit /configure /db $tempDb /cfg $tempCfg /areas USER_RIGHTS 2>$null
-            Write-Detail "Granted 'Log on as a service' right to '$MinionSvcUser'"
-        }
-    }
-    Remove-Item $tempCfg, $tempDb -Force -ErrorAction SilentlyContinue
-
-    # Step 5: Create config directory and default .env
-    Write-Step 5 $totalSteps "Creating config directory..."
+    # Step 4: Create config directory and default .env
+    Write-Step 4 $totalSteps "Creating config directory..."
     New-Item -Path $DataDir -ItemType Directory -Force | Out-Null
     New-Item -Path $LogDir -ItemType Directory -Force | Out-Null
     if (-not (Test-Path $EnvFile)) {
@@ -653,16 +603,8 @@ function Invoke-Setup {
         Write-Detail "$EnvFile already exists, preserving"
     }
 
-    # Grant minion service account read/write access to data directory
-    $minionAcl = Get-Acl $DataDir
-    $minionRule = New-Object System.Security.AccessControl.FileSystemAccessRule(
-        $MinionSvcUser, 'Modify', 'ContainerInherit,ObjectInherit', 'None', 'Allow')
-    $minionAcl.AddAccessRule($minionRule)
-    Set-Acl $DataDir $minionAcl
-    Write-Detail "Granted '$MinionSvcUser' access to $DataDir"
-
-    # Step 6: Install node-pty (required for Windows terminal management)
-    Write-Step 6 $totalSteps "Installing terminal support (node-pty)..."
+    # Step 5: Install node-pty (required for Windows terminal management)
+    Write-Step 5 $totalSteps "Installing terminal support (node-pty)..."
     $minionPkgDir = $CliDir
     if (Test-Path $minionPkgDir) {
         Push-Location $minionPkgDir
@@ -696,22 +638,22 @@ function Invoke-Setup {
     }
     else {
         Write-Warn "Minion package not found at $minionPkgDir"
-        Write-Host "  Please run: npm install -g @geekbeer/minion"
+        Write-Host "  Please run (admin PowerShell): npm install -g @geekbeer/minion"
     }
 
     # Step 7: Verify NSSM
-    Write-Step 7 $totalSteps "Verifying NSSM..."
+    Write-Step 6 $totalSteps "Verifying NSSM..."
     Assert-NssmAvailable
     $nssmVersion = Invoke-Nssm version
     Write-Detail "NSSM available: $NssmPath ($nssmVersion)"
 
     # Step 8: Register Windows Services via NSSM
-    Write-Step 8 $totalSteps "Registering Windows Services..."
+    Write-Step 7 $totalSteps "Registering Windows Services..."
 
     $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"
+        Write-Host "  Please run (admin PowerShell): npm install -g @geekbeer/minion"
         exit 1
     }
     $nodePath = (Get-Command node).Source
@@ -743,13 +685,15 @@ function Invoke-Setup {
     Invoke-Nssm set minion-agent Start SERVICE_AUTO_START
     Invoke-Nssm set minion-agent DisplayName "Minion Agent"
     Invoke-Nssm set minion-agent Description "GeekBeer Minion AI Agent Service"
-    # Run as dedicated minion service account (not LocalSystem)
-    Invoke-Nssm set minion-agent ObjectName $MinionSvcUserFull $svcPassword
+    # Runs as LocalSystem (NSSM default). USERPROFILE/HOME env vars point to target user's profile.
     Grant-ServiceControlToUser 'minion-agent' $setupUserSid
-    Write-Detail "minion-agent service registered (runs as '$MinionSvcUser')"
+    if ($targetUserSid -and $targetUserSid -ne $setupUserSid) {
+        Grant-ServiceControlToUser 'minion-agent' $targetUserSid
+    }
+    Write-Detail "minion-agent service registered (runs as LocalSystem)"
 
-    # Step 9: Install and configure TightVNC (runs as LocalSystem for desktop capture)
-    Write-Step 9 $totalSteps "Setting up TightVNC Server..."
+    # Step 9: Install and configure TightVNC (runs as logon task in user session for desktop capture)
+    Write-Step 8 $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'
@@ -798,31 +742,32 @@ function Invoke-Setup {
     }
 
     # Configure TightVNC registry (localhost-only, no VNC auth)
-    $vncRegPath = 'HKCU:\Software\TightVNC\Server'
+    # Write to both HKCU (for user-session -run mode) and HKLM (fallback)
     if ($vncExePath) {
-        if (-not (Test-Path $vncRegPath)) {
-            New-Item -Path $vncRegPath -Force | Out-Null
+        foreach ($vncRegPath in @('HKCU:\Software\TightVNC\Server', 'HKLM:\Software\TightVNC\Server')) {
+            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
         }
-        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
+        Write-Detail "TightVNC registry configured (HKCU + HKLM)"
 
-        # Register VNC as NSSM service (application mode, not TightVNC's own service)
+        # Remove legacy NSSM service if present (VNC now runs as logon task)
         Invoke-Nssm stop minion-vnc
         Invoke-Nssm remove minion-vnc confirm
-        Invoke-Nssm install minion-vnc $vncExePath '-run'
-        Invoke-Nssm set minion-vnc Start SERVICE_AUTO_START
-        Invoke-Nssm set minion-vnc DisplayName "Minion VNC Server"
-        Invoke-Nssm set minion-vnc Description "TightVNC for Minion remote desktop"
-        Invoke-Nssm set minion-vnc AppRestartDelay 3000
-        Grant-ServiceControlToUser 'minion-vnc' $setupUserSid
-        Write-Detail "minion-vnc service registered"
+
+        # Register VNC as logon task (must run in user session for desktop capture)
+        schtasks /Delete /TN "MinionVNC" /F 2>$null
+        schtasks /Create /TN "MinionVNC" /TR "'$vncExePath' -run" /SC ONLOGON /RL HIGHEST /F | Out-Null
+        Write-Detail "TightVNC registered as logon task (user session, not service)"
     }
 
     # Step 10: Setup websockify (runs as LocalSystem, paired with VNC)
-    Write-Step 10 $totalSteps "Setting up websockify..."
+    Write-Step 9 $totalSteps "Setting up websockify..."
     [array]$wsCmd = Get-WebsockifyCommand
     if (-not $wsCmd) {
         # Ensure Python is installed
@@ -878,7 +823,7 @@ function Invoke-Setup {
     }
 
     if ($wsCmd -and $vncExePath) {
-        # Register websockify as NSSM service
+        # Register websockify as NSSM service (no dependency on minion-vnc — VNC runs as logon task)
         Invoke-Nssm stop minion-websockify
         Invoke-Nssm remove minion-websockify confirm
         if ($wsCmd.Count -eq 1) {
@@ -888,19 +833,21 @@ function Invoke-Setup {
             $wsArgs = ($wsCmd[1..($wsCmd.Count-1)] + @('6080', 'localhost:5900')) -join ' '
             Invoke-Nssm install minion-websockify $wsCmd[0] $wsArgs
         }
-        Invoke-Nssm set minion-websockify DependOnService minion-vnc
         Invoke-Nssm set minion-websockify Start SERVICE_AUTO_START
         Invoke-Nssm set minion-websockify DisplayName "Minion Websockify"
         Invoke-Nssm set minion-websockify Description "WebSocket proxy for VNC (6080 -> 5900)"
         Invoke-Nssm set minion-websockify AppRestartDelay 3000
         Grant-ServiceControlToUser 'minion-websockify' $setupUserSid
-        Write-Detail "minion-websockify service registered (depends on minion-vnc)"
+        if ($targetUserSid -and $targetUserSid -ne $setupUserSid) {
+            Grant-ServiceControlToUser 'minion-websockify' $targetUserSid
+        }
+        Write-Detail "minion-websockify service registered"
     } else {
         Write-Warn "websockify not available, VNC WebSocket proxy will not be registered"
     }
 
     # Step 11: Disable screensaver, lock screen, and sleep
-    Write-Step 11 $totalSteps "Disabling screensaver, lock screen, and sleep..."
+    Write-Step 10 $totalSteps "Disabling screensaver, lock screen, and sleep..."
     Set-ItemProperty -Path 'HKCU:\Control Panel\Desktop' -Name ScreenSaveActive -Value '0'
     Set-ItemProperty -Path 'HKCU:\Control Panel\Desktop' -Name ScreenSaveTimeOut -Value '0'
     Set-ItemProperty -Path 'HKCU:\Control Panel\Desktop' -Name SCRNSAVE.EXE -Value ''
@@ -914,7 +861,7 @@ function Invoke-Setup {
     Write-Detail "Sleep and monitor timeout disabled"
 
     # Configure firewall rules
-    Write-Step 10 $totalSteps "Configuring firewall rules..."
+    Write-Step 11 $totalSteps "Configuring firewall rules..."
     $fwRules = @(
         @{ Name = 'Minion Agent'; Port = 8080 },
         @{ Name = 'Minion Terminal'; Port = 7681 },
@@ -930,25 +877,73 @@ function Invoke-Setup {
         }
     }
 
-    # Grant minion service account access to .claude directory (skills, rules, settings)
-    $claudeDir = Join-Path $TargetUserProfile '.claude'
-    New-Item -Path $claudeDir -ItemType Directory -Force | Out-Null
-    $claudeAcl = Get-Acl $claudeDir
-    $claudeRule = New-Object System.Security.AccessControl.FileSystemAccessRule(
-        $MinionSvcUser, 'Modify', 'ContainerInherit,ObjectInherit', 'None', 'Allow')
-    $claudeAcl.AddAccessRule($claudeRule)
-    Set-Acl $claudeDir $claudeAcl
-    Write-Detail "Granted '$MinionSvcUser' access to $claudeDir"
+    # Grant target user access to admin's minion package and bin links (so target user can run minion-cli-win)
+    $adminNpmBin = Split-Path (Get-Command minion-cli-win -ErrorAction SilentlyContinue).Source -ErrorAction SilentlyContinue
+    if (-not $adminNpmBin) {
+        $adminNpmBin = & npm config get prefix 2>$null
+    }
+    if ($adminNpmBin -and ($adminNpmBin -ne (Join-Path $TargetUserProfile 'AppData\Roaming\npm'))) {
+        $targetUserName = Split-Path $TargetUserProfile -Leaf
 
-    # Grant minion service account access to npm global directory (for package access)
-    $npmGlobalDir = Split-Path $CliDir
-    if ($npmGlobalDir -and (Test-Path $npmGlobalDir)) {
-        $npmAcl = Get-Acl $npmGlobalDir
-        $npmRule = New-Object System.Security.AccessControl.FileSystemAccessRule(
-            $MinionSvcUser, 'ReadAndExecute', 'ContainerInherit,ObjectInherit', 'None', 'Allow')
-        $npmAcl.AddAccessRule($npmRule)
-        Set-Acl $npmGlobalDir $npmAcl
-        Write-Detail "Granted '$MinionSvcUser' read access to npm global"
+        # Grant ReadAndExecute on bin links (minion-cli-win.cmd, hq-win.cmd, etc.)
+        $binFiles = Get-ChildItem -Path $adminNpmBin -Filter '*minion*' -ErrorAction SilentlyContinue
+        $binFiles += Get-ChildItem -Path $adminNpmBin -Filter '*hq-win*' -ErrorAction SilentlyContinue
+        foreach ($f in $binFiles) {
+            icacls $f.FullName /grant "${targetUserName}:(RX)" /Q 2>$null | Out-Null
+        }
+        # Grant ReadAndExecute on the @geekbeer/minion package directory (recursive)
+        $minionPkgDir = Join-Path (Join-Path $adminNpmBin 'node_modules') '@geekbeer\minion'
+        if (Test-Path $minionPkgDir) {
+            icacls $minionPkgDir /grant "${targetUserName}:(OI)(CI)RX" /T /Q 2>$null | Out-Null
+            Write-Detail "Granted target user read access to $minionPkgDir"
+        }
+        # Grant traverse access on ancestor directories so the path is reachable
+        # e.g., C:\Users\yunoda -> AppData -> Roaming -> npm -> node_modules -> @geekbeer
+        $traverseDirs = @(
+            $adminNpmBin,
+            (Join-Path $adminNpmBin 'node_modules'),
+            (Join-Path $adminNpmBin 'node_modules\@geekbeer')
+        )
+        # Walk up from npm bin dir to drive root to grant traverse (list+read) on each
+        $walkDir = $adminNpmBin
+        while ($walkDir) {
+            $parent = Split-Path $walkDir -Parent
+            if (-not $parent -or $parent -eq $walkDir) { break }
+            $traverseDirs += $parent
+            $walkDir = $parent
+            # Stop at drive root
+            if ($parent.Length -le 3) { break }
+        }
+        foreach ($dir in ($traverseDirs | Select-Object -Unique)) {
+            if (Test-Path $dir) {
+                # Grant only traverse + list (no recursive, no inherit)
+                icacls $dir /grant "${targetUserName}:(RX)" /Q 2>$null | Out-Null
+            }
+        }
+
+        # Add admin's npm bin to target user's PATH
+        $targetUserSid = $null
+        try {
+            $targetUserSid = (New-Object System.Security.Principal.NTAccount($targetUserName)).Translate(
+                [System.Security.Principal.SecurityIdentifier]).Value
+        } catch {}
+        if ($targetUserSid) {
+            $regPath = "Registry::HKEY_USERS\$targetUserSid\Environment"
+            if (Test-Path $regPath) {
+                $currentPath = (Get-ItemProperty -Path $regPath -Name PATH -ErrorAction SilentlyContinue).PATH
+                if ($currentPath -and $currentPath -notlike "*$adminNpmBin*") {
+                    Set-ItemProperty -Path $regPath -Name PATH -Value "$currentPath;$adminNpmBin"
+                    Write-Detail "Added $adminNpmBin to target user's PATH"
+                } elseif (-not $currentPath) {
+                    Set-ItemProperty -Path $regPath -Name PATH -Value $adminNpmBin
+                    Write-Detail "Set target user's PATH to $adminNpmBin"
+                } else {
+                    Write-Detail "Target user's PATH already contains $adminNpmBin"
+                }
+            } else {
+                Write-Warn "Target user's registry not loaded. User must log in and re-run setup, or manually add $adminNpmBin to PATH."
+            }
+        }
     }
 
     Write-Host ""
@@ -958,8 +953,8 @@ function Invoke-Setup {
     Write-Host ""
     Write-Host "Services registered (not yet started):"
     Write-Host "  minion-agent       - AI Agent (port 8080)"
-    Write-Host "  minion-vnc         - TightVNC Server (port 5900)"
     Write-Host "  minion-websockify  - WebSocket proxy (port 6080)"
+    Write-Host "  MinionVNC (task)   - TightVNC (port 5900, starts at logon)"
     Write-Host ""
     Write-Host "Next step: Connect to HQ (run as regular user):" -ForegroundColor Yellow
     Write-Host "  minion-cli-win configure ``"
@@ -1001,12 +996,12 @@ function Invoke-Uninstall {
     }
     Write-Host ""
 
-    $totalSteps = 7
+    $totalSteps = 6
 
     # Step 1: Stop and remove all NSSM services
     Write-Step 1 $totalSteps "Stopping and removing services..."
     if ($NssmPath -and (Test-Path $NssmPath)) {
-        foreach ($svc in @('minion-cloudflared', 'minion-websockify', 'minion-vnc', 'minion-agent')) {
+        foreach ($svc in @('minion-cloudflared', 'minion-websockify', 'minion-agent')) {
             $status = Invoke-Nssm status $svc
             if ($status) {
                 Invoke-Nssm stop $svc
@@ -1016,6 +1011,12 @@ function Invoke-Uninstall {
         }
     }
 
+    # Remove VNC logon task and legacy NSSM service
+    schtasks /Delete /TN "MinionVNC" /F 2>$null
+    Invoke-Nssm stop minion-vnc
+    Invoke-Nssm remove minion-vnc confirm
+    Write-Detail "VNC logon task and legacy service removed"
+
     # Also stop legacy processes
     Stop-Process -Name tvnserver -Force -ErrorAction SilentlyContinue
     Stop-Process -Name websockify -Force -ErrorAction SilentlyContinue
@@ -1024,7 +1025,7 @@ function Invoke-Uninstall {
 
     # Step 2: Remove firewall rules
     Write-Step 2 $totalSteps "Removing firewall rules..."
-    foreach ($ruleName in @('Minion Agent', 'Minion VNC')) {
+    foreach ($ruleName in @('Minion Agent', 'Minion Terminal', 'Minion VNC')) {
         $existing = Get-NetFirewallRule -DisplayName $ruleName -ErrorAction SilentlyContinue
         if ($existing) {
             Remove-NetFirewallRule -DisplayName $ruleName
@@ -1095,24 +1096,15 @@ function Invoke-Uninstall {
         Write-Detail "Removed rules: core.md"
     }
 
-    # Step 6: Remove minion service account
-    Write-Step 6 $totalSteps "Removing service account..."
-    $MinionSvcUser = 'minion'
-    if (Get-LocalUser -Name $MinionSvcUser -ErrorAction SilentlyContinue) {
-        Remove-LocalUser -Name $MinionSvcUser
-        Write-Detail "Removed local user '$MinionSvcUser'"
-    } else {
-        Write-Detail "Service account '$MinionSvcUser' not found, skipping"
-    }
-    # Remove stored service password
+    # Clean up legacy service account and password file (from v3.1.0-v3.4.x)
     $svcPasswordFile = Join-Path $DataDir '.svc-password'
     if (Test-Path $svcPasswordFile) {
         Remove-Item $svcPasswordFile -Force
-        Write-Detail "Removed service credentials file"
+        Write-Detail "Removed legacy service credentials file"
     }
 
-    # Step 7: Remove Cloudflare Tunnel configuration
-    Write-Step 7 $totalSteps "Removing Cloudflare Tunnel configuration..."
+    # Step 6: Remove Cloudflare Tunnel configuration
+    Write-Step 6 $totalSteps "Removing Cloudflare Tunnel configuration..."
     $cfConfigDir = Join-Path $TargetUserProfile '.cloudflared'
     if (Test-Path $cfConfigDir) {
         Remove-Item $cfConfigDir -Recurse -Force
@@ -1280,13 +1272,24 @@ function Invoke-Configure {
     # Start services (uses sc.exe — works without admin via SDDL)
     $startStep = if ($SetupTunnel) { $totalSteps - 2 } else { $totalSteps - 2 }
     Write-Step ($totalSteps - 1) $totalSteps "Starting services..."
-    # Start VNC/websockify if registered
-    foreach ($svc in @('minion-vnc', 'minion-websockify')) {
-        $svcState = Get-ServiceState $svc
-        if ($svcState -and $svcState -ne 'RUNNING') {
-            sc.exe start $svc 2>&1 | Out-Null
-            Write-Detail "$svc started"
+    # Start VNC (logon task — runs in user session for desktop capture)
+    $vncProcess = Get-Process -Name tvnserver -ErrorAction SilentlyContinue
+    if (-not $vncProcess) {
+        $vncSystemPath = 'C:\Program Files\TightVNC\tvnserver.exe'
+        $vncPortablePath = Join-Path $DataDir 'tightvnc\PFiles\TightVNC\tvnserver.exe'
+        $vncExe = if (Test-Path $vncSystemPath) { $vncSystemPath } elseif (Test-Path $vncPortablePath) { $vncPortablePath } else { $null }
+        if ($vncExe) {
+            Start-Process -FilePath $vncExe -ArgumentList '-run'
+            Write-Detail "TightVNC started (user session)"
         }
+    } else {
+        Write-Detail "TightVNC already running"
+    }
+    # Start websockify service
+    $wsState = Get-ServiceState 'minion-websockify'
+    if ($wsState -and $wsState -ne 'RUNNING') {
+        sc.exe start minion-websockify 2>&1 | Out-Null
+        Write-Detail "minion-websockify started"
     }
     Start-MinionService
 
@@ -1334,16 +1337,24 @@ function Invoke-Configure {
 # ============================================================
 
 function Show-Status {
-    $state = Get-ServiceState 'minion-agent'
-    if ($state) {
-        Write-Host "minion-agent: $state"
-    } else {
-        Write-Host "minion-agent: not installed"
+    try {
+        $response = Invoke-RestMethod -Uri "$AgentUrl/api/status" -TimeoutSec 5 -ErrorAction Stop
+        # Pretty-print the JSON response
+        $response | ConvertTo-Json -Depth 5 | Write-Host
+    }
+    catch {
+        # API unreachable — fall back to service state
+        $state = Get-ServiceState 'minion-agent'
+        if ($state) {
+            Write-Host "minion-agent: $state (API unreachable)"
+        } else {
+            Write-Host "minion-agent: not installed"
+        }
     }
 }
 
 function Show-Daemons {
-    foreach ($svc in @('minion-agent', 'minion-vnc', 'minion-websockify', 'minion-cloudflared')) {
+    foreach ($svc in @('minion-agent', 'minion-websockify', 'minion-cloudflared')) {
         $state = Get-ServiceState $svc
         if ($state) {
             Write-Host "${svc}: $state"
@@ -1351,6 +1362,13 @@ function Show-Daemons {
             Write-Host "${svc}: not installed"
         }
     }
+    # VNC runs as logon task, not NSSM service
+    $vncProc = Get-Process -Name tvnserver -ErrorAction SilentlyContinue
+    if ($vncProc) {
+        Write-Host "vnc (task): RUNNING (PID $($vncProc[0].Id))"
+    } else {
+        Write-Host "vnc (task): not running"
+    }
 }
 
 function Show-Health {
@@ -1383,13 +1401,7 @@ function Show-Diagnose {
     Write-Host ""
 
     Write-Host "Service Account:" -ForegroundColor Yellow
-    $MinionSvcUser = 'minion'
-    $svcUser = Get-LocalUser -Name $MinionSvcUser -ErrorAction SilentlyContinue
-    if ($svcUser) {
-        Write-Host "  User: $MinionSvcUser (Enabled: $($svcUser.Enabled))"
-    } else {
-        Write-Host "  User: NOT FOUND (services run as LocalSystem)" -ForegroundColor Yellow
-    }
+    Write-Host "  Runs as: LocalSystem"
     Write-Host ""
 
     Write-Host "NSSM:" -ForegroundColor Yellow

package/win/postinstall.ps1

@@ -0,0 +1,82 @@
+# postinstall.ps1 — Re-apply file ACLs after npm install -g replaces the package directory.
+# Called automatically from postinstall.js on Windows.
+# Requires Administrator privileges (npm install -g typically runs as admin).
+# Exit silently if not admin or if setup has never been run (no .target-user-profile).
+
+$ErrorActionPreference = 'SilentlyContinue'
+
+# --- Locate setup metadata ---------------------------------------------------
+# During setup, .minion/.target-user-profile is written to the target user's
+# home directory.  We need to find it by scanning user profiles.
+
+function Find-TargetUserProfile {
+    $profiles = Get-CimInstance Win32_UserProfile -ErrorAction SilentlyContinue |
+        Where-Object { -not $_.Special -and $_.LocalPath -and $_.LocalPath -notmatch '\\(systemprofile|LocalService|NetworkService)$' }
+
+    foreach ($p in $profiles) {
+        $candidate = Join-Path $p.LocalPath '.minion\.target-user-profile'
+        if (Test-Path $candidate) {
+            $saved = ([System.IO.File]::ReadAllText($candidate)).Trim()
+            if ($saved -and (Test-Path $saved)) { return $saved }
+        }
+    }
+    return $null
+}
+
+# --- Main ---------------------------------------------------------------------
+
+# Must be admin (npm install -g runs as admin)
+$isAdmin = ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole(
+    [Security.Principal.WindowsBuiltInRole]::Administrator)
+if (-not $isAdmin) { exit 0 }
+
+$TargetUserProfile = Find-TargetUserProfile
+if (-not $TargetUserProfile) { exit 0 }  # setup never ran — nothing to fix
+
+$targetUserName = Split-Path $TargetUserProfile -Leaf
+
+# Determine npm global bin directory (where minion-cli-win.cmd lives)
+$adminNpmBin = Split-Path (Get-Command minion-cli-win -ErrorAction SilentlyContinue).Source -ErrorAction SilentlyContinue
+if (-not $adminNpmBin) {
+    $adminNpmBin = & npm config get prefix 2>$null
+}
+if (-not $adminNpmBin) { exit 0 }
+
+# Skip if the target user's own npm prefix (no ACL fix needed)
+if ($adminNpmBin -eq (Join-Path $TargetUserProfile 'AppData\Roaming\npm')) { exit 0 }
+
+# 1. Grant ReadAndExecute on bin links (minion-cli-win.cmd, hq-win.cmd, etc.)
+$binFiles = @()
+$binFiles += Get-ChildItem -Path $adminNpmBin -Filter '*minion*' -ErrorAction SilentlyContinue
+$binFiles += Get-ChildItem -Path $adminNpmBin -Filter '*hq-win*' -ErrorAction SilentlyContinue
+foreach ($f in $binFiles) {
+    icacls $f.FullName /grant "${targetUserName}:(RX)" /Q 2>$null | Out-Null
+}
+
+# 2. Grant ReadAndExecute on the @geekbeer/minion package directory (recursive)
+$minionPkgDir = Join-Path (Join-Path $adminNpmBin 'node_modules') '@geekbeer\minion'
+if (Test-Path $minionPkgDir) {
+    icacls $minionPkgDir /grant "${targetUserName}:(OI)(CI)RX" /T /Q 2>$null | Out-Null
+}
+
+# 3. Grant traverse access on ancestor directories (idempotent)
+$traverseDirs = @(
+    $adminNpmBin,
+    (Join-Path $adminNpmBin 'node_modules'),
+    (Join-Path $adminNpmBin 'node_modules\@geekbeer')
+)
+$walkDir = $adminNpmBin
+while ($walkDir) {
+    $parent = Split-Path $walkDir -Parent
+    if (-not $parent -or $parent -eq $walkDir) { break }
+    $traverseDirs += $parent
+    $walkDir = $parent
+    if ($parent.Length -le 3) { break }
+}
+foreach ($dir in ($traverseDirs | Select-Object -Unique)) {
+    if (Test-Path $dir) {
+        icacls $dir /grant "${targetUserName}:(RX)" /Q 2>$null | Out-Null
+    }
+}
+
+Write-Host "[@geekbeer/minion] postinstall: file permissions restored for user '$targetUserName'"

package/win/routes/commands.js

@@ -4,7 +4,7 @@
  * Same API as routes/commands.js but uses win/process-manager.js
  */
 
-const { exec, spawn } = require('child_process')
+const { exec, execSync } = require('child_process')
 const { promisify } = require('util')
 const fs = require('fs')
 const path = require('path')
@@ -13,11 +13,11 @@ const execAsync = promisify(exec)
 
 const { verifyToken } = require('../../core/lib/auth')
 const { config } = require('../../core/config')
-const { detectProcessManager, buildAllowedCommands } = require('../lib/process-manager')
+const { detectProcessManager, buildAllowedCommands, getNssmPath } = require('../lib/process-manager')
 
-const SPAWN_LOG = path.join(os.homedir(), '.minion', 'spawn-debug.log')
-function spawnLog(msg) {
-  try { fs.appendFileSync(SPAWN_LOG, `${new Date().toISOString()} ${msg}\n`) } catch {}
+const DEFERRED_LOG = path.join(os.homedir(), '.minion', 'logs', 'deferred-debug.log')
+function deferredLog(msg) {
+  try { fs.appendFileSync(DEFERRED_LOG, `${new Date().toISOString()} ${msg}\n`) } catch {}
 }
 
 const PROC_MGR = detectProcessManager()
@@ -64,29 +64,45 @@ async function commandRoutes(fastify) {
     if (allowedCommand.deferred) {
       console.log(`[Command] Scheduling deferred command: ${command}`)
       setTimeout(() => {
-        if (allowedCommand.spawnArgs) {
-          const [cmd, args] = allowedCommand.spawnArgs
-          spawnLog(`[${command}] spawn: ${cmd} ${JSON.stringify(args)}`)
+        if (allowedCommand.nssmService) {
+          // Register and start a temporary NSSM service to run the script
+          // independently of the minion-agent service process tree.
+          const { scriptPath } = allowedCommand.nssmService
+          const nssmPath = getNssmPath()
+          const svcName = 'minion-update'
+          deferredLog(`[${command}] registering NSSM service: ${svcName}`)
           try {
-            const stderrPath = path.join(os.homedir(), '.minion', `${command}-stderr.log`)
-            const stderrFd = fs.openSync(stderrPath, 'w')
-            const child = spawn(cmd, args, {
-              detached: true,
-              stdio: ['ignore', 'ignore', stderrFd],
-            })
-            child.on('error', (err) => {
-              spawnLog(`[${command}] child error: ${err.message}`)
-              console.error(`[Command] Spawn child error: ${command} - ${err.message}`)
-            })
-            child.on('exit', (code, signal) => {
-              spawnLog(`[${command}] child exit: code=${code} signal=${signal}`)
-            })
-            child.unref()
-            spawnLog(`[${command}] spawned pid=${child.pid}`)
-            console.log(`[Command] Deferred command spawned: ${command} (pid: ${child.pid})`)
+            // Copy nssm.exe to data dir so the service wrapper binary is
+            // outside the npm package directory. This prevents EBUSY when
+            // npm tries to replace the package during update.
+            const dataDirNssm = path.join(os.homedir(), '.minion', 'nssm.exe')
+            fs.copyFileSync(nssmPath, dataDirNssm)
+            const svcNssm = dataDirNssm
+
+            // Clean up any leftover service from a previous run
+            try { execSync(`"${svcNssm}" stop ${svcName} confirm`, { stdio: 'ignore', timeout: 10000 }) } catch {}
+            try { execSync(`"${svcNssm}" remove ${svcName} confirm`, { stdio: 'ignore', timeout: 10000 }) } catch {}
+
+            const powershellPath = 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe'
+            const args = `-NoProfile -ExecutionPolicy Bypass -File "${scriptPath}"`
+
+            execSync(`"${svcNssm}" install ${svcName} "${powershellPath}" ${args}`, { timeout: 10000 })
+            execSync(`"${svcNssm}" set ${svcName} AppDirectory "${path.dirname(scriptPath)}"`, { stdio: 'ignore', timeout: 5000 })
+            execSync(`"${svcNssm}" set ${svcName} Start SERVICE_DEMAND_START`, { stdio: 'ignore', timeout: 5000 })
+            execSync(`"${svcNssm}" set ${svcName} AppExit Default Exit`, { stdio: 'ignore', timeout: 5000 })
+
+            // Redirect service stdout/stderr to log files
+            const svcLogDir = path.join(os.homedir(), '.minion', 'logs')
+            execSync(`"${svcNssm}" set ${svcName} AppStdout "${path.join(svcLogDir, `${command}-svc-stdout.log`)}"`, { stdio: 'ignore', timeout: 5000 })
+            execSync(`"${svcNssm}" set ${svcName} AppStderr "${path.join(svcLogDir, `${command}-svc-stderr.log`)}"`, { stdio: 'ignore', timeout: 5000 })
+
+            // Start the service (runs asynchronously, independent of minion-agent)
+            execSync(`"${svcNssm}" start ${svcName}`, { timeout: 10000 })
+            deferredLog(`[${command}] NSSM service started: ${svcName}`)
+            console.log(`[Command] Deferred command started via NSSM service: ${command}`)
           } catch (err) {
-            spawnLog(`[${command}] spawn threw: ${err.message}`)
-            console.error(`[Command] Deferred spawn failed: ${command} - ${err.message}`)
+            deferredLog(`[${command}] NSSM service failed: ${err.message}`)
+            console.error(`[Command] Deferred NSSM service failed: ${command} - ${err.message}`)
           }
         } else {
           exec(allowedCommand.command, { timeout: 60000, shell: true }, (err) => {