ac-framework 1.9.8 → 2.0.0

package/README.md

@@ -6,7 +6,7 @@ It combines three layers in one CLI:
 - template-based assistant configurations for multiple IDEs and AI CLIs
 - a built-in spec-driven workflow inspired by OpenSpec / spec-driven development
 - a persistent local memory system with MCP integration for supported assistants
-- an optional collaborative multi-agent runtime powered by OpenCode + tmux
+- an optional collaborative multi-agent runtime powered by OpenCode + zellij (tmux fallback)
 
 ## Why AC Framework
 
@@ -26,7 +26,7 @@ The goal is simple: help AI write better code, with more context, more disciplin
 - `Spec-driven workflow` - use `acfm spec` to initialize, create, validate, continue, and archive structured changes.
 - `Persistent memory` - store architectural decisions, bugfixes, refactors, conventions, and context in a local SQLite memory database.
 - `MCP integration` - connect the memory system to supported assistants through MCP so they can recall and save context directly.
-- `Collaborative agents (optional)` - enable SynapseGrid to run planner/critic/coder/reviewer in coordinated tmux panes with shared context.
+- `Collaborative agents (optional)` - enable SynapseGrid to run planner/critic/coder/reviewer in coordinated zellij panes (tmux fallback) with shared context.
 - `GitHub sync` - use `acfm init --latest` or `acfm update` to pull the latest framework content from GitHub.
 - `Legacy compatibility` - `.acfm/` is the new default, but existing `openspec/` directories still work.
 
@@ -57,7 +57,7 @@ The CLI now guides you through:
 2. choose one or more assistants from that template
 3. install the matching root instruction files like `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or `copilot-instructions.md`
 4. optionally initialize NexusVault persistent memory and MCP connections
-5. optionally enable SynapseGrid collaborative agents (auto-installs OpenCode + tmux)
+5. optionally enable SynapseGrid collaborative agents (auto-installs OpenCode + zellij/tmux)
 
 If enabled, `acfm init` also auto-installs the optional SynapseGrid MCP server into detected assistants.
 
@@ -130,7 +130,7 @@ Some assistants include bundled companions automatically:
 
 ### Collaborative Agents (Optional)
 
-SynapseGrid is an optional collaborative runtime that coordinates 4 OpenCode-backed roles in tmux panes:
+SynapseGrid is an optional collaborative runtime that coordinates 4 OpenCode-backed roles in multiplexer panes (zellij preferred, tmux fallback):
 - planner
 - critic
 - coder
@@ -140,18 +140,23 @@ Each role runs in turn against a shared, accumulating context so outputs from on
 
 | Command | Description |
 |---|---|
-| `acfm agents setup` | Install optional dependencies (`opencode` and `tmux`) |
-| `acfm agents doctor` | Validate OpenCode/tmux/model preflight before start |
+| `acfm agents setup` | Install optional dependencies (`opencode` and `zellij`/`tmux`) |
+| `acfm agents doctor` | Validate OpenCode/multiplexer/model preflight before start |
 | `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 |
+| `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 |
-| `acfm agents attach` | Attach directly to the SynapseGrid tmux session |
-| `acfm agents live` | Attach to full live tmux view (all agents) |
+| `acfm agents attach` | Attach directly to the active SynapseGrid multiplexer session |
+| `acfm agents live` | Attach to full live multiplexer view (all agents) |
 | `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 |
@@ -166,7 +171,7 @@ Each role runs in turn against a shared, accumulating context so outputs from on
 
 When driving SynapseGrid from another agent via MCP, prefer asynchronous run tools over role-by-role stepping:
 
-- `collab_start_session` to initialize session and optional tmux workers
+- `collab_start_session` to initialize session and optional zellij/tmux workers
 - `collab_invoke_team` to launch full 4-role collaboration run
 - `collab_wait_run` to wait for completion/failure with bounded timeout
 - `collab_get_result` to fetch final consolidated output and run diagnostics
@@ -180,16 +185,19 @@ When driving SynapseGrid from another agent via MCP, prefer asynchronous run too
 - Attach to worker panes with `acfm agents live` (or `acfm agents attach`) to see real-time role discussion.
 - Inspect worker errors quickly with `acfm agents logs --role all --lines 120`.
 - Inspect collaborative discussion with `acfm agents transcript` and `acfm agents summary`.
-- MCP starts can now create tmux workers directly; if your assistant used headless steps before, start a new session and ensure worker spawning is enabled.
+- MCP starts can now create zellij/tmux workers directly; if your assistant used headless steps before, start a new session and ensure worker spawning is enabled.
 - 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.8",
+  "version": "2.0.0",
   "description": "Agentic Coding Framework - Multi-assistant configuration system with OpenSpec workflows",
   "main": "src/index.js",
   "exports": {

package/src/agents/config-store.js

@@ -10,10 +10,26 @@ const CONFIG_PATH = join(ACFM_DIR, 'config.json');
 
 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,14 +11,45 @@ import {
 } from './run-state.js';
 import {
   addAgentMessage,
+  appendTurnRawCapture,
   appendMeetingTurn,
   loadSessionState,
   saveSessionState,
   stopSession,
+  updateSessionDiagnostics,
   writeMeetingSummary,
   withSessionLock,
 } from './state-store.js';
 
+async function finalizeSessionArtifacts(state) {
+  const runState = ensureRunState(state);
+  const summaryMd = buildMeetingSummary(state.messages, runState, runState.sharedContext);
+  await writeMeetingSummary(state.sessionId, summaryMd);
+  const completedRun = {
+    ...runState,
+    finalSummary: extractFinalSummary(state.messages, runState),
+  };
+  return saveSessionState({
+    ...state,
+    run: completedRun,
+  });
+}
+
+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({
@@ -63,6 +94,13 @@ function ensureRunState(state) {
     round: state.round || 1,
     events: [],
     finalSummary: null,
+    sharedContext: {
+      decisions: [],
+      openIssues: [],
+      risks: [],
+      actionItems: [],
+      notes: [],
+    },
     lastError: null,
     policy: {
       timeoutPerRoleMs: 180000,
@@ -141,6 +179,8 @@ 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;
     }
@@ -178,6 +218,8 @@ export async function runTurn(sessionId, options = {}) {
 
     if (shouldStop(state)) {
       state = await stopSession(state, 'completed');
+      await maybeRecordNoTurnDiagnostic(state);
+      state = await finalizeSessionArtifacts(state);
     }
 
     return state;
@@ -244,6 +286,8 @@ export async function executeActiveTurn(sessionId, role, options = {}) {
 
     if (shouldStop(state)) {
       state = await stopSession(state, 'completed');
+      await maybeRecordNoTurnDiagnostic(state);
+      state = await finalizeSessionArtifacts(state);
     }
 
     return state;
@@ -293,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 = '';
@@ -316,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;
@@ -324,14 +372,28 @@ 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;
     }
 
@@ -343,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({
@@ -360,8 +430,6 @@ export async function runWorkerIteration(sessionId, role, options = {}) {
 
     if (shouldStop(state)) {
       state = await stopSession(state, 'completed');
-      const summaryMd = buildMeetingSummary(state.messages, ensureRunState(state), ensureRunState(state).sharedContext);
-      await writeMeetingSummary(sessionId, summaryMd);
       const finalRun = appendRunEvent({
         ...ensureRunState(state),
         status: 'completed',
@@ -372,6 +440,8 @@ export async function runWorkerIteration(sessionId, role, options = {}) {
         ...state,
         run: finalRun,
       });
+      await maybeRecordNoTurnDiagnostic(state);
+      state = await finalizeSessionArtifacts(state);
     }
 
     return state;

package/src/agents/runtime.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { writeFile } from 'node:fs/promises';
 import { COLLAB_ROLES } from './constants.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -10,7 +11,7 @@ export function roleLogPath(sessionDir, role) {
   return resolve(sessionDir, `${role}.log`);
 }
 
-export function runTmux(command, args, options = {}) {
+function runCommand(command, args, options = {}) {
   return new Promise((resolvePromise, rejectPromise) => {
     const child = spawn(command, args, {
       cwd: options.cwd || process.cwd(),
@@ -42,6 +43,14 @@ export function runTmux(command, args, options = {}) {
   });
 }
 
+function workerCommand(sessionId, role, roleLog) {
+  return `bash -lc 'node "${runnerPath}" agents worker --session ${sessionId} --role ${role} 2>&1 | tee -a "${roleLog}"'`;
+}
+
+export async function runTmux(command, args, options = {}) {
+  return runCommand(command, args, options);
+}
+
 export async function spawnTmuxSession({ sessionName, sessionDir, sessionId }) {
   const role0 = COLLAB_ROLES[0];
   const role0Log = roleLogPath(sessionDir, role0);
@@ -52,7 +61,7 @@ export async function spawnTmuxSession({ sessionName, sessionDir, sessionId }) {
     sessionName,
     '-n',
     role0,
-    `bash -lc 'node "${runnerPath}" agents worker --session ${sessionId} --role ${role0} 2>&1 | tee -a "${role0Log}"'`,
+    workerCommand(sessionId, role0, role0Log),
   ]);
 
   for (let idx = 1; idx < COLLAB_ROLES.length; idx += 1) {
@@ -63,7 +72,7 @@ export async function spawnTmuxSession({ sessionName, sessionDir, sessionId }) {
       '-t',
       sessionName,
       '-v',
-      `bash -lc 'node "${runnerPath}" agents worker --session ${sessionId} --role ${role} 2>&1 | tee -a "${roleLog}"'`,
+      workerCommand(sessionId, role, roleLog),
     ]);
   }
 
@@ -80,3 +89,69 @@ export async function tmuxSessionExists(sessionName) {
     return false;
   }
 }
+
+async function writeZellijLayout({ layoutPath, sessionId, sessionDir }) {
+  const panes = COLLAB_ROLES.map((role) => {
+    const roleLog = roleLogPath(sessionDir, role);
+    const cmd = workerCommand(sessionId, role, roleLog).replace(/"/g, '\\"');
+    return `                    pane name="${role}" command="bash" args { "-lc" "${cmd}" }`;
+  });
+
+  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],
+    '                }',
+    '            }',
+    '        }',
+    '    }',
+    '}',
+    '',
+  ].join('\n');
+
+  await writeFile(layoutPath, content, 'utf8');
+}
+
+export async function spawnZellijSession({ sessionName, sessionDir, sessionId, binaryPath }) {
+  const layoutPath = resolve(sessionDir, 'synapsegrid-layout.kdl');
+  await writeZellijLayout({ layoutPath, sessionId, sessionDir });
+  const command = binaryPath || process.env.ACFM_ZELLIJ_BIN || 'zellij';
+  await runCommand(command, ['--session', sessionName, '--layout', layoutPath, '--detach']);
+  return { layoutPath };
+}
+
+export async function zellijSessionExists(sessionName, binaryPath) {
+  try {
+    const command = binaryPath || process.env.ACFM_ZELLIJ_BIN || 'zellij';
+    const result = await runCommand(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 {
+    return false;
+  }
+}
+
+export async function runZellij(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) {
+  if (preferred === 'tmux') {
+    return hasTmuxCommand ? 'tmux' : null;
+  }
+  if (preferred === 'zellij') {
+    return hasZellijCommand ? 'zellij' : null;
+  }
+  if (hasZellijCommand) return 'zellij';
+  if (hasTmuxCommand) return 'tmux';
+  return null;
+}

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();
@@ -73,6 +95,8 @@ function initialState(task, options = {}) {
     model: options.model || null,
     roleModels: sanitizeRoleModels(options.roleModels),
     opencodeBin: options.opencodeBin || null,
+    multiplexer: options.multiplexer || 'auto',
+    multiplexerSessionName: options.multiplexerSessionName || null,
     tmuxSessionName: options.tmuxSessionName || null,
     run: createRunState(options.runPolicy, Number.isInteger(options.maxRounds) ? options.maxRounds : DEFAULT_MAX_ROUNDS),
     messages: [
@@ -92,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';
@@ -110,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 : [];
 
@@ -147,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,
@@ -154,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');
@@ -208,6 +375,8 @@ export async function listSessions(limit = 20) {
         round: state.round,
         maxRounds: state.maxRounds,
         tmuxSessionName: state.tmuxSessionName || null,
+        multiplexer: state.multiplexer || 'auto',
+        multiplexerSessionName: state.multiplexerSessionName || null,
         createdAt: state.createdAt,
         updatedAt: state.updatedAt,
         mtime: stateStats.mtimeMs,