mcp-coordinator 0.2.1 → 0.4.0

package/dist/src/impact-scorer.js

@@ -1,3 +1,12 @@
+// Layer 0 (announced-intent) recency window. Resolved threads older than this
+// are excluded — yesterday's resolved work shouldn't trigger today's scoring.
+// Aligned with file-tracker's default conflict window per the audit guidance.
+const LAYER_0_WINDOW_MINUTES = 30;
+// Layer 1 / 2 (file-activity) recency window. Preserved at 60 minutes to keep
+// strict behavioral parity with the original scorer (the prior implementation
+// hard-coded 60 in the checkFileConflict calls). Performance optimizations
+// must not change scoring outcomes for existing callers.
+const FILE_ACTIVITY_WINDOW_MINUTES = 60;
 export class ImpactScorer {
     registry;
     fileTracker;
@@ -11,64 +20,92 @@ export class ImpactScorer {
         const onlineAgents = this.registry
             .listOnline()
             .filter((a) => a.id !== params.agent_id);
+        if (onlineAgents.length === 0)
+            return [];
+        // O1: cache parsed agent.modules JSON ONCE per scoring call.
+        // Previously each agent's modules were JSON.parse'd inside the hot path
+        // (Layer 3), which is O(A) parses for A agents. With Layer 0 also reading
+        // thread.target_files / depends_on_files per agent, the original code
+        // re-parsed agent state up to ~4·A times per call.
+        const moduleCache = new Map();
+        for (const a of onlineAgents) {
+            moduleCache.set(a.id, JSON.parse(a.modules));
+        }
+        // O3: pre-compute file → set<agent_id> for every file we'll inspect.
+        // Replaces N `checkFileConflict` calls (each = 1 SQL round-trip) with a
+        // single batched query, and turns the inner per-agent file check into
+        // an O(1) Set.has() lookup.
+        const filesToIndex = [
+            ...params.target_files,
+            ...(params.depends_on_files || []),
+        ];
+        const fileToAgents = filesToIndex.length > 0
+            ? this.fileTracker.getFileToAgentsIndex(filesToIndex, params.agent_id, FILE_ACTIVITY_WINDOW_MINUTES)
+            : new Map();
+        // O2: bound the resolved-thread query to a recency window. Without this,
+        // listThreads({status:'resolved'}) returns ALL historical resolved threads
+        // (unbounded growth). The Layer 0 filter only keeps threads where the
+        // initiator is the currently-evaluated agent, but the SQL still scanned
+        // every row before the JS filter ran. Since-bound at the SQL layer.
+        let activeThreadsByAgent = null;
+        if (this.consultation) {
+            const allActive = [
+                ...this.consultation.listThreads({ status: "open" }),
+                ...this.consultation.listThreads({ status: "resolving" }),
+                ...this.consultation.listThreads({ status: "resolved", since_minutes: LAYER_0_WINDOW_MINUTES }),
+            ];
+            // Group by initiator_id so the per-agent loop is O(threads-for-this-agent)
+            // rather than O(all-active-threads). Avoids an outer-product scan over
+            // (agents × threads) when both sets are large.
+            activeThreadsByAgent = new Map();
+            for (const t of allActive) {
+                const list = activeThreadsByAgent.get(t.initiator_id);
+                if (list) {
+                    list.push(t);
+                }
+                else {
+                    activeThreadsByAgent.set(t.initiator_id, [t]);
+                }
+            }
+        }
         return onlineAgents.map((agent) => {
-            const agentModules = JSON.parse(agent.modules);
+            const agentModules = moduleCache.get(agent.id);
             const reasons = [];
             let maxScore = 0;
             // Layer 0: Announced intent overlap (checks active threads from this agent).
-            // Resolved threads older than LAYER_0_RESOLVED_WINDOW_MS are excluded —
-            // yesterday's resolved work shouldn't trigger today's scoring.
-            if (this.consultation) {
-                const LAYER_0_RESOLVED_WINDOW_MS = 30 * 60 * 1000; // 30 minutes
-                const now = Date.now();
-                // SQLite datetime('now') returns UTC without a TZ suffix. new Date(str)
-                // parses it as local time by default — causing a local-offset skew.
-                // Normalize by treating the space as T and appending Z.
-                const parseSqliteUtc = (s) => {
-                    const iso = /[Tt]/.test(s) ? s : s.replace(" ", "T");
-                    return new Date(/[zZ]|[+-]\d{2}:?\d{2}$/.test(iso) ? iso : iso + "Z").getTime();
-                };
-                const activeThreads = [
-                    ...this.consultation.listThreads({ status: "open" }),
-                    ...this.consultation.listThreads({ status: "resolving" }),
-                    ...this.consultation
-                        .listThreads({ status: "resolved" })
-                        .filter((t) => {
-                        if (!t.resolved_at)
-                            return true;
-                        const resolvedAt = parseSqliteUtc(t.resolved_at);
-                        return !isNaN(resolvedAt) && now - resolvedAt <= LAYER_0_RESOLVED_WINDOW_MS;
-                    }),
-                ].filter((t) => t.initiator_id === agent.id);
-                for (const thread of activeThreads) {
-                    const threadFiles = JSON.parse(thread.target_files || "[]");
-                    const threadDeps = JSON.parse(thread.depends_on_files || "[]");
-                    // 0a: My target_files ∩ their target_files → score 100
-                    const fileOverlap = params.target_files.filter((f) => threadFiles.includes(f));
-                    if (fileOverlap.length > 0) {
-                        maxScore = Math.max(maxScore, 100);
-                        reasons.push(`announced same file: ${fileOverlap.join(", ")} (thread ${thread.id.slice(0, 8)})`);
-                    }
-                    // 0b: My depends_on ∩ their target_files → score 80 (they modify what I depend on)
-                    if (params.depends_on_files) {
-                        const depOverlap = params.depends_on_files.filter((f) => threadFiles.includes(f));
-                        if (depOverlap.length > 0) {
+            if (activeThreadsByAgent) {
+                const agentThreads = activeThreadsByAgent.get(agent.id);
+                if (agentThreads) {
+                    for (const thread of agentThreads) {
+                        const threadFiles = JSON.parse(thread.target_files || "[]");
+                        const threadDeps = JSON.parse(thread.depends_on_files || "[]");
+                        // 0a: My target_files ∩ their target_files → score 100
+                        const fileOverlap = params.target_files.filter((f) => threadFiles.includes(f));
+                        if (fileOverlap.length > 0) {
+                            maxScore = Math.max(maxScore, 100);
+                            reasons.push(`announced same file: ${fileOverlap.join(", ")} (thread ${thread.id.slice(0, 8)})`);
+                        }
+                        // 0b: My depends_on ∩ their target_files → score 80 (they modify what I depend on)
+                        if (params.depends_on_files) {
+                            const depOverlap = params.depends_on_files.filter((f) => threadFiles.includes(f));
+                            if (depOverlap.length > 0) {
+                                maxScore = Math.max(maxScore, 80);
+                                reasons.push(`modifies my dependency: ${depOverlap.join(", ")} (thread ${thread.id.slice(0, 8)})`);
+                            }
+                        }
+                        // 0c: My target_files ∩ their depends_on → score 80 (I modify what they depend on)
+                        const reverseDepOverlap = params.target_files.filter((f) => threadDeps.includes(f));
+                        if (reverseDepOverlap.length > 0) {
                             maxScore = Math.max(maxScore, 80);
-                            reasons.push(`modifies my dependency: ${depOverlap.join(", ")} (thread ${thread.id.slice(0, 8)})`);
+                            reasons.push(`they depend on my target: ${reverseDepOverlap.join(", ")} (thread ${thread.id.slice(0, 8)})`);
                         }
                     }
-                    // 0c: My target_files ∩ their depends_on → score 80 (I modify what they depend on)
-                    const reverseDepOverlap = params.target_files.filter((f) => threadDeps.includes(f));
-                    if (reverseDepOverlap.length > 0) {
-                        maxScore = Math.max(maxScore, 80);
-                        reasons.push(`they depend on my target: ${reverseDepOverlap.join(", ")} (thread ${thread.id.slice(0, 8)})`);
-                    }
                 }
             }
-            // Layer 1: Same file recently modified (score 100)
+            // Layer 1: Same file recently modified (score 100) — uses pre-built index.
             for (const targetFile of params.target_files) {
-                const conflict = this.fileTracker.checkFileConflict(targetFile, params.agent_id, 60);
-                if (conflict.agents.includes(agent.id)) {
+                const agentsForFile = fileToAgents.get(targetFile);
+                if (agentsForFile && agentsForFile.has(agent.id)) {
                     maxScore = Math.max(maxScore, 100);
                     reasons.push(`same file: ${targetFile}`);
                 }
@@ -76,8 +113,8 @@ export class ImpactScorer {
             // Layer 2: Depends-on file recently modified (score 80)
             if (params.depends_on_files) {
                 for (const depFile of params.depends_on_files) {
-                    const conflict = this.fileTracker.checkFileConflict(depFile, params.agent_id, 60);
-                    if (conflict.agents.includes(agent.id)) {
+                    const agentsForFile = fileToAgents.get(depFile);
+                    if (agentsForFile && agentsForFile.has(agent.id)) {
                         maxScore = Math.max(maxScore, 80);
                         reasons.push(`depends on: ${depFile}`);
                     }

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/metrics.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Prometheus /metrics endpoint for mcp-coordinator (v0.4 Operability fix).
+ *
+ * Audit gap: README claims "Production-ready" but only exposed /health stub.
+ * This module wires prom-client counters/gauges keyed off the events that
+ * already flow through the coordinator (announces, resolutions, MQTT
+ * publishes, REST requests, auth rejections) plus a snapshot of the live
+ * system state (agents, threads, MQTT listeners, SSE clients).
+ *
+ * Design notes:
+ *  - Uses a per-instance `Registry` (not the global default registry) so that
+ *    multiple Coordinator instances in the same process (essaim's orchestrator
+ *    pattern) get isolated metric counters instead of cross-contaminating.
+ *  - Gauges are pulled lazily from a `services` snapshot at scrape time via
+ *    `gaugeSnapshot()` — cheaper than maintaining mirror state and guarantees
+ *    the value matches the DB (no drift from missed events).
+ *  - SSE clients and MQTT listeners aren't exposed as public counts on those
+ *    classes today. Callers update those gauges directly via `setSseClients`
+ *    / `setMqttListeners` from the request lifecycle (see integration patch).
+ */
+import type { IncomingMessage, ServerResponse } from "http";
+import { Registry, Counter, Gauge } from "prom-client";
+import type { CoordinatorServices } from "./server-setup.js";
+export type AnnounceResult = "thread_opened" | "auto_resolved";
+export type ResolutionType = "consensus" | "timeout" | "auto_resolved" | "agent_departure" | "max_rounds" | "closed";
+export interface MetricsOptions {
+    /**
+     * If true, also collect Node.js process metrics (CPU, memory, event-loop
+     * lag, etc.) via prom-client's collectDefaultMetrics. Default: true.
+     */
+    collectDefault?: boolean;
+}
+export declare class Metrics {
+    readonly registry: Registry;
+    readonly announces: Counter<"result">;
+    readonly threadsResolved: Counter<"type">;
+    readonly mqttPublishes: Counter<string>;
+    readonly httpRequests: Counter<"route" | "status">;
+    readonly authRejected: Counter<string>;
+    readonly agentsOnline: Gauge<string>;
+    readonly threadsOpen: Gauge<string>;
+    readonly threadsResolving: Gauge<string>;
+    readonly mqttListenersActive: Gauge<string>;
+    readonly sseClientsActive: Gauge<string>;
+    constructor(opts?: MetricsOptions);
+    recordAnnounce(result: AnnounceResult): void;
+    recordThreadResolved(type: ResolutionType): void;
+    recordMqttPublish(): void;
+    recordHttpRequest(route: string, status: number): void;
+    recordAuthRejected(): void;
+    setSseClients(n: number): void;
+    incSseClients(): void;
+    decSseClients(): void;
+    setMqttListeners(n: number): void;
+    /**
+     * Snapshot the gauges that derive from durable state (agents/threads).
+     * Called at scrape time so the values are fresh without us having to mirror
+     * every state transition. Safe to call repeatedly.
+     *
+     * Reads via the DB directly because AgentRegistry/Consultation don't yet
+     * expose count getters — adding them would touch unrelated modules.
+     */
+    gaugeSnapshot(services: CoordinatorServices): void;
+    /**
+     * Render the current registry as Prometheus text exposition format.
+     * Returns the body string + the content-type to set on the response.
+     */
+    render(): Promise<{
+        body: string;
+        contentType: string;
+    }>;
+}
+/**
+ * HTTP handler for GET /metrics. Refreshes the derived gauges from a
+ * services snapshot, then writes the prom-client text exposition.
+ *
+ * Wire from serve-http.ts:
+ *     if (url === "/metrics" && req.method === "GET") {
+ *       await serveMetrics(req, res, services, metrics);
+ *       return;
+ *     }
+ */
+export declare function serveMetrics(_req: IncomingMessage, res: ServerResponse, services: CoordinatorServices, metrics: Metrics): Promise<void>;

package/dist/src/metrics.js

@@ -0,0 +1,162 @@
+import { Registry, Counter, Gauge, collectDefaultMetrics, } from "prom-client";
+import { getDb } from "./database.js";
+export class Metrics {
+    registry;
+    // Counters
+    announces;
+    threadsResolved;
+    mqttPublishes;
+    httpRequests;
+    authRejected;
+    // Gauges
+    agentsOnline;
+    threadsOpen;
+    threadsResolving;
+    mqttListenersActive;
+    sseClientsActive;
+    constructor(opts = {}) {
+        this.registry = new Registry();
+        if (opts.collectDefault !== false) {
+            collectDefaultMetrics({ register: this.registry });
+        }
+        this.announces = new Counter({
+            name: "mcp_coordinator_announces_total",
+            help: "Total announce_work calls, partitioned by outcome",
+            labelNames: ["result"],
+            registers: [this.registry],
+        });
+        this.threadsResolved = new Counter({
+            name: "mcp_coordinator_threads_resolved_total",
+            help: "Total threads resolved, partitioned by resolution type",
+            labelNames: ["type"],
+            registers: [this.registry],
+        });
+        this.mqttPublishes = new Counter({
+            name: "mcp_coordinator_mqtt_publishes_total",
+            help: "Total MQTT publishes by the coordinator bridge",
+            registers: [this.registry],
+        });
+        this.httpRequests = new Counter({
+            name: "mcp_coordinator_http_requests_total",
+            help: "Total HTTP requests handled, partitioned by route + status",
+            labelNames: ["route", "status"],
+            registers: [this.registry],
+        });
+        this.authRejected = new Counter({
+            name: "mcp_coordinator_auth_rejected_total",
+            help: "Total authentication rejections",
+            registers: [this.registry],
+        });
+        this.agentsOnline = new Gauge({
+            name: "mcp_coordinator_agents_online",
+            help: "Current number of agents reporting status=online",
+            registers: [this.registry],
+        });
+        this.threadsOpen = new Gauge({
+            name: "mcp_coordinator_threads_open",
+            help: "Current number of threads in status=open",
+            registers: [this.registry],
+        });
+        this.threadsResolving = new Gauge({
+            name: "mcp_coordinator_threads_resolving",
+            help: "Current number of threads in status=resolving",
+            registers: [this.registry],
+        });
+        this.mqttListenersActive = new Gauge({
+            name: "mcp_coordinator_mqtt_listeners_active",
+            help: "Current number of registered MQTT consultation listeners",
+            registers: [this.registry],
+        });
+        this.sseClientsActive = new Gauge({
+            name: "mcp_coordinator_sse_clients_active",
+            help: "Current number of connected SSE clients",
+            registers: [this.registry],
+        });
+    }
+    // ── Counter helpers (named methods make hook points obvious) ──
+    recordAnnounce(result) {
+        this.announces.inc({ result }, 1);
+    }
+    recordThreadResolved(type) {
+        this.threadsResolved.inc({ type }, 1);
+    }
+    recordMqttPublish() {
+        this.mqttPublishes.inc(1);
+    }
+    recordHttpRequest(route, status) {
+        this.httpRequests.inc({ route, status: String(status) }, 1);
+    }
+    recordAuthRejected() {
+        this.authRejected.inc(1);
+    }
+    // ── Gauge setters (called from request lifecycle, see integration patch) ──
+    setSseClients(n) {
+        this.sseClientsActive.set(n);
+    }
+    incSseClients() {
+        this.sseClientsActive.inc(1);
+    }
+    decSseClients() {
+        this.sseClientsActive.dec(1);
+    }
+    setMqttListeners(n) {
+        this.mqttListenersActive.set(n);
+    }
+    /**
+     * Snapshot the gauges that derive from durable state (agents/threads).
+     * Called at scrape time so the values are fresh without us having to mirror
+     * every state transition. Safe to call repeatedly.
+     *
+     * Reads via the DB directly because AgentRegistry/Consultation don't yet
+     * expose count getters — adding them would touch unrelated modules.
+     */
+    gaugeSnapshot(services) {
+        try {
+            this.agentsOnline.set(services.registry.listOnline().length);
+        }
+        catch {
+            // Registry not initialised yet (test bootstrap race) — leave gauge at 0.
+        }
+        try {
+            const db = getDb();
+            const open = db
+                .prepare("SELECT COUNT(*) as c FROM threads WHERE status = 'open'")
+                .get();
+            const resolving = db
+                .prepare("SELECT COUNT(*) as c FROM threads WHERE status = 'resolving'")
+                .get();
+            this.threadsOpen.set(open.c);
+            this.threadsResolving.set(resolving.c);
+        }
+        catch {
+            // DB not initialised — leave gauges at their last-set values.
+        }
+    }
+    /**
+     * Render the current registry as Prometheus text exposition format.
+     * Returns the body string + the content-type to set on the response.
+     */
+    async render() {
+        const body = await this.registry.metrics();
+        return { body, contentType: this.registry.contentType };
+    }
+}
+/**
+ * HTTP handler for GET /metrics. Refreshes the derived gauges from a
+ * services snapshot, then writes the prom-client text exposition.
+ *
+ * Wire from serve-http.ts:
+ *     if (url === "/metrics" && req.method === "GET") {
+ *       await serveMetrics(req, res, services, metrics);
+ *       return;
+ *     }
+ */
+export async function serveMetrics(_req, res, services, metrics) {
+    metrics.gaugeSnapshot(services);
+    const { body, contentType } = await metrics.render();
+    res.writeHead(200, {
+        "Content-Type": contentType,
+        "Cache-Control": "no-cache",
+    });
+    res.end(body);
+}

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

@@ -10,14 +10,35 @@ export declare class MqttBridge {
     private onOfflineHandler;
     private listeners;
     private log;
+    private agentId;
+    /**
+     * P1: track the last threadId we retained on `coordinator/consultations/new`.
+     * The topic is fixed (not per-thread), so retain holds only the LAST event.
+     * `clearRetainedConsultation(threadId)` only clears when it matches, so a
+     * later consultation isn't accidentally wiped by a stale resolve callback.
+     */
+    private lastRetainedConsultationThreadId;
     constructor(logger?: Logger);
     connect(config: {
         url: string;
+        username?: string;
+        password?: string;
+        agentId?: string;
     }): Promise<void>;
     isConnected(): boolean;
     onOffline(handler: (agentId: string) => void): void;
     registerAgent(agentId: string, name: string): void;
     publishConsultation(threadId: string, agentId: string, subject: string, targetModules: string[]): void;
+    /**
+     * P1 fix: clear the retained `coordinator/consultations/new` event when the
+     * matching thread resolves. The topic is fixed (not per-thread), so retain
+     * holds only the LAST consultation — clearing here means a coordinator
+     * restart after resolution doesn't re-broadcast a stale "new" event.
+     *
+     * No-op when the supplied threadId doesn't match the currently retained one
+     * (a newer consultation has already overwritten it).
+     */
+    clearRetainedConsultation(threadId: string): void;
     publishMessage(threadId: string, agentId: string, type: string, content: string): void;
     publishResolution(threadId: string, status: string, summary: string): void;
     publishBroadcast(agentId: string, message: string): void;

package/dist/src/mqtt-bridge.js

@@ -6,6 +6,14 @@ export class MqttBridge {
     onOfflineHandler = null;
     listeners = new Map();
     log;
+    agentId = "coordinator-internal";
+    /**
+     * P1: track the last threadId we retained on `coordinator/consultations/new`.
+     * The topic is fixed (not per-thread), so retain holds only the LAST event.
+     * `clearRetainedConsultation(threadId)` only clears when it matches, so a
+     * later consultation isn't accidentally wiped by a stale resolve callback.
+     */
+    lastRetainedConsultationThreadId = null;
     constructor(logger) {
         this.log = logger || silentLogger;
     }
@@ -14,9 +22,24 @@ export class MqttBridge {
             const timeout = setTimeout(() => {
                 reject(new Error("MQTT connection timeout"));
             }, 5000);
+            // P1 fix: LWT requires a stable agent identifier. Default to
+            // "coordinator-internal" which matches the auth identity used by
+            // serve-http for the embedded broker bridge.
+            this.agentId = config.agentId || "coordinator-internal";
             this.client = mqtt.connect(config.url, {
-                clientId: `coordinator-${Date.now()}`,
+                clientId: `${this.agentId}-${Date.now()}`,
                 clean: true,
+                username: config.username,
+                password: config.password,
+                // P1 fix: register Last Will & Testament so a crashed/disconnected
+                // bridge automatically broadcasts offline status. Without this the
+                // agent appears online indefinitely after an unexpected disconnect.
+                will: {
+                    topic: `coordinator/agents/${this.agentId}/status`,
+                    payload: Buffer.from(JSON.stringify({ status: "offline", reason: "lwt_unexpected" })),
+                    qos: 1,
+                    retain: false,
+                },
             });
             this.client.on("connect", () => {
                 clearTimeout(timeout);
@@ -78,17 +101,40 @@ export class MqttBridge {
     publishConsultation(threadId, agentId, subject, targetModules) {
         if (!this.client || !this.connected)
             return;
-        this.client.publish("coordinator/consultations/new", JSON.stringify({ thread_id: threadId, agent_id: agentId, subject, target_modules: targetModules }));
+        // P1 fix: QoS 1 (at-least-once) so consultation events survive transient
+        // disconnects. retain=true so a coordinator/subscriber restart can rebuild
+        // the active state without an event-history replay.
+        this.lastRetainedConsultationThreadId = threadId;
+        this.client.publish("coordinator/consultations/new", JSON.stringify({ thread_id: threadId, agent_id: agentId, subject, target_modules: targetModules }), { qos: 1, retain: true });
+    }
+    /**
+     * P1 fix: clear the retained `coordinator/consultations/new` event when the
+     * matching thread resolves. The topic is fixed (not per-thread), so retain
+     * holds only the LAST consultation — clearing here means a coordinator
+     * restart after resolution doesn't re-broadcast a stale "new" event.
+     *
+     * No-op when the supplied threadId doesn't match the currently retained one
+     * (a newer consultation has already overwritten it).
+     */
+    clearRetainedConsultation(threadId) {
+        if (!this.client || !this.connected)
+            return;
+        if (this.lastRetainedConsultationThreadId !== threadId)
+            return;
+        this.client.publish("coordinator/consultations/new", "", { qos: 1, retain: true });
+        this.lastRetainedConsultationThreadId = null;
     }
     publishMessage(threadId, agentId, type, content) {
         if (!this.client || !this.connected)
             return;
+        // QoS 0: high-frequency chat-style traffic, lossy-OK.
         this.client.publish(`coordinator/consultations/${threadId}/messages`, JSON.stringify({ agent_id: agentId, type, content }));
     }
     publishResolution(threadId, status, summary) {
         if (!this.client || !this.connected)
             return;
-        this.client.publish(`coordinator/consultations/${threadId}/status`, JSON.stringify({ status, summary }), { retain: true });
+        // P1 fix: QoS 1 (at-least-once) — resolution is a state-change event.
+        this.client.publish(`coordinator/consultations/${threadId}/status`, JSON.stringify({ status, summary }), { qos: 1, retain: true });
     }
     publishBroadcast(agentId, message) {
         if (!this.client || !this.connected)
@@ -103,12 +149,15 @@ export class MqttBridge {
     publishTaskClaimed(threadId, claimedBy) {
         if (!this.client || !this.connected)
             return;
-        this.client.publish(`coordinator/consultations/${threadId}/claimed`, JSON.stringify({ agent_id: claimedBy, claimed_by: claimedBy, claimed_at: new Date().toISOString() }));
+        // P1 fix: QoS 1 — claim is a coordination state-change. Loss would mean
+        // multiple agents think a task is unclaimed.
+        this.client.publish(`coordinator/consultations/${threadId}/claimed`, JSON.stringify({ agent_id: claimedBy, claimed_by: claimedBy, claimed_at: new Date().toISOString() }), { qos: 1 });
     }
     publishTaskCompleted(threadId, completedBy, summary) {
         if (!this.client || !this.connected)
             return;
-        this.client.publish(`coordinator/consultations/${threadId}/completed`, JSON.stringify({ agent_id: completedBy, completed_by: completedBy, summary }));
+        // P1 fix: QoS 1 — completion is a coordination state-change.
+        this.client.publish(`coordinator/consultations/${threadId}/completed`, JSON.stringify({ agent_id: completedBy, completed_by: completedBy, summary }), { qos: 1 });
     }
     /**
      * Fanout a refreshed QuotaInfo to live subscribers (dashboard widget,
@@ -118,6 +167,7 @@ export class MqttBridge {
     publishQuotaUpdate(info) {
         if (!this.client || !this.connected)
             return;
+        // QoS 0: high-frequency telemetry, lossy-OK (the next refresh overwrites).
         this.client.publish("coordinator/quota/update", JSON.stringify(info));
     }
     // ── Agent listener methods (for integrated MCP tools) ──

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;