patchwarden 1.5.0 → 1.6.1

package/dist/config.js

@@ -1,5 +1,6 @@
 import { readFileSync, existsSync } from "node:fs";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+import { validateWorkspaceRoot } from "./security/workspaceRootGuard.js";
 // ── Defaults ──────────────────────────────────────────────────────
 const DEFAULT_CONFIG = {
     workspaceRoot: process.cwd(),
@@ -7,16 +8,7 @@ const DEFAULT_CONFIG = {
     tasksDir: ".patchwarden/tasks",
     assessmentsDir: ".patchwarden/assessments",
     assessmentTtlSeconds: 3600,
-    agents: {
-        codex: {
-            command: "codex",
-            args: ["exec", "--cd", "{repo}", "{prompt}"],
-        },
-        opencode: {
-            command: "opencode",
-            args: ["run", "{prompt}"],
-        },
-    },
+    agents: {},
     allowedTestCommands: [
         "npm test",
         "npm run test",
@@ -123,6 +115,11 @@ function normalizeConfig(config) {
     if (!config.workspaceRoot || typeof config.workspaceRoot !== "string") {
         throw new Error("workspaceRoot must be a non-empty string");
     }
+    const workspaceValidation = validateWorkspaceRoot(config.workspaceRoot);
+    if (!workspaceValidation.ok) {
+        throw new Error(`Invalid workspaceRoot: ${workspaceValidation.reason} (${workspaceValidation.path})`);
+    }
+    config.workspaceRoot = workspaceValidation.path;
     if (!config.plansDir || typeof config.plansDir !== "string") {
         throw new Error("plansDir must be a non-empty string");
     }
@@ -138,6 +135,21 @@ function normalizeConfig(config) {
     if (!config.agents || typeof config.agents !== "object") {
         throw new Error("agents must be an object");
     }
+    const agents = {};
+    for (const [agentName, agent] of Object.entries(config.agents)) {
+        if (!agent || typeof agent !== "object" || typeof agent.command !== "string" || !Array.isArray(agent.args)) {
+            throw new Error(`agents["${agentName}"] must define command and args`);
+        }
+        const envAllowlist = agent.envAllowlist ?? [];
+        if (!Array.isArray(envAllowlist) || envAllowlist.some((name) => typeof name !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))) {
+            throw new Error(`agents["${agentName}"].envAllowlist must contain only environment variable names`);
+        }
+        const blockedNames = new Set(["CONTROL_PLANE_API_KEY", "PATCHWARDEN_OWNER_TOKEN", config.http?.ownerTokenEnv?.toUpperCase()]);
+        const blocked = envAllowlist.find((name) => blockedNames.has(name.toUpperCase()));
+        if (blocked)
+            throw new Error(`agents["${agentName}"].envAllowlist cannot include reserved variable "${blocked}"`);
+        agents[agentName] = { ...agent, args: [...agent.args], envAllowlist: [...new Set(envAllowlist)] };
+    }
     if (!Array.isArray(config.allowedTestCommands)) {
         throw new Error("allowedTestCommands must be an array");
     }
@@ -182,6 +194,42 @@ function normalizeConfig(config) {
         config.toolProfile !== "chatgpt_search") {
         throw new Error('toolProfile must be "full", "chatgpt_core", "chatgpt_direct", or "chatgpt_search"');
     }
+    if (config.repoAliases !== undefined) {
+        if (typeof config.repoAliases !== "object" || config.repoAliases === null || Array.isArray(config.repoAliases)) {
+            throw new Error("repoAliases must be an object mapping alias names to repository paths");
+        }
+        for (const [alias, target] of Object.entries(config.repoAliases)) {
+            if (typeof target !== "string") {
+                throw new Error(`repoAliases["${alias}"] must be a string`);
+            }
+        }
+    }
+    if (config.httpPort !== undefined) {
+        if (typeof config.httpPort !== "number" || !Number.isInteger(config.httpPort) || config.httpPort < 1 || config.httpPort > 65535) {
+            throw new Error("httpPort must be an integer from 1 to 65535");
+        }
+    }
+    if (config.http !== undefined) {
+        if (typeof config.http !== "object" || config.http === null || Array.isArray(config.http)) {
+            throw new Error("http must be an object");
+        }
+        if (config.http.port !== undefined) {
+            if (typeof config.http.port !== "number" || !Number.isInteger(config.http.port) || config.http.port < 1 || config.http.port > 65535) {
+                throw new Error("http.port must be an integer from 1 to 65535");
+            }
+        }
+        if (config.http.host !== undefined && typeof config.http.host !== "string") {
+            throw new Error("http.host must be a string");
+        }
+        if (config.http.ownerTokenEnv !== undefined
+            && (typeof config.http.ownerTokenEnv !== "string"
+                || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(config.http.ownerTokenEnv))) {
+            throw new Error("http.ownerTokenEnv must be a valid environment variable name");
+        }
+    }
+    if (config.enableRunTaskTool !== undefined && typeof config.enableRunTaskTool !== "boolean") {
+        throw new Error("enableRunTaskTool must be a boolean");
+    }
     if (config.enableAgentAssessment !== undefined && typeof config.enableAgentAssessment !== "boolean") {
         throw new Error("enableAgentAssessment must be a boolean");
     }
@@ -201,6 +249,44 @@ function normalizeConfig(config) {
     if (config.enableDirectProfile !== undefined && typeof config.enableDirectProfile !== "boolean") {
         throw new Error("enableDirectProfile must be a boolean");
     }
+    if (config.tunnelClientPath !== undefined) {
+        if (typeof config.tunnelClientPath !== "string" || !isAbsolute(config.tunnelClientPath)) {
+            throw new Error("tunnelClientPath must be an absolute path");
+        }
+        if (basename(config.tunnelClientPath).toLowerCase() !== "tunnel-client.exe") {
+            throw new Error("tunnelClientPath must point to tunnel-client.exe");
+        }
+    }
+    if (config.tunnelProxy !== undefined) {
+        if (!config.tunnelProxy || typeof config.tunnelProxy !== "object" || !["shared", "separate"].includes(config.tunnelProxy.scope)) {
+            throw new Error("tunnelProxy.scope must be shared or separate");
+        }
+        for (const key of ["core", "direct"]) {
+            const endpoint = config.tunnelProxy[key];
+            if (!endpoint || typeof endpoint !== "object" || !["environment", "none", "manual"].includes(endpoint.mode)) {
+                throw new Error(`tunnelProxy.${key}.mode must be environment, none, or manual`);
+            }
+            if (endpoint.mode === "manual") {
+                if (typeof endpoint.url !== "string")
+                    throw new Error(`tunnelProxy.${key}.url is required in manual mode`);
+                let parsed;
+                try {
+                    parsed = new URL(endpoint.url);
+                }
+                catch {
+                    throw new Error(`tunnelProxy.${key}.url must be a valid URL`);
+                }
+                if (!["http:", "https:", "socks5:"].includes(parsed.protocol)) {
+                    throw new Error(`tunnelProxy.${key}.url must use http, https, or socks5`);
+                }
+                if (parsed.username || parsed.password)
+                    throw new Error(`tunnelProxy.${key}.url must not contain credentials`);
+            }
+            else if (endpoint.url !== undefined) {
+                throw new Error(`tunnelProxy.${key}.url is only allowed in manual mode`);
+            }
+        }
+    }
     if (!config.directSessionsDir || typeof config.directSessionsDir !== "string") {
         throw new Error("directSessionsDir must be a non-empty string");
     }
@@ -242,6 +328,7 @@ function normalizeConfig(config) {
     }
     return {
         ...config,
+        agents,
         workspaceRoot: resolve(config.workspaceRoot),
         allowedTestCommands: [...new Set(config.allowedTestCommands.map((command) => command.trim()))],
         repoAllowedTestCommands,

package/dist/control/fileManager.d.ts

@@ -0,0 +1,2 @@
+/** Launch a trusted platform file manager without inheriting ambient secrets. */
+export declare function launchFileManager(target: string, cwd: string): boolean;

package/dist/control/fileManager.js

@@ -0,0 +1,39 @@
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { buildChildEnvironment, resolveTrustedExecutable } from "../runner/processSecurity.js";
+const FILE_MANAGER_ENVIRONMENT = [
+    "DISPLAY",
+    "WAYLAND_DISPLAY",
+    "DBUS_SESSION_BUS_ADDRESS",
+    "XDG_RUNTIME_DIR",
+];
+/** Launch a trusted platform file manager without inheriting ambient secrets. */
+export function launchFileManager(target, cwd) {
+    try {
+        const env = buildChildEnvironment({ cwd, allowedNames: FILE_MANAGER_ENVIRONMENT });
+        const requested = fileManagerCommand(env);
+        const command = resolveTrustedExecutable(requested, cwd, { pathValue: env.PATH });
+        const child = spawn(command, [target], {
+            cwd,
+            detached: true,
+            env,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        child.on("error", () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function fileManagerCommand(env) {
+    if (process.platform === "win32") {
+        const windowsRoot = env.SystemRoot || env.WINDIR;
+        return windowsRoot ? join(windowsRoot, "explorer.exe") : "explorer.exe";
+    }
+    if (process.platform === "darwin")
+        return "open";
+    return "xdg-open";
+}

package/dist/control/middleware/auth.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Control Center auth middleware — control token validation.
+ *
+ * POST routes are gated behind an in-memory control token generated at boot.
+ * The token is exposed read-only via GET /control-token.json (handled by the
+ * server router) so the local dashboard can read it, but every mutating
+ * action must pass through `checkControlToken` first.
+ */
+import { type IncomingMessage } from "node:http";
+export declare function checkControlToken(req: IncomingMessage): boolean;
+/**
+ * Reject non-loopback Host headers before exposing the browser-readable
+ * control token. Binding to 127.0.0.1 alone does not prevent DNS rebinding.
+ */
+export declare function isTrustedControlHost(req: IncomingMessage, expectedPort: number): boolean;
+export declare function isTrustedControlHostHeader(value: string | string[] | undefined, expectedPort: number): boolean;

package/dist/control/middleware/auth.js

@@ -0,0 +1,17 @@
+import { firstHeaderValue, timingSafeStringEqual } from "../../security/secretComparison.js";
+import { isTrustedLoopbackHostHeader } from "../../security/loopbackHost.js";
+import { controlToken } from "../shared.js";
+export function checkControlToken(req) {
+    const provided = firstHeaderValue(req.headers["x-patchwarden-control-token"]);
+    return provided.length > 0 && timingSafeStringEqual(provided, controlToken);
+}
+/**
+ * Reject non-loopback Host headers before exposing the browser-readable
+ * control token. Binding to 127.0.0.1 alone does not prevent DNS rebinding.
+ */
+export function isTrustedControlHost(req, expectedPort) {
+    return isTrustedControlHostHeader(req.headers.host, expectedPort);
+}
+export function isTrustedControlHostHeader(value, expectedPort) {
+    return isTrustedLoopbackHostHeader(value, expectedPort);
+}

package/dist/control/middleware/static.d.ts

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

package/dist/control/middleware/static.js

@@ -0,0 +1,78 @@
+/**
+ * Control Center static file middleware.
+ *
+ * Serves the bundled `ui/` directory (dashboard pages, partials, vendor
+ * assets, css) with path-traversal protection, plus the inline SVG favicon.
+ * Content types are mapped from `CONTENT_TYPES` in shared.ts.
+ */
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { extname, isAbsolute, relative, resolve } from "node:path";
+import { CONTENT_TYPES, CONTROL_CENTER_FAVICON, errorMessage, sendJson, uiRoot, } from "../shared.js";
+export function serveStatic(res, urlPath) {
+    let candidate = "";
+    try {
+        const normalized = urlPath.startsWith("/") ? urlPath.slice(1) : urlPath;
+        let decoded;
+        try {
+            decoded = decodeURIComponent(normalized);
+        }
+        catch {
+            sendJson(res, 400, { error: "Invalid path encoding" });
+            return;
+        }
+        if (decoded.includes("\0")) {
+            sendJson(res, 400, { error: "Invalid path" });
+            return;
+        }
+        const segments = decoded.split("/").filter(Boolean);
+        if (segments.some((s) => s === "..")) {
+            sendJson(res, 403, { error: "Forbidden" });
+            return;
+        }
+        candidate = resolve(uiRoot, ...segments);
+        const rel = relative(uiRoot, candidate);
+        if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+            sendJson(res, 403, { error: "Forbidden" });
+            return;
+        }
+    }
+    catch (err) {
+        sendJson(res, 500, { error: errorMessage(err) });
+        return;
+    }
+    try {
+        if (!existsSync(candidate) || !statSync(candidate).isFile()) {
+            sendJson(res, 404, { error: "Not found" });
+            return;
+        }
+        // Resolve links before reading. Lexical `..` checks alone do not stop a
+        // symlink or junction inside `ui/` from pointing outside the bundle.
+        const realRoot = realpathSync(uiRoot);
+        const realCandidate = realpathSync(candidate);
+        const realRelative = relative(realRoot, realCandidate);
+        if (realRelative === "" || realRelative.startsWith("..") || isAbsolute(realRelative)) {
+            sendJson(res, 403, { error: "Forbidden" });
+            return;
+        }
+        if (!statSync(realCandidate).isFile()) {
+            sendJson(res, 404, { error: "Not found" });
+            return;
+        }
+        const ext = extname(realCandidate).toLowerCase();
+        const contentType = CONTENT_TYPES[ext] || "application/octet-stream";
+        const content = readFileSync(realCandidate);
+        res.writeHead(200, { "Content-Type": contentType });
+        res.end(content);
+    }
+    catch (err) {
+        sendJson(res, 500, { error: errorMessage(err) });
+    }
+}
+export function serveFavicon(res) {
+    res.writeHead(200, {
+        "Content-Type": "image/svg+xml; charset=utf-8",
+        "Cache-Control": "public, max-age=86400",
+        "X-Content-Type-Options": "nosniff",
+    });
+    res.end(CONTROL_CENTER_FAVICON);
+}

package/dist/control/routeTable.d.ts

@@ -0,0 +1,24 @@
+/**
+ * PatchWarden Control Center — declarative route table.
+ *
+ * Exports `buildRoutes(parsedUrl)` which returns the full `Route[]` array
+ * consumed by `server.ts`'s `handleRequest`. Routes that need query-string
+ * parameters (e.g. `/api/tasks`, `/api/logs/:category`) close over `parsedUrl`
+ * via the `query` helper, so each request gets its own self-contained table
+ * without module-scoped request state. This keeps concurrent requests safe.
+ *
+ * Ordering rules:
+ *   - GET routes first, POST routes second.
+ *   - Within each method, more specific patterns precede generic `:id`
+ *     patterns (e.g. `/api/tasks/stale` before `/api/tasks/:id`).
+ *   - Static asset routes (`/`, `/favicon.ico`, CSS/JS, `/pages/`,
+ *     `/partials/`, `/vendor/`) and `/control-token.json` are NOT in this
+ *     table — they remain priority branches in `server.ts`.
+ */
+import { type Route } from "./shared.js";
+/**
+ * Build the per-request `Route[]` table. `parsedUrl` is captured by closures
+ * so handlers that need query parameters can read `searchParams` without any
+ * module-scoped state.
+ */
+export declare function buildRoutes(parsedUrl: URL): Route[];

package/dist/control/routeTable.js

@@ -0,0 +1,263 @@
+/**
+ * PatchWarden Control Center — declarative route table.
+ *
+ * Exports `buildRoutes(parsedUrl)` which returns the full `Route[]` array
+ * consumed by `server.ts`'s `handleRequest`. Routes that need query-string
+ * parameters (e.g. `/api/tasks`, `/api/logs/:category`) close over `parsedUrl`
+ * via the `query` helper, so each request gets its own self-contained table
+ * without module-scoped request state. This keeps concurrent requests safe.
+ *
+ * Ordering rules:
+ *   - GET routes first, POST routes second.
+ *   - Within each method, more specific patterns precede generic `:id`
+ *     patterns (e.g. `/api/tasks/stale` before `/api/tasks/:id`).
+ *   - Static asset routes (`/`, `/favicon.ico`, CSS/JS, `/pages/`,
+ *     `/partials/`, `/vendor/`) and `/control-token.json` are NOT in this
+ *     table — they remain priority branches in `server.ts`.
+ */
+import { decodeParam, resolveTailParam, sendJson } from "./shared.js";
+import { isValidTaskId } from "./runtime.js";
+import { handleTasks, handleStaleTasks, handleTaskDetail, handleTaskSafeResult, handleTaskSafeAudit, handleTaskSafeTestSummary, handleTaskSafeDiffSummary, } from "./routes/tasks.js";
+import { handleReconcile, handleTaskAudit, handleOpenTaskFolder, handleHideStale, } from "./routes/taskActions.js";
+import { handleDirectSessions, handleDirectSessionDetail, handleDirectSessionSafeSummary, handleDirectSessionFinalize, handleDirectSessionAudit, handleDirectSessionHide, } from "./routes/sessions.js";
+import { handleLineages, handleLineageDetail } from "./routes/lineage.js";
+import { handleEvidencePacks, handleEvidencePackDetail, handleEvidencePackExport, } from "./routes/evidence.js";
+import { handleProjectPolicy, handleReleaseStatus } from "./routes/policy.js";
+import { handleWorkspace, handleWorkspaceRepos, handleWorkspaceRepoStatus, } from "./routes/workspace.js";
+import { handleManageAction, handleOpenLogsFolder } from "./routes/process.js";
+import { handleStatus, handleControlCenterStatus, handleEvents, handleTunnelUiUrl, handleDiagnostics, } from "./routes/status.js";
+import { handleLogs, handleAudit, handleWarnings } from "./routes/audit.js";
+const KNOWN_LOG_CATEGORIES = new Set([
+    "core",
+    "direct",
+    "watcher",
+    "control-center",
+]);
+/**
+ * Build the per-request `Route[]` table. `parsedUrl` is captured by closures
+ * so handlers that need query parameters can read `searchParams` without any
+ * module-scoped state.
+ */
+export function buildRoutes(parsedUrl) {
+    const query = parsedUrl.searchParams;
+    // ── GET routes (no token required) ──────────────────────────────
+    const getRoutes = [
+        { method: "GET", pattern: /^\/api\/status$/, handler: (res) => handleStatus(res) },
+        {
+            method: "GET",
+            pattern: /^\/api\/tasks$/,
+            handler: (res) => handleTasks(res, {
+                repo_path: query.get("repo_path") || undefined,
+                status: query.get("status") || undefined,
+                acceptance_status: query.get("acceptance_status") || undefined,
+                agent: query.get("agent") || undefined,
+                warning_type: query.get("warning_type") || undefined,
+                date_from: query.get("date_from") || undefined,
+                date_to: query.get("date_to") || undefined,
+                limit: query.get("limit") ? Number(query.get("limit")) : undefined,
+                cursor: query.get("cursor") || undefined,
+            }),
+        },
+        // /api/tasks/stale MUST precede /api/tasks/:id (stale matches the :id pattern).
+        { method: "GET", pattern: /^\/api\/tasks\/stale$/, handler: (res) => handleStaleTasks(res) },
+        { method: "GET", pattern: /^\/api\/lineages$/, handler: (res) => handleLineages(res) },
+        {
+            method: "GET",
+            pattern: /^\/api\/lineages\/([^/]+)$/,
+            handler: (res, p) => handleLineageDetail(res, decodeParam(p, 0)),
+        },
+        {
+            method: "GET",
+            pattern: /^\/api\/project-policy$/,
+            handler: (res) => handleProjectPolicy(res, query.get("repo_path") || "."),
+        },
+        {
+            method: "GET",
+            pattern: /^\/api\/release\/status$/,
+            handler: (res) => handleReleaseStatus(res, query.get("repo_path") || "."),
+        },
+        { method: "GET", pattern: /^\/api\/evidence-packs$/, handler: (res) => handleEvidencePacks(res) },
+        {
+            method: "GET",
+            pattern: /^\/api\/evidence-packs\/([^/]+)$/,
+            handler: (res, p) => handleEvidencePackDetail(res, decodeParam(p, 0)),
+        },
+        {
+            method: "GET",
+            pattern: /^\/api\/tasks\/([^/]+)$/,
+            handler: (res, p) => {
+                const taskId = decodeParam(p, 0);
+                if (!isValidTaskId(taskId)) {
+                    sendJson(res, 400, { error: "Invalid task id" });
+                    return;
+                }
+                handleTaskDetail(res, taskId);
+            },
+        },
+        // Safe, bounded views for task artifacts (no full stdout/stderr/diff).
+        {
+            method: "GET",
+            pattern: /^\/api\/tasks\/([^/]+)\/safe-result$/,
+            handler: (res, p) => handleTaskSafeResult(res, decodeParam(p, 0)),
+        },
+        {
+            method: "GET",
+            pattern: /^\/api\/tasks\/([^/]+)\/safe-audit$/,
+            handler: (res, p) => handleTaskSafeAudit(res, decodeParam(p, 0)),
+        },
+        {
+            method: "GET",
+            pattern: /^\/api\/tasks\/([^/]+)\/safe-test-summary$/,
+            handler: (res, p) => handleTaskSafeTestSummary(res, decodeParam(p, 0)),
+        },
+        {
+            method: "GET",
+            pattern: /^\/api\/tasks\/([^/]+)\/safe-diff-summary$/,
+            handler: (res, p) => handleTaskSafeDiffSummary(res, decodeParam(p, 0)),
+        },
+        // /api/logs/<category>?tail=<100|300|1000>
+        {
+            method: "GET",
+            pattern: /^\/api\/logs\/([a-z-]+)$/,
+            handler: (res, p) => {
+                const rawCat = p[0] || "";
+                const category = KNOWN_LOG_CATEGORIES.has(rawCat)
+                    ? rawCat
+                    : null;
+                if (!category) {
+                    sendJson(res, 404, { error: "Unknown log category" });
+                    return;
+                }
+                const tail = resolveTailParam(query.get("tail"));
+                handleLogs(res, category, tail);
+            },
+        },
+        { method: "GET", pattern: /^\/api\/workspace$/, handler: (res) => handleWorkspace(res) },
+        // /api/workspace/repos MUST precede /api/workspace/:repo+/status (no segment conflict,
+        // but preserved for ordering clarity).
+        { method: "GET", pattern: /^\/api\/workspace\/repos$/, handler: (res) => handleWorkspaceRepos(res) },
+        {
+            method: "GET",
+            pattern: /^\/api\/workspace\/([^/]+(?:\/[^/]+)*)\/status$/,
+            handler: (res, p) => {
+                const raw = p[0] || "";
+                let repoParam;
+                try {
+                    repoParam = decodeURIComponent(raw);
+                }
+                catch {
+                    sendJson(res, 400, { error: "Invalid repo path encoding" });
+                    return;
+                }
+                handleWorkspaceRepoStatus(res, repoParam);
+            },
+        },
+        {
+            method: "GET",
+            pattern: /^\/api\/direct-sessions$/,
+            handler: (res) => handleDirectSessions(res, {
+                state: (query.get("state") || undefined),
+                repo_path: query.get("repo_path") || undefined,
+                date_from: query.get("date_from") || undefined,
+                date_to: query.get("date_to") || undefined,
+                limit: query.get("limit") ? Number(query.get("limit")) : undefined,
+                cursor: query.get("cursor") || undefined,
+            }),
+        },
+        // /api/direct-sessions/:id/summary MUST precede /api/direct-sessions/:id.
+        {
+            method: "GET",
+            pattern: /^\/api\/direct-sessions\/([^/]+)\/summary$/,
+            handler: (res, p) => handleDirectSessionSafeSummary(res, decodeParam(p, 0)),
+        },
+        {
+            method: "GET",
+            pattern: /^\/api\/direct-sessions\/([^/]+)$/,
+            handler: (res, p) => handleDirectSessionDetail(res, decodeParam(p, 0)),
+        },
+        { method: "GET", pattern: /^\/api\/audit$/, handler: (res) => handleAudit(res) },
+        { method: "GET", pattern: /^\/api\/warnings$/, handler: (res) => handleWarnings(res) },
+        { method: "GET", pattern: /^\/api\/diagnostics$/, handler: (res) => handleDiagnostics(res) },
+        { method: "GET", pattern: /^\/api\/tunnel-ui-url$/, handler: (res) => handleTunnelUiUrl(res) },
+        {
+            method: "GET",
+            pattern: /^\/api\/events$/,
+            handler: (res) => {
+                const limitParam = query.get("limit");
+                let limit = 100;
+                if (limitParam !== null) {
+                    const n = parseInt(limitParam, 10);
+                    if (Number.isFinite(n) && n > 0 && n <= 1000)
+                        limit = n;
+                }
+                handleEvents(res, limit);
+            },
+        },
+        {
+            method: "GET",
+            pattern: /^\/api\/control-center-status$/,
+            handler: (res) => handleControlCenterStatus(res),
+        },
+    ];
+    // ── POST routes (requiresToken: true) ──────────────────────────
+    const postRoutes = [
+        { method: "POST", pattern: /^\/api\/start-all$/, requiresToken: true, handler: (res) => handleManageAction(res, "start", "all") },
+        { method: "POST", pattern: /^\/api\/stop-all$/, requiresToken: true, handler: (res) => handleManageAction(res, "stop", "all") },
+        { method: "POST", pattern: /^\/api\/restart-all$/, requiresToken: true, handler: (res) => handleManageAction(res, "restart", "all") },
+        { method: "POST", pattern: /^\/api\/core\/start$/, requiresToken: true, handler: (res) => handleManageAction(res, "start", "core") },
+        { method: "POST", pattern: /^\/api\/core\/stop$/, requiresToken: true, handler: (res) => handleManageAction(res, "stop", "core") },
+        { method: "POST", pattern: /^\/api\/direct\/start$/, requiresToken: true, handler: (res) => handleManageAction(res, "start", "direct") },
+        { method: "POST", pattern: /^\/api\/direct\/stop$/, requiresToken: true, handler: (res) => handleManageAction(res, "stop", "direct") },
+        { method: "POST", pattern: /^\/api\/open-logs-folder$/, requiresToken: true, handler: (res) => handleOpenLogsFolder(res) },
+        // /api/direct-sessions/:id/finalize MUST precede any generic /api/direct-sessions/:id pattern.
+        {
+            method: "POST",
+            pattern: /^\/api\/direct-sessions\/([^/]+)\/finalize$/,
+            requiresToken: true,
+            handler: (res, p) => handleDirectSessionFinalize(res, decodeParam(p, 0)),
+        },
+        {
+            method: "POST",
+            pattern: /^\/api\/direct-sessions\/([^/]+)\/audit$/,
+            requiresToken: true,
+            handler: (res, p) => handleDirectSessionAudit(res, decodeParam(p, 0)),
+        },
+        {
+            method: "POST",
+            pattern: /^\/api\/direct-sessions\/([^/]+)\/hide$/,
+            requiresToken: true,
+            handler: (res, p) => handleDirectSessionHide(res, decodeParam(p, 0)),
+        },
+        {
+            method: "POST",
+            pattern: /^\/api\/tasks\/([^/]+)\/reconcile$/,
+            requiresToken: true,
+            handler: (res, p) => handleReconcile(res, decodeParam(p, 0)),
+        },
+        {
+            method: "POST",
+            pattern: /^\/api\/tasks\/([^/]+)\/audit$/,
+            requiresToken: true,
+            handler: (res, p) => handleTaskAudit(res, decodeParam(p, 0)),
+        },
+        {
+            method: "POST",
+            pattern: /^\/api\/tasks\/([^/]+)\/open-folder$/,
+            requiresToken: true,
+            handler: (res, p) => handleOpenTaskFolder(res, decodeParam(p, 0)),
+        },
+        {
+            method: "POST",
+            pattern: /^\/api\/tasks\/([^/]+)\/hide-stale$/,
+            requiresToken: true,
+            handler: (res, p) => handleHideStale(res, decodeParam(p, 0)),
+        },
+        {
+            method: "POST",
+            pattern: /^\/api\/evidence-packs\/([^/]+)\/export$/,
+            requiresToken: true,
+            handler: (res, p) => handleEvidencePackExport(res, decodeParam(p, 0)),
+        },
+    ];
+    return [...getRoutes, ...postRoutes];
+}

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

@@ -0,0 +1,15 @@
+import { type ServerResponse } from "node:http";
+export type LogCategory = "core" | "direct" | "watcher" | "control-center";
+export declare function handleLogs(res: ServerResponse, category: LogCategory, tailLines: number): void;
+export declare function handleAudit(res: ServerResponse): void;
+/**
+ * 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 declare function handleWarnings(res: ServerResponse): void;