create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/terminal-attach-geometry.js

@@ -0,0 +1,985 @@
+'use strict';
+
+// Landing-throughput WP-5 shard S6 (design doc §5 D-10 "move-only", §6 "Shard
+// module seam", §8 WP-6, §9 S-21..S-27): the WebSocket attach / geometry-handler
+// cluster (handleAttach, handleTerminalBootstrap, handleResize, handleReflow) moves
+// out of server.js VERBATIM into this module behind the same configure(deps) seam as
+// lib/api/session-messages.js (S3) and lib/api/diagnostics.js (S4). This module
+// registers NO ws handlers -- dispatch stays in lib/ws/terminal-attach.js, whose
+// configure() call in server.js now receives attachGeometry.handleAttach /
+// attachGeometry.handleTerminalBootstrap / attachGeometry.handleResize /
+// attachGeometry.handleReflow. Each moved body is identical to server.js's
+// declaration except for the `_deps.` prefix on every identifier that used to resolve
+// to a server.js top-level binding (D-10 rule 1), proven by
+// `node bin/move-only-check.js`.
+//
+// Injected deps, per function:
+//   handleAttach: CTM_FLOW_CONTROL_ENABLED, CTM_INTERACTIVE_SERIALIZE_TIMEOUT_MS,
+//     MIRROR_BACKGROUND_ROWS, _applyActivationArchiveTopup, _cacheSerializedSnapshot,
+//     _coalesceSnapshotSynchronizedFrames, _codexRolloutHistoryActive, _composeCodexRolloutResp,
+//     _ensureScrollbackTailCache, _flowPruneStalePausers, _hydrateRuntimeGoalProjectionForSocket,
+//     _lifecycleClientKind, _markCtmUiRefreshActivitySuppression, _maybeAutoStartDeferredRestore,
+//     _noteInteractiveSerializeDone, _noteInteractiveSerializeStart,
+//     _prefetchActivationArchiveTopup, _recordClientAttachDiagnostic, _replayRestoreWakeVerdict,
+//     _reportWorkerIpc, _resolveRestoredHeadlessRequestGrid, _restoreFailureWirePayload,
+//     _restoreMirrorToPtyGridAfterSerialize, _resumeLifecycleWireState,
+//     _sendRuntimeWorkStateToSocket, _serveCachedSnapshotOnSerializeTimeout, _snapshotOutputMarker,
+//     _startDeferredRestoreSession, _subscribeStateSyncClient, _wakeBlockedNoticeOwnsUi,
+//     _wsClientAsset, _wsSend, cachedSnapshotMatchesAuthority, headlessWorker,
+//     normalizeSnapshotScrollbackRows, recordSessionDiagnostic, sendCachedSnapshot,
+//     sendDeferredRestoreStatus, sessionEvents, sessions
+//   handleTerminalBootstrap: TERMINAL_BOOTSTRAP_ABSOLUTE_LIFETIME_MS,
+//     _armTerminalBootstrapGateDeadline, _clearTerminalBootstrapGate,
+//     _detachTerminalBootstrapSocket, _impliedView, _maybeAutoStartDeferredRestore,
+//     _postWorkerClientDetached, _recordClientAttachDiagnostic, _replayRestoreWakeVerdict,
+//     _restoreWindowPending, _retainRestoreAwaitingSocket, _sendTerminalBootstrapFailed,
+//     _sessionHasViewer, _subscribeStateSyncClient, _terminalBootstrapGatesFor,
+//     _terminalProcessGeneration, _wsSend, composeTerminalBootstrapResult, headlessWorker,
+//     isSubscribed, isWalleLikeSession, normalizeSnapshotScrollbackRows,
+//     parseTerminalBootstrapRequest, sendDeferredRestoreStatus, sessions, truncateBootstrapAnsi
+//   handleResize: CTM_FRESH_PROCESS_ADOPT_ENABLED, CTM_FRESH_PROCESS_ADOPT_MS, CTM_GRID_PROVENANCE,
+//     GeometryClaimValidationError, _applyPrimaryPtyResize, _broadcastViewerRoles,
+//     _claimGeometryFocus, _clearRowsFlapDebounce, _deferPrimaryPtyResizeIfStreaming,
+//     _geometryLease, _markCtmUiRefreshActivitySuppression, _maybeDebounceRowsFlapResize,
+//     _providerIdFromCmd, _pushSecondarySnapshots, _recordGridProvenanceDiagnostic,
+//     _recordViewerDims, _resolveRestoredHeadlessRequestGrid, _sendTerminalGeometryFenceAck,
+//     _viewerArbitration, classifyInboundGrid, looksLikeXtermDefault, mayDrivePtyResize,
+//     recordSessionDiagnostic, sanitizeGeometryResize, sessions, validateGeometryFence
+//   handleReflow: CTM_INTERACTIVE_SERIALIZE_TIMEOUT_MS, RENDER_CHURN_FLASH_THRESHOLD,
+//     RENDER_CHURN_WINDOW_MS, _cacheSerializedSnapshot, _coalesceSnapshotSynchronizedFrames,
+//     _codexRolloutHistoryActive, _composeCodexRolloutResp, _deferPrimaryPtyResizeIfStreaming,
+//     _markCtmUiRefreshActivitySuppression, _maybeAutoStartDeferredRestore,
+//     _noteInteractiveSerializeDone, _noteInteractiveSerializeStart, _recordRenderChurn,
+//     _resolveRestoredHeadlessRequestGrid, _serveCachedSnapshotOnSerializeTimeout,
+//     _snapshotOutputMarker, _wsClientAsset, _wsSend, buildPtyResizeAppliedDetail, headlessWorker,
+//     normalizeSnapshotScrollbackRows, recordSessionDiagnostic, sendDeferredRestoreStatus,
+//     sendTerminalSessionUnavailableSnapshot, sessions
+//
+// None of these bindings is reassigned in server.js, so all are passed by value (no
+// getters needed) and no moved body assigns server.js state.
+
+let _deps = null;
+
+function configure(deps = {}) {
+  _deps = deps;
+}
+
+async function handleAttach(ws, msg) {
+  let session = _deps.sessions.get(msg.id);
+  if (!session) {
+    _deps._wsSend(ws, JSON.stringify({ type: 'error', message: 'Session not found', id: msg.id }));
+    return;
+  }
+  const _attachScrollbackRows = _deps.normalizeSnapshotScrollbackRows(msg.scrollback);
+  session._snapshotScrollbackRows = _attachScrollbackRows;
+  _deps._markCtmUiRefreshActivitySuppression(session, 'attach');
+  if (!session.clients.includes(ws)) {
+    session.clients.push(ws);
+  }
+  _deps._recordClientAttachDiagnostic(session, msg.id, ws);
+  // A client attaching after the app already entered its TUI modes must learn them now (the enable
+  // sequences were stripped from the stream and only broadcast on change), so wheel→PTY forwarding works.
+  if (session._tuiModes && (session._tuiModes.altScreen || session._tuiModes.appMouse)) {
+    try {
+      _deps._wsSend(ws, JSON.stringify({
+        type: 'tui-mode', id: msg.id,
+        altScreen: session._tuiModes.altScreen, appMouse: session._tuiModes.appMouse, mouseEnc: session._tuiModes.mouseEnc,
+      }));
+    } catch {}
+  }
+  if (_deps.CTM_FLOW_CONTROL_ENABLED && session._flowPaused) _deps._flowPruneStalePausers(session, msg.id);
+  // Auto-attach on attach: a client explicitly asking to
+  // attach is asking to receive this session output immediately, without a separate
+  // subscribe round-trip — see tests/create-subscribe-race.test.js.
+  _deps._subscribeStateSyncClient(ws, msg.id, 'attach');
+  // Resume transitions can race ahead of a newly-created browser session and are intentionally
+  // multicast only to attached viewers. Re-publish the current generation after subscription so
+  // attach is a state barrier: a prompt/ready transition that happened between `created` and this
+  // request cannot remain invisible until the next session-list refresh.
+  const attachedResume = _deps._resumeLifecycleWireState(session);
+  if (attachedResume && ws.readyState === 1) {
+    _deps._wsSend(ws, JSON.stringify({ type: 'resume-state', id: msg.id, resume: attachedResume, transition: session._resumeLastTransition || null }));
+  }
+  _deps._replayRestoreWakeVerdict(session, msg.id, ws); // D-B2: a late-attaching tab still gets the revived verdict
+
+  if (session._restoreDeferred && (session._restoreTask?.type === 'walle' || session._restoreTask?.type === 'dsh')) { // WP-5 (S-40): attaching a restored DeepSeek Harness tab starts it through the same wake path.
+    // _startDeferredRestoreSession is async (Fix B Stage 4). It still rejects a
+    // failed spawn synchronously (returns false before any yield), so awaiting
+    // the promise resolves to that same boolean — we just notify the client
+    // when it settles instead of synchronously.
+    _deps._startDeferredRestoreSession(session, {
+      cols: msg.cols || session._ptyCols || 120,
+      rows: msg.rows || session._ptyRows || 30,
+      terminalDimsMeasured: msg.terminalDimsMeasured === true,
+      scrollbackRows: _attachScrollbackRows,
+      clientRestoreSeq: msg.clientRestoreSeq,
+      source: 'attach',
+      clientKind: _deps._lifecycleClientKind(ws, msg),
+    }).then((started) => {
+      if (started || ws.readyState !== 1) return;
+      // FINAL REVIEW S-2 (Important): `started === false` here is NOT one fact. Several bails
+      // inside _startDeferredRestoreSession(Attempt) return false with no failure emitted and
+      // NO server retry queued behind them (wake-capacity refusal, rollout-compaction bail,
+      // restore-backoff skip). Two rulings, both about not lying to the client:
+      //   (a) the wake-capacity refusal already owns the UI via its own `session-wake-blocked`
+      //       notice -- emit nothing at all, or the user gets two contradictory surfaces;
+      //   (b) every other bail has no retry behind it, so the payload must say retryable:false.
+      //       (The old code let the wire contract compute retryable from the backoff ledger,
+      //       which reports "sure, retry later" for a loop nobody is going to run.)
+      if (_deps._wakeBlockedNoticeOwnsUi(session)) return;
+      _deps._wsSend(ws, JSON.stringify(_deps._restoreFailureWirePayload(msg.id, {
+        code: 'walle_restore_not_started',
+        message: 'Wall-E session failed to resume.',
+        retryable: false,
+      })));
+    }).catch((e) => console.error('[ctm] attach-triggered walle restore error:', e.message));
+    _deps.sessionEvents.emit('session:attached', { id: msg.id, clientCount: session.clients.length, deferred: true, walle: true });
+    return;
+  }
+
+  if (session._restoreDeferred) {
+    const starting = _deps._maybeAutoStartDeferredRestore(session, msg, 'attach', ws);
+    _deps.sendDeferredRestoreStatus(ws, session, msg.id, msg.cols, msg.rows, 'attach', {
+      scrollbackRows: _attachScrollbackRows,
+      clientRestoreSeq: msg.clientRestoreSeq,
+      restoreSource: 'attach-deferred-cache',
+      starting,
+    });
+    _deps.sessionEvents.emit('session:attached', { id: msg.id, clientCount: session.clients.length, deferred: true });
+    return;
+  }
+
+  // Wall-E sessions: replay chat history instead of PTY scrollback
+  if (session.type === 'walle') {
+    _deps._sendRuntimeWorkStateToSocket(ws, msg.id, 'attach');
+    _deps._hydrateRuntimeGoalProjectionForSocket(ws, msg.id, 'attach-goal-hydrated');
+    return;
+  }
+
+  // Fast path: send cached snapshot immediately if available (pre-cached on
+  // unsubscribe). Do NOT consume the cache — a concurrent-or-subsequent
+  // retry would otherwise hit the same slow worker and leave the tab blank.
+  // The fresh serialize below refreshes the cache when it eventually arrives.
+  _deps._ensureScrollbackTailCache(session);
+  const _attachGrid = _deps._resolveRestoredHeadlessRequestGrid(session, msg, 'attach');
+  const _cacheServed = _deps.sendCachedSnapshot(ws, session, msg.id, _attachGrid.cols, _attachGrid.rows, 'attach', {
+    allowMismatched: !!msg.allowMismatchedCache,
+    allowDirty: !!session._cachedSnapshotInterim,
+    scrollbackRows: _attachScrollbackRows,
+    clientRestoreSeq: msg.clientRestoreSeq,
+  });
+  const _cacheMatchesAttachDims = _cacheServed
+    && _deps.cachedSnapshotMatchesAuthority(session, _attachGrid.cols, _attachGrid.rows);
+
+  // Open a 2s output-budget grace window: tab-switch usually triggers a PTY
+  // resize → SIGWINCH → TUI redraw burst (Claude Code / Codex easily emit
+  // 60-100KB on a single redraw). Without grace, the burst trips the 64KB
+  // budget cap and triggers a budget-recovery snapshot ~2s later, which the
+  // user sees as a delayed re-render. Letting raw bytes through during the
+  // first 2s after attach means the redraw paints incrementally rather than
+  // being suppressed-then-snapshotted.
+  if (_cacheServed) session._budgetGraceUntil = Date.now() + 2000;
+
+  // Skip the fresh-serialize round-trip only when the cache is pristine and
+  // dimension-compatible with this attach request. A mismatched cache is sent
+  // as an interim restore; the client then expects a full snapshot at the
+  // requested dimensions to complete loading without tab-switch retries.
+  // The dim-matched fast path avoids the "Codex tab renders, then re-renders
+  // a few seconds later" complaint from redundant cache+fresh frames.
+  if (_cacheServed && _cacheMatchesAttachDims && session._cachedSnapshotDirty === false && session._cachedSnapshotInterim === false) {
+    _deps.sessionEvents.emit('session:attached', { id: msg.id, clientCount: session.clients.length });
+    return;
+  }
+
+  // Phase 3D: send snapshot from headless terminal instead of in-memory scrollback.
+  // The headless terminal has the authoritative state (text, colors, cursor).
+  // If the client sends cols/rows, resize headless terminal to match before serializing.
+  // Otherwise, sync headless terminal to the PTY's actual dimensions.
+  if (typeof session._flushHeadlessFeed === 'function') session._flushHeadlessFeed();
+  if (_attachGrid.cols && _attachGrid.rows) {
+    _deps.headlessWorker.postMessage({ type: 'resize', sessionId: msg.id, cols: _attachGrid.cols, rows: _attachGrid.rows });
+  } else if (session.ptyProcess) {
+    // Use PTY's actual cols/rows as fallback
+    try {
+      const ptyCols = session.ptyProcess.cols || 120;
+      const ptyRows = session.ptyProcess.rows || 30;
+      _deps.headlessWorker.postMessage({ type: 'resize', sessionId: msg.id, cols: ptyCols, rows: ptyRows });
+    } catch {}
+  }
+  const _attachWs = ws;
+  const _attachId = msg.id;
+  const _attachUseRolloutHistory = _deps._codexRolloutHistoryActive(session, _attachId);
+  // WP-3 fix round 1: Phase A -- bulk prefetch BEFORE the marker/serialize, OUTSIDE the stale-window.
+  const _topupPrefetch = (!_attachUseRolloutHistory && _attachScrollbackRows > _deps.MIRROR_BACKGROUND_ROWS)
+    ? await _deps._prefetchActivationArchiveTopup(_attachId, _attachScrollbackRows) : null;
+  const _snapReqId = `attach-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+  const _attachOutputMarker = _deps._snapshotOutputMarker(session);
+  const _attachTimer = setTimeout(() => {
+    _deps.headlessWorker.off('message', _onSnap);
+    _deps._noteInteractiveSerializeDone(_snapReqId);
+    console.warn(`[attach] Headless worker timed out for session ${_attachId.slice(0, 8)}`);
+    _deps.recordSessionDiagnostic(_attachId, 'attach-snapshot-timeout', { requestId: _snapReqId, cols: _attachGrid.cols || 0, rows: _attachGrid.rows || 0 });
+    // Prefer the last good cached frame over a blank/data:null + client retry that would
+    // re-contend the busy worker (same fallback as the reflow path).
+    const _attachSess = _deps.sessions.get(_attachId);
+    if (_deps._serveCachedSnapshotOnSerializeTimeout(_attachWs, _attachSess, _attachId, _attachGrid.cols, _attachGrid.rows, 'attach', msg.clientRestoreSeq)) return;
+    // Notify client so it can trigger recovery instead of staying blank
+    if (_attachWs.readyState === 1) _deps._wsSend(_attachWs, JSON.stringify({ type: 'snapshot', id: _attachId, data: null, timedOut: true, clientRestoreSeq: msg.clientRestoreSeq, restoreSource: 'attach' }));
+  }, _deps.CTM_INTERACTIVE_SERIALIZE_TIMEOUT_MS);
+  const _onSnap = (resp) => { _onSnapAsync(resp).catch((error) => _deps._reportWorkerIpc('attach-snapshot', error, _attachId)); }; // WP-3: async body (Phase B); a rejection must never reach unhandledRejection (_fatalShutdown)
+  const _onSnapAsync = async (resp) => {
+    if (resp.type !== 'serialized' || resp.requestId !== _snapReqId) return;
+    clearTimeout(_attachTimer);
+    _deps._noteInteractiveSerializeDone(_snapReqId);
+    _deps.headlessWorker.off('message', _onSnap);
+    // Update cache for next time
+    const s = _deps.sessions.get(_attachId);
+    if (_attachUseRolloutHistory && s && resp.data) {
+      resp = _deps._composeCodexRolloutResp(s, _attachId, resp);
+    } else if (s && resp.data) {
+      // WP-3 fix round 1: Phase B (bulk read already ran as `_topupPrefetch` above).
+      resp = await _deps._applyActivationArchiveTopup(_attachId, _attachScrollbackRows, resp, _topupPrefetch);
+    }
+    let staleSnapshot = false;
+    let staleMarker; let staleCurrent;
+    if (s) {
+      const stored = _deps._cacheSerializedSnapshot(s, resp, _attachOutputMarker);
+      staleSnapshot = !!stored.stale;
+      if (staleSnapshot) {
+        staleMarker = stored.marker; staleCurrent = stored.current;
+        _deps.recordSessionDiagnostic(_attachId, 'attach-stale-output-after-request', {
+          requestId: _snapReqId,
+          marker: stored.marker,
+          current: stored.current,
+        });
+      }
+    }
+    // WP-4f round 3: a stale marker used to skip the only snapshot send, stranding a
+    // cold attach forever — still send it, flagged stale/allowStaleSnapshotData (client honors this).
+    if (_attachWs.readyState === 1) {
+      const snapshotData = _deps._coalesceSnapshotSynchronizedFrames(resp.data);
+      _deps._wsSend(_attachWs, JSON.stringify({
+        type: 'snapshot', id: _attachId, data: snapshotData,
+        ptyCols: resp.cols, ptyRows: resp.rows,
+        scrollback: resp.scrollback,
+        clientRestoreSeq: msg.clientRestoreSeq,
+        restoreSource: 'attach',
+        codexRolloutComposed: resp.codexRolloutComposed || undefined,
+        frameOwnedViewport: resp.frameOwnedViewport || undefined,
+        terminalDisplayMode: resp.terminalDisplayMode || undefined,
+        renderProjection: resp.renderProjection || undefined, archiveRow0: Number.isFinite(resp.archiveRow0) ? resp.archiveRow0 : null, // D-4: client identity-seam anchor
+        stale: staleSnapshot || undefined, allowStaleSnapshotData: staleSnapshot || undefined,
+      }));
+    }
+    const _snapshotSendDiagFields = {
+      requestId: _snapReqId,
+      clientAsset: _deps._wsClientAsset(_attachWs),
+      cols: resp.cols || 0,
+      rows: resp.rows || 0,
+      bytes: String(resp.data || '').length,
+    };
+    if (staleSnapshot) {
+      _deps.recordSessionDiagnostic(_attachId, 'attach-stale-snapshot-send', { ..._snapshotSendDiagFields, marker: staleMarker, current: staleCurrent });
+    } else {
+      _deps.recordSessionDiagnostic(_attachId, 'attach-fresh-snapshot-send', { ..._snapshotSendDiagFields, stale: false });
+    }
+  };
+  _deps.headlessWorker.on('message', _onSnap);
+  _deps._noteInteractiveSerializeStart(_snapReqId); // Part 1: prewarm defers while this is in flight
+  _deps.headlessWorker.postMessage({ type: 'serialize', sessionId: _attachId, requestId: _snapReqId, scrollback: _attachUseRolloutHistory ? 0 : _attachScrollbackRows });
+  _deps._restoreMirrorToPtyGridAfterSerialize(session, _attachId, _attachGrid, 'attach');
+  _deps.sessionEvents.emit('session:attached', { id: msg.id, clientCount: session.clients.length });
+}
+
+function handleTerminalBootstrap(ws, msg) {
+  let request;
+  try { request = _deps.parseTerminalBootstrapRequest(msg); } catch { return; }
+  const session = _deps.sessions.get(request.id);
+  if (!session) {
+    // WP-1 (§5 D-1): an id the restore loop has not reached YET is a non-terminal
+    // "restore-starting" (like a 503), not the terminal "session-not-found" a deleted/
+    // unknown id gets -- the live incident this fixes is exactly this misclassification: a
+    // reconnect ~4s ahead of the loop's insertion for this id was told the session is gone
+    // and never retried when it came back 3s later. Retain the socket so D-2's announce can
+    // reach it the moment the loop inserts this session; an id outside the startup set falls
+    // through unchanged (AC-1d).
+    if (_deps._restoreWindowPending(request.id)) {
+      _deps._retainRestoreAwaitingSocket(request.id, ws);
+      return _deps._sendTerminalBootstrapFailed(ws, request.id, 'restore-starting', true);
+    }
+    return _deps._sendTerminalBootstrapFailed(ws, request.id, 'session-not-found');
+  }
+  if (session.type === 'walle') return _deps._sendTerminalBootstrapFailed(ws, request.id, 'session-not-live', false);
+  // F5 (WP-2 review round 1): Wall-E-like sessions (chatSessionId set, agentType 'walle', etc.
+  // -- see isWalleLikeSession) are not terminal frames; D-4's revive is scoped to Codex/Claude
+  // PTY sessions only. shouldAutoStartDeferredRestore keeps requiring 'attach' for these.
+  if (_deps.isWalleLikeSession(session)) return _deps._sendTerminalBootstrapFailed(ws, request.id, 'session-not-live', false);
+  if (session._exited) return _deps._sendTerminalBootstrapFailed(ws, request.id, 'session-exited');
+  if (!session.ptyProcess) {
+    // D-4 (session-runtime-reset-regression-triage-2026-09-06.html §5): a deferred
+    // (parked-PTY) session used to answer 'session-not-live' here and never start the
+    // restore, stranding the client after its one retry. Kick the deferred restore the
+    // same way `attach`/`snapshot`/`reflow` already do and tell the client to wait for
+    // liveness instead of giving up -- but ONLY for a focused/visible request. F2 (WP-2
+    // review round 1): handleSessionInventory fans this out to up to 128 ids on every
+    // reconnect; without this gate every deferred BACKGROUND session would force-start a
+    // restore. A background id stays parked; selecting it later re-requests bootstrap
+    // through WP-1's afterPaint path, which IS focused.
+    // `request.focused` is the client's in-band statement that this is its active tab or a
+    // split-visible pane (public/index.html _terminalBootstrapRequestIsFocused). Needed because a
+    // cold selection's request arrives BEFORE the visibility/subscription traffic that feeds
+    // _sessionHasViewer -- live on primary the gate answered session-not-live at +2 ms.
+    const focused = request.focused === true
+      || !!(ws?.viewing?.has(request.id)) || _deps._sessionHasViewer(request.id);
+    if (focused && (session._restoreDeferred || session._restoreStarting)) {
+      // F1 (WP-2 review round 1): retain this socket as a lifecycle listener BEFORE replying
+      // restore-starting, or the session-wake-ready signal this reply promises
+      // (broadcastToSession only iterates session.clients) never reaches it. This is NOT a
+      // state-sync/input route; the later live bootstrap installs that through
+      // _subscribeStateSyncClient before returning terminal-bootstrap-result.
+      if (!session.clients.includes(ws)) {
+        session.clients.push(ws);
+        _deps._recordClientAttachDiagnostic(session, request.id, ws);
+      }
+      // D-8 (WP-3): the placeholder already holds the persisted last screen in
+      // _cachedSnapshot; serve it now instead of leaving the cold click on a blank
+      // pixel-less reply while the restore loop spins up. Called UNCONDITIONALLY (fix-round-2:
+      // a boot-restore deferred placeholder has no _cachedSnapshot yet -- sendDeferredRestoreStatus
+      // itself calls _ensureScrollbackTailCache first, which is what BUILDS the interim tail;
+      // gating this call on session._cachedSnapshot already being set, like the legacy attach
+      // path never did, would skip that build entirely). `terminal-bootstrap` carries no
+      // cols/rows/scrollback/clientRestoreSeq of its own (parseTerminalBootstrapRequest
+      // allowlists only type/id/lastAppliedSeq/knownProcessGeneration/focused) -- serve the
+      // placeholder's OWN geometry rather than reading undefined request fields, or
+      // cachedSnapshotMatchesScrollback's gate (server.js sendCachedSnapshot, not covered
+      // by allowMismatched) would silently refuse whenever the placeholder's stored
+      // scrollback differs from the library default.
+      // Final-review finding #3: compute `starting` FIRST (same order handleAttach already
+      // uses, ~line 41433) — the deferred-serve frame below must report the REAL outcome of
+      // the auto-start attempt, not a hardcoded `true` followed moments later by a
+      // 'restore-blocked' failed frame that contradicts it (that ordering told a blocked
+      // client "Starting terminal process..." right before "restore-blocked"). Calling
+      // _maybeAutoStartDeferredRestore here (once) also means the later check below never
+      // needs to call it again.
+      let starting = true;
+      if (session._restoreDeferred && !session._restoreStarting) {
+        starting = _deps._maybeAutoStartDeferredRestore(session,
+          { type: 'terminal-bootstrap', autoStartRestore: true, focused: true }, 'terminal-bootstrap', ws);
+      }
+      // Final-review finding #5: a Wall-E session never legitimately reaches this deferred
+      // branch (handled by the earlier session.type/isWalleLikeSession guards above), but the
+      // deferred-serve call itself carried no matching guard, unlike the removed
+      // attach-resuming block and handleAttach's cache serve — add it defensively so the two
+      // sites stay consistent; the failed reply below is unchanged for walle.
+      if (session.type !== 'walle') {
+        _deps.sendDeferredRestoreStatus(ws, session, request.id, session._cachedSnapshotCols, session._cachedSnapshotRows, 'terminal-bootstrap', {
+          scrollbackRows: session._cachedSnapshotScrollbackRows != null
+            ? session._cachedSnapshotScrollbackRows
+            : _deps.normalizeSnapshotScrollbackRows(undefined),
+          restoreSource: 'terminal-bootstrap-deferred-cache',
+          starting: starting === true,
+        });
+      }
+      if (session._restoreDeferred && !session._restoreStarting) {
+        return _deps._sendTerminalBootstrapFailed(ws, request.id, starting ? 'restore-starting' : 'restore-blocked', starting === true);
+      }
+      return _deps._sendTerminalBootstrapFailed(ws, request.id, 'restore-starting', true);
+    }
+    return _deps._sendTerminalBootstrapFailed(ws, request.id, 'session-not-live', false);
+  }
+  const gates = _deps._terminalBootstrapGatesFor(ws);
+  const existingGate = gates.get(request.id);
+  if (existingGate?.phase === 'serializing') return;
+  if (existingGate?.phase === 'await-ack' && existingGate.result) {
+    _deps._wsSend(ws, existingGate.result, { class: 'interactive', channel: 'terminal-bootstrap', sessionId: request.id });
+    return;
+  }
+  if (existingGate) return;
+  const wasAttached = session.clients.includes(ws) && _deps.isSubscribed(ws, request.id);
+  if (wasAttached) {
+    // A bootstrap from a socket that already holds a live route on this session (session-inventory
+    // re-send, manual retry, deferred revive) is a ROUTE RESET, not a departure. Only the worker-side
+    // route is reset; attachment authority (viewer-connected), geometry lease / primary role /
+    // measured dims and session.clients membership stay intact. Live 2026-09-07 19:53 (4dd72d9f):
+    // the departure path here dispatched viewer-disconnected, clearOwnerForClient wiped the tab's
+    // lease + primary + dims with no diagnostic, and the next role broadcast locked its input.
+    _deps._postWorkerClientDetached(request.id, ws);
+  } else {
+    _deps._detachTerminalBootstrapSocket(session, request.id, ws);
+  }
+  const requestId = `terminal-bootstrap-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const gate = {
+    phase: 'serializing', requestId, timer: null, onSerialized: null, baseSeq: 0, result: null,
+    provisionalAttached: false,
+    processGeneration: _deps._terminalProcessGeneration(session),
+    absoluteDeadlineAt: Date.now() + _deps.TERMINAL_BOOTSTRAP_ABSOLUTE_LIFETIME_MS,
+  };
+  gates.set(request.id, gate);
+  if (!session.clients.includes(ws)) {
+    session.clients.push(ws);
+    _deps._recordClientAttachDiagnostic(session, request.id, ws);
+  }
+  if (!_deps._subscribeStateSyncClient(ws, request.id, 'terminal-bootstrap-route', { skipWorkerAttach: true })) {
+    session.clients = session.clients.filter(client => client !== ws);
+    gates.delete(request.id);
+    return _deps._sendTerminalBootstrapFailed(ws, request.id, 'session-not-live');
+  }
+  _deps._replayRestoreWakeVerdict(session, request.id, ws); // D-B2
+  // D-3: a terminal-bootstrap request IS a request to view this session's live frames -- a
+  // socket driving bootstrap through a route that predates (or never sends) an explicit 'view'
+  // declaration must still get frames once its base ACK installs, or the catch-up this gate
+  // exists to deliver would never leave the worker (see _impliedView).
+  _deps._impliedView(ws, request.id, 'terminal-bootstrap', { skipWorkerAttach: true }); // NEW-3: same skip as its own subscribe above
+  // Input routing is live before visual serialization. The worker bootstrap reservation still
+  // holds ordinary frames until the base ACK, so early keystrokes cannot race stale projection
+  // bytes even though they reach the live PTY immediately. "provisional" means THIS bootstrap
+  // attached the socket -- a failed re-bootstrap of an already-live socket must not detach it.
+  gate.provisionalAttached = !wasAttached;
+  const onSerialized = (serialized) => {
+    if (serialized.type !== 'serialized' || serialized.requestId !== requestId) return;
+    if (gates.get(request.id) !== gate || gate.phase !== 'serializing') return;
+    clearTimeout(gate.timer);
+    _deps.headlessWorker.off('message', onSerialized);
+    gate.timer = null;
+    gate.onSerialized = null;
+    const currentSession = _deps.sessions.get(request.id);
+    if (!currentSession || currentSession._exited || !currentSession.ptyProcess
+        || _deps._terminalProcessGeneration(currentSession) !== gate.processGeneration) {
+      return _deps._clearTerminalBootstrapGate(ws, request.id, {
+        reason: 'process-replaced', notify: true,
+      });
+    }
+    const cols = Number(serialized.cols || 0);
+    const rows = Number(serialized.rows || 0);
+    const baseSeq = Math.max(0, Number(serialized.bootstrap?.baseSeq || 0) || 0);
+    if (!serialized.bootstrap || !Number.isSafeInteger(cols) || cols <= 0 || !Number.isSafeInteger(rows) || rows <= 0) {
+      return _deps._clearTerminalBootstrapGate(ws, request.id, {
+        reason: 'serialize-invalid', notify: true,
+      });
+    }
+    // D-5/WP-3 fix2: mirror the worker's own base-vs-keyframe decision (from `clientBufferLength`).
+    const bootstrapMode = serialized.bootstrapMode === 'keyframe' ? 'keyframe' : 'base';
+    // WP-3 (D-9/S-48): the reservation is the ONLY source of gridRevision/surfaceEpoch for the
+    // wire result -- carrying them lets the browser commit a real baseline tuple from the
+    // bootstrap seed instead of forcing a keyframe on the first post-activation frame.
+    const gridRevision = Math.max(0, Number(serialized.bootstrap?.gridRevision || 0) || 0);
+    const surfaceEpoch = Math.max(0, Number(serialized.bootstrap?.surfaceEpoch || 0) || 0);
+    let result;
+    try {
+      result = _deps.truncateBootstrapAnsi(serialized.data, (ansi) => _deps.composeTerminalBootstrapResult({
+        id: request.id, baseSeq, cols, rows, ansi, mode: bootstrapMode, gridRevision, surfaceEpoch, ...(bootstrapMode === 'base' ? { archiveRow0: Number.isFinite(serialized.archiveRow0) ? serialized.archiveRow0 : null } : {}), // D-4 (WP-4 fix round 4): base-only identity-seam anchor, worker-computed
+        ...(serialized.mouse ? { mouse: serialized.mouse } : {}), // altscreen-wheel-mouse-report-truth-2026-09-12 gap fix: same-instant mirror mouse state
+      }));
+    } catch (error) {
+      // Fixed metadata is bounded; this is a defensive truthful completion if an
+      // unexpected serializer value still cannot compose a truncated base. Never
+      // send unchanged here: a cold client has no prior base to acknowledge.
+      return _deps._clearTerminalBootstrapGate(ws, request.id, {
+        reason: 'serialize-invalid', notify: true,
+      });
+    }
+    if (_deps.sessions.get(request.id) !== currentSession
+        || _deps._terminalProcessGeneration(currentSession) !== gate.processGeneration) {
+      return _deps._clearTerminalBootstrapGate(ws, request.id, {
+        reason: 'process-replaced', notify: true,
+      });
+    }
+    // S-31 (terminal-baseline-single-owner-2026-09-14 WP-4): deliberately NO gridRevision check
+    // here. Under D-2 a seq is never reused within a worker lifetime, and `processGeneration`
+    // already covers a PTY restart (the one case a seq could repeat) -- `lastAppliedSeq ===
+    // baseSeq` at an unchanged `processGeneration` already uniquely identifies the same delivery
+    // state the client already has. Adding a gridRevision comparison would only add a field this
+    // decision does not need to disambiguate anything it doesn't already disambiguate.
+    const unchanged = request.knownProcessGeneration > 0
+      && request.knownProcessGeneration === gate.processGeneration
+      && request.lastAppliedSeq === baseSeq;
+    _deps._armTerminalBootstrapGateDeadline(ws, request.id, gate, 'await-ack');
+    gate.baseSeq = baseSeq;
+    gate.bootstrapMode = bootstrapMode; gate.clientBufferLength = Number(request.clientBufferLength || 0); gate.rows = rows;
+    gate.result = unchanged // altscreen-wheel-mouse-report-truth-2026-09-12 gap fix: mouse rides unchanged too
+      ? _deps.composeTerminalBootstrapResult({ id: request.id, baseSeq, unchanged: true, gridRevision, surfaceEpoch, ...(serialized.mouse ? { mouse: serialized.mouse } : {}) })
+      : result;
+    _deps._wsSend(ws, gate.result, { class: 'interactive', channel: 'terminal-bootstrap', sessionId: request.id });
+  };
+  gate.onSerialized = onSerialized;
+  _deps._armTerminalBootstrapGateDeadline(ws, request.id, gate, 'serializing');
+  _deps.headlessWorker.on('message', onSerialized);
+  _deps.headlessWorker.postMessage({
+    // WP-6 (reload regression): was a hardcoded scrollback: 0 -- post the same normalized cap handleAttach uses.
+    type: 'serialize-bootstrap', sessionId: request.id, requestId, scrollback: _deps.normalizeSnapshotScrollbackRows(session._snapshotScrollbackRows),
+    clientId: String(ws.clientId || ''), socketGeneration: Number(ws.socketGeneration || 0),
+    clientBufferLength: request.clientBufferLength,
+  });
+}
+
+function handleResize(ws, msg) {
+  let request = msg;
+  if (msg?.geometryProtocolVersion === 2) {
+    try {
+      const sanitized = _deps.sanitizeGeometryResize(msg, Number(ws?.socketGeneration || 0));
+      request = sanitized;
+    } catch (error) {
+      if (!(error instanceof _deps.GeometryClaimValidationError)) throw error;
+      const candidateId = typeof msg?.id === 'string' && msg.id.length <= 128 ? msg.id : '';
+      if (candidateId && _deps.sessions.has(candidateId)) {
+        _deps.recordSessionDiagnostic(candidateId, 'terminal-geometry-fenced', {
+          operation: 'resize', reason: String(error.code || 'resize-shape-invalid').slice(0, 40),
+        });
+      }
+      _deps._sendTerminalGeometryFenceAck(ws, {
+        id: candidateId, operation: 'resize', reason: String(error.code || 'resize-shape-invalid'),
+      });
+      return;
+    }
+  }
+  msg = request;
+  const session = _deps.sessions.get(msg.id);
+  if (session && msg.cols != null && msg.rows != null) {
+    if (msg.geometryProtocolVersion !== 2) {
+      _deps.recordSessionDiagnostic(msg.id, 'terminal-geometry-fenced', {
+        operation: 'resize', reason: 'geometry-claim-required',
+      });
+      _deps._sendTerminalGeometryFenceAck(ws, {
+        id: msg.id, operation: 'resize', reason: 'geometry-claim-required',
+      });
+      return;
+    }
+    let geometryFence = null;
+    if (msg.geometryProtocolVersion === 2) {
+      geometryFence = {
+        clientId: String(ws.clientId || ''),
+        socketGeneration: msg.socketGeneration,
+        ownerGeneration: msg.ownerGeneration,
+        measurementId: msg.measurementId,
+        layoutEpoch: msg.layoutEpoch,
+        cols: msg.cols,
+        rows: msg.rows,
+      };
+      const fence = _deps.validateGeometryFence(_deps._geometryLease(session, msg.id), geometryFence);
+      if (!fence.ok) {
+        _deps.recordSessionDiagnostic(msg.id, 'terminal-geometry-fenced', {
+          operation: 'resize', reason: fence.reason,
+          ownerGeneration: msg.ownerGeneration,
+          measurementId: msg.measurementId,
+        });
+        _deps._sendTerminalGeometryFenceAck(ws, {
+          id: msg.id, operation: 'resize', reason: fence.reason,
+        });
+        return;
+      }
+    }
+    if (!_deps.CTM_GRID_PROVENANCE && (!msg.cols || !msg.rows)) return;
+    if (!session.ptyProcess) return;
+    const activation = null;
+    if (false) {
+      // This guard exists to stop a resize from moving the PTY out from under an in-flight
+      // activation. It must protect the PTY DIMENSIONS, not discard the client's identity.
+      // A resize for the dims the activation ALREADY owns conflicts with nothing — there is
+      // no PTY change to make — yet the old unconditional return also skipped
+      // _recordViewerDims and _claimGeometryFocus below. A client whose fit-resize reliably
+      // lands during activation was therefore never registered as a viewer and never
+      // promoted to primary geometry owner, so the lease's measurement identity could never
+      // reconverge with the client's newer measurement. Every subsequent activation was then
+      // refused 'geometry-generation-fenced', the client's bounded redrive budget (2) drained,
+      // the activation latched DEGRADED, and projectInputOwnership disabled terminal input
+      // with no escape — a session frozen with a perfectly alive PTY.
+      // Live evidence (session eed3efb1): 'primary': null with its ONLY viewer classified as a
+      // secondary, three activation epochs fenced in ~1s, then input readiness latched false.
+      // Register the identity; decline only the PTY drive.
+      const requestedCols = Number(msg.cols) || 0;
+      const requestedRows = Number(msg.rows) || 0;
+      const ownedCols = Number(activation.grid?.cols || 0);
+      const ownedRows = Number(activation.grid?.rows || 0);
+      const sameGrid = requestedCols > 0 && requestedRows > 0
+        && requestedCols === ownedCols && requestedRows === ownedRows;
+      _deps.recordSessionDiagnostic(msg.id, 'terminal-activation-resize-rejected', {
+        activationEpoch: activation.activationEpoch,
+        phase: activation.phase,
+        requestedCols,
+        requestedRows,
+        ownedCols,
+        ownedRows,
+        disposition: sameGrid ? 'noop-registered' : 'rejected',
+      });
+      if (sameGrid) {
+        _deps._recordViewerDims(ws, msg.id, requestedCols, requestedRows, 'measured');
+        _deps._claimGeometryFocus(ws, msg.id, 'resize', { interaction: true });
+        return;
+      }
+      _deps._sendTerminalGeometryFenceAck(ws, {
+        id: msg.id, operation: 'resize', reason: 'activation-owns-grid',
+      });
+      return;
+    }
+    const verdict = msg.geometryProtocolVersion === 2 ? {
+      source: 'measured',
+      cols: Number(msg.cols),
+      rows: Number(msg.rows),
+      valid: true,
+      reason: '',
+    } : _deps.classifyInboundGrid(msg);
+    const gate = _deps.mayDrivePtyResize(verdict);
+    const emitSite = String(msg.emitSite || 'unknown').slice(0, 80);
+    const clientId = String(ws.clientId || '').slice(0, 12);
+    if (_deps.CTM_GRID_PROVENANCE && !gate.allow) {
+      const details = {
+        requestedCols: verdict.cols,
+        requestedRows: verdict.rows,
+        source: verdict.source,
+        reason: gate.reason,
+        emitSite,
+        ptyCols: Number(session._ptyCols) || 0,
+        ptyRows: Number(session._ptyRows) || 0,
+        looksDefault: _deps.looksLikeXtermDefault(verdict.cols, verdict.rows),
+        clientId,
+      };
+      _deps._recordGridProvenanceDiagnostic(session, msg.id, 'unmeasured-resize-rejected', details);
+      _deps._recordGridProvenanceDiagnostic(session, msg.id, 'geometry-provenance', {
+        ...details,
+        outcome: 'rejected',
+      });
+      if (session._restoredHeadlessFromSnapshotAtSpawn) {
+        _deps._recordGridProvenanceDiagnostic(session, msg.id, 'restored-headless-unmeasured-resize-skip', details);
+      }
+      return;
+    }
+    if (!_deps.CTM_GRID_PROVENANCE
+        && session._restoredHeadlessFromSnapshotAtSpawn
+        && msg.geometryProtocolVersion !== 2
+        && msg.terminalDimsMeasured !== true) {
+      const grid = _deps._resolveRestoredHeadlessRequestGrid(session, msg, 'resize');
+      _deps.recordSessionDiagnostic(msg.id, 'restored-headless-unmeasured-resize-skip', {
+        requestedCols: msg.cols || 0,
+        requestedRows: msg.rows || 0,
+        cols: grid.cols || 0,
+        rows: grid.rows || 0,
+      });
+      return;
+    }
+    const cols = _deps.CTM_GRID_PROVENANCE ? verdict.cols : (Number(msg.cols) || 0);
+    const rows = _deps.CTM_GRID_PROVENANCE ? verdict.rows : (Number(msg.rows) || 0);
+    const acceptedSource = _deps.CTM_GRID_PROVENANCE ? verdict.source : 'measured';
+    _deps._recordViewerDims(ws, msg.id, cols, rows, acceptedSource);
+    _deps._claimGeometryFocus(ws, msg.id, 'resize', { interaction: true });
+
+    // Width arbitration: the shared PTY follows the PRIMARY viewer only. A
+    // SECONDARY viewer's resize must NOT move the PTY/headless — that drift is
+    // exactly what corrupts the other viewers' scrollback (their width-specific
+    // raw stream lands at the wrong width). Secondaries are rendered at their own
+    // width via a pushed snapshot instead. Single-viewer sessions: that sole
+    // viewer is the primary, so this is identical to the old behavior.
+    const arb = _deps._viewerArbitration(session, msg.id);
+    const isPrimary = !arb.primaryWs || arb.primaryWs === ws;
+    if (_deps.CTM_GRID_PROVENANCE) {
+      _deps._recordGridProvenanceDiagnostic(session, msg.id, 'geometry-provenance', {
+        requestedCols: cols,
+        requestedRows: rows,
+        source: acceptedSource,
+        reason: gate.reason,
+        outcome: 'accepted',
+        emitSite,
+        ptyCols: Number(session._ptyCols) || 0,
+        ptyRows: Number(session._ptyRows) || 0,
+        clientId,
+        appliedToPty: isPrimary,
+        arbitration: isPrimary ? 'primary' : 'secondary',
+      });
+    }
+
+    if (isPrimary) {
+      _deps._markCtmUiRefreshActivitySuppression(session, 'resize');
+      // WI-3 (resume-grid-mismatch-render-churn): a resize arriving within
+      // CTM_FRESH_PROCESS_ADOPT_MS of the PTY's own process spawn is nearly free — the TUI
+      // hasn't painted a screen the user is reading yet, so applying it now beats deferring 30s
+      // (_deferPrimaryPtyResizeIfStreaming's quiet-window hold) and later SIGWINCHing a settled
+      // screen into a full reflow. Scoped to agent TUIs (shell PTYs already resize eagerly via
+      // the fall-through below) and to a genuine dims change.
+      const freshProviderId = session._providerId || _deps._providerIdFromCmd(session.cmd || '');
+      const freshAgentTui = !!freshProviderId && freshProviderId !== 'shell';
+      const freshPtyCols = Number(session._ptyCols || 0);
+      const freshPtyRows = Number(session._ptyRows || 0);
+      const freshSpawnedAt = Number(session._ptySpawnedAt || 0);
+      const freshAgeMs = freshSpawnedAt > 0 ? Date.now() - freshSpawnedAt : -1;
+      const freshDimsDiffer = freshPtyCols > 0 && freshPtyRows > 0 && (cols !== freshPtyCols || rows !== freshPtyRows);
+      if (_deps.CTM_FRESH_PROCESS_ADOPT_ENABLED && freshAgentTui && freshDimsDiffer
+          && freshAgeMs >= 0 && freshAgeMs < _deps.CTM_FRESH_PROCESS_ADOPT_MS
+          && _deps._applyPrimaryPtyResize(session, msg.id, cols, rows, { site: 'resize-fresh-process' })) {
+        _deps._clearRowsFlapDebounce(session);
+        _deps.recordSessionDiagnostic(msg.id, 'resize-applied-fresh-process', { cols, rows, ageMs: freshAgeMs });
+        _deps._broadcastViewerRoles(session, msg.id);
+        return;
+      }
+      if (_deps._deferPrimaryPtyResizeIfStreaming(session, msg.id, cols, rows, 'resize', { geometryFence })) {
+        // Output resumed → the stream policy owns convergence now; drop any idle flap
+        // debounce so its trailing timer can't apply a stale grid behind the turn.
+        _deps._clearRowsFlapDebounce(session);
+        _deps._broadcastViewerRoles(session, msg.id);
+        return;
+      }
+      // Not streaming: an idle rows-only micro-flap (the resume-time chrome-height
+      // jitter) is trailing-edge debounced instead of applied per event — otherwise
+      // each SIGWINCH re-seeds the full composed history and the client re-prints it
+      // from the top. Genuine resizes fall through and apply immediately.
+      if (_deps._maybeDebounceRowsFlapResize(session, msg.id, cols, rows, { geometryFence })) {
+        _deps._broadcastViewerRoles(session, msg.id);
+        return;
+      }
+      if (!_deps._applyPrimaryPtyResize(session, msg.id, cols, rows, { site: 'resize-primary' })) return;
+    } else {
+      // Secondary viewer: dims recorded above; render it at its own width now
+      // without disturbing the PTY/heartbeat dims.
+      _deps._pushSecondarySnapshots(session, msg.id, 'secondary-resize').catch(() => {});
+    }
+    _deps._broadcastViewerRoles(session, msg.id);
+  }
+}
+
+function handleReflow(ws, msg) {
+  const session = _deps.sessions.get(msg.id);
+  if (!session) {
+    _deps.sendTerminalSessionUnavailableSnapshot(ws, msg.id, 'reflow', msg);
+    return;
+  }
+  _deps._recordRenderChurn(session, 'reflow');
+  const reflowGrid = _deps._resolveRestoredHeadlessRequestGrid(session, msg, 'reflow');
+  const cols = reflowGrid.cols;
+  const rows = reflowGrid.rows;
+  _deps.recordSessionDiagnostic(msg.id, 'reflow-request', {
+    cols, rows,
+    redraw: !!msg.redraw,
+    source: msg.restoreSource || null,
+    clientRestoreSeq: msg.clientRestoreSeq || null,
+    clientAsset: _deps._wsClientAsset(ws),
+  });
+  // Reflow-storm cost containment: under a churn storm (≥ threshold reflows in the rolling
+  // window — the signature of a client stuck re-requesting), cap FRESH full serializes of
+  // the giant session to one per window-half and serve the cached snapshot in between.
+  // Freshness still converges (a fresh serialize is always allowed once the cap elapses,
+  // and the heartbeat/boundary paths keep refreshing the cache); what this kills is the
+  // "full multi-MB serialize every 4.5s for an entire turn" failure mode. redraw reflows
+  // (stale-width recovery) are never throttled.
+  if (!msg.redraw && session._renderChurn && session._renderChurn.reflows.length >= _deps.RENDER_CHURN_FLASH_THRESHOLD
+      && Date.now() - (session._lastFreshReflowServeAt || 0) < _deps.RENDER_CHURN_WINDOW_MS / 2
+      && _deps._serveCachedSnapshotOnSerializeTimeout(ws, session, msg.id, cols, rows, 'reflow', msg.clientRestoreSeq)) {
+    _deps.recordSessionDiagnostic(msg.id, 'reflow-churn-served-cache', {
+      cols, rows, reflowsInWindow: session._renderChurn.reflows.length,
+    });
+    return;
+  }
+  session._lastFreshReflowServeAt = Date.now();
+  const scrollbackRows = _deps.normalizeSnapshotScrollbackRows(msg.scrollback);
+  session._snapshotScrollbackRows = scrollbackRows;
+  // Codex rollout-backed history: re-render at the REQUESTED cols (clean, width-perfect)
+  // instead of reflowing the lossy serialize blob — this is what kills the resize-time
+  // in-place corruption (s6ssion / "Working 3 12"). Serialize the native live region only.
+  const useRolloutHistory = _deps._codexRolloutHistoryActive(session, msg.id);
+  if (session._restoreDeferred) {
+    const starting = _deps._maybeAutoStartDeferredRestore(session, msg, 'reflow', ws);
+    _deps.sendDeferredRestoreStatus(ws, session, msg.id, cols, rows, 'reflow', {
+      scrollbackRows,
+      clientRestoreSeq: msg.clientRestoreSeq,
+      restoreSource: 'reflow-deferred-cache',
+      starting,
+    });
+    return;
+  }
+  if (typeof session._flushHeadlessFeed === 'function') session._flushHeadlessFeed();
+  const reqId = `reflow-${Date.now()}`;
+  let reflowOutputMarker = _deps._snapshotOutputMarker(session);
+  const timer = setTimeout(() => {
+    _deps.headlessWorker.off('message', onSnap);
+    _deps._noteInteractiveSerializeDone(reqId);
+    console.warn(`[reflow] Headless worker timed out for session ${msg.id.slice(0, 8)}`);
+    // Serve the last good cached frame instead of leaving the client on a half-painted
+    // one (and instead of a data:null retry that re-contends the worker). Self-heals via
+    // the heartbeat divergence check once the worker frees up.
+    const sess = _deps.sessions.get(msg.id);
+    if (_deps._serveCachedSnapshotOnSerializeTimeout(ws, sess, msg.id, cols, rows, 'reflow', msg.clientRestoreSeq)) return;
+    if (ws.readyState === 1) _deps._wsSend(ws, JSON.stringify({ type: 'snapshot', id: msg.id, data: null, timedOut: true, clientRestoreSeq: msg.clientRestoreSeq, restoreSource: 'reflow' }));
+  }, _deps.CTM_INTERACTIVE_SERIALIZE_TIMEOUT_MS);
+  const onSnap = (resp) => {
+    if (resp.type !== 'serialized' || resp.requestId !== reqId) return;
+    clearTimeout(timer);
+    _deps._noteInteractiveSerializeDone(reqId);
+    _deps.headlessWorker.off('message', onSnap);
+    const currentSession = _deps.sessions.get(msg.id);
+    const forceMidTurnSnapshot = msg.forceMidTurnSnapshot === true;
+    if (useRolloutHistory && currentSession && resp.data) {
+      resp = _deps._composeCodexRolloutResp(currentSession, msg.id, resp, {
+        deferMidTurn: true,
+        forceMidTurnSnapshot,
+        reflow: true,
+      });
+    }
+    // Mid-turn suppression: the compose declined to push a destructive snapshot while the
+    // codex turn is still streaming (see _shouldSuppressMidTurnRestore). Tell the client to
+    // keep its current live render; the settle-time reconcile reapplies the clean snapshot.
+    if (resp && resp._codexMidTurnDeferred) {
+      _deps.recordSessionDiagnostic(msg.id, 'reflow-deferred-midturn', { requestId: reqId, clientRestoreSeq: msg.clientRestoreSeq || null });
+      if (ws.readyState === 1) {
+        _deps._wsSend(ws, JSON.stringify({ type: 'snapshot', id: msg.id, data: null, midTurnDeferred: true, clientRestoreSeq: msg.clientRestoreSeq, restoreSource: 'reflow' }));
+      }
+      return;
+    }
+    if (resp?.composePending) {
+      _deps.recordSessionDiagnostic(msg.id, 'interactive-compose-pending', {
+        requestId: reqId,
+        retryAfterMs: Number(resp.retryAfterMs) || 1000,
+      });
+      if (ws.readyState === 1) {
+        _deps._wsSend(ws, JSON.stringify({
+          type: 'snapshot',
+          id: msg.id,
+          data: null,
+          composePending: true,
+          retryAfterMs: Number(resp.retryAfterMs) || 1000,
+          clientRestoreSeq: msg.clientRestoreSeq,
+          restoreSource: 'reflow',
+        }));
+      }
+      return;
+    }
+    let staleSnapshot = false;
+    if (currentSession && resp.data) {
+      const stored = _deps._cacheSerializedSnapshot(currentSession, resp, reflowOutputMarker);
+      staleSnapshot = !!stored.stale;
+      if (staleSnapshot) {
+        _deps.recordSessionDiagnostic(msg.id, 'reflow-stale-output-after-request', {
+          requestId: reqId,
+          clientRestoreSeq: msg.clientRestoreSeq || null,
+          marker: stored.marker,
+          current: stored.current,
+        });
+      }
+    }
+    if (staleSnapshot) {
+      _deps.recordSessionDiagnostic(msg.id, 'reflow-stale-snapshot-skip', {
+        requestId: reqId,
+        clientRestoreSeq: msg.clientRestoreSeq || null,
+        cols: resp.cols || 0,
+        rows: resp.rows || 0,
+        bytes: String(resp.data || '').length,
+      });
+      if (ws.readyState === 1) {
+        _deps._wsSend(ws, JSON.stringify({
+          type: 'snapshot',
+          id: msg.id,
+          data: null,
+          stale: true,
+          clientRestoreSeq: msg.clientRestoreSeq,
+          restoreSource: 'reflow',
+        }));
+      }
+      return;
+    }
+    _deps.recordSessionDiagnostic(msg.id, 'reflow-fresh-snapshot-send', {
+      requestId: reqId,
+      clientRestoreSeq: msg.clientRestoreSeq || null,
+      clientAsset: _deps._wsClientAsset(ws),
+      cols: resp.cols || 0,
+      rows: resp.rows || 0,
+      bytes: String(resp.data || '').length,
+      stale: false,
+    });
+    if (ws.readyState === 1) {
+      const snapshotData = _deps._coalesceSnapshotSynchronizedFrames(resp.data);
+      _deps._wsSend(ws, JSON.stringify({ type: 'snapshot', id: msg.id, data: snapshotData, ptyCols: resp.cols, ptyRows: resp.rows, scrollback: resp.scrollback, clientRestoreSeq: msg.clientRestoreSeq, restoreSource: 'reflow', codexRolloutComposed: resp.codexRolloutComposed || undefined, frameOwnedViewport: resp.frameOwnedViewport || undefined, terminalDisplayMode: resp.terminalDisplayMode || undefined, renderProjection: resp.renderProjection || undefined, fp: resp.fp }));
+    }
+  };
+  _deps.headlessWorker.on('message', onSnap);
+  _deps._noteInteractiveSerializeStart(reqId); // Part 1: prewarm defers while this reflow serialize is in flight
+
+  const serialize = () => {
+    if (typeof session._flushHeadlessFeed === 'function') session._flushHeadlessFeed();
+    reflowOutputMarker = _deps._snapshotOutputMarker(session);
+    // Ensure headless terminal matches client dimensions, then serialize and
+    // send snapshot — same path as tab-switch restore.
+    _deps.headlessWorker.postMessage({ type: 'resize', sessionId: msg.id, cols, rows });
+    _deps.headlessWorker.postMessage({ type: 'serialize', sessionId: msg.id, requestId: reqId, scrollback: useRolloutHistory ? 0 : scrollbackRows });
+  };
+
+  // Width arbitration: only the PRIMARY viewer may SIGWINCH the shared PTY. A
+  // redraw-reflow from a secondary would move the PTY to that viewer's width and
+  // corrupt everyone else — downgrade it to a plain serialize at the requested
+  // dims (no PTY poke), then restore the headless to the primary grid so the
+  // heartbeat fingerprint stays put. Scoped strictly to the multi-viewer case:
+  // with no secondaries this is ALWAYS true, so single-viewer reflow (the common
+  // case) is identical to pre-arbitration behavior.
+  const reqMayDrivePty = !session._hasSecondaryViewers || !session._primaryWs || session._primaryWs === ws;
+  // Mid-stream guard: a SIGWINCH while output is in flight makes the TUI re-emit its
+  // in-flight block -> permanent duplicate scrollback (see _deferPrimaryPtyResizeIfStreaming).
+  // While deferred, the PTY/headless grid stays put; we serialize at the REQUESTED dims
+  // and restore the headless to the PTY grid afterward (same dance as the secondary
+  // path). The destructive redraw nudge is pointless mid-stream anyway — the live
+  // output is already repainting the screen.
+  const ptyResizeDeferred = reqMayDrivePty && session.ptyProcess
+    && _deps._deferPrimaryPtyResizeIfStreaming(session, msg.id, cols, rows, msg.redraw ? 'reflow-redraw' : 'reflow');
+  if (ptyResizeDeferred && msg.redraw) {
+    _deps.recordSessionDiagnostic(msg.id, 'reflow-redraw-downgraded-streaming', { cols, rows });
+  }
+  if (msg.redraw && session.ptyProcess && reqMayDrivePty && !ptyResizeDeferred) {
+    _deps._markCtmUiRefreshActivitySuppression(session, 'reflow');
+    const nudgeCols = cols > 20 ? cols - 1 : cols + 1;
+    try {
+      // A same-size resize often does not produce SIGWINCH, so tools like
+      // Codex/Claude/OpenCode do not repaint their full-screen UI. Nudge one
+      // column, then restore the target size and snapshot after the app has a
+      // chance to redraw from its own source state.
+      session.ptyProcess.resize(nudgeCols, rows);
+      session._lastViewerProvokeAt = Date.now(); // SIGWINCH repaint = viewer-provoked output (status D-2)
+      _deps.recordSessionDiagnostic(msg.id, 'pty-resize-applied', _deps.buildPtyResizeAppliedDetail({ site: 'reflow-nudge', cols: nudgeCols, rows, intent: 'nudge-enter' }));
+      _deps.headlessWorker.postMessage({ type: 'resize', sessionId: msg.id, cols: nudgeCols, rows, nudge: 'enter' });
+    } catch {}
+    setTimeout(() => {
+      try {
+        session.ptyProcess.resize(cols, rows);
+        session._lastViewerProvokeAt = Date.now(); // SIGWINCH repaint = viewer-provoked output (status D-2)
+        _deps.recordSessionDiagnostic(msg.id, 'pty-resize-applied', _deps.buildPtyResizeAppliedDetail({ site: 'reflow-nudge', cols, rows, intent: 'nudge-exit' }));
+      } catch {}
+      _deps.headlessWorker.postMessage({ type: 'resize', sessionId: msg.id, cols, rows, nudge: 'exit' });
+      setTimeout(serialize, 120);
+    }, 80);
+  } else {
+    // Also sync PTY dimensions (in case they drifted) — ONLY when the requester
+    // is the primary. A secondary's reflow must NOT move the shared PTY.
+    if (session.ptyProcess && reqMayDrivePty && !ptyResizeDeferred) {
+      _deps._markCtmUiRefreshActivitySuppression(session, 'reflow');
+      try {
+        session.ptyProcess.resize(cols, rows);
+        session._lastViewerProvokeAt = Date.now(); // SIGWINCH repaint = viewer-provoked output (status D-2)
+        _deps.recordSessionDiagnostic(msg.id, 'pty-resize-applied', _deps.buildPtyResizeAppliedDetail({ site: 'reflow-sync', cols, rows }));
+      } catch {}
+    }
+    serialize();
+    if ((!reqMayDrivePty || ptyResizeDeferred) && session._ptyCols > 0 && session._ptyRows > 0
+        && (session._ptyCols !== cols || session._ptyRows !== rows)) {
+      // The serialize ran at the requester's dims; restore the headless to the
+      // authoritative PTY grid (FIFO after serialize). The PTY grid is what the TUI
+      // BELIEVES the screen is — holding the mirror at ANY other rows makes the TUI's
+      // scroll-at-believed-bottom-row miss the mirror's real bottom, so its diff-painter
+      // model diverges and every repaint bakes interleaved ghost rows INTO the mirror
+      // (live 3457b284/b363b51d: old "Working (Xs)…" rows stranded mid-transcript for the
+      // whole rows-only defer — queue-bar row flaps + a chattering background terminal
+      // mean the defer can run for many minutes). The previous rows-only "mirror hold"
+      // (reflow-storm fix) assumed equal-cols divergence was content-safe; it is NOT —
+      // scroll behavior depends on rows. The storm's client half is fixed at the source
+      // instead (no adopt-mirror-rows, micro-flap suppression, recovery backoff), so the
+      // mirror follows the PTY unconditionally and the client tolerates the shorter
+      // frames (clear-orphans) until the deferred resize applies.
+      try { _deps.headlessWorker.postMessage({ type: 'resize', sessionId: msg.id, cols: session._ptyCols, rows: session._ptyRows }); } catch {}
+      if (ptyResizeDeferred && reqMayDrivePty && session._ptyCols === cols) {
+        _deps.recordSessionDiagnostic(msg.id, 'reflow-mirror-restored-rows-only-defer', {
+          cols, rows, ptyRows: session._ptyRows,
+        });
+      }
+    }
+  }
+}
+
+module.exports = {
+  configure,
+  handleAttach,
+  handleTerminalBootstrap,
+  handleResize,
+  handleReflow,
+};