mcp-coordinator 0.3.0 → 0.5.0

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,11 +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);
@@ -80,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)
@@ -105,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,
@@ -120,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/path-normalize.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Normalize a file path for matching/correctness — NOT security.
+ *
+ * Returns POSIX (forward slash), repo-relative when repoRoot is provided,
+ * lower-cased when the path is Windows-style (drive letter prefix in repoRoot
+ * or input, or backslash in input). Collapses ./ and .. segments via
+ * path.posix.normalize.
+ *
+ * The lowercase pass is anchored to path SHAPE rather than `process.platform`
+ * so a Linux coordinator processing paths from a Windows agent (or a CI run
+ * exercising Windows-shaped fixtures) still produces consistent canonical
+ * forms.
+ *
+ * Throws when an absolute path falls outside repoRoot. Security path
+ * traversal checks are separate (see path-guard.ts:safeJoinUnderRoot).
+ */
+export declare function normalizePath(repoRoot: string | null, input: string): string;

package/dist/src/path-normalize.js

@@ -0,0 +1,38 @@
+import path from "path";
+/**
+ * Normalize a file path for matching/correctness — NOT security.
+ *
+ * Returns POSIX (forward slash), repo-relative when repoRoot is provided,
+ * lower-cased when the path is Windows-style (drive letter prefix in repoRoot
+ * or input, or backslash in input). Collapses ./ and .. segments via
+ * path.posix.normalize.
+ *
+ * The lowercase pass is anchored to path SHAPE rather than `process.platform`
+ * so a Linux coordinator processing paths from a Windows agent (or a CI run
+ * exercising Windows-shaped fixtures) still produces consistent canonical
+ * forms.
+ *
+ * Throws when an absolute path falls outside repoRoot. Security path
+ * traversal checks are separate (see path-guard.ts:safeJoinUnderRoot).
+ */
+export function normalizePath(repoRoot, input) {
+    const isWindowsStyle = (repoRoot != null && (/^[a-zA-Z]:/.test(repoRoot) || repoRoot.includes("\\"))) ||
+        /^[a-zA-Z]:/.test(input) ||
+        input.includes("\\");
+    let p = input.replace(/\\/g, "/");
+    if (repoRoot) {
+        const root = repoRoot.replace(/\\/g, "/").replace(/\/+$/, "");
+        if (path.isAbsolute(input) || /^[a-zA-Z]:/.test(input)) {
+            const lowerP = isWindowsStyle ? p.toLowerCase() : p;
+            const lowerRoot = isWindowsStyle ? root.toLowerCase() : root;
+            if (!lowerP.startsWith(lowerRoot + "/") && lowerP !== lowerRoot) {
+                throw new Error(`path is outside repoRoot: ${input}`);
+            }
+            p = p.slice(root.length).replace(/^\/+/, "");
+        }
+    }
+    p = path.posix.normalize(p).replace(/^\.\//, "");
+    if (isWindowsStyle)
+        p = p.toLowerCase();
+    return p;
+}

package/dist/src/serve-http.js

@@ -17,6 +17,8 @@ import { createLogger } from "./logger.js";
 import { initAuth, authenticateRequest, createToken, refreshToken, revokeAgent, setAuthLogger, verifyToken } from "./auth.js";
 import { safeJoinUnderRoot } from "./path-guard.js";
 import { handleRest as handleRestExt } from "./http/handle-rest.js";
+import { handleLivez, handleReadyz, handleHealth } from "./http/handle-health.js";
+import { serveMetrics } from "./metrics.js";
 import { parseBody as parseBodyShared, json as jsonShared } from "./http/utils.js";
 import { getVersion } from "../cli/version.js";
 const VERSION = getVersion();
@@ -83,7 +85,15 @@ async function handleRest(req, res) {
 }
 async function handleAuth(req, res) {
     const url = req.url || "";
-    const body = await parseBody(req);
+    let body;
+    try {
+        body = await parseBody(req);
+    }
+    catch (err) {
+        const e = err;
+        json(res, { error: e.message || "Invalid request" }, e.statusCode || 400);
+        return;
+    }
     if (url === "/api/auth/register" && req.method === "POST") {
         const { agent_name, registration_secret } = body;
         if (!agent_name || !registration_secret) {
@@ -167,6 +177,16 @@ function writeSseEvent(res, event) {
     const data = injectTimestamp(event.payload, event.created_at ?? new Date().toISOString());
     res.write(`id: ${event.id}\nevent: ${event.type}\ndata: ${data}\n\n`);
 }
+// P3: heartbeat interval in ms. Default 30s — well under nginx/Cloudflare's
+// typical 60s idle SSE timeout, but infrequent enough to add negligible
+// bandwidth (one ":keep-alive\n\n" comment is ~16 bytes).
+const SSE_HEARTBEAT_MS = (() => {
+    const raw = process.env.COORDINATOR_SSE_HEARTBEAT_MS;
+    if (!raw)
+        return 30_000;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : 30_000;
+})();
 function handleSse(req, res) {
     res.writeHead(200, {
         "Content-Type": "text/event-stream",
@@ -174,6 +194,8 @@ function handleSse(req, res) {
         Connection: "keep-alive",
         "Access-Control-Allow-Origin": "*",
     });
+    services.metrics.incSseClients();
+    services.metrics.recordHttpRequest("/api/events", 200);
     // Use Last-Event-ID for resumption, otherwise send last 50
     const lastEventId = parseInt(req.headers["last-event-id"] || "0", 10);
     const events = lastEventId > 0
@@ -186,7 +208,29 @@ function handleSse(req, res) {
     const unsubscribe = services.sseEmitter.addListener((event) => {
         writeSseEvent(res, event);
     });
-    req.on("close", () => unsubscribe());
+    // P3: heartbeat. Browsers ignore the `:` comment line per the SSE spec,
+    // but it counts as activity for intermediate proxies that would otherwise
+    // kill an idle connection after ~60s. Wrapped in try/catch because once
+    // the socket is half-closed res.write throws synchronously.
+    const heartbeat = setInterval(() => {
+        try {
+            res.write(":keep-alive\n\n");
+        }
+        catch {
+            // Connection already torn down — req.on("close") will clean up shortly.
+        }
+    }, SSE_HEARTBEAT_MS);
+    // Don't keep the event loop alive solely for heartbeats; without unref()
+    // a still-open SSE connection at process shutdown delays exit.
+    if (typeof heartbeat.unref === "function")
+        heartbeat.unref();
+    req.on("close", () => {
+        // P3: clear the interval BEFORE unsubscribing so a heartbeat tick that
+        // fires between close and unsubscribe can't write to a dead socket.
+        clearInterval(heartbeat);
+        unsubscribe();
+        services.metrics.decSseClients();
+    });
 }
 export async function startServer(opts) {
     const port = opts?.port ?? PORT;
@@ -272,8 +316,21 @@ export async function startServer(opts) {
                 }
                 return;
             }
+            else if (url === "/livez") {
+                handleLivez(req, res);
+                services.metrics.recordHttpRequest("/livez", 200);
+            }
+            else if (url === "/readyz") {
+                handleReadyz(req, res, services);
+                services.metrics.recordHttpRequest("/readyz", res.statusCode || 0);
+            }
             else if (url === "/health") {
-                json(res, { status: "ok", version: VERSION });
+                handleHealth(req, res);
+                services.metrics.recordHttpRequest("/health", 200);
+            }
+            else if (url === "/metrics" && req.method === "GET") {
+                await serveMetrics(req, res, services, services.metrics);
+                services.metrics.recordHttpRequest("/metrics", 200);
             }
             else if (url === "/api/events" && req.method === "GET") {
                 handleSse(req, res);
@@ -330,15 +387,18 @@ export async function startServer(opts) {
                     const authResult = await authenticateRequest(req);
                     if (!authResult.ok) {
                         authLog.warn({ reason: authResult.error, url, ip: req.socket.remoteAddress }, "Auth rejected");
+                        services.metrics.recordAuthRejected();
                         json(res, { error: authResult.error }, authResult.status);
                         return;
                     }
                 }
                 if (url.startsWith("/api/") && (req.method === "POST" || req.method === "GET")) {
                     await handleRest(req, res);
+                    services.metrics.recordHttpRequest((url.split("?")[0] || ""), res.statusCode || 0);
                 }
                 else {
                     json(res, { error: "not found" }, 404);
+                    services.metrics.recordHttpRequest((url.split("?")[0] || ""), 404);
                 }
             }
         }
@@ -380,10 +440,17 @@ export async function startServer(opts) {
         url: `mqtt://127.0.0.1:${mqttTcpPort}`,
         username: AUTH_ENABLED ? "coordinator-internal" : undefined,
         password: internalToken,
+        // P1 fix: stable agent identity for LWT topic
+        // (`coordinator/agents/coordinator-internal/status`).
+        agentId: "coordinator-internal",
     });
     services.mqttBridge.onOffline((agentId) => {
         services.registry.setOffline(agentId);
         services.consultation.handleAgentDeparture(agentId);
+        // Clear in-flight working_files AFTER consultation cleanup so any future
+        // consultation logic that might inspect working_files state for this agent
+        // sees the pre-cleanup view.
+        services.workingFiles.clearForAgent(agentId);
         services.sseEmitter.emit("agent_offline", { agent_id: agentId });
     });
     // Wait for the HTTP server to be actually listening before resolving the
@@ -449,6 +516,12 @@ export async function startServer(opts) {
         catch (err) {
             log.warn({ err }, "Error stopping timeout sweeper");
         }
+        try {
+            services.workingFiles.stopSweeper();
+        }
+        catch (err) {
+            log.warn({ err }, "Error stopping working-files sweeper");
+        }
         try {
             const { closeDb } = await import("./database.js");
             closeDb?.();

package/dist/src/server-setup.d.ts

@@ -11,6 +11,10 @@ import { SseEmitter } from "./sse-emitter.js";
 import { MqttBridge } from "./mqtt-bridge.js";
 import { AgentActivityTracker } from "./agent-activity.js";
 import { QuotaCache } from "./quota/quota-cache.js";
+import { WorkingFilesTracker } from "./working-files-tracker.js";
+import { Metrics } from "./metrics.js";
+import { TreeSitterExtractor } from "./tree-sitter-extractor.js";
+import { GitCochangeBuilder } from "./git-cochange-builder.js";
 import type { CoordinatorConfig } from "./types.js";
 import { type Logger } from "./logger.js";
 export interface CoordinatorServices {
@@ -22,11 +26,15 @@ export interface CoordinatorServices {
     depMap: DependencyMapper;
     fileTracker: FileTracker;
     impactScorer: ImpactScorer;
+    workingFiles: WorkingFilesTracker;
     introspection: IntrospectionManager;
     contextProvider: SummaryContextProvider;
     sseEmitter: SseEmitter;
     mqttBridge: MqttBridge;
     quotaCache: QuotaCache;
+    metrics: Metrics;
+    treeSitter: TreeSitterExtractor;
+    gitCochange: GitCochangeBuilder | null;
 }
 /** Create shared services (once at startup). */
 export declare function createServices(config: CoordinatorConfig): CoordinatorServices;

package/dist/src/server-setup.js

@@ -18,6 +18,10 @@ import { SseEmitter } from "./sse-emitter.js";
 import { MqttBridge } from "./mqtt-bridge.js";
 import { AgentActivityTracker } from "./agent-activity.js";
 import { QuotaCache } from "./quota/quota-cache.js";
+import { WorkingFilesTracker } from "./working-files-tracker.js";
+import { Metrics } from "./metrics.js";
+import { TreeSitterExtractor } from "./tree-sitter-extractor.js";
+import { GitCochangeBuilder } from "./git-cochange-builder.js";
 import { createLogger } from "./logger.js";
 import { getVersion } from "../cli/version.js";
 const VERSION = getVersion();
@@ -25,17 +29,35 @@ const VERSION = getVersion();
 export function createServices(config) {
     initDatabase(config.dataDir);
     const logger = createLogger();
+    const metrics = new Metrics();
     const registry = new AgentRegistry();
     const activityTracker = new AgentActivityTracker(registry);
     const consultation = new Consultation(logger.child({ component: "consultation" }));
     const depMap = new DependencyMapper();
     const fileTracker = new FileTracker();
-    const impactScorer = new ImpactScorer(registry, fileTracker, consultation);
+    const workingFiles = new WorkingFilesTracker(logger.child({ component: "working-files" }), metrics);
+    workingFiles.startSweeper(parseInt(process.env.COORDINATOR_WORKING_FILES_SWEEP_INTERVAL_MS || "60000", 10));
+    const impactScorer = new ImpactScorer(registry, fileTracker, consultation, workingFiles);
     const introspection = new IntrospectionManager();
     const conflictDetector = new ConflictDetector(consultation, depMap, fileTracker, logger.child({ component: "conflict" }));
     const contextProvider = new SummaryContextProvider(registry, consultation, fileTracker);
     const sseEmitter = new SseEmitter();
     const mqttBridge = new MqttBridge(logger.child({ component: "mqtt" }));
+    const treeSitter = new TreeSitterExtractor(metrics);
+    treeSitter.load().catch(() => { });
+    const repoRoot = process.env.COORDINATOR_REPO_ROOT;
+    const gitCochange = repoRoot
+        ? new GitCochangeBuilder({
+            repoRoot,
+            logger: logger.child({ component: "gitcc" }),
+            metrics,
+            sinceDays: parseInt(process.env.COORDINATOR_LAYER4_SINCE_DAYS || "7", 10),
+            maxCount: parseInt(process.env.COORDINATOR_LAYER4_MAX_COMMITS || "2000", 10),
+            refreshMs: parseInt(process.env.COORDINATOR_LAYER4_REFRESH_INTERVAL_MS || "1800000", 10),
+            retryMs: parseInt(process.env.COORDINATOR_LAYER4_RETRY_MS || "300000", 10),
+        })
+        : null;
+    gitCochange?.startScheduler();
     // Quota cache — macOS-only for now, Linux/Windows stubs return 503 via the
     // /api/quota handler so raids keep running without a quota guardrail there.
     // onRefresh fans the new data out to dashboard (SSE) + any live listener (MQTT)
@@ -62,8 +84,9 @@ export function createServices(config) {
         else if (event.type === "agent_offline")
             quotaCache.onAgentInactive();
     });
-    // Centralized resolution → SSE + MQTT
+    // Centralized resolution → SSE + MQTT + metrics
     consultation.onResolve((event) => {
+        metrics.recordThreadResolved(event.resolution_type);
         sseEmitter.emit("thread_resolved", {
             thread_id: event.thread_id,
             resolution_type: event.resolution_type,
@@ -77,10 +100,15 @@ export function createServices(config) {
         if (event.resolution_type !== "auto_resolved") {
             mqttBridge.publishResolution(event.thread_id, "resolved", event.resolution_summary || "");
         }
+        // P1 fix: clear the retained `coordinator/consultations/new` event so a
+        // coordinator restart doesn't re-broadcast a consultation that's already
+        // been resolved. No-op when the retained slot holds a different (newer)
+        // thread.
+        mqttBridge.clearRetainedConsultation(event.thread_id);
     });
     return {
         logger, registry, activityTracker, consultation, conflictDetector,
-        depMap, fileTracker, impactScorer, introspection, contextProvider, sseEmitter, mqttBridge, quotaCache,
+        depMap, fileTracker, impactScorer, workingFiles, introspection, contextProvider, sseEmitter, mqttBridge, quotaCache, metrics, treeSitter, gitCochange,
     };
 }
 /** Create a new McpServer bound to the shared services (one per MCP session). */

package/dist/src/sse-emitter.d.ts

@@ -1,10 +1,16 @@
 import type { CoordinatorEvent, EventType } from "./types.js";
 type EventListener = (event: CoordinatorEvent) => void;
+export declare const MAX_SSE_CLIENTS: number;
 export declare class SseEmitter {
     private listeners;
+    private rejectedCount;
     emit(type: EventType, payload: Record<string, unknown>): void;
     getEventsSince(lastId: number): CoordinatorEvent[];
     addListener(listener: EventListener): () => void;
     removeAllListeners(): void;
+    /** P3: introspection for tests + ops dashboards. */
+    listenerCount(): number;
+    /** P3: count of addListener calls refused due to MAX_SSE_CLIENTS. */
+    getRejectedCount(): number;
 }
 export {};

package/dist/src/sse-emitter.js

@@ -1,6 +1,25 @@
 import { getDb } from "./database.js";
+/**
+ * P3: bound the listener array so a runaway client (or DoS attempt) can't
+ * grow it without limit. Default 100 covers a small-to-mid swarm — enough
+ * headroom for a dashboard + every agent + a handful of CLI tailers, but
+ * not so large that a leak would silently exhaust memory. Override via
+ * COORDINATOR_MAX_SSE_CLIENTS for larger deployments.
+ */
+const DEFAULT_MAX_SSE_CLIENTS = 100;
+export const MAX_SSE_CLIENTS = (() => {
+    const raw = process.env.COORDINATOR_MAX_SSE_CLIENTS;
+    if (!raw)
+        return DEFAULT_MAX_SSE_CLIENTS;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_MAX_SSE_CLIENTS;
+})();
+const NOOP = () => { };
 export class SseEmitter {
     listeners = [];
+    // P3: track refusals so operators can see when the cap is being hit.
+    // Also lets tests assert "we refused without throwing" without scraping logs.
+    rejectedCount = 0;
     emit(type, payload) {
         const db = getDb();
         const payloadStr = JSON.stringify(payload);
@@ -13,8 +32,22 @@ export class SseEmitter {
             payload: payloadStr,
             created_at: new Date().toISOString(),
         };
-        for (const listener of this.listeners) {
-            listener(event);
+        // P3: async fan-out via setImmediate so a slow listener (e.g. a stalled
+        // SSE client whose socket buffer is full) cannot block siblings or the
+        // emit() caller. Snapshot the array first so a listener that unsubscribes
+        // mid-loop doesn't shift indices under us.
+        const snapshot = this.listeners.slice();
+        for (const listener of snapshot) {
+            setImmediate(() => {
+                try {
+                    listener(event);
+                }
+                catch {
+                    // Listener errors must not crash the emitter or affect siblings.
+                    // Drop silently — the SSE response writers swallow their own
+                    // socket errors via the unsubscribe path on req.on("close").
+                }
+            });
         }
     }
     getEventsSince(lastId) {
@@ -24,6 +57,13 @@ export class SseEmitter {
             .all(lastId);
     }
     addListener(listener) {
+        // P3: refuse-with-no-op when the cap is reached. Returning a no-op
+        // keeps the caller's unsubscribe contract intact (no special-casing
+        // upstream) while preventing the array from growing past MAX_SSE_CLIENTS.
+        if (this.listeners.length >= MAX_SSE_CLIENTS) {
+            this.rejectedCount++;
+            return NOOP;
+        }
         this.listeners.push(listener);
         return () => {
             this.listeners = this.listeners.filter((l) => l !== listener);
@@ -32,4 +72,12 @@ export class SseEmitter {
     removeAllListeners() {
         this.listeners = [];
     }
+    /** P3: introspection for tests + ops dashboards. */
+    listenerCount() {
+        return this.listeners.length;
+    }
+    /** P3: count of addListener calls refused due to MAX_SSE_CLIENTS. */
+    getRejectedCount() {
+        return this.rejectedCount;
+    }
 }

package/dist/src/tools/consultation-tools.js

@@ -30,7 +30,9 @@ export function registerConsultationTools(server, services, mcpLog) {
         exports_affected: z.array(z.string()).optional(),
         keep_open: z.boolean().optional().describe("Keep thread open even if no agents are concerned (for manual coordination like games or debates)"),
         assigned_to: z.string().optional().describe("Directed-dispatch: only this agent_id will be allowed to claim the thread. Use for lead→worker handoffs in maitre/chaine/relais presets. Implies keep_open=true."),
-    }, async ({ agent_id, subject, plan, target_modules, target_files, depends_on_files, exports_affected, keep_open, assigned_to }) => {
+        target_symbols: z.array(z.string().max(256)).max(200).optional()
+            .describe("Qualified symbol names you intend to touch (e.g. 'UserService.getById'). Used by Layer 0.5 to annotate same-file overlaps."),
+    }, async ({ agent_id, subject, plan, target_modules, target_files, depends_on_files, exports_affected, keep_open, assigned_to, target_symbols }) => {
         mcpLog.info({ tool: "announce_work", agent_id, subject, target_modules, target_files, assigned_to }, "Tool called");
         const conflicts = conflictDetector.detect({ agent_id, target_modules, target_files });
         const thread = consultation.announceWork({
@@ -41,7 +43,7 @@ export function registerConsultationTools(server, services, mcpLog) {
                 .run(JSON.stringify(conflicts), thread.id);
         }
         const { updated, categorized, respondents, planQuality } = runCommonAnnounceFlow(services, thread.id, {
-            agent_id, subject, plan, target_modules, target_files, depends_on_files, exports_affected, keep_open,
+            agent_id, subject, plan, target_modules, target_files, depends_on_files, exports_affected, keep_open, target_symbols,
         });
         sseEmitter.emit("thread_opened", {
             thread_id: thread.id, initiator: agent_id, subject, target_modules, conflicts,

package/dist/src/tree-sitter-extractor.d.ts

@@ -0,0 +1,36 @@
+import type { Metrics } from "./metrics.js";
+/**
+ * Tree-sitter symbol extractor.
+ *
+ * Loads grammars asynchronously at boot. extract() runs synchronously per call
+ * so it slots into the existing synchronous file_activity ingest path.
+ *
+ * Naming table per language documented in the v0.6 spec:
+ * - top-level fn / arrow assigned to const → `name`
+ * - class member  → `Class.method`
+ * - anonymous default export → `<file_basename>:default`
+ * - re-exports, anonymous IIFE → not emitted
+ */
+export declare class TreeSitterExtractor {
+    private grammars;
+    private ready;
+    private grammarsLoaded;
+    private totalGrammars;
+    private metrics?;
+    constructor(metrics?: Metrics);
+    load(): Promise<void>;
+    status(): {
+        ok: boolean;
+        grammars_loaded: number;
+        total_grammars: number;
+        optional: true;
+    };
+    /**
+     * Extract qualified symbol names from `content`. Returns null on parse
+     * failure, unsupported extension, or grammar not loaded.
+     * Caps output at 200 entries (per spec).
+     */
+    extract(filePath: string, content: string, _changedRanges: Array<[number, number]> | null): string[] | null;
+    private extToKey;
+    private walk;
+}