patchwarden 1.5.0 → 1.5.1

package/README.en.md

@@ -8,7 +8,7 @@
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-339933.svg)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-Current source version: **v1.5.0**. See the
+Current source version: **v1.5.1**. See the
 [CHANGELOG](CHANGELOG.md), [migration guide](docs/migration-from-safe-bifrost.md), and
 [release checklist](docs/release-checklist.md). Verify GitHub Release / npm publication separately before release.
 
@@ -46,6 +46,7 @@ independent verification evidence.
 - [HTTP MCP mode](#http-mcp-mode)
 - [Diagnostics and health checks](#diagnostics-and-health-checks)
 - [Lessons learned and troubleshooting](#lessons-learned-and-troubleshooting)
+- [Ecosystem guides](#ecosystem-guides)
 - [Security boundaries and local data](#security-boundaries-and-local-data)
 - [Upgrading and migration](#upgrading-and-migration)
 - [Development and release verification](#development-and-release-verification)
@@ -845,6 +846,31 @@ It stops only this project's launchers and Watcher plus `tunnel-client.exe`
 processes that exactly match the selected profile. It does not globally
 terminate unrelated PatchWarden, OpenCode, or Codex instances.
 
+## Dashboard pages and recommended workflow
+
+The PatchWarden Dashboard (Control Center) provides these main pages:
+
+- **Dashboard**: System overview, including Repo selector, Health Score, service status, Release card, Project Policy, Lineage, Evidence Pack, stale task hints, recent task list, and system status (with Copy diagnostics).
+- **Tasks**: Task list, filterable by repo_path / status / acceptance_status / warning type / agent / date range. Each row offers safe_result / safe_audit / safe_test_summary / safe_diff_summary quick actions.
+- **Task Detail**: Defaults to a safe summary (safe_result / safe_test_summary / safe_diff_summary / safe_audit). Full result / diff / test log live in a collapsed advanced section and load on demand.
+- **Direct Sessions**: Grouped by active / finalized / audited / expired, with safe_direct_summary / safe_finalize_direct_session / safe_audit_direct_session quick actions.
+- **Audit / Warnings**: Aggregated by warning type, showing affected tasks / severity / recommended action.
+- **Workspace**: First-level workspace directories and project list.
+- **Logs**: Tails of Core / Direct / Watcher / Control Center logs.
+
+Recommended workflow:
+
+1. Select the target repo at the top of the Dashboard.
+2. Check the Health Score to confirm system health.
+3. Click safe_result on a recent task row to view the task summary.
+4. Open Task Detail for safe-first acceptance; expand the advanced section only when you need the full logs.
+5. Use Lineage Detail to inspect why a run_task_loop succeeded or failed.
+6. Export the Evidence Pack after acceptance.
+7. Use Direct sessions for independent verification, then finalize + audit.
+8. When something goes wrong, click Copy diagnostics and paste the output to ChatGPT / Codex / opencode for triage.
+
+> See [docs/dashboard-overview.md](docs/dashboard-overview.md), [docs/task-safe-review-workflow.md](docs/task-safe-review-workflow.md), [docs/lineage-evidence-pack-workflow.md](docs/lineage-evidence-pack-workflow.md), and [docs/direct-session-workflow.md](docs/direct-session-workflow.md) for details.
+
 ## Lessons learned and troubleshooting
 
 ### Quick reference
@@ -1017,6 +1043,17 @@ the Watcher, and retains the existing DPAPI credential handling. In a fresh
 ChatGPT conversation, `health_check` should report `chatgpt_direct`, fourteen
 tools, and `direct_profile_enabled=true`.
 
+## Ecosystem guides
+
+- [Why PatchWarden](docs/why-patchwarden.md)
+- [Evidence Pack v2 schema](docs/evidence-pack-schema.md)
+- [Spec Kit integration](docs/spec-kit-integration.md)
+- [AgentSeal integration](docs/agentseal-integration.md)
+- [MCP Inspector testing](docs/mcp-inspector-testing.md)
+- [OpenCode worker integration](docs/opencode-worker.md)
+- [OpenHands worker integration](docs/openhands-worker.md)
+- [Threat model](docs/threat-model.md)
+
 ## Security boundaries and local data
 
 Primary protections:
@@ -1122,6 +1159,10 @@ and release-asset checksums independently.
 - [ChatGPT usage guide](docs/chatgpt-usage.md)
 - [Migration guide](docs/migration-from-safe-bifrost.md)
 - [ChatGPT Connector demo](docs/demo.md)
+- [Dashboard overview](docs/dashboard-overview.md)
+- [Task safe review workflow](docs/task-safe-review-workflow.md)
+- [Lineage and Evidence Pack workflow](docs/lineage-evidence-pack-workflow.md)
+- [Direct session workflow](docs/direct-session-workflow.md)
 - [OpenAI tunnel examples](examples/openai-tunnel/README.md)
 - [ChatGPT test prompt](examples/openai-tunnel/chatgpt-test-prompt.md)
 
@@ -1137,7 +1178,7 @@ and release-asset checksums independently.
 - [x] Release Gate (five-stage pre-release verification)
 - [x] Worktree isolation
 - [x] Multi-agent routing
-- [ ] Local dashboard
+- [x] Local dashboard
 
 ## License
 

package/README.md

@@ -8,7 +8,7 @@
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-339933.svg)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-当前源码版本：**v1.5.0**。查看
+当前源码版本：**v1.5.1**。查看
 [CHANGELOG](CHANGELOG.md)、[迁移指南](docs/migration-from-safe-bifrost.md)和
 [发布检查清单](docs/release-checklist.md)。GitHub Release / npm 发布状态需要在发布前单独核对。
 
@@ -44,6 +44,7 @@ PatchWarden 负责把计划保存成工作区内任务，再由预先配置的
 - [诊断与健康检查](#诊断与健康检查)
 - [踩坑记录与故障排查](#踩坑记录与故障排查)
 - [Direct 模式：ChatGPT 直接开发](#direct-模式chatgpt-直接开发)
+- [生态适配](#生态适配)
 - [安全边界与本地数据](#安全边界与本地数据)
 - [升级与旧版本迁移](#升级与旧版本迁移)
 - [开发与发布验证](#开发与发布验证)
@@ -751,6 +752,31 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%CD%\scripts\control\st
 `chatgpt_core` / `patchwarden` → `127.0.0.1:8080`，
 `chatgpt_direct` / `patchwarden-direct` → `127.0.0.1:8081`。
 
+## Dashboard 主要页面与推荐工作流
+
+PatchWarden Dashboard (Control Center) 提供以下主要页面：
+
+- **控制台 (Dashboard)**: 系统总览，包含 Repo selector、Health Score、服务状态、Release 卡片、Project Policy、Lineage、Evidence Pack、Stale 任务提示、最近任务列表、系统状态（含 Copy diagnostics）。
+- **任务面板 (Tasks)**: 任务列表，支持按 repo_path / status / acceptance_status / warning type / agent / date range 过滤，每行提供 safe_result / safe_audit / safe_test_summary / safe_diff_summary 快捷操作。
+- **任务详情 (Task Detail)**: 默认展示 safe 摘要（safe_result / safe_test_summary / safe_diff_summary / safe_audit），完整 result / diff / test log 在折叠的高级区按需加载。
+- **Direct 会话 (Direct Sessions)**: 按 active / finalized / audited / expired 分组，提供 safe_direct_summary / safe_finalize_direct_session / safe_audit_direct_session 快捷操作。
+- **审计日志 / Warnings (Audit)**: 按 warning 类型聚合，显示 affected tasks / severity / recommended action。
+- **工作区 (Workspace)**: workspace 一级目录与项目列表。
+- **日志 (Logs)**: Core / Direct / Watcher / Control Center 日志尾部。
+
+推荐工作流：
+
+1. 在 Dashboard 顶部选择目标 repo。
+2. 查看 Health Score 确认系统健康。
+3. 在最近任务列表点击 safe_result 快捷查看任务摘要。
+4. 打开 Task Detail 进行 safe-first 验收，仅在需要时展开高级区查看完整日志。
+5. 使用 Lineage Detail 查看 run_task_loop 的成功/失败原因。
+6. 验收完成后导出 Evidence Pack。
+7. Direct 会话用于独立验证，完成后 finalize + audit。
+8. 遇到问题时点击 Copy diagnostics 复制诊断信息发给 ChatGPT / Codex / opencode 排查。
+
+> 详细说明见 [docs/dashboard-overview.md](docs/dashboard-overview.md)、[docs/task-safe-review-workflow.md](docs/task-safe-review-workflow.md)、[docs/lineage-evidence-pack-workflow.md](docs/lineage-evidence-pack-workflow.md)、[docs/direct-session-workflow.md](docs/direct-session-workflow.md)。
+
 ## 踩坑记录与故障排查
 
 ### 快速对照表
@@ -977,6 +1003,17 @@ Direct 模式在受控 session 内执行，具有以下硬性限制：
 
 Direct 模式不支持：shell、delete、rename、commit、push、publish、deployment。
 
+## 生态适配
+
+- [为什么需要 PatchWarden](docs/why-patchwarden.md)
+- [Evidence Pack v2 文件结构](docs/evidence-pack-schema.md)
+- [Spec Kit 集成模式](docs/spec-kit-integration.md)
+- [AgentSeal 集成模式](docs/agentseal-integration.md)
+- [MCP Inspector 测试](docs/mcp-inspector-testing.md)
+- [OpenCode worker 集成](docs/opencode-worker.md)
+- [OpenHands worker 集成](docs/openhands-worker.md)
+- [威胁模型](docs/threat-model.md)
+
 ## 安全边界与本地数据
 
 PatchWarden 的主要保护：
@@ -1081,6 +1118,10 @@ Release 和发布资产校验值。
 - [ChatGPT 调用规范](docs/chatgpt-usage.md)
 - [旧版本迁移指南](docs/migration-from-safe-bifrost.md)
 - [ChatGPT Connector 演示](docs/demo.md)
+- [Dashboard 概览](docs/dashboard-overview.md)
+- [任务 safe 验收工作流](docs/task-safe-review-workflow.md)
+- [Lineage 与 Evidence Pack 工作流](docs/lineage-evidence-pack-workflow.md)
+- [Direct 会话工作流](docs/direct-session-workflow.md)
 - [OpenAI Tunnel 示例](examples/openai-tunnel/README.md)
 - [ChatGPT 测试提示词](examples/openai-tunnel/chatgpt-test-prompt.md)
 
@@ -1096,7 +1137,7 @@ Release 和发布资产校验值。
 - [x] Release Gate（发布前五阶段校验）
 - [x] Worktree 隔离
 - [x] 多 Agent 路由
-- [ ] 本地 Dashboard
+- [x] 本地 Dashboard
 
 ## License
 

package/dist/assessments/agentAssessor.d.ts

@@ -12,4 +12,4 @@ export interface AgentAssessorInput {
     maxOutputBytes: number;
     config: PatchWardenConfig;
 }
-export declare function runAgentAssessment(input: AgentAssessorInput): AgentAssessmentSummary;
+export declare function runAgentAssessment(input: AgentAssessorInput): Promise<AgentAssessmentSummary>;

package/dist/assessments/agentAssessor.js

@@ -4,7 +4,7 @@ import { buildAgentInvocation, buildAssessmentPrompt } from "../runner/agentInvo
 import { runSimpleProcessSync } from "../runner/simpleProcess.js";
 import { captureRepoSnapshot, compareSnapshots } from "../runner/changeCapture.js";
 const ASSESSMENT_MARKER = "===ASSESSMENT_JSON===";
-export function runAgentAssessment(input) {
+export async function runAgentAssessment(input) {
     const logPaths = {
         stdout: resolve(input.assessmentDir, "agent-assessment-stdout.log"),
         stderr: resolve(input.assessmentDir, "agent-assessment-stderr.log"),
@@ -33,7 +33,7 @@ export function runAgentAssessment(input) {
     // ── 2. Before snapshot (repo-scoped) ──
     let repoBefore;
     try {
-        repoBefore = captureRepoSnapshot(input.repoPath);
+        repoBefore = await captureRepoSnapshot(input.repoPath);
     }
     catch {
         // If we can't capture before snapshot, conservatively skip agent assessment
@@ -73,7 +73,7 @@ export function runAgentAssessment(input) {
     let readOnlyViolation = false;
     let violationFiles = [];
     try {
-        const repoAfter = captureRepoSnapshot(input.repoPath);
+        const repoAfter = await captureRepoSnapshot(input.repoPath);
         const changes = compareSnapshots(repoBefore, repoAfter);
         if (changes.length > 0) {
             readOnlyViolation = true;

package/dist/assessments/assessmentStore.d.ts

@@ -117,7 +117,7 @@ export declare function validateAssessmentFreshness(assessmentId: string, curren
  * This is intentionally not registered as an MCP tool: a remote client may
  * request confirmation, but it cannot grant confirmation to itself.
  */
-export declare function confirmAssessment(assessmentId: string): AssessmentConfirmationResult;
+export declare function confirmAssessment(assessmentId: string): Promise<AssessmentConfirmationResult>;
 export declare function computeWorkspaceFingerprint(snapshot: RepoSnapshot): string;
 interface PolicyHashInput {
     change_policy: ChangePolicy;

package/dist/assessments/assessmentStore.js

@@ -156,7 +156,7 @@ export function validateAssessmentFreshness(assessmentId, currentSnapshot, optio
  * This is intentionally not registered as an MCP tool: a remote client may
  * request confirmation, but it cannot grant confirmation to itself.
  */
-export function confirmAssessment(assessmentId) {
+export async function confirmAssessment(assessmentId) {
     if (!/^assessment_\d{8}_\d{6}_[0-9a-f]{32}$/.test(assessmentId)) {
         throw new PatchWardenError("assessment_id_invalid", "Local confirmation requires the full assessment_id (32 hexadecimal random characters).", "Copy the complete assessment_id from the assess_only response; assessment_short_id is display-only.");
     }
@@ -166,7 +166,7 @@ export function confirmAssessment(assessmentId) {
             ? "Fix the hard-rule finding and run assess_only again."
             : "This assessment does not require confirmation; execute it with the minimal assessment_id call.");
     }
-    const snapshot = captureRepoSnapshot(assessment.resolved_repo_path);
+    const snapshot = await captureRepoSnapshot(assessment.resolved_repo_path);
     const validation = validateAssessmentFreshness(assessmentId, snapshot, {
         allow_unconfirmed: true,
         // A standalone CLI has no active MCP profile snapshot. The execute path

package/dist/assessments/confirmCli.js

@@ -9,18 +9,19 @@
 import { loadConfig } from "../config.js";
 import { confirmAssessment } from "./assessmentStore.js";
 import { errorPayload } from "../errors.js";
+import { logger } from "../logging.js";
 loadConfig();
 const assessmentId = process.argv[2];
 if (!assessmentId || process.argv.length !== 3) {
-    console.error("Usage: patchwarden-confirm <full_assessment_id>");
-    console.error("The display-only assessment_short_id is not accepted.");
+    logger.info("Usage: patchwarden-confirm <full_assessment_id>");
+    logger.info("The display-only assessment_short_id is not accepted.");
     process.exit(1);
 }
 try {
-    const result = confirmAssessment(assessmentId);
+    const result = await confirmAssessment(assessmentId);
     console.log(JSON.stringify(result, null, 2));
 }
 catch (error) {
-    console.error(JSON.stringify(errorPayload(error), null, 2));
+    logger.error("confirm_assessment_failed", { error: errorPayload(error) });
     process.exit(1);
 }

package/dist/config.d.ts

@@ -17,6 +17,13 @@ export interface PatchWardenConfig {
     watcherStaleSeconds: number;
     toolProfile?: "full" | "chatgpt_core" | "chatgpt_direct" | "chatgpt_search";
     repoAliases?: Record<string, string>;
+    httpPort?: number;
+    http?: {
+        port?: number;
+        host?: string;
+        ownerTokenEnv?: string;
+    };
+    enableRunTaskTool?: boolean;
     enableAgentAssessment?: boolean;
     agentAssessmentTimeoutSeconds?: number;
     agentAssessmentMaxOutputBytes?: number;

package/dist/config.js

@@ -182,6 +182,40 @@ function normalizeConfig(config) {
         config.toolProfile !== "chatgpt_search") {
         throw new Error('toolProfile must be "full", "chatgpt_core", "chatgpt_direct", or "chatgpt_search"');
     }
+    if (config.repoAliases !== undefined) {
+        if (typeof config.repoAliases !== "object" || config.repoAliases === null || Array.isArray(config.repoAliases)) {
+            throw new Error("repoAliases must be an object mapping alias names to repository paths");
+        }
+        for (const [alias, target] of Object.entries(config.repoAliases)) {
+            if (typeof target !== "string") {
+                throw new Error(`repoAliases["${alias}"] must be a string`);
+            }
+        }
+    }
+    if (config.httpPort !== undefined) {
+        if (typeof config.httpPort !== "number" || !Number.isInteger(config.httpPort) || config.httpPort < 1 || config.httpPort > 65535) {
+            throw new Error("httpPort must be an integer from 1 to 65535");
+        }
+    }
+    if (config.http !== undefined) {
+        if (typeof config.http !== "object" || config.http === null || Array.isArray(config.http)) {
+            throw new Error("http must be an object");
+        }
+        if (config.http.port !== undefined) {
+            if (typeof config.http.port !== "number" || !Number.isInteger(config.http.port) || config.http.port < 1 || config.http.port > 65535) {
+                throw new Error("http.port must be an integer from 1 to 65535");
+            }
+        }
+        if (config.http.host !== undefined && typeof config.http.host !== "string") {
+            throw new Error("http.host must be a string");
+        }
+        if (config.http.ownerTokenEnv !== undefined && typeof config.http.ownerTokenEnv !== "string") {
+            throw new Error("http.ownerTokenEnv must be a string");
+        }
+    }
+    if (config.enableRunTaskTool !== undefined && typeof config.enableRunTaskTool !== "boolean") {
+        throw new Error("enableRunTaskTool must be a boolean");
+    }
     if (config.enableAgentAssessment !== undefined && typeof config.enableAgentAssessment !== "boolean") {
         throw new Error("enableAgentAssessment must be a boolean");
     }

package/dist/control/middleware/auth.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Control Center auth middleware — control token validation.
+ *
+ * POST routes are gated behind an in-memory control token generated at boot.
+ * The token is exposed read-only via GET /control-token.json (handled by the
+ * server router) so the local dashboard can read it, but every mutating
+ * action must pass through `checkControlToken` first.
+ */
+import { type IncomingMessage } from "node:http";
+export declare function checkControlToken(req: IncomingMessage): boolean;

package/dist/control/middleware/auth.js

@@ -0,0 +1,8 @@
+import { controlToken } from "../shared.js";
+export function checkControlToken(req) {
+    const header = req.headers["x-patchwarden-control-token"];
+    const provided = Array.isArray(header) ? header[0] : header;
+    if (typeof provided !== "string" || provided.length === 0)
+        return false;
+    return provided === controlToken;
+}

package/dist/control/middleware/static.d.ts

@@ -0,0 +1,3 @@
+import { type ServerResponse } from "node:http";
+export declare function serveStatic(res: ServerResponse, urlPath: string): void;
+export declare function serveFavicon(res: ServerResponse): void;

package/dist/control/middleware/static.js

@@ -0,0 +1,65 @@
+/**
+ * Control Center static file middleware.
+ *
+ * Serves the bundled `ui/` directory (dashboard pages, partials, vendor
+ * assets, css) with path-traversal protection, plus the inline SVG favicon.
+ * Content types are mapped from `CONTENT_TYPES` in shared.ts.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { extname, isAbsolute, relative, resolve } from "node:path";
+import { CONTENT_TYPES, CONTROL_CENTER_FAVICON, errorMessage, sendJson, uiRoot, } from "../shared.js";
+export function serveStatic(res, urlPath) {
+    let candidate = "";
+    try {
+        const normalized = urlPath.startsWith("/") ? urlPath.slice(1) : urlPath;
+        let decoded;
+        try {
+            decoded = decodeURIComponent(normalized);
+        }
+        catch {
+            sendJson(res, 400, { error: "Invalid path encoding" });
+            return;
+        }
+        if (decoded.includes("\0")) {
+            sendJson(res, 400, { error: "Invalid path" });
+            return;
+        }
+        const segments = decoded.split("/").filter(Boolean);
+        if (segments.some((s) => s === "..")) {
+            sendJson(res, 403, { error: "Forbidden" });
+            return;
+        }
+        candidate = resolve(uiRoot, ...segments);
+        const rel = relative(uiRoot, candidate);
+        if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+            sendJson(res, 403, { error: "Forbidden" });
+            return;
+        }
+    }
+    catch (err) {
+        sendJson(res, 500, { error: errorMessage(err) });
+        return;
+    }
+    try {
+        if (!existsSync(candidate) || !statSync(candidate).isFile()) {
+            sendJson(res, 404, { error: "Not found" });
+            return;
+        }
+        const ext = extname(candidate).toLowerCase();
+        const contentType = CONTENT_TYPES[ext] || "application/octet-stream";
+        const content = readFileSync(candidate);
+        res.writeHead(200, { "Content-Type": contentType });
+        res.end(content);
+    }
+    catch (err) {
+        sendJson(res, 500, { error: errorMessage(err) });
+    }
+}
+export function serveFavicon(res) {
+    res.writeHead(200, {
+        "Content-Type": "image/svg+xml; charset=utf-8",
+        "Cache-Control": "public, max-age=86400",
+        "X-Content-Type-Options": "nosniff",
+    });
+    res.end(CONTROL_CENTER_FAVICON);
+}

package/dist/control/routes/audit.d.ts

@@ -0,0 +1,15 @@
+import { type ServerResponse } from "node:http";
+export type LogCategory = "core" | "direct" | "watcher" | "control-center";
+export declare function handleLogs(res: ServerResponse, category: LogCategory, tailLines: number): void;
+export declare function handleAudit(res: ServerResponse): void;
+/**
+ * Aggregate warnings from multiple sources:
+ *  - audit.json warnings/fail_checks/possible_false_positives/manual_verification_required
+ *  - stale task classification (heartbeat stale, collecting_artifacts stale, etc.)
+ *  - task status=failed_verification
+ *
+ * Each warning type is grouped into a bucket with affected task IDs. The
+ * handler is fault-tolerant: any per-task read failure is skipped, and a
+ * top-level failure returns an empty warnings array (never 500).
+ */
+export declare function handleWarnings(res: ServerResponse): void;