patchwarden 1.5.1 → 1.6.2

package/README.md

@@ -8,20 +8,31 @@
 [![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.2](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.2/PatchWarden-Setup-1.6.2-x64.exe)
+· [免安装 ZIP](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.2/PatchWarden-Portable-1.6.2-x64.zip)
+· [校验文件](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.2/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>
+
+当前源码版本和 Windows Release：**v1.6.2**。npm `latest` 由维护者独立手动发布，
+请以页面顶部的 npm 徽章和注册表查询结果为准。Windows 首次体验推荐上面的安装版；查看
+[CHANGELOG](CHANGELOG.md)、[迁移指南](docs/migration-from-safe-bifrost.md)和
+[发布检查清单](docs/release-checklist.md)。
 
-![PatchWarden ChatGPT connector demo](docs/assets/patchwarden-chatgpt-demo.svg)
+> [!NOTE]
+> 当前桌面安装包暂时只提供 Windows x64。macOS、Linux 或暂时不安装桌面版的用户，
+> 可以继续使用 npm 上已有的稳定版本及其内置本地 Dashboard；本次 GitHub Release 不自动执行 `npm publish`。
 
 > [!IMPORTANT]
 > PatchWarden 不是通用远程 Shell。MCP 客户端不能随意执行命令：
@@ -33,7 +44,7 @@ PatchWarden 负责把计划保存成工作区内任务，再由预先配置的
 - [它解决什么问题](#它解决什么问题)
 - [运行结构](#运行结构)
 - [环境要求](#环境要求)
-- [五分钟快速开始](#五分钟快速开始)
+- [三分钟快速开始](#三分钟快速开始)
 - [完整配置说明](#完整配置说明)
 - [接入 OpenCode](#接入-opencode)
 - [接入 Codex](#接入-codex)
@@ -58,9 +69,9 @@ PatchWarden 负责把计划保存成工作区内任务，再由预先配置的
 - 每个任务必须指定位于 `workspaceRoot` 内的 `repo_path`。
 - Agent 启动命令来自本地配置，而不是来自模型输入。
 - 测试命令必须精确匹配 `allowedTestCommands`。
-- 任务完成后保存结构化结果、完整差异、文件统计和独立验证记录。
+- 任务完成后保存结构化结果、有界且脱敏的差异、文件统计和独立验证记录。
 - 工作区外出现变化时，任务会标记为作用域违规，而不是悄悄接受。
-- `.env`、Token、SSH 密钥、Cookie、凭据文件等敏感路径默认不可读。
+- `.patchwarden/` 不是敏感路径豁免区；`.env`、Token、SSH 密钥、Cookie、凭据文件等敏感名称无论位于哪一层目录都不可读。
 
 适合的场景：
 
@@ -134,9 +145,32 @@ where.exe codex
 应用程序，它不一定是可供 PatchWarden 调用的 Codex CLI。请安装或指定真正的
 CLI，或者先把 OpenCode 配置为执行 Agent。
 
-## 五分钟快速开始
+## 三分钟快速开始
+
+如果已经安装 Node.js 18+ 和至少一个本地编程 Agent，这条 Windows 路径的目标是
+在三分钟内完成首次只读健康检查。首次体验不需要配置 ChatGPT Tunnel。
+
+### 方案 A：Windows 安装版（首次体验推荐）
+
+1. 下载 [Windows 安装版 v1.6.2](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.2/PatchWarden-Setup-1.6.2-x64.exe)
+   和 [SHA256 校验文件](https://github.com/jiezeng2004-design/PatchWarden/releases/download/v1.6.2/PatchWarden-Desktop-SHA256SUMS.txt)。
+2. 在 PowerShell 中校验安装包：
 
-### 方案 A：从源码运行（推荐）
+```powershell
+Get-FileHash .\PatchWarden-Setup-1.6.2-x64.exe -Algorithm SHA256
+```
+
+请以同一 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 +205,7 @@ npm.cmd run watch
 
 保持该窗口运行，再按照后文配置 OpenCode、Codex 或 ChatGPT Connector。
 
-### 方案 B：使用 npm 包
+### 方案 C：使用 npm 包
 
 npm 包适合让 MCP 客户端通过固定版本启动 PatchWarden。为了执行任务，
 仍然必须另外启动 Watcher。
@@ -213,11 +247,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 +282,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 +406,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
@@ -516,7 +568,7 @@ Tunnel。支持范围可能变化，因此不要在项目里写死国家列表
 推荐顺序：
 
 1. `health_check`：确认版本、工作区、Watcher 和工具目录。
-2. `list_agents`：确认本地 Agent 命令可用。
+2. `list_agents`：确认本地 Agent 可执行文件可用；该检查不会验证模型提供商余额、登录态或调用权限，结果中的 `provider_status` 默认为 `not_checked`。
 3. `list_workspace`：确定 `repo_path`。
 4. `save_plan`，或在创建任务时提供 `inline_plan`。
 5. `create_task`：明确 Agent、仓库和验证命令。
@@ -572,19 +624,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 +717,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 +849,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 +860,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 +985,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 +1094,9 @@ Direct 模式在受控 session 内执行，具有以下硬性限制：
 - 禁止修改 `node_modules`
 - 禁止手动修改 release/dist
 - 禁止修改二进制文件
+- 只修改大小受限的 UTF-8 文本；补丁按 UTF-8 字节计数
+- 补丁或同步结果包含疑似凭据时拒绝写入
+- 同一 session 的 patch、sync、verify、finalize、audit 串行化
 - 所有操作限制在 `workspaceRoot` 和 session repo 内
 
 ### 不支持内容
@@ -1022,9 +1122,9 @@ PatchWarden 的主要保护：
 - Agent 命令和参数模板必须预先配置。
 - 验证命令必须精确匹配白名单。
 - 文件访问被限制在 `workspaceRoot` 内。
-- 敏感文件名和明显的凭据读取计划会被阻止。
-- 任务产物中的疑似密钥值会被脱敏。
-- HTTP Server 只绑定 `127.0.0.1`。
+- 敏感文件名和明显的凭据读取计划会被阻止；`.patchwarden/` 不会绕过该检查。
+- 任务差异中的疑似密钥值会在落盘前脱敏，并把任务标记为策略违规。
+- HTTP 服务只绑定 `127.0.0.1`，并拒绝非回环 Host。
 - Runner 不会自动 commit、push、发布或重置仓库。
 
 需要保护的本地路径：

package/dist/assessments/agentAssessor.js

@@ -1,8 +1,9 @@
-import { writeFileSync } from "node:fs";
-import { resolve, relative, isAbsolute } from "node:path";
+import { resolve, relative, isAbsolute, sep } from "node:path";
 import { buildAgentInvocation, buildAssessmentPrompt } from "../runner/agentInvocation.js";
 import { runSimpleProcessSync } from "../runner/simpleProcess.js";
 import { captureRepoSnapshot, compareSnapshots } from "../runner/changeCapture.js";
+import { atomicWriteFileSync, atomicWriteJsonFileSync } from "../utils/atomicFile.js";
+import { redactSensitiveContent } from "../security/contentRedaction.js";
 const ASSESSMENT_MARKER = "===ASSESSMENT_JSON===";
 export async function runAgentAssessment(input) {
     const logPaths = {
@@ -26,9 +27,11 @@ export async function runAgentAssessment(input) {
         log_paths: logPaths,
     };
     // ── 1. Build prompt and write to file for {prompt_file} support ──
-    const assessmentPrompt = buildAssessmentPrompt(input.goal, input.planContent, input.repoPath);
+    const safeGoal = redactSensitiveContent(input.goal).content.slice(0, 10_000);
+    const safePlan = redactSensitiveContent(input.planContent).content.slice(0, 1024 * 1024);
+    const assessmentPrompt = buildAssessmentPrompt(safeGoal, safePlan, input.repoPath);
     const promptFilePath = resolve(input.assessmentDir, "agent-assessment-prompt.md");
-    writeFileSync(promptFilePath, assessmentPrompt, "utf-8");
+    atomicWriteFileSync(promptFilePath, assessmentPrompt);
     logPaths.prompt = promptFilePath;
     // ── 2. Before snapshot (repo-scoped) ──
     let repoBefore;
@@ -68,6 +71,8 @@ export async function runAgentAssessment(input) {
         maxStderrBytes: Math.max(16384, Math.floor(input.maxOutputBytes / 4)),
         stdoutPath: logPaths.stdout,
         stderrPath: logPaths.stderr,
+        environmentVariableNames: invocation.environmentVariableNames,
+        blockedEnvironmentVariableNames: invocation.blockedEnvironmentVariableNames,
     });
     // ── 5. After snapshot + read-only violation check ──
     let readOnlyViolation = false;
@@ -101,11 +106,11 @@ export async function runAgentAssessment(input) {
             stderr_truncated: result.stderrTruncated,
             log_paths: { ...logPaths, violation: resolve(input.assessmentDir, "agent-assessment-violation.json") },
         };
-        writeFileSync(summary.log_paths.violation, JSON.stringify({
+        atomicWriteJsonFileSync(summary.log_paths.violation, {
             violation: "read_only_violation",
             files: violationFiles,
             exit_code: result.exitCode,
-        }, null, 2), "utf-8");
+        });
         writeSummary(logPaths.assessment, summary);
         return summary;
     }
@@ -216,13 +221,17 @@ function parseAssessmentJson(stdout, repoPath) {
     const jsonEnd = jsonText.lastIndexOf("}");
     if (jsonStart < 0 || jsonEnd < 0 || jsonEnd <= jsonStart)
         return { output: null, sanitized_reasons };
-    let parsed;
+    let parsedValue;
     try {
-        parsed = JSON.parse(jsonText.slice(jsonStart, jsonEnd + 1));
+        parsedValue = JSON.parse(jsonText.slice(jsonStart, jsonEnd + 1));
     }
     catch {
         return { output: null, sanitized_reasons };
     }
+    if (!parsedValue || typeof parsedValue !== "object" || Array.isArray(parsedValue)) {
+        return { output: null, sanitized_reasons };
+    }
+    const parsed = parsedValue;
     // ── Strict validation ──
     if (parsed.risk_level !== "low" && parsed.risk_level !== "medium" && parsed.risk_level !== "high") {
         return { output: null, sanitized_reasons };
@@ -235,7 +244,7 @@ function parseAssessmentJson(stdout, repoPath) {
         return { output: null, sanitized_reasons };
     if (parsed.reason_codes.length > 50)
         return { output: null, sanitized_reasons };
-    const reasonCodes = parsed.reason_codes.filter((r) => typeof r === "string" && r.length <= 100);
+    const reasonCodes = parsed.reason_codes.filter((reason) => typeof reason === "string" && reason.length <= 100);
     if (reasonCodes.length !== parsed.reason_codes.length) {
         sanitized_reasons.push("reason_codes_filtered");
     }
@@ -257,7 +266,7 @@ function parseAssessmentJson(stdout, repoPath) {
         }
         const resolved = resolve(repoPath, p);
         const rel = relative(repoPath, resolved);
-        if (rel.startsWith("..")) {
+        if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
             pathsSanitized = true;
             continue;
         }
@@ -270,7 +279,7 @@ function parseAssessmentJson(stdout, repoPath) {
         return { output: null, sanitized_reasons };
     if (parsed.destructive_actions.length > 20)
         return { output: null, sanitized_reasons };
-    const destructiveActions = parsed.destructive_actions.filter((d) => typeof d === "string" && d.length <= 200);
+    const destructiveActions = parsed.destructive_actions.filter((action) => typeof action === "string" && action.length <= 200);
     if (typeof parsed.requires_user_confirm !== "boolean")
         return { output: null, sanitized_reasons };
     const notes = typeof parsed.notes === "string" ? parsed.notes.slice(0, 2000) : "";
@@ -289,5 +298,5 @@ function parseAssessmentJson(stdout, repoPath) {
     };
 }
 function writeSummary(path, summary) {
-    writeFileSync(path, JSON.stringify(summary, null, 2), "utf-8");
+    atomicWriteJsonFileSync(path, summary);
 }

package/dist/assessments/assessmentDiagnostics.d.ts

@@ -0,0 +1,29 @@
+import type { AssessmentValidationResult } from "./assessmentStore.js";
+export interface AssessmentValidationFailureDiagnostic {
+    diagnostic_version: string;
+    error_code: string;
+    reason_code: string;
+    assessment_id: string | null;
+    assessment_config_sha256: string | null;
+    current_config_sha256: string | null;
+    assessment_config_hash: string | null;
+    current_config_hash: string | null;
+    snapshot_version: string | null;
+    assessment_fingerprint_version: string | null;
+    current_fingerprint_version: string;
+    assessment_schema_epoch: string | null;
+    current_schema_epoch: string;
+    assessment_created_at: string | null;
+    assessment_expires_at: string | null;
+    config_changed: boolean;
+    changed_field_names: string[];
+    changed_config_sections: string[];
+    validator_module_path: string;
+    validator_build_id: string;
+    watcher_instance_id: string | null;
+    observed_at: string;
+}
+export declare function buildAssessmentValidationFailureDiagnostic(result: AssessmentValidationResult): AssessmentValidationFailureDiagnostic | null;
+/** Persist a bounded value-free failure summary without changing validation behavior. */
+export declare function recordAssessmentValidationFailure(result: AssessmentValidationResult): boolean;
+export declare function readLastAssessmentValidationFailure(): AssessmentValidationFailureDiagnostic | null;

package/dist/assessments/assessmentDiagnostics.js

@@ -0,0 +1,132 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAssessmentsDir, getConfig } from "../config.js";
+import { guardPath } from "../security/pathGuard.js";
+import { atomicWriteJsonFileSync } from "../utils/atomicFile.js";
+import { readJsonObjectFileSync } from "../utils/lockedJsonFile.js";
+import { ASSESSMENT_SECURITY_SNAPSHOT_VERSION } from "./securitySnapshot.js";
+import { PATCHWARDEN_VERSION, TOOL_SCHEMA_EPOCH } from "../version.js";
+const DIAGNOSTIC_VERSION = "assessment-validation-diagnostic-v2";
+const DIAGNOSTIC_FILE = "last-validation-failure.json";
+const VALIDATOR_MODULE_PATH = "dist/assessments/assessmentStore.js";
+const VALIDATOR_BUILD_ID = `patchwarden-${PATCHWARDEN_VERSION}:${TOOL_SCHEMA_EPOCH}:${ASSESSMENT_SECURITY_SNAPSHOT_VERSION}`;
+export function buildAssessmentValidationFailureDiagnostic(result) {
+    if (result.valid || !result.failure_reason)
+        return null;
+    const reasonCode = safeCode(result.failure_reason);
+    const assessmentHash = safeHash(result.expected_hash);
+    const currentHash = safeHash(result.actual_hash);
+    const changedSections = [...new Set((result.config_change_categories || [])
+            .map((name) => safeCode(name))
+            .filter(Boolean))]
+        .sort()
+        .slice(0, 32);
+    const assessmentVersion = safeText(result.assessment?.assessment_security_snapshot_version, 80);
+    return {
+        diagnostic_version: DIAGNOSTIC_VERSION,
+        error_code: reasonCode,
+        reason_code: reasonCode,
+        assessment_id: safeAssessmentId(result.assessment?.assessment_id),
+        assessment_config_sha256: assessmentHash,
+        current_config_sha256: currentHash,
+        assessment_config_hash: assessmentHash,
+        current_config_hash: currentHash,
+        snapshot_version: assessmentVersion,
+        assessment_fingerprint_version: assessmentVersion,
+        current_fingerprint_version: ASSESSMENT_SECURITY_SNAPSHOT_VERSION,
+        assessment_schema_epoch: safeText(result.assessment?.assessment_schema_epoch, 80),
+        current_schema_epoch: TOOL_SCHEMA_EPOCH,
+        assessment_created_at: safeTimestamp(result.assessment?.created_at),
+        assessment_expires_at: safeTimestamp(result.assessment?.expires_at),
+        config_changed: result.failure_reason === "assessment_stale_config",
+        changed_field_names: changedSections,
+        changed_config_sections: changedSections,
+        validator_module_path: VALIDATOR_MODULE_PATH,
+        validator_build_id: VALIDATOR_BUILD_ID,
+        watcher_instance_id: safeInstanceId(process.env.PATCHWARDEN_WATCHER_INSTANCE_ID),
+        observed_at: new Date().toISOString(),
+    };
+}
+/** Persist a bounded value-free failure summary without changing validation behavior. */
+export function recordAssessmentValidationFailure(result) {
+    const diagnostic = buildAssessmentValidationFailureDiagnostic(result);
+    if (!diagnostic)
+        return false;
+    try {
+        const config = getConfig();
+        const assessmentsDir = getAssessmentsDir(config);
+        const file = guardPath(join(assessmentsDir, DIAGNOSTIC_FILE), config.workspaceRoot, config.assessmentsDir);
+        mkdirSync(dirname(file), { recursive: true });
+        atomicWriteJsonFileSync(file, diagnostic);
+        return true;
+    }
+    catch {
+        // Diagnostics must never replace the original fail-closed validation error.
+        return false;
+    }
+}
+export function readLastAssessmentValidationFailure() {
+    try {
+        const config = getConfig();
+        const file = guardPath(join(getAssessmentsDir(config), DIAGNOSTIC_FILE), config.workspaceRoot, config.assessmentsDir);
+        if (!existsSync(file))
+            return null;
+        const raw = readJsonObjectFileSync(file);
+        if (raw.diagnostic_version !== DIAGNOSTIC_VERSION)
+            return null;
+        const changedSections = Array.isArray(raw.changed_config_sections)
+            ? [...new Set(raw.changed_config_sections.map(safeCode).filter(Boolean))].sort().slice(0, 32)
+            : [];
+        return {
+            diagnostic_version: DIAGNOSTIC_VERSION,
+            error_code: safeCode(raw.error_code),
+            reason_code: safeCode(raw.reason_code),
+            assessment_id: safeAssessmentId(raw.assessment_id),
+            assessment_config_sha256: safeHash(raw.assessment_config_sha256),
+            current_config_sha256: safeHash(raw.current_config_sha256),
+            assessment_config_hash: safeHash(raw.assessment_config_hash),
+            current_config_hash: safeHash(raw.current_config_hash),
+            snapshot_version: safeText(raw.snapshot_version, 80),
+            assessment_fingerprint_version: safeText(raw.assessment_fingerprint_version, 80),
+            current_fingerprint_version: safeText(raw.current_fingerprint_version, 80) || ASSESSMENT_SECURITY_SNAPSHOT_VERSION,
+            assessment_schema_epoch: safeText(raw.assessment_schema_epoch, 80),
+            current_schema_epoch: safeText(raw.current_schema_epoch, 80) || TOOL_SCHEMA_EPOCH,
+            assessment_created_at: safeTimestamp(raw.assessment_created_at),
+            assessment_expires_at: safeTimestamp(raw.assessment_expires_at),
+            config_changed: raw.config_changed === true,
+            changed_field_names: Array.isArray(raw.changed_field_names)
+                ? [...new Set(raw.changed_field_names.map(safeCode).filter(Boolean))].sort().slice(0, 32)
+                : [],
+            changed_config_sections: changedSections,
+            validator_module_path: safeText(raw.validator_module_path, 120) || VALIDATOR_MODULE_PATH,
+            validator_build_id: safeText(raw.validator_build_id, 160) || VALIDATOR_BUILD_ID,
+            watcher_instance_id: safeInstanceId(raw.watcher_instance_id),
+            observed_at: safeTimestamp(raw.observed_at) || new Date(0).toISOString(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function safeAssessmentId(value) {
+    return typeof value === "string" && /^assessment_\d{8}_\d{6}_[0-9a-f]{32}$/.test(value) ? value : null;
+}
+function safeInstanceId(value) {
+    return typeof value === "string" && /^[a-zA-Z0-9_-]{1,100}$/.test(value) ? value : null;
+}
+function safeCode(value) {
+    return typeof value === "string" && /^[a-z0-9_]{1,80}$/.test(value) ? value : "";
+}
+function safeHash(value) {
+    return typeof value === "string" && /^[0-9a-f]{64}$/.test(value) ? value : null;
+}
+function safeText(value, maxLength) {
+    return typeof value === "string" && value.length > 0
+        ? value.replace(/[\r\n]+/g, " ").slice(0, maxLength)
+        : null;
+}
+function safeTimestamp(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value))
+        ? new Date(value).toISOString()
+        : null;
+}

package/dist/assessments/assessmentStore.d.ts

@@ -1,6 +1,8 @@
+import { PatchWardenConfig } from "../config.js";
 import { type RepoSnapshot } from "../runner/changeCapture.js";
 import type { RiskAssessmentResult } from "../security/riskEngine.js";
 import type { TaskTemplateName, ChangePolicy } from "../tools/taskTemplates.js";
+import { type SecuritySnapshotCategory } from "./securitySnapshot.js";
 export interface AgentAssessmentSummary {
     attempted: boolean;
     status: "completed" | "timed_out" | "non_zero_exit" | "parse_failed" | "read_only_violation" | "spawn_failed" | "not_run";
@@ -44,6 +46,12 @@ export interface AssessmentRecord {
     plan_id: string | null;
     policy_hash: string;
     tool_manifest_sha256: string;
+    execution_config_hash?: string;
+    execution_config_component_hashes?: Partial<Record<ExecutionConfigChangeCategory, string>>;
+    assessment_security_snapshot_version?: string;
+    assessment_security_snapshot_sha256?: string;
+    assessment_security_snapshot_component_hashes?: Partial<Record<ExecutionConfigChangeCategory, string>>;
+    assessment_schema_epoch?: string;
     workspace_fingerprint: string;
     workspace_snapshot_summary: {
         head: string | null;
@@ -62,10 +70,15 @@ export interface AssessmentRecord {
     agent: string;
     timeout_seconds?: number;
     change_policy?: ChangePolicy;
+    scope?: string[];
+    forbidden?: string[];
+    verification?: string[];
+    done_evidence?: string[];
     requires_confirm: boolean;
     confirmed: boolean;
     confirmed_at: string | null;
     confirm_code: string | null;
+    used_at?: string | null;
     agent_assessment_summary?: AgentAssessmentSummary | null;
 }
 export interface AssessmentCreateInput {
@@ -85,6 +98,10 @@ export interface AssessmentCreateInput {
     agent: string;
     timeout_seconds?: number;
     change_policy?: ChangePolicy;
+    scope?: string[];
+    forbidden?: string[];
+    verification?: string[];
+    done_evidence?: string[];
     snapshot: RepoSnapshot;
     assessment_id?: string;
     assessment_dir?: string;
@@ -94,7 +111,11 @@ export interface AssessmentValidationResult {
     valid: boolean;
     failure_reason: string | null;
     assessment: AssessmentRecord | null;
+    expected_hash?: string;
+    actual_hash?: string;
+    config_change_categories?: ExecutionConfigChangeCategory[];
 }
+export type ExecutionConfigChangeCategory = SecuritySnapshotCategory | "allowed_test_commands" | "execution_config";
 export interface AssessmentConfirmationResult {
     assessment_id: string;
     decision: "needs_confirm";
@@ -111,6 +132,8 @@ export declare function generateAssessmentId(): string;
 export declare function createAssessmentDir(assessmentId: string): string;
 export declare function createAssessment(input: AssessmentCreateInput): AssessmentRecord;
 export declare function readAssessment(assessmentId: string): AssessmentRecord;
+/** Atomically consume an Assessment before creating its one allowed task. */
+export declare function markAssessmentUsed(assessmentId: string): AssessmentRecord;
 export declare function validateAssessmentFreshness(assessmentId: string, currentSnapshot: RepoSnapshot, options?: AssessmentValidationOptions): AssessmentValidationResult;
 /**
  * Records an explicit confirmation performed from the local PatchWarden CLI.
@@ -130,4 +153,20 @@ interface PolicyHashInput {
     schema_epoch: string;
 }
 export declare function computePolicyHash(input: PolicyHashInput): string;
+interface ExecutionConfigHashInput {
+    agent: string;
+    tool_manifest_sha256: string;
+    tool_profile: string;
+    repo_path: string;
+    change_policy?: string | null;
+    template?: string | null;
+    verify_commands?: string[];
+    test_command?: string | null;
+    task_timeout_seconds?: number | null;
+    scope?: string[];
+    forbidden?: string[];
+    verification?: string[];
+    done_evidence?: string[];
+}
+export declare function computeExecutionConfigHash(config: PatchWardenConfig, input: ExecutionConfigHashInput): string;
 export {};