code-graph-context 2.14.1 → 3.0.1

package/README.md

@@ -674,7 +674,7 @@ code-graph-context stop             # Stop Neo4j container
 ## Contributing
 
 ```bash
-git clone https://github.com/drewdrewH/code-graph-context.git
+git clone https://github.com/andrew-hernandez-paragon/code-graph-context.git
 cd code-graph-context
 npm install
 npm run build
@@ -693,6 +693,6 @@ MIT - see [LICENSE](LICENSE)
 
 ## Links
 
-- [Issues](https://github.com/drewdrewH/code-graph-context/issues)
+- [Issues](https://github.com/andrew-hernandez-paragon/code-graph-context/issues)
 - [MCP Documentation](https://modelcontextprotocol.io/docs)
 - [Neo4j](https://neo4j.com/)

package/dist/core/embeddings/natural-language-to-cypher.service.js

@@ -77,7 +77,7 @@ CONTAINS (file→declaration), HAS_MEMBER (class→method/property), HAS_PARAMET
         try {
             const content = fs.readFileSync(this.schemaPath, 'utf-8');
             const schema = JSON.parse(content);
-            if (!schema || !schema.nodeTypes) {
+            if (!schema?.nodeTypes) {
                 return 'No schema available.';
             }
             // Format node types with properties
@@ -93,9 +93,7 @@ CONTAINS (file→declaration), HAS_MEMBER (class→method/property), HAS_PARAMET
                 .join('\n') ?? 'none';
             // Format semantic types
             const semanticTypeList = schema.semanticTypes?.map((s) => s.type) ?? [];
-            const semTypeLines = schema.semanticTypes
-                ?.map((s) => `  ${s.type} (on ${s.label}, ${s.count} nodes)`)
-                .join('\n') ?? 'none';
+            const semTypeLines = schema.semanticTypes?.map((s) => `  ${s.type} (on ${s.label}, ${s.count} nodes)`).join('\n') ?? 'none';
             // Format common patterns
             const patternLines = schema.commonPatterns
                 ?.map((p) => `  (${p.from})-[:${p.relationship}]->(${p.to}) × ${p.count}`)

package/dist/mcp/constants.js

@@ -36,6 +36,8 @@ export const TOOL_NAMES = {
     swarmCleanup: 'swarm_cleanup',
     swarmPostTask: 'swarm_post_task',
     swarmClaimTask: 'swarm_claim_task',
+    swarmReleaseTask: 'swarm_release_task',
+    swarmAdvanceTask: 'swarm_advance_task',
     swarmCompleteTask: 'swarm_complete_task',
     swarmGetTasks: 'swarm_get_tasks',
     saveSessionBookmark: 'save_session_bookmark',
@@ -44,327 +46,153 @@ export const TOOL_NAMES = {
     recallSessionNotes: 'recall_session_notes',
     cleanupSession: 'cleanup_session',
     swarmMessage: 'swarm_message',
+    sessionSave: 'session_save',
+    sessionRecall: 'session_recall',
 };
 // Tool Metadata
 export const TOOL_METADATA = {
     [TOOL_NAMES.hello]: {
         title: 'Hello Tool',
-        description: 'Test tool that says hello',
+        description: 'Diagnostic tool. Use only to verify the MCP server is running.',
     },
     [TOOL_NAMES.searchCodebase]: {
         title: 'Search Codebase',
-        description: `Semantic search for code, functions, classes, implementations. Returns normalized JSON with source code.
+        description: `Primary tool for finding code. Use this first for any code exploration query. Combines semantic vector search with dependency graph traversal from the best match.
 
-Use list_projects first to get project name/ID.
-
-Parameters:
-- query: Natural language description of what you're looking for
-- maxDepth (default: 3): Relationship hops to traverse
-- includeCode (default: true): Set false for structure only
-- snippetLength (default: 700): Code snippet length
-- maxNodesPerChain (default: 5): Chains per depth level
-
-If output too large: reduce maxDepth, set includeCode=false, or reduce snippetLength.`,
+Returns normalized JSON with nodes map and relationship chains. If output too large: reduce maxDepth, set includeCode=false, or reduce snippetLength.`,
     },
     [TOOL_NAMES.naturalLanguageToCypher]: {
         title: 'Natural Language to Cypher',
-        description: `Convert natural language to Cypher for complex queries search_codebase can't handle.
-
-Use list_projects first to get project name.
+        description: `Advanced query tool. Use only when search_codebase cannot answer the question — aggregate queries ('how many services exist'), complex relationship patterns, or bulk property filtering. Requires OPENAI_API_KEY.
 
 **Node types:** SourceFile, Class, Function, Method, Interface, Property, Parameter, Import, Export, Enum, TypeAlias
-
 **Key relationships:** CONTAINS, HAS_MEMBER, HAS_PARAMETER, IMPORTS, EXTENDS, IMPLEMENTS, CALLS, TYPED_AS
-
-**NestJS:** Use semanticType property (e.g., semanticType='NestController'), not decorators. Relationships: INJECTS, EXPOSES, MODULE_IMPORTS/PROVIDES/EXPORTS
-
-**Tips:** Use concrete properties (filePath, name) not abstract concepts. Import nodes store file paths, not module names.`,
+**NestJS:** Use semanticType property (e.g., semanticType='NestController'). Relationships: INJECTS, EXPOSES, MODULE_IMPORTS/PROVIDES/EXPORTS
+**Tips:** Use concrete properties (filePath, name) not abstract concepts.`,
     },
     [TOOL_NAMES.traverseFromNode]: {
         title: 'Traverse from Node',
-        description: `Explore connections from a node ID (from search_codebase results).
+        description: `Follow-up exploration tool. Use after search_codebase when you have a specific node ID and want to explore its relationships in more depth or different directions.
 
-Parameters:
-- nodeId (required): Starting node ID
-- maxDepth (default: 3): Relationship hops (1-10)
-- includeCode (default: true): Set false for structure only
-- summaryOnly: true for file paths and stats only
-- maxNodesPerChain (default: 5): Chains per depth level
-- maxTotalNodes: Cap unique nodes returned`,
+Accepts nodeId or filePath as starting point. Set summaryOnly=true for file paths and stats only.`,
     },
     [TOOL_NAMES.parseTypescriptProject]: {
         title: 'Parse TypeScript Project',
-        description: `Parse a TypeScript/NestJS project and build a code graph in Neo4j.
-
-**IMPORTANT: Always use async mode for parsing:**
-- Set async: true to avoid timeouts on large codebases
-- Use check_parse_status to monitor progress
+        description: `Setup tool. Parse a TypeScript/NestJS project and build a code graph in Neo4j. Run once per project, then use search_codebase to query.
 
-**Workflow:**
-1. Call with async: true and projectPath
-2. Note the returned jobId
-3. Poll check_parse_status({ jobId }) until completed
-4. Use list_projects to confirm the project was added
-
-**Parameters:**
-- projectPath (required): Absolute path to the project root
-- async (recommended: true): Run parsing in background
-- clearExisting: Set true to replace existing graph for this project
-- projectId: Optional custom ID (auto-generated from path if omitted)
-
-**Example:**
-parse_typescript_project({ projectPath: "/path/to/project", async: true })
-→ Returns jobId for polling`,
+**Always use async mode:** set async=true, then poll check_parse_status with the returned jobId. Set clearExisting=true to replace an existing graph.`,
     },
     [TOOL_NAMES.testNeo4jConnection]: {
         title: 'Test Neo4j Connection & APOC',
-        description: 'Test connection to Neo4j database and verify APOC plugin is available',
+        description: 'Diagnostic tool. Use only to verify Neo4j connectivity and APOC plugin availability.',
     },
     [TOOL_NAMES.impactAnalysis]: {
         title: 'Impact Analysis',
-        description: `Analyze the impact of modifying a code node. Shows what depends on this node and helps assess risk before making changes.
-
-**Before analyzing:**
-Use list_projects to see available projects and get the project name.
-
-Returns:
-- Risk level (LOW/MEDIUM/HIGH/CRITICAL) based on dependency count and relationship types
-- Direct dependents: nodes that directly reference the target
-- Transitive dependents: nodes affected through dependency chains
-- Affected files: list of files that would need review
-- Critical paths: high-risk dependency chains
+        description: `Risk assessment tool. Use before modifying shared code to understand what depends on a node and the blast radius of changes.
 
-Parameters:
-- nodeId: Node ID from search_codebase or traverse_from_node results
-- filePath: Alternative - analyze all exports from a file
-- maxDepth: How far to trace transitive dependencies (default: 4)
-
-Use this before refactoring to understand blast radius of changes.`,
+Returns risk level (LOW/MEDIUM/HIGH/CRITICAL), direct and transitive dependents, affected files, and critical paths. Accepts nodeId or filePath.`,
     },
     [TOOL_NAMES.checkParseStatus]: {
         title: 'Check Parse Status',
-        description: `Check the status of an async parsing job started with parse_typescript_project({ async: true }).
-
-Returns:
-- Job status (pending/running/completed/failed)
-- Progress: phase, files processed, chunks completed
-- Nodes and edges imported so far
-- Final result on completion or error message on failure
-
-Use this to poll for progress when parsing large codebases asynchronously.`,
+        description: `Setup tool. Poll the status of an async parsing job started with parse_typescript_project. Returns job status, progress, and final result.`,
     },
     [TOOL_NAMES.listProjects]: {
         title: 'List Projects',
-        description: `List all parsed projects in the database with their IDs, names, and paths.
-
-Returns:
-- projectId: The full project ID (e.g., "proj_a1b2c3d4e5f6")
-- name: Friendly project name from package.json (e.g., "backend")
-- path: Full filesystem path to the project
-- updatedAt: When the project was last parsed
-
-Use the name or path in other tools instead of the cryptic projectId.`,
+        description: `Utility tool. Lists all parsed projects with IDs, names, and paths. Most tools accept project names or paths directly, so this is rarely needed.`,
     },
     [TOOL_NAMES.startWatchProject]: {
         title: 'Start Watch Project',
-        description: `Watch project for .ts file changes and auto-update graph.
-
-Parameters: projectPath (required), tsconfigPath (required), debounceMs (default: 1000ms).
-
-Auto-excludes node_modules, dist, build, .git. Use list_watchers to see active, stop_watch_project to stop.`,
+        description: `File watcher tool. Watch a project for .ts file changes and auto-update the graph. Auto-excludes node_modules, dist, build, .git.`,
     },
     [TOOL_NAMES.stopWatchProject]: {
         title: 'Stop Watch Project',
-        description: `Stop watching a project. Requires projectId.`,
+        description: `File watcher tool. Stop watching a project for file changes.`,
     },
     [TOOL_NAMES.listWatchers]: {
         title: 'List Watchers',
-        description: `List active file watchers with status, pending changes, last update time.`,
+        description: `File watcher tool. List active file watchers with status and pending changes.`,
     },
     [TOOL_NAMES.detectDeadCode]: {
         title: 'Detect Dead Code',
-        description: `Find unused exports, uncalled methods, orphan interfaces. Use list_projects first.
+        description: `Code quality tool. Find unused exports, uncalled methods, and orphan interfaces. Returns items with confidence scores grouped by type and category.
 
-Returns risk level, dead code items with confidence (HIGH/MEDIUM/LOW), grouped by type and category.
-
-Key parameters:
-- projectId (required)
-- filterCategory: library-export, ui-component, internal-unused, all (default: all)
-- minConfidence: LOW/MEDIUM/HIGH (default: LOW)
-- summaryOnly: true for stats only
-- excludePatterns, excludeSemanticTypes: Additional exclusions
-
-Auto-excludes NestJS entry points (controllers, modules, guards, etc.). Use filterCategory=internal-unused for actionable cleanup.`,
+Auto-excludes NestJS entry points. Use filterCategory=internal-unused for actionable cleanup.`,
     },
     [TOOL_NAMES.detectDuplicateCode]: {
         title: 'Detect Duplicate Code',
-        description: `Find duplicates using structural (AST hash) and semantic (embedding) analysis. Use list_projects first.
-
-Parameters:
-- projectId (required)
-- type: structural, semantic, or all (default: all)
-- minSimilarity: 0.5-1.0 (default: 0.80). 0.90+ = almost certain duplicates
-- scope: methods, functions, classes, or all (default: all)
-- summaryOnly: true for stats only
-- includeCode: Include source snippets (default: false)`,
+        description: `Code quality tool. Find duplicates using structural (AST hash) and semantic (embedding) analysis. Returns grouped results with similarity scores.`,
     },
     [TOOL_NAMES.swarmPheromone]: {
         title: 'Swarm Pheromone',
-        description: `Mark a code node with a pheromone for coordination. Types: exploring (2min), modifying (10min), claiming (1hr), completed (24hr), warning (permanent), blocked (5min), proposal (1hr), needs_review (30min), session_context (8hr).
-
-Workflow states (exploring/claiming/modifying/completed/blocked) are mutually exclusive per agent+node. Flag types (warning/proposal/needs_review/session_context) can coexist. Use remove:true to delete. Pheromones decay automatically.`,
+        description: `Swarm coordination tool. Mark a code node with a pheromone to signal activity. Workflow states (exploring/claiming/modifying/completed/blocked) are mutually exclusive per agent+node. Flag types (warning/proposal/needs_review/session_context) can coexist. Pheromones decay automatically.`,
     },
     [TOOL_NAMES.swarmSense]: {
         title: 'Swarm Sense',
-        description: `Query active pheromones to see what other agents are doing. Filter by swarmId, types, nodeIds, agentIds. Use excludeAgentId to see only others' activity.
-
-Returns pheromones with current intensity after decay. minIntensity default: 0.3. Add includeStats:true for summary counts.`,
+        description: `Swarm coordination tool. Query active pheromones to see what other agents are doing. Filter by swarmId, types, nodeIds, agentIds. Returns pheromones with current intensity after decay.`,
     },
     [TOOL_NAMES.swarmCleanup]: {
         title: 'Swarm Cleanup',
-        description: `Bulk delete pheromones, tasks, and messages. Specify swarmId, agentId, or all:true. Warning pheromones preserved by default (override with keepTypes:[]). Messages and tasks are deleted when swarmId is provided. Use dryRun:true to preview.`,
+        description: `Swarm orchestration tool. Bulk delete pheromones, tasks, and messages for a swarm or agent. Warning pheromones preserved by default. Use dryRun=true to preview.`,
     },
     [TOOL_NAMES.swarmPostTask]: {
         title: 'Swarm Post Task',
-        description: `Post a task to the swarm queue. Required: projectId, swarmId, title, description, type, createdBy.
-
-Types: implement, refactor, fix, test, review, document, investigate, plan. Priority: critical, high, normal, low, backlog.
-
-Use dependencies array for task ordering. Tasks with incomplete deps auto-block until ready.`,
+        description: `Swarm orchestration tool. Post a task to the swarm queue. Use dependencies array for task ordering — tasks with incomplete deps auto-block until ready.`,
     },
     [TOOL_NAMES.swarmClaimTask]: {
         title: 'Swarm Claim Task',
-        description: `Claim a task from the swarm task queue.
-
-**Actions:** claim_and_start (default, recommended), claim, start, release, abandon, force_start
-
-**Flow:** claim_and_start → do work → swarm_complete_task
+        description: `Swarm orchestration tool. Claim a task from the queue. Without taskId, claims highest-priority available task. Set startImmediately=false to claim without starting.
 
-Without taskId, claims highest-priority available task. Use types/minPriority to filter.
-
-Recovery: Use abandon to release stuck tasks, force_start to recover from failed start.`,
+Flow: swarm_claim_task → do work → swarm_complete_task. Use swarm_release_task to give up work, swarm_advance_task for state transitions.`,
+    },
+    [TOOL_NAMES.swarmReleaseTask]: {
+        title: 'Swarm Release Task',
+        description: `Swarm orchestration tool. Release or abandon a claimed task. Use when an agent can no longer complete a task. Set trackAbandonment=true to record the abandonment for retry tracking.`,
+    },
+    [TOOL_NAMES.swarmAdvanceTask]: {
+        title: 'Swarm Advance Task',
+        description: `Swarm orchestration tool. Start or force-start a claimed task. Use after claiming with startImmediately=false, or set force=true to recover from a stuck claimed state.`,
     },
     [TOOL_NAMES.swarmCompleteTask]: {
         title: 'Swarm Complete Task',
-        description: `Mark a task as completed, failed, or request review.
-
-**Actions:** complete, fail, request_review, approve, reject, retry
-
-Required: summary (for complete/request_review), reason (for fail), reviewerId (for approve/reject).
-
-Complete unblocks dependent tasks. Failed tasks can be retried if retryable=true.`,
+        description: `Swarm orchestration tool. Mark a task as completed, failed, or request review. Completing unblocks dependent tasks. Failed tasks can be retried if retryable=true.`,
     },
     [TOOL_NAMES.swarmGetTasks]: {
         title: 'Swarm Get Tasks',
-        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.`,
+        description: `Swarm orchestration tool. Query tasks with filters. Use taskId for a single task, or filter by swarmId, statuses, types, claimedBy. Add includeStats=true for aggregate counts.`,
     },
     [TOOL_NAMES.saveSessionBookmark]: {
         title: 'Save Session Bookmark',
-        description: `Save current session context as a bookmark for cross-session continuity.
-
-Records your working set (code node IDs), task context, findings, and next steps so a future session can resume exactly where you left off.
-
-Parameters:
-- projectId (required): Project ID, name, or path
-- sessionId (required): Unique session/conversation ID for recovery
-- agentId (required): Your agent identifier
-- summary (required, min 10 chars): Brief description of current work state
-- workingSetNodeIds (required): Code node IDs you are focused on
-- taskContext (required): High-level task being worked on
-- findings: Key discoveries or decisions made so far
-- nextSteps: What to do next when resuming
-- metadata: Additional structured data
-
-Returns bookmarkId for use with restore_session_bookmark.`,
+        description: `Session persistence tool. Save current working set, task context, findings, and next steps as a bookmark for cross-session continuity. Use session_recall to resume.`,
     },
     [TOOL_NAMES.restoreSessionBookmark]: {
         title: 'Restore Session Bookmark',
-        description: `Restore a previously saved session bookmark to resume work.
-
-Retrieves the bookmark, fetches working set code nodes (with source), and returns any session notes. Use after conversation compaction or when resuming a task in a new session.
-
-Parameters:
-- projectId (required): Project ID, name, or path
-- sessionId: Specific session to restore (latest bookmark if omitted)
-- agentId: Filter by agent ID (any agent if omitted)
-- includeCode (default: true): Include source code for working set nodes
-- snippetLength (default: 500): Max characters per code snippet
-
-Returns: bookmark data, working set nodes, session notes, and staleNodeIds (nodes no longer in graph after re-parse).`,
+        description: `Session persistence tool. Restore a previously saved bookmark to resume work. Returns bookmark data, working set nodes with source code, session notes, and stale node IDs.`,
     },
     [TOOL_NAMES.saveSessionNote]: {
         title: 'Save Session Note',
-        description: `Save an observation, decision, insight, or risk as a durable session note linked to code nodes.
-
-Notes survive session compaction and are recalled by restore_session_bookmark or recall_session_notes.
-
-Parameters:
-- projectId (required): Project ID, name, or path
-- sessionId (required): Session/conversation identifier
-- agentId (required): Your agent identifier
-- topic (required, 3-100 chars): Short topic label
-- content (required, min 10 chars): Full observation text
-- category (required): architectural, bug, insight, decision, risk, or todo
-- severity (default: info): info, warning, or critical
-- aboutNodeIds: Code node IDs this note is about (creates [:ABOUT] links)
-- expiresInHours: Auto-expire after N hours (omit for permanent)
-
-Returns noteId, hasEmbedding (enables semantic recall), and expiresAt.`,
+        description: `Session persistence tool. Save an observation, decision, or risk as a durable note linked to code nodes. Notes survive session compaction and are searchable via session_recall.`,
     },
     [TOOL_NAMES.recallSessionNotes]: {
         title: 'Recall Session Notes',
-        description: `Search and retrieve saved session notes. Supports semantic vector search (when query provided) or filter-based search.
-
-Parameters:
-- projectId (required): Project ID, name, or path
-- query: Natural language search — triggers semantic vector search when provided
-- category: Filter by architectural, bug, insight, decision, risk, todo
-- severity: Filter by info, warning, or critical
-- sessionId: Filter by session ID
-- agentId: Filter by agent ID
-- limit (default: 10, max: 50): Maximum notes to return
-- minSimilarity (default: 0.3): Minimum similarity for vector search
-
-Returns notes with topic, content, category, severity, relevance score (vector mode), and linked aboutNodes.`,
+        description: `Session persistence tool. Search and retrieve saved session notes. Provide query for semantic vector search, or filter by category/severity/sessionId/agentId.`,
     },
     [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.`,
+        description: `Session persistence tool. Remove expired session notes and old bookmarks, keeping the most recent per session.`,
+    },
+    [TOOL_NAMES.sessionSave]: {
+        title: 'Session Save',
+        description: `Session persistence tool. Save session context — auto-detects bookmark vs note based on input. Provide workingSetNodeIds for a bookmark, topic+content for a note, or both for a bookmark with an attached note.`,
+    },
+    [TOOL_NAMES.sessionRecall]: {
+        title: 'Session Recall',
+        description: `Session persistence tool. Retrieve saved session context. Provide query for semantic note search, or sessionId to restore the latest bookmark and all notes for that session.`,
     },
     [TOOL_NAMES.swarmMessage]: {
         title: 'Swarm Message',
-        description: `Direct agent-to-agent messaging via Neo4j. Unlike pheromones (passive/decay-based), messages are explicit and delivered when agents claim tasks.
-
-**Actions:**
-- send: Post a message to a specific agent or broadcast to all agents in a swarm
-- read: Retrieve unread messages (or all messages) for an agent
-- acknowledge: Mark messages as read
-
-**Categories:** blocked, conflict, finding, request, alert, handoff
-
-**Key behavior:**
-- Messages sent to a specific agent are delivered when that agent calls swarm_claim_task
-- Broadcast messages (toAgentId omitted) are visible to all agents in the swarm
-- Messages auto-expire after 4 hours (configurable via ttlMs)
-- Use this for critical coordination signals that agents MUST see, not optional context
+        description: `Swarm coordination tool. Direct agent-to-agent messaging. Unlike pheromones (passive/decay-based), messages are explicit and delivered when agents claim tasks. Use for critical coordination signals.
 
-**Examples:**
-- Agent finds a breaking type error: send alert to all
-- Agent is blocked on a file another agent owns: send blocked to that agent
-- Agent discovers context another agent needs: send finding to that agent`,
+Actions: send (post or broadcast), read (retrieve), acknowledge (mark read). Categories: blocked, conflict, finding, request, alert, handoff.`,
     },
 };
 // Default Values

package/dist/mcp/handlers/swarm/abandon.handler.js

@@ -0,0 +1,61 @@
+import { GET_TASK_STATE_QUERY } from './queries.js';
+/**
+ * Query to abandon a task — releases it with tracking for debugging.
+ * More explicit than release: tracks abandon history (count, previous claimant).
+ */
+const ABANDON_TASK_QUERY = `
+  MATCH (t:SwarmTask {id: $taskId, projectId: $projectId})
+  WHERE t.claimedBy = $agentId
+    AND t.status IN ['claimed', 'in_progress']
+
+  // Track abandon history
+  SET t.status = 'available',
+      t.previousClaimedBy = t.claimedBy,
+      t.claimedBy = null,
+      t.claimedAt = null,
+      t.startedAt = null,
+      t.updatedAt = timestamp(),
+      t.abandonedBy = $agentId,
+      t.abandonedAt = timestamp(),
+      t.abandonReason = $reason,
+      t.abandonCount = COALESCE(t.abandonCount, 0) + 1
+
+  RETURN t.id as id,
+         t.title as title,
+         t.status as status,
+         t.abandonCount as abandonCount,
+         t.abandonReason as abandonReason
+`;
+export class SwarmAbandonHandler {
+    neo4jService;
+    constructor(neo4jService) {
+        this.neo4jService = neo4jService;
+    }
+    async abandon(projectId, taskId, agentId, reason) {
+        const result = await this.neo4jService.run(ABANDON_TASK_QUERY, {
+            taskId,
+            projectId,
+            agentId,
+            reason: reason || 'No reason provided',
+        });
+        if (result.length === 0) {
+            const stateResult = await this.neo4jService.run(GET_TASK_STATE_QUERY, {
+                taskId,
+                projectId,
+            });
+            return { error: true, data: stateResult[0] };
+        }
+        const row = result[0];
+        const abandonCount = typeof row.abandonCount === 'object' ? row.abandonCount.toNumber() : row.abandonCount;
+        return {
+            error: false,
+            data: {
+                id: row.id,
+                title: row.title,
+                status: row.status,
+                abandonCount,
+                abandonReason: row.abandonReason,
+            },
+        };
+    }
+}

package/dist/mcp/handlers/swarm/advance.handler.js

@@ -0,0 +1,78 @@
+import { GET_TASK_STATE_QUERY } from './queries.js';
+/**
+ * Query to start working on a claimed task (transition to in_progress)
+ */
+const START_TASK_QUERY = `
+  MATCH (t:SwarmTask {id: $taskId, projectId: $projectId})
+  WHERE t.status = 'claimed' AND t.claimedBy = $agentId
+
+  SET t.status = 'in_progress',
+      t.startedAt = timestamp(),
+      t.updatedAt = timestamp()
+
+  RETURN t.id as id,
+         t.status as status,
+         t.claimedBy as claimedBy,
+         t.startedAt as startedAt
+`;
+/**
+ * Query to force-start a task stuck in claimed state.
+ * Allows recovery when the normal start action fails.
+ */
+const FORCE_START_QUERY = `
+  MATCH (t:SwarmTask {id: $taskId, projectId: $projectId})
+  WHERE t.claimedBy = $agentId
+    AND t.status IN ['claimed', 'available']
+
+  SET t.status = 'in_progress',
+      t.claimedBy = $agentId,
+      t.claimedAt = COALESCE(t.claimedAt, timestamp()),
+      t.startedAt = timestamp(),
+      t.updatedAt = timestamp(),
+      t.forceStarted = true,
+      t.forceStartReason = $reason
+
+  RETURN t.id as id,
+         t.title as title,
+         t.status as status,
+         t.claimedBy as claimedBy,
+         t.startedAt as startedAt,
+         t.forceStarted as forceStarted
+`;
+export class SwarmAdvanceHandler {
+    neo4jService;
+    constructor(neo4jService) {
+        this.neo4jService = neo4jService;
+    }
+    async start(projectId, taskId, agentId) {
+        const result = await this.neo4jService.run(START_TASK_QUERY, {
+            taskId,
+            projectId,
+            agentId,
+        });
+        if (result.length === 0) {
+            const stateResult = await this.neo4jService.run(GET_TASK_STATE_QUERY, {
+                taskId,
+                projectId,
+            });
+            return { error: true, data: stateResult[0] };
+        }
+        return { error: false, data: result[0] };
+    }
+    async forceStart(projectId, taskId, agentId, reason) {
+        const result = await this.neo4jService.run(FORCE_START_QUERY, {
+            taskId,
+            projectId,
+            agentId,
+            reason: reason || 'Recovering from stuck state',
+        });
+        if (result.length === 0) {
+            const stateResult = await this.neo4jService.run(GET_TASK_STATE_QUERY, {
+                taskId,
+                projectId,
+            });
+            return { error: true, data: stateResult[0] };
+        }
+        return { error: false, data: result[0] };
+    }
+}

package/dist/mcp/handlers/swarm/claim.handler.js

@@ -0,0 +1,61 @@
+import { TASK_PRIORITIES } from '../../tools/swarm-constants.js';
+import { CLAIM_TASK_BY_ID_QUERY, CLAIM_NEXT_TASK_QUERY, GET_TASK_STATE_QUERY } from './queries.js';
+/** Maximum retries when racing for a task */
+const MAX_CLAIM_RETRIES = 3;
+/** Delay between retries (ms) */
+const RETRY_DELAY_BASE_MS = 50;
+export class SwarmClaimHandler {
+    neo4jService;
+    constructor(neo4jService) {
+        this.neo4jService = neo4jService;
+    }
+    /**
+     * Claim a specific task by ID.
+     */
+    async claimById(projectId, taskId, agentId, targetStatus) {
+        const result = await this.neo4jService.run(CLAIM_TASK_BY_ID_QUERY, {
+            taskId,
+            projectId,
+            agentId,
+            targetStatus,
+        });
+        if (result.length === 0) {
+            const stateResult = await this.neo4jService.run(GET_TASK_STATE_QUERY, {
+                taskId,
+                projectId,
+            });
+            return { error: true, data: stateResult[0], retryAttempts: 0 };
+        }
+        return { error: false, data: result[0], retryAttempts: 0 };
+    }
+    /**
+     * Auto-select and claim the highest priority available task.
+     * Includes retry logic with exponential backoff for race conditions.
+     */
+    async claimNext(projectId, swarmId, agentId, targetStatus, filters) {
+        const minPriorityScore = filters?.minPriority ? TASK_PRIORITIES[filters.minPriority] : null;
+        let result = [];
+        let retryCount = 0;
+        while (retryCount < MAX_CLAIM_RETRIES) {
+            result = await this.neo4jService.run(CLAIM_NEXT_TASK_QUERY, {
+                projectId,
+                swarmId,
+                agentId,
+                types: filters?.types || null,
+                minPriority: minPriorityScore,
+                targetStatus,
+            });
+            if (result.length > 0) {
+                break;
+            }
+            retryCount++;
+            if (retryCount < MAX_CLAIM_RETRIES) {
+                await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_BASE_MS * Math.pow(2, retryCount - 1)));
+            }
+        }
+        if (result.length === 0) {
+            return { error: false, data: null, retryAttempts: retryCount };
+        }
+        return { error: false, data: result[0], retryAttempts: retryCount };
+    }
+}

package/dist/mcp/handlers/swarm/index.js

@@ -0,0 +1,5 @@
+export { SwarmClaimHandler } from './claim.handler.js';
+export { SwarmReleaseHandler } from './release.handler.js';
+export { SwarmAbandonHandler } from './abandon.handler.js';
+export { SwarmAdvanceHandler } from './advance.handler.js';
+export { GET_TASK_STATE_QUERY, CLAIM_TASK_BY_ID_QUERY, CLAIM_NEXT_TASK_QUERY } from './queries.js';