chore(release): v0.4.0 - High Availability, Progressive Discovery, and Stability Improvements

Author: bugstan

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.0] - 2026-01-14
+### 🚀 High Availability & Scalability
+- **Failover Mechanism**: Implemented automatic Guest-to-Host promotion. If the Host process dies, a Guest detects usage of the port/lock and takes over immediately with data persistence.
+- **Progressive Discovery**: Added `search_projects` tool. Allows AI to find relevant projects by query without loading the entire 1000+ project registry, reducing context usage.
+- **Immediate Handshake**: Implementing Request Buffering allows the server to accept IDE requests immediately (<10ms) while the Host Election runs in background (~300ms). Fixes startup race conditions.
+- **Stability**: Added explicit E2E tests for process failover (`tests/failover.test.ts`) and request buffering (`tests/buffered_requests.test.ts`).
+
 ## [0.3.9] - 2026-01-11
 ### 🚀 Online First Architecture
 - **Performance**: Removed top-level blocking await for election. Server now starts in <300ms (Online First), reducing startup time by 99% in congested networks.

README.md

@@ -92,9 +92,9 @@
 ```
 
 - **Zero Config**: Just run `npx @datafrog-io/n2n-nexus` - no `--id` or `--host` required.
-- **Auto Election**: First instance binds port 5688 and becomes Host; others join as Guests.
-- **Cross-Project Sync**: All IDEs share the same Hub, enabling real-time cross-project meetings.
-- **Hot Failover**: If Host disconnects, a Guest automatically promotes within 10 seconds.
+- **Immediate Handshake**: Stdio connects instantly (<10ms) for static requests (`tools/list`), buffering dynamic requests until election completes.
+- **Parallel Election**: Concurrent port scanning ensures Host/Guest resolution in <300ms.
+- **Hot Failover**: If Host disconnects, a Guest automatically promotes itself to Host and others reconnect.
 
 ## 🚀 Quick Start
 

docs/ARCHITECTURE.md

@@ -61,3 +61,18 @@ To ensure clarity and prevent collisions in the flat local namespace, all Projec
 | `bot_` | Bots (Discord, Slack, DingTalk, etc.) | `bot_auto-moderator` |
 | `infra_` | Infrastructure as Code, CI/CD, DevOps scripts | `infra_k8s-config` |
 | `doc_` | Pure technical handbooks, strategies, roadmaps | `doc_coding-guide` |
+
+## 🌐 Host-Guest Network Architecture (v2)
+
+### Zero-Config Startup & Election
+The system aims for a "magic" user experience where multiple instances on the same machine automatically discover each other without manual configuration.
+
+1.  **Parallel Race Election**: Upon startup, every instance scans the first 5 ports (5688-5692) concurrently (<300ms).
+2.  **Role Resolution**:
+    *   **Host**: If a port is free, the instance binds it and becomes the Host.
+    *   **Guest**: If a Host is found, the instance connects via SSE (Server-Sent Events) and becomes a Guest.
+3.  **Immediate Handshake**: The `StdioServerTransport` connects immediately (<10ms) to the IDE. Static requests (`tools/list`) are served locally, preventing IDE timeouts. Dynamic requests are **buffered** until the election concludes.
+
+### Failover & Resilience
+*   **Smart Proxy**: Guest instances proxy IDE requests to the Host via HTTP/SSE. They handle backpressure and buffering to prevent data loss during connection blips.
+*   **Auto-Failover**: If the Host process terminates (e.g., user closes the Host IDE window), Guest instances detect the connection loss (via `ECONNREFUSED` or SSE `end`) and trigger a **Re-Election**. One of the surviving Guests will promote itself to become the new Host, restoring the cluster automatically.

docs/ARCHITECTURE_zh.md

@@ -41,3 +41,18 @@ Nexus_Storage/
 **自我修复 (Self-healing)**: 核心数据文件（如 `registry.json`, `discussion.json`）具备自动检测与修复机制。如果文件损坏或意外丢失，系统会自动重建初始状态，确保服务不中断。
 
 **多并发安全 (Concurrency Safety)**: 对共享文件（`discussion.json`, `registry.json`）的所有写入操作均受 `AsyncMutex` 锁保护，防止多个 AI 代理同时通信时发生竞争条件。
+
+## 🌐 Host-Guest 网络架构 (v2)
+
+### 零配置启动与选举
+系统旨在提供“魔法般”的用户体验，同一台机器上的多个实例无需手动配置即可自动发现并组网。
+
+1.  **并行竞速选举**: 启动时，每个实例并发扫描前 5 个端口 (5688-5692) (<300ms)。
+2.  **角色解析**:
+    *   **Host**: 如果发现空闲端口，实例绑定该端口并成为 Host。
+    *   **Guest**: 如果发现已有 Host，实例通过 SSE (Server-Sent Events) 连接并成为 Guest。
+3.  **立即握手**: `StdioServerTransport` 对 IDE 的连接是立即完成的 (<10ms)。静态请求（如 `tools/list`）由本地直接响应，避免 IDE 超时；动态请求被**缓冲**，直到选举完成。
+
+### 故障转移与高可用
+*   **智能代理 (Smart Proxy)**: Guest 实例通过 HTTP/SSE 将 IDE 请求代理给 Host。它们处理背压和缓冲，防止网络抖动导致数据丢失。
+*   **自动故障转移**: 如果 Host 进程终止（例如用户关闭了 Host IDE 窗口），Guest 实例会检测到连接断开（通过 `ECONNREFUSED` 或 SSE `end`），并触发 **重新选举**。其中一个幸存的 Guest 将自动晋升为新的 Host，自动恢复集群服务。

docs/ASSISTANT_GUIDE.md

@@ -1,4 +1,4 @@
-# Nexus 助手协作指令 (v0.3.0)
+# Nexus Assistant Guide
 
 你现在是 **n2ns Nexus** 协作网络的一员。该系统集成了实时通信、结构化资产管理、**异步任务流 (Task Primitives)** 以及 **全局 Hub 架构 (v0.3.0)**，所有操作均落地在本地文件系统。
 

docs/CHANGELOG_zh.md

@@ -2,6 +2,19 @@
 
 本项目的所有重大变更都将记录在此文件中。
 
+## [0.4.0] - 2026-01-14
+### 🚀 高可用与高扩展 (High Availability & Scalability)
+- **Failover Mechanism**: 实现了自动的 Guest-to-Host 故障转移。如果 Host 进程意外退出，Guest 会检测到端口/锁释放并立即接管 Host 角色，同时保证数据持久性。
+- **Progressive Discovery**: 新增 `search_projects` 工具。允许 AI 根据意图搜索相关项目，而无需读取包含 1000+ 项目的完整注册表，大幅节省 Token。
+- **Immediate Handshake**: 实现了请求缓冲机制 (Request Buffering)，允许 Server 在 Host 选举 (~300ms) 完成前就立即接受 (<10ms) IDE 的请求，彻底解决了启动时的竞态条件。
+- **Stability**: 增加了针对进程故障转移 (`tests/failover.test.ts`) 和请求缓冲 (`tests/buffered_requests.test.ts`) 的端到端测试。
+
+## [0.3.9] - 2026-01-14
+### 🚀 故障切换与立即握手
+- **立即握手**: 实现了基于缓冲区的设计，Stdio 启动后 <10ms 内即可响应，不再阻塞 IDE 等待选举。
+- **自动故障切换**: 新增了 `Failover` 机制。如果 Host 进程被杀或崩溃，存活的 Guest 会在检测到连接断开后立即触发重新选举，并自动晋升为新 Host。
+- **零配置 V2**: 进一步优化了启动流程，完全无需用户干预即可组建高可用集群。
+
 ## [0.3.5] - 2026-01-10
 ### 协议与稳定性
 - **修复 (僵尸 Host)**: 实现了“智能重试”和“重新选举”逻辑。如果 Guest 反复连接到僵尸 Host（握手成功但 SSE 断开），现在会自动触发重新选举流程，将坏端口加入黑名单，并在必要时在从端口上将自身提升为 Host。

docs/README_zh.md

@@ -92,9 +92,9 @@
 ```
 
 - **零配置**: 只需运行 `npx @datafrog-io/n2n-nexus` — 无需 `--id` 或 `--host`。
-- **自动选举**: 首个实例绑定 5688 端口成为 Host；其余自动加入为 Guest。
-- **跨项目同步**: 所有 IDE 共享同一个 Hub，实现实时跨项目会议。
-- **热故障转移**: 若 Host 断开，Guest 将在 10 秒内自动升迁。
+- **立即握手**: Stdio 瞬间响应 (<10ms) 静态请求 (`tools/list`)，动态请求自动缓冲。
+- **并行选举**: 并发端口探测保证选举过程在 <300ms 完成。
+- **热故障转移**: 若 Host 断开，Guest 自动检测并选举成为新 Host，实现自动修复。
 
 ## 🚀 快速启动
 

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datafrog-io/n2n-nexus",
-    "version": "0.3.9",
+    "version": "0.4.0",
     "description": "Modular MCP Server for multi-AI assistant coordination",
     "main": "build/index.js",
     "type": "module",
@@ -41,6 +41,7 @@
         "start": "node build/index.js",
         "dev": "tsc -w",
         "test": "vitest run",
+        "test:integration": "vitest run tests/integration.test.ts tests/failover.test.ts tests/meeting.test.ts tests/guest_connection.test.ts",
         "lint": "eslint src/**",
         "prepublishOnly": "npm run build"
     },

src/constants.ts

@@ -17,7 +17,7 @@ export const PORT_RANGE_START = 5688;
 export const PORT_RANGE_END = 5800;
 
 // Timeouts (milliseconds)
-export const HANDSHAKE_TIMEOUT = 500;
+export const HANDSHAKE_TIMEOUT = 200;
 export const HEARTBEAT_INTERVAL = 30000;
 
 // Task cleanup