code-graph-context 2.2.0 → 2.3.0

package/README.md

@@ -30,6 +30,7 @@ A Model Context Protocol (MCP) server that builds rich code graphs to provide de
 - **Impact Analysis**: Assess refactoring risk with dependency analysis (LOW/MEDIUM/HIGH/CRITICAL scoring)
 - **Dead Code Detection**: Find unreferenced exports, uncalled private methods, unused interfaces with confidence scoring
 - **Duplicate Code Detection**: Identify structural duplicates (identical AST) and semantic duplicates (similar logic via embeddings)
+- **Swarm Coordination**: Multi-agent stigmergic coordination through pheromone markers with exponential decay
 - **High Performance**: Optimized Neo4j storage with vector indexing for fast retrieval
 - **MCP Integration**: Seamless integration with Claude Code and other MCP-compatible tools
 
@@ -255,6 +256,9 @@ npm run build
 | `natural_language_to_cypher` | Convert natural language to Cypher | **Advanced queries** - complex graph queries |
 | `detect_dead_code` | Find unreferenced exports, uncalled methods, unused interfaces | **Code cleanup** - identify potentially removable code |
 | `detect_duplicate_code` | Find structural and semantic code duplicates | **Refactoring** - identify DRY violations |
+| `swarm_pheromone` | Leave pheromone markers on code nodes | **Multi-agent** - stigmergic coordination |
+| `swarm_sense` | Query pheromones in the code graph | **Multi-agent** - sense what other agents are doing |
+| `swarm_cleanup` | Bulk delete pheromones | **Multi-agent** - cleanup after swarm completion |
 | `test_neo4j_connection` | Verify database connectivity | **Health check** - troubleshooting |
 
 > **Note**: All query tools (`search_codebase`, `traverse_from_node`, `impact_analysis`, `natural_language_to_cypher`) require a `projectId` parameter. Use `list_projects` to discover available projects.
@@ -755,6 +759,67 @@ await mcp.call('stop_watch_project', {
 - 1000 pending events per watcher
 - Graceful cleanup on server shutdown
 
+#### 8. Swarm Coordination Tools
+**Purpose**: Enable multiple parallel agents to coordinate work through stigmergic pheromone markers in the code graph—no direct messaging needed.
+
+**Core Concepts:**
+- **Pheromones**: Markers attached to graph nodes that decay over time
+- **swarmId**: Groups related agents for bulk cleanup when done
+- **Workflow States**: `exploring`, `claiming`, `modifying`, `completed`, `blocked` (mutually exclusive per agent+node)
+- **Flags**: `warning`, `proposal`, `needs_review` (can coexist with workflow states)
+
+**Pheromone Types & Decay:**
+| Type | Half-Life | Use |
+|------|-----------|-----|
+| `exploring` | 2 min | Browsing/reading |
+| `modifying` | 10 min | Active work |
+| `claiming` | 1 hour | Ownership |
+| `completed` | 24 hours | Done |
+| `warning` | Never | Danger |
+| `blocked` | 5 min | Stuck |
+| `proposal` | 1 hour | Awaiting approval |
+| `needs_review` | 30 min | Review requested |
+
+```typescript
+// Orchestrator: Generate swarm ID and spawn agents
+const swarmId = `swarm_${Date.now()}`;
+
+// Agent: Check what's claimed before working
+await mcp.call('swarm_sense', {
+  projectId: 'my-backend',
+  swarmId,
+  types: ['claiming', 'modifying']
+});
+
+// Agent: Claim a node before working
+await mcp.call('swarm_pheromone', {
+  projectId: 'my-backend',
+  nodeId: 'proj_xxx:ClassDeclaration:abc123',  // From search_codebase or traverse_from_node
+  type: 'claiming',
+  agentId: 'agent_1',
+  swarmId
+});
+
+// Agent: Mark complete when done
+await mcp.call('swarm_pheromone', {
+  projectId: 'my-backend',
+  nodeId: 'proj_xxx:ClassDeclaration:abc123',
+  type: 'completed',
+  agentId: 'agent_1',
+  swarmId,
+  data: { summary: 'Added soft delete support' }
+});
+
+// Orchestrator: Clean up when swarm is done
+await mcp.call('swarm_cleanup', {
+  projectId: 'my-backend',
+  swarmId,
+  keepTypes: ['warning']  // Preserve warnings
+});
+```
+
+**Important**: Node IDs must come from graph tool responses (`search_codebase`, `traverse_from_node`). Never fabricate node IDs—they are hash-based strings like `proj_xxx:ClassDeclaration:abc123`.
+
 ### Workflow Examples
 
 #### Example 1: Understanding Authentication Flow

package/dist/mcp/constants.js

@@ -31,6 +31,9 @@ export const TOOL_NAMES = {
     listWatchers: 'list_watchers',
     detectDeadCode: 'detect_dead_code',
     detectDuplicateCode: 'detect_duplicate_code',
+    swarmPheromone: 'swarm_pheromone',
+    swarmSense: 'swarm_sense',
+    swarmCleanup: 'swarm_cleanup',
 };
 // Tool Metadata
 export const TOOL_METADATA = {
@@ -354,6 +357,123 @@ Parameters:
 
 Use this to identify refactoring opportunities and reduce code duplication.`,
     },
+    [TOOL_NAMES.swarmPheromone]: {
+        title: 'Swarm Pheromone',
+        description: `Leave a pheromone marker on a code node for stigmergic coordination between agents.
+
+**What is Stigmergy?**
+Agents coordinate indirectly by leaving markers (pheromones) on code nodes. Other agents sense these markers and adapt their behavior. No direct messaging needed.
+
+**Pheromone Types:**
+- exploring: "I'm looking at this" (2 min half-life)
+- modifying: "I'm actively working on this" (10 min half-life)
+- claiming: "This is my territory" (1 hour half-life)
+- completed: "I finished work here" (24 hour half-life)
+- warning: "Danger - don't touch" (never decays)
+- blocked: "I'm stuck on this" (5 min half-life)
+- proposal: "Proposed artifact awaiting approval" (1 hour half-life)
+- needs_review: "Someone should check this" (30 min half-life)
+
+**Parameters:**
+- nodeId: The code node ID to mark
+- type: Type of pheromone (see above)
+- agentId: Your unique agent identifier
+- swarmId: Swarm ID from orchestrator (for bulk cleanup)
+- intensity: 0.0-1.0, how strong the signal (default: 1.0)
+- data: Optional metadata (summary, reason, etc.)
+- remove: Set true to remove the pheromone
+
+**Workflow states** (exploring, claiming, modifying, completed, blocked) are mutually exclusive per agent+node. Setting one automatically removes others.
+
+**Usage Pattern:**
+1. Before starting work: swarm_sense to check what's claimed
+2. Claim your target: swarm_pheromone({ nodeId, type: "claiming", agentId, swarmId })
+3. Refresh periodically if working long
+4. Mark complete: swarm_pheromone({ nodeId, type: "completed", agentId, swarmId, data: { summary: "..." } })
+
+**Decay:**
+Pheromones automatically fade over time. If an agent dies, its markers decay and work becomes available again.`,
+    },
+    [TOOL_NAMES.swarmSense]: {
+        title: 'Swarm Sense',
+        description: `Query pheromones in the code graph to sense what other agents are doing.
+
+**What This Does:**
+Returns active pheromones with their current intensity (after decay). Use this to:
+- See what nodes are being worked on
+- Avoid conflicts with other agents
+- Find unclaimed work
+- Check if your dependencies are being modified
+
+**Parameters:**
+- swarmId: Filter by swarm ID (see only this swarm's pheromones)
+- types: Filter by pheromone types (e.g., ["modifying", "claiming"])
+- nodeIds: Check specific nodes
+- agentIds: Filter by specific agents
+- excludeAgentId: Exclude your own pheromones (see what OTHERS are doing)
+- minIntensity: Minimum intensity after decay (default: 0.3)
+- limit: Max results (default: 50)
+- includeStats: Get summary statistics by type
+- cleanup: Remove fully decayed pheromones (intensity < 0.01)
+
+**Usage Pattern:**
+\`\`\`
+// Before starting work, check what's taken
+swarm_sense({
+  types: ["modifying", "claiming"],
+  minIntensity: 0.3
+})
+
+// Check a specific node before modifying
+swarm_sense({
+  nodeIds: ["proj_xxx:Service:UserService"],
+  types: ["modifying", "warning"]
+})
+
+// See what other agents are doing (exclude self)
+swarm_sense({
+  excludeAgentId: "my-agent-id",
+  types: ["exploring", "modifying"]
+})
+\`\`\`
+
+**Decay:**
+Intensity decreases over time (exponential decay). A pheromone with intensity 0.25 is almost gone. Below minIntensity threshold, it's not returned.`,
+    },
+    [TOOL_NAMES.swarmCleanup]: {
+        title: 'Swarm Cleanup',
+        description: `Bulk delete pheromones after a swarm completes.
+
+**When to use:**
+Call this when a swarm finishes to clean up all its pheromones. Prevents pollution for future swarms.
+
+**Parameters:**
+- projectId: Required - the project
+- swarmId: Delete all pheromones from this swarm
+- agentId: Delete all pheromones from this specific agent
+- all: Set true to delete ALL pheromones in project (use with caution)
+- keepTypes: Pheromone types to preserve (default: ["warning"])
+- dryRun: Preview what would be deleted without deleting
+
+**Must specify one of:** swarmId, agentId, or all=true
+
+**Examples:**
+\`\`\`
+// Clean up after a swarm completes
+swarm_cleanup({ projectId: "backend", swarmId: "swarm_abc123" })
+
+// Preview what would be deleted
+swarm_cleanup({ projectId: "backend", swarmId: "swarm_abc123", dryRun: true })
+
+// Clean up a specific agent's pheromones
+swarm_cleanup({ projectId: "backend", agentId: "swarm_abc123_auth" })
+
+// Nuclear option: delete all (except warnings)
+swarm_cleanup({ projectId: "backend", all: true })
+\`\`\`
+
+**Note:** \`warning\` pheromones are preserved by default. Pass \`keepTypes: []\` to delete everything.`,
+    },
 };
 // Default Values
 export const DEFAULTS = {

package/dist/mcp/handlers/incremental-parse.handler.js

@@ -37,6 +37,7 @@ export const performIncrementalParse = async (projectPath, projectId, tsconfigPa
         });
         // If no changes, return early
         if (filesToReparse.length === 0 && filesToDelete.length === 0) {
+            await debugLog('Incremental parse: no changes, returning early', {});
             return {
                 nodesUpdated: 0,
                 edgesUpdated: 0,
@@ -44,24 +45,35 @@ export const performIncrementalParse = async (projectPath, projectId, tsconfigPa
                 filesDeleted: filesToDelete.length,
             };
         }
+        await debugLog('Incremental parse: changes detected, continuing', { filesToReparse: filesToReparse.length });
         let savedCrossFileEdges = [];
         const filesToRemoveFromGraph = [...filesToDelete, ...filesToReparse];
         if (filesToRemoveFromGraph.length > 0) {
+            await debugLog('Incremental parse: getting cross-file edges', { count: filesToRemoveFromGraph.length });
             // Save cross-file edges before deletion
             savedCrossFileEdges = await getCrossFileEdges(neo4jService, filesToRemoveFromGraph, resolvedId);
+            await debugLog('Incremental parse: got cross-file edges', { savedCount: savedCrossFileEdges.length });
+            await debugLog('Incremental parse: deleting old subgraphs', {});
             // Delete old subgraphs
             await deleteSourceFileSubgraphs(neo4jService, filesToRemoveFromGraph, resolvedId);
+            await debugLog('Incremental parse: deleted old subgraphs', {});
         }
         let nodesImported = 0;
         let edgesImported = 0;
         if (filesToReparse.length > 0) {
+            await debugLog('Incremental parse: loading existing nodes', {});
             // Load existing nodes for edge detection
             const existingNodes = await loadExistingNodesForEdgeDetection(neo4jService, filesToRemoveFromGraph, resolvedId);
+            await debugLog('Incremental parse: loaded existing nodes', { count: existingNodes.length });
             parser.setExistingNodes(existingNodes);
+            await debugLog('Incremental parse: parsing workspace', { fileCount: filesToReparse.length });
             // Parse only changed files
             await parser.parseWorkspace(filesToReparse);
+            await debugLog('Incremental parse: parsed workspace', {});
             // Export graph data
+            await debugLog('Incremental parse: exporting to JSON', {});
             const { nodes, edges } = parser.exportToJson();
+            await debugLog('Incremental parse: exported to JSON', { nodeCount: nodes.length, edgeCount: edges.length });
             // Get framework schemas if available (use unknown as intermediate to access private property)
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const parserAny = parser;
@@ -80,26 +92,33 @@ export const performIncrementalParse = async (projectPath, projectId, tsconfigPa
                 },
             };
             // Write to JSON file (required by GraphGeneratorHandler)
+            await debugLog('Incremental parse: writing JSON file', {});
             const outputPath = join(projectPath, FILE_PATHS.graphOutput);
             writeFileSync(outputPath, JSON.stringify(graphData, null, LOG_CONFIG.jsonIndentation));
+            await debugLog('Incremental parse: wrote JSON file', { outputPath });
             // Update Project node
+            await debugLog('Incremental parse: updating project node', {});
             await neo4jService.run(UPSERT_PROJECT_QUERY, {
                 projectId: resolvedId,
                 path: projectPath,
                 name: projectName,
                 status: 'complete',
             });
+            await debugLog('Incremental parse: updated project node', {});
             // Import nodes and edges (clearExisting = false for incremental)
+            await debugLog('Incremental parse: starting graph import', {});
             graphHandler.setProjectId(resolvedId);
             try {
                 const result = await graphHandler.generateGraph(outputPath, DEFAULTS.batchSize, false);
                 nodesImported = result.nodesImported;
                 edgesImported = result.edgesImported;
+                await debugLog('Incremental parse: graph import completed', { nodesImported, edgesImported });
             }
             finally {
                 // Clean up temporary graph.json file
                 try {
                     unlinkSync(outputPath);
+                    await debugLog('Incremental parse: cleaned up temp file', {});
                 }
                 catch {
                     // Ignore cleanup errors - file may not exist or be inaccessible

package/dist/mcp/mcp.server.js

@@ -22,11 +22,34 @@ import { initializeServices } from './service-init.js';
 import { watchManager } from './services/watch-manager.js';
 import { registerAllTools } from './tools/index.js';
 import { debugLog } from './utils.js';
+// Track server state for debugging
+let serverStartTime;
+let toolCallCount = 0;
+let lastToolCall = null;
+/**
+ * Log memory usage and server stats
+ */
+const logServerStats = async (context) => {
+    const mem = process.memoryUsage();
+    await debugLog(`Server stats [${context}]`, {
+        uptime: serverStartTime ? `${Math.round((Date.now() - serverStartTime.getTime()) / 1000)}s` : 'not started',
+        toolCallCount,
+        lastToolCall,
+        memory: {
+            heapUsed: `${Math.round(mem.heapUsed / 1024 / 1024)}MB`,
+            heapTotal: `${Math.round(mem.heapTotal / 1024 / 1024)}MB`,
+            rss: `${Math.round(mem.rss / 1024 / 1024)}MB`,
+        },
+        pid: process.pid,
+    });
+};
 /**
  * Main server initialization and startup
  */
 const startServer = async () => {
+    serverStartTime = new Date();
     console.error(JSON.stringify({ level: 'info', message: MESSAGES.server.starting }));
+    await debugLog('Server starting', { pid: process.pid, startTime: serverStartTime.toISOString() });
     // Create MCP server instance
     const server = new McpServer({
         name: MCP_SERVER_CONFIG.name,
@@ -34,6 +57,7 @@ const startServer = async () => {
     });
     // Register all tools
     registerAllTools(server);
+    await debugLog('Tools registered', { toolCount: 15 });
     // Configure watch manager with incremental parse handler and MCP server
     watchManager.setIncrementalParseHandler(performIncrementalParse);
     watchManager.setMcpServer(server.server);
@@ -50,22 +74,46 @@ const startServer = async () => {
     });
     // Create and connect transport
     console.error(JSON.stringify({ level: 'info', message: MESSAGES.server.creatingTransport }));
+    await debugLog('Creating stdio transport', {});
     const transport = new StdioServerTransport();
+    // Add transport event logging
+    process.stdin.on('close', async () => {
+        await debugLog('STDIN closed - client disconnected', {});
+        await logServerStats('stdin-close');
+    });
+    process.stdin.on('end', async () => {
+        await debugLog('STDIN ended', {});
+        await logServerStats('stdin-end');
+    });
+    process.stdin.on('error', async (err) => {
+        await debugLog('STDIN error', { error: err.message, stack: err.stack });
+    });
+    process.stdout.on('close', async () => {
+        await debugLog('STDOUT closed', {});
+    });
+    process.stdout.on('error', async (err) => {
+        await debugLog('STDOUT error', { error: err.message, stack: err.stack });
+    });
     console.error(JSON.stringify({ level: 'info', message: MESSAGES.server.connectingTransport }));
+    await debugLog('Connecting transport', {});
     await server.connect(transport);
     console.error(JSON.stringify({ level: 'info', message: MESSAGES.server.connected }));
+    await debugLog('Server connected and ready', { pid: process.pid });
+    await logServerStats('server-ready');
 };
 /**
  * Graceful shutdown handler
  */
 const shutdown = async (signal) => {
     console.error(JSON.stringify({ level: 'info', message: `Received ${signal}, shutting down...` }));
+    await logServerStats(`shutdown-${signal}`);
     try {
         await watchManager.stopAllWatchers();
         await debugLog('Shutdown complete', { signal });
     }
     catch (error) {
         console.error(JSON.stringify({ level: 'error', message: 'Error during shutdown', error: String(error) }));
+        await debugLog('Error during shutdown', { signal, error: String(error) });
     }
     process.exit(0);
 };
@@ -73,14 +121,41 @@ const shutdown = async (signal) => {
 process.on('uncaughtException', async (error) => {
     console.error(JSON.stringify({ level: 'error', message: 'Uncaught exception', error: String(error), stack: error.stack }));
     await debugLog('Uncaught exception', { error: String(error), stack: error.stack });
+    await logServerStats('uncaught-exception');
 });
 process.on('unhandledRejection', async (reason) => {
     console.error(JSON.stringify({ level: 'error', message: 'Unhandled rejection', reason: String(reason) }));
     await debugLog('Unhandled rejection', { reason: String(reason) });
+    await logServerStats('unhandled-rejection');
+});
+// Log other process events that might indicate issues
+process.on('warning', async (warning) => {
+    await debugLog('Process warning', { name: warning.name, message: warning.message, stack: warning.stack });
+});
+process.on('beforeExit', async (code) => {
+    await debugLog('Process beforeExit', { code });
+    await logServerStats('before-exit');
+});
+process.on('exit', (code) => {
+    // Note: Can't use async here, exit is synchronous
+    console.error(JSON.stringify({ level: 'info', message: `Process exiting with code ${code}` }));
 });
 // Register shutdown handlers
-process.on('SIGINT', () => shutdown('SIGINT'));
+// NOTE: Only handle SIGTERM for graceful shutdown. SIGINT is ignored because
+// Claude Code may propagate SIGINT to child processes when spawning agents,
+// which would incorrectly kill the MCP server. The MCP server lifecycle is
+// managed by Claude Code via stdio transport closure.
 process.on('SIGTERM', () => shutdown('SIGTERM'));
+// Log SIGINT but don't exit - Claude Code manages our lifecycle
+process.on('SIGINT', async () => {
+    await debugLog('SIGINT received but ignored - lifecycle managed by Claude Code', {});
+    await logServerStats('sigint-ignored');
+});
+// Also ignore SIGHUP which can be sent during terminal operations
+process.on('SIGHUP', async () => {
+    await debugLog('SIGHUP received but ignored', {});
+    await logServerStats('sighup-ignored');
+});
 // Start the server
 console.error(JSON.stringify({ level: 'info', message: MESSAGES.server.startingServer }));
 await startServer();

package/dist/mcp/services/watch-manager.js

@@ -26,9 +26,12 @@ class WatchManager {
      * Send a notification via MCP logging (if supported)
      */
     sendNotification(notification) {
+        debugLog('sendNotification called', { type: notification.type, projectId: notification.projectId });
         if (!this.mcpServer) {
+            debugLog('sendNotification: no MCP server, skipping', {});
             return;
         }
+        debugLog('sendNotification: sending to MCP', { type: notification.type });
         // sendLoggingMessage returns a Promise - use .catch() to handle rejection
         this.mcpServer
             .sendLoggingMessage({
@@ -36,9 +39,16 @@ class WatchManager {
             logger: 'file-watcher',
             data: notification,
         })
-            .catch(() => {
-            // MCP logging not supported - silently ignore
+            .then(() => {
+            debugLog('sendNotification: MCP message sent successfully', { type: notification.type });
+        })
+            .catch((error) => {
+            // MCP logging not supported - log but don't crash
             // This is expected if the client doesn't support logging capability
+            debugLog('sendNotification: MCP message failed (expected if client lacks logging)', {
+                type: notification.type,
+                error: String(error)
+            });
         });
     }
     /**
@@ -128,7 +138,7 @@ class WatchManager {
      * Handle a file system event
      */
     handleFileEvent(state, type, filePath) {
-        debugLog('File event received', { type, filePath, projectId: state.projectId, status: state.status });
+        debugLog('handleFileEvent START', { type, filePath, projectId: state.projectId, status: state.status, isStopping: state.isStopping });
         // Ignore events if watcher is stopping or not active
         if (state.isStopping || state.status !== 'active') {
             debugLog('Ignoring event - watcher not active or stopping', {
@@ -166,20 +176,35 @@ class WatchManager {
             timestamp: new Date().toISOString(),
         });
         // Set new debounce timer
+        debugLog('handleFileEvent: setting debounce timer', { debounceMs: state.config.debounceMs });
         state.debounceTimer = setTimeout(() => {
+            debugLog('handleFileEvent: debounce timer fired, calling processEvents', { projectId: state.projectId });
             this.processEvents(state).catch((error) => {
+                debugLog('handleFileEvent: processEvents error', { error: String(error) });
                 console.error('[WatchManager] Error in processEvents:', error);
             });
         }, state.config.debounceMs);
+        debugLog('handleFileEvent END', { pendingCount: state.pendingEvents.length });
     }
     /**
      * Process accumulated file events after debounce period
      */
     async processEvents(state) {
+        await debugLog('processEvents START', {
+            projectId: state.projectId,
+            isProcessing: state.isProcessing,
+            pendingCount: state.pendingEvents.length,
+            isStopping: state.isStopping
+        });
         // Don't process if already processing, no events, or watcher is stopping
-        if (state.isProcessing || state.pendingEvents.length === 0 || state.isStopping)
+        if (state.isProcessing || state.pendingEvents.length === 0 || state.isStopping) {
+            await debugLog('processEvents: early return', {
+                reason: state.isProcessing ? 'already processing' : state.pendingEvents.length === 0 ? 'no events' : 'stopping'
+            });
             return;
+        }
         state.isProcessing = true;
+        await debugLog('processEvents: set isProcessing=true', {});
         const events = [...state.pendingEvents];
         state.pendingEvents = [];
         state.debounceTimer = null;
@@ -199,7 +224,15 @@ class WatchManager {
             if (!this.incrementalParseHandler) {
                 throw new Error('Incremental parse handler not configured');
             }
+            await debugLog('processEvents: calling incrementalParseHandler', {
+                projectPath: state.projectPath,
+                projectId: state.projectId
+            });
             const result = await this.incrementalParseHandler(state.projectPath, state.projectId, state.tsconfigPath);
+            await debugLog('processEvents: incrementalParseHandler returned', {
+                nodesUpdated: result.nodesUpdated,
+                edgesUpdated: result.edgesUpdated
+            });
             state.lastUpdateTime = new Date();
             const elapsedMs = Date.now() - startTime;
             this.sendNotification({
@@ -221,6 +254,7 @@ class WatchManager {
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
+            await debugLog('processEvents: error caught', { error: errorMessage });
             this.sendNotification({
                 type: 'incremental_parse_failed',
                 projectId: state.projectId,
@@ -235,6 +269,7 @@ class WatchManager {
         }
         finally {
             state.isProcessing = false;
+            await debugLog('processEvents END', { projectId: state.projectId, isProcessing: state.isProcessing });
         }
     }
     /**
@@ -243,9 +278,14 @@ class WatchManager {
     handleWatcherError(state, error) {
         state.status = 'error';
         state.errorMessage = error instanceof Error ? error.message : String(error);
-        debugLog('Watcher error', { projectId: state.projectId, error: state.errorMessage });
+        debugLog('handleWatcherError START', { projectId: state.projectId, error: state.errorMessage });
         // Clean up the failed watcher to prevent it from staying in error state indefinitely
-        this.stopWatching(state.projectId).catch((cleanupError) => {
+        this.stopWatching(state.projectId)
+            .then(() => {
+            debugLog('handleWatcherError: cleanup succeeded', { projectId: state.projectId });
+        })
+            .catch((cleanupError) => {
+            debugLog('handleWatcherError: cleanup failed', { projectId: state.projectId, cleanupError: String(cleanupError) });
             console.error(`[WatchManager] Failed to cleanup errored watcher ${state.projectId}:`, cleanupError);
         });
     }
@@ -255,23 +295,33 @@ class WatchManager {
      * Promise is tracked on state to allow cleanup during stop
      */
     syncMissedChanges(state) {
-        if (!this.incrementalParseHandler)
+        debugLog('syncMissedChanges START', { projectId: state.projectId });
+        if (!this.incrementalParseHandler) {
+            debugLog('syncMissedChanges: no handler, skipping', {});
             return;
+        }
         // Track the promise on state so stopWatching can wait for it
         state.syncPromise = this.incrementalParseHandler(state.projectPath, state.projectId, state.tsconfigPath)
             .then((result) => {
+            debugLog('syncMissedChanges: completed', {
+                projectId: state.projectId,
+                nodesUpdated: result.nodesUpdated,
+                edgesUpdated: result.edgesUpdated
+            });
             if (result.nodesUpdated > 0 || result.edgesUpdated > 0) {
                 console.log(`[WatchManager] Synced missed changes for ${state.projectId}: ` +
                     `${result.nodesUpdated} nodes, ${result.edgesUpdated} edges`);
             }
         })
             .catch((error) => {
+            debugLog('syncMissedChanges: error', { projectId: state.projectId, error: String(error), isStopping: state.isStopping });
             // Only log if watcher hasn't been stopped
             if (!state.isStopping) {
                 console.error(`[WatchManager] Failed to sync missed changes for ${state.projectId}:`, error);
             }
         })
             .finally(() => {
+            debugLog('syncMissedChanges END', { projectId: state.projectId });
             state.syncPromise = undefined;
         });
     }

package/dist/mcp/tools/hello.tool.js

@@ -3,11 +3,25 @@
  * Simple test tool to verify MCP connection
  */
 import { TOOL_NAMES, TOOL_METADATA, MESSAGES } from '../constants.js';
-import { createSuccessResponse } from '../utils.js';
+import { createSuccessResponse, debugLog } from '../utils.js';
+import { logToolCallStart, logToolCallEnd } from './index.js';
 export const createHelloTool = (server) => {
     server.registerTool(TOOL_NAMES.hello, {
         title: TOOL_METADATA[TOOL_NAMES.hello].title,
         description: TOOL_METADATA[TOOL_NAMES.hello].description,
         inputSchema: {},
-    }, async () => createSuccessResponse(MESSAGES.success.hello));
+    }, async () => {
+        const startTime = Date.now();
+        const callId = await logToolCallStart('hello');
+        try {
+            const result = createSuccessResponse(MESSAGES.success.hello);
+            await logToolCallEnd('hello', callId, true, Date.now() - startTime);
+            return result;
+        }
+        catch (error) {
+            await debugLog('Hello tool error', { error: String(error) });
+            await logToolCallEnd('hello', callId, false, Date.now() - startTime);
+            throw error;
+        }
+    });
 };

package/dist/mcp/tools/index.js

@@ -2,6 +2,7 @@
  * MCP Tool Factory
  * Centralized tool creation and registration
  */
+import { debugLog } from '../utils.js';
 import { createCheckParseStatusTool } from './check-parse-status.tool.js';
 import { createDetectDeadCodeTool } from './detect-dead-code.tool.js';
 import { createDetectDuplicateCodeTool } from './detect-duplicate-code.tool.js';
@@ -14,8 +15,36 @@ import { createParseTypescriptProjectTool } from './parse-typescript-project.too
 import { createSearchCodebaseTool } from './search-codebase.tool.js';
 import { createStartWatchProjectTool } from './start-watch-project.tool.js';
 import { createStopWatchProjectTool } from './stop-watch-project.tool.js';
+import { createSwarmCleanupTool } from './swarm-cleanup.tool.js';
+import { createSwarmPheromoneTool } from './swarm-pheromone.tool.js';
+import { createSwarmSenseTool } from './swarm-sense.tool.js';
 import { createTestNeo4jConnectionTool } from './test-neo4j-connection.tool.js';
 import { createTraverseFromNodeTool } from './traverse-from-node.tool.js';
+// Track tool calls for debugging
+let globalToolCallCount = 0;
+/**
+ * Log tool call start (exported for use by individual tools)
+ */
+export const logToolCallStart = async (toolName, params) => {
+    globalToolCallCount++;
+    const callId = globalToolCallCount;
+    await debugLog(`Tool call START: ${toolName}`, {
+        callId,
+        totalCalls: globalToolCallCount,
+        params: params ? JSON.stringify(params).substring(0, 500) : 'none',
+    });
+    return callId;
+};
+/**
+ * Log tool call end (exported for use by individual tools)
+ */
+export const logToolCallEnd = async (toolName, callId, success, duration) => {
+    await debugLog(`Tool call END: ${toolName}`, {
+        callId,
+        success,
+        duration: duration ? `${duration}ms` : 'unknown',
+    });
+};
 /**
  * Register all MCP tools with the server
  */
@@ -39,4 +68,8 @@ export const registerAllTools = (server) => {
     createStartWatchProjectTool(server);
     createStopWatchProjectTool(server);
     createListWatchersTool(server);
+    // Register swarm coordination tools
+    createSwarmPheromoneTool(server);
+    createSwarmSenseTool(server);
+    createSwarmCleanupTool(server);
 };

package/dist/mcp/tools/swarm-cleanup.tool.js

@@ -0,0 +1,157 @@
+/**
+ * Swarm Cleanup Tool
+ * Bulk delete pheromones after a swarm completes
+ */
+import { z } from 'zod';
+import { Neo4jService } from '../../storage/neo4j/neo4j.service.js';
+import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
+import { createErrorResponse, createSuccessResponse, resolveProjectIdOrError, debugLog } from '../utils.js';
+/**
+ * Neo4j query to delete pheromones by swarm ID
+ */
+const CLEANUP_BY_SWARM_QUERY = `
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId
+    AND p.swarmId = $swarmId
+    AND NOT p.type IN $keepTypes
+  WITH p, p.agentId as agentId, p.type as type
+  DETACH DELETE p
+  RETURN count(p) as deleted, collect(DISTINCT agentId) as agents, collect(DISTINCT type) as types
+`;
+/**
+ * Neo4j query to delete pheromones by agent ID
+ */
+const CLEANUP_BY_AGENT_QUERY = `
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId
+    AND p.agentId = $agentId
+    AND NOT p.type IN $keepTypes
+  WITH p, p.swarmId as swarmId, p.type as type
+  DETACH DELETE p
+  RETURN count(p) as deleted, collect(DISTINCT swarmId) as swarms, collect(DISTINCT type) as types
+`;
+/**
+ * Neo4j query to delete all pheromones in a project
+ */
+const CLEANUP_ALL_QUERY = `
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId
+    AND NOT p.type IN $keepTypes
+  WITH p, p.agentId as agentId, p.swarmId as swarmId, p.type as type
+  DETACH DELETE p
+  RETURN count(p) as deleted, collect(DISTINCT agentId) as agents, collect(DISTINCT swarmId) as swarms, collect(DISTINCT type) as types
+`;
+/**
+ * Count queries for dry run
+ */
+const COUNT_BY_SWARM_QUERY = `
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId AND p.swarmId = $swarmId AND NOT p.type IN $keepTypes
+  RETURN count(p) as count, collect(DISTINCT p.agentId) as agents, collect(DISTINCT p.type) as types
+`;
+const COUNT_BY_AGENT_QUERY = `
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId AND p.agentId = $agentId AND NOT p.type IN $keepTypes
+  RETURN count(p) as count, collect(DISTINCT p.swarmId) as swarms, collect(DISTINCT p.type) as types
+`;
+const COUNT_ALL_QUERY = `
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId AND NOT p.type IN $keepTypes
+  RETURN count(p) as count, collect(DISTINCT p.agentId) as agents, collect(DISTINCT p.swarmId) as swarms, collect(DISTINCT p.type) as types
+`;
+export const createSwarmCleanupTool = (server) => {
+    server.registerTool(TOOL_NAMES.swarmCleanup, {
+        title: TOOL_METADATA[TOOL_NAMES.swarmCleanup].title,
+        description: TOOL_METADATA[TOOL_NAMES.swarmCleanup].description,
+        inputSchema: {
+            projectId: z.string().describe('Project ID, name, or path'),
+            swarmId: z.string().optional().describe('Delete all pheromones from this swarm'),
+            agentId: z.string().optional().describe('Delete all pheromones from this agent'),
+            all: z.boolean().optional().default(false).describe('Delete ALL pheromones in project (use with caution)'),
+            keepTypes: z
+                .array(z.string())
+                .optional()
+                .default(['warning'])
+                .describe('Pheromone types to preserve (default: ["warning"])'),
+            dryRun: z.boolean().optional().default(false).describe('Preview what would be deleted without deleting'),
+        },
+    }, async ({ projectId, swarmId, agentId, all = false, keepTypes = ['warning'], dryRun = false }) => {
+        const neo4jService = new Neo4jService();
+        // Resolve project ID
+        const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
+        if (!projectResult.success) {
+            await neo4jService.close();
+            return projectResult.error;
+        }
+        const resolvedProjectId = projectResult.projectId;
+        try {
+            // Validate: must specify swarmId, agentId, or all
+            if (!swarmId && !agentId && !all) {
+                return createErrorResponse('Must specify one of: swarmId, agentId, or all=true. Use dryRun=true to preview.');
+            }
+            await debugLog('Swarm cleanup operation', {
+                projectId: resolvedProjectId,
+                swarmId,
+                agentId,
+                all,
+                keepTypes,
+                dryRun,
+            });
+            const params = { projectId: resolvedProjectId, keepTypes };
+            let deleteQuery;
+            let countQuery;
+            let mode;
+            if (swarmId) {
+                params.swarmId = swarmId;
+                deleteQuery = CLEANUP_BY_SWARM_QUERY;
+                countQuery = COUNT_BY_SWARM_QUERY;
+                mode = 'swarm';
+            }
+            else if (agentId) {
+                params.agentId = agentId;
+                deleteQuery = CLEANUP_BY_AGENT_QUERY;
+                countQuery = COUNT_BY_AGENT_QUERY;
+                mode = 'agent';
+            }
+            else {
+                deleteQuery = CLEANUP_ALL_QUERY;
+                countQuery = COUNT_ALL_QUERY;
+                mode = 'all';
+            }
+            if (dryRun) {
+                const result = await neo4jService.run(countQuery, params);
+                const count = result[0]?.count ?? 0;
+                return createSuccessResponse(JSON.stringify({
+                    success: true,
+                    dryRun: true,
+                    mode,
+                    wouldDelete: typeof count === 'object' && 'toNumber' in count ? count.toNumber() : count,
+                    agents: result[0]?.agents ?? [],
+                    swarms: result[0]?.swarms ?? [],
+                    types: result[0]?.types ?? [],
+                    keepTypes,
+                    projectId: resolvedProjectId,
+                }));
+            }
+            const result = await neo4jService.run(deleteQuery, params);
+            const deleted = result[0]?.deleted ?? 0;
+            return createSuccessResponse(JSON.stringify({
+                success: true,
+                mode,
+                deleted: typeof deleted === 'object' && 'toNumber' in deleted ? deleted.toNumber() : deleted,
+                agents: result[0]?.agents ?? [],
+                swarms: result[0]?.swarms ?? [],
+                types: result[0]?.types ?? [],
+                keepTypes,
+                projectId: resolvedProjectId,
+            }));
+        }
+        catch (error) {
+            await debugLog('Swarm cleanup error', { error: String(error) });
+            return createErrorResponse(error instanceof Error ? error : String(error));
+        }
+        finally {
+            await neo4jService.close();
+        }
+    });
+};

package/dist/mcp/tools/swarm-constants.js

@@ -0,0 +1,35 @@
+/**
+ * Shared constants for swarm coordination tools
+ */
+/**
+ * Pheromone types and their half-lives in milliseconds.
+ * Half-life determines decay rate - after one half-life, intensity drops to 50%.
+ */
+export const PHEROMONE_CONFIG = {
+    exploring: { halfLife: 2 * 60 * 1000, description: 'Browsing/reading' },
+    modifying: { halfLife: 10 * 60 * 1000, description: 'Active work' },
+    claiming: { halfLife: 60 * 60 * 1000, description: 'Ownership' },
+    completed: { halfLife: 24 * 60 * 60 * 1000, description: 'Done' },
+    warning: { halfLife: -1, description: 'Never decays' },
+    blocked: { halfLife: 5 * 60 * 1000, description: 'Stuck' },
+    proposal: { halfLife: 60 * 60 * 1000, description: 'Awaiting approval' },
+    needs_review: { halfLife: 30 * 60 * 1000, description: 'Review requested' },
+};
+export const PHEROMONE_TYPES = Object.keys(PHEROMONE_CONFIG);
+/**
+ * Get half-life for a pheromone type.
+ * Returns -1 for types that never decay (e.g., warning).
+ */
+export const getHalfLife = (type) => {
+    return PHEROMONE_CONFIG[type]?.halfLife ?? PHEROMONE_CONFIG.exploring.halfLife;
+};
+/**
+ * Workflow states are mutually exclusive per agent+node.
+ * Setting one removes others in this group.
+ * Flags (warning, proposal, needs_review) can coexist with workflow states.
+ */
+export const WORKFLOW_STATES = ['exploring', 'claiming', 'modifying', 'completed', 'blocked'];
+/**
+ * Flags can coexist with workflow states.
+ */
+export const FLAG_TYPES = ['warning', 'proposal', 'needs_review'];

package/dist/mcp/tools/swarm-pheromone.tool.js

@@ -0,0 +1,196 @@
+/**
+ * Swarm Pheromone Tool
+ * Leave a pheromone marker on a code node for stigmergic coordination
+ */
+import { z } from 'zod';
+import { Neo4jService } from '../../storage/neo4j/neo4j.service.js';
+import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
+import { createErrorResponse, createSuccessResponse, resolveProjectIdOrError, debugLog } from '../utils.js';
+import { PHEROMONE_TYPES, WORKFLOW_STATES, getHalfLife } from './swarm-constants.js';
+/**
+ * Neo4j query to clean up other workflow states before setting a new one.
+ * Only runs for workflow state pheromones, not flags.
+ */
+const CLEANUP_WORKFLOW_STATES_QUERY = `
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId
+    AND p.nodeId = $nodeId
+    AND p.agentId = $agentId
+    AND p.swarmId = $swarmId
+    AND p.type IN $workflowStates
+    AND p.type <> $newType
+  DETACH DELETE p
+  RETURN count(p) as cleaned
+`;
+/**
+ * Neo4j query to create or update a pheromone
+ */
+const CREATE_PHEROMONE_QUERY = `
+  // Find the target code node (exclude other pheromones)
+  MATCH (target)
+  WHERE target.id = $nodeId
+    AND target.projectId = $projectId
+    AND NOT target:Pheromone
+  WITH target
+  LIMIT 1
+
+  // Create or update pheromone (scoped to project)
+  MERGE (p:Pheromone {projectId: $projectId, nodeId: $nodeId, agentId: $agentId, swarmId: $swarmId, type: $type})
+  ON CREATE SET
+    p.id = randomUUID(),
+    p.intensity = $intensity,
+    p.timestamp = timestamp(),
+    p.data = $data,
+    p.halfLife = $halfLife
+  ON MATCH SET
+    p.intensity = $intensity,
+    p.timestamp = timestamp(),
+    p.data = $data
+
+  // Create relationship to target node if it exists
+  WITH p, target
+  WHERE target IS NOT NULL
+  MERGE (p)-[:MARKS]->(target)
+
+  RETURN p.id as id, p.nodeId as nodeId, p.projectId as projectId, p.type as type, p.intensity as intensity,
+         p.timestamp as timestamp, p.agentId as agentId, p.swarmId as swarmId,
+         CASE WHEN target IS NOT NULL THEN true ELSE false END as linkedToNode
+`;
+/**
+ * Neo4j query to delete a pheromone
+ */
+const DELETE_PHEROMONE_QUERY = `
+  MATCH (p:Pheromone {projectId: $projectId, nodeId: $nodeId, agentId: $agentId, swarmId: $swarmId, type: $type})
+  DETACH DELETE p
+  RETURN count(p) as deleted
+`;
+export const createSwarmPheromoneTool = (server) => {
+    server.registerTool(TOOL_NAMES.swarmPheromone, {
+        title: TOOL_METADATA[TOOL_NAMES.swarmPheromone].title,
+        description: TOOL_METADATA[TOOL_NAMES.swarmPheromone].description,
+        inputSchema: {
+            projectId: z.string().describe('Project ID, name, or path (e.g., "backend" or "proj_a1b2c3d4e5f6")'),
+            nodeId: z.string().describe('The code node ID to mark with a pheromone'),
+            type: z
+                .enum(PHEROMONE_TYPES)
+                .describe('Type of pheromone: exploring (browsing), modifying (active work), claiming (ownership), completed (done), warning (danger), blocked (stuck), proposal (awaiting approval), needs_review (review request)'),
+            intensity: z
+                .number()
+                .min(0)
+                .max(1)
+                .optional()
+                .default(1.0)
+                .describe('Pheromone intensity from 0.0 to 1.0 (default: 1.0)'),
+            agentId: z.string().describe('Unique identifier for the agent leaving the pheromone'),
+            swarmId: z.string().describe('Swarm ID for grouping related agents (e.g., "swarm_xyz")'),
+            data: z
+                .record(z.unknown())
+                .optional()
+                .describe('Optional metadata to attach to the pheromone (e.g., summary, reason)'),
+            remove: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('If true, removes the pheromone instead of creating/updating it'),
+        },
+    }, async ({ projectId, nodeId, type, intensity = 1.0, agentId, swarmId, data, remove = false }) => {
+        const neo4jService = new Neo4jService();
+        // Resolve project ID
+        const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
+        if (!projectResult.success) {
+            await neo4jService.close();
+            return projectResult.error;
+        }
+        const resolvedProjectId = projectResult.projectId;
+        try {
+            if (remove) {
+                const result = await neo4jService.run(DELETE_PHEROMONE_QUERY, {
+                    projectId: resolvedProjectId,
+                    nodeId,
+                    agentId,
+                    swarmId,
+                    type,
+                });
+                const deleted = result[0]?.deleted ?? 0;
+                if (deleted > 0) {
+                    return createSuccessResponse(JSON.stringify({
+                        success: true,
+                        action: 'removed',
+                        projectId: resolvedProjectId,
+                        nodeId,
+                        type,
+                        agentId,
+                        swarmId,
+                    }));
+                }
+                else {
+                    return createSuccessResponse(JSON.stringify({
+                        success: true,
+                        action: 'not_found',
+                        message: 'No matching pheromone found to remove',
+                        projectId: resolvedProjectId,
+                        nodeId,
+                        type,
+                        agentId,
+                        swarmId,
+                    }));
+                }
+            }
+            // Create or update pheromone
+            const halfLife = getHalfLife(type);
+            const dataJson = data ? JSON.stringify(data) : null;
+            // If setting a workflow state, clean up other workflow states first
+            let cleanedStates = 0;
+            if (WORKFLOW_STATES.includes(type)) {
+                const cleanupResult = await neo4jService.run(CLEANUP_WORKFLOW_STATES_QUERY, {
+                    projectId: resolvedProjectId,
+                    nodeId,
+                    agentId,
+                    swarmId,
+                    workflowStates: WORKFLOW_STATES,
+                    newType: type,
+                });
+                cleanedStates = cleanupResult[0]?.cleaned ?? 0;
+            }
+            const result = await neo4jService.run(CREATE_PHEROMONE_QUERY, {
+                projectId: resolvedProjectId,
+                nodeId,
+                type,
+                intensity,
+                agentId,
+                swarmId,
+                data: dataJson,
+                halfLife,
+            });
+            if (result.length === 0) {
+                return createErrorResponse(`Failed to create pheromone. Node ${nodeId} may not exist in the graph.`);
+            }
+            const pheromone = result[0];
+            return createSuccessResponse(JSON.stringify({
+                success: true,
+                action: cleanedStates > 0 ? 'transitioned' : 'created',
+                previousStatesRemoved: cleanedStates,
+                pheromone: {
+                    id: pheromone.id,
+                    projectId: pheromone.projectId,
+                    nodeId: pheromone.nodeId,
+                    type: pheromone.type,
+                    intensity: pheromone.intensity,
+                    agentId: pheromone.agentId,
+                    swarmId: pheromone.swarmId,
+                    timestamp: pheromone.timestamp,
+                    linkedToNode: pheromone.linkedToNode,
+                    halfLifeMs: halfLife,
+                    expiresIn: halfLife < 0 ? 'never' : `${Math.round(halfLife / 60000)} minutes`,
+                },
+            }));
+        }
+        catch (error) {
+            await debugLog('Swarm pheromone error', { error: String(error) });
+            return createErrorResponse(error instanceof Error ? error : String(error));
+        }
+        finally {
+            await neo4jService.close();
+        }
+    });
+};

package/dist/mcp/tools/swarm-sense.tool.js

@@ -0,0 +1,212 @@
+/**
+ * Swarm Sense Tool
+ * Query pheromones in the code graph for stigmergic coordination
+ */
+import { z } from 'zod';
+import { Neo4jService } from '../../storage/neo4j/neo4j.service.js';
+import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
+import { createErrorResponse, createSuccessResponse, resolveProjectIdOrError, debugLog } from '../utils.js';
+import { PHEROMONE_TYPES } from './swarm-constants.js';
+/**
+ * Neo4j query to sense pheromones with decay calculation
+ * Uses nodeId-based matching (self-healing) instead of [:MARKS] relationship
+ * This survives graph rebuilds since nodeIds are deterministic
+ */
+const SENSE_PHEROMONES_QUERY = `
+  // Match pheromones scoped to project, optionally filtering by type
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId
+    AND ($types IS NULL OR size($types) = 0 OR p.type IN $types)
+    AND ($nodeIds IS NULL OR size($nodeIds) = 0 OR p.nodeId IN $nodeIds)
+    AND ($agentIds IS NULL OR size($agentIds) = 0 OR p.agentId IN $agentIds)
+    AND ($swarmId IS NULL OR p.swarmId = $swarmId)
+    AND ($excludeAgentId IS NULL OR p.agentId <> $excludeAgentId)
+
+  // Calculate current intensity with exponential decay
+  WITH p,
+    CASE
+      WHEN p.halfLife IS NULL OR p.halfLife <= 0 THEN p.intensity
+      ELSE p.intensity * exp(-0.693147 * (timestamp() - p.timestamp) / p.halfLife)
+    END AS currentIntensity
+
+  // Filter by minimum intensity
+  WHERE currentIntensity >= $minIntensity
+
+  // Find target by nodeId (self-healing - survives graph rebuilds)
+  OPTIONAL MATCH (target)
+  WHERE target.id = p.nodeId AND target.projectId = p.projectId
+
+  // Return pheromone data
+  RETURN
+    p.id AS id,
+    p.projectId AS projectId,
+    p.nodeId AS nodeId,
+    p.type AS type,
+    p.intensity AS originalIntensity,
+    currentIntensity,
+    p.agentId AS agentId,
+    p.swarmId AS swarmId,
+    p.timestamp AS timestamp,
+    p.data AS data,
+    p.halfLife AS halfLifeMs,
+    CASE WHEN target IS NOT NULL THEN labels(target)[0] ELSE null END AS targetType,
+    CASE WHEN target IS NOT NULL THEN target.name ELSE null END AS targetName,
+    CASE WHEN target IS NOT NULL THEN target.filePath ELSE null END AS targetFilePath
+
+  ORDER BY currentIntensity DESC, p.timestamp DESC
+  LIMIT toInteger($limit)
+`;
+/**
+ * Neo4j query to get pheromone summary statistics
+ */
+const PHEROMONE_STATS_QUERY = `
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId
+  WITH p,
+    CASE
+      WHEN p.halfLife IS NULL OR p.halfLife <= 0 THEN p.intensity
+      ELSE p.intensity * exp(-0.693147 * (timestamp() - p.timestamp) / p.halfLife)
+    END AS currentIntensity
+  WHERE currentIntensity >= $minIntensity
+
+  RETURN
+    p.type AS type,
+    count(p) AS count,
+    avg(currentIntensity) AS avgIntensity,
+    collect(DISTINCT p.agentId) AS agents
+  ORDER BY count DESC
+`;
+/**
+ * Neo4j query to clean up fully decayed pheromones for a project
+ */
+const CLEANUP_DECAYED_QUERY = `
+  MATCH (p:Pheromone)
+  WHERE p.projectId = $projectId
+    AND p.halfLife IS NOT NULL
+    AND p.halfLife > 0
+    AND p.intensity * exp(-0.693147 * (timestamp() - p.timestamp) / p.halfLife) < 0.01
+  DETACH DELETE p
+  RETURN count(p) AS cleaned
+`;
+export const createSwarmSenseTool = (server) => {
+    server.registerTool(TOOL_NAMES.swarmSense, {
+        title: TOOL_METADATA[TOOL_NAMES.swarmSense].title,
+        description: TOOL_METADATA[TOOL_NAMES.swarmSense].description,
+        inputSchema: {
+            projectId: z.string().describe('Project ID, name, or path (e.g., "backend" or "proj_a1b2c3d4e5f6")'),
+            types: z
+                .array(z.enum(PHEROMONE_TYPES))
+                .optional()
+                .describe('Filter by pheromone types. If empty, returns all types. Options: exploring, modifying, claiming, completed, warning, blocked, proposal, needs_review'),
+            nodeIds: z.array(z.string()).optional().describe('Filter by specific node IDs. If empty, searches all nodes.'),
+            agentIds: z
+                .array(z.string())
+                .optional()
+                .describe('Filter by specific agent IDs. If empty, returns pheromones from all agents.'),
+            swarmId: z.string().optional().describe('Filter by swarm ID. If empty, returns pheromones from all swarms.'),
+            excludeAgentId: z
+                .string()
+                .optional()
+                .describe('Exclude pheromones from this agent ID (useful for seeing what OTHER agents are doing)'),
+            minIntensity: z
+                .number()
+                .min(0)
+                .max(1)
+                .optional()
+                .default(0.3)
+                .describe('Minimum effective intensity after decay (0.0-1.0, default: 0.3)'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(500)
+                .optional()
+                .default(50)
+                .describe('Maximum number of pheromones to return (default: 50, max: 500)'),
+            includeStats: z.boolean().optional().default(false).describe('Include summary statistics by pheromone type'),
+            cleanup: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Run cleanup of fully decayed pheromones (intensity < 0.01)'),
+        },
+    }, async ({ projectId, types, nodeIds, agentIds, swarmId, excludeAgentId, minIntensity = 0.3, limit = 50, includeStats = false, cleanup = false, }) => {
+        const neo4jService = new Neo4jService();
+        // Resolve project ID
+        const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
+        if (!projectResult.success) {
+            await neo4jService.close();
+            return projectResult.error;
+        }
+        const resolvedProjectId = projectResult.projectId;
+        try {
+            const result = {
+                pheromones: [],
+                projectId: resolvedProjectId,
+                query: {
+                    types: types ?? null,
+                    minIntensity,
+                    limit,
+                },
+            };
+            // Run cleanup if requested
+            if (cleanup) {
+                const cleanupResult = await neo4jService.run(CLEANUP_DECAYED_QUERY, { projectId: resolvedProjectId });
+                result.cleaned = cleanupResult[0]?.cleaned ?? 0;
+            }
+            // Query pheromones (ensure limit is integer for Neo4j LIMIT clause)
+            const pheromones = await neo4jService.run(SENSE_PHEROMONES_QUERY, {
+                projectId: resolvedProjectId,
+                types: types ?? null,
+                nodeIds: nodeIds ?? null,
+                agentIds: agentIds ?? null,
+                swarmId: swarmId ?? null,
+                excludeAgentId: excludeAgentId ?? null,
+                minIntensity,
+                limit: Math.floor(limit),
+            });
+            result.pheromones = pheromones.map((p) => {
+                // Convert Neo4j Integer to JS number
+                const ts = typeof p.timestamp === 'object' && p.timestamp?.toNumber ? p.timestamp.toNumber() : p.timestamp;
+                return {
+                    id: p.id,
+                    projectId: p.projectId,
+                    nodeId: p.nodeId,
+                    type: p.type,
+                    intensity: Math.round(p.currentIntensity * 1000) / 1000, // Round to 3 decimals
+                    originalIntensity: p.originalIntensity,
+                    agentId: p.agentId,
+                    swarmId: p.swarmId,
+                    timestamp: ts,
+                    age: ts ? `${Math.round((Date.now() - ts) / 1000)}s ago` : null,
+                    data: p.data ? JSON.parse(p.data) : null,
+                    target: p.targetType
+                        ? {
+                            type: p.targetType,
+                            name: p.targetName,
+                            filePath: p.targetFilePath,
+                        }
+                        : null,
+                };
+            });
+            // Include stats if requested
+            if (includeStats) {
+                const stats = await neo4jService.run(PHEROMONE_STATS_QUERY, { projectId: resolvedProjectId, minIntensity });
+                result.stats = stats.map((s) => ({
+                    type: s.type,
+                    count: typeof s.count === 'object' ? s.count.toNumber() : s.count,
+                    avgIntensity: Math.round(s.avgIntensity * 1000) / 1000,
+                    activeAgents: s.agents,
+                }));
+            }
+            return createSuccessResponse(JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            await debugLog('Swarm sense error', { error: String(error) });
+            return createErrorResponse(error instanceof Error ? error : String(error));
+        }
+        finally {
+            await neo4jService.close();
+        }
+    });
+};

package/dist/storage/neo4j/neo4j.service.js

@@ -215,15 +215,19 @@ export const QUERIES = {
     // The previous query (WHERE startNode(r) IS NULL OR endNode(r) IS NULL) could never match anything
     // Get existing nodes (excluding files being reparsed) for edge target matching
     // Returns minimal info needed for edge detection: id, name, coreType, semanticType
+    // NOTE: Using property-based query instead of path traversal to avoid Cartesian explosion
+    // The old query `MATCH (sf:SourceFile)-[*]->(n)` caused OOM with large graphs
     GET_EXISTING_NODES_FOR_EDGE_DETECTION: `
-    MATCH (sf:SourceFile)-[*]->(n)
-    WHERE NOT sf.filePath IN $excludeFilePaths AND sf.projectId = $projectId
-    RETURN n.id AS id,
+    MATCH (n)
+    WHERE n.projectId = $projectId
+      AND n.filePath IS NOT NULL
+      AND NOT n.filePath IN $excludeFilePaths
+    RETURN DISTINCT n.id AS id,
            n.name AS name,
            n.coreType AS coreType,
            n.semanticType AS semanticType,
            labels(n) AS labels,
-           sf.filePath AS filePath
+           n.filePath AS filePath
   `,
     EXPLORE_ALL_CONNECTIONS: (maxDepth = MAX_TRAVERSAL_DEPTH, direction = 'BOTH', relationshipTypes) => {
         const safeMaxDepth = Math.min(Math.max(maxDepth, 1), MAX_TRAVERSAL_DEPTH);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-graph-context",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "MCP server that builds code graphs to provide rich context to LLMs",
   "type": "module",
   "homepage": "https://github.com/drewdrewH/code-graph-context#readme",