create-walle 0.9.26 → 0.9.28

package/template/claude-task-manager/server.js

@@ -106,6 +106,7 @@ const sessionIntegrity = require('./session-integrity');
 const codexLaunchHealth = require('./lib/codex-launch-health');
 const codexPaths = require('./lib/codex-paths');
 const terminalChoice = require('./lib/terminal-choice');
+const macCaps = require('./lib/macos-capabilities');
 const { auditRelink } = require('./lib/relink-audit');
 const { verifyCandidateForTab } = require('./lib/session-verify');
 const { verifyLineage: verifyLineageForTab } = require('./lib/session-lineage');
@@ -208,6 +209,8 @@ const {
   terminalOutputFlushDelay,
 } = require('./lib/terminal-output-flush');
 const { coalesceSyncFrames } = require('./lib/coalesce-sync-frames');
+const _flushRedrawMarkers = require('./lib/flush-redraw-markers');
+const { createTtlMemo } = require('./lib/ttl-memo');
 const {
   fingerprintFinalText,
   latestCodexFinalTextFromJsonlFile,
@@ -276,6 +279,7 @@ const cursorConversationStore = require('./lib/cursor-conversation-store');
 const SessionSearchUtils = require('./public/js/session-search-utils.js');
 const agentHooksInstaller = require('./lib/agent-hooks-installer');
 const statusHooks = require('./lib/status-hooks');
+const SessionPhase = require('./public/js/session-phase');
 
 function publicAgentHookPlan(plan) {
   if (!plan || typeof plan !== 'object') return plan;
@@ -1246,6 +1250,41 @@ const TURN_SETTLE_SNAPSHOT_OUTPUT_QUIET_FLOOR_MS = 1500;
 // snapshot debounce (which is 15s for claude/codex) so render-divergence is caught
 // within ~1s for every session type, not just gemini.
 const FINGERPRINT_QUIET_FLOOR_MS = 1000;
+// Option A — "keyframe on every boundary" (terminal-rendering-redesign.html). When ON,
+// the server pushes an AUTHORITATIVE headless keyframe (serialized at each viewer's own
+// dims) on every render boundary — activation, resize, and output-quiet — and the client
+// renders it unconditionally instead of running the ~13-path divergence-detect/repair
+// "heal" overlay. The two sources of truth collapse to one (the headless mirror); a stale
+// frame on tab-switch becomes structurally impossible. Default OFF — flag-off is byte-for-
+// byte the legacy behavior, so rollback is instant. Set CTM_KEYFRAME_SYNC=1 to enable.
+const KEYFRAME_SYNC_ENABLED = process.env.CTM_KEYFRAME_SYNC === '1'
+  || String(process.env.CTM_KEYFRAME_SYNC || '').toLowerCase() === 'true';
+// Option A.5 — "streaming keyframe heartbeat". Option A only pushes an authoritative
+// keyframe at activation/resize/output-QUIET boundaries. A long streaming turn never
+// goes quiet, so the live byte stream (absolute-positioned, lossy under coalescing /
+// the output budget / flow-control) can shear mid-turn with NOTHING to correct it until
+// the turn ends (+1s). This pushes a keyframe at a controlled frame rate WHILE output is
+// sustained too — mosh's "fast-forward to truth at a frame rate" property — so streaming
+// divergence is bounded to one interval instead of a whole turn. The client applies one
+// only when its settled frame actually diverges (fp mismatch), so the converged case is a
+// free no-op (no flicker). Requires KEYFRAME_SYNC; default OFF. Set CTM_STREAM_KEYFRAME=1.
+const STREAM_KEYFRAME_ENABLED = process.env.CTM_STREAM_KEYFRAME === '1'
+  || String(process.env.CTM_STREAM_KEYFRAME || '').toLowerCase() === 'true';
+const STREAM_KEYFRAME_INTERVAL_MS = Math.max(120, Number(process.env.CTM_STREAM_KEYFRAME_INTERVAL_MS) || 400);
+// Pure throttle predicate (extracted so it is unit-testable without booting the server).
+function _streamKeyframeThrottleReady(lastAt, now, intervalMs) {
+  return (now - (Number(lastAt) || 0)) >= intervalMs;
+}
+// Called from the output-flush path on each active output chunk. Throttled to one push
+// per STREAM_KEYFRAME_INTERVAL_MS; the downstream _scheduleKeyframePush debounce +
+// in-flight coalesce + marker-gate bound the actual serialize cost.
+function _maybeStreamKeyframe(session) {
+  if (!STREAM_KEYFRAME_ENABLED || !KEYFRAME_SYNC_ENABLED || !session || session._exited) return;
+  const now = Date.now();
+  if (!_streamKeyframeThrottleReady(session._lastStreamKeyframeAt, now, STREAM_KEYFRAME_INTERVAL_MS)) return;
+  session._lastStreamKeyframeAt = now;
+  _scheduleKeyframePush(session, session.id, 'stream-keyframe');
+}
 // NOTE: the proactive turn-settle snapshot PUSH (formerly _scheduleTurnSettleCleanSnapshot,
 // gated by TURN_SETTLE_PROACTIVE_SNAPSHOT) was removed — fully replaced by fingerprint
 // reconcile-on-divergence (see _scheduleFingerprintRefreshAfterOutputQuiet and the client
@@ -1324,6 +1363,10 @@ function _scheduleFingerprintRefreshAfterOutputQuiet(session) {
     session._fingerprintQuietTimer = null;
     if (!_fingerprintRefreshEligible(session)) return;
     _refreshSessionFingerprint(session).catch(() => {});
+    // Option A: on the same output-quiet boundary, push an authoritative keyframe to all
+    // viewers (no-op unless KEYFRAME_SYNC_ENABLED). This is what lets the client retire the
+    // divergence-detect heal paths — it is handed ground truth instead of guessing.
+    _scheduleKeyframePush(session, session.id, 'output-quiet');
   }, FINGERPRINT_QUIET_FLOOR_MS);
   if (session._fingerprintQuietTimer && typeof session._fingerprintQuietTimer.unref === 'function') {
     session._fingerprintQuietTimer.unref();
@@ -9036,6 +9079,13 @@ async function handleApi(req, res, url) {
   if (url.pathname === '/api/services/status' && req.method === 'GET') {
     return apiServicesStatus(req, res);
   }
+  // --- macOS capability (Full Disk Access) endpoints ---
+  if (url.pathname === '/api/capabilities' && req.method === 'GET') {
+    return apiCapabilities(req, res);
+  }
+  if (url.pathname === '/api/capabilities/open-fda' && req.method === 'POST') {
+    return apiCapabilitiesOpenFda(req, res);
+  }
   // --- Approver debug API ---
   if (url.pathname.startsWith('/api/approver/debug/') && req.method === 'GET') {
     const sessionId = url.pathname.split('/').pop();
@@ -10524,6 +10574,45 @@ function _standupSummaryFor(source, ctmSessionId, agentSessionId, identity = nul
   return null;
 }
 
+// Per-session timeline-summary cache. The materialized standup snapshot refreshes every
+// STANDUP_MATERIALIZED_REFRESH_AFTER_MS (1.5s) and re-projects EVERY active session — each projection
+// is a full-conversation merge (conversation-tail-merge dedupText) + summarize. With 16 mostly-idle
+// sessions, that re-derived the whole history of every session ~every 1.5s on the main loop (the
+// CPU-profiler's top `dedupText` freeze frame). Cache the per-session summary keyed on a CHEAP
+// content-version — the durable row count (countSessionMessageRows, an indexed COUNT) plus the live
+// stream summary's latest-activity ms — so an UNCHANGED session returns its cached summary instantly
+// and only sessions with new durable rows or new stream output pay the projection. A generous max-age
+// is a safety net against any version signal a change slips past. Disable with
+// CTM_TIMELINE_SUMMARY_CACHE=0; tune staleness with CTM_TIMELINE_SUMMARY_CACHE_MAX_AGE_MS.
+const _timelineStandupSummaryCache = new Map(); // ctmId → { version, summary, at }
+const _TIMELINE_SUMMARY_CACHE_MAX_AGE_MS = Number(process.env.CTM_TIMELINE_SUMMARY_CACHE_MAX_AGE_MS ?? 300000);
+function _timelineSummaryCacheVersion(ctmId, rawSummary) {
+  let count = 0;
+  try { count = dbModule.countSessionMessageRows(ctmId) || 0; } catch {}
+  let streamMs = 0;
+  try {
+    const fn = require('./lib/session-timeline-summary')._private?._summaryActivityMs;
+    streamMs = rawSummary && typeof fn === 'function' ? (fn(rawSummary) || 0) : 0;
+  } catch {}
+  return `${count}:${streamMs}`;
+}
+async function _cachedTimelineSummaryForStandup(sessionId, identity, rawSummary) {
+  if (process.env.CTM_TIMELINE_SUMMARY_CACHE === '0') return _timelineSummaryForStandup(sessionId, identity);
+  const ctmId = _resolveOwnerCtmSessionId(sessionId) || sessionId;
+  const version = _timelineSummaryCacheVersion(ctmId, rawSummary);
+  const now = Date.now();
+  const hit = _timelineStandupSummaryCache.get(ctmId);
+  if (hit && hit.version === version && (now - hit.at) < _TIMELINE_SUMMARY_CACHE_MAX_AGE_MS) {
+    return hit.summary;
+  }
+  const summary = await _timelineSummaryForStandup(sessionId, identity);
+  // Bound memory: this only ever keys active sessions, but a long-lived process churns through many —
+  // drop the whole map if it grows past a sane ceiling (cheap to repopulate).
+  if (_timelineStandupSummaryCache.size > 512) _timelineStandupSummaryCache.clear();
+  _timelineStandupSummaryCache.set(ctmId, { version, summary, at: now });
+  return summary;
+}
+
 async function _timelineSummaryForStandup(sessionId, identity = null) {
   const resolved = identity || _resolveSessionTimelineIdentity(sessionId);
   let timeline = null;
@@ -11108,13 +11197,9 @@ function _standupWaitingReason(sessionId, session) {
   return String(session?._waitingForInputReason || idleNotifyState.get(sessionId)?.reason || '').toLowerCase();
 }
 
+// Single definition shared with the client + standup classifier via session-phase.js.
 function _standupIsBlockingWaitingReason(reason) {
-  const text = String(reason || '').toLowerCase();
-  return text === 'approval' ||
-    text === 'choice' ||
-    text === 'plan' ||
-    /\bapproval\b/.test(text) ||
-    /\bpermission\b/.test(text);
+  return SessionPhase.isBlockingWaitingReason(reason);
 }
 
 function _standupHasRecentNonResolvingInput(session) {
@@ -11250,6 +11335,95 @@ function _standupLiveStatusWithReasonForSession(session, now = Date.now()) {
   return { status: '', reason: '' };
 }
 
+// --- Session phase projection (redesign — see docs/session-status-redesign.html) ---
+// Single source of truth: map the server's signals to confidence-ranked CONDITIONS
+// and let SessionPhase.derivePhase() decide ONE phase. The server's existing,
+// battle-tested liveStatus verdict is seeded as a HIGH-confidence spine so `phase`
+// can never regress below today's behavior; the raw conditions only ADD value
+// (they can promote a stale idle on newer evidence, never demote a strong signal).
+const PHASE_DECISION_LOG = process.env.CTM_PHASE_LOG === '1';
+
+function _mapLiveStatusToPhase(liveStatus) {
+  switch (String(liveStatus || '')) {
+    case 'running': return 'running';
+    case 'waiting_input': return 'needs_you';
+    case 'resuming': return 'resuming';
+    case 'idle': return 'idle';
+    case 'exited': return 'exited';
+    default: return '';
+  }
+}
+
+function _phaseDecisionLogger(session) {
+  if (!PHASE_DECISION_LOG) return null;
+  return (entry) => {
+    try {
+      console.log('[phase]', session && session.id ? session.id.slice(0, 8) : '-', JSON.stringify(entry));
+    } catch {}
+  };
+}
+
+// Returns { phase, cls, source, confidence, reason } or null for no-PTY/empty.
+function _sessionPhaseProjection(session, now, liveStatus, liveStatusReason) {
+  if (!session) return null;
+  try {
+    const status = typeof liveStatus === 'string'
+      ? liveStatus
+      : _standupLiveStatusForSession(session, now);
+    const reason = liveStatusReason != null
+      ? liveStatusReason
+      : (_standupLiveStatusWithReasonForSession(session, now).reason || '');
+
+    const log = _phaseDecisionLogger(session);
+    const ptyAt = _serverObservedTimeMs(session.lastPtyActivity, now, session, 'lastPtyActivity', 'session-phase');
+
+    const signals = {
+      exited: status === 'exited' || !!session._exited,
+      waitingForInput: _isServerWaitingForInput(session.id, session, now),
+      waitingReason: _standupWaitingReason(session.id, session),
+      activeTurnOpen: _serverSessionHasOpenTurn(session, now),
+      activeTurnStartedAt: _activeTurnObservedMs(session._activeTurnStartedAt, now, session, 'activeTurnStartedAt'),
+      activeTurnLastEvidenceAt: _activeTurnObservedMs(session._activeTurnLastEvidenceAt, now, session, 'activeTurnLastEvidenceAt'),
+      activeTurnSource: session._activeTurnSource || '',
+      lastOutputAt: ptyAt,
+    };
+    const conditions = SessionPhase.buildSessionConditions(signals, { now, baseline: false });
+
+    // Seed the server's considered verdict as the HIGH-confidence spine.
+    const verdictPhase = _mapLiveStatusToPhase(status);
+    if (verdictPhase) {
+      const blocking = verdictPhase === 'needs_you' &&
+        _standupIsBlockingWaitingReason(_standupWaitingReason(session.id, session));
+      conditions.push(SessionPhase.condition(verdictPhase, SessionPhase.CONFIDENCE.HIGH, now,
+        `server:${reason || status}`, blocking ? { blocking: true } : null));
+    }
+    // Weakest floor so a live session with no positive signal reads idle, not unknown.
+    if (_isLiveTerminalSession(session)) {
+      conditions.push(SessionPhase.condition('idle', SessionPhase.CONFIDENCE.LOW, ptyAt, 'default-idle'));
+    }
+    if (!conditions.length) return null;
+
+    const derived = SessionPhase.derivePhase(conditions, { now, log });
+    if (!derived.phase) return null;
+
+    if (PHASE_DECISION_LOG && verdictPhase && derived.phase !== verdictPhase) {
+      console.log('[phase] mismatch', session.id ? session.id.slice(0, 8) : '-',
+        'liveStatus=' + status, 'phase=' + derived.phase, 'reason=' + derived.reason);
+    }
+
+    return {
+      phase: derived.phase,
+      cls: SessionPhase.phaseToCls(derived.phase),
+      source: derived.source,
+      confidence: derived.confidence,
+      reason: derived.reason,
+    };
+  } catch (e) {
+    if (PHASE_DECISION_LOG) console.log('[phase] error', e && e.message);
+    return null;
+  }
+}
+
 async function _buildStandupSnapshot(options = {}) {
   const forceRefresh = options.forceRefresh === true;
   const includeTimeline = options.includeTimeline !== false;
@@ -11275,7 +11449,7 @@ async function _buildStandupSnapshot(options = {}) {
     const timelineIdentity = _resolveSessionTimelineIdentity(payload.id);
     const rawSummary = _standupSummaryFor(source, payload.id, agentSessionId, timelineIdentity);
     const timelineSummary = includeTimeline
-      ? await _timelineSummaryForStandup(payload.id, timelineIdentity)
+      ? await _cachedTimelineSummaryForStandup(payload.id, timelineIdentity, rawSummary)
       : null;
     const rawMergedSummary = mergeTimelineSummaries(rawSummary, timelineSummary);
     let summary = rawMergedSummary ? {
@@ -12915,6 +13089,28 @@ async function _buildSessionMessagesPageResponseOffThread(payload) {
   });
 }
 
+// Stage C: the NON-paginated full read — project (merge + exclusions + image-refs) AND serialize the
+// whole conversation OFF the main loop (the on-main projection over a 3k-16k-msg array was the
+// profiled "reading conversational logs" freeze). Same shared projection module → byte-identical
+// on-main fallback (named apiSessionMessages:serializeFullResponse) on pool failure/degrade.
+async function _buildSessionMessagesFullResponseOffThread(payload) {
+  const onMain = () => {
+    const obj = require('./lib/session-messages-projection').buildFullMessagesResponse(payload);
+    const str = _perfTracker.runSyncProbed('apiSessionMessages:serializeFullResponse',
+      () => JSON.stringify(obj),
+      { context: () => ({ msgs: Array.isArray(obj) ? obj.length : (Array.isArray(obj?.messages) ? obj.messages.length : 0), fallback: 1 }) });
+    return Buffer.from(str, 'utf8');
+  };
+  return _offthreadRead({
+    breaker: _sessionMessagesPageBreaker,
+    op: 'buildSessionMessagesFullResponse',
+    timeoutMs: _SESSION_MESSAGES_READPOOL_TIMEOUT_MS,
+    payload,
+    onSuccess: (res) => (res && Buffer.isBuffer(res.__resultBuffer)) ? res.__resultBuffer : onMain(),
+    onFail: () => onMain(),
+  });
+}
+
 // Wave 3.1: off-thread the durable-tail reconcile's bounded JSONL parse. The cheap gate
 // (resolve the live JSONL path/size + the imported byte HWM) stays on main; only when the
 // importer is lagging (live > imported) do we hit the pool, so the common "caught up" case
@@ -12972,6 +13168,8 @@ async function apiSessionMessages(req, res, url) {
   const offset = paginated ? Math.max(0, parseInt(offsetRaw || '0', 10) || 0) : 0;
   const limit = paginated ? Math.max(1, Math.min(1000, parseInt(limitRaw || '200', 10) || 200)) : 0;
   const paginationMode = url.searchParams.get('mode') === 'turns' ? 'turns' : 'messages';
+  const compactConversation = paginated && paginationMode === 'turns'
+    && (url.searchParams.get('compact') === 'conversation' || url.searchParams.get('conversationCompact') === '1');
   const MAX_SYNC_SIZE = 10 * 1024 * 1024; // 10MB — parse synchronously up to this
   if (!sessionId) {
     res.writeHead(400, { 'Content-Type': 'application/json' });
@@ -12984,8 +13182,72 @@ async function apiSessionMessages(req, res, url) {
     return;
   }
 
+  // Off-thread NON-paginated full read: resolve the small projection inputs on main, then merge +
+  // exclude + image-ref + serialize the WHOLE conversation on the read-pool worker (mirrors
+  // sendPaginatedMessagePage, for the full-array case). Removes the on-main projection that froze
+  // the loop while reading a large conversation. Same shared module → byte-identical on-main
+  // fallback on pool failure. Cacheable with a stream-event signature folded into the key (so a hot
+  // tail rebuilds), exactly like the page path — no main-thread merge needed to decide cacheability.
+  const _sendFullMessagesOffThread = async (baseMessages, extra = {}) => {
+    const skipStreamTail = extra.skipStreamTail === true;
+    let identity = null;
+    let streamEvents = [];
+    if (!skipStreamTail) {
+      identity = _resolveSessionTimelineIdentity(sessionId);
+      streamEvents = collectTimelineStreamEvents(identity, {
+        limit: 200,
+        getRecentEvents: (lookupId, lookupLimit) => _getRecentStreamEventsForTimelineId(lookupId, lookupLimit),
+      });
+    }
+    const _extraForKey = { ...extra };
+    delete _extraForKey.skipStreamTail;
+    // Bare array iff the caller passed no extra — matches sendMessages' `JSON.stringify(visibleMessages)`.
+    const bareArray = Object.keys(_extraForKey).length === 0;
+    const _cacheable = CTM_MSG_RESPONSE_CACHE_ENABLED;
+    let _cacheKey = null;
+    if (_cacheable) {
+      _cacheKey = buildResponseCacheKey({
+        sessionId,
+        sourceVersion: _msgBaseSignature(baseMessages),
+        exclusionsVersion: _msgExclusionsSignature(sessionId),
+        offset, limit,
+        mode: `mfull:${skipStreamTail ? '1' : '0'}:s${_streamEventsSignature(streamEvents)}:${JSON.stringify(_extraForKey)}`,
+      });
+      if (!noCache) {
+        const _hit = _msgResponseCache.get(_cacheKey);
+        if (_hit) {
+          res.writeHead(200, { 'Content-Type': 'application/json', 'X-Msg-Cache': 'hit' });
+          res.end(_hit.buffer);
+          return;
+        }
+      }
+    }
+    const exclusionRows = _loadSessionMessageExclusions(sessionId);
+    const filterCodexSynthetic = _shouldFilterCodexSyntheticMessages(sessionId, baseMessages, {});
+    const imageManifests = _resolveImageManifestsForProjection(sessionId, baseMessages, streamEvents);
+    const buffer = await _buildSessionMessagesFullResponseOffThread({
+      baseMessages, streamEvents, skipStreamTail, exclusionRows, filterCodexSynthetic, imageManifests,
+      extra, publicIdentity: _publicTimelineIdentity(identity), bareArray,
+    });
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    if (_cacheable && _cacheKey) _msgResponseCache.set(_cacheKey, { buffer });
+    res.end(buffer);
+  };
+
+  const compactPageForConversation = (page) => (
+    compactConversation
+      ? require('./lib/session-messages-projection').applyConversationCompactionToPage(page, { compactConversation: true })
+      : page
+  );
+
   const sendMessages = (messages, extra = {}) => {
     const baseMessages = Array.isArray(messages) ? messages : [];
+    // Large non-paginated read → project + serialize OFF the main loop (the conversation-read freeze).
+    // Small reads stay on main (a worker round-trip + array clone isn't worth it); paginated reads
+    // already have their own off-thread page path. CTM_MSG_OFFTHREAD_FULL=0 forces the on-main path.
+    if (!paginated && CTM_MSG_OFFTHREAD_FULL_ENABLED && baseMessages.length >= CTM_MSG_OFFTHREAD_FULL_MIN) {
+      return _sendFullMessagesOffThread(baseMessages, extra);
+    }
     // Compute the stream-tail merge first (own attribution probe) so we can both name
     // it AND gate the serialized-response cache on whether the live tail adds anything.
     const merge = extra.skipStreamTail
@@ -13006,7 +13268,7 @@ async function apiSessionMessages(req, res, url) {
         sourceVersion: _msgBaseSignature(baseMessages),
         exclusionsVersion: _msgExclusionsSignature(sessionId),
         offset, limit,
-        mode: `m:${paginated ? paginationMode : 'full'}:${JSON.stringify(_extraForKey)}`,
+        mode: `m:${paginated ? paginationMode : 'full'}:c${compactConversation ? 1 : 0}:${JSON.stringify(_extraForKey)}`,
       });
       if (!noCache) {
         const _hit = _msgResponseCache.get(_cacheKey);
@@ -13055,7 +13317,7 @@ async function apiSessionMessages(req, res, url) {
     // async source-resolution — i.e. another `(unknown)` candidate. Name it. Phase 2.
     const _payload = _perfTracker.runSyncProbed('apiSessionMessages:serializeResponse', () => {
       if (paginated) {
-        return JSON.stringify({ ..._paginateSessionMessages(visibleMessages, offset, limit, paginationMode), ...finalExtra });
+        return JSON.stringify({ ...compactPageForConversation(_paginateSessionMessages(visibleMessages, offset, limit, paginationMode)), ...finalExtra });
       }
       if (Object.keys(finalExtra).length > 0) {
         return JSON.stringify({ messages: visibleMessages, ...finalExtra });
@@ -13098,7 +13360,7 @@ async function apiSessionMessages(req, res, url) {
         sourceVersion: _msgBaseSignature(baseMessages),
         exclusionsVersion: _msgExclusionsSignature(sessionId),
         offset, limit,
-        mode: `p:${paginationMode}:s${_streamEventsSignature(streamEvents)}:${JSON.stringify(_pageMeta)}:${JSON.stringify(_extraForKey)}`,
+        mode: `p:${paginationMode}:c${compactConversation ? 1 : 0}:s${_streamEventsSignature(streamEvents)}:${JSON.stringify(_pageMeta)}:${JSON.stringify(_extraForKey)}`,
       });
       if (!noCache) {
         const _hit = _msgResponseCache.get(_cacheKey);
@@ -13119,7 +13381,7 @@ async function apiSessionMessages(req, res, url) {
     delete _pageMeta.messages;
     const buffer = await _buildSessionMessagesPageResponseOffThread({
       baseMessages, streamEvents, skipStreamTail, exclusionRows, filterCodexSynthetic, imageManifests,
-      pageMeta: _pageMeta, extra, publicIdentity: _publicTimelineIdentity(identity),
+      pageMeta: _pageMeta, extra, publicIdentity: _publicTimelineIdentity(identity), compactConversation,
     });
     res.writeHead(200, { 'Content-Type': 'application/json' });
     if (_cacheable && _cacheKey) _msgResponseCache.set(_cacheKey, { buffer });
@@ -13135,7 +13397,7 @@ async function apiSessionMessages(req, res, url) {
       res.writeHead(200, { 'Content-Type': 'application/json' });
       const _payload = _perfTracker.runSyncProbed('apiSessionMessages:desktopHistory',
         () => (paginated
-          ? JSON.stringify(_paginateSessionMessages(messages, offset, limit, paginationMode))
+          ? JSON.stringify(compactPageForConversation(_paginateSessionMessages(messages, offset, limit, paginationMode)))
           : JSON.stringify(messages)),
         { context: () => ({ msgs: Array.isArray(messages) ? messages.length : 0, paginated: paginated ? 1 : 0 }) });
       res.end(_payload);
@@ -13177,7 +13439,7 @@ async function apiSessionMessages(req, res, url) {
     if (paginated) {
       res.end(_perfTracker.runSyncProbed('apiSessionMessages:walleHistory',
         () => JSON.stringify({
-          ..._paginateSessionMessages(messages, offset, limit, paginationMode),
+          ...compactPageForConversation(_paginateSessionMessages(messages, offset, limit, paginationMode)),
           source: cachedWalleHistory ? 'walle-conversation-cache' : 'walle-local-history',
           cacheFresh: !!cachedWalleHistory || walleHistory.length > 0,
         }),
@@ -13205,26 +13467,25 @@ async function apiSessionMessages(req, res, url) {
   // ladder and never breaks.
   if (CTM_SESSION_ROWS_ENABLED) {
     try {
-      if (dbModule.sessionContentRowsAvailable(sessionId)) {
-        // noCache used to skip the row store entirely and re-parse the whole JSONL on the main
-        // loop — for a large Codex session that froze the event loop 6–22s, and the Conversation
-        // tab fires nocache=1 on every "fresh" refresh during a running burst (the reported codex
-        // freeze). The row store is the durable source (kept fresh by the importer) and the
-        // offset-0 page / sendMessages both merge the live stream tail, so it is fresh enough; on
-        // noCache we additionally kick an incremental import so the next poll reflects any
-        // just-written external JSONL — without ever blocking the loop on a full parse.
-        if (noCache) { try { requestConversationImport('session-rows-nocache-refresh'); } catch {} }
-        let pageDeferredUnderStorm = false;
+      // A CTM tab can map to one or more provider-native agent ids. The row store is keyed by the
+      // source id that imported the transcript, so check all canonical source ids before falling
+      // through to cache/JSONL. This keeps CTM-id requests on the bounded row path after restart.
+      const rowSourceIds = _sessionMessageRowSourceIds(sessionId);
+      if (noCache && rowSourceIds.length) { try { requestConversationImport('session-rows-nocache-refresh'); } catch {} }
+      let pageDeferredUnderStorm = false;
+      for (const rowSourceId of rowSourceIds) {
+        if (!dbModule.sessionContentRowsAvailable(rowSourceId)) continue;
         if (paginated) {
           // Wave 3: the page fetch (COUNT(*) over ALL rows + candidate-turn scan + bounded
           // SELECT) is the prime apiSessionMessages cold-page block — move it OFF the main loop
           // to the read pool, with an on-main fallback. See _fetchSessionMessagesPageOffThread.
-          let page = await _fetchSessionMessagesPageOffThread(sessionId, { offset, limit, mode: paginationMode }, { deferOnStorm: true });
+          let page = await _fetchSessionMessagesPageOffThread(rowSourceId, { offset, limit, mode: paginationMode }, { deferOnStorm: true });
           if (page === null) {
             // Storm defer (read pool saturated): serve stale via the cache/JSONL ladder below — do NOT
             // fall to the full-array getSessionMessagesArray materialize on main (that's the very freeze
             // we're avoiding). The next poll retries the bounded page off-thread once a worker frees.
             pageDeferredUnderStorm = true;
+            break;
           } else {
             // Newest page only: reconcile against the live JSONL tail so a lagging
             // importer can't drop the turn the model just finished (the durable
@@ -13240,6 +13501,7 @@ async function apiSessionMessages(req, res, url) {
                 source: paginationMode === 'turns' ? 'session-rows-turn-page' : 'session-rows-message-page',
                 cacheFresh: true,
                 skipStreamTail: offset > 0,
+                rowSourceId: rowSourceId === sessionId ? undefined : rowSourceId,
               });
               return;
             }
@@ -13247,10 +13509,13 @@ async function apiSessionMessages(req, res, url) {
         }
         if (!pageDeferredUnderStorm) {
           const rowMessages = _perfTracker.runSyncProbed('apiSessionMessages:materializeRows',
-            () => dbModule.getSessionMessagesArray(sessionId, { fallbackToBlob: false }),
-            { context: () => ({}) });
+            () => dbModule.getSessionMessagesArray(rowSourceId, { fallbackToBlob: false }),
+            { context: () => ({ row_source: rowSourceId === sessionId ? 'requested' : 'mapped' }) });
           if (Array.isArray(rowMessages) && rowMessages.length > 0) {
-            sendMessages(rowMessages, paginated ? { source: 'session-rows' } : {});
+            sendMessages(rowMessages, paginated ? {
+              source: 'session-rows',
+              rowSourceId: rowSourceId === sessionId ? undefined : rowSourceId,
+            } : {});
             return;
           }
         }
@@ -13512,7 +13777,7 @@ async function apiSessionMessages(req, res, url) {
       sourceVersion: _msgFilesSignature(filePaths),
       exclusionsVersion: _msgExclusionsSignature(sessionId),
       offset, limit,
-      mode: `jsonl:${paginated ? paginationMode : 'full'}`,
+      mode: `jsonl:${paginated ? paginationMode : 'full'}:c${compactConversation ? 1 : 0}`,
     });
     if (!noCache) {
       const _hit = _msgResponseCache.get(_jsonlCacheKey);
@@ -13613,7 +13878,7 @@ async function apiSessionMessages(req, res, url) {
     () => JSON.stringify(obj),
     { context: () => ({ msgs: Array.isArray(visibleMessages) ? visibleMessages.length : 0, partial: partialLoad ? 1 : 0 }) });
   if (paginated) {
-    const page = _paginateSessionMessages(visibleMessages, offset, limit, paginationMode);
+    const page = compactPageForConversation(_paginateSessionMessages(visibleMessages, offset, limit, paginationMode));
     res.writeHead(200, { 'Content-Type': 'application/json' });
     if (partialLoad) {
       res.end(_serveJsonl({
@@ -14053,17 +14318,29 @@ const _promptComputeInFlight = new Map(); // sessionId -> Promise<result>
 const PROMPT_PREVIEW_CACHE_TTL_MS = Math.max(0, Number(process.env.CTM_PROMPT_PREVIEW_CACHE_TTL_MS) || 10000);
 const PROMPT_PREVIEW_CACHE_MAX = 200;
 
+// The freshness key runs on EVERY /api/session/prompts poll (before the preview-cache
+// check) and each call is an UNCACHED SQLite probe (getSessionUserPromptFreshness). With
+// many sessions polling concurrently those probes stack into a main-loop block (observed
+// up to 790ms on a dev storm, multi-second on the primary with cold pages — the
+// apiSessionPrompts [perf-lag] freezes). A user-prompt count changes rarely, so collapse
+// repeated identical probes behind a sub-second TTL: a new prompt still busts the preview
+// cache within the TTL (far faster than the 10s preview-cache TTL this key guards). null
+// (DB error) is never cached so a transient failure re-probes on the next poll.
+const PROMPT_FRESHNESS_KEY_TTL_MS = Math.max(0, Number(process.env.CTM_PROMPT_FRESHNESS_KEY_TTL_MS) || 750);
+const _promptFreshnessKeyMemo = createTtlMemo({ ttlMs: PROMPT_FRESHNESS_KEY_TTL_MS, max: 512 });
 function _promptPreviewFreshnessKey(sessionId) {
-  try {
-    const ids = _messageIndexPromptSourceIds(sessionId);
-    // USER-scoped: the prompt list only changes when a user prompt is added. Keying on
-    // user-only freshness means a session streaming assistant output (which grows the
-    // all-message index every chunk) no longer busts the prompt-preview cache, so the
-    // sha1-per-prompt summary isn't recomputed on every poll of an active session.
-    const f = dbModule.getSessionUserPromptFreshness(ids);
-    if (!f) return null; // null => do not trust cache (DB error)
-    return `u${f.maxIndex}:${f.rows}`;
-  } catch { return null; }
+  return _promptFreshnessKeyMemo.get(sessionId, () => {
+    try {
+      const ids = _messageIndexPromptSourceIds(sessionId);
+      // USER-scoped: the prompt list only changes when a user prompt is added. Keying on
+      // user-only freshness means a session streaming assistant output (which grows the
+      // all-message index every chunk) no longer busts the prompt-preview cache, so the
+      // sha1-per-prompt summary isn't recomputed on every poll of an active session.
+      const f = dbModule.getSessionUserPromptFreshness(ids);
+      if (!f) return null; // null => do not trust cache (DB error)
+      return `u${f.maxIndex}:${f.rows}`;
+    } catch { return null; }
+  }, (key) => key != null); // never pin a null "do-not-trust" key for the TTL
 }
 
 // Phase 1: run the prompt-index compute (SELECT + sort + exclusions + sha1 summary) on the
@@ -14936,6 +15213,11 @@ const _sessionMessageExclusionsCache = new Map(); // sessionId -> { at, rows }
 // function of the output and served only when the live stream tail adds nothing
 // (merge.added === 0) — turns a steady-state poll into a Map lookup + res.end().
 const CTM_MSG_RESPONSE_CACHE_ENABLED = process.env.CTM_MSG_RESPONSE_CACHE !== '0';
+// Off-thread the NON-paginated full conversation read (merge + exclusions + image-refs + serialize)
+// once the base is large enough that a worker round-trip + array clone beats blocking the loop.
+// CTM_MSG_OFFTHREAD_FULL=0 disables (force on-main); CTM_MSG_OFFTHREAD_FULL_MIN tunes the threshold.
+const CTM_MSG_OFFTHREAD_FULL_ENABLED = process.env.CTM_MSG_OFFTHREAD_FULL !== '0';
+const CTM_MSG_OFFTHREAD_FULL_MIN = Math.max(1, Number(process.env.CTM_MSG_OFFTHREAD_FULL_MIN) || 800);
 const _msgResponseCache = createResponseCache({
   maxEntries: Math.max(16, Number(process.env.CTM_MSG_RESPONSE_CACHE_MAX) || 256),
 });
@@ -15013,16 +15295,25 @@ function _loadSessionMessageExclusions(sessionId) {
   }
 }
 
+// A session's codex-ness is effectively immutable (set when its agent row is linked), yet
+// this ran an UNCACHED agent_sessions lookup on every prompt cache-miss and every exclusion
+// projection. Cache it over a short TTL: a late-linked codex row is still picked up within
+// the TTL, and _shouldFilterCodexSyntheticMessages ORs this with the live message-provider
+// check, so a brief stale `false` cannot hide real codex filtering.
+const SESSION_CODEX_SOURCE_TTL_MS = Math.max(0, Number(process.env.CTM_SESSION_CODEX_SOURCE_TTL_MS) || 30000);
+const _sessionCodexSourceMemo = createTtlMemo({ ttlMs: SESSION_CODEX_SOURCE_TTL_MS, max: 512 });
 function _sessionHasCodexMessageSource(sessionId) {
   if (!sessionId) return false;
-  try {
-    return _getAgentSessionRowsForAnyId(sessionId).some((row) => {
-      const provider = String(row?.provider || '').trim().toLowerCase();
-      return provider === 'codex' || _isCodexRolloutFilePath(row?.jsonl_path);
-    });
-  } catch {
-    return false;
-  }
+  return _sessionCodexSourceMemo.get(sessionId, () => {
+    try {
+      return _getAgentSessionRowsForAnyId(sessionId).some((row) => {
+        const provider = String(row?.provider || '').trim().toLowerCase();
+        return provider === 'codex' || _isCodexRolloutFilePath(row?.jsonl_path);
+      });
+    } catch {
+      return false;
+    }
+  });
 }
 
 function _messagesCarryCodexProvider(messages) {
@@ -15091,6 +15382,30 @@ function _getAgentSessionRowsForAnyId(sessionId) {
   }
 }
 
+function _sessionMessageRowSourceIds(sessionId) {
+  const ids = [];
+  const seen = new Set();
+  const add = (value) => {
+    const clean = String(value || '').trim();
+    if (!clean || seen.has(clean)) return;
+    seen.add(clean);
+    ids.push(clean);
+  };
+  add(sessionId);
+  try {
+    for (const sourceId of dbModule.getSessionConversationSourceIds(sessionId, { includeCtmFallback: true }) || []) {
+      add(sourceId);
+    }
+  } catch {}
+  try {
+    for (const row of _getAgentSessionRowsForAnyId(sessionId)) {
+      add(row.agent_session_id);
+      add(row.ctm_session_id);
+    }
+  } catch {}
+  return ids;
+}
+
 // Opportunity C: memoize the parsed/sorted cache blob. apiSessionMessages /
 // apiSessionPrompts re-parse the SAME multi-MB messages blob on every UI poll (a
 // 12k-message session = ~3MB JSON.parse + sort = 400-720ms main-loop blocks). The
@@ -18631,7 +18946,7 @@ wss.on('connection', (ws, req) => {
   // browser echoes this in X-CTM-Client-Id when calling PUT /api/settings,
   // and we filter it out of broadcastUiPrefs to prevent self-echo.
   ws.clientId = crypto.randomUUID();
-  try { ws.send(JSON.stringify({ type: 'hello', clientId: ws.clientId, appVersion: getAppVersionInfo() })); } catch {}
+  try { ws.send(JSON.stringify({ type: 'hello', clientId: ws.clientId, appVersion: getAppVersionInfo(), keyframeSync: KEYFRAME_SYNC_ENABLED, streamKeyframe: STREAM_KEYFRAME_ENABLED })); } catch {}
   ws.on('pong', () => { ws.isAlive = true; });
 
   ws.on('message', (raw) => {
@@ -22250,7 +22565,11 @@ function handleCreate(ws, msg) {
       const resumeCwdInfo = getCodexThreadResumeCwdInfo(preConfigResume.sessionId, { fallbackCwd: cwd, expectedCwd });
       _recordCodexResumeCwdMismatch(id, preConfigResume.sessionId, resumeCwdInfo);
       const resumeCwd = resumeCwdInfo.cwd;
-      if (resumeCwd && resumeCwd !== cwd && fs.existsSync(resumeCwd)) {
+      // On cold-boot restore, don't stat a resume cwd that lives on a Dropbox/NFS/external
+      // volume — that's the macOS "network volume" TCC trigger. Trust the stored path; it gets
+      // checked for real when the session actually launches on activation.
+      const resumeCwdDeferStat = !!msg._isRestore && resumeCwd && macCaps.isPathOnNonLocalVolume(resumeCwd);
+      if (resumeCwd && resumeCwd !== cwd && (resumeCwdDeferStat || fs.existsSync(resumeCwd))) {
         console.log(`[codex-resume] using thread cwd for ${String(preConfigResume.sessionId).slice(0,8)}: ${cwd} -> ${resumeCwd}`);
         _codexResumeCwdToHeal = resumeCwd;
         cwd = resumeCwd;
@@ -22287,6 +22606,16 @@ function handleCreate(ws, msg) {
   const createAgentType = detectAgentType(cmd);
   if (createAgentType === 'codex') {
     args = _withCodexResumeCd(args, cwd);
+    // Preflight: Codex reads its config from CODEX_HOME (default ~/.codex) at startup. If that
+    // lives on a File Provider / network volume (e.g. ~/.codex symlinked into Dropbox) and CTM
+    // lacks Full Disk Access, the read fails with EPERM and EVERY Codex session dies with
+    // "Error loading config.toml". Detect it up front and ASK for FDA (banner) instead of
+    // letting it fail silently. Behavior-preserving: we still launch.
+    try {
+      // codexPaths.codexHome() is the canonical resolver (honors $CODEX_HOME, else ~/.codex) —
+      // the SAME path Codex itself reads, so the probe checks exactly what will fail.
+      _preflightAgentPathAccess({ path: path.join(codexPaths.codexHome(), 'config.toml'), provider: 'codex', reason: 'CODEX_HOME config' });
+    } catch { /* preflight is best-effort — never block a launch */ }
     // Opt-in (CTM_CODEX_SANDBOX=1): give CTM-spawned Codex its native sandbox +
     // on-request approval so it auto-runs safe commands contained and prompts less —
     // keeps the Codex TUI; does NOT route the remaining prompts through CTM's classifier
@@ -22994,6 +23323,12 @@ function handleCreate(ws, msg) {
   // everything). Client gets full state via snapshot on next tab switch.
   const OUTPUT_BUDGET_BYTES = 65536; // 64KB per 32ms flush window
   const OUTPUT_BULK_FAST_PATH_BYTES = 256 * 1024;
+  // The redraw classifiers only need the VISIBLE frame (always at the tail of the batch) to
+  // decide "is this an interactive TUI redraw?". During heavy repaint bursts the batch holds
+  // many stacked frames (132KB+ observed) and stripAnsi + the alternation regexes over the WHOLE
+  // batch blocked the loop ~342ms ([freeze-probe] flush:classify-detect) — freezing input in
+  // whatever tab (codex OR claude) is focused. Bound the marker scan to the visible tail.
+  const REDRAW_CLASSIFY_TAIL_BYTES = _flushRedrawMarkers.DEFAULT_TAIL_BYTES;
   let _outputBudgetUsed = 0;
   let _outputBudgetResetTimer = null;
   let _budgetSnapshotPending = false; // suppress raw output until snapshot delivered
@@ -23035,20 +23370,11 @@ function handleCreate(ws, msg) {
     const hasAlternateScreenOrCursorRedraw = raw.includes('\x1b[?2026') || /\x1b\[[0-9;?]*[HJfK]/.test(raw);
     if (!hasAlternateScreenOrCursorRedraw) return false;
 
-    const text = stripAnsi(raw);
-    const hasPromptWithDollarTrigger =
-      /(?:^|\n)\s*[›>]\s*[^\n]*\$/m.test(text) ||
-      /[›>]\s*[^\n\r]{0,240}\$[A-Za-z0-9_.:-]*/.test(text);
-    if (!hasPromptWithDollarTrigger) return false;
-    const hasPickerMarker = /\[Skill\]|Press enter to insert|esc to close|no matches/i.test(text);
-    if (hasPickerMarker) return true;
-
-    // Real Codex hides the picker once an exact $skill token is complete, but
-    // keeps repainting the full composer/status screen while the user types the
-    // next token. Those frames are still interactive input echo and should not
-    // enter output-budget snapshot recovery just because the visible picker
-    // rows are gone.
-    return /\b(?:gpt-[\w.-]+|o\d|claude|sonnet|opus|haiku|deepseek|gemini|qwen|llama|mistral|kimi|moonshot)\b[^\n]*(?:\b(?:x?high|medium|low|fast)\b|[~/]|[-·])/i.test(text);
+    // Detect against the VISIBLE tail only — the picker/composer state Codex is echoing is at
+    // the end of the batch; a marker in an earlier superseded frame isn't on screen. Bounding
+    // the strip+regex here is what removes the multi-hundred-ms classify block on big batches.
+    const text = _flushRedrawMarkers.markerTailText(raw, stripAnsi, REDRAW_CLASSIFY_TAIL_BYTES);
+    return _flushRedrawMarkers.hasCodexSkillRedrawMarkers(text);
   }
 
   function _isCodexNativeRedrawContinuation(batch) {
@@ -23078,8 +23404,8 @@ function handleCreate(ws, msg) {
     // status updates as well as composer input. Treat those as TUI redraws, not
     // bulk command output, or the generic output budget drops the latest frame
     // and forces visible dirty/snapshot repair while Codex is still working.
-    const text = stripAnsi(raw);
-    return /Working|esc to interrupt|Conversation interrupted|Explored|Ran|Read|Search|Use \/skills|\bgpt-[\w.-]+|\b(?:x?high|medium|low)\b.*(?:fast|[~/])/i.test(text);
+    const text = _flushRedrawMarkers.markerTailText(raw, stripAnsi, REDRAW_CLASSIFY_TAIL_BYTES);
+    return _flushRedrawMarkers.hasCodexSyncTuiMarkers(text);
   }
 
   function _isClaudeTuiRedraw(batch) {
@@ -23096,8 +23422,8 @@ function handleCreate(ws, msg) {
       /\x1b\[[0-9;?]*[ACHJKf]/.test(raw);
     if (!hasTuiControl) return false;
 
-    const text = stripAnsi(raw);
-    return /Crunching|esc to interrupt|Esc to cancel|Do you want to|Bash(?:\(| command)?|Read\(|Edit\(|Write\(|Grep\(|Glob\(|TodoWrite|tokens|thought for|ctrl\+o to expand|⎿|Claude Code|Working|Cogitating|Forming|plan mode|accept edits|shift\+tab|for agents|running stop hooks|[❯⏵]/i.test(text);
+    const text = _flushRedrawMarkers.markerTailText(raw, stripAnsi, REDRAW_CLASSIFY_TAIL_BYTES);
+    return _flushRedrawMarkers.hasClaudeTuiMarkers(text);
   }
 
   function _isClaudeTuiRedrawContinuation(batch) {
@@ -24315,6 +24641,10 @@ function handleCreate(ws, msg) {
         suppressedUiRefreshChunk ? 'output-quiet:ui-refresh-suppressed' : 'output-quiet'
       );
       _scheduleFingerprintRefreshAfterOutputQuiet(session);
+      // Option A.5: also push an authoritative keyframe at a controlled frame rate DURING
+      // sustained output (throttled), so a mid-turn byte-stream shear self-corrects within
+      // one interval instead of persisting until the turn quiets.
+      _maybeStreamKeyframe(session);
     }
     if (busyStatusChunk && waitingForInput && !restoreActivitySuppressed && !suppressedInputEchoChunk) {
       const providerId = session?._providerId || _providerIdFromCmd(session?.cmd || '') || 'provider';
@@ -25531,11 +25861,31 @@ function _interactiveSerializePending() {
 function _serveCachedSnapshotOnSerializeTimeout(ws, session, sessionId, cols, rows, restoreSource, clientRestoreSeq) {
   if (!ws || ws.readyState !== 1) return false;
   if (!session) return false;
+  // A REFLOW (unlike a cold attach) targets a terminal that already has a rendered frame
+  // on screen. The bridge below is applied as a forced repaint EXEMPT from the client
+  // seq-behind guard — so bridging a STALE frame over a reflow REVERTS a good render to a
+  // bad one. That is exactly the "reflow fixes it, then it reverts in a second" loop on a
+  // huge, continuously-emitting Codex session whose ~800KB serialize keeps timing out:
+  // each timeout re-paints the dirty cache. For a reflow we therefore refuse to bridge a
+  // STALE cache (dirty, or the interim/wrong-width STEPS 2-4 below) — we leave the client's
+  // current frame untouched (the reflow falls to data:null → keep-frame) and let the
+  // heartbeat / stale-skip retry pull a fresh frame once the worker frees. A cold ATTACH
+  // still bridges (a stale frame beats a 30s blank). Only a CLEAN dims-correct cache (a
+  // genuine good frame, not a revert) is still served on a reflow.
+  const isReflow = restoreSource === 'reflow';
   // STEP 1 (always on): a complete, dimension-correct cached frame — the ideal bridge.
   // cachedSnapshotMatchesDimensions also rejects an interim cache, so this is a full frame.
   // Applied as a forced full repaint (RIS), exempt from the client seq-behind guard; the
   // heartbeat divergence check + settle re-check pull a FRESH frame once the worker frees.
   if (session._cachedSnapshot && cachedSnapshotMatchesDimensions(session, cols, rows)) {
+    if (isReflow && session._cachedSnapshotDirty) {
+      recordSessionDiagnostic(sessionId, 'serialize-timeout-dirty-reflow-skip', {
+        cols: Number(session._cachedSnapshotCols) || 0,
+        rows: Number(session._cachedSnapshotRows) || 0,
+        bytes: String(session._cachedSnapshot || '').length,
+      });
+      return false; // keep the client's current frame; do not revert it to the dirty cache
+    }
     recordSessionDiagnostic(sessionId, 'serialize-timeout-cache-fallback', {
       restoreSource: restoreSource || '',
       cols: Number(session._cachedSnapshotCols) || 0,
@@ -25562,6 +25912,10 @@ function _serveCachedSnapshotOnSerializeTimeout(ws, session, sessionId, cols, ro
   // interim branch paints it readable (seq-guard exempt, never reverted) and waits for the
   // fresh frame; the heartbeat/reconcile then pulls a dims-correct serialize and heals it.
   if (!CTM_SERIALIZE_TIMEOUT_BRIDGE) return false;
+  // For a reflow, an interim/wrong-width bridge would also revert the live frame (it is
+  // seq-guard-exempt too). The client already has content — keep it; only cold restores
+  // need this anti-blank bridge.
+  if (isReflow) return false;
   _ensureScrollbackTailCache(session); // loads the disk tail into _cachedSnapshot if there's no in-memory cache
   if (!session._cachedSnapshot) return false;
   // Never bridge a Codex transcript-pager frame (it would paint the pager over live output).
@@ -26830,6 +27184,88 @@ async function _pushSecondarySnapshots(session, sessionId, reason) {
     }
   }
 }
+// --- Option A: authoritative keyframe push (the missing "every boundary" I-frame) ---
+//
+// Unlike _pushSecondarySnapshots (secondaries only), this re-syncs EVERY viewer of the
+// session — primary included — by serializing the headless mirror at each viewer's own
+// dims and sending it as a 'keyframe' snapshot. It is the server half of Option A: on the
+// output-quiet boundary the client is handed ground truth, so the client no longer has to
+// DETECT drift (the fingerprint/garble/flash-loop heal zoo) — it just renders truth. The
+// client skips the repaint if its viewport already matches the keyframe fp (idempotent
+// push, not a divergence-driven pull). No-op unless KEYFRAME_SYNC_ENABLED.
+const KEYFRAME_PUSH_DEBOUNCE_MS = 120;
+function _scheduleKeyframePush(session, sessionId, reason) {
+  if (!KEYFRAME_SYNC_ENABLED || !session || session._exited) return;
+  if (session._keyframePushTimer) return; // coalesce a burst into one push
+  session._keyframePushTimer = setTimeout(() => {
+    session._keyframePushTimer = null;
+    _pushKeyframeSnapshots(session, sessionId, reason).catch(() => {});
+  }, KEYFRAME_PUSH_DEBOUNCE_MS);
+  if (session._keyframePushTimer && typeof session._keyframePushTimer.unref === 'function') {
+    session._keyframePushTimer.unref();
+  }
+}
+async function _pushKeyframeSnapshots(session, sessionId, reason) {
+  if (!KEYFRAME_SYNC_ENABLED) return;
+  if (!sessions.has(sessionId) || sessions.get(sessionId) !== session) return;
+  if (session._keyframePushInFlight) { session._keyframePushAgain = true; session._keyframePushAgainReason = reason; return; }
+  // Only push when output could have changed since the last keyframe we sent. A purely
+  // idle session that produced no new output needs no re-sync (and the client already
+  // pulled a keyframe on activation). Bounds the serialize cost on giant sessions.
+  const marker = _snapshotOutputMarker(session);
+  if (marker && session._lastKeyframeMarker === marker) return;
+  const arb = _viewerArbitration(session, sessionId);
+  if (!arb.viewers.length) return;
+  const primaryCols = arb.primaryCols || session._ptyCols || 0;
+  const primaryRows = arb.primaryRows || session._ptyRows || 0;
+  // Distinct viewer grids → one serialize per grid, fanned out to its viewers.
+  const byGrid = new Map();
+  for (const v of arb.viewers) {
+    const key = v.cols + 'x' + v.rows;
+    if (!byGrid.has(key)) byGrid.set(key, { cols: v.cols, rows: v.rows, wss: [] });
+    byGrid.get(key).wss.push(v.ws);
+  }
+  const scrollbackRows = normalizeSnapshotScrollbackRows(session._snapshotScrollbackRows);
+  const useRolloutHistory = _codexRolloutHistoryActive(session, sessionId);
+  session._keyframePushInFlight = true;
+  try {
+    if (typeof session._flushHeadlessFeed === 'function') session._flushHeadlessFeed();
+    for (const grid of byGrid.values()) {
+      let resp = await _serializeSessionSnapshotAtDims(sessionId, grid.cols, grid.rows, useRolloutHistory ? 0 : scrollbackRows);
+      if (resp && resp.data && useRolloutHistory) resp = _composeCodexRolloutResp(session, sessionId, resp);
+      if (!sessions.has(sessionId) || sessions.get(sessionId) !== session) return;
+      if (!resp || !resp.data) continue;
+      const payload = JSON.stringify({
+        type: 'snapshot', id: sessionId, data: resp.data,
+        ptyCols: resp.cols, ptyRows: resp.rows, scrollback: resp.scrollback,
+        restoreSource: 'keyframe', restoreReason: reason || 'keyframe', fp: resp.fp,
+        autoStartRestore: true,
+        snapshotMarker: marker || undefined,
+        snapshotCurrentMarker: _snapshotOutputMarker(session),
+      });
+      for (const ws of grid.wss) {
+        if (ws.readyState === 1) { try { ws.send(payload); } catch {} }
+      }
+    }
+    session._lastKeyframeMarker = marker;
+  } finally {
+    // Restore authoritative (primary) dims so the live feed + heartbeat resume at the
+    // primary grid (mirrors _pushSecondarySnapshots).
+    if (primaryCols > 0 && primaryRows > 0) {
+      try { headlessWorker.postMessage({ type: 'resize', sessionId, cols: primaryCols, rows: primaryRows }); } catch {}
+    }
+    session._keyframePushInFlight = false;
+    if (session._keyframePushAgain) {
+      session._keyframePushAgain = false;
+      // Preserve a stream-keyframe reason across the coalesce so the client still applies it
+      // via the mid-stream path (a generic 'coalesced-again' would hit the late-snapshot gates).
+      const againReason = session._keyframePushAgainReason === 'stream-keyframe' ? 'stream-keyframe' : 'coalesced-again';
+      session._keyframePushAgainReason = null;
+      _scheduleKeyframePush(session, sessionId, againReason);
+    }
+  }
+}
+
 // Tell a viewer its role so the client knows whether to consume the raw stream
 // (primary) or render from pushed snapshots (secondary). Idempotent per-ws.
 function _notifyViewerRole(ws, sessionId, role) {
@@ -29569,6 +30005,17 @@ function _sessionPayload(s, options = {}) {
     lastPtyActivity,
     liveStatus,
     liveStatusAt: liveStatus ? now : null,
+    ...(() => {
+      const ph = _sessionPhaseProjection(s, now, liveStatus, null);
+      return ph ? {
+        phase: ph.phase,
+        phaseCls: ph.cls,
+        phaseSource: ph.source,
+        phaseConfidence: ph.confidence,
+        phaseReason: ph.reason,
+        phaseAt: now,
+      } : {};
+    })(),
     activeTurnOpen,
     active_turn_open: activeTurnOpen,
     activeTurnStartedAt: activeTurnStartedAt || null,
@@ -30190,6 +30637,7 @@ setInterval(() => {
     const activeTurnStartedAt = _activeTurnObservedMs(s._activeTurnStartedAt, now, s, 'activeTurnStartedAt');
     const activeTurnLastEvidenceAt = _activeTurnObservedMs(s._activeTurnLastEvidenceAt, now, s, 'activeTurnLastEvidenceAt');
     const restoreInterrupted = _isRestoreInterruptedSession(s);
+    const phaseProjection = _sessionPhaseProjection(s, now, liveStatus, liveStatusReason);
     active.push({
       id,
       ts: ptyActivity || lastActivity || createdAt || null,
@@ -30198,6 +30646,11 @@ setInterval(() => {
       status: liveStatus,
       statusReason: liveStatusReason,
       status_reason: liveStatusReason,
+      phase: phaseProjection ? phaseProjection.phase : undefined,
+      phaseCls: phaseProjection ? phaseProjection.cls : undefined,
+      phaseSource: phaseProjection ? phaseProjection.source : undefined,
+      phaseConfidence: phaseProjection ? phaseProjection.confidence : undefined,
+      phaseReason: phaseProjection ? phaseProjection.reason : undefined,
       activeTurnOpen,
       active_turn_open: activeTurnOpen,
       activeTurnStartedAt: activeTurnStartedAt || null,
@@ -30726,6 +31179,120 @@ async function apiServicesStatus(req, res) {
   }));
 }
 
+// --- macOS Full Disk Access capability ---
+// Why: many sessions live under ~/Library/CloudStorage/Dropbox (a File Provider = "network
+// volume" to macOS) or NFS mounts. Touching those re-fires the "Coding Task Manager would like
+// to access files on a network volume" TCC prompt on every restart. FDA is a SUPERSET of the
+// network-volume / app-data / removable services, so one FDA grant (persisting under the stable
+// Dev-ID identity) ends all of them. We only NAG when FDA is missing AND there's actually a
+// network/cloud-backed session — and we can only detect + guide, since Apple forbids granting
+// FDA programmatically.
+let _capabilitiesCache = null;
+const CAPABILITIES_CACHE_TTL_MS = 30000;
+
+// Recently-observed read-access denials (EPERM/EACCES) on a file an agent NEEDS to launch —
+// e.g. a Codex CODEX_HOME/config.toml that lives on Dropbox. Recording one makes the FDA
+// capability banner fire reliably (and name the cause) instead of letting the session fail
+// silently. Keyed by path; pruned by TTL so the banner self-clears once access is restored.
+const _accessDenials = new Map(); // path -> { path, provider, reason, code, at }
+const ACCESS_DENIAL_TTL_MS = 10 * 60 * 1000;
+
+function _recordAccessDenial({ path: p, provider, reason, code }) {
+  if (!p) return;
+  _accessDenials.set(p, { path: p, provider: provider || '', reason: reason || '', code: code || 'EPERM', at: Date.now() });
+  _capabilitiesCache = null; // surface it on the next capabilities poll
+}
+
+function _recentAccessDenials(now = Date.now()) {
+  const out = [];
+  for (const [p, d] of _accessDenials) {
+    if (now - d.at > ACCESS_DENIAL_TTL_MS) { _accessDenials.delete(p); continue; }
+    out.push(d);
+  }
+  return out;
+}
+
+// Provider-agnostic preflight: before spawning an agent that reads a config/home outside the
+// cwd, confirm we can actually read it. On a denial, LOG it and record it (so the user is
+// ASKED for Full Disk Access) rather than letting the agent crash-loop on an unreadable file.
+// Never blocks the launch — the agent still spawns; the banner explains why it may fail.
+function _preflightAgentPathAccess({ path: p, provider, reason }) {
+  try {
+    const code = macCaps.probePathReadDenied(p);
+    if (!code) return false;
+    console.warn(
+      `[access-preflight] ${provider || 'agent'} cannot read ${p} (${code}). ` +
+      'It is likely on a File Provider / network volume (Dropbox/iCloud/NFS) and CTM lacks ' +
+      'Full Disk Access — surfacing the FDA banner so it can be granted instead of failing silently.'
+    );
+    _recordAccessDenial({ path: p, provider, reason, code });
+    return true;
+  } catch { return false; }
+}
+
+function _countNonLocalVolumeSessions() {
+  try {
+    const tasks = dbModule.listStartupTasks() || [];
+    let n = 0;
+    for (const t of tasks) {
+      if (!t || (t.status && t.status === 'exited')) continue;
+      if ((t.cwd && macCaps.isPathOnNonLocalVolume(t.cwd)) ||
+          (t.worktree_path && macCaps.isPathOnNonLocalVolume(t.worktree_path))) n++;
+    }
+    return n;
+  } catch { return 0; }
+}
+
+function _computeCapabilities() {
+  const platform = process.platform;
+  const fdaGranted = macCaps.fullDiskAccessGranted();       // true | false | null (undeterminable)
+  const networkSessionCount = _countNonLocalVolumeSessions();
+  const accessDenials = _recentAccessDenials();
+  const guidance = macCaps.fdaGuidance();
+  // Nag when we are SURE FDA is missing AND there's a concrete reason: either a network/cloud
+  // session (the cwd heuristic) OR an OBSERVED read denial on an agent's config/home (the
+  // authoritative probe — catches the Codex-on-Dropbox case the cwd heuristic misses).
+  const needsAttention = platform === 'darwin' && fdaGranted === false
+    && (networkSessionCount > 0 || accessDenials.length > 0);
+  return {
+    platform,
+    fdaGranted,
+    needsAttention,
+    networkSessionCount,
+    accessDenials: accessDenials.map((d) => ({ path: d.path, provider: d.provider, code: d.code })),
+    bundlePath: guidance.bundlePath,
+    settingsUrl: guidance.settingsUrl,
+    hint: guidance.hint,
+  };
+}
+
+function apiCapabilities(req, res) {
+  const now = Date.now();
+  if (!_capabilitiesCache || now - _capabilitiesCache.ts > CAPABILITIES_CACHE_TTL_MS) {
+    _capabilitiesCache = { ts: now, payload: _computeCapabilities() };
+  }
+  return sendJsonResponse(res, 200, _capabilitiesCache.payload);
+}
+
+function apiCapabilitiesOpenFda(req, res) {
+  if (process.platform !== 'darwin') {
+    return sendJsonResponse(res, 400, { ok: false, error: 'macOS only' });
+  }
+  const g = macCaps.fdaGuidance();
+  // CTM_FDA_OPEN_STUB lets /ctm-dev point this at /usr/bin/true so tests can exercise the
+  // endpoint without actually launching System Settings.
+  const opener = process.env.CTM_FDA_OPEN_STUB || 'open';
+  try {
+    execFile(opener, [g.settingsUrl], () => {});           // jump to Full Disk Access pane
+    execFile(opener, ['-R', g.bundlePath], () => {});      // reveal the bundle so it can be dragged in
+    console.log(`[capabilities] open-fda -> ${opener} ${g.settingsUrl} ; reveal ${g.bundlePath}`);
+  } catch (e) {
+    return sendJsonResponse(res, 500, { ok: false, error: e.message });
+  }
+  _capabilitiesCache = null; // force a fresh probe next poll so the banner clears once granted
+  return sendJsonResponse(res, 200, { ok: true, settingsUrl: g.settingsUrl, bundlePath: g.bundlePath, hint: g.hint });
+}
+
 // --- Worktree API Handlers ---
 const gitUtilsWorktree = require('./git-utils');
 const branchInventory = require('./lib/branch-inventory');
@@ -32312,7 +32879,15 @@ function _startupTaskRestoreCwd(task) {
       identity: _sessionWorkspaceIdentity({ id: task.session_id }),
       worktrees: [],
     });
-    if (binding?.worktreePath && fs.existsSync(binding.worktreePath)) return binding.worktreePath;
+    // At cold boot NO session is active yet (this is a deferred restore — the tab isn't open).
+    // Statting a worktree on a Dropbox/NFS/external volume here is what fires the macOS
+    // "network volume" TCC prompt every restart. Skip the existsSync for non-local paths and
+    // trust the stored path; the existence check happens later when the user actually opens
+    // the tab (an intentional access that persists with one Allow / Full Disk Access).
+    if (binding?.worktreePath) {
+      if (macCaps.isPathOnNonLocalVolume(binding.worktreePath)) return binding.worktreePath;
+      if (fs.existsSync(binding.worktreePath)) return binding.worktreePath;
+    }
   } catch (e) {
     console.error('[restore] workspace binding cwd resolution error:', e.message);
   }