ac-framework 2.1.0 → 2.3.0

package/README.md

@@ -142,6 +142,7 @@ Each role runs in turn against a shared, accumulating context so outputs from on
 |---|---|
 | `acfm agents setup` | Install optional dependencies (`opencode` and `zellij`/`tmux`) |
 | `acfm agents doctor` | Validate OpenCode/multiplexer/model preflight before start |
+| `acfm agents doctor --verbose` | Include zellij capability probe details for strategy diagnostics |
 | `acfm agents install-mcps` | Install SynapseGrid MCP server for detected assistants |
 | `acfm agents uninstall-mcps` | Remove SynapseGrid MCP server from assistants |
 | `acfm agents start --task "..." --model-coder provider/model` | Start session with optional per-role models |
@@ -190,6 +191,7 @@ When driving SynapseGrid from another agent via MCP, prefer asynchronous run too
 - Default SynapseGrid model fallback is `opencode/mimo-v2-pro-free`.
 - Run `acfm agents doctor` when panes look idle to confirm model/provider preflight health.
 - When zellij is managed by AC Framework, its binary path is saved in `~/.acfm/config.json` and executed directly by SynapseGrid.
+- `acfm agents start --json` now includes startup strategy diagnostics for zellij (`attach_with_layout`, fallbacks, and per-strategy errors).
 
 Each collaborative session now keeps human-readable artifacts under `~/.acfm/synapsegrid/<sessionId>/`:
 - `transcript.jsonl`: full chronological message stream

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ac-framework",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Agentic Coding Framework - Multi-assistant configuration system with OpenSpec workflows",
   "main": "src/index.js",
   "exports": {

package/src/agents/runtime.js

@@ -47,8 +47,80 @@ function sleep(ms) {
   return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
 }
 
+function stripAnsi(text) {
+  return String(text || '').replace(/\x1B\[[0-9;]*m/g, '');
+}
+
+async function commandSupports(command, args, pattern, runner) {
+  try {
+    const result = await runner(command, args);
+    return pattern.test(`${result.stdout || ''}\n${result.stderr || ''}`);
+  } catch {
+    return false;
+  }
+}
+
+export async function probeZellijCapabilities(binaryPath, options = {}) {
+  const runner = options.runCommandImpl || runCommand;
+  const command = binaryPath || process.env.ACFM_ZELLIJ_BIN || 'zellij';
+  const capabilities = {
+    binary: command,
+    version: null,
+    attachCreateBackground: false,
+    actionNewTabLayout: false,
+    actionNewPane: false,
+    listPanesJson: false,
+    setupCheck: false,
+  };
+
+  try {
+    const versionResult = await runner(command, ['--version']);
+    capabilities.version = stripAnsi(versionResult.stdout || versionResult.stderr || '').trim() || null;
+  } catch {
+    capabilities.version = null;
+  }
+
+  capabilities.attachCreateBackground = await commandSupports(
+    command,
+    ['attach', '--help'],
+    /--create-background/,
+    runner,
+  );
+  capabilities.actionNewTabLayout = await commandSupports(
+    command,
+    ['action', 'new-tab', '--help'],
+    /--layout/,
+    runner,
+  );
+  capabilities.actionNewPane = await commandSupports(
+    command,
+    ['action', 'new-pane', '--help'],
+    /USAGE:/,
+    runner,
+  );
+  capabilities.listPanesJson = await commandSupports(
+    command,
+    ['action', 'list-panes', '--help'],
+    /--json/,
+    runner,
+  );
+  capabilities.setupCheck = await commandSupports(
+    command,
+    ['setup', '--help'],
+    /--check/,
+    runner,
+  );
+
+  return capabilities;
+}
+
+function workerShellCommand(sessionId, role, roleLog) {
+  return `node "${runnerPath}" agents worker --session ${sessionId} --role ${role} 2>&1 | tee -a "${roleLog}"`;
+}
+
 function workerCommand(sessionId, role, roleLog) {
-  return `bash -lc 'node "${runnerPath}" agents worker --session ${sessionId} --role ${role} 2>&1 | tee -a "${roleLog}"'`;
+  const shell = workerShellCommand(sessionId, role, roleLog);
+  return `bash -lc '${shell}'`;
 }
 
 export async function runTmux(command, args, options = {}) {
@@ -95,26 +167,26 @@ export async function tmuxSessionExists(sessionName) {
 }
 
 async function writeZellijLayout({ layoutPath, sessionId, sessionDir }) {
-  const panes = COLLAB_ROLES.map((role) => {
+  const paneNode = (role) => {
     const roleLog = roleLogPath(sessionDir, role);
     const cmd = workerCommand(sessionId, role, roleLog).replace(/"/g, '\\"');
-    return `                    pane name="${role}" command="bash" args { "-lc" "${cmd}" }`;
-  });
+    return [
+      `                    pane name="${role}" command="bash" {`,
+      `                        args "-lc" "${cmd}"`,
+      '                    }',
+    ].join('\n');
+  };
 
   const content = [
     'layout {',
-    '    default_tab_template {',
-    '        tab name="SynapseGrid" {',
-    '            pane split_direction="vertical" {',
-    '                pane split_direction="horizontal" {',
-    panes[0],
-    panes[1],
-    '                }',
-    '                pane split_direction="horizontal" {',
-    panes[2],
-    panes[3],
-    '                }',
-    '            }',
+    '    pane split_direction="vertical" {',
+    '        pane split_direction="horizontal" {',
+    paneNode(COLLAB_ROLES[0]),
+    paneNode(COLLAB_ROLES[1]),
+    '        }',
+    '        pane split_direction="horizontal" {',
+    paneNode(COLLAB_ROLES[2]),
+    paneNode(COLLAB_ROLES[3]),
     '        }',
     '    }',
     '}',
@@ -132,36 +204,114 @@ export async function spawnZellijSession({
   waitForSessionMs = 10000,
   pollIntervalMs = 250,
   runCommandImpl,
-  spawnImpl,
+  capabilities = null,
 }) {
   const layoutPath = resolve(sessionDir, 'synapsegrid-layout.kdl');
   await writeZellijLayout({ layoutPath, sessionId, sessionDir });
   const command = binaryPath || process.env.ACFM_ZELLIJ_BIN || 'zellij';
+  const runner = runCommandImpl || runCommand;
+  const caps = capabilities || await probeZellijCapabilities(binaryPath, { runCommandImpl: runner });
+  const strategyErrors = [];
 
-  const spawnFn = spawnImpl || spawn;
-  const child = spawnFn(command, ['--session', sessionName, '--layout', layoutPath], {
-    cwd: sessionDir,
-    env: process.env,
-    detached: true,
-    stdio: 'ignore',
-  });
-  if (typeof child.unref === 'function') {
-    child.unref();
+  const existing = await zellijSessionExists(sessionName, binaryPath, { runCommandImpl: runner });
+  if (existing) {
+    return { layoutPath, strategy: 'already_exists', capabilities: caps, strategyErrors };
+  }
+
+  const strategies = [];
+  if (caps.attachCreateBackground) {
+    strategies.push({
+      name: 'attach_with_layout',
+      run: async () => {
+        await runner(command, ['--layout', layoutPath, 'attach', '--create-background', sessionName], {
+          cwd: sessionDir,
+        });
+      },
+    });
+  }
+
+  if (caps.attachCreateBackground && caps.actionNewTabLayout) {
+    strategies.push({
+      name: 'attach_then_newtab_layout',
+      run: async () => {
+        await runner(command, ['attach', '--create-background', sessionName], { cwd: sessionDir });
+        await runner(command, ['--session', sessionName, 'action', 'new-tab', '--name', 'SynapseGrid', '--layout', layoutPath], {
+          cwd: sessionDir,
+        });
+      },
+    });
+  }
+
+  if (caps.attachCreateBackground && caps.actionNewPane) {
+    strategies.push({
+      name: 'attach_then_action_panes',
+      run: async () => {
+        await runner(command, ['attach', '--create-background', sessionName], { cwd: sessionDir });
+        const role0 = COLLAB_ROLES[0];
+        const role0Log = roleLogPath(sessionDir, role0);
+        await runner(
+          command,
+          ['--session', sessionName, 'action', 'new-tab', '--name', 'SynapseGrid', '--', 'bash', '-lc', workerShellCommand(sessionId, role0, role0Log)],
+          { cwd: sessionDir },
+        );
+
+        const role1 = COLLAB_ROLES[1];
+        const role1Log = roleLogPath(sessionDir, role1);
+        await runner(
+          command,
+          ['--session', sessionName, 'action', 'new-pane', '--direction', 'right', '--', 'bash', '-lc', workerShellCommand(sessionId, role1, role1Log)],
+          { cwd: sessionDir },
+        );
+
+        const role2 = COLLAB_ROLES[2];
+        const role2Log = roleLogPath(sessionDir, role2);
+        await runner(
+          command,
+          ['--session', sessionName, 'action', 'new-pane', '--direction', 'down', '--', 'bash', '-lc', workerShellCommand(sessionId, role2, role2Log)],
+          { cwd: sessionDir },
+        );
+
+        const role3 = COLLAB_ROLES[3];
+        const role3Log = roleLogPath(sessionDir, role3);
+        await runner(
+          command,
+          ['--session', sessionName, 'action', 'new-pane', '--direction', 'right', '--', 'bash', '-lc', workerShellCommand(sessionId, role3, role3Log)],
+          { cwd: sessionDir },
+        );
+      },
+    });
+  }
+
+  let strategyUsed = null;
+  for (const strategy of strategies) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      await strategy.run();
+      strategyUsed = strategy.name;
+      break;
+    } catch (error) {
+      strategyErrors.push({ strategy: strategy.name, error: error.message });
+    }
+  }
+
+  if (!strategyUsed) {
+    const details = strategyErrors.map((item) => `${item.strategy}: ${item.error}`).join(' | ');
+    throw new Error(`Unable to initialize zellij session using supported strategies. ${details || 'No compatible strategy available.'}`);
   }
 
   const startedAt = Date.now();
   while ((Date.now() - startedAt) < waitForSessionMs) {
     // eslint-disable-next-line no-await-in-loop
-    const exists = await zellijSessionExists(sessionName, binaryPath, { runCommandImpl });
+    const exists = await zellijSessionExists(sessionName, binaryPath, { runCommandImpl: runner });
     if (exists) {
-      return { layoutPath };
+      return { layoutPath, strategy: strategyUsed, capabilities: caps, strategyErrors };
     }
     // eslint-disable-next-line no-await-in-loop
     await sleep(pollIntervalMs);
   }
 
   throw new Error(
-    `Timed out waiting for zellij session '${sessionName}' to start (binary: ${command}). ` +
+    `Timed out waiting for zellij session '${sessionName}' to start (binary: ${command}, strategy: ${strategyUsed || 'none'}). ` +
     'Try `acfm agents doctor` or fallback with `acfm agents start --mux tmux ...`'
   );
 }
@@ -171,8 +321,14 @@ export async function zellijSessionExists(sessionName, binaryPath, options = {})
     const runner = options.runCommandImpl || runCommand;
     const command = binaryPath || process.env.ACFM_ZELLIJ_BIN || 'zellij';
     const result = await runner(command, ['list-sessions']);
-    const lines = result.stdout.split('\n').map((line) => line.trim()).filter(Boolean);
-    return lines.some((line) => line === sessionName || line.startsWith(`${sessionName} `));
+    const lines = stripAnsi(result.stdout)
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean);
+    return lines.some((line) => {
+      if (line === sessionName || line.startsWith(`${sessionName} `)) return true;
+      return line.includes(sessionName);
+    });
   } catch {
     return false;
   }

package/src/commands/agents.js

@@ -31,6 +31,7 @@ import {
   writeMeetingSummary,
 } from '../agents/state-store.js';
 import {
+  probeZellijCapabilities,
   roleLogPath,
   runTmux,
   runZellij,
@@ -153,6 +154,16 @@ async function attachToMux(multiplexer, sessionName, readonly = false, zellijPat
   await runTmux('tmux', args, { stdio: 'inherit' });
 }
 
+async function readZellijCapabilities(config) {
+  const zellijPath = resolveConfiguredZellijPath(config);
+  if (!zellijPath) return null;
+  try {
+    return await probeZellijCapabilities(zellijPath);
+  } catch {
+    return null;
+  }
+}
+
 function toMarkdownTranscript(state, transcript) {
   const displayedRound = Math.min(state.round, state.maxRounds);
   const lines = [
@@ -1270,6 +1281,7 @@ Examples:
         const muxResolution = resolveMultiplexerWithPaths(config, configuredMux);
         let selectedMux = muxResolution.selected;
         let zellijPath = muxResolution.zellijPath;
+        const tmuxPath = muxResolution.tmuxPath;
         if (!selectedMux) {
           if (configuredMux !== 'tmux' && shouldUseManagedZellij(config)) {
             const installResult = await installManagedZellijLatest();
@@ -1336,41 +1348,64 @@ Examples:
         const muxSessionName = `acfm-synapse-${state.sessionId.slice(0, 8)}`;
         const sessionDir = getSessionDir(state.sessionId);
 
-        if (selectedMux === 'zellij') {
-          await spawnZellijSession({
-            sessionName: muxSessionName,
-            sessionDir,
-            sessionId: state.sessionId,
-            binaryPath: zellijPath,
-          });
-        } else {
+        let activeMux = selectedMux;
+        let startupDiagnostics = null;
+        try {
+          if (selectedMux === 'zellij') {
+            startupDiagnostics = await spawnZellijSession({
+              sessionName: muxSessionName,
+              sessionDir,
+              sessionId: state.sessionId,
+              binaryPath: zellijPath,
+            });
+          } else {
+            await spawnTmuxSession({
+              sessionName: muxSessionName,
+              sessionDir,
+              sessionId: state.sessionId,
+            });
+          }
+        } catch (muxError) {
+          const canFallbackToTmux = configuredMux === 'auto' && selectedMux === 'zellij' && Boolean(tmuxPath);
+          if (!canFallbackToTmux) {
+            throw muxError;
+          }
+
+          if (!opts.json) {
+            console.log(chalk.yellow(`zellij startup failed, falling back to tmux: ${muxError.message}`));
+          }
           await spawnTmuxSession({
             sessionName: muxSessionName,
             sessionDir,
             sessionId: state.sessionId,
           });
+          activeMux = 'tmux';
         }
 
         const updated = await saveSessionState({
           ...state,
-          multiplexer: selectedMux,
+          multiplexer: activeMux,
           multiplexerSessionName: muxSessionName,
-          tmuxSessionName: selectedMux === 'tmux' ? muxSessionName : null,
+          tmuxSessionName: activeMux === 'tmux' ? muxSessionName : null,
         });
 
         output({
           sessionId: updated.sessionId,
-          multiplexer: selectedMux,
+          multiplexer: activeMux,
           multiplexerSessionName: muxSessionName,
           status: updated.status,
+          startupDiagnostics,
         }, opts.json);
         if (!opts.json) {
           printStartSummary(updated);
+          if (startupDiagnostics?.strategy) {
+            console.log(chalk.dim(`  zellij strategy: ${startupDiagnostics.strategy}`));
+          }
           printModelConfig(updated);
         }
 
         if (opts.attach) {
-          await attachToMux(selectedMux, muxSessionName, false, zellijPath);
+          await attachToMux(activeMux, muxSessionName, false, zellijPath);
         }
       } catch (error) {
         output({ error: error.message }, opts.json);
@@ -1503,7 +1538,15 @@ Examples:
           try {
             await runZellij(['delete-session', muxSessionName], { binaryPath: zellijPath });
           } catch {
-            // ignore if already closed
+            try {
+              await runZellij(['kill-session', muxSessionName], { binaryPath: zellijPath });
+            } catch {
+              try {
+                await runZellij(['delete-session', '--force', muxSessionName], { binaryPath: zellijPath });
+              } catch {
+                // ignore if already closed
+              }
+            }
           }
         }
         if (multiplexer === 'tmux' && muxSessionName && hasCommand('tmux')) {
@@ -1608,6 +1651,7 @@ Examples:
   agents
     .command('doctor')
     .description('Run diagnostics for SynapseGrid/OpenCode runtime')
+    .option('--verbose', 'Include backend capability details', false)
     .option('--json', 'Output as JSON')
     .action(async (opts) => {
       try {
@@ -1630,8 +1674,13 @@ Examples:
           defaultModel,
           defaultRoleModels: cfg.agents.defaultRoleModels,
           preflight: null,
+          zellijCapabilities: null,
         };
 
+        if (opts.verbose && zellijPath) {
+          result.zellijCapabilities = await readZellijCapabilities(cfg);
+        }
+
         if (opencodeBin) {
           result.preflight = await preflightModel({
             opencodeBin,

package/src/mcp/collab-server.js

@@ -18,6 +18,7 @@ import { buildEffectiveRoleModels, sanitizeRoleModels } from '../agents/model-se
 import { runWorkerIteration } from '../agents/orchestrator.js';
 import { getSessionDir } from '../agents/state-store.js';
 import {
+  probeZellijCapabilities,
   spawnTmuxSession,
   spawnZellijSession,
   tmuxSessionExists,
@@ -84,6 +85,16 @@ function resolveConfiguredZellijPath(config) {
   return resolveCommandPath('zellij');
 }
 
+async function readZellijCapabilities(config) {
+  const zellijPath = resolveConfiguredZellijPath(config);
+  if (!zellijPath) return null;
+  try {
+    return await probeZellijCapabilities(zellijPath);
+  } catch {
+    return null;
+  }
+}
+
 async function muxExists(multiplexer, sessionName, zellijPath = null) {
   if (multiplexer === 'zellij') return zellijSessionExists(sessionName, zellijPath);
   return tmuxSessionExists(sessionName);
@@ -152,7 +163,13 @@ class MCPCollabServer {
             const sessionName = `acfm-synapse-${state.sessionId.slice(0, 8)}`;
             const sessionDir = getSessionDir(state.sessionId);
             if (multiplexer === 'zellij') {
-              await spawnZellijSession({ sessionName, sessionDir, sessionId: state.sessionId, binaryPath: zellijPath });
+              await spawnZellijSession({
+                sessionName,
+                sessionDir,
+                sessionId: state.sessionId,
+                binaryPath: zellijPath,
+                capabilities: await readZellijCapabilities(config),
+              });
             } else {
               await spawnTmuxSession({ sessionName, sessionDir, sessionId: state.sessionId });
             }
@@ -477,7 +494,13 @@ class MCPCollabServer {
             const sessionDir = getSessionDir(state.sessionId);
             if (multiplexer === 'zellij') {
               if (!zellijPath) throw new Error('zellij is not installed. Run: acfm agents setup');
-              await spawnZellijSession({ sessionName, sessionDir, sessionId: state.sessionId, binaryPath: zellijPath });
+              await spawnZellijSession({
+                sessionName,
+                sessionDir,
+                sessionId: state.sessionId,
+                binaryPath: zellijPath,
+                capabilities: await readZellijCapabilities(config),
+              });
             } else {
               if (!hasCommand('tmux')) throw new Error('tmux is not installed. Run: acfm agents setup');
               await spawnTmuxSession({ sessionName, sessionDir, sessionId: state.sessionId });