ac-framework 2.2.0 → 2.4.0

package/framework/web_development/CLAUDE.md

@@ -15,6 +15,7 @@ If you attempt to proceed without completing a required step, you MUST STOP and
 | Skill | Description | Primary Use | Required Before |
 |-------|-------------|-------------|-----------------|
 | `secure-coding-cybersecurity` | Detects and prevents security vulnerabilities (SQLi, XSS, command injection, hardcoded secrets). Follows OWASP Top 10 standards. | Secure code validation | `code-maintainability` |
+| `vibe-security` | Final security audit focused on AI-generated/vibe-coded risks (exposed keys, broken access control, auth/payment/data validation gaps). | Final security validation before closure | `openspec-archive-change` |
 | `code-maintainability` | Analyzes code maintainability: duplication, documentation, error handling, naming conventions, SOLID architecture, performance. | Refactoring and standards | `project-constitution` |
 | `error-handling-patterns` | Error handling patterns in multiple languages: exceptions, Result types, retry, circuit breaker, graceful degradation. | Application resilience | `secure-coding-cybersecurity` |
 | `performance-optimizer` | Methodologies for measuring, profiling, and optimizing code (caching, algorithm complexity, resource usage). | Performance Engineering | After Implementation |
@@ -99,6 +100,80 @@ acfm memory stats
 **User communication:** "Memory saved: [brief description]" when auto-saving occurs.
 
 
+
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**When to delegate to SynapseGrid:**
+- Multi-step features with architecture + implementation + review work
+- Tasks requiring critical analysis before coding (security, API contracts, refactors)
+- Long-running work where transcript, artifacts, and resumability are important
+- Situations where one assistant would benefit from role-based challenge/review
+
+**Role delegation model (what each agent does best):**
+- `planner`: breaks down scope, constraints, approach, acceptance criteria
+- `critic`: challenges assumptions, finds risks/blind spots, proposes safer alternatives
+- `coder`: implements code and applies concrete changes
+- `reviewer`: validates quality, consistency with spec/tasks, and production readiness
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer SynapseGrid MCP tools for start/wait/result/cancel/status flows.
+2. Use transcript + meeting summary + artifacts as source of truth.
+3. If collaborative MCP is unavailable, use equivalent CLI commands.
+
+**Preferred MCP flow (recommended):**
+1. `collab_start_session`
+2. `collab_invoke_team`
+3. `collab_wait_run`
+4. `collab_get_result`
+5. Optional diagnostics: `collab_get_transcript`, `collab_get_meeting_log`, `collab_status`
+
+**CLI fallback and operations:**
+```bash
+# Setup/runtime
+acfm agents setup
+acfm agents runtime install-zellij
+acfm agents runtime set auto
+acfm agents doctor --verbose
+
+# Start/run
+acfm agents start --task "design and implement feature X" --mux auto
+acfm agents live
+acfm agents status
+
+# Visibility and artifacts
+acfm agents transcript --role all --limit 80
+acfm agents summary
+acfm agents artifacts --watch --interval 1200
+acfm agents export --format md --out synapse-session.md
+
+# Model management
+acfm agents model list
+acfm agents model choose
+acfm agents model set --role coder provider/model
+
+# Lifecycle
+acfm agents resume
+acfm agents stop
+```
+
+**Collaboration artifacts (deterministic, not prompt-dependent):**
+- `~/.acfm/synapsegrid/<sessionId>/transcript.jsonl`
+- `~/.acfm/synapsegrid/<sessionId>/meeting-log.md`
+- `~/.acfm/synapsegrid/<sessionId>/meeting-summary.md`
+- `~/.acfm/synapsegrid/<sessionId>/turns/*.json`
+- `~/.acfm/synapsegrid/<sessionId>/turns/raw/*.ndjson`
+- `~/.acfm/synapsegrid/<sessionId>/turns/raw/*.stderr.log`
+- `~/.acfm/synapsegrid/<sessionId>/diagnostics.json`
+
+**Troubleshooting and robust behavior:**
+- Use `acfm agents doctor --verbose` for capability probe diagnostics.
+- In `--mux auto`, runtime prefers zellij and falls back to tmux when zellij startup fails.
+- If model/provider errors appear, validate with `opencode auth list` and `opencode models`.
+- If workers are running but unclear, inspect `logs`, `transcript`, and `artifacts` before restarting.
+
+
 ### OpenSpec Skills (The heart of the framework)
 
 | Skill | Description | Primary Use | Required Before |
@@ -169,7 +244,7 @@ Before proceeding to next phase, verify you have these outputs:
 | Phase 2 | project-index.md exists, exploration notes | [ ] |
 | Phase 3 | proposal.md, specs/, design.md, tasks.md | [ ] |
 | Phase 4 | Tests written, code implemented, tasks marked complete | [ ] |
-| Phase 5 | Verification passed, docs updated, change archived | [ ] |
+| Phase 5 | Verification passed, `vibe-security` audit complete, docs updated, change archived | [ ] |
 
 **Rule 4: Pre-Implementation Safety Check**
 Before `openspec-apply-change`, ALL must be TRUE:
@@ -331,15 +406,17 @@ When starting a project **from scratch**, follow this **MANDATORY** workflow:
     ║      └─ Resolve any issues                   ║
     ║  26. openspec-verify-change                  ║
     ║      └─ Validate against specs               ║
-    ║  27. documentation                           ║
+    ║  27. vibe-security                           ║
+    ║      └─ Final security audit before closure  ║
+    ║  28. documentation                           ║
     ║      └─ Generate technical docs & diagrams   ║
-    ║  28. sync-index                              ║
+    ║  29. sync-index                              ║
     ║      └─ Update project documentation         ║
-    ║  29. changelog-generator                     ║
+    ║  30. changelog-generator                     ║
     ║      └─ Generate release notes               ║
-    ║  30. ci-deploy                               ║
+    ║  31. ci-deploy                               ║
     ║      └─ Deploy and verify solution           ║
-    ║  31. openspec-archive-change                 ║
+    ║  32. openspec-archive-change                 ║
     ║      └─ Archive the change                   ║
     ╚══════════════════════════════════════════════╝
 ```
@@ -457,15 +534,17 @@ When working on an **existing codebase** (adding features, fixing bugs, refactor
     ║      └─ Fix regressions                      ║
     ║  23. openspec-verify-change                  ║
     ║      └─ Final verification                   ║
-    ║  24. documentation                           ║
+    ║  24. vibe-security                           ║
+    ║      └─ Final security audit before closure  ║
+    ║  25. documentation                           ║
     ║      └─ Generate technical docs & diagrams   ║
-    ║  25. sync-index (IMPORTANT)                  ║
+    ║  26. sync-index (IMPORTANT)                  ║
     ║      └─ Update docs with new changes         ║
-    ║  26. changelog-generator                     ║
+    ║  27. changelog-generator                     ║
     ║      └─ Generate release notes               ║
-    ║  27. ci-deploy                               ║
+    ║  28. ci-deploy                               ║
     ║      └─ Deploy and verify solution           ║
-    ║  28. openspec-archive-change                 ║
+    ║  29. openspec-archive-change                 ║
     ║      └─ Archive change                       ║
     ╚══════════════════════════════════════════════╝
 ```

package/framework/web_development/GEMINI.md

@@ -15,6 +15,7 @@ If you attempt to proceed without completing a required step, you MUST STOP and
 | Skill | Description | Primary Use | Required Before |
 |-------|-------------|-------------|-----------------|
 | `secure-coding-cybersecurity` | Detects and prevents security vulnerabilities (SQLi, XSS, command injection, hardcoded secrets). Follows OWASP Top 10 standards. | Secure code validation | `code-maintainability` |
+| `vibe-security` | Final security audit focused on AI-generated/vibe-coded risks (exposed keys, broken access control, auth/payment/data validation gaps). | Final security validation before closure | `openspec-archive-change` |
 | `code-maintainability` | Analyzes code maintainability: duplication, documentation, error handling, naming conventions, SOLID architecture, performance. | Refactoring and standards | `project-constitution` |
 | `error-handling-patterns` | Error handling patterns in multiple languages: exceptions, Result types, retry, circuit breaker, graceful degradation. | Application resilience | `secure-coding-cybersecurity` |
 | `performance-optimizer` | Methodologies for measuring, profiling, and optimizing code (caching, algorithm complexity, resource usage). | Performance Engineering | After Implementation |
@@ -99,6 +100,80 @@ acfm memory stats
 **User communication:** "Memory saved: [brief description]" when auto-saving occurs.
 
 
+
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**When to delegate to SynapseGrid:**
+- Multi-step features with architecture + implementation + review work
+- Tasks requiring critical analysis before coding (security, API contracts, refactors)
+- Long-running work where transcript, artifacts, and resumability are important
+- Situations where one assistant would benefit from role-based challenge/review
+
+**Role delegation model (what each agent does best):**
+- `planner`: breaks down scope, constraints, approach, acceptance criteria
+- `critic`: challenges assumptions, finds risks/blind spots, proposes safer alternatives
+- `coder`: implements code and applies concrete changes
+- `reviewer`: validates quality, consistency with spec/tasks, and production readiness
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer SynapseGrid MCP tools for start/wait/result/cancel/status flows.
+2. Use transcript + meeting summary + artifacts as source of truth.
+3. If collaborative MCP is unavailable, use equivalent CLI commands.
+
+**Preferred MCP flow (recommended):**
+1. `collab_start_session`
+2. `collab_invoke_team`
+3. `collab_wait_run`
+4. `collab_get_result`
+5. Optional diagnostics: `collab_get_transcript`, `collab_get_meeting_log`, `collab_status`
+
+**CLI fallback and operations:**
+```bash
+# Setup/runtime
+acfm agents setup
+acfm agents runtime install-zellij
+acfm agents runtime set auto
+acfm agents doctor --verbose
+
+# Start/run
+acfm agents start --task "design and implement feature X" --mux auto
+acfm agents live
+acfm agents status
+
+# Visibility and artifacts
+acfm agents transcript --role all --limit 80
+acfm agents summary
+acfm agents artifacts --watch --interval 1200
+acfm agents export --format md --out synapse-session.md
+
+# Model management
+acfm agents model list
+acfm agents model choose
+acfm agents model set --role coder provider/model
+
+# Lifecycle
+acfm agents resume
+acfm agents stop
+```
+
+**Collaboration artifacts (deterministic, not prompt-dependent):**
+- `~/.acfm/synapsegrid/<sessionId>/transcript.jsonl`
+- `~/.acfm/synapsegrid/<sessionId>/meeting-log.md`
+- `~/.acfm/synapsegrid/<sessionId>/meeting-summary.md`
+- `~/.acfm/synapsegrid/<sessionId>/turns/*.json`
+- `~/.acfm/synapsegrid/<sessionId>/turns/raw/*.ndjson`
+- `~/.acfm/synapsegrid/<sessionId>/turns/raw/*.stderr.log`
+- `~/.acfm/synapsegrid/<sessionId>/diagnostics.json`
+
+**Troubleshooting and robust behavior:**
+- Use `acfm agents doctor --verbose` for capability probe diagnostics.
+- In `--mux auto`, runtime prefers zellij and falls back to tmux when zellij startup fails.
+- If model/provider errors appear, validate with `opencode auth list` and `opencode models`.
+- If workers are running but unclear, inspect `logs`, `transcript`, and `artifacts` before restarting.
+
+
 ### OpenSpec Skills (The heart of the framework)
 
 | Skill | Description | Primary Use | Required Before |
@@ -169,7 +244,7 @@ Before proceeding to next phase, verify you have these outputs:
 | Phase 2 | project-index.md exists, exploration notes | [ ] |
 | Phase 3 | proposal.md, specs/, design.md, tasks.md | [ ] |
 | Phase 4 | Tests written, code implemented, tasks marked complete | [ ] |
-| Phase 5 | Verification passed, docs updated, change archived | [ ] |
+| Phase 5 | Verification passed, `vibe-security` audit complete, docs updated, change archived | [ ] |
 
 **Rule 4: Pre-Implementation Safety Check**
 Before `openspec-apply-change`, ALL must be TRUE:
@@ -331,15 +406,17 @@ When starting a project **from scratch**, follow this **MANDATORY** workflow:
     ║      └─ Resolve any issues                   ║
     ║  26. openspec-verify-change                  ║
     ║      └─ Validate against specs               ║
-    ║  27. documentation                           ║
+    ║  27. vibe-security                           ║
+    ║      └─ Final security audit before closure  ║
+    ║  28. documentation                           ║
     ║      └─ Generate technical docs & diagrams   ║
-    ║  28. sync-index                              ║
+    ║  29. sync-index                              ║
     ║      └─ Update project documentation         ║
-    ║  29. changelog-generator                     ║
+    ║  30. changelog-generator                     ║
     ║      └─ Generate release notes               ║
-    ║  30. ci-deploy                               ║
+    ║  31. ci-deploy                               ║
     ║      └─ Deploy and verify solution           ║
-    ║  31. openspec-archive-change                 ║
+    ║  32. openspec-archive-change                 ║
     ║      └─ Archive the change                   ║
     ╚══════════════════════════════════════════════╝
 ```
@@ -457,15 +534,17 @@ When working on an **existing codebase** (adding features, fixing bugs, refactor
     ║      └─ Fix regressions                      ║
     ║  23. openspec-verify-change                  ║
     ║      └─ Final verification                   ║
-    ║  24. documentation                           ║
+    ║  24. vibe-security                           ║
+    ║      └─ Final security audit before closure  ║
+    ║  25. documentation                           ║
     ║      └─ Generate technical docs & diagrams   ║
-    ║  25. sync-index (IMPORTANT)                  ║
+    ║  26. sync-index (IMPORTANT)                  ║
     ║      └─ Update docs with new changes         ║
-    ║  26. changelog-generator                     ║
+    ║  27. changelog-generator                     ║
     ║      └─ Generate release notes               ║
-    ║  27. ci-deploy                               ║
+    ║  28. ci-deploy                               ║
     ║      └─ Deploy and verify solution           ║
-    ║  28. openspec-archive-change                 ║
+    ║  29. openspec-archive-change                 ║
     ║      └─ Archive change                       ║
     ╚══════════════════════════════════════════════╝
 ```

package/framework/web_development/copilot-instructions.md

@@ -15,6 +15,7 @@ If you attempt to proceed without completing a required step, you MUST STOP and
 | Skill | Description | Primary Use | Required Before |
 |-------|-------------|-------------|-----------------|
 | `secure-coding-cybersecurity` | Detects and prevents security vulnerabilities (SQLi, XSS, command injection, hardcoded secrets). Follows OWASP Top 10 standards. | Secure code validation | `code-maintainability` |
+| `vibe-security` | Final security audit focused on AI-generated/vibe-coded risks (exposed keys, broken access control, auth/payment/data validation gaps). | Final security validation before closure | `openspec-archive-change` |
 | `code-maintainability` | Analyzes code maintainability: duplication, documentation, error handling, naming conventions, SOLID architecture, performance. | Refactoring and standards | `project-constitution` |
 | `error-handling-patterns` | Error handling patterns in multiple languages: exceptions, Result types, retry, circuit breaker, graceful degradation. | Application resilience | `secure-coding-cybersecurity` |
 | `performance-optimizer` | Methodologies for measuring, profiling, and optimizing code (caching, algorithm complexity, resource usage). | Performance Engineering | After Implementation |
@@ -99,6 +100,80 @@ acfm memory stats
 **User communication:** "Memory saved: [brief description]" when auto-saving occurs.
 
 
+
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**When to delegate to SynapseGrid:**
+- Multi-step features with architecture + implementation + review work
+- Tasks requiring critical analysis before coding (security, API contracts, refactors)
+- Long-running work where transcript, artifacts, and resumability are important
+- Situations where one assistant would benefit from role-based challenge/review
+
+**Role delegation model (what each agent does best):**
+- `planner`: breaks down scope, constraints, approach, acceptance criteria
+- `critic`: challenges assumptions, finds risks/blind spots, proposes safer alternatives
+- `coder`: implements code and applies concrete changes
+- `reviewer`: validates quality, consistency with spec/tasks, and production readiness
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer SynapseGrid MCP tools for start/wait/result/cancel/status flows.
+2. Use transcript + meeting summary + artifacts as source of truth.
+3. If collaborative MCP is unavailable, use equivalent CLI commands.
+
+**Preferred MCP flow (recommended):**
+1. `collab_start_session`
+2. `collab_invoke_team`
+3. `collab_wait_run`
+4. `collab_get_result`
+5. Optional diagnostics: `collab_get_transcript`, `collab_get_meeting_log`, `collab_status`
+
+**CLI fallback and operations:**
+```bash
+# Setup/runtime
+acfm agents setup
+acfm agents runtime install-zellij
+acfm agents runtime set auto
+acfm agents doctor --verbose
+
+# Start/run
+acfm agents start --task "design and implement feature X" --mux auto
+acfm agents live
+acfm agents status
+
+# Visibility and artifacts
+acfm agents transcript --role all --limit 80
+acfm agents summary
+acfm agents artifacts --watch --interval 1200
+acfm agents export --format md --out synapse-session.md
+
+# Model management
+acfm agents model list
+acfm agents model choose
+acfm agents model set --role coder provider/model
+
+# Lifecycle
+acfm agents resume
+acfm agents stop
+```
+
+**Collaboration artifacts (deterministic, not prompt-dependent):**
+- `~/.acfm/synapsegrid/<sessionId>/transcript.jsonl`
+- `~/.acfm/synapsegrid/<sessionId>/meeting-log.md`
+- `~/.acfm/synapsegrid/<sessionId>/meeting-summary.md`
+- `~/.acfm/synapsegrid/<sessionId>/turns/*.json`
+- `~/.acfm/synapsegrid/<sessionId>/turns/raw/*.ndjson`
+- `~/.acfm/synapsegrid/<sessionId>/turns/raw/*.stderr.log`
+- `~/.acfm/synapsegrid/<sessionId>/diagnostics.json`
+
+**Troubleshooting and robust behavior:**
+- Use `acfm agents doctor --verbose` for capability probe diagnostics.
+- In `--mux auto`, runtime prefers zellij and falls back to tmux when zellij startup fails.
+- If model/provider errors appear, validate with `opencode auth list` and `opencode models`.
+- If workers are running but unclear, inspect `logs`, `transcript`, and `artifacts` before restarting.
+
+
 ### OpenSpec Skills (The heart of the framework)
 
 | Skill | Description | Primary Use | Required Before |
@@ -169,7 +244,7 @@ Before proceeding to next phase, verify you have these outputs:
 | Phase 2 | project-index.md exists, exploration notes | [ ] |
 | Phase 3 | proposal.md, specs/, design.md, tasks.md | [ ] |
 | Phase 4 | Tests written, code implemented, tasks marked complete | [ ] |
-| Phase 5 | Verification passed, docs updated, change archived | [ ] |
+| Phase 5 | Verification passed, `vibe-security` audit complete, docs updated, change archived | [ ] |
 
 **Rule 4: Pre-Implementation Safety Check**
 Before `openspec-apply-change`, ALL must be TRUE:
@@ -331,15 +406,17 @@ When starting a project **from scratch**, follow this **MANDATORY** workflow:
     ║      └─ Resolve any issues                   ║
     ║  26. openspec-verify-change                  ║
     ║      └─ Validate against specs               ║
-    ║  27. documentation                           ║
+    ║  27. vibe-security                           ║
+    ║      └─ Final security audit before closure  ║
+    ║  28. documentation                           ║
     ║      └─ Generate technical docs & diagrams   ║
-    ║  28. sync-index                              ║
+    ║  29. sync-index                              ║
     ║      └─ Update project documentation         ║
-    ║  29. changelog-generator                     ║
+    ║  30. changelog-generator                     ║
     ║      └─ Generate release notes               ║
-    ║  30. ci-deploy                               ║
+    ║  31. ci-deploy                               ║
     ║      └─ Deploy and verify solution           ║
-    ║  31. openspec-archive-change                 ║
+    ║  32. openspec-archive-change                 ║
     ║      └─ Archive the change                   ║
     ╚══════════════════════════════════════════════╝
 ```
@@ -457,15 +534,17 @@ When working on an **existing codebase** (adding features, fixing bugs, refactor
     ║      └─ Fix regressions                      ║
     ║  23. openspec-verify-change                  ║
     ║      └─ Final verification                   ║
-    ║  24. documentation                           ║
+    ║  24. vibe-security                           ║
+    ║      └─ Final security audit before closure  ║
+    ║  25. documentation                           ║
     ║      └─ Generate technical docs & diagrams   ║
-    ║  25. sync-index (IMPORTANT)                  ║
+    ║  26. sync-index (IMPORTANT)                  ║
     ║      └─ Update docs with new changes         ║
-    ║  26. changelog-generator                     ║
+    ║  27. changelog-generator                     ║
     ║      └─ Generate release notes               ║
-    ║  27. ci-deploy                               ║
+    ║  28. ci-deploy                               ║
     ║      └─ Deploy and verify solution           ║
-    ║  28. openspec-archive-change                 ║
+    ║  29. openspec-archive-change                 ║
     ║      └─ Archive change                       ║
     ╚══════════════════════════════════════════════╝
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ac-framework",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Agentic Coding Framework - Multi-assistant configuration system with OpenSpec workflows",
   "main": "src/index.js",
   "exports": {
@@ -42,16 +42,16 @@
   },
   "homepage": "https://github.com/b4san/AC-framework#readme",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
-    "better-sqlite3": "^11.8.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.9.0",
     "chalk": "^5.3.0",
-    "commander": "^12.1.0",
+    "commander": "^14.0.3",
     "gradient-string": "^3.0.0",
-    "inquirer": "^12.3.2",
+    "inquirer": "^13.4.3",
     "js-yaml": "^4.1.1",
     "nanospinner": "^1.2.2",
-    "tar": "^7.5.7",
-    "zod": "^4.3.6"
+    "tar": "^7.5.15",
+    "zod": "^4.4.3"
   },
   "type": "module",
   "engines": {

package/src/agents/runtime.js

@@ -51,8 +51,76 @@ 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 = {}) {
@@ -136,34 +204,114 @@ export async function spawnZellijSession({
   waitForSessionMs = 10000,
   pollIntervalMs = 250,
   runCommandImpl,
+  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 existing = await zellijSessionExists(sessionName, binaryPath, { runCommandImpl: runner });
   if (existing) {
-    return { layoutPath };
+    return { layoutPath, strategy: 'already_exists', capabilities: caps, strategyErrors };
   }
 
-  await runner(command, ['--layout', layoutPath, 'attach', '--create-background', sessionName], {
-    cwd: sessionDir,
-  });
+  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: 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 ...`'
   );
 }
@@ -177,7 +325,10 @@ export async function zellijSessionExists(sessionName, binaryPath, options = {})
       .split('\n')
       .map((line) => line.trim())
       .filter(Boolean);
-    return lines.some((line) => line === sessionName || line.startsWith(`${sessionName} `));
+    return lines.some((line) => {
+      if (line === sessionName || line.startsWith(`${sessionName} `)) return true;
+      return line.includes(sessionName);
+    });
   } catch {
     return false;
   }