ac-framework 1.9.9 → 2.1.0

package/README.md

@@ -147,6 +147,7 @@ Each role runs in turn against a shared, accumulating context so outputs from on
 | `acfm agents start --task "..." --model-coder provider/model` | Start session with optional per-role models |
 | `acfm agents start --task "..." --mux zellij` | Start session forcing zellij backend (`auto`/`tmux` also supported) |
 | `acfm agents runtime get` | Show configured multiplexer backend (`auto`, `zellij`, `tmux`) |
+| `acfm agents runtime install-zellij` | Download latest zellij release into `~/.acfm/tools/zellij` |
 | `acfm agents runtime set zellij` | Persist preferred multiplexer backend |
 | `acfm agents resume` | Resume a previous session and recreate workers if needed |
 | `acfm agents list` | List recent SynapseGrid sessions |
@@ -155,6 +156,7 @@ Each role runs in turn against a shared, accumulating context so outputs from on
 | `acfm agents logs` | Show recent worker logs (all roles or one role) |
 | `acfm agents transcript --role all --limit 40` | Show captured cross-agent transcript |
 | `acfm agents summary` | Show generated collaboration meeting summary |
+| `acfm agents artifacts` | Show artifact paths/existence for current session |
 | `acfm agents export --format md --out file.md` | Export transcript in Markdown or JSON |
 | `acfm agents send "..."` | Send a new user message into the active session |
 | `acfm agents status` | Show current collaborative session state |
@@ -187,12 +189,15 @@ When driving SynapseGrid from another agent via MCP, prefer asynchronous run too
 - Configure role models directly at start (for example `--model-planner`, `--model-coder`) or persist defaults via `acfm agents model choose` / `acfm agents model set`.
 - 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.
 
 Each collaborative session now keeps human-readable artifacts under `~/.acfm/synapsegrid/<sessionId>/`:
 - `transcript.jsonl`: full chronological message stream
 - `turns/*.json`: one file per round/role turn with captured output metadata
 - `meeting-log.md`: incremental meeting notes generated per turn
 - `meeting-summary.md`: final consolidated summary (roles, decisions, open issues, risks, action items)
+- `turns/raw/*.ndjson`: raw OpenCode event stream captured per role/round
+- `turns/raw/*.stderr.log`: stderr capture per role/round
 
 ### Spec Workflow
 

package/package.json

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

package/src/agents/config-store.js

@@ -12,11 +12,24 @@ function normalizeConfig(raw) {
   const agents = raw?.agents && typeof raw.agents === 'object' ? raw.agents : {};
   const configuredMultiplexer = typeof agents.multiplexer === 'string' ? agents.multiplexer.trim().toLowerCase() : '';
   const multiplexer = ['auto', 'zellij', 'tmux'].includes(configuredMultiplexer) ? configuredMultiplexer : 'auto';
+  const zellij = agents?.zellij && typeof agents.zellij === 'object' ? agents.zellij : {};
+  const zellijStrategy = typeof zellij.strategy === 'string' ? zellij.strategy.trim().toLowerCase() : 'auto';
+  const strategy = ['auto', 'managed', 'system'].includes(zellijStrategy) ? zellijStrategy : 'auto';
+  const binaryPath = typeof zellij.binaryPath === 'string' && zellij.binaryPath.trim() ? zellij.binaryPath.trim() : null;
+  const version = typeof zellij.version === 'string' && zellij.version.trim() ? zellij.version.trim() : null;
+  const source = typeof zellij.source === 'string' && zellij.source.trim() ? zellij.source.trim() : null;
+
   return {
     agents: {
       defaultModel: normalizeModelId(agents.defaultModel) || DEFAULT_SYNAPSE_MODEL,
       defaultRoleModels: sanitizeRoleModels(agents.defaultRoleModels),
       multiplexer,
+      zellij: {
+        strategy,
+        binaryPath,
+        version,
+        source,
+      },
     },
   };
 }

package/src/agents/orchestrator.js

@@ -11,10 +11,12 @@ import {
 } from './run-state.js';
 import {
   addAgentMessage,
+  appendTurnRawCapture,
   appendMeetingTurn,
   loadSessionState,
   saveSessionState,
   stopSession,
+  updateSessionDiagnostics,
   writeMeetingSummary,
   withSessionLock,
 } from './state-store.js';
@@ -33,6 +35,21 @@ async function finalizeSessionArtifacts(state) {
   });
 }
 
+async function maybeRecordNoTurnDiagnostic(state) {
+  const runState = ensureRunState(state);
+  const hasTurnEvents = Array.isArray(runState.events)
+    ? runState.events.some((event) => event?.type === 'role_succeeded' || event?.type === 'role_failed')
+    : false;
+  if (!hasTurnEvents) {
+    await updateSessionDiagnostics(state.sessionId, {
+      warning: 'Session ended before any role turn was captured',
+      runStatus: runState.status,
+      stateStatus: state.status,
+      runEventCount: Array.isArray(runState.events) ? runState.events.length : 0,
+    });
+  }
+}
+
 function buildRuntimePrompt({ state, role }) {
   const roleContext = ROLE_SYSTEM_PROMPTS[role] || '';
   const collaborativePrompt = buildAgentPrompt({
@@ -162,6 +179,7 @@ export async function runTurn(sessionId, options = {}) {
     if (shouldStop(state)) {
       if (state.status === 'running') {
         state = await stopSession(state, 'completed');
+        await maybeRecordNoTurnDiagnostic(state);
         state = await finalizeSessionArtifacts(state);
       }
       return state;
@@ -200,6 +218,7 @@ export async function runTurn(sessionId, options = {}) {
 
     if (shouldStop(state)) {
       state = await stopSession(state, 'completed');
+      await maybeRecordNoTurnDiagnostic(state);
       state = await finalizeSessionArtifacts(state);
     }
 
@@ -267,6 +286,7 @@ export async function executeActiveTurn(sessionId, role, options = {}) {
 
     if (shouldStop(state)) {
       state = await stopSession(state, 'completed');
+      await maybeRecordNoTurnDiagnostic(state);
       state = await finalizeSessionArtifacts(state);
     }
 
@@ -317,6 +337,8 @@ export async function runWorkerIteration(sessionId, role, options = {}) {
     const prompt = buildRuntimePrompt({ state, role });
     let content;
     let outputEvents = [];
+    let outputStdout = '';
+    let outputStderr = '';
     let effectiveModel = null;
     let failed = false;
     let errorMessage = '';
@@ -340,6 +362,8 @@ export async function runWorkerIteration(sessionId, role, options = {}) {
       });
       content = output.text;
       outputEvents = output.events || [];
+      outputStdout = output.stdout || '';
+      outputStderr = output.stderr || '';
     } catch (error) {
       failed = true;
       errorMessage = error.message;
@@ -348,15 +372,26 @@ export async function runWorkerIteration(sessionId, role, options = {}) {
 
     state = await addAgentMessage(state, role, content);
     if (failed) {
-      await appendMeetingTurn(sessionId, createTurnRecord({
+      const failedTurn = createTurnRecord({
         round: state.round,
         role,
         model: effectiveModel,
         content,
         events: outputEvents,
-      }));
+      });
+      await appendMeetingTurn(sessionId, failedTurn);
+      await appendTurnRawCapture(sessionId, failedTurn, {
+        stdout: outputStdout,
+        stderr: outputStderr,
+        events: outputEvents,
+      });
+      await updateSessionDiagnostics(sessionId, {
+        lastError: errorMessage,
+        lastFailedRole: role,
+      });
       state = await saveSessionState(applyRoleFailurePolicy(state, role, errorMessage));
       if (state.status === 'failed') {
+        await maybeRecordNoTurnDiagnostic(state);
         state = await finalizeSessionArtifacts(state);
       }
       return state;
@@ -370,6 +405,14 @@ export async function runWorkerIteration(sessionId, role, options = {}) {
       events: outputEvents,
     });
     await appendMeetingTurn(sessionId, turnRecord);
+    await appendTurnRawCapture(sessionId, turnRecord, {
+      stdout: outputStdout,
+      stderr: outputStderr,
+      events: outputEvents,
+    });
+    await updateSessionDiagnostics(sessionId, {
+      lastError: null,
+    });
 
     const updatedShared = updateSharedContext(ensureRunState(state).sharedContext, turnRecord);
     const succeededRun = appendRunEvent({
@@ -397,6 +440,7 @@ export async function runWorkerIteration(sessionId, role, options = {}) {
         ...state,
         run: finalRun,
       });
+      await maybeRecordNoTurnDiagnostic(state);
       state = await finalizeSessionArtifacts(state);
     }
 

package/src/agents/runtime.js

@@ -43,6 +43,10 @@ function runCommand(command, args, options = {}) {
   });
 }
 
+function sleep(ms) {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+
 function workerCommand(sessionId, role, roleLog) {
   return `bash -lc 'node "${runnerPath}" agents worker --session ${sessionId} --role ${role} 2>&1 | tee -a "${roleLog}"'`;
 }
@@ -120,16 +124,53 @@ async function writeZellijLayout({ layoutPath, sessionId, sessionDir }) {
   await writeFile(layoutPath, content, 'utf8');
 }
 
-export async function spawnZellijSession({ sessionName, sessionDir, sessionId }) {
+export async function spawnZellijSession({
+  sessionName,
+  sessionDir,
+  sessionId,
+  binaryPath,
+  waitForSessionMs = 10000,
+  pollIntervalMs = 250,
+  runCommandImpl,
+  spawnImpl,
+}) {
   const layoutPath = resolve(sessionDir, 'synapsegrid-layout.kdl');
   await writeZellijLayout({ layoutPath, sessionId, sessionDir });
-  await runCommand('zellij', ['--session', sessionName, '--layout', layoutPath, '--detach']);
-  return { layoutPath };
+  const command = binaryPath || process.env.ACFM_ZELLIJ_BIN || 'zellij';
+
+  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 startedAt = Date.now();
+  while ((Date.now() - startedAt) < waitForSessionMs) {
+    // eslint-disable-next-line no-await-in-loop
+    const exists = await zellijSessionExists(sessionName, binaryPath, { runCommandImpl });
+    if (exists) {
+      return { layoutPath };
+    }
+    // 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}). ` +
+    'Try `acfm agents doctor` or fallback with `acfm agents start --mux tmux ...`'
+  );
 }
 
-export async function zellijSessionExists(sessionName) {
+export async function zellijSessionExists(sessionName, binaryPath, options = {}) {
   try {
-    const result = await runCommand('zellij', ['list-sessions']);
+    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} `));
   } catch {
@@ -138,7 +179,8 @@ export async function zellijSessionExists(sessionName) {
 }
 
 export async function runZellij(args, options = {}) {
-  return runCommand('zellij', args, options);
+  const command = options.binaryPath || process.env.ACFM_ZELLIJ_BIN || 'zellij';
+  return runCommand(command, args, options);
 }
 
 export function resolveMultiplexer(preferred = 'auto', hasTmuxCommand = false, hasZellijCommand = false) {

package/src/agents/state-store.js

@@ -55,6 +55,28 @@ function getMeetingSummaryPath(sessionId) {
   return join(getSessionDir(sessionId), 'meeting-summary.md');
 }
 
+function getTurnsRawDir(sessionId) {
+  return join(getTurnsDir(sessionId), 'raw');
+}
+
+function getDiagnosticsPath(sessionId) {
+  return join(getSessionDir(sessionId), 'diagnostics.json');
+}
+
+export function sessionArtifactPaths(sessionId) {
+  return {
+    sessionDir: getSessionDir(sessionId),
+    statePath: getSessionStatePath(sessionId),
+    transcriptPath: getTranscriptPath(sessionId),
+    turnsDir: getTurnsDir(sessionId),
+    turnsRawDir: getTurnsRawDir(sessionId),
+    meetingLogPath: getMeetingLogPath(sessionId),
+    meetingLogJsonlPath: getMeetingLogJsonlPath(sessionId),
+    meetingSummaryPath: getMeetingSummaryPath(sessionId),
+    diagnosticsPath: getDiagnosticsPath(sessionId),
+  };
+}
+
 function initialState(task, options = {}) {
   const sessionId = randomUUID();
   const createdAt = new Date().toISOString();
@@ -94,13 +116,98 @@ export async function createSession(task, options = {}) {
   await ensureSessionRoot();
   const state = initialState(task, options);
   const sessionDir = getSessionDir(state.sessionId);
+  const turnsDir = getTurnsDir(state.sessionId);
+  const turnsRawDir = getTurnsRawDir(state.sessionId);
+  const meetingLogPath = getMeetingLogPath(state.sessionId);
+  const meetingLogJsonlPath = getMeetingLogJsonlPath(state.sessionId);
+  const meetingSummaryPath = getMeetingSummaryPath(state.sessionId);
+  const diagnosticsPath = getDiagnosticsPath(state.sessionId);
   await mkdir(sessionDir, { recursive: true });
+  await mkdir(turnsDir, { recursive: true });
+  await mkdir(turnsRawDir, { recursive: true });
   await writeFile(getSessionStatePath(state.sessionId), JSON.stringify(state, null, 2) + '\n', 'utf8');
+  await writeFile(meetingLogPath, [
+    '# SynapseGrid Meeting Log',
+    '',
+    `Session: ${state.sessionId}`,
+    `Created: ${state.createdAt}`,
+    '',
+    '_No turns captured yet._',
+    '',
+  ].join('\n'), 'utf8');
+  await writeFile(meetingLogJsonlPath, '', 'utf8');
+  await writeFile(meetingSummaryPath, [
+    '# SynapseGrid Meeting Summary',
+    '',
+    `Session: ${state.sessionId}`,
+    'Status: running',
+    '',
+    'Summary is pending until the first turn is captured.',
+    '',
+  ].join('\n'), 'utf8');
+  await writeFile(diagnosticsPath, JSON.stringify({
+    sessionId: state.sessionId,
+    createdAt: state.createdAt,
+    turnCount: 0,
+    lastTurnAt: null,
+    lastError: null,
+  }, null, 2) + '\n', 'utf8');
   await writeCurrentSession(state.sessionId, state.updatedAt);
   await appendTranscript(state.sessionId, state.messages[0]);
   return state;
 }
 
+export async function ensureSessionArtifacts(sessionId, state = null) {
+  const paths = sessionArtifactPaths(sessionId);
+  await mkdir(paths.sessionDir, { recursive: true });
+  await mkdir(paths.turnsDir, { recursive: true });
+  await mkdir(paths.turnsRawDir, { recursive: true });
+
+  const currentState = state || (existsSync(paths.statePath)
+    ? JSON.parse(await readFile(paths.statePath, 'utf8'))
+    : null);
+
+  if (!existsSync(paths.meetingLogPath)) {
+    await writeFile(paths.meetingLogPath, [
+      '# SynapseGrid Meeting Log',
+      '',
+      `Session: ${sessionId}`,
+      `Created: ${currentState?.createdAt || new Date().toISOString()}`,
+      '',
+      '_No turns captured yet._',
+      '',
+    ].join('\n'), 'utf8');
+  }
+
+  if (!existsSync(paths.meetingLogJsonlPath)) {
+    await writeFile(paths.meetingLogJsonlPath, '', 'utf8');
+  }
+
+  if (!existsSync(paths.meetingSummaryPath)) {
+    await writeFile(paths.meetingSummaryPath, [
+      '# SynapseGrid Meeting Summary',
+      '',
+      `Session: ${sessionId}`,
+      `Status: ${currentState?.status || 'running'}`,
+      '',
+      'Summary is pending until the first turn is captured.',
+      '',
+    ].join('\n'), 'utf8');
+  }
+
+  if (!existsSync(paths.diagnosticsPath)) {
+    await writeFile(paths.diagnosticsPath, JSON.stringify({
+      sessionId,
+      createdAt: currentState?.createdAt || new Date().toISOString(),
+      turnCount: 0,
+      lastTurnAt: null,
+      lastError: null,
+    }, null, 2) + '\n', 'utf8');
+  }
+
+  return paths;
+}
+
 export async function appendTranscript(sessionId, message) {
   const transcriptPath = getTranscriptPath(sessionId);
   const line = JSON.stringify(message) + '\n';
@@ -112,18 +219,25 @@ export async function appendTranscript(sessionId, message) {
 }
 
 export async function appendMeetingTurn(sessionId, turnRecord) {
-  const sessionDir = getSessionDir(sessionId);
-  const turnsDir = getTurnsDir(sessionId);
+  const {
+    sessionDir,
+    turnsDir,
+    turnsRawDir,
+    meetingLogPath,
+    meetingLogJsonlPath,
+    diagnosticsPath,
+  } = sessionArtifactPaths(sessionId);
   await mkdir(sessionDir, { recursive: true });
   await mkdir(turnsDir, { recursive: true });
+  await mkdir(turnsRawDir, { recursive: true });
 
   const safeRole = String(turnRecord?.role || 'unknown').replace(/[^a-z0-9_-]/gi, '_');
   const safeRound = Number.isInteger(turnRecord?.round) ? turnRecord.round : 0;
   const turnFilePath = join(turnsDir, `${String(safeRound).padStart(3, '0')}-${safeRole}.json`);
   await writeFile(turnFilePath, JSON.stringify(turnRecord, null, 2) + '\n', 'utf8');
 
-  const mdPath = getMeetingLogPath(sessionId);
-  const jsonlPath = getMeetingLogJsonlPath(sessionId);
+  const mdPath = meetingLogPath;
+  const jsonlPath = meetingLogJsonlPath;
   const snippet = (turnRecord?.snippet || '').trim() || '(empty output)';
   const keyPoints = Array.isArray(turnRecord?.keyPoints) ? turnRecord.keyPoints : [];
 
@@ -149,6 +263,16 @@ export async function appendMeetingTurn(sessionId, turnRecord) {
   }
 
   await appendFile(jsonlPath, JSON.stringify(turnRecord) + '\n', 'utf8');
+
+  const diagnostics = existsSync(diagnosticsPath)
+    ? JSON.parse(await readFile(diagnosticsPath, 'utf8'))
+    : { sessionId, turnCount: 0 };
+  diagnostics.turnCount = Number.isInteger(diagnostics.turnCount) ? diagnostics.turnCount + 1 : 1;
+  diagnostics.lastTurnAt = turnRecord?.timestamp || new Date().toISOString();
+  diagnostics.lastRole = safeRole;
+  diagnostics.lastRound = safeRound;
+  await writeFile(diagnosticsPath, JSON.stringify(diagnostics, null, 2) + '\n', 'utf8');
+
   return {
     turnFilePath,
     meetingLogPath: mdPath,
@@ -156,6 +280,47 @@ export async function appendMeetingTurn(sessionId, turnRecord) {
   };
 }
 
+export async function appendTurnRawCapture(sessionId, turnRecord, capture = {}) {
+  const { turnsRawDir } = sessionArtifactPaths(sessionId);
+  await mkdir(turnsRawDir, { recursive: true });
+
+  const safeRole = String(turnRecord?.role || 'unknown').replace(/[^a-z0-9_-]/gi, '_');
+  const safeRound = Number.isInteger(turnRecord?.round) ? turnRecord.round : 0;
+  const baseName = `${String(safeRound).padStart(3, '0')}-${safeRole}`;
+  const ndjsonPath = join(turnsRawDir, `${baseName}.ndjson`);
+  const stderrPath = join(turnsRawDir, `${baseName}.stderr.log`);
+  const metaPath = join(turnsRawDir, `${baseName}.meta.json`);
+
+  await writeFile(ndjsonPath, String(capture.stdout || ''), 'utf8');
+  await writeFile(stderrPath, String(capture.stderr || ''), 'utf8');
+  await writeFile(metaPath, JSON.stringify({
+    round: safeRound,
+    role: safeRole,
+    model: turnRecord?.model || null,
+    capturedAt: new Date().toISOString(),
+    stdoutBytes: Buffer.byteLength(String(capture.stdout || ''), 'utf8'),
+    stderrBytes: Buffer.byteLength(String(capture.stderr || ''), 'utf8'),
+    eventCount: Array.isArray(capture.events) ? capture.events.length : 0,
+  }, null, 2) + '\n', 'utf8');
+
+  return { ndjsonPath, stderrPath, metaPath };
+}
+
+export async function updateSessionDiagnostics(sessionId, patch = {}) {
+  const { diagnosticsPath, sessionDir } = sessionArtifactPaths(sessionId);
+  await mkdir(sessionDir, { recursive: true });
+  const current = existsSync(diagnosticsPath)
+    ? JSON.parse(await readFile(diagnosticsPath, 'utf8'))
+    : { sessionId, turnCount: 0, lastTurnAt: null };
+  const next = {
+    ...current,
+    ...patch,
+    updatedAt: new Date().toISOString(),
+  };
+  await writeFile(diagnosticsPath, JSON.stringify(next, null, 2) + '\n', 'utf8');
+  return next;
+}
+
 export async function writeMeetingSummary(sessionId, summaryMarkdown) {
   const outputPath = getMeetingSummaryPath(sessionId);
   await writeFile(outputPath, String(summaryMarkdown || '').trimEnd() + '\n', 'utf8');

package/src/commands/agents.js

@@ -18,6 +18,7 @@ import { runWorkerIteration } from '../agents/orchestrator.js';
 import {
   addUserMessage,
   createSession,
+  ensureSessionArtifacts,
   getSessionDir,
   loadCurrentSessionId,
   loadSessionState,
@@ -26,6 +27,7 @@ import {
   saveSessionState,
   setCurrentSession,
   stopSession,
+  sessionArtifactPaths,
   writeMeetingSummary,
 } from '../agents/state-store.js';
 import {
@@ -45,7 +47,13 @@ import {
   normalizeModelId,
   sanitizeRoleModels,
 } from '../agents/model-selection.js';
-import { ensureCollabDependencies, hasCommand, resolveCommandPath } from '../services/dependency-installer.js';
+import {
+  ensureCollabDependencies,
+  hasCommand,
+  resolveCommandPath,
+  resolveManagedZellijPath,
+  installManagedZellijLatest,
+} from '../services/dependency-installer.js';
 
 function output(data, json) {
   if (json) {
@@ -101,14 +109,42 @@ function sessionMuxName(state) {
   return state.multiplexerSessionName || state.tmuxSessionName || `acfm-synapse-${state.sessionId.slice(0, 8)}`;
 }
 
-async function sessionExistsForMux(multiplexer, sessionName) {
-  if (multiplexer === 'zellij') return zellijSessionExists(sessionName);
+async function sessionExistsForMux(multiplexer, sessionName, zellijPath = null) {
+  if (multiplexer === 'zellij') return zellijSessionExists(sessionName, zellijPath);
   return tmuxSessionExists(sessionName);
 }
 
-async function attachToMux(multiplexer, sessionName, readonly = false) {
+function resolveConfiguredZellijPath(config) {
+  const strategy = config?.agents?.zellij?.strategy || 'auto';
+  if (strategy === 'system') {
+    return resolveCommandPath('zellij');
+  }
+  const managed = resolveManagedZellijPath(config);
+  if (managed) return managed;
+  return resolveCommandPath('zellij');
+}
+
+function shouldUseManagedZellij(config) {
+  const strategy = config?.agents?.zellij?.strategy || 'auto';
+  if (strategy === 'managed') return true;
+  if (strategy === 'system') return false;
+  return true;
+}
+
+function resolveMultiplexerWithPaths(config, requestedMux = 'auto') {
+  const zellijPath = resolveConfiguredZellijPath(config);
+  const tmuxPath = resolveCommandPath('tmux');
+  const selected = resolveMultiplexer(requestedMux, Boolean(tmuxPath), Boolean(zellijPath));
+  return {
+    selected,
+    zellijPath,
+    tmuxPath,
+  };
+}
+
+async function attachToMux(multiplexer, sessionName, readonly = false, zellijPath = null) {
   if (multiplexer === 'zellij') {
-    await runZellij(['attach', sessionName], { stdio: 'inherit' });
+    await runZellij(['attach', sessionName], { stdio: 'inherit', binaryPath: zellijPath });
     return;
   }
   const args = ['attach'];
@@ -206,6 +242,18 @@ async function readSessionArtifact(sessionId, filename) {
   return readFile(path, 'utf8');
 }
 
+async function collectArtifactStatus(sessionId) {
+  await ensureSessionArtifacts(sessionId);
+  const paths = sessionArtifactPaths(sessionId);
+  return {
+    sessionId,
+    checkedAt: new Date().toISOString(),
+    artifacts: Object.fromEntries(
+      Object.entries(paths).map(([key, value]) => [key, { path: value, exists: existsSync(value) }])
+    ),
+  };
+}
+
 async function preflightModel({ opencodeBin, model, cwd }) {
   const selected = normalizeModelId(model) || DEFAULT_SYNAPSE_MODEL;
   try {
@@ -230,7 +278,9 @@ export function agentsCommand() {
 Examples:
   acfm agents start --task "Implement auth flow" --mux auto
   acfm agents setup
+  acfm agents artifacts
   acfm agents runtime get
+  acfm agents runtime install-zellij
   acfm agents runtime set zellij
   acfm agents model choose
   acfm agents model list
@@ -270,28 +320,50 @@ Examples:
       const result = ensureCollabDependencies({
         installZellij,
         installTmux,
+        preferManagedZellij: installZellij,
       });
+      const awaited = await result;
       let collabMcp = null;
 
-      if (result.success) {
+      if (awaited.success) {
         const { detectAndInstallMCPs } = await import('../services/mcp-installer.js');
         collabMcp = detectAndInstallMCPs({ target: 'collab' });
       }
 
-      const payload = { ...result, collabMcp };
+      const payload = { ...awaited, collabMcp };
       output(payload, opts.json);
       if (!opts.json) {
-        const oLabel = result.opencode.success ? chalk.green('ok') : chalk.red('failed');
-        const tLabel = result.tmux.success ? chalk.green('ok') : chalk.red('failed');
-        const zLabel = result.zellij.success ? chalk.green('ok') : chalk.red('failed');
-        console.log(`OpenCode: ${oLabel} - ${result.opencode.message}`);
-        console.log(`zellij:   ${zLabel} - ${result.zellij.message}`);
-        console.log(`tmux:     ${tLabel} - ${result.tmux.message}`);
+        const oLabel = awaited.opencode.success ? chalk.green('ok') : chalk.red('failed');
+        const tLabel = awaited.tmux.success ? chalk.green('ok') : chalk.red('failed');
+        const zLabel = awaited.zellij.success ? chalk.green('ok') : chalk.red('failed');
+        console.log(`OpenCode: ${oLabel} - ${awaited.opencode.message}`);
+        console.log(`zellij:   ${zLabel} - ${awaited.zellij.message}`);
+        if (awaited.zellij.binaryPath) {
+          console.log(chalk.dim(`          ${awaited.zellij.binaryPath}`));
+        }
+        console.log(`tmux:     ${tLabel} - ${awaited.tmux.message}`);
         if (collabMcp) {
           console.log(`Collab MCP: ${chalk.green('ok')} - installed ${collabMcp.success}/${collabMcp.installed} on detected assistants`);
         }
       }
-      if (!result.success) process.exit(1);
+
+      if (awaited.zellij.success && awaited.zellij.source === 'managed' && awaited.zellij.binaryPath) {
+        await updateAgentsConfig((current) => ({
+          agents: {
+            defaultModel: current.agents.defaultModel,
+            defaultRoleModels: { ...current.agents.defaultRoleModels },
+            multiplexer: current.agents.multiplexer || 'auto',
+            zellij: {
+              strategy: 'managed',
+              binaryPath: awaited.zellij.binaryPath,
+              version: awaited.zellij.version || null,
+              source: 'managed',
+            },
+          },
+        }));
+      }
+
+      if (!awaited.success) process.exit(1);
     });
 
   agents
@@ -393,12 +465,14 @@ Examples:
       try {
         const sessionId = await ensureSessionId(true);
         const state = await loadSessionState(sessionId);
+        const cfg = await loadAgentsConfig();
+        const zellijPath = resolveConfiguredZellijPath(cfg);
         const multiplexer = state.multiplexer || 'tmux';
         const muxSessionName = sessionMuxName(state);
         if (!muxSessionName) {
           throw new Error('No multiplexer session registered for active collaborative session');
         }
-        await attachToMux(multiplexer, muxSessionName, false);
+        await attachToMux(multiplexer, muxSessionName, false, zellijPath);
       } catch (error) {
         console.error(chalk.red(`Error: ${error.message}`));
         process.exit(1);
@@ -413,16 +487,18 @@ Examples:
       try {
         const sessionId = await ensureSessionId(true);
         const state = await loadSessionState(sessionId);
+        const cfg = await loadAgentsConfig();
+        const zellijPath = resolveConfiguredZellijPath(cfg);
         const multiplexer = state.multiplexer || 'tmux';
         const muxSessionName = sessionMuxName(state);
         if (!muxSessionName) {
           throw new Error('No multiplexer session registered for active collaborative session');
         }
-        const sessionExists = await sessionExistsForMux(multiplexer, muxSessionName);
+        const sessionExists = await sessionExistsForMux(multiplexer, muxSessionName, zellijPath);
         if (!sessionExists) {
           throw new Error(`${multiplexer} session ${muxSessionName} no longer exists. Run: acfm agents resume`);
         }
-        await attachToMux(multiplexer, muxSessionName, Boolean(opts.readonly));
+        await attachToMux(multiplexer, muxSessionName, Boolean(opts.readonly), zellijPath);
       } catch (error) {
         console.error(chalk.red(`Error: ${error.message}`));
         process.exit(1);
@@ -441,21 +517,29 @@ Examples:
         const sessionId = opts.session || await ensureSessionId(true);
         let state = await loadSessionState(sessionId);
         const multiplexer = state.multiplexer || 'tmux';
+        const cfg = await loadAgentsConfig();
+        const zellijPath = resolveConfiguredZellijPath(cfg);
+        const tmuxPath = resolveCommandPath('tmux');
 
-        if (multiplexer === 'zellij' && !hasCommand('zellij')) {
+        if (multiplexer === 'zellij' && !zellijPath) {
           throw new Error('zellij is not installed. Run: acfm agents setup');
         }
-        if (multiplexer === 'tmux' && !hasCommand('tmux')) {
+        if (multiplexer === 'tmux' && !tmuxPath) {
           throw new Error('tmux is not installed. Run: acfm agents setup');
         }
 
         const muxSessionName = sessionMuxName(state);
-        const muxExists = await sessionExistsForMux(multiplexer, muxSessionName);
+        const muxExists = await sessionExistsForMux(multiplexer, muxSessionName, zellijPath);
 
         if (!muxExists && opts.recreate) {
           const sessionDir = getSessionDir(state.sessionId);
           if (multiplexer === 'zellij') {
-            await spawnZellijSession({ sessionName: muxSessionName, sessionDir, sessionId: state.sessionId });
+            await spawnZellijSession({
+              sessionName: muxSessionName,
+              sessionDir,
+              sessionId: state.sessionId,
+              binaryPath: zellijPath,
+            });
           } else {
             await spawnTmuxSession({ sessionName: muxSessionName, sessionDir, sessionId: state.sessionId });
           }
@@ -484,7 +568,7 @@ Examples:
         }
 
         if (opts.attach) {
-          await attachToMux(multiplexer, muxSessionName, false);
+          await attachToMux(multiplexer, muxSessionName, false, zellijPath);
         }
       } catch (error) {
         output({ error: error.message }, opts.json);
@@ -564,15 +648,19 @@ Examples:
       try {
         const cfg = await loadAgentsConfig();
         const configured = validateMultiplexer(cfg.agents.multiplexer || 'auto');
-        const resolved = resolveMultiplexer(configured, hasCommand('tmux'), hasCommand('zellij'));
+        const zellijPath = resolveConfiguredZellijPath(cfg);
+        const tmuxPath = resolveCommandPath('tmux');
+        const resolved = resolveMultiplexer(configured, Boolean(tmuxPath), Boolean(zellijPath));
         const payload = {
           configPath: getAgentsConfigPath(),
           multiplexer: configured,
           resolved,
           available: {
-            zellij: hasCommand('zellij'),
-            tmux: hasCommand('tmux'),
+            zellij: Boolean(zellijPath),
+            tmux: Boolean(tmuxPath),
           },
+          zellij: cfg.agents.zellij,
+          zellijPath,
         };
         output(payload, opts.json);
         if (!opts.json) {
@@ -581,6 +669,9 @@ Examples:
           console.log(chalk.dim(`Configured: ${configured}`));
           console.log(chalk.dim(`Resolved: ${resolved || 'none'}`));
           console.log(chalk.dim(`zellij=${payload.available.zellij} tmux=${payload.available.tmux}`));
+          if (payload.zellijPath) {
+            console.log(chalk.dim(`zellij path: ${payload.zellijPath}`));
+          }
         }
       } catch (error) {
         output({ error: error.message }, opts.json);
@@ -601,9 +692,14 @@ Examples:
             defaultModel: current.agents.defaultModel,
             defaultRoleModels: { ...current.agents.defaultRoleModels },
             multiplexer: selected,
+            zellij: {
+              ...(current.agents.zellij || { strategy: 'auto', binaryPath: null, version: null, source: null }),
+            },
           },
         }));
-        const resolved = resolveMultiplexer(updated.agents.multiplexer, hasCommand('tmux'), hasCommand('zellij'));
+        const zellijPath = resolveConfiguredZellijPath(updated);
+        const tmuxPath = resolveCommandPath('tmux');
+        const resolved = resolveMultiplexer(updated.agents.multiplexer, Boolean(tmuxPath), Boolean(zellijPath));
         const payload = {
           success: true,
           configPath: getAgentsConfigPath(),
@@ -623,6 +719,46 @@ Examples:
       }
     });
 
+  runtime
+    .command('install-zellij')
+    .description('Install latest zellij release managed by AC Framework')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+      try {
+        const result = await installManagedZellijLatest();
+        if (!result.success) {
+          output(result, opts.json);
+          if (!opts.json) console.error(chalk.red(`Error: ${result.message}`));
+          process.exit(1);
+        }
+
+        await updateAgentsConfig((current) => ({
+          agents: {
+            defaultModel: current.agents.defaultModel,
+            defaultRoleModels: { ...current.agents.defaultRoleModels },
+            multiplexer: current.agents.multiplexer || 'auto',
+            zellij: {
+              strategy: result.source === 'system' ? 'system' : 'managed',
+              binaryPath: result.binaryPath,
+              version: result.version || null,
+              source: result.source || 'managed',
+            },
+          },
+        }));
+
+        output(result, opts.json);
+        if (!opts.json) {
+          console.log(chalk.green('✓ Managed zellij ready'));
+          console.log(chalk.dim(`  Version: ${result.version || 'unknown'}`));
+          console.log(chalk.dim(`  Binary: ${result.binaryPath}`));
+        }
+      } catch (error) {
+        output({ error: error.message }, opts.json);
+        if (!opts.json) console.error(chalk.red(`Error: ${error.message}`));
+        process.exit(1);
+      }
+    });
+
   model
     .command('list')
     .description('List available OpenCode models grouped by provider')
@@ -767,6 +903,9 @@ Examples:
               defaultModel: current.agents.defaultModel,
               defaultRoleModels: { ...current.agents.defaultRoleModels },
               multiplexer: current.agents.multiplexer || 'auto',
+              zellij: {
+                ...(current.agents.zellij || { strategy: 'auto', binaryPath: null, version: null, source: null }),
+              },
             },
           };
 
@@ -828,6 +967,9 @@ Examples:
               defaultModel: current.agents.defaultModel,
               defaultRoleModels: { ...current.agents.defaultRoleModels },
               multiplexer: current.agents.multiplexer || 'auto',
+              zellij: {
+                ...(current.agents.zellij || { strategy: 'auto', binaryPath: null, version: null, source: null }),
+              },
             },
           };
           if (role === 'all') {
@@ -877,6 +1019,9 @@ Examples:
               defaultModel: current.agents.defaultModel,
               defaultRoleModels: { ...current.agents.defaultRoleModels },
               multiplexer: current.agents.multiplexer || 'auto',
+              zellij: {
+                ...(current.agents.zellij || { strategy: 'auto', binaryPath: null, version: null, source: null }),
+              },
             },
           };
           if (role === 'all') {
@@ -985,6 +1130,66 @@ Examples:
       }
     });
 
+  agents
+    .command('artifacts')
+    .description('Show SynapseGrid artifact paths and existence status')
+    .option('--session <id>', 'Session ID (defaults to current)')
+    .option('--watch', 'Continuously watch artifact status', false)
+    .option('--interval <ms>', 'Polling interval in milliseconds for --watch', '1500')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+      try {
+        const sessionId = opts.session || await ensureSessionId(true);
+        const intervalMs = Number.parseInt(opts.interval, 10);
+        if (!Number.isInteger(intervalMs) || intervalMs <= 0) {
+          throw new Error('--interval must be a positive integer');
+        }
+
+        const printSnapshot = async () => {
+          const snapshot = await collectArtifactStatus(sessionId);
+          if (opts.json) {
+            process.stdout.write(JSON.stringify(snapshot) + '\n');
+            return;
+          }
+
+          console.log(chalk.bold('SynapseGrid artifacts'));
+          console.log(chalk.dim(`Session: ${snapshot.sessionId}`));
+          console.log(chalk.dim(`Checked: ${snapshot.checkedAt}`));
+          for (const [key, meta] of Object.entries(snapshot.artifacts)) {
+            console.log(chalk.dim(`${key}: ${meta.exists ? 'ok' : 'missing'} -> ${meta.path}`));
+          }
+        };
+
+        if (!opts.watch) {
+          const snapshot = await collectArtifactStatus(sessionId);
+          output(snapshot, opts.json);
+          if (!opts.json) {
+            console.log(chalk.bold('SynapseGrid artifacts'));
+            for (const [key, meta] of Object.entries(snapshot.artifacts)) {
+              console.log(chalk.dim(`${key}: ${meta.exists ? 'ok' : 'missing'} -> ${meta.path}`));
+            }
+          }
+          return;
+        }
+
+        if (!opts.json) {
+          console.log(chalk.cyan('Watching artifacts (Ctrl+C to stop)\n'));
+        }
+
+        while (true) {
+          if (!opts.json) {
+            process.stdout.write('\x1Bc');
+          }
+          await printSnapshot();
+          await new Promise((resolvePromise) => setTimeout(resolvePromise, intervalMs));
+        }
+      } catch (error) {
+        output({ error: error.message }, opts.json);
+        if (!opts.json) console.error(chalk.red(`Error: ${error.message}`));
+        process.exit(1);
+      }
+    });
+
   agents
     .command('export')
     .description('Export collaborative transcript')
@@ -1062,7 +1267,31 @@ Examples:
 
         const config = await loadAgentsConfig();
         const configuredMux = validateMultiplexer(opts.mux || config.agents.multiplexer || 'auto');
-        const selectedMux = resolveMultiplexer(configuredMux, hasCommand('tmux'), hasCommand('zellij'));
+        const muxResolution = resolveMultiplexerWithPaths(config, configuredMux);
+        let selectedMux = muxResolution.selected;
+        let zellijPath = muxResolution.zellijPath;
+        if (!selectedMux) {
+          if (configuredMux !== 'tmux' && shouldUseManagedZellij(config)) {
+            const installResult = await installManagedZellijLatest();
+            if (installResult.success && installResult.binaryPath) {
+              await updateAgentsConfig((current) => ({
+                agents: {
+                  defaultModel: current.agents.defaultModel,
+                  defaultRoleModels: { ...current.agents.defaultRoleModels },
+                  multiplexer: current.agents.multiplexer || 'auto',
+                  zellij: {
+                    strategy: 'managed',
+                    binaryPath: installResult.binaryPath,
+                    version: installResult.version || null,
+                    source: 'managed',
+                  },
+                },
+              }));
+              zellijPath = installResult.binaryPath;
+              selectedMux = resolveMultiplexer(configuredMux, Boolean(resolveCommandPath('tmux')), Boolean(zellijPath));
+            }
+          }
+        }
         if (!selectedMux) {
           throw new Error('No multiplexer found. Install zellij or tmux with: acfm agents setup');
         }
@@ -1112,6 +1341,7 @@ Examples:
             sessionName: muxSessionName,
             sessionDir,
             sessionId: state.sessionId,
+            binaryPath: zellijPath,
           });
         } else {
           await spawnTmuxSession({
@@ -1140,7 +1370,7 @@ Examples:
         }
 
         if (opts.attach) {
-          await attachToMux(selectedMux, muxSessionName, false);
+          await attachToMux(selectedMux, muxSessionName, false, zellijPath);
         }
       } catch (error) {
         output({ error: error.message }, opts.json);
@@ -1176,6 +1406,7 @@ Examples:
       try {
         const sessionId = await ensureSessionId(true);
         const state = await loadSessionState(sessionId);
+        await ensureSessionArtifacts(sessionId, state);
         const effectiveRoleModels = buildEffectiveRoleModels(state, state.model || null);
         output({ ...state, effectiveRoleModels }, opts.json);
         if (!opts.json) {
@@ -1199,8 +1430,12 @@ Examples:
           }
           const meetingLogPath = resolve(getSessionDir(state.sessionId), 'meeting-log.md');
           const meetingSummaryPath = resolve(getSessionDir(state.sessionId), 'meeting-summary.md');
+          const turnsDirPath = resolve(getSessionDir(state.sessionId), 'turns');
+          const rawDirPath = resolve(getSessionDir(state.sessionId), 'turns', 'raw');
           console.log(chalk.dim(`meeting-log: ${existsSync(meetingLogPath) ? meetingLogPath : 'not generated yet'}`));
           console.log(chalk.dim(`meeting-summary: ${existsSync(meetingSummaryPath) ? meetingSummaryPath : 'not generated yet'}`));
+          console.log(chalk.dim(`turns: ${existsSync(turnsDirPath) ? turnsDirPath : 'not generated yet'}`));
+          console.log(chalk.dim(`turns/raw: ${existsSync(rawDirPath) ? rawDirPath : 'not generated yet'}`));
         }
       } catch (error) {
         output({ error: error.message }, opts.json);
@@ -1262,9 +1497,11 @@ Examples:
 
         const multiplexer = state.multiplexer || 'tmux';
         const muxSessionName = sessionMuxName(state);
-        if (multiplexer === 'zellij' && muxSessionName && hasCommand('zellij')) {
+        const cfg = await loadAgentsConfig();
+        const zellijPath = resolveConfiguredZellijPath(cfg);
+        if (multiplexer === 'zellij' && muxSessionName && zellijPath) {
           try {
-            await runZellij(['delete-session', muxSessionName]);
+            await runZellij(['delete-session', muxSessionName], { binaryPath: zellijPath });
           } catch {
             // ignore if already closed
           }
@@ -1376,8 +1613,9 @@ Examples:
       try {
         const opencodeBin = resolveCommandPath('opencode');
         const tmuxInstalled = hasCommand('tmux');
-        const zellijInstalled = hasCommand('zellij');
         const cfg = await loadAgentsConfig();
+        const zellijPath = resolveConfiguredZellijPath(cfg);
+        const zellijInstalled = Boolean(zellijPath);
         const defaultModel = cfg.agents.defaultModel || DEFAULT_SYNAPSE_MODEL;
         const configuredMux = validateMultiplexer(cfg.agents.multiplexer || 'auto');
         const resolvedMux = resolveMultiplexer(configuredMux, tmuxInstalled, zellijInstalled);
@@ -1385,6 +1623,8 @@ Examples:
           opencodeBin,
           tmuxInstalled,
           zellijInstalled,
+          zellijPath,
+          zellijConfig: cfg.agents.zellij,
           configuredMultiplexer: configuredMux,
           resolvedMultiplexer: resolvedMux,
           defaultModel,
@@ -1407,6 +1647,7 @@ Examples:
           console.log(chalk.bold('SynapseGrid doctor'));
           console.log(chalk.dim(`opencode: ${opencodeBin || 'not found'}`));
           console.log(chalk.dim(`zellij: ${zellijInstalled ? 'installed' : 'not installed'}`));
+          if (zellijPath) console.log(chalk.dim(`zellij path: ${zellijPath}`));
           console.log(chalk.dim(`tmux: ${tmuxInstalled ? 'installed' : 'not installed'}`));
           console.log(chalk.dim(`multiplexer: configured=${configuredMux} resolved=${resolvedMux || 'none'}`));
           console.log(chalk.dim(`default model: ${defaultModel}`));

package/src/commands/init.js

@@ -236,13 +236,20 @@ async function setupCollaborativeSystem() {
   console.log(chalk.hex('#B2BEC3')(`  Installing ${COLLAB_SYSTEM_NAME} dependencies...`));
   console.log();
 
-  const result = ensureCollabDependencies({ installZellij: true, installTmux: true });
+  const result = await ensureCollabDependencies({
+    installZellij: true,
+    installTmux: true,
+    preferManagedZellij: true,
+  });
 
   const oColor = result.opencode.success ? chalk.hex('#00B894') : chalk.hex('#D63031');
   const zColor = result.zellij.success ? chalk.hex('#00B894') : chalk.hex('#D63031');
   const tColor = result.tmux.success ? chalk.hex('#00B894') : chalk.hex('#D63031');
   console.log(oColor(`  ◆ OpenCode: ${result.opencode.message}`));
   console.log(zColor(`  ◆ zellij: ${result.zellij.message}`));
+  if (result.zellij.binaryPath) {
+    console.log(chalk.hex('#636E72')(`    ${result.zellij.binaryPath}`));
+  }
   console.log(tColor(`  ◆ tmux: ${result.tmux.message}`));
   console.log();
 

package/src/mcp/collab-server.js

@@ -34,7 +34,7 @@ import {
   setCurrentSession,
   stopSession,
 } from '../agents/state-store.js';
-import { hasCommand, resolveCommandPath } from '../services/dependency-installer.js';
+import { hasCommand, resolveCommandPath, resolveManagedZellijPath } from '../services/dependency-installer.js';
 import { loadAgentsConfig } from '../agents/config-store.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -74,8 +74,18 @@ function launchAutopilot(sessionId) {
   child.unref();
 }
 
-async function muxExists(multiplexer, sessionName) {
-  if (multiplexer === 'zellij') return zellijSessionExists(sessionName);
+function resolveConfiguredZellijPath(config) {
+  const strategy = config?.agents?.zellij?.strategy || 'auto';
+  if (strategy === 'system') {
+    return resolveCommandPath('zellij');
+  }
+  const managed = resolveManagedZellijPath(config);
+  if (managed) return managed;
+  return resolveCommandPath('zellij');
+}
+
+async function muxExists(multiplexer, sessionName, zellijPath = null) {
+  if (multiplexer === 'zellij') return zellijSessionExists(sessionName, zellijPath);
   return tmuxSessionExists(sessionName);
 }
 
@@ -121,7 +131,8 @@ class MCPCollabServer {
 
           const config = await loadAgentsConfig();
           const configuredMux = config.agents.multiplexer || 'auto';
-          const multiplexer = resolveMultiplexer(configuredMux, hasCommand('tmux'), hasCommand('zellij'));
+          const zellijPath = resolveConfiguredZellijPath(config);
+          const multiplexer = resolveMultiplexer(configuredMux, hasCommand('tmux'), Boolean(zellijPath));
           if (spawnWorkers && !multiplexer) {
             throw new Error('No multiplexer found (zellij/tmux). Run: acfm agents setup');
           }
@@ -141,7 +152,7 @@ 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 });
+              await spawnZellijSession({ sessionName, sessionDir, sessionId: state.sessionId, binaryPath: zellijPath });
             } else {
               await spawnTmuxSession({ sessionName, sessionDir, sessionId: state.sessionId });
             }
@@ -452,19 +463,21 @@ class MCPCollabServer {
           const id = sessionId || await loadCurrentSessionId();
           if (!id) throw new Error('No active session found');
           let state = await loadSessionState(id);
+          const config = await loadAgentsConfig();
+          const zellijPath = resolveConfiguredZellijPath(config);
 
-          const multiplexer = state.multiplexer || resolveMultiplexer('auto', hasCommand('tmux'), hasCommand('zellij'));
+          const multiplexer = state.multiplexer || resolveMultiplexer('auto', hasCommand('tmux'), Boolean(zellijPath));
           if (!multiplexer) {
             throw new Error('No multiplexer found (zellij/tmux). Run: acfm agents setup');
           }
           const sessionName = state.multiplexerSessionName || state.tmuxSessionName || `acfm-synapse-${state.sessionId.slice(0, 8)}`;
-          const sessionExists = await muxExists(multiplexer, sessionName);
+          const sessionExists = await muxExists(multiplexer, sessionName, zellijPath);
 
           if (!sessionExists && recreateWorkers) {
             const sessionDir = getSessionDir(state.sessionId);
             if (multiplexer === 'zellij') {
-              if (!hasCommand('zellij')) throw new Error('zellij is not installed. Run: acfm agents setup');
-              await spawnZellijSession({ sessionName, sessionDir, sessionId: state.sessionId });
+              if (!zellijPath) throw new Error('zellij is not installed. Run: acfm agents setup');
+              await spawnZellijSession({ sessionName, sessionDir, sessionId: state.sessionId, binaryPath: zellijPath });
             } else {
               if (!hasCommand('tmux')) throw new Error('tmux is not installed. Run: acfm agents setup');
               await spawnTmuxSession({ sessionName, sessionDir, sessionId: state.sessionId });

package/src/services/dependency-installer.js

@@ -1,7 +1,9 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
+import { chmod, mkdir, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { platform } from 'node:os';
+import { arch, homedir, platform } from 'node:os';
+import { createHash } from 'node:crypto';
 
 function preferredOpenCodePath() {
   const home = process.env.HOME;
@@ -24,6 +26,61 @@ function runInstallCommand(command) {
   return run('bash', ['-lc', command], { stdio: 'inherit' });
 }
 
+async function fetchJson(url) {
+  const response = await fetch(url, {
+    headers: {
+      Accept: 'application/vnd.github+json',
+      'User-Agent': 'ac-framework',
+    },
+  });
+  if (!response.ok) {
+    throw new Error(`Request failed (${response.status}) while fetching ${url}`);
+  }
+  return response.json();
+}
+
+function sha256HexFromBuffer(buffer) {
+  const hash = createHash('sha256');
+  hash.update(buffer);
+  return hash.digest('hex');
+}
+
+function managedToolsRoot() {
+  return join(homedir(), '.acfm', 'tools', 'zellij');
+}
+
+function platformAssetPrefix() {
+  const p = platform();
+  const a = arch();
+  if (p === 'linux' && a === 'x64') return 'zellij-x86_64-unknown-linux-musl';
+  if (p === 'linux' && a === 'arm64') return 'zellij-aarch64-unknown-linux-musl';
+  if (p === 'darwin' && a === 'x64') return 'zellij-x86_64-apple-darwin';
+  if (p === 'darwin' && a === 'arm64') return 'zellij-aarch64-apple-darwin';
+  if (p === 'win32' && a === 'x64') return 'zellij-x86_64-pc-windows-msvc';
+  return null;
+}
+
+function managedZellijBinaryPath(version) {
+  const fileName = platform() === 'win32' ? 'zellij.exe' : 'zellij';
+  return join(managedToolsRoot(), version, fileName);
+}
+
+function extractTarball(tarPath, outputDir) {
+  return run('tar', ['-xzf', tarPath, '-C', outputDir]);
+}
+
+function findReleaseAsset(release, suffix) {
+  return (release.assets || []).find((asset) => asset.name === suffix) || null;
+}
+
+export function resolveManagedZellijPath(config = null) {
+  const fromEnv = process.env.ACFM_ZELLIJ_BIN;
+  if (fromEnv && existsSync(fromEnv)) return fromEnv;
+  const configured = config?.agents?.zellij?.binaryPath;
+  if (configured && existsSync(configured)) return configured;
+  return null;
+}
+
 export function hasCommand(command) {
   return Boolean(resolveCommandPath(command));
 }
@@ -164,15 +221,132 @@ export function installZellij() {
   };
 }
 
-export function ensureCollabDependencies(options = {}) {
+export async function installManagedZellijLatest() {
+  const existingSystem = resolveCommandPath('zellij');
+  if (existingSystem) {
+    return {
+      success: true,
+      installed: false,
+      version: null,
+      binaryPath: existingSystem,
+      message: 'zellij already installed in system PATH',
+      source: 'system',
+    };
+  }
+
+  const prefix = platformAssetPrefix();
+  if (!prefix) {
+    return {
+      success: false,
+      installed: false,
+      version: null,
+      binaryPath: null,
+      message: `Unsupported OS/arch for managed zellij install: ${platform()}/${arch()}`,
+      source: 'managed',
+    };
+  }
+
+  try {
+    const release = await fetchJson('https://api.github.com/repos/zellij-org/zellij/releases/latest');
+    const version = String(release.tag_name || '').trim() || 'latest';
+
+    if (platform() === 'win32') {
+      const zipAsset = findReleaseAsset(release, `${prefix}.zip`);
+      if (!zipAsset) {
+        throw new Error(`No matching Windows asset found for ${prefix}`);
+      }
+      return {
+        success: false,
+        installed: false,
+        version,
+        binaryPath: null,
+        message: 'Managed Windows zellij install is not implemented yet; use winget/choco/scoop.',
+        source: 'managed',
+      };
+    }
+
+    const tarAsset = findReleaseAsset(release, `${prefix}.tar.gz`);
+    if (!tarAsset?.browser_download_url) {
+      throw new Error(`No matching zellij asset found for ${prefix}`);
+    }
+
+    const targetDir = join(managedToolsRoot(), version);
+    const binaryPath = managedZellijBinaryPath(version);
+    if (existsSync(binaryPath)) {
+      return {
+        success: true,
+        installed: false,
+        version,
+        binaryPath,
+        message: `Managed zellij already installed (${version})`,
+        source: 'managed',
+      };
+    }
+
+    await mkdir(targetDir, { recursive: true });
+    const tmpTarPath = join(targetDir, `${prefix}.tar.gz.download`);
+    const response = await fetch(tarAsset.browser_download_url, {
+      headers: { 'User-Agent': 'ac-framework' },
+    });
+    if (!response.ok) {
+      throw new Error(`Failed downloading ${tarAsset.name} (${response.status})`);
+    }
+    const raw = Buffer.from(await response.arrayBuffer());
+
+    const expectedDigest = String(tarAsset.digest || '').replace(/^sha256:/, '');
+    if (expectedDigest) {
+      const actualDigest = sha256HexFromBuffer(raw);
+      if (actualDigest !== expectedDigest) {
+        throw new Error(`Digest mismatch for ${tarAsset.name}`);
+      }
+    }
+
+    await writeFile(tmpTarPath, raw);
+    const extracted = extractTarball(tmpTarPath, targetDir);
+    await rm(tmpTarPath, { force: true });
+    if (extracted.status !== 0) {
+      throw new Error('Failed extracting zellij tarball');
+    }
+    if (!existsSync(binaryPath)) {
+      throw new Error(`zellij binary not found after extraction at ${binaryPath}`);
+    }
+    await chmod(binaryPath, 0o755);
+
+    const versionProbe = run(binaryPath, ['--version']);
+    if (versionProbe.status !== 0) {
+      throw new Error('Installed zellij binary failed version check');
+    }
+
+    return {
+      success: true,
+      installed: true,
+      version,
+      binaryPath,
+      message: `Managed zellij installed (${version})`,
+      source: 'managed',
+    };
+  } catch (error) {
+    return {
+      success: false,
+      installed: false,
+      version: null,
+      binaryPath: null,
+      message: `Managed zellij install failed: ${error.message}`,
+      source: 'managed',
+    };
+  }
+}
+
+export async function ensureCollabDependencies(options = {}) {
   const installTmuxEnabled = options.installTmux ?? true;
   const installZellijEnabled = options.installZellij ?? true;
+  const preferManagedZellij = options.preferManagedZellij ?? false;
   const opencode = installOpenCode();
   const tmux = installTmuxEnabled
     ? installTmux()
     : { success: hasCommand('tmux'), installed: false, message: hasCommand('tmux') ? 'tmux already installed' : 'tmux installation skipped' };
   const zellij = installZellijEnabled
-    ? installZellij()
+    ? (preferManagedZellij ? await installManagedZellijLatest() : installZellij())
     : { success: hasCommand('zellij'), installed: false, message: hasCommand('zellij') ? 'zellij already installed' : 'zellij installation skipped' };
 
   const hasMultiplexer = tmux.success || zellij.success;