patchwarden 1.5.0 → 1.6.1

package/src/control/runtime.ts

@@ -0,0 +1,508 @@
+/**
+ * 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, type TaskEntry } from "../tools/tasks/listTasks.js";
+import { listAgents, type AgentAvailability } from "../tools/workspace/listAgents.js";
+import { readWatcherStatus, type WatcherStatusSnapshot } 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,
+  CORE_BASE_URL,
+  DIRECT_BASE_URL,
+  errorMessage,
+  getControlCenterLogDir,
+  getRuntimeRoot,
+  host,
+  MAX_EVENT_LINES,
+  port,
+  readJsonFileSafe,
+} from "./shared.js";
+
+// ── Health probing ────────────────────────────────────────────────
+
+export interface HealthProbe {
+  available: boolean;
+  status: number | null;
+  reason: string | null;
+}
+
+export function probeHealthStatus(targetUrl: string): Promise<HealthProbe> {
+  return new Promise((resolve) => {
+    const controller = new AbortController();
+    let settled = false;
+    const finish = (result: HealthProbe) => {
+      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 interface RuntimeHealth {
+  available: boolean;
+  reason: string | null;
+  healthz: { status: number } | null;
+  readyz: { status: number } | null;
+}
+
+export async function probeRuntimeHealth(baseUrl: string): Promise<RuntimeHealth> {
+  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: boolean): Record<string, unknown> {
+  const filePath = join(getRuntimeRoot(direct), "tunnel-status.json");
+  if (!existsSync(filePath)) return { observed: false };
+  try {
+    const data = readJsonFileSafe<Record<string, unknown>>(filePath);
+    if (data === null) return { observed: true, error: "invalid JSON" };
+    return { observed: true, ...data };
+  } catch (err) {
+    return { observed: true, error: errorMessage(err) };
+  }
+}
+
+export interface ToolManifestSummary {
+  tool_profile: string | null;
+  tool_count: number | null;
+  schema_epoch: string | null;
+  tool_manifest_sha256: string | null;
+  tool_names: string[] | null;
+}
+
+export function readToolManifest(direct: boolean): ToolManifestSummary {
+  const empty: ToolManifestSummary = {
+    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<Record<string, unknown>>(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 as string[]) : null,
+  };
+}
+
+export function readTunnelUrl(direct: boolean): { url: string | null; reason: string | null } {
+  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(): WatcherStatusSnapshot {
+  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(): AgentAvailability[] {
+  try {
+    return listAgents().agents;
+  } catch {
+    return [];
+  }
+}
+
+export function resolveWorkspaceRootSafe(): string | null {
+  try {
+    return resolveWorkspaceRoot(config);
+  } catch {
+    return null;
+  }
+}
+
+// ── Stale task classification ─────────────────────────────────────
+
+export interface StatusTasks {
+  tasks: unknown[];
+  total: number;
+  active: number;
+  stale: number;
+  stale_task_ids: string[];
+  reason: string | null;
+}
+
+export interface StaleClassification {
+  is_stale: boolean;
+  stale_reasons: string[];
+}
+
+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: TaskEntry,
+  watcher: WatcherStatusSnapshot,
+  nowMs = Date.now()
+): StaleClassification {
+  const reasons: string[] = [];
+  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: TaskEntry, watcher: WatcherStatusSnapshot, nowMs = Date.now()): TaskEntry & StaleClassification {
+  const cls = classifyStaleTask(task, watcher, nowMs);
+  return { ...task, is_stale: cls.is_stale, stale_reasons: cls.stale_reasons };
+}
+
+export function listTasksForStatus(): StatusTasks {
+  try {
+    const result = listTasks({ limit: 100 });
+    const watcher = result.watcher;
+    const now = Date.now();
+    let active = 0;
+    let stale = 0;
+    const staleTaskIds: string[] = [];
+    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) };
+  }
+}
+
+// ── Control Center status file + activity timeline ────────────────
+
+export interface ControlCenterStatusFile {
+  pid: number;
+  port: number;
+  started_at: string;
+  url: string;
+  version: string;
+}
+
+export function writeStatusFile(): void {
+  const status: ControlCenterStatusFile = {
+    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(): void {
+  try {
+    if (existsSync(controlCenterStatusPath)) {
+      unlinkSync(controlCenterStatusPath);
+    }
+  } catch (err) {
+    logger.error("[control-center] Failed to remove status file", { error: errorMessage(err) });
+  }
+}
+
+export interface ControlCenterEvent {
+  timestamp: string;
+  type: string;
+  payload?: Record<string, unknown>;
+}
+
+/**
+ * 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: string, payload?: Record<string, unknown>): void {
+  const event: ControlCenterEvent = {
+    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(): void {
+  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: number): ControlCenterEvent[] {
+  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: ControlCenterEvent[] = [];
+    for (const line of sliced) {
+      try {
+        events.push(JSON.parse(line) as ControlCenterEvent);
+      } catch {
+        /* skip malformed line */
+      }
+    }
+    return events;
+  } catch {
+    return [];
+  }
+}
+
+// ── Hidden stale task IDs (local UI state) ────────────────────────
+
+export function readHiddenStaleIds(): string[] {
+  const p = join(getControlCenterLogDir(), "hidden-stale-ids.json");
+  if (!existsSync(p)) return [];
+  return readStoredStringArray(p);
+}
+
+export function reconstructTaskEntry(
+  taskId: string,
+  statusData: Record<string, unknown>,
+  runtimeData: Record<string, unknown> = {},
+  watcher: WatcherStatusSnapshot = readWatcherStatusSafe(),
+): TaskEntry {
+  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 as TaskEntry["status"],
+    phase: String(runtimeData.phase || statusData.phase || "queued") as TaskEntry["phase"],
+    acceptance_status: acceptanceStatus as TaskEntry["acceptance_status"],
+    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): command is string => 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: string[]): void {
+  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(): string[] {
+  const p = join(getControlCenterLogDir(), "hidden-direct-session-ids.json");
+  if (!existsSync(p)) return [];
+  return readStoredStringArray(p);
+}
+
+export function writeHiddenDirectSessionIds(ids: string[]): void {
+  const dir = getControlCenterLogDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  atomicWriteJsonFileSync(join(dir, "hidden-direct-session-ids.json"), normalizeStoredIds(ids));
+}
+
+export function isValidDirectSessionId(sessionId: string): boolean {
+  return isValidStoredDirectSessionId(sessionId);
+}
+
+export function isValidTaskId(taskId: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9_-]{0,159}$/.test(taskId);
+}
+
+function readStoredStringArray(path: string): string[] {
+  const value = readJsonFileSafe<unknown>(path);
+  if (!Array.isArray(value)) return [];
+  return normalizeStoredIds(value);
+}
+
+function normalizeStoredIds(value: unknown[]): string[] {
+  return [...new Set(value.filter((entry): entry is string => typeof entry === "string" && entry.length > 0))];
+}
+
+// ── Small shared helpers ──────────────────────────────────────────
+
+export function parseReviewVerdict(content: string): string | null {
+  // 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: string): string | null {
+  try {
+    const m = statSync(filePath).mtime;
+    return m ? m.toISOString() : null;
+  } catch {
+    return null;
+  }
+}

package/src/control/server.ts

@@ -0,0 +1,165 @@
+/**
+ * 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, type IncomingMessage, type Server, type ServerResponse } 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: IncomingMessage, res: ServerResponse): Promise<void> {
+  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: Server | null = null;
+
+export function startServer(): Server {
+  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(): void {
+  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();
+}