create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/codex-rollout-history.js

@@ -0,0 +1,743 @@
+'use strict';
+
+// Landing-throughput WP-6 shard S9 (design doc §5 D-10 "move-only", §6 "Shard
+// module seam"): the fourteen Codex-rollout-history render/compose functions move out
+// of server.js VERBATIM into this module behind the same configure(deps) seam as
+// lib/api/session-messages.js (S3), lib/api/session-attach.js and
+// lib/terminal-attach-geometry.js (S6) and lib/walle-history-serve.js (S8). It
+// registers NO route and NO socket handler: lib/ws/lifecycle.js and lib/ws/state-sync.js
+// (wsLifecycleApi / wsStateSyncApi) and attachGeometry keep their tables and now receive
+// this module's exports, while server.js keeps the pass-through callers
+// (codexRolloutHistory.<name>) plus this by-value configure() seam.
+// Bodies are identical to server.js's declarations 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`. No moved body contains an inline
+// `require(...)`, so there is no require rebase here (unlike S1/S3/S6/S8).
+//
+// The module deliberately lives at lib/codex-rollout-history.js and NOT under lib/ws/:
+// these are payload/render helpers, not ws-router handlers.
+//
+// Injected deps, per function:
+//   _codexRowCandidateIds: (none)
+//   _sessionHasFocusedViewer: (none)
+//   requestRowCursorRepublish: _codexHistoryCursorRepairAt, recordSessionDiagnostic,
+//     requestTargetedConversationImport
+//   _codexRowHistoryBase: dbModule
+//   _matchingPublishedCodexRollout: (none)
+//   _transcriptHistoryProvider: CTM_CODEX_ROLLOUT_HISTORY_ENABLED, detectAgentType
+//   _codexRolloutHistoryActive: (none)
+//   _codexHistoryRenderCacheEntry: CODEX_HISTORY_EFFECTIVE_RENDERER_VERSION
+//   _codexHistoryRenderNull: recordSessionDiagnostic
+//   _codexHistoryRenderInputForBase: CODEX_HISTORY_EFFECTIVE_RENDERER_VERSION
+//   _runCodexHistoryRenderQueue: CODEX_ROLLOUT_HISTORY_TAIL_MAX_MSGS,
+//     CODEX_ROLLOUT_HISTORY_TAIL_SEED_MSGS, CTM_READPOOL_INTERACTIVE_LANE_ENABLED,
+//     CTM_SNAPSHOT_SHALLOW_GUARD_ENABLED, RESUME_PRIORITY_LANE_ENABLED,
+//     _SESSION_MESSAGES_READPOOL_TIMEOUT_MS, _offthreadRead, _rolloutRenderBreaker,
+//     _scheduleSecondaryPush, _snapshotSessionScrollbackToFile,
+//     _testHistoryRenderNullsRemaining, dbModule, recordSessionDiagnostic, sessions
+//   _requestCodexHistoryRender: CTM_READPOOL_INTERACTIVE_LANE_ENABLED
+//   _scheduleCodexHistoryRender: (none)
+//   _composeCodexRolloutResp: CODEX_HISTORY_EFFECTIVE_RENDERER_VERSION,
+//     CODEX_HISTORY_ROWS_STALE_ALARM_MS, CODEX_ROLLOUT_DURABLE_STALE_RENDER_MS,
+//     CODEX_ROLLOUT_HISTORY_MAX_LINES, CODEX_ROLLOUT_HISTORY_REFLOW_MAX_LINES,
+//     CTM_READPOOL_INTERACTIVE_LANE_ENABLED, CTM_SEAM_CONTENT_TRIM_ENABLED,
+//     RESUME_REPLAY_DEDUP_ENABLED, _buildCodexComposedMemoKey,
+//     _canReuseDurableHistoryRender, _codexViewportLooksSettled,
+//     _composeCodexHistorySnapshot, _decideCodexComposedMemoReuse,
+//     _hashCodexComposeViewport, _mirrorGridLinesForCompose,
+//     _observeCodexHistoryStaleRows, _selectCodexHistoryLineCap,
+//     _shouldSuppressMidTurnRestore, normalizeSnapshotScrollbackRows,
+//     recordSessionDiagnostic
+//
+// Mutable module state (D-10 rule 2): _testHistoryRenderNullsRemaining is the ONE
+// server.js binding a moved body WRITES (_runCodexHistoryRenderQueue's
+// `_testHistoryRenderNullsRemaining -= 1`), so it is injected as a getter/setter pair --
+// exactly how S3 (lib/api/session-messages.js) re-homed the two bindings its moved
+// bodies assign -- so the write reaches the same server.js binding instead of a copy
+// frozen at configure() time. _codexHistoryCursorRepairAt is a const Map that is only
+// mutated in place (never rebound), so it is passed by value like S8's per-session Maps.
+// Every other dep is a by-value reference; calls between the fourteen moved functions
+// stay direct (no _deps.).
+
+let _deps = null;
+
+function configure(deps = {}) {
+  _deps = deps;
+}
+
+function _codexRowCandidateIds(session, sessionId) {
+  const ids = [];
+  const add = (value) => {
+    const id = String(value || '').trim();
+    if (id && !ids.includes(id)) ids.push(id);
+  };
+  add(sessionId);
+  add(session && session._claudeSessionId);
+  return ids;
+}
+
+function _sessionHasFocusedViewer(session, sessionId) {
+  if (!session || !sessionId || !Array.isArray(session.clients)) return false;
+  return session.clients.some((ws) => (
+    ws?.readyState === 1
+    && ws.focused === sessionId
+    && (!(ws.viewing instanceof Set) || ws.viewing.has(sessionId))
+  ));
+}
+
+function requestRowCursorRepublish(sessionId, sourceId) {
+  const id = String(sessionId || '');
+  const source = String(sourceId || id);
+  if (!id || !source) return false;
+  const now = Date.now();
+  if (now - Number(_deps._codexHistoryCursorRepairAt.get(id) || 0) < 60000) return false;
+  _deps._codexHistoryCursorRepairAt.set(id, now);
+  void _deps.requestTargetedConversationImport(source, 'codex-history-stale-repair', { cursorOnly: false })
+    .then((result) => {
+      _deps.recordSessionDiagnostic(id, 'codex-history-row-cursor-republished', {
+        sourceId: source,
+        accepted: result?.accepted !== false,
+        completed: result?.completed !== false,
+      });
+    })
+    .catch((error) => {
+      _deps.recordSessionDiagnostic(id, 'codex-history-row-cursor-republish-failed', {
+        sourceId: source,
+        code: error?.code || '',
+        error: error?.message || String(error),
+      });
+    });
+  if (_deps._codexHistoryCursorRepairAt.size > 1000) {
+    for (const [repairId, at] of _deps._codexHistoryCursorRepairAt) {
+      if (now - at > 5 * 60 * 1000) _deps._codexHistoryCursorRepairAt.delete(repairId);
+    }
+  }
+  return true;
+}
+
+function _codexRowHistoryBase(session, sessionId) {
+  for (const id of _codexRowCandidateIds(session, sessionId)) {
+    try {
+      const state = _deps.dbModule.getSessionRowSourceCursorState(id);
+      const count = Number(state?.rowCount || 0);
+      if (count > 0) {
+        const projectionEpoch = Math.max(0, Number(state.projectionEpoch || 0));
+        const renderFresh = state.renderFresh === true;
+        const version = [
+          count,
+          state.checked ? 1 : 0,
+          renderFresh ? 1 : 0,
+          Number(state.importedSize || 0),
+          Number(state.maxTranscriptEventId || 0),
+          Number(state.rowBackfillCursorEventId || 0),
+          projectionEpoch,
+        ].join(':');
+        return {
+          id,
+          count,
+          fresh: !state.checked || state.fresh === true,
+          renderFresh,
+          state: String(state.state || ''),
+          cursorLagBytes: Math.max(0, Number(state.cursorLagBytes || 0)),
+          pendingEvents: Math.max(0, Number(state.pendingEvents || 0)),
+          parserVersion: Math.max(0, Number(state.parserVersion || 0)),
+          projectionEpoch,
+          projectionState: String(state.projectionState || 'ready'),
+          maxRowId: Math.max(0, Number(state.maxRowId || 0)),
+          version,
+        };
+      }
+    } catch { /* registry publication is best-effort; retry on the next snapshot */ }
+  }
+  return null;
+}
+
+// Published metadata only: a cache miss never discovers a transcript on main.
+function _matchingPublishedCodexRollout(session, sessionId) {
+  const threadId = session?._claudeSessionId || session?._providerResumeId || sessionId || session?.id;
+  const alias = session?._providerResumeId && session._providerResumeId !== threadId ? session._providerResumeId : '';
+  const cache = session?._codexRolloutPathCache;
+  return cache && cache.threadId === threadId
+    && (cache.providerResumeId === undefined || cache.providerResumeId === alias) ? cache : null;
+}
+
+// The provider-neutral transcript source for this session, or null if neither applies (wrong
+// provider or codex's kill switch is off). Two independent consumers key off this: (1) the
+// paged older-transcript-history API (apiSessionHistoryWindow / serveTranscriptHistoryV2),
+// which serves both codex and claude and has no kill switch of its own for claude, and
+// (2) the composed-terminal-seed gate (_codexRolloutHistoryActive below), which additionally
+// requires 'codex' — WP-5 retired the composed seed for claude, not this provider lookup.
+function _transcriptHistoryProvider(session) {
+  const agentType = _deps.detectAgentType((session && session.cmd) || '');
+  if (agentType === 'codex' && _deps.CTM_CODEX_ROLLOUT_HISTORY_ENABLED) return 'codex';
+  if (agentType === 'claude') return 'claude';
+  return null;
+}
+
+// Is the rollout-backed composed terminal seed active for this session? Codex only (WP-5
+// retired the claude compose) + a usable durable row source. Terminal UX never reads JSONL
+// directly; if rows are unavailable, callers behave exactly like today (serialize the
+// headless blob) -- and a claude session always behaves like today now, unconditionally.
+function _codexRolloutHistoryActive(session, sessionId) {
+  if (!session || _transcriptHistoryProvider(session) !== 'codex') return false;
+  return !!_codexRowHistoryBase(session, sessionId);
+}
+
+function _codexHistoryRenderCacheEntry(input, rendered) {
+  return {
+    key: input.renderKey,
+    ansi: rendered.ansi,
+    lineCount: rendered.lineCount,
+    renderedLineCount: rendered.renderedLineCount,
+    fellBack: rendered.fellBack,
+    messages: rendered.messages,
+    capped: !!rendered.capped,
+    elidedLines: Number(rendered.elidedLines || 0),
+    bound: input.historyLineCap,
+    source: input.sourceKey,
+    sourceKey: input.sourceKey,
+    lookupId: input.lookupId,
+    cols: input.cols,
+    rowMessages: Number(rendered.rowMessages || 0),
+    rowBaseCount: Number(input.rowBaseCount || 0),
+    rowBaseVersion: String(input.rowBaseVersion || ''),
+    sourceRowHwm: Math.max(0, Number(input.sourceRowHwm || 0)),
+    displayMode: rendered.displayMode || 'terminal-markdown',
+    historyLineCap: input.historyLineCap,
+    messageSpans: Array.isArray(rendered.spans) ? rendered.spans : [],
+    elidedMessages: Number(rendered.elidedMessages || 0),
+    rendererVersion: _deps.CODEX_HISTORY_EFFECTIVE_RENDERER_VERSION,
+    historyRenderFidelity: true,
+    createdAt: Date.now(),
+    // WP-0: worker-measured render time (see workers/read-pool-worker.js 'renderRolloutHistory'),
+    // threaded through the cache entry so a cache-hit compose can still report it.
+    renderMs: Number.isFinite(Number(rendered.workerRenderMs)) ? Number(rendered.workerRenderMs) : undefined,
+  };
+}
+
+function _codexHistoryRenderNull(sessionId, reason, details = {}) {
+  _deps.recordSessionDiagnostic(sessionId, 'codex-history-render-null', { reason, ...details });
+  return { retryable: true, cause: reason };
+}
+
+function _codexHistoryRenderInputForBase(input, rowBase) {
+  const sourceKey = rowBase.renderFresh ? 'rows' : 'rows-stale';
+  return {
+    ...input,
+    renderKey: `${input.agentType}:${sourceKey}:${rowBase.id}:${rowBase.version}:${input.cols}:${input.historyLineCap}:renderer${_deps.CODEX_HISTORY_EFFECTIVE_RENDERER_VERSION}:fidelity1`,
+    lookupId: rowBase.id,
+    sourceKey,
+    rowBaseCount: rowBase.count || 0,
+    rowBaseVersion: rowBase.version,
+    sourceRowHwm: rowBase.maxRowId || 0,
+  };
+}
+
+function _runCodexHistoryRenderQueue(session) {
+  if (!session || session._codexHistoryRenderInFlight) return;
+  const queue = session._codexHistoryRenderQueue;
+  if (!Array.isArray(queue) || queue.length === 0) return;
+  const request = queue.shift();
+  if (_deps.sessions.get(request.sessionId) !== session) {
+    request.resolve(_codexHistoryRenderNull(request.sessionId, 'session-swap'));
+    setImmediate(() => _runCodexHistoryRenderQueue(session));
+    return;
+  }
+  const input = request.input;
+  session._codexHistoryRenderInFlight = request;
+  void _deps._offthreadRead({
+    breaker: _deps._rolloutRenderBreaker,
+    op: 'renderRolloutHistory',
+    timeoutMs: _deps._SESSION_MESSAGES_READPOOL_TIMEOUT_MS,
+    payload: {
+      dbPath: _deps.dbModule.getDbPath(),
+      rowSourceId: input.lookupId,
+      messageLimit: _deps.CODEX_ROLLOUT_HISTORY_TAIL_MAX_MSGS,
+      minSeedMessages: _deps.CODEX_ROLLOUT_HISTORY_TAIL_SEED_MSGS,
+      seedMsgs: Number(input.seedMsgs || 0),
+      agentType: input.agentType,
+      cols: input.cols,
+      cliVersion: input.cliVersion || '',
+      historyLineCap: input.historyLineCap,
+      historyRenderFidelity: true,
+      // WP-3 (terminal-memory-endgame S-11): the true store depth (session_message_rows
+      // COUNT), NOT the render window. The worker uses this — not the page's own `total`,
+      // which reflects whatever store getMessagesPage happens to read (v2 turns can be a
+      // much smaller count than the granular row store) — as the denominator for the
+      // elided-messages marker, so "N elided" is honest against the full transcript depth.
+      rowBaseCount: Number(input.rowBaseCount || 0),
+      telemetryReason: 'rollout-history-render',
+    },
+    // WI-7c: downgrade a durable (background persistence) render off the declared 'service'
+    // class so it can never head-of-line block a foreground render behind a bulk/durable
+    // backlog — see resolveReadPoolClass (a downgrade-only ceiling, never an escalation).
+    requestClass: _deps.CTM_READPOOL_INTERACTIVE_LANE_ENABLED && input.requestClass
+      ? input.requestClass
+      : (_deps.RESUME_PRIORITY_LANE_ENABLED && input.durable ? 'batch' : undefined),
+    onSuccess: (result) => result && typeof result === 'object' ? result : null,
+    onFail: (error) => input.requestClass === 'interactive'
+      ? {
+        composePending: true,
+        retryAfterMs: 1000,
+        errorCode: String(error?.code || ''),
+      }
+      : null,
+  }).then((renderedResult) => {
+    let rendered = renderedResult;
+    if (input.requestClass === 'interactive' && _deps._testHistoryRenderNullsRemaining > 0) {
+      _deps._testHistoryRenderNullsRemaining -= 1;
+      rendered = null;
+      _deps.recordSessionDiagnostic(request.sessionId, 'codex-history-render-null', {
+        reason: 'test-worker-null',
+        remaining: _deps._testHistoryRenderNullsRemaining,
+      });
+    }
+    if (rendered?.composePending) {
+      session._codexHistoryComposePending = {
+        until: Date.now() + Math.max(250, Number(rendered.retryAfterMs) || 1000),
+        retryAfterMs: Math.max(250, Number(rendered.retryAfterMs) || 1000),
+      };
+      request.resolve(rendered);
+      return;
+    }
+    if (!rendered?.ansi || session._codexHistoryRenderInFlight !== request
+        || _deps.sessions.get(request.sessionId) !== session) {
+      const reason = _deps.sessions.get(request.sessionId) !== session ? 'session-swap'
+        : (rendered?.composePending ? 'pool-fail' : 'worker-error');
+      request.resolve(rendered?.composePending || _codexHistoryRenderNull(request.sessionId, reason));
+      return;
+    }
+    const completedInput = request.input;
+    const current = _codexRowHistoryBase(session, request.sessionId);
+    if (!current || current.id !== completedInput.lookupId
+        || current.version !== completedInput.rowBaseVersion) {
+      if (!current || current.id !== completedInput.lookupId) {
+        request.resolve(_codexHistoryRenderNull(request.sessionId, current ? 'source-swap' : 'session-swap'));
+        return;
+      }
+      const completed = {
+        ..._codexHistoryRenderCacheEntry(completedInput, rendered),
+        staleByVersions: true,
+        currentRowBaseVersion: current.version,
+      };
+      _deps.recordSessionDiagnostic(request.sessionId, 'codex-history-render-version-advanced', {
+        fromVersion: completedInput.rowBaseVersion,
+        toVersion: current.version,
+      });
+      request.resolve(completed);
+      _scheduleCodexHistoryRender(session, request.sessionId, _codexHistoryRenderInputForBase(completedInput, current));
+      return;
+    }
+    session._rolloutHistoryTailSeed = Number(rendered.nextSeed || 0);
+    const cacheEntry = _codexHistoryRenderCacheEntry(completedInput, rendered);
+    session._codexHistoryRenderCache = cacheEntry;
+    session._codexHistoryComposePending = null;
+    // WP-4 (S-5/D-6): a DURABLE render request means the caller was
+    // _snapshotSessionScrollbackToFile's own compose attempt bailing (nothing cached
+    // yet) -- this render landing is exactly the deferred completion the shallow-
+    // overwrite guard above told the caller to wait for. Re-persist once now that a
+    // composed render exists, so the durable file catches up to full depth instead of
+    // waiting for the next periodic sweep (30s) or shutdown.
+    if (_deps.CTM_SNAPSHOT_SHALLOW_GUARD_ENABLED && completedInput.durable === true) {
+      setImmediate(() => {
+        if (_deps.sessions.get(request.sessionId) !== session) return;
+        _deps._snapshotSessionScrollbackToFile(request.sessionId, 5000).catch(() => { /* expected: best-effort re-persist -- a failure here just leaves the file at whatever the shallow-skip guard kept, which the next periodic sweep or shutdown snapshot still catches up */ });
+      });
+    }
+    _deps.recordSessionDiagnostic(request.sessionId, 'codex-rollout-history-render-ready', {
+      agent: completedInput.agentType,
+      cols: completedInput.cols,
+      rows: rendered.lineCount,
+      messages: rendered.messages,
+      capped: !!rendered.capped,
+    });
+    request.resolve(cacheEntry);
+    if (completedInput.settled === true
+        && Number(session._ptyCols || 0) === Number(completedInput.cols)
+        && typeof session._sendCleanSnapshot === 'function') {
+      setImmediate(() => {
+        if (_deps.sessions.get(request.sessionId) !== session) return;
+        session._sendCleanSnapshot(request.sessionId, null, {
+          restoreSource: 'rollout-history-render-ready',
+          reason: 'rollout-history-render-ready',
+          skipIfStale: true,
+        });
+      });
+    }
+    if (session._hasSecondaryViewers) _deps._scheduleSecondaryPush(session, request.sessionId, 'rollout-history-render-ready');
+  }).catch((err) => {
+    console.error('[rollout-history] worker render completion failed:', err.message);
+    request.resolve(_codexHistoryRenderNull(request.sessionId, 'worker-error', {
+      code: String(err?.code || ''),
+    }));
+  }).finally(() => {
+    if (session._codexHistoryRenderInFlight === request) session._codexHistoryRenderInFlight = null;
+    setImmediate(() => _runCodexHistoryRenderQueue(session));
+  });
+}
+
+function _requestCodexHistoryRender(session, sessionId, input) {
+  if (!session || !input?.renderKey) return Promise.resolve(null);
+  const cached = session._codexHistoryRenderCache;
+  if (cached?.key === input.renderKey && cached.ansi) return Promise.resolve(cached);
+
+  const inFlight = session._codexHistoryRenderInFlight;
+  if (inFlight?.key === input.renderKey) {
+    if (input.settled === true) inFlight.input.settled = true;
+    return inFlight.promise;
+  }
+  if (!Array.isArray(session._codexHistoryRenderQueue)) session._codexHistoryRenderQueue = [];
+  const queued = session._codexHistoryRenderQueue.find((entry) => entry.key === input.renderKey);
+  if (queued) {
+    if (input.settled === true) queued.input.settled = true;
+    return queued.promise;
+  }
+
+  let resolveRequest;
+  const promise = new Promise((resolve) => { resolveRequest = resolve; });
+  const request = {
+    key: input.renderKey,
+    sessionId,
+    input: { ...input },
+    promise,
+    resolve: resolveRequest,
+  };
+  if (_deps.CTM_READPOOL_INTERACTIVE_LANE_ENABLED && input.requestClass === 'interactive') {
+    session._codexHistoryRenderQueue.unshift(request);
+  } else {
+    session._codexHistoryRenderQueue.push(request);
+  }
+  _runCodexHistoryRenderQueue(session);
+  return promise;
+}
+
+function _scheduleCodexHistoryRender(session, sessionId, input) {
+  void _requestCodexHistoryRender(session, sessionId, input);
+}
+
+// Given a serialize reply that was requested at scrollback:0 (the native live
+// region only), prepend the rollout-synthesized settled history (rendered at the
+// SAME cols so the client never reflows it) and return a resp with composed data.
+// Codex only (WP-5 retired the claude compose path) — a non-codex session (including
+// claude, whose local scrollback is now served exactly like any other normal-buffer
+// session) returns resp UNCHANGED, never gets misrouted into this render path.
+// FAIL-SAFE: any problem returns the original resp unchanged (the native viewport),
+// so a bad render degrades to "live region only", never to corruption or a throw.
+function _composeCodexRolloutResp(session, sessionId, resp, opts = {}) {
+  if (!resp || !resp.data) return resp;
+  const agentType = _transcriptHistoryProvider(session);
+  if (agentType !== 'codex') return resp;
+  // durable: this snapshot is being PERSISTED to file (cold-resume seed), not sent
+  // live. The interactive transcript pager is kept for live sends but dropped for
+  // durable persistence so a cold resume never restores into a dead pager.
+  const durable = !!(opts && opts.durable);
+  const isReflow = !!(opts && opts.reflow);
+  try {
+    const cols = Number(resp.cols) || session._ptyCols || 80;
+    const liveViewportData = String(resp.data || '');
+    const settled = _deps._codexViewportLooksSettled(liveViewportData);
+    const gridSample = _deps._mirrorGridLinesForCompose(session, resp);
+    const capPolicy = _deps._selectCodexHistoryLineCap({
+      isReflow,
+      cols,
+      lastComposedCols: session._lastCodexHistoryComposeCols,
+      normalMaxLines: _deps.CODEX_ROLLOUT_HISTORY_MAX_LINES,
+      reflowMaxLines: _deps.CODEX_ROLLOUT_HISTORY_REFLOW_MAX_LINES,
+    });
+    const historyLineCap = capPolicy.cap;
+    const rowBase = _codexRowHistoryBase(session, sessionId);
+    if (!rowBase) return resp;
+    const lookupId = rowBase && rowBase.id;
+    if (!lookupId) return resp;
+    const sourceKey = rowBase.renderFresh ? 'rows' : 'rows-stale';
+    // Cheap content-version so repeated snapshots of unchanged row history
+    // (tab-switch, reconnect, secondary-push, reflow at the same width) skip the
+    // row fetch + render entirely. Terminal compose is row-only; rollout JSONL
+    // tails are not merged into this surface.
+    const version = rowBase.version;
+    // agentType-prefixed so a cached codex render can never serve a claude session (the
+    // cache lives on the session object and is per-session anyway; this is paranoia).
+    const renderKey = `${agentType}:${sourceKey}:${lookupId}:${version}:${cols}:${historyLineCap}:renderer${_deps.CODEX_HISTORY_EFFECTIVE_RENDERER_VERSION}:fidelity1`;
+    let historyAnsi; let lineCount; let renderedLineCount; let historyElidedLines = 0; let fellBack; let msgCount; let historyCapped = false; let displayMode = 'terminal-markdown'; let messageSpans = []; let historyElidedMessages = 0;
+    let source = sourceKey; let rowMsgCount = 0; let renderMs; // WP-0: worker-measured, undefined when not from a fresh/cached render
+    const rc = session._codexHistoryRenderCache;
+    const exactCacheHit = rc && rc.key === renderKey && !!rc.ansi;
+    const reusedStaleRender = !exactCacheHit && _deps._canReuseDurableHistoryRender({
+      durable,
+      cacheEntry: rc,
+      lookupId,
+      sourceKey,
+      cols,
+      historyLineCap,
+      rowBaseCount: rowBase.count || 0,
+      rendererVersion: _deps.CODEX_HISTORY_EFFECTIVE_RENDERER_VERSION,
+      historyRenderFidelity: true,
+      settled,
+      now: Date.now(),
+      maxAgeMs: _deps.CODEX_ROLLOUT_DURABLE_STALE_RENDER_MS,
+    });
+    const cacheHit = exactCacheHit || reusedStaleRender;
+    if (cacheHit) {
+      ({ ansi: historyAnsi, lineCount, renderedLineCount, fellBack, messages: msgCount } = rc);
+      messageSpans = Array.isArray(rc.messageSpans) ? rc.messageSpans : [];
+      historyElidedMessages = Number(rc.elidedMessages || 0);
+      displayMode = rc.displayMode || displayMode;
+      historyCapped = !!rc.capped;
+      historyElidedLines = Number(rc.elidedLines || 0);
+      source = rc.source || source;
+      rowMsgCount = Number(rc.rowMessages || 0);
+      renderMs = Number.isFinite(Number(rc.renderMs)) ? Number(rc.renderMs) : undefined;
+    } else {
+      const renderRequestClass = _deps.CTM_READPOOL_INTERACTIVE_LANE_ENABLED
+        ? (opts.requestClass || (
+          durable
+            ? 'batch'
+            : (_sessionHasFocusedViewer(session, sessionId) ? 'interactive' : 'service')
+        ))
+        : undefined;
+      const pending = session._codexHistoryComposePending;
+      if (renderRequestClass === 'interactive' && Number(pending?.until) > Date.now()) {
+        return {
+          ...resp,
+          data: null,
+          composePending: true,
+          retryAfterMs: Math.max(250, Number(pending.retryAfterMs) || 1000),
+        };
+      }
+      _scheduleCodexHistoryRender(session, sessionId, {
+        renderKey,
+        lookupId,
+        sourceKey,
+        rowBaseCount: rowBase.count || 0,
+        rowBaseVersion: rowBase.version,
+        agentType,
+        cols,
+        cliVersion: session._codexCliVersion || '',
+        historyLineCap,
+        seedMsgs: session._rolloutHistoryTailSeed || 0,
+        settled,
+        // WI-7c: a durable (persistence/cold-resume-seed) render is background work — it isn't
+        // shown to any connected client — so it must never queue ahead of a foreground render's
+        // own renderRolloutHistory read on the read pool (see _runCodexHistoryRenderQueue).
+        durable,
+        requestClass: renderRequestClass,
+      });
+      return resp;
+    }
+    // The live region is owned by Codex/state-sync. A flap/divergence-driven
+    // reflow (opts.deferMidTurn) that restores history while the turn is still
+    // streaming can reset over Codex's live inline repaint. Keep the current
+    // frame mid-turn; the settle-time reconcile applies H and then forces L.
+    // Returns data:null + a marker so the caller sends "keep-current".
+    if (_deps._shouldSuppressMidTurnRestore({
+      deferrableSource: !!(opts && opts.deferMidTurn),
+      settled,
+      forceMidTurnSnapshot: !!(opts && opts.forceMidTurnSnapshot),
+    })) {
+      _deps.recordSessionDiagnostic(sessionId, 'codex-midturn-restore-suppressed', { agent: agentType, cols, source });
+      return { ...resp, data: null, _codexMidTurnDeferred: true };
+    }
+    // WI-9 step 2: _composeCodexHistorySnapshot (seam compute + string concat of potentially
+    // multi-MB historyAnsi + liveViewportData) is a PURE function of (renderKey resolved above,
+    // the live viewport bytes, durable/reflow/rows/scrollbackRows) — a repeated snapshot request
+    // for a session sitting idle at the same settled screen (tab-switch, reconnect, secondary-
+    // push) recomputes byte-identical output every time. Memoize the COMPOSED result (not just
+    // the history render, already cached via session._codexHistoryRenderCache) per that tuple so
+    // an unchanged snapshot skips compose entirely.
+    const composeRows = Number(resp.rows) || Number(session._ptyRows) || 0;
+    const composeScrollbackRows = _deps.normalizeSnapshotScrollbackRows(session._snapshotScrollbackRows);
+    const composedMemoKey = _deps._buildCodexComposedMemoKey({
+      renderKey,
+      viewportHash: _deps._hashCodexComposeViewport(liveViewportData),
+      rows: composeRows,
+      durable,
+      reflow: isReflow,
+      scrollbackRows: composeScrollbackRows,
+    });
+    // Two memo slots (durable persistence vs live/client compose) so the interleaved durable
+    // scrollback-snapshot job and the client settle-reconcile composes stop EVICTING each other
+    // from a single slot — the cause of memo-hit=0 on a session with an active persistence job AND
+    // a viewer (prod 16864329 2026-07-22: 49 recomposes/2h, 0 memo hits, ~250 KB each). `durable`
+    // is already part of composedMemoKey, so a slot only ever reuses a same-durable payload;
+    // splitting slots changes hit rate, never correctness.
+    const composedMemoSlot = durable ? 'durable' : 'live';
+    const composedMemoStore = (session._codexComposedRespMemo && typeof session._codexComposedRespMemo === 'object')
+      ? session._codexComposedRespMemo : null;
+    const composedMemo = composedMemoStore ? composedMemoStore[composedMemoSlot] : null;
+    const staleRows = !!(rowBase && !rowBase.renderFresh);
+    const staleAlarm = _deps._observeCodexHistoryStaleRows(session, {
+      staleRows,
+      lookupId,
+      count: rowBase.count || 0,
+      state: rowBase.state || '',
+      cursorLagBytes: rowBase.cursorLagBytes || 0,
+      pendingEvents: rowBase.pendingEvents || 0,
+      parserVersion: rowBase.parserVersion || 0,
+      now: Date.now(),
+      thresholdMs: _deps.CODEX_HISTORY_ROWS_STALE_ALARM_MS,
+    });
+    if (staleAlarm) {
+      _deps.recordSessionDiagnostic(sessionId, 'codex-history-rows-stale-persistent', { agent: agentType, ...staleAlarm });
+      requestRowCursorRepublish(sessionId, lookupId);
+    }
+    if (_deps._decideCodexComposedMemoReuse({
+      enabled: _deps.RESUME_REPLAY_DEDUP_ENABLED,
+      memoKey: composedMemoKey,
+      lastMemoKey: composedMemo && composedMemo.key,
+      hasComposedPayload: !!(composedMemo && composedMemo.payload),
+    })) {
+      _deps.recordSessionDiagnostic(sessionId, 'codex-rollout-history-composed-memo-hit', {
+        agent: agentType,
+        cols,
+        bytes: composedMemo.payload.data ? composedMemo.payload.data.length : 0,
+      });
+      return { ...resp, ...composedMemo.payload };
+    }
+    const composed = _deps._composeCodexHistorySnapshot({
+      historyAnsi,
+      viewportAnsi: liveViewportData,
+      gridLines: gridSample.gridLines,
+      messageSpans,
+      settled,
+      gridStable: true, // agentType is guaranteed 'codex' here (claude compose retired, WP-5)
+      contentTrim: _deps.CTM_SEAM_CONTENT_TRIM_ENABLED,
+      durable,
+      opts: {
+        seam: true,
+        cols,
+        stale: staleRows,
+        // State-sync owns the live grid. Live snapshots restore H only; the
+        // restore-applied ACK resets the diff baseline and forces L over the
+        // visible history tail. Durable files still include the native viewport
+        // because no client/keyframe handshake exists while persisting.
+        frameOwnedViewport: !durable,
+        // Blank-viewport padding when the alt-screen live region is dropped (claude
+        // fullscreen): keeps history + seam in scrollback instead of letting the next
+        // keyframe paint the live screen over the history tail. Live sends only (the
+        // compose ignores padRows for durable persists).
+        padRows: Number(resp.rows) || Number(session._ptyRows) || 0,
+      },
+    });
+    if (!composed || !composed.data) return resp;
+    const terminalSurface = {
+      agent: agentType,
+      viewport: composed.droppedAltViewport
+        ? 'alt-screen'
+        : (composed.frameOwnedViewport ? 'frame-owned' : 'live'),
+      scrollback: {
+        witnessed: composed.witnessed,
+        recomposed: {
+          rows: Number(lineCount || 0),
+          cols,
+          bound: historyLineCap,
+          elided: historyElidedLines,
+          elidedMessages: historyElidedMessages,
+          parity: 'codex-tui',
+          stale: staleRows,
+        },
+        seam: {
+          present: !!(composed.seam && composed.seam.present),
+          text: (composed.seam && composed.seam.text) || '',
+        },
+        trimSkipReason: composed.trimSkipReason || '',
+      },
+      widths: {
+        pty: Number(resp.cols) || cols,
+        mirror: Number(resp.cols) || cols,
+      },
+      reason: opts && opts.reflow
+        ? (capPolicy.reflowWidthChanged ? 'width-change' : 'same-width-reflow')
+        : (opts && opts.deferMidTurn ? 'settle-reconcile' : (durable ? 'durable-persist' : 'settle-reconcile')),
+    };
+    _deps.recordSessionDiagnostic(sessionId, 'codex-rollout-history-composed', {
+      agent: agentType,
+      cols,
+      source,
+      cached: cacheHit,
+      reusedStaleRender: reusedStaleRender || undefined,
+      settled,
+      historyLines: lineCount,
+      historyLineCap,
+      reflow: isReflow || undefined,
+      reflowWidthChanged: capPolicy.reflowWidthChanged || undefined,
+      messages: msgCount,
+      rowMessages: rowMsgCount || undefined,
+      staleRows: rowBase && !rowBase.renderFresh || undefined,
+      capped: historyCapped,
+      bound: historyLineCap,
+      elidedLines: historyElidedLines || undefined,
+      elidedMessages: historyElidedMessages || undefined,
+      contentTrimmedLines: Number(composed.trimmed) || undefined,
+      trimSkipReason: composed.trimSkipReason || undefined,
+      fellBack,
+      displayMode,
+      terminalSurface,
+      bytes: composed.data.length,
+      // WP-0: worker-measured renderRolloutHistoryTail duration (undefined when this
+      // compose reused a durable/stale-tolerant render entry with no timing recorded).
+      renderMs,
+      // Codex gpt-5.5's full-screen (alt-screen) native viewport can't be inlined
+      // after the main-buffer history — the compose drops it and serves
+      // history-only so the browser doesn't switch to the alt buffer and hide the
+      // composer. Surface that so the "no input box" garble is diagnosable.
+      droppedAltViewport: composed.droppedAltViewport || undefined,
+    });
+    _deps.recordSessionDiagnostic(sessionId, 'terminal-surface-decision', terminalSurface);
+    session._lastCodexHistoryComposeCols = cols;
+    session._lastCodexHistoryComposeAt = Date.now();
+    // Report the full requested scrollback budget so cache-reuse matching treats
+    // this as a full-scrollback snapshot (the composed history covers it).
+    // Tag the result so the client applies H, acknowledges the restore, and lets
+    // the forced state-sync keyframe paint L. Interactive alt-screen composes do
+    // not carry frameOwnedViewport and remain owned by their native viewport.
+    const composedPayload = {
+      data: composed.data,
+      codexRolloutComposed: true,
+      frameOwnedViewport: !!composed.frameOwnedViewport,
+      terminalDisplayMode: displayMode,
+      terminalSurface,
+      renderProjection: {
+        surface: 'terminal',
+        displayMode,
+        source: 'codex-rollout-history',
+        terminalSurface,
+      },
+      scrollback: _deps.normalizeSnapshotScrollbackRows(session._snapshotScrollbackRows),
+      snapshotScrollbackFp: composed.snapshotScrollbackFp || undefined,
+      snapshotViewportOffset: Number(composed.snapshotViewportOffset || 0),
+      rendererVersion: _deps.CODEX_HISTORY_EFFECTIVE_RENDERER_VERSION,
+      composedAt: Date.now(),
+      _durableViewportData: durable ? liveViewportData : undefined,
+    };
+    // WI-9 step 2: stash for the next compose call on this session — see the memo-key check
+    // near the top of this function. Only meaningful while the flag is on; harmless dead weight
+    // otherwise (never read when RESUME_REPLAY_DEDUP_ENABLED is false).
+    if (!session._codexComposedRespMemo || typeof session._codexComposedRespMemo !== 'object') {
+      session._codexComposedRespMemo = {};
+    }
+    session._codexComposedRespMemo[composedMemoSlot] = { key: composedMemoKey, payload: composedPayload, createdAt: Date.now() };
+    return { ...resp, ...composedPayload };
+  } catch (e) {
+    _deps.recordSessionDiagnostic(sessionId, 'codex-rollout-history-compose-error', { error: e.message });
+    return resp;
+  }
+}
+
+
+module.exports = {
+  configure,
+  _codexRowCandidateIds,
+  _sessionHasFocusedViewer,
+  requestRowCursorRepublish,
+  _codexRowHistoryBase,
+  _matchingPublishedCodexRollout,
+  _transcriptHistoryProvider,
+  _codexRolloutHistoryActive,
+  _codexHistoryRenderCacheEntry,
+  _codexHistoryRenderNull,
+  _codexHistoryRenderInputForBase,
+  _runCodexHistoryRenderQueue,
+  _requestCodexHistoryRender,
+  _scheduleCodexHistoryRender,
+  _composeCodexRolloutResp,
+};