patchwarden 1.5.1 → 1.6.1

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,21 @@ 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.0](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.0/PatchWarden-Setup-1.6.0-x64.exe)
+· [Portable ZIP](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.0/PatchWarden-Portable-1.6.0-x64.zip)
+· [Checksums](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.0/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: **v1.6.1**; current Windows Release: **v1.6.0**; npm
+`latest`: **v1.5.1**. Use the installer above for the first Windows experience;
+pin an actually published version for npm/CLI use. See the
+[CHANGELOG](CHANGELOG.md), [migration guide](docs/migration-from-safe-bifrost.md), and
+[release checklist](docs/release-checklist.md).
 
 > [!IMPORTANT]
 > PatchWarden is not a general-purpose remote shell. MCP clients cannot run
@@ -36,7 +48,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 +73,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 +123,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 +231,37 @@ 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.0](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.0/PatchWarden-Setup-1.6.0-x64.exe)
+   and its [SHA256 checksum file](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.0/PatchWarden-Desktop-SHA256SUMS.txt).
+2. Verify the installer in PowerShell:
+
+```powershell
+Get-FileHash .\PatchWarden-Setup-1.6.0-x64.exe -Algorithm SHA256
+```
+
+The current published value is `77d655545925ae283a0caed0fff12554debac15b54c5decf1ae8f3867703058e`;
+always prefer 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 +298,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 +341,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 +376,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 +393,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 +512,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 +576,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.
@@ -687,13 +751,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 +849,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 +1114,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 +1140,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 +1187,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 +1279,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)

package/README.md

@@ -8,20 +8,27 @@
 [![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)
 
-当前源码版本：**v1.5.1**。查看
-[CHANGELOG](CHANGELOG.md)、[迁移指南](docs/migration-from-safe-bifrost.md)和
-[发布检查清单](docs/release-checklist.md)。GitHub Release / npm 发布状态需要在发布前单独核对。
+**让 ChatGPT、Codex 等 MCP 客户端负责规划与验收，让本地编程 Agent 在明确的安全边界内执行，并留下可审计证据。**
 
 PatchWarden 是一个面向本地编程 Agent 的安全 MCP 桥接器。上游的
 ChatGPT、Codex、OpenCode 或其他 MCP 客户端负责规划与验收，
 PatchWarden 负责把计划保存成工作区内任务，再由预先配置的本地 Agent
 执行，并返回结果、代码差异和独立测试记录。
 
-统一英文定位：
+[下载 Windows 安装版 v1.6.0](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.0/PatchWarden-Setup-1.6.0-x64.exe)
+· [免安装 ZIP](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.0/PatchWarden-Portable-1.6.0-x64.zip)
+· [校验文件](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.0/PatchWarden-Desktop-SHA256SUMS.txt)
+· [三分钟快速开始](#三分钟快速开始)
+· [Discussions](https://github.com/jiezeng2004-design/PatchWarden/discussions)
+
+![PatchWarden Desktop 真实首启界面](docs/assets/patchwarden-desktop-onboarding.png)
 
-> PatchWarden is a local-first MCP safety and verification layer for AI coding agents, with workspace confinement, command allowlists, scope-violation detection, and auditable task evidence.
+<sub>PatchWarden Desktop 真实首启界面，来自隐私安全的桌面 smoke 验收；截图未使用真实工作区、账号或凭据。</sub>
 
-![PatchWarden ChatGPT connector demo](docs/assets/patchwarden-chatgpt-demo.svg)
+当前源码版本：**v1.6.1**；当前 Windows Release：**v1.6.0**；npm `latest`：**v1.5.1**。
+Windows 首次体验推荐上面的安装版；npm/CLI 用户请固定已发布版本。查看
+[CHANGELOG](CHANGELOG.md)、[迁移指南](docs/migration-from-safe-bifrost.md)和
+[发布检查清单](docs/release-checklist.md)。
 
 > [!IMPORTANT]
 > PatchWarden 不是通用远程 Shell。MCP 客户端不能随意执行命令：
@@ -33,7 +40,7 @@ PatchWarden 负责把计划保存成工作区内任务，再由预先配置的
 - [它解决什么问题](#它解决什么问题)
 - [运行结构](#运行结构)
 - [环境要求](#环境要求)
-- [五分钟快速开始](#五分钟快速开始)
+- [三分钟快速开始](#三分钟快速开始)
 - [完整配置说明](#完整配置说明)
 - [接入 OpenCode](#接入-opencode)
 - [接入 Codex](#接入-codex)
@@ -58,9 +65,9 @@ PatchWarden 负责把计划保存成工作区内任务，再由预先配置的
 - 每个任务必须指定位于 `workspaceRoot` 内的 `repo_path`。
 - Agent 启动命令来自本地配置，而不是来自模型输入。
 - 测试命令必须精确匹配 `allowedTestCommands`。
-- 任务完成后保存结构化结果、完整差异、文件统计和独立验证记录。
+- 任务完成后保存结构化结果、有界且脱敏的差异、文件统计和独立验证记录。
 - 工作区外出现变化时，任务会标记为作用域违规，而不是悄悄接受。
-- `.env`、Token、SSH 密钥、Cookie、凭据文件等敏感路径默认不可读。
+- `.patchwarden/` 不是敏感路径豁免区；`.env`、Token、SSH 密钥、Cookie、凭据文件等敏感名称无论位于哪一层目录都不可读。
 
 适合的场景：
 
@@ -134,9 +141,33 @@ where.exe codex
 应用程序，它不一定是可供 PatchWarden 调用的 Codex CLI。请安装或指定真正的
 CLI，或者先把 OpenCode 配置为执行 Agent。
 
-## 五分钟快速开始
+## 三分钟快速开始
+
+如果已经安装 Node.js 18+ 和至少一个本地编程 Agent，这条 Windows 路径的目标是
+在三分钟内完成首次只读健康检查。首次体验不需要配置 ChatGPT Tunnel。
 
-### 方案 A：从源码运行（推荐）
+### 方案 A：Windows 安装版（首次体验推荐）
+
+1. 下载 [Windows 安装版 v1.6.0](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.0/PatchWarden-Setup-1.6.0-x64.exe)
+   和 [SHA256 校验文件](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.0/PatchWarden-Desktop-SHA256SUMS.txt)。
+2. 在 PowerShell 中校验安装包：
+
+```powershell
+Get-FileHash .\PatchWarden-Setup-1.6.0-x64.exe -Algorithm SHA256
+```
+
+当前发布值应为 `77d655545925ae283a0caed0fff12554debac15b54c5decf1ae8f3867703058e`；
+仍应以同一 Release 的校验文件为准。安装包尚未代码签名，Windows SmartScreen
+可能显示“未知发布者”。
+
+3. 安装并打开 PatchWarden Desktop，选择一个只包含项目的专用工作区。
+4. 首屏选择 **本地 MCP**，确认检测到的 Agent，让只读健康检查完成。
+
+成功标志：向导能够进入只读控制台，显示所选工作区，并完成 Agent 与运行环境检查。
+安装成功或遇到阻塞时，请到 [Discussions](https://github.com/jiezeng2004-design/PatchWarden/discussions)
+记录操作系统、Node.js 版本、使用的 Agent 和卡住的步骤。
+
+### 方案 B：从源码运行（开发者）
 
 源码方式最适合完整使用 Watcher、Windows 一键启动器和诊断脚本。
 
@@ -171,7 +202,7 @@ npm.cmd run watch
 
 保持该窗口运行，再按照后文配置 OpenCode、Codex 或 ChatGPT Connector。
 
-### 方案 B：使用 npm 包
+### 方案 C：使用 npm 包
 
 npm 包适合让 MCP 客户端通过固定版本启动 PatchWarden。为了执行任务，
 仍然必须另外启动 Watcher。
@@ -213,11 +244,13 @@ Copy-Item .\examples\config.example.json .\patchwarden.config.json
   "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": [
@@ -246,6 +279,7 @@ Copy-Item .\examples\config.example.json .\patchwarden.config.json
 | `tasksDir` | 是 | 任务和结果目录，通常使用 `.patchwarden/tasks`。 |
 | `toolProfile` | 否 | `full`、`chatgpt_core`、`chatgpt_direct` 或 `chatgpt_search`；本地客户端推荐 `full`，动态工具发现场景使用 `chatgpt_search`。 |
 | `agents` | 是 | 可执行 Agent 白名单；支持 `{repo}` 和 `{prompt}` 占位符。 |
+| `agents.<name>.envAllowlist` | 否 | 显式传给该 Agent 的 provider 环境变量名；默认不继承。Tunnel owner token 禁止透传。 |
 | `allowedTestCommands` | 是 | 独立验证命令白名单，调用时必须精确匹配。 |
 | `repoAllowedTestCommands` | 否 | 按工作区相对仓库路径增加精确验证命令；不支持通配符。 |
 | `maxReadFileBytes` | 是 | MCP 单次文件读取上限。 |
@@ -369,6 +403,21 @@ PATCHWARDEN_TOOL_PROFILE = "full"
 
 ## 接入 ChatGPT Connector
 
+> 当前 ChatGPT 术语为 **developer-mode app / Plugins**；旧版文档与部分界面曾称为 Connector。新配置请以 Plugins 为准。
+
+### 桌面版八步新手流程
+
+1. 确认 OpenAI Platform 账号具有 Tunnel 权限，并在目标 ChatGPT workspace 开启 developer mode。
+2. 打开 [Platform Tunnel 设置](https://platform.openai.com/settings/organization/tunnels)，创建 Tunnel，并关联目标 ChatGPT workspace。
+3. 启动 PatchWarden Desktop，在“设置 → MCP 与隧道”检测或选择现有的 `tunnel-client.exe`；应用不会自动下载或执行新软件。
+4. 输入 Core Tunnel ID 与专用 Tunnel runtime API key。该凭据对应 `CONTROL_PLANE_API_KEY`，**不是**普通应用使用的 `OPENAI_API_KEY`。
+5. 配置环境代理、无代理或不含凭据的 HTTP/HTTPS/SOCKS5（Mixed）代理，并先确认代理端口可达。
+6. 点击“配置并验证 Core”。桌面端初始化 `patchwarden` profile，运行 `tunnel-client doctor --explain --json`，验证成功后才用 Windows DPAPI 保存凭据；随后启动 Core。
+7. 在“开始使用”确认 Tunnel ready、Watcher healthy，并确认 `chatgpt_core` 发现固定的 26 个工具。Direct 是设置页中的可选高级能力，未启用时“全部启动”只启动 Core。
+8. 在 ChatGPT **Settings → Plugins** 创建 developer-mode app，选择刚创建的 Tunnel；重新连接后新建对话，调用 `health_check` 验证。
+
+首次引导也可选择“本地 MCP”。该路线只配置安全工作区和本地 MCP 客户端，可以跳过第 1、2、4、5、7、8 步中的 Platform/ChatGPT Tunnel 操作。
+
 推荐的 Windows 链路：
 
 ```text
@@ -572,19 +621,25 @@ ChatGPT 任务应优先选择前三个守护模板：只读诊断使用 `inspect
 | `progress.md` | Agent 写入的进度记录。 |
 | `result.md` | 人类可读的执行报告。 |
 | `result.json` | 结构化结果、路径、变更、警告和后续建议。 |
-| `diff.patch` | 完整任务差异证据。 |
+| `diff.patch` | 最多 20 MiB 的任务差异证据；疑似凭据会在落盘前脱敏，超限会明确标记截断。 |
 | `artifact_manifest.json` | 构建或发布产物的路径、类型、大小与 SHA-256。 |
 | `file-stats.json` | 文件级增删统计。 |
 | `verify.json` | 每条独立验证命令的结构化记录。 |
 | `verify.log` | 独立验证的可读日志。 |
 | `test.log` | Agent 执行过程中产生的测试输出。 |
 
+面向客户端的任务产物读取受 `maxReadFileBytes` 限制；diff、summary 与日志 tail
+只读取有界前缀或尾部。`audit_task` 最多扫描 200 个 Markdown 文件和 4 MiB 文档内容，
+达到预算会返回 warning。invocation/reconcile 等持续日志使用跨进程锁内的有界追加，
+超限时保留最近内容并写入明确的截断标记。
+
 本地 Agent 声称“已推送”“已发布”不属于可靠的远程证据。GitHub、npm、
 Tag 和 Release 必须再用对应平台的实时状态核验。
 
 ## HTTP MCP 模式
 
-HTTP Server 只绑定 `127.0.0.1`，默认端口 7331，不会直接监听局域网。
+HTTP Server 只绑定 `127.0.0.1`，默认端口 7331，不会直接监听局域网；
+HTTP MCP 与 Control Center 同时拒绝非 `127.0.0.1`/`localhost` 的 Host，防止 DNS rebinding 绕过回环边界。
 
 终端 1，启动 Watcher：
 
@@ -659,10 +714,43 @@ Direct 两种模式的启动、停止、重启与状态。也可以在 PowerShel
 .\PatchWarden.cmd restart all
 .\PatchWarden.cmd status all
 .\PatchWarden.cmd kill all
-.\Stop-PatchWarden.cmd
+.\scripts\launchers\Stop-PatchWarden.cmd
 ```
 
-日常桌面入口：`PatchWarden-Desktop.cmd` 启动托盘并确保 Control Center 可用，不自动打开额外浏览器窗口。只有调试托盘时才使用 `PatchWarden-Control-Tray.cmd --foreground`；需要完整 Web 控制台时打开 `PatchWarden-Control.cmd`；需要一键收尾时使用 `Stop-PatchWarden.cmd` 关闭 Core/Direct、Control Center 和托盘。
+日常桌面入口：`scripts\launchers\PatchWarden-Desktop.cmd` 启动托盘并确保 Control Center 可用，不自动打开额外浏览器窗口。只有调试托盘时才使用 `scripts\launchers\PatchWarden-Control-Tray.cmd --foreground`；需要完整 Web 控制台时打开 `scripts\launchers\PatchWarden-Control.cmd`；需要一键收尾时使用 `scripts\launchers\Stop-PatchWarden.cmd` 关闭 Core/Direct、Control Center 和托盘。
+
+### Windows 安装版
+
+公开分发可以构建 PatchWarden Desktop 安装包和免安装 ZIP。它提供 Electron
+独立窗口、首次工作区引导、系统托盘和设置页，同时继续复用相同的
+loopback Control Center 与安全控制 API。桌面依赖隔离在私有的
+`desktop/` 子包中，不进入 `patchwarden` npm 包。
+
+安装版仍要求 Windows x64、Node.js 18+ 和 tunnel-client。首次启动会在
+`PATH`、当前用户目录和工作区附近做有界检测；未找到时可进入只读控制台，
+再从“设置 -> MCP 与隧道”选择 `tunnel-client.exe` 并查看 SHA256 校验步骤。
+应用不会自动下载或运行新软件。设置页还提供 Direct 显式开关，以及环境代理、
+无代理、手动代理三种模式；手动代理只接受不含凭据的 http/https/socks5 URL。
+启动和重启只有在 health/ready 与 Core Watcher 验证通过后才会报告成功。
+桌面端支持 Codex、OpenCode、Claude Code、Gemini CLI、GitHub Copilot CLI、
+Qwen Code、Kimi Code 和 Aider；只读取各 Agent 配置中的模型字段，不读取凭据。
+
+```powershell
+npm.cmd install --prefix desktop --cache .\.npm-cache
+npm.cmd run desktop:test
+npm.cmd run desktop:preflight
+npm.cmd run desktop:package
+```
+
+安装包、免安装 ZIP 与 SHA256 文件输出到 `release\desktop`。首版不包含自动更新或
+代码签名，Windows SmartScreen 可能提示未知发布者；发布前必须核对
+GitHub Release 来源和 SHA256。完整安装、运行与卸载说明见
+[docs/desktop-app.md](docs/desktop-app.md)。
+
+`desktop:preflight` 会使用唯一目录完成 clean build、完整单测、桌面测试、npm 包面、
+Electron 目录包、仓库外 26-tool manifest 与隔离 unpacked UI/单实例验收，并生成
+`preflight-report.json` / `preflight-report.md`。正式发布前必须在干净 checkout 运行
+`npm.cmd run desktop:preflight:release`；该命令发现未提交路径时会直接阻断。
 
 旧的单用途入口保留在 `scripts/launchers/` 作为兼容层；个人入口位于
 `.local/launchers/`，并继续被 Git 和发布包排除。`stop` / `restart` 会同时检查
@@ -758,7 +846,7 @@ PatchWarden Dashboard (Control Center) 提供以下主要页面：
 
 - **控制台 (Dashboard)**: 系统总览，包含 Repo selector、Health Score、服务状态、Release 卡片、Project Policy、Lineage、Evidence Pack、Stale 任务提示、最近任务列表、系统状态（含 Copy diagnostics）。
 - **任务面板 (Tasks)**: 任务列表，支持按 repo_path / status / acceptance_status / warning type / agent / date range 过滤，每行提供 safe_result / safe_audit / safe_test_summary / safe_diff_summary 快捷操作。
-- **任务详情 (Task Detail)**: 默认展示 safe 摘要（safe_result / safe_test_summary / safe_diff_summary / safe_audit），完整 result / diff / test log 在折叠的高级区按需加载。
+- **任务详情 (Task Detail)**: 默认展示 safe 摘要（safe_result / safe_test_summary / safe_diff_summary / safe_audit），配置上限内的 result / diff / test log 在折叠的高级区按需加载。
 - **Direct 会话 (Direct Sessions)**: 按 active / finalized / audited / expired 分组，提供 safe_direct_summary / safe_finalize_direct_session / safe_audit_direct_session 快捷操作。
 - **审计日志 / Warnings (Audit)**: 按 warning 类型聚合，显示 affected tasks / severity / recommended action。
 - **工作区 (Workspace)**: workspace 一级目录与项目列表。
@@ -769,7 +857,7 @@ PatchWarden Dashboard (Control Center) 提供以下主要页面：
 1. 在 Dashboard 顶部选择目标 repo。
 2. 查看 Health Score 确认系统健康。
 3. 在最近任务列表点击 safe_result 快捷查看任务摘要。
-4. 打开 Task Detail 进行 safe-first 验收，仅在需要时展开高级区查看完整日志。
+4. 打开 Task Detail 进行 safe-first 验收，仅在需要时展开高级区查看有界日志。
 5. 使用 Lineage Detail 查看 run_task_loop 的成功/失败原因。
 6. 验收完成后导出 Evidence Pack。
 7. Direct 会话用于独立验证，完成后 finalize + audit。
@@ -894,6 +982,12 @@ 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 的状态变更通过共享的跨进程 mutation lock 串行化并原子落盘；
+非空 Goal 的所有子目标都被 `accept_subgoal` 接受后，Goal 会自动转为 `completed`。
+`create_subgoal_task` 以 Goal 已保存的 `repo_path` 为权威，调用方传入其他仓库会以
+`goal_repo_mismatch` 拒绝；隔离 worktree 也从该仓库创建，且 create/merge/discard
+共用仓库级 lifecycle lock。
+
 `get_project_policy` 是 v1.3 的只读策略入口，返回 `.patchwarden/project-policy.json`
 的有界 effective policy 与 release readiness，不会扩大命令白名单。v1.3 的
 `release_check`、`release_prepare`、`release_verify`、`release_cleanup` 仅在 `full`
@@ -997,6 +1091,9 @@ Direct 模式在受控 session 内执行，具有以下硬性限制：
 - 禁止修改 `node_modules`
 - 禁止手动修改 release/dist
 - 禁止修改二进制文件
+- 只修改大小受限的 UTF-8 文本；补丁按 UTF-8 字节计数
+- 补丁或同步结果包含疑似凭据时拒绝写入
+- 同一 session 的 patch、sync、verify、finalize、audit 串行化
 - 所有操作限制在 `workspaceRoot` 和 session repo 内
 
 ### 不支持内容
@@ -1022,9 +1119,9 @@ PatchWarden 的主要保护：
 - Agent 命令和参数模板必须预先配置。
 - 验证命令必须精确匹配白名单。
 - 文件访问被限制在 `workspaceRoot` 内。
-- 敏感文件名和明显的凭据读取计划会被阻止。
-- 任务产物中的疑似密钥值会被脱敏。
-- HTTP Server 只绑定 `127.0.0.1`。
+- 敏感文件名和明显的凭据读取计划会被阻止；`.patchwarden/` 不会绕过该检查。
+- 任务差异中的疑似密钥值会在落盘前脱敏，并把任务标记为策略违规。
+- HTTP 服务只绑定 `127.0.0.1`，并拒绝非回环 Host。
 - Runner 不会自动 commit、push、发布或重置仓库。
 
 需要保护的本地路径：