mcp-coordinator 0.3.0 → 0.5.0

package/dist/src/impact-scorer.d.ts

@@ -1,6 +1,7 @@
 import type { AgentRegistry } from "./agent-registry.js";
 import type { FileTracker } from "./file-tracker.js";
 import type { Consultation } from "./consultation.js";
+import type { WorkingFilesTracker } from "./working-files-tracker.js";
 export interface ImpactScore {
     agent_id: string;
     agent_name: string;
@@ -19,13 +20,16 @@ interface AnnounceParams {
     target_files: string[];
     depends_on_files?: string[];
     exports_affected?: string[];
+    target_symbols?: string[];
 }
 export declare class ImpactScorer {
     private registry;
     private fileTracker;
     private consultation?;
-    constructor(registry: AgentRegistry, fileTracker: FileTracker, consultation?: Consultation | undefined);
+    private workingFiles?;
+    constructor(registry: AgentRegistry, fileTracker: FileTracker, consultation?: Consultation | undefined, workingFiles?: WorkingFilesTracker | undefined);
     score(params: AnnounceParams): ImpactScore[];
     categorize(params: AnnounceParams): CategorizedImpact;
+    private getRecentSymbolsForFile;
 }
 export {};

package/dist/src/impact-scorer.js

@@ -1,83 +1,171 @@
+import { getDb } from "./database.js";
+// 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;
     consultation;
-    constructor(registry, fileTracker, consultation) {
+    workingFiles;
+    constructor(registry, fileTracker, consultation, workingFiles) {
         this.registry = registry;
         this.fileTracker = fileTracker;
         this.consultation = consultation;
+        this.workingFiles = workingFiles;
     }
     score(params) {
         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();
+        const inFlightToAgents = this.workingFiles
+            ? this.workingFiles.getIndex(filesToIndex, params.agent_id)
+            : new Map();
+        // Pre-load symbols_touched for the target_files × online_agents matrix once,
+        // keyed by (file_path, agent_id). Avoids N*M DB roundtrips inside the score loop.
+        let symbolsByFileAgent = null;
+        if (params.target_symbols && params.target_symbols.length > 0 && params.target_files.length > 0) {
+            const db = getDb();
+            const placeholders = params.target_files.map(() => "?").join(",");
+            const rows = db.prepare(`SELECT agent_id, file_path, symbols_touched
+         FROM file_activity
+         WHERE file_path IN (${placeholders})
+           AND symbols_touched IS NOT NULL
+           AND id IN (
+             SELECT MAX(id) FROM file_activity
+             WHERE file_path IN (${placeholders})
+               AND symbols_touched IS NOT NULL
+             GROUP BY agent_id, file_path
+           )`).all(...params.target_files, ...params.target_files);
+            symbolsByFileAgent = new Map();
+            for (const r of rows) {
+                try {
+                    const arr = JSON.parse(r.symbols_touched);
+                    symbolsByFileAgent.set(`${r.file_path}|${r.agent_id}`, arr);
+                }
+                catch { /* malformed JSON: ignore */ }
+            }
+        }
+        // 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 (file_activity) OR currently in flight (working_files).
             for (const targetFile of params.target_files) {
-                const conflict = this.fileTracker.checkFileConflict(targetFile, params.agent_id, 60);
-                if (conflict.agents.includes(agent.id)) {
+                const recentAgents = fileToAgents.get(targetFile);
+                const inFlightAgents = inFlightToAgents.get(targetFile);
+                if (recentAgents && recentAgents.has(agent.id)) {
                     maxScore = Math.max(maxScore, 100);
-                    reasons.push(`same file: ${targetFile}`);
+                    let annotated = false;
+                    if (params.target_symbols && params.target_symbols.length > 0) {
+                        const theirSymbols = symbolsByFileAgent?.get(`${targetFile}|${agent.id}`) || null;
+                        if (theirSymbols && theirSymbols.length > 0) {
+                            const mine = new Set(params.target_symbols);
+                            const theirs = new Set(theirSymbols);
+                            const overlap = [...mine].some(s => theirs.has(s));
+                            if (!overlap) {
+                                reasons.push(`same file: ${targetFile}; disjoint symbols: you=[${[...mine].join(",")}], them=[${[...theirs].join(",")}] — verify shared module state`);
+                                annotated = true;
+                            }
+                        }
+                    }
+                    if (!annotated) {
+                        reasons.push(`same file (recent): ${targetFile}`);
+                    }
+                }
+                if (inFlightAgents && inFlightAgents.has(agent.id)) {
+                    maxScore = Math.max(maxScore, 100);
+                    reasons.push(`same file (in flight): ${targetFile}`);
                 }
             }
             // 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}`);
                     }
@@ -89,9 +177,34 @@ export class ImpactScorer {
                 maxScore = Math.max(maxScore, 30);
                 reasons.push(`module overlap: ${overlapping.join(", ")}`);
             }
-            // Layer 4 (future): Git co-change analysis
-            // Score 60 for >50% co-change ratio, 40 for >20%
-            // Requires git history analysis — not implemented in v3 prototype
+            // Layer 4: git co-change. For each target_file F, find rows in git_cochange where
+            // (LEAST(F,partner), GREATEST(F,partner)) match. If the OTHER agent recently
+            // touched the partner file, apply the co-change score.
+            const db = getDb();
+            for (const targetFile of params.target_files) {
+                const rows = db.prepare(`SELECT file_a, file_b, count, total_commits FROM git_cochange
+           WHERE file_a = ? OR file_b = ?`).all(targetFile, targetFile);
+                for (const r of rows) {
+                    const partner = r.file_a === targetFile ? r.file_b : r.file_a;
+                    const ratio = r.count / Math.max(r.total_commits, 1);
+                    let layer4Score = 0;
+                    if (ratio > 0.5)
+                        layer4Score = 60;
+                    else if (ratio > 0.2)
+                        layer4Score = 40;
+                    if (layer4Score === 0)
+                        continue;
+                    // Did the OTHER agent touch the partner file recently?
+                    const partnerActivity = db.prepare(`SELECT 1 FROM file_activity
+             WHERE file_path = ? AND agent_id = ?
+               AND created_at > datetime('now', '-60 minutes')
+             LIMIT 1`).get(partner, agent.id);
+                    if (partnerActivity) {
+                        maxScore = Math.max(maxScore, layer4Score);
+                        reasons.push(`co-change: ${targetFile} ↔ ${partner} (ratio ${ratio.toFixed(2)})`);
+                    }
+                }
+            }
             return {
                 agent_id: agent.id,
                 agent_name: agent.name,
@@ -109,4 +222,18 @@ export class ImpactScorer {
             pass: scores.filter((s) => s.score < 30),
         };
     }
+    getRecentSymbolsForFile(filePath, agentId) {
+        const db = getDb();
+        const row = db.prepare(`SELECT symbols_touched FROM file_activity
+       WHERE agent_id = ? AND file_path = ? AND symbols_touched IS NOT NULL
+       ORDER BY id DESC LIMIT 1`).get(agentId, filePath);
+        if (!row || !row.symbols_touched)
+            return null;
+        try {
+            return JSON.parse(row.symbols_touched);
+        }
+        catch {
+            return null;
+        }
+    }
 }

package/dist/src/metrics.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 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>;
+    readonly workingFilesActive: Gauge<string>;
+    readonly gitCochangePairs: Gauge<string>;
+    readonly workingFilesStarts: Counter<"result">;
+    readonly treeSitterParseFailures: Counter<string>;
+    readonly gitCochangeBuilds: Counter<"outcome">;
+    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,195 @@
+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;
+    workingFilesActive;
+    gitCochangePairs;
+    // v0.6 counters
+    workingFilesStarts;
+    treeSitterParseFailures;
+    gitCochangeBuilds;
+    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],
+        });
+        this.workingFilesActive = new Gauge({
+            name: "mcp_coordinator_working_files_active",
+            help: "Current working_files row count",
+            registers: [this.registry],
+        });
+        this.workingFilesStarts = new Counter({
+            name: "mcp_coordinator_working_files_starts_total",
+            help: "Total working_files start calls",
+            labelNames: ["result"],
+            registers: [this.registry],
+        });
+        this.treeSitterParseFailures = new Counter({
+            name: "mcp_coordinator_tree_sitter_parse_failures_total",
+            help: "Tree-sitter parse failures",
+            registers: [this.registry],
+        });
+        this.gitCochangeBuilds = new Counter({
+            name: "mcp_coordinator_git_cochange_builds_total",
+            help: "git_cochange build attempts",
+            labelNames: ["outcome"],
+            registers: [this.registry],
+        });
+        this.gitCochangePairs = new Gauge({
+            name: "mcp_coordinator_git_cochange_pairs_total",
+            help: "Current git_cochange row count",
+            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,16 +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;