patchwarden 1.5.0 → 1.5.1

package/dist/control/routes/tasks.js

@@ -0,0 +1,310 @@
+/**
+ * Control Center routes — task queries (GET /api/tasks/*).
+ *
+ * Hosts the read-only task endpoints: list/filter tasks, stale-task
+ * classification with explanations, task detail, and the safe bounded views
+ * (safe-result / safe-audit / safe-test-summary / safe-diff-summary) that
+ * never expose full stdout/stderr/diff content. Mutating task actions live in
+ * taskActions.ts.
+ */
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { listTasks } from "../../tools/listTasks.js";
+import { safeAudit, safeDiffSummary, safeResult, safeTestSummary } from "../../tools/safeViews.js";
+import { getTasksDir } from "../../config.js";
+import { augmentTaskWithStale, classifyStaleTask, fileMtimeIso, isValidTaskId, parseReviewVerdict, readWatcherStatusSafe, } from "../runtime.js";
+import { config, errorMessage, readJsonFileSafe, readTextFileSafe, sendJson } from "../shared.js";
+export function handleTasks(res, filters) {
+    try {
+        const result = listTasks({ limit: 100 });
+        const watcher = result.watcher;
+        const now = Date.now();
+        let augmented = result.tasks.map((t) => augmentTaskWithStale(t, watcher, now));
+        // Apply optional filters from query params.
+        if (filters) {
+            if (filters.repo_path) {
+                const filterRepo = filters.repo_path.trim().replace(/\\/g, "/");
+                augmented = augmented.filter((t) => {
+                    const taskRepo = String(t.repo_path || ".").replace(/\\/g, "/");
+                    const taskResolved = String(t.resolved_repo_path || "").replace(/\\/g, "/");
+                    return taskRepo === filterRepo || taskResolved === filterRepo;
+                });
+            }
+            if (filters.status) {
+                augmented = augmented.filter((t) => t.status === filters.status);
+            }
+            if (filters.acceptance_status) {
+                augmented = augmented.filter((t) => {
+                    // Tasks without acceptance status only match the "pending" filter when
+                    // status is done_by_agent; null acceptance never matches other values.
+                    return t.acceptance_status === filters.acceptance_status;
+                });
+            }
+            if (filters.agent) {
+                const filterAgent = filters.agent.toLowerCase();
+                augmented = augmented.filter((t) => String(t.agent || "").toLowerCase() === filterAgent);
+            }
+            if (filters.warning_type) {
+                const wt = filters.warning_type;
+                if (wt === "stale") {
+                    augmented = augmented.filter((t) => t.is_stale);
+                }
+                else if (wt === "error") {
+                    augmented = augmented.filter((t) => t.error !== null && t.error !== "");
+                }
+                else {
+                    // Treat as a specific stale_reason token to match against.
+                    augmented = augmented.filter((t) => Array.isArray(t.stale_reasons) && t.stale_reasons.includes(wt));
+                }
+            }
+        }
+        const staleCount = augmented.filter((t) => t.is_stale).length;
+        sendJson(res, 200, {
+            tasks: augmented,
+            total: augmented.length,
+            returned: augmented.length,
+            watcher,
+            stale_count: staleCount,
+        });
+    }
+    catch (err) {
+        sendJson(res, 200, {
+            tasks: [],
+            total: 0,
+            returned: 0,
+            watcher: null,
+            stale_count: 0,
+            error: errorMessage(err),
+        });
+    }
+}
+export function deriveStaleReasonCode(staleReasons) {
+    if (staleReasons.length === 0)
+        return "unknown";
+    if (staleReasons.some((r) => r.includes("heartbeat_stale")))
+        return "heartbeat_stale";
+    if (staleReasons.some((r) => r.includes("config") || r.includes("assessment")))
+        return "assessment_stale_config";
+    if (staleReasons.some((r) => r.includes("runtime") || r.includes("missing")))
+        return "runtime_missing";
+    return staleReasons[0];
+}
+export function staleExplanationFor(reasonCode) {
+    switch (reasonCode) {
+        case "assessment_stale_config":
+            return {
+                explanation: "配置或 tool manifest 已变化，旧 assessment 已过期，需要重新评估或重新创建任务。",
+                next_action: "reconcile or recreate task",
+            };
+        case "heartbeat_stale":
+            return {
+                explanation: "任务心跳已过期，watcher 可能未运行或任务已僵死，建议 reconcile 或 kill。",
+                next_action: "reconcile or kill task",
+            };
+        case "runtime_missing":
+            return {
+                explanation: "任务运行时文件缺失，可能被外部清理，建议重新创建任务。",
+                next_action: "recreate task",
+            };
+        default:
+            return {
+                explanation: "任务状态异常",
+                next_action: "review task",
+            };
+    }
+}
+export function handleStaleTasks(res) {
+    try {
+        const result = listTasks({ limit: 100 });
+        const watcher = result.watcher;
+        const now = Date.now();
+        const staleTasks = result.tasks
+            .map((t) => augmentTaskWithStale(t, watcher, now))
+            .filter((t) => t.is_stale)
+            .map((t) => {
+            const reasonCode = deriveStaleReasonCode(t.stale_reasons);
+            const { explanation, next_action } = staleExplanationFor(reasonCode);
+            return { ...t, reason_code: reasonCode, explanation, next_action };
+        });
+        sendJson(res, 200, {
+            stale_tasks: staleTasks,
+            total: staleTasks.length,
+            watcher,
+            stale_threshold_seconds: config.watcherStaleSeconds,
+            reason: null,
+        });
+    }
+    catch (err) {
+        sendJson(res, 200, { stale_tasks: [], total: 0, reason: errorMessage(err) });
+    }
+}
+export function handleTaskDetail(res, taskId) {
+    try {
+        const tasksDir = getTasksDir(config);
+        const taskDir = join(tasksDir, taskId);
+        if (!existsSync(taskDir) || !statSync(taskDir).isDirectory()) {
+            sendJson(res, 404, { error: "Task not found" });
+            return;
+        }
+        const statusData = readJsonFileSafe(join(taskDir, "status.json"));
+        const runtimeData = readJsonFileSafe(join(taskDir, "runtime.json"));
+        const resultData = readJsonFileSafe(join(taskDir, "result.json"));
+        const auditData = readJsonFileSafe(join(taskDir, "audit.json"));
+        const verifyData = readJsonFileSafe(join(taskDir, "verify.json"));
+        const changedFiles = readJsonFileSafe(join(taskDir, "changed-files.json"));
+        const fileStats = readJsonFileSafe(join(taskDir, "file-stats.json"));
+        const reconcileData = readJsonFileSafe(join(taskDir, "reconcile.json"));
+        // independent-review.md is the primary audit artifact (written by audit_task)
+        const reviewPath = join(taskDir, "independent-review.md");
+        let independentReview = { verdict: null, content: null };
+        if (existsSync(reviewPath)) {
+            const content = readTextFileSafe(reviewPath) ?? "";
+            independentReview = { verdict: parseReviewVerdict(content), content };
+        }
+        // Verification summary from verify.json
+        const verificationSummary = verifyData
+            ? {
+                status: verifyData.status ?? null,
+                commands: Array.isArray(verifyData.commands) ? verifyData.commands : null,
+                checked_at: fileMtimeIso(join(taskDir, "verify.json")),
+            }
+            : null;
+        // Warnings / errors collected from status.error, result.warnings, error.log
+        const warnings = [];
+        const errors = [];
+        if (statusData && statusData.error)
+            errors.push(String(statusData.error));
+        if (resultData && Array.isArray(resultData.warnings)) {
+            for (const w of resultData.warnings)
+                warnings.push(String(w));
+        }
+        if (resultData && resultData.error)
+            errors.push(String(resultData.error));
+        const errorLog = readJsonFileSafe(join(taskDir, "error.log"));
+        if (errorLog && errorLog.message)
+            errors.push(String(errorLog.message));
+        // Stale classification (best-effort, using watcher snapshot)
+        let stale = null;
+        if (statusData) {
+            const watcher = readWatcherStatusSafe();
+            const VALID_ACCEPTANCE2 = ["pending", "accepted", "rejected", "needs_fix", "blocked"];
+            const taskStatus2 = String(statusData.status || "pending");
+            const taskAcceptanceStatus2 = taskStatus2 === "done_by_agent"
+                ? (typeof statusData.acceptance_status === "string" && VALID_ACCEPTANCE2.includes(statusData.acceptance_status) ? statusData.acceptance_status : "pending")
+                : null;
+            const entry = {
+                task_id: taskId,
+                plan_id: String(statusData.plan_id || ""),
+                title: "",
+                agent: String(statusData.agent || ""),
+                status: taskStatus2,
+                phase: String(runtimeData?.phase || statusData.phase || "queued"),
+                acceptance_status: taskAcceptanceStatus2,
+                created_at: String(statusData.created_at || ""),
+                updated_at: String(statusData.updated_at || ""),
+                workspace_root: String(statusData.workspace_root || config.workspaceRoot),
+                repo_path: String(statusData.repo_path || "."),
+                resolved_repo_path: String(statusData.resolved_repo_path || statusData.repo_path || config.workspaceRoot),
+                test_command: String(statusData.test_command || ""),
+                verify_commands: Array.isArray(statusData.verify_commands) ? statusData.verify_commands : [],
+                error: statusData.error ? String(statusData.error) : null,
+                last_heartbeat_at: String(runtimeData?.last_heartbeat_at || statusData.last_heartbeat_at || statusData.updated_at || ""),
+                current_command: runtimeData?.current_command === undefined ? null : String(runtimeData.current_command || "") || null,
+                timeout_seconds: Number(statusData.timeout_seconds) || config.defaultTaskTimeoutSeconds,
+                pending_reason: null,
+                watcher_status: watcher.status,
+            };
+            stale = classifyStaleTask(entry, watcher);
+        }
+        sendJson(res, 200, {
+            task_id: taskId,
+            status: statusData,
+            runtime: runtimeData,
+            result: resultData,
+            audit: auditData,
+            independent_review: independentReview,
+            diff_patch: readTextFileSafe(join(taskDir, "diff.patch")),
+            test_log: readTextFileSafe(join(taskDir, "test.log")) ?? readTextFileSafe(join(taskDir, "test-log.txt")),
+            verify_log: readTextFileSafe(join(taskDir, "verify.log")),
+            changed_files: changedFiles,
+            file_stats: fileStats,
+            verification_summary: verificationSummary,
+            warnings,
+            errors,
+            stale,
+            reconcile: reconcileData,
+            task_dir: taskDir,
+        });
+    }
+    catch (err) {
+        sendJson(res, 200, { task_id: taskId, error: errorMessage(err) });
+    }
+}
+export function handleTaskSafeResult(res, taskId) {
+    try {
+        if (!isValidTaskId(taskId)) {
+            sendJson(res, 400, { error: "Invalid task id" });
+            return;
+        }
+        try {
+            sendJson(res, 200, safeResult(taskId, { max_items: 12 }));
+        }
+        catch (err) {
+            sendJson(res, 200, { task_id: taskId, error: errorMessage(err) });
+        }
+    }
+    catch (err) {
+        sendJson(res, 200, { task_id: taskId, error: errorMessage(err) });
+    }
+}
+export function handleTaskSafeAudit(res, taskId) {
+    try {
+        if (!isValidTaskId(taskId)) {
+            sendJson(res, 400, { error: "Invalid task id" });
+            return;
+        }
+        try {
+            sendJson(res, 200, safeAudit(taskId, { max_items: 12 }));
+        }
+        catch (err) {
+            sendJson(res, 200, { task_id: taskId, error: errorMessage(err) });
+        }
+    }
+    catch (err) {
+        sendJson(res, 200, { task_id: taskId, error: errorMessage(err) });
+    }
+}
+export function handleTaskSafeTestSummary(res, taskId) {
+    try {
+        if (!isValidTaskId(taskId)) {
+            sendJson(res, 400, { error: "Invalid task id" });
+            return;
+        }
+        try {
+            sendJson(res, 200, safeTestSummary(taskId));
+        }
+        catch (err) {
+            sendJson(res, 200, { task_id: taskId, error: errorMessage(err) });
+        }
+    }
+    catch (err) {
+        sendJson(res, 200, { task_id: taskId, error: errorMessage(err) });
+    }
+}
+export function handleTaskSafeDiffSummary(res, taskId) {
+    try {
+        if (!isValidTaskId(taskId)) {
+            sendJson(res, 400, { error: "Invalid task id" });
+            return;
+        }
+        try {
+            sendJson(res, 200, safeDiffSummary(taskId, { max_items: 12 }));
+        }
+        catch (err) {
+            sendJson(res, 200, { task_id: taskId, error: errorMessage(err) });
+        }
+    }
+    catch (err) {
+        sendJson(res, 200, { task_id: taskId, error: errorMessage(err) });
+    }
+}

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

@@ -0,0 +1,15 @@
+import { type ServerResponse } from "node:http";
+export declare function handleWorkspace(res: ServerResponse): void;
+/**
+ * Lists first-level subdirectories of the workspace root and, for each one,
+ * reads package.json (if present) to expose name/version. Read-only and
+ * path-bounded: only direct children of workspaceRoot are inspected.
+ */
+export declare function handleWorkspaceRepos(res: ServerResponse): void;
+/**
+ * On-demand `git status --short` for a single repo under workspaceRoot.
+ * The repo parameter is resolved against workspaceRoot and must stay inside it;
+ * any path traversal attempt is rejected with 400. This intentionally does NOT
+ * run a full workspace scan — only the repo the user clicked is inspected.
+ */
+export declare function handleWorkspaceRepoStatus(res: ServerResponse, repoParam: string): void;

package/dist/control/routes/workspace.js

@@ -0,0 +1,193 @@
+/**
+ * Control Center routes — workspace (/api/workspace/*).
+ *
+ * Lists workspace directories + agent/config summary, lists first-level repo
+ * subdirectories with package.json metadata, and runs on-demand
+ * `git status --short` for a single repo. The git-status endpoint rejects path
+ * traversal and is the only place that shells out to git.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+import { listAgents } from "../../tools/listAgents.js";
+import { resolveWorkspaceRoot } from "../../config.js";
+import { guardWorkspacePath } from "../../security/pathGuard.js";
+import { config, errorMessage, sendJson } from "../shared.js";
+export function handleWorkspace(res) {
+    let workspaceRoot = null;
+    let directories = [];
+    let agents = [];
+    let configSummary = null;
+    try {
+        workspaceRoot = resolveWorkspaceRoot(config);
+    }
+    catch {
+        workspaceRoot = null;
+    }
+    if (workspaceRoot) {
+        try {
+            directories = readdirSync(workspaceRoot, { withFileTypes: true })
+                .filter((e) => e.isDirectory())
+                .map((e) => e.name)
+                .sort();
+        }
+        catch {
+            directories = [];
+        }
+    }
+    try {
+        agents = listAgents().agents;
+    }
+    catch {
+        agents = [];
+    }
+    try {
+        configSummary = {
+            toolProfile: config.toolProfile ?? null,
+            allowedTestCommandsCount: config.allowedTestCommands.length,
+            enableDirectProfile: config.enableDirectProfile ?? false,
+        };
+    }
+    catch {
+        configSummary = null;
+    }
+    sendJson(res, 200, { workspace_root: workspaceRoot, directories, agents, config: configSummary });
+}
+/**
+ * Lists first-level subdirectories of the workspace root and, for each one,
+ * reads package.json (if present) to expose name/version. Read-only and
+ * path-bounded: only direct children of workspaceRoot are inspected.
+ */
+export function handleWorkspaceRepos(res) {
+    let workspaceRoot = null;
+    try {
+        workspaceRoot = resolveWorkspaceRoot(config);
+    }
+    catch (err) {
+        sendJson(res, 200, { repos: [], workspace_root: null, error: errorMessage(err) });
+        return;
+    }
+    if (!workspaceRoot) {
+        sendJson(res, 200, { repos: [], workspace_root: null });
+        return;
+    }
+    let entries = [];
+    try {
+        entries = readdirSync(workspaceRoot, { withFileTypes: true }).filter((e) => e.isDirectory());
+    }
+    catch (err) {
+        sendJson(res, 200, { repos: [], workspace_root: workspaceRoot, error: errorMessage(err) });
+        return;
+    }
+    const repos = entries.map((entry) => {
+        const dirPath = join(workspaceRoot, entry.name);
+        const packageJsonPath = join(dirPath, "package.json");
+        let packageName = null;
+        let version = null;
+        let hasPackageJson = false;
+        if (existsSync(packageJsonPath)) {
+            hasPackageJson = true;
+            try {
+                const raw = readFileSync(packageJsonPath, "utf-8").replace(/^\uFEFF/, "");
+                const data = JSON.parse(raw);
+                packageName = typeof data.name === "string" ? data.name : null;
+                version = typeof data.version === "string" ? data.version : null;
+            }
+            catch {
+                // package.json exists but is unreadable/invalid; keep nulls.
+            }
+        }
+        return {
+            name: entry.name,
+            path: dirPath,
+            has_package_json: hasPackageJson,
+            package_name: packageName,
+            version,
+        };
+    });
+    repos.sort((a, b) => a.name.localeCompare(b.name));
+    sendJson(res, 200, { repos, workspace_root: workspaceRoot });
+}
+/**
+ * On-demand `git status --short` for a single repo under workspaceRoot.
+ * The repo parameter is resolved against workspaceRoot and must stay inside it;
+ * any path traversal attempt is rejected with 400. This intentionally does NOT
+ * run a full workspace scan — only the repo the user clicked is inspected.
+ */
+export function handleWorkspaceRepoStatus(res, repoParam) {
+    try {
+        let workspaceRoot;
+        try {
+            workspaceRoot = resolveWorkspaceRoot(config);
+        }
+        catch (err) {
+            sendJson(res, 500, { error: `workspace root unavailable: ${errorMessage(err)}` });
+            return;
+        }
+        // Reject obvious traversal in the raw parameter before resolving.
+        if (repoParam.includes("\0") || repoParam.includes("..")) {
+            sendJson(res, 400, { error: "Invalid repo path: traversal segments are not allowed" });
+            return;
+        }
+        let repoAbs;
+        try {
+            // guardWorkspacePath rejects absolute paths outside workspace and any
+            // resolved path that escapes workspaceRoot.
+            repoAbs = guardWorkspacePath(repoParam || ".", workspaceRoot);
+        }
+        catch (err) {
+            sendJson(res, 400, { error: `Invalid repo path: ${errorMessage(err)}` });
+            return;
+        }
+        if (!existsSync(repoAbs) || !statSync(repoAbs).isDirectory()) {
+            sendJson(res, 404, { error: "Repo directory not found", repo_path: repoParam });
+            return;
+        }
+        // Only `git status --short` is permitted; no arbitrary git subcommand.
+        // Timeout guards against a hung git prompt (e.g. credential dialog).
+        execFile("git", ["status", "--short"], { cwd: repoAbs, maxBuffer: 1024 * 1024, timeout: 8000, windowsHide: true, encoding: "utf-8" }, (err, stdout, stderr) => {
+            if (err) {
+                // Not a git repo, git missing, or git errored — return a structured
+                // failure rather than 500 so the UI can render it gracefully.
+                sendJson(res, 200, {
+                    repo_path: repoParam,
+                    resolved_repo_path: repoAbs,
+                    is_git_repo: false,
+                    changed_files_count: 0,
+                    untracked_count: 0,
+                    modified_count: 0,
+                    is_clean: true,
+                    short_status: "",
+                    error: errorMessage(err),
+                    stderr: stderr ? String(stderr).slice(0, 500) : "",
+                });
+                return;
+            }
+            const text = String(stdout);
+            const lines = text.split(/\r?\n/).filter((l) => l.length > 0);
+            let modified = 0;
+            let untracked = 0;
+            for (const line of lines) {
+                const xy = line.slice(0, 2);
+                if (xy === "??")
+                    untracked++;
+                else
+                    modified++;
+            }
+            sendJson(res, 200, {
+                repo_path: repoParam,
+                resolved_repo_path: repoAbs,
+                is_git_repo: true,
+                changed_files_count: lines.length,
+                untracked_count: untracked,
+                modified_count: modified,
+                is_clean: lines.length === 0,
+                short_status: text,
+                error: null,
+            });
+        });
+    }
+    catch (err) {
+        sendJson(res, 500, { error: errorMessage(err) });
+    }
+}

package/dist/control/runtime.d.ts

@@ -0,0 +1,91 @@
+import { type TaskEntry } from "../tools/listTasks.js";
+import { type AgentAvailability } from "../tools/listAgents.js";
+import { type WatcherStatusSnapshot } from "../watcherStatus.js";
+export interface HealthProbe {
+    available: boolean;
+    status: number | null;
+    reason: string | null;
+}
+export declare function probeHealthStatus(targetUrl: string): Promise<HealthProbe>;
+export interface RuntimeHealth {
+    available: boolean;
+    reason: string | null;
+    healthz: {
+        status: number;
+    } | null;
+    readyz: {
+        status: number;
+    } | null;
+}
+export declare function probeRuntimeHealth(baseUrl: string): Promise<RuntimeHealth>;
+export declare function readTunnelStatus(direct: boolean): Record<string, unknown>;
+export interface ToolManifestSummary {
+    tool_profile: string | null;
+    tool_count: number | null;
+    schema_epoch: string | null;
+    tool_manifest_sha256: string | null;
+    tool_names: string[] | null;
+}
+export declare function readToolManifest(direct: boolean): ToolManifestSummary;
+export declare function readTunnelUrl(direct: boolean): {
+    url: string | null;
+    reason: string | null;
+};
+export declare function readWatcherStatusSafe(): WatcherStatusSnapshot;
+export declare function listAgentsSafe(): AgentAvailability[];
+export declare function resolveWorkspaceRootSafe(): string | null;
+export interface StatusTasks {
+    tasks: unknown[];
+    total: number;
+    active: number;
+    stale: number;
+    stale_task_ids: string[];
+    reason: string | null;
+}
+export interface StaleClassification {
+    is_stale: boolean;
+    stale_reasons: string[];
+}
+export declare const TERMINAL_TASK_STATUSES: Set<string>;
+/**
+ * Classify a task as stale based on Phase 2 rules:
+ *  - status=running but last_heartbeat_at exceeds threshold
+ *  - phase=collecting_artifacts exceeds threshold
+ *  - current_command=null AND watcher currently healthy
+ *  - task last_heartbeat_at significantly earlier than current watcher heartbeat
+ *
+ * Only pending/running tasks can be stale; terminal tasks are never stale.
+ */
+export declare function classifyStaleTask(task: TaskEntry, watcher: WatcherStatusSnapshot, nowMs?: number): StaleClassification;
+export declare function augmentTaskWithStale(task: TaskEntry, watcher: WatcherStatusSnapshot, nowMs?: number): TaskEntry & StaleClassification;
+export declare function listTasksForStatus(): StatusTasks;
+export interface ControlCenterStatusFile {
+    pid: number;
+    port: number;
+    started_at: string;
+    url: string;
+    version: string;
+}
+export declare function writeStatusFile(): void;
+export declare function removeStatusFile(): void;
+export interface ControlCenterEvent {
+    timestamp: string;
+    type: string;
+    payload?: Record<string, unknown>;
+}
+/**
+ * Append a single event line to the JSONL timeline. Best-effort: a write
+ * failure is logged but never crashes the server. Trims the file to
+ * MAX_EVENT_LINES lazily when it grows past 1.5x the cap, so we don't pay the
+ * trim cost on every event.
+ */
+export declare function recordEvent(type: string, payload?: Record<string, unknown>): void;
+export declare function readEvents(limit: number): ControlCenterEvent[];
+export declare function readHiddenStaleIds(): string[];
+export declare function writeHiddenStaleIds(ids: string[]): void;
+export declare function readHiddenDirectSessionIds(): string[];
+export declare function writeHiddenDirectSessionIds(ids: string[]): void;
+export declare function isValidDirectSessionId(sessionId: string): boolean;
+export declare function isValidTaskId(taskId: string): boolean;
+export declare function parseReviewVerdict(content: string): string | null;
+export declare function fileMtimeIso(filePath: string): string | null;