patchwarden 0.6.1 → 1.1.0

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/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
 #

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "patchwarden",
-  "version": "0.6.1",
-  "description": "A secure local MCP bridge: clients save plans, local agents execute tasks, and results are returned through workspace-scoped files.",
+  "version": "1.1.0",
+  "description": "Secure local MCP bridge for ChatGPT and local agents, with workspace-scoped tasks, safe summaries, audits, and Direct editing.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,9 +17,16 @@
     "src/",
     "examples/",
     "scripts/",
-    "!scripts/kill-patchwarden.ps1",
+    "!scripts/control/kill-patchwarden.ps1",
     "!scripts/launchers/Kill-PatchWarden.cmd",
+    "!.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",
@@ -29,25 +36,27 @@
     "build": "node ./node_modules/typescript/bin/tsc",
     "start": "node dist/index.js",
     "start:http": "node dist/httpServer.js",
+    "start:control": "node dist/controlCenter.js",
     "dev": "npm run build && node dist/index.js",
     "runner": "node dist/runner/cli.js",
     "watch": "node dist/runner/watch.js",
     "doctor": "node dist/doctor.js",
     "doctor:ci": "node dist/doctor.js --allow-default-config",
-    "test:unit": "node scripts/unit-tests.js",
-    "test": "node dist/smoke-test.js && node scripts/unit-tests.js && node scripts/lifecycle-smoke.js && node scripts/doctor-smoke.js && node scripts/tunnel-supervisor-smoke.js && node scripts/watcher-supervisor-smoke.js && node scripts/control-smoke.js && node scripts/mcp-manifest-check.js && node scripts/brand-check.js",
-    "test:lifecycle": "npm run build && node scripts/lifecycle-smoke.js",
-    "test:doctor": "npm run build && node scripts/doctor-smoke.js",
-    "test:tunnel-supervisor": "npm run build && node scripts/tunnel-supervisor-smoke.js",
-    "test:watcher-supervisor": "npm run build && node scripts/watcher-supervisor-smoke.js",
-    "check:tool-manifest": "npm run build && node scripts/mcp-manifest-check.js",
-    "check:direct-tool-manifest": "npm run build && node scripts/mcp-manifest-check.js --profile chatgpt_direct",
-    "check:brand": "node scripts/brand-check.js",
-    "test:mcp": "npm run build && node scripts/mcp-smoke.js",
-    "test:http-mcp": "npm run build && node scripts/http-mcp-smoke.js",
+    "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: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",
+    "test:watcher-supervisor": "npm run build && node scripts/checks/watcher-supervisor-smoke.js",
+    "check:tool-manifest": "npm run build && node scripts/checks/mcp-manifest-check.js",
+    "check:direct-tool-manifest": "npm run build && node scripts/checks/mcp-manifest-check.js --profile chatgpt_direct",
+    "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:http-mcp": "npm run build && node scripts/checks/http-mcp-smoke.js",
     "pretest": "npm run build",
-    "pack:clean": "npm run build && node scripts/pack-clean.js",
-    "verify:package": "npm run build && node scripts/package-manifest-check.js"
+    "pack:clean": "npm run build && node scripts/release/pack-clean.js",
+    "verify:package": "npm run build && node scripts/checks/package-manifest-check.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0"

package/scripts/README.md

@@ -0,0 +1,47 @@
+# PatchWarden Scripts
+
+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
+.\PatchWarden.cmd status all
+```
+
+## Control Scripts
+
+- `control/manage-patchwarden.ps1`: backing implementation for `PatchWarden.cmd`.
+- `control/start-control-center.ps1`: starts the local Web dashboard.
+- `control/restart-control-center.ps1`: restarts the local Web dashboard.
+- `control/control-center-tray.ps1`: Windows tray quick controls.
+- `control/stop-patchwarden.ps1`: one-click shutdown for Core/Direct,
+  Control Center, and tray.
+- `control/start-patchwarden-tunnel.ps1`: starts Core or Direct tunnel supervision.
+- `control/restart-patchwarden.ps1`: compatibility restart helper.
+
+## MCP Entrypoints
+
+- `mcp/patchwarden-mcp-stdio.cmd`: Core stdio MCP launcher.
+- `mcp/patchwarden-mcp-direct.cmd`: Direct stdio MCP launcher.
+
+## Smoke Tests And Checks
+
+- `checks/*-smoke.js`: targeted smoke tests.
+- `checks/unit-tests.js`: Node unit test entry.
+- `checks/mcp-manifest-check.js`: validates MCP manifest expectations.
+- `brand-check.js`: checks public brand strings.
+- `checks/package-manifest-check.js`: verifies package contents.
+
+## Release Helpers
+
+- `release/pack-clean.js`: rebuilds `release/`, `patchwarden-release.tar.gz`, and the
+  versioned `PatchWarden-v*.zip` artifact.
+
+## Compatibility Launchers
+
+Compatibility `.cmd` files live under `scripts/launchers/`. User-private local
+launchers belong under `.local/` and must stay out of Git and release packages.
+

package/scripts/{brand-check.js → checks/brand-check.js}

@@ -12,8 +12,8 @@ const allowedLegacyFiles = new Set([
   "docs/release-v0.3.0.md",
   "docs/release-v0.4.0.md",
   "docs/release-v0.6.0.md",
-  "scripts/brand-check.js",
-  "scripts/pack-clean.js",
+  "scripts/checks/brand-check.js",
+  "scripts/release/pack-clean.js",
 ]);
 const legacyPattern = /safe-bifrost|Safe-Bifrost|SAFE_BIFROST|SafeBifrost|safe_bifrost/;