patchwarden 1.5.1 → 1.6.2

package/PatchWarden.cmd

@@ -3,6 +3,37 @@ setlocal EnableExtensions
 chcp 65001 >nul
 cd /d "%~dp0"
 
+set "LAUNCHERS_DIR=%~dp0scripts\launchers"
+set "PATCHWARDEN_COMMAND=%~1"
+
+if /i "%PATCHWARDEN_COMMAND%"=="control" goto dispatch_control
+if /i "%PATCHWARDEN_COMMAND%"=="desktop" goto dispatch_desktop
+if /i "%PATCHWARDEN_COMMAND%"=="tray" goto dispatch_tray
+if /i "%PATCHWARDEN_COMMAND%"=="stop" goto dispatch_stop
+if /i "%PATCHWARDEN_COMMAND%"=="restart-control" goto dispatch_restart_control
+goto default_behavior
+
+:dispatch_control
+call "%LAUNCHERS_DIR%\PatchWarden-Control.cmd" %2 %3 %4 %5 %6 %7 %8 %9
+exit /b %ERRORLEVEL%
+
+:dispatch_desktop
+call "%LAUNCHERS_DIR%\PatchWarden-Desktop.cmd" %2 %3 %4 %5 %6 %7 %8 %9
+exit /b %ERRORLEVEL%
+
+:dispatch_tray
+call "%LAUNCHERS_DIR%\PatchWarden-Control-Tray.cmd" %2 %3 %4 %5 %6 %7 %8 %9
+exit /b %ERRORLEVEL%
+
+:dispatch_stop
+call "%LAUNCHERS_DIR%\Stop-PatchWarden.cmd" %2 %3 %4 %5 %6 %7 %8 %9
+exit /b %ERRORLEVEL%
+
+:dispatch_restart_control
+call "%LAUNCHERS_DIR%\Restart-PatchWarden-Control.cmd" %2 %3 %4 %5 %6 %7 %8 %9
+exit /b %ERRORLEVEL%
+
+:default_behavior
 set "DEFAULT_PROXY=http://127.0.0.1:7892"
 
 if not defined PATCHWARDEN_PROXY_URL (
@@ -20,8 +51,7 @@ set "HTTPS_PROXY=%PATCHWARDEN_PROXY_URL%"
 set "ALL_PROXY=%PATCHWARDEN_PROXY_URL%"
 set "NO_PROXY=localhost,127.0.0.1,::1"
 
-set "SCRIPTS_DIR=%~dp0scripts\control"
-set "MANAGER=%SCRIPTS_DIR%\manage-patchwarden.ps1"
+set "MANAGER=%~dp0scripts\control\manage-patchwarden.ps1"
 
 if not exist "%MANAGER%" (
   echo [error] manage-patchwarden.ps1 not found:

package/README.en.md

@@ -8,9 +8,7 @@
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-339933.svg)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-Current source version: **v1.5.1**. See the
-[CHANGELOG](CHANGELOG.md), [migration guide](docs/migration-from-safe-bifrost.md), and
-[release checklist](docs/release-checklist.md). Verify GitHub Release / npm publication separately before release.
+**Let an MCP client such as ChatGPT or Codex plan and review the work while a local coding agent executes inside explicit safety boundaries and leaves auditable evidence.**
 
 PatchWarden is a local-first MCP safety and verification layer for AI coding
 agents, with workspace confinement, command allowlists, scope-violation
@@ -21,7 +19,27 @@ PatchWarden stores that plan as a workspace-scoped task, lets a preconfigured
 local agent execute it, and returns results, diffs, artifact manifests, and
 independent verification evidence.
 
-![PatchWarden ChatGPT connector demo](docs/assets/patchwarden-chatgpt-demo.svg)
+[Download Windows installer v1.6.2](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.2/PatchWarden-Setup-1.6.2-x64.exe)
+· [Portable ZIP](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.2/PatchWarden-Portable-1.6.2-x64.zip)
+· [Checksums](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.2/PatchWarden-Desktop-SHA256SUMS.txt)
+· [Three-minute quick start](#three-minute-quick-start)
+· [Discussions](https://github.com/jiezeng2004-design/PatchWarden/discussions)
+
+![Real PatchWarden Desktop first-run screen](docs/assets/patchwarden-desktop-onboarding.png)
+
+<sub>Real PatchWarden Desktop first-run UI from a privacy-safe smoke run; no real workspace, account, or credential data is shown.</sub>
+
+Current source version and Windows Release: **v1.6.2**. npm `latest` is
+published separately by the maintainer; use the npm badge above or query the
+registry for its current value. Use the installer above for the first Windows experience. See the
+[CHANGELOG](CHANGELOG.md), [migration guide](docs/migration-from-safe-bifrost.md), and
+[release checklist](docs/release-checklist.md).
+
+> [!NOTE]
+> The desktop installer is currently available for Windows x64 only. macOS,
+> Linux, and users who are not installing Desktop yet can continue using the
+> existing stable npm package and its built-in local Dashboard. This change
+> does not run `npm publish` automatically.
 
 > [!IMPORTANT]
 > PatchWarden is not a general-purpose remote shell. MCP clients cannot run
@@ -36,7 +54,7 @@ independent verification evidence.
 - [Evidence example](#evidence-example)
 - [Runtime architecture](#runtime-architecture)
 - [Requirements](#requirements)
-- [Five-minute quick start](#five-minute-quick-start)
+- [Three-minute quick start](#three-minute-quick-start)
 - [Complete configuration guide](#complete-configuration-guide)
 - [Connect OpenCode](#connect-opencode)
 - [Connect Codex](#connect-codex)
@@ -61,12 +79,13 @@ PatchWarden uses a narrower, auditable task channel:
 - Every task must specify a `repo_path` inside `workspaceRoot`.
 - Agent launch commands come from local configuration, not model input.
 - Verification commands must exactly match `allowedTestCommands`.
-- Every completed task records structured results, a full diff, file
+- Every completed task records structured results, a bounded and redacted diff, file
   statistics, and independent verification output.
 - Changes outside the requested repository cause a scope violation instead of
   being silently accepted.
-- Sensitive paths such as `.env` files, tokens, SSH keys, cookies, and
-  credential stores are blocked by default.
+- `.patchwarden/` is not a sensitive-path exemption. Names such as `.env`
+  files, tokens, SSH keys, cookies, and credential stores remain blocked at
+  every directory depth.
 
 Good use cases:
 
@@ -110,7 +129,7 @@ A completed task writes bounded, reviewable artifacts under
 - `result.json` - final status, verification status, changed-file groups, and warnings.
 - `artifact_manifest.json` - generated artifacts with size, type, and SHA-256.
 - `verify.json` - exact verification commands and exit codes.
-- `diff.patch` - complete source diff when Git evidence is available.
+- `diff.patch` - up to 20 MiB of redacted source diff when Git evidence is available; truncation is explicit.
 - `rollback_scope_violation_plan.md` - review plan when a task changes files outside `repo_path`.
 
 Example compact evidence:
@@ -218,9 +237,36 @@ If `where.exe codex` only returns the Codex Desktop executable under
 WindowsApps, it may not be a callable Codex CLI. Install or point to the real
 CLI, or configure OpenCode as the execution agent.
 
-## Five-minute quick start
+## Three-minute quick start
+
+If Node.js 18+ and at least one local coding agent are already installed, this
+Windows path is designed to reach its first read-only health check in about
+three minutes. A ChatGPT Tunnel is not required for this first run.
+
+### Option A: Windows installer (recommended for a first run)
+
+1. Download the [Windows installer v1.6.2](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.2/PatchWarden-Setup-1.6.2-x64.exe)
+   and its [SHA256 checksum file](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.2/PatchWarden-Desktop-SHA256SUMS.txt).
+2. Verify the installer in PowerShell:
+
+```powershell
+Get-FileHash .\PatchWarden-Setup-1.6.2-x64.exe -Algorithm SHA256
+```
+
+Always use the checksum file from the same Release. The installer is not
+code-signed yet, so Windows SmartScreen may show an unknown-publisher warning.
+
+3. Install and open PatchWarden Desktop, then choose a dedicated workspace that
+   contains only your projects.
+4. Select **Local MCP** on the first screen, review the detected agent, and let
+   the read-only health check finish.
 
-### Option A: run from source (recommended)
+Success means the onboarding flow reaches the read-only console, shows the
+selected workspace, and completes the agent/runtime checks. Share a successful
+install or a blocked step in [Discussions](https://github.com/jiezeng2004-design/PatchWarden/discussions),
+including your OS, Node.js version, agent, and the step where you stopped.
+
+### Option B: run from source (developer workflow)
 
 Source mode is the easiest way to use the Watcher, Windows launchers, and
 diagnostic scripts together.
@@ -257,7 +303,7 @@ npm.cmd run watch
 Keep this window open, then configure OpenCode, Codex, or ChatGPT as described
 below.
 
-### Option B: use the npm package
+### Option C: use the npm package
 
 The npm package is convenient for launching a pinned MCP server. Task
 execution still requires a separate Watcher.
@@ -300,11 +346,13 @@ Recommended Windows example:
   "agents": {
     "opencode": {
       "command": "opencode",
-      "args": ["run", "{prompt}"]
+      "args": ["run", "{prompt}"],
+      "envAllowlist": []
     },
     "codex": {
       "command": "codex",
-      "args": ["exec", "--cd", "{repo}", "{prompt}"]
+      "args": ["exec", "--cd", "{repo}", "{prompt}"],
+      "envAllowlist": []
     }
   },
   "allowedTestCommands": [
@@ -333,6 +381,7 @@ Configuration fields:
 | `tasksDir` | Yes | Task and result directory, normally `.patchwarden/tasks`. |
 | `toolProfile` | No | `full`, `chatgpt_core`, `chatgpt_direct`, or `chatgpt_search`; use `full` for local clients and `chatgpt_search` for compact discovery-driven clients. |
 | `agents` | Yes | Execution-agent allowlist; supports `{repo}` and `{prompt}` placeholders. |
+| `agents.<name>.envAllowlist` | No | Provider environment variable names explicitly forwarded to that agent; none are inherited by default. Tunnel and HTTP owner credentials are always blocked. |
 | `allowedTestCommands` | Yes | Exact allowlist for independent verification commands. |
 | `repoAllowedTestCommands` | No | Extra exact commands keyed by workspace-relative repository path; wildcards are unsupported. |
 | `maxReadFileBytes` | Yes | Maximum bytes returned by one MCP file read. |
@@ -349,12 +398,17 @@ Important configuration rules:
 - If you use backslashes, escape them as `D:\\path\\to\\project`.
 - Do not set `workspaceRoot` to a drive root, home directory, Desktop,
   Downloads, or Documents.
+- Configuration loading fails closed when `workspaceRoot` is missing,
+  inaccessible, not a directory, or one of those unsafe broad roots.
 - `plansDir` and `tasksDir` are resolved relative to `workspaceRoot`.
 - `repo_path` must stay inside `workspaceRoot` and cannot escape with `..`.
 - `allowedTestCommands` uses exact matching; similar commands are not
   automatically authorized.
 - Repository-specific commands come only from trusted local configuration;
   a target repository cannot authorize itself through `package.json`.
+- Every execution agent must be explicitly registered. Provider credentials or
+  proxy variables are forwarded only when their names appear in that agent's
+  `envAllowlist`; owner credentials cannot be allow-listed.
 - Configuration may contain private paths and should not be committed.
 
 Set the configuration path:
@@ -463,11 +517,26 @@ configured under `agents` is available.
 
 ## Connect ChatGPT
 
+> The current ChatGPT terms are **developer-mode app / Plugins**. Older docs and UI builds called this a Connector.
+
+### Eight-step desktop setup
+
+1. Confirm that the OpenAI Platform account has Tunnel access and enable developer mode in the target ChatGPT workspace.
+2. Open [Platform Tunnel settings](https://platform.openai.com/settings/organization/tunnels), create a Tunnel, and associate the target ChatGPT workspace.
+3. Start PatchWarden Desktop and detect or choose an existing `tunnel-client.exe` under **Settings → MCP and Tunnel**. The app never downloads or executes new software automatically.
+4. Enter the Core Tunnel ID and the dedicated Tunnel runtime API key. This credential is used as `CONTROL_PLANE_API_KEY`; it is **not** the `OPENAI_API_KEY` used by ordinary applications.
+5. Select environment proxy, no proxy, or a credential-free HTTP/HTTPS/SOCKS5 (Mixed) proxy, then confirm that its port is reachable.
+6. Choose **Configure and verify Core**. Desktop initializes the `patchwarden` profile, runs `tunnel-client doctor --explain --json`, and saves the credential with Windows DPAPI only after validation succeeds; then start Core.
+7. On **Getting Started**, confirm Tunnel ready and Watcher healthy, and verify that `chatgpt_core` exposes the fixed 26-tool catalog. Direct is optional; when disabled, Start All starts Core and reports Direct as skipped.
+8. In ChatGPT **Settings → Plugins**, create a developer-mode app and choose the Tunnel. Reconnect it, open a new chat, and call `health_check`.
+
+The first-run wizard also offers **Local MCP**. That route configures the safe workspace and a local MCP client, and can skip the Platform/ChatGPT Tunnel portions of steps 1, 2, 4, 5, 7, and 8.
+
 Recommended Windows path:
 
 ```text
 ChatGPT Web
-→ ChatGPT Connector
+→ ChatGPT developer-mode app / Plugins (formerly Connector)
 → OpenAI Secure MCP Tunnel
 → PatchWarden stdio MCP
 → Watcher
@@ -512,7 +581,7 @@ Runtime status is stored under:
 This directory contains PIDs, health state, and redacted diagnostics. It must
 not contain the API key or Tunnel ID.
 
-When creating the ChatGPT Connector:
+When creating the ChatGPT developer-mode app in Plugins:
 
 - Select the tunnel **Channel**.
 - Choose **None** for authentication unless you implemented OAuth.
@@ -619,7 +688,7 @@ country list.
 Use this sequence:
 
 1. `health_check` — verify version, workspace, Watcher, and tool catalog.
-2. `list_agents` — confirm the local execution agent is available.
+2. `list_agents` — confirm the local agent executable is available. This read-only check does not verify provider balance, login state, or model permissions; `provider_status` is `not_checked` by default.
 3. `list_workspace` — identify the correct `repo_path`.
 4. `save_plan`, or provide an `inline_plan` when creating the task.
 5. `create_task` — specify the agent, repository, and verification commands.
@@ -687,13 +756,20 @@ mean the task is wrong.
 | `progress.md` | Progress reported by the agent. |
 | `result.md` | Human-readable execution report. |
 | `result.json` | Structured result, paths, changes, warnings, and next steps. |
-| `diff.patch` | Complete task change evidence. |
+| `diff.patch` | Up to 20 MiB of task change evidence; credential-like values are redacted before persistence and truncation is explicit. |
 | `artifact_manifest.json` | Generated artifact paths, types, sizes, and SHA-256 hashes. |
 | `file-stats.json` | Per-file addition and deletion statistics. |
 | `verify.json` | Structured record for every independent verification command. |
 | `verify.log` | Human-readable independent verification output. |
 | `test.log` | Test output captured during agent execution. |
 
+Client-facing task artifact reads are limited by `maxReadFileBytes`; diff,
+summary, and log-tail surfaces read bounded prefixes or suffixes. `audit_task`
+scans at most 200 Markdown files and 4 MiB of documentation and returns a
+warning when that budget is reached. Persistent invocation and reconciliation
+logs use cross-process locked, bounded append and retain recent content with an
+explicit truncation marker when full.
+
 An agent saying “published” or “pushed” is not reliable remote evidence.
 Verify GitHub, npm, tags, and releases against the live platform state.
 
@@ -778,10 +854,51 @@ available from PowerShell:
 .\PatchWarden.cmd restart all
 .\PatchWarden.cmd status all
 .\PatchWarden.cmd kill all
-.\Stop-PatchWarden.cmd
+.\scripts\launchers\Stop-PatchWarden.cmd
 ```
 
-For daily desktop use, start with `PatchWarden-Desktop.cmd`; it starts the tray and keeps Control Center available without opening extra browser windows. Use `PatchWarden-Control-Tray.cmd --foreground` only for tray debugging, `PatchWarden-Control.cmd` for the full local Web dashboard, and `Stop-PatchWarden.cmd` for one-click shutdown of Core/Direct, Control Center, and the tray.
+For daily desktop use, start with `scripts\launchers\PatchWarden-Desktop.cmd`; it starts the tray and keeps Control Center available without opening extra browser windows. Use `scripts\launchers\PatchWarden-Control-Tray.cmd --foreground` only for tray debugging, `scripts\launchers\PatchWarden-Control.cmd` for the full local Web dashboard, and `scripts\launchers\Stop-PatchWarden.cmd` for one-click shutdown of Core/Direct, Control Center, and the tray.
+
+### Windows installer
+
+PatchWarden Desktop ships as an installer and a no-install ZIP. It provides an Electron window,
+first-run workspace setup, a system tray, and desktop settings while reusing
+the same loopback Control Center and bounded control APIs. Electron and builder
+dependencies remain isolated in the private `desktop/` package and are not
+included in the public `patchwarden` npm package.
+
+The installer still requires Windows x64, Node.js 18+, and tunnel-client. The
+first run performs bounded discovery through `PATH`, current-user locations,
+and the area next to the workspace. If it is missing, the read-only console
+remains available and **Settings > MCP and tunnel** provides a dedicated file
+picker plus SHA256 guidance. The app never downloads or runs new software
+automatically. Settings also exposes the explicit Direct switch and
+environment, none, or manual proxy modes; manual URLs support only http,
+https, or socks5 without embedded credentials. Start/restart reports success
+only after health/ready and the Core watcher have been verified.
+Desktop supports Codex, OpenCode, Claude Code, Gemini CLI, GitHub Copilot CLI,
+Qwen Code, Kimi Code, and Aider. It reads only model fields from agent settings,
+never credentials.
+
+```powershell
+npm.cmd install --prefix desktop --cache .\.npm-cache
+npm.cmd run desktop:test
+npm.cmd run desktop:preflight
+npm.cmd run desktop:package
+```
+
+The installer, portable ZIP, and SHA256 file are written to `release\desktop`. The first
+release is unsigned and has no automatic updater, so Windows SmartScreen may
+show an unknown-publisher warning. Verify the GitHub Release source and SHA256.
+See [docs/desktop-app.md](docs/desktop-app.md) for installation, runtime, and
+uninstall details.
+
+`desktop:preflight` uses a unique output directory for clean builds, complete
+unit and desktop tests, npm package-surface validation, an Electron directory
+package, an isolated 26-tool runtime check, and unpacked UI/single-instance
+smoke evidence. It writes `preflight-report.json` and `preflight-report.md`.
+Before release, run `npm.cmd run desktop:preflight:release` from a clean
+checkout; it rejects any uncommitted path.
 
 The old single-purpose launchers remain under `scripts/launchers/` as a
 compatibility layer. Personal launchers live under `.local/launchers/` and
@@ -1002,6 +1119,13 @@ creation. `export_task_evidence_pack` writes bounded `evidence.json` and
 `EVIDENCE.md` files under `.patchwarden/evidence-packs/<lineage_id>/` without
 stdout/stderr tails, full diffs, verification logs, or sensitive file content.
 
+Goal Session state changes are serialized by a shared cross-process mutation
+lock and committed atomically. A non-empty Goal automatically becomes
+`completed` after every subgoal is accepted. `create_subgoal_task` treats the
+Goal's stored `repo_path` as authoritative and rejects a caller-supplied mismatch
+with `goal_repo_mismatch`; isolated worktrees are created from that repository,
+and create/merge/discard share a repository lifecycle lock.
+
 `full` additionally provides:
 
 - `get_plan`
@@ -1021,6 +1145,12 @@ session, read and search source files, apply hash-bound JSON patches, run
 exactly allowlisted verification commands or a bounded verification bundle, finalize the evidence, and audit
 the result without a local execution agent.
 
+Direct patch and sync operations accept only size-bounded UTF-8 text, count
+patch limits in UTF-8 bytes, reject credential-like results, revalidate hashes
+immediately before replacement, and serialize patch/sync/verify/finalize/audit
+for each session. Direct still does not expose shell, delete, rename, commit,
+push, publish, or deployment operations.
+
 Enable it in the trusted local configuration while keeping the ordinary Core
 profile unchanged:
 
@@ -1062,9 +1192,10 @@ Primary protections:
 - Agent commands and argument templates must be configured in advance.
 - Verification commands must exactly match the allowlist.
 - File access is contained to `workspaceRoot`.
-- Sensitive filenames and obvious credential-read plans are blocked.
-- Secret-like values in task artifacts are redacted.
-- HTTP mode binds only to `127.0.0.1`.
+- Sensitive filenames and obvious credential-read plans are blocked;
+  `.patchwarden/` does not bypass this check.
+- Credential-like diff content is redacted before persistence and marks the task as a policy violation.
+- HTTP services bind only to `127.0.0.1` and reject non-loopback Host headers.
 - The Runner does not automatically commit, push, publish, or reset.
 
 Protect these local paths:
@@ -1153,9 +1284,10 @@ and release-asset checksums independently.
 
 ## Related documentation
 
-- [v0.6.4 release notes](docs/release-v0.6.4.md)
-- [v0.6.1 release notes](docs/release-v0.6.1.md)
-- [v0.6.0 release notes](docs/release-v0.6.0.md)
+- [Windows Desktop installer](docs/desktop-app.md)
+- [v0.6.4 release notes](docs/archive/releases/release-v0.6.4.md)
+- [v0.6.1 release notes](docs/archive/releases/release-v0.6.1.md)
+- [v0.6.0 release notes](docs/archive/releases/release-v0.6.0.md)
 - [ChatGPT usage guide](docs/chatgpt-usage.md)
 - [Migration guide](docs/migration-from-safe-bifrost.md)
 - [ChatGPT Connector demo](docs/demo.md)