patchwarden 0.6.1 → 0.6.4

package/dist/doctor.js

@@ -210,7 +210,7 @@ async function main() {
     check("Read-only task artifact allowlist", requiredReadOnlyFiles.every((name) => TASK_READ_ONLY_FILES.includes(name)), requiredReadOnlyFiles.join(", "));
     const packageJson = JSON.parse(readFileSync(resolve(process.cwd(), "package.json"), "utf-8"));
     check("Server version matches package.json", packageJson.version === PATCHWARDEN_VERSION, `${PATCHWARDEN_VERSION} vs ${packageJson.version}`);
-    check("Manifest preflight script exists", existsSync(resolve(process.cwd(), "scripts/mcp-manifest-check.js")), "scripts/mcp-manifest-check.js");
+    check("Manifest preflight script exists", existsSync(resolve(process.cwd(), "scripts/checks/mcp-manifest-check.js")), "scripts/checks/mcp-manifest-check.js");
     const previousProfile = process.env.PATCHWARDEN_TOOL_PROFILE;
     try {
         process.env.PATCHWARDEN_TOOL_PROFILE = "full";
@@ -403,9 +403,9 @@ async function main() {
         "examples/openai-tunnel/README.md",
         "examples/openai-tunnel/tunnel-client.example.yaml",
         "examples/openai-tunnel/chatgpt-test-prompt.md",
-        "scripts/patchwarden-mcp-direct.cmd",
+        "scripts/mcp/patchwarden-mcp-direct.cmd",
         "PatchWarden.cmd",
-        "scripts/manage-patchwarden.ps1",
+        "scripts/control/manage-patchwarden.ps1",
         "scripts/launchers/Start-PatchWarden-Direct-Tunnel.cmd",
     ];
     for (const tf of tunnelFiles) {

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const PATCHWARDEN_VERSION = "0.6.1";
+export declare const PATCHWARDEN_VERSION = "0.6.4";
 export declare const TOOL_SCHEMA_EPOCH = "2026-06-24-v7";

package/dist/version.js

@@ -1,2 +1,2 @@
-export const PATCHWARDEN_VERSION = "0.6.1";
+export const PATCHWARDEN_VERSION = "0.6.4";
 export const TOOL_SCHEMA_EPOCH = "2026-06-24-v7";

package/docs/control-center/README.md

@@ -0,0 +1,33 @@
+# PatchWarden Control Center
+
+PatchWarden has three control layers:
+
+1. Web dashboard: the daily management surface for status, setup checks, tasks,
+   stale-task actions, Direct sessions, audit logs, and long logs.
+2. Tray entry: a lightweight quick-control surface for opening the dashboard,
+   checking compact status, Start/Stop/Restart, opening logs, and quitting the
+   tray.
+3. CLI/scripts: the lower-level fallback for automation, smoke tests, package
+   checks, and troubleshooting.
+
+## User Entrypoints
+
+From the repository root:
+
+```powershell
+.\PatchWarden-Desktop.cmd
+.\PatchWarden-Control.cmd
+.\PatchWarden-Control-Tray.cmd --foreground
+.\PatchWarden.cmd status all
+```
+
+Use `PatchWarden-Control.cmd` for normal desktop use. Use the tray when you only
+need quick controls. Use `PatchWarden.cmd` when you need explicit CLI output or
+automation-friendly commands.
+
+## Design Notes
+
+- `control-center-mvp.md`: first Web dashboard scope.
+- `control-center-phase2.md`: follow-up management and diagnostics scope.
+- `control-center-daily-driver.md`: current daily-use contract.
+

package/docs/control-center/control-center-daily-driver.md

@@ -0,0 +1,211 @@
+# PatchWarden Control Center Daily Driver
+
+> v0.6.4 在 v0.6.2 MVP 与 v0.6.3 Phase 2 基础上，把 Control Center 从「启动页面脚本」
+> 升级为日常入口：单实例启动、后台运行、托盘入口、健康修复建议、页面通知和活动时间线。
+> 不重构架构，不合并 Core/Direct MCP，不改现有 MCP 工具注册逻辑。
+> 不发布 npm，不打 git tag。
+
+## 概述
+
+Daily Driver 完全在 Control Center HTTP 层与启动脚本层增强，未触动 MCP 工具注册、
+watcher 核心循环或 Direct session 写入逻辑。新增的 API 沿用既有 token 校验、路径围栏
+和脱敏机制；托盘与后台模式仅调用现有 Control Center API，不引入新的进程管理路径。
+
+- **单实例启动**：status 文件 + 端口探测，重复运行只开浏览器，不启第二个服务
+- **后台运行**：`-Background`（默认）/ `-Foreground` / `-NoBrowser`，日志写入
+  `%LOCALAPPDATA%\patchwarden\control-center\control-center.{stdout,stderr}.log`
+- **托盘入口**：基于 .NET NotifyIcon 的轻量 PowerShell 托盘，无需 Electron
+- **健康修复建议**：`/api/status` 新增 `suggestions` 字段，dashboard 显示建议卡片
+- **页面通知**：dashboard 轮询状态变化时弹出 toast，同一事件只提示一次
+- **Activity Timeline**：`runtime/control-center-events.jsonl` 记录关键事件，
+  `GET /api/events` 返回最近事件，dashboard 显示时间线区块
+
+## 启动方式
+
+### 1. 日常入口（推荐）
+
+```powershell
+.\PatchWarden-Control.cmd
+```
+
+默认后台启动 Control Center 并打开浏览器。再次运行时：
+
+- 如果 127.0.0.1:8090 已经是当前 Control Center —— 直接打开浏览器页面，不重复启动
+- 如果端口被其他程序占用 —— 给出明确错误提示并退出
+- 如果 status 文件指向已死的 PID —— 清理孤儿进程后启动新实例
+
+### 2. 启动参数
+
+```powershell
+.\PatchWarden-Control.cmd -NoBrowser       # 启动但不打开浏览器
+.\PatchWarden-Control.cmd -Foreground      # 前台运行，日志直接输出到控制台
+.\PatchWarden-Control.cmd -Background      # 后台运行（默认），脚本启动后即退出
+```
+
+`-Foreground` 与 `-Background` 互斥；都不传时默认 `-Background`。
+
+### 3. 托盘入口
+
+```powershell
+.\PatchWarden-Control-Tray.cmd
+```
+
+启动 Windows 系统托盘图标（基于 .NET NotifyIcon，无需额外依赖）。如果 Control Center
+未运行，托盘脚本会先在后台启动它。托盘菜单：
+
+| 菜单项 | 行为 |
+| --- | --- |
+| Open Control Center | 在默认浏览器打开 dashboard |
+| Start All | `POST /api/start-all`（带 token） |
+| Stop All | `POST /api/stop-all`（带 token） |
+| Restart All | `POST /api/restart-all`（带 token） |
+| Open Workspace | 通过 `GET /api/workspace` 获取 workspaceRoot 后用 explorer 打开 |
+| Open Logs Folder | `POST /api/open-logs-folder`（带 token） |
+| Exit | 关闭托盘（不停止 Control Center 后台进程） |
+
+双击托盘图标打开 dashboard。所有 API 调用通过 `/control-token.json` 获取 token 后
+带 `X-PatchWarden-Control-Token` 头发起请求。
+
+## 改动文件
+
+| 文件 | 改动 |
+| --- | --- |
+| `src/version.ts` | `PATCHWARDEN_VERSION` 0.6.3 → 0.6.4 |
+| `package.json` | `version` 0.6.3 → 0.6.4 |
+| `src/controlCenter.ts` | 新增 status 文件、events JSONL、suggestions 引擎、`/api/events`、`/api/control-center-status`；`getControlCenterLogDir` 支持 `PATCHWARDEN_CONTROL_LOG_DIR` 覆盖 |
+| `scripts/control/start-control-center.ps1` | 重写：单实例检测、`-NoBrowser`/`-Foreground`/`-Background`、孤儿清理、端口冲突检测 |
+| `scripts/control/control-center-tray.ps1` | 新文件：.NET NotifyIcon 托盘，菜单驱动 Control Center API |
+| `PatchWarden-Control-Tray.cmd` | 新文件：托盘启动入口 |
+| `ui/pages/dashboard.html` | 新增 Health Suggestions 卡片、toast 通知、Activity Timeline 区块 |
+| `scripts/checks/control-center-smoke.js` | 新增 Test 16–20 覆盖 Daily Driver API；`PATCHWARDEN_CONTROL_LOG_DIR` 重定向到项目内临时目录 |
+| `scripts/release/pack-clean.js` | forbidden 列表新增 `.tmp/` |
+| `.gitignore` | 新增 `.tmp/` |
+| `docs/control-center/control-center-daily-driver.md` | 本文档 |
+
+## 新增 API
+
+### GET 接口（免 token）
+
+| 路径 | 说明 |
+| --- | --- |
+| `GET /api/events?limit=<N>` | 返回最近 N 条活动事件（最大 1000），结构 `{events, total, limit}` |
+| `GET /api/control-center-status` | 读取 status 文件，返回 `{running, pid, port, started_at, url, version}` 或 `{running: false}` |
+
+### /api/status 增强字段
+
+`GET /api/status` 响应新增 `suggestions` 数组，每条建议包含：
+
+```json
+{
+  "code": "core_stopped",
+  "severity": "warning",
+  "message": "Core 未运行，建议启动 Core profile",
+  "action": "/api/core/start",
+  "link": null
+}
+```
+
+| code | severity | 触发条件 | action |
+| --- | --- | --- | --- |
+| `core_stopped` | warning | Core 探测不可用 | `/api/core/start` |
+| `direct_stopped` | warning | Direct 探测不可用 | `/api/direct/start` |
+| `watcher_stale` | error | watcher 状态为 stale/unreadable | `/api/restart-all` |
+| `stale_task` | warning | 存在 stale 任务 | 无 action，`link` 指向 tasks 页面 |
+| `tunnel_not_ready` | warning | Core 或 Direct tunnel 未就绪 | `/api/restart-all` |
+| `agent_missing` | info | 配置的 agent 不可用 | 无 action，提示检查路径 |
+
+## 活动事件
+
+事件写入 `%LOCALAPPDATA%\patchwarden\control-center\control-center-events.jsonl`，
+每行一个 JSON 对象 `{timestamp, type, payload?}`。文件超过 512KB 时惰性裁剪到
+2000 行。
+
+### 事件类型
+
+| type | 触发时机 |
+| --- | --- |
+| `control_center.started` | 服务 listen 成功 |
+| `control_center.stopped` | 服务收到 SIGTERM/SIGINT 关闭 |
+| `manage.start.all` / `manage.stop.all` / `manage.restart.all` | 用户请求 start/stop/restart all |
+| `manage.<mode>.<action>.failed` | manage-patchwarden.ps1 执行失败 |
+| `core.status_changed` | Core 可用性发生变化（diff 自上次 /api/status 轮询） |
+| `direct.status_changed` | Direct 可用性发生变化 |
+| `watcher.status_changed` | watcher 状态发生变化 |
+| `task.status_changed` | 任务状态从 running → done/failed 等 |
+| `task.reconciled` | 用户对 stale 任务执行 reconcile |
+| `task.audited` | 用户对任务执行 audit |
+
+> Control Center 是无状态、拉取驱动的服务。`core/direct/watcher/task.status_changed`
+> 事件在 `/api/status` 轮询时通过 digest diff 检测，因此事件时间戳反映的是「被观察到」
+> 的时间，不保证是状态变化的精确时刻。
+
+## 页面通知（toast）
+
+dashboard.html 轮询 `/api/status`（30s）和 `/api/audit`（90s）时检测以下状态变化并
+弹出 toast 通知：
+
+- core/direct: available → unavailable（error）/ unavailable → available（success）
+- watcher: healthy → stale/unreadable（error）/ stale → healthy（success）
+- task: running → done（success）/ running → failed*（error）
+- audit: 新出现的 pass（success）/ warn（warning）/ fail（error）
+
+同一事件通过 dedup key 只提示一次；toast 8 秒后自动消失，也可手动关闭。首次加载时
+audit 列表会 seed 到 `seenAuditKeys`，不会对已有审计记录弹通知。
+
+## 运行时文件
+
+| 文件 | 路径 | 说明 |
+| --- | --- | --- |
+| status 文件 | `%LOCALAPPDATA%\patchwarden\control-center\control-center-status.json` | pid/port/started_at/url/version，服务启动时写入，关闭时删除 |
+| events 文件 | `%LOCALAPPDATA%\patchwarden\control-center\control-center-events.jsonl` | 活动事件 JSONL |
+| stdout 日志 | `%LOCALAPPDATA%\patchwarden\control-center\control-center.stdout.log` | 后台模式 stdout |
+| stderr 日志 | `%LOCALAPPDATA%\patchwarden\control-center\control-center.stderr.log` | 后台模式 stderr |
+
+> `PATCHWARDEN_CONTROL_LOG_DIR` 环境变量可覆盖上述目录（必须为绝对路径），
+> 主要用于 smoke test 将其重定向到项目内临时目录。
+
+## 测试
+
+```powershell
+npm.cmd test
+```
+
+### control-center-smoke.js（21 项）
+
+| # | 测试 | 覆盖 |
+| --- | --- | --- |
+| 1–1b | 静态文件 + 页面路由 | 基础服务 |
+| 2 | `/api/status` JSON + 容错 | 结构校验 |
+| 3–4 | tasks JSON + control-token | token 机制 |
+| 5–7 | POST 无 token / 错 token → 403 | 安全门 |
+| 8–9 | token 不污染 git + 无 CDN | 发布卫生 |
+| 10 | 其他 GET API 可达 | workspace/audit/logs/tunnel |
+| 11–15 | Phase 2 API | stale/reconcile/workspace/direct-sessions/logs |
+| **16** | `/api/status` 包含 `suggestions` 数组 | Daily Driver |
+| **17** | `/api/events` 返回 JSON | Daily Driver |
+| **18** | `/api/logs/control-center` 返回 JSON | Daily Driver |
+| **19** | POST `/api/restart-all` 无 token → 403 | Daily Driver |
+| **20** | `/api/control-center-status` 报告 running 实例 | Daily Driver（单实例检测） |
+
+### 全量测试结果
+
+```
+security tests:    139 passed, 0 failed
+unit tests:        136 passed, 0 failed (1 skipped: Windows symlink)
+lifecycle tests:    22 passed, 0 failed
+control-center:     21 passed, 0 failed
+```
+
+## 已知限制
+
+1. **托盘为 PowerShell 实现**：基于 .NET NotifyIcon，不提供跨平台支持；在非 Windows
+   环境下不可用。如需跨平台托盘，需引入 Electron 或类似框架（本阶段刻意避免）。
+2. **事件时间为观测时间**：Control Center 无状态，`status_changed` 事件在轮询时通过
+   diff 检测，时间戳是「被观察到」的时间，不保证是状态变化的精确时刻。
+3. **status 文件依赖可写目录**：如果 `%LOCALAPPDATA%` 不可写（如沙箱环境），
+   status 文件不会生成，单实例检测会退化为端口探测模式。可通过
+   `PATCHWARDEN_CONTROL_LOG_DIR` 覆盖到可写目录。
+4. **toast 为页面内通知**：不要求系统级通知；仅当 dashboard 页面打开时才会弹出。
+5. **托盘 Exit 不停止后台进程**：Exit 仅关闭托盘，Control Center 后台 node 进程继续
+   运行。需通过 Stop All 或 `Stop-Process -Id <pid>` 停止。
+6. **事件文件不轮转**：超过 512KB 时惰性裁剪到 2000 行，不按日期轮转。

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
 ```