@datafrog-io/n2n-nexus 0.3.4 → 0.3.6

package/build/config/cli.js

@@ -0,0 +1,11 @@
+/**
+ * CLI Argument Parsing
+ */
+const args = process.argv.slice(2);
+export function getArg(k) {
+    const i = args.indexOf(k);
+    return i !== -1 && args[i + 1] ? args[i + 1] : "";
+}
+export function hasFlag(k) {
+    return args.includes(k) || args.includes(k.charAt(1) === "-" ? k : k.substring(0, 2));
+}

package/build/config/index.js

@@ -0,0 +1,81 @@
+/**
+ * Config Module - Central Configuration
+ */
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { FILE_ENCODING, PACKAGE_JSON } from "../constants.js";
+import { getArg, hasFlag } from "./cli.js";
+import { getRootPath } from "./paths.js";
+import { isHostAutoElection } from "../network/election.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Load version from package.json
+const pkgPath = path.resolve(__dirname, `../../${PACKAGE_JSON}`);
+const pkg = JSON.parse(fs.readFileSync(pkgPath, FILE_ENCODING));
+export { pkg };
+// --- CLI Commands Handlers ---
+if (hasFlag("--help") || hasFlag("-h")) {
+    console.error(`
+n2ns Nexus 🚀 - Local Digital Asset Hub (MCP Server) v${pkg.version}
+
+USAGE:
+  npx -y @datafrog-io/n2n-nexus [options]
+
+DESCRIPTION:
+  A local-first project management and collaboration hub designed for 
+  multi-AI assistant coordination across different IDEs (Cursor, VS Code, etc.).
+
+OPTIONS:
+  --root <path>     Directory for data persistence. Default: ~/.n2n-nexus
+  --version, -v     Show version number.
+  --help, -h        Show this message.
+
+MCP CONFIG EXAMPLE (claude_desktop_config.json):
+  {
+    "mcpServers": {
+      "n2n-nexus": {
+        "command": "npx",
+        "args": ["-y", "@datafrog-io/n2n-nexus", "--root", "/path/to/storage"]
+      }
+    }
+  }
+
+ENVIRONMENT VARIABLES:
+  NEXUS_ROOT        Override default storage path.
+    `);
+    process.exit(0);
+}
+if (hasFlag("--version") || hasFlag("-v")) {
+    console.error(pkg.version);
+    process.exit(0);
+}
+/**
+ * Automatic Project Name Detection
+ */
+function getAutoProjectName() {
+    try {
+        const localPkgPath = path.join(process.cwd(), PACKAGE_JSON);
+        if (fs.existsSync(localPkgPath)) {
+            const localPkg = JSON.parse(fs.readFileSync(localPkgPath, FILE_ENCODING));
+            if (localPkg.name)
+                return localPkg.name.split("/").pop() || localPkg.name;
+        }
+    }
+    catch { /* ignore */ }
+    const base = path.basename(process.cwd()) || "Assistant";
+    const suffix = Math.random().toString(36).substring(2, 6);
+    return `${base}-${suffix}`;
+}
+// Run election at module load
+const rootPath = getRootPath();
+const election = await isHostAutoElection(rootPath);
+const projectName = getAutoProjectName();
+export const hostServer = election.server;
+export const CONFIG = {
+    instanceId: getArg("--id") || projectName,
+    isHost: election.isHost,
+    rootStorage: election.isHost ? rootPath : (election.rootStorage || rootPath),
+    port: election.port
+};
+// Re-export for Guest reconnection
+export { isHostAutoElection } from "../network/election.js";

package/build/config/paths.js

@@ -0,0 +1,38 @@
+/**
+ * Path Resolution Logic
+ */
+import path from "path";
+import os from "os";
+import { SERVICE_NAME } from "../constants.js";
+import { getArg } from "./cli.js";
+/**
+ * Normalize and resolve the root storage path
+ */
+export function normalizeRootPath(inputPath) {
+    // Priority: CLI --root > ENV NEXUS_ROOT > System Default
+    let root = inputPath || process.env.NEXUS_ROOT || getDefaultDataDir();
+    // Resolve ~ to home directory
+    if (root.startsWith("~")) {
+        root = path.join(os.homedir(), root.slice(1));
+    }
+    // Cross-platform adaptation (WSL <-> Windows)
+    if (process.platform === "linux" && /^[a-zA-Z]:[/\\]/.test(root)) {
+        const drive = root[0].toLowerCase();
+        root = `/mnt/${drive}${root.slice(2).replace(/\\/g, "/")}`;
+    }
+    return path.resolve(root);
+}
+/**
+ * Get the default data directory
+ */
+export function getDefaultDataDir() {
+    const home = os.homedir();
+    // Use ~/.n2n-nexus for all platforms (developer-friendly convention)
+    return path.join(home, `.${SERVICE_NAME}`);
+}
+/**
+ * Get the root storage path from CLI or environment
+ */
+export function getRootPath() {
+    return normalizeRootPath(getArg("--root"));
+}

package/build/constants.js

@@ -0,0 +1,22 @@
+/**
+ * Nexus Network Constants
+ *
+ * Centralized configuration for network-related settings.
+ */
+// Service identification
+export const SERVICE_NAME = "n2n-nexus";
+// Host address for binding and connecting
+// Use "0.0.0.0" to allow connections from any interface
+// Use "127.0.0.1" to restrict to localhost only
+export const NEXUS_HOST = "0.0.0.0";
+// Port range for auto-election
+export const PORT_RANGE_START = 5688;
+export const PORT_RANGE_END = 5800;
+// Timeouts (milliseconds)
+export const HANDSHAKE_TIMEOUT = 500;
+export const HEARTBEAT_INTERVAL = 30000;
+// Task cleanup
+export const TASK_CLEANUP_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+// File I/O
+export const FILE_ENCODING = "utf-8";
+export const PACKAGE_JSON = "package.json";

package/build/index.js

@@ -1,31 +1,25 @@
 #!/usr/bin/env node
+/**
+ * n2ns Nexus: Unified Project Asset & Collaboration Hub
+ *
+ * Modular MCP Server for multi-AI assistant coordination.
+ */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
-import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
-import { readFileSync } from "fs";
-import { join } from "path";
-import { fileURLToPath } from "url";
-import http from "http";
-import { CONFIG, hostServer } from "./config.js";
+import { CONFIG, hostServer, pkg } from "./config/index.js";
 import { StorageManager } from "./storage/index.js";
 import { TOOL_DEFINITIONS, handleToolCall } from "./tools/index.js";
 import { listResources, getResourceContent } from "./resources/index.js";
 import { sanitizeErrorMessage } from "./utils/error.js";
 import { checkHostPermission } from "./utils/auth.js";
-const __dirname = fileURLToPath(new URL(".", import.meta.url));
-const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8"));
-/**
- * n2ns Nexus: Unified Project Asset & Collaboration Hub
- *
- * Modular MCP Server for multi-AI assistant coordination.
- */
+import { SERVICE_NAME } from "./constants.js";
+import { startHost, startGuest } from "./network/index.js";
 class NexusServer {
     server;
     currentProject = null;
     sseTransports = new Map();
     constructor() {
-        this.server = new Server({ name: "n2n-nexus", version: pkg.version }, { capabilities: { resources: {}, tools: {}, prompts: {} } });
+        this.server = new Server({ name: SERVICE_NAME, version: pkg.version }, { capabilities: { resources: {}, tools: {}, prompts: {} } });
         this.setupHandlers();
     }
     setupHandlers() {
@@ -41,96 +35,101 @@ class NexusServer {
         });
         // --- Resource Reading ---
         this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-            const { uri } = request.params;
             try {
-                await StorageManager.init();
-                const content = await getResourceContent(uri, this.currentProject);
-                if (content) {
-                    return { contents: [{ uri, mimeType: content.mimeType, text: content.text }] };
+                const result = await getResourceContent(request.params.uri, this.currentProject);
+                if (!result) {
+                    throw new McpError(ErrorCode.InvalidRequest, `Resource not found: ${request.params.uri}`);
                 }
-                throw new McpError(ErrorCode.InvalidRequest, `Resource not found: ${uri}`);
+                return { contents: [{ uri: request.params.uri, ...result }] };
             }
             catch (error) {
-                if (error instanceof McpError)
-                    throw error;
                 const msg = error instanceof Error ? error.message : String(error);
-                throw new McpError(ErrorCode.InternalError, `Nexus Resource Error: ${sanitizeErrorMessage(msg)}`);
+                throw new McpError(ErrorCode.InternalError, `Nexus Read Error: ${sanitizeErrorMessage(msg)}`);
             }
         });
         // --- Tool Listing ---
-        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
-            tools: TOOL_DEFINITIONS
-        }));
-        // --- Tool Execution ---
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            return { tools: TOOL_DEFINITIONS };
+        });
+        // --- Tool Calling ---
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
-            const { name, arguments: toolArgs } = request.params;
+            const agentId = CONFIG.instanceId;
             try {
-                if (name.startsWith("host_"))
-                    checkHostPermission(name);
-                const result = await handleToolCall(name, toolArgs, {
+                // Special handling for switch_project
+                if (request.params.name === "switch_project") {
+                    const args = request.params.arguments;
+                    if (args.project_id) {
+                        const manifest = await StorageManager.getProjectManifest(args.project_id);
+                        if (manifest) {
+                            this.currentProject = args.project_id;
+                            return { content: [{ type: "text", text: `Switched to project: ${args.project_id}` }] };
+                        }
+                    }
+                    return { content: [{ type: "text", text: `Project '${args.project_id}' not found.` }] };
+                }
+                // Host permission check for privileged tools
+                const hostOnlyTools = ["delete_project", "rename_project", "clear_global_logs", "archive_meeting"];
+                if (hostOnlyTools.includes(request.params.name)) {
+                    try {
+                        checkHostPermission(request.params.name);
+                    }
+                    catch {
+                        return { content: [{ type: "text", text: `[Permission Denied] Tool '${request.params.name}' requires Host privileges.` }] };
+                    }
+                }
+                // Delegate to tool handler
+                const ctx = {
                     currentProject: this.currentProject,
                     setCurrentProject: (id) => { this.currentProject = id; },
-                    notifyResourceUpdate: (uri) => {
-                        this.server.sendResourceUpdated({ uri });
-                    }
-                });
+                    notifyResourceUpdate: (_uri) => { }
+                };
+                const result = await handleToolCall(request.params.name, request.params.arguments, ctx);
                 return result;
             }
             catch (error) {
-                if (error instanceof McpError)
-                    throw error;
-                const errorMessage = error instanceof Error ? error.message : String(error);
+                const msg = error instanceof Error ? error.message : String(error);
                 return {
-                    isError: true,
-                    content: [{ type: "text", text: `Nexus Error: ${sanitizeErrorMessage(errorMessage)}` }]
+                    content: [{ type: "text", text: sanitizeErrorMessage(`Tool Error: ${msg}`) }],
+                    isError: true
                 };
             }
         });
         // --- Prompt Listing ---
-        this.server.setRequestHandler(ListPromptsRequestSchema, async () => ({
-            prompts: [
-                {
-                    name: "init_project_nexus",
-                    description: "Step-by-step guide for registering a new project with proper ID naming conventions.",
-                    arguments: [
-                        { name: "projectType", description: "Type: web, api, chrome, vscode, mcp, android, ios, flutter, desktop, lib, bot, infra, doc", required: true },
-                        { name: "technicalName", description: "Domain (e.g., example.com) or repo slug (e.g., my-library)", required: true }
-                    ]
-                }
-            ]
-        }));
-        // --- Prompt Retrieval ---
+        this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
+            return {
+                prompts: [
+                    {
+                        name: "nexus_status",
+                        description: "Get a comprehensive status report of the current Nexus Hub state"
+                    }
+                ]
+            };
+        });
+        // --- Prompt Getting ---
         this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-            const { name, arguments: args } = request.params;
-            if (name === "init_project_nexus") {
-                const projectType = args?.projectType || "[TYPE]";
-                const technicalName = args?.technicalName || "[NAME]";
-                const projectId = `${projectType}_${technicalName}`;
+            if (request.params.name === "nexus_status") {
+                const registry = await StorageManager.listRegistry();
+                const projectCount = Object.keys(registry.projects).length;
+                const logs = await StorageManager.getRecentLogs(5);
                 return {
-                    description: "Initialize a new Nexus project",
-                    messages: [
-                        {
+                    messages: [{
                             role: "user",
                             content: {
                                 type: "text",
-                                text: `I want to register a new project in Nexus.\n\n**Project Type:** ${projectType}\n**Technical Name:** ${technicalName}`
+                                text: `Nexus Hub Status:
+- Role: ${CONFIG.isHost ? "Host" : "Guest"}
+- Instance: ${CONFIG.instanceId}
+- Port: ${CONFIG.port}
+- Active Projects: ${projectCount}
+- Recent Activity: ${logs.length} entries`
                             }
-                        },
-                        {
-                            role: "assistant",
-                            content: {
-                                type: "text",
-                                text: `## Project ID Convention\n\nBased on your input, the correct Project ID is:\n\n\`\`\`\n${projectId}\n\`\`\`\n\n### Prefix Dictionary\n| Prefix | Use Case |\n|--------|----------|\n| web_ | Websites/Domains |\n| api_ | Backend Services |\n| chrome_ | Chrome Extensions |\n| vscode_ | VSCode Extensions |\n| mcp_ | MCP Servers |\n| android_ | Native Android |\n| ios_ | Native iOS |\n| flutter_ | Cross-platform Mobile |\n| desktop_ | Desktop Apps |\n| lib_ | Libraries/SDKs |\n| bot_ | Bots |\n| infra_ | Infrastructure as Code |\n| doc_ | Technical Docs |\n\n### Next Steps\n1. Call \`register_session_context\` with projectId: \`${projectId}\`\n2. Call \`sync_project_assets\` with your manifest and internal docs.`
-                            }
-                        }
-                    ]
+                        }]
                 };
             }
-            throw new McpError(ErrorCode.InvalidRequest, `Unknown prompt: ${name}`);
+            throw new McpError(ErrorCode.InvalidRequest, `Prompt not found: ${request.params.name}`);
         });
     }
-    async run() {
-        // Handle graceful shutdown
+    setupShutdownHandlers() {
         const shutdown = async (signal) => {
             console.error(`\n[Nexus] Received ${signal}. Shutting down...`);
             try {
@@ -141,154 +140,28 @@ class NexusServer {
             catch { /* ignore */ }
             process.exit(0);
         };
-        // Global Error Handlers to prevent process exit on background errors
         process.on("uncaughtException", (err) => {
             console.error("[Nexus CRITICAL] Uncaught Exception:", err);
-            // Attempt to log to disk if possible, but keep process alive if safe
-            // For a Hub, staying alive is often preferred over crashing
         });
         process.on("unhandledRejection", (reason, promise) => {
             console.error("[Nexus WARNING] Unhandled Rejection at:", promise, "reason:", reason);
-            // Do not exit. Background tasks (like file sync) often trigger this.
         });
         process.on("SIGINT", () => shutdown("SIGINT"));
         process.on("SIGTERM", () => shutdown("SIGTERM"));
+    }
+    async run() {
+        this.setupShutdownHandlers();
+        const context = {
+            config: CONFIG,
+            pkg,
+            mcpServer: this.server,
+            sseTransports: this.sseTransports
+        };
         if (CONFIG.isHost && hostServer) {
-            // --- HOST MODE: Central Hub ---
-            await StorageManager.init();
-            hostServer.on("request", async (req, res) => {
-                const url = new URL(req.url || "", `http://${req.headers.host}`);
-                if (url.pathname === "/mcp") {
-                    const guestId = url.searchParams.get("id") || "UnknownGuest";
-                    if (req.method === "GET") {
-                        const transport = new SSEServerTransport("/mcp", res);
-                        this.sseTransports.set(transport.sessionId, transport);
-                        const msg = `Guest Joined: ${guestId}`;
-                        await StorageManager.addGlobalLog(`HOST:${CONFIG.instanceId}`, msg, "UPDATE");
-                        console.error(`[Nexus Hub] ${msg} (Session: ${transport.sessionId})`);
-                        // Heartbeat: keep connection alive
-                        const heartbeat = setInterval(() => {
-                            try {
-                                res.write(": ping\n\n");
-                            }
-                            catch {
-                                clearInterval(heartbeat);
-                            }
-                        }, 30000);
-                        transport.onclose = () => {
-                            this.sseTransports.delete(transport.sessionId);
-                            clearInterval(heartbeat);
-                            console.error(`[Nexus Hub] Guest Left: ${guestId}`);
-                        };
-                        await this.server.connect(transport);
-                        return;
-                    }
-                    else if (req.method === "POST") {
-                        const sessionId = url.searchParams.get("sessionId");
-                        const transport = sessionId ? this.sseTransports.get(sessionId) : null;
-                        if (transport) {
-                            await transport.handlePostMessage(req, res);
-                        }
-                        else {
-                            res.writeHead(404).end("Session unknown");
-                        }
-                        return;
-                    }
-                }
-            });
-            // Support local stdio for the host's own IDE
-            const transport = new StdioServerTransport();
-            await this.server.connect(transport);
-            const onlineMsg = `Nexus Hub Active. Playing Host.`;
-            await StorageManager.addGlobalLog(`SYSTEM:${CONFIG.instanceId}`, onlineMsg, "UPDATE");
-            console.error(`[Nexus:${CONFIG.instanceId}] ${onlineMsg} (Port: ${CONFIG.port})`);
+            await startHost(hostServer, context);
         }
         else {
-            // --- GUEST MODE: SSE Proxy ---
-            const guestId = CONFIG.instanceId;
-            let retryCount = 0;
-            const maxRetries = 50; // Prevent infinite reconnection loops
-            // Random delay function to prevent thundering herd during re-election
-            const randomDelay = () => Math.floor(Math.random() * 3000);
-            const startProxy = () => {
-                if (retryCount >= maxRetries) {
-                    console.error(`[Nexus Guest] Max retries (${maxRetries}) reached. Exiting.`);
-                    process.exit(1);
-                }
-                retryCount++;
-                // Clear any stale stdin listeners before starting
-                process.stdin.removeAllListeners("data");
-                console.error(`[Nexus:${guestId}] Global Hub detected at ${CONFIG.port}. Joining... (attempt ${retryCount})`);
-                let sessionId = null;
-                let lastActivity = Date.now();
-                // Watchdog: trigger re-election if Host is silent for too long
-                const watchdog = setInterval(() => {
-                    if (Date.now() - lastActivity > 60000) {
-                        console.error("[Nexus Guest] Host stale. Reconnecting...");
-                        cleanup();
-                        // Use setImmediate to break call stack, then delay
-                        setImmediate(() => setTimeout(startProxy, randomDelay()));
-                    }
-                }, 10000);
-                const cleanup = () => {
-                    clearInterval(watchdog);
-                    process.stdin.removeAllListeners("data");
-                };
-                const stdioHandler = (chunk) => {
-                    if (!sessionId)
-                        return;
-                    try {
-                        const req = http.request({
-                            hostname: "127.0.0.1",
-                            port: CONFIG.port,
-                            path: `/mcp?sessionId=${sessionId}&id=${encodeURIComponent(guestId)}`,
-                            method: "POST",
-                            headers: { "Content-Type": "application/json" }
-                        });
-                        // Handle request errors to prevent unhandled exceptions
-                        req.on("error", () => { });
-                        req.write(chunk);
-                        req.end();
-                    }
-                    catch { /* suppress */ }
-                };
-                process.stdin.on("data", stdioHandler);
-                http.get(`http://127.0.0.1:${CONFIG.port}/mcp?id=${encodeURIComponent(guestId)}`, (res) => {
-                    retryCount = 0; // Reset on successful connection
-                    let buffer = "";
-                    res.on("data", (chunk) => {
-                        lastActivity = Date.now();
-                        const str = chunk.toString();
-                        buffer += str;
-                        if (!sessionId && buffer.includes("event: endpoint")) {
-                            const match = buffer.match(/sessionId=([a-f0-9-]+)/);
-                            if (match)
-                                sessionId = match[1];
-                        }
-                        if (str.includes("event: message")) {
-                            const lines = str.split("\n");
-                            const dataLine = lines.find((l) => l.startsWith("data: "));
-                            if (dataLine) {
-                                try {
-                                    process.stdout.write(dataLine.substring(6) + "\n");
-                                }
-                                catch { /* ignore stdout errors */ }
-                            }
-                        }
-                    });
-                    res.on("end", () => {
-                        console.error("[Nexus Guest] Lost connection to Host. Reconnecting...");
-                        cleanup();
-                        // Use setImmediate to break call stack
-                        setImmediate(() => setTimeout(startProxy, randomDelay()));
-                    });
-                }).on("error", () => {
-                    console.error("[Nexus Guest] Proxy Receive Error. Retrying...");
-                    cleanup();
-                    setImmediate(() => setTimeout(startProxy, 1000 + randomDelay()));
-                });
-            };
-            startProxy();
+            await startGuest(CONFIG.port, context);
         }
     }
 }

package/build/network/election.js

@@ -0,0 +1,94 @@
+/**
+ * Host Election Logic
+ *
+ * Handles port scanning, handshake probing, and Host/Guest election.
+ */
+import http from "http";
+import { NEXUS_HOST, PORT_RANGE_START, PORT_RANGE_END, HANDSHAKE_TIMEOUT, SERVICE_NAME } from "../constants.js";
+import { getArg } from "../config/cli.js";
+// We need pkg version for handshake - import dynamically to avoid circular dep
+let pkgVersion = "0.0.0";
+import("../config/index.js").then(m => { pkgVersion = m.pkg.version; }).catch(() => { });
+/**
+ * Probe a port to see if it's a Nexus Host using the Custom Handshake Protocol
+ */
+export async function probeHost(port, myId) {
+    return new Promise((resolve) => {
+        const postData = JSON.stringify({
+            clientVersion: pkgVersion,
+            instanceId: myId
+        });
+        const req = http.request({
+            hostname: NEXUS_HOST,
+            port: port,
+            path: "/nexus/handshake",
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Content-Length": Buffer.byteLength(postData)
+            },
+            timeout: HANDSHAKE_TIMEOUT
+        }, (res) => {
+            let data = "";
+            res.on("data", (chunk) => data += chunk);
+            res.on("end", () => {
+                try {
+                    const info = JSON.parse(data);
+                    if (info.service === SERVICE_NAME && info.role === "host") {
+                        resolve({ isNexus: true, rootStorage: info.rootStorage });
+                    }
+                    else {
+                        resolve({ isNexus: false });
+                    }
+                }
+                catch {
+                    resolve({ isNexus: false });
+                }
+            });
+        });
+        req.on("error", () => resolve({ isNexus: false }));
+        req.on("timeout", () => {
+            req.destroy();
+            resolve({ isNexus: false });
+        });
+        req.write(postData);
+        req.end();
+    });
+}
+/**
+ * Automatic Host Election
+ *
+ * For each port in range:
+ * 1. Try to bind → Success → I am Host
+ * 2. Bind fails → Try handshake → Success → I am Guest
+ * 3. Handshake fails → Port occupied by non-Nexus → Next port
+ */
+export async function isHostAutoElection(_root, blacklistPorts = []) {
+    const startPort = PORT_RANGE_START;
+    const endPort = PORT_RANGE_END;
+    const myId = getArg("--id") || `node-${Math.random().toString(36).substring(2, 6)}`;
+    for (let port = startPort; port <= endPort; port++) {
+        if (blacklistPorts.includes(port))
+            continue;
+        // 1. Try to bind port
+        const bindResult = await new Promise((resolve) => {
+            const server = http.createServer();
+            server.on("error", () => resolve({ success: false }));
+            server.listen(port, NEXUS_HOST, () => resolve({ success: true, server }));
+        });
+        if (bindResult.success) {
+            // Bind success → I am Host
+            return { isHost: true, port, server: bindResult.server };
+        }
+        // 2. Bind failed → Try handshake
+        const probe = await probeHost(port, myId);
+        if (probe.isNexus) {
+            // Handshake success → I am Guest
+            return { isHost: false, port, rootStorage: probe.rootStorage };
+        }
+        // 3. Handshake failed → Port occupied by non-Nexus → Continue
+    }
+    // All ports unavailable
+    console.error(`[Nexus] All ports ${startPort}-${endPort} occupied by non-Nexus processes.`);
+    throw new Error("No available port for Nexus");
+}