patchwarden 1.5.1 → 1.6.1

package/scripts/control/start-patchwarden-tunnel.ps1

@@ -3,7 +3,10 @@
   [string]$Profile = "patchwarden",
   [ValidateSet("chatgpt_core", "chatgpt_direct")]
   [string]$ToolProfile = "chatgpt_core",
-  [string]$ProxyUrl = $(if ($env:HTTPS_PROXY) { $env:HTTPS_PROXY } else { "http://127.0.0.1:7892" }),
+  [ValidateSet("", "environment", "none", "manual")]
+  [string]$ProxyMode = "",
+  [AllowEmptyString()]
+  [string]$ProxyUrl = "",
   [string]$TunnelClientExe = $(if ($env:TUNNEL_CLIENT_EXE) { $env:TUNNEL_CLIENT_EXE } else { $env:PATCHWARDEN_TUNNEL_CLIENT_EXE }),
   [string]$OpencodeBin = $env:OPENCODE_BIN_DIR,
   [string]$ConfigPath = $env:PATCHWARDEN_CONFIG,
@@ -22,6 +25,47 @@
 
 $ErrorActionPreference = "Stop"
 
+if ([string]::IsNullOrWhiteSpace($ProxyMode)) {
+  $ProxyMode = if ($ToolProfile -eq "chatgpt_direct" -and $env:PATCHWARDEN_DIRECT_PROXY_MODE) {
+    $env:PATCHWARDEN_DIRECT_PROXY_MODE
+  } elseif ($env:PATCHWARDEN_TUNNEL_PROXY_MODE) {
+    $env:PATCHWARDEN_TUNNEL_PROXY_MODE
+  } else {
+    "environment"
+  }
+}
+if ([string]::IsNullOrWhiteSpace($ProxyUrl)) {
+  $ProxyUrl = if ($ToolProfile -eq "chatgpt_direct" -and $env:PATCHWARDEN_DIRECT_PROXY_URL) {
+    $env:PATCHWARDEN_DIRECT_PROXY_URL
+  } else {
+    $env:PATCHWARDEN_TUNNEL_PROXY_URL
+  }
+}
+
+$script:UseProxyArgument = $false
+switch ($ProxyMode) {
+  "manual" {
+    if ([string]::IsNullOrWhiteSpace($ProxyUrl)) { throw "Manual proxy mode requires ProxyUrl." }
+    $proxyUri = $null
+    if (-not [Uri]::TryCreate($ProxyUrl, [UriKind]::Absolute, [ref]$proxyUri) -or $proxyUri.Scheme -notin @("http", "https", "socks5")) {
+      throw "ProxyUrl must use http, https, or socks5."
+    }
+    if (-not [string]::IsNullOrEmpty($proxyUri.UserInfo)) { throw "ProxyUrl must not contain credentials." }
+    $env:HTTP_PROXY = $ProxyUrl
+    $env:HTTPS_PROXY = $ProxyUrl
+    $env:ALL_PROXY = $ProxyUrl
+    $script:UseProxyArgument = $true
+  }
+  "none" {
+    Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:ALL_PROXY -ErrorAction SilentlyContinue
+  }
+  "environment" {
+    $script:UseProxyArgument = -not [string]::IsNullOrWhiteSpace($env:HTTPS_PROXY)
+  }
+  default { throw "Unsupported proxy mode: $ProxyMode" }
+}
+$env:NO_PROXY = "localhost,127.0.0.1,::1"
+
 if ([string]::IsNullOrWhiteSpace($HealthListenAddr)) {
   if ($Profile -eq "patchwarden-direct" -or $ToolProfile -eq "chatgpt_direct") {
     $HealthListenAddr = "127.0.0.1:8081"
@@ -58,12 +102,35 @@ $script:WatcherManaged = $false
 $script:WatcherRestartAttempts = 0
 $script:WatcherHealthySince = $null
 $script:WatcherRestartExhausted = $false
-$DefaultTunnelClientPath = "D:\ai_agent\tunnel-client-v0.0.9--context-conduit-topaz-windows-amd64\tunnel-client.exe"
-
 if ($ToolProfile -eq "chatgpt_direct") {
   $SkipWatcher = $true
 }
 
+$script:AgentEnvironmentNames = @(
+  ([string]$env:PATCHWARDEN_AGENT_ENV_ALLOWLIST -split ';') |
+    Where-Object { $_ -match '^[A-Za-z_][A-Za-z0-9_]*$' } |
+    Select-Object -Unique
+)
+
+function Suspend-AgentProviderEnvironment {
+  $saved = @{}
+  foreach ($name in $script:AgentEnvironmentNames) {
+    $item = Get-Item -LiteralPath "Env:$name" -ErrorAction SilentlyContinue
+    if ($null -ne $item) {
+      $saved[$name] = [string]$item.Value
+      Remove-Item -LiteralPath "Env:$name" -ErrorAction SilentlyContinue
+    }
+  }
+  return $saved
+}
+
+function Restore-AgentProviderEnvironment {
+  param([hashtable]$Saved)
+  foreach ($name in $Saved.Keys) {
+    Set-Item -LiteralPath "Env:$name" -Value $Saved[$name]
+  }
+}
+
 function Assert-File {
   param([string]$Path, [string]$Name)
   if (-not (Test-Path -LiteralPath $Path)) {
@@ -230,9 +297,17 @@ function Get-DiagnosticCode {
 }
 
 function Invoke-TunnelDoctor {
-  $output = (& $TunnelClientExe doctor --profile $Profile --explain --json --http-proxy env:HTTPS_PROXY 2>&1 | Out-String)
+  $doctorArguments = @("doctor", "--profile", $Profile, "--explain", "--json")
+  if ($script:UseProxyArgument) { $doctorArguments += @("--http-proxy", "env:HTTPS_PROXY") }
+  $savedAgentEnvironment = Suspend-AgentProviderEnvironment
+  try {
+    $output = (& $TunnelClientExe @doctorArguments 2>&1 | Out-String)
+    $exitCode = $LASTEXITCODE
+  } finally {
+    Restore-AgentProviderEnvironment -Saved $savedAgentEnvironment
+  }
   return [pscustomobject]@{
-    ExitCode = $LASTEXITCODE
+    ExitCode = $exitCode
     Output = $output
     ReasonCode = Get-DiagnosticCode $output
   }
@@ -306,11 +381,15 @@ function Start-OwnedWatcherProcess {
   $previousWatcherLauncherPid = $env:PATCHWARDEN_WATCHER_LAUNCHER_PID
   $previousXdgConfigHome = $env:XDG_CONFIG_HOME
   $previousPath = $env:PATH
+  $previousControlPlaneApiKey = $env:CONTROL_PLANE_API_KEY
+  $previousOwnerToken = $env:PATCHWARDEN_OWNER_TOKEN
   try {
     $env:PATCHWARDEN_WATCHER_INSTANCE_ID = $script:WatcherInstanceId
     $env:PATCHWARDEN_WATCHER_LAUNCHER_PID = [string]$PID
     $env:XDG_CONFIG_HOME = $OpencodeConfigHome
     if ($OpencodeBin) { $env:PATH = "$OpencodeBin;$env:PATH" }
+    Remove-Item Env:CONTROL_PLANE_API_KEY -ErrorAction SilentlyContinue
+    Remove-Item Env:PATCHWARDEN_OWNER_TOKEN -ErrorAction SilentlyContinue
     $script:WatcherProcess = Start-Process -FilePath $node `
       -ArgumentList @((Join-Path $ProjectRoot "dist\runner\watch.js")) `
       -WorkingDirectory $ProjectRoot -PassThru -WindowStyle Hidden `
@@ -319,6 +398,8 @@ function Start-OwnedWatcherProcess {
     if ($null -eq $previousWatcherInstanceId) { Remove-Item Env:PATCHWARDEN_WATCHER_INSTANCE_ID -ErrorAction SilentlyContinue } else { $env:PATCHWARDEN_WATCHER_INSTANCE_ID = $previousWatcherInstanceId }
     if ($null -eq $previousWatcherLauncherPid) { Remove-Item Env:PATCHWARDEN_WATCHER_LAUNCHER_PID -ErrorAction SilentlyContinue } else { $env:PATCHWARDEN_WATCHER_LAUNCHER_PID = $previousWatcherLauncherPid }
     if ($null -eq $previousXdgConfigHome) { Remove-Item Env:XDG_CONFIG_HOME -ErrorAction SilentlyContinue } else { $env:XDG_CONFIG_HOME = $previousXdgConfigHome }
+    if ($null -eq $previousControlPlaneApiKey) { Remove-Item Env:CONTROL_PLANE_API_KEY -ErrorAction SilentlyContinue } else { $env:CONTROL_PLANE_API_KEY = $previousControlPlaneApiKey }
+    if ($null -eq $previousOwnerToken) { Remove-Item Env:PATCHWARDEN_OWNER_TOKEN -ErrorAction SilentlyContinue } else { $env:PATCHWARDEN_OWNER_TOKEN = $previousOwnerToken }
     $env:PATH = $previousPath
   }
   Write-WatcherStatus -Status "starting"
@@ -368,7 +449,12 @@ function Invoke-WatcherSupervisorTick {
 
 function Get-TunnelHealth {
   if (-not (Test-Path -LiteralPath $HealthUrlFile) -or -not (Test-Path -LiteralPath $PidFile)) { return $null }
-  $output = (& $TunnelClientExe health --json --url-file $HealthUrlFile --pid-file $PidFile 2>&1 | Out-String)
+  $savedAgentEnvironment = Suspend-AgentProviderEnvironment
+  try {
+    $output = (& $TunnelClientExe health --json --url-file $HealthUrlFile --pid-file $PidFile 2>&1 | Out-String)
+  } finally {
+    Restore-AgentProviderEnvironment -Saved $savedAgentEnvironment
+  }
   try { return $output | ConvertFrom-Json } catch { return $null }
 }
 
@@ -505,8 +591,7 @@ if (-not $TunnelClientExe) {
 
 # Search common installation locations
 $commonPaths = @(
-  $DefaultTunnelClientPath
-  Join-Path $env:LOCALAPPDATA "patchwarden\tunnel-client.exe"
+  Join-Path $env:LOCALAPPDATA "PatchWarden\tunnel-client.exe"
   Join-Path $env:APPDATA "tunnel-client\tunnel-client.exe"
   Join-Path $env:USERPROFILE "tunnel-client\tunnel-client.exe"
 )
@@ -525,11 +610,8 @@ if (-not $TunnelClientExe) {
   Write-Host "[input] tunnel-client.exe not found on PATH or common locations." -ForegroundColor Yellow
   Write-Host "        Please provide the full path."
   Write-Host ""
-  Write-Host "        To search for it manually, try one of these commands:" -ForegroundColor Cyan
-  Write-Host "          Get-ChildItem -Path `$env:LOCALAPPDATA -Recurse -Filter tunnel-client.exe -ErrorAction SilentlyContinue" -ForegroundColor Gray
-  Write-Host "          Get-ChildItem -Path `$env:APPDATA -Recurse -Filter tunnel-client.exe -ErrorAction SilentlyContinue" -ForegroundColor Gray
-  Write-Host "          Get-ChildItem -Path C:\ -Recurse -Filter tunnel-client.exe -ErrorAction SilentlyContinue" -ForegroundColor Gray
-  Write-Host "        Or download it from: https://platform.openai.com/docs/guides/mcp-connector" -ForegroundColor Cyan
+  Write-Host "        Desktop users can open Settings -> MCP and tunnel -> Auto detect / Choose file." -ForegroundColor Cyan
+  Write-Host "        The desktop guide explains trusted downloads and SHA256 verification." -ForegroundColor Cyan
   Write-Host ""
   $TunnelClientExe = Read-Host "Path to tunnel-client.exe"
 }
@@ -556,7 +638,7 @@ if (-not $TunnelId -and (Test-Path -LiteralPath $ProfilePath)) {
     $profileContent = Get-Content -LiteralPath $ProfilePath -Raw -Encoding UTF8
     if ($profileContent -match 'tunnel_id:\s*"([^"]+)"') {
       $TunnelId = $matches[1]
-      Write-Host "[detect] Tunnel ID read from profile $Profile`: $TunnelId" -ForegroundColor Green
+      Write-Host "[detect] Tunnel ID read from profile $Profile." -ForegroundColor Green
     }
   } catch {
     Write-Host "[warn] Could not read Tunnel ID from $ProfilePath`: $($_.Exception.Message)" -ForegroundColor Yellow
@@ -580,8 +662,15 @@ if (-not (Test-Path -LiteralPath (Join-Path $ProjectRoot "dist\index.js"))) {
 New-Item -ItemType Directory -Force -Path $RuntimeDirectory | Out-Null
 $env:PATCHWARDEN_CONFIG = $ConfigPath
 Write-Host "[manifest] Verifying the exact $ToolProfile stdio MCP tool catalog..."
-$manifestOutput = (& node (Join-Path $ProjectRoot "scripts\checks\mcp-manifest-check.js") --profile $ToolProfile --json 2>&1 | Out-String).Trim()
-if ($LASTEXITCODE -ne 0) {
+$previousErrorActionPreference = $ErrorActionPreference
+try {
+  $ErrorActionPreference = "Continue"
+  $manifestOutput = (& node (Join-Path $ProjectRoot "scripts\checks\mcp-manifest-check.js") --profile $ToolProfile --json 2>&1 | Out-String).Trim()
+  $manifestExitCode = $LASTEXITCODE
+} finally {
+  $ErrorActionPreference = $previousErrorActionPreference
+}
+if ($manifestExitCode -ne 0) {
   Write-TunnelStatus -Status "stopped" -ReasonCode "tool_manifest_check_failed" -LastError "The tunnel MCP tool manifest preflight failed."
   throw "Tool manifest preflight failed: $manifestOutput"
 }
@@ -601,10 +690,6 @@ Write-Host "[config] health listen addr: $HealthListenAddr"
 Set-SecretEnvIfMissing
 
 $env:PATCHWARDEN_CONFIG = $ConfigPath
-$env:HTTP_PROXY = $ProxyUrl
-$env:HTTPS_PROXY = $ProxyUrl
-$env:ALL_PROXY = $ProxyUrl
-$env:NO_PROXY = "localhost,127.0.0.1,::1"
 
 $profileNeedsInit = $true
 if (Test-Path -LiteralPath $ProfilePath) {
@@ -614,12 +699,17 @@ if (Test-Path -LiteralPath $ProfilePath) {
 
 if ($profileNeedsInit) {
   Write-Host "[init] Creating tunnel-client profile: $Profile"
-  & $TunnelClientExe init `
-    --sample sample_mcp_stdio_local `
-    --profile $Profile `
-    --tunnel-id $TunnelId `
-    --mcp-command $McpStdioLauncherForTunnel `
-    --force
+  $savedAgentEnvironment = Suspend-AgentProviderEnvironment
+  try {
+    & $TunnelClientExe init `
+      --sample sample_mcp_stdio_local `
+      --profile $Profile `
+      --tunnel-id $TunnelId `
+      --mcp-command $McpStdioLauncherForTunnel `
+      --force
+  } finally {
+    Restore-AgentProviderEnvironment -Saved $savedAgentEnvironment
+  }
   Set-ProfileHealthListenAddr -ProfilePath $ProfilePath -HealthListenAddr $HealthListenAddr
 } else {
   Set-ProfileHealthListenAddr -ProfilePath $ProfilePath -HealthListenAddr $HealthListenAddr
@@ -628,7 +718,7 @@ if ($profileNeedsInit) {
 $env:PATCHWARDEN_TUNNEL_STATUS_FILE = $StatusFile
 if (-not $SkipWatcher) { Start-PatchWardenWatcher }
 
-Write-Host "[doctor] Checking tunnel-client profile through the configured proxy..."
+Write-Host "[doctor] Checking tunnel-client profile (proxy mode: $ProxyMode)..."
 $preflightAttempt = 0
 $preflightMaxRetries = 3
 $doctor = Invoke-TunnelDoctor
@@ -665,8 +755,7 @@ Write-Host "[run-config] health url file: $HealthUrlFile"
 Write-Host "[run-config] pid file: $PidFile"
 Write-Host "[run-config] stdout log: $StdoutLogFile"
 Write-Host "[run-config] stderr log: $StderrLogFile"
-Write-Host "[run-config] HTTPS_PROXY: $env:HTTPS_PROXY"
-Write-Host "[run-config] HTTP_PROXY: $env:HTTP_PROXY"
+Write-Host "[run-config] proxy mode: $ProxyMode"
 Write-Host "[run-config] CONTROL_PLANE_API_KEY: $(if ($env:CONTROL_PLANE_API_KEY) { 'set' } else { 'missing' })"
 Write-Host "[run-config] cwd: $ProjectRoot"
 Write-Host ""
@@ -681,18 +770,23 @@ try {
     Write-TunnelStatus -Status "starting" -ReasonCode $null -Ready $false -Attempt $attempt
     $runArguments = @(
       "run", "--profile", $Profile,
-      "--http-proxy", "env:HTTPS_PROXY",
       "--health.url-file", $HealthUrlFile,
       "--pid.file", $PidFile,
       "--log.format", "json"
     )
+    if ($script:UseProxyArgument) { $runArguments += @("--http-proxy", "env:HTTPS_PROXY") }
     if ($openUi) { $runArguments += "--open-web-ui"; $openUi = $false }
     $argumentLine = ($runArguments | ForEach-Object { Quote-ProcessArgument $_ }) -join " "
     Write-Host "[run-config] command: tunnel-client $($runArguments -join ' ')"
     $redirectedCommand = '""' + $TunnelClientExe + '" ' + $argumentLine + ' 1>"' + $StdoutLogFile + '" 2>"' + $StderrLogFile + '""'
     $processArgumentLine = '/d /s /c ' + $redirectedCommand
-    $script:TunnelProcess = Start-Process -FilePath $env:ComSpec -ArgumentList $processArgumentLine `
-      -WorkingDirectory $ProjectRoot -PassThru -WindowStyle Hidden
+    $savedAgentEnvironment = Suspend-AgentProviderEnvironment
+    try {
+      $script:TunnelProcess = Start-Process -FilePath $env:ComSpec -ArgumentList $processArgumentLine `
+        -WorkingDirectory $ProjectRoot -PassThru -WindowStyle Hidden
+    } finally {
+      Restore-AgentProviderEnvironment -Saved $savedAgentEnvironment
+    }
     Write-TunnelStatus -Status "connecting" -ReasonCode $null -Ready $false -Attempt $attempt -ProcessId $script:TunnelProcess.Id
     Write-Host "[run] supervised command PID $($script:TunnelProcess.Id), attempt $attempt"
 

package/{PatchWarden-Control-Tray.cmd → scripts/launchers/PatchWarden-Control-Tray.cmd}

@@ -1,11 +1,11 @@
 @echo off
 setlocal
-cd /d "%~dp0"
+cd /d "%~dp0..\.."
 if /i "%~1"=="--foreground" (
-  powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0scripts\control\control-center-tray.ps1" %*
+  powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0..\control\control-center-tray.ps1" %*
   set EXITCODE=%ERRORLEVEL%
   endlocal & exit /b %EXITCODE%
 )
 
-start "" powershell.exe -NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File "%~dp0scripts\control\control-center-tray.ps1" %*
+start "" powershell.exe -NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File "%~dp0..\control\control-center-tray.ps1" %*
 endlocal & exit /b 0

package/scripts/launchers/PatchWarden-Control.cmd

@@ -0,0 +1,6 @@
+@echo off
+setlocal
+cd /d "%~dp0..\.."
+powershell -ExecutionPolicy Bypass -NoProfile -File "%~dp0..\control\start-control-center.ps1" %*
+set EXITCODE=%ERRORLEVEL%
+endlocal & exit /b %EXITCODE%

package/{PatchWarden-Desktop.cmd → scripts/launchers/PatchWarden-Desktop.cmd}

@@ -1,5 +1,5 @@
 @echo off
 setlocal
-cd /d "%~dp0"
-start "" powershell.exe -NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File "%~dp0scripts\control\control-center-tray.ps1" %*
+cd /d "%~dp0..\.."
+start "" powershell.exe -NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File "%~dp0..\control\control-center-tray.ps1" %*
 endlocal & exit /b 0

package/scripts/launchers/Restart-PatchWarden-Control.cmd

@@ -0,0 +1,6 @@
+@echo off
+setlocal
+cd /d "%~dp0..\.."
+powershell -ExecutionPolicy Bypass -NoProfile -File "%~dp0..\control\restart-control-center.ps1" %*
+set EXITCODE=%ERRORLEVEL%
+endlocal & exit /b %EXITCODE%

package/{Stop-PatchWarden.cmd → scripts/launchers/Stop-PatchWarden.cmd}

@@ -1,7 +1,7 @@
 @echo off
 setlocal
-cd /d "%~dp0"
-powershell -ExecutionPolicy Bypass -NoProfile -File "%~dp0scripts\control\stop-patchwarden.ps1" %*
+cd /d "%~dp0..\.."
+powershell -ExecutionPolicy Bypass -NoProfile -File "%~dp0..\control\stop-patchwarden.ps1" %*
 set EXITCODE=%ERRORLEVEL%
 if not "%EXITCODE%"=="0" (
   echo.

package/scripts/lib/clean-generated-output.js

@@ -0,0 +1,11 @@
+import { rmSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+
+export function cleanGeneratedOutput(projectRoot, outputPath) {
+  const root = resolve(projectRoot);
+  const output = resolve(outputPath);
+  if (dirname(output) !== root || basename(output).toLowerCase() !== "dist") {
+    throw new Error(`Refusing to clean non-dist output: ${output}`);
+  }
+  rmSync(output, { recursive: true, force: true });
+}

package/scripts/lib/file-discovery.js

@@ -0,0 +1,12 @@
+import { readdirSync } from "node:fs";
+import { resolve } from "node:path";
+
+export function collectMatchingFiles(directory, predicate) {
+  return readdirSync(directory, { withFileTypes: true })
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .flatMap((entry) => {
+      const path = resolve(directory, entry.name);
+      if (entry.isDirectory()) return collectMatchingFiles(path, predicate);
+      return entry.isFile() && predicate(entry.name, path) ? [path] : [];
+    });
+}

package/scripts/release/desktop-preflight.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(fileURLToPath(new URL("../..", import.meta.url)));
+const desktopRoot = join(root, "desktop");
+const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+const argv = process.argv.slice(2);
+const requireClean = argv.includes("--require-clean");
+const skipUiSmoke = argv.includes("--skip-ui-smoke");
+
+function option(name) {
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1] : null;
+}
+
+function json(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function directoryStats(directory) {
+  let files = 0;
+  let bytes = 0;
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      const nested = directoryStats(path);
+      files += nested.files;
+      bytes += nested.bytes;
+    } else if (entry.isFile()) {
+      files += 1;
+      bytes += statSync(path).size;
+    }
+  }
+  return { files, bytes };
+}
+
+function spawnSpec(command, args) {
+  if (process.platform === "win32" && /\.cmd$/i.test(command)) {
+    return { command: process.env.ComSpec || "cmd.exe", args: ["/d", "/s", "/c", command, ...args] };
+  }
+  return { command, args };
+}
+
+function capture(command, args, cwd = root) {
+  const spec = spawnSpec(command, args);
+  const result = spawnSync(spec.command, spec.args, { cwd, encoding: "utf8", windowsHide: true, maxBuffer: 64 * 1024 * 1024 });
+  if (result.status !== 0) throw new Error(`${command} ${args.join(" ")} failed: ${result.stderr || result.stdout || result.error?.message || "unknown error"}`);
+  return String(result.stdout || "").trim();
+}
+
+const rootPackage = json(join(root, "package.json"));
+const rootLock = json(join(root, "package-lock.json"));
+const desktopPackage = json(join(desktopRoot, "package.json"));
+const desktopLock = json(join(desktopRoot, "package-lock.json"));
+const versionSource = readFileSync(join(root, "src", "version.ts"), "utf8");
+const sourceVersion = versionSource.match(/PATCHWARDEN_VERSION\s*=\s*"([^"]+)"/)?.[1] || null;
+const versions = [rootPackage.version, rootLock.version, rootLock.packages?.[""]?.version, desktopPackage.version, desktopLock.version, desktopLock.packages?.[""]?.version, sourceVersion];
+if (versions.some((version) => version !== rootPackage.version)) throw new Error(`Version mismatch: ${versions.join(", ")}`);
+if (process.platform !== "win32") throw new Error("Desktop preflight requires Windows.");
+
+const gitStatus = capture("git", ["status", "--porcelain=v1", "-z"]);
+const changedFileCount = gitStatus ? gitStatus.split("\0").filter(Boolean).length : 0;
+if (requireClean && changedFileCount > 0) throw new Error(`Release preflight requires a clean worktree; found ${changedFileCount} changed paths.`);
+
+const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+const defaultOutput = join(root, "release", `desktop-preflight-${rootPackage.version}-${stamp}`);
+const outputRoot = resolve(option("--output") || defaultOutput);
+if (existsSync(outputRoot)) throw new Error(`Preflight output already exists: ${outputRoot}`);
+mkdirSync(outputRoot, { recursive: true });
+
+const report = {
+  schema_version: "patchwarden-desktop-preflight-v1",
+  status: "running",
+  started_at: new Date().toISOString(),
+  finished_at: null,
+  version: rootPackage.version,
+  output_directory: outputRoot,
+  source: {
+    branch: capture("git", ["branch", "--show-current"]),
+    head: capture("git", ["rev-parse", "HEAD"]),
+    dirty: changedFileCount > 0,
+    changed_path_count: changedFileCount,
+    status_sha256: sha256(gitStatus),
+    tracked_diff_sha256: sha256(capture("git", ["diff", "--binary", "HEAD"])),
+  },
+  environment: {
+    platform: process.platform,
+    arch: process.arch,
+    node: process.version,
+    npm: capture(npmCommand, ["--version"]),
+    electron: desktopPackage.devDependencies.electron,
+    electron_builder: desktopPackage.devDependencies["electron-builder"],
+  },
+  options: { require_clean: requireClean, skip_ui_smoke: skipUiSmoke },
+  checks: [],
+  package: null,
+  runtime_manifest: null,
+  ui_smoke: null,
+  artifact: null,
+  error: null,
+};
+
+function saveReport() {
+  writeFileSync(join(outputRoot, "preflight-report.json"), `${JSON.stringify(report, null, 2)}\n`, "utf8");
+  const lines = [
+    `# PatchWarden Desktop ${report.version} preflight`,
+    "",
+    `- Status: ${report.status}`,
+    `- Source: ${report.source.branch} @ ${report.source.head}`,
+    `- Dirty baseline: ${report.source.dirty} (${report.source.changed_path_count} paths, status SHA256 ${report.source.status_sha256})`,
+    `- Node/npm: ${report.environment.node} / ${report.environment.npm}`,
+    `- Electron: ${report.environment.electron}`,
+    `- Output: ${report.output_directory}`,
+    "",
+    "## Checks",
+    "",
+    ...report.checks.map((check) => `- ${check.ok ? "PASS" : "FAIL"} ${check.name} (${check.duration_ms} ms)`),
+    "",
+    report.runtime_manifest ? `Packaged runtime: ${report.runtime_manifest.tool_profile}, ${report.runtime_manifest.tool_count} tools, manifest SHA256 ${report.runtime_manifest.tool_manifest_sha256}.` : "Packaged runtime: not verified.",
+    report.ui_smoke ? `UI smoke: ${report.ui_smoke.ok ? "passed" : "failed"}.` : "UI smoke: not run.",
+    report.error ? `\nError: ${report.error}` : "",
+  ];
+  writeFileSync(join(outputRoot, "preflight-report.md"), `${lines.join("\n")}\n`, "utf8");
+}
+
+function run(name, command, args, cwd = root) {
+  const started = Date.now();
+  const spec = spawnSpec(command, args);
+  const result = spawnSync(spec.command, spec.args, { cwd, encoding: "utf8", windowsHide: true, maxBuffer: 128 * 1024 * 1024 });
+  const stdout = String(result.stdout || "");
+  const stderr = String(result.stderr || "");
+  if (stdout) process.stdout.write(stdout);
+  if (stderr) process.stderr.write(stderr);
+  const check = { name, ok: result.status === 0, exit_code: result.status, duration_ms: Date.now() - started };
+  report.checks.push(check);
+  saveReport();
+  if (!check.ok) throw new Error(`${name} failed with exit code ${result.status ?? "unknown"}: ${stderr || result.error?.message || "see command output"}`);
+  return stdout;
+}
+
+let isolatedRoot = null;
+try {
+  run("root clean build", npmCommand, ["run", "build"]);
+  run("build output contract", npmCommand, ["run", "check:build-output"]);
+  const unitOutput = run("root unit tests", npmCommand, ["run", "test:unit"]);
+  const desktopOutput = run("desktop tests", npmCommand, ["run", "desktop:test"]);
+  const packageOutput = run("npm package surface", npmCommand, ["run", "verify:package"]);
+  run("desktop staging", npmCommand, ["run", "desktop:stage"]);
+  run("Electron directory package", npmCommand, ["exec", "electron-builder", "--", "--win", "dir", "--x64", `--config.directories.output=${outputRoot}`], desktopRoot);
+
+  report.package = {
+    npm_file_count: Number(packageOutput.match(/OK:\s+(\d+) package files/)?.[1] || 0),
+    root_unit_tests: Number([...unitOutput.matchAll(/tests\s+(\d+)/g)].at(-1)?.[1] || 0),
+    desktop_tests: Number([...desktopOutput.matchAll(/tests\s+(\d+)/g)].at(-1)?.[1] || 0),
+  };
+
+  const unpackedRoot = join(outputRoot, "win-unpacked");
+  const executable = join(unpackedRoot, "PatchWarden.exe");
+  const packagedCore = join(unpackedRoot, "resources", "core");
+  if (!existsSync(executable) || !existsSync(packagedCore)) throw new Error("Electron directory package is missing its executable or core runtime.");
+  for (const forbidden of ["dist/test", "src/test", "docs/archive", "scripts/checks/doctor-smoke.js"]) {
+    if (existsSync(join(packagedCore, forbidden))) throw new Error(`Packaged core contains development-only path: ${forbidden}`);
+  }
+  const packagedChecks = readdirSync(join(packagedCore, "scripts", "checks")).sort();
+  if (JSON.stringify(packagedChecks) !== JSON.stringify(["mcp-manifest-check.js"])) {
+    throw new Error(`Packaged core has unexpected check scripts: ${packagedChecks.join(", ")}`);
+  }
+  const coreStats = directoryStats(packagedCore);
+  report.package.packaged_core_file_count = coreStats.files;
+  report.package.packaged_core_size_bytes = coreStats.bytes;
+
+  isolatedRoot = join(tmpdir(), `patchwarden-preflight-${process.pid}-${Date.now()}`);
+  cpSync(packagedCore, isolatedRoot, { recursive: true });
+  const manifestOutput = run("isolated packaged runtime manifest", process.execPath, ["scripts/checks/mcp-manifest-check.js", "--profile", "chatgpt_core"], isolatedRoot);
+  report.runtime_manifest = JSON.parse(manifestOutput);
+  if (!report.runtime_manifest.ok || report.runtime_manifest.server_version !== rootPackage.version || report.runtime_manifest.tool_count !== 26) {
+    throw new Error("Packaged runtime manifest did not match the 1.6.1 26-tool contract.");
+  }
+
+  if (!skipUiSmoke) {
+    const smokeOutput = run("unpacked desktop UI smoke", process.execPath, ["scripts/smoke-unpacked.mjs", "--exe", executable, "--output", join(outputRoot, "ui-smoke")], desktopRoot);
+    report.ui_smoke = JSON.parse(smokeOutput.trim().split(/\r?\n/).at(-1));
+    if (!report.ui_smoke.ok) throw new Error("Unpacked desktop UI smoke did not pass.");
+  }
+
+  report.artifact = {
+    name: basename(executable),
+    size_bytes: readFileSync(executable).length,
+    sha256: sha256(readFileSync(executable)),
+  };
+  report.status = "passed";
+} catch (error) {
+  report.status = "failed";
+  report.error = error instanceof Error ? error.message : String(error);
+  throw error;
+} finally {
+  if (isolatedRoot) rmSync(isolatedRoot, { recursive: true, force: true });
+  report.finished_at = new Date().toISOString();
+  saveReport();
+}
+
+console.log(`[desktop-preflight] PASS: ${outputRoot}`);