farming-code 2.2.8 → 2.2.12

package/backend/local-session-engine.js

@@ -9,6 +9,25 @@ const {
 const { terminalInputToPtyString } = require('./input-parts');
 const { deriveTerminalStatus } = require('./terminal-status');
 const { normalizeInteractiveTerminalEnv } = require('./agent-env');
+const {
+  allocateNativePtyRuntimeGeneration,
+  formatNativePtyRuntimeEpoch,
+} = require('./native-pty-controller-generation');
+const storageLayout = require('./storage-layout');
+const {
+  acknowledgeTerminalReducerData,
+  createTerminalReducerFlowControl,
+  ensureTerminalReducerFlowControl,
+  enqueueTerminalReducerData,
+  resetTerminalReducerFlowControl,
+} = require('./terminal-reducer-flow-control');
+const {
+  captureTerminalAttachCheckpoint,
+} = require('./terminal-attach-checkpoint');
+const {
+  acceptTerminalExitData,
+  waitForTerminalExitDataQuiescence,
+} = require('./terminal-exit-quiescence');
 
 const CONTROLLED_BASH_PROMPT = [
   '\\[\\e[90m\\]│\\[\\e[0m\\] ',
@@ -145,8 +164,9 @@ function normalizeShellSessionOptions(options) {
 }
 
 class LocalSessionEngine extends SessionEngine {
-  constructor() {
+  constructor(options = {}) {
     super();
+    this.configDir = options.configDir || storageLayout.farmingConfigDir();
     this.sessions = new Map();
     this.screenWorkerPool = new TerminalScreenWorkerPool({
       size: 3,
@@ -162,9 +182,13 @@ class LocalSessionEngine extends SessionEngine {
     const normalized = normalizeShellSessionOptions(options);
     const previewCols = normalized.cols || 80;
     const previewRows = normalized.rows || 30;
+    const runtimeGeneration = await allocateNativePtyRuntimeGeneration(this.configDir);
+    const runtimeEpoch = formatNativePtyRuntimeEpoch(runtimeGeneration);
     const screenWorker = await this.screenWorkerPool.acquire({
       cols: previewCols,
       rows: previewRows,
+      runtimeEpoch,
+      runtimeGeneration,
     });
 
     let ptyProcess;
@@ -190,6 +214,11 @@ class LocalSessionEngine extends SessionEngine {
       process: ptyProcess,
       output: '',
       outputSeq: 0,
+      stateRevision: 0,
+      runtimeEpoch,
+      stateProofAvailable: true,
+      reducerFlowControl: createTerminalReducerFlowControl(),
+      reducerCommitQueue: Promise.resolve(),
       renderOutput: '',
       previewText: '',
       previewSnapshot: null,
@@ -216,7 +245,7 @@ class LocalSessionEngine extends SessionEngine {
 
     session.screenWorker.on('preview', ({ previewText, title, cols, rows, previewSnapshot }) => {
       const current = this.sessions.get(session.id);
-      if (!current) return;
+      if (current !== session) return;
 
       current.previewText = previewText || '';
       current.previewSnapshot = previewSnapshot || null;
@@ -227,7 +256,8 @@ class LocalSessionEngine extends SessionEngine {
         current.title = title;
         this.emit('session-title', {
           sessionId: current.id,
-          title: current.title
+          title: current.title,
+          runtimeEpoch: current.runtimeEpoch,
         });
       }
 
@@ -237,184 +267,275 @@ class LocalSessionEngine extends SessionEngine {
         cols: current.previewCols,
         rows: current.previewRows,
         previewSnapshot: current.previewSnapshot,
+        runtimeEpoch: current.runtimeEpoch,
       });
     });
 
     session.screenWorker.on('error', (error) => {
-      this.emit('session-error', {
-        sessionId: session.id,
-        error: `Failed to update terminal screen state: ${error.message}`,
-        fatal: false
-      });
+      this.failSessionScreenState(session, error);
     });
 
     this.sessions.set(session.id, session);
     this.emit('session-started', {
       sessionId: session.id,
       status: session.status,
-      startedAt: session.startedAt
+      startedAt: session.startedAt,
+      runtimeEpoch: session.runtimeEpoch,
+      outputSeq: session.outputSeq,
+      stateRevision: session.stateRevision
     });
 
-    ptyProcess.onData((data) => {
-      const current = this.sessions.get(session.id);
-      if (!current) return;
-
-      const busyState = parseShellBusyMarkers(data, current.terminalBusy, current.shellBusyMarkerPending);
-      current.shellBusyMarkerPending = busyState.pending;
-      if (busyState.markerSeen) {
-        const markerAt = Date.now();
-        current.terminalBusy = busyState.terminalBusy;
-        if (busyState.cwd) {
-          current.shellCwd = busyState.cwd;
-        }
-        if (busyState.exitCodeSeen) {
-          current.shellLastExitCode = busyState.lastExitCode;
-        }
-        if (busyState.shellEvent) {
-          current.shellLastEvent = busyState.shellEvent;
-        }
-        if (busyState.shellEvent === 'start') {
-          current.shellCommandStartedAt = markerAt;
-        }
-        if (busyState.commandTextSeen) {
-          current.shellCommand = busyState.shellCommand || '';
-        }
-        if (busyState.shellEvent === 'finish') {
-          const commandStartedAt = current.shellCommandStartedAt;
-          if (current.shellCommand) {
-            current.shellLastCommand = current.shellCommand;
-          }
-          if (typeof commandStartedAt === 'number') {
-            current.shellLastCommandStartedAt = commandStartedAt;
-            current.shellLastCommandFinishedAt = markerAt;
-            current.shellLastCommandDurationMs = Math.max(0, markerAt - commandStartedAt);
-          }
-          current.shellCommand = '';
-          current.shellCommandStartedAt = null;
-        }
-        this.emit('session-busy-state', {
-          sessionId: current.id,
-          terminalBusy: current.terminalBusy,
-          cwd: current.shellCwd || current.cwd,
-          lastExitCode: current.shellLastExitCode,
-          shellEvent: current.shellLastEvent,
-          shellCommand: current.shellCommand,
-          shellLastCommand: current.shellLastCommand,
-          shellCommandStartedAt: current.shellCommandStartedAt,
-          shellLastCommandStartedAt: current.shellLastCommandStartedAt,
-          shellLastCommandFinishedAt: current.shellLastCommandFinishedAt,
-          shellLastCommandDurationMs: current.shellLastCommandDurationMs,
-          statusMarkerSeen: busyState.statusMarkerSeen,
-          busyMarkerSeen: busyState.busyMarkerSeen,
-        });
-      }
+    ptyProcess.onData(data => this.handleSessionData(session.id, data, session));
 
-      data = busyState.data;
-      if (!data) return;
+    ptyProcess.onExit(({ code }) => {
+      void this.handleSessionExit(session, code);
+    });
 
-      current.outputSeq += 1;
-      current.output += data;
-      current.lastActivityAt = Date.now();
+    return {
+      sessionId: session.id,
+      status: session.status
+    };
+  }
 
-      if (current.output.length > 10000) {
-        current.output = current.output.slice(-10000);
-      }
+  handleSessionExit(session, code) {
+    if (this.sessions.get(session.id) !== session || session.status === 'exited') {
+      return Promise.resolve();
+    }
+    if (session.exitFinalizationPromise) return session.exitFinalizationPromise;
+    const finalization = this.finalizeSessionExit(session, code);
+    session.exitFinalizationPromise = finalization;
+    return finalization;
+  }
 
-      const fallbackTitle = extractLatestTerminalTitle(data);
-      if (fallbackTitle && fallbackTitle !== current.title) {
-        current.title = fallbackTitle;
-        this.emit('session-title', {
-          sessionId: current.id,
-          title: current.title
-        });
+  async finalizeSessionExit(session, code) {
+    const quiesced = await waitForTerminalExitDataQuiescence(session, {
+      flushMs: this.terminalExitDataFlushMs,
+      isCurrent: () => this.sessions.get(session.id) === session,
+    });
+    if (!quiesced) return;
+    await Promise.resolve(session.reducerCommitQueue).catch(() => {});
+    if (this.sessions.get(session.id) !== session) return;
+    const finalCheckpoint = await captureTerminalAttachCheckpoint(session, { requireCurrentCut: true });
+    if (this.sessions.get(session.id) !== session) return;
+
+    session.status = 'exited';
+    session.exitedAt = Date.now();
+    resetTerminalReducerFlowControl(
+      ensureTerminalReducerFlowControl(session),
+      session.process,
+    );
+    if (finalCheckpoint) {
+      session.finalCheckpoint = Object.freeze({ ...finalCheckpoint });
+      session.renderOutput = finalCheckpoint.renderOutput;
+      session.previewText = finalCheckpoint.previewText;
+      session.previewSnapshot = finalCheckpoint.previewSnapshot;
+      session.previewCols = finalCheckpoint.cols;
+      session.previewRows = finalCheckpoint.rows;
+      session.title = finalCheckpoint.title || session.title;
+    } else {
+      this.failSessionScreenState(session, new Error('Unable to capture the exact final Terminal checkpoint'));
+    }
+    if (session.screenWorker) {
+      await session.screenWorker.dispose().catch(() => {});
+      session.screenWorker = null;
+    }
+    cleanupShellBusyIntegration(session.shellBusyIntegration);
+
+    this.emit('session-exited', {
+      sessionId: session.id,
+      code,
+      exitedAt: session.exitedAt,
+      runtimeEpoch: session.runtimeEpoch,
+      outputSeq: session.outputSeq,
+      stateRevision: session.stateRevision,
+      stateProofAvailable: session.stateProofAvailable !== false,
+    });
+    if (finalCheckpoint) {
+      this.emit('session-preview', {
+        sessionId: session.id,
+        previewText: session.previewText,
+        cols: session.previewCols,
+        rows: session.previewRows,
+        previewSnapshot: session.previewSnapshot,
+        runtimeEpoch: session.runtimeEpoch,
+      });
+    }
+  }
+
+  handleSessionData(sessionId, rawData, expectedSession = null) {
+    const current = this.sessions.get(sessionId);
+    if (!current || (expectedSession && current !== expectedSession) || current.stateProofAvailable === false) return;
+    if (!acceptTerminalExitData(current)) {
+      current.finalCheckpoint = null;
+      this.failSessionScreenState(current, new Error('PTY emitted data after its final checkpoint cut'));
+      return;
+    }
+
+    const busyState = parseShellBusyMarkers(
+      rawData,
+      current.terminalBusy,
+      current.shellBusyMarkerPending,
+    );
+    current.shellBusyMarkerPending = busyState.pending;
+    if (busyState.markerSeen) {
+      const markerAt = Date.now();
+      current.terminalBusy = busyState.terminalBusy;
+      if (busyState.cwd) current.shellCwd = busyState.cwd;
+      if (busyState.exitCodeSeen) current.shellLastExitCode = busyState.lastExitCode;
+      if (busyState.shellEvent) current.shellLastEvent = busyState.shellEvent;
+      if (busyState.shellEvent === 'start') current.shellCommandStartedAt = markerAt;
+      if (busyState.commandTextSeen) current.shellCommand = busyState.shellCommand || '';
+      if (busyState.shellEvent === 'finish') {
+        const commandStartedAt = current.shellCommandStartedAt;
+        if (current.shellCommand) current.shellLastCommand = current.shellCommand;
+        if (typeof commandStartedAt === 'number') {
+          current.shellLastCommandStartedAt = commandStartedAt;
+          current.shellLastCommandFinishedAt = markerAt;
+          current.shellLastCommandDurationMs = Math.max(0, markerAt - commandStartedAt);
+        }
+        current.shellCommand = '';
+        current.shellCommandStartedAt = null;
       }
+      this.emit('session-busy-state', {
+        sessionId: current.id,
+        terminalBusy: current.terminalBusy,
+        cwd: current.shellCwd || current.cwd,
+        lastExitCode: current.shellLastExitCode,
+        shellEvent: current.shellLastEvent,
+        shellCommand: current.shellCommand,
+        shellLastCommand: current.shellLastCommand,
+        shellCommandStartedAt: current.shellCommandStartedAt,
+        shellLastCommandStartedAt: current.shellLastCommandStartedAt,
+        shellLastCommandFinishedAt: current.shellLastCommandFinishedAt,
+        shellLastCommandDurationMs: current.shellLastCommandDurationMs,
+        statusMarkerSeen: busyState.statusMarkerSeen,
+        busyMarkerSeen: busyState.busyMarkerSeen,
+        runtimeEpoch: current.runtimeEpoch,
+      });
+    }
 
-      this.emit('session-output', {
+    const data = busyState.data;
+    if (!data) return;
+    const reducerDelivery = enqueueTerminalReducerData(
+      ensureTerminalReducerFlowControl(current),
+      current.process,
+      data,
+    );
+    if (reducerDelivery.error) {
+      this.failSessionScreenState(current, reducerDelivery.error);
+      return;
+    }
+    current.outputSeq += 1;
+    current.stateRevision += 1;
+    const outputSeq = current.outputSeq;
+    const stateRevision = current.stateRevision;
+    current.output = `${current.output}${data}`.slice(-10000);
+    current.lastActivityAt = Date.now();
+
+    const fallbackTitle = extractLatestTerminalTitle(data);
+    if (fallbackTitle && fallbackTitle !== current.title) {
+      current.title = fallbackTitle;
+      this.emit('session-title', {
         sessionId: current.id,
+        title: current.title,
+        runtimeEpoch: current.runtimeEpoch,
+      });
+    }
+
+    const commit = current.screenWorker.append(data, stateRevision, outputSeq);
+    current.reducerCommitQueue = current.reducerCommitQueue.then(() => commit).then(() => {
+      const latest = this.sessions.get(current.id);
+      if (latest !== current || latest.stateProofAvailable === false) return;
+      const flowError = acknowledgeTerminalReducerData(
+        ensureTerminalReducerFlowControl(latest),
+        latest.process,
+        reducerDelivery.bytes,
+      );
+      if (flowError) {
+        this.failSessionScreenState(latest, flowError);
+        return;
+      }
+      this.emit('session-output', {
+        sessionId: latest.id,
         data,
-        outputSeq: current.outputSeq
+        runtimeEpoch: latest.runtimeEpoch,
+        outputSeq,
+        stateRevision,
       });
       this.emit('session-activity', {
-        sessionId: current.id,
-        lastActivityAt: current.lastActivityAt
+        sessionId: latest.id,
+        lastActivityAt: latest.lastActivityAt,
+        runtimeEpoch: latest.runtimeEpoch,
       });
+    }).catch(error => this.failSessionScreenState(current, error));
+  }
 
-      current.screenWorker.append(data);
-    });
-
-    ptyProcess.onExit(({ code }) => {
-      const current = this.sessions.get(session.id);
-      if (!current) return;
-
-      current.screenWorker.getState().catch(() => ({
-        renderOutput: current.renderOutput,
-        previewText: current.previewText,
-        previewSnapshot: current.previewSnapshot,
-        title: current.title
-      })).then((screenState) => {
-        const latest = this.sessions.get(session.id);
-        if (!latest) return;
-
-        latest.status = 'exited';
-        latest.exitedAt = Date.now();
-        latest.renderOutput = screenState.renderOutput || latest.renderOutput;
-        latest.previewText = screenState.previewText || latest.previewText || latest.output.slice(-2000);
-        latest.previewSnapshot = screenState.previewSnapshot || latest.previewSnapshot;
-        latest.previewCols = screenState.cols || latest.previewCols;
-        latest.previewRows = screenState.rows || latest.previewRows;
-        latest.title = screenState.title || latest.title;
-        if (latest.screenWorker) {
-          latest.screenWorker.dispose().catch(() => {});
-          latest.screenWorker = null;
-        }
-        cleanupShellBusyIntegration(latest.shellBusyIntegration);
-
-        this.emit('session-exited', {
-          sessionId: latest.id,
-          code,
-          exitedAt: latest.exitedAt
-        });
-        this.emit('session-preview', {
-          sessionId: latest.id,
-          previewText: latest.previewText,
-          cols: latest.previewCols,
-          rows: latest.previewRows,
-          previewSnapshot: latest.previewSnapshot,
-        });
-      });
+  failSessionScreenState(session, error) {
+    const current = this.sessions.get(session.id);
+    if (current !== session || current.stateProofAvailable === false) return;
+    current.stateProofAvailable = false;
+    const message = error instanceof Error ? error.message : String(error || 'unknown reducer failure');
+    this.emit('session-error', {
+      sessionId: current.id,
+      error: `Terminal state reducer failed: ${message}`,
+      fatal: true,
+      runtimeEpoch: current.runtimeEpoch,
     });
-
-    return {
-      sessionId: session.id,
-      status: session.status
-    };
+    try {
+      current.process?.kill();
+    } catch {
+      // The runtime cannot continue safely without its authoritative reducer.
+    }
   }
 
-  async sendInput(sessionId, input) {
+  async sendInput(sessionId, input, options = {}) {
     const session = this.sessions.get(sessionId);
-    if (!session || !session.process) {
+    if (!session || !session.process || session.status === 'exited' || session.exitFinalizing === true) {
       throw new Error('Session not available');
     }
 
+    if (options.expectedRuntimeEpoch && options.expectedRuntimeEpoch !== session.runtimeEpoch) {
+      return { status: 'input-rejected', reason: 'runtime-epoch-mismatch' };
+    }
     session.process.write(terminalInputToPtyString(input));
     session.lastActivityAt = Date.now();
     this.emit('session-activity', {
       sessionId,
-      lastActivityAt: session.lastActivityAt
+      lastActivityAt: session.lastActivityAt,
+      runtimeEpoch: session.runtimeEpoch,
     });
+    return { sent: true };
+  }
+
+  async interruptSession(sessionId, input = '\x03', options = {}) {
+    return this.sendInput(sessionId, input, options);
   }
 
-  async interruptSession(sessionId, input = '\x03') {
-    return this.sendInput(sessionId, input);
+  async getSessionAttachCheckpoint(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session) return null;
+    const checkpoint = await captureTerminalAttachCheckpoint(session);
+    return this.sessions.get(sessionId) === session ? checkpoint : null;
   }
 
   async resizeSession(sessionId, cols, rows) {
     const session = this.sessions.get(sessionId);
     if (!session || !session.process || !session.process.resize) {
-      return { resized: false };
+      return { status: 'resize-rejected', reason: 'session-unavailable', resized: false };
+    }
+    if (session.status === 'exited' || session.exitFinalizing === true) {
+      return { status: 'resize-rejected', reason: 'session-unavailable', resized: false };
     }
-    if (session.status === 'exited') {
-      return { resized: false };
+
+    if (cols === session.previewCols && rows === session.previewRows) {
+      if (this.sessions.get(sessionId) !== session) {
+        return { status: 'resize-rejected', reason: 'session-replaced', resized: false };
+      }
+      return {
+        status: 'resize-committed',
+        resized: true,
+        unchanged: true,
+      };
     }
 
     try {
@@ -423,96 +544,191 @@ class LocalSessionEngine extends SessionEngine {
       if (error && String(error.message || '').includes('EBADF')) {
         session.status = 'exited';
         session.exitedAt = session.exitedAt || Date.now();
-        return { resized: false };
+        return { status: 'resize-rejected', reason: 'session-unavailable', resized: false };
       }
-      throw error;
+      return {
+        status: 'resize-rejected',
+        reason: 'pty-resize-failed',
+        resized: false,
+        error: error instanceof Error ? error.message : String(error || 'unknown PTY resize failure'),
+      };
+    }
+    if (this.sessions.get(sessionId) !== session) {
+      return { status: 'resize-rejected', reason: 'session-replaced', resized: false };
     }
+    session.stateRevision += 1;
+    const stateRevision = session.stateRevision;
+    const outputSeq = session.outputSeq;
+    const runtimeEpoch = session.runtimeEpoch;
     session.previewCols = cols || session.previewCols;
     session.previewRows = rows || session.previewRows;
     if (!session.screenWorker) {
-      return { resized: true, cols: session.previewCols, rows: session.previewRows };
+      if (this.sessions.get(sessionId) !== session) {
+        return { status: 'resize-rejected', reason: 'session-replaced', resized: false };
+      }
+      return {
+        status: 'resize-committed',
+        resized: true,
+        unchanged: false,
+      };
     }
 
-    try {
-      const screenState = await session.screenWorker.resize(cols, rows);
+    const reducerCommit = session.screenWorker.resize(cols, rows, stateRevision);
+    const publishedCommit = session.reducerCommitQueue.then(() => reducerCommit).then((screenState) => {
+      if (this.sessions.get(sessionId) !== session) {
+        throw new Error('Terminal session was replaced during resize');
+      }
+      if (
+        screenState.runtimeEpoch !== runtimeEpoch ||
+        screenState.outputSeq !== outputSeq ||
+        screenState.stateRevision !== stateRevision
+      ) {
+        throw new Error('Terminal screen resize returned a non-authoritative state cut');
+      }
       session.previewText = screenState.previewText || '';
       session.previewSnapshot = screenState.previewSnapshot || session.previewSnapshot;
-      session.renderOutput = screenState.renderOutput || session.renderOutput;
+      session.renderOutput = typeof screenState.renderOutput === 'string'
+        ? screenState.renderOutput
+        : session.renderOutput;
       session.previewCols = screenState.cols || cols || session.previewCols;
       session.previewRows = screenState.rows || rows || session.previewRows;
       if (screenState.title && screenState.title !== session.title) {
         session.title = screenState.title;
         this.emit('session-title', {
           sessionId,
-          title: session.title
+          title: session.title,
+          runtimeEpoch: session.runtimeEpoch,
         });
       }
-    } catch (error) {
-      this.emit('session-error', {
+      this.emit('session-transition', {
         sessionId,
-        error: `Failed to resize terminal screen state: ${error.message}`,
-        fatal: false
+        kind: 'resize',
+        data: '',
+        runtimeEpoch: screenState.runtimeEpoch,
+        outputSeq: screenState.outputSeq,
+        stateRevision: screenState.stateRevision,
+        cols: screenState.cols,
+        rows: screenState.rows
       });
+      return screenState;
+    });
+    session.reducerCommitQueue = publishedCommit.catch(error => {
+      this.failSessionScreenState(session, error);
+    });
+    try {
+      await publishedCommit;
+    } catch {
+      return { status: 'resize-rejected', reason: 'screen-reducer-failed', resized: false };
     }
-    return { resized: true, cols: session.previewCols, rows: session.previewRows };
+    if (this.sessions.get(sessionId) !== session) {
+      return { status: 'resize-rejected', reason: 'session-replaced', resized: false };
+    }
+    return {
+      status: 'resize-committed',
+      resized: true,
+      unchanged: false,
+      runtimeEpoch,
+      outputSeq,
+      stateRevision,
+      cols,
+      rows,
+    };
   }
 
-  async clearBuffer(sessionId) {
+  async clearBuffer(sessionId, options = {}) {
     const session = this.sessions.get(sessionId);
-    if (!session) {
+    if (!session || session.status === 'exited' || session.exitFinalizing === true) {
       return { cleared: false };
     }
+    if (options.expectedRuntimeEpoch && options.expectedRuntimeEpoch !== session.runtimeEpoch) {
+      return { cleared: false, reason: 'runtime-epoch-mismatch' };
+    }
 
     session.output = '';
-    session.outputSeq = (session.outputSeq || 0) + 1;
+    session.stateRevision += 1;
+    const stateRevision = session.stateRevision;
+    const outputSeq = session.outputSeq;
+    const runtimeEpoch = session.runtimeEpoch;
     session.renderOutput = '';
     session.previewText = '';
     session.previewSnapshot = null;
     session.lastActivityAt = Date.now();
 
+    let exactState = {
+      renderOutput: '',
+      runtimeEpoch,
+      outputSeq,
+      stateRevision,
+      cols: session.previewCols,
+      rows: session.previewRows,
+    };
     if (session.screenWorker) {
-      try {
-        const screenState = await session.screenWorker.clear();
-        session.renderOutput = screenState.renderOutput || '';
+      const reducerCommit = session.screenWorker.clear(stateRevision, outputSeq);
+      const publishedCommit = session.reducerCommitQueue.then(() => reducerCommit).then((screenState) => {
+        if (this.sessions.get(sessionId) !== session) {
+          throw new Error('Terminal session was replaced during clear');
+        }
+        if (
+          screenState.runtimeEpoch !== runtimeEpoch ||
+          screenState.outputSeq !== outputSeq ||
+          screenState.stateRevision !== stateRevision
+        ) {
+          throw new Error('Terminal screen clear returned a non-authoritative state cut');
+        }
+        session.renderOutput = typeof screenState.renderOutput === 'string' ? screenState.renderOutput : '';
         session.previewText = screenState.previewText || '';
         session.previewSnapshot = screenState.previewSnapshot || null;
         session.previewCols = screenState.cols || session.previewCols;
         session.previewRows = screenState.rows || session.previewRows;
+        exactState = screenState;
         if (screenState.title && screenState.title !== session.title) {
           session.title = screenState.title;
-          this.emit('session-title', {
-            sessionId,
-            title: session.title
-          });
+          this.emit('session-title', { sessionId, title: session.title, runtimeEpoch: session.runtimeEpoch });
         }
-      } catch (error) {
-        this.emit('session-error', {
+        this.emit('session-transition', {
           sessionId,
-          error: `Failed to clear terminal screen state: ${error.message}`,
-          fatal: false
+          kind: 'clear',
+          data: '\x1b[2J\x1b[3J\x1b[H',
+          runtimeEpoch: screenState.runtimeEpoch,
+          outputSeq: screenState.outputSeq,
+          stateRevision: screenState.stateRevision,
+          cols: screenState.cols,
+          rows: screenState.rows
         });
+        return screenState;
+      });
+      session.reducerCommitQueue = publishedCommit.catch(error => {
+        this.failSessionScreenState(session, error);
+      });
+      try {
+        await publishedCommit;
+      } catch {
+        return { cleared: false };
       }
     }
-
-    this.emit('session-sync', {
-      sessionId,
-      output: session.renderOutput || session.output,
-      outputSeq: session.outputSeq,
-      replaceLive: true
-    });
+    if (this.sessions.get(sessionId) !== session) return { cleared: false, reason: 'session-replaced' };
     this.emit('session-preview', {
       sessionId,
       previewText: session.previewText,
       cols: session.previewCols,
       rows: session.previewRows,
       previewSnapshot: session.previewSnapshot,
-      title: session.title
+      title: session.title,
+      runtimeEpoch: session.runtimeEpoch,
     });
     this.emit('session-activity', {
       sessionId,
-      lastActivityAt: session.lastActivityAt
+      lastActivityAt: session.lastActivityAt,
+      runtimeEpoch: session.runtimeEpoch,
     });
-    return { cleared: true, outputSeq: session.outputSeq };
+    return {
+      cleared: true,
+      runtimeEpoch: exactState.runtimeEpoch,
+      outputSeq: exactState.outputSeq,
+      stateRevision: exactState.stateRevision,
+      cols: exactState.cols,
+      rows: exactState.rows,
+    };
   }
 
   async killSession(sessionId) {
@@ -527,7 +743,7 @@ class LocalSessionEngine extends SessionEngine {
 
     const killTimer = setTimeout(() => {
       const latest = this.sessions.get(sessionId);
-      if (!latest || latest.status === 'exited' || !latest.process) {
+      if (latest !== session || latest.status === 'exited' || !latest.process) {
         return;
       }
       latest.process.kill('SIGKILL');
@@ -538,23 +754,31 @@ class LocalSessionEngine extends SessionEngine {
   async getSessionState(sessionId) {
     const session = this.sessions.get(sessionId);
     if (!session) return null;
-    const screenState = session.screenWorker
-      ? await session.screenWorker.getState().catch(() => null)
-      : null;
-
-    const title = (screenState && screenState.title) || session.title;
-    const previewText = (screenState && screenState.previewText) || session.previewText;
+    const snapshotOutput = session.output;
+    const fallbackPreviewText = session.previewText;
+    const fallbackPreviewSnapshot = session.previewSnapshot;
+    const fallbackPreviewCols = session.previewCols;
+    const fallbackPreviewRows = session.previewRows;
+    const fallbackTitle = session.title;
+    const stateProofAvailable = session.stateProofAvailable !== false;
+    const checkpoint = stateProofAvailable ? await captureTerminalAttachCheckpoint(session) : null;
+    if (this.sessions.get(sessionId) !== session) return null;
+    const title = checkpoint ? checkpoint.title : fallbackTitle;
+    const previewText = checkpoint ? checkpoint.previewText : (stateProofAvailable ? fallbackPreviewText : '');
 
     return {
       sessionId: session.id,
       status: session.status,
-      output: session.output,
-      outputSeq: session.outputSeq || 0,
-      renderOutput: (screenState && screenState.renderOutput) || session.renderOutput,
+      runtimeEpoch: session.runtimeEpoch,
+      output: snapshotOutput,
+      outputSeq: checkpoint?.outputSeq ?? null,
+      stateRevision: checkpoint?.stateRevision ?? null,
+      stateProofAvailable,
+      renderOutput: checkpoint ? checkpoint.renderOutput : (stateProofAvailable ? snapshotOutput : ''),
       previewText,
-      previewSnapshot: (screenState && screenState.previewSnapshot) || session.previewSnapshot,
-      previewCols: (screenState && screenState.cols) || session.previewCols,
-      previewRows: (screenState && screenState.rows) || session.previewRows,
+      previewSnapshot: checkpoint ? checkpoint.previewSnapshot : (stateProofAvailable ? fallbackPreviewSnapshot : null),
+      previewCols: checkpoint ? checkpoint.cols : fallbackPreviewCols,
+      previewRows: checkpoint ? checkpoint.rows : fallbackPreviewRows,
       title,
       lastActivityAt: session.lastActivityAt,
       startedAt: session.startedAt,
@@ -593,6 +817,7 @@ class LocalSessionEngine extends SessionEngine {
     const screenState = session.screenWorker
       ? await session.screenWorker.getState({ includeRenderOutput: false }).catch(() => null)
       : null;
+    if (this.sessions.get(sessionId) !== session) return '';
     return (screenState && screenState.previewText) || session.previewText;
   }