farming-code 2.2.7 → 2.2.11

package/backend/native-pty-host.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+const crypto = require('crypto');
 const fs = require('fs');
 const net = require('net');
 const os = require('os');
@@ -20,6 +21,30 @@ const {
 } = require('./local-session-engine');
 const { deriveTerminalStatus } = require('./terminal-status');
 const { probeUnixSocket } = require('./terminal-runtime-cleanup');
+const { nativePtyHostRuntimeIdentity } = require('./native-pty-host-identity');
+const {
+  allocateNativePtyRuntimeGeneration,
+  formatNativePtyRuntimeEpoch,
+} = require('./native-pty-controller-generation');
+const {
+  acknowledgeTerminalReducerData,
+  createTerminalReducerFlowControl,
+  ensureTerminalReducerFlowControl,
+  enqueueTerminalReducerData,
+  resetTerminalReducerFlowControl,
+  setTerminalExternalFlowControlBlocked,
+} = require('./terminal-reducer-flow-control');
+const {
+  normalizeTerminalStateEntry,
+  serializeTerminalState,
+} = require('./terminal-state-serialization');
+const {
+  captureTerminalAttachCheckpoint,
+} = require('./terminal-attach-checkpoint');
+const {
+  acceptTerminalExitData,
+  waitForTerminalExitDataQuiescence,
+} = require('./terminal-exit-quiescence');
 
 const OUTPUT_LIMIT = 10000;
 const DEFAULT_COLS = 80;
@@ -27,6 +52,11 @@ const DEFAULT_ROWS = 30;
 const OWNER_CHECK_INTERVAL_MS = 1000;
 const DISPOSE_PTY_GRACE_MS = 800;
 const DEFAULT_IDLE_EXIT_MS = 60000;
+const DEFAULT_CLIENT_MAX_BUFFERED_BYTES = 16 * 1024 * 1024;
+const DEFAULT_CLIENT_MAX_REQUEST_BYTES = 16 * 1024 * 1024;
+const HOST_RUNTIME_IDENTITY = nativePtyHostRuntimeIdentity();
+const CONTROLLER_MUTATION_ADMISSION = Symbol('controllerMutationAdmission');
+const TERMINAL_HISTORY_RESTORED_MESSAGE = '\r\n\x1b[7m History restored \x1b[0m\r\n';
 
 function trimOutput(output) {
   const text = typeof output === 'string' ? output : '';
@@ -52,11 +82,32 @@ class NativePtyHost {
     this.configDir = options.configDir || process.env.FARMING_CONFIG_DIR || path.join(os.homedir(), '.farming');
     this.socketPath = options.socketPath || process.env.FARMING_NATIVE_PTY_HOST_SOCKET || nativePtyHostSocketPath(this.configDir);
     this.ownerPid = Number(options.ownerPid || process.env.FARMING_NATIVE_PTY_HOST_OWNER_PID || 0);
+    this.runtimeIdentity = options.runtimeIdentity || HOST_RUNTIME_IDENTITY;
+    this.exitOnShutdown = options.exitOnShutdown !== false;
     this.sessions = new Map();
     this.clients = new Set();
     this.ownerCheckTimer = null;
     this.idleExitTimer = null;
     this.hasAcceptedClient = false;
+    this.activeControllerClient = null;
+    this.activeControllerIdentity = null;
+    this.sessionMutationQueues = new Map();
+    this.activeControllerMutations = new Set();
+    this.controllerRegistrationQueue = Promise.resolve();
+    this.controllerHandoff = null;
+    this.rotationPreparation = null;
+    this.clientMaxBufferedBytes = normalizePositiveInteger(
+      options.clientMaxBufferedBytes,
+      DEFAULT_CLIENT_MAX_BUFFERED_BYTES,
+      1024,
+      256 * 1024 * 1024,
+    );
+    this.clientMaxRequestBytes = normalizePositiveInteger(
+      options.clientMaxRequestBytes,
+      DEFAULT_CLIENT_MAX_REQUEST_BYTES,
+      1024,
+      256 * 1024 * 1024,
+    );
     this.idleExitMs = normalizePositiveInteger(
       options.idleExitMs ?? process.env.FARMING_NATIVE_PTY_HOST_IDLE_EXIT_MS,
       DEFAULT_IDLE_EXIT_MS,
@@ -125,7 +176,7 @@ class NativePtyHost {
   }
 
   handleConnection(socket) {
-    const client = { socket, buffer: '' };
+    const client = { socket, buffer: '', disconnected: false };
     this.hasAcceptedClient = true;
     this.cancelIdleExit();
     this.clients.add(client);
@@ -135,8 +186,43 @@ class NativePtyHost {
   }
 
   removeClient(client) {
+    if (!client || client.disconnected === true) return Promise.resolve();
+    client.disconnected = true;
     this.clients.delete(client);
+    let retirement = Promise.resolve();
+    if (
+      this.activeControllerClient === client
+      || this.controllerHandoff?.fromClient === client
+      || this.controllerHandoff?.toClient === client
+    ) {
+      retirement = this.controllerRegistrationQueue
+        .catch(() => {})
+        .then(() => this.retireControllerClient(client));
+      this.controllerRegistrationQueue = retirement;
+    }
     this.scheduleIdleExitIfUnused();
+    return retirement;
+  }
+
+  async retireControllerClient(client) {
+    if (this.activeControllerClient !== client) return;
+    const handoff = {
+      fromClient: client,
+      fromIdentity: this.activeControllerIdentity,
+      toClient: null,
+      toIdentity: null,
+    };
+    this.controllerHandoff = handoff;
+    try {
+      // A disconnect closes admission immediately, but an operation that was
+      // already admitted owns its linearization point until it completes.
+      // Retire the server client only after that exact set has drained.
+      await Promise.allSettled([...this.activeControllerMutations]);
+      if (this.activeControllerClient !== client) return;
+      this.activeControllerClient = null;
+    } finally {
+      if (this.controllerHandoff === handoff) this.controllerHandoff = null;
+    }
   }
 
   hasLiveSessions() {
@@ -186,6 +272,10 @@ class NativePtyHost {
     client.buffer += chunk.toString('utf8');
     let newline = client.buffer.indexOf('\n');
     while (newline >= 0) {
+      if (newline > this.clientMaxRequestBytes) {
+        this.disconnectSlowClient(client, 'native pty request exceeded limit');
+        return;
+      }
       const line = client.buffer.slice(0, newline);
       client.buffer = client.buffer.slice(newline + 1);
       if (line.trim()) {
@@ -193,6 +283,9 @@ class NativePtyHost {
       }
       newline = client.buffer.indexOf('\n');
     }
+    if (client.buffer.length > this.clientMaxRequestBytes) {
+      this.disconnectSlowClient(client, 'native pty request exceeded limit');
+    }
   }
 
   async handleClientMessage(client, line) {
@@ -207,7 +300,7 @@ class NativePtyHost {
     if (!id) return;
 
     try {
-      const result = await this.dispatch(message.method, message.params || {});
+      const result = await this.dispatch(message.method, message.params || {}, client);
       this.send(client, { id, ok: true, result });
     } catch (error) {
       this.send(client, {
@@ -218,45 +311,146 @@ class NativePtyHost {
     }
   }
 
-  dispatch(method, params) {
+  dispatch(method, params, client) {
     switch (method) {
       case 'ping':
-        return { ok: true };
+        return {
+          ok: true,
+          pid: process.pid,
+          runtimeIdentity: this.runtimeIdentity,
+        };
+      case 'registerController':
+        return this.registerController(client, params.identity || {});
       case 'createSession':
-        return this.createSession(params.options || {});
+        return this.enqueueControllerMutation(
+          params.options?.agentId,
+          client,
+          () => this.createSession(params.options || {}),
+        );
       case 'sendInput':
-        return this.sendInput(params.sessionId, params.input);
+        return this.enqueueControllerMutation(
+          params.sessionId,
+          client,
+          () => this.sendInput(params.sessionId, params.input, params.expectedRuntimeEpoch || ''),
+        );
       case 'resizeSession':
-        return this.resizeSession(params.sessionId, params.cols, params.rows);
+        return this.enqueueControllerMutation(
+          params.sessionId,
+          client,
+          () => this.resizeSession(params.sessionId, params.cols, params.rows),
+        );
       case 'clearBuffer':
-        return this.clearBuffer(params.sessionId);
+        return this.enqueueControllerMutation(
+          params.sessionId,
+          client,
+          () => this.clearBuffer(params.sessionId, params.expectedRuntimeEpoch || ''),
+        );
       case 'killSession':
-        return this.killSession(params.sessionId);
+        return this.enqueueControllerMutation(
+          params.sessionId,
+          client,
+          () => this.killSession(params.sessionId),
+        );
       case 'getSessionState':
         return this.getSessionState(params.sessionId);
+      case 'getSessionAttachCheckpoint':
+        return this.getSessionAttachCheckpoint(params.sessionId, client);
       case 'getSessionPreview':
         return this.getSessionPreview(params.sessionId);
       case 'recoverSessions':
         return this.recoverSessions();
+      case 'serializeTerminalState':
+        return this.serializeTerminalState(client);
+      case 'resumeTerminalState':
+        return this.resumeTerminalState(client, params.preparationToken || '');
       case 'updateSessionMetadata':
-        return this.updateSessionMetadata(params.sessionId, params.patch || {});
+        return this.enqueueControllerMutation(
+          params.sessionId,
+          client,
+          () => this.updateSessionMetadata(params.sessionId, params.patch || {}),
+        );
       case 'shutdownHost':
-        return this.shutdownHost();
+        return this.shutdownHost(
+          client,
+          params.controller || {},
+          params.preparationToken || '',
+        );
       default:
         throw new Error(`Unknown native pty host method: ${method}`);
     }
   }
 
+  enqueueControllerMutation(sessionId, client, operation) {
+    // Admission is fenced before queueing. Once a newer controller starts its
+    // handoff, no additional work from the retiring controller may enter the
+    // mutation set; work admitted before that cut is allowed to finish.
+    try {
+      this.assertActiveController(client);
+      if (this.controllerHandoff) {
+        throw new Error('Native pty controller handoff is in progress');
+      }
+      if (this.rotationPreparation) {
+        throw new Error('Native pty host is frozen for runtime rotation');
+      }
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    const admission = Object.freeze({
+      [CONTROLLER_MUTATION_ADMISSION]: true,
+      client,
+      controllerId: client.controllerId,
+      controllerGeneration: client.controllerGeneration,
+    });
+    const key = typeof sessionId === 'string' && sessionId ? sessionId : '__host__';
+    const previous = this.sessionMutationQueues.get(key) || Promise.resolve();
+    const next = previous
+      .catch(() => {})
+      .then(() => {
+        if (this.rotationPreparation) {
+          throw new Error('Native pty host is frozen for runtime rotation');
+        }
+        return operation(admission);
+      });
+    this.activeControllerMutations.add(next);
+    this.sessionMutationQueues.set(key, next);
+    const cleanup = () => {
+      this.activeControllerMutations.delete(next);
+      if (this.sessionMutationQueues.get(key) === next) {
+        this.sessionMutationQueues.delete(key);
+      }
+    };
+    next.then(cleanup, cleanup);
+    return next;
+  }
+
   send(client, message) {
-    if (!client || !client.socket || client.socket.destroyed) return;
-    client.socket.write(`${JSON.stringify(message)}\n`);
+    this.writeClientMessage(client, `${JSON.stringify(message)}\n`);
+  }
+
+  disconnectSlowClient(client, reason) {
+    if (!client || !client.socket || client.socket.destroyed) return false;
+    client.socket.destroy(new Error(reason));
+    return true;
+  }
+
+  writeClientMessage(client, message) {
+    if (!client || !client.socket || client.socket.destroyed) return false;
+    if (client.socket.writableLength > this.clientMaxBufferedBytes) {
+      this.disconnectSlowClient(client, 'native pty client backpressure');
+      return false;
+    }
+    const accepted = client.socket.write(message);
+    if (!accepted && client.socket.writableLength > this.clientMaxBufferedBytes) {
+      this.disconnectSlowClient(client, 'native pty client backpressure');
+      return false;
+    }
+    return true;
   }
 
   broadcast(event, payload) {
     const message = `${JSON.stringify({ event, payload })}\n`;
     for (const client of this.clients) {
-      if (client.socket.destroyed) continue;
-      client.socket.write(message);
+      this.writeClientMessage(client, message);
     }
   }
 
@@ -264,7 +458,88 @@ class NativePtyHost {
     this.broadcast(event, payload);
   }
 
+  registerController(client, rawIdentity) {
+    if (!client || client.disconnected === true) {
+      throw new Error('Native pty controller client is disconnected');
+    }
+    const identity = {
+      id: typeof rawIdentity.id === 'string' ? rawIdentity.id : '',
+      generation: Math.floor(Number(rawIdentity.generation)),
+    };
+    if (!identity.id || !Number.isFinite(identity.generation) || identity.generation <= 0) {
+      throw new Error('Invalid native pty controller identity');
+    }
+
+    const registration = this.controllerRegistrationQueue
+      .catch(() => {})
+      .then(async () => {
+        const current = this.activeControllerIdentity;
+        if (
+          current &&
+          (identity.generation < current.generation ||
+            (identity.generation === current.generation && current.id !== identity.id))
+        ) {
+          throw new Error('Stale native pty controller');
+        }
+
+        const replacesController = !current
+          || current.id !== identity.id
+          || current.generation !== identity.generation
+          || this.activeControllerClient !== client;
+        if (replacesController && current) {
+          const handoff = {
+            fromClient: this.activeControllerClient,
+            fromIdentity: current,
+            toClient: client,
+            toIdentity: identity,
+          };
+          this.controllerHandoff = handoff;
+          try {
+            // New admissions from the retiring controller are now closed.
+            // Drain the exact set admitted before that cut before publishing
+            // the new generation as active.
+            await Promise.allSettled([...this.activeControllerMutations]);
+          } finally {
+            if (this.controllerHandoff === handoff) this.controllerHandoff = null;
+          }
+        }
+
+        if (client.disconnected === true) {
+          throw new Error('Native pty controller client is disconnected');
+        }
+
+        this.activeControllerIdentity = identity;
+        this.activeControllerClient = client;
+        client.controllerId = identity.id;
+        client.controllerGeneration = identity.generation;
+        return {
+          registered: true,
+          controllerId: identity.id,
+          controllerGeneration: identity.generation,
+        };
+      });
+    this.controllerRegistrationQueue = registration;
+    return registration;
+  }
+
+  assertActiveController(client) {
+    if (client?.[CONTROLLER_MUTATION_ADMISSION] === true) return;
+    if (
+      !client ||
+      client.disconnected === true ||
+      client !== this.activeControllerClient ||
+      !this.activeControllerIdentity ||
+      client.controllerId !== this.activeControllerIdentity.id ||
+      client.controllerGeneration !== this.activeControllerIdentity.generation
+    ) {
+      throw new Error('Native pty mutation requires the active controller');
+    }
+  }
+
   async createSession(options) {
+    if (this.rotationPreparation) {
+      throw new Error('Native pty host is frozen for runtime rotation');
+    }
     this.cancelIdleExit();
     const normalized = options.shellIntegrationPrepared === true
       ? {
@@ -286,9 +561,31 @@ class NativePtyHost {
       return { sessionId: agentId, status: existing.status };
     }
 
-    const cols = normalized.cols || DEFAULT_COLS;
-    const rows = normalized.rows || DEFAULT_ROWS;
-    const screenWorker = await this.screenWorkerPool.acquire({ cols, rows });
+    const reviveState = options.reviveState
+      ? normalizeTerminalStateEntry(options.reviveState)
+      : null;
+    const reviveEvent = reviveState?.replayEvent?.events?.[0] || null;
+    const cols = reviveEvent?.cols || normalized.cols || DEFAULT_COLS;
+    const rows = reviveEvent?.rows || normalized.rows || DEFAULT_ROWS;
+    const runtimeGeneration = await allocateNativePtyRuntimeGeneration(this.configDir);
+    const runtimeEpoch = formatNativePtyRuntimeEpoch(runtimeGeneration);
+    const screenWorker = await this.screenWorkerPool.acquire({ cols, rows, runtimeEpoch });
+    const replayText = reviveEvent?.data || '';
+    const restoredOutput = reviveState
+      ? `${replayText}${TERMINAL_HISTORY_RESTORED_MESSAGE}`
+      : '';
+    let restoredScreenState = null;
+    if (restoredOutput) {
+      try {
+        await screenWorker.append(restoredOutput, 1, 1);
+        restoredScreenState = await screenWorker.getState();
+      } catch (error) {
+        await screenWorker.dispose().catch(() => {});
+        throw new Error(`Failed to restore serialized terminal history: ${error.message}`, {
+          cause: error,
+        });
+      }
+    }
     const metadata = {
       ...(normalized.metadata || {}),
       protocolVersion: 1,
@@ -321,14 +618,20 @@ class NativePtyHost {
       cwd: normalized.cwd,
       metadata,
       process: ptyProcess,
-      output: '',
-      outputSeq: 0,
-      renderOutput: '',
-      previewText: '',
-      previewSnapshot: null,
-      previewCols: cols,
-      previewRows: rows,
-      title: '',
+      output: trimOutput(restoredOutput),
+      outputSeq: restoredOutput ? 1 : 0,
+      stateRevision: restoredOutput ? 1 : 0,
+      runtimeEpoch,
+      runtimeGeneration,
+      stateProofAvailable: true,
+      reducerFlowControl: createTerminalReducerFlowControl(),
+      reducerCommitQueue: Promise.resolve(),
+      renderOutput: restoredScreenState?.renderOutput || restoredOutput,
+      previewText: restoredScreenState?.previewText || restoredOutput,
+      previewSnapshot: restoredScreenState?.previewSnapshot || null,
+      previewCols: restoredScreenState?.cols || cols,
+      previewRows: restoredScreenState?.rows || rows,
+      title: restoredScreenState?.title || '',
       status: 'running',
       terminalBusy: null,
       shellCwd: '',
@@ -355,7 +658,24 @@ class NativePtyHost {
       sessionId: agentId,
       status: session.status,
       startedAt: session.startedAt,
+      runtimeEpoch: session.runtimeEpoch,
+      outputSeq: session.outputSeq,
+      stateRevision: session.stateRevision,
     });
+    if (restoredOutput) {
+      this.emitSessionEvent('session-sync', {
+        sessionId: agentId,
+        output: session.renderOutput,
+        textOutput: session.output,
+        replaceLive: true,
+        runtimeEpoch: session.runtimeEpoch,
+        outputSeq: session.outputSeq,
+        stateRevision: session.stateRevision,
+        cols: session.previewCols,
+        rows: session.previewRows,
+        revived: true,
+      });
+    }
 
     return { sessionId: agentId, status: session.status };
   }
@@ -363,7 +683,7 @@ class NativePtyHost {
   bindScreenWorker(session) {
     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;
@@ -375,6 +695,7 @@ class NativePtyHost {
         this.emitSessionEvent('session-title', {
           sessionId: current.id,
           title: current.title,
+          runtimeEpoch: current.runtimeEpoch,
         });
       }
 
@@ -384,34 +705,60 @@ class NativePtyHost {
         cols: current.previewCols,
         rows: current.previewRows,
         previewSnapshot: current.previewSnapshot,
+        runtimeEpoch: current.runtimeEpoch,
       });
     });
 
     session.screenWorker.on('error', error => {
-      this.emitSessionEvent('session-error', {
-        sessionId: session.id,
-        error: `Failed to update terminal screen state: ${error.message}`,
-        fatal: false,
-      });
+      this.failSessionScreenState(session, error);
+    });
+  }
+
+  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.emitSessionEvent('session-error', {
+      sessionId: current.id,
+      error: `Terminal state reducer failed: ${message}`,
+      fatal: true,
+      runtimeEpoch: current.runtimeEpoch,
     });
+    try {
+      current.process?.kill();
+    } catch {
+      // The session is already unusable because its authoritative reducer failed.
+    }
   }
 
   bindPty(session) {
-    session.process.onData(data => this.handleSessionData(session.id, data));
+    session.process.onData(data => this.handleSessionData(session.id, data, session));
     session.process.onExit(({ code }) => {
-      this.handleSessionExit(session.id, code).catch(error => {
+      this.handleSessionExit(session.id, code, session).catch(error => {
+        if (this.sessions.get(session.id) !== session) return;
         this.emitSessionEvent('session-error', {
           sessionId: session.id,
           error: error.message,
           fatal: false,
+          runtimeEpoch: session.runtimeEpoch,
         });
       });
     });
   }
 
-  handleSessionData(sessionId, rawData) {
+  handleSessionData(sessionId, rawData, expectedSession = null) {
     const current = this.sessions.get(sessionId);
-    if (!current) return;
+    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;
@@ -460,13 +807,26 @@ class NativePtyHost {
         shellLastCommandDurationMs: current.shellLastCommandDurationMs,
         statusMarkerSeen: busyState.statusMarkerSeen,
         busyMarkerSeen: busyState.busyMarkerSeen,
+        runtimeEpoch: current.runtimeEpoch,
       });
     }
 
     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 = trimOutput(current.output + data);
     current.lastActivityAt = Date.now();
 
@@ -476,46 +836,85 @@ class NativePtyHost {
       this.emitSessionEvent('session-title', {
         sessionId,
         title: current.title,
+        runtimeEpoch: current.runtimeEpoch,
       });
     }
 
-    this.emitSessionEvent('session-output', {
-      sessionId,
-      data,
-      outputSeq: current.outputSeq,
-    });
-    this.emitSessionEvent('session-activity', {
-      sessionId,
-      lastActivityAt: current.lastActivityAt,
-    });
-
     if (current.screenWorker) {
-      current.screenWorker.append(data);
+      const commit = current.screenWorker.append(data, stateRevision, outputSeq);
+      current.reducerCommitQueue = current.reducerCommitQueue.then(() => commit).then(() => {
+        const latest = this.sessions.get(sessionId);
+        if (latest !== current || latest.stateProofAvailable === false) return;
+        const flowError = acknowledgeTerminalReducerData(
+          ensureTerminalReducerFlowControl(latest),
+          latest.process,
+          reducerDelivery.bytes,
+        );
+        if (flowError) {
+          this.failSessionScreenState(latest, flowError);
+          return;
+        }
+        this.emitSessionEvent('session-output', {
+          sessionId,
+          data,
+          runtimeEpoch: latest.runtimeEpoch,
+          outputSeq,
+          stateRevision,
+        });
+        this.emitSessionEvent('session-activity', {
+          sessionId,
+          lastActivityAt: latest.lastActivityAt,
+          runtimeEpoch: latest.runtimeEpoch,
+        });
+      }).catch(error => this.failSessionScreenState(current, error));
     }
   }
 
-  async handleSessionExit(sessionId, code) {
+  handleSessionExit(sessionId, code, expectedSession = null) {
     const session = this.sessions.get(sessionId);
-    if (!session || session.status === 'exited') return;
+    if (
+      !session ||
+      (expectedSession && session !== expectedSession) ||
+      session.status === 'exited'
+    ) return Promise.resolve();
+    if (session.exitFinalizationPromise) return session.exitFinalizationPromise;
+    const finalization = this.finalizeSessionExit(sessionId, code, session);
+    session.exitFinalizationPromise = finalization;
+    return finalization;
+  }
 
-    let screenState = null;
-    if (session.screenWorker) {
-      screenState = await session.screenWorker.getState().catch(() => null);
-    }
-    if (screenState) {
-      session.renderOutput = screenState.renderOutput || session.renderOutput;
-      session.previewText = screenState.previewText || session.previewText || session.output.slice(-2000);
-      session.previewSnapshot = screenState.previewSnapshot || session.previewSnapshot;
-      session.previewCols = screenState.cols || session.previewCols;
-      session.previewRows = screenState.rows || session.previewRows;
-      session.title = screenState.title || session.title;
+  async finalizeSessionExit(sessionId, code, session) {
+    const quiesced = await waitForTerminalExitDataQuiescence(session, {
+      flushMs: this.terminalExitDataFlushMs,
+      isCurrent: () => this.sessions.get(sessionId) === session,
+    });
+    if (!quiesced) return;
+
+    await Promise.resolve(session.reducerCommitQueue).catch(() => {});
+    if (this.sessions.get(sessionId) !== session) return;
+    const finalCheckpoint = await captureTerminalAttachCheckpoint(session, { requireCurrentCut: true });
+    if (this.sessions.get(sessionId) !== session) return;
+    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'));
     }
 
     session.status = 'exited';
     session.exitedAt = Date.now();
+    resetTerminalReducerFlowControl(
+      ensureTerminalReducerFlowControl(session),
+      session.process,
+    );
     cleanupShellBusyIntegration(session.shellBusyIntegration);
     if (session.screenWorker) {
-      session.screenWorker.dispose().catch(() => {});
+      await session.screenWorker.dispose().catch(() => {});
       session.screenWorker = null;
     }
 
@@ -523,107 +922,226 @@ class NativePtyHost {
       sessionId,
       code: code == null ? 'unknown' : code,
       exitedAt: session.exitedAt,
+      runtimeEpoch: session.runtimeEpoch,
+      outputSeq: session.outputSeq,
+      stateRevision: session.stateRevision,
+      stateProofAvailable: session.stateProofAvailable !== false,
     });
-    this.emitSessionEvent('session-preview', {
-      sessionId,
-      previewText: session.previewText,
-      cols: session.previewCols,
-      rows: session.previewRows,
-      previewSnapshot: session.previewSnapshot,
-    });
+    if (finalCheckpoint) {
+      this.emitSessionEvent('session-preview', {
+        sessionId,
+        previewText: session.previewText,
+        cols: session.previewCols,
+        rows: session.previewRows,
+        previewSnapshot: session.previewSnapshot,
+        runtimeEpoch: session.runtimeEpoch,
+      });
+    }
     this.scheduleIdleExitIfUnused();
   }
 
-  async sendInput(sessionId, input) {
+  async sendInput(sessionId, input, expectedRuntimeEpoch = '') {
     const session = this.sessions.get(sessionId);
-    if (!session || !session.process || session.status === 'exited') {
+    if (!session || !session.process || session.status === 'exited' || session.exitFinalizing === true) {
       throw new Error('Session not available');
     }
+    if (session.rotationFrozen === true) {
+      throw new Error('Terminal session is frozen for native PTY host rotation');
+    }
+    if (expectedRuntimeEpoch && expectedRuntimeEpoch !== session.runtimeEpoch) {
+      return { status: 'input-rejected', reason: 'runtime-epoch-mismatch' };
+    }
     session.process.write(terminalInputToPtyString(input));
     session.lastActivityAt = Date.now();
     this.emitSessionEvent('session-activity', {
       sessionId,
       lastActivityAt: session.lastActivityAt,
+      runtimeEpoch: session.runtimeEpoch,
     });
     return { sent: true };
   }
 
+  async getSessionAttachCheckpoint(sessionId, client) {
+    this.assertActiveController(client);
+    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.status === 'exited') {
-      return { resized: false };
+    if (!session || !session.process || session.status === 'exited' || session.exitFinalizing === true) {
+      return { status: 'resize-rejected', reason: 'session-unavailable', resized: false };
+    }
+    if (session.rotationFrozen === true) {
+      return { status: 'resize-rejected', reason: 'runtime-rotation', resized: false };
     }
 
     const nextCols = normalizePositiveInteger(cols, session.previewCols || DEFAULT_COLS, 1, 1000);
     const nextRows = normalizePositiveInteger(rows, session.previewRows || DEFAULT_ROWS, 1, 1000);
-    session.process.resize(nextCols, nextRows);
+    if (nextCols === session.previewCols && nextRows === session.previewRows) {
+      return {
+        status: 'resize-committed',
+        resized: true,
+        unchanged: true,
+      };
+    }
+
+    try {
+      session.process.resize(nextCols, nextRows);
+    } catch (error) {
+      return {
+        status: 'resize-rejected',
+        reason: 'pty-resize-failed',
+        resized: false,
+        error: error instanceof Error ? error.message : String(error || 'unknown PTY resize failure'),
+      };
+    }
+    session.stateRevision += 1;
+    const stateRevision = session.stateRevision;
+    const outputSeq = session.outputSeq;
+    const runtimeEpoch = session.runtimeEpoch;
     session.previewCols = nextCols;
     session.previewRows = nextRows;
 
     if (session.screenWorker) {
-      try {
-        const screenState = await session.screenWorker.resize(nextCols, nextRows);
+      const reducerCommit = session.screenWorker.resize(nextCols, nextRows, 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 || nextCols;
         session.previewRows = screenState.rows || nextRows;
         session.title = screenState.title || session.title;
-      } catch (error) {
-        this.emitSessionEvent('session-error', {
+        this.emitSessionEvent('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 };
       }
     }
+    if (this.sessions.get(sessionId) !== session) {
+      return { status: 'resize-rejected', reason: 'session-replaced', resized: false };
+    }
 
-    return { resized: true, cols: session.previewCols, rows: session.previewRows };
+    return {
+      status: 'resize-committed',
+      resized: true,
+      unchanged: false,
+      runtimeEpoch,
+      outputSeq,
+      stateRevision,
+      cols: nextCols,
+      rows: nextRows,
+    };
   }
 
-  async clearBuffer(sessionId) {
+  async clearBuffer(sessionId, expectedRuntimeEpoch = '') {
     const session = this.sessions.get(sessionId);
-    if (!session) {
+    if (!session || session.status === 'exited' || session.exitFinalizing === true) {
       return { cleared: false };
     }
+    if (session.rotationFrozen === true) {
+      return { cleared: false, reason: 'runtime-rotation' };
+    }
+    if (expectedRuntimeEpoch && 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.emitSessionEvent('session-title', {
             sessionId,
             title: session.title,
+            runtimeEpoch: session.runtimeEpoch,
           });
         }
-      } catch (error) {
-        this.emitSessionEvent('session-error', {
+        this.emitSessionEvent('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.emitSessionEvent('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.emitSessionEvent('session-preview', {
       sessionId,
       previewText: session.previewText,
@@ -631,12 +1149,21 @@ class NativePtyHost {
       rows: session.previewRows,
       previewSnapshot: session.previewSnapshot,
       title: session.title,
+      runtimeEpoch: session.runtimeEpoch,
     });
     this.emitSessionEvent('session-activity', {
       sessionId,
       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) {
@@ -648,7 +1175,7 @@ class NativePtyHost {
     session.process.kill('SIGTERM');
     const timer = setTimeout(() => {
       const latest = this.sessions.get(sessionId);
-      if (!latest || latest.status === 'exited' || !latest.process) return;
+      if (latest !== session || latest.status === 'exited' || !latest.process) return;
       latest.process.kill('SIGKILL');
     }, 1500);
     if (typeof timer.unref === 'function') timer.unref();
@@ -658,23 +1185,34 @@ class NativePtyHost {
   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 || session.output.slice(-2000);
+    // Cut the raw output before the async worker request. The screen worker
+    // receives every append with its output sequence and reports the exact
+    // sequence represented by its serialized terminal state.
+    const snapshotOutput = session.output;
+    const fallbackPreviewText = session.previewText || snapshotOutput.slice(-2000);
+    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 || session.output,
+      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,
@@ -723,6 +1261,137 @@ class NativePtyHost {
     return recovered;
   }
 
+  serializeTerminalState(client = null) {
+    if (client) this.assertActiveController(client);
+    if (this.rotationPreparation) {
+      if (
+        client &&
+        this.rotationPreparation.controllerClient &&
+        this.rotationPreparation.controllerClient !== client
+      ) {
+        throw new Error('Native pty host rotation is owned by another controller');
+      }
+      return this.rotationPreparation.promise;
+    }
+
+    const preparation = {
+      token: crypto.randomUUID(),
+      controllerClient: client,
+      phase: 'preparing',
+      promise: null,
+      serializedTerminalState: '',
+    };
+    this.rotationPreparation = preparation;
+    preparation.promise = this.prepareSerializedTerminalState(preparation);
+    return preparation.promise;
+  }
+
+  async prepareSerializedTerminalState(preparation) {
+    const entries = [];
+    try {
+      await Promise.allSettled([...this.activeControllerMutations]);
+      if (this.rotationPreparation !== preparation) {
+        throw new Error('Native pty host rotation preparation was cancelled');
+      }
+
+      const liveSessions = [...this.sessions.values()]
+        .filter(session => session.status === 'running' && session.stateProofAvailable !== false);
+      for (const session of liveSessions) {
+        session.rotationFrozen = true;
+        const flowError = setTerminalExternalFlowControlBlocked(
+          session.reducerFlowControl,
+          session.process,
+          true,
+        );
+        if (flowError) throw flowError;
+      }
+
+      for (const session of liveSessions) {
+        await session.reducerCommitQueue;
+        const state = await this.getSessionState(session.id);
+        const current = this.sessions.get(session.id);
+        if (
+          current !== session ||
+          session.status !== 'running' ||
+          state?.status !== 'running'
+        ) {
+          continue;
+        }
+        if (
+          !state ||
+          typeof state.renderOutput !== 'string' ||
+          !Number.isFinite(state.outputSeq) ||
+          !Number.isFinite(state.stateRevision)
+        ) {
+          throw new Error(`Cannot serialize terminal ${session.id} without an exact reducer checkpoint`);
+        }
+        entries.push({
+          id: session.id,
+          metadata: session.metadata || {},
+          processDetails: {
+            cwd: session.shellCwd || session.cwd || '',
+            title: state.title || session.title || '',
+          },
+          processLaunchConfig: {
+            command: session.command || '',
+            args: session.args || [],
+            category: session.metadata?.category || '',
+          },
+          replayEvent: {
+            events: [{
+              data: state.renderOutput,
+              cols: state.previewCols || session.previewCols || DEFAULT_COLS,
+              rows: state.previewRows || session.previewRows || DEFAULT_ROWS,
+            }],
+          },
+          timestamp: Date.now(),
+        });
+      }
+      const serializedTerminalState = serializeTerminalState(entries);
+      preparation.phase = 'prepared';
+      preparation.serializedTerminalState = serializedTerminalState;
+      return {
+        preparationToken: preparation.token,
+        serializedTerminalState,
+      };
+    } catch (error) {
+      this.resumePreparedTerminalState(preparation.token);
+      throw error;
+    }
+  }
+
+  resumeTerminalState(client = null, preparationToken = '') {
+    if (client) this.assertActiveController(client);
+    return this.resumePreparedTerminalState(preparationToken);
+  }
+
+  resumePreparedTerminalState(preparationToken = '') {
+    const preparation = this.rotationPreparation;
+    if (!preparation) return { resumed: 0 };
+    if (preparationToken && preparation.token !== preparationToken) {
+      throw new Error('Native pty rotation preparation token does not match');
+    }
+    let resumed = 0;
+    for (const session of this.sessions.values()) {
+      if (session.rotationFrozen !== true) continue;
+      session.rotationFrozen = false;
+      const flowError = setTerminalExternalFlowControlBlocked(
+        session.reducerFlowControl,
+        session.process,
+        false,
+      );
+      if (flowError) {
+        this.failSessionScreenState(session, flowError);
+        continue;
+      }
+      resumed += 1;
+    }
+    if (this.rotationPreparation === preparation) {
+      this.rotationPreparation = null;
+    }
+    return { resumed };
+  }
+
   async updateSessionMetadata(sessionId, patch) {
     const session = this.sessions.get(sessionId);
     if (!session) return null;
@@ -735,9 +1404,39 @@ class NativePtyHost {
     return session.metadata;
   }
 
-  shutdownHost() {
+  shutdownHost(client, rawIdentity = {}, preparationToken = '') {
+    const requestedGeneration = Math.floor(Number(rawIdentity.generation));
+    const requestedId = typeof rawIdentity.id === 'string' ? rawIdentity.id : '';
+    const active = this.activeControllerIdentity;
+    const activeClient = client
+      && client === this.activeControllerClient
+      && active
+      && client.controllerId === active.id
+      && client.controllerGeneration === active.generation;
+    const newerController = requestedId
+      && Number.isFinite(requestedGeneration)
+      && requestedGeneration > 0
+      && (!active || requestedGeneration > active.generation);
+    if (!activeClient && !newerController) {
+      throw new Error('Native pty shutdown requires the active or a newer controller');
+    }
+    const preparation = this.rotationPreparation;
+    if (preparation) {
+      if (
+        preparation.phase !== 'prepared' ||
+        !preparationToken ||
+        preparationToken !== preparation.token
+      ) {
+        throw new Error('Native pty shutdown requires the prepared rotation token');
+      }
+      preparation.phase = 'committing';
+    } else if (this.hasLiveSessions()) {
+      throw new Error('Native pty shutdown requires a prepared terminal checkpoint');
+    }
     setImmediate(() => {
-      this.dispose().finally(() => process.exit(0));
+      this.dispose().finally(() => {
+        if (this.exitOnShutdown) process.exit(0);
+      });
     });
     return { shuttingDown: true };
   }