crewswarm 0.9.4 → 0.9.5

package/.env.example

@@ -159,7 +159,14 @@
 # ── Ports ─────────────────────────────────────────────────────────────────────
 # CREW_LEAD_PORT=5010        # crew-lead HTTP API
 # SWARM_DASH_PORT=4319       # Dashboard web UI
-# WA_HTTP_PORT=3000          # WhatsApp bridge HTTP
+# WA_HTTP_PORT=5015          # WhatsApp bridge HTTP
+# STUDIO_PORT=3333           # Vibe IDE
+
+# ── Runtime & Config ──────────────────────────────────────────────────────────
+# CREWSWARM_DIR=$HOME/.crewswarm          # Override config directory
+# CREWSWARM_RT_AUTH_TOKEN=               # RT bus auth token (auto-generated by install.sh)
+# CREWSWARM_MAX_BRIDGES=10               # Max concurrent agent bridge processes
+# CREWSWARM_BIND_HOST=127.0.0.1          # Host to bind all services to (use 0.0.0.0 for remote access)
 
 # ── Execution Engines ─────────────────────────────────────────────────────────
 # CREWSWARM_OPENCODE_ENABLED=off              # Route coding agents through OpenCode

package/README.md

@@ -9,7 +9,7 @@
 [![Website](https://img.shields.io/badge/website-crewswarm.ai-blue)](https://crewswarm.ai)
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/crewswarm?label=Sponsor)](https://github.com/sponsors/crewswarm)
 
-![crewswarm Dashboard](website/dashboard-agents.webp)
+![crewswarm Demo](website/crewswarm-demo.gif)
 
 ---
 
@@ -168,11 +168,11 @@ Or skip API keys entirely — use Claude Code, Cursor, or Gemini CLI with OAuth
 ## Commands
 
 ```bash
-crewswarm                    # Start all services
+crewswarm                    # Start full stack: RT bus, crew-lead, bridges, then dashboard
 crewswarm pm-loop            # Run autonomous PM loop
 npm run doctor               # Preflight check
 npm run restart-all          # Restart the stack
-npm test                     # 2,500+ tests, 100% passing
+npm test                     # 4,530 tests, 100% passing
 npm run test:report          # View test results summary
 crew exec "Build X"          # Send task via CLI
 ```

package/apps/dashboard/README.md

@@ -0,0 +1,49 @@
+# crewswarm-dashboard
+
+Real-time control panel for CrewSwarm. Vanilla JS + Vite, no framework dependencies.
+
+## Development
+
+```bash
+cd apps/dashboard
+npm install
+npm run dev        # http://localhost:5173
+```
+
+## Build
+
+```bash
+npm run build      # outputs to dist/
+npm run preview    # preview production build
+```
+
+## Structure
+
+```
+src/
+  app.js              # Main app entry, tab routing, SSE connections
+  styles.css          # Global styles (dark theme)
+  chat/               # Chat tab (crew-lead conversation)
+  tabs/               # Tab modules (Build, Swarm, Agents, Engines, etc.)
+  components/         # Shared UI components
+  core/               # Core utilities (SSE, state, API client)
+  cli-process.js      # CLI Process tab
+  setup-wizard.js     # First-run setup wizard
+  orchestration-status.js  # Pipeline status display
+```
+
+## Key tabs
+
+- **Chat** -- Talk to crew-lead, dispatch tasks
+- **Build** -- One-click build from a requirement
+- **Swarm** -- Active sessions and agent activity
+- **Agents** -- Configure sub-agents, models, permissions
+- **Engines** -- Manage CLI engines (Claude Code, Codex, Gemini, Cursor)
+- **RT Messages** -- Live message bus inspector
+- **Services** -- Health status of all services
+
+## Notes
+
+- Connects to crew-lead at `http://localhost:5010` by default
+- All state comes from SSE streams and REST API -- no local state management
+- Brotli-compressed `.br` files are pre-built for production serving

package/apps/dashboard/dist/index.html

@@ -5582,6 +5582,8 @@
         <div id="testingContent">
           <div class="meta" style="padding: 20px">Loading test results...</div>
         </div>
+        <div id="testingChart"></div>
+        <div id="testingCoverage"></div>
         <div id="testingHistory"></div>
       </div>
 

package/install.sh

@@ -121,7 +121,7 @@ if [[ ! -f "$CONFIG_FILE" ]]; then
   }
 }
 EOF
-  success "Created ~/.crewswarm/crewswarm.json  (RT token: $RT_TOKEN)"
+  success "Created ~/.crewswarm/config.json  (RT token: $RT_TOKEN)"
 else
   success "~/.crewswarm/crewswarm.json already exists — keeping it"
 fi
@@ -307,7 +307,7 @@ elif [[ "$SHELL" == *"bash"* ]]; then
   SHELL_RC="$HOME/.bash_profile"
 fi
 
-BIN_ALIAS="alias crew-cli='node $REPO_DIR/crew-cli.mjs'"
+BIN_ALIAS="alias crew-cli='node $REPO_DIR/crew-cli/dist/crew.mjs'"
 if [[ -n "$SHELL_RC" ]] && ! grep -q "crew-cli" "$SHELL_RC" 2>/dev/null; then
   echo "" >> "$SHELL_RC"
   echo "# CrewSwarm" >> "$SHELL_RC"

package/lib/crew-lead/wave-dispatcher.mjs

@@ -13,6 +13,12 @@ import { normalizeProjectDir } from "../runtime/project-dir.mjs";
 import { loadProjectMessages } from "../chat/project-messages.mjs";
 import * as tmuxBridge from "../bridges/tmux-bridge.mjs";
 import * as sessionManager from "../sessions/session-manager.mjs";
+import {
+  isGitRepo,
+  createWorktree,
+  mergeWorktree,
+  cleanupPipelineWorktrees,
+} from "./worktree.mjs";
 
 let _deps = {};
 
@@ -295,6 +301,12 @@ export function cancelAllPipelines(sessionId) {
     console.log(`[crew-lead] Cancelling pipeline ${pid} (${waveInfo}, ${pipeline.pendingTaskIds.size} pending tasks)`);
     _deps.broadcastSSE?.({ type: "pipeline_cancelled", pipelineId: pid, ts: Date.now() });
     deletePipelineState(pid);
+    // Clean up any active worktrees for this pipeline.
+    if (pipeline.projectDir) {
+      try { cleanupPipelineWorktrees(pipeline.projectDir, pid); } catch (e) {
+        console.warn(`[worktree] cleanup on cancel failed for ${pid}: ${e.message}`);
+      }
+    }
     cancelled++;
   }
   pendingPipelines.clear();
@@ -425,12 +437,50 @@ export function dispatchPipelineWave(pipelineId) {
   }
 
   // ── Standard path (individual dispatch per agent) ───────────────────────
+
+  // ── Worktree isolation (multi-agent waves only) ──────────────────────────
+  // When CREWSWARM_WORKTREE_ISOLATION is not "false" (default: enabled for
+  // multi-agent waves) AND the pipeline has a projectDir that is a git repo,
+  // create an isolated worktree for each agent so parallel file writes don't
+  // conflict.  Single-agent waves skip worktree overhead by default.
+  const worktreeEnabled = (() => {
+    const envVal = process.env.CREWSWARM_WORKTREE_ISOLATION;
+    if (envVal === "false" || envVal === "0") return false;
+    // Per-pipeline spec can also disable it.
+    if (pipeline.worktreeIsolation === false) return false;
+    return waveSteps.length > 1;
+  })();
+
+  if (!pipeline.worktrees) pipeline.worktrees = new Map();
+
+  if (worktreeEnabled && pipeline.projectDir) {
+    let repoConfirmed = false;
+    try { repoConfirmed = isGitRepo(pipeline.projectDir); } catch {}
+
+    if (repoConfirmed) {
+      console.log(`[worktree] pipeline ${pipelineId.slice(0, 8)} wave ${currentWave + 1}: creating worktrees for ${waveSteps.length} agent(s)`);
+      for (const step of waveSteps) {
+        const agentId = step.agent;
+        const wtPath = createWorktree(pipeline.projectDir, pipelineId, currentWave, agentId);
+        if (wtPath) {
+          pipeline.worktrees.set(agentId, { path: wtPath, waveIndex: currentWave });
+        }
+      }
+    }
+  }
+
   for (const step of waveSteps) {
+    // Use per-agent worktree path if one was created, otherwise use the shared projectDir.
+    const agentWorktree = pipeline.worktrees?.get(step.agent);
+    const effectiveProjectDir = agentWorktree?.waveIndex === currentWave
+      ? agentWorktree.path
+      : pipeline.projectDir;
+
     let taskText = projectRootBanner + step.task + contextBlock;
     // QA always writes to projectDir/qa-report.md so reports aren't random filenames
     const isQa = step.agent === "crew-qa" || (step.agent && step.agent.includes("qa"));
-    if (isQa && pipeline.projectDir && !/qa-report\.md|Write your report to/i.test(taskText)) {
-      taskText += `\n\nWrite your report to ${pipeline.projectDir}/qa-report.md (no other filename).`;
+    if (isQa && effectiveProjectDir && !/qa-report\.md|Write your report to/i.test(taskText)) {
+      taskText += `\n\nWrite your report to ${effectiveProjectDir}/qa-report.md (no other filename).`;
     }
     const stepSpec = {
       task: taskText,
@@ -445,7 +495,7 @@ export function dispatchPipelineWave(pipelineId) {
     const taskId = dispatchTask(step.agent, stepSpec, sessionId, {
       pipelineId,
       waveIndex: currentWave,
-      projectDir: pipeline.projectDir,
+      projectDir: effectiveProjectDir,
       originProjectId: pipeline.originProjectId,
       originChannel: pipeline.originChannel,
       originThreadId: pipeline.originThreadId,

package/lib/crew-lead/worktree.mjs

@@ -0,0 +1,258 @@
+/**
+ * Git worktree isolation helpers for parallel wave dispatch.
+ * Each agent in a multi-agent wave gets its own git worktree so they can't
+ * conflict with each other on the filesystem.
+ *
+ * All operations are wrapped in try/catch — if git fails, callers fall back
+ * to the shared directory.
+ */
+
+import { execSync } from "node:child_process";
+import path from "node:path";
+import fs from "node:fs";
+
+// ── Naming helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Return the deterministic worktree path for an agent in a pipeline wave.
+ * Format: /tmp/crewswarm-wt-{pipelineId.slice(0,8)}-{agentId}
+ */
+export function worktreePath(pipelineId, agentId) {
+  return `/tmp/crewswarm-wt-${pipelineId.slice(0, 8)}-${agentId}`;
+}
+
+/**
+ * Return the deterministic branch name for an agent in a pipeline wave.
+ * Format: crewswarm/wave-{pipelineId.slice(0,8)}-{agentId}
+ */
+export function worktreeBranch(pipelineId, agentId) {
+  return `crewswarm/wave-${pipelineId.slice(0, 8)}-${agentId}`;
+}
+
+// ── Core helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Check if a directory is inside a git repository.
+ * Returns true if git reports it is inside a work tree, false otherwise.
+ */
+export function isGitRepo(dir) {
+  try {
+    const result = execSync("git rev-parse --is-inside-work-tree", {
+      cwd: dir,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5000,
+    }).trim();
+    return result === "true";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create a git worktree for an agent's wave task.
+ *
+ * @param {string} projectDir - The shared project directory (must be a git repo).
+ * @param {string} pipelineId - The pipeline ID (used for naming).
+ * @param {number} waveIndex  - The zero-based wave index (informational, used in logs).
+ * @param {string} agentId    - The agent ID (used for naming).
+ * @returns {string|null} The worktree path, or null if git isn't available or
+ *                        projectDir isn't a git repo.
+ */
+export function createWorktree(projectDir, pipelineId, waveIndex, agentId) {
+  try {
+    if (!projectDir || !isGitRepo(projectDir)) {
+      console.log(`[worktree] ${agentId}: projectDir is not a git repo — skipping worktree`);
+      return null;
+    }
+
+    const wtPath = worktreePath(pipelineId, agentId);
+    const branch = worktreeBranch(pipelineId, agentId);
+
+    // Remove stale worktree at the same path if it exists (e.g. crashed previous run).
+    if (fs.existsSync(wtPath)) {
+      console.log(`[worktree] ${agentId}: stale worktree found at ${wtPath} — removing`);
+      try {
+        execSync(`git worktree remove --force "${wtPath}"`, {
+          cwd: projectDir, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"], timeout: 10000,
+        });
+      } catch {
+        // If git worktree remove fails, try cleaning up the directory directly.
+        try { fs.rmSync(wtPath, { recursive: true, force: true }); } catch {}
+      }
+      // Also delete the branch if it was left dangling.
+      try {
+        execSync(`git branch -D "${branch}"`, {
+          cwd: projectDir, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"], timeout: 5000,
+        });
+      } catch {}
+    }
+
+    // Create the worktree on a new branch forked from the current HEAD.
+    execSync(`git worktree add -b "${branch}" "${wtPath}" HEAD`, {
+      cwd: projectDir,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 15000,
+    });
+
+    console.log(`[worktree] wave ${waveIndex + 1} ${agentId}: created worktree at ${wtPath} (branch: ${branch})`);
+    return wtPath;
+  } catch (e) {
+    console.error(`[worktree] ${agentId}: failed to create worktree — ${e.message}`);
+    return null;
+  }
+}
+
+/**
+ * Merge a worktree branch back into the current branch (usually main/HEAD) and
+ * clean up the worktree + branch.
+ *
+ * @param {string} projectDir - The shared project directory.
+ * @param {string} pipelineId - The pipeline ID.
+ * @param {number} waveIndex  - The zero-based wave index (informational).
+ * @param {string} agentId    - The agent ID.
+ * @returns {{ ok: boolean, conflicts?: string[], merged_files?: string[] }}
+ */
+export function mergeWorktree(projectDir, pipelineId, waveIndex, agentId) {
+  const wtPath = worktreePath(pipelineId, agentId);
+  const branch = worktreeBranch(pipelineId, agentId);
+
+  // If the worktree path doesn't even exist, nothing to do.
+  if (!fs.existsSync(wtPath)) {
+    console.log(`[worktree] ${agentId}: worktree at ${wtPath} not found — skipping merge`);
+    return { ok: true, merged_files: [] };
+  }
+
+  try {
+    // Collect files that changed in the worktree branch vs the shared repo HEAD
+    // so we can report them even if the merge is a no-op.
+    let mergedFiles = [];
+    try {
+      const diffOutput = execSync(`git diff --name-only HEAD "${branch}"`, {
+        cwd: projectDir,
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 10000,
+      }).trim();
+      mergedFiles = diffOutput ? diffOutput.split("\n").filter(Boolean) : [];
+    } catch {}
+
+    // Perform the merge (--no-ff to keep history readable).
+    execSync(`git merge --no-ff -m "crewswarm: merge wave ${waveIndex + 1} ${agentId}" "${branch}"`, {
+      cwd: projectDir,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 30000,
+    });
+
+    console.log(`[worktree] wave ${waveIndex + 1} ${agentId}: merged ${mergedFiles.length} file(s) from ${branch}`);
+    _cleanupWorktree(projectDir, wtPath, branch);
+    return { ok: true, merged_files: mergedFiles };
+  } catch (e) {
+    // Check if it's a merge conflict.
+    const isConflict = /CONFLICT|Automatic merge failed/i.test(e.message || "");
+    if (isConflict) {
+      // Collect conflict file names.
+      let conflicts = [];
+      try {
+        const conflictOutput = execSync("git diff --name-only --diff-filter=U", {
+          cwd: projectDir,
+          encoding: "utf8",
+          stdio: ["pipe", "pipe", "pipe"],
+          timeout: 5000,
+        }).trim();
+        conflicts = conflictOutput ? conflictOutput.split("\n").filter(Boolean) : [];
+      } catch {}
+
+      // Abort the merge so the repo stays clean.
+      try {
+        execSync("git merge --abort", {
+          cwd: projectDir,
+          encoding: "utf8",
+          stdio: ["pipe", "pipe", "pipe"],
+          timeout: 10000,
+        });
+      } catch {}
+
+      console.error(`[worktree] wave ${waveIndex + 1} ${agentId}: merge conflicts in ${conflicts.length} file(s): ${conflicts.join(", ")}`);
+      _cleanupWorktree(projectDir, wtPath, branch);
+      return { ok: false, conflicts };
+    }
+
+    // Other error — still attempt cleanup.
+    console.error(`[worktree] ${agentId}: merge failed — ${e.message}`);
+    _cleanupWorktree(projectDir, wtPath, branch);
+    return { ok: false, conflicts: [] };
+  }
+}
+
+/**
+ * Clean up all worktrees for a pipeline (called on pipeline completion or cancellation).
+ *
+ * @param {string} projectDir - The shared project directory.
+ * @param {string} pipelineId - The pipeline ID whose worktrees should be removed.
+ */
+export function cleanupPipelineWorktrees(projectDir, pipelineId) {
+  const prefix = `/tmp/crewswarm-wt-${pipelineId.slice(0, 8)}-`;
+  const branchPrefix = `crewswarm/wave-${pipelineId.slice(0, 8)}-`;
+
+  // Find all matching worktree paths under /tmp.
+  let wtDirs = [];
+  try {
+    wtDirs = fs.readdirSync("/tmp")
+      .filter(name => name.startsWith(`crewswarm-wt-${pipelineId.slice(0, 8)}-`))
+      .map(name => path.join("/tmp", name));
+  } catch {}
+
+  for (const wtPath of wtDirs) {
+    // Derive the agentId from the path suffix after the pipeline prefix.
+    const agentId = wtPath.slice(prefix.length);
+    const branch = `${branchPrefix}${agentId}`;
+    _cleanupWorktree(projectDir, wtPath, branch);
+  }
+
+  if (wtDirs.length > 0) {
+    console.log(`[worktree] pipeline ${pipelineId.slice(0, 8)}: cleaned up ${wtDirs.length} worktree(s)`);
+  }
+}
+
+// ── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Remove a worktree directory and delete its tracking branch.
+ * Silently ignores errors so callers always continue.
+ */
+function _cleanupWorktree(projectDir, wtPath, branch) {
+  // git worktree remove
+  if (fs.existsSync(wtPath)) {
+    try {
+      execSync(`git worktree remove --force "${wtPath}"`, {
+        cwd: projectDir,
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 10000,
+      });
+      console.log(`[worktree] removed worktree at ${wtPath}`);
+    } catch (e) {
+      // Last resort: rm -rf the directory.
+      console.warn(`[worktree] git worktree remove failed for ${wtPath} — ${e.message}; falling back to rm`);
+      try { fs.rmSync(wtPath, { recursive: true, force: true }); } catch {}
+    }
+  }
+
+  // Delete the branch.
+  if (projectDir && branch) {
+    try {
+      execSync(`git branch -D "${branch}"`, {
+        cwd: projectDir,
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 5000,
+      });
+      console.log(`[worktree] deleted branch ${branch}`);
+    } catch {
+      // Branch may already be gone — that's fine.
+    }
+  }
+}

package/lib/crew-lead/ws-router.mjs

@@ -3,6 +3,7 @@ import path from "node:path";
 import os from "node:os";
 import fs from "node:fs";
 import { applyProjectDirToPipelineSteps } from "../dispatch/parsers.mjs";
+import { mergeWorktree } from "./worktree.mjs";
 
 let reconnectTimer = null;
 let isConnecting = false;
@@ -482,6 +483,48 @@ export function initWsRouter(deps) {
                             if (pipeline.pendingTaskIds.size === 0) {
                                 if (!pipeline.completedWaveResults) pipeline.completedWaveResults = [];
                                 pipeline.completedWaveResults.push([...pipeline.waveResults]);
+
+                                // ── Merge worktrees back into the shared branch ───────────
+                                // If this wave used per-agent worktrees, merge them now that
+                                // all agents have finished.  Report any conflicts via SSE.
+                                if (pipeline.worktrees?.size > 0 && pipeline.projectDir) {
+                                    const waveIdx = pipeline.currentWave;
+                                    const mergeResults = [];
+                                    const allConflicts = [];
+                                    for (const [agentId, wtMeta] of pipeline.worktrees) {
+                                        if (wtMeta.waveIndex !== waveIdx) continue;
+                                        try {
+                                            const result = mergeWorktree(pipeline.projectDir, dispatch.pipelineId, waveIdx, agentId);
+                                            mergeResults.push({ agentId, ...result });
+                                            if (!result.ok && result.conflicts?.length) {
+                                                allConflicts.push(...result.conflicts.map(f => `${agentId}:${f}`));
+                                            }
+                                        } catch (e) {
+                                            console.warn(`[worktree] merge failed for ${agentId}: ${e.message}`);
+                                            mergeResults.push({ agentId, ok: false, conflicts: [] });
+                                        }
+                                        pipeline.worktrees.delete(agentId);
+                                    }
+                                    if (mergeResults.length > 0) {
+                                        broadcastSSE?.({
+                                            type: "pipeline_worktree_merged",
+                                            pipelineId: dispatch.pipelineId,
+                                            waveIndex: waveIdx,
+                                            results: mergeResults,
+                                            conflicts: allConflicts,
+                                            ts: Date.now(),
+                                        });
+                                        if (allConflicts.length > 0) {
+                                            appendHistory?.(
+                                                "default",
+                                                pipeline.sessionId || "owner",
+                                                "system",
+                                                `Pipeline wave ${waveIdx + 1} worktree merge had ${allConflicts.length} conflict(s): ${allConflicts.join(", ")}. Manual resolution may be required.`,
+                                            );
+                                        }
+                                    }
+                                }
+
                                 const gateResult = checkWaveQualityGate(pipeline, dispatch.pipelineId);
                                 if (gateResult.pass) {
                                     pipeline.currentWave++;

package/lib/memory/relevance-scorer.mjs

@@ -0,0 +1,199 @@
+/**
+ * Memory Relevance Scorer
+ *
+ * Score memories by relevance to a query using:
+ * 1. Recency     — newer memories score higher (exponential decay, ~30-day half-life)
+ * 2. Frequency   — memories accessed more often score higher (normalised log)
+ * 3. Keyword     — TF-IDF-like scoring against query terms (inverse-length weighting)
+ * 4. Context     — memories from the same project/agent/session score higher
+ *
+ * Pure functions only — zero I/O, zero dependencies.
+ */
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+/**
+ * Tokenise a string into lowercase alpha-numeric tokens of length >= 2.
+ * @param {string} text
+ * @returns {string[]}
+ */
+function tokenise(text) {
+  if (!text || typeof text !== 'string') return [];
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s_-]/g, ' ')
+    .split(/\s+/)
+    .filter(t => t.length >= 2);
+}
+
+// ─── Individual scoring components ──────────────────────────────────────────
+
+/**
+ * Recency score: exponential decay with ~30-day half-life.
+ * Returns 1.0 for brand-new memories, approaching 0 for very old ones.
+ *
+ * @param {string|number|Date} timestamp - ISO string, epoch ms, or Date
+ * @param {number} nowMs - current epoch ms (injectable for testing)
+ * @returns {number} [0, 1]
+ */
+export function computeRecency(timestamp, nowMs = Date.now()) {
+  if (timestamp == null) return 0;
+  const createdAt = timestamp instanceof Date
+    ? timestamp.getTime()
+    : new Date(timestamp).getTime();
+  if (Number.isNaN(createdAt)) return 0;
+  const daysSince = Math.max(0, (nowMs - createdAt) / (1000 * 60 * 60 * 24));
+  return Math.exp(-daysSince / 30);
+}
+
+/**
+ * Frequency score: log-normalised access count relative to a max.
+ * Both accessCount and maxAccessCount must be >= 0.
+ *
+ * @param {number} accessCount
+ * @param {number} maxAccessCount - upper bound for normalisation (default 100)
+ * @returns {number} [0, 1]
+ */
+export function computeFrequency(accessCount, maxAccessCount = 100) {
+  const count = Math.max(0, Number(accessCount) || 0);
+  const maxCount = Math.max(1, Number(maxAccessCount) || 100);
+  return Math.min(1, Math.log(1 + count) / Math.log(1 + maxCount));
+}
+
+/**
+ * Keyword match score: TF-IDF-like overlap between query tokens and memory content.
+ * Rarer (longer) query words are weighted more heavily.
+ *
+ * @param {string} content - memory content
+ * @param {string} query
+ * @returns {number} [0, 1]
+ */
+export function computeKeywordMatch(content, query) {
+  const queryTokens = tokenise(query);
+  const contentTokens = tokenise(content);
+
+  if (queryTokens.length === 0 || contentTokens.length === 0) return 0;
+
+  const contentSet = new Set(contentTokens);
+
+  // Weight each query token by its length (longer words are more specific)
+  let weightedMatch = 0;
+  let totalWeight = 0;
+
+  for (const token of queryTokens) {
+    // IDF proxy: weight proportional to token length (longer = rarer heuristic)
+    const weight = Math.log(1 + token.length);
+    totalWeight += weight;
+    if (contentSet.has(token)) {
+      weightedMatch += weight;
+    }
+  }
+
+  if (totalWeight === 0) return 0;
+  return weightedMatch / totalWeight;
+}
+
+/**
+ * Context match score: bonus points for shared project / agent / session.
+ *
+ * @param {object} memory - memory object with optional projectId, agentId, sessionId
+ * @param {object} context - { projectId?, agentId?, sessionId? }
+ * @returns {number} [0, 1]
+ */
+export function computeContextMatch(memory, context = {}) {
+  if (!memory || !context) return 0;
+
+  let score = 0;
+
+  if (context.projectId && memory.projectId &&
+      context.projectId === memory.projectId) {
+    score += 0.5;
+  }
+
+  if (context.agentId && memory.agentId &&
+      context.agentId === memory.agentId) {
+    score += 0.3;
+  }
+
+  if (context.sessionId && memory.sessionId &&
+      context.sessionId === memory.sessionId) {
+    score += 0.2;
+  }
+
+  // Cap at 1.0
+  return Math.min(1, score);
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Score a single memory object for relevance to a query + context.
+ *
+ * Expected memory shape (all fields optional except content):
+ * {
+ *   content:     string,
+ *   timestamp:   string|number|Date,   // ISO or epoch ms
+ *   accessCount: number,
+ *   projectId:   string,
+ *   agentId:     string,
+ *   sessionId:   string,
+ * }
+ *
+ * @param {object} memory
+ * @param {string} query
+ * @param {object} [context]   - { projectId?, agentId?, sessionId? }
+ * @param {object} [opts]
+ * @param {number} [opts.nowMs]            - override current time (for testing)
+ * @param {number} [opts.maxAccessCount]   - normalisation ceiling for frequency
+ * @returns {number} weighted relevance score in [0, 1]
+ */
+export function scoreMemory(memory, query, context = {}, opts = {}) {
+  if (!memory) return 0;
+
+  const nowMs = opts.nowMs != null ? opts.nowMs : Date.now();
+  const maxAccessCount = opts.maxAccessCount != null ? opts.maxAccessCount : 100;
+
+  const recencyScore  = computeRecency(memory.timestamp, nowMs);
+  const frequencyScore = computeFrequency(memory.accessCount || 0, maxAccessCount);
+  const keywordScore  = computeKeywordMatch(memory.content || '', query);
+  const contextScore  = computeContextMatch(memory, context);
+
+  return (
+    0.30 * recencyScore  +
+    0.20 * frequencyScore +
+    0.35 * keywordScore  +
+    0.15 * contextScore
+  );
+}
+
+/**
+ * Rank an array of memories by relevance and return the top N.
+ * Attaches a `relevanceScore` property to each returned object.
+ *
+ * @param {object[]} memories
+ * @param {string}   query
+ * @param {object}   [context]   - { projectId?, agentId?, sessionId? }
+ * @param {number}   [maxResults=10]
+ * @param {object}   [opts]      - forwarded to scoreMemory
+ * @returns {object[]} sorted slice with relevanceScore attached
+ */
+export function rankMemories(memories, query, context = {}, maxResults = 10, opts = {}) {
+  if (!Array.isArray(memories) || memories.length === 0) return [];
+
+  return memories
+    .map(m => ({ ...m, relevanceScore: scoreMemory(m, query, context, opts) }))
+    .sort((a, b) => b.relevanceScore - a.relevanceScore)
+    .slice(0, Math.max(1, maxResults));
+}
+
+/**
+ * Derive the max accessCount from a collection of memories.
+ * Useful for caller-side normalisation when passing opts.maxAccessCount.
+ *
+ * @param {object[]} memories
+ * @returns {number}
+ */
+export function maxAccessCount(memories) {
+  if (!Array.isArray(memories) || memories.length === 0) return 0;
+  return memories.reduce((max, m) => Math.max(max, m.accessCount || 0), 0);
+}

package/lib/memory/shared-adapter.mjs

@@ -12,6 +12,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { createRequire } from 'node:module';
+import { rankMemories, maxAccessCount } from './relevance-scorer.mjs';
 
 const require = createRequire(import.meta.url);
 
@@ -124,41 +125,106 @@ export function rememberFact(agentId, content, options = {}) {
 
 /**
  * Recall memory context for a task using MemoryBroker (blends AgentKeeper + AgentMemory + Collections).
+ * ENHANCED: Applies relevance scoring (recency + frequency + keyword + context) and tracks access metadata.
  * ENHANCED: Also includes relevant conversation history from project messages.
  * @param {string} projectDir - Project directory
  * @param {string} query - Task description or search query
- * @param {object} options - { maxResults?, includeDocs?, includeCode?, pathHints?, preferSuccessful?, userId?, projectId? }
+ * @param {object} options - { maxResults?, includeDocs?, includeCode?, pathHints?, preferSuccessful?, userId?, projectId?, agentId?, sessionId? }
  * @returns {Promise<string>} - Formatted context block
  */
 export async function recallMemoryContext(projectDir, query, options = {}) {
   const broker = getMemoryBroker(projectDir, { crewId: options.crewId || 'crew-lead' });
-  
+
   let memoryContext = '';
-  
+
   // Get standard memory (AgentKeeper + AgentMemory + Collections)
-  // NEW: Filter for success-weighted, high-signal artifacts only
+  // Fetch a larger candidate set so the relevance ranker has room to reorder
   if (broker) {
-    memoryContext = await broker.recallAsContext(query, {
-      maxResults: options.maxResults || 5,
-      includeDocs: options.includeDocs !== false,
-      includeCode: Boolean(options.includeCode),
-      pathHints: options.pathHints || [],
-      preferSuccessful: options.preferSuccessful !== false,
-      // NEW: Quality filters to prevent context contamination
-      minScore: 0.7,  // Only high-confidence matches
-      excludeFailed: true,  // Filter out failed tasks
-      excludeErrors: true,  // Filter out error-only entries
-      excludeTimeouts: true  // Filter out timeout failures
-    });
+    const maxResults = options.maxResults || 5;
+    const candidateLimit = Math.max(maxResults * 3, 15);
+
+    // Pull raw structured hits when available, fall back to formatted context
+    let rawHits = null;
+    if (typeof broker.recall === 'function') {
+      try {
+        rawHits = await broker.recall(query, {
+          maxResults: candidateLimit,
+          includeDocs: options.includeDocs !== false,
+          includeCode: Boolean(options.includeCode),
+          pathHints: options.pathHints || [],
+          preferSuccessful: options.preferSuccessful !== false,
+          minScore: 0.7,
+          excludeFailed: true,
+          excludeErrors: true,
+          excludeTimeouts: true
+        });
+      } catch {
+        rawHits = null;
+      }
+    }
+
+    if (rawHits && Array.isArray(rawHits) && rawHits.length > 0) {
+      // Build a relevance context for the ranker
+      const scoringContext = {
+        projectId: options.projectId,
+        agentId:   options.agentId,
+        sessionId: options.sessionId
+      };
+
+      // Normalise hits to the shape scoreMemory expects
+      const now = Date.now();
+      const normalised = rawHits.map(hit => ({
+        ...hit,
+        content:     hit.text || hit.content || '',
+        timestamp:   hit.metadata?.timestamp || hit.timestamp || new Date(now - 86400000).toISOString(),
+        accessCount: (hit.accessCount || 0) + 1,  // count this retrieval
+        lastAccessed: new Date(now).toISOString(),
+        projectId:   hit.metadata?.projectId || hit.projectId,
+        agentId:     hit.metadata?.agentId   || hit.agentId,
+        sessionId:   hit.metadata?.sessionId || hit.sessionId
+      }));
+
+      const scoringOpts = { nowMs: now, maxAccessCount: maxAccessCount(normalised) };
+      const ranked = rankMemories(normalised, query, scoringContext, maxResults, scoringOpts);
+
+      // Re-serialise to context string (mirrors broker.recallAsContext format)
+      if (ranked.length > 0) {
+        const lines = ranked.map((hit, i) => {
+          const score = hit.relevanceScore.toFixed(3);
+          const source = hit.source || hit.metadata?.source || 'memory';
+          const title  = hit.title  || hit.metadata?.title  || `Result ${i + 1}`;
+          return `[${source}] ${title} (relevance: ${score})\n${hit.content}`;
+        });
+        memoryContext = lines.join('\n\n---\n\n');
+      }
+    } else {
+      // Fallback: broker doesn't expose raw hits — use formatted context as-is
+      try {
+        memoryContext = await broker.recallAsContext(query, {
+          maxResults: options.maxResults || 5,
+          includeDocs: options.includeDocs !== false,
+          includeCode: Boolean(options.includeCode),
+          pathHints: options.pathHints || [],
+          preferSuccessful: options.preferSuccessful !== false,
+          // Quality filters to prevent context contamination
+          minScore: 0.7,
+          excludeFailed: true,
+          excludeErrors: true,
+          excludeTimeouts: true
+        });
+      } catch {
+        memoryContext = '';
+      }
+    }
   }
-  
+
   // ENHANCEMENT: Add relevant conversation history from project messages
   // This lets agents see past discussions about the same topic
   if (options.projectId) {
     try {
       const ragModule = await getProjectMessagesRag();
       const conversationContext = ragModule?.getConversationContext(options.projectId, query, 3);
-      
+
       if (conversationContext) {
         memoryContext += (memoryContext ? '\n\n' : '') + conversationContext;
       }
@@ -167,7 +233,7 @@ export async function recallMemoryContext(projectDir, query, options = {}) {
       console.warn('[shared-adapter] Failed to load conversation context:', e.message);
     }
   }
-  
+
   return memoryContext;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crewswarm",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "description": "Local-first multi-agent orchestration platform — coordinate AI coding agents, LLMs, and tools from a single dashboard",
   "type": "module",
   "license": "MIT",
@@ -8,6 +8,10 @@
     "type": "git",
     "url": "https://github.com/crewswarm/crewswarm.git"
   },
+  "homepage": "https://crewswarm.ai",
+  "bugs": {
+    "url": "https://github.com/crewswarm/crewswarm/issues"
+  },
   "keywords": [
     "ai",
     "agents",
@@ -110,6 +114,7 @@
     "vibe:start": "cd apps/vibe && NODE_DISABLE_COMPILE_CACHE=1 npm start",
     "vibe:watch": "NODE_DISABLE_COMPILE_CACHE=1 node apps/vibe/watch-server.mjs",
     "vibe:full": "bash scripts/start-studio-full.sh",
+    "test:playwright": "npx playwright test --reporter=line",
     "test:e2e:vibe": "node node_modules/playwright/cli.js test --config=playwright.config.js",
     "test:e2e:vibe:headed": "node node_modules/playwright/cli.js test --config=playwright.config.js --headed",
     "crew-lead": "node crew-lead.mjs",

package/scripts/dashboard.mjs

@@ -1831,8 +1831,13 @@ const server = http.createServer(async (req, res) => {
       req.on("data", (c) => (body += c));
       req.on("end", async () => {
         let suite = "test:unit";
-        try { const parsed = JSON.parse(body); suite = parsed.suite || suite; } catch { /* default */ }
-        const allowed = ["test:unit", "test:integration", "test:e2e", "test:all", "test", "test:e2e:vibe"];
+        let singleFile = null;
+        try {
+          const parsed = JSON.parse(body);
+          suite = parsed.suite || suite;
+          singleFile = parsed.file || null;
+        } catch { /* default */ }
+        const allowed = ["test:unit", "test:integration", "test:e2e", "test:all", "test", "test:e2e:vibe", "test:playwright"];
         if (!allowed.includes(suite)) {
           res.writeHead(400, { "content-type": "application/json" });
           res.end(JSON.stringify({ error: "Invalid suite: " + suite }));
@@ -1842,9 +1847,16 @@ const server = http.createServer(async (req, res) => {
         const progressFile = path.join(CREWSWARM_DIR, "test-results", ".test-progress.json");
         const outputFile = path.join(CREWSWARM_DIR, "test-results", ".test-output.log");
         // Write initial progress
-        await fs.promises.writeFile(progressFile, JSON.stringify({ suite, running: true, pid: 0, started: Date.now(), passed: 0, failed: 0, skipped: 0, files_done: 0, current_file: "" }));
+        await fs.promises.writeFile(progressFile, JSON.stringify({ suite, running: true, pid: 0, started: Date.now(), passed: 0, failed: 0, skipped: 0, files_done: 0, current_file: singleFile || "" }));
+        let child;
         const outFd = fs.openSync(outputFile, "w");
-        const child = spawn("npm", ["run", suite], { cwd: CREWSWARM_DIR, stdio: ["ignore", outFd, outFd], detached: true });
+        if (singleFile) {
+          // Single-file run: use node --test directly on the file
+          const absFile = path.isAbsolute(singleFile) ? singleFile : path.join(CREWSWARM_DIR, singleFile);
+          child = spawn("node", ["--test", "--test-reporter=./scripts/test-reporter.mjs", absFile], { cwd: CREWSWARM_DIR, stdio: ["ignore", outFd, outFd], detached: true });
+        } else {
+          child = spawn("npm", ["run", suite], { cwd: CREWSWARM_DIR, stdio: ["ignore", outFd, outFd], detached: true });
+        }
         child.unref();
         fs.closeSync(outFd);
         // Update progress by tailing the output file
@@ -1898,6 +1910,173 @@ const server = http.createServer(async (req, res) => {
       return;
     }
 
+    // ── GET /api/tests/stale — files changed since last test run ────────────
+    if (url.pathname === "/api/tests/stale" && req.method === "GET") {
+      const resultsDir = path.join(CREWSWARM_DIR, "test-results");
+      const logPath = path.join(resultsDir, "test-log.jsonl");
+      try {
+        // Read last-run fingerprints from test-log.jsonl
+        const fingerprintByFile = new Map();
+        try {
+          const lines = (await fs.promises.readFile(logPath, "utf8")).split("\n").filter(Boolean);
+          for (const line of lines) {
+            try {
+              const entry = JSON.parse(line);
+              if (entry.file && entry.file_fingerprint?.mtime) {
+                // Keep the most recent entry per file
+                fingerprintByFile.set(entry.file, entry.file_fingerprint);
+              }
+            } catch {}
+          }
+        } catch {}
+        const stale = [];
+        for (const [filePath, fp] of fingerprintByFile) {
+          try {
+            const stat = await fs.promises.stat(filePath);
+            const currentMtime = stat.mtime.toISOString();
+            if (currentMtime > fp.mtime) {
+              stale.push({
+                file: filePath.replace(CREWSWARM_DIR + "/", ""),
+                lastRun: fp.mtime,
+                lastModified: currentMtime,
+              });
+            }
+          } catch {}
+        }
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ stale }));
+      } catch (e) {
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ stale: [], error: e.message }));
+      }
+      return;
+    }
+
+    // ── GET /api/tests/stream — SSE stream of running test output ───────────
+    if (url.pathname === "/api/tests/stream" && req.method === "GET") {
+      const outputFile = path.join(CREWSWARM_DIR, "test-results", ".test-output.log");
+      res.writeHead(200, {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache",
+        "connection": "keep-alive",
+        "access-control-allow-origin": "*",
+      });
+      let lastSize = 0;
+      // Send existing content first
+      try {
+        const content = await fs.promises.readFile(outputFile, "utf8");
+        if (content) {
+          res.write("data: " + JSON.stringify({ text: content, reset: true }) + "\n\n");
+          lastSize = Buffer.byteLength(content, "utf8");
+        }
+      } catch {}
+      const streamInterval = setInterval(async () => {
+        try {
+          const stat = await fs.promises.stat(outputFile);
+          if (stat.size > lastSize) {
+            const fd = await fs.promises.open(outputFile, "r");
+            const newBytes = stat.size - lastSize;
+            const buf = Buffer.alloc(newBytes);
+            await fd.read(buf, 0, newBytes, lastSize);
+            await fd.close();
+            const text = buf.toString("utf8");
+            lastSize = stat.size;
+            res.write("data: " + JSON.stringify({ text }) + "\n\n");
+          }
+          // Check if done
+          const progressFile = path.join(CREWSWARM_DIR, "test-results", ".test-progress.json");
+          try {
+            const prog = JSON.parse(await fs.promises.readFile(progressFile, "utf8"));
+            if (!prog.running && prog.finished) {
+              res.write("data: " + JSON.stringify({ done: true }) + "\n\n");
+              clearInterval(streamInterval);
+              res.end();
+            }
+          } catch {}
+        } catch {}
+      }, 500);
+      req.on("close", () => { clearInterval(streamInterval); });
+      return;
+    }
+
+    // ── GET /api/tests/screenshot — serve a Playwright failure screenshot ────
+    if (url.pathname === "/api/tests/screenshot" && req.method === "GET") {
+      const relPath = url.searchParams.get("path");
+      if (!relPath) { res.writeHead(400); res.end("Missing path"); return; }
+      // Security: only allow paths within test-results/
+      const safePath = path.normalize(relPath).replace(/^(\.\.(\/|\\|$))+/, "");
+      const absPath = path.join(CREWSWARM_DIR, "test-results", safePath);
+      if (!absPath.startsWith(path.join(CREWSWARM_DIR, "test-results"))) {
+        res.writeHead(403); res.end("Forbidden"); return;
+      }
+      try {
+        const stat = await fs.promises.stat(absPath);
+        const ext = path.extname(absPath).toLowerCase();
+        const mimeMap = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp" };
+        const mime = mimeMap[ext] || "application/octet-stream";
+        res.writeHead(200, { "content-type": mime, "content-length": stat.size, "cache-control": "max-age=300" });
+        fs.createReadStream(absPath).pipe(res);
+      } catch {
+        res.writeHead(404); res.end("Screenshot not found");
+      }
+      return;
+    }
+
+    // ── GET /api/tests/coverage-map — source files vs test coverage ──────────
+    if (url.pathname === "/api/tests/coverage-map" && req.method === "GET") {
+      try {
+        const libDir = path.join(CREWSWARM_DIR, "lib");
+        const crewCliSrcDir = path.join(CREWSWARM_DIR, "crew-cli", "src");
+        const unitTestDir = path.join(CREWSWARM_DIR, "test", "unit");
+        const crewCliTestDir = path.join(CREWSWARM_DIR, "crew-cli", "tests", "unit");
+
+        // Collect test file basenames (strip extension)
+        const testBases = new Set();
+        async function collectTestBases(dir) {
+          try {
+            for (const ent of await fs.promises.readdir(dir, { withFileTypes: true })) {
+              if (ent.isDirectory()) { await collectTestBases(path.join(dir, ent.name)); continue; }
+              if (ent.name.match(/\.test\.(mjs|js|ts)$/)) {
+                // e.g. crew-judge.test.mjs -> crew-judge
+                testBases.add(ent.name.replace(/\.test\.(mjs|js|ts)$/, ""));
+              }
+            }
+          } catch {}
+        }
+        await collectTestBases(unitTestDir);
+        await collectTestBases(crewCliTestDir);
+
+        // Collect source files and check coverage
+        const covered = [];
+        const uncovered = [];
+        async function scanSourceDir(dir, prefix) {
+          try {
+            for (const ent of await fs.promises.readdir(dir, { withFileTypes: true })) {
+              const fullPath = path.join(dir, ent.name);
+              const relPath = prefix + "/" + ent.name;
+              if (ent.isDirectory()) { await scanSourceDir(fullPath, relPath); continue; }
+              if (!ent.name.match(/\.(mjs|js|ts)$/) || ent.name.includes(".d.ts") || ent.name.includes(".test.")) continue;
+              const base = ent.name.replace(/\.(mjs|js|ts)$/, "");
+              // Check if any test file matches by base name (fuzzy: contains or equals)
+              const hasCoverage = [...testBases].some(tb => tb === base || tb.includes(base) || base.includes(tb));
+              const entry = { file: relPath, base };
+              if (hasCoverage) covered.push(entry);
+              else uncovered.push(entry);
+            }
+          } catch {}
+        }
+        await scanSourceDir(libDir, "lib");
+        await scanSourceDir(crewCliSrcDir, "crew-cli/src");
+
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ covered, uncovered, totalCovered: covered.length, totalUncovered: uncovered.length }));
+      } catch (e) {
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ covered: [], uncovered: [], error: e.message }));
+      }
+      return;
+    }
+
     // ── First-run detection ──────────────────────────────────────────────────
     if (url.pathname === "/api/first-run-status" && req.method === "GET") {
       const cfg = readSwarmConfigSafe();

package/scripts/install-docker.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # crewswarm Docker Installer — one-line setup for cloud VMs and dedicated servers
-# Usage: curl -fsSL https://raw.githubusercontent.com/your-org/crewswarm/main/scripts/install-docker.sh | bash
+# Usage: curl -fsSL https://raw.githubusercontent.com/crewswarm/crewswarm/main/scripts/install-docker.sh | bash
 
 set -e
 

package/scripts/start.mjs

@@ -2,24 +2,29 @@
 /**
  * scripts/start.mjs — CrewSwarm first-run entry point
  *
- * This is the script behind `npm start`.  It validates the environment before
- * handing off to the real stack so that a brand-new user who clones the repo
- * and types `npm start` gets clear, actionable guidance rather than a stack
- * trace.
+ * This is the script behind `npm start` / `npx crewswarm`.  It validates the
+ * environment before handing off to the real stack so that a brand-new user
+ * who clones the repo and types `npm start` gets clear, actionable guidance
+ * rather than a stack trace.
  *
  * Checks performed (in order):
  *   1. Node.js version >= 20
  *   2. ~/.crewswarm/crewswarm.json exists (created by install.sh)
- *   3. ~/.crewswarm/crewswarm.json exists (created by install.sh)
+ *   3. ~/.crewswarm/config.json exists (created by install.sh)
  *   4. At least one provider with an apiKey is configured
  *
- * On success, delegates to `npm run dashboard` (the standard start target).
+ * On success:
+ *   1. Spawns start-crew.mjs in the background (RT bus + crew-lead + bridges)
+ *   2. Waits 3 seconds for services to come up
+ *   3. Starts dashboard in the foreground (the process the user sees)
+ *
+ * NOTE: `npm run dashboard` still starts only the dashboard (unchanged).
  */
 
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -63,7 +68,7 @@ success(`Node.js v${process.versions.node}`);
 // ── 2. Config directory ───────────────────────────────────────────────────────
 const CREWSWARM_DIR = path.join(os.homedir(), ".crewswarm");
 const SWARM_CFG     = path.join(CREWSWARM_DIR, "crewswarm.json");
-const SYS_CFG       = path.join(CREWSWARM_DIR, "crewswarm.json");
+const SYS_CFG       = path.join(CREWSWARM_DIR, "config.json");
 const INSTALL_SH    = path.join(ROOT, "install.sh");
 
 function tryReadJSON(p) {
@@ -130,14 +135,44 @@ if (agents.length === 0) {
 }
 info(`${agents.length} agent(s) defined`);
 
-// ── 7. Hand off to dashboard ──────────────────────────────────────────────────
+// ── 7. Start full stack ───────────────────────────────────────────────────────
+console.log("");
+divider();
+info("All checks passed — starting full CrewSwarm stack");
+divider();
+console.log("");
+
+// Step 1: Spawn start-crew.mjs in the background (RT bus + crew-lead + bridges)
+info("Launching RT bus, crew-lead, and gateway bridges…");
+const crewScript = path.join(ROOT, "scripts", "start-crew.mjs");
+const crewProc = spawn(process.execPath, [crewScript], {
+  cwd: ROOT,
+  stdio: "inherit",
+  detached: false,
+  env: process.env,
+});
+
+// Wait for start-crew.mjs to finish its synchronous setup (it exits after spawning daemons)
+await new Promise((resolve) => {
+  crewProc.on("exit", resolve);
+  crewProc.on("error", (err) => {
+    warn(`start-crew.mjs exited with error: ${err.message}`);
+    resolve();
+  });
+});
+
+// Step 2: Give the background daemons a moment to bind their ports
+info("Waiting 3 s for services to come up…");
+await new Promise((resolve) => setTimeout(resolve, 3000));
+
+// Step 3: Start dashboard in the foreground (what the user sees)
 console.log("");
 divider();
-info("All checks passed — launching dashboard on http://127.0.0.1:4319");
+console.log(bold("  All services started.  Dashboard → http://127.0.0.1:4319"));
 divider();
 console.log("");
 
-const result = spawnSync("node", [path.join(ROOT, "scripts", "dashboard.mjs")], {
+const result = spawnSync(process.execPath, [path.join(ROOT, "scripts", "dashboard.mjs")], {
   cwd: ROOT,
   stdio: "inherit",
   env: process.env,