patchwarden 1.5.0 → 1.6.1

package/dist/control/routes/taskActions.js

@@ -0,0 +1,197 @@
+/**
+ * Control Center routes — mutating task actions (POST /api/tasks/:id/*).
+ *
+ * These handlers are invoked only after the server router has validated the
+ * control token. They cover reconcile, on-demand audit_task, opening the task
+ * folder in the host file explorer, and hiding a stale task from the
+ * dashboard. None of them delete task files; they annotate or launch external
+ * viewers.
+ */
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { auditTask } from "../../tools/diagnostics/auditTask.js";
+import { getTasksDir } from "../../config.js";
+import { classifyStaleTask, isValidTaskId, readHiddenStaleIds, reconstructTaskEntry, readWatcherStatusSafe, recordEvent, TERMINAL_TASK_STATUSES, writeHiddenStaleIds, } from "../runtime.js";
+import { launchFileManager } from "../fileManager.js";
+import { config, errorMessage, guardControlPath, readJsonFileSafe, sendJson } from "../shared.js";
+import { atomicWriteJsonFileSync } from "../../utils/atomicFile.js";
+import { mutateTaskStatus } from "../../runner/taskStatusStore.js";
+/**
+ * Reconcile a stale task. Does NOT delete the task. Reads the task files,
+ * decides whether it is safe to mark the task as stale/archived, writes a
+ * reconcile record, and (when safe) annotates status.json with reconcile
+ * metadata. The task status enum is never changed — only metadata is added.
+ */
+export function handleReconcile(res, taskId) {
+    try {
+        if (!isValidTaskId(taskId)) {
+            sendJson(res, 400, { error: "Invalid task id" });
+            return;
+        }
+        const tasksDir = getTasksDir(config);
+        const taskDir = guardControlPath(join(tasksDir, taskId), config.tasksDir);
+        if (!taskDir || !existsSync(taskDir) || !statSync(taskDir).isDirectory()) {
+            sendJson(res, 404, { error: "Task not found" });
+            return;
+        }
+        const statusPath = join(taskDir, "status.json");
+        const runtimePath = join(taskDir, "runtime.json");
+        const statusData = readJsonFileSafe(statusPath) ?? {};
+        const runtimeData = readJsonFileSafe(runtimePath) ?? {};
+        const watcher = readWatcherStatusSafe();
+        const taskEntry = reconstructTaskEntry(taskId, statusData, runtimeData, watcher);
+        const cls = classifyStaleTask(taskEntry, watcher);
+        const isTerminal = TERMINAL_TASK_STATUSES.has(taskEntry.status);
+        // Safe to mark stale/archived when:
+        //  - terminal status  -> archive (already finished)
+        //  - stale AND watcher is not actively driving it (no current_command OR watcher not healthy)
+        let decision;
+        let safe = false;
+        if (isTerminal) {
+            decision = "marked_archived";
+            safe = true;
+        }
+        else if (cls.is_stale &&
+            (taskEntry.current_command === null || taskEntry.current_command === "" || watcher.status !== "healthy")) {
+            decision = "marked_stale";
+            safe = true;
+        }
+        else {
+            decision = "no_action";
+            safe = false;
+        }
+        const reconciledAt = new Date().toISOString();
+        const reconcileRecord = {
+            task_id: taskId,
+            reconciled_at: reconciledAt,
+            decision,
+            safe,
+            previous_status: taskEntry.status,
+            previous_phase: taskEntry.phase,
+            is_stale: cls.is_stale,
+            stale_reasons: cls.stale_reasons,
+            watcher_status: watcher.status,
+            watcher_last_heartbeat_at: watcher.last_heartbeat_at,
+            task_last_heartbeat_at: taskEntry.last_heartbeat_at || null,
+            task_current_command: taskEntry.current_command,
+            notes: decision === "no_action"
+                ? "Task does not currently qualify for safe reconcile (still actively running or watcher is healthy)."
+                : "Task annotated with reconcile metadata; original status preserved. No files were deleted.",
+        };
+        // Write the reconcile record artifact.
+        try {
+            atomicWriteJsonFileSync(join(taskDir, "reconcile.json"), reconcileRecord);
+        }
+        catch (writeErr) {
+            sendJson(res, 500, { error: `Failed to write reconcile record: ${errorMessage(writeErr)}` });
+            return;
+        }
+        // Annotate status.json with reconcile metadata (do not mutate status enum).
+        if (safe) {
+            const annotation = {
+                reconcile_state: decision === "marked_archived" ? "archived" : "stale",
+                reconciled_at: reconciledAt,
+            };
+            try {
+                mutateTaskStatus(statusPath, (current) => {
+                    if (current.status !== taskEntry.status) {
+                        throw new Error("Task status changed while reconcile was being evaluated; retry.");
+                    }
+                    const next = { ...current, ...annotation, updated_at: new Date().toISOString() };
+                    return { next, result: next };
+                });
+            }
+            catch (writeErr) {
+                sendJson(res, 500, { error: `Failed to annotate status.json: ${errorMessage(writeErr)}` });
+                return;
+            }
+        }
+        recordEvent("task.reconciled", {
+            task_id: taskId,
+            decision,
+            safe,
+            previous_status: taskEntry.status,
+            is_stale: cls.is_stale,
+        });
+        sendJson(res, 200, reconcileRecord);
+    }
+    catch (err) {
+        sendJson(res, 500, { error: errorMessage(err) });
+    }
+}
+/**
+ * Run audit_task for a task. Only safe to delegate when the task directory
+ * exists and the task is in a terminal state (auditing a running task mid-flight
+ * would race with the watcher writing artifacts).
+ */
+export function handleTaskAudit(res, taskId) {
+    try {
+        if (!isValidTaskId(taskId)) {
+            sendJson(res, 400, { error: "Invalid task id" });
+            return;
+        }
+        const tasksDir = getTasksDir(config);
+        const taskDir = guardControlPath(join(tasksDir, taskId), config.tasksDir);
+        if (!taskDir || !existsSync(taskDir) || !statSync(taskDir).isDirectory()) {
+            sendJson(res, 404, { error: "Task not found" });
+            return;
+        }
+        const statusData = readJsonFileSafe(join(taskDir, "status.json"));
+        const taskStatus = statusData ? String(statusData.status || "") : "";
+        if (!TERMINAL_TASK_STATUSES.has(taskStatus)) {
+            sendJson(res, 409, {
+                error: "Task is not in a terminal state; audit_task can only run safely after completion.",
+                status: taskStatus || "unknown",
+            });
+            return;
+        }
+        const output = auditTask(taskId);
+        recordEvent("task.audited", { task_id: taskId, previous_status: taskStatus });
+        sendJson(res, 200, { ok: true, audit: output });
+    }
+    catch (err) {
+        sendJson(res, 500, { error: errorMessage(err) });
+    }
+}
+export function handleOpenTaskFolder(res, taskId) {
+    try {
+        if (!isValidTaskId(taskId)) {
+            sendJson(res, 400, { error: "Invalid task id" });
+            return;
+        }
+        const tasksDir = getTasksDir(config);
+        const taskDir = guardControlPath(join(tasksDir, taskId), config.tasksDir);
+        if (!taskDir || !existsSync(taskDir) || !statSync(taskDir).isDirectory()) {
+            sendJson(res, 404, { error: "Task not found" });
+            return;
+        }
+        launchFileManager(taskDir, tasksDir);
+        sendJson(res, 200, { ok: true, path: taskDir });
+    }
+    catch (err) {
+        sendJson(res, 500, { error: errorMessage(err) });
+    }
+}
+/**
+ * Hide a stale task from the dashboard's stale-task view. The task itself is
+ * NOT deleted or modified — only the control-center's local hidden-stale-ids
+ * state file is updated. Requires control token (enforced by the POST router).
+ */
+export function handleHideStale(res, taskId) {
+    try {
+        if (!isValidTaskId(taskId)) {
+            sendJson(res, 400, { error: "Invalid task id" });
+            return;
+        }
+        const ids = readHiddenStaleIds();
+        if (!ids.includes(taskId)) {
+            ids.push(taskId);
+            writeHiddenStaleIds(ids);
+        }
+        recordEvent("task.hide_stale", { task_id: taskId });
+        sendJson(res, 200, { ok: true, hidden: taskId });
+    }
+    catch (err) {
+        sendJson(res, 500, { error: errorMessage(err) });
+    }
+}

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

@@ -0,0 +1,24 @@
+import { type ServerResponse } from "node:http";
+export interface TaskFilters {
+    repo_path?: string;
+    status?: string;
+    acceptance_status?: string;
+    agent?: string;
+    warning_type?: string;
+    date_from?: string;
+    date_to?: string;
+    limit?: number;
+    cursor?: string;
+}
+export declare function handleTasks(res: ServerResponse, filters?: TaskFilters): void;
+export declare function deriveStaleReasonCode(staleReasons: string[]): string;
+export declare function staleExplanationFor(reasonCode: string): {
+    explanation: string;
+    next_action: string;
+};
+export declare function handleStaleTasks(res: ServerResponse): void;
+export declare function handleTaskDetail(res: ServerResponse, taskId: string): void;
+export declare function handleTaskSafeResult(res: ServerResponse, taskId: string): void;
+export declare function handleTaskSafeAudit(res: ServerResponse, taskId: string): void;
+export declare function handleTaskSafeTestSummary(res: ServerResponse, taskId: string): void;
+export declare function handleTaskSafeDiffSummary(res: ServerResponse, taskId: string): void;

package/dist/control/routes/tasks.js

@@ -0,0 +1,309 @@
+/**
+ * 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/tasks/listTasks.js";
+import { safeAudit, safeDiffSummary, safeResult, safeTestSummary } from "../../tools/diagnostics/safeViews.js";
+import { getTasksDir } from "../../config.js";
+import { augmentTaskWithStale, classifyStaleTask, fileMtimeIso, isValidTaskId, parseReviewVerdict, reconstructTaskEntry, readWatcherStatusSafe, } from "../runtime.js";
+import { config, errorMessage, guardControlPath, 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));
+        const facetSource = augmented.slice();
+        // 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" || wt === "stale_task") {
+                    augmented = augmented.filter((t) => t.is_stale);
+                }
+                else if (wt === "error") {
+                    augmented = augmented.filter((t) => t.error !== null && t.error !== "");
+                }
+                else if (wt === "failed_verification") {
+                    augmented = augmented.filter((t) => t.status === wt);
+                }
+                else {
+                    augmented = augmented.filter((t) => t.status === wt || t.acceptance_status === wt ||
+                        (Array.isArray(t.stale_reasons) && t.stale_reasons.includes(wt)));
+                }
+            }
+            if (filters.date_from || filters.date_to) {
+                const from = filters.date_from ? Date.parse(`${filters.date_from}T00:00:00`) : Number.NEGATIVE_INFINITY;
+                const to = filters.date_to ? Date.parse(`${filters.date_to}T23:59:59`) : Number.POSITIVE_INFINITY;
+                augmented = augmented.filter((task) => {
+                    const timestamp = Date.parse(String(task.updated_at || task.created_at || ""));
+                    return Number.isFinite(timestamp) && timestamp >= from && timestamp <= to;
+                });
+            }
+        }
+        augmented.sort((a, b) => String(b.created_at || "").localeCompare(String(a.created_at || "")) || String(b.task_id).localeCompare(String(a.task_id)));
+        const staleCount = augmented.filter((t) => t.is_stale).length;
+        const limit = Math.max(10, Math.min(filters?.limit || 25, 100));
+        const offset = filters?.cursor && /^\d+$/.test(filters.cursor) ? Number(filters.cursor) : 0;
+        const page = augmented.slice(offset, offset + limit);
+        const nextCursor = offset + page.length < augmented.length ? String(offset + page.length) : null;
+        const facets = {
+            repos: [...new Set(facetSource.map((task) => String(task.repo_path || ".")))].sort(),
+            statuses: [...new Set(facetSource.map((task) => String(task.status || "unknown")))].sort(),
+            agents: [...new Set(facetSource.map((task) => String(task.agent || "unknown")))].sort(),
+        };
+        sendJson(res, 200, {
+            tasks: page,
+            total: augmented.length,
+            returned: page.length,
+            nextCursor,
+            next_cursor: nextCursor,
+            filters: {
+                applied: {
+                    repo_path: filters?.repo_path || null,
+                    status: filters?.status || null,
+                    acceptance_status: filters?.acceptance_status || null,
+                    agent: filters?.agent || null,
+                    warning_type: filters?.warning_type || null,
+                    date_from: filters?.date_from || null,
+                    date_to: filters?.date_to || null,
+                },
+                options: facets,
+            },
+            facets,
+            watcher,
+            stale_count: staleCount,
+        });
+    }
+    catch (err) {
+        sendJson(res, 200, {
+            tasks: [],
+            total: 0,
+            returned: 0,
+            nextCursor: null,
+            next_cursor: null,
+            filters: { applied: {}, options: { repos: [], statuses: [], agents: [] } },
+            facets: { repos: [], statuses: [], agents: [] },
+            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 {
+        if (!isValidTaskId(taskId)) {
+            sendJson(res, 400, { error: "Invalid task id" });
+            return;
+        }
+        const tasksDir = getTasksDir(config);
+        const taskDir = guardControlPath(join(tasksDir, taskId), config.tasksDir);
+        if (!taskDir || !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 entry = reconstructTaskEntry(taskId, statusData, runtimeData ?? {}, watcher);
+            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;
+        }
+        sendJson(res, 200, safeResult(taskId, { max_items: 12 }));
+    }
+    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;
+        }
+        sendJson(res, 200, safeAudit(taskId, { max_items: 12 }));
+    }
+    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;
+        }
+        sendJson(res, 200, safeTestSummary(taskId));
+    }
+    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;
+        }
+        sendJson(res, 200, safeDiffSummary(taskId, { max_items: 12 }));
+    }
+    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;