mcp-coordinator 0.2.0 → 0.3.0

package/dist/src/http/handle-rest.js

@@ -0,0 +1,374 @@
+import { getDb } from "../database.js";
+import { runCommonAnnounceFlow } from "../announce-workflow.js";
+import { canResetDb } from "../reset-guard.js";
+import { parseBody, json } from "./utils.js";
+export async function handleRest(req, res, ctx) {
+    const { services, httpLog, authEnabled, getRunConfig, setRunConfig } = ctx;
+    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, 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 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;
+        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);
+        // S2 fix: shared workflow (impact scoring, override respondents, auto-resolve,
+        // impact_scored + introspection SSE, plan-quality downgrade event). Same
+        // function used by the MCP announce_work tool path.
+        const { updated, categorized, respondents, planQuality } = runCommonAnnounceFlow(services, thread.id, {
+            agent_id, subject, plan, target_modules, target_files, depends_on_files, exports_affected, keep_open,
+        });
+        // REST-specific thread_opened SSE shape (different field set than MCP — kept
+        // divergent because consumers may depend on this exact contract).
+        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: planQuality.mode,
+            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 = 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 = 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 = 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") {
+            setRunConfig(body);
+            sseEmitter.emit("run_config", getRunConfig());
+            json(res, { ok: true });
+        }
+        else {
+            json(res, getRunConfig() || { active: false });
+        }
+    }
+    else if (url === "/api/reset") {
+        // B4 fix: gate destructive reset when AUTH is disabled.
+        // When AUTH_ENABLED=true, ADMIN_ONLY_ROUTES already enforced upstream
+        // by authenticateRequest (see auth.ts). This guard covers the AUTH off case.
+        if (!canResetDb(process.env, authEnabled)) {
+            json(res, {
+                error: "Forbidden: /api/reset requires NODE_ENV=test, COORDINATOR_ALLOW_RESET=true, or COORDINATOR_AUTH_ENABLED with admin token",
+            }, 403);
+            return;
+        }
+        // Reset all tables for clean test run (disable FK checks to avoid ordering issues)
+        const db = 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");
+        setRunConfig(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 aid = url.split("/")[3];
+        const agent = registry.get(aid);
+        if (!agent) {
+            json(res, { registered: false, status: "unknown" });
+        }
+        else {
+            const activity = activityTracker.getActivity(aid, { 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);
+    }
+}

package/dist/src/http/utils.d.ts

@@ -0,0 +1,15 @@
+import type { IncomingMessage, ServerResponse } from "http";
+/**
+ * S1: shared HTTP helpers extracted from serve-http.ts.
+ * parseBody, json, decodeJwtPayload, safeEqual.
+ */
+export declare function parseBody(req: IncomingMessage): Promise<Record<string, unknown>>;
+export declare function json(res: ServerResponse, data: unknown, status?: number): void;
+/**
+ * Decode a JWT payload WITHOUT verifying. 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().
+ */
+export declare function decodeJwtPayload(token: string): Record<string, unknown>;
+export declare function safeEqual(a: string, b: string): boolean;

package/dist/src/http/utils.js

@@ -0,0 +1,39 @@
+import { timingSafeEqual } from "crypto";
+/**
+ * S1: shared HTTP helpers extracted from serve-http.ts.
+ * parseBody, json, decodeJwtPayload, safeEqual.
+ */
+export 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);
+    });
+}
+export function json(res, data, status = 200) {
+    res.writeHead(status, { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" });
+    res.end(JSON.stringify(data));
+}
+/**
+ * Decode a JWT payload WITHOUT verifying. 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().
+ */
+export function decodeJwtPayload(token) {
+    const base64url = token.split(".")[1];
+    return JSON.parse(Buffer.from(base64url, "base64url").toString("utf-8"));
+}
+export function safeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+}

package/dist/src/introspection.js

@@ -4,7 +4,7 @@ export class IntrospectionManager {
     create(params) {
         const db = getDb();
         const id = randomUUID();
-        db.prepare(`INSERT INTO introspections (id, thread_id, agent_id, score, reasons)
+        db.prepare(`INSERT INTO introspections (id, thread_id, agent_id, score, reasons)
        VALUES (?, ?, ?, ?, ?)`).run(id, params.thread_id, params.agent_id, params.score, JSON.stringify(params.reasons));
         return this.get(id);
     }

package/dist/src/mqtt-bridge.d.ts

@@ -13,6 +13,8 @@ export declare class MqttBridge {
     constructor(logger?: Logger);
     connect(config: {
         url: string;
+        username?: string;
+        password?: string;
     }): Promise<void>;
     isConnected(): boolean;
     onOffline(handler: (agentId: string) => void): void;

package/dist/src/mqtt-bridge.js

@@ -17,6 +17,8 @@ export class MqttBridge {
             this.client = mqtt.connect(config.url, {
                 clientId: `coordinator-${Date.now()}`,
                 clean: true,
+                username: config.username,
+                password: config.password,
             });
             this.client.on("connect", () => {
                 clearTimeout(timeout);

package/dist/src/mqtt-broker.d.ts

@@ -5,11 +5,27 @@ export interface EmbeddedMqttBroker {
     wsPath: string | null;
     close: () => Promise<void>;
 }
+/**
+ * B3 fix: opt-in MQTT authentication. When provided, every CONNECT packet's
+ * password field is passed to authenticate(). Returning false rejects the
+ * client. When omitted (default), the broker accepts anonymous connections —
+ * preserving the existing behavior so essaim and other clients without auth
+ * keep working unchanged.
+ *
+ * The internal coordinator client (MqttBridge) bypasses this by passing an
+ * internal admin token when AUTH_ENABLED is true.
+ */
+export type MqttAuthVerifier = (username: string | undefined, password: Buffer | undefined) => Promise<boolean>;
 export interface EmbeddedMqttOptions {
     tcpPort?: number;
     httpServer?: HttpServer;
     wsPath?: string;
     logger: Logger;
+    /**
+     * Per-CONNECT auth verifier. Omit to allow anonymous (default — backwards
+     * compatible with essaim and any client not using auth).
+     */
+    authenticate?: MqttAuthVerifier;
 }
 /**
  * Start an embedded MQTT broker (aedes) exposed via TCP, WebSocket, or both.

package/dist/src/mqtt-broker.js

@@ -38,8 +38,23 @@ function wsToDuplex(ws) {
  * fully ready, which causes client connect timeouts in compiled binaries.
  */
 export async function startEmbeddedMqttBroker(opts) {
-    const { tcpPort, httpServer, wsPath = "/mqtt", logger } = opts;
+    const { tcpPort, httpServer, wsPath = "/mqtt", logger, authenticate } = opts;
     const broker = await Aedes.createBroker();
+    if (authenticate) {
+        // B3 fix: when AUTH_ENABLED, every CONNECT must present a valid token.
+        broker.authenticate =
+            (client, username, password, cb) => {
+                Promise.resolve(authenticate(username, password)).then((ok) => {
+                    if (!ok)
+                        logger.warn({ client_id: client?.id, username }, "MQTT auth rejected");
+                    cb(null, ok);
+                }, (err) => {
+                    logger.warn({ client_id: client?.id, err: err.message }, "MQTT auth error");
+                    cb(null, false);
+                });
+            };
+        logger.info("MQTT auth enabled (token in CONNECT password)");
+    }
     broker.on("client", (client) => {
         logger.debug({ client_id: client?.id }, "MQTT client connected");
     });

package/dist/src/path-guard.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resolve a request URL into a safe filesystem path within a known root.
+ *
+ * Defends against path traversal: a request like `/dashboard/../../etc/passwd`
+ * would otherwise escape the dashboard directory because `path.join` does not
+ * validate that the result stays under the root.
+ *
+ * Returns the resolved absolute path on success, or `null` if the path would
+ * escape the root, contains a null byte, or is otherwise invalid.
+ *
+ * `urlPath` should already have the route prefix stripped (e.g. for
+ * `/dashboard/app.js` pass `"app.js"`).
+ */
+export declare function safeJoinUnderRoot(root: string, urlPath: string): string | null;

package/dist/src/path-guard.js

@@ -0,0 +1,44 @@
+import path from "path";
+/**
+ * Resolve a request URL into a safe filesystem path within a known root.
+ *
+ * Defends against path traversal: a request like `/dashboard/../../etc/passwd`
+ * would otherwise escape the dashboard directory because `path.join` does not
+ * validate that the result stays under the root.
+ *
+ * Returns the resolved absolute path on success, or `null` if the path would
+ * escape the root, contains a null byte, or is otherwise invalid.
+ *
+ * `urlPath` should already have the route prefix stripped (e.g. for
+ * `/dashboard/app.js` pass `"app.js"`).
+ */
+export function safeJoinUnderRoot(root, urlPath) {
+    // Reject null bytes (NUL injection that some libs/OS handle inconsistently).
+    if (urlPath.includes("\0"))
+        return null;
+    // Decode percent-encoding so "%2e%2e/foo" cannot bypass the literal ".." check.
+    // decodeURIComponent throws on malformed sequences — treat as invalid.
+    let decoded;
+    try {
+        decoded = decodeURIComponent(urlPath);
+    }
+    catch {
+        return null;
+    }
+    if (decoded.includes("\0"))
+        return null;
+    // Strip leading slashes so absolute-path injection ("//etc/passwd") becomes relative.
+    const trimmed = decoded.replace(/^[/\\]+/, "");
+    // Empty after strip → caller decides what default file to serve.
+    if (trimmed === "")
+        return null;
+    const rootResolved = path.resolve(root);
+    const candidate = path.resolve(rootResolved, trimmed);
+    // The resolved candidate MUST be either equal to the root or live below it.
+    // Append separator before comparison to avoid the "/var/data" vs "/var/data-evil" trap.
+    const rootWithSep = rootResolved.endsWith(path.sep) ? rootResolved : rootResolved + path.sep;
+    if (candidate !== rootResolved && !candidate.startsWith(rootWithSep)) {
+        return null;
+    }
+    return candidate;
+}

package/dist/src/reset-guard.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Guard for the destructive `/api/reset` endpoint.
+ *
+ * `/api/reset` wipes every coordination table. When `COORDINATOR_AUTH_ENABLED`
+ * is on, the upstream auth middleware enforces admin-role tokens for this route
+ * (see `auth.ts` `ADMIN_ONLY_ROUTES`). When auth is OFF (the default), we still
+ * need to prevent accidental data loss in production.
+ *
+ * Allowed when ANY of:
+ *   - NODE_ENV === "test"          (vitest sets this automatically)
+ *   - COORDINATOR_ALLOW_RESET=true (explicit opt-in for dev/CI scripts)
+ *   - authEnabled === true         (handled by the auth middleware upstream)
+ *
+ * Otherwise rejected.
+ */
+export declare function canResetDb(env: NodeJS.ProcessEnv, authEnabled: boolean): boolean;

package/dist/src/reset-guard.js

@@ -0,0 +1,24 @@
+/**
+ * Guard for the destructive `/api/reset` endpoint.
+ *
+ * `/api/reset` wipes every coordination table. When `COORDINATOR_AUTH_ENABLED`
+ * is on, the upstream auth middleware enforces admin-role tokens for this route
+ * (see `auth.ts` `ADMIN_ONLY_ROUTES`). When auth is OFF (the default), we still
+ * need to prevent accidental data loss in production.
+ *
+ * Allowed when ANY of:
+ *   - NODE_ENV === "test"          (vitest sets this automatically)
+ *   - COORDINATOR_ALLOW_RESET=true (explicit opt-in for dev/CI scripts)
+ *   - authEnabled === true         (handled by the auth middleware upstream)
+ *
+ * Otherwise rejected.
+ */
+export function canResetDb(env, authEnabled) {
+    if (authEnabled)
+        return true;
+    if (env.NODE_ENV === "test")
+        return true;
+    if (env.COORDINATOR_ALLOW_RESET === "true")
+        return true;
+    return false;
+}

package/dist/src/serve-http.d.ts

@@ -1,5 +1,35 @@
 export interface ServerOptions {
     port?: number;
     dataDir?: string;
+    /**
+     * MQTT TCP listener port. Defaults to COORDINATOR_MQTT_TCP_PORT env or 1883.
+     * Pass an OS-ephemeral free port (see net.createServer().listen(0)) to run
+     * multiple coordinators in the same process without collision.
+     */
+    mqttTcpPort?: number;
+    /**
+     * MQTT WebSocket path on the HTTP server. Defaults to COORDINATOR_MQTT_WS_PATH or "/mqtt".
+     */
+    mqttWsPath?: string;
+    /**
+     * If false, do NOT register process-level SIGTERM/SIGINT handlers. Default
+     * true. Embedders that manage their own signals (essaim's orchestrator runs
+     * many in-process coordinators per session) should pass false and call
+     * `handle.stop()` from their own teardown.
+     */
+    registerSignalHandlers?: boolean;
 }
-export declare function startServer(opts?: ServerOptions): Promise<void>;
+/**
+ * Returned by startServer(). Lets callers shut down all owned resources
+ * (HTTP server, MQTT broker + bridge, SSE listeners, DB, quota timer) without
+ * waiting for process exit. Safe to call multiple times.
+ *
+ * Backward-compatible: previous callers used `await startServer({...})` and
+ * ignored the resolved value. They continue to work; the new return value is
+ * additive.
+ */
+export interface ServerHandle {
+    port: number;
+    stop: () => Promise<void>;
+}
+export declare function startServer(opts?: ServerOptions): Promise<ServerHandle>;