patchwarden 1.1.0 → 1.5.1

package/dist/control/runtime.js

@@ -0,0 +1,392 @@
+/**
+ * PatchWarden Control Center — runtime state readers and domain helpers.
+ *
+ * Provides health probing, runtime file readers (tunnel status, tool manifest,
+ * watcher status), stale-task classification, the control-center status/event
+ * timeline, hidden-id UI state, and small shared helpers (verdict parsing,
+ * file mtime, id validation). These are pure helpers consumed by the route
+ * modules; they hold no HTTP-layer concerns beyond reusing `sendJson`.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { get as httpGet } from "node:http";
+import { listTasks } from "../tools/listTasks.js";
+import { listAgents } from "../tools/listAgents.js";
+import { readWatcherStatus } from "../watcherStatus.js";
+import { resolveWorkspaceRoot } from "../config.js";
+import { PATCHWARDEN_VERSION } from "../version.js";
+import { logger } from "../logging.js";
+import { config, controlCenterEventsPath, controlCenterStatusPath, errorMessage, getControlCenterLogDir, getRuntimeRoot, host, MAX_EVENT_LINES, port, readJsonFileSafe, } from "./shared.js";
+export function probeHealthStatus(targetUrl) {
+    return new Promise((resolve) => {
+        const controller = new AbortController();
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            try {
+                controller.abort();
+            }
+            catch { /* ignore */ }
+            finish({ available: false, status: null, reason: "timeout after 2000ms" });
+        }, 2000);
+        try {
+            const req = httpGet(targetUrl, { signal: controller.signal }, (resp) => {
+                resp.resume();
+                const status = resp.statusCode ?? 0;
+                // Only 2xx counts as available. A 404 from an unrelated service (or a
+                // 4xx/5xx from the real service) must NOT be treated as healthy.
+                if (status >= 200 && status < 300) {
+                    finish({ available: true, status, reason: null });
+                }
+                else {
+                    finish({ available: false, status, reason: `unexpected status ${status}` });
+                }
+            });
+            req.on("error", (err) => {
+                finish({ available: false, status: null, reason: err.message });
+            });
+        }
+        catch (err) {
+            finish({ available: false, status: null, reason: errorMessage(err) });
+        }
+    });
+}
+export async function probeRuntimeHealth(baseUrl) {
+    const [h, r] = await Promise.all([
+        probeHealthStatus(`${baseUrl}/healthz`),
+        probeHealthStatus(`${baseUrl}/readyz`),
+    ]);
+    if (h.available && r.available && h.status !== null && r.status !== null) {
+        return { available: true, reason: null, healthz: { status: h.status }, readyz: { status: r.status } };
+    }
+    const failed = !h.available ? h : r;
+    return { available: false, reason: failed.reason ?? "unavailable", healthz: null, readyz: null };
+}
+// ── Runtime file readers ──────────────────────────────────────────
+export function readTunnelStatus(direct) {
+    const filePath = join(getRuntimeRoot(direct), "tunnel-status.json");
+    if (!existsSync(filePath))
+        return { observed: false };
+    try {
+        const data = readJsonFileSafe(filePath);
+        if (data === null)
+            return { observed: true, error: "invalid JSON" };
+        return { observed: true, ...data };
+    }
+    catch (err) {
+        return { observed: true, error: errorMessage(err) };
+    }
+}
+export function readToolManifest(direct) {
+    const empty = {
+        tool_profile: null,
+        tool_count: null,
+        schema_epoch: null,
+        tool_manifest_sha256: null,
+        tool_names: null,
+    };
+    const filePath = join(getRuntimeRoot(direct), "tool-manifest.json");
+    if (!existsSync(filePath))
+        return empty;
+    const data = readJsonFileSafe(filePath);
+    if (!data)
+        return empty;
+    return {
+        tool_profile: typeof data.tool_profile === "string" ? data.tool_profile : null,
+        tool_count: typeof data.tool_count === "number" ? data.tool_count : null,
+        schema_epoch: typeof data.schema_epoch === "string" ? data.schema_epoch : null,
+        tool_manifest_sha256: typeof data.tool_manifest_sha256 === "string" ? data.tool_manifest_sha256 : null,
+        tool_names: Array.isArray(data.tool_names) ? data.tool_names : null,
+    };
+}
+export function readTunnelUrl(direct) {
+    const filePath = join(getRuntimeRoot(direct), "tunnel-health-url.txt");
+    if (!existsSync(filePath))
+        return { url: null, reason: "tunnel-health-url.txt not found" };
+    try {
+        const content = readFileSync(filePath, "utf-8").trim();
+        if (!content)
+            return { url: null, reason: "tunnel-health-url.txt is empty" };
+        return { url: content, reason: null };
+    }
+    catch (err) {
+        return { url: null, reason: errorMessage(err) };
+    }
+}
+// ── Safe wrappers around reusable modules ─────────────────────────
+export function readWatcherStatusSafe() {
+    try {
+        return readWatcherStatus(config);
+    }
+    catch (err) {
+        return {
+            status: "unreadable",
+            available: false,
+            stale_after_seconds: config.watcherStaleSeconds,
+            last_heartbeat_at: null,
+            heartbeat_age_seconds: null,
+            heartbeat_pid: null,
+            instance_id: null,
+            launcher_pid: null,
+            reason: errorMessage(err),
+            activity: null,
+        };
+    }
+}
+export function listAgentsSafe() {
+    try {
+        return listAgents().agents;
+    }
+    catch {
+        return [];
+    }
+}
+export function resolveWorkspaceRootSafe() {
+    try {
+        return resolveWorkspaceRoot(config);
+    }
+    catch {
+        return null;
+    }
+}
+export const TERMINAL_TASK_STATUSES = new Set([
+    "done",
+    "done_by_agent",
+    "failed",
+    "failed_verification",
+    "failed_scope_violation",
+    "failed_policy_violation",
+    "canceled",
+    "timeout",
+]);
+/**
+ * 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 function classifyStaleTask(task, watcher, nowMs = Date.now()) {
+    const reasons = [];
+    if (TERMINAL_TASK_STATUSES.has(task.status)) {
+        return { is_stale: false, stale_reasons: reasons };
+    }
+    // Only pending/running are candidates for staleness.
+    if (task.status !== "pending" && task.status !== "running") {
+        return { is_stale: false, stale_reasons: reasons };
+    }
+    const staleThresholdMs = config.watcherStaleSeconds * 1000;
+    const hbMs = Date.parse(task.last_heartbeat_at || "");
+    const heartbeatAgeMs = Number.isFinite(hbMs) ? Math.max(0, nowMs - hbMs) : null;
+    // Rule 1: running with stale heartbeat
+    if (task.status === "running" && heartbeatAgeMs !== null && heartbeatAgeMs > staleThresholdMs) {
+        reasons.push("heartbeat_stale");
+    }
+    // Rule 2: collecting_artifacts phase exceeds threshold
+    if (task.phase === "collecting_artifacts" && heartbeatAgeMs !== null && heartbeatAgeMs > staleThresholdMs) {
+        reasons.push("collecting_artifacts_stale");
+    }
+    // Rule 3: running with no current_command while watcher is healthy
+    if (task.status === "running" &&
+        (task.current_command === null || task.current_command === "") &&
+        watcher.status === "healthy") {
+        reasons.push("running_no_command_watcher_healthy");
+    }
+    // Rule 4: task heartbeat significantly earlier than watcher heartbeat
+    if (heartbeatAgeMs !== null && watcher.last_heartbeat_at) {
+        const watcherHbMs = Date.parse(watcher.last_heartbeat_at);
+        if (Number.isFinite(watcherHbMs)) {
+            const gapMs = watcherHbMs - hbMs;
+            // Task heartbeat is "significantly earlier" than watcher heartbeat when
+            // the task has not heartbeat for at least 2x the stale threshold while
+            // the watcher is alive.
+            if (gapMs > staleThresholdMs * 2 && watcher.status === "healthy") {
+                reasons.push("heartbeat_far_behind_watcher");
+            }
+        }
+    }
+    return { is_stale: reasons.length > 0, stale_reasons: reasons };
+}
+export function augmentTaskWithStale(task, watcher, nowMs = Date.now()) {
+    const cls = classifyStaleTask(task, watcher, nowMs);
+    return { ...task, is_stale: cls.is_stale, stale_reasons: cls.stale_reasons };
+}
+export function listTasksForStatus() {
+    try {
+        const result = listTasks({ limit: 100 });
+        const watcher = result.watcher;
+        const now = Date.now();
+        let active = 0;
+        let stale = 0;
+        const staleTaskIds = [];
+        const augmented = result.tasks.map((t) => {
+            const a = augmentTaskWithStale(t, watcher, now);
+            if (t.status === "pending" || t.status === "running")
+                active++;
+            if (a.is_stale) {
+                stale++;
+                staleTaskIds.push(t.task_id);
+            }
+            return a;
+        });
+        return { tasks: augmented, total: result.total, active, stale, stale_task_ids: staleTaskIds, reason: null };
+    }
+    catch (err) {
+        return { tasks: [], total: 0, active: 0, stale: 0, stale_task_ids: [], reason: errorMessage(err) };
+    }
+}
+export function writeStatusFile() {
+    const status = {
+        pid: process.pid,
+        port,
+        started_at: new Date().toISOString(),
+        url: `http://${host}:${port}/`,
+        version: PATCHWARDEN_VERSION,
+    };
+    try {
+        mkdirSync(getControlCenterLogDir(), { recursive: true });
+        writeFileSync(controlCenterStatusPath, JSON.stringify(status, null, 2), "utf-8");
+    }
+    catch (err) {
+        logger.error("[control-center] Failed to write status file", { error: errorMessage(err) });
+    }
+}
+export function removeStatusFile() {
+    try {
+        if (existsSync(controlCenterStatusPath)) {
+            unlinkSync(controlCenterStatusPath);
+        }
+    }
+    catch (err) {
+        logger.error("[control-center] Failed to remove status file", { error: errorMessage(err) });
+    }
+}
+/**
+ * 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 function recordEvent(type, payload) {
+    const event = {
+        timestamp: new Date().toISOString(),
+        type,
+        payload,
+    };
+    try {
+        mkdirSync(getControlCenterLogDir(), { recursive: true });
+        appendFileSync(controlCenterEventsPath, JSON.stringify(event) + "\n", "utf-8");
+    }
+    catch (err) {
+        logger.error("[control-center] Failed to write event", { error: errorMessage(err) });
+    }
+    // Lazy trim: only when the file grows well past the cap.
+    try {
+        const stat = statSync(controlCenterEventsPath);
+        if (stat.size > 512 * 1024) {
+            trimEventsFile();
+        }
+    }
+    catch {
+        /* ignore */
+    }
+}
+function trimEventsFile() {
+    try {
+        if (!existsSync(controlCenterEventsPath))
+            return;
+        const raw = readFileSync(controlCenterEventsPath, "utf-8");
+        const lines = raw.split(/\r?\n/).filter((l) => l.length > 0);
+        if (lines.length <= MAX_EVENT_LINES)
+            return;
+        const trimmed = lines.slice(lines.length - MAX_EVENT_LINES);
+        writeFileSync(controlCenterEventsPath, trimmed.join("\n") + "\n", "utf-8");
+    }
+    catch (err) {
+        logger.error("[control-center] Failed to trim events file", { error: errorMessage(err) });
+    }
+}
+export function readEvents(limit) {
+    if (!existsSync(controlCenterEventsPath))
+        return [];
+    try {
+        const raw = readFileSync(controlCenterEventsPath, "utf-8");
+        const lines = raw.split(/\r?\n/).filter((l) => l.length > 0);
+        const sliced = lines.slice(Math.max(0, lines.length - limit));
+        const events = [];
+        for (const line of sliced) {
+            try {
+                events.push(JSON.parse(line));
+            }
+            catch {
+                /* skip malformed line */
+            }
+        }
+        return events;
+    }
+    catch {
+        return [];
+    }
+}
+// ── Hidden stale task IDs (local UI state) ────────────────────────
+export function readHiddenStaleIds() {
+    const p = join(getControlCenterLogDir(), "hidden-stale-ids.json");
+    if (!existsSync(p))
+        return [];
+    return readJsonFileSafe(p) || [];
+}
+export function writeHiddenStaleIds(ids) {
+    const dir = getControlCenterLogDir();
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "hidden-stale-ids.json"), JSON.stringify(ids, null, 2));
+}
+// ── Hidden direct session IDs (local UI state) ────────────────────
+export function readHiddenDirectSessionIds() {
+    const p = join(getControlCenterLogDir(), "hidden-direct-session-ids.json");
+    if (!existsSync(p))
+        return [];
+    return readJsonFileSafe(p) || [];
+}
+export function writeHiddenDirectSessionIds(ids) {
+    const dir = getControlCenterLogDir();
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "hidden-direct-session-ids.json"), JSON.stringify(ids, null, 2));
+}
+export function isValidDirectSessionId(sessionId) {
+    // Allow alphanumeric, dash, underscore only — reject path traversal and NUL.
+    return (sessionId.length > 0 &&
+        /^[A-Za-z0-9_-]+$/.test(sessionId) &&
+        !sessionId.includes("\0"));
+}
+export function isValidTaskId(taskId) {
+    return !(taskId === "." ||
+        taskId === ".." ||
+        taskId.includes("/") ||
+        taskId.includes("\\") ||
+        taskId.includes("\0"));
+}
+// ── Small shared helpers ──────────────────────────────────────────
+export function parseReviewVerdict(content) {
+    // independent-review.md format: "**Verdict**: PASS" (case-insensitive)
+    const m = content.match(/\*\*Verdict\*\*\s*:\s*([A-Za-z]+)/);
+    return m ? m[1].toLowerCase() : null;
+}
+export function fileMtimeIso(filePath) {
+    try {
+        const m = statSync(filePath).mtime;
+        return m ? m.toISOString() : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/control/server.d.ts

@@ -0,0 +1,13 @@
+/**
+ * PatchWarden Control Center — HTTP server creation, routing, and lifecycle.
+ *
+ * This module wires together the route handlers (routes/*.ts), middleware
+ * (auth/static), and the shared/runtime helpers. It owns the `handleRequest`
+ * router that dispatches every GET/POST route, the POST control-token gate,
+ * and the server bootstrap/shutdown lifecycle (status file, activity events,
+ * SIGINT/SIGTERM).
+ *
+ * Entry point: `controlCenter.ts` imports `startServer()` from here.
+ */
+import { type Server } from "node:http";
+export declare function startServer(): Server;