farming-code 2.2.8 → 2.2.12

package/backend/server.js

@@ -9,6 +9,7 @@ const { execFile } = require('child_process');
 const { promisify } = require('util');
 const { URLSearchParams, pathToFileURL } = require('url');
 const AgentManager = require('./agent-manager');
+const { runtimeKind } = require('./agent-runtime-binding');
 const ConfigManager = require('./config-manager');
 const ThemeManager = require('./theme-manager');
 const TokenAuth = require('./auth');
@@ -17,6 +18,7 @@ const { listAvailableAgents, resolveCompatibleCodexExecutable } = require('./exe
 const { readClaudeSettingsSummary } = require('./claude-settings');
 const { listCodexModelOptions } = require('./codex-models');
 const { listCodexSessions } = require('./codex-session-history');
+const { unarchiveCodexSession } = require('./codex-session-archive');
 const {
   buildAgentSessionResumeCommand,
   findAgentSession,
@@ -24,6 +26,7 @@ const {
   listAgentSessions,
   normalizeProvider,
   paginateAgentSessions,
+  resolveCodexResumeModelProvider,
   searchAgentSessions,
 } = require('./agent-session-history');
 const {
@@ -33,9 +36,11 @@ const {
   resumedAgentSource,
 } = require('./main-page-session');
 const { discoverAgentWorkspaces } = require('./workspace-discovery');
+const { createWorkspaceDirectoryRouter } = require('./workspace-directory');
 const { createControlRouter } = require('./control-api');
 const { WorkspaceFileService, WorkspaceFileError } = require('./workspace-file-service');
-const { createWorkspaceFileRouter } = require('./workspace-file-router');
+const { createWorkspaceFileRouter, resolveWorkspaceRoot } = require('./workspace-file-router');
+const { WorkspaceRootRegistry, rootIdForPath } = require('./workspace-root-registry');
 const { UsageMonitor } = require('./usage-monitor');
 const { CodexContextWindowReader } = require('./codex-context-window');
 const { DEFAULT_MAX_TURNS: DEFAULT_CODEX_TRANSCRIPT_MAX_TURNS, readCodexTranscript } = require('./codex-transcript');
@@ -61,8 +66,18 @@ const {
   rewriteIndexHtmlForBasePath,
   appendIndexHtmlAssetToken,
 } = require('./index-html');
-
-const execFileAsync = promisify(execFile);
+const {
+  coalesceSessionStream,
+  deliverSessionStreamToClients,
+  shouldBroadcastSessionStreamImmediately,
+} = require('./session-stream-protocol');
+const {
+  MIN_PROTOCOL_VERSION,
+  PROTOCOL_VERSION,
+  protocolCompatible,
+  sanitizeAgentUpdatePatch,
+  validateClientMessage,
+} = require('../shared/browser-protocol');
 
 const BASE_PATH = normalizeBasePath(process.env.FARMING_BASE_PATH || '/');
 const PORT = process.env.PORT || 3000;
@@ -72,6 +87,7 @@ const WS_PATH = routePath(BASE_PATH, '/ws');
 const encodeCookieToken = TokenAuth.encodeCookieToken;
 const MAX_CODEX_TRANSCRIPT_TURNS = 1000;
 const INTERACTIVE_REFRESH_CACHE_MAX_AGE_MS = 3_000;
+const execFileAsync = promisify(execFile);
 
 const app = express();
 const server = http.createServer(app);
@@ -98,6 +114,7 @@ const agentManager = new AgentManager(configManager, {
 });
 const themeManager = new ThemeManager({ configDir: configManager.farmingDir });
 const workspaceFileService = new WorkspaceFileService();
+const workspaceRootRegistry = new WorkspaceRootRegistry(agentManager);
 const updateService = new FarmingUpdateService({
   rootDir: path.join(__dirname, '..'),
   configDir: configManager.farmingDir,
@@ -115,7 +132,7 @@ const usageSummaryCache = new AsyncCache(() => usageMonitor.getUsageSummary(), {
 });
 const codexModelOptionsCache = new AsyncCache(() => listCodexModelOptions(), {
   ttlMs: 5 * 60_000,
-  staleMs: 30 * 60_000,
+  staleMs: 5 * 60_000,
 });
 function configuredProviderHomes() {
   const settings = configManager.getSettings();
@@ -367,11 +384,13 @@ function shareTargetQueryFromBody(body) {
   const agentId = shareTargetString(target.agentId, 160);
   const absolutePath = shareTargetString(target.absolutePath, 2048);
   const projectLabel = shareTargetString(target.projectLabel, 160);
+  const readingAnchor = shareTargetString(target.readingAnchor, 1800);
   if (!kind || kind === 'agent' && !agentId || kind !== 'agent' && !absolutePath && !agentId && !projectLabel) return '';
 
   const params = new URLSearchParams();
   params.set('ftarget', kind);
   if (agentId) params.set('agent', agentId);
+  if (kind === 'agent' && readingAnchor && /^[A-Za-z0-9_-]+$/.test(readingAnchor)) params.set('fra', readingAnchor);
   if (absolutePath) params.set('path', absolutePath);
   if (projectLabel) params.set('project', projectLabel);
 
@@ -478,14 +497,28 @@ app.use(`${crtEntryPath}/shared`, express.static(frontendDir, { index: false }))
 app.use(`${crtEntryPath}/`, express.static(crtFrontendDir, { index: false }));
 app.use(BASE_PATH || '/', express.static(staticAppDir, { index: false }));
 
-app.use(routePath(BASE_PATH, '/api/files'), createWorkspaceFileRouter(agentManager, workspaceFileService));
+app.use(routePath(BASE_PATH, '/api/files'), createWorkspaceFileRouter(agentManager, workspaceFileService, {
+  rootRegistry: workspaceRootRegistry,
+}));
 
 app.use(routePath(BASE_PATH, '/api/review-sessions'), createReviewSessionRouter(reviewSessionService));
 app.use(routePath(BASE_PATH, '/api/reviews'), createReviewDiffRouter(reviewDiffService, reviewSessionService));
 app.use(routePath(BASE_PATH, '/api/reviews'), createReviewStateRouter(reviewStateStore));
 
+if (process.env.NODE_ENV === 'test' && process.env.FARMING_E2E_FAKE_EXECUTABLES === '1') {
+  app.post(routePath(BASE_PATH, '/api/control/e2e/close-websockets'), express.json(), (_req, res) => {
+    const clients = [...wss.clients].filter(client => client.readyState === WebSocket.OPEN);
+    res.json({ closing: clients.length, code: 1013 });
+    setImmediate(() => {
+      clients.forEach(client => client.close(1013, 'terminal stream backpressure test'));
+    });
+  });
+}
+
 app.use(routePath(BASE_PATH, '/api/control'), createControlRouter(agentManager, {
   notifyUpdate: broadcastState,
+  allowConcurrentTestControl: process.env.NODE_ENV === 'test'
+    && process.env.FARMING_E2E_FAKE_EXECUTABLES === '1',
 }));
 
 app.use(routePath(BASE_PATH, '/api/app-server'), createAppServerApiRouter({
@@ -541,6 +574,8 @@ app.get(routePath(BASE_PATH, '/api/workspaces/complete'), async (req, res) => {
   }
 });
 
+app.use(routePath(BASE_PATH, '/api/workspaces'), createWorkspaceDirectoryRouter());
+
 app.get(routePath(BASE_PATH, '/api/skills'), (_req, res) => {
   res.json({ skills: getMainAgentSkillsCatalog() });
 });
@@ -640,8 +675,16 @@ app.post(
 );
 
 app.get(routePath(BASE_PATH, '/api/codex/models'), async (req, res) => {
-  const catalog = await codexModelOptionsCache.get('catalog');
-  res.json(catalog);
+  try {
+    const catalog = await codexModelOptionsCache.get('catalog');
+    res.json(catalog);
+  } catch (error) {
+    const timedOut = error && error.code === 'CODEX_MODELS_TIMEOUT';
+    res.status(timedOut ? 504 : 502).json({
+      error: error && error.message ? error.message : 'Failed to load Codex model catalog',
+      code: error && error.code ? error.code : 'CODEX_MODELS_FAILED',
+    });
+  }
 });
 
 app.get(routePath(BASE_PATH, '/api/claude/settings'), (req, res) => {
@@ -662,7 +705,10 @@ app.get(routePath(BASE_PATH, '/api/usage'), async (req, res) => {
 app.get(routePath(BASE_PATH, '/api/usage/day'), async (req, res) => {
   try {
     const date = String(req.query.date || '').trim();
-    const detail = await usageMonitor.getUsageDay(date, { fresh: req.query.fresh === '1' });
+    const detail = await usageMonitor.getUsageDay(date, {
+      fresh: req.query.fresh === '1',
+      live: req.query.live === '1',
+    });
     res.json({ detail });
   } catch (error) {
     const invalidDate = error instanceof RangeError;
@@ -943,7 +989,7 @@ app.get(routePath(BASE_PATH, '/api/agents/:agentId/codex-transcript'), async (re
       : DEFAULT_CODEX_TRANSCRIPT_MAX_TURNS;
     const transcript = await readCodexTranscript(providerSession.sessionId, {
       maxTurns,
-      codexHome: providerSession.codexRuntimeMode === 'app-server'
+      codexHome: runtimeKind(providerSession) === 'app-server'
         ? (providerSession.codexAppServerHomePath || providerSession.providerHomePath || '')
         : (providerSession.providerHomePath || ''),
     });
@@ -1222,6 +1268,38 @@ app.delete(routePath(BASE_PATH, '/api/agents/:agentId/codex-goal'), async (req,
   }
 });
 
+app.post(routePath(BASE_PATH, '/api/agents/:agentId/codex-terminal-profile'), express.json(), async (req, res) => {
+  const requestAbort = new globalThis.AbortController();
+  const abortRequest = () => requestAbort.abort(new Error('Terminal profile request was canceled'));
+  const abortClosedResponse = () => {
+    if (!res.writableEnded) abortRequest();
+  };
+  req.once('aborted', abortRequest);
+  res.once('close', abortClosedResponse);
+  try {
+    const profile = await agentManager.setCodexTerminalProfile(req.params.agentId, {
+      model: req.body?.model,
+      effort: req.body?.effort,
+      serviceTier: req.body?.serviceTier,
+    }, {
+      signal: requestAbort.signal,
+      timeoutMs: 44_000,
+    });
+    res.json({ profile });
+  } catch (error) {
+    const message = error && error.message ? error.message : 'Failed to update Codex Terminal profile';
+    const status = message === 'Agent not found'
+      ? 404
+      : /^A valid Codex /.test(message)
+        ? 400
+        : 409;
+    if (!res.headersSent && !res.destroyed) res.status(status).json({ error: message });
+  } finally {
+    req.off('aborted', abortRequest);
+    res.off('close', abortClosedResponse);
+  }
+});
+
 app.patch(routePath(BASE_PATH, '/api/agents/:agentId'), express.json(), async (req, res) => {
   const body = req.body || {};
   const updates = {};
@@ -1253,6 +1331,15 @@ app.patch(routePath(BASE_PATH, '/api/agents/:agentId'), express.json(), async (r
   if (typeof body.readAttentionSeq === 'number' && Number.isFinite(body.readAttentionSeq)) {
     flagPatch.readAttentionSeq = body.readAttentionSeq;
   }
+  if (
+    typeof body.readOutputEpoch === 'string'
+    && body.readOutputEpoch
+    && typeof body.readOutputSeq === 'number'
+    && Number.isFinite(body.readOutputSeq)
+  ) {
+    flagPatch.readOutputEpoch = body.readOutputEpoch;
+    flagPatch.readOutputSeq = body.readOutputSeq;
+  }
 
   if (flagPatch.archived === true) {
     const result = await agentManager.archiveAgent(req.params.agentId);
@@ -1266,6 +1353,7 @@ app.patch(routePath(BASE_PATH, '/api/agents/:agentId'), express.json(), async (r
     delete flagPatch.archived;
   }
 
+  let flagUpdateRequiresState = false;
   if (Object.keys(flagPatch).length > 0) {
     const result = agentManager.updateAgentFlags(req.params.agentId, flagPatch);
     if (result.error) {
@@ -1275,6 +1363,7 @@ app.patch(routePath(BASE_PATH, '/api/agents/:agentId'), express.json(), async (r
     }
     Object.assign(updates, result);
     delete updates.agentId;
+    flagUpdateRequiresState = result.requiresState === true;
   }
 
   if (typeof body.launchPermissionMode === 'string') {
@@ -1304,11 +1393,13 @@ app.patch(routePath(BASE_PATH, '/api/agents/:agentId'), express.json(), async (r
   }
 
   if (Object.keys(updates).length === 0) {
-    res.status(400).json({ error: 'customTitle, task, pinned, unread, archived, readAttentionSeq, launchPermissionMode, or agentRuntimeMode is required' });
+    res.status(400).json({ error: 'customTitle, task, pinned, unread, archived, readAttentionSeq, readOutputEpoch/readOutputSeq, launchPermissionMode, or agentRuntimeMode is required' });
     return;
   }
 
-  scheduleBroadcastState();
+  if (flagUpdateRequiresState || typeof body.task === 'string' || typeof body.customTitle === 'string' || typeof body.launchPermissionMode === 'string' || typeof body.agentRuntimeMode === 'string') {
+    scheduleBroadcastState();
+  }
   res.json({ agentId: req.params.agentId, ...updates });
 });
 
@@ -1339,6 +1430,65 @@ app.post(routePath(BASE_PATH, '/api/agents/:agentId/fork'), express.json(), asyn
   res.status(201).json(result);
 });
 
+function resolveProjectActionRoot(rootId) {
+  const root = workspaceRootRegistry.resolve(rootId);
+  if (!root || root.kind === 'global') {
+    throw new WorkspaceFileError('project workspace is required', 400);
+  }
+  return root;
+}
+
+app.post(routePath(BASE_PATH, '/api/projects/reveal'), express.json(), async (req, res) => {
+  try {
+    const root = resolveProjectActionRoot(req.body?.rootId);
+    const command = process.platform === 'darwin'
+      ? 'open'
+      : process.platform === 'win32'
+        ? 'explorer'
+        : 'xdg-open';
+    await execFileAsync(command, [root.canonicalPath], {
+      timeout: 15000,
+      maxBuffer: 1024 * 1024,
+    });
+    res.json({ revealed: true, workspace: root.canonicalPath });
+  } catch (error) {
+    const status = error instanceof WorkspaceFileError ? error.statusCode : 500;
+    res.status(status).json({ error: error.message || 'Failed to reveal project workspace' });
+  }
+});
+
+app.post(routePath(BASE_PATH, '/api/projects/create-worktree'), express.json(), async (req, res) => {
+  let created = null;
+  let previousProjects = null;
+  try {
+    const root = resolveProjectActionRoot(req.body?.rootId);
+    created = await agentManager.createPermanentWorktree(root.canonicalPath);
+    previousProjects = configManager.getSettings().projectWorkspaces || [];
+    configManager.updateSettings({
+      projectWorkspaces: [
+        created.workspace,
+        ...previousProjects.filter(workspace => workspace !== created.workspace),
+      ],
+    });
+    res.status(201).json({
+      workspace: created.workspace,
+      branch: created.branch,
+      projectWorkspaces: configManager.getSettings().projectWorkspaces,
+    });
+  } catch (error) {
+    if (created) await agentManager.rollbackPermanentWorktree(created);
+    if (previousProjects) {
+      try {
+        configManager.updateSettings({ projectWorkspaces: previousProjects });
+      } catch {
+        // Keep the original error visible; the failed settings write is already the root cause.
+      }
+    }
+    const status = error instanceof WorkspaceFileError ? error.statusCode : 400;
+    res.status(status).json({ error: error.message || 'Failed to create permanent worktree' });
+  }
+});
+
 app.post(routePath(BASE_PATH, '/api/projects/delete-worktree'), express.json(), async (req, res) => {
   const body = req.body || {};
   const workspace = typeof body.workspace === 'string' ? body.workspace : '';
@@ -1427,38 +1577,6 @@ function forgetMainPageAgentSession(provider, sessionId, providerHomeId = '') {
   });
 }
 
-async function unarchiveCodexSession(sessionId, session = {}) {
-  const codexResolution = resolveCompatibleCodexExecutable(session.cliVersion || '');
-  if (!codexResolution.compatible) {
-    return {
-      error: codexResolution.error || 'Codex CLI is not compatible with this session',
-      status: 400,
-    };
-  }
-
-  try {
-    await execFileAsync(codexResolution.path || 'codex', ['unarchive', sessionId], {
-      cwd: session.cwd || session.workspace || os.homedir(),
-      env: session.providerHomePath
-        ? { ...process.env, CODEX_HOME: session.providerHomePath }
-        : process.env,
-      timeout: 30_000,
-      maxBuffer: 1024 * 1024,
-    });
-    return { unarchived: true };
-  } catch (error) {
-    const message = [
-      error && error.stdout ? String(error.stdout).trim() : '',
-      error && error.stderr ? String(error.stderr).trim() : '',
-      error && error.message ? String(error.message).trim() : '',
-    ].filter(Boolean).join('\n') || 'failed to unarchive Codex session';
-    return {
-      error: message,
-      status: 409,
-    };
-  }
-}
-
 async function resumeAgentSessionById(provider, rawSessionId, options = {}) {
   const normalizedProvider = normalizeProvider(provider);
   const sessionId = String(rawSessionId || '').trim();
@@ -1551,6 +1669,9 @@ async function resumeAgentSessionById(provider, rawSessionId, options = {}) {
     const command = buildAgentSessionResumeCommand(normalizedProvider, sessionId, {
       fork: shouldFork,
       cwd: workingDirectory,
+      modelProvider: normalizedProvider === 'codex'
+        ? resolveCodexResumeModelProvider(session ? session.providerHomePath : '')
+        : '',
     });
 
     if (!command) {
@@ -1584,6 +1705,7 @@ async function resumeAgentSessionById(provider, rawSessionId, options = {}) {
         providerHomeId: resolvedProviderHomeId,
         providerHomePath: session ? (session.providerHomePath || '') : '',
         autoReadInitialAttention: options.autoReadInitialAttention === true,
+        preserveProviderSessionProfile: normalizedProvider === 'codex',
       });
       Promise.resolve(startResult).catch((error) => {
         resolve({ error: error.message || 'failed to resume agent session', status: 500 });
@@ -1653,10 +1775,29 @@ async function autoResumeMainPageAgentSessions() {
   const sessions = mainPageAgentSessionsToAutoResume(configManager.getSettings());
   if (sessions.length === 0) return;
 
+  let knownSessions;
+  try {
+    knownSessions = await agentSessionsCache.get(
+      JSON.stringify(configManager.getSettings().agentHomes || {}),
+      { maxAgeMs: INTERACTIVE_REFRESH_CACHE_MAX_AGE_MS }
+    );
+  } catch (error) {
+    console.warn('Failed to load Agent session catalog for auto-resume:', error && (error.message || error));
+    return;
+  }
+  const knownSessionByKey = new Map(knownSessions.map(session => [
+    mainPageAgentSessionKey(session.provider, session.id, session.providerHomeId || 'default'),
+    session,
+  ]));
+
   let resumedCount = 0;
   for (const session of sessions) {
     try {
-      const sessionDetails = await findAgentSession(session.provider, session.sessionId, { limit: 200, providerHomeId: session.providerHomeId || 'default', providerHomes: configuredProviderHomes() });
+      const sessionDetails = knownSessionByKey.get(mainPageAgentSessionKey(
+        session.provider,
+        session.sessionId,
+        session.providerHomeId || 'default'
+      ));
       if (!sessionDetails) {
         console.warn('Dropping stale main-page session from auto-resume:', session.provider, session.sessionId);
         forgetMainPageAgentSession(session.provider, session.sessionId, session.providerHomeId || 'default');
@@ -1705,7 +1846,7 @@ app.post(routePath(BASE_PATH, '/api/settings'), express.json(), (req, res) => {
     success: true,
     settings: configManager.getSettings()
   });
-  broadcastState();
+  scheduleBroadcastState();
 });
 
 app.post(routePath(BASE_PATH, '/api/themes/:themeId/set'), express.json(), (req, res) => {
@@ -1773,13 +1914,30 @@ wss.on('connection', (ws, req) => {
   }
 
   console.log('Client connected');
+  ws.connectionId = crypto.randomUUID();
 
   ws.on('message', (message) => {
     try {
       const data = JSON.parse(message);
+      const validation = validateClientMessage(data);
+      if (!validation.ok) {
+        ws.send(JSON.stringify({
+          type: 'protocol-error',
+          protocolVersion: PROTOCOL_VERSION,
+          requestId: typeof data?.requestId === 'string' ? data.requestId : '',
+          message: validation.error,
+        }));
+        return;
+      }
       handleMessage(ws, data);
     } catch (e) {
       console.error('Failed to parse message:', e);
+      ws.send(JSON.stringify({
+        type: 'protocol-error',
+        protocolVersion: PROTOCOL_VERSION,
+        requestId: '',
+        message: 'message must be valid JSON',
+      }));
     }
   });
   
@@ -1788,6 +1946,11 @@ wss.on('connection', (ws, req) => {
     console.log('Client disconnected');
   });
   
+  ws.send(JSON.stringify({
+    type: 'protocol-hello',
+    protocolVersion: PROTOCOL_VERSION,
+    minProtocolVersion: MIN_PROTOCOL_VERSION,
+  }));
   sendState(ws);
 });
 
@@ -1872,6 +2035,15 @@ async function sendComposerInputMessage(ws, data) {
     }
   }
   if (!targetAgentId || content.length === 0) return;
+  const targetAgent = agentManager.getState().agents.find(agent => agent.id === targetAgentId);
+  const structuredRuntime = targetAgent && runtimeKind(targetAgent) !== 'terminal';
+  if (!structuredRuntime) {
+    ws.send(JSON.stringify({
+      type: 'error',
+      message: 'Terminal Composer input requires the active terminal owner',
+    }));
+    return;
+  }
   try {
     await agentManager.sendComposerMessage(targetAgentId, content);
   } catch (error) {
@@ -1901,6 +2073,13 @@ async function respondToAppServerRequest(ws, data) {
 
 function handleMessage(ws, data) {
   switch (data.type) {
+    case 'protocol-hello':
+      if (!protocolCompatible(data.protocolVersion)) {
+        ws.close(4002, `Unsupported Farming protocol version ${data.protocolVersion}`);
+        return;
+      }
+      ws.protocolVersion = data.protocolVersion;
+      break;
     case 'start-agent': {
       const workspace = data.workspace || null;
       agentManager.startAgent(data.command, workspace, (agentId, error) => {
@@ -1964,7 +2143,7 @@ function handleMessage(ws, data) {
 
     case 'interrupt-agent':
       if (data.agentId) {
-        agentManager.interruptAgent(data.agentId);
+        void agentManager.interruptAgent(data.agentId);
       }
       break;
       
@@ -1983,10 +2162,14 @@ function handleMessage(ws, data) {
 
     case 'resize-agent':
       if (data.agentId && Number.isFinite(data.cols) && Number.isFinite(data.rows)) {
-        agentManager.resizeAgentSession(data.agentId, data.cols, data.rows);
+        agentManager.requestAgentSessionResize(data.agentId, data.cols, data.rows);
       }
       break;
 
+    case 'clear-terminal':
+      if (data.agentId) void agentManager.clearAgentSessionBuffer(data.agentId);
+      break;
+
     case 'watch-workspace-files':
       watchWorkspaceFiles(ws, data);
       break;
@@ -2054,10 +2237,7 @@ async function watchWorkspaceFiles(ws, data) {
       return;
     }
 
-    const root = agentManager.getAgentWorkspaceRoot(data.agentId);
-    if (!root) {
-      throw new WorkspaceFileError('agent not found', 404);
-    }
+    const root = resolveWorkspaceRoot(agentManager, data.agentId);
 
     const unsubscribe = await workspaceFileService.subscribe(root, (event) => {
       if (ws.readyState !== WebSocket.OPEN) return;
@@ -2081,8 +2261,14 @@ async function watchWorkspaceFiles(ws, data) {
 }
 
 function buildStatePayload() {
+  const state = agentManager.getState();
   return {
-    ...agentManager.getState(),
+    ...state,
+    agents: state.agents.map(agent => ({
+      ...agent,
+      workspaceRootId: rootIdForPath(agent.projectWorkspace || agent.gitWorktree?.workspace || agent.cwd),
+    })),
+    workspaceRoots: workspaceRootRegistry.list(),
     mainPageSessionKeys: typeof configManager.getMainPageSessionKeys === 'function'
       ? configManager.getMainPageSessionKeys()
       : (Array.isArray(configManager.getSettings().mainPageSessionKeys) ? configManager.getSettings().mainPageSessionKeys : []),
@@ -2097,22 +2283,39 @@ function sendState(ws) {
   });
 }
 
+function previewForClient(preview, client) {
+  if (!preview || !client || client.focusedAgentId !== preview.agentId || !preview.previewSnapshot) {
+    return preview;
+  }
+  // The active terminal is hydrated from its authoritative session-view and
+  // receives live session-output. Sending its sidebar snapshot again adds a
+  // large, unrelated React update to every keystroke in a full-screen TUI.
+  return {
+    ...preview,
+    previewSnapshot: null,
+  };
+}
+
 function sendPreview(ws, preview) {
   ws.send(JSON.stringify({
     type: 'session-preview',
-    preview,
+    preview: previewForClient(preview, ws),
   }));
 }
 
 const STATE_BROADCAST_INTERVAL_MS = 120;
 const PREVIEW_BROADCAST_INTERVAL_MS = 500;
 const SESSION_STREAM_BROADCAST_INTERVAL_MS = 33;
+const AGENT_ACTIVITY_BROADCAST_DELAY_MS = SESSION_STREAM_BROADCAST_INTERVAL_MS;
 const MAX_SESSION_STREAM_CLIENT_BUFFERED_AMOUNT = 4 * 1024 * 1024;
 let stateBroadcastTimer = null;
 let lastStateBroadcastAt = 0;
 const pendingPreviewBroadcasts = new Map();
+const pendingAgentActivityBroadcasts = new Map();
+const pendingAgentUpdates = new Map();
 const pendingSessionStreams = new Map();
 let sessionStreamBroadcastTimer = null;
+let lastSessionStreamBroadcastAt = 0;
 let shutdownStarted = false;
 
 function broadcastState() {
@@ -2146,16 +2349,11 @@ function scheduleBroadcastState() {
 }
 
 function broadcastSessionPreview(preview) {
-  const message = JSON.stringify({
-    type: 'session-preview',
-    preview,
-  });
-
   wss.clients.forEach((client) => {
     const previewAllowed = client.previewScope !== 'none'
       && (client.previewScope !== 'focused' || client.focusedAgentId === preview.agentId);
     if (client.readyState === WebSocket.OPEN && previewAllowed) {
-      client.send(message);
+      sendPreview(client, preview);
     }
   });
 }
@@ -2214,6 +2412,78 @@ agentManager.on('provider-session-updated', () => {
   scheduleBroadcastState();
 });
 
+function broadcastAgentActivity(activity) {
+  const message = JSON.stringify({
+    type: 'agent-activity',
+    activity,
+  });
+  wss.clients.forEach((client) => {
+    if (client.readyState === WebSocket.OPEN) {
+      client.send(message);
+    }
+  });
+}
+
+function scheduleAgentActivityBroadcast(activity) {
+  if (!activity || !activity.agentId) return;
+  const agentId = activity.agentId;
+  const existing = pendingAgentActivityBroadcasts.get(agentId);
+  if (existing) {
+    existing.activity = activity;
+    return;
+  }
+  const entry = {
+    activity,
+    timer: setTimeout(() => {
+      pendingAgentActivityBroadcasts.delete(agentId);
+      broadcastAgentActivity(entry.activity);
+    }, AGENT_ACTIVITY_BROADCAST_DELAY_MS),
+  };
+  entry.timer.unref?.();
+  pendingAgentActivityBroadcasts.set(agentId, entry);
+}
+
+agentManager.onAgentActivity(scheduleAgentActivityBroadcast);
+
+function scheduleAgentUpdate(update) {
+  const patch = sanitizeAgentUpdatePatch(update?.patch);
+  if (!update?.agentId || !patch) return;
+  const existing = pendingAgentUpdates.get(update.agentId);
+  if (existing) {
+    Object.assign(existing.patch, patch);
+    return;
+  }
+  const entry = {
+    patch,
+    timer: setTimeout(() => {
+      pendingAgentUpdates.delete(update.agentId);
+      const message = JSON.stringify({
+        type: 'agent-update',
+        update: { agentId: update.agentId, patch: entry.patch },
+      });
+      wss.clients.forEach((client) => {
+        if (client.readyState === WebSocket.OPEN) client.send(message);
+      });
+    }, AGENT_ACTIVITY_BROADCAST_DELAY_MS),
+  };
+  entry.timer.unref?.();
+  pendingAgentUpdates.set(update.agentId, entry);
+}
+
+agentManager.on('agent-update', scheduleAgentUpdate);
+
+function broadcastAgentRead(read) {
+  if (!read || !read.agentId) return;
+  const message = JSON.stringify({ type: 'agent-read', read });
+  wss.clients.forEach((client) => {
+    if (client.readyState === WebSocket.OPEN) {
+      client.send(message);
+    }
+  });
+}
+
+agentManager.on('agent-read', broadcastAgentRead);
+
 function sessionStreamKey(stream) {
   return `${stream.agentId || ''}\0${stream.sessionSource || ''}`;
 }
@@ -2223,13 +2493,10 @@ function broadcastSessionStream(stream) {
     type: 'session-output',
     stream
   });
-
-  wss.clients.forEach((client) => {
-    if (client.readyState === WebSocket.OPEN) {
-      if (client.streamScope === 'focused' && client.focusedAgentId !== stream.agentId) return;
-      if (client.bufferedAmount > MAX_SESSION_STREAM_CLIENT_BUFFERED_AMOUNT) return;
-      client.send(message);
-    }
+  deliverSessionStreamToClients(wss.clients, stream, {
+    openState: WebSocket.OPEN,
+    maxBufferedAmount: MAX_SESSION_STREAM_CLIENT_BUFFERED_AMOUNT,
+    message,
   });
 }
 
@@ -2237,31 +2504,26 @@ function flushSessionStreams() {
   sessionStreamBroadcastTimer = null;
   const streams = Array.from(pendingSessionStreams.values());
   pendingSessionStreams.clear();
+  if (streams.length > 0) lastSessionStreamBroadcastAt = Date.now();
   streams.forEach(broadcastSessionStream);
 }
 
 function scheduleSessionStreamBroadcast(stream) {
   if (!stream || !stream.agentId) return;
+  const now = Date.now();
+  if (shouldBroadcastSessionStreamImmediately({
+    pendingCount: pendingSessionStreams.size,
+    lastBroadcastAt: lastSessionStreamBroadcastAt,
+    now,
+    intervalMs: SESSION_STREAM_BROADCAST_INTERVAL_MS,
+  })) {
+    lastSessionStreamBroadcastAt = now;
+    broadcastSessionStream(coalesceSessionStream(null, stream));
+    return;
+  }
   const key = sessionStreamKey(stream);
   const existing = pendingSessionStreams.get(key);
-  const data = typeof stream.data === 'string' ? stream.data : String(stream.data || '');
-  const outputSeq = Number.isFinite(stream.outputSeq) ? stream.outputSeq : undefined;
-
-  if (existing) {
-    pendingSessionStreams.set(key, {
-      ...stream,
-      data: stream.replace === true ? data : `${existing.data || ''}${data}`,
-      replace: existing.replace || stream.replace === true,
-      outputSeq: outputSeq ?? existing.outputSeq,
-    });
-  } else {
-    pendingSessionStreams.set(key, {
-      ...stream,
-      data,
-      replace: stream.replace === true,
-      outputSeq,
-    });
-  }
+  pendingSessionStreams.set(key, coalesceSessionStream(existing, stream));
 
   if (!sessionStreamBroadcastTimer) {
     sessionStreamBroadcastTimer = setTimeout(flushSessionStreams, SESSION_STREAM_BROADCAST_INTERVAL_MS);
@@ -2280,6 +2542,14 @@ function clearBroadcastTimers() {
     }
   }
   pendingPreviewBroadcasts.clear();
+  for (const entry of pendingAgentActivityBroadcasts.values()) {
+    if (entry && entry.timer) clearTimeout(entry.timer);
+  }
+  pendingAgentActivityBroadcasts.clear();
+  for (const entry of pendingAgentUpdates.values()) {
+    if (entry && entry.timer) clearTimeout(entry.timer);
+  }
+  pendingAgentUpdates.clear();
   if (sessionStreamBroadcastTimer) {
     clearTimeout(sessionStreamBroadcastTimer);
     sessionStreamBroadcastTimer = null;