mcp-coordinator 0.2.1 → 0.4.0

package/dist/src/serve-http.js

@@ -14,8 +14,10 @@ const __dirname = path.dirname(__filename);
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { createServices, createMcpServer } from "./server-setup.js";
 import { createLogger } from "./logger.js";
-import { initAuth, authenticateRequest, createToken, refreshToken, revokeAgent, setAuthLogger } from "./auth.js";
-import { assessPlanQuality } from "./plan-quality.js";
+import { initAuth, authenticateRequest, createToken, refreshToken, revokeAgent, setAuthLogger, verifyToken } from "./auth.js";
+import { safeJoinUnderRoot } from "./path-guard.js";
+import { handleRest as handleRestExt } from "./http/handle-rest.js";
+import { parseBody as parseBodyShared, json as jsonShared } from "./http/utils.js";
 import { getVersion } from "../cli/version.js";
 const VERSION = getVersion();
 import { startEmbeddedMqttBroker } from "./mqtt-broker.js";
@@ -48,439 +50,36 @@ let httpLog;
 let mcpLog;
 let authLog;
 let currentRunConfig = null;
-function parseBody(req) {
-    return new Promise((resolve, reject) => {
-        let body = "";
-        req.on("data", (chunk) => (body += chunk.toString()));
-        req.on("end", () => {
-            try {
-                resolve(body ? JSON.parse(body) : {});
-            }
-            catch {
-                reject(new Error("Invalid JSON"));
-            }
-        });
-        req.on("error", reject);
-    });
-}
-function json(res, data, status = 200) {
-    res.writeHead(status, { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" });
-    res.end(JSON.stringify(data));
-}
+// S1: parseBody and json moved to ./http/utils.js (shared with handle-rest.ts).
+// Re-bound to local names so the rest of this file (handleAuth, handleSse,
+// startServer) can keep using `parseBody` / `json` without changes.
+const parseBody = parseBodyShared;
+const json = jsonShared;
 function decodeJwtPayload(token) {
+    // Used only on tokens we just minted ourselves (to read the `exp` claim
+    // before returning it to the client). Real verification of inbound tokens
+    // happens in `authenticateRequest` via jose.jwtVerify().
     const base64url = token.split(".")[1];
-    const base64 = base64url.replace(/-/g, "+").replace(/_/g, "/");
-    return JSON.parse(atob(base64));
+    return JSON.parse(Buffer.from(base64url, "base64url").toString("utf-8"));
 }
 function safeEqual(a, b) {
     if (a.length !== b.length)
         return false;
     return timingSafeEqual(Buffer.from(a), Buffer.from(b));
 }
+// S1: handleRest extracted to ./http/handle-rest.ts. Thin wrapper here keeps
+// startServer's call site stable while the 382-line REST router lives in its
+// own module. currentRunConfig stays here as the single mutable owner; the
+// extracted function reads/writes via getRunConfig/setRunConfig accessors.
 async function handleRest(req, res) {
-    const url = req.url || "";
-    const body = await parseBody(req);
-    const agentId = body.agent_id;
-    // Dashboard/work-stealing polls these endpoints every few seconds — demote to debug
-    // to keep the info log focused on coordination events (announce, claim, resolve, etc).
-    const isPoll = url === "/api/hot-files" || url === "/api/threads-active" || url === "/api/status" || url === "/api/quota";
-    // Note: /api/quota/refresh is NOT in the poll list — it's a manual user
-    // action and deserves an info-level log for auditability.
-    if (isPoll) {
-        httpLog.debug({ method: req.method, url, agent_id: agentId }, "REST request");
-    }
-    else {
-        httpLog.info({ method: req.method, url, agent_id: agentId }, "REST request");
-    }
-    const { registry, activityTracker, consultation, fileTracker, impactScorer, introspection, sseEmitter, mqttBridge, quotaCache } = services;
-    if (url === "/api/register") {
-        const { agent_id, name, modules } = body;
-        const agent = registry.register(agent_id, name, modules || []);
-        sseEmitter.emit("agent_online", { agent_id, name, modules });
-        json(res, agent);
-    }
-    else if (url === "/api/session-start") {
-        const { agent_id, agent_name } = body;
-        const online = registry.listOnline();
-        const openThreads = consultation.listThreads({ status: "open" });
-        const hotFiles = fileTracker.getHotFiles(30);
-        const briefing = [
-            `Agents en ligne: ${online.map((a) => a.name).join(", ") || "aucun"}`,
-            `Consultations ouvertes: ${openThreads.length}`,
-            `Hot files: ${hotFiles.map((f) => f.file_path).join(", ") || "aucun"}`,
-        ].join("\n");
-        json(res, { briefing, summary: { online: online.length, open_threads: openThreads.length, hot_files: hotFiles.length } });
-    }
-    else if (url === "/api/session-stop") {
-        const { agent_id } = body;
-        registry.setOffline(agent_id);
-        activityTracker.reportOffline(agent_id);
-        consultation.handleAgentDeparture(agent_id);
-        sseEmitter.emit("agent_offline", { agent_id });
-        json(res, { ok: true });
-    }
-    else if (url === "/api/check-conflict") {
-        const { file, agent_id } = body;
-        const conflict = fileTracker.checkFileConflict(file, agent_id, 30);
-        const warnings = [];
-        if (conflict.conflict) {
-            warnings.push(`File ${file} recently edited by: ${conflict.agents.join(", ")}`);
-        }
-        json(res, { conflict: conflict.conflict, warnings });
-    }
-    else if (url === "/api/log-file") {
-        const { session_id, agent_id, agent_name, tool_name, file } = body;
-        fileTracker.log({ session_id, agent_id, agent_name, tool_name, file_path: file });
-        activityTracker.reportFileActivity(agent_id, file);
-        sseEmitter.emit("file_edited", { agent_id, agent_name: agent_name || agent_id, file, tool_name });
-        json(res, { ok: true });
-    }
-    else if (url === "/api/announce") {
-        const { agent_id, subject, plan, target_modules, target_files, depends_on_files, exports_affected, keep_open, assigned_to } = body;
-        // Quality gate on plan
-        const planQuality = assessPlanQuality(plan);
-        const effectiveMode = planQuality.mode;
-        const thread = consultation.announceWork({ agent_id, subject, plan, target_modules, target_files, depends_on_files, exports_affected, keep_open, assigned_to });
-        const agentInfo = registry.get(agent_id);
-        // Impact scoring: categorize all online agents
-        const categorized = impactScorer.categorize({
-            agent_id, target_modules, target_files, depends_on_files, exports_affected,
-        });
-        // Override expected_respondents with concerned agents from scorer
-        {
-            const db = (await import("./database.js")).getDb();
-            const concernedIds = categorized.concerned.map(s => s.agent_id);
-            db.prepare("UPDATE threads SET expected_respondents = ? WHERE id = ?")
-                .run(JSON.stringify(concernedIds), thread.id);
-            // Only auto-resolve when truly alone — no other online agents.
-            // If peers are online but not yet concerned (e.g. they haven't announced
-            // yet), keep the thread open so a subsequent announce can still match
-            // this work via Layer 0. Thread will timeout naturally if no one joins.
-            const otherOnlineCount = registry.listOnline().filter((a) => a.id !== agent_id).length;
-            const shouldAutoResolve = concernedIds.length === 0 && otherOnlineCount === 0;
-            if (shouldAutoResolve && thread.status === "open" && !keep_open) {
-                db.prepare("UPDATE threads SET status = 'resolved', resolved_at = ? WHERE id = ?")
-                    .run(new Date().toISOString(), thread.id);
-                consultation.emitResolution(thread.id, "auto_resolved");
-            }
-        }
-        // Emit impact_scored SSE events for all agents
-        for (const s of [...categorized.concerned, ...categorized.gray_zone, ...categorized.pass]) {
-            sseEmitter.emit("impact_scored", {
-                thread_id: thread.id, agent_id: s.agent_id, agent_name: s.agent_name,
-                score: s.score, reasons: s.reasons, category: s.score >= 90 ? "concerned" : s.score >= 30 ? "gray_zone" : "pass",
-            });
-        }
-        // Create introspection records and emit introspection_requested for gray_zone agents
-        for (const s of categorized.gray_zone) {
-            introspection.create({ thread_id: thread.id, agent_id: s.agent_id, score: s.score, reasons: s.reasons });
-            sseEmitter.emit("introspection_requested", {
-                thread_id: thread.id, agent_id: s.agent_id, agent_name: s.agent_name, score: s.score, reasons: s.reasons,
-            });
-        }
-        const updated = consultation.getThread(thread.id);
-        const respondents = JSON.parse(updated.expected_respondents || "[]");
-        // Emit downgrade event when plan is provided but quality is insufficient
-        if (plan && effectiveMode === "discovery") {
-            sseEmitter.emit("impact_scored", {
-                thread_id: thread.id,
-                agent_id: agent_id,
-                agent_name: agentInfo?.name || agent_id,
-                score: planQuality.score,
-                reasons: [`plan downgraded: score ${planQuality.score}/3 — ${!planQuality.checks.mentions_files ? 'no files' : ''} ${!planQuality.checks.concrete_approach ? 'vague approach' : ''} ${!planQuality.checks.sufficient_detail ? 'too short' : ''}`.trim()],
-                category: "plan_quality",
-            });
-        }
-        sseEmitter.emit("thread_opened", {
-            thread_id: thread.id, subject, agent_id, agent_name: agentInfo?.name || agent_id,
-            target_modules, target_files, expected_respondents: respondents,
-            conflicts: updated.conflicts ? JSON.parse(updated.conflicts) : [],
-            created_at: updated.created_at,
-            mode: effectiveMode,
-            plan: plan || null,
-            plan_quality: planQuality,
-        });
-        json(res, { thread_id: thread.id, status: updated.status, impact: categorized });
-    }
-    else if (url === "/api/post-to-thread") {
-        const { thread_id, agent_id, agent_name, type, content } = body;
-        // Pre-check the thread so we can return actionable status codes instead
-        // of always-500 on any error. The client uses the status to decide
-        // whether to warn (unexpected) or silently skip (normal race).
-        const targetThread = consultation.getThread(thread_id);
-        if (!targetThread) {
-            json(res, { error: "thread_not_found", thread_id }, 404);
-            return;
-        }
-        if (targetThread.status === "cancelled") {
-            json(res, { error: "thread_cancelled", thread_id }, 410);
-            return;
-        }
-        const msg = consultation.postToThread({ thread_id, agent_id, agent_name, type, content });
-        const thread = consultation.getThread(thread_id);
-        sseEmitter.emit("message_posted", {
-            thread_id, agent_id, agent_name: agent_name || agent_id,
-            type, content, round: thread?.round || 1,
-            token_estimate: msg.token_estimate || 0,
-        });
-        json(res, msg);
-    }
-    else if (url === "/api/token-usage") {
-        // Agent → coordinator telemetry, emitted once per LLM turn so the dashboard
-        // and reports can pinpoint where tokens are being burned.
-        const payload = body;
-        sseEmitter.emit("token_usage", payload);
-        json(res, { ok: true });
-    }
-    else if (url === "/api/unclaim-task") {
-        const { thread_id, agent_id } = body;
-        if (!thread_id || !agent_id) {
-            json(res, { success: false, error: "thread_id and agent_id required" }, 400);
-            return;
-        }
-        const db = (await import("./database.js")).getDb();
-        // F4: increment unclaim counter. After POISON_THRESHOLD aborts, flip status
-        // to "poisoned" so no agent claims it again — prevents the tight
-        // claim → no DONE → unclaim → re-claim loop we observed on stuck tasks.
-        // Only the claiming agent can unclaim to prevent cross-agent interference.
-        const POISON_THRESHOLD = 2;
-        const result = db.prepare("UPDATE threads SET claimed_by = NULL, claimed_at = NULL, unclaim_count = COALESCE(unclaim_count, 0) + 1 WHERE id = ? AND claimed_by = ? AND status = 'open'").run(thread_id, agent_id);
-        let poisoned = false;
-        if (result.changes === 1) {
-            const row = db.prepare("SELECT unclaim_count FROM threads WHERE id = ?").get(thread_id);
-            if (row && (row.unclaim_count ?? 0) >= POISON_THRESHOLD) {
-                db.prepare("UPDATE threads SET status = 'poisoned' WHERE id = ? AND status = 'open'").run(thread_id);
-                poisoned = true;
-                httpLog.warn({ thread_id, unclaim_count: row.unclaim_count }, "thread poisoned after repeated unclaims");
-            }
-        }
-        json(res, { success: result.changes === 1, poisoned });
-    }
-    else if (url === "/api/claim-task") {
-        const { thread_id, agent_id } = body;
-        if (!thread_id || !agent_id) {
-            json(res, { success: false, error: "thread_id and agent_id required" }, 400);
-            return;
-        }
-        const db = (await import("./database.js")).getDb();
-        // Only claim threads with status='open' — poisoned threads are filtered out
-        // automatically because the status filter excludes them.
-        // Directed-dispatch constraint: if assigned_to is set, only that specific
-        // agent can claim; NULL keeps the original open-pool semantics.
-        const result = db.prepare("UPDATE threads SET claimed_by = ?, claimed_at = ? WHERE id = ? AND claimed_by IS NULL AND status = 'open' AND (assigned_to IS NULL OR assigned_to = ?)").run(agent_id, new Date().toISOString(), thread_id, agent_id);
-        if (result.changes === 1) {
-            mqttBridge.publishTaskClaimed(thread_id, agent_id);
-            sseEmitter.emit("task_claimed", { thread_id, agent_id });
-            json(res, { success: true });
-        }
-        else {
-            const thread = consultation.getThread(thread_id);
-            // Surface the assigned_to in the 'why not' response so clients can
-            // distinguish "already claimed by X" from "reserved for Y".
-            json(res, {
-                success: false,
-                claimed_by: thread?.claimed_by || null,
-                assigned_to: thread?.assigned_to || null,
-                status: thread?.status,
-            });
-        }
-    }
-    else if (url === "/api/propose-resolution") {
-        const { thread_id, agent_id, summary } = body;
-        const agentInfo = registry.get(agent_id);
-        consultation.proposeResolution(thread_id, agent_id, summary);
-        sseEmitter.emit("resolution_proposed", {
-            thread_id, agent_id, agent_name: agentInfo?.name || agent_id, summary,
-        });
-        json(res, consultation.getThread(thread_id));
-        mqttBridge.publishTaskCompleted(thread_id, agent_id, summary);
-    }
-    else if (url === "/api/approve-resolution") {
-        const { thread_id, agent_id } = body;
-        const agentInfo = registry.get(agent_id);
-        consultation.approveResolution(thread_id, agent_id, agentInfo?.name);
-        const t = consultation.getThread(thread_id);
-        json(res, t);
-    }
-    else if (url?.startsWith("/api/consultation/") && url?.endsWith("/status")) {
-        const threadId = url.split("/")[3];
-        const thread = consultation.getThreadWithMessages(threadId);
-        if (!thread) {
-            json(res, { error: "not found" }, 404);
-        }
-        else {
-            json(res, {
-                status: thread.thread.status,
-                messages: thread.messages,
-                resolution_summary: thread.thread.resolution_summary,
-                expected_respondents: JSON.parse(thread.thread.expected_respondents || "[]"),
-            });
-        }
-    }
-    else if (url === "/api/threads-active") {
-        const open = consultation.listThreads({ status: "open" });
-        const resolving = consultation.listThreads({ status: "resolving" });
-        json(res, [...open, ...resolving]);
-    }
-    else if (url === "/api/hot-files") {
-        const { since_minutes } = body;
-        json(res, fileTracker.getHotFiles(since_minutes || 30));
-    }
-    else if (url === "/api/quota") {
-        // Pre-flight + live widget endpoint. 200 with fresh QuotaInfo when the
-        // Keychain + Anthropic API are reachable, 503 otherwise. Consumers treat
-        // 503 as "quota unknown = proceed" (fail-open) per the project decision.
-        const info = await quotaCache.get();
-        if (!info) {
-            const status = quotaCache.snapshot();
-            json(res, {
-                error: "quota unavailable",
-                reason: status.lastError,
-                cooldown_until: status.cooldownUntil,
-            }, 503);
-        }
-        else {
-            json(res, {
-                five_hour: info.fiveHour,
-                seven_day: info.sevenDay,
-                seven_day_sonnet: info.sevenDaySonnet,
-                fetched_at: info.fetchedAt,
-            });
-        }
-    }
-    else if (url === "/api/quota/refresh") {
-        // Force-refresh the cache, bypassing the TTL. Used by the dashboard's
-        // manual refresh button. The underlying quotaCache.refresh() is single-
-        // flight-deduped, so mashing the button doesn't stack parallel fetches.
-        // The onRefresh callback on the cache broadcasts via SSE + MQTT, so the
-        // dashboard receives the update through the normal channel too — this
-        // endpoint only exists for "give me the answer now" semantics.
-        const info = await quotaCache.refresh();
-        if (!info) {
-            const status = quotaCache.snapshot();
-            json(res, {
-                error: "quota unavailable",
-                reason: status.lastError,
-                cooldown_until: status.cooldownUntil,
-            }, 503);
-        }
-        else {
-            json(res, {
-                five_hour: info.fiveHour,
-                seven_day: info.sevenDay,
-                seven_day_sonnet: info.sevenDaySonnet,
-                fetched_at: info.fetchedAt,
-            });
-        }
-    }
-    else if (url === "/api/introspection-response") {
-        const { introspection_id, concerned, reason } = body;
-        const intro = introspection.respond(introspection_id, concerned, reason);
-        // If concerned, add to thread's expected_respondents
-        if (concerned && intro) {
-            const db = (await import("./database.js")).getDb();
-            const thread = consultation.getThread(intro.thread_id);
-            if (thread && (thread.status === "open" || thread.status === "resolving")) {
-                const respondents = JSON.parse(thread.expected_respondents || "[]");
-                if (!respondents.includes(intro.agent_id)) {
-                    respondents.push(intro.agent_id);
-                    db.prepare("UPDATE threads SET expected_respondents = ? WHERE id = ?")
-                        .run(JSON.stringify(respondents), thread.id);
-                }
-            }
-        }
-        const agentInfo = registry.get(intro?.agent_id || "");
-        sseEmitter.emit("introspection_completed", {
-            introspection_id, thread_id: intro?.thread_id,
-            agent_id: intro?.agent_id, agent_name: agentInfo?.name || intro?.agent_id,
-            concerned, reason,
-        });
-        json(res, intro);
-    }
-    else if (url?.startsWith("/api/pending-introspections")) {
-        const urlObj = new URL(url, "http://localhost");
-        const agent_id = urlObj.searchParams.get("agent_id") || "";
-        const pending = introspection.getPending(agent_id);
-        json(res, pending);
-    }
-    else if (url === "/api/run-config") {
-        if (req.method === "POST") {
-            currentRunConfig = body;
-            sseEmitter.emit("run_config", currentRunConfig);
-            json(res, { ok: true });
-        }
-        else {
-            json(res, currentRunConfig || { active: false });
-        }
-    }
-    else if (url === "/api/reset") {
-        // Reset all tables for clean test run (disable FK checks to avoid ordering issues)
-        const db = (await import("./database.js")).getDb();
-        db.exec("PRAGMA foreign_keys = OFF");
-        db.exec("DELETE FROM introspections");
-        db.exec("DELETE FROM events");
-        db.exec("DELETE FROM thread_messages");
-        db.exec("DELETE FROM threads");
-        db.exec("DELETE FROM action_summaries");
-        db.exec("DELETE FROM file_activity");
-        db.exec("DELETE FROM agent_activity_status");
-        db.exec("DELETE FROM dependency_map");
-        db.exec("DELETE FROM agents");
-        db.exec("DELETE FROM revoked_agents");
-        db.exec("PRAGMA foreign_keys = ON");
-        currentRunConfig = null;
-        json(res, { ok: true });
-    }
-    else if (url === "/api/check-interrupt") {
-        const { agent_id } = body;
-        // Check for threads where this agent is an expected respondent and hasn't posted yet.
-        // Covers both open threads (waiting for initial response) and resolving threads
-        // (waiting for approval/contest of a proposed resolution).
-        const pendingThreads = [
-            ...consultation.listThreads({ status: "open" }),
-            ...consultation.listThreads({ status: "resolving" }),
-        ].filter((t) => {
-            const respondents = JSON.parse(t.expected_respondents || "[]");
-            return respondents.includes(agent_id);
-        });
-        if (pendingThreads.length > 0) {
-            const details = pendingThreads.map((t) => ({
-                thread_id: t.id,
-                subject: t.subject,
-                initiator_id: t.initiator_id,
-                status: t.status,
-                target_files: JSON.parse(t.target_files || "[]"),
-            }));
-            json(res, { interrupt: true, threads: details });
-        }
-        else {
-            json(res, { interrupt: false });
-        }
-    }
-    else if (url?.startsWith("/api/agent-status/")) {
-        const agentId = url.split("/")[3];
-        const agent = registry.get(agentId);
-        if (!agent) {
-            json(res, { registered: false, status: "unknown" });
-        }
-        else {
-            const activity = activityTracker.getActivity(agentId, { idleAfterMinutes: 5 });
-            json(res, { registered: true, status: agent.status, activity: activity.activity_status });
-        }
-    }
-    else if (url === "/api/status") {
-        const online = registry.listOnline();
-        const openThreads = consultation.listThreads({ status: "open" });
-        json(res, {
-            online: online.length,
-            open_threads: openThreads.length,
-            hot_files: fileTracker.getHotFiles(30).length,
-            mqtt: services.mqttBridge.isConnected(),
-        });
-    }
-    else {
-        json(res, { error: "not found" }, 404);
-    }
+    const ctx = {
+        services,
+        httpLog,
+        authEnabled: AUTH_ENABLED,
+        getRunConfig: () => currentRunConfig,
+        setRunConfig: (cfg) => { currentRunConfig = cfg; },
+    };
+    return handleRestExt(req, res, ctx);
 }
 async function handleAuth(req, res) {
     const url = req.url || "";
@@ -568,6 +167,16 @@ function writeSseEvent(res, event) {
     const data = injectTimestamp(event.payload, event.created_at ?? new Date().toISOString());
     res.write(`id: ${event.id}\nevent: ${event.type}\ndata: ${data}\n\n`);
 }
+// P3: heartbeat interval in ms. Default 30s — well under nginx/Cloudflare's
+// typical 60s idle SSE timeout, but infrequent enough to add negligible
+// bandwidth (one ":keep-alive\n\n" comment is ~16 bytes).
+const SSE_HEARTBEAT_MS = (() => {
+    const raw = process.env.COORDINATOR_SSE_HEARTBEAT_MS;
+    if (!raw)
+        return 30_000;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : 30_000;
+})();
 function handleSse(req, res) {
     res.writeHead(200, {
         "Content-Type": "text/event-stream",
@@ -587,11 +196,35 @@ function handleSse(req, res) {
     const unsubscribe = services.sseEmitter.addListener((event) => {
         writeSseEvent(res, event);
     });
-    req.on("close", () => unsubscribe());
+    // P3: heartbeat. Browsers ignore the `:` comment line per the SSE spec,
+    // but it counts as activity for intermediate proxies that would otherwise
+    // kill an idle connection after ~60s. Wrapped in try/catch because once
+    // the socket is half-closed res.write throws synchronously.
+    const heartbeat = setInterval(() => {
+        try {
+            res.write(":keep-alive\n\n");
+        }
+        catch {
+            // Connection already torn down — req.on("close") will clean up shortly.
+        }
+    }, SSE_HEARTBEAT_MS);
+    // Don't keep the event loop alive solely for heartbeats; without unref()
+    // a still-open SSE connection at process shutdown delays exit.
+    if (typeof heartbeat.unref === "function")
+        heartbeat.unref();
+    req.on("close", () => {
+        // P3: clear the interval BEFORE unsubscribing so a heartbeat tick that
+        // fires between close and unsubscribe can't write to a dead socket.
+        clearInterval(heartbeat);
+        unsubscribe();
+    });
 }
 export async function startServer(opts) {
     const port = opts?.port ?? PORT;
     const dataDir = opts?.dataDir ?? DATA_DIR;
+    // Resolve MQTT ports per-call so tests/embedders can override module-load env values.
+    const mqttTcpPort = opts?.mqttTcpPort ?? MQTT_TCP_PORT;
+    const mqttWsPath = opts?.mqttWsPath ?? MQTT_WS_PATH;
     services = createServices({ dataDir });
     const log = services.logger;
     httpLog = log.child({ component: "http" });
@@ -638,10 +271,19 @@ export async function startServer(opts) {
                     json(res, { error: "dashboard not available" }, 404);
                     return;
                 }
-                const filePath = url === "/dashboard" || url === "/dashboard/"
-                    ? path.join(dashboardDir, "index.html")
-                    : path.join(dashboardDir, url.replace("/dashboard/", ""));
-                if (existsSync(filePath)) {
+                // B5 fix: defend against path traversal. safeJoinUnderRoot decodes the
+                // URL, strips leading slashes, resolves the path, and verifies the
+                // result stays under dashboardDir. Returns null on traversal attempts.
+                let filePath;
+                if (url === "/dashboard" || url === "/dashboard/") {
+                    filePath = path.join(dashboardDir, "index.html");
+                }
+                else {
+                    // Strip query string before joining (browsers append ?v=...)
+                    const urlPath = (url.split("?")[0] || "").replace("/dashboard/", "");
+                    filePath = safeJoinUnderRoot(dashboardDir, urlPath);
+                }
+                if (filePath && existsSync(filePath)) {
                     const ext = path.extname(filePath);
                     const contentTypes = {
                         ".html": "text/html",
@@ -739,30 +381,131 @@ export async function startServer(opts) {
     // Start the embedded MQTT broker (TCP + WebSocket on HTTP upgrade).
     // Awaiting ensures the TCP listener is fully bound before we connect our
     // own client or tell users the coordinator is ready.
-    await startEmbeddedMqttBroker({
-        tcpPort: MQTT_TCP_PORT,
+    // B3 fix: when AUTH_ENABLED, gate every MQTT CONNECT by JWT in the password
+    // field. Anonymous connections are rejected. Default off (essaim and any
+    // client without auth keep working unchanged).
+    const mqttAuth = AUTH_ENABLED
+        ? async (_username, password) => {
+            if (!password)
+                return false;
+            try {
+                await verifyToken(password.toString("utf-8"));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        : undefined;
+    const broker = await startEmbeddedMqttBroker({
+        tcpPort: mqttTcpPort,
         httpServer,
-        wsPath: MQTT_WS_PATH,
+        wsPath: mqttWsPath,
         logger: log.child({ component: "mqtt-broker" }),
+        authenticate: mqttAuth,
+    });
+    // B3: when AUTH_ENABLED, the internal coordinator client must authenticate
+    // too. Mint a short-lived admin token for the bridge.
+    const internalToken = AUTH_ENABLED ? await createToken("coordinator-internal", "admin", "1h") : undefined;
+    await services.mqttBridge.connect({
+        url: `mqtt://127.0.0.1:${mqttTcpPort}`,
+        username: AUTH_ENABLED ? "coordinator-internal" : undefined,
+        password: internalToken,
+        // P1 fix: stable agent identity for LWT topic
+        // (`coordinator/agents/coordinator-internal/status`).
+        agentId: "coordinator-internal",
     });
-    // Connect the coordinator's own MQTT client to the embedded broker BEFORE
-    // the HTTP server accepts requests — agents shouldn't see a half-ready coordinator.
-    await services.mqttBridge.connect({ url: `mqtt://127.0.0.1:${MQTT_TCP_PORT}` });
     services.mqttBridge.onOffline((agentId) => {
         services.registry.setOffline(agentId);
         services.consultation.handleAgentDeparture(agentId);
         services.sseEmitter.emit("agent_offline", { agent_id: agentId });
     });
-    httpServer.listen(port, () => {
-        log.info({
-            port,
-            mcp: `POST http://localhost:${port}/mcp`,
-            rest: `POST http://localhost:${port}/api/*`,
-            sse: `GET http://localhost:${port}/api/events`,
-            mqtt_tcp: `mqtt://127.0.0.1:${MQTT_TCP_PORT}`,
-            mqtt_ws: `ws://localhost:${port}${MQTT_WS_PATH}`,
-        }, "Coordinator v3 started");
+    // Wait for the HTTP server to be actually listening before resolving the
+    // returned handle. Otherwise callers (tests, essaim) may try to connect
+    // before the port is bound.
+    await new Promise((resolve, reject) => {
+        const onError = (err) => reject(err);
+        httpServer.once("error", onError);
+        httpServer.listen(port, () => {
+            httpServer.off("error", onError);
+            log.info({
+                port,
+                mcp: `POST http://localhost:${port}/mcp`,
+                rest: `POST http://localhost:${port}/api/*`,
+                sse: `GET http://localhost:${port}/api/events`,
+                mqtt_tcp: `mqtt://127.0.0.1:${mqttTcpPort}`,
+                mqtt_ws: `ws://localhost:${port}${mqttWsPath}`,
+            }, "Coordinator v3 started");
+            resolve();
+        });
     });
+    // B2 fix: start the consultation timeout sweeper.
+    // Reads no longer mutate state — this background tick handles timeouts.
+    services.consultation.startTimeoutSweeper();
+    // B6 fix: graceful shutdown.
+    // Cleanup sequence: stop accepting new HTTP connections → end MQTT bridge →
+    // close MQTT broker → stop quota background timer → close DB.
+    // Idempotent: stopped flag prevents double-cleanup if SIGTERM races with
+    // an explicit handle.stop() call.
+    let stopped = false;
+    const stop = async () => {
+        if (stopped)
+            return;
+        stopped = true;
+        log.info("Coordinator shutting down...");
+        try {
+            await new Promise((resolve) => httpServer.close(() => resolve()));
+        }
+        catch (err) {
+            log.warn({ err }, "Error closing HTTP server");
+        }
+        try {
+            await services.mqttBridge.disconnect();
+        }
+        catch (err) {
+            log.warn({ err }, "Error disconnecting MQTT bridge");
+        }
+        try {
+            await broker.close();
+        }
+        catch (err) {
+            log.warn({ err }, "Error closing MQTT broker");
+        }
+        try {
+            services.quotaCache.stopBackgroundTick();
+        }
+        catch (err) {
+            log.warn({ err }, "Error stopping quota timer");
+        }
+        try {
+            services.consultation.stopTimeoutSweeper();
+        }
+        catch (err) {
+            log.warn({ err }, "Error stopping timeout sweeper");
+        }
+        try {
+            const { closeDb } = await import("./database.js");
+            closeDb?.();
+        }
+        catch (err) {
+            log.warn({ err }, "Error closing database");
+        }
+        log.info("Coordinator shutdown complete");
+    };
+    // Register signal handlers (default true). Embedders can opt out via
+    // registerSignalHandlers: false to manage their own teardown.
+    if (opts?.registerSignalHandlers !== false) {
+        const onSignal = (signal) => {
+            log.info({ signal }, "Received shutdown signal");
+            stop().then(() => process.exit(0)).catch((err) => {
+                log.error({ err }, "Shutdown error, forcing exit");
+                process.exit(1);
+            });
+        };
+        process.once("SIGTERM", () => onSignal("SIGTERM"));
+        process.once("SIGINT", () => onSignal("SIGINT"));
+    }
+    return { port, stop };
 }
 // Auto-start when run directly (not imported)
 const isMainModule = process.argv[1]?.endsWith("serve-http.ts") || process.argv[1]?.endsWith("serve-http.js");