patchwarden 0.6.0 → 0.6.4

package/scripts/checks/unit-tests.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { existsSync, readdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = resolve(fileURLToPath(new URL(".", import.meta.url)));
+const root = resolve(scriptDir, "..", "..");
+const unitDir = resolve(root, "dist", "test", "unit");
+
+if (!existsSync(unitDir)) {
+  console.error(`[unit-tests] Missing compiled test directory: ${unitDir}`);
+  console.error("[unit-tests] Run npm run build before npm run test:unit.");
+  process.exit(1);
+}
+
+const testFiles = readdirSync(unitDir)
+  .filter((name) => name.endsWith(".test.js"))
+  .sort()
+  .map((name) => resolve(unitDir, name));
+
+if (testFiles.length === 0) {
+  console.error(`[unit-tests] No compiled unit tests found in ${unitDir}`);
+  process.exit(1);
+}
+
+const result = spawnSync(process.execPath, ["--test", ...testFiles], {
+  stdio: "inherit",
+});
+
+if (result.error) {
+  console.error(`[unit-tests] Failed to run unit tests: ${result.error.message}`);
+  process.exit(1);
+}
+
+process.exit(typeof result.status === "number" ? result.status : 1);

package/scripts/{watcher-supervisor-smoke.js → checks/watcher-supervisor-smoke.js}

@@ -19,7 +19,7 @@ if (process.platform !== "win32") {
   process.exit(0);
 }
 
-const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const root = resolve(fileURLToPath(new URL("../..", import.meta.url)));
 const temp = mkdtempSync(join(tmpdir(), "patchwarden-watcher-supervisor-"));
 const children = [];
 
@@ -87,13 +87,19 @@ async function runExternalScenario() {
 function createFixture(name) {
   const project = join(temp, name, "patchwarden-fixture");
   const scripts = join(project, "scripts");
+  const controlScripts = join(scripts, "control");
+  const mcpScripts = join(scripts, "mcp");
+  const checkScripts = join(scripts, "checks");
   const runner = join(project, "dist", "runner");
   const workspace = join(project, "workspace");
   mkdirSync(scripts, { recursive: true });
+  mkdirSync(controlScripts, { recursive: true });
+  mkdirSync(mcpScripts, { recursive: true });
+  mkdirSync(checkScripts, { recursive: true });
   mkdirSync(runner, { recursive: true });
   mkdirSync(workspace, { recursive: true });
-  cpSync(join(root, "scripts", "start-patchwarden-tunnel.ps1"), join(scripts, "start-patchwarden-tunnel.ps1"));
-  writeFileSync(join(scripts, "patchwarden-mcp-stdio.cmd"), "@echo off\r\nexit /b 0\r\n", "utf-8");
+  cpSync(join(root, "scripts", "control", "start-patchwarden-tunnel.ps1"), join(controlScripts, "start-patchwarden-tunnel.ps1"));
+  writeFileSync(join(mcpScripts, "patchwarden-mcp-stdio.cmd"), "@echo off\r\nexit /b 0\r\n", "utf-8");
   const manifestFixture = JSON.stringify({
     ok: true,
     server_version: "0.6.0",
@@ -103,7 +109,7 @@ function createFixture(name) {
     tool_names: [],
     tool_manifest_sha256: "a".repeat(64),
   });
-  writeFileSync(join(scripts, "mcp-manifest-check.js"), `process.stdout.write(${JSON.stringify(manifestFixture)});\n`, "utf-8");
+  writeFileSync(join(checkScripts, "mcp-manifest-check.js"), `process.stdout.write(${JSON.stringify(manifestFixture)});\n`, "utf-8");
   writeFileSync(join(project, "dist", "index.js"), "", "utf-8");
   const watcherAttemptPath = join(project, "watcher-attempt.txt");
   const watcherPath = join(runner, "watch.js");
@@ -140,7 +146,7 @@ function createFixture(name) {
 
 function runLauncher(fixture, mode, maxRestarts, lifetimeMs) {
   return spawnSync("powershell.exe", [
-    "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", join(fixture.project, "scripts", "start-patchwarden-tunnel.ps1"),
+    "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", join(fixture.project, "scripts", "control", "start-patchwarden-tunnel.ps1"),
     "-TunnelId", "tunnel_watcher_fixture",
     "-TunnelClientExe", fixture.mockCmd,
     "-ProxyUrl", "http://127.0.0.1:1",

package/scripts/control/control-center-tray.ps1

@@ -0,0 +1,281 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+  Lightweight PatchWarden Control Center system tray entry.
+.DESCRIPTION
+  Builds a Windows NotifyIcon (no Electron, no extra dependencies) whose menu
+  drives the Control Center via its HTTP API with the control token. If the
+  Control Center is not running when the tray starts, it is launched in the
+  background first.
+
+  Menu:
+    - Open Dashboard           (opens the dashboard in the default browser)
+    - Status                   (shows a compact Core/Direct/Watcher summary)
+    - Start All                (POST /api/start-all)
+    - Stop All                 (POST /api/stop-all)
+    - Restart All              (POST /api/restart-all)
+    - Open Logs                (POST /api/open-logs-folder)
+    - Quit Tray                (disposes the tray and exits)
+#>
+param(
+  [int]$Port = 8090,
+  [switch]$NoStartupBalloon
+)
+
+$ErrorActionPreference = "Stop"
+$ProjectRoot = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)
+$BaseUrl = "http://127.0.0.1:$Port/"
+$RuntimeDirectory = Join-Path $env:LOCALAPPDATA "patchwarden\control-center"
+$StatusFile = Join-Path $RuntimeDirectory "control-center-status.json"
+$MutexName = "Local\PatchWarden-Control-Tray-" + ([Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($ProjectRoot)) -replace "[^A-Za-z0-9]", "").Substring(0, 16)
+
+# ── Load WinForms + Drawing ──────────────────────────────────────
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+
+$createdMutex = $false
+$trayMutex = New-Object System.Threading.Mutex($true, $MutexName, [ref]$createdMutex)
+if (-not $createdMutex) {
+  $trayMutex.Dispose()
+  exit 0
+}
+
+# ── Helpers ──────────────────────────────────────────────────────
+
+function Invoke-ControlApi {
+  param([Parameter(Mandatory = $true)][string]$Path, [string]$Method = "POST")
+  $url = $BaseUrl.TrimEnd("/") + $Path
+  # Fetch the control token (in-memory, per server run).
+  $token = $null
+  try {
+    $tokenResp = Invoke-WebRequest -Uri ($BaseUrl.TrimEnd("/") + "/control-token.json") -UseBasicParsing -TimeoutSec 3 -ErrorAction Stop
+    $token = ($tokenResp.Content | ConvertFrom-Json).token
+  } catch {
+    [System.Windows.Forms.MessageBox]::Show(
+      "Could not reach the Control Center at $BaseUrl.`n`nError: $($_.Exception.Message)",
+      "PatchWarden Tray",
+      [System.Windows.Forms.MessageBoxButtons]::OK,
+      [System.Windows.Forms.MessageBoxIcon]::Warning
+    ) | Out-Null
+    return $null
+  }
+  $headers = @{ "X-PatchWarden-Control-Token" = $token }
+  try {
+    $resp = Invoke-WebRequest -Uri $url -Method $Method -Headers $headers -UseBasicParsing -TimeoutSec 60 -ErrorAction Stop
+    return $resp.Content | ConvertFrom-Json
+  } catch {
+    [System.Windows.Forms.MessageBox]::Show(
+      "API call failed: $Path`n`nError: $($_.Exception.Message)",
+      "PatchWarden Tray",
+      [System.Windows.Forms.MessageBoxButtons]::OK,
+      [System.Windows.Forms.MessageBoxIcon]::Warning
+    ) | Out-Null
+    return $null
+  }
+}
+
+function New-PatchWardenTrayIcon {
+  $bitmap = New-Object System.Drawing.Bitmap 32, 32
+  $graphics = [System.Drawing.Graphics]::FromImage($bitmap)
+  $graphics.SmoothingMode = [System.Drawing.Drawing2D.SmoothingMode]::AntiAlias
+  $graphics.Clear([System.Drawing.Color]::Transparent)
+
+  $background = New-Object System.Drawing.SolidBrush -ArgumentList ([System.Drawing.Color]::FromArgb(255, 10, 14, 20))
+  $accent = New-Object System.Drawing.SolidBrush -ArgumentList ([System.Drawing.Color]::FromArgb(255, 45, 212, 168))
+  $darkPen = New-Object System.Drawing.Pen -ArgumentList ([System.Drawing.Color]::FromArgb(255, 5, 9, 14)), 1.5
+
+  $graphics.FillEllipse($background, 1, 1, 30, 30)
+  $points = [System.Drawing.Point[]]@(
+    [System.Drawing.Point]::new(16, 5),
+    [System.Drawing.Point]::new(25, 9),
+    [System.Drawing.Point]::new(24, 17),
+    [System.Drawing.Point]::new(16, 27),
+    [System.Drawing.Point]::new(8, 17),
+    [System.Drawing.Point]::new(7, 9)
+  )
+  $graphics.FillPolygon($accent, $points)
+  $graphics.DrawPolygon($darkPen, $points)
+  $graphics.DrawLine($darkPen, 16, 8, 16, 23)
+  $graphics.DrawLine($darkPen, 11, 15, 21, 15)
+
+  $handle = $bitmap.GetHicon()
+  try {
+    return [System.Drawing.Icon]::FromHandle($handle)
+  } finally {
+    $graphics.Dispose()
+    $background.Dispose()
+    $accent.Dispose()
+    $darkPen.Dispose()
+  }
+}
+
+function Show-TrayBalloon {
+  param([string]$Title, [string]$Text, [System.Windows.Forms.ToolTipIcon]$Icon = [System.Windows.Forms.ToolTipIcon]::Info)
+  if ($null -eq $script:notifyIcon) { return }
+  $script:notifyIcon.BalloonTipTitle = $Title
+  $script:notifyIcon.BalloonTipText = $Text
+  $script:notifyIcon.BalloonTipIcon = $Icon
+  $script:notifyIcon.ShowBalloonTip(2200)
+}
+
+function Invoke-TrayControlAction {
+  param([string]$Path, [string]$SuccessText)
+  $result = Invoke-ControlApi -Path $Path
+  if ($null -eq $result) { return }
+  if ($result.ok -eq $false) {
+    Show-TrayBalloon -Title "PatchWarden needs attention" -Text "Open Dashboard for details." -Icon ([System.Windows.Forms.ToolTipIcon]::Warning)
+    return
+  }
+  Show-TrayBalloon -Title "PatchWarden" -Text $SuccessText
+}
+
+function Test-ControlCenterRunning {
+  # Probe the status endpoint to confirm the server is live and is ours.
+  try {
+    $resp = Invoke-WebRequest -Uri ($BaseUrl.TrimEnd("/") + "/api/control-center-status") -UseBasicParsing -TimeoutSec 2 -ErrorAction Stop
+    if ($resp.StatusCode -eq 200) {
+      $body = $resp.Content | ConvertFrom-Json
+      return [bool]$body.running
+    }
+  } catch {}
+  return $false
+}
+
+function Ensure-ControlCenterRunning {
+  if (Test-ControlCenterRunning) { return $true }
+  Write-Host "[tray] Preparing PatchWarden Control Center..."
+  $startScript = Join-Path $PSScriptRoot "start-control-center.ps1"
+  if (-not (Test-Path -LiteralPath $startScript)) {
+    [System.Windows.Forms.MessageBox]::Show(
+      "start-control-center.ps1 not found at:`n$startScript",
+      "PatchWarden Tray",
+      [System.Windows.Forms.MessageBoxButtons]::OK,
+      [System.Windows.Forms.MessageBoxIcon]::Error
+    ) | Out-Null
+    return $false
+  }
+  try {
+    Start-Process -FilePath "powershell.exe" `
+      -ArgumentList @("-NoProfile", "-ExecutionPolicy", "Bypass", "-File", $startScript, "-NoBrowser") `
+      -WindowStyle Hidden -Wait -ErrorAction Stop
+  } catch {
+    [System.Windows.Forms.MessageBox]::Show(
+      "Failed to start the Control Center:`n$($_.Exception.Message)",
+      "PatchWarden Tray",
+      [System.Windows.Forms.MessageBoxButtons]::OK,
+      [System.Windows.Forms.MessageBoxIcon]::Error
+    ) | Out-Null
+    return $false
+  }
+  # Wait up to 20s for readiness.
+  for ($i = 0; $i -lt 20; $i++) {
+    Start-Sleep -Seconds 1
+    if (Test-ControlCenterRunning) { return $true }
+  }
+  return $false
+}
+
+function Show-CompactStatus {
+  $data = Invoke-ControlApi -Path "/api/status" -Method "GET"
+  if ($null -eq $data) { return }
+
+  $core = if ($data.core.available) { "available" } else { "stopped" }
+  $direct = if ($data.direct.available) { "available" } else { "stopped" }
+  $watcher = if ($data.watcher.status) { [string]$data.watcher.status } else { "unknown" }
+  $workspace = if ($data.workspace_root) { [string]$data.workspace_root } else { "not configured" }
+
+  $message = @(
+    "Core: $core"
+    "Direct: $direct"
+    "Watcher: $watcher"
+    ""
+    "Workspace:"
+    $workspace
+    ""
+    "Open Dashboard for tasks, audit logs, Direct sessions, and setup details."
+  ) -join "`n"
+
+  [System.Windows.Forms.MessageBox]::Show(
+    $message,
+    "PatchWarden Status",
+    [System.Windows.Forms.MessageBoxButtons]::OK,
+    [System.Windows.Forms.MessageBoxIcon]::Information
+  ) | Out-Null
+}
+
+# ── Ensure the control center is up before showing the tray ──────
+[void](Ensure-ControlCenterRunning)
+
+# ── Build the tray icon ──────────────────────────────────────────
+$script:notifyIcon = New-Object System.Windows.Forms.NotifyIcon
+$notifyIcon = $script:notifyIcon
+try {
+  $notifyIcon.Icon = New-PatchWardenTrayIcon
+} catch {
+  $notifyIcon.Icon = [System.Drawing.SystemIcons]::Shield
+}
+$notifyIcon.Text = "PatchWarden: local control"
+$notifyIcon.Visible = $true
+
+# Double-click opens the dashboard.
+$notifyIcon.Add_DoubleClick({
+  Start-Process -FilePath $BaseUrl
+})
+
+# ── Context menu ─────────────────────────────────────────────────
+$menu = New-Object System.Windows.Forms.ContextMenuStrip
+
+[void]$menu.Items.Add("Open Dashboard", $null, {
+  Start-Process -FilePath $BaseUrl
+})
+
+[void]$menu.Items.Add("Status", $null, {
+  Show-CompactStatus
+})
+
+[void]$menu.Items.Add("-")  # separator
+
+[void]$menu.Items.Add("Start All", $null, {
+  Invoke-TrayControlAction -Path "/api/start-all" -SuccessText "Core and Direct are starting in the background."
+})
+
+[void]$menu.Items.Add("Stop All", $null, {
+  Invoke-TrayControlAction -Path "/api/stop-all" -SuccessText "Core and Direct were asked to stop. Tray and dashboard stay available."
+})
+
+[void]$menu.Items.Add("Restart All", $null, {
+  Invoke-TrayControlAction -Path "/api/restart-all" -SuccessText "Core and Direct are restarting in the background."
+})
+
+[void]$menu.Items.Add("-")  # separator
+
+[void]$menu.Items.Add("Open Logs", $null, {
+  Invoke-TrayControlAction -Path "/api/open-logs-folder" -SuccessText "Opening PatchWarden runtime logs."
+})
+
+[void]$menu.Items.Add("-")  # separator
+
+[void]$menu.Items.Add("Quit Tray", $null, {
+  $notifyIcon.Visible = $false
+  [System.Windows.Forms.Application]::Exit()
+})
+
+$notifyIcon.ContextMenuStrip = $menu
+
+# Show a brief balloon on launch.
+if (-not $NoStartupBalloon) {
+  Show-TrayBalloon -Title "PatchWarden is ready" -Text "Right-click for quick controls. Open Dashboard for the full console."
+}
+
+Write-Host "[tray] PatchWarden Control Center tray is active. Right-click the icon for actions."
+
+# Run the application loop. Without this the script exits immediately and the
+# tray disappears. The loop exits when Application::Exit() is called from the
+# Exit menu item.
+[System.Windows.Forms.Application]::Run()
+
+# Cleanup on exit.
+$notifyIcon.Visible = $false
+$notifyIcon.Dispose()
+if ($trayMutex) { $trayMutex.ReleaseMutex(); $trayMutex.Dispose() }
+Write-Host "[tray] Exited."

package/scripts/{get-patchwarden-health.ps1 → control/get-patchwarden-health.ps1}

@@ -1,6 +1,6 @@
 $ErrorActionPreference = "Stop"
 
-$ProjectRoot = Split-Path -Parent $PSScriptRoot
+$ProjectRoot = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)
 $ConfigPath = Join-Path $ProjectRoot "patchwarden.config.json"
 $RuntimeDirectory = Join-Path $env:LOCALAPPDATA "patchwarden\runtime"
 $HealthUrlFile = Join-Path $RuntimeDirectory "tunnel-health-url.txt"
@@ -15,7 +15,7 @@ $packageVersion = [string](Get-Content -LiteralPath (Join-Path $ProjectRoot "pac
 
 $configuredTunnelManifest = $null
 try {
-  $manifestJson = node (Join-Path $ProjectRoot "scripts\mcp-manifest-check.js") 2>$null
+  $manifestJson = node (Join-Path $ProjectRoot "scripts\checks\mcp-manifest-check.js") 2>$null
   if ($LASTEXITCODE -eq 0 -and $manifestJson) {
     $configuredTunnelManifest = $manifestJson | ConvertFrom-Json
   }
@@ -70,7 +70,7 @@ if (Test-Path -LiteralPath $HealthUrlFile) {
 
 $tunnelProcesses = @($safeProcesses | Where-Object { $_.name -eq "tunnel-client.exe" })
 $mcpChildProcesses = @($safeProcesses | Where-Object {
-  $_.command_line -match '(?i)patchwarden-mcp-stdio\.cmd|patchwarden\\dist\\index\.js|patchwarden/scripts/\.\./dist/index\.js'
+  $_.command_line -match '(?i)patchwarden-mcp-stdio\.cmd|patchwarden\\dist\\index\.js|patchwarden/scripts/mcp/../../dist/index.js'
 })
 $deploymentConsistent = [bool](
   $configuredTunnelManifest -and

package/scripts/{manage-patchwarden.ps1 → control/manage-patchwarden.ps1}

@@ -1,4 +1,4 @@
-[CmdletBinding()]
+[CmdletBinding()]
 param(
   [Parameter(Position = 0)]
   [ValidateSet("menu", "start", "stop", "restart", "status", "health", "reset-key", "kill")]
@@ -11,13 +11,14 @@ param(
   [switch]$SkipBuild,
   [switch]$WhatIf,
   [switch]$Json,
+  [switch]$Background,
   [int]$KillTimeoutSeconds = 10
 )
 
 $ErrorActionPreference = "Stop"
 $ProgressPreference = "SilentlyContinue"
-$ProjectRoot = Split-Path -Parent $PSScriptRoot
-$LauncherDirectory = Join-Path $PSScriptRoot "launchers"
+$ProjectRoot = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)
+$LauncherDirectory = Join-Path $ProjectRoot "scripts\launchers"
 $LocalLauncherDirectory = Join-Path $ProjectRoot ".local\launchers"
 $PatchWardenRuntimeRoot = Join-Path $env:LOCALAPPDATA "patchwarden"
 
@@ -518,7 +519,32 @@ function Start-Mode {
   }
   Assert-NoUnsafePortConflicts -Definitions @($Definition)
 
-  $launcher = if (Test-Path -LiteralPath $Definition.LocalLauncher) { $Definition.LocalLauncher } else { $Definition.GenericLauncher }
+  if ($Background) {
+    $launcherScript = Join-Path $PSScriptRoot "start-patchwarden-tunnel.ps1"
+    if (-not (Test-Path -LiteralPath $launcherScript)) { throw "Launcher script not found: $launcherScript" }
+    $healthListenAddr = ([Uri]$Definition.HealthBaseUrl).Authority
+    $arguments = @(
+      "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", $launcherScript,
+      "-ToolProfile", $Definition.ToolProfile,
+      "-Profile", $Definition.Profile,
+      "-HealthListenAddr", $healthListenAddr,
+      "-NoTunnelWebUi"
+    )
+    if (-not $Definition.HasWatcher) { $arguments += "-SkipWatcher" }
+    if ($WhatIf) {
+      Write-Host "[start:$($Definition.Key)] WHAT-IF: start hidden supervisor for $($Definition.Profile)" -ForegroundColor Magenta
+      return
+    }
+    $process = Start-Process -FilePath "powershell.exe" -ArgumentList $arguments -WorkingDirectory $ProjectRoot -PassThru -WindowStyle Hidden
+    Write-Host "[start:$($Definition.Key)] Started hidden supervisor PID $($process.Id). Logs: $($Definition.RuntimeDirectory)" -ForegroundColor Green
+    return
+  }
+
+  # Prefer the project's built-in launcher (scripts\launchers\*.cmd) over
+  # .local\launchers\*.local.cmd. A .local launcher, if present, MUST call
+  # the project root scripts\launchers\*.cmd via relative path (..\..\scripts\launchers\*),
+  # NOT assume its own directory contains the target script.
+  $launcher = if (Test-Path -LiteralPath $Definition.GenericLauncher) { $Definition.GenericLauncher } else { $Definition.LocalLauncher }
   if (-not (Test-Path -LiteralPath $launcher)) { throw "Launcher not found: $launcher" }
   $launcherName = Split-Path -Leaf $launcher
   if ($WhatIf) {

package/scripts/control/restart-control-center.ps1

@@ -0,0 +1,173 @@
+#Requires -Version 5.1
+param(
+  [switch]$NoBrowser,
+  [switch]$NoBuild
+)
+
+$ErrorActionPreference = "Stop"
+
+$ProjectRoot = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)
+$ControlCenterEntry = Join-Path $ProjectRoot "dist\controlCenter.js"
+$ControlCenterEntryFull = [System.IO.Path]::GetFullPath($ControlCenterEntry)
+$ProjectRootFull = [System.IO.Path]::GetFullPath($ProjectRoot).TrimEnd("\")
+$ListenPort = 8090
+$ListenUrl = "http://127.0.0.1:$ListenPort/"
+$RuntimeDirectory = Join-Path $env:LOCALAPPDATA "patchwarden\control-center"
+$StdoutLog = Join-Path $RuntimeDirectory "control-center.stdout.log"
+$StderrLog = Join-Path $RuntimeDirectory "control-center.stderr.log"
+$MaxWaitSeconds = 15
+
+Set-Location -LiteralPath $ProjectRoot
+
+function Test-ControlCenterProcess {
+  param([Parameter(Mandatory = $true)]$ProcessInfo)
+
+  $commandLine = [string]$ProcessInfo.CommandLine
+  if (-not $commandLine) { return $false }
+
+  $normalizedCommand = $commandLine.Replace("/", "\").ToLowerInvariant()
+  $normalizedEntry = $ControlCenterEntryFull.ToLowerInvariant()
+  $normalizedRoot = $ProjectRootFull.ToLowerInvariant()
+
+  return $normalizedCommand.Contains($normalizedEntry) -or (
+    $normalizedCommand.Contains("dist\controlcenter.js") -and
+    $normalizedCommand.Contains($normalizedRoot)
+  )
+}
+
+function Get-ControlCenterProcesses {
+  Get-CimInstance Win32_Process -Filter "Name = 'node.exe'" |
+    Where-Object { Test-ControlCenterProcess $_ }
+}
+
+function Assert-PortIsNotForeign {
+  try {
+    $listeners = Get-NetTCPConnection -LocalPort $ListenPort -State Listen -ErrorAction Stop
+  } catch {
+    return
+  }
+
+  foreach ($listener in $listeners) {
+    $owner = Get-CimInstance Win32_Process -Filter "ProcessId = $($listener.OwningProcess)" -ErrorAction SilentlyContinue
+    if (-not $owner) { continue }
+    if (-not (Test-ControlCenterProcess $owner)) {
+      Write-Host "[error] Port $ListenPort is used by a non-PatchWarden Control Center process." -ForegroundColor Red
+      Write-Host "[error] PID $($owner.ProcessId): $($owner.CommandLine)" -ForegroundColor DarkRed
+      Write-Host "[error] Close that process manually, then rerun this script." -ForegroundColor Yellow
+      exit 1
+    }
+  }
+}
+
+function Stop-ControlCenterProcesses {
+  $processes = @(Get-ControlCenterProcesses)
+  if ($processes.Count -eq 0) {
+    Write-Host "[stop] No existing PatchWarden Control Center process found." -ForegroundColor DarkGray
+    return
+  }
+
+  foreach ($proc in $processes) {
+    Write-Host "[stop] Stopping Control Center PID $($proc.ProcessId)." -ForegroundColor Yellow
+    Stop-Process -Id $proc.ProcessId -ErrorAction SilentlyContinue
+  }
+
+  Start-Sleep -Milliseconds 800
+
+  foreach ($proc in $processes) {
+    $stillRunning = Get-Process -Id $proc.ProcessId -ErrorAction SilentlyContinue
+    if ($stillRunning) {
+      Write-Host "[stop] PID $($proc.ProcessId) did not exit cleanly; forcing stop." -ForegroundColor Yellow
+      Stop-Process -Id $proc.ProcessId -Force -ErrorAction SilentlyContinue
+    }
+  }
+}
+
+function Invoke-BuildIfNeeded {
+  if ($NoBuild) {
+    Write-Host "[build] Skipped by -NoBuild." -ForegroundColor DarkGray
+    return
+  }
+
+  Write-Host "[build] Running npm.cmd run build..." -ForegroundColor Cyan
+  npm.cmd run build
+  if ($LASTEXITCODE -ne 0) {
+    Write-Host "[error] npm.cmd run build exited with code $LASTEXITCODE." -ForegroundColor Red
+    exit $LASTEXITCODE
+  }
+  if (-not (Test-Path -LiteralPath $ControlCenterEntryFull)) {
+    Write-Host "[error] Build completed but dist\controlCenter.js is missing." -ForegroundColor Red
+    exit 1
+  }
+}
+
+function Start-ControlCenter {
+  $nodeCommand = Get-Command node.exe -ErrorAction SilentlyContinue
+  if (-not $nodeCommand) {
+    Write-Host "[error] node.exe was not found on PATH." -ForegroundColor Red
+    exit 1
+  }
+
+  New-Item -ItemType Directory -Force -Path $RuntimeDirectory | Out-Null
+  Remove-Item -LiteralPath $StdoutLog, $StderrLog -Force -ErrorAction SilentlyContinue
+
+  Write-Host "[run] Starting PatchWarden Control Center on $ListenUrl" -ForegroundColor Cyan
+  $process = Start-Process -FilePath $nodeCommand.Source `
+    -ArgumentList @($ControlCenterEntryFull) `
+    -WorkingDirectory $ProjectRoot `
+    -RedirectStandardOutput $StdoutLog `
+    -RedirectStandardError $StderrLog `
+    -PassThru -WindowStyle Hidden
+
+  Start-Sleep -Milliseconds 500
+  if ($process.HasExited) {
+    Write-Host "[error] Control Center exited immediately with code $($process.ExitCode)." -ForegroundColor Red
+    if (Test-Path -LiteralPath $StderrLog) {
+      Get-Content -LiteralPath $StderrLog -Tail 20 -ErrorAction SilentlyContinue
+    }
+    exit 1
+  }
+
+  $ready = $false
+  for ($attempt = 1; $attempt -le $MaxWaitSeconds; $attempt++) {
+    try {
+      $process.Refresh()
+      if ($process.HasExited) {
+        Write-Host "[error] Control Center exited before readiness with code $($process.ExitCode)." -ForegroundColor Red
+        if (Test-Path -LiteralPath $StderrLog) {
+          Get-Content -LiteralPath $StderrLog -Tail 20 -ErrorAction SilentlyContinue
+        }
+        exit 1
+      }
+
+      $response = Invoke-WebRequest -Uri $ListenUrl -UseBasicParsing -TimeoutSec 2 -ErrorAction Stop
+      if ($response.StatusCode -ge 200 -and $response.StatusCode -lt 500) {
+        $ready = $true
+        break
+      }
+    } catch {
+      Start-Sleep -Seconds 1
+    }
+  }
+
+  if (-not $ready) {
+    Write-Host "[error] Control Center did not become ready on $ListenUrl within $MaxWaitSeconds seconds." -ForegroundColor Red
+    Stop-Process -Id $process.Id -Force -ErrorAction SilentlyContinue
+    exit 1
+  }
+
+  Write-Host "[ok] PatchWarden Control Center restarted at $ListenUrl" -ForegroundColor Green
+  Write-Host "[info] node PID $($process.Id)" -ForegroundColor DarkGray
+  Write-Host "[info] stdout log: $StdoutLog" -ForegroundColor DarkGray
+  Write-Host "[info] stderr log: $StderrLog" -ForegroundColor DarkGray
+
+  if (-not $NoBrowser) {
+    $cacheBuster = Get-Date -Format "yyyyMMddHHmmss"
+    Start-Process "$ListenUrl`?restarted=$cacheBuster"
+  }
+}
+
+Assert-PortIsNotForeign
+Stop-ControlCenterProcesses
+Invoke-BuildIfNeeded
+Assert-PortIsNotForeign
+Start-ControlCenter

package/scripts/{restart-patchwarden.ps1 → control/restart-patchwarden.ps1}

@@ -8,7 +8,7 @@ param(
 $ErrorActionPreference = "Stop"
 $ProgressPreference = "SilentlyContinue"
 
-$ProjectRoot = Split-Path -Parent $PSScriptRoot
+$ProjectRoot = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)
 $ConfigPath = Join-Path $ProjectRoot "patchwarden.config.json"
 $RuntimeDirectory = Join-Path $env:LOCALAPPDATA "patchwarden\runtime"