patchwarden 1.5.0 → 1.6.1

package/dist/control/runtime.js

@@ -0,0 +1,425 @@
+/**
+ * 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 } from "node:fs";
+import { join } from "node:path";
+import { get as httpGet } from "node:http";
+import { listTasks } from "../tools/tasks/listTasks.js";
+import { listAgents } from "../tools/workspace/listAgents.js";
+import { readWatcherStatus } from "../watcherStatus.js";
+import { resolveWorkspaceRoot } from "../config.js";
+import { PATCHWARDEN_VERSION } from "../version.js";
+import { isValidDirectSessionId as isValidStoredDirectSessionId } from "../direct/directSessionStore.js";
+import { atomicWriteFileSync, atomicWriteJsonFileSync } from "../utils/atomicFile.js";
+import { withFileLockSync } from "../utils/lockedJsonFile.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 });
+        atomicWriteJsonFileSync(controlCenterStatusPath, status);
+    }
+    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 });
+        withFileLockSync(controlCenterEventsPath, () => {
+            appendFileSync(controlCenterEventsPath, JSON.stringify(event) + "\n", "utf-8");
+            const stat = statSync(controlCenterEventsPath);
+            if (stat.size > 512 * 1024)
+                trimEventsFileUnlocked();
+        });
+    }
+    catch (err) {
+        logger.error("[control-center] Failed to write event", { error: errorMessage(err) });
+    }
+}
+function trimEventsFileUnlocked() {
+    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);
+        atomicWriteFileSync(controlCenterEventsPath, trimmed.join("\n") + "\n");
+    }
+    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 readStoredStringArray(p);
+}
+export function reconstructTaskEntry(taskId, statusData, runtimeData = {}, watcher = readWatcherStatusSafe()) {
+    const validAcceptance = new Set(["pending", "accepted", "rejected", "needs_fix", "blocked"]);
+    const taskStatus = String(statusData.status || "pending");
+    const acceptanceStatus = taskStatus === "done_by_agent"
+        ? (typeof statusData.acceptance_status === "string" && validAcceptance.has(statusData.acceptance_status)
+            ? statusData.acceptance_status
+            : "pending")
+        : null;
+    return {
+        task_id: taskId,
+        plan_id: String(statusData.plan_id || ""),
+        title: "",
+        agent: String(statusData.agent || ""),
+        status: taskStatus,
+        phase: String(runtimeData.phase || statusData.phase || "queued"),
+        acceptance_status: acceptanceStatus,
+        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.filter((command) => typeof command === "string")
+            : [],
+        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,
+    };
+}
+export function writeHiddenStaleIds(ids) {
+    const dir = getControlCenterLogDir();
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    atomicWriteJsonFileSync(join(dir, "hidden-stale-ids.json"), normalizeStoredIds(ids));
+}
+// ── Hidden direct session IDs (local UI state) ────────────────────
+export function readHiddenDirectSessionIds() {
+    const p = join(getControlCenterLogDir(), "hidden-direct-session-ids.json");
+    if (!existsSync(p))
+        return [];
+    return readStoredStringArray(p);
+}
+export function writeHiddenDirectSessionIds(ids) {
+    const dir = getControlCenterLogDir();
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    atomicWriteJsonFileSync(join(dir, "hidden-direct-session-ids.json"), normalizeStoredIds(ids));
+}
+export function isValidDirectSessionId(sessionId) {
+    return isValidStoredDirectSessionId(sessionId);
+}
+export function isValidTaskId(taskId) {
+    return /^[A-Za-z0-9][A-Za-z0-9_-]{0,159}$/.test(taskId);
+}
+function readStoredStringArray(path) {
+    const value = readJsonFileSafe(path);
+    if (!Array.isArray(value))
+        return [];
+    return normalizeStoredIds(value);
+}
+function normalizeStoredIds(value) {
+    return [...new Set(value.filter((entry) => typeof entry === "string" && entry.length > 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;

package/dist/control/server.js

@@ -0,0 +1,150 @@
+/**
+ * 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 { createServer } from "node:http";
+import { PATCHWARDEN_VERSION, TOOL_SCHEMA_EPOCH } from "../version.js";
+import { logger } from "../logging.js";
+import { config, controlToken, errorMessage, host, PAGE_ALIASES, port, readBody, sendJson, } from "./shared.js";
+import { recordEvent, removeStatusFile, writeStatusFile } from "./runtime.js";
+import { checkControlToken, isTrustedControlHost } from "./middleware/auth.js";
+import { serveFavicon, serveStatic } from "./middleware/static.js";
+import { buildRoutes } from "./routeTable.js";
+// ── Request router ────────────────────────────────────────────────
+async function handleRequest(req, res) {
+    res.setHeader("Content-Security-Policy", "frame-ancestors 'none'");
+    res.setHeader("Cross-Origin-Resource-Policy", "same-origin");
+    res.setHeader("Referrer-Policy", "no-referrer");
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    res.setHeader("X-Frame-Options", "DENY");
+    if (!isTrustedControlHost(req, port)) {
+        sendJson(res, 421, { error: "Untrusted Host header" });
+        return;
+    }
+    const parsedUrl = new URL(req.url || "/", `http://${host}:${port}`);
+    const pathname = parsedUrl.pathname;
+    const method = (req.method || "GET").toUpperCase();
+    // ── Static resource priority branches (not in routeTable.ts) ──
+    if (method === "GET" && pathname === "/") {
+        serveStatic(res, "pages/dashboard.html");
+        return;
+    }
+    const pageAlias = PAGE_ALIASES[pathname];
+    if (method === "GET" && pageAlias) {
+        serveStatic(res, pageAlias);
+        return;
+    }
+    if (method === "GET" && pathname === "/control-token.json") {
+        sendJson(res, 200, { token: controlToken });
+        return;
+    }
+    if (method === "GET" && pathname === "/favicon.ico") {
+        serveFavicon(res);
+        return;
+    }
+    if (method === "GET" &&
+        (pathname === "/colors_and_type.css" ||
+            pathname === "/desktop.css" ||
+            pathname === "/desktop-bridge.js" ||
+            pathname === "/i18n.js" ||
+            pathname === "/getting-started.js" ||
+            pathname === "/settings.js" ||
+            pathname.startsWith("/pages/") ||
+            pathname.startsWith("/partials/") ||
+            pathname.startsWith("/vendor/"))) {
+        serveStatic(res, pathname);
+        return;
+    }
+    // ── POST routes: drain body + verify control token before dispatch ──
+    // All POST routes in the table declare `requiresToken: true`; the body is
+    // drained up-front so HTTP keep-alive connections stay clean even when the
+    // route is unknown (preserving the original handleRequest behavior).
+    if (method === "POST") {
+        await readBody(req);
+        if (!checkControlToken(req)) {
+            sendJson(res, 403, { error: "Missing or invalid control token" });
+            return;
+        }
+    }
+    // ── Declarative route table dispatch ──
+    // Filter by method → match pattern (in declaration order, so specific
+    // patterns win over generic `:id`) → call handler with capture-group slice.
+    const routes = buildRoutes(parsedUrl);
+    for (const route of routes) {
+        if (route.method !== method)
+            continue;
+        const match = pathname.match(route.pattern);
+        if (!match)
+            continue;
+        await route.handler(res, match.slice(1));
+        return;
+    }
+    sendJson(res, 404, { error: "Not found" });
+}
+// ── Server bootstrap ──────────────────────────────────────────────
+let server = null;
+export function startServer() {
+    server = createServer((req, res) => {
+        handleRequest(req, res).catch((err) => {
+            if (!res.headersSent) {
+                sendJson(res, 500, { error: errorMessage(err) });
+            }
+            else {
+                try {
+                    res.end();
+                }
+                catch { /* ignore */ }
+            }
+        });
+    });
+    server.on("error", (err) => {
+        logger.fatal("[control-center] Server error", { error: errorMessage(err) });
+        process.exit(1);
+    });
+    server.listen(port, host, () => {
+        const addr = server.address();
+        const formatted = addr && typeof addr === "object" ? `http://${addr.address}:${addr.port}/` : `http://${host}:${port}/`;
+        logger.info(`[control-center] PatchWarden v${PATCHWARDEN_VERSION} (schema epoch ${TOOL_SCHEMA_EPOCH})`);
+        logger.info(`[control-center] Workspace: ${config.workspaceRoot}`);
+        logger.info(`[control-center] Listening: ${formatted}`);
+        logger.info(`[control-center] Bound to 127.0.0.1 only — not exposed to network`);
+        // Persist status file so the launcher can detect a running instance and
+        // open the browser without spawning a second server.
+        writeStatusFile();
+        recordEvent("control_center.started", {
+            pid: process.pid,
+            port,
+            url: formatted,
+            version: PATCHWARDEN_VERSION,
+        });
+    });
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    return server;
+}
+function shutdown() {
+    logger.info("[control-center] Shutting down...");
+    recordEvent("control_center.stopped", { pid: process.pid });
+    removeStatusFile();
+    if (server) {
+        server.close(() => {
+            try {
+                process.exit(0);
+            }
+            catch { /* ignore */ }
+        });
+    }
+    setTimeout(() => {
+        try {
+            process.exit(0);
+        }
+        catch { /* ignore */ }
+    }, 3000).unref();
+}

package/dist/control/shared.d.ts

@@ -0,0 +1,59 @@
+import { delimiter, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { type PatchWardenConfig } from "../config.js";
+export declare const projectRoot: string;
+export declare const uiRoot: string;
+export declare const manageScriptPath: string;
+export declare const activeConfigPath: string;
+export declare const configIdentitySha256: string;
+export declare const PAGE_ALIASES: Record<string, string>;
+export declare function createFallbackConfig(): PatchWardenConfig;
+export declare let config: PatchWardenConfig;
+export declare const controlToken: `${string}-${string}-${string}-${string}-${string}`;
+export declare function resolvePort(): number;
+export declare const port: number;
+export declare const host = "127.0.0.1";
+export declare const CORE_BASE_URL: string;
+export declare const DIRECT_BASE_URL: string;
+export declare const CONTROL_CENTER_FAVICON = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 64 64\">\n  <rect width=\"64\" height=\"64\" rx=\"14\" fill=\"#0a0e14\"/>\n  <path d=\"M32 52s17-8 17-27V14L32 8 15 14v11c0 19 17 27 17 27z\" fill=\"#111820\" stroke=\"#2dd4a8\" stroke-width=\"4\" stroke-linejoin=\"round\"/>\n  <path d=\"M24 32l6 6 12-14\" fill=\"none\" stroke=\"#2dd4a8\" stroke-width=\"5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n</svg>";
+export declare function errorMessage(err: unknown): string;
+export declare function getRuntimeRoot(direct: boolean): string;
+export declare function getControlCenterLogDir(): string;
+export declare const controlCenterStatusPath: string;
+export declare const controlCenterEventsPath: string;
+export declare const MAX_EVENT_LINES = 2000;
+export declare const ALLOWED_LOG_TAILS: Set<number>;
+export declare function resolveTailParam(value: string | null): number;
+export declare const CONTENT_TYPES: Record<string, string>;
+export declare function sendJson(res: ServerResponse, status: number, body: unknown): void;
+export declare function readBody(req: IncomingMessage): Promise<unknown | null>;
+export declare function readJsonFileSafe<T = unknown>(filePath: string): T | null;
+export declare function isPathInside(root: string, target: string): boolean;
+export declare function readJsonFileSafeUnder<T = unknown>(root: string, relPath: string): T | null;
+export declare function readTextFileSafe(filePath: string): string | null;
+/** Resolve a Control Center artifact path and reject symlink/junction escapes. */
+export declare function guardControlPath(path: string, allowedPrefix: string): string | null;
+export declare function readFileTail(filePath: string, lines?: number): string;
+export declare function findLatestLog(dir: string, pattern: RegExp): string | null;
+/**
+ * Declarative route descriptor consumed by `routeTable.ts` and dispatched by
+ * `server.ts`'s `handleRequest`. The handler receives the slice of path
+ * capture groups `[match[1], match[2], ...]` so wrappers can decode them via
+ * `decodeParam`. POST routes default to `requiresToken: true`.
+ */
+export interface Route {
+    method: "GET" | "POST";
+    pattern: RegExp;
+    handler: (res: ServerResponse, params: string[]) => Promise<void> | void;
+    requiresToken?: boolean;
+}
+/**
+ * Safely decode a path capture group, falling back to the raw value if the
+ * percent-encoding is malformed. Accepts the raw `RegExpMatchArray` or the
+ * sliced `string[]` params passed to a Route handler — both are readable by
+ * numeric index. Note: under `lib: es2024+` `RegExpMatchArray` is a tuple
+ * `[string, ...string[]]`, so we widen the parameter to `readonly string[]` to
+ * accept both shapes without forcing callers to cast.
+ */
+export declare function decodeParam(match: readonly string[] | RegExpMatchArray | null, index: number): string;
+export { delimiter, extname, join, resolve, isAbsolute, relative };