code-graph-context 2.7.0 → 2.8.0

package/README.md

@@ -345,7 +345,6 @@ Explicit task management with dependencies:
 
 | Tool | Purpose |
 |------|---------|
-| `swarm_orchestrate` | Decompose a task and spawn worker agents |
 | `swarm_post_task` | Add a task to the queue |
 | `swarm_get_tasks` | Query tasks with filters |
 | `swarm_claim_task` | Claim/start/release a task |
@@ -357,28 +356,20 @@ Explicit task management with dependencies:
 ### Example: Parallel Refactoring
 
 ```typescript
-// Orchestrator decomposes and creates tasks
-swarm_orchestrate({
+// Orchestrator decomposes the task and creates individual work items
+swarm_post_task({
   projectId: "backend",
-  task: "Rename getUserById to findUserById across the codebase",
-  maxAgents: 3
+  swarmId: "swarm_rename_user",
+  title: "Update UserService.findUserById",
+  description: "Rename getUserById to findUserById in UserService",
+  type: "refactor",
+  createdBy: "orchestrator"
 })
 
-// Returns a plan:
-{
-  swarmId: "swarm_abc123",
-  plan: {
-    totalTasks: 12,
-    parallelizable: 8,
-    sequential: 4,  // These have dependencies
-    tasks: [
-      { id: "task_1", title: "Update UserService.findUserById", status: "available" },
-      { id: "task_2", title: "Update UserController references", status: "blocked", depends: ["task_1"] },
-      ...
-    ]
-  },
-  workerInstructions: "..."  // Copy-paste to spawn workers
-}
+// Workers claim and execute tasks
+swarm_claim_task({ projectId: "backend", swarmId: "swarm_rename_user", agentId: "worker_1" })
+// ... do work ...
+swarm_complete_task({ taskId: "task_1", agentId: "worker_1", action: "complete", summary: "Renamed method" })
 ```
 
 ### Install the Swarm Skill
@@ -428,7 +419,6 @@ See [`skills/swarm/SKILL.md`](skills/swarm/SKILL.md) for the full documentation.
 | `stop_watch_project` | Stop file watching |
 | `list_watchers` | List active file watchers |
 | **Swarm** | |
-| `swarm_orchestrate` | Plan and spawn parallel agents |
 | `swarm_post_task` | Add task to the queue |
 | `swarm_get_tasks` | Query tasks |
 | `swarm_claim_task` | Claim/start/release tasks |
@@ -458,7 +448,7 @@ detect_dead_code → detect_duplicate_code → prioritize cleanup
 
 **Pattern 4: Multi-Agent Work**
 ```
-swarm_orchestrate → spawn workers → swarm_get_tasks(includeStats) → swarm_cleanup
+swarm_post_task → swarm_claim_task → swarm_complete_task → swarm_get_tasks(includeStats) → swarm_cleanup
 ```
 
 ### Multi-Project Support

package/dist/mcp/constants.js

@@ -38,11 +38,11 @@ export const TOOL_NAMES = {
     swarmClaimTask: 'swarm_claim_task',
     swarmCompleteTask: 'swarm_complete_task',
     swarmGetTasks: 'swarm_get_tasks',
-    swarmOrchestrate: 'swarm_orchestrate',
     saveSessionBookmark: 'save_session_bookmark',
     restoreSessionBookmark: 'restore_session_bookmark',
     saveSessionNote: 'save_session_note',
     recallSessionNotes: 'recall_session_notes',
+    cleanupSession: 'cleanup_session',
 };
 // Tool Metadata
 export const TOOL_METADATA = {
@@ -258,12 +258,6 @@ Complete unblocks dependent tasks. Failed tasks can be retried if retryable=true
         description: `Query tasks with filters. Use taskId for single task, or filter by swarmId, statuses, types, claimedBy, createdBy, minPriority.
 
 Sort by: priority (default), created, updated. Add includeStats:true for aggregate counts.`,
-    },
-    [TOOL_NAMES.swarmOrchestrate]: {
-        title: 'Swarm Orchestrate',
-        description: `Coordinate multiple agents for complex multi-file tasks. Analyzes codebase, decomposes into atomic tasks, spawns workers, monitors progress.
-
-Use dryRun:true to preview plan. maxAgents controls parallelism (default: 3). Failed tasks auto-retry via pheromone decay.`,
     },
     [TOOL_NAMES.saveSessionBookmark]: {
         title: 'Save Session Bookmark',
@@ -334,6 +328,21 @@ Parameters:
 
 Returns notes with topic, content, category, severity, relevance score (vector mode), and linked aboutNodes.`,
     },
+    [TOOL_NAMES.cleanupSession]: {
+        title: 'Cleanup Session',
+        description: `Clean up expired session notes and old session bookmarks.
+
+Removes:
+- Expired SessionNote nodes (past expiresAt) and their edges
+- Old SessionBookmark nodes, keeping only the most recent N per session (default: 3)
+
+Parameters:
+- projectId (required): Project ID, name, or path
+- keepBookmarks (default: 3): Number of most recent bookmarks to keep per session
+- dryRun (default: false): Preview what would be deleted without deleting
+
+Returns counts of deleted notes, bookmarks, and edges.`,
+    },
 };
 // Default Values
 export const DEFAULTS = {

package/dist/mcp/handlers/graph-generator.handler.js

@@ -74,6 +74,9 @@ export class GraphGeneratorHandler {
         await this.neo4jService.run(QUERIES.CREATE_PROJECT_ID_INDEX_EMBEDDED);
         await this.neo4jService.run(QUERIES.CREATE_PROJECT_ID_INDEX_SOURCEFILE);
         await this.neo4jService.run(QUERIES.CREATE_NORMALIZED_HASH_INDEX);
+        await this.neo4jService.run(QUERIES.CREATE_SESSION_BOOKMARK_INDEX);
+        await this.neo4jService.run(QUERIES.CREATE_SESSION_NOTE_INDEX);
+        await this.neo4jService.run(QUERIES.CREATE_SESSION_NOTE_CATEGORY_INDEX);
         await debugLog('Project indexes created');
     }
     async importNodes(nodes, batchSize) {

package/dist/mcp/tools/index.js

@@ -13,6 +13,7 @@ import { createNaturalLanguageToCypherTool } from './natural-language-to-cypher.
 import { createParseTypescriptProjectTool } from './parse-typescript-project.tool.js';
 import { createSearchCodebaseTool } from './search-codebase.tool.js';
 import { createRestoreSessionBookmarkTool, createSaveSessionBookmarkTool } from './session-bookmark.tool.js';
+import { createCleanupSessionTool } from './session-cleanup.tool.js';
 import { createRecallSessionNotesTool, createSaveSessionNoteTool } from './session-note.tool.js';
 import { createStartWatchProjectTool } from './start-watch-project.tool.js';
 import { createStopWatchProjectTool } from './stop-watch-project.tool.js';
@@ -20,7 +21,6 @@ import { createSwarmClaimTaskTool } from './swarm-claim-task.tool.js';
 import { createSwarmCleanupTool } from './swarm-cleanup.tool.js';
 import { createSwarmCompleteTaskTool } from './swarm-complete-task.tool.js';
 import { createSwarmGetTasksTool } from './swarm-get-tasks.tool.js';
-import { createSwarmOrchestrateTool } from './swarm-orchestrate.tool.js';
 import { createSwarmPheromoneTool } from './swarm-pheromone.tool.js';
 import { createSwarmPostTaskTool } from './swarm-post-task.tool.js';
 import { createSwarmSenseTool } from './swarm-sense.tool.js';
@@ -73,12 +73,12 @@ export const registerAllTools = (server) => {
     createSwarmClaimTaskTool(server);
     createSwarmCompleteTaskTool(server);
     createSwarmGetTasksTool(server);
-    // Register swarm orchestration tool (meta-tool for coordinating multi-agent work)
-    createSwarmOrchestrateTool(server);
     // Register session bookmark tools (cross-session context continuity)
     createSaveSessionBookmarkTool(server);
     createRestoreSessionBookmarkTool(server);
     // Register session note tools (durable observations and decisions)
     createSaveSessionNoteTool(server);
     createRecallSessionNotesTool(server);
+    // Register session cleanup tool
+    createCleanupSessionTool(server);
 };

package/dist/mcp/tools/session-bookmark.tool.js

@@ -96,11 +96,24 @@ const GET_SESSION_NOTES_QUERY = `
   MATCH (n:SessionNote)
   WHERE n.projectId = $projectId
     AND n.sessionId = $sessionId
+    AND (n.expiresAt IS NULL OR n.expiresAt > timestamp())
+
+  OPTIONAL MATCH (n)-[:ABOUT]->(codeNode)
+  WHERE NOT codeNode:SessionNote
+    AND NOT codeNode:SessionBookmark
+    AND NOT codeNode:Pheromone
+    AND NOT codeNode:SwarmTask
+
   RETURN n.id AS id,
-         n.sessionId AS sessionId,
-         n.agentId AS agentId,
+         n.topic AS topic,
          n.content AS content,
-         n.createdAt AS createdAt
+         n.category AS category,
+         n.severity AS severity,
+         n.agentId AS agentId,
+         n.sessionId AS sessionId,
+         n.createdAt AS createdAt,
+         n.expiresAt AS expiresAt,
+         collect(DISTINCT {id: codeNode.id, name: codeNode.name, filePath: codeNode.filePath}) AS aboutNodes
   ORDER BY n.createdAt ASC
   LIMIT 50
 `;
@@ -266,13 +279,21 @@ export const createRestoreSessionBookmarkTool = (server) => {
                 }
                 return node;
             });
-            const notes = noteRows.map((n) => ({
-                id: n.id,
-                sessionId: n.sessionId,
-                agentId: n.agentId,
-                content: n.content,
-                createdAt: typeof n.createdAt === 'object' && n.createdAt?.toNumber ? n.createdAt.toNumber() : n.createdAt,
-            }));
+            const notes = noteRows.map((n) => {
+                const aboutNodes = (n.aboutNodes ?? []).filter((node) => node?.id != null);
+                return {
+                    id: n.id,
+                    topic: n.topic,
+                    content: n.content,
+                    category: n.category,
+                    severity: n.severity,
+                    agentId: n.agentId,
+                    sessionId: n.sessionId,
+                    createdAt: typeof n.createdAt === 'object' && n.createdAt?.toNumber ? n.createdAt.toNumber() : n.createdAt,
+                    expiresAt: typeof n.expiresAt === 'object' && n.expiresAt?.toNumber ? n.expiresAt.toNumber() : n.expiresAt,
+                    aboutNodes,
+                };
+            });
             // Identify working set nodes not found in the graph (stale IDs after re-parse)
             const foundIds = new Set(workingSetRows.map((r) => r.id));
             const storedIds = Array.isArray(bm.workingSetNodeIds) ? bm.workingSetNodeIds : [];

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

@@ -0,0 +1,139 @@
+/**
+ * Session Cleanup Tool
+ * Remove expired notes and prune old bookmarks
+ */
+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';
+/**
+ * Count expired notes (for dry run)
+ */
+const COUNT_EXPIRED_NOTES_QUERY = `
+  MATCH (n:SessionNote)
+  WHERE n.projectId = $projectId
+    AND n.expiresAt IS NOT NULL
+    AND n.expiresAt <= timestamp()
+  RETURN count(n) AS count
+`;
+/**
+ * Delete expired notes and their edges
+ */
+const DELETE_EXPIRED_NOTES_QUERY = `
+  MATCH (n:SessionNote)
+  WHERE n.projectId = $projectId
+    AND n.expiresAt IS NOT NULL
+    AND n.expiresAt <= timestamp()
+  WITH collect(n) AS toDelete
+  WITH size(toDelete) AS cnt, toDelete
+  FOREACH (n IN toDelete | DETACH DELETE n)
+  RETURN cnt AS deleted
+`;
+/**
+ * Find old bookmarks to prune (keeping N most recent per session)
+ */
+const COUNT_OLD_BOOKMARKS_QUERY = `
+  MATCH (b:SessionBookmark)
+  WHERE b.projectId = $projectId
+  WITH b.sessionId AS sessionId, b
+  ORDER BY b.createdAt DESC
+  WITH sessionId, collect(b) AS bookmarks
+  WHERE size(bookmarks) > $keepBookmarks
+  UNWIND bookmarks[$keepBookmarks..] AS old
+  RETURN count(old) AS count
+`;
+/**
+ * Delete old bookmarks (keeping N most recent per session)
+ */
+const DELETE_OLD_BOOKMARKS_QUERY = `
+  MATCH (b:SessionBookmark)
+  WHERE b.projectId = $projectId
+  WITH b.sessionId AS sessionId, b
+  ORDER BY b.createdAt DESC
+  WITH sessionId, collect(b) AS bookmarks
+  WHERE size(bookmarks) > $keepBookmarks
+  WITH reduce(all = [], bs IN collect(bookmarks[$keepBookmarks..]) | all + bs) AS toDelete
+  WITH size(toDelete) AS cnt, toDelete
+  FOREACH (b IN toDelete | DETACH DELETE b)
+  RETURN cnt AS deleted
+`;
+export const createCleanupSessionTool = (server) => {
+    server.registerTool(TOOL_NAMES.cleanupSession, {
+        title: TOOL_METADATA[TOOL_NAMES.cleanupSession].title,
+        description: TOOL_METADATA[TOOL_NAMES.cleanupSession].description,
+        inputSchema: {
+            projectId: z.string().describe('Project ID, name, or path (e.g., "backend" or "proj_a1b2c3d4e5f6")'),
+            keepBookmarks: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .default(3)
+                .describe('Number of most recent bookmarks to keep per session (default: 3)'),
+            dryRun: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Preview what would be deleted without deleting (default: false)'),
+        },
+    }, async ({ projectId, keepBookmarks = 3, dryRun = false }) => {
+        const neo4jService = new Neo4jService();
+        const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
+        if (!projectResult.success) {
+            await neo4jService.close();
+            return projectResult.error;
+        }
+        const resolvedProjectId = projectResult.projectId;
+        try {
+            const params = { projectId: resolvedProjectId, keepBookmarks };
+            if (dryRun) {
+                const [noteCount, bookmarkCount] = await Promise.all([
+                    neo4jService.run(COUNT_EXPIRED_NOTES_QUERY, params),
+                    neo4jService.run(COUNT_OLD_BOOKMARKS_QUERY, params),
+                ]);
+                const expiredNotes = noteCount[0]?.count ?? 0;
+                const oldBookmarks = bookmarkCount[0]?.count ?? 0;
+                const toNumber = (v) => (typeof v === 'object' && v?.toNumber ? v.toNumber() : v);
+                return createSuccessResponse(JSON.stringify({
+                    dryRun: true,
+                    projectId: resolvedProjectId,
+                    wouldDelete: {
+                        expiredNotes: toNumber(expiredNotes),
+                        oldBookmarks: toNumber(oldBookmarks),
+                    },
+                    keepBookmarks,
+                    message: toNumber(expiredNotes) === 0 && toNumber(oldBookmarks) === 0
+                        ? 'Nothing to clean up.'
+                        : `Would delete ${toNumber(expiredNotes)} expired notes and ${toNumber(oldBookmarks)} old bookmarks.`,
+                }));
+            }
+            const [noteResult, bookmarkResult] = await Promise.all([
+                neo4jService.run(DELETE_EXPIRED_NOTES_QUERY, params),
+                neo4jService.run(DELETE_OLD_BOOKMARKS_QUERY, params),
+            ]);
+            const toNumber = (v) => (typeof v === 'object' && v?.toNumber ? v.toNumber() : v);
+            const deletedNotes = toNumber(noteResult[0]?.deleted ?? 0);
+            const deletedBookmarks = toNumber(bookmarkResult[0]?.deleted ?? 0);
+            return createSuccessResponse(JSON.stringify({
+                success: true,
+                projectId: resolvedProjectId,
+                deleted: {
+                    expiredNotes: deletedNotes,
+                    oldBookmarks: deletedBookmarks,
+                },
+                keepBookmarks,
+                message: deletedNotes === 0 && deletedBookmarks === 0
+                    ? 'Nothing to clean up.'
+                    : `Deleted ${deletedNotes} expired notes and ${deletedBookmarks} old bookmarks.`,
+            }));
+        }
+        catch (error) {
+            await debugLog('Cleanup session error', { error: String(error) });
+            return createErrorResponse(error instanceof Error ? error : String(error));
+        }
+        finally {
+            await neo4jService.close();
+        }
+    });
+};

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

@@ -152,6 +152,10 @@ export const QUERIES = {
     \`vector.similarity_function\`: 'cosine'
   }}
 `,
+    // Indexes for efficient SessionBookmark and SessionNote lookups
+    CREATE_SESSION_BOOKMARK_INDEX: 'CREATE INDEX session_bookmark_idx IF NOT EXISTS FOR (n:SessionBookmark) ON (n.projectId, n.sessionId)',
+    CREATE_SESSION_NOTE_INDEX: 'CREATE INDEX session_note_idx IF NOT EXISTS FOR (n:SessionNote) ON (n.projectId, n.sessionId)',
+    CREATE_SESSION_NOTE_CATEGORY_INDEX: 'CREATE INDEX session_note_category_idx IF NOT EXISTS FOR (n:SessionNote) ON (n.projectId, n.category)',
     // Vector search with configurable fetch multiplier for project filtering.
     // fetchMultiplier (default: 10) controls how many extra results to fetch before filtering by projectId.
     // minSimilarity (default: 0.3) filters out low-confidence matches for nonsense queries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-graph-context",
-  "version": "2.7.0",
+  "version": "2.8.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",

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

@@ -1,471 +0,0 @@
-/**
- * Swarm Orchestrate Tool
- * Orchestrates multiple agents to tackle complex, multi-file code tasks in parallel
- *
- * This is the main entry point for swarm-based task execution. It:
- * 1. Analyzes the task using semantic search and impact analysis
- * 2. Decomposes the task into atomic, dependency-ordered SwarmTasks
- * 3. Creates tasks on the blackboard for worker agents
- * 4. Returns execution plan for agents to claim and execute
- */
-import { z } from 'zod';
-import { EmbeddingsService } from '../../core/embeddings/embeddings.service.js';
-import { Neo4jService } from '../../storage/neo4j/neo4j.service.js';
-import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
-import { TaskDecompositionHandler, } from '../handlers/task-decomposition.handler.js';
-import { createErrorResponse, createSuccessResponse, resolveProjectIdOrError, debugLog } from '../utils.js';
-import { TASK_PRIORITIES, generateSwarmId, ORCHESTRATOR_CONFIG, getHalfLife } from './swarm-constants.js';
-/**
- * Query to search for nodes matching the task description
- */
-const SEMANTIC_SEARCH_QUERY = `
-  CALL db.index.vector.queryNodes('embedded_nodes_idx', toInteger($limit), $embedding)
-  YIELD node, score
-  WHERE node.projectId = $projectId
-    AND score >= $minSimilarity
-  RETURN node.id AS id,
-         node.name AS name,
-         node.coreType AS coreType,
-         node.semanticType AS semanticType,
-         node.filePath AS filePath,
-         substring(node.sourceCode, 0, 500) AS sourceCode,
-         node.startLine AS startLine,
-         node.endLine AS endLine,
-         score
-  ORDER BY score DESC
-  LIMIT toInteger($limit)
-`;
-/**
- * Query to get impact analysis for a node
- */
-const IMPACT_QUERY = `
-  MATCH (target)
-  WHERE target.id = $nodeId AND target.projectId = $projectId
-  OPTIONAL MATCH (dependent)-[r]->(target)
-  WHERE dependent.projectId = $projectId
-    AND NOT dependent:Pheromone
-    AND NOT dependent:SwarmTask
-  WITH target, collect(DISTINCT {
-    nodeId: dependent.id,
-    filePath: dependent.filePath,
-    relType: type(r)
-  }) AS dependents
-  RETURN target.id AS nodeId,
-         size(dependents) AS dependentCount,
-         [d IN dependents | d.filePath] AS affectedFiles,
-         CASE
-           WHEN size(dependents) >= 20 THEN 'CRITICAL'
-           WHEN size(dependents) >= 10 THEN 'HIGH'
-           WHEN size(dependents) >= 5 THEN 'MEDIUM'
-           ELSE 'LOW'
-         END AS riskLevel
-`;
-/**
- * Query to create a pheromone marker on a node
- */
-const CREATE_PHEROMONE_QUERY = `
-  MATCH (target)
-  WHERE target.id = $nodeId AND target.projectId = $projectId
-  MERGE (p:Pheromone {
-    nodeId: $nodeId,
-    agentId: $agentId,
-    type: $type,
-    projectId: $projectId
-  })
-  ON CREATE SET
-    p.id = randomUUID(),
-    p.swarmId = $swarmId,
-    p.intensity = $intensity,
-    p.timestamp = timestamp(),
-    p.halfLife = $halfLife,
-    p.data = $data
-  ON MATCH SET
-    p.intensity = $intensity,
-    p.timestamp = timestamp(),
-    p.data = $data
-  MERGE (p)-[:MARKS]->(target)
-  RETURN p.nodeId AS nodeId
-`;
-/**
- * Query to get node IDs for a file path (fallback when decomposition has no nodeIds)
- * Uses ENDS WITH for flexible matching (handles absolute vs relative paths)
- */
-const GET_NODES_FOR_FILE_QUERY = `
-  MATCH (n)
-  WHERE (n.filePath = $filePath OR n.filePath ENDS WITH $filePath)
-    AND n.projectId = $projectId
-    AND n.id IS NOT NULL
-    AND NOT n:Pheromone
-    AND NOT n:SwarmTask
-  RETURN n.id AS id, n.name AS name, n.coreType AS coreType
-  ORDER BY n.startLine
-  LIMIT 20
-`;
-/**
- * Query to create a SwarmTask node
- */
-const CREATE_TASK_QUERY = `
-  CREATE (t:SwarmTask {
-    id: $taskId,
-    projectId: $projectId,
-    swarmId: $swarmId,
-    title: $title,
-    description: $description,
-    type: $type,
-    priority: $priority,
-    priorityScore: $priorityScore,
-    status: $status,
-    targetNodeIds: $targetNodeIds,
-    targetFilePaths: $targetFilePaths,
-    dependencies: $dependencies,
-    createdBy: $createdBy,
-    createdAt: timestamp(),
-    updatedAt: timestamp(),
-    metadata: $metadata
-  })
-
-  // Link to target code nodes if they exist
-  WITH t
-  OPTIONAL MATCH (target)
-  WHERE target.id IN $targetNodeIds
-    AND target.projectId = $projectId
-    AND NOT target:SwarmTask
-    AND NOT target:Pheromone
-  WITH t, collect(DISTINCT target) as targets
-  FOREACH (target IN targets | MERGE (t)-[:TARGETS]->(target))
-
-  // Link to dependency tasks if they exist
-  WITH t
-  OPTIONAL MATCH (dep:SwarmTask)
-  WHERE dep.id IN $dependencies
-    AND dep.projectId = $projectId
-  WITH t, collect(DISTINCT dep) as deps
-  FOREACH (dep IN deps | MERGE (t)-[:DEPENDS_ON]->(dep))
-
-  RETURN t.id AS id
-`;
-export const createSwarmOrchestrateTool = (server) => {
-    const embeddingsService = new EmbeddingsService();
-    const taskDecomposer = new TaskDecompositionHandler();
-    server.registerTool(TOOL_NAMES.swarmOrchestrate, {
-        title: TOOL_METADATA[TOOL_NAMES.swarmOrchestrate].title,
-        description: TOOL_METADATA[TOOL_NAMES.swarmOrchestrate].description,
-        inputSchema: {
-            projectId: z.string().describe('Project ID, name, or path'),
-            task: z.string().min(10).describe('Natural language description of the task to execute'),
-            maxAgents: z
-                .number()
-                .int()
-                .min(1)
-                .max(ORCHESTRATOR_CONFIG.maxAgentsLimit)
-                .optional()
-                .default(ORCHESTRATOR_CONFIG.defaultMaxAgents)
-                .describe(`Maximum concurrent worker agents (default: ${ORCHESTRATOR_CONFIG.defaultMaxAgents})`),
-            dryRun: z
-                .boolean()
-                .optional()
-                .default(false)
-                .describe('If true, only plan without creating tasks (default: false)'),
-            priority: z
-                .enum(Object.keys(TASK_PRIORITIES))
-                .optional()
-                .default('normal')
-                .describe('Overall priority level for tasks'),
-            minSimilarity: z
-                .number()
-                .min(0.5)
-                .max(1.0)
-                .optional()
-                .default(0.65)
-                .describe('Minimum similarity score for semantic search (default: 0.65)'),
-            maxNodes: z
-                .number()
-                .int()
-                .min(1)
-                .max(100)
-                .optional()
-                .default(50)
-                .describe('Maximum nodes to consider from search (default: 50)'),
-        },
-    }, async ({ projectId, task, maxAgents = ORCHESTRATOR_CONFIG.defaultMaxAgents, dryRun = false, priority = 'normal', minSimilarity = 0.65, maxNodes = 50, }) => {
-        const neo4jService = new Neo4jService();
-        const swarmId = generateSwarmId();
-        try {
-            // Step 1: Resolve project ID
-            const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
-            if (!projectResult.success) {
-                await neo4jService.close();
-                return projectResult.error;
-            }
-            const resolvedProjectId = projectResult.projectId;
-            // Step 2: Semantic search to find affected nodes
-            let embedding;
-            try {
-                embedding = await embeddingsService.embedText(task);
-            }
-            catch (error) {
-                return createErrorResponse(`Failed to generate embedding for task description: ${error}`);
-            }
-            const searchResults = await neo4jService.run(SEMANTIC_SEARCH_QUERY, {
-                projectId: resolvedProjectId,
-                embedding,
-                minSimilarity,
-                limit: Math.floor(maxNodes),
-            });
-            if (searchResults.length === 0) {
-                return createErrorResponse(`No code found matching task: "${task}". Try rephrasing or use search_codebase to explore the codebase first.`);
-            }
-            const affectedNodes = searchResults.map((r) => ({
-                id: r.id,
-                name: r.name,
-                coreType: r.coreType,
-                semanticType: r.semanticType,
-                filePath: r.filePath,
-                sourceCode: r.sourceCode,
-                startLine: typeof r.startLine === 'object' ? r.startLine.toNumber() : r.startLine,
-                endLine: typeof r.endLine === 'object' ? r.endLine.toNumber() : r.endLine,
-            }));
-            // Step 3: Run impact analysis on each node
-            const impactMap = new Map();
-            for (const node of affectedNodes) {
-                const impactResult = await neo4jService.run(IMPACT_QUERY, {
-                    nodeId: node.id,
-                    projectId: resolvedProjectId,
-                });
-                if (impactResult.length > 0) {
-                    const impact = impactResult[0];
-                    impactMap.set(node.id, {
-                        nodeId: node.id,
-                        riskLevel: impact.riskLevel,
-                        directDependents: {
-                            count: typeof impact.dependentCount === 'object'
-                                ? impact.dependentCount.toNumber()
-                                : impact.dependentCount,
-                            byType: {},
-                        },
-                        transitiveDependents: { count: 0 },
-                        affectedFiles: impact.affectedFiles ?? [],
-                    });
-                }
-            }
-            // Step 4: Decompose task into atomic tasks
-            const decomposition = await taskDecomposer.decomposeTask(task, affectedNodes, impactMap, priority);
-            if (decomposition.tasks.length === 0) {
-                return createErrorResponse('Task decomposition produced no actionable tasks');
-            }
-            // Step 5: Create SwarmTasks on the blackboard (unless dry run)
-            if (!dryRun) {
-                for (const atomicTask of decomposition.tasks) {
-                    // Determine initial status based on dependencies
-                    const hasUnmetDeps = atomicTask.dependencies.length > 0;
-                    const initialStatus = hasUnmetDeps ? 'blocked' : 'available';
-                    // Filter out null/undefined nodeIds, then fallback to file query if empty
-                    let targetNodeIds = (atomicTask.nodeIds || []).filter((id) => typeof id === 'string' && id.length > 0);
-                    if (targetNodeIds.length === 0 && atomicTask.filePath) {
-                        const fileNodes = await neo4jService.run(GET_NODES_FOR_FILE_QUERY, {
-                            filePath: atomicTask.filePath,
-                            projectId: resolvedProjectId,
-                        });
-                        if (fileNodes.length > 0) {
-                            targetNodeIds = fileNodes.map((n) => n.id).filter(Boolean);
-                        }
-                    }
-                    await neo4jService.run(CREATE_TASK_QUERY, {
-                        taskId: atomicTask.id,
-                        projectId: resolvedProjectId,
-                        swarmId,
-                        title: atomicTask.title,
-                        description: atomicTask.description,
-                        type: atomicTask.type,
-                        priority: atomicTask.priority,
-                        priorityScore: atomicTask.priorityScore,
-                        status: initialStatus,
-                        targetNodeIds,
-                        targetFilePaths: [atomicTask.filePath],
-                        dependencies: atomicTask.dependencies,
-                        createdBy: 'orchestrator',
-                        metadata: JSON.stringify(atomicTask.metadata ?? {}),
-                    });
-                    // Update the atomicTask.nodeIds for pheromone creation below
-                    atomicTask.nodeIds = targetNodeIds;
-                }
-                // Step 5b: Leave "proposal" pheromones on all target nodes
-                // This signals to other agents that work is planned for these nodes
-                const uniqueNodeIds = new Set();
-                for (const atomicTask of decomposition.tasks) {
-                    for (const nodeId of atomicTask.nodeIds) {
-                        uniqueNodeIds.add(nodeId);
-                    }
-                }
-                for (const nodeId of uniqueNodeIds) {
-                    await neo4jService.run(CREATE_PHEROMONE_QUERY, {
-                        nodeId,
-                        projectId: resolvedProjectId,
-                        agentId: 'orchestrator',
-                        swarmId,
-                        type: 'proposal',
-                        intensity: 1.0,
-                        halfLife: getHalfLife('proposal'),
-                        data: JSON.stringify({ task, swarmId }),
-                    });
-                }
-            }
-            // Step 6: Generate worker instructions
-            const workerInstructions = generateWorkerInstructions(swarmId, resolvedProjectId, maxAgents, decomposition.tasks.length);
-            // Step 7: Build result
-            const result = {
-                swarmId,
-                status: dryRun ? 'planning' : 'ready',
-                plan: {
-                    totalTasks: decomposition.tasks.length,
-                    parallelizable: decomposition.summary.parallelizable,
-                    sequential: decomposition.summary.sequential,
-                    estimatedComplexity: decomposition.summary.estimatedComplexity,
-                    tasks: decomposition.tasks.map((t) => ({
-                        id: t.id,
-                        title: t.title,
-                        type: t.type,
-                        priority: t.priority,
-                        status: t.dependencies.length > 0 ? 'blocked' : 'available',
-                        dependencyCount: t.dependencies.length,
-                        targetFiles: [t.filePath],
-                    })),
-                    dependencyGraph: buildDependencyGraph(decomposition),
-                },
-                workerInstructions,
-                message: dryRun
-                    ? `Dry run complete. ${decomposition.tasks.length} tasks planned but not created.`
-                    : `Swarm ready! ${decomposition.tasks.length} tasks created. ${decomposition.summary.parallelizable} can run in parallel.`,
-            };
-            return createSuccessResponse(JSON.stringify(result, null, 2));
-        }
-        catch (error) {
-            await debugLog('Swarm orchestration error', { swarmId, error: String(error) });
-            return createErrorResponse(error instanceof Error ? error : String(error));
-        }
-        finally {
-            await neo4jService.close();
-        }
-    });
-};
-/**
- * Generate instructions for spawning worker agents
- */
-function generateWorkerInstructions(swarmId, projectId, maxAgents, taskCount) {
-    const recommendedAgents = Math.min(maxAgents, Math.ceil(taskCount / 2), taskCount);
-    // Generate unique agent IDs for each worker
-    const agentIds = Array.from({ length: recommendedAgents }, (_, i) => `${swarmId}_worker_${i + 1}`);
-    const workerPrompt = `You are a swarm worker agent with access to a code graph.
-- Agent ID: {AGENT_ID}
-- Swarm ID: ${swarmId}
-- Project: ${projectId}
-
-## RULES
-1. Use graph tools (traverse_from_node, search_codebase) for context
-2. Tasks provide: targets (best), targetNodeIds (good), targetFilePaths (fallback)
-3. Exit when swarm_claim_task returns "no_tasks"
-
-## WORKFLOW
-
-### Step 1: Claim a task
-swarm_claim_task({
-  projectId: "${projectId}",
-  swarmId: "${swarmId}",
-  agentId: "{AGENT_ID}"
-})
-// Returns: { task: { id, targets: [{nodeId, name, filePath}], targetFilePaths, ... } }
-// If "no_tasks" → exit
-
-### Step 2: Understand context via graph (USE NODE IDs!)
-// Priority: task.targets[0].nodeId > task.targetNodeIds[0] > search
-traverse_from_node({
-  projectId: "${projectId}",
-  nodeId: "<nodeId_FROM_task.targets>",
-  maxDepth: 2
-})
-
-// Fallback if no nodeIds:
-search_codebase({ projectId: "${projectId}", query: "<TASK_DESCRIPTION>" })
-
-### Step 3: Mark nodes you're analyzing/modifying
-swarm_pheromone({
-  projectId: "${projectId}",
-  nodeId: "<nodeId>",
-  type: "modifying",
-  agentId: "{AGENT_ID}",
-  swarmId: "${swarmId}"
-})
-
-### Step 4: Do the work
-- Read tool for full source
-- Edit tool for changes
-
-### Step 5: Complete the task
-swarm_complete_task({
-  projectId: "${projectId}",
-  taskId: "<TASK_ID>",
-  agentId: "{AGENT_ID}",
-  action: "complete",
-  summary: "<WHAT_YOU_DID>",
-  filesChanged: ["<FILES>"]
-})
-
-### Step 6: Loop to Step 1
-
-## IF STUCK
-swarm_complete_task({ ..., action: "fail", reason: "<WHY>", retryable: true })
-Then claim another task.`;
-    const taskCalls = agentIds
-        .map((agentId) => {
-        const prompt = workerPrompt.replace(/\{AGENT_ID\}/g, agentId);
-        return `Task({
-  subagent_type: "general-purpose",
-  run_in_background: false,
-  prompt: \`${prompt}\`
-})`;
-    })
-        .join('\n\n');
-    return `
-## Worker Agent Instructions
-
-Spawn ${recommendedAgents} worker agent(s) IN PARALLEL (all Task calls in ONE message):
-
-\`\`\`javascript
-${taskCalls}
-\`\`\`
-
-**CRITICAL:** Include ALL ${recommendedAgents} Task calls in a single message to run them in parallel.
-
-## Monitoring Progress
-
-Check swarm progress:
-\`\`\`javascript
-swarm_get_tasks({
-  projectId: "${projectId}",
-  swarmId: "${swarmId}",
-  includeStats: true
-})
-\`\`\`
-
-## Cleanup (after all workers complete)
-
-\`\`\`javascript
-swarm_cleanup({
-  projectId: "${projectId}",
-  swarmId: "${swarmId}"
-})
-\`\`\`
-`;
-}
-/**
- * Build dependency graph edges for visualization
- */
-function buildDependencyGraph(decomposition) {
-    const edges = [];
-    for (const task of decomposition.tasks) {
-        for (const depId of task.dependencies) {
-            edges.push({ from: depId, to: task.id });
-        }
-    }
-    return edges;
-}