crewswarm 0.9.1 → 0.9.2

package/README.md

@@ -3,7 +3,7 @@
 **The only multi-engine AI coding platform.** Switch between Claude Code, Cursor, Gemini, Codex, and OpenCode mid-conversation. Parallel agents. Persistent sessions. No vendor lock-in.
 
 [![npm version](https://img.shields.io/npm/v/crewswarm)](https://www.npmjs.com/package/crewswarm)
-[![Tests](https://img.shields.io/badge/tests-929%20passed-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-957%20passed-brightgreen)]()
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/Node.js-20%2B-green)](https://nodejs.org)
 [![Website](https://img.shields.io/badge/website-crewswarm.ai-blue)](https://crewswarm.ai)
@@ -161,7 +161,7 @@ crewswarm                    # Start all services
 crewswarm pm-loop            # Run autonomous PM loop
 npm run doctor               # Preflight check
 npm run restart-all          # Restart the stack
-npm test                     # Run 929 tests
+npm test                     # Run 957 tests
 crew exec "Build X"          # Send task via CLI
 ```
 

package/apps/dashboard/index.html

@@ -4402,6 +4402,76 @@
             ></div>
           </div>
 
+          <div class="card" style="margin-top: 16px">
+            <div
+              style="
+                display: flex;
+                align-items: center;
+                justify-content: space-between;
+                flex-wrap: wrap;
+                gap: 12px;
+              "
+            >
+              <div>
+                <div class="card-title" style="margin-bottom: 2px">
+                  🔌 tmux-bridge Sessions
+                </div>
+                <div
+                  style="
+                    font-size: 11px;
+                    color: var(--text-3);
+                    line-height: 1.5;
+                  "
+                >
+                  Enable persistent tmux sessions that survive across pipeline
+                  waves. Agents can hand off live execution context (running
+                  servers, env vars, cwd) to the next wave instead of
+                  cold-starting. Requires
+                  <code
+                    style="
+                      background: var(--bg-1);
+                      padding: 1px 4px;
+                      border-radius: 3px;
+                    "
+                    >tmux</code
+                  >
+                  +
+                  <code
+                    style="
+                      background: var(--bg-1);
+                      padding: 1px 4px;
+                      border-radius: 3px;
+                    "
+                    >smux</code
+                  >
+                  installed. One writer per session (lock enforced).
+                </div>
+              </div>
+              <button
+                id="tmuxBridgeBtn"
+                data-action="toggleTmuxBridge"
+                style="
+                  font-size: 12px;
+                  font-weight: 700;
+                  padding: 8px 18px;
+                  border-radius: 8px;
+                  cursor: pointer;
+                  border: 1px solid var(--border);
+                  background: var(--surface-2);
+                  color: var(--text-2);
+                  white-space: nowrap;
+                  min-width: 80px;
+                "
+              >
+                Loading…
+              </button>
+            </div>
+            <div
+              id="tmuxBridgeStatus"
+              style="margin-top: 8px; font-size: 12px; color: var(--text-3)"
+            ></div>
+          </div>
+
           <div class="card" style="margin-top: 16px">
             <div
               style="

package/apps/dashboard/src/app.js

@@ -181,6 +181,8 @@ import {
   loadLoopBrain,
   saveLoopBrain,
   loadEnvAdvanced,
+  loadTmuxBridge,
+  toggleTmuxBridge,
 } from "./tabs/settings-tab.js";
 import {
   initCommsTab,
@@ -1739,6 +1741,7 @@ function showSettingsTab(tab) {
     loadGlobalFallback();
     loadConfigLockStatus();
     loadCursorWaves();
+    loadTmuxBridge();
     loadAutonomousMentions();
     loadClaudeCode();
     loadCodexExecutor();
@@ -2181,6 +2184,7 @@ const ACTION_REGISTRY = {
   saveGlobalFallback,
   toggleBgConsciousness,
   toggleCursorWaves,
+  toggleTmuxBridge,
   toggleAutonomousMentions,
   toggleClaudeCode,
   toggleCodexExecutor,
@@ -2772,6 +2776,7 @@ Object.assign(window, {
   toggleAddSkill,
   toggleBgConsciousness,
   toggleCursorWaves,
+  toggleTmuxBridge,
   toggleClaudeCode,
   toggleEmojiPicker,
   updateSkillAuthFields,

package/apps/dashboard/src/tabs/settings-tab.js

@@ -290,6 +290,36 @@ export async function toggleCursorWaves() {
   } catch(e) { showNotification('Failed: ' + e.message, 'error'); }
 }
 
+export async function loadTmuxBridge() {
+  const btn = document.getElementById('tmuxBridgeBtn');
+  const status = document.getElementById('tmuxBridgeStatus');
+  try {
+    const d = await getJSON('/api/settings/tmux-bridge');
+    const on = d.enabled;
+    if (btn) {
+      btn.textContent = on ? '🔌 ON' : '⚫ OFF';
+      btn.style.background = on ? 'rgba(52,211,153,0.15)' : 'var(--surface-2)';
+      btn.style.borderColor = on ? 'rgba(52,211,153,0.3)' : 'var(--border)';
+      btn.style.color = on ? 'var(--green)' : 'var(--text-2)';
+    }
+    if (status) status.textContent = on
+      ? 'Active — agents can share persistent tmux sessions across pipeline waves. Requires tmux + smux.'
+      : 'Off — agents use standard cold-start execution (no session persistence).';
+  } catch(e) {
+    if (btn) btn.textContent = 'Error';
+    if (status) status.textContent = 'Could not load: ' + e.message;
+  }
+}
+
+export async function toggleTmuxBridge() {
+  try {
+    const current = await getJSON('/api/settings/tmux-bridge');
+    const d = await postJSON('/api/settings/tmux-bridge', { enabled: !current.enabled });
+    showNotification('tmux-bridge ' + (d.enabled ? 'ENABLED 🔌' : 'DISABLED'));
+    loadTmuxBridge();
+  } catch(e) { showNotification('Failed: ' + e.message, 'error'); }
+}
+
 export async function loadAutonomousMentions() {
   const btn = document.getElementById('autonomousMentionsBtn');
   const status = document.getElementById('autonomousMentionsStatus');
@@ -691,6 +721,34 @@ const ENV_GROUPS = [
       { key: 'SHARED_MEMORY_DIR',       hint: 'Directory for shared memory files',       default: '~/.crewswarm/memory' },
     ],
   },
+  {
+    label: 'crew-cli — Streaming & Hooks',
+    note: 'Controls for crew-cli streaming output, tool hooks, and session token limits.',
+    vars: [
+      { key: 'CREW_NO_STREAM',          hint: 'Disable streaming output — tokens arrive after full response (true/false)', default: 'false' },
+      { key: 'CREW_HOOKS_FILE',         hint: 'Path to hooks.json for PreToolUse/PostToolUse hooks',                       default: '.crew/hooks.json' },
+      { key: 'CREW_MAX_SESSION_TOKENS',  hint: 'Max estimated tokens per session before oldest turns are trimmed',          default: '100000' },
+    ],
+  },
+  {
+    label: 'crew-cli — Codebase Index & RAG',
+    note: 'Codebase embedding index auto-builds on startup. Injects relevant file context into every worker prompt.',
+    vars: [
+      { key: 'CREW_RAG_MODE',            hint: 'RAG mode: auto (use index when ready, else keyword), semantic, keyword, import-graph, off', default: 'auto' },
+      { key: 'CREW_EMBEDDING_PROVIDER',  hint: 'Embedding provider: local (zero-cost), openai (best), gemini (free tier)',                  default: 'local' },
+      { key: 'CREW_RAG_WORKER_BUDGET',   hint: 'Max tokens of RAG context injected per worker (approximate)',                               default: '4000' },
+      { key: 'CREW_RAG_MAX_FILES',       hint: 'Max code files to index (larger repos should increase this)',                                default: '2000' },
+      { key: 'CREW_RAG_BATCH_SIZE',      hint: 'Files per embedding batch (higher = faster but more API calls)',                             default: '20' },
+    ],
+  },
+  {
+    label: 'crew-cli — Checkpointing',
+    note: 'Automatic git checkpoints during pipeline execution for easy rollback.',
+    vars: [
+      { key: 'CREW_AUTO_CHECKPOINT',         hint: 'Enable auto-commit at task boundaries (true/false)',                     default: 'true' },
+      { key: 'CREW_CHECKPOINT_INTERVAL_MS',  hint: 'Periodic git stash snapshot interval during long tasks (ms, 0=off)',     default: '60000' },
+    ],
+  },
   {
     label: 'PM Loop',
     vars: [

package/crew-lead.mjs

@@ -33,8 +33,10 @@ import {
   DISPATCH_TIMEOUT_MS,
   DISPATCH_CLAIMED_TIMEOUT_MS,
   loadCursorWavesEnabled,
-  loadClaudeCodeEnabled
+  loadClaudeCodeEnabled,
+  loadTmuxBridgeEnabled
 } from "./lib/runtime/config.mjs";
+import { _reset as resetTmuxBridge } from "./lib/bridges/tmux-bridge.mjs";
 import {
   CREWSWARM_TOOL_NAMES,
   readAgentTools,
@@ -157,6 +159,7 @@ function broadcastSSE(payload) {
 
 let _cursorWavesEnabled = loadCursorWavesEnabled();
 let _claudeCodeEnabled = loadClaudeCodeEnabled();
+let _tmuxBridgeEnabled = loadTmuxBridgeEnabled();
 
 const BG_CONSCIOUSNESS_INTERVAL_MS = Number(process.env.CREWSWARM_BG_CONSCIOUSNESS_INTERVAL_MS) || 15 * 60 * 1000;
 let BG_CONSCIOUSNESS_MODEL = (() => {
@@ -501,6 +504,15 @@ const bgConsciousnessRef = {
 };
 const cursorWavesRef = { get enabled() { return _cursorWavesEnabled; }, set enabled(v) { _cursorWavesEnabled = v; } };
 const claudeCodeRef = { get enabled() { return _claudeCodeEnabled; }, set enabled(v) { _claudeCodeEnabled = v; } };
+const tmuxBridgeRef = {
+  get enabled() { return _tmuxBridgeEnabled; },
+  set enabled(v) {
+    _tmuxBridgeEnabled = v;
+    // Sync env var and reset detection cache so tmux-bridge module picks up runtime changes
+    process.env.CREWSWARM_TMUX_BRIDGE = v ? "1" : "0";
+    resetTmuxBridge();
+  },
+};
 
 // connectRT is initialized after RT_URL/RT_TOKEN — use a mutable ref so HTTP server can call it
 let _connectRT = () => { throw new Error("connectRT not initialized yet"); };
@@ -544,6 +556,7 @@ initHttpServer({
   bgConsciousnessIntervalMs: BG_CONSCIOUSNESS_INTERVAL_MS,
   cursorWavesRef,
   claudeCodeRef,
+  tmuxBridgeRef,
 });
 createAndStartServer(PORT);
 

package/lib/bridges/tmux-bridge.mjs

@@ -0,0 +1,200 @@
+/**
+ * tmux-bridge adapter — thin wrapper around smux's tmux-bridge CLI
+ *
+ * Provides agent-to-agent pane communication when running inside a tmux session
+ * with smux installed. All functions degrade to no-ops when unavailable.
+ *
+ * Opt-in: requires $TMUX set, `tmux-bridge` on PATH, and
+ *   CREWSWARM_TMUX_BRIDGE=1 env var (or tmuxBridge: true in system config).
+ */
+
+import { execFileSync, execSync } from "node:child_process";
+
+function which(bin) {
+  try { execSync(`which ${bin}`, { stdio: "ignore" }); return true; } catch { return false; }
+}
+
+// ── Detection & caching ─────────────────────────────────────────────────────
+
+let _available = null;
+let _ownPaneId = null;
+const _resolveCache = new Map(); // label → { paneId, ts }
+const RESOLVE_TTL_MS = 30_000;
+const TMUX_BRIDGE_BIN = process.env.SMUX_BRIDGE_BIN || "tmux-bridge";
+
+function exec(args, { timeout = 5000 } = {}) {
+  try {
+    return execFileSync(TMUX_BRIDGE_BIN, args, {
+      encoding: "utf8",
+      timeout,
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if tmux-bridge is available and opted-in.
+ * Result is cached for the process lifetime.
+ */
+export function detect() {
+  if (_available !== null) return _available;
+
+  // Must be inside a tmux session
+  if (!process.env.TMUX) {
+    _available = false;
+    return false;
+  }
+
+  // Must have tmux-bridge binary
+  if (!which(TMUX_BRIDGE_BIN)) {
+    _available = false;
+    return false;
+  }
+
+  // Must be opted-in via env var or config
+  const envFlag = process.env.CREWSWARM_TMUX_BRIDGE;
+  if (!envFlag || envFlag === "0" || envFlag === "false") {
+    _available = false;
+    return false;
+  }
+
+  _available = true;
+  return true;
+}
+
+/**
+ * Get this process's own tmux pane ID.
+ * @returns {string|null} e.g. "%3"
+ */
+export function id() {
+  if (!detect()) return null;
+  if (_ownPaneId) return _ownPaneId;
+  _ownPaneId = exec(["id"]);
+  return _ownPaneId;
+}
+
+/**
+ * Label a pane with an agent ID so other agents can discover it.
+ * @param {string} agentId - CrewSwarm agent ID (e.g. "crew-coder")
+ * @param {string} [paneId] - Target pane ID. Defaults to own pane.
+ * @returns {boolean} success
+ */
+export function label(agentId, paneId) {
+  if (!detect()) return false;
+  const target = paneId || id();
+  if (!target) return false;
+  const result = exec(["name", target, agentId]);
+  if (result !== null) {
+    // Update cache
+    _resolveCache.set(agentId, { paneId: target, ts: Date.now() });
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Resolve an agent ID to a tmux pane ID.
+ * @param {string} agentId
+ * @returns {string|null} pane ID or null
+ */
+export function resolve(agentId) {
+  if (!detect()) return null;
+
+  // Check cache
+  const cached = _resolveCache.get(agentId);
+  if (cached && (Date.now() - cached.ts) < RESOLVE_TTL_MS) {
+    return cached.paneId;
+  }
+
+  const paneId = exec(["resolve", agentId]);
+  if (paneId) {
+    _resolveCache.set(agentId, { paneId, ts: Date.now() });
+  }
+  return paneId;
+}
+
+/**
+ * Read the last N lines from an agent's pane.
+ * Also satisfies the read-guard requirement for subsequent sends.
+ * @param {string} agentId
+ * @param {number} [lines=50]
+ * @returns {string|null} pane content or null
+ */
+export function read(agentId, lines = 50) {
+  if (!detect()) return null;
+  const paneId = resolve(agentId);
+  if (!paneId) return null;
+  const output = exec(["read", paneId, String(lines)]);
+  return output;
+}
+
+/**
+ * Send text to an agent's pane followed by Enter.
+ * Reads the pane before each write command to satisfy tmux-bridge's read-guard
+ * (the guard is consumed on every type/keys call).
+ * @param {string} agentId
+ * @param {string} text
+ * @returns {boolean} success
+ */
+export function send(agentId, text) {
+  if (!detect()) return false;
+  const paneId = resolve(agentId);
+  if (!paneId) return false;
+
+  // Read-guard is consumed on each type/keys call, so read before each one
+  exec(["read", paneId, "1"]);
+  const typeResult = exec(["type", paneId, text]);
+  if (typeResult === null) return false;
+
+  exec(["read", paneId, "1"]);
+  const keyResult = exec(["keys", paneId, "Enter"]);
+  return keyResult !== null;
+}
+
+/**
+ * List all tmux panes with their labels and metadata.
+ * @returns {Array<{paneId: string, label: string, raw: string}>}
+ */
+export function list() {
+  if (!detect()) return [];
+  const raw = exec(["list"]);
+  if (!raw) return [];
+
+  // Parse tmux-bridge list output:
+  //   TARGET   SESSION:WIN      SIZE       PROCESS                   LABEL      CWD
+  //   %0       crewtest:0       120x29     -zsh                      crew-coder ~/CrewSwarm
+  const lines = raw.split("\n").filter(Boolean);
+  // Skip header row (starts with "TARGET")
+  return lines
+    .filter(line => line.trimStart().startsWith("%"))
+    .map(line => {
+      const parts = line.split(/\s+/).filter(Boolean);
+      return {
+        paneId: parts[0] || "",
+        session: parts[1] || "",
+        size: parts[2] || "",
+        process: parts[3] || "",
+        label: (parts[4] && parts[4] !== "-") ? parts[4] : "",
+        cwd: parts[5] || "",
+        raw: line,
+      };
+    });
+}
+
+/**
+ * Clear the resolve cache (useful after pane layout changes).
+ */
+export function clearCache() {
+  _resolveCache.clear();
+}
+
+/**
+ * Reset detection state (for testing).
+ */
+export function _reset() {
+  _available = null;
+  _ownPaneId = null;
+  clearCache();
+}

package/lib/cli-process-tracker.mjs

@@ -160,7 +160,8 @@ export function getActiveProcesses() {
     idleFor: now - proc.lastActivity,
     outputLines: proc.outputLines,
     chatId: proc.chatId,
-    sessionId: proc.sessionId
+    sessionId: proc.sessionId,
+    tmuxSessionId: proc.tmuxSessionId || null
   }));
 }
 

package/lib/crew-lead/http-server.mjs

@@ -1087,6 +1087,7 @@ export function createAndStartServer(PORT) {
     bgConsciousnessIntervalMs,
     cursorWavesRef,
     claudeCodeRef,
+    tmuxBridgeRef,
   } = _deps;
 
   // Debug: verify critical deps
@@ -4580,6 +4581,46 @@ export function createAndStartServer(PORT) {
         }
       }
 
+      // GET/POST /api/settings/tmux-bridge — toggle tmux-bridge session layer at runtime
+      if (url.pathname === "/api/settings/tmux-bridge") {
+        if (!checkBearer(req)) {
+          json(res, 401, { ok: false, error: "Unauthorized" });
+          return;
+        }
+        if (req.method === "GET") {
+          json(res, 200, { ok: true, enabled: tmuxBridgeRef?.enabled ?? false });
+          return;
+        }
+        if (req.method === "POST") {
+          const body = await readBody(req);
+          const enable =
+            typeof body.enabled === "boolean"
+              ? body.enabled
+              : !(tmuxBridgeRef?.enabled ?? false);
+          if (tmuxBridgeRef) tmuxBridgeRef.enabled = enable;
+          try {
+            const cfgPath = path.join(
+              os.homedir(),
+              ".crewswarm",
+              "crewswarm.json",
+            );
+            const cfg = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
+            cfg.tmuxBridge = enable;
+            fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2));
+          } catch (e) {
+            console.warn(
+              "[crew-lead] Could not persist tmuxBridge:",
+              e.message,
+            );
+          }
+          console.log(
+            `[crew-lead] tmux-bridge ${enable ? "ENABLED" : "DISABLED"} via dashboard`,
+          );
+          json(res, 200, { ok: true, enabled: tmuxBridgeRef?.enabled ?? enable });
+          return;
+        }
+      }
+
       // GET/POST /api/settings/global-fallback — set/get global OpenCode fallback model
       if (url.pathname === "/api/settings/global-fallback") {
         if (!checkBearer(req)) {
@@ -4680,6 +4721,250 @@ export function createAndStartServer(PORT) {
         }
       }
 
+      // ── Missing settings endpoints (bulk implementation) ─────────────────────
+
+      // Helper: read/write crewswarm.json for simple boolean/string settings
+      const cfgPath = path.join(os.homedir(), ".crewswarm", "crewswarm.json");
+      function readCfg() {
+        try { return JSON.parse(fs.readFileSync(cfgPath, "utf8")); } catch { return {}; }
+      }
+      function writeCfg(cfg) {
+        fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2));
+      }
+      function whichBin(bin) {
+        try {
+          const r = spawn("which", [bin], { stdio: "ignore" });
+          // spawn is async but we can check if the binary exists via fs
+          const paths = (process.env.PATH || "").split(":");
+          return paths.some(p => { try { fs.accessSync(path.join(p, bin), fs.constants.X_OK); return true; } catch { return false; } });
+        } catch { return false; }
+      }
+
+      // GET/POST /api/settings/autonomous-mentions
+      if (url.pathname === "/api/settings/autonomous-mentions") {
+        if (!checkBearer(req)) { json(res, 401, { ok: false, error: "Unauthorized" }); return; }
+        if (req.method === "GET") {
+          const cfg = readCfg();
+          const enabled = cfg.settings?.autonomousMentionsEnabled !== false;
+          json(res, 200, { ok: true, enabled });
+          return;
+        }
+        if (req.method === "POST") {
+          const body = await readBody(req);
+          const cfg = readCfg();
+          if (!cfg.settings) cfg.settings = {};
+          cfg.settings.autonomousMentionsEnabled = typeof body.enabled === "boolean" ? body.enabled : true;
+          writeCfg(cfg);
+          console.log(`[crew-lead] Autonomous mentions ${cfg.settings.autonomousMentionsEnabled ? "ENABLED" : "DISABLED"} via dashboard`);
+          json(res, 200, { ok: true, enabled: cfg.settings.autonomousMentionsEnabled });
+          return;
+        }
+      }
+
+      // GET/POST /api/settings/codex
+      if (url.pathname === "/api/settings/codex") {
+        if (!checkBearer(req)) { json(res, 401, { ok: false, error: "Unauthorized" }); return; }
+        if (req.method === "GET") {
+          const cfg = readCfg();
+          const enabled = cfg.codexEnabled === true || /^1|true|yes$/i.test(String(process.env.CREWSWARM_CODEX_ENABLED || ""));
+          json(res, 200, { ok: true, enabled });
+          return;
+        }
+        if (req.method === "POST") {
+          const body = await readBody(req);
+          const cfg = readCfg();
+          const enable = typeof body.enabled === "boolean" ? body.enabled : !cfg.codexEnabled;
+          cfg.codexEnabled = enable;
+          writeCfg(cfg);
+          console.log(`[crew-lead] Codex executor ${enable ? "ENABLED" : "DISABLED"} via dashboard`);
+          json(res, 200, { ok: true, enabled: enable });
+          return;
+        }
+      }
+
+      // GET/POST /api/settings/gemini-cli
+      if (url.pathname === "/api/settings/gemini-cli") {
+        if (!checkBearer(req)) { json(res, 401, { ok: false, error: "Unauthorized" }); return; }
+        if (req.method === "GET") {
+          const cfg = readCfg();
+          const enabled = cfg.geminiCliEnabled === true || /^1|true|yes$/i.test(String(process.env.CREWSWARM_GEMINI_CLI_ENABLED || ""));
+          const installed = whichBin("gemini");
+          json(res, 200, { ok: true, enabled, installed });
+          return;
+        }
+        if (req.method === "POST") {
+          const body = await readBody(req);
+          const cfg = readCfg();
+          const enable = typeof body.enabled === "boolean" ? body.enabled : !cfg.geminiCliEnabled;
+          cfg.geminiCliEnabled = enable;
+          writeCfg(cfg);
+          console.log(`[crew-lead] Gemini CLI ${enable ? "ENABLED" : "DISABLED"} via dashboard`);
+          json(res, 200, { ok: true, enabled: enable, installed: whichBin("gemini") });
+          return;
+        }
+      }
+
+      // GET/POST /api/settings/crew-cli
+      if (url.pathname === "/api/settings/crew-cli") {
+        if (!checkBearer(req)) { json(res, 401, { ok: false, error: "Unauthorized" }); return; }
+        if (req.method === "GET") {
+          const cfg = readCfg();
+          const enabled = cfg.crewCliEnabled === true || /^1|true|yes$/i.test(String(process.env.CREWSWARM_CREW_CLI_ENABLED || ""));
+          json(res, 200, { ok: true, enabled });
+          return;
+        }
+        if (req.method === "POST") {
+          const body = await readBody(req);
+          const cfg = readCfg();
+          const enable = typeof body.enabled === "boolean" ? body.enabled : !cfg.crewCliEnabled;
+          cfg.crewCliEnabled = enable;
+          writeCfg(cfg);
+          console.log(`[crew-lead] Crew CLI ${enable ? "ENABLED" : "DISABLED"} via dashboard`);
+          json(res, 200, { ok: true, enabled: enable });
+          return;
+        }
+      }
+
+      // GET/POST /api/settings/opencode
+      if (url.pathname === "/api/settings/opencode") {
+        if (!checkBearer(req)) { json(res, 401, { ok: false, error: "Unauthorized" }); return; }
+        if (req.method === "GET") {
+          const cfg = readCfg();
+          const enabled = cfg.opencodeEnabled === true || /^1|true|yes$/i.test(String(process.env.CREWSWARM_OPENCODE_ENABLED || ""));
+          const installed = whichBin("opencode");
+          json(res, 200, { ok: true, enabled, installed });
+          return;
+        }
+        if (req.method === "POST") {
+          const body = await readBody(req);
+          const cfg = readCfg();
+          const enable = typeof body.enabled === "boolean" ? body.enabled : !cfg.opencodeEnabled;
+          cfg.opencodeEnabled = enable;
+          writeCfg(cfg);
+          console.log(`[crew-lead] OpenCode ${enable ? "ENABLED" : "DISABLED"} via dashboard`);
+          json(res, 200, { ok: true, enabled: enable, installed: whichBin("opencode") });
+          return;
+        }
+      }
+
+      // GET/POST /api/settings/global-oc-loop
+      if (url.pathname === "/api/settings/global-oc-loop") {
+        if (!checkBearer(req)) { json(res, 401, { ok: false, error: "Unauthorized" }); return; }
+        if (req.method === "GET") {
+          const cfg = readCfg();
+          const enabled = cfg.engineLoop === true || /^1|true|yes$/i.test(String(process.env.CREWSWARM_ENGINE_LOOP || ""));
+          const maxRounds = cfg.engineLoopMaxRounds ?? parseInt(process.env.CREWSWARM_ENGINE_LOOP_MAX_ROUNDS || "10", 10);
+          json(res, 200, { ok: true, enabled, maxRounds });
+          return;
+        }
+        if (req.method === "POST") {
+          const body = await readBody(req);
+          const cfg = readCfg();
+          if (typeof body.enabled === "boolean") cfg.engineLoop = body.enabled;
+          if (body.maxRounds !== undefined) cfg.engineLoopMaxRounds = parseInt(body.maxRounds, 10) || 10;
+          writeCfg(cfg);
+          console.log(`[crew-lead] Engine loop: enabled=${cfg.engineLoop ?? false}, maxRounds=${cfg.engineLoopMaxRounds ?? 10}`);
+          json(res, 200, { ok: true, enabled: cfg.engineLoop ?? false, maxRounds: cfg.engineLoopMaxRounds ?? 10 });
+          return;
+        }
+      }
+
+      // GET/POST /api/settings/passthrough-notify
+      if (url.pathname === "/api/settings/passthrough-notify") {
+        if (!checkBearer(req)) { json(res, 401, { ok: false, error: "Unauthorized" }); return; }
+        if (req.method === "GET") {
+          const cfg = readCfg();
+          json(res, 200, { ok: true, value: cfg.passthroughNotify || "both" });
+          return;
+        }
+        if (req.method === "POST") {
+          const body = await readBody(req);
+          const cfg = readCfg();
+          cfg.passthroughNotify = body.value || "both";
+          writeCfg(cfg);
+          console.log(`[crew-lead] Passthrough notify → ${cfg.passthroughNotify}`);
+          json(res, 200, { ok: true, value: cfg.passthroughNotify });
+          return;
+        }
+      }
+
+      // GET/POST /api/settings/loop-brain
+      if (url.pathname === "/api/settings/loop-brain") {
+        if (!checkBearer(req)) { json(res, 401, { ok: false, error: "Unauthorized" }); return; }
+        if (req.method === "GET") {
+          const cfg = readCfg();
+          json(res, 200, { ok: true, loopBrain: cfg.loopBrain || "" });
+          return;
+        }
+        if (req.method === "POST") {
+          const body = await readBody(req);
+          const cfg = readCfg();
+          cfg.loopBrain = body.loopBrain || "";
+          writeCfg(cfg);
+          console.log(`[crew-lead] Loop brain → ${cfg.loopBrain || "(cleared)"}`);
+          json(res, 200, { ok: true, loopBrain: cfg.loopBrain });
+          return;
+        }
+      }
+
+      // GET /api/settings/openclaw-status
+      if (url.pathname === "/api/settings/openclaw-status" && req.method === "GET") {
+        if (!checkBearer(req)) { json(res, 401, { ok: false, error: "Unauthorized" }); return; }
+        const cfg = readCfg();
+        const installed = !!(cfg.openClaw?.enabled || cfg.openclaw?.gatewayUrl || process.env.OPENCLAW_GATEWAY_URL);
+        json(res, 200, { ok: true, installed });
+        return;
+      }
+
+      // GET/POST /api/settings/rt-token
+      if (url.pathname === "/api/settings/rt-token") {
+        if (!checkBearer(req)) { json(res, 401, { ok: false, error: "Unauthorized" }); return; }
+        if (req.method === "GET") {
+          const cfg = readCfg();
+          const token = cfg.rtToken || process.env.CREWSWARM_RT_AUTH_TOKEN || "";
+          json(res, 200, { ok: true, token: token ? true : false });
+          return;
+        }
+        if (req.method === "POST") {
+          const body = await readBody(req);
+          if (!body.token) { json(res, 400, { ok: false, error: "No token provided" }); return; }
+          const cfg = readCfg();
+          cfg.rtToken = body.token;
+          writeCfg(cfg);
+          console.log("[crew-lead] RT token saved via dashboard");
+          json(res, 200, { ok: true, saved: true });
+          return;
+        }
+      }
+
+      // GET /api/config/lock-status, POST /api/config/lock, POST /api/config/unlock
+      if (url.pathname === "/api/config/lock-status" && req.method === "GET") {
+        if (!checkBearer(req)) { json(res, 401, { ok: false, error: "Unauthorized" }); return; }
+        const lockFile = path.join(os.homedir(), ".crewswarm", ".config.lock");
+        json(res, 200, { ok: true, locked: fs.existsSync(lockFile) });
+        return;
+      }
+      if (url.pathname === "/api/config/lock" && req.method === "POST") {
+        if (!checkBearer(req)) { json(res, 401, { ok: false, error: "Unauthorized" }); return; }
+        const lockFile = path.join(os.homedir(), ".crewswarm", ".config.lock");
+        try {
+          fs.writeFileSync(lockFile, new Date().toISOString());
+          console.log("[crew-lead] Config LOCKED via dashboard");
+          json(res, 200, { ok: true, locked: true });
+        } catch (e) { json(res, 500, { ok: false, error: e.message }); }
+        return;
+      }
+      if (url.pathname === "/api/config/unlock" && req.method === "POST") {
+        if (!checkBearer(req)) { json(res, 401, { ok: false, error: "Unauthorized" }); return; }
+        const lockFile = path.join(os.homedir(), ".crewswarm", ".config.lock");
+        try {
+          fs.unlinkSync(lockFile);
+          console.log("[crew-lead] Config UNLOCKED via dashboard");
+        } catch {}
+        json(res, 200, { ok: true, locked: false });
+        return;
+      }
+
       // POST /api/spending/reset — reset today's spending counters
       if (url.pathname === "/api/spending/reset" && req.method === "POST") {
         if (!checkBearer(req)) {

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

@@ -11,6 +11,8 @@ import { randomUUID } from "node:crypto";
 import { getStatePath, getConfigPath } from "../runtime/paths.mjs";
 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";
 
 let _deps = {};
 
@@ -425,6 +427,11 @@ export function dispatchPipelineWave(pipelineId) {
       ...(step.verify ? { verify: step.verify } : {}),
       ...(step.done   ? { done:   step.done   } : {}),
     };
+    // Build session handoff metadata for tmux-bridge
+    const sessionMeta = {};
+    if (step.session) sessionMeta.session = step.session;
+    else if (pipeline._tmuxSessionId) sessionMeta.session = `handoff:${pipeline._tmuxSessionId}`;
+
     const taskId = dispatchTask(step.agent, stepSpec, sessionId, {
       pipelineId,
       waveIndex: currentWave,
@@ -434,6 +441,7 @@ export function dispatchPipelineWave(pipelineId) {
       originThreadId: pipeline.originThreadId,
       originMessageId: pipeline.originMessageId,
       triggeredBy: pipeline.triggeredBy || "pipeline",
+      ...sessionMeta,
     });
     if (taskId && taskId !== true) pipeline.pendingTaskIds.add(taskId);
   }
@@ -762,6 +770,36 @@ export function dispatchTask(agent, task, sessionId = "owner", pipelineMeta = nu
       if (pipelineMeta?.mentionedBy) extraFlags.mentionedBy = pipelineMeta.mentionedBy;
       if (pipelineMeta?.autonomous !== undefined) extraFlags.autonomous = pipelineMeta.autonomous;
 
+      // ── tmux session handoff ──────────────────────────────────────────────
+      // If pipelineMeta carries a tmux session, hand it off to this agent
+      // or create a new one if session: "persist" is set.
+      if (tmuxBridge.detect()) {
+        const sessionSpec = pipelineMeta?.session;
+        if (typeof sessionSpec === "string" && sessionSpec.startsWith("handoff:")) {
+          const existingSessionId = sessionSpec.slice("handoff:".length);
+          const prevOwner = sessionManager.getSession(existingSessionId)?.owner;
+          if (prevOwner) {
+            sessionManager.handoff(existingSessionId, prevOwner, agent);
+          }
+          const meta = sessionManager.getSession(existingSessionId);
+          if (meta?.paneId) extraFlags.tmuxSessionId = meta.paneId;
+        } else if (sessionSpec === "persist") {
+          const newSessionId = sessionManager.create({
+            workspaceId: pipelineMeta?.pipelineId || "default",
+            agentId: agent,
+            cwd: pipelineMeta?.projectDir || undefined,
+          });
+          if (newSessionId) {
+            const meta = sessionManager.getSession(newSessionId);
+            if (meta?.paneId) extraFlags.tmuxSessionId = meta.paneId;
+            // Store session ID on pipeline meta so next wave can handoff
+            if (pipelineMeta) pipelineMeta._tmuxSessionId = newSessionId;
+          }
+        } else if (pipelineMeta?.tmuxSessionId) {
+          extraFlags.tmuxSessionId = pipelineMeta.tmuxSessionId;
+        }
+      }
+
       // Log enrichment for verification
       const engineFlags = Object.keys(extraFlags).filter(k => k.startsWith('use') || k.includes('Model') || k === 'engine');
       if (engineFlags.length > 0) {

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 {} */
@@ -1207,6 +1223,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/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,6 +1,6 @@
 {
   "name": "crewswarm",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Local-first multi-agent orchestration platform — coordinate AI coding agents, LLMs, and tools from a single dashboard",
   "type": "module",
   "license": "MIT",