patchwarden 1.1.0 → 1.5.1

package/dist/control/routes/audit.js

@@ -0,0 +1,277 @@
+/**
+ * Control Center routes — audit aggregation, warnings, and log tails.
+ *
+ * `handleAudit` joins independent-review.md + audit.json across tasks and
+ * direct sessions. `handleWarnings` buckets audit/stale/verification warnings
+ * by type. `handleLogs` returns redacted stdout/stderr tails for core, direct,
+ * watcher, and control-center log categories.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { listTasks } from "../../tools/listTasks.js";
+import { redactSensitiveContent } from "../../security/contentRedaction.js";
+import { getDirectSessionsDir, getTasksDir } from "../../config.js";
+import { classifyStaleTask, fileMtimeIso, parseReviewVerdict, readWatcherStatusSafe, } from "../runtime.js";
+import { config, errorMessage, findLatestLog, getControlCenterLogDir, getRuntimeRoot, readFileTail, readJsonFileSafe, readTextFileSafe, sendJson, } from "../shared.js";
+export function handleLogs(res, category, tailLines) {
+    try {
+        let dir;
+        let stdoutPath;
+        let stderrPath;
+        let stdoutExists;
+        let stderrExists;
+        if (category === "control-center") {
+            dir = getControlCenterLogDir();
+            stdoutPath = join(dir, "control-center.stdout.log");
+            stderrPath = join(dir, "control-center.stderr.log");
+            stdoutExists = existsSync(stdoutPath);
+            stderrExists = existsSync(stderrPath);
+        }
+        else if (category === "watcher") {
+            dir = getRuntimeRoot(false);
+            const sp = findLatestLog(dir, /^watcher-.*\.stdout\.log$/);
+            const ep = findLatestLog(dir, /^watcher-.*\.stderr\.log$/);
+            stdoutPath = sp ?? "";
+            stderrPath = ep ?? "";
+            stdoutExists = sp !== null;
+            stderrExists = ep !== null;
+        }
+        else {
+            // core | direct -> tunnel client logs in the matching runtime dir
+            dir = getRuntimeRoot(category === "direct");
+            stdoutPath = join(dir, "tunnel-client.stdout.log");
+            stderrPath = join(dir, "tunnel-client.stderr.log");
+            stdoutExists = existsSync(stdoutPath);
+            stderrExists = existsSync(stderrPath);
+        }
+        if (!stdoutExists && !stderrExists) {
+            sendJson(res, 200, {
+                stdout: "",
+                stderr: "",
+                category,
+                tail: tailLines,
+                reason: "log file not found",
+            });
+            return;
+        }
+        const stdoutRaw = stdoutExists ? readFileTail(stdoutPath, tailLines) : "";
+        const stderrRaw = stderrExists ? readFileTail(stderrPath, tailLines) : "";
+        const stdout = redactSensitiveContent(stdoutRaw).content;
+        const stderr = redactSensitiveContent(stderrRaw).content;
+        sendJson(res, 200, { stdout, stderr, category, tail: tailLines, reason: null });
+    }
+    catch (err) {
+        sendJson(res, 200, { stdout: "", stderr: "", category, tail: tailLines, reason: errorMessage(err) });
+    }
+}
+export function handleAudit(res) {
+    try {
+        const audits = [];
+        // 1. tasks/*/independent-review.md (written by audit_task — the primary audit artifact)
+        // 2. tasks/*/audit.json (legacy/explicit JSON audit, if present)
+        const tasksDir = getTasksDir(config);
+        if (existsSync(tasksDir)) {
+            let taskEntries = [];
+            try {
+                taskEntries = readdirSync(tasksDir, { withFileTypes: true }).filter((e) => e.isDirectory());
+            }
+            catch {
+                taskEntries = [];
+            }
+            for (const entry of taskEntries) {
+                const taskDir = join(tasksDir, entry.name);
+                // independent-review.md
+                const reviewFile = join(taskDir, "independent-review.md");
+                if (existsSync(reviewFile)) {
+                    const content = readTextFileSafe(reviewFile) ?? "";
+                    audits.push({
+                        task_id: entry.name,
+                        source: "independent-review.md",
+                        verdict: parseReviewVerdict(content),
+                        checked_at: fileMtimeIso(reviewFile),
+                        content_excerpt: content.slice(0, 500),
+                    });
+                }
+                // audit.json (explicit JSON audit if present)
+                const auditFile = join(taskDir, "audit.json");
+                if (existsSync(auditFile)) {
+                    const data = readJsonFileSafe(auditFile);
+                    if (data) {
+                        audits.push({
+                            task_id: entry.name,
+                            source: "audit.json",
+                            checked_at: data.checked_at ?? fileMtimeIso(auditFile),
+                            ...data,
+                        });
+                    }
+                }
+            }
+        }
+        // 3. direct-sessions/*/audit.json (written by Direct audit_session)
+        const sessionsDir = getDirectSessionsDir(config);
+        if (existsSync(sessionsDir)) {
+            let sessionEntries = [];
+            try {
+                sessionEntries = readdirSync(sessionsDir, { withFileTypes: true }).filter((e) => e.isDirectory());
+            }
+            catch {
+                sessionEntries = [];
+            }
+            for (const entry of sessionEntries) {
+                const auditFile = join(sessionsDir, entry.name, "audit.json");
+                if (!existsSync(auditFile))
+                    continue;
+                const data = readJsonFileSafe(auditFile);
+                if (data) {
+                    audits.push({
+                        source: "direct-session",
+                        session_id: data.session_id ?? entry.name,
+                        checked_at: fileMtimeIso(auditFile),
+                        ...data,
+                    });
+                }
+            }
+        }
+        // Sort by checked_at descending (missing timestamps sort last).
+        audits.sort((a, b) => {
+            const ac = String(a.checked_at ?? "");
+            const bc = String(b.checked_at ?? "");
+            return bc.localeCompare(ac);
+        });
+        const limited = audits.slice(0, 50);
+        sendJson(res, 200, { audits: limited, total: limited.length });
+    }
+    catch (err) {
+        sendJson(res, 200, { audits: [], reason: errorMessage(err) });
+    }
+}
+/**
+ * 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 function handleWarnings(res) {
+    try {
+        const buckets = {
+            unrecorded_command_execution: new Set(),
+            artifact_hygiene: new Set(),
+            scope_changes: new Set(),
+            release_publish_claim: new Set(),
+            manual_verification_required: new Set(),
+            stale_task: new Set(),
+            failed_verification: new Set(),
+        };
+        const tasksDir = getTasksDir(config);
+        let taskList = [];
+        let watcher;
+        try {
+            const result = listTasks({ limit: 100 });
+            taskList = result.tasks;
+            watcher = result.watcher;
+        }
+        catch (err) {
+            watcher = readWatcherStatusSafe();
+        }
+        const now = Date.now();
+        for (const task of taskList) {
+            const taskId = task.task_id;
+            // 1. Read audit.json for warning strings
+            const auditFile = join(tasksDir, taskId, "audit.json");
+            const audit = readJsonFileSafe(auditFile);
+            if (audit) {
+                const warningTexts = [];
+                const collectStrings = (field) => {
+                    if (Array.isArray(field)) {
+                        for (const w of field) {
+                            if (typeof w === "string") {
+                                warningTexts.push(w);
+                            }
+                            else if (w && typeof w === "object") {
+                                const obj = w;
+                                if (typeof obj.message === "string")
+                                    warningTexts.push(obj.message);
+                                else if (typeof obj.description === "string")
+                                    warningTexts.push(obj.description);
+                                else if (typeof obj.warning === "string")
+                                    warningTexts.push(obj.warning);
+                                else
+                                    warningTexts.push(JSON.stringify(obj));
+                            }
+                        }
+                    }
+                    else if (typeof field === "string") {
+                        warningTexts.push(field);
+                    }
+                };
+                collectStrings(audit.warnings);
+                collectStrings(audit.fail_checks);
+                collectStrings(audit.possible_false_positives);
+                for (const text of warningTexts) {
+                    const lower = text.toLowerCase();
+                    if (lower.includes("unrecorded") || lower.includes("command execution")) {
+                        buckets.unrecorded_command_execution.add(taskId);
+                    }
+                    if (lower.includes("artifact") || lower.includes("hygiene")) {
+                        buckets.artifact_hygiene.add(taskId);
+                    }
+                    if (lower.includes("scope") || lower.includes("out_of_scope")) {
+                        buckets.scope_changes.add(taskId);
+                    }
+                    if (lower.includes("release") || lower.includes("publish")) {
+                        buckets.release_publish_claim.add(taskId);
+                    }
+                }
+                // manual_verification_required flag
+                if (audit.manual_verification_required === true) {
+                    buckets.manual_verification_required.add(taskId);
+                }
+            }
+            // 2. Stale tasks
+            try {
+                const cls = classifyStaleTask(task, watcher, now);
+                if (cls.is_stale) {
+                    buckets.stale_task.add(taskId);
+                }
+            }
+            catch {
+                // skip stale classification failure
+            }
+            // 3. Failed verification
+            if (task.status === "failed_verification") {
+                buckets.failed_verification.add(taskId);
+            }
+        }
+        const warnings = [];
+        const addWarning = (type, severity, likelyFalsePositive, needsFix, blocked, recommendedAction) => {
+            const tasks = buckets[type];
+            if (tasks.size === 0)
+                return;
+            warnings.push({
+                type,
+                severity,
+                affected_tasks_count: tasks.size,
+                affected_tasks: Array.from(tasks),
+                likely_false_positive: likelyFalsePositive,
+                needs_fix: needsFix,
+                blocked,
+                recommended_action: recommendedAction,
+            });
+        };
+        addWarning("failed_verification", "error", false, true, false, "Re-run verification or fix the failing checks before retrying.");
+        addWarning("stale_task", "warning", false, false, false, "Reconcile or recreate stale tasks.");
+        addWarning("manual_verification_required", "warning", false, false, false, "Review the audit findings and manually verify the changes.");
+        addWarning("unrecorded_command_execution", "info", false, true, false, "Investigate unrecorded command executions; ensure watcher captures all commands.");
+        addWarning("release_publish_claim", "info", false, false, true, "Verify the release/publish claim against actual release artifacts before proceeding.");
+        addWarning("artifact_hygiene", "info", true, false, false, "Review artifact hygiene warnings; many are likely false positives.");
+        addWarning("scope_changes", "info", true, false, false, "Review scope changes; verify they are intentional before accepting.");
+        sendJson(res, 200, { warnings, total: warnings.length });
+    }
+    catch (err) {
+        sendJson(res, 200, { warnings: [], total: 0, error: errorMessage(err) });
+    }
+}

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

@@ -0,0 +1,4 @@
+import { type ServerResponse } from "node:http";
+export declare function handleEvidencePacks(res: ServerResponse): void;
+export declare function handleEvidencePackDetail(res: ServerResponse, lineageId: string): void;
+export declare function handleEvidencePackExport(res: ServerResponse, lineageId: string): void;

package/dist/control/routes/evidence.js

@@ -0,0 +1,96 @@
+/**
+ * Control Center routes — evidence packs (/api/evidence-packs/*).
+ *
+ * Lists exported evidence packs (bounded to 50), reads a single pack detail,
+ * and exports a pack for a lineage on demand. The export endpoint is a POST
+ * route gated by the control token in the server router.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { exportTaskEvidencePack, listEvidencePacks, readEvidencePack, } from "../../tools/evidencePack.js";
+import { errorMessage, sendJson, config } from "../shared.js";
+function augmentEvidencePackSummary(pack) {
+    const jsonExists = existsSync(pack.files.json);
+    const mdExists = existsSync(pack.files.markdown);
+    return {
+        ...pack,
+        export_status: jsonExists ? "exported" : "pending",
+        evidence_json_exists: jsonExists,
+        evidence_md_exists: mdExists,
+        exported_at: pack.generated_at,
+    };
+}
+export function handleEvidencePacks(res) {
+    try {
+        const list = listEvidencePacks({ max_items: 50 });
+        const packs = list.evidence_packs.map((pack) => augmentEvidencePackSummary(pack));
+        // Detect lineages that exist but have no exported evidence pack yet, so the
+        // dashboard can show an "Export evidence pack" action for the most recent one.
+        const lineagesRoot = join(config.workspaceRoot, ".patchwarden", "lineages");
+        let lineageCount = 0;
+        const exportedIds = new Set(packs.map((p) => p.lineage_id));
+        const pendingLineageIds = [];
+        if (existsSync(lineagesRoot)) {
+            const dirs = readdirSync(lineagesRoot, { withFileTypes: true }).filter((e) => e.isDirectory());
+            lineageCount = dirs.length;
+            for (const dir of dirs) {
+                if (!exportedIds.has(dir.name))
+                    pendingLineageIds.push(dir.name);
+            }
+        }
+        sendJson(res, 200, {
+            evidence_packs: packs,
+            total: packs.length,
+            truncated: list.truncated,
+            has_lineages: lineageCount > 0,
+            lineage_count: lineageCount,
+            pending_lineage_ids: pendingLineageIds.slice(0, 20),
+            reason: null,
+        });
+    }
+    catch (err) {
+        sendJson(res, 200, { evidence_packs: [], total: 0, reason: errorMessage(err) });
+    }
+}
+export function handleEvidencePackDetail(res, lineageId) {
+    try {
+        if (!/^[A-Za-z0-9_-]+$/.test(lineageId)) {
+            sendJson(res, 400, { error: "Invalid lineage id" });
+            return;
+        }
+        const pack = readEvidencePack(lineageId);
+        if (!pack) {
+            sendJson(res, 404, { error: "Evidence pack not found" });
+            return;
+        }
+        sendJson(res, 200, augmentEvidencePackSummary(pack));
+    }
+    catch (err) {
+        sendJson(res, 200, { lineage_id: lineageId, error: errorMessage(err), bounded: true });
+    }
+}
+export function handleEvidencePackExport(res, lineageId) {
+    try {
+        if (!/^[A-Za-z0-9_-]+$/.test(lineageId)) {
+            sendJson(res, 400, { error: "Invalid lineage id" });
+            return;
+        }
+        // Check lineage exists.
+        const lineageFile = join(config.workspaceRoot, ".patchwarden", "lineages", lineageId, "lineage.json");
+        if (!existsSync(lineageFile)) {
+            sendJson(res, 404, { error: "Lineage not found" });
+            return;
+        }
+        // Check if already exported.
+        const evidenceJsonPath = join(config.workspaceRoot, ".patchwarden", "evidence-packs", lineageId, "evidence.json");
+        if (existsSync(evidenceJsonPath)) {
+            sendJson(res, 200, { ok: true, already_exported: true, lineage_id: lineageId });
+            return;
+        }
+        const pack = exportTaskEvidencePack({ lineage_id: lineageId });
+        sendJson(res, 200, { ok: true, exported: true, lineage_id: lineageId, evidence_pack_id: pack.evidence_pack_id });
+    }
+    catch (err) {
+        sendJson(res, 200, { ok: false, lineage_id: lineageId, error: errorMessage(err) });
+    }
+}

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

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

package/dist/control/routes/lineage.js

@@ -0,0 +1,71 @@
+/**
+ * Control Center routes — task lineage (/api/lineages/*).
+ *
+ * Lists all lineages under .patchwarden/lineages (bounded to 50, most recently
+ * updated first) and serves a single lineage detail. Each record is projected
+ * through `toSafeTaskLineage` so full artifact content is bounded.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { toSafeTaskLineage } from "../../tools/taskLineage.js";
+import { config, errorMessage, readJsonFileSafeUnder, sendJson } from "../shared.js";
+function augmentLineageSummary(safe, record) {
+    const directSessions = safe.tasks.direct_sessions;
+    const firstDirect = directSessions.length > 0 ? directSessions[0] : null;
+    const directVerification = firstDirect
+        ? {
+            session_id: firstDirect.session_id,
+            status: firstDirect.status || "unknown",
+            audit_decision: firstDirect.audit_decision || "not_run",
+            command_count: firstDirect.command_count ?? 0,
+            passed_commands: firstDirect.passed_commands ?? 0,
+            failed_commands: firstDirect.failed_commands ?? 0,
+        }
+        : null;
+    return {
+        ...safe,
+        iterations: record.rounds.length,
+        main_task_count: record.main_task ? 1 : 0,
+        fix_task_count: record.fix_tasks.length,
+        cleanup_task_count: record.cleanup_tasks.length,
+        direct_verification: directVerification,
+        warnings_count: record.warnings.length,
+    };
+}
+export function handleLineages(res) {
+    try {
+        const root = join(config.workspaceRoot, ".patchwarden", "lineages");
+        if (!existsSync(root)) {
+            sendJson(res, 200, { lineages: [], total: 0, reason: null });
+            return;
+        }
+        const lineages = readdirSync(root, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => readJsonFileSafeUnder(root, join(entry.name, "lineage.json")))
+            .filter((entry) => entry !== null)
+            .map((entry) => augmentLineageSummary(toSafeTaskLineage(entry, 6), entry))
+            .sort((a, b) => b.updated_at.localeCompare(a.updated_at))
+            .slice(0, 50);
+        sendJson(res, 200, { lineages, total: lineages.length, reason: null });
+    }
+    catch (err) {
+        sendJson(res, 200, { lineages: [], total: 0, reason: errorMessage(err) });
+    }
+}
+export function handleLineageDetail(res, lineageId) {
+    try {
+        if (!/^[A-Za-z0-9_-]+$/.test(lineageId)) {
+            sendJson(res, 400, { error: "Invalid lineage id" });
+            return;
+        }
+        const data = readJsonFileSafeUnder(join(config.workspaceRoot, ".patchwarden", "lineages"), join(lineageId, "lineage.json"));
+        if (!data) {
+            sendJson(res, 404, { error: "Lineage not found" });
+            return;
+        }
+        sendJson(res, 200, augmentLineageSummary(toSafeTaskLineage(data, 20), data));
+    }
+    catch (err) {
+        sendJson(res, 200, { lineage_id: lineageId, error: errorMessage(err) });
+    }
+}

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

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

package/dist/control/routes/policy.js

@@ -0,0 +1,81 @@
+/**
+ * Control Center routes — project policy + release status.
+ *
+ * Read-only wrappers around `getProjectPolicySummary` that surface release
+ * readiness, blocked commands, and version consistency for the dashboard's
+ * release panel. Never performs remote writes (`remote_write_performed` is
+ * always false).
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { getProjectPolicySummary } from "../../policy/projectPolicy.js";
+import { errorMessage, sendJson } from "../shared.js";
+export function handleProjectPolicy(res, repoPath) {
+    try {
+        sendJson(res, 200, getProjectPolicySummary(repoPath || "."));
+    }
+    catch (err) {
+        sendJson(res, 200, {
+            repo_path: repoPath || ".",
+            valid: false,
+            issues: [{ code: "policy_unavailable", severity: "error", field: "repo_path", message: errorMessage(err) }],
+        });
+    }
+}
+export function handleReleaseStatus(res, repoPath) {
+    try {
+        const policy = getProjectPolicySummary(repoPath || ".");
+        const readiness = policy.release_readiness;
+        const requiredCommands = readiness.required_commands.map((c) => ({
+            command: c.command,
+            allowed: c.allowed,
+            blocked_reason: c.allowed ? null : (c.reason || "not_allowed"),
+        }));
+        const commandsBlockedCount = requiredCommands.filter((c) => !c.allowed).length;
+        const hasPackageJson = existsSync(join(policy.resolved_repo_path, "package.json"));
+        const versionSource = hasPackageJson
+            ? "package.json"
+            : (repoPath || ".") === "."
+                ? "workspace_root"
+                : "unknown";
+        let readyState;
+        if (!policy.valid || commandsBlockedCount > 0) {
+            readyState = "blocked";
+        }
+        else if (readiness.version === null) {
+            readyState = "unknown";
+        }
+        else if (readiness.version_consistent === true) {
+            readyState = "ready";
+        }
+        else {
+            readyState = "blocked";
+        }
+        sendJson(res, 200, {
+            repo_path: repoPath || ".",
+            resolved_repo_path: policy.resolved_repo_path,
+            policy_valid: policy.valid,
+            policy_issue_count: policy.issues.length,
+            policy_issues: policy.issues.slice(0, 10),
+            release_readiness: readiness,
+            package_name: readiness.package_name,
+            version_source: versionSource,
+            version_consistent: readiness.version_consistent,
+            required_commands: requiredCommands,
+            commands_blocked_count: commandsBlockedCount,
+            ready_state: readyState,
+            next_action: policy.valid && readiness.version_consistent !== false
+                ? "Run release_check via create_task template, or run_task_loop with template=release_check."
+                : "Fix project-policy or version consistency issues before release preparation.",
+            remote_write_performed: false,
+        });
+    }
+    catch (err) {
+        sendJson(res, 200, {
+            repo_path: repoPath || ".",
+            policy_valid: false,
+            error: errorMessage(err),
+            remote_write_performed: false,
+        });
+    }
+}

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

@@ -0,0 +1,5 @@
+import { type ServerResponse } from "node:http";
+declare function findTunnelClientExecutable(): string | null;
+export { findTunnelClientExecutable };
+export declare function handleManageAction(res: ServerResponse, action: string, mode: string): Promise<void>;
+export declare function handleOpenLogsFolder(res: ServerResponse): void;