patchwarden 0.6.0 → 0.6.4

package/docs/control-center/control-center-mvp.md

@@ -0,0 +1,205 @@
+# PatchWarden Control Center MVP
+
+> 本地 Web 控制中心，统一管理 PatchWarden Core 与 PatchWarden Direct 两个 MCP profile。
+> 不合并工具，不发布到 npm，不打 git tag。
+
+## 概述
+
+Control Center 是一个绑定 `127.0.0.1:8090` 的本地 HTTP 服务，提供静态 UI 页面和一组容错 JSON API。
+所有进程生命周期操作（start/stop/restart）均委托 `scripts/control/manage-patchwarden.ps1` 执行，
+Control Center 自身不直接 kill 进程，也不读取任意 PID 文件。
+
+- **Core profile**: `chatgpt_core`，17 个工具，HTTP 端口 8080
+- **Direct profile**: `chatgpt_direct`，10 个工具，HTTP 端口 8081
+
+## 新增文件
+
+| 文件 | 说明 |
+| --- | --- |
+| `src/controlCenter.ts` | Control Center HTTP 服务主程序（TypeScript 源） |
+| `scripts/checks/control-center-smoke.js` | 测试模式冒烟测试（ESM，仅用 Node 内置模块） |
+| `scripts/control/start-control-center.ps1` | PowerShell 启动脚本（含构建检查、端口轮询、浏览器自动打开；支持 `-NoBrowser`） |
+| `PatchWarden-Control.cmd` | 根目录 CMD 入口，调用上述 PowerShell 脚本 |
+| `ui/pages/dashboard.html` | 总控首页（真实状态，7 个工具栏按钮，两张服务卡） |
+| `ui/pages/tasks.html` | 任务列表页（接 `/api/tasks`） |
+| `ui/pages/task-detail.html` | 任务详情页（接 `/api/tasks/:taskId`） |
+| `ui/pages/workspace.html` | 工作区页（接轻量 `/api/workspace`） |
+| `ui/pages/audit.html` | 审计历史页（接 `/api/audit`） |
+| `ui/partials/project-shell.html` | 页面外壳（CDN 引用已替换为本地 `/vendor/`） |
+| `ui/colors_and_type.css` | 颜色与字体样式 |
+| `ui/vendor/tailwindcss-browser.js` | Tailwind v4.3.1 browser build（本地副本，离线可用） |
+| `ui/vendor/lucide.js` | Lucide v1.8.0 UMD（本地副本，离线可用） |
+| `docs/control-center/control-center-mvp.md` | 本文档 |
+
+## 改动文件
+
+| 文件 | 改动 |
+| --- | --- |
+| `package.json` | 新增 `start:control` 脚本（`node dist/controlCenter.js`）；`files` 数组新增 `ui/`；`test` 脚本末尾追加 `&& node scripts/checks/control-center-smoke.js` |
+| `.gitignore` | 新增 `/CODE_WIKI.md`、`/PatchWarden-UI.zip`、`/patchwarden-v0.6.1-SHA256SUMS.txt`（避免 brand-check 误报） |
+
+## 启动方式
+
+### 方式一：CMD 入口（推荐用户使用）
+
+```powershell
+.\PatchWarden-Control.cmd
+```
+
+### 方式二：PowerShell 脚本
+
+```powershell
+# 正常启动（构建检查 + 打开浏览器）
+powershell -ExecutionPolicy Bypass -File scripts\control\start-control-center.ps1
+
+# 测试模式（不打开浏览器）
+powershell -ExecutionPolicy Bypass -File scripts\control\start-control-center.ps1 -NoBrowser
+```
+
+### 方式三：npm 脚本（需先 `npm run build`）
+
+```powershell
+npm.cmd run build
+npm.cmd run start:control
+```
+
+启动后自动打开 `http://127.0.0.1:8090`。
+
+端口可通过环境变量覆盖（仅用于测试）：
+
+```powershell
+$env:PATCHWARDEN_CONTROL_PORT=18090; node dist/controlCenter.js
+```
+
+## 控制 Token 校验
+
+- 服务启动时通过 `crypto.randomUUID()` 生成 token，**仅保存在内存中**，不写入任何文件。
+- 前端通过 `GET /control-token.json` 从内存获取 token，响应头 `Cache-Control: no-store`。
+- **所有 POST 接口**（含 `/api/start-all`、`/api/stop-all`、`/api/restart-all`、`/api/core/*`、`/api/direct/*`、`/api/open-logs-folder`）必须携带 `X-PatchWarden-Control-Token` 请求头。
+- token 缺失或错误时返回 `403`，不执行任何进程控制或本地系统动作。
+- GET 接口（status、tasks、logs 等）不需要 token。
+- `git status --porcelain` 不会出现 `ui/control-token.json`。
+
+## API 清单
+
+### GET 接口（免 token）
+
+| 路径 | 说明 |
+| --- | --- |
+| `GET /` | 返回 `ui/pages/dashboard.html` |
+| `GET /control-token.json` | 从内存返回控制 token，`Cache-Control: no-store` |
+| `GET /colors_and_type.css` | 静态 CSS |
+| `GET /pages/*` | 静态 HTML 页面 |
+| `GET /partials/*` | 静态 HTML 片段 |
+| `GET /vendor/*` | 本地化的 Tailwind / Lucide |
+| `GET /api/status` | 聚合状态（容错，永不 500） |
+| `GET /api/tasks` | 任务列表（复用 `listTasks`） |
+| `GET /api/tasks/:taskId` | 任务详情（status/runtime/result/audit/diff_patch/test_log） |
+| `GET /api/logs/core` | Core runtime 日志尾部 100 行（脱敏） |
+| `GET /api/logs/direct` | Direct runtime 日志尾部 100 行（脱敏） |
+| `GET /api/logs/watcher` | Watcher 日志尾部 100 行（脱敏） |
+| `GET /api/workspace` | 轻量工作区信息（workspace_root、directories、agents、config 摘要；**不做 git 扫描**） |
+| `GET /api/audit` | 审计历史（扫描 tasks 目录下含 audit.json 的任务，最多 50 条） |
+| `GET /api/tunnel-ui-url` | 读取 Core/Direct 的 tunnel-health-url.txt |
+
+### POST 接口（必须校验 token）
+
+| 路径 | 委托命令 | 说明 |
+| --- | --- | --- |
+| `POST /api/start-all` | `manage-patchwarden.ps1 start all` | 启动全部 |
+| `POST /api/stop-all` | `manage-patchwarden.ps1 stop all` | 停止全部 |
+| `POST /api/restart-all` | `manage-patchwarden.ps1 restart all` | 重启全部 |
+| `POST /api/core/start` | `manage-patchwarden.ps1 start core` | 启动 Core |
+| `POST /api/core/stop` | `manage-patchwarden.ps1 stop core` | 停止 Core |
+| `POST /api/direct/start` | `manage-patchwarden.ps1 start direct` | 启动 Direct |
+| `POST /api/direct/stop` | `manage-patchwarden.ps1 stop direct` | 停止 Direct |
+| `POST /api/open-logs-folder` | 系统命令打开 runtime 目录 | 打开日志文件夹 |
+
+### `/api/status` 返回结构（容错）
+
+```json
+{
+  "core": { "available": false, "reason": "...", "healthz": null, "readyz": null },
+  "direct": { "available": false, "reason": "...", "healthz": null, "readyz": null },
+  "watcher": { "status": "missing|healthy|stale|unreadable", "available": false, "reason": "..." },
+  "tunnel": { "core": { "observed": false }, "direct": { "observed": false } },
+  "tools": {
+    "core": { "tool_profile": null, "tool_count": null, "schema_epoch": null, "tool_manifest_sha256": null, "tool_names": null },
+    "direct": { "tool_profile": null, "tool_count": null, "schema_epoch": null, "tool_manifest_sha256": null, "tool_names": null }
+  },
+  "agents": [],
+  "workspace_root": "string | null",
+  "tasks": { "tasks": [], "total": 0, "active": 0, "stale": 0, "reason": null }
+}
+```
+
+容错保证：
+- core/direct health 探测失败 → `{ available: false, reason: "..." }`，接口仍 200
+- runtime 文件（tunnel-status.json、tool-manifest.json）缺失 → 返回 null 或 `{ observed: false }`，接口仍 200
+- 日志文件缺失 → `{ stdout: "", stderr: "", reason: "..." }`，接口仍 200
+- tasks 目录缺失 → `{ tasks: [], total: 0, reason: "..." }`，接口仍 200
+- Core/Direct 未启动时 `/api/status` 仍返回 200 JSON，不报 500
+
+## 进程安全
+
+- Control Center **不直接 kill 进程**，所有 start/stop/restart 均委托 `scripts/control/manage-patchwarden.ps1`。
+- `manage-patchwarden.ps1` 的 `Test-TunnelProcessForMode` 在 stop/restart 前校验进程命令行属于 `tunnel-client.exe --profile` 模式，仅停止匹配的进程。
+- **不根据任意 PID 文件 kill 进程**。
+- Control Center 仅在自身服务关闭时退出自己启动的 HTTP server。
+
+## CDN 本地化
+
+- 所有 HTML 无 `https://cdn` 或 `https://unpkg` 引用。
+- `ui/vendor/tailwindcss-browser.js`（Tailwind v4.3.1）和 `ui/vendor/lucide.js`（Lucide v1.8.0）为本地副本。
+- 断网后页面样式和图标正常渲染。
+
+## 冒烟测试（测试模式）
+
+`scripts/checks/control-center-smoke.js` 严格遵循测试模式：
+
+- 不打开浏览器
+- 不真正 start/stop Core 或 Direct
+- 不 kill 任何进程（仅关闭自己 spawn 的 controlCenter 子进程）
+- 使用测试端口 `18090`（通过 `PATCHWARDEN_CONTROL_PORT`），避免 8090 冲突
+- 测试结束关闭 server，释放端口
+
+测试覆盖（10 项）：
+
+1. 静态文件服务（`/`、`/vendor/*`、`/colors_and_type.css` 返回 200 + 正确 Content-Type）
+2. `/api/status` 返回有效 JSON 且容错（core/direct 未启动时仍 200）
+3. `/api/tasks` 返回有效 JSON
+4. `/control-token.json` 返回 token + `Cache-Control: no-store`
+5. POST `/api/start-all` 不带 token → 403
+6. POST `/api/start-all` 带错误 token → 403
+7. POST `/api/open-logs-folder` 不带 token → 403
+8. token 不污染 Git（`git status --porcelain` 不含 `ui/control-token.json`）
+9. 无 CDN 引用（HTML 文件无 `https://cdn` / `https://unpkg`）
+10. 其他 GET API 可达（`/api/workspace`、`/api/audit`、`/api/logs/core`、`/api/tunnel-ui-url`）
+
+## 测试结果
+
+`npm test` 全量通过（`FINAL_EXIT_CODE: 0`）：
+
+| 测试链 | 结果 |
+| --- | --- |
+| smoke-test | OK |
+| unit-tests | 139 total（136 pass，0 fail，1 skipped） |
+| lifecycle-smoke | 22 passed, 0 failed |
+| doctor-smoke | OK |
+| tunnel-supervisor-smoke | OK |
+| watcher-supervisor-smoke | OK |
+| control-smoke | OK |
+| mcp-manifest-check | 17 tools, chatgpt_core profile |
+| brand-check | OK: 144 tracked files checked |
+| control-center-smoke | 10 passed, 0 failed |
+
+未发布 npm、未打 git tag、未上传 npm。
+
+## 已知限制
+
+1. **`/api/workspace` 轻量版**：第一版只返回 workspace_root、项目列表（一级子目录）、agents、config 摘要。不做 git 扫描，不返回 repo clean 状态。workspace.html 中 "Repo Clean 状态" 显示为"按需接口待实现"占位。
+2. **task-detail / workspace / audit 为基础接入**：能加载数据并渲染，但未实现全部高级功能（如 diff 高亮、审计证据深度展示）。diff/test-log 仅做文本预览。
+3. **进程控制仅支持 Windows**：`manage-patchwarden.ps1` 为 PowerShell 脚本，POST 控制接口在非 Windows 环境下不可用。`/api/open-logs-folder` 在 macOS/Linux 下会尝试 `open`/`xdg-open`。
+4. **Health 探测端口固定**：Core 探测 `127.0.0.1:8080`，Direct 探测 `127.0.0.1:8081`，暂不支持配置覆盖。
+5. **Control token 生命周期**：token 在服务进程内存中，服务重启后 token 会变化（前端通过 `/control-token.json` 重新获取）。
+6. **日志读取**：仅返回各日志文件尾部 100 行，并对敏感内容脱敏（复用 `redactSensitiveContent`）。

package/docs/control-center/control-center-phase2.md

@@ -0,0 +1,159 @@
+# PatchWarden Control Center Phase 2
+
+> v0.6.3 在 v0.6.2 MVP 基础上增强任务、工作区、Direct session 和日志体验。
+> 不重构架构，不合并 Core/Direct MCP，不改现有 MCP 工具注册逻辑。
+> 不发布 npm，不打 git tag。
+
+## 概述
+
+Phase 2 完全在 Control Center HTTP 层增强，未触动 MCP 工具注册、watcher 核心循环或
+Direct session 写入逻辑。新增的 API 全部沿用既有 token 校验、路径围栏和脱敏机制。
+
+- **Stale Task 管理**：4 条规则识别僵死任务，reconcile 只标注不删除
+- **task-detail 增强**：变更文件、验证摘要、警告/错误、stale 横幅 + 4 个动作按钮
+- **工作区按需 git 状态**：仅在用户点击时对单个 repo 执行 `git status --short`
+- **Direct Sessions 页面**：浏览 `.patchwarden/direct-sessions` 下的会话产物
+- **Logs 页面**：core/direct/watcher/control-center 四类日志，支持 tail 100/300/1000
+
+## 启动方式
+
+启动方式与 MVP 完全一致，无新增入口：
+
+```powershell
+.\PatchWarden-Control.cmd
+# 或
+npm.cmd run build
+npm.cmd run start:control
+```
+
+启动后访问 `http://127.0.0.1:8090`，左侧导航新增「Direct 会话」和「日志」两项。
+
+## 改动文件
+
+| 文件 | 改动 |
+| --- | --- |
+| `src/version.ts` | `PATCHWARDEN_VERSION` 0.6.2 → 0.6.3 |
+| `package.json` | `version` 0.6.2 → 0.6.3 |
+| `src/controlCenter.ts` | 新增 stale/reconcile/task-detail 增强/workspace repo status/direct sessions/logs 分类等 API |
+| `ui/pages/dashboard.html` | 侧边栏新增 Direct 会话 + 日志导航 |
+| `ui/pages/tasks.html` | 侧边栏新增 Direct 会话 + 日志导航 |
+| `ui/pages/task-detail.html` | 新增变更文件卡、验证摘要卡、警告/错误卡、stale 横幅、Refresh/Copy task_id/Open folder/Run audit/Reconcile 按钮 |
+| `ui/pages/workspace.html` | 每个 repo 新增「检查」按钮，按需调用 `/api/workspace/:repo/status`，渲染 git 状态面板 |
+| `ui/pages/audit.html` | 侧边栏新增 Direct 会话 + 日志导航 |
+| `ui/pages/direct-sessions.html` | 新页面：会话列表 + 会话详情（summary.md / audit.md / audit.json / diff.patch / changed-files.json） |
+| `ui/pages/logs.html` | 新页面：分类选择 + tail 选择 + 自动刷新开关 |
+| `scripts/checks/control-center-smoke.js` | 新增 Test 11–15 覆盖 Phase 2 API |
+| `docs/control-center/control-center-phase2.md` | 本文档 |
+
+## 新增 API
+
+### GET 接口（免 token）
+
+| 路径 | 说明 |
+| --- | --- |
+| `GET /api/tasks/stale` | 返回当前判定为 stale 的任务列表（含 stale_reasons） |
+| `GET /api/tasks/:taskId` | 增强详情：新增 `changed_files`、`file_stats`、`verification_summary`、`warnings`、`errors`、`stale`、`reconcile`、`task_dir`、`independent_review`、`verify_log` |
+| `GET /api/workspace/:repo/status` | 对单个 repo 执行 `git status --short`，返回 changed_files_count/untracked_count/modified_count/is_clean/short_status |
+| `GET /api/direct-sessions` | 列出 `.patchwarden/direct-sessions` 下所有会话摘要 |
+| `GET /api/direct-sessions/:sessionId` | 返回会话详情：summary/session/summary_md/diff_patch/audit_json/audit_md/changed_files |
+| `GET /api/logs/:category?tail=<100\|300\|1000>` | 四类日志（core/direct/watcher/control-center），支持 tail 行数 |
+
+### POST 接口（必须校验 token）
+
+| 路径 | 说明 |
+| --- | --- |
+| `POST /api/tasks/:taskId/reconcile` | 标注 stale/archived，写入 `reconcile.json`，不删除任务 |
+| `POST /api/tasks/:taskId/audit` | 仅当任务处于终态时委托 `auditTask` 运行独立审计 |
+| `POST /api/tasks/:taskId/open-folder` | 通过系统命令打开任务目录 |
+
+## Stale Task 判定规则
+
+`classifyStaleTask` 仅对 `pending` / `running` 状态任务判定（终态任务直接返回非 stale）。
+判定使用 `config.watcherStaleSeconds` 作为阈值，4 条规则任一命中即标记 stale：
+
+| 规则 | 字段值 | 说明 |
+| --- | --- | --- |
+| `heartbeat_stale` | status=running 且 last_heartbeat_at 超过阈值 | 运行中但心跳长时间未更新 |
+| `collecting_artifacts_stale` | phase=collecting_artifacts 且心跳超过阈值 | 卡在产物收集阶段 |
+| `running_no_command_watcher_healthy` | status=running 且 current_command 为空且 watcher healthy | 运行中无命令但 watcher 在工作，疑似僵死 |
+| `heartbeat_far_behind_watcher` | 任务心跳比 watcher 心跳早 2× 阈值以上且 watcher healthy | 任务明显落后于 watcher |
+
+`/api/status` 和 `/api/tasks` 返回的任务对象均带 `is_stale: boolean` 和
+`stale_reasons: string[]`。`/api/status.tasks` 还聚合了 `stale` 计数和
+`stale_task_ids` 列表。
+
+## Reconcile 行为
+
+`POST /api/tasks/:taskId/reconcile` 的安全契约：
+
+- **不删除任务**，不修改 `status` 枚举值
+- 读取 `status.json` / `runtime.json` 重建 `TaskEntry`，重新调用 `classifyStaleTask`
+- 决策（`decision` 字段）：
+  - `marked_archived`：任务已处于终态 → 标注归档
+  - `marked_stale`：stale 且 watcher 未在驱动（无 current_command 或 watcher 非 healthy）→ 标注僵死
+  - `no_action`：不满足上述条件 → 仅记录，不标注
+- 写入 `tasks/<taskId>/reconcile.json`（完整决策记录）
+- 仅当 `safe=true` 时，在 `status.json` 追加 `reconcile_state`（`"stale"` 或 `"archived"`）和 `reconciled_at`，**原 status 字段保持不变**
+- 返回 reconcile 记录 JSON
+
+## 路径围栏（workspace repo status）
+
+`GET /api/workspace/:repo/status` 的安全约束：
+
+- `repo` 参数经 `decodeURIComponent` 后若包含 `..` 或 `\0` → 直接 400
+- 通过 `guardWorkspacePath(repo, workspaceRoot)` 解析为绝对路径，任何逃逸 `workspaceRoot` 的路径 → 400
+- 仅对解析后的目录执行 `git status --short`，超时 8 秒，maxBuffer 1MB
+- 非 git 仓库或 git 不可用时返回 200 + `is_git_repo: false` + error 字段，不返回 500
+- smoke test 用 `encodeURIComponent("../secret")` 验证穿越被拒（400）
+
+## Direct Sessions 数据来源
+
+- 会话目录：`getDirectSessionsDir(config)` → `<runtime>/.patchwarden/direct-sessions/`
+- 每个会话子目录读取：`session.json`、`summary.json`、`audit.json`、`summary.md`、`diff.patch`、`audit.md`、`changed-files.json`
+- `DirectSessionSummary` 字段：`session_id`、`repo_path`、`resolved_repo_path`、`created_at`、`expires_at`、`finalized`、`finalized_at`、`audited`、`changed_files_total`、`verification_summary`、`audit_decision`、`audit_checked_at`、`title`
+- 目录不存在时返回 `{ sessions: [], total: 0, reason: null }`，**不返回 500**
+- 会话按 `created_at` 降序排列
+
+## 日志脱敏
+
+- 所有 `/api/logs/:category` 响应均经 `redactSensitiveContent` 脱敏
+- tail 行数限制在 `ALLOWED_LOG_TAILS = {100, 300, 1000}`，非法值回退到 100
+- 日志文件缺失时返回 `{ stdout: "", stderr: "", reason: "log file not found" }`
+
+## 冒烟测试
+
+`scripts/checks/control-center-smoke.js` 在原 10 项基础上新增 5 项（共 16 项）：
+
+| # | 测试 |
+| --- | --- |
+| 11 | `GET /api/tasks/stale` 返回有效 JSON（`stale_tasks` 数组、`total` 数字、`stale_threshold_seconds` 数字） |
+| 12 | `GET /api/workspace/<traversal>/status` 被拒绝（400，error 含 "traversal"） |
+| 13 | `POST /api/tasks/:taskId/reconcile` 无 token → 403 |
+| 14 | `GET /api/direct-sessions` 目录缺失时返回空列表（200，非 500） |
+| 15 | `GET /api/logs/core?tail=300` 响应包含 `tail: 300` |
+
+## 测试结果
+
+```
+npm.cmd run build         # tsc 编译通过
+node scripts/checks/control-center-smoke.js
+  # Summary: 16 passed, 0 failed
+```
+
+全量 `npm test` 链路（security 139 + unit 136 + lifecycle 22 + control-center 16）
+全部通过，0 失败。
+
+> 注：在 TRAE IDE 沙盒内运行 `npm test` 时，control-center-smoke spawn 的子进程退出
+> 后 Windows 会尝试更新 jump list 临时文件，被沙盒拒绝并打印
+> "TRAE Sandbox Error: hit restricted …CustomDestinations…"。该错误与测试逻辑无关，
+> 所有测试用例均报告 PASS。直接运行 `node scripts/checks/control-center-smoke.js` 退出码为 0。
+
+## 已知限制
+
+- `/api/workspace/:repo/status` 仅运行 `git status --short`，不返回 diff 或 stash 信息
+- reconcile 不会清理任务文件，需人工后续处理或由 watcher 在下个周期自然覆盖
+- `/api/tasks/:taskId/audit` 仅在任务处于终态（done/failed/failed_verification/
+  failed_scope_violation/failed_policy_violation/canceled/timeout）时才执行，否则返回 409
+- Direct Sessions 页面只读，不提供 finalize 或 audit 触发入口（这些操作仍需通过 MCP 工具完成）
+- Logs 页面的自动刷新间隔固定为 5 秒，不读取 watcher 实时事件
+- task-detail 的「Open task folder」按钮通过 `explorer.exe` / `open` / `xdg-open` 打开，需要本地图形环境

package/docs/demo.md

@@ -42,7 +42,10 @@ Expected artifacts under the configured workspace:
 ```text
 .patchwarden/tasks/<task_id>/status.json
 .patchwarden/tasks/<task_id>/result.md
+.patchwarden/tasks/<task_id>/result.json
+.patchwarden/tasks/<task_id>/artifact_manifest.json
 .patchwarden/tasks/<task_id>/git.diff
+.patchwarden/tasks/<task_id>/verify.json
 .patchwarden/tasks/<task_id>/test.log
 ```
 

package/docs/performance-notes.md

@@ -0,0 +1,55 @@
+# PatchWarden Performance Notes
+
+## Current State (v0.6.1)
+
+### Identified Optimization Opportunities
+
+The following performance optimizations have been identified for future implementation. They are documented here rather than implemented in v0.6.1 to avoid introducing risk to the core task execution path.
+
+### 1. Async Git Operations in changeCapture.ts
+
+**Current**: `runGit()` uses `spawnSync()` which blocks the event loop during git operations.
+
+**Proposed**: Replace with `execFile()` (async) and use `Promise.all()` for independent git queries in `captureRepoSnapshot()`.
+
+**Risk**: Medium — changes the core change capture path. Requires careful testing of all snapshot/diff/scope scenarios.
+
+**Expected Benefit**: ~200-500ms improvement per task for repos with many files, as multiple git queries can run concurrently.
+
+### 2. Streaming File Hash
+
+**Current**: `computeFileSha256()` reads the entire file into memory with `readFileSync()`.
+
+**Proposed**: Use `createReadStream()` + `crypto.createHash()` for streaming hash computation.
+
+**Risk**: Low — isolated to hash computation, no semantic change.
+
+**Expected Benefit**: Reduces peak memory usage for large files (e.g., release artifacts > 5MB).
+
+### 3. Workspace Snapshot Caching
+
+**Current**: `walkWorkspace()` traverses the entire workspace directory tree on every snapshot.
+
+**Proposed**: Cache the directory listing and invalidate on file modification events.
+
+**Risk**: High — requires file system watchers and cache invalidation logic. Could introduce stale data bugs.
+
+**Expected Benefit**: ~100-1000ms improvement for large workspaces with many repos.
+
+### 4. Parallel Task Status Reads
+
+**Current**: `listTasks()` reads each task's `status.json` sequentially.
+
+**Proposed**: Use `Promise.all()` to read multiple task status files concurrently.
+
+**Risk**: Low — read-only operation, no semantic change.
+
+**Expected Benefit**: ~50-200ms improvement when listing 10+ tasks.
+
+## Decision for v0.6.1
+
+All four optimizations are deferred to a future release. The current synchronous implementation is correct and well-tested. Changing the core paths would require extensive regression testing that is beyond the scope of this stability release.
+
+## Monitoring
+
+The structured logging module (`src/logging.ts`) added in v0.6.1 provides the infrastructure to measure tool call durations (`duration_ms` in audit logs). Once deployed, real-world timing data can be collected to prioritize which optimization to implement first.

package/docs/release-v0.6.1.md

@@ -0,0 +1,75 @@
+# PatchWarden v0.6.1 Release Notes
+
+**Release Date**: 2026-06-25
+
+## Overview
+
+PatchWarden v0.6.1 is a stability and observability release. It addresses watcher heartbeat false positives, adds Chinese path reliability, introduces two new tools (`safe_status` and `sync_file`), and adds comprehensive security guard unit tests.
+
+## New Features
+
+### safe_status Tool
+
+A minimal task lifecycle status tool that returns task state without exposing diff, log content, or file contents. Useful when upper-layer security policies block content-bearing tools.
+
+```json
+{
+  "task_id": "task-001",
+  "status": "running",
+  "phase": "executing_agent",
+  "last_heartbeat_at": "2026-06-24T10:00:12Z",
+  "current_command": "codex exec",
+  "watcher_state": "healthy"
+}
+```
+
+### sync_file Tool
+
+Copy a file from source to target within a Direct session repo. Both paths must be inside the session's `repo_path`. Supports optional sha256 verification for both source and target.
+
+### Android Build Doctor
+
+When a managed project contains an `android_app` directory, the health check now includes Android build environment diagnostics: Java version, JAVA_HOME, ANDROID_HOME, SDK platform, build-tools, Gradle wrapper, and APK output path.
+
+## Bug Fixes
+
+- **Watcher stale false positive**: Long-running tasks no longer cause the watcher to be incorrectly reported as stale. The watcher status now falls back to checking running task heartbeats.
+- **Chinese path encoding**: All file I/O operations verified to use UTF-8 encoding. Health check now reports `path_encoding` status.
+- **Tracked external dirty detection**: `captureRepoSnapshot` now correctly identifies tracked-but-modified external files via `dirty_paths` field parsed from `git status --porcelain`. The regex now includes `R` (rename) status, fixing dead code that previously never executed for renamed files.
+- **Release zip path separators**: The packaging script (`pack-clean.js`) now creates zip archives with POSIX `/` path separators instead of Windows backslashes. Linux `unzip` no longer reports `warning: appears to use backslashes as path separators`.
+
+## Security
+
+- 136 unit tests covering all security guards (path guard, sensitive guard, command guard, direct guards)
+- Tests use Node's built-in `node:test` — zero new dependencies
+
+## Observability
+
+- Structured JSON logging to stderr (never stdout, to avoid polluting MCP JSON-RPC)
+- Tool call audit logs with duration tracking
+- Global `unhandledRejection` and `uncaughtException` handlers
+
+## Tool Profile Changes
+
+| Profile | v0.6.0 | v0.6.1 |
+|---------|--------|--------|
+| full | 28 | 30 |
+| chatgpt_core | 16 | 17 |
+| chatgpt_direct | 9 | 10 |
+
+## Migration
+
+No breaking changes. All new fields are optional. New tools are additive and do not affect existing tools.
+
+## Verification
+
+- TypeScript compilation: PASS
+- Unit tests: 136 pass, 0 fail, 1 skipped (Windows symlink)
+- Smoke tests: 139 pass, 0 fail
+- Lifecycle tests: 22 pass, 0 fail (includes tracked external file rename regression test)
+- Doctor CI: PASS (81 OK, 0 WARN, 0 FAIL on the release check host)
+- Tool manifest check: PASS
+- Package manifest check: PASS (260 files)
+- Brand check: PASS (128 tracked files)
+- MCP HTTP tests: 13 pass, 0 fail
+- Release zip: POSIX path separators verified (261 entries, no backslashes)

package/docs/release-v0.6.4.md

@@ -0,0 +1,45 @@
+# PatchWarden v0.6.4 Release Notes
+
+**Release Date**: 2026-06-26
+
+## Overview
+
+PatchWarden v0.6.4 is a desktop experience release. It keeps the existing CLI and script surface, but makes the normal Windows workflow feel like a lightweight local application: start one desktop entry, control Core/Direct from the tray or Web dashboard, and shut everything down from one stop command.
+
+## Desktop Entry
+
+- Added `PatchWarden-Desktop.cmd` as the recommended daily entry point.
+- The desktop entry starts the tray in a hidden PowerShell host and ensures the local Control Center is available.
+- It does not automatically open a browser window. Use **Open Dashboard** from the tray or `PatchWarden-Control.cmd` when you want the full Web console.
+- `PatchWarden-Control-Tray.cmd --foreground` remains available for tray debugging.
+
+## Tray Improvements
+
+- Added single-instance protection for the tray process.
+- Replaced the generic system icon path with a small PatchWarden-styled shield icon drawn through WinForms/System.Drawing.
+- Kept the tray as a lightweight switch layer: Open Dashboard, Status, Start All, Stop All, Restart All, Open Logs, and Quit Tray.
+- Added clearer balloon/status feedback for startup and lifecycle actions.
+- Clarified action semantics: **Stop All** stops Core/Direct and leaves tray/dashboard available; **Quit Tray** exits only the tray; `Stop-PatchWarden.cmd` performs full shutdown.
+
+## Background Lifecycle
+
+- Control Center now invokes `manage-patchwarden.ps1` with `-Background` and `windowsHide: true` for lifecycle API calls.
+- The manager starts Core/Direct supervisors hidden for desktop/Web flows, while preserving visible launcher windows for explicit CLI/debug usage.
+- Added `-NoTunnelWebUi` to `start-patchwarden-tunnel.ps1` so background starts do not open tunnel-client Web UI tabs.
+
+## Verification
+
+- TypeScript build: PASS
+- Control smoke: PASS
+- Control Center smoke: PASS (23 passed, 0 failed)
+- Package manifest check: PASS
+- PowerShell control script parse check: PASS
+- Manual desktop-flow evidence: desktop entry starts only tray + Control Center; Start/Restart uses hidden supervisors; Stop-PatchWarden closes Core/Direct, Control Center, and tray.
+
+## Migration
+
+No breaking changes. Existing CLI commands and compatibility launchers remain available. For daily Windows use, prefer:
+
+```powershell
+.\PatchWarden-Desktop.cmd
+```

package/examples/openai-tunnel/README.md

@@ -15,7 +15,7 @@ or local private paths.
 
 1. Configure `patchwarden.config.json`.
 2. Run `npm.cmd run build`.
-3. Use `scripts/patchwarden-mcp-stdio.cmd` as the tunnel MCP command.
+3. Use `scripts/mcp/patchwarden-mcp-stdio.cmd` as the tunnel MCP command.
 4. Start `npm.cmd run watch` in a separate terminal.
 5. Start `tunnel-client run` or use `PatchWarden.cmd start core`.
 6. Create a ChatGPT Connector using the tunnel channel.
@@ -25,10 +25,10 @@ or local private paths.
 
 For ChatGPT Direct editing, set `enableDirectProfile: true` in the trusted
 local config and run `PatchWarden.cmd start direct`. It uses
-`scripts/patchwarden-mcp-direct.cmd`, the separate `patchwarden-direct` Tunnel
+`scripts/mcp/patchwarden-mcp-direct.cmd`, the separate `patchwarden-direct` Tunnel
 Client profile, no Watcher, and an isolated `runtime-direct` status directory.
-Use a separate Direct Connector/Tunnel ID so the fixed 16-tool Core catalog and
-the 9-tool Direct catalog never overwrite each other's cached schema.
+Use a separate Direct Connector/Tunnel ID so the fixed 17-tool Core catalog and
+the 10-tool Direct catalog never overwrite each other's cached schema.
 
 The Windows launcher prompts for the runtime API key once and stores only a
 Windows DPAPI-encrypted value under `%APPDATA%\patchwarden`. Use
@@ -38,7 +38,7 @@ Before the launcher starts the tunnel it performs a real MCP stdio handshake
 and requires the exact `chatgpt_core` manifest. Run
 `PatchWarden.cmd health` to see the version, profile, tool names, schema
 hash, process sources, and any mixed-version warnings. The check is read-only.
-The v0.4.1 core manifest contains 16 tools. A different count or schema hash
+The v0.6.1 core manifest contains 17 tools. A different count or schema hash
 requires a Connector refresh and validation from a new ChatGPT conversation.
 
 ## Architecture

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

@@ -12,7 +12,7 @@
 #   --sample sample_mcp_stdio_local \
 #   --profile patchwarden \
 #   --tunnel-id tunnel_xxx \
-#   --mcp-command "C:/path/to/patchwarden/scripts/patchwarden-mcp-stdio.cmd"
+#   --mcp-command "C:/path/to/patchwarden/scripts/mcp/patchwarden-mcp-stdio.cmd"
 
 # Direct mode uses a separate profile and command:
 #
@@ -20,12 +20,12 @@
 #   --sample sample_mcp_stdio_local \
 #   --profile patchwarden-direct \
 #   --tunnel-id tunnel_xxx \
-#   --mcp-command "C:/path/to/patchwarden/scripts/patchwarden-mcp-direct.cmd"
+#   --mcp-command "C:/path/to/patchwarden/scripts/mcp/patchwarden-mcp-direct.cmd"
 
 mcp:
   commands:
     - channel: main
-      command: "C:/path/to/patchwarden/scripts/patchwarden-mcp-stdio.cmd"
+      command: "C:/path/to/patchwarden/scripts/mcp/patchwarden-mcp-stdio.cmd"
 
 # Mode B: HTTP
 #