gitnexus 1.1.1 → 1.1.2

package/README.md

@@ -1,196 +1,196 @@
-# GitNexus
-
-**Graph-powered code intelligence for AI agents.** Index any codebase into a knowledge graph, then query it via MCP or CLI.
-
-Works with **Cursor**, **Claude Code**, **Windsurf**, **Cline**, **OpenCode**, and any MCP-compatible tool.
-
-[![npm version](https://img.shields.io/npm/v/gitnexus.svg)](https://www.npmjs.com/package/gitnexus)
-[![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
-
----
-
-## Why?
-
-AI coding tools don't understand your codebase structure. They edit a function without knowing 47 other functions depend on it. GitNexus fixes this by **precomputing every dependency, call chain, and relationship** into a queryable graph.
-
-**Three commands to give your AI agent full codebase awareness.**
-
-## Quick Start
-
-```bash
-# Install
-npm install -g gitnexus
-
-# One-time: configure MCP for your editors
-gitnexus setup
-
-# Index your repository (run from repo root)
-gitnexus analyze
-
-# Done! Open your editor — MCP connects automatically.
-```
-
-Or without installing globally:
-
-```bash
-npx gitnexus setup       # one-time
-npx gitnexus analyze     # per repo
-```
-
-The `setup` command auto-detects Cursor, Claude Code, and OpenCode, then writes the correct global MCP config. You only run it once.
-
-## MCP Setup (manual)
-
-If you prefer to configure manually instead of using `gitnexus setup`:
-
-### Cursor / Windsurf
-
-Add to `~/.cursor/mcp.json` (global — works for all projects):
-
-```json
-{
-  "mcpServers": {
-    "gitnexus": {
-      "command": "npx",
-      "args": ["-y", "gitnexus", "mcp"]
-    }
-  }
-}
-```
-
-### Claude Code
-
-```bash
-claude mcp add gitnexus -- npx -y gitnexus mcp
-```
-
-### OpenCode
-
-Add to `~/.config/opencode/config.json`:
-
-```json
-{
-  "mcp": {
-    "gitnexus": {
-      "command": "npx",
-      "args": ["-y", "gitnexus", "mcp"]
-    }
-  }
-}
-```
-
-## What It Does
-
-GitNexus indexes your codebase through 7 phases:
-
-1. **Structure** — File/folder tree
-2. **Parse** — AST extraction via Tree-sitter (9 languages)
-3. **Imports** — Resolve import paths (including TS path aliases, Rust modules, Java wildcards, Go packages)
-4. **Calls** — Function call resolution with confidence scoring (0.3-0.9)
-5. **Heritage** — Class extends/implements chains
-6. **Communities** — Leiden algorithm clusters related code into functional groups
-7. **Processes** — Entry point detection and execution flow tracing
-
-The result is a **KuzuDB graph database** stored locally in `.gitnexus/` with full-text search and semantic embeddings.
-
-## MCP Tools
-
-Your AI agent gets these tools automatically:
-
-| Tool | What It Does | `repo` Param |
-|------|-------------|--------------|
-| `list_repos` | Discover all indexed repositories | — |
-| `search` | Hybrid search (BM25 + semantic) with cluster context | Optional |
-| `overview` | List all clusters and processes | Optional |
-| `explore` | Deep dive on a symbol, cluster, or process | Optional |
-| `impact` | Blast radius analysis | Optional |
-| `cypher` | Raw Cypher graph queries | Optional |
-| `analyze` | Index or re-index a repository | Optional |
-
-> With one indexed repo, the `repo` param is optional. With multiple, specify which: `search({query: "auth", repo: "my-app"})`.
-
-## MCP Resources
-
-| Resource | Purpose |
-|----------|---------|
-| `gitnexus://repos` | List all indexed repositories (read first) |
-| `gitnexus://repo/{name}/context` | Codebase stats and overview |
-| `gitnexus://repo/{name}/clusters` | All functional clusters |
-| `gitnexus://repo/{name}/cluster/{name}` | Cluster members and details |
-| `gitnexus://repo/{name}/processes` | All execution flows |
-| `gitnexus://repo/{name}/process/{name}` | Full process trace |
-| `gitnexus://repo/{name}/schema` | Graph schema for Cypher queries |
-
-## CLI Commands
-
-```bash
-gitnexus setup                # Configure MCP for your editors (one-time)
-gitnexus analyze [path]       # Index a repository (or update stale index)
-gitnexus analyze --force      # Force full re-index
-gitnexus mcp                  # Start MCP server (stdio) — serves all indexed repos
-gitnexus serve                # Start HTTP server for web UI
-gitnexus list                 # List all indexed repositories
-gitnexus status               # Show index status for current repo
-gitnexus clean                # Delete index for current repo
-gitnexus clean --all          # Delete all indexes
-```
-
-## Multi-Repo Support
-
-GitNexus supports indexing multiple repositories. Each `gitnexus analyze` registers the repo in a global registry (`~/.gitnexus/registry.json`). The MCP server serves all indexed repos automatically with lazy KuzuDB connections.
-
-## Supported Languages
-
-TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust
-
-## How Impact Analysis Works
-
-```
-gitnexus_impact({target: "UserService", direction: "upstream", repo: "my-app"})
-
-TARGET: Class UserService (src/services/user.ts)
-
-UPSTREAM (what depends on this):
-  Depth 1 (direct callers):
-    handleLogin [CALLS 90%] → src/api/auth.ts:45
-    handleRegister [CALLS 90%] → src/api/auth.ts:78
-  Depth 2:
-    authRouter [IMPORTS] → src/routes/auth.ts
-
-8 files affected, 3 clusters touched
-```
-
-Options: `maxDepth`, `minConfidence`, `relationTypes`, `includeTests`
-
-## Agent Skills
-
-GitNexus ships with skill files that teach AI agents how to use the tools effectively:
-
-- **Exploring** — Navigate unfamiliar code using the knowledge graph
-- **Debugging** — Trace bugs through call chains
-- **Impact Analysis** — Analyze blast radius before changes
-- **Refactoring** — Plan safe refactors using dependency mapping
-
-These are installed automatically to `.claude/skills/` when you run `gitnexus analyze`.
-
-## Requirements
-
-- Node.js >= 18
-- Git repository (uses git for commit tracking)
-
-## Privacy
-
-- All processing happens locally on your machine
-- No code is sent to any server
-- Index stored in `.gitnexus/` inside your repo (gitignored)
-- Global registry at `~/.gitnexus/` stores only paths and metadata
-
-## Web UI
-
-GitNexus also has a browser-based UI at [gitnexus.vercel.app](https://gitnexus.vercel.app) — 100% client-side, your code never leaves the browser.
-
-## License
-
-[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/)
-
-Free for non-commercial use. Contact for commercial licensing.
+# GitNexus
+
+**Graph-powered code intelligence for AI agents.** Index any codebase into a knowledge graph, then query it via MCP or CLI.
+
+Works with **Cursor**, **Claude Code**, **Windsurf**, **Cline**, **OpenCode**, and any MCP-compatible tool.
+
+[![npm version](https://img.shields.io/npm/v/gitnexus.svg)](https://www.npmjs.com/package/gitnexus)
+[![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
+
+---
+
+## Why?
+
+AI coding tools don't understand your codebase structure. They edit a function without knowing 47 other functions depend on it. GitNexus fixes this by **precomputing every dependency, call chain, and relationship** into a queryable graph.
+
+**Three commands to give your AI agent full codebase awareness.**
+
+## Quick Start
+
+```bash
+# Install
+npm install -g gitnexus
+
+# One-time: configure MCP for your editors
+gitnexus setup
+
+# Index your repository (run from repo root)
+gitnexus analyze
+
+# Done! Open your editor — MCP connects automatically.
+```
+
+Or without installing globally:
+
+```bash
+npx gitnexus setup       # one-time
+npx gitnexus analyze     # per repo
+```
+
+The `setup` command auto-detects Cursor, Claude Code, and OpenCode, then writes the correct global MCP config. You only run it once.
+
+## MCP Setup (manual)
+
+If you prefer to configure manually instead of using `gitnexus setup`:
+
+### Cursor / Windsurf
+
+Add to `~/.cursor/mcp.json` (global — works for all projects):
+
+```json
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add gitnexus -- npx -y gitnexus@latest mcp
+```
+
+### OpenCode
+
+Add to `~/.config/opencode/config.json`:
+
+```json
+{
+  "mcp": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}
+```
+
+## What It Does
+
+GitNexus indexes your codebase through 7 phases:
+
+1. **Structure** — File/folder tree
+2. **Parse** — AST extraction via Tree-sitter (9 languages)
+3. **Imports** — Resolve import paths (including TS path aliases, Rust modules, Java wildcards, Go packages)
+4. **Calls** — Function call resolution with confidence scoring (0.3-0.9)
+5. **Heritage** — Class extends/implements chains
+6. **Communities** — Leiden algorithm clusters related code into functional groups
+7. **Processes** — Entry point detection and execution flow tracing
+
+The result is a **KuzuDB graph database** stored locally in `.gitnexus/` with full-text search and semantic embeddings.
+
+## MCP Tools
+
+Your AI agent gets these tools automatically:
+
+| Tool | What It Does | `repo` Param |
+|------|-------------|--------------|
+| `list_repos` | Discover all indexed repositories | — |
+| `search` | Hybrid search (BM25 + semantic) with cluster context | Optional |
+| `overview` | List all clusters and processes | Optional |
+| `explore` | Deep dive on a symbol, cluster, or process | Optional |
+| `impact` | Blast radius analysis | Optional |
+| `cypher` | Raw Cypher graph queries | Optional |
+| `analyze` | Index or re-index a repository | Optional |
+
+> With one indexed repo, the `repo` param is optional. With multiple, specify which: `search({query: "auth", repo: "my-app"})`.
+
+## MCP Resources
+
+| Resource | Purpose |
+|----------|---------|
+| `gitnexus://repos` | List all indexed repositories (read first) |
+| `gitnexus://repo/{name}/context` | Codebase stats and overview |
+| `gitnexus://repo/{name}/clusters` | All functional clusters |
+| `gitnexus://repo/{name}/cluster/{name}` | Cluster members and details |
+| `gitnexus://repo/{name}/processes` | All execution flows |
+| `gitnexus://repo/{name}/process/{name}` | Full process trace |
+| `gitnexus://repo/{name}/schema` | Graph schema for Cypher queries |
+
+## CLI Commands
+
+```bash
+gitnexus setup                # Configure MCP for your editors (one-time)
+gitnexus analyze [path]       # Index a repository (or update stale index)
+gitnexus analyze --force      # Force full re-index
+gitnexus mcp                  # Start MCP server (stdio) — serves all indexed repos
+gitnexus serve                # Start HTTP server for web UI
+gitnexus list                 # List all indexed repositories
+gitnexus status               # Show index status for current repo
+gitnexus clean                # Delete index for current repo
+gitnexus clean --all          # Delete all indexes
+```
+
+## Multi-Repo Support
+
+GitNexus supports indexing multiple repositories. Each `gitnexus analyze` registers the repo in a global registry (`~/.gitnexus/registry.json`). The MCP server serves all indexed repos automatically with lazy KuzuDB connections.
+
+## Supported Languages
+
+TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust
+
+## How Impact Analysis Works
+
+```
+gitnexus_impact({target: "UserService", direction: "upstream", repo: "my-app"})
+
+TARGET: Class UserService (src/services/user.ts)
+
+UPSTREAM (what depends on this):
+  Depth 1 (direct callers):
+    handleLogin [CALLS 90%] → src/api/auth.ts:45
+    handleRegister [CALLS 90%] → src/api/auth.ts:78
+  Depth 2:
+    authRouter [IMPORTS] → src/routes/auth.ts
+
+8 files affected, 3 clusters touched
+```
+
+Options: `maxDepth`, `minConfidence`, `relationTypes`, `includeTests`
+
+## Agent Skills
+
+GitNexus ships with skill files that teach AI agents how to use the tools effectively:
+
+- **Exploring** — Navigate unfamiliar code using the knowledge graph
+- **Debugging** — Trace bugs through call chains
+- **Impact Analysis** — Analyze blast radius before changes
+- **Refactoring** — Plan safe refactors using dependency mapping
+
+These are installed automatically to `.claude/skills/` when you run `gitnexus analyze`.
+
+## Requirements
+
+- Node.js >= 18
+- Git repository (uses git for commit tracking)
+
+## Privacy
+
+- All processing happens locally on your machine
+- No code is sent to any server
+- Index stored in `.gitnexus/` inside your repo (gitignored)
+- Global registry at `~/.gitnexus/` stores only paths and metadata
+
+## Web UI
+
+GitNexus also has a browser-based UI at [gitnexus.vercel.app](https://gitnexus.vercel.app) — 100% client-side, your code never leaves the browser.
+
+## License
+
+[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/)
+
+Free for non-commercial use. Contact for commercial licensing.

package/dist/cli/ai-context.js

@@ -17,85 +17,85 @@ const GITNEXUS_END_MARKER = '<!-- gitnexus:end -->';
  * Generate the full GitNexus context content (resources-first approach)
  */
 function generateGitNexusContent(projectName, stats) {
-    return `${GITNEXUS_START_MARKER}
-# GitNexus MCP
-
-This project is indexed as **${projectName}** by GitNexus, providing AI agents with deep code intelligence.
-
-## Project: ${projectName}
-
-| Metric | Count |
-|--------|-------|
-| Files | ${stats.files || 0} |
-| Symbols | ${stats.nodes || 0} |
-| Relationships | ${stats.edges || 0} |
-| Communities | ${stats.communities || 0} |
-| Processes | ${stats.processes || 0} |
-
-## Quick Start
-
-\`\`\`
-1. READ gitnexus://repos                          → Discover all indexed repos
-2. READ gitnexus://repo/${projectName}/context     → Get codebase overview (~150 tokens)
-3. READ gitnexus://repo/${projectName}/clusters    → See all functional clusters
-4. gitnexus_search({query: "...", repo: "${projectName}"}) → Find code by query
-\`\`\`
-
-## Available Resources
-
-| Resource | Purpose |
-|----------|---------|
-| \`gitnexus://repos\` | List all indexed repositories |
-| \`gitnexus://repo/${projectName}/context\` | Codebase stats, tools, and resources overview |
-| \`gitnexus://repo/${projectName}/clusters\` | All clusters with symbol counts and cohesion |
-| \`gitnexus://repo/${projectName}/cluster/{name}\` | Cluster members and details |
-| \`gitnexus://repo/${projectName}/processes\` | All execution flows with types |
-| \`gitnexus://repo/${projectName}/process/{name}\` | Full process trace with steps |
-| \`gitnexus://repo/${projectName}/schema\` | Graph schema for Cypher queries |
-
-## Available Tools
-
-| Tool | Purpose | When to Use |
-|------|---------|-------------|
-| \`list_repos\` | Discover indexed repos | First step with multiple repos |
-| \`search\` | Semantic + keyword search | Finding code by query |
-| \`overview\` | List clusters & processes | Understanding architecture |
-| \`explore\` | Deep dive on symbol/cluster/process | Detailed investigation |
-| \`impact\` | Blast radius analysis | Before making changes |
-| \`cypher\` | Raw graph queries | Complex analysis |
-
-> **Multi-repo:** When multiple repos are indexed, pass \`repo: "${projectName}"\` to target this project.
-
-## Workflow Examples
-
-### Exploring the Codebase
-\`\`\`
-READ gitnexus://repos                            → Discover repos
-READ gitnexus://repo/${projectName}/context       → Stats and overview
-READ gitnexus://repo/${projectName}/clusters      → Find relevant cluster
-READ gitnexus://repo/${projectName}/cluster/Auth  → Explore Auth cluster
-gitnexus_explore({name: "validateUser", type: "symbol", repo: "${projectName}"})
-\`\`\`
-
-### Planning a Change
-\`\`\`
-gitnexus_impact({target: "UserService", direction: "upstream", repo: "${projectName}"})
-READ gitnexus://repo/${projectName}/processes     → Check affected flows
-gitnexus_explore({name: "LoginFlow", type: "process", repo: "${projectName}"})
-\`\`\`
-
-## Graph Schema
-
-**Nodes:** File, Function, Class, Interface, Method, Community, Process
-
-**Relationships:** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
-
-\`\`\`cypher
-// Example: Find callers of a function
-MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
-RETURN caller.name, caller.filePath
-\`\`\`
-
+    return `${GITNEXUS_START_MARKER}
+# GitNexus MCP
+
+This project is indexed as **${projectName}** by GitNexus, providing AI agents with deep code intelligence.
+
+## Project: ${projectName}
+
+| Metric | Count |
+|--------|-------|
+| Files | ${stats.files || 0} |
+| Symbols | ${stats.nodes || 0} |
+| Relationships | ${stats.edges || 0} |
+| Communities | ${stats.communities || 0} |
+| Processes | ${stats.processes || 0} |
+
+## Quick Start
+
+\`\`\`
+1. READ gitnexus://repos                          → Discover all indexed repos
+2. READ gitnexus://repo/${projectName}/context     → Get codebase overview (~150 tokens)
+3. READ gitnexus://repo/${projectName}/clusters    → See all functional clusters
+4. gitnexus_search({query: "...", repo: "${projectName}"}) → Find code by query
+\`\`\`
+
+## Available Resources
+
+| Resource | Purpose |
+|----------|---------|
+| \`gitnexus://repos\` | List all indexed repositories |
+| \`gitnexus://repo/${projectName}/context\` | Codebase stats, tools, and resources overview |
+| \`gitnexus://repo/${projectName}/clusters\` | All clusters with symbol counts and cohesion |
+| \`gitnexus://repo/${projectName}/cluster/{name}\` | Cluster members and details |
+| \`gitnexus://repo/${projectName}/processes\` | All execution flows with types |
+| \`gitnexus://repo/${projectName}/process/{name}\` | Full process trace with steps |
+| \`gitnexus://repo/${projectName}/schema\` | Graph schema for Cypher queries |
+
+## Available Tools
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| \`list_repos\` | Discover indexed repos | First step with multiple repos |
+| \`search\` | Semantic + keyword search | Finding code by query |
+| \`overview\` | List clusters & processes | Understanding architecture |
+| \`explore\` | Deep dive on symbol/cluster/process | Detailed investigation |
+| \`impact\` | Blast radius analysis | Before making changes |
+| \`cypher\` | Raw graph queries | Complex analysis |
+
+> **Multi-repo:** When multiple repos are indexed, pass \`repo: "${projectName}"\` to target this project.
+
+## Workflow Examples
+
+### Exploring the Codebase
+\`\`\`
+READ gitnexus://repos                            → Discover repos
+READ gitnexus://repo/${projectName}/context       → Stats and overview
+READ gitnexus://repo/${projectName}/clusters      → Find relevant cluster
+READ gitnexus://repo/${projectName}/cluster/Auth  → Explore Auth cluster
+gitnexus_explore({name: "validateUser", type: "symbol", repo: "${projectName}"})
+\`\`\`
+
+### Planning a Change
+\`\`\`
+gitnexus_impact({target: "UserService", direction: "upstream", repo: "${projectName}"})
+READ gitnexus://repo/${projectName}/processes     → Check affected flows
+gitnexus_explore({name: "LoginFlow", type: "process", repo: "${projectName}"})
+\`\`\`
+
+## Graph Schema
+
+**Nodes:** File, Function, Class, Interface, Method, Community, Process
+
+**Relationships:** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
+
+\`\`\`cypher
+// Example: Find callers of a function
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
+RETURN caller.name, caller.filePath
+\`\`\`
+
 ${GITNEXUS_END_MARKER}`;
 }
 /**
@@ -179,16 +179,16 @@ async function installSkills(repoPath) {
             }
             catch {
                 // Fallback: generate minimal skill content
-                skillContent = `---
-name: gitnexus-${skill.name}
-description: ${skill.description}
----
-
-# ${skill.name.charAt(0).toUpperCase() + skill.name.slice(1)}
-
-${skill.description}
-
-Use GitNexus tools to accomplish this task.
+                skillContent = `---
+name: gitnexus-${skill.name}
+description: ${skill.description}
+---
+
+# ${skill.name.charAt(0).toUpperCase() + skill.name.slice(1)}
+
+${skill.description}
+
+Use GitNexus tools to accomplish this task.
 `;
             }
             await fs.writeFile(skillPath, skillContent, 'utf-8');

package/dist/cli/setup.js

@@ -15,7 +15,7 @@ import { getGlobalDir } from '../storage/repo-manager.js';
 function getMcpEntry() {
     return {
         command: 'npx',
-        args: ['-y', 'gitnexus', 'mcp'],
+        args: ['-y', 'gitnexus@latest', 'mcp'],
     };
 }
 /**

package/dist/core/ingestion/pipeline.js

@@ -169,6 +169,9 @@ export const runPipelineFromRepo = async (repoPath, onProgress) => {
             message: 'Detecting execution flows...',
             stats: { filesProcessed: files.length, totalFiles: files.length, nodesCreated: graph.nodeCount },
         });
+        // Dynamic process cap based on codebase size
+        const symbolCount = graph.nodes.filter(n => n.label !== 'File').length;
+        const dynamicMaxProcesses = Math.max(20, Math.min(300, Math.round(symbolCount / 10)));
         const processResult = await processProcesses(graph, communityResult.memberships, (message, progress) => {
             const processProgress = 98 + (progress * 0.01);
             onProgress({
@@ -177,7 +180,7 @@ export const runPipelineFromRepo = async (repoPath, onProgress) => {
                 message,
                 stats: { filesProcessed: files.length, totalFiles: files.length, nodesCreated: graph.nodeCount },
             });
-        });
+        }, { maxProcesses: dynamicMaxProcesses, minSteps: 3 });
         if (isDev) {
             console.log(`🔄 Process detection: ${processResult.stats.totalProcesses} processes found (${processResult.stats.crossCommunityCount} cross-community)`);
         }

package/dist/core/ingestion/process-processor.js

@@ -15,7 +15,7 @@ const DEFAULT_CONFIG = {
     maxTraceDepth: 10,
     maxBranching: 4,
     maxProcesses: 75,
-    minSteps: 2,
+    minSteps: 3, // 3+ steps = genuine multi-hop flow (2-step is just "A calls B")
 };
 // ============================================================================
 // MAIN PROCESSOR
@@ -51,10 +51,13 @@ export const processProcesses = async (knowledgeGraph, memberships, onProgress,
         }
     }
     onProgress?.(`Found ${allTraces.length} traces, deduplicating...`, 60);
-    // Step 3: Deduplicate similar traces
+    // Step 3: Deduplicate similar traces (subset removal)
     const uniqueTraces = deduplicateTraces(allTraces);
+    // Step 3b: Deduplicate by entry+terminal pair (keep longest path per pair)
+    const endpointDeduped = deduplicateByEndpoints(uniqueTraces);
+    onProgress?.(`Deduped ${uniqueTraces.length} → ${endpointDeduped.length} unique endpoint pairs`, 70);
     // Step 4: Limit to max processes (prioritize longer traces)
-    const limitedTraces = uniqueTraces
+    const limitedTraces = endpointDeduped
         .sort((a, b) => b.length - a.length)
         .slice(0, cfg.maxProcesses);
     onProgress?.(`Creating ${limitedTraces.length} process nodes...`, 80);
@@ -266,6 +269,27 @@ const deduplicateTraces = (traces) => {
     return unique;
 };
 // ============================================================================
+// HELPER: Deduplicate by entry+terminal endpoints
+// ============================================================================
+/**
+ * Keep only the longest trace per unique entry→terminal pair.
+ * Multiple paths between the same two endpoints are redundant for agents.
+ */
+const deduplicateByEndpoints = (traces) => {
+    if (traces.length === 0)
+        return [];
+    const byEndpoints = new Map();
+    // Sort longest first so the first seen per key is the longest
+    const sorted = [...traces].sort((a, b) => b.length - a.length);
+    for (const trace of sorted) {
+        const key = `${trace[0]}::${trace[trace.length - 1]}`;
+        if (!byEndpoints.has(key)) {
+            byEndpoints.set(key, trace);
+        }
+    }
+    return Array.from(byEndpoints.values());
+};
+// ============================================================================
 // HELPER: String utilities
 // ============================================================================
 const capitalize = (s) => {