patchwarden 1.5.1 → 1.6.2

package/scripts/checks/mcp-manifest-check.js

@@ -4,7 +4,7 @@ import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { CHATGPT_CORE_TOOL_NAMES, CHATGPT_DIRECT_TOOL_NAMES, CHATGPT_SEARCH_TOOL_NAMES } from "../../dist/tools/toolCatalog.js";
+import { CHATGPT_CORE_TOOL_NAMES, CHATGPT_DIRECT_TOOL_NAMES, CHATGPT_SEARCH_TOOL_NAMES } from "../../dist/tools/catalog/toolCatalog.js";
 
 const root = resolve(fileURLToPath(new URL("../..", import.meta.url)));
 const jsonOnly = process.argv.includes("--json");

package/scripts/checks/mcp-smoke.js

@@ -14,7 +14,10 @@ import { fileURLToPath } from "node:url";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 
-const root = resolve(fileURLToPath(new URL("../..", import.meta.url)));
+const sourceRoot = resolve(fileURLToPath(new URL("../..", import.meta.url)));
+const root = process.env.PATCHWARDEN_TEST_RUNTIME_ROOT
+  ? resolve(process.env.PATCHWARDEN_TEST_RUNTIME_ROOT)
+  : sourceRoot;
 const packageJson = JSON.parse(readFileSync(join(root, "package.json"), "utf-8"));
 const expectedServerVersion = packageJson.version;
 const tempRoot = mkdtempSync(join(tmpdir(), "patchwarden-mcp-"));
@@ -54,6 +57,8 @@ try {
   }), "utf-8");
   writeFileSync(join(workspaceRoot, "hello.txt"), "hello from mcp smoke\n", "utf-8");
   writeFileSync(join(workspaceRoot, ".env"), "SECRET=blocked\n", "utf-8");
+  writeFileSync(join(workspaceRoot, "npm.cmd"), "@echo repo npm hijack executed\r\n@exit /b 99\r\n", "utf-8");
+  writeFileSync(join(workspaceRoot, "git.cmd"), "@echo repo git hijack executed\r\n@exit /b 98\r\n", "utf-8");
   writeFileSync(
     join(workspaceRoot, "package.json"),
     JSON.stringify({
@@ -290,6 +295,33 @@ try {
   }
   ok("create_task accepts inline plans and guarded templates");
 
+  const assessment = await parseToolJson("create_task", {
+    execution_mode: "assess_only",
+    template: "inspect_only",
+    goal: "Inspect package metadata without changing files.",
+    agent: "codex",
+    repo_path: ".",
+    verify_commands: [],
+    scope: ["package.json"],
+    forbidden: ["release/**"],
+  });
+  const assessmentFile = join(workspaceRoot, ".patchwarden", "assessments", assessment.assessment_id, "assessment.json");
+  const assessmentRecord = JSON.parse(readFileSync(assessmentFile, "utf-8"));
+  if (
+    !/^[a-f0-9]{64}$/.test(assessmentRecord.execution_config_hash || "") ||
+    assessmentRecord.assessment_security_snapshot_version !== "assessment-security-v2"
+  ) {
+    throw new Error(`assessment security fingerprint missing: ${JSON.stringify(assessmentRecord)}`);
+  }
+  const assessedTask = await parseToolJson("create_task", {
+    execution_mode: "execute",
+    assessment_id: assessment.assessment_id,
+  });
+  if (assessedTask.status !== "pending" || !assessedTask.task_id) {
+    throw new Error(`two-stage assessment did not create a pending task: ${JSON.stringify(assessedTask)}`);
+  }
+  ok("assess_only then execute preserves the versioned security fingerprint");
+
   const blockedAgent = await client.callTool({
     name: "create_task",
     arguments: { plan_id: plan.plan_id, agent: "missing-agent", repo_path: "." },
@@ -320,7 +352,11 @@ try {
   );
   ok("sensitive file and path escape checks reject access");
 
-  const runner = spawnSync("node", ["dist/runner/cli.js", task.task_id], {
+  // The runner executes with the temporary workspace as cwd; use an absolute
+  // package path so the smoke test does not depend on that workspace having a
+  // copied `dist/` tree.
+  const runnerPath = resolve(root, "dist", "runner", "cli.js");
+  const runner = spawnSync("node", [runnerPath, task.task_id], {
     cwd: root,
     env: { ...process.env, PATCHWARDEN_CONFIG: configPath },
     encoding: "utf-8",
@@ -437,7 +473,9 @@ try {
   writeFileSync(join(directRepo, "package.json"), JSON.stringify({
     name: "direct-fixture",
     private: true,
-    scripts: { test: 'node -e "console.log(\'ok\')"' },
+    // Exercise the npm-script execution path without relying on a temporary
+    // script file or platform-specific quoting.
+    scripts: { test: "node --version" },
   }, null, 2), "utf-8");
 
   writeFileSync(
@@ -517,7 +555,23 @@ try {
     })).content?.[0]?.text || "{}"
   );
   if (bundleResult.status !== "passed" || bundleResult.command_count !== 1 || bundleResult.passed_commands !== 1) {
-    throw new Error(`run_direct_verification_bundle failed: ${JSON.stringify(bundleResult)}`);
+    // This repository and command are generated entirely by this smoke test,
+    // so a bounded log excerpt is safe and makes platform-only CI failures
+    // actionable without weakening the production tool's safe summary.
+    const sessionDir = join(workspaceRoot, ".patchwarden", "direct-sessions", sessionResult.session_id);
+    const verificationPath = join(sessionDir, "verification.json");
+    const logPath = join(sessionDir, "verification.log");
+    const verification = existsSync(verificationPath)
+      ? readFileSync(verificationPath, "utf-8").slice(-2000)
+      : "missing verification.json";
+    const fixtureLog = existsSync(logPath)
+      ? readFileSync(logPath, "utf-8").slice(-2000)
+      : "missing verification.log";
+    throw new Error(
+      `run_direct_verification_bundle failed: ${JSON.stringify(bundleResult)}; ` +
+      `synthetic_fixture_verification=${JSON.stringify(verification)}; ` +
+      `synthetic_fixture_log=${JSON.stringify(fixtureLog)}`
+    );
   }
   const bundleText = JSON.stringify(bundleResult).toLowerCase();
   if (bundleText.includes("stdout_tail") || bundleText.includes("stderr_tail") || bundleText.includes("verification.log")) {

package/scripts/checks/package-manifest-check.js

@@ -1,15 +1,24 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  buildChildEnvironment,
+  resolvePackageManagerInvocation,
+} from "../../dist/runner/processSecurity.js";
 
-const isWindows = process.platform === "win32";
-const command = isWindows ? (process.env.ComSpec || "cmd.exe") : "npm";
-const args = isWindows
-  ? ["/d", "/s", "/c", "npm.cmd pack --dry-run --json"]
-  : ["pack", "--dry-run", "--json"];
-const result = spawnSync(command, args, {
+const root = resolve(fileURLToPath(new URL("../..", import.meta.url)));
+const env = buildChildEnvironment({ cwd: root });
+const invocation = resolvePackageManagerInvocation(process.platform === "win32" ? "npm.cmd" : "npm", root, {
+  pathValue: env.PATH,
+});
+const result = spawnSync(invocation.command, [...invocation.argsPrefix, "pack", "--dry-run", "--json"], {
+  cwd: root,
   encoding: "utf8",
+  env,
   shell: false,
+  windowsHide: true,
 });
 
 if (result.status !== 0) {
@@ -35,6 +44,8 @@ const forbidden = [
   /\.dpapi$/i,
   /^docs\/optimization-proposal\.md$/i,
   /(^|\/)kill-patchwarden\.(cmd|ps1)$/i,
+  /^(?:dist|src)\/test\//i,
+  /^docs\/archive\//i,
 ];
 const leaked = files.filter((file) => forbidden.some((pattern) => pattern.test(file)));
 if (leaked.length > 0) {
@@ -44,8 +55,10 @@ if (leaked.length > 0) {
 }
 
 const required = [
+  "dist/index.js",
+  "dist/index.d.ts",
   "PatchWarden.cmd",
-  "PatchWarden-Desktop.cmd",
+  "scripts/launchers/PatchWarden-Desktop.cmd",
   "scripts/control/manage-patchwarden.ps1",
   "scripts/launchers/Start-PatchWarden-Tunnel.cmd",
   "scripts/launchers/Start-PatchWarden-Direct-Tunnel.cmd",

package/scripts/checks/unit-tests.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { collectMatchingFiles } from "../lib/file-discovery.js";
 
 const scriptDir = resolve(fileURLToPath(new URL(".", import.meta.url)));
 const root = resolve(scriptDir, "..", "..");
@@ -14,10 +15,7 @@ if (!existsSync(unitDir)) {
   process.exit(1);
 }
 
-const testFiles = readdirSync(unitDir)
-  .filter((name) => name.endsWith(".test.js"))
-  .sort()
-  .map((name) => resolve(unitDir, name));
+const testFiles = collectMatchingFiles(unitDir, (name) => name.endsWith(".test.js"));
 
 if (testFiles.length === 0) {
   console.error(`[unit-tests] No compiled unit tests found in ${unitDir}`);

package/scripts/checks/watcher-supervisor-smoke.js

@@ -36,8 +36,9 @@ try {
     }
   });
 
+  await runReusedPidLockScenario();
   await runExternalScenario();
-  console.log("ok - watcher supervisor isolates environment and handles exit, stale heartbeat, retry limit, and external ownership");
+  console.log("ok - watcher supervisor isolates environment and handles exit, stale heartbeat, PID reuse, retry limit, and external ownership");
 } finally {
   for (const child of children) {
     if (child.exitCode === null) child.kill("SIGKILL");
@@ -45,6 +46,32 @@ try {
   rmSync(temp, { recursive: true, force: true });
 }
 
+async function runReusedPidLockScenario() {
+  const fixture = createFixture("reused-pid-lock");
+  mkdirSync(dirname(fixture.lockPath), { recursive: true });
+  writeFileSync(fixture.lockPath, JSON.stringify({
+    pid: process.pid,
+    instance_id: "stale-reused-pid",
+    launcher_pid: 999999,
+    started_at: "2026-01-01T00:00:00.000Z",
+  }), "utf-8");
+  writeFileSync(fixture.heartbeatPath, JSON.stringify({
+    status: "running",
+    pid: process.pid,
+    instance_id: "stale-reused-pid",
+    launcher_pid: 999999,
+    started_at: "2026-01-01T00:00:00.000Z",
+    last_heartbeat_at: "2026-01-01T00:00:00.000Z",
+  }), "utf-8");
+
+  const result = runLauncher(fixture, "healthy", 1, 7_000);
+  if (result.error && result.error.code === "ETIMEDOUT") throw result.error;
+  const attempts = Number(readFileSync(fixture.watcherAttemptPath, "utf-8")) || 0;
+  if (attempts < 1 || !result.stdout.includes("Removed stale watcher lock after PID identity verification")) {
+    throw new Error(`Reused PID lock was not safely retired: ${JSON.stringify({ attempts, stdout: result.stdout, stderr: result.stderr })}`);
+  }
+}
+
 async function runScenario(label, mode, maxRestarts, lifetimeMs, assertState) {
   const fixture = createFixture(label.replace(/[^a-z0-9]+/gi, "-"));
   const result = runLauncher(fixture, mode, maxRestarts, lifetimeMs);
@@ -60,6 +87,8 @@ async function runScenario(label, mode, maxRestarts, lifetimeMs, assertState) {
 async function runExternalScenario() {
   const fixture = createFixture("external");
   const env = fixtureEnv(fixture, "healthy", 7_000);
+  delete env.CONTROL_PLANE_API_KEY;
+  delete env.PATCHWARDEN_OWNER_TOKEN;
   const external = spawn(process.execPath, [fixture.watcherPath], {
     cwd: fixture.project,
     env: {
@@ -137,6 +166,7 @@ function createFixture(name) {
     watcherPath,
     watcherAttemptPath,
     heartbeatPath: join(workspace, ".patchwarden", "watcher-heartbeat.json"),
+    lockPath: join(workspace, ".patchwarden", "watcher.lock"),
     watcherStatusPath: join(localAppData, "patchwarden", "runtime", "watcher-status.json"),
     mockCmd,
     localAppData,
@@ -168,6 +198,9 @@ function fixtureEnv(fixture, mode, lifetimeMs) {
     APPDATA: fixture.appData,
     LOCALAPPDATA: fixture.localAppData,
     CONTROL_PLANE_API_KEY: "test-key",
+    PATCHWARDEN_OWNER_TOKEN: "test-owner-token",
+    PATCHWARDEN_AGENT_ENV_ALLOWLIST: "PATCHWARDEN_TEST_PROVIDER_KEY",
+    PATCHWARDEN_TEST_PROVIDER_KEY: "provider-key-canary",
     WATCHER_FIXTURE_MODE: mode,
     TUNNEL_FIXTURE_LIFETIME_MS: String(lifetimeMs),
   };
@@ -177,6 +210,9 @@ function watcherFixtureSource(attemptPath) {
   return `
 const fs=require('fs');const path=require('path');
 if(!process.env.XDG_CONFIG_HOME){console.error('watcher did not receive XDG_CONFIG_HOME');process.exit(12)}
+if(process.env.CONTROL_PLANE_API_KEY){console.error('watcher received tunnel owner credential');process.exit(13)}
+if(process.env.PATCHWARDEN_OWNER_TOKEN){console.error('watcher received HTTP owner credential');process.exit(14)}
+if(process.env.PATCHWARDEN_TEST_PROVIDER_KEY!=='provider-key-canary'){console.error('watcher did not receive allow-listed provider credential');process.exit(15)}
 let attempt=0;try{attempt=Number(fs.readFileSync(${JSON.stringify(attemptPath)},'utf8'))||0}catch{}
 attempt++;fs.writeFileSync(${JSON.stringify(attemptPath)},String(attempt));
 const cfg=JSON.parse(fs.readFileSync(process.env.PATCHWARDEN_CONFIG,'utf8'));
@@ -192,6 +228,7 @@ else setInterval(write,250);
 function tunnelFixtureSource() {
   return `
 const fs=require('fs');const path=require('path');const args=process.argv.slice(2);const command=args[0]||'';
+if(process.env.PATCHWARDEN_TEST_PROVIDER_KEY){console.error('allow-listed provider credential leaked into tunnel-client');process.exit(22)}
 const flag=(name)=>{const i=args.indexOf(name);return i>=0?args[i+1]:''};
 if(command==='init'){const profile=flag('--profile')||'patchwarden';const mcpCommand=flag('--mcp-command')||'';const yamlDir=path.join(process.env.APPDATA,'tunnel-client');const yamlPath=path.join(yamlDir,profile+'.yaml');fs.mkdirSync(yamlDir,{recursive:true});fs.writeFileSync(yamlPath,'mcp:\\n  commands:\\n    - channel: main\\n      command: \"'+mcpCommand.replace(/\\\\/g,'/')+'\"\\n\\nhealth:\\n  listen_addr: \"127.0.0.1:8080\"\\n');console.log('{}');process.exit(0)}
 if(command==='doctor'){console.log('{}');process.exit(0)}

package/scripts/control/get-patchwarden-health.ps1

@@ -6,7 +6,7 @@ $RuntimeDirectory = Join-Path $env:LOCALAPPDATA "patchwarden\runtime"
 $HealthUrlFile = Join-Path $RuntimeDirectory "tunnel-health-url.txt"
 
 $env:PATCHWARDEN_CONFIG = $ConfigPath
-$healthJson = node --input-type=module -e "Promise.all([import('./dist/tools/healthCheck.js'),import('./dist/tools/registry.js')]).then(([h,r])=>console.log(JSON.stringify(h.healthCheck(r.getToolCatalogSnapshot()))))" 2>$null
+$healthJson = node --input-type=module -e "Promise.all([import('./dist/tools/diagnostics/healthCheck.js'),import('./dist/tools/registry.js')]).then(([h,r])=>console.log(JSON.stringify(h.healthCheck(r.getToolCatalogSnapshot()))))" 2>$null
 if ($LASTEXITCODE -ne 0 -or -not $healthJson) {
   throw "Could not load PatchWarden health information. Run npm.cmd run build first."
 }

package/scripts/control/manage-patchwarden.ps1

@@ -89,6 +89,58 @@ function Read-FileLineSafe {
   }
 }
 
+function Write-JsonFileAtomic {
+  param([string]$Path, [object]$Payload)
+  $directory = Split-Path -Parent $Path
+  New-Item -ItemType Directory -Force -Path $directory | Out-Null
+  $temporary = "$Path.tmp"
+  $Payload | ConvertTo-Json -Depth 5 | Set-Content -LiteralPath $temporary -Encoding UTF8
+  Move-Item -LiteralPath $temporary -Destination $Path -Force
+}
+
+function Write-BackgroundStartingState {
+  param($Definition)
+  $statusPath = Join-Path $Definition.RuntimeDirectory "tunnel-status.json"
+  $previous = Read-JsonFileSafe -Path $statusPath
+  $payload = [ordered]@{
+    status = "starting"
+    reason_code = $null
+    ready = $false
+    attempt = 0
+    pid = $null
+    checked_at = (Get-Date).ToUniversalTime().ToString("o")
+    next_retry_at = $null
+    last_error = $null
+    last_exit_code = $null
+    stdout_tail = @()
+    stderr_tail = @()
+    stdout_log = Join-Path $Definition.RuntimeDirectory "tunnel-client.stdout.log"
+    stderr_log = Join-Path $Definition.RuntimeDirectory "tunnel-client.stderr.log"
+    server_version = if ($previous) { $previous.server_version } else { $null }
+    schema_epoch = if ($previous) { $previous.schema_epoch } else { $null }
+    tool_profile = $Definition.ToolProfile
+    tool_count = if ($previous) { $previous.tool_count } else { $null }
+    tool_names = if ($previous -and $previous.tool_names) { @($previous.tool_names) } else { @() }
+    tool_manifest_sha256 = if ($previous) { $previous.tool_manifest_sha256 } else { $null }
+    tools_ready = [bool]($previous -and $previous.tools_ready)
+    core_tools_ready = [bool]($Definition.Key -eq "core" -and $previous -and $previous.core_tools_ready)
+  }
+  Write-JsonFileAtomic -Path $statusPath -Payload $payload
+}
+
+function Write-BackgroundSupervisorState {
+  param($Definition, [string]$Status, [Nullable[int]]$ProcessId, [string]$ReasonCode = $null)
+  $payload = [ordered]@{
+    status = $Status
+    reason_code = $ReasonCode
+    pid = $ProcessId
+    checked_at = (Get-Date).ToUniversalTime().ToString("o")
+    stdout_log = Join-Path $Definition.RuntimeDirectory "supervisor.stdout.log"
+    stderr_log = Join-Path $Definition.RuntimeDirectory "supervisor.stderr.log"
+  }
+  Write-JsonFileAtomic -Path (Join-Path $Definition.RuntimeDirectory "supervisor-status.json") -Payload $payload
+}
+
 function Test-TunnelHealthEndpoint {
   param([string]$HealthUrl)
   if (-not $HealthUrl) { return $null }
@@ -522,20 +574,33 @@ function Start-Mode {
   if ($Background) {
     $launcherScript = Join-Path $PSScriptRoot "start-patchwarden-tunnel.ps1"
     if (-not (Test-Path -LiteralPath $launcherScript)) { throw "Launcher script not found: $launcherScript" }
+    $backgroundWrapper = Join-Path $PSScriptRoot "run-background-supervisor.ps1"
+    if (-not (Test-Path -LiteralPath $backgroundWrapper)) { throw "Background wrapper not found: $backgroundWrapper" }
     $healthListenAddr = ([Uri]$Definition.HealthBaseUrl).Authority
     $arguments = @(
-      "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", $launcherScript,
+      "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", $backgroundWrapper,
       "-ToolProfile", $Definition.ToolProfile,
       "-Profile", $Definition.Profile,
-      "-HealthListenAddr", $healthListenAddr,
-      "-NoTunnelWebUi"
+      "-HealthListenAddr", $healthListenAddr
     )
     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
+    New-Item -ItemType Directory -Force -Path $Definition.RuntimeDirectory | Out-Null
+    $supervisorStdout = Join-Path $Definition.RuntimeDirectory "supervisor.stdout.log"
+    $supervisorStderr = Join-Path $Definition.RuntimeDirectory "supervisor.stderr.log"
+    Write-BackgroundStartingState -Definition $Definition
+    Set-Content -LiteralPath $supervisorStdout -Value "" -Encoding UTF8 -NoNewline
+    Set-Content -LiteralPath $supervisorStderr -Value "" -Encoding UTF8 -NoNewline
+    try {
+      $process = Start-Process -FilePath "powershell.exe" -ArgumentList $arguments -WorkingDirectory $ProjectRoot -PassThru -WindowStyle Hidden
+      Write-BackgroundSupervisorState -Definition $Definition -Status "running" -ProcessId $process.Id
+    } catch {
+      Write-BackgroundSupervisorState -Definition $Definition -Status "failed" -ProcessId $null -ReasonCode "supervisor_launch_failed"
+      throw
+    }
     Write-Host "[start:$($Definition.Key)] Started hidden supervisor PID $($process.Id). Logs: $($Definition.RuntimeDirectory)" -ForegroundColor Green
     return
   }

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

@@ -0,0 +1,127 @@
+[CmdletBinding()]
+param(
+  [Parameter(Mandatory = $true)]
+  [ValidateSet("core", "direct")]
+  [string]$Mode,
+  [AllowEmptyString()]
+  [string]$TunnelId = "",
+  [Parameter(Mandatory = $true)]
+  [string]$TunnelClientExe,
+  [Parameter(Mandatory = $true)]
+  [string]$ConfigPath,
+  [Parameter(Mandatory = $true)]
+  [string]$CredentialPath,
+  [ValidateSet("environment", "none", "manual")]
+  [string]$ProxyMode = "environment",
+  [AllowEmptyString()]
+  [string]$ProxyUrl = "",
+  [switch]$UseSavedCredential
+)
+
+$ErrorActionPreference = "Stop"
+$ProjectRoot = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)
+$Profile = if ($Mode -eq "direct") { "patchwarden-direct" } else { "patchwarden" }
+$ToolProfile = if ($Mode -eq "direct") { "chatgpt_direct" } else { "chatgpt_core" }
+$LauncherName = if ($Mode -eq "direct") { "patchwarden-mcp-direct.cmd" } else { "patchwarden-mcp-stdio.cmd" }
+$HealthListenAddr = if ($Mode -eq "direct") { "127.0.0.1:8081" } else { "127.0.0.1:8080" }
+$ProfilePath = Join-Path $env:APPDATA "tunnel-client\$Profile.yaml"
+$McpLauncher = (Join-Path $ProjectRoot "scripts\mcp\$LauncherName") -replace "\\", "/"
+$profileBackup = "$ProfilePath.patchwarden-provision-backup-$PID"
+$hadProfile = Test-Path -LiteralPath $ProfilePath
+$runtimeKey = $null
+
+function Write-Result {
+  param([bool]$Ok, [string]$ReasonCode, [string]$NextStep)
+  [ordered]@{ ok = $Ok; reason_code = $ReasonCode; next_step = $NextStep } | ConvertTo-Json -Compress
+}
+
+function Get-DoctorReason {
+  param([string]$Text)
+  $value = [string]$Text
+  if ($value -match '(?i)unauthor|forbidden|invalid.*(?:key|token)|authentication|401|403') { return "authentication_failed" }
+  if ($value -match '(?i)proxy|ECONNREFUSED|connection refused|connect.*failed|timeout|timed out') { return "proxy_unreachable" }
+  if ($value -match '(?i)region|country|unsupported location|not available in') { return "region_unsupported" }
+  return "doctor_failed"
+}
+
+try {
+  if (-not (Test-Path -LiteralPath $TunnelClientExe -PathType Leaf)) { throw "tunnel_client_missing" }
+  if (-not (Test-Path -LiteralPath $ConfigPath -PathType Leaf)) { throw "config_missing" }
+  if (-not (Test-Path -LiteralPath ($McpLauncher -replace "/", "\") -PathType Leaf)) { throw "mcp_launcher_missing" }
+  if ($UseSavedCredential) {
+    if (-not (Test-Path -LiteralPath $ProfilePath -PathType Leaf)) { throw "tunnel_profile_missing" }
+    if (-not (Test-Path -LiteralPath $CredentialPath -PathType Leaf)) { throw "tunnel_credential_missing" }
+    $secure = ConvertTo-SecureString (Get-Content -LiteralPath $CredentialPath -Raw -Encoding UTF8)
+    $bstr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)
+    try { $runtimeKey = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($bstr) }
+    finally { if ($bstr -ne [IntPtr]::Zero) { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr) } }
+  } else {
+    if ([string]::IsNullOrWhiteSpace($TunnelId)) { throw "tunnel_id_missing" }
+    $runtimeKey = [Console]::In.ReadLine()
+  }
+  if ([string]::IsNullOrWhiteSpace($runtimeKey)) { throw "runtime_key_missing" }
+  $env:CONTROL_PLANE_API_KEY = $runtimeKey
+  $env:PATCHWARDEN_CONFIG = $ConfigPath
+  $env:NO_PROXY = "localhost,127.0.0.1,::1"
+
+  $useProxy = $false
+  switch ($ProxyMode) {
+    "manual" {
+      $proxyUri = $null
+      if (-not [Uri]::TryCreate($ProxyUrl, [UriKind]::Absolute, [ref]$proxyUri) -or $proxyUri.Scheme -notin @("http", "https", "socks5")) { throw "proxy_invalid" }
+      if (-not [string]::IsNullOrEmpty($proxyUri.UserInfo)) { throw "proxy_credentials_forbidden" }
+      $env:HTTP_PROXY = $ProxyUrl; $env:HTTPS_PROXY = $ProxyUrl; $env:ALL_PROXY = $ProxyUrl
+      $useProxy = $true
+    }
+    "none" { Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:ALL_PROXY -ErrorAction SilentlyContinue }
+    "environment" { $useProxy = -not [string]::IsNullOrWhiteSpace($env:HTTPS_PROXY) }
+  }
+
+  if (-not $UseSavedCredential) {
+    New-Item -ItemType Directory -Force -Path (Split-Path -Parent $ProfilePath) | Out-Null
+    if ($hadProfile) { Copy-Item -LiteralPath $ProfilePath -Destination $profileBackup -Force }
+    & $TunnelClientExe init --sample sample_mcp_stdio_local --profile $Profile --tunnel-id $TunnelId --mcp-command $McpLauncher --force | Out-Null
+    if ($LASTEXITCODE -ne 0) { throw "profile_init_failed" }
+
+    $profileText = Get-Content -LiteralPath $ProfilePath -Raw -Encoding UTF8
+    if ($profileText -match 'listen_addr:\s*"[^"]*"') {
+      $profileText = $profileText -replace '(listen_addr:\s*)"[^"]*"', "`$1`"$HealthListenAddr`""
+    } elseif ($profileText -match '(?m)^health:') {
+      $profileText = $profileText -replace '(?m)^(health:.*)$', "`$1`n  listen_addr: `"$HealthListenAddr`""
+    } else {
+      $profileText = "$($profileText.TrimEnd())`n`nhealth:`n  listen_addr: `"$HealthListenAddr`"`n"
+    }
+    Set-Content -LiteralPath $ProfilePath -Value $profileText -Encoding UTF8 -NoNewline
+  }
+
+  $doctorArgs = @("doctor", "--profile", $Profile, "--explain", "--json")
+  if ($useProxy) { $doctorArgs += @("--http-proxy", "env:HTTPS_PROXY") }
+  $doctorOutput = (& $TunnelClientExe @doctorArgs 2>&1 | Out-String)
+  if ($LASTEXITCODE -ne 0) { throw (Get-DoctorReason -Text $doctorOutput) }
+
+  if (-not $UseSavedCredential) {
+    $secure = ConvertTo-SecureString $runtimeKey -AsPlainText -Force
+    $encrypted = ConvertFrom-SecureString $secure
+    $credentialDirectory = Split-Path -Parent $CredentialPath
+    New-Item -ItemType Directory -Force -Path $credentialDirectory | Out-Null
+    $credentialTemp = "$CredentialPath.tmp-$PID"
+    Set-Content -LiteralPath $credentialTemp -Value $encrypted -Encoding UTF8 -NoNewline
+    Move-Item -LiteralPath $credentialTemp -Destination $CredentialPath -Force
+  }
+  Remove-Item -LiteralPath $profileBackup -Force -ErrorAction SilentlyContinue
+  Write-Result -Ok $true -ReasonCode "configured" -NextStep "start_core"
+  exit 0
+} catch {
+  if ($hadProfile -and (Test-Path -LiteralPath $profileBackup)) {
+    Move-Item -LiteralPath $profileBackup -Destination $ProfilePath -Force
+  } elseif (-not $hadProfile) {
+    Remove-Item -LiteralPath $ProfilePath -Force -ErrorAction SilentlyContinue
+  }
+  $reason = [string]$_.Exception.Message
+  if ($reason -notmatch '^[a-z0-9_]+$') { $reason = "provisioning_failed" }
+  Write-Result -Ok $false -ReasonCode $reason -NextStep $(if ($reason -eq "authentication_failed") { "replace_runtime_key" } elseif ($reason -eq "proxy_unreachable") { "check_proxy" } else { "review_tunnel_setup" })
+  exit 1
+} finally {
+  $env:CONTROL_PLANE_API_KEY = $null
+  $runtimeKey = $null
+}

package/scripts/control/run-background-supervisor.ps1

@@ -0,0 +1,41 @@
+[CmdletBinding()]
+param(
+  [Parameter(Mandatory = $true)]
+  [ValidateSet("chatgpt_core", "chatgpt_direct")]
+  [string]$ToolProfile,
+
+  [Parameter(Mandatory = $true)]
+  [ValidateSet("patchwarden", "patchwarden-direct")]
+  [string]$Profile,
+
+  [Parameter(Mandatory = $true)]
+  [ValidatePattern('^127\.0\.0\.1:\d+$')]
+  [string]$HealthListenAddr,
+
+  [switch]$SkipWatcher
+)
+
+$ErrorActionPreference = "Stop"
+$launcherScript = Join-Path $PSScriptRoot "start-patchwarden-tunnel.ps1"
+$runtimeName = if ($ToolProfile -eq "chatgpt_direct") { "runtime-direct" } else { "runtime" }
+$runtimeDirectory = Join-Path $env:LOCALAPPDATA "patchwarden\$runtimeName"
+$stdout = Join-Path $runtimeDirectory "supervisor.stdout.log"
+$stderr = Join-Path $runtimeDirectory "supervisor.stderr.log"
+
+New-Item -ItemType Directory -Force -Path $runtimeDirectory | Out-Null
+$arguments = @(
+  "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", $launcherScript,
+  "-ToolProfile", $ToolProfile,
+  "-Profile", $Profile,
+  "-HealthListenAddr", $HealthListenAddr,
+  "-NoTunnelWebUi"
+)
+if ($SkipWatcher) { $arguments += "-SkipWatcher" }
+
+try {
+  & powershell.exe @arguments 1> $stdout 2> $stderr
+  exit $LASTEXITCODE
+} catch {
+  $_ | Out-String | Set-Content -LiteralPath $stderr -Encoding UTF8
+  exit 1
+}