patchwarden 1.5.0 → 1.6.1

package/docs/spec-kit-integration.md

@@ -0,0 +1,131 @@
+# Spec Kit 集成模式
+
+> 本文基于 v1.5.1 源码编写；安装时请使用已验证发布的 <published-version>。
+> 说明：本文描述的是 PatchWarden 与 Spec Kit 的集成模式建议，**不是** Spec Kit 的官方功能。
+> Spec Kit 是 GitHub 维护的独立项目，本文不声称任何官方集成关系。
+
+## Spec Kit 是什么
+
+Spec Kit 是 GitHub 推出的 spec-driven development（规格驱动开发）工具集，
+用于在代码实现之前先定义、版本化、验证规格（spec）。典型流程为：
+
+1. **Spec**：用结构化方式描述功能需求与验收标准。
+2. **Tasks**：将 spec 拆解为可执行的任务列表。
+3. **Implementation**：由人或 Agent 执行任务。
+4. **Verification**：根据 spec 的验收标准验证实现结果。
+
+Spec Kit 的核心价值在于把“要做什么”与“怎么做”显式分离，让验收有据可依。
+
+## PatchWarden 在 Spec Kit 流程中的位置
+
+PatchWarden 不替代 Spec Kit 的规格定义能力，而是承担 Spec Kit 流程中
+“Implementation”与“Verification”两个阶段的**安全执行与证据收集**角色：
+
+```
+Spec Kit: spec → tasks → implementation → verification
+                              ↑                ↑
+                              PatchWarden 在此执行并产出 Evidence Pack v2
+```
+
+- **Implementation 阶段**：PatchWarden 以 MCP 安全桥接器身份接收任务，
+  在 workspace 隔离、命令允许列表、范围违规检测下执行。
+- **Verification 阶段**：PatchWarden 导出 Evidence Pack v2，作为 spec
+  验收的结构化证据。
+
+## Evidence Pack v2 作为 spec 验收证据
+
+Spec Kit 的验收标准通常是自然语言描述。PatchWarden 的 Evidence Pack v2
+提供机器可读的对应物，便于自动化对齐：
+
+| Evidence Pack 文件 | Spec 验收对应物 |
+| --- | --- |
+| `evidence.json` | 任务整体证据，含 lineage、policy、catalog 摘要 |
+| `EVIDENCE.md` | 人类可读摘要，便于 spec reviewer 阅读 |
+| `risk.json` | 实现过程中识别的风险项，对应 spec 的风险条款 |
+| `verify.json` | 每轮迭代的结构化验证记录 |
+| `diffstat.json` | 文件级改动统计，对应 spec 声明的改动范围 |
+| `lineage.json` | 任务谱系，证明实现源自哪条 spec task |
+| `attestation.json` | 任务签名与证明 |
+| `redactions.json` | 已脱敏内容清单 |
+
+## 集成流程示例
+
+### 1. 在 Spec Kit 中定义 spec 与 tasks
+
+在 Spec Kit 仓库中编写 spec 与 task 清单，例如：
+
+```json
+{
+  "spec": "add-rate-limit-middleware",
+  "tasks": [
+    { "id": "T1", "desc": "implement rate limiter", "files": ["src/middleware/rate.ts"] },
+    { "id": "T2", "desc": "add tests", "files": ["test/middleware/rate.test.ts"] }
+  ],
+  "acceptance": ["T1 passes", "T2 passes", "no changes outside declared files"]
+}
+```
+
+### 1.5 批量导入 Spec Kit tasks 为 PatchWarden subgoal
+
+PatchWarden 提供 `import_speckit_tasks` 工具，可将 Spec Kit 的 tasks 批量导入为 Goal 下的 subgoal：
+
+- 每个 Spec Kit task 创建一个对应 subgoal，title 取自 task.desc
+- task.files 映射为 subgoal 的 scope_hints（声明改动范围提示）
+- task.depends_on 映射为 subgoal 间的依赖关系
+- Spec Kit 的 acceptance[] 存入 Goal 的 acceptance_criteria 字段
+- 支持幂等导入：重复导入同一 Spec Kit JSON 不会创建重复 subgoal
+
+### 2. 通过 PatchWarden 执行任务
+
+将 Spec Kit 的 task 通过 MCP 客户端交给 PatchWarden：
+
+```powershell
+# 假设 PatchWarden MCP server 已启动
+# MCP 客户端调用 PatchWarden 工具，传入 task 描述与声明的文件范围
+```
+
+PatchWarden 会在执行时：
+
+- 校验改动是否仅在 `src/middleware/rate.ts` 与 `test/middleware/rate.test.ts`。
+- 阻断任何越界文件改动或未注册命令。
+- 在每轮迭代后记录结构化验证。
+
+### 3. 导出 Evidence Pack 并与 spec 对齐
+
+任务完成后导出 Evidence Pack v2：
+
+```powershell
+# 通过 MCP 工具 export_task_evidence_pack 导出
+# 产物位于 .patchwarden/evidence-packs/<lineage_id>/
+```
+
+随后可用脚本将 `diffstat.json` 与 spec 声明的 `files` 对齐，
+将 `verify.json` 与 spec `acceptance` 对齐。
+
+### 4. Spec 验收
+
+reviewer 阅读 `EVIDENCE.md` 与 `verify.json`，
+确认实现满足 spec 验收标准后标记 spec 为已验收。
+
+## 配置要点
+
+- PatchWarden 的 `workspaceRoot` 应覆盖 Spec Kit 仓库根目录。
+- Spec Kit 的 task 中声明的文件范围应与 PatchWarden Project Policy 的
+  allowed paths 一致，避免执行时被范围违规检测阻断。
+- Evidence Pack v2 的 `lineage.json` 可用于回溯到 Spec Kit 的 task id，
+  建议在任务描述中包含 Spec Kit task id。
+
+## 边界与注意事项
+
+- PatchWarden 不解析 Spec Kit 的 spec 格式本身，只处理 tasks 与 acceptance 字段并产出证据。
+- Spec Kit 的 spec 验收逻辑由 Spec Kit 自身或 reviewer 负责，
+  PatchWarden 只提供证据材料。
+- 本集成模式不修改 Spec Kit 的任何行为，仅在流程上配合使用。
+- 如 Spec Kit task 要求读取 `.env` 或敏感文件，PatchWarden 会按安全契约阻断，
+  此时需要重新设计 task 以避免触碰敏感资源。
+
+## 相关文档
+
+- `docs/evidence-pack-schema.md`：Evidence Pack v2 文件结构。
+- `docs/threat-model.md`：PatchWarden 安全契约。
+- `docs/why-patchwarden.md`：PatchWarden 定位与动机。

package/docs/task-safe-review-workflow.md

@@ -0,0 +1,98 @@
+# 任务 Safe 验收工作流
+
+> 本文基于 v1.5.1 源码编写；安装时请使用已验证发布的 <published-version>。
+> 相关页面：Tasks、Task Detail
+
+## 目的
+
+在不暴露完整日志、diff、test log 的前提下，用一组 safe 摘要接口完成对单个任务的
+验收判断。完整产物仅在确认需要时才从折叠的“高级区”按需加载。
+
+## 核心概念
+
+- **safe_result**：任务结果摘要，包含 status、acceptance_status、verification 概要、
+  warnings、fail_checks、manual_verification_required、recommended_next_actions。
+- **safe_test_summary**：测试摘要，只包含通过/失败计数和失败用例名称，不含完整 stdout。
+- **safe_diff_summary**：diff 摘要，包含变更文件数、新增/删除/修改行数统计、
+  受保护路径命中情况，不含完整 diff。
+- **safe_audit**：审计摘要，包含 artifact 完整性、scope_changes、命令白名单合规性
+  的有界摘要。
+- **acceptance_status**：任务的验收状态，比 `status` 更能反映“是否真的通过”。
+- **Advanced 区**：折叠区域，包含配置上限内的 result / diff / test_log，需手动展开。
+
+## 验收工作流
+
+### 1. 在 Tasks 列表筛选目标任务
+
+Tasks 页支持按 `repo_path` / `status` / `acceptance_status` / `warning_type` /
+`agent` / date range 过滤。建议优先关注：
+
+- `acceptance_status` 为 `pending` 或 `failed_verification` 的任务
+- 带有 warning 的任务（warning_type 列会高亮）
+
+### 2. 使用行内快捷操作预览
+
+每行任务提供以下快捷操作，无需进入详情页即可快速判断：
+
+- `safe_result` — 查看任务结果摘要
+- `safe_test_summary` — 查看测试摘要
+- `safe_diff_summary` — 查看变更摘要
+- `safe_audit` — 查看审计摘要
+- `open detail` — 进入 Task Detail 页
+- `copy id` — 复制完整 task_id
+
+### 3. 进入 Task Detail 进行完整 safe 验收
+
+Task Detail 默认展示 safe 摘要视图：
+
+- **safe_result** 区：status、acceptance_status、verification headline、warnings、
+  fail_checks、manual_verification_required、recommended_next_actions
+- **safe_test_summary** 区：通过/失败计数、失败用例名
+- **safe_diff_summary** 区：变更文件数、行数统计、受保护路径命中
+- **safe_audit** 区：artifact 完整性、scope_changes、命令合规性
+
+### 4. 仅在必要时展开高级区
+
+只有当 safe 摘要无法定论时（例如 `manual_verification_required` 为 true，
+或 `fail_checks` 指向某个具体失败），才展开高级区查看配置上限内的产物：
+
+- 有界并脱敏的 result（JSON）
+- 有界并脱敏的 diff
+- 有界并脱敏的 test_log
+
+> 高级区内容不会自动加载，必须手动点击展开。展开不会触发任何写操作。
+
+### 5. 根据 recommended_next_actions 决定下一步
+
+safe_result 的 `recommended_next_actions` 会给出建议，例如：
+
+- 验收通过 → 导出 Evidence Pack 或进行 Direct 独立验证
+- 验收失败 → 基于 `run_task_loop` 创建修复任务
+- 需要人工确认 → 标记 `manual_verification_required` 后人工复核
+
+## Stale 任务处理
+
+Stale 任务卡片会给出 explanation 和 next_action：
+
+- **view detail** — 查看 safe 摘要判断是否需要重建
+- **copy task_id** — 复制 id 用于后续命令
+- **hide** — 调用 `POST /api/tasks/:taskId/hide-stale` 从 stale 列表隐藏
+- **recreate task** — 基于原任务参数创建新任务
+
+## 安全边界
+
+- safe 接口返回有界摘要，不含完整 stdout/stderr、完整 diff、密钥、token。
+- 完整产物仅在高级区手动展开后加载，且不离开本机。
+- 验收操作不触发远程写（不 publish、不 push、不 tag、不 release）。
+- `acceptance_status` 由 watcher 与 verification 流程计算，不能从 UI 直接伪造。
+
+## 相关 API 端点
+
+- `GET /api/tasks` — 任务列表（支持 repo_path / status / acceptance_status /
+  agent / warning_type 过滤）
+- `GET /api/tasks/:taskId/safe-result` — safe_result 摘要
+- `GET /api/tasks/:taskId/safe-test-summary` — safe_test_summary 摘要
+- `GET /api/tasks/:taskId/safe-diff-summary` — safe_diff_summary 摘要
+- `GET /api/tasks/:taskId/safe-audit` — safe_audit 摘要
+- `GET /api/tasks/stale` — stale 任务列表（含 explanation / next_action）
+- `POST /api/tasks/:taskId/hide-stale` — 隐藏 stale 任务

package/docs/threat-model.md

@@ -0,0 +1,97 @@
+# PatchWarden Threat Model
+
+PatchWarden is a local MCP bridge for AI coding workflows. Its core security
+goal is to let an MCP client request bounded maintainer tasks without turning
+the local machine into a general-purpose remote shell.
+
+## Assets Protected
+
+- source repositories under the configured workspace
+- release artifacts and checksums
+- task evidence under `.patchwarden/`
+- local configuration files
+- `.env` files, API keys, tokens, SSH keys, cookies, browser state, and
+  credential stores
+- maintainer time and trust in verification evidence
+
+## Trust Boundaries
+
+PatchWarden assumes the upstream model or MCP client can be wrong, overbroad, or
+prompt-injected. It should not be trusted with unrestricted command execution,
+arbitrary filesystem reads, or release authority.
+
+Trusted local configuration includes:
+
+- `workspaceRoot`
+- registered agents and their command templates
+- `allowedTestCommands`
+- project policy files reviewed by the maintainer
+
+Human maintainer confirmation remains required for high-risk actions such as
+publishing, pushing, creating releases, changing live services, or approving
+local confirmation tickets.
+
+## Main Threats
+
+| Threat | Example | Mitigation |
+| --- | --- | --- |
+| Arbitrary shell execution | A prompt asks the MCP server to run a custom command. | PatchWarden exposes task tools, not a general shell; verification commands must exactly match allowlists. |
+| Path traversal | A task tries to edit `../other-project` or user home files. | Task paths are resolved under `workspaceRoot`; out-of-scope changes are reported as violations. |
+| Secret exfiltration | A task asks to read `.env`, SSH keys, cookies, or credentials. | Sensitive path names are blocked and docs require redacted logs. |
+| Prompt injection | Repository text instructs the model to ignore safety constraints. | Safety is enforced by local code and configuration, not by prompt instructions alone. |
+| Unsafe release claims | A local build passes and the agent claims npm/GitHub publish is complete. | Release docs require separate verification of PR/CI, GitHub Release, npm version, and `dist-tags.latest`. |
+| Evidence overload | A client requests full logs, diffs, or private task history by default. | Safe summary tools and bounded evidence packs are the preferred review surfaces. |
+| Evidence secret persistence | An agent writes a token into a normal source file and the Git diff duplicates it under `.patchwarden`. | Diff evidence is capped at 20 MiB, redacted before persistence, and credential-like content produces a policy violation. |
+| Artifact-directory confusion | A secret-shaped filename is placed under `.patchwarden` and assumed safe because it is an internal artifact. | The sensitive-name guard applies at every depth; `.patchwarden` has no blanket exemption. |
+| Concurrent Goal/worktree mutation | Two MCP processes accept subgoals or create/merge/discard worktrees at the same time and lose state or corrupt repository lifecycle. | Goal mutations share a cross-process lock and atomic replacement; worktree repository mutations share a lifecycle lock. |
+| Evidence resource exhaustion | Oversized task logs or a large documentation tree consume unbounded memory, response size, or disk. | Task and Control reads use bounded prefix/tail reads, audit scans enforce file/byte budgets, and persistent invocation/reconcile logs use locked bounded append with explicit truncation. |
+| DNS rebinding | A hostile web origin resolves to `127.0.0.1` and tries to read the Control token or call HTTP MCP. | Control Center and HTTP MCP reject Host headers other than the configured `127.0.0.1`/`localhost` origin. |
+| Live-service disruption | A task restarts tunnels, watchers, or unrelated processes. | Project rules forbid blanket process kills; live cutover must be explicit and separately approved. |
+
+## Security Invariants
+
+PatchWarden changes should preserve these invariants:
+
+- no general-purpose remote shell
+- all task repositories stay under `workspaceRoot`
+- agents are explicitly registered before use
+- child processes receive a minimal environment; provider variables require an
+  explicit per-agent `envAllowlist`, and Tunnel owner credentials are never
+  forwarded
+- model input cannot define arbitrary agent launch commands
+- verification commands use exact allowlist matching
+- sensitive paths remain blocked at every directory depth, including under
+  `.patchwarden`
+- task artifacts remain auditable and redacted where appropriate
+- Goal status mutations and worktree repository lifecycle changes are
+  cross-process serialized; a non-empty Goal becomes completed only after all
+  subgoals are accepted
+- subgoal tasks use the Goal's stored `repo_path` as authority and reject a
+  caller-supplied repository mismatch
+- task/audit/log read and append paths enforce explicit byte, line, or file
+  budgets and report truncation
+- Direct patch/sync accepts only bounded UTF-8 text, rejects credential-like
+  results, and serializes session mutations
+- scope violations are surfaced, not silently accepted
+- publish, push, tag, release, and live-service operations remain
+  confirmation-gated
+
+## Non-Goals
+
+PatchWarden is not a full sandbox, container runtime, endpoint security product,
+or secret scanner. It adds policy, task evidence, verification, and review
+records around local agent work. It should be used with normal operating-system
+permissions, Git review, CI, and maintainer judgment.
+
+## Review Checklist For Security-Sensitive Changes
+
+- [ ] Does the change weaken workspace confinement?
+- [ ] Does it expand command execution beyond exact allowlists?
+- [ ] Does it expose full logs, diffs, task history, or file contents where a
+      safe summary would be enough?
+- [ ] Does it read or persist credentials, tokens, cookies, browser state, or
+      `.env` content?
+- [ ] Does it auto-push, auto-publish, auto-tag, or restart live services?
+- [ ] Does it add or update smoke coverage for changed behavior?
+- [ ] Does it keep README, examples, tool manifests, package metadata, and
+      migration docs aligned?

package/docs/user-feedback.md

@@ -0,0 +1,40 @@
+# PatchWarden User Feedback
+
+This file tracks real feedback only. Do not add invented users, fake adoption,
+or private conversations that cannot be shared.
+
+## Current Status
+
+No third-party feedback has been imported into this repository yet.
+
+Before using this file as application evidence, collect public feedback through
+GitHub issues or discussions from real testers who have tried at least one of
+the documented flows.
+
+## Feedback To Collect
+
+Ask testers to include:
+
+- operating system
+- Node.js version
+- MCP client used, such as ChatGPT, Codex, OpenCode, or another MCP client
+- whether `npm.cmd run doctor` or the documented setup passed
+- what task they attempted
+- whether task evidence, safe summaries, or audit output helped
+- confusing setup steps
+- feature requests
+
+## Public Feedback Log
+
+| Date | Source | Tester context | Result | Follow-up |
+| --- | --- | --- | --- | --- |
+| Pending | Pending GitHub issue or discussion | Pending | Pending | Pending |
+
+## Maintainer Response Rules
+
+- Keep feedback public when possible.
+- Redact local paths, logs, keys, tokens, cookies, `.env` contents, and account
+  identifiers.
+- Convert recurring friction into issues with `documentation`, `good first
+  issue`, `help wanted`, or `security` labels when appropriate.
+- Close the loop by linking fixes, docs, or release notes back to the feedback.

package/docs/why-patchwarden.md

@@ -0,0 +1,110 @@
+# 为什么需要 PatchWarden
+
+> 本文基于 v1.5.1 源码编写；安装时请使用已验证发布的 <published-version>。
+> 面向：使用 ChatGPT、Codex、OpenCode 等 MCP 客户端但需要安全边界的开发者
+
+## 背景：本地 Agent 的安全缺口
+
+当前主流的本地编程 Agent（如 ChatGPT 桌面端、Codex CLI、OpenCode、OpenHands）
+在带来生产力提升的同时，也引入了新的攻击面：
+
+- Agent 可执行本地命令，一旦被 prompt injection 或上下文污染，可能执行越权操作。
+- 通用远程 Shell 模式将完整命令执行能力暴露给 MCP 客户端，缺乏边界。
+- 任务产物分散在 stdout / stderr / diff 中，难以审计与验收。
+- `.env`、token、SSH key、cookie、浏览器状态等敏感文件缺乏强制隔离。
+
+PatchWarden 不是另一个通用 Shell。它定位为本地优先的 MCP 安全与验证层
+（local-first MCP safety and verification layer for AI coding agents），
+在不牺牲 Agent 能力的前提下提供可审计的安全边界。
+
+## 核心价值
+
+### 1. Workspace Confinement（工作区隔离）
+
+所有仓库路径必须位于配置的 `workspaceRoot` 之下。PatchWarden 会阻断：
+
+- 越出 workspace 的文件读写。
+- 对敏感文件名（如 `.env`、`id_rsa`、`cookies.db`）的访问。
+- 跨仓库的非授权改动。
+
+### 2. Command Allowlists（命令允许列表）
+
+PatchWarden 采用精确命令匹配，而非宽松的 glob 或前缀匹配：
+
+- 只有显式注册的命令才能执行。
+- 参数变化同样受约束，避免命令注入绕过。
+- 不存在“允许 `git` 即允许任意 git 子命令”的隐式放大。
+
+### 3. Scope-Violation Detection（范围违规检测）
+
+Agent 提出的任务若超出声明的 scope（例如修改了未授权文件、执行了未注册命令），
+PatchWarden 会在执行前或执行中识别并阻断，而不是事后才在日志里发现。
+
+### 4. Auditable Task Evidence（可审计任务证据）
+
+每个任务通过 Evidence Pack v2 导出 8 个有界文件：
+
+| 文件 | 用途 |
+| --- | --- |
+| `evidence.json` | 完整有界证据包（机器可读） |
+| `EVIDENCE.md` | 人类可读的 Markdown 摘要 |
+| `risk.json` | 聚合的风险项与严重度 |
+| `verify.json` | 每轮迭代的结构化验证记录 |
+| `diffstat.json` | 文件级增删统计（不含完整 diff） |
+| `lineage.json` | 任务谱系与上下文链 |
+| `attestation.json` | 任务签名与证明 |
+| `redactions.json` | 已脱敏内容清单 |
+
+这些文件只包含有界摘要，**不**包含完整 stdout/stderr、完整 diff、
+secrets、token、cookie 或凭据路径。
+
+## 与通用远程 Shell 的区别
+
+| 维度 | 通用远程 Shell | PatchWarden |
+| --- | --- | --- |
+| 命令执行 | 任意命令 | 精确允许列表 |
+| 路径访问 | 通常无约束 | 强制 workspace 隔离 |
+| 敏感文件 | 取决于调用方自觉 | 强制阻断 |
+| 任务证据 | 散落在日志 | 8 个有界文件可审计 |
+| 范围违规 | 事后发现 | 执行前/中阻断 |
+| MCP 客户端权限 | 全权委托 | 受约束代理 |
+
+PatchWarden 假设上游模型或 MCP 客户端可能出错、过度宽泛或被 prompt injection。
+它不应被信任以无约束方式执行命令。
+
+## 适用场景
+
+- 使用 ChatGPT / Codex / OpenCode / OpenHands 等 MCP 客户端进行本地代码维护。
+- 需要对 Agent 任务进行可审计验收的团队或个人。
+- 希望将 Agent 限制在特定 workspace 内的开发工作流。
+- 需要生成 spec 验收证据的 spec-driven 开发流程。
+
+## 不适用场景
+
+- 需要任意远程 shell 访问的场景（PatchWarden 刻意不提供）。
+- 需要读取或修改 `.env`、SSH key、浏览器状态等敏感文件的工作流。
+- 需要 Agent 跨多个不受信任 workspace 自由移动的场景。
+- 不接受命令允许列表约束的通用任务执行需求。
+
+## 目标用户
+
+- 使用 ChatGPT 桌面端、Codex CLI、OpenCode 等 MCP 客户端的开发者。
+- 在本地维护多个仓库并希望统一安全边界的维护者。
+- 需要为 Agent 任务生成可审计证据的团队。
+- 对 prompt injection 风险敏感、希望有执行前阻断机制的安全工程师。
+
+## 安全契约要点
+
+PatchWarden 的安全契约（详见 `docs/threat-model.md`）包括：
+
+- 不暴露通用远程 shell，不弱化精确命令匹配。
+- 所有仓库路径保持在 `workspaceRoot` 下，阻断敏感名与越界改动。
+- 不读取或持久化 token、cookie、浏览器状态、`.env`、SSH key、凭据文件。
+- 不无差别 kill watcher 或 tunnel，仅监督 launcher 拥有的进程。
+- 保留结构化任务证据、心跳状态、Git before/after 快照、改动文件记录与脱敏。
+
+## 下一步
+
+- 阅读 `docs/threat-model.md` 了解完整威胁模型。
+- 阅读 `docs/evidence-pack-schema.md` 了解证据包文件结构。
+- 阅读 `docs/dashboard-overview.md` 了解 Control Center 工作流。

package/examples/config.example.json

@@ -6,11 +6,13 @@
   "agents": {
     "codex": {
       "command": "codex",
-      "args": ["exec", "--cd", "{repo}", "{prompt}"]
+      "args": ["exec", "--cd", "{repo}", "{prompt}"],
+      "envAllowlist": []
     },
     "opencode": {
       "command": "opencode",
-      "args": ["run", "{prompt}"]
+      "args": ["run", "{prompt}"],
+      "envAllowlist": []
     }
   },
   "allowedTestCommands": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchwarden",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Secure local MCP bridge for ChatGPT and local agents, with workspace-scoped task loops, safe summaries, audits, and Direct editing.",
   "type": "module",
   "main": "dist/index.js",
@@ -12,9 +12,12 @@
   },
   "files": [
     "dist/",
+    "!dist/test/",
     "docs/",
+    "!docs/archive/",
     "!docs/optimization-proposal.md",
     "src/",
+    "!src/test/",
     "examples/",
     "scripts/",
     "!scripts/control/kill-patchwarden.ps1",
@@ -22,18 +25,14 @@
     "!.local/",
     "ui/",
     "PatchWarden.cmd",
-    "PatchWarden-Control.cmd",
-    "PatchWarden-Control-Tray.cmd",
-    "PatchWarden-Desktop.cmd",
-    "Restart-PatchWarden-Control.cmd",
-    "Stop-PatchWarden.cmd",
     "README.md",
     "README.en.md",
     "LICENSE",
     "tsconfig.json"
   ],
   "scripts": {
-    "build": "node ./node_modules/typescript/bin/tsc",
+    "build": "node scripts/build.js",
+    "check:build-output": "node scripts/checks/build-output-check.js",
     "start": "node dist/index.js",
     "start:http": "node dist/httpServer.js",
     "start:control": "node dist/controlCenter.js",
@@ -43,7 +42,7 @@
     "doctor": "node dist/doctor.js",
     "doctor:ci": "node dist/doctor.js --allow-default-config",
     "test:unit": "node scripts/checks/unit-tests.js",
-    "test": "node dist/smoke-test.js && node scripts/checks/unit-tests.js && node scripts/checks/lifecycle-smoke.js && node scripts/checks/doctor-smoke.js && node scripts/checks/tunnel-supervisor-smoke.js && node scripts/checks/watcher-supervisor-smoke.js && node scripts/checks/control-smoke.js && node scripts/checks/mcp-manifest-check.js && node scripts/checks/brand-check.js && node scripts/checks/control-center-smoke.js",
+    "test": "node scripts/checks/build-output-check.js && node dist/smoke-test.js && node scripts/checks/unit-tests.js && node scripts/checks/lifecycle-smoke.js && node scripts/checks/doctor-smoke.js && node scripts/checks/tunnel-supervisor-smoke.js && node scripts/checks/watcher-supervisor-smoke.js && node scripts/checks/control-smoke.js && node scripts/checks/mcp-manifest-check.js && node scripts/checks/brand-check.js && node scripts/checks/control-center-smoke.js",
     "test:lifecycle": "npm run build && node scripts/checks/lifecycle-smoke.js",
     "test:doctor": "npm run build && node scripts/checks/doctor-smoke.js",
     "test:tunnel-supervisor": "npm run build && node scripts/checks/tunnel-supervisor-smoke.js",
@@ -53,18 +52,36 @@
     "check:search-tool-manifest": "npm run build && node scripts/checks/mcp-manifest-check.js --profile chatgpt_search",
     "check:brand": "node scripts/checks/brand-check.js",
     "test:mcp": "npm run build && node scripts/checks/mcp-smoke.js",
+    "test:mcp:built": "node scripts/checks/mcp-smoke.js",
     "test:http-mcp": "npm run build && node scripts/checks/http-mcp-smoke.js",
+    "test:http-mcp:built": "node scripts/checks/http-mcp-smoke.js",
     "pretest": "npm run build",
     "pack:clean": "npm run build && node scripts/release/pack-clean.js",
-    "verify:package": "npm run build && node scripts/checks/package-manifest-check.js"
+    "pack:clean:built": "node scripts/release/pack-clean.js",
+    "verify:package": "npm run build && node scripts/checks/package-manifest-check.js",
+    "verify:package:built": "node scripts/checks/package-manifest-check.js",
+    "desktop:install": "npm.cmd --prefix desktop install --cache ..\\.npm-cache",
+    "desktop:test": "npm.cmd --prefix desktop test",
+    "desktop:smoke:unpacked": "npm.cmd --prefix desktop run smoke:unpacked --",
+    "desktop:stage": "npm run build && npm.cmd --prefix desktop run stage",
+    "desktop:dev": "npm run build && npm.cmd --prefix desktop run dev",
+    "desktop:package:dir": "npm run build && npm.cmd --prefix desktop run build:dir",
+    "desktop:package": "npm run build && npm.cmd --prefix desktop run build",
+    "desktop:preflight": "node scripts/release/desktop-preflight.js",
+    "desktop:preflight:release": "node scripts/release/desktop-preflight.js --require-clean"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
+    "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^26.1.0",
     "typescript": "^6.0.3"
   },
+  "overrides": {
+    "@hono/node-server": "2.0.11",
+    "hono": "4.12.31",
+    "fast-uri": "4.1.1"
+  },
   "engines": {
     "node": ">=18.0.0"
   },

package/scripts/README.md

@@ -4,13 +4,18 @@ This directory keeps implementation scripts out of the root folder. Normal
 desktop use should start from the root entrypoints:
 
 ```powershell
-.\PatchWarden-Desktop.cmd
-.\PatchWarden-Control.cmd
-.\PatchWarden-Control-Tray.cmd --foreground
-.\Stop-PatchWarden.cmd
+.\scripts\launchers\PatchWarden-Desktop.cmd
+.\scripts\launchers\PatchWarden-Control.cmd
+.\scripts\launchers\PatchWarden-Control-Tray.cmd --foreground
+.\scripts\launchers\Stop-PatchWarden.cmd
 .\PatchWarden.cmd status all
 ```
 
+The installable Windows desktop shell is built separately with
+`npm.cmd run desktop:package`. It preserves these source/npm entrypoints and
+uses the same Control Center API rather than adding another process-management
+surface. See `docs/desktop-app.md`.
+
 ## Control Scripts
 
 - `control/manage-patchwarden.ps1`: backing implementation for `PatchWarden.cmd`.
@@ -34,11 +39,15 @@ desktop use should start from the root entrypoints:
 - `checks/mcp-manifest-check.js`: validates MCP manifest expectations.
 - `brand-check.js`: checks public brand strings.
 - `checks/package-manifest-check.js`: verifies package contents.
+- `checks/build-output-check.js`: verifies clean-output confinement and exact recursive unit-test compilation.
+- `release/desktop-preflight.js`: builds an isolated Windows directory package and writes a bounded preflight receipt.
 
 ## Release Helpers
 
-- `release/pack-clean.js`: rebuilds `release/`, `patchwarden-release.tar.gz`, and the
-  versioned `PatchWarden-v*.zip` artifact.
+- `release/pack-clean.js`: rebuilds the isolated `release/package/` staging
+  directory, `patchwarden-release.tar.gz`, and the versioned
+  `PatchWarden-v*.zip` artifact. Desktop and preflight siblings under
+  `release/` are preserved.
 
 ## Compatibility Launchers
 

package/scripts/build.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { cleanGeneratedOutput } from "./lib/clean-generated-output.js";
+
+const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const dist = resolve(root, "dist");
+
+cleanGeneratedOutput(root, dist);
+process.chdir(root);
+await import("../node_modules/typescript/lib/tsc.js");

package/scripts/checks/brand-check.js

@@ -12,6 +12,9 @@ const allowedLegacyFiles = new Set([
   "docs/release-v0.3.0.md",
   "docs/release-v0.4.0.md",
   "docs/release-v0.6.0.md",
+  "docs/archive/releases/release-v0.6.0.md",
+  "docs/archive/releases/release-v0.6.1.md",
+  "docs/archive/releases/release-v0.6.4.md",
   "scripts/checks/brand-check.js",
   "scripts/release/pack-clean.js",
 ]);