crewswarm 0.9.1 → 0.9.3

package/lib/engines/runners.mjs

@@ -21,6 +21,7 @@ import { initEngineRegistry, selectEngine as registrySelectEngine, getEngineById
 import { runCrewCLITask } from "./crew-cli.mjs";
 import { normalizeProjectDir } from "../runtime/project-dir.mjs";
 import { resolveCursorLaunchSpec } from "./cursor-launcher.mjs";
+import * as tmuxBridge from "../bridges/tmux-bridge.mjs";
 
 function which(bin) {
   try { execSync(`which ${bin}`, { stdio: "ignore" }); return true; } catch { return false; }
@@ -357,6 +358,11 @@ export async function runGeminiCliTask(prompt, payload = {}) {
       stdio: ["ignore", "pipe", "pipe"],
     });
 
+    // Label tmux pane with agent ID for cross-agent discovery
+    if (payload?.tmuxSessionId && tmuxBridge.detect()) {
+      try { tmuxBridge.label(agentId, payload.tmuxSessionId); } catch {}
+    }
+
     let lineBuffer = "";
     let accumulatedText = "";
     let orphanStream = "";
@@ -683,6 +689,11 @@ export async function runCursorCliTask(prompt, payload = {}) {
       stdio: ["ignore", "pipe", "pipe"],
     });
 
+    // Label tmux pane with agent ID for cross-agent discovery
+    if (payload?.tmuxSessionId && tmuxBridge.detect()) {
+      try { tmuxBridge.label(agentId, payload.tmuxSessionId); } catch {}
+    }
+
     let lineBuffer = "";
     let accumulatedText = "";
     let lastCursorAssistantNorm = "";
@@ -915,6 +926,11 @@ export async function runCodexTask(prompt, payload = {}) {
       stdio: ["ignore", "pipe", "pipe"],
     });
 
+    // Label tmux pane with agent ID for cross-agent discovery
+    if (payload?.tmuxSessionId && tmuxBridge.detect()) {
+      try { tmuxBridge.label(agentId, payload.tmuxSessionId); } catch {}
+    }
+
     let lineBuffer = "";
     let accumulatedText = "";
     /** Non-JSON lines (stderr, errors, usage) — previously swallowed by catch {} */
@@ -1165,6 +1181,7 @@ export async function runClaudeCodeTask(prompt, payload = {}) {
     const agentPrefix = agentId ? `[${agentId}]` : "";
     const titledPrompt = agentPrefix ? `${agentPrefix} ${String(prompt)}` : String(prompt);
 
+    const emptyMcpCfg = path.join(os.homedir(), ".crewswarm", "config", "empty-mcp.json");
     const args = [
       "-p",
       "--dangerously-skip-permissions",
@@ -1189,8 +1206,10 @@ export async function runClaudeCodeTask(prompt, payload = {}) {
       }
     }
     
-    // CRITICAL: Claude Code expects the prompt as a command-line argument, NOT via stdin
-    args.push(titledPrompt);
+    // Skip user MCP servers to avoid 30s+ init hangs
+    args.push("--strict-mcp-config", "--mcp-config", emptyMcpCfg);
+    // -- separates flags from prompt (--mcp-config is variadic and eats positional args)
+    args.push("--", titledPrompt);
 
     if (!which(CLAUDE_CODE_BIN)) {
       throw new Error(`Claude Code CLI not found: "${CLAUDE_CODE_BIN}". Install with: npm i -g @anthropic-ai/claude-code`);
@@ -1207,6 +1226,11 @@ export async function runClaudeCodeTask(prompt, payload = {}) {
       stdio: ["ignore", "pipe", "pipe"],  // Changed from "pipe" to "ignore" for stdin since we use args
     });
 
+    // Label tmux pane with agent ID for cross-agent discovery
+    if (payload?.tmuxSessionId && tmuxBridge.detect()) {
+      try { tmuxBridge.label(agentId, payload.tmuxSessionId); } catch {}
+    }
+
     let lineBuffer = "";
     let accumulatedText = "";
     let stderrText = "";

package/lib/runtime/config.mjs

@@ -290,6 +290,13 @@ export function loadClaudeCodeEnabled() {
   if (typeof cfg.claudeCode === "boolean") return cfg.claudeCode;
   return false;
 }
+
+export function loadTmuxBridgeEnabled() {
+  if (process.env.CREWSWARM_TMUX_BRIDGE) return /^1|true|yes$/i.test(String(process.env.CREWSWARM_TMUX_BRIDGE));
+  const cfg = loadSystemConfig();
+  if (typeof cfg.tmuxBridge === "boolean") return cfg.tmuxBridge;
+  return false;
+}
 // ── Configuration Parsers (Migrated from registry.mjs) ───────────────────
 export function resolveConfig() {
   const paths = [CREWSWARM_CONFIG_PATH, path.join(LEGACY_STATE_DIR, "openclaw.json")];

package/lib/runtime/paths.mjs

@@ -21,14 +21,16 @@ let _stateDir = null;
  */
 export function getConfigDir() {
   if (_configDir) return _configDir;
-  
-  if (process.env.CREWSWARM_TEST_MODE === "true") {
+
+  if (process.env.CREWSWARM_CONFIG_DIR) {
+    _configDir = process.env.CREWSWARM_CONFIG_DIR;
+  } else if (process.env.CREWSWARM_TEST_MODE === "true") {
     // Use a consistent temp dir for the entire test process (not per-call)
     _configDir = path.join(os.tmpdir(), `crewswarm-test-${process.pid}`);
   } else {
-    _configDir = process.env.CREWSWARM_CONFIG_DIR || path.join(os.homedir(), ".crewswarm");
+    _configDir = path.join(os.homedir(), ".crewswarm");
   }
-  
+
   fs.mkdirSync(_configDir, { recursive: true });
   return _configDir;
 }
@@ -39,14 +41,16 @@ export function getConfigDir() {
  */
 export function getStateDir() {
   if (_stateDir) return _stateDir;
-  
-  if (process.env.CREWSWARM_TEST_MODE === "true") {
+
+  if (process.env.CREWSWARM_STATE_DIR) {
+    _stateDir = process.env.CREWSWARM_STATE_DIR;
+  } else if (process.env.CREWSWARM_TEST_MODE === "true") {
     // Use a consistent temp dir for the entire test process (not per-call)
     _stateDir = path.join(os.tmpdir(), `crewswarm-test-${process.pid}`);
   } else {
-    _stateDir = process.env.CREWSWARM_STATE_DIR || path.join(os.homedir(), ".crewswarm");
+    _stateDir = path.join(os.homedir(), ".crewswarm");
   }
-  
+
   fs.mkdirSync(_stateDir, { recursive: true });
   return _stateDir;
 }

package/lib/sessions/session-manager.mjs

@@ -0,0 +1,287 @@
+/**
+ * Session Manager — persistent tmux sessions as first-class execution resources
+ *
+ * Manages session lifecycle: create, attach, exec, lock, handoff, terminate.
+ * One writer per session (lock enforcement). Transcripts logged for auditability.
+ *
+ * Sessions are stored as metadata files under ~/.crewswarm/state/sessions/.
+ * The actual tmux sessions are managed via tmux CLI.
+ */
+
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { getStatePath } from "../runtime/paths.mjs";
+import * as tmuxBridge from "../bridges/tmux-bridge.mjs";
+
+const SESSION_DIR = getStatePath("sessions");
+const TRANSCRIPT_DIR = getStatePath("sessions", "transcripts");
+
+try { fs.mkdirSync(SESSION_DIR, { recursive: true }); } catch {}
+try { fs.mkdirSync(TRANSCRIPT_DIR, { recursive: true }); } catch {}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function sessionMetaPath(sessionId) {
+  return path.join(SESSION_DIR, `${sessionId}.json`);
+}
+
+function transcriptPath(sessionId) {
+  return path.join(TRANSCRIPT_DIR, `${sessionId}.jsonl`);
+}
+
+function loadMeta(sessionId) {
+  try {
+    return JSON.parse(fs.readFileSync(sessionMetaPath(sessionId), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function saveMeta(sessionId, meta) {
+  try {
+    fs.writeFileSync(sessionMetaPath(sessionId), JSON.stringify(meta, null, 2));
+  } catch (e) {
+    console.error(`[session-manager] Failed to save meta for ${sessionId}: ${e.message}`);
+  }
+}
+
+function appendTranscript(sessionId, entry) {
+  try {
+    const line = JSON.stringify({ ts: new Date().toISOString(), ...entry });
+    fs.appendFileSync(transcriptPath(sessionId), line + "\n");
+  } catch {}
+}
+
+function tmuxExec(cmd, timeout = 5000) {
+  try {
+    return execSync(cmd, { encoding: "utf8", timeout, stdio: ["ignore", "pipe", "pipe"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Create a new persistent tmux session for agent work.
+ * @param {object} opts
+ * @param {string} opts.workspaceId - Logical workspace name
+ * @param {string} opts.agentId - Owning agent
+ * @param {string} [opts.cwd] - Working directory
+ * @param {Record<string, string>} [opts.env] - Extra env vars
+ * @returns {string|null} sessionId or null on failure
+ */
+export function create({ workspaceId, agentId, cwd, env } = {}) {
+  if (!tmuxBridge.detect()) return null;
+
+  const sessionId = `cs-${workspaceId}-${randomUUID().slice(0, 8)}`;
+  const sessionName = sessionId;
+
+  // Create a new tmux session (detached)
+  const envStr = env
+    ? Object.entries(env).map(([k, v]) => `-e ${k}=${v}`).join(" ")
+    : "";
+  const cwdFlag = cwd ? `-c "${cwd}"` : "";
+  const result = tmuxExec(`tmux new-session -d -s "${sessionName}" ${cwdFlag} ${envStr}`);
+  if (result === null) {
+    console.error(`[session-manager] Failed to create tmux session: ${sessionName}`);
+    return null;
+  }
+
+  // Label the session's first pane with the agent ID
+  const paneId = tmuxExec(`tmux list-panes -t "${sessionName}" -F "#{pane_id}" | head -1`);
+  if (paneId) {
+    tmuxBridge.label(agentId, paneId);
+  }
+
+  const meta = {
+    sessionId,
+    sessionName,
+    workspaceId,
+    owner: agentId,
+    lockedBy: agentId,
+    paneId: paneId || null,
+    cwd: cwd || null,
+    env: env || null,
+    createdAt: new Date().toISOString(),
+    status: "active",
+  };
+  saveMeta(sessionId, meta);
+  appendTranscript(sessionId, { action: "created", agent: agentId, cwd });
+
+  console.log(`[session-manager] Created session ${sessionId} for ${agentId} (pane=${paneId})`);
+  return sessionId;
+}
+
+/**
+ * Attach an agent to an existing session (for handoff or observation).
+ * @param {string} sessionId
+ * @param {string} agentId
+ * @returns {{ paneId: string, sessionName: string }|null}
+ */
+export function attach(sessionId, agentId) {
+  const meta = loadMeta(sessionId);
+  if (!meta || meta.status !== "active") return null;
+
+  appendTranscript(sessionId, { action: "attached", agent: agentId });
+  console.log(`[session-manager] ${agentId} attached to session ${sessionId}`);
+
+  return { paneId: meta.paneId, sessionName: meta.sessionName };
+}
+
+/**
+ * Execute a command in a session's tmux pane.
+ * Only the lock owner can execute.
+ * @param {string} sessionId
+ * @param {string} command
+ * @param {object} [opts]
+ * @param {string} opts.actorId - Agent executing the command
+ * @param {number} [opts.timeout=30000] - Timeout in ms
+ * @returns {{ output: string }|null}
+ */
+export function exec(sessionId, command, { actorId, timeout = 30000 } = {}) {
+  const meta = loadMeta(sessionId);
+  if (!meta || meta.status !== "active") return null;
+
+  // Enforce lock
+  if (meta.lockedBy && meta.lockedBy !== actorId) {
+    console.warn(`[session-manager] ${actorId} cannot exec in ${sessionId} — locked by ${meta.lockedBy}`);
+    return null;
+  }
+
+  const paneId = meta.paneId;
+  if (!paneId) return null;
+
+  // Send keys to the pane
+  tmuxExec(`tmux send-keys -t "${paneId}" "${command.replace(/"/g, '\\"')}" Enter`, timeout);
+  appendTranscript(sessionId, { action: "exec", agent: actorId, command: command.slice(0, 500) });
+
+  // Read back output after a short delay
+  const output = tmuxBridge.read(meta.owner, 50);
+  return { output: output || "" };
+}
+
+/**
+ * Lock a session for exclusive write access.
+ * @param {string} sessionId
+ * @param {string} ownerId - Agent requesting the lock
+ * @returns {boolean} true if lock acquired
+ */
+export function lock(sessionId, ownerId) {
+  const meta = loadMeta(sessionId);
+  if (!meta || meta.status !== "active") return false;
+
+  if (meta.lockedBy && meta.lockedBy !== ownerId) {
+    console.warn(`[session-manager] Lock denied for ${ownerId} on ${sessionId} — held by ${meta.lockedBy}`);
+    return false;
+  }
+
+  meta.lockedBy = ownerId;
+  meta.lockedAt = new Date().toISOString();
+  saveMeta(sessionId, meta);
+  appendTranscript(sessionId, { action: "locked", agent: ownerId });
+  return true;
+}
+
+/**
+ * Unlock a session.
+ * @param {string} sessionId
+ * @param {string} ownerId - Must match current lock holder
+ * @returns {boolean}
+ */
+export function unlock(sessionId, ownerId) {
+  const meta = loadMeta(sessionId);
+  if (!meta) return false;
+
+  if (meta.lockedBy && meta.lockedBy !== ownerId) {
+    console.warn(`[session-manager] Unlock denied for ${ownerId} on ${sessionId} — held by ${meta.lockedBy}`);
+    return false;
+  }
+
+  meta.lockedBy = null;
+  meta.lockedAt = null;
+  saveMeta(sessionId, meta);
+  appendTranscript(sessionId, { action: "unlocked", agent: ownerId });
+  return true;
+}
+
+/**
+ * Hand off a session from one agent to another.
+ * Transfers lock ownership and re-labels the pane.
+ * @param {string} sessionId
+ * @param {string} fromAgent
+ * @param {string} toAgent
+ * @returns {boolean}
+ */
+export function handoff(sessionId, fromAgent, toAgent) {
+  const meta = loadMeta(sessionId);
+  if (!meta || meta.status !== "active") return false;
+
+  // Only the current lock holder (or unlocked session) can hand off
+  if (meta.lockedBy && meta.lockedBy !== fromAgent) {
+    console.warn(`[session-manager] Handoff denied: ${sessionId} locked by ${meta.lockedBy}, not ${fromAgent}`);
+    return false;
+  }
+
+  meta.owner = toAgent;
+  meta.lockedBy = toAgent;
+  meta.lockedAt = new Date().toISOString();
+  saveMeta(sessionId, meta);
+
+  // Re-label pane for the new agent
+  if (meta.paneId) {
+    tmuxBridge.label(toAgent, meta.paneId);
+  }
+
+  appendTranscript(sessionId, { action: "handoff", from: fromAgent, to: toAgent });
+  console.log(`[session-manager] Session ${sessionId} handed off: ${fromAgent} → ${toAgent}`);
+  return true;
+}
+
+/**
+ * Terminate a session and clean up its tmux pane.
+ * @param {string} sessionId
+ * @returns {boolean}
+ */
+export function terminate(sessionId) {
+  const meta = loadMeta(sessionId);
+  if (!meta) return false;
+
+  // Kill the tmux session
+  if (meta.sessionName) {
+    tmuxExec(`tmux kill-session -t "${meta.sessionName}"`);
+  }
+
+  meta.status = "terminated";
+  meta.terminatedAt = new Date().toISOString();
+  saveMeta(sessionId, meta);
+  appendTranscript(sessionId, { action: "terminated" });
+  console.log(`[session-manager] Session ${sessionId} terminated`);
+  return true;
+}
+
+/**
+ * Get metadata for a session.
+ * @param {string} sessionId
+ * @returns {object|null}
+ */
+export function getSession(sessionId) {
+  return loadMeta(sessionId);
+}
+
+/**
+ * List all active sessions.
+ * @returns {Array<object>}
+ */
+export function listSessions() {
+  try {
+    const files = fs.readdirSync(SESSION_DIR).filter(f => f.endsWith(".json"));
+    return files
+      .map(f => loadMeta(f.replace(".json", "")))
+      .filter(m => m && m.status === "active");
+  } catch {
+    return [];
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "crewswarm",
-  "version": "0.9.1",
-  "description": "Local-first multi-agent orchestration platform — coordinate AI coding agents, LLMs, and tools from a single dashboard",
+  "version": "0.9.3",
+  "description": "Local-first multi-agent orchestration platform \u2014 coordinate AI coding agents, LLMs, and tools from a single dashboard",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -29,10 +29,11 @@
     "engines/",
     "prompts/",
     "apps/dashboard/dist/",
-    "apps/dashboard/src/",
-    "apps/dashboard/index.html",
-    "apps/dashboard/package.json",
-    "apps/vibe/",
+    "apps/vibe/dist/",
+    "apps/vibe/package.json",
+    "apps/vibe/public/",
+    "apps/vibe/server.mjs",
+    "apps/vibe/watch-server.mjs",
     "contrib/openclaw-plugin/",
     "crew-lead.mjs",
     "gateway-bridge.mjs",
@@ -61,14 +62,25 @@
     "@whiskeysockets/baileys": "^7.0.0-rc.9"
   },
   "scripts": {
-    "postinstall": "node -e \"try{require('child_process').execSync('git --version',{stdio:'pipe'})}catch{console.log('\\n⚠️  git not found. Install git for full functionality (WhatsApp bridge, crew-cli git tools).\\n   macOS: xcode-select --install\\n   Ubuntu: sudo apt install git\\n   Alpine: apk add git\\n')}\"",
+    "postinstall": "node -e \"try{require('child_process').execSync('git --version',{stdio:'pipe'})}catch{console.log('\\n\u26a0\ufe0f  git not found. Install git for full functionality (WhatsApp bridge, crew-cli git tools).\\n   macOS: xcode-select --install\\n   Ubuntu: sudo apt install git\\n   Alpine: apk add git\\n')}\"",
     "start": "node scripts/start.mjs",
-    "test": "node --test test/unit/*.test.mjs test/mention-participants.test.mjs test/project-messages-chat-protocol.test.mjs && npm --prefix crew-cli test",
-    "test:unit": "node --test test/unit/*.test.mjs",
-    "test:integration": "PM_LOOP_TEST_MODE=1 node --test test/integration/*.test.mjs",
+    "test": "node --test --test-reporter=./scripts/test-reporter.mjs test/unit/*.test.mjs test/mention-participants.test.mjs test/project-messages-chat-protocol.test.mjs && npm --prefix crew-cli test",
+    "test:unit": "node --test --test-reporter=./scripts/test-reporter.mjs test/unit/*.test.mjs",
+    "test:integration": "PM_LOOP_TEST_MODE=1 node --test --test-reporter=./scripts/test-reporter.mjs test/integration/*.test.mjs",
     "test:integration:bounded": "node scripts/run-integration-bounded.mjs",
-    "test:e2e": "node --test test/e2e/*.test.mjs",
-    "test:all": "PM_LOOP_TEST_MODE=1 node --test test/unit/*.test.mjs test/integration/*.test.mjs test/e2e/*.test.mjs",
+    "test:e2e": "node --test --test-reporter=./scripts/test-reporter.mjs test/e2e/*.test.mjs",
+    "test:all": "PM_LOOP_TEST_MODE=1 node --test --test-reporter=./scripts/test-reporter.mjs test/unit/*.test.mjs test/integration/*.test.mjs test/e2e/*.test.mjs",
+    "test:coverage:root": "node --test --experimental-test-coverage test/unit/*.test.mjs",
+    "test:coverage": "node scripts/coverage-report.mjs",
+    "test:coverage:summary": "node scripts/coverage-summary.mjs",
+    "test:live:providers": "node scripts/live-provider-failover-matrix.mjs",
+    "test:live:providers:matrix": "node scripts/live-provider-matrix.mjs",
+    "test:live:providers:smoke": "node scripts/live-provider-matrix.mjs --smoke",
+    "test:live:clis": "node scripts/live-cli-matrix.mjs",
+    "test:live:clis:smoke": "node scripts/live-cli-matrix.mjs --smoke",
+    "test:live:bridges": "node scripts/live-bridge-matrix.mjs",
+    "test:live:crewchat": "node scripts/live-crewchat-check.mjs",
+    "test:live": "node scripts/live-provider-failover-matrix.mjs && node scripts/live-bridge-matrix.mjs && node scripts/live-crewchat-check.mjs",
     "docs:api": "node scripts/generate-api-docs.mjs",
     "changelog:generate": "node scripts/generate-changelog.mjs",
     "changelog:release": "node scripts/generate-changelog.mjs --release",
@@ -86,7 +98,12 @@
     "stop-crew": "node scripts/start-crew.mjs --stop",
     "dashboard": "node scripts/dashboard.mjs",
     "vibe": "node apps/vibe/server.mjs",
-    "vibe:watch": "node apps/vibe/watch-server.mjs",
+    "vibe:build": "cd apps/vibe && npm run build",
+    "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: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",
     "mcp": "node scripts/mcp-server.mjs",
     "studio": "cd apps/vibe && npm run dev",
@@ -100,10 +117,13 @@
     "smoke:static": "bash scripts/smoke.sh",
     "health": "node scripts/health-check.mjs",
     "doctor": "node scripts/doctor.mjs",
-    "release:check": "bash scripts/release-check.sh"
+    "release:check": "bash scripts/release-check.sh",
+    "test:report": "node scripts/test-report-summary.mjs",
+    "test:rerun": "node scripts/test-rerun.mjs",
+    "test:stale": "node scripts/test-rerun.mjs --stale"
   },
   "devDependencies": {
     "@playwright/test": "^1.58.2",
     "puppeteer-core": "^24.40.0"
   }
-}
+}

package/scripts/capture-build-flow.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * capture-build-flow.mjs — Puppeteer script that captures dashboard
+ * screenshots during a build flow for documentation / demo purposes.
+ *
+ * Usage:  node scripts/capture-build-flow.mjs
+ * Requires: dashboard running at http://127.0.0.1:4319
+ */
+
+import { mkdir } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import puppeteer from "puppeteer-core";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, "..");
+const OUT_DIR = resolve(ROOT, "website/screenshots/flow");
+const BASE_URL = "http://127.0.0.1:4319";
+
+const STEPS = [
+  { name: "step1-build-tab",    hash: "build",  waitMs: 2000  },
+  { name: "step2-requirement",  action: "type"                 },
+  { name: "step3-plan",         action: "plan",  waitMs: 20000 },
+  { name: "step4-chat",         hash: "chat",   waitMs: 3000  },
+  { name: "step5-agents",       hash: "swarm",  waitMs: 2000  },
+  { name: "step6-rt-messages",  hash: "rt",     waitMs: 2000  },
+];
+
+async function screenshot(page, name) {
+  const path = resolve(OUT_DIR, `${name}.webp`);
+  await page.screenshot({ path, type: "webp", quality: 85 });
+}
+
+async function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+async function main() {
+  await mkdir(OUT_DIR, { recursive: true });
+
+  const browser = await puppeteer.launch({
+    headless: true,
+    executablePath:
+      "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    args: ["--no-sandbox"],
+    defaultViewport: { width: 1440, height: 960 },
+  });
+
+  const page = await browser.newPage();
+
+  // Step 1 — navigate to #build
+  await page.goto(`${BASE_URL}/#build`, { waitUntil: "domcontentloaded" });
+  await sleep(2000);
+  await screenshot(page, "step1-build-tab");
+
+  // Step 2 — type requirement
+  const REQUIREMENT = "Create a simple hello world HTML page";
+  // Try a few selectors for the requirement input
+  const textareaSelector = await page
+    .waitForSelector("textarea, #requirement, .requirement-input", {
+      timeout: 5000,
+    })
+    .catch(() => null);
+
+  if (textareaSelector) {
+    await textareaSelector.click();
+    await textareaSelector.type(REQUIREMENT, { delay: 30 });
+  }
+  await screenshot(page, "step2-requirement");
+
+  // Step 3 — click Plan and wait for result
+  await page.evaluate(() => {
+    const buttons = [...document.querySelectorAll("button")];
+    const planBtn = buttons.find((b) => /plan/i.test(b.textContent));
+    if (planBtn) planBtn.click();
+  });
+  await sleep(20000);
+  await screenshot(page, "step3-plan");
+
+  // Step 4 — Chat tab
+  await page.goto(`${BASE_URL}/#chat`, { waitUntil: "domcontentloaded" });
+  await sleep(3000);
+  await screenshot(page, "step4-chat");
+
+  // Step 5 — Swarm / agents tab
+  await page.goto(`${BASE_URL}/#swarm`, { waitUntil: "domcontentloaded" });
+  await sleep(2000);
+  await screenshot(page, "step5-agents");
+
+  // Step 6 — RT messages tab
+  await page.goto(`${BASE_URL}/#rt`, { waitUntil: "domcontentloaded" });
+  await sleep(2000);
+  await screenshot(page, "step6-rt-messages");
+
+  await browser.close();
+
+  const files = [
+    "step1-build-tab.webp",
+    "step2-requirement.webp",
+    "step3-plan.webp",
+    "step4-chat.webp",
+    "step5-agents.webp",
+    "step6-rt-messages.webp",
+  ];
+
+  console.log(`\nCaptured ${files.length} build flow frames:`);
+  for (const f of files) {
+    console.log(`  website/screenshots/flow/${f}`);
+  }
+  console.log(
+    `\nTo create animated webp: convert -delay 200 website/screenshots/flow/*.webp website/screenshots/build-flow.webp`,
+  );
+}
+
+main().catch((err) => {
+  console.error("Build flow capture failed:", err.message);
+  process.exit(1);
+});