helixevo 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to HelixEvo are documented here.
 
+## [0.3.1] - 2026-03-23
+
+### Fixed
+- `helixevo dashboard` now recovers cleanly when the preferred port is occupied: it reuses a known managed dashboard if one is already running there, otherwise it falls forward to the next open port instead of failing with `EADDRINUSE`
+- Added `helixevo dashboard --port <port>` so operators can choose a preferred starting port while preserving automatic fallback behavior
+- Background dashboard stop/reuse logic now tracks the actual assigned port, so `helixevo dashboard --stop` works correctly even after fallback to a non-default port
+
 ## [0.3.0] - 2026-03-23
 
 ### Added

package/README.md

@@ -90,7 +90,7 @@ helixevo dashboard
 | `helixevo specialize --project <name>` | Create project-specific skills ↓ |
 | `helixevo graph` | View skill network in terminal |
 | `helixevo research` | Proactive web research for skill improvement |
-| `helixevo dashboard` | Open web dashboard at localhost:3847 |
+| `helixevo dashboard [--port <n>]` | Open web dashboard, preferring localhost:3847 and falling forward if occupied |
 | `helixevo status` | Show system health |
 | `helixevo report` | Generate evolution report |
 
@@ -149,7 +149,10 @@ The dashboard provides an interactive view of your skill ecosystem:
 
 ```bash
 helixevo dashboard
-# Opens http://localhost:3847
+# Prefers http://localhost:3847 and falls forward if that port is occupied
+
+helixevo dashboard --port 3900
+# Prefer port 3900 first
 ```
 
 **Tabs:**

package/dashboard/app/commands/page.tsx

@@ -242,21 +242,23 @@ const COMMANDS: CommandInfo[] = [
   },
   {
     name: 'dashboard',
-    description: 'Launch the web dashboard at http://localhost:3847. When a newer npm version is available, HelixEvo now auto-updates itself before opening the dashboard unless you opt out.',
+    description: 'Launch the web dashboard at http://localhost:3847 by default. When that port is occupied, HelixEvo now reuses a known managed dashboard or falls forward to the next open port instead of failing. When a newer npm version is available, HelixEvo also auto-updates itself before opening the dashboard unless you opt out.',
     usage: 'helixevo dashboard [options]',
     examples: [
-      { cmd: 'helixevo dashboard', desc: 'Auto-update to the latest version if needed, then open the dashboard' },
+      { cmd: 'helixevo dashboard', desc: 'Auto-update to the latest version if needed, then open the dashboard on 3847 or the next open port' },
       { cmd: 'helixevo dashboard --background', desc: 'Run the dashboard in the background after the same update check' },
+      { cmd: 'helixevo dashboard --port 3900', desc: 'Prefer port 3900 first, then fall forward if that port is occupied' },
       { cmd: 'helixevo dashboard --no-auto-update', desc: 'Open the dashboard immediately without checking npm for updates' },
     ],
     options: [
       { flag: '--background', desc: 'Run the dashboard detached from the terminal' },
-      { flag: '--stop', desc: 'Stop a background dashboard process' },
+      { flag: '--stop', desc: 'Stop a managed background dashboard process' },
+      { flag: '--port <port>', desc: 'Preferred port to try first (default: 3847)' },
       { flag: '--no-auto-update', desc: 'Skip the automatic update check before launch' },
     ],
     category: 'system',
     needsLLM: false,
-    note: 'You are currently using the dashboard. By default it now upgrades itself first when a newer release is available.',
+    note: 'You are currently using the dashboard. It now prefers 3847, reuses a known managed dashboard when one is already running there, and otherwise falls forward to the next open port.',
   },
 ]
 

package/dashboard/app/guide/page.tsx

@@ -395,8 +395,14 @@ helixevo graph
 # Open this dashboard
 helixevo dashboard
 
+# Prefer a different port if you want
+helixevo dashboard --port 3900
+
 # Check system health
 helixevo status`}</Code>
+            <p className="guide-text-sm">
+              The dashboard prefers port <code>3847</code>. If that port is already occupied, HelixEvo now reuses a known managed dashboard or falls forward to the next open port instead of failing immediately.
+            </p>
           </Step>
         </Section>
 
@@ -456,8 +462,8 @@ helixevo status`}</Code>
               },
               {
                 cmd: 'helixevo dashboard',
-                desc: 'Open the interactive web dashboard at localhost:3847. Before launch, HelixEvo checks npm for a newer version and auto-updates itself unless you opt out.',
-                flags: ['--background', '--stop', '--no-auto-update'],
+                desc: 'Open the interactive web dashboard. HelixEvo prefers localhost:3847, reuses a known managed dashboard if one is already there, and otherwise falls forward to the next open port. Before launch, it also checks npm for a newer version and auto-updates itself unless you opt out.',
+                flags: ['--background', '--stop', '--port <port>', '--no-auto-update'],
               },
               {
                 cmd: 'helixevo status',

package/dist/cli.js

@@ -12809,9 +12809,10 @@ ${replay.slice(0, 800)}`
 // src/commands/dashboard.ts
 import { execSync as execSync2, spawn as spawn2 } from "node:child_process";
 import { join as join17, dirname as dirname3 } from "node:path";
-import { existsSync as existsSync11, cpSync as cpSync3, mkdirSync as mkdirSync5, readdirSync as readdirSync3, readFileSync as readFileSync9, rmSync as rmSync2, writeFileSync as writeFileSync10 } from "node:fs";
+import { existsSync as existsSync11, cpSync as cpSync3, mkdirSync as mkdirSync5, openSync, readdirSync as readdirSync3, readFileSync as readFileSync9, rmSync as rmSync2, writeFileSync as writeFileSync10 } from "node:fs";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { homedir as homedir4 } from "node:os";
+import { createServer } from "node:net";
 init_skills();
 init_data();
 
@@ -12920,11 +12921,23 @@ function printUpdateBanner(currentVersion, latestVersion) {
 
 // src/commands/dashboard.ts
 var __filename = "/Users/tianchichen/Documents/GitHub/helixevo/src/commands/dashboard.ts";
-var HELIX_DASHBOARD_DIR = join17(homedir4(), ".helix", "dashboard");
+var HELIX_HOME_DIR = join17(homedir4(), ".helix");
+var HELIX_DASHBOARD_DIR = join17(HELIX_HOME_DIR, "dashboard");
+var DASHBOARD_LOG_FILE = join17(HELIX_HOME_DIR, "dashboard.log");
+var DASHBOARD_PID_FILE = join17(HELIX_HOME_DIR, "dashboard.pid");
+var DASHBOARD_STATE_FILE = join17(HELIX_HOME_DIR, "dashboard-state.json");
 var DASHBOARD_SKIP_AUTO_UPDATE_ENV = "HELIXEVO_DASHBOARD_SKIP_AUTO_UPDATE";
+var DEFAULT_DASHBOARD_PORT = 3847;
+var MAX_PORT_SCAN_ATTEMPTS = 25;
+var RESTART_EXIT_CODE = 75;
 async function dashboardCommand(options) {
+  if (options.stop) {
+    stopDashboard();
+    return;
+  }
+  const preferredPort = parseDashboardPort(options.port);
   if (options.autoUpdate !== false && process.env[DASHBOARD_SKIP_AUTO_UPDATE_ENV] !== "1" && !findDevDashboard()) {
-    const didRelaunch = await maybeAutoUpdateAndRelaunch(options);
+    const didRelaunch = await maybeAutoUpdateAndRelaunch({ ...options, port: preferredPort });
     if (didRelaunch)
       return;
   }
@@ -12934,14 +12947,14 @@ async function dashboardCommand(options) {
 `);
     console.error("  You can install and run it manually:");
     console.error("    git clone https://github.com/danielchen26/helixevo.git");
-    console.error("    cd helixevo/dashboard && npm install && npx next dev --port 3847");
+    console.error(`    cd helixevo/dashboard && npm install && npx next dev --port ${preferredPort}`);
     process.exit(1);
   }
   if (!existsSync11(join17(dir, "node_modules"))) {
     console.log("  Installing dashboard dependencies...");
     try {
       execSync2("npm install --no-audit --no-fund", { cwd: dir, stdio: "inherit" });
-    } catch (err) {
+    } catch {
       console.error("  Failed to install dashboard dependencies.");
       console.error("  Try running manually:");
       console.error(`    cd ${dir} && npm install`);
@@ -12949,43 +12962,39 @@ async function dashboardCommand(options) {
     }
   }
   ensureSkillGraph();
-  if (options.background) {
-    const logFile = join17(homedir4(), ".helix", "dashboard.log");
-    const out = __require("fs").openSync(logFile, "a");
-    const err = __require("fs").openSync(logFile, "a");
-    let currentVersion2 = VERSION;
-    try {
-      currentVersion2 = execSync2("helixevo --version 2>/dev/null", { encoding: "utf-8" }).trim() || VERSION;
-    } catch {}
-    const child = spawn2("npx", ["next", "dev", "--port", "3847"], {
-      cwd: dir,
-      stdio: ["ignore", out, err],
-      env: { ...process.env, HELIXEVO_VERSION: currentVersion2 },
-      detached: true
-    });
-    child.unref();
-    writeFileSync10(join17(homedir4(), ".helix", "dashboard.pid"), String(child.pid));
-    console.log(`  \uD83C\uDF10 HelixEvo Dashboard v${currentVersion2} running in background`);
-    console.log(`     http://localhost:3847`);
-    console.log(`     Logs: ${logFile}`);
-    console.log(`     Stop: helixevo dashboard --stop
+  let target;
+  try {
+    target = await resolveLaunchTarget(preferredPort);
+  } catch (error) {
+    console.error(`  ${error.message}`);
+    process.exit(1);
+  }
+  const currentVersion = readCurrentVersion();
+  if (target.source === "existing" && target.state) {
+    const url = getDashboardUrl(target.state.port);
+    console.log(`  ✓ HelixEvo Dashboard is already running at ${url}`);
+    if (options.background) {
+      console.log(`     Logs: ${DASHBOARD_LOG_FILE}`);
+      console.log(`     Stop: helixevo dashboard --stop
 `);
-    setTimeout(() => {
-      try {
-        const platform = process.platform;
-        const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
-        execSync2(`${cmd} http://localhost:3847`, { stdio: "ignore" });
-      } catch {}
-    }, 2000);
-    process.exit(0);
+    } else {
+      console.log("");
+    }
+    openDashboardUrl(target.state.port);
+    return;
   }
-  let currentVersion = VERSION;
-  try {
-    currentVersion = execSync2("helixevo --version 2>/dev/null", { encoding: "utf-8" }).trim() || VERSION;
-  } catch {}
-  console.log(`  \uD83C\uDF10 Starting HelixEvo Dashboard v${currentVersion} at http://localhost:3847
+  if (target.source === "fallback") {
+    console.log(`  Port ${preferredPort} is already in use.`);
+    console.log(`  Falling forward to ${getDashboardUrl(target.port)} instead.
 `);
-  launchDashboard(dir, true);
+  }
+  if (options.background) {
+    launchBackgroundDashboard(dir, target.port, currentVersion);
+    return;
+  }
+  console.log(`  \uD83C\uDF10 Starting HelixEvo Dashboard v${currentVersion} at ${getDashboardUrl(target.port)}
+`);
+  launchDashboard(dir, true, target.port);
 }
 async function maybeAutoUpdateAndRelaunch(options) {
   const update = await getUpdateInfo(VERSION);
@@ -13015,7 +13024,9 @@ async function maybeAutoUpdateAndRelaunch(options) {
     args.push("--background");
   if (options.autoUpdate === false)
     args.push("--no-auto-update");
-  await new Promise((resolve, reject) => {
+  if (options.port !== undefined)
+    args.push("--port", String(options.port));
+  await new Promise((_resolve, reject) => {
     const child = spawn2(executable, args, {
       stdio: "inherit",
       env: { ...process.env, [DASHBOARD_SKIP_AUTO_UPDATE_ENV]: "1" }
@@ -13027,30 +13038,49 @@ async function maybeAutoUpdateAndRelaunch(options) {
   });
   return true;
 }
-var RESTART_EXIT_CODE = 75;
-function launchDashboard(dir, openBrowser) {
-  let currentVersion = VERSION;
-  try {
-    currentVersion = execSync2("helixevo --version 2>/dev/null", { encoding: "utf-8" }).trim() || VERSION;
-  } catch {}
-  const child = spawn2("npx", ["next", "dev", "--port", "3847"], {
+function launchBackgroundDashboard(dir, port, version) {
+  mkdirSync5(HELIX_HOME_DIR, { recursive: true });
+  const out = openSync(DASHBOARD_LOG_FILE, "a");
+  const err = openSync(DASHBOARD_LOG_FILE, "a");
+  const child = spawn2("npx", ["next", "dev", "--port", String(port)], {
+    cwd: dir,
+    stdio: ["ignore", out, err],
+    env: { ...process.env, HELIXEVO_VERSION: version },
+    detached: true
+  });
+  child.unref();
+  writeDashboardState({
+    pid: child.pid ?? -1,
+    port,
+    version,
+    startedAt: new Date().toISOString()
+  });
+  console.log(`  \uD83C\uDF10 HelixEvo Dashboard v${version} running in background`);
+  console.log(`     ${getDashboardUrl(port)}`);
+  console.log(`     Logs: ${DASHBOARD_LOG_FILE}`);
+  console.log(`     Stop: helixevo dashboard --stop
+`);
+  setTimeout(() => {
+    openDashboardUrl(port);
+  }, 2000);
+  process.exit(0);
+}
+function launchDashboard(dir, openBrowser, port) {
+  const currentVersion = readCurrentVersion();
+  const child = spawn2("npx", ["next", "dev", "--port", String(port)], {
     cwd: dir,
     stdio: "inherit",
     env: { ...process.env, HELIXEVO_VERSION: currentVersion }
   });
   if (openBrowser) {
     setTimeout(() => {
-      try {
-        const platform = process.platform;
-        const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
-        execSync2(`${cmd} http://localhost:3847`, { stdio: "ignore" });
-      } catch {}
+      openDashboardUrl(port);
     }, 3000);
   }
   child.on("close", (code) => {
     if (code === RESTART_EXIT_CODE) {
       console.log(`
-  \uD83D\uDD04 Restarting dashboard after update...
+  \uD83D\uDD04 Restarting dashboard after update on ${getDashboardUrl(port)}...
 `);
       setTimeout(() => {
         const nextCache = join17(dir, ".next");
@@ -13060,19 +13090,138 @@ function launchDashboard(dir, openBrowser) {
           } catch {}
         }
         ensureSkillGraph();
-        let updatedVersion = currentVersion;
-        try {
-          updatedVersion = execSync2("helixevo --version 2>/dev/null", { encoding: "utf-8" }).trim() || currentVersion;
-        } catch {}
-        console.log(`  \uD83C\uDF10 HelixEvo Dashboard v${updatedVersion} at http://localhost:3847
+        const updatedVersion = readCurrentVersion(currentVersion);
+        console.log(`  \uD83C\uDF10 HelixEvo Dashboard v${updatedVersion} at ${getDashboardUrl(port)}
 `);
-        launchDashboard(dir, false);
+        launchDashboard(dir, false, port);
       }, 2000);
     } else {
       process.exit(code ?? 0);
     }
   });
 }
+async function resolveLaunchTarget(preferredPort) {
+  const existingState = readDashboardState();
+  if (existingState && existingState.port === preferredPort) {
+    return { port: preferredPort, source: "existing", state: existingState };
+  }
+  if (await isPortAvailable(preferredPort)) {
+    return { port: preferredPort, source: "preferred" };
+  }
+  const fallbackPort = await findAvailablePort(preferredPort + 1);
+  return { port: fallbackPort, source: "fallback" };
+}
+function stopDashboard() {
+  const state = readDashboardState();
+  if (!state) {
+    console.log("  No background dashboard running.");
+    return;
+  }
+  try {
+    process.kill(state.pid, "SIGTERM");
+  } catch {}
+  clearDashboardState();
+  console.log(`  Dashboard stopped (${getDashboardUrl(state.port)}).`);
+}
+function parseDashboardPort(port) {
+  if (port === undefined)
+    return DEFAULT_DASHBOARD_PORT;
+  const parsed = typeof port === "number" ? port : Number.parseInt(String(port), 10);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+    console.error(`  Invalid dashboard port: ${port}`);
+    process.exit(1);
+  }
+  return parsed;
+}
+function readCurrentVersion(fallback = VERSION) {
+  try {
+    return execSync2("helixevo --version 2>/dev/null", { encoding: "utf-8" }).trim() || fallback;
+  } catch {
+    return fallback;
+  }
+}
+function getDashboardUrl(port) {
+  return `http://localhost:${port}`;
+}
+function openDashboardUrl(port) {
+  try {
+    const platform = process.platform;
+    const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
+    execSync2(`${cmd} ${getDashboardUrl(port)}`, { stdio: "ignore" });
+  } catch {}
+}
+function writeDashboardState(state) {
+  mkdirSync5(HELIX_HOME_DIR, { recursive: true });
+  writeFileSync10(DASHBOARD_PID_FILE, String(state.pid));
+  writeFileSync10(DASHBOARD_STATE_FILE, JSON.stringify(state, null, 2));
+}
+function readDashboardState() {
+  let state = null;
+  if (existsSync11(DASHBOARD_STATE_FILE)) {
+    try {
+      const parsed = JSON.parse(readFileSync9(DASHBOARD_STATE_FILE, "utf-8"));
+      if (Number.isInteger(parsed.pid) && Number.isInteger(parsed.port)) {
+        state = parsed;
+      }
+    } catch {}
+  }
+  if (!state && existsSync11(DASHBOARD_PID_FILE)) {
+    try {
+      const pid = Number.parseInt(readFileSync9(DASHBOARD_PID_FILE, "utf-8").trim(), 10);
+      if (Number.isInteger(pid)) {
+        state = {
+          pid,
+          port: DEFAULT_DASHBOARD_PORT,
+          version: VERSION,
+          startedAt: ""
+        };
+      }
+    } catch {}
+  }
+  if (!state)
+    return null;
+  if (state.pid <= 0 || !isProcessAlive(state.pid)) {
+    clearDashboardState();
+    return null;
+  }
+  return state;
+}
+function clearDashboardState() {
+  try {
+    rmSync2(DASHBOARD_PID_FILE, { force: true });
+  } catch {}
+  try {
+    rmSync2(DASHBOARD_STATE_FILE, { force: true });
+  } catch {}
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function isPortAvailable(port) {
+  return await new Promise((resolve) => {
+    const server = createServer();
+    server.unref();
+    server.once("error", () => {
+      resolve(false);
+    });
+    server.listen(port, () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+async function findAvailablePort(startPort) {
+  for (let attempt = 0;attempt < MAX_PORT_SCAN_ATTEMPTS; attempt += 1) {
+    const candidate = startPort + attempt;
+    if (await isPortAvailable(candidate))
+      return candidate;
+  }
+  throw new Error(`Unable to find an open dashboard port after checking ${MAX_PORT_SCAN_ATTEMPTS} ports starting at ${startPort}.`);
+}
 function prepareDashboard() {
   const devDir = findDevDashboard();
   if (devDir)
@@ -14007,9 +14156,6 @@ async function projectSetupCommand(projectPath, options) {
 }
 
 // src/cli.ts
-import { join as join21 } from "node:path";
-import { homedir as homedir6 } from "node:os";
-import { existsSync as existsSync16, readFileSync as readFileSync13, rmSync as rmSync3 } from "node:fs";
 var program2 = new Command;
 program2.name("helixevo").description("Self-evolving skill ecosystem for AI agents").version(VERSION).addHelpText("after", `
 Examples:
@@ -14037,21 +14183,7 @@ program2.command("generalize").description("Promote cross-skill patterns to high
 program2.command("specialize").description("Create project-specific skills ↓ --project <name> [--dry-run] [--verbose]").requiredOption("--project <name>", "Project name").option("--dry-run", "Show candidates without applying").option("--verbose", "Show detailed analysis").action(specializeCommand);
 program2.command("graph").description("Skill network [--mermaid] [--obsidian <path>] [--rebuild] [--optimize]").option("--mermaid", "Render as Mermaid diagram in browser").option("--rebuild", "Force rebuild (re-infer relationships via LLM)").option("--obsidian <path>", "Sync to Obsidian vault at path").option("--optimize", "Run network optimization (merge/split/conflict detection)").option("--verbose", "Show detailed analysis").action(graphCommand);
 program2.command("research").description("Proactive research via web [--project <path>] [--dry-run] [--verbose]").option("--project <path>", "Project path for goal extraction").option("--dry-run", "Show discoveries without creating skills").option("--verbose", "Show detailed research steps").option("--max-hypotheses <n>", "Max hypotheses to test", "3").action(researchCommand);
-program2.command("dashboard").description("Open web dashboard at http://localhost:3847").option("--background", "Run in background (detach from terminal)").option("--stop", "Stop a background dashboard").option("--no-auto-update", "Skip automatic update check before launching the dashboard").action(async (options) => {
-  if (options.stop) {
-    const pidFile = join21(homedir6(), ".helix", "dashboard.pid");
-    if (existsSync16(pidFile)) {
-      const pid = parseInt(readFileSync13(pidFile, "utf-8").trim());
-      try {
-        process.kill(pid, "SIGTERM");
-      } catch {}
-      rmSync3(pidFile);
-      console.log("  Dashboard stopped.");
-    } else {
-      console.log("  No background dashboard running.");
-    }
-    return;
-  }
+program2.command("dashboard").description("Open web dashboard (default: http://localhost:3847, falls forward if occupied)").option("--background", "Run in background (detach from terminal)").option("--stop", "Stop a background dashboard").option("--port <port>", "Preferred port to try first (default: 3847)").option("--no-auto-update", "Skip automatic update check before launching the dashboard").action(async (options) => {
   await dashboardCommand(options);
 });
 program2.command("status").description("Show frontier, skills, failures, and network health").action(statusCommand);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helixevo",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Co-evolving skill and project brain for AI agents, with ontology-aware learning, pressure modeling, and a premium dashboard.",
   "type": "module",
   "bin": {