patchwarden 0.4.0

package/docs/demo.md

@@ -0,0 +1,58 @@
+# PatchWarden Demo
+
+This is a privacy-safe demo flow for GitHub. It uses placeholder workspace
+names and avoids real tunnel IDs, account names, API keys, or local user paths.
+
+## Demo: ChatGPT Lists A Workspace
+
+Prompt in ChatGPT with the PatchWarden connector selected:
+
+```text
+Use the patchwarden tool list_workspace to list the configured workspace.
+```
+
+Expected response shape:
+
+```text
+Workspace files:
+
+| Name         | Type | Size |
+|--------------|------|------|
+| README.md    | file | ...  |
+| package.json | file | ...  |
+```
+
+![PatchWarden ChatGPT connector demo](assets/patchwarden-chatgpt-demo.svg)
+
+## Demo: Plan And Execute
+
+Prompt in ChatGPT:
+
+```text
+Use patchwarden to:
+1. read README.md
+2. save a plan that appends a Usage section
+3. create a task with an explicit repo_path and verify_commands
+4. call wait_for_task repeatedly while continuation_required is true
+5. review get_task_summary, audit_task, result, diff, and verification logs
+```
+
+Expected artifacts under the configured workspace:
+
+```text
+.patchwarden/tasks/<task_id>/status.json
+.patchwarden/tasks/<task_id>/result.md
+.patchwarden/tasks/<task_id>/git.diff
+.patchwarden/tasks/<task_id>/test.log
+```
+
+## Privacy Notes
+
+Do not publish:
+
+- real API keys or runtime keys
+- real tunnel IDs
+- ChatGPT account names or workspace IDs
+- screenshots containing sidebars with private chat/project names
+- `patchwarden.config.json`
+- `.patchwarden/` task history from private workspaces

package/docs/migration-from-safe-bifrost.md

@@ -0,0 +1,31 @@
+# Migrating from Safe-Bifrost to PatchWarden
+
+PatchWarden v0.4.0 is an intentional pre-1.0 breaking rename. It does not load
+legacy names automatically.
+
+## Package and commands
+
+- Replace `safe-bifrost` with `patchwarden` in npm dependencies and MCP client
+  commands.
+- Replace the old runner command with `patchwarden-runner`.
+- Replace Windows launchers with the corresponding `PatchWarden` launchers.
+
+## Configuration
+
+1. Copy `safe-bifrost.config.json` to `patchwarden.config.json`.
+2. Change `plansDir` and `tasksDir` from `.safe-bifrost/...` to
+   `.patchwarden/...`.
+3. Rename every `SAFE_BIFROST_*` environment variable to `PATCHWARDEN_*`.
+4. Replace `x-safe-bifrost-token` with `x-patchwarden-token` for local HTTP
+   authentication.
+
+## Local state
+
+PatchWarden writes new task state under `.patchwarden`, runtime status under
+`%LOCALAPPDATA%\patchwarden`, and the DPAPI tunnel credential under
+`%APPDATA%\patchwarden`. Old directories are not deleted or migrated
+automatically. Keep them as a backup until the new installation is verified.
+
+The old DPAPI credential is intentionally not copied. Run the new tunnel
+launcher and enter the control-plane key again so PatchWarden can save it under
+the new application directory.

package/docs/release-v0.3.0.md

@@ -0,0 +1,43 @@
+# Safe-Bifrost v0.3.0
+
+Safe-Bifrost v0.3.0 makes ChatGPT-managed local agent work easier to monitor,
+verify, and accept without weakening the workspace and command boundaries.
+
+## Highlights
+
+- Adds `wait_for_task` so ChatGPT can stay in the tool loop until a task is
+  terminal, plus `get_task_summary` for one-call acceptance evidence.
+- Requires an explicit existing repository directory and supports both
+  workspace-relative and absolute `repo_path` values.
+- Adds independent multi-command `verify_commands` while keeping
+  `test_command` compatibility.
+- Generates structured `result.json`, `verify.json`, readable `verify.log`,
+  and a complete `diff.patch` for every terminal task.
+- Adds task-scoped file statistics, clear large/no-diff responses, and avoids
+  including unchanged pre-existing workspace files in task diff evidence.
+- Detects changes outside `resolved_repo_path`, marks the task
+  `failed_scope_violation`, invalidates verification acceptance, and creates a
+  review-only `rollback_scope_violation_plan.md`.
+- Allows ordinary long build/test/release plans while blocking explicit
+  credential theft, destructive disk deletion, and malicious persistence.
+- Redacts secret-like values in ordinary task artifacts instead of rejecting
+  the entire read.
+- Expands `doctor`, stdio/HTTP MCP smoke tests, lifecycle coverage, packaging
+  checks, and ChatGPT workflow documentation.
+
+## Compatibility note
+
+`create_task` now requires `repo_path`. Existing clients that omitted it must
+pass an existing directory under `workspaceRoot`. `test_command` remains
+supported and is converted into a one-entry verification list.
+
+## Verification
+
+- `npm test`: 63 security tests, 14 lifecycle tests, and doctor smoke passed
+- `npm run test:mcp`: passed
+- `npm run test:http-mcp`: 11 passed
+- `npm run doctor`: 47 OK, 0 WARN, 0 FAIL
+- `npm run pack:clean`: passed
+- `npm run verify:package`: passed
+
+Tracked in [issue #1](https://github.com/jiezeng2004-design/safe-bifrost/issues/1).

package/docs/release-v0.4.0.md

@@ -0,0 +1,74 @@
+# PatchWarden v0.4.0
+
+PatchWarden v0.4.0 hardens the ChatGPT-to-local-agent task loop without
+weakening workspace, command, or sensitive-file boundaries.
+
+This release also completes the project rename from Safe-Bifrost to
+PatchWarden. The npm package is now `patchwarden`; the old package is retained
+only to point existing users to the new name.
+
+## Highlights
+
+- Adds supervised Windows tunnel recovery with local readiness probes,
+  structured failure categories, capped retry backoff, and redacted runtime
+  state under `%LOCALAPPDATA%\patchwarden\runtime`.
+- Adds `Check-PatchWarden-Health.cmd` for diagnostics when the MCP tunnel itself
+  is unreachable.
+- Expands `health_check` with workspace, tasks directory, watcher, agent, tunnel,
+  and last-error evidence; local HTTP `/healthz` and `/readyz` are also available.
+- Lets `create_task` use exactly one of a saved `plan_id`, persisted
+  `inline_plan`, or a guarded task template.
+- Adds `inspect_only`, `feature_small`, `fix_tests`, `release_check`, and safe
+  review-only `rollback_scope_violation` templates.
+- Enforces no-change templates with `failed_policy_violation`.
+- Adds deterministic failure guidance through `failure_reason`,
+  `failed_command`, `suggested_next_action`, and `safe_followup_prompt`.
+- Adds standalone `file-stats.json` while preserving complete `diff.patch`,
+  `changed-files.json`, and the v0.3.0 acceptance contract.
+- Adds deterministic `full` and `chatgpt_core` tool profiles. Tunnel stdio uses
+  an exact 16-tool core manifest while ordinary local launches remain on the
+  22-tool full profile.
+- Adds schema-inclusive tool manifest hashing, `schema_epoch`, server version,
+  and a real MCP stdio preflight before tunnel startup.
+- Adds structured `create_task.next_tool_call`, preferred
+  `wait_for_task(timeout_seconds)`, legacy `wait_seconds` compatibility, and a
+  complete terminal summary in the wait response.
+- Adds recursive redaction for structured result/verification summaries and
+  concise verification counts/headlines such as `166 passed`.
+- Adds explicit `get_diff.patch_mode` values for textual, no-change, and
+  hash-only evidence, including a reason when a textual patch is unavailable.
+- Enhances the local health report with process source/version evidence and
+  mixed-version warnings without automatically ending any process.
+- Adds first-class watcher stale/missing evidence, structured pending artifact
+  responses, and controlled recovery for launcher-owned watcher processes.
+- Reports stale client catalogs as `tool_catalog_mismatch` with the active
+  profile, schema epoch, manifest hash, and Connector refresh guidance.
+- Fixes a plan-guard bypass where generic security wording could suppress a
+  later credential-access instruction. Every dangerous occurrence is now
+  evaluated independently and only directly negated actions are allowed.
+
+## Compatibility
+
+The MCP tool names and `save_plan` -> `create_task` workflow remain stable, but
+the product rename is intentionally breaking: old CLI names, `SAFE_BIFROST_*`
+variables, `safe-bifrost.config.json`, `.safe-bifrost/`, and legacy AppData
+paths are not loaded. Follow the migration guide before replacing an existing
+installation. `repo_path`, configured agent validation, and exact
+verification-command allowlists remain mandatory.
+
+## Verification
+
+Run the following from Windows PowerShell:
+
+```powershell
+npm.cmd test
+npm.cmd run test:mcp
+npm.cmd run test:http-mcp
+npm.cmd run doctor
+npm.cmd run check:tool-manifest
+npm.cmd run check:brand
+npm.cmd run test:tunnel-supervisor
+npm.cmd run test:watcher-supervisor
+npm.cmd run pack:clean
+npm.cmd run verify:package
+```

package/examples/config.example.json

@@ -0,0 +1,40 @@
+{
+  "workspaceRoot": "D:/path/to/test-project",
+  "plansDir": ".patchwarden/plans",
+  "tasksDir": ".patchwarden/tasks",
+  "toolProfile": "full",
+  "agents": {
+    "codex": {
+      "command": "codex",
+      "args": ["exec", "--cd", "{repo}", "{prompt}"]
+    },
+    "opencode": {
+      "command": "opencode",
+      "args": ["run", "{prompt}"]
+    }
+  },
+  "allowedTestCommands": [
+    "npm test",
+    "npm run test",
+    "npm run lint",
+    "npm run format:check",
+    "npm run build",
+    "npm run dist",
+    "npm run doctor",
+    "pnpm test",
+    "pnpm run test",
+    "pnpm run lint",
+    "pnpm run format:check",
+    "pnpm run build",
+    "pnpm run dist",
+    "pnpm run doctor",
+    "yarn test",
+    "pytest",
+    "cargo test",
+    "go test ./..."
+  ],
+  "maxReadFileBytes": 200000,
+  "defaultTaskTimeoutSeconds": 900,
+  "maxTaskTimeoutSeconds": 3600,
+  "watcherStaleSeconds": 30
+}

package/examples/openai-tunnel/README.md

@@ -0,0 +1,48 @@
+# OpenAI Tunnel Examples
+
+This directory contains privacy-safe examples for connecting PatchWarden to
+ChatGPT through an OpenAI Secure MCP Tunnel.
+
+Do not commit real API keys, tunnel IDs, ChatGPT workspace IDs, account names,
+or local private paths.
+
+## Files
+
+- `tunnel-client.example.yaml` - profile snippets for stdio and HTTP mode
+- `chatgpt-test-prompt.md` - prompt to verify the connector from ChatGPT
+
+## Recommended Windows Flow
+
+1. Configure `patchwarden.config.json`.
+2. Run `npm.cmd run build`.
+3. Use `scripts/patchwarden-mcp-stdio.cmd` as the tunnel MCP command.
+4. Start `npm.cmd run watch` in a separate terminal.
+5. Start `tunnel-client run` or use `Start-PatchWarden-Tunnel.cmd`.
+6. Create a ChatGPT Connector using the tunnel channel.
+7. After a tunnel/schema refresh, reconnect the Connector and validate from a
+   new ChatGPT conversation; an already-open conversation may retain its older
+   tool catalog.
+
+The Windows launcher prompts for the runtime API key once and stores only a
+Windows DPAPI-encrypted value under `%APPDATA%\patchwarden`. Use
+`Reset-PatchWarden-Tunnel-Key.cmd` to remove the saved credential.
+
+Before the launcher starts the tunnel it performs a real MCP stdio handshake
+and requires the exact `chatgpt_core` manifest. Run
+`Check-PatchWarden-Health.cmd` to see the version, profile, tool names, schema
+hash, process sources, and any mixed-version warnings. The check is read-only.
+The v0.4.0 core manifest contains 16 tools. A different count or schema hash
+requires a Connector refresh and validation from a new ChatGPT conversation.
+
+## Architecture
+
+```text
+ChatGPT Web
+-> ChatGPT Connector
+-> OpenAI Secure MCP Tunnel
+-> PatchWarden MCP Server
+-> watcher
+-> local agent
+-> .patchwarden/tasks/<task_id>/
+-> ChatGPT reads result, diff, and test log
+```

package/examples/openai-tunnel/chatgpt-test-prompt.md

@@ -0,0 +1,53 @@
+# PatchWarden ChatGPT Test Prompt
+
+Paste this into a ChatGPT conversation where the PatchWarden Connector is
+selected.
+
+```text
+Use the patchwarden connector tools to verify the workflow.
+
+Step 1:
+Call health_check and list_agents. Continue only if the watcher and selected
+agent are available. Then call list_workspace for the configured workspace.
+Confirm schema_epoch is 2026-06-20-v2, tool_profile is chatgpt_core, and
+tool_count is 16. If the watcher is stale or missing, stop the task flow and
+report the health_check recovery instruction.
+
+Step 2:
+Call read_workspace_file for README.md.
+
+Step 3:
+Call save_plan with:
+
+title: Add Usage Section
+
+content:
+Add a "## Usage" section to the end of README.md. The section should include
+one sentence: "This repository was updated through PatchWarden."
+Do not modify other files. After the change, run the configured test command.
+
+Step 4:
+Call create_task with the returned plan_id, agent "opencode", an explicit
+repo_path for the target repository, and verify_commands ["npm test"]. Set
+timeout_seconds to 600.
+
+Step 5:
+Immediately call wait_for_task with timeout_seconds 25. If it returns
+continuation_required: true, call wait_for_task again in this same assistant
+turn. Do not stop or reply to the user until terminal is true.
+If execution_blocked is true or next_tool_call is health_check, do not keep
+polling; report the watcher recovery requirement.
+
+Step 6:
+When terminal is true, review the included summary, call get_task_summary and
+audit_task, then call get_diff, get_test_log, and get_result_json as needed.
+
+Step 7:
+Summarize:
+- final task status
+- files changed
+- whether tests passed
+- whether any out-of-scope changes were detected
+- acceptance_status and audit verdict
+- whether the diff is acceptable
+```

package/examples/openai-tunnel/tunnel-client.example.yaml

@@ -0,0 +1,39 @@
+# PatchWarden tunnel-client example configuration
+#
+# This is an example only. Do not commit real keys, tunnel IDs, account names,
+# workspace IDs, or local private paths.
+
+# Mode A: stdio
+#
+# On Windows, prefer the wrapper. It sets PATCHWARDEN_CONFIG and starts the
+# MCP server from the PatchWarden project root.
+#
+# tunnel-client init \
+#   --sample sample_mcp_stdio_local \
+#   --profile patchwarden \
+#   --tunnel-id tunnel_xxx \
+#   --mcp-command "C:/path/to/patchwarden/scripts/patchwarden-mcp-stdio.cmd"
+
+mcp:
+  commands:
+    - channel: main
+      command: "C:/path/to/patchwarden/scripts/patchwarden-mcp-stdio.cmd"
+
+# Mode B: HTTP
+#
+# Start PatchWarden HTTP first:
+#
+#   npm run start:http
+#
+# Then point tunnel-client at it:
+#
+#   tunnel-client init \
+#     --sample sample_mcp_with_dcr \
+#     --profile patchwarden-http \
+#     --tunnel-id tunnel_xxx \
+#     --mcp-server-url "http://127.0.0.1:7331/mcp"
+#
+# mcp:
+#   server_urls:
+#     - channel: main
+#       url: "http://127.0.0.1:7331/mcp"

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "patchwarden",
+  "version": "0.4.0",
+  "description": "A secure local MCP bridge: clients save plans, local agents execute tasks, and results are returned through workspace-scoped files.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "patchwarden": "dist/index.js",
+    "patchwarden-runner": "dist/runner/cli.js"
+  },
+  "files": [
+    "dist/",
+    "docs/",
+    "src/",
+    "examples/",
+    "scripts/",
+    "Start-PatchWarden-Tunnel.cmd",
+    "Restart-PatchWarden.cmd",
+    "Check-PatchWarden-Health.cmd",
+    "Reset-PatchWarden-Tunnel-Key.cmd",
+    "README.md",
+    "LICENSE",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "build": "node ./node_modules/typescript/bin/tsc",
+    "start": "node dist/index.js",
+    "start:http": "node dist/httpServer.js",
+    "dev": "npm run build && node dist/index.js",
+    "runner": "node dist/runner/cli.js",
+    "watch": "node dist/runner/watch.js",
+    "doctor": "node dist/doctor.js",
+    "test": "node dist/smoke-test.js && node scripts/lifecycle-smoke.js && node scripts/doctor-smoke.js && node scripts/tunnel-supervisor-smoke.js && node scripts/watcher-supervisor-smoke.js && node scripts/mcp-manifest-check.js && node scripts/brand-check.js",
+    "test:lifecycle": "npm run build && node scripts/lifecycle-smoke.js",
+    "test:doctor": "npm run build && node scripts/doctor-smoke.js",
+    "test:tunnel-supervisor": "npm run build && node scripts/tunnel-supervisor-smoke.js",
+    "test:watcher-supervisor": "npm run build && node scripts/watcher-supervisor-smoke.js",
+    "check:tool-manifest": "npm run build && node scripts/mcp-manifest-check.js",
+    "check:brand": "node scripts/brand-check.js",
+    "test:mcp": "npm run build && node scripts/mcp-smoke.js",
+    "test:http-mcp": "npm run build && node scripts/http-mcp-smoke.js",
+    "pretest": "npm run build",
+    "pack:clean": "npm run build && node scripts/pack-clean.js",
+    "verify:package": "npm run build && npm pack --dry-run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "codex",
+    "opencode",
+    "local-agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jiezeng2004-design/PatchWarden.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jiezeng2004-design/PatchWarden/issues"
+  },
+  "homepage": "https://github.com/jiezeng2004-design/PatchWarden#readme",
+  "license": "MIT"
+}

package/scripts/brand-check.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+const allowedLegacyFiles = new Set([
+  ".gitignore",
+  ".npmignore",
+  "README.md",
+  "docs/migration-from-safe-bifrost.md",
+  "docs/release-v0.3.0.md",
+  "docs/release-v0.4.0.md",
+  "scripts/brand-check.js",
+  "scripts/pack-clean.js",
+]);
+const legacyPattern = /safe-bifrost|Safe-Bifrost|SAFE_BIFROST|SafeBifrost|safe_bifrost/;
+const trackedFiles = execFileSync(
+  "git",
+  ["ls-files", "--cached", "--others", "--exclude-standard"],
+  { encoding: "utf-8" }
+)
+  .split(/\r?\n/)
+  .filter(Boolean);
+const failures = [];
+
+for (const file of trackedFiles) {
+  const normalized = file.replace(/\\/g, "/");
+  if (allowedLegacyFiles.has(normalized)) continue;
+  if (legacyPattern.test(normalized)) {
+    failures.push(`${normalized}: legacy brand in path`);
+    continue;
+  }
+  const content = readFileSync(file);
+  if (!content.includes(0) && legacyPattern.test(content.toString("utf-8"))) {
+    failures.push(`${normalized}: legacy brand in content`);
+  }
+}
+
+if (failures.length > 0) {
+  console.error("[brand-check] Legacy brand found outside the approved migration/history files:");
+  for (const failure of failures) console.error(`  ${failure}`);
+  process.exit(1);
+}
+
+console.log(`[brand-check] OK: ${trackedFiles.length} tracked files checked.`);

package/scripts/doctor-smoke.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const tempRoot = mkdtempSync(join(tmpdir(), "patchwarden-doctor-"));
+const workspaceRoot = join(tempRoot, "workspace");
+const configPath = join(tempRoot, "patchwarden.config.json");
+
+try {
+  mkdirSync(workspaceRoot, { recursive: true });
+  writeFileSync(configPath, JSON.stringify({
+    workspaceRoot,
+    plansDir: ".patchwarden/plans",
+    tasksDir: ".patchwarden/tasks",
+    agents: {
+      fixture: { command: process.execPath, args: ["-e", "console.log('fixture')"] },
+    },
+    allowedTestCommands: ["npm test", "npm run lint"],
+    maxReadFileBytes: 200000,
+    defaultTaskTimeoutSeconds: 30,
+    maxTaskTimeoutSeconds: 60,
+  }, null, 2), "utf-8");
+
+  const result = spawnSync(process.execPath, ["dist/doctor.js"], {
+    cwd: root,
+    env: { ...process.env, PATCHWARDEN_CONFIG: configPath },
+    encoding: "utf-8",
+    timeout: 30000,
+  });
+  if (result.status !== 0) {
+    throw new Error(`doctor exited ${result.status}: ${result.stdout}\n${result.stderr}`);
+  }
+  const requiredLines = [
+    "[OK]   workspaceRoot exists",
+    "[OK]   repo_path resolver supports relative and absolute paths",
+    "[OK]   save_plan security rules loaded",
+    "[OK]   Read-only task artifact allowlist",
+    "[OK]   Task directory writable",
+    "[OK]   Example task directory read/write",
+    "[OK]   allowedTestCommands is non-empty",
+  ];
+  for (const line of requiredLines) {
+    if (!result.stdout.includes(line)) throw new Error(`doctor output missing stable line: ${line}`);
+  }
+  console.log("ok - doctor stable output and self-checks");
+} finally {
+  rmSync(tempRoot, { recursive: true, force: true });
+}

package/scripts/get-patchwarden-health.ps1

@@ -0,0 +1,114 @@
+$ErrorActionPreference = "Stop"
+
+$ProjectRoot = 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"
+
+$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
+if ($LASTEXITCODE -ne 0 -or -not $healthJson) {
+  throw "Could not load PatchWarden health information. Run npm.cmd run build first."
+}
+$health = $healthJson | ConvertFrom-Json
+$packageVersion = [string](Get-Content -LiteralPath (Join-Path $ProjectRoot "package.json") -Raw | ConvertFrom-Json).version
+
+$configuredTunnelManifest = $null
+try {
+  $manifestJson = node (Join-Path $ProjectRoot "scripts\mcp-manifest-check.js") 2>$null
+  if ($LASTEXITCODE -eq 0 -and $manifestJson) {
+    $configuredTunnelManifest = $manifestJson | ConvertFrom-Json
+  }
+} catch {}
+
+$safeProcesses = @()
+try {
+  $allProcesses = Get-CimInstance Win32_Process
+  foreach ($process in $allProcesses) {
+    $commandLine = [string]$process.CommandLine
+    if (-not $commandLine -or $commandLine -notmatch '(?i)patchwarden') { continue }
+    if ($process.ProcessId -eq $PID -or $commandLine -match 'get-patchwarden-health\.ps1') { continue }
+    $detectedVersion = "unknown"
+    $origin = "unknown"
+    if ($commandLine -match '(?i)patchwarden@([0-9]+(?:\.[0-9]+){1,2})') {
+      $detectedVersion = $matches[1]
+      $origin = "npm_package"
+    } elseif ($commandLine -like "*$ProjectRoot*") {
+      $detectedVersion = [string]$health.server_version
+      $origin = "current_workspace"
+    }
+    $safeCommand = $commandLine `
+      -replace '(?i)(CONTROL_PLANE_API_KEY\s*=\s*)\S+', '$1[REDACTED]' `
+      -replace '(?i)tunnel_[a-z0-9_-]{12,}', '[REDACTED_TUNNEL_ID]'
+    $safeProcesses += [ordered]@{
+      pid = $process.ProcessId
+      parent_pid = $process.ParentProcessId
+      name = $process.Name
+      detected_version = $detectedVersion
+      origin = $origin
+      command_line = $safeCommand.Substring(0, [Math]::Min(500, $safeCommand.Length))
+      version_conflict = $detectedVersion -ne "unknown" -and $detectedVersion -ne [string]$health.server_version
+    }
+  }
+} catch {}
+
+$liveTunnel = [ordered]@{ observed = $false; healthz = $false; readyz = $false; error = $null }
+if (Test-Path -LiteralPath $HealthUrlFile) {
+  try {
+    $baseUrl = (Get-Content -LiteralPath $HealthUrlFile -Raw).Trim().TrimEnd('/')
+    if ($baseUrl -notmatch '^http://127\.0\.0\.1:\d+$') { throw "Health URL is not loopback-only." }
+    $healthz = Invoke-WebRequest -Uri "$baseUrl/healthz" -UseBasicParsing -TimeoutSec 3
+    $readyz = Invoke-WebRequest -Uri "$baseUrl/readyz" -UseBasicParsing -TimeoutSec 3
+    $liveTunnel.observed = $true
+    $liveTunnel.healthz = $healthz.StatusCode -eq 200
+    $liveTunnel.readyz = $readyz.StatusCode -eq 200
+  } catch {
+    $liveTunnel.observed = $true
+    $liveTunnel.error = "Tunnel local health endpoint is unavailable."
+  }
+}
+
+$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'
+})
+$deploymentConsistent = [bool](
+  $configuredTunnelManifest -and
+  $health.tunnel.tool_manifest_sha256 -and
+  [string]$configuredTunnelManifest.tool_manifest_sha256 -eq [string]$health.tunnel.tool_manifest_sha256
+)
+
+[ordered]@{
+  checked_at = (Get-Date).ToUniversalTime().ToString("o")
+  overall_status = $health.status
+  source_version = $packageVersion
+  dist_version = $health.server_version
+  schema_epoch = $health.schema_epoch
+  local_server_catalog = [ordered]@{
+    tool_profile = $health.tool_profile
+    tool_count = $health.tool_count
+    tool_names = $health.tool_names
+    tool_manifest_sha256 = $health.tool_manifest_sha256
+    catalog_consistent = $health.catalog_consistent
+    mismatch_report = $health.mismatch_report
+    tunnel_catalog_comparison = $health.tunnel_catalog_comparison
+  }
+  configured_tunnel_manifest = $configuredTunnelManifest
+  deployment_consistency = [ordered]@{
+    consistent = $deploymentConsistent
+    reason = if ($deploymentConsistent) { $null } else { "Configured tunnel manifest differs from the running tunnel state. Restart the owned tunnel, then refresh the Connector and use a new conversation." }
+  }
+  connector_visibility = $health.connector_visibility
+  mcp_server = $health.mcp_server
+  workspace_root = $health.workspace_root
+  tasks_dir = $health.tasks_dir
+  watcher = $health.watcher
+  agents = $health.agents
+  tunnel_state = $health.tunnel
+  tunnel_live_probe = $liveTunnel
+  tunnel_processes = $tunnelProcesses
+  mcp_child_processes = $mcpChildProcesses
+  patchwarden_processes = $safeProcesses
+  version_conflicts = @($safeProcesses | Where-Object { $_.version_conflict })
+  last_error = $health.last_error
+} | ConvertTo-Json -Depth 8