create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/api/session-messages.js

@@ -0,0 +1,1384 @@
+'use strict';
+
+// Landing-throughput WP-5 shard S3 (design doc §5 D-10 "move-only", §6 "Shard",
+// module seam", §8 WP-5, §9 S-21..S-27): the session-messages API cluster moves out
+// of server.js VERBATIM into this module behind the same configure(deps) seam as
+// lib/api/setup-network.js. It registers NO routes -- the routes stay in
+// lib/api/sessions.js, whose configure() call in server.js now receives
+// sessionMessagesApi.apiSessionMessages / sessionMessagesApi.apiGenerateTitles.
+// Each moved body is identical to server.js's declaration except for the `_deps.`
+// prefix on every identifier that used to resolve to a server.js top-level binding
+// (D-10 rule 1), proven by `node bin/move-only-check.js`.
+//
+// Injected deps, per function:
+//   apiSessionMessages: SESSION_ID_RE, _RESPONSE_CONTRACT_RANGE_METRICS, _RESPONSE_CONTRACT_STATUS, _RESPONSE_HISTORY_TIMING, _buildConversationPageV4OffThread, _buildSessionMessagesPageResponseFromRowsOffThread, _convFailSoftEnabled, _focusConversationRecovery, _kickUiRowMissImport, _loadSessionMessageExclusionsOffThread, _peekSessionMessageExclusionsMemo, _queueConversationCatchUpIfNeeded, _resolveCanonicalRowSources, _sessionHasCodexMessageSource, _sessionMessageRowsHwmOffThread, _sessionMessagesForegroundBreaker, _sessionRowsFreshnessForSource, _standupStatusText, _walleHistoryHttpCorrelationFromUrl, dbModule, getSession
+//   _computePromptMessagesFromFreshestSource: CTM_PROMPT_INDEX_RESOLVE_IN_WORKER, LARGE_SESSION_TAIL_READ_BYTES, _applySessionMessageExclusionsFromRows, _catchUpTranscriptStoreForSession, _computeUserPromptIndexOffThread, _loadSessionMessageExclusionsOffThread, _mergeSessionMessagesWithStreamTail, _messageIndexPromptSourceIds, _perfTracker, _promptRowsFreshness, _promptSummaryFromMessages, _resolveAllSessionFilesOffThread, _sessionHasCodexMessageSource, _sourceWithStreamTail, promptIdentityKey, streamEventToMessage
+//   _apiRecentSessionsLegacy: CTM_RECENT_SERIALIZE_CACHE_ENABLED, HOSTNAME, _RECENT_SERIALIZE_CACHE_TTL_MS, _RECENT_SESSIONS_CACHE_TTL, _apiAgentSessionsFromDbRow, _controlSnapshot, _dedupeRecentSessionsByCanonicalId, _getCachedStarredSessionIds, _inRestoreStorm, _isProviderChildAgentRow, _isProviderChildSessionRow, _loadPersistedRecentSessionsCache, _mainTranscriptReads, _perfTracker, _recentSessionActivityMs, _recentSessionFromDbRow, _recentSessionRowsMapCache, _recentSessionsCache, _recentSessionsCacheTime, _recentSessionsPersistLoaded, _recentSessionsSerializedCache, _recentTranscriptPathsForRows, _scheduleRecentSessionsFullRescan, _scheduleRecentSessionsRebuild, _shouldIncludeDbOnlyRecentSession, _starredIdsCacheAt, dbModule, dbRowAgentSessionIds, maxUserMsgCount, remoteMachineCatalog, sessionEmpty
+//   buildSessionSearchResponse: CTM_SEARCH_SEMANTIC_MIN_LEXICAL_RESULTS, SessionSearchUtils, _analysisFtsSearchRows, _apiAgentSessionsFromDbRow, _buildSearchSessionMap, _canonicalSearchSessionId, _dedupeSearchRows, _emptySessionSearchResponse, _groupMessageResults, _likeSearchMetadata, _loadSearchCorpusSessions, _mergeSearchSources, _primaryApiAgentSession, _scoreTranscriptEventFtsRows, _searchResultTitleFields, _searchSessionFtsCorpusOffThread, _semanticSessionSearch, _sessionCatalogForSearch, _sessionReferenceSearch, _sessionSearchPlan, _skippedSessionSearchSemanticStatus, dbRowAgentSessionIds, maxUserMsgCount, requestConversationImport
+//   apiGenerateTitles: _readSessionCatalogOffThread, callClaudeAsync, cleanFirstMessage, dbModule, isCtmInternalSession, isHumanPromptCandidate, persistTitleStatus, titleGenerationFailureInfo
+//
+// Mutable module state is injected as GETTERS (D-10 rule 2) -- _recentSessionRowsMapCache, _recentSessionsCache, _recentSessionsCacheTime, _recentSessionsPersistLoaded, _recentSessionsSerializedCache, _starredIdsCacheAt.
+// The two the moved bodies also ASSIGN to are injected as getter/setter pairs
+// (_recentSessionsPersistLoaded, _recentSessionsSerializedCache), so the write reaches the same server.js
+// binding instead of a copy frozen at configure() time.
+//
+// apiSessionMessages' four inline `require('./lib/...')` calls are rebased to the
+// module's own static require('../...') (S1 precedent: injecting server.js's
+// `require` is a loader-value transfer the public runtime closure guard refuses).
+// That is the ONE deviation from a pure move-only diff; the checker reports it.
+
+let _deps = null;
+
+function configure(deps = {}) {
+  _deps = deps;
+}
+
+async function apiSessionMessages(req, res, url) {
+  void req;
+  const Protocol = require('../conversation-read-protocol');
+  const Cursor = require('../conversation-page-cursor');
+  const sendJson = (statusCode, body, headers = {}) => {
+    res.writeHead(statusCode, { 'Content-Type': 'application/json', ...headers });
+    res.end(JSON.stringify(body));
+  };
+  const sendBuffer = (statusCode, buffer, headers = {}) => {
+    const timing = buffer?.[_deps._RESPONSE_HISTORY_TIMING];
+    const boundedDuration = (value) => Math.max(0,
+      Math.round((Number(value) || 0) * 10) / 10);
+    const timingHeaders = timing ? {
+      'Server-Timing': [
+        `ctm_history;dur=${boundedDuration(timing.totalMs)}`,
+        `ctm_queue;dur=${boundedDuration(timing.queueMs)}`,
+        `ctm_query;dur=${boundedDuration(timing.queryMs)}`,
+        `ctm_render;dur=${boundedDuration(timing.renderMs)}`,
+      ].join(', '),
+      'X-CTM-History-Total-Ms': String(boundedDuration(timing.totalMs)),
+    } : {};
+    res.writeHead(statusCode, {
+      'Content-Type': 'application/json',
+      ...headers,
+      ...timingHeaders,
+    });
+    res.end(buffer);
+  };
+
+  const sessionId = String(url.searchParams.get('id') || '').trim();
+  const historyHttpCorrelation = _deps._walleHistoryHttpCorrelationFromUrl(url);
+  if (historyHttpCorrelation) {
+    const correlation = historyHttpCorrelation.fields;
+    res.setHeader('X-CTM-History-Request-Id', String(correlation.historyRequestId || 0));
+    res.setHeader('X-CTM-History-Contract-Version', String(correlation.historyContractVersion || 0));
+    res.setHeader('X-CTM-History-Cycle-Id', String(correlation.historyCycleId || 0));
+    res.setHeader('X-CTM-History-Mode', correlation.historyMode);
+    res.setHeader('X-CTM-History-Cursor', encodeURIComponent(correlation.requestedCursor || ''));
+    res.setHeader('X-CTM-History-Requested-Generation', String(correlation.requestedGeneration));
+    res.setHeader(
+      'X-CTM-History-Requested-Ordering-Generation',
+      String(correlation.requestedOrderingGeneration),
+    );
+    // H2 controller incarnation echo (same-realm correlation, never an auth/proof claim):
+    // emitted ONLY when the request carried the marker own. A valid marker echoes its canonical
+    // decimal text; the explicit null sentinel is labeled 'invalid' -- never '0', never empty,
+    // never undefined and never an omission. A truly markerless request adds no header at all.
+    if (Object.prototype.hasOwnProperty.call(correlation, 'historyControllerInstanceId')) {
+      res.setHeader(
+        'X-CTM-History-Controller-Instance-Id',
+        correlation.historyControllerInstanceId === null
+          ? 'invalid'
+          : String(correlation.historyControllerInstanceId),
+      );
+    }
+    if (historyHttpCorrelation.error) {
+      sendJson(400, {
+        ...Protocol.conversationErrorEnvelope({
+          status: 'invalid_request', reason: historyHttpCorrelation.error,
+        }),
+        error: historyHttpCorrelation.error,
+        ...correlation,
+      });
+      return;
+    }
+  }
+  if (!sessionId) {
+    sendJson(400, Protocol.conversationErrorEnvelope({
+      status: 'invalid_request', reason: 'missing_session_id',
+    }));
+    return;
+  }
+  if (!_deps.SESSION_ID_RE.test(sessionId)) {
+    sendJson(400, Protocol.conversationErrorEnvelope({
+      status: 'invalid_request', reason: 'invalid_session_id',
+    }));
+    return;
+  }
+
+  const beforeCursor = String(url.searchParams.get('before') || '').trim();
+  const afterCursor = String(url.searchParams.get('afterCursor') || '').trim();
+  const rangeCursor = String(url.searchParams.get('rangeCursor') || '').trim();
+  const cursorInputs = [beforeCursor, afterCursor, rangeCursor].filter(Boolean);
+  if (cursorInputs.length > 1) {
+    sendJson(400, Protocol.conversationErrorEnvelope({
+      status: 'invalid_cursor', reason: 'multiple_cursor_parameters',
+    }));
+    return;
+  }
+  const cursorToken = cursorInputs[0] || '';
+  const cursorDirection = beforeCursor ? 'older' : (afterCursor ? 'newer' : 'range');
+  const paginationMode = url.searchParams.get('mode') === 'turns' ? 'turns' : 'messages';
+  let offset = Math.max(0, parseInt(url.searchParams.get('offset') || '0', 10) || 0);
+  let exactRange = false;
+  let limit = Math.max(1, Math.min(
+    Cursor.MAX_PAGE_SIZE,
+    parseInt(url.searchParams.get('limit') || '200', 10) || 200,
+  ));
+  const compactConversation = paginationMode === 'turns'
+    && (url.searchParams.get('compact') === 'conversation'
+      || url.searchParams.get('conversationCompact') === '1');
+  const requestedContract = Number(url.searchParams.get('conversationContract'));
+  const conversationContract = requestedContract === 4 ? 4
+    : (requestedContract === 3 && process.env.CTM_CONVERSATION_V3 !== '0' ? 3 : 2);
+
+  // A contract-4 client never receives the contract-2 pending envelope: it gets the typed v4 503.
+  const sendReaderUnavailable = () => {
+    Protocol.logConversationServeRefusal(sessionId, 'canonical_reader_unavailable');
+    if (conversationContract === 4) {
+      sendJson(503, {
+        contractVersion: 4, status: 'error', transient: true, retryAfterMs: 750, reason: 'canonical_reader_unavailable',
+      }, { 'Retry-After': '1', 'Cache-Control': 'no-store' });
+      return;
+    }
+    sendJson(200, Protocol.pendingConversationEnvelope({ reason: 'canonical_reader_unavailable' }), { 'Retry-After': '1' });
+  };
+
+  _deps._focusConversationRecovery(sessionId);
+  const resolution = _deps._resolveCanonicalRowSources(sessionId);
+  const canonicalSessionId = String(resolution?.canonicalSessionId || sessionId).trim();
+  const rowSources = Array.isArray(resolution?.sources) && resolution.sources.length > 0
+    ? resolution.sources
+    : [{ id: canonicalSessionId, reason: 'canonical-fallback', rank: 1 }];
+  // D-3 (WP-2): a foreground viewer must never trade a real page for a fabricated pending
+  // envelope just because an auxiliary read (exclusions) or one row source's HWM failed.
+  // CTM_CONV_FAILSOFT=0 restores today's fail-hard-to-pending semantics byte-for-byte.
+  const failSoftEnabled = _deps._convFailSoftEnabled();
+  let exclusionRows;
+  let exclusionsDegraded = false;
+  try {
+    exclusionRows = await _deps._loadSessionMessageExclusionsOffThread(sessionId);
+  } catch {
+    if (!failSoftEnabled) {
+      sendReaderUnavailable();
+      return;
+    }
+    exclusionRows = _deps._peekSessionMessageExclusionsMemo(sessionId) || [];
+    exclusionsDegraded = true;
+    Protocol.logConversationServeRefusal(sessionId, 'exclusions_degraded');
+  }
+
+  let selectedRowSource = null;
+  let canonicalSourceKnown = false;
+  let hwmAttempted = 0;
+  let hwmFailed = 0;
+  for (const rowSource of rowSources) {
+    const rowSourceId = String(rowSource?.id || '').trim();
+    if (!rowSourceId) continue;
+    hwmAttempted += 1;
+    let rowHwm;
+    try {
+      rowHwm = await _deps._sessionMessageRowsHwmOffThread(rowSourceId, sessionId, {
+        preferRichProjection: true,
+        breaker: _deps._sessionMessagesForegroundBreaker,
+      });
+    } catch {
+      if (!failSoftEnabled) {
+        sendReaderUnavailable();
+        return;
+      }
+      hwmFailed += 1;
+      Protocol.logConversationServeRefusal(sessionId, 'row_hwm_degraded');
+      continue;
+    }
+    const freshness = _deps._sessionRowsFreshnessForSource(sessionId, rowSourceId, {
+      knownRowCount: Number(rowHwm?.rowCount || 0),
+    });
+    const sourceKnown = rowSource?.reason !== 'fallback'
+      || Number(freshness?.expectedSize || 0) > 0
+      || Number(rowHwm?.rowCount || 0) > 0;
+    canonicalSourceKnown = canonicalSourceKnown || sourceKnown;
+    if (!sourceKnown) continue;
+    const isCanonical = rowSource?.isCanonical === true || rowSourceId === canonicalSessionId;
+    if (!isCanonical) continue;
+    if (!(Number(rowHwm?.rowCount) > 0) && freshness?.fresh !== true) continue;
+    selectedRowSource = { rowSource, rowSourceId, rowHwm, freshness };
+    break;
+  }
+  // Only when EVERY attempted source failed does this degrade to the same pending envelope
+  // the old unconditional-return-on-first-failure code produced.
+  if (!selectedRowSource && failSoftEnabled && hwmAttempted > 0 && hwmFailed === hwmAttempted) {
+    sendReaderUnavailable();
+    return;
+  }
+
+  if (conversationContract === 4 && !selectedRowSource) {
+    // Same targeted import the v2/v3 tail triggers, so a source that has no rows yet gets some.
+    _deps._kickUiRowMissImport(sessionId, rowSources, canonicalSourceKnown);
+    sendJson(503, {
+      contractVersion: 4, status: 'error', transient: true, retryAfterMs: 750,
+      reason: 'no_canonical_source',
+    }, { 'Retry-After': '1', 'Cache-Control': 'no-store' });
+    return;
+  }
+
+  if (selectedRowSource) {
+    const { rowSourceId, rowHwm, freshness } = selectedRowSource;
+    if (freshness?.fresh !== true) {
+      const recoverySourceIds = [...new Set(rowSources
+        .map((source) => String(source?.id || '').trim())
+        .filter(Boolean))].slice(0, 16);
+      _deps._queueConversationCatchUpIfNeeded(
+        sessionId,
+        freshness,
+        'canonical-row-page-stale',
+        { sourceIds: recoverySourceIds },
+      );
+    }
+    if (conversationContract === 4) {
+      const param = (name) => String(url.searchParams.get(name) || '').trim() || undefined;
+      let sessionGenerating = false;
+      try {
+        sessionGenerating = ['busy', 'running', 'working'].includes(_deps._standupStatusText(_deps.getSession(sessionId)));
+      } catch {
+        /* expected: an unloaded/unknown session is simply not generating */
+      }
+      const v4Payload = {
+        dbPath: _deps.dbModule.getDbPath(),
+        sessionId: rowSourceId,
+        before: param('before'),
+        after: param('after'),
+        around: param('around'),
+        entries: param('entries'),
+        limitTurns: Number(url.searchParams.get('limitTurns')) || undefined,
+        maxBytes: Number(url.searchParams.get('maxBytes')) || undefined,
+        outline: url.searchParams.get('outline') === '1',
+        resident: param('resident'),
+        sessionGenerating,
+        freshness: { fresh: freshness?.fresh === true },
+      };
+      let result = await _deps._buildConversationPageV4OffThread(v4Payload);
+      if (result?.error?.code === 'turn_index_missing') {
+        // The read-only worker cannot rebuild a missing index: heal on the writer DB, retry once.
+        try {
+          const healStartedAt = Date.now();
+          require('../conversation-turn-index').ensureTurnIndex(_deps.dbModule.getDb(), rowSourceId);
+          console.warn(`[conversation-v4] main-thread turn-index heal session=${rowSourceId} ms=${Date.now() - healStartedAt}`);
+          result = await _deps._buildConversationPageV4OffThread(v4Payload);
+        } catch (healError) {
+          result = { error: { code: 'turn_index_missing', message: String(healError?.message || healError).slice(0, 300) } };
+        }
+      }
+      if (Buffer.isBuffer(result)) {
+        const status = String(result[_deps._RESPONSE_CONTRACT_STATUS] || 'ready');
+        const statusCode = status === 'range-invalidated' ? 409 : (status === 'invalid_request' ? 400 : 200);
+        sendBuffer(statusCode, result, {
+          'Cache-Control': 'no-store',
+          ...(status === 'syncing' ? { 'Retry-After': '1' } : {}),
+        });
+        return;
+      }
+      sendJson(503, {
+        contractVersion: 4, status: 'error', transient: true, retryAfterMs: 750,
+        reason: String(result?.error?.code || 'canonical_reader_unavailable'),
+      }, { 'Retry-After': '1', 'Cache-Control': 'no-store' });
+      return;
+    }
+    if (conversationContract === 3) {
+      const result = await _deps._buildSessionMessagesPageResponseFromRowsOffThread({
+        contractVersion: 3,
+        dbPath: _deps.dbModule.getDbPath(),
+        sessionId,
+        sessionImagesDir: _deps.dbModule.SESSION_IMAGES_DIR,
+        rowSourceId,
+        exclusionRows,
+        filterCodexSyntheticBase: _deps._sessionHasCodexMessageSource(sessionId),
+        mode: paginationMode,
+        direction: cursorDirection,
+        cursor: cursorToken || null,
+        limit,
+        maxSourceRows: 200,
+        compactConversation,
+        syncing: freshness?.fresh !== true,
+        telemetryReason: 'canonical-row-page-v3',
+      });
+      if (Buffer.isBuffer(result)) {
+        const status = String(result[_deps._RESPONSE_CONTRACT_STATUS] || 'error');
+        require('../conversation-range-metrics').recordAuthoritativePage(
+          {
+            ...(result[_deps._RESPONSE_CONTRACT_RANGE_METRICS] || { sessionId: rowSourceId, status }),
+            ...(result[_deps._RESPONSE_HISTORY_TIMING] || {}),
+            requestId: Number(historyHttpCorrelation?.fields?.historyRequestId) || 0,
+          },
+        );
+        const statusCode = status === 'range-invalidated' ? 409 : (status === 'error' ? 503 : 200);
+        const headers = { 'Cache-Control': 'no-store' };
+        if (status === 'upgrading' || status === 'syncing' || status === 'error') headers['Retry-After'] = '1';
+        sendBuffer(statusCode, result, headers);
+        return;
+      }
+      Protocol.logConversationServeRefusal(sessionId, 'canonical_reader_unavailable');
+      sendJson(503, Protocol.pendingConversationEnvelope({
+        reason: 'canonical_reader_unavailable',
+      }), { 'Retry-After': '1' });
+      return;
+    }
+    const generation = Math.max(0, Number(rowHwm?.projectionEpoch) || 0);
+    const identity = Protocol.canonicalTimelineIdentity(canonicalSessionId, generation);
+    if (cursorToken) {
+      const validation = Cursor.validateConversationPageCursor(cursorToken, {
+        sessionId,
+        identity,
+        generation,
+        mode: paginationMode,
+        direction: cursorDirection,
+        // Message counts cannot validate turn coordinates. Exact upper-bound
+        // validation is repeated by the worker against the requested domain.
+        maxOffset: paginationMode === 'messages'
+          ? Math.max(0, Number(rowHwm?.rowCount) || 0)
+          : undefined,
+        allowLegacy: true,
+      });
+      if (!validation.ok) {
+        if (validation.error === 'stale_cursor') {
+          sendJson(409, Protocol.staleCursorEnvelope({
+            identity,
+            generation,
+            reason: validation.field || 'timeline',
+          }));
+        } else {
+          sendJson(400, Protocol.conversationErrorEnvelope({
+            status: 'invalid_cursor', reason: validation.field || 'invalid_cursor',
+          }));
+        }
+        return;
+      }
+      offset = validation.cursor.offset;
+      if (validation.cursor.version === Cursor.CURSOR_VERSION) {
+        limit = validation.cursor.size;
+        exactRange = true;
+      }
+    }
+    const observedAt = new Date().toISOString();
+    const settled = freshness?.fresh === true;
+    const extra = {
+      settled,
+      catchingUp: !settled,
+      cacheFresh: settled,
+      readiness: {
+        reason: settled ? 'complete' : 'catching_up',
+        rowCount: Number(rowHwm.rowCount),
+        lagBytes: Math.max(0, Number(freshness?.lagBytes || 0)),
+      },
+      total_messages: Number(rowHwm.rowCount),
+      rowHwm,
+      rowSourceId,
+      requestedId: sessionId,
+      canonicalSessionId,
+      observedAt,
+      skipStreamTail: true,
+      // D-4-server additive field (WP-2 item 6): the page still served, but an auxiliary
+      // read degraded to last-known-good — never fabricated rows, just a badge hook for
+      // the client (WP-1 D-4). Omitted entirely (not `false`) on the healthy path so the
+      // shape is byte-identical to before this WP for the common case.
+      ...(exclusionsDegraded ? { exclusionsDegraded: true } : {}),
+    };
+    const result = await _deps._buildSessionMessagesPageResponseFromRowsOffThread({
+      dbPath: _deps.dbModule.getDbPath(),
+      sessionId,
+      sessionImagesDir: _deps.dbModule.SESSION_IMAGES_DIR,
+      rowSourceId,
+      streamEvents: [],
+      skipStreamTail: true,
+      // Store selection follows the exact HWM snapshot above. Freshness controls
+      // settled/catching-up truth, not which store owns that snapshot: choosing v2
+      // after a rich HWM was published creates a split 6-row count / 4-row payload.
+      // The worker still requires active Wall-E cutover + v2 coverage + exact count.
+      preferRichProjection: true,
+      expectedRowCount: Number(rowHwm.rowCount),
+      exclusionRows,
+      filterCodexSyntheticBase: _deps._sessionHasCodexMessageSource(sessionId),
+      extra,
+      publicIdentity: identity,
+      cursorContext: {
+        sessionId,
+        canonicalSessionId,
+        identity,
+        generation,
+      },
+      offset,
+      limit,
+      exactRange,
+      allowAuthoritativeEmpty: settled && Number(rowHwm.rowCount) === 0,
+      mode: paginationMode,
+      compactConversation,
+      telemetryReason: 'canonical-row-page',
+    });
+    if (result === 'empty') selectedRowSource = null;
+    if (result?.staleCursor === true) {
+      sendJson(409, Protocol.staleCursorEnvelope({
+        identity,
+        generation,
+        reason: result.field || 'offset',
+        ...Protocol.resumeHistoryObservationFields(result),
+      }));
+      return;
+    }
+    if (Buffer.isBuffer(result)) {
+      sendBuffer(200, result);
+      return;
+    }
+    if (result !== 'empty') {
+      Protocol.logConversationServeRefusal(sessionId, 'canonical_reader_unavailable');
+      sendJson(200, Protocol.pendingConversationEnvelope({
+        reason: 'canonical_reader_unavailable',
+      }), { 'Retry-After': '1' });
+      return;
+    }
+  }
+
+  if (cursorToken) {
+    sendJson(409, Protocol.staleCursorEnvelope({ reason: 'canonical_rows_not_ready' }));
+    return;
+  }
+
+  const sourceIds = _deps._kickUiRowMissImport(sessionId, rowSources, canonicalSourceKnown);
+  const _finalPendingReason = sourceIds.length > 0 ? 'canonical_rows_not_ready' : 'canonical_source_unavailable';
+  Protocol.logConversationServeRefusal(sessionId, _finalPendingReason);
+  sendJson(200, Protocol.pendingConversationEnvelope({
+    source: 'row_import_pending',
+    reason: _finalPendingReason,
+  }), { 'Retry-After': '1' });
+}
+
+async function _computePromptMessagesFromFreshestSource(sessionId) {
+  // The Queue Builder only needs the USER-PROMPT list, not the full conversation
+  // timeline. Building the full conversation projection on every prompt fetch
+  // does a SQLite read + JSON.parse of the entire cached
+  // conversation + transcript-store read + a merge/exclusions pass over the whole
+  // message array and was observed blocking the event loop up to 10s during a
+  // Codex "running" burst. The row-level message index
+  // already holds user prompts as a bounded, indexed query and is kept fresh by
+  // the same importer that powers Conversation/Review. So serve from the index
+  // FIRST + the live stream tail. An empty index degrades to that bounded tail
+  // while a background import converges; it never reconstructs history in-request.
+  // Phase 1: the heavy part (SELECT all user rows + sort + exclusions + sha1-per-prompt
+  // summary) runs on the read-pool worker (read-only connection), off the main loop. The 3
+  // small INPUTS (sourceIds/exclusions/codex-source) are resolved on the worker too by default
+  // (CTM_PROMPT_INDEX_RESOLVE_IN_WORKER) — that cold per-session resolution, stacked across a
+  // restore storm, is the apiSessionPrompts freeze. When the flag is off we resolve them here.
+  let indexSourceIds = _deps.CTM_PROMPT_INDEX_RESOLVE_IN_WORKER ? null : _deps._messageIndexPromptSourceIds(sessionId);
+  let indexExclusionRows = _deps.CTM_PROMPT_INDEX_RESOLVE_IN_WORKER
+    ? null
+    : await _deps._loadSessionMessageExclusionsOffThread(sessionId);
+  const indexResult = await _deps._computeUserPromptIndexOffThread(
+    sessionId,
+    _deps.CTM_PROMPT_INDEX_RESOLVE_IN_WORKER ? null : {
+      sourceIds: indexSourceIds,
+      exclusionRows: indexExclusionRows,
+      filterCodexSynthetic: _deps._sessionHasCodexMessageSource(sessionId),
+    }
+  );
+  // The worker echoes the resolved sourceIds back (main still needs them below for the
+  // stream-tail merge + deferred placeholder). On a breaker short-circuit / fallback the worker
+  // didn't resolve → [] (the deferred list is empty and sourceIds is only a downstream hint there).
+  if (indexSourceIds == null) {
+    indexSourceIds = Array.isArray(indexResult._resolvedSourceIds) ? indexResult._resolvedSourceIds : [];
+  }
+  if (indexExclusionRows == null) {
+    indexExclusionRows = Array.isArray(indexResult._resolvedExclusionRows)
+      ? indexResult._resolvedExclusionRows
+      : [];
+  }
+  const indexMessages = indexResult.messages || [];
+  if (indexResult.capped) {
+    console.warn(`[prompt-index] sid=${String(sessionId).slice(0, 8)} hit the per-session row ceiling (rowCount=${indexResult.rowCount}) — prompt nav shows the most-recent prompts only (defensive cap, not a data loss).`);
+  }
+  const indexRowsFreshness = _deps._promptRowsFreshness(sessionId, indexSourceIds || []);
+
+  if (indexResult._deferred) {
+    // Restore storm: the off-thread prompt-index compute was deferred to avoid a main-thread
+    // freeze and there's nothing cached to serve. Return an empty, explicitly-deferred result
+    // instead of running the heavy timeline projection (multi-MB JSON.parse) on the loop here.
+    // Not cached as final (see _loadPromptMessagesFromFreshestSource) → the next poll re-fetches.
+    return {
+      source: 'deferred',
+      promptMessages: [],
+      responsePrompts: [],
+      promptFingerprint: '',
+      lastPromptPreview: '',
+      userPromptCount: 0,
+      sourceIds: indexSourceIds || [],
+      streamTailAdded: 0,
+      cacheDetails: {},
+      cacheAvailable: false,
+      cacheFresh: false,
+      indexPromptCount: 0,
+      cachePromptCount: 0,
+      _deferred: true,
+    };
+  }
+
+  if (indexMessages.length > 0) {
+    if (indexRowsFreshness.fresh !== true) {
+      // Fire-and-forget freshness nudge: the index is stale, so schedule the background worker
+      // catch-up that makes the NEXT poll fresh. We serve THIS response from the index we already
+      // have — so this nudge must not block the response. Previously it ran inline on the request
+      // path and did synchronous cold fs (`_resolveAllSessionFiles`) + a throwaway
+      // durable transcript-store read whose result we discard, which is the
+      // low-CPU / high-latency half of the apiSessionPrompts freeze (I/O-wait, up to 3.4s). Defer it
+      // to a later tick, off the response's critical path, and probe it so [perf-lag] attributes its
+      // residual cost by name instead of as `apiSessionPrompts (last completed)`.
+      setImmediate(() => {
+        _deps._perfTracker.runSyncProbed('prompts:stale-catchup-schedule', () => {
+          _deps._resolveAllSessionFilesOffThread(sessionId, '', { origin: 'prompt-nudge:stale-index' }).then((filePaths) => {
+            if (filePaths.length > 0) {
+              return _deps._catchUpTranscriptStoreForSession(sessionId, filePaths, {
+                reason: 'prompt-index-source-stale',
+                scheduleOnly: true,
+                maxBytesPerFile: _deps.LARGE_SESSION_TAIL_READ_BYTES,
+              });
+            }
+            return null;
+          }).catch(() => {});
+        }, { context: () => ({ sid: String(sessionId).slice(0, 8) }) });
+      });
+    }
+    // Post-await sync chunk — the perf-tracker tag set by the parent
+    // apiSessionPrompts wrap was cleared at the await above, so without
+    // this probe these N-message merge/filter/summary passes log as
+    // active op:(unknown). Named here so [perf-lag] and the topOps trail
+    // in /api/diagnostics/event-loop can attribute the block.
+    return _deps._perfTracker.runSyncProbed(
+      'prompts:index-merge-respond',
+      () => {
+        // Index hit — the common, hot path. Apply the live stream tail (recent prompts
+        // not yet flushed to the index) without touching the conversation cache.
+        const durableUserTailKeys = new Set(
+          Array.isArray(indexResult.userPromptTailIdentityKeys)
+            ? indexResult.userPromptTailIdentityKeys
+            : [],
+        );
+        const merge = _deps._mergeSessionMessagesWithStreamTail(sessionId, indexMessages, {
+          allowEmptyBase: true,
+          limit: 200,
+          eventFilter: (event) => {
+            const message = _deps.streamEventToMessage(event);
+            if (!message || String(message.role || '').trim() !== 'user') return false;
+            return !durableUserTailKeys.has(_deps.promptIdentityKey(message));
+          },
+        });
+        const mergedTailAdded = Math.max(0, (merge.messages || []).length - indexMessages.length);
+        const sourceIds = Array.from(new Set([
+          ...(indexSourceIds || []),
+          ...((merge.identity && merge.identity.conversationSourceIds) || []),
+        ]));
+        let withTail;
+        let sourceSummary;
+        let responsePrompts;
+        if (mergedTailAdded === 0) {
+          // No live prompt beyond the index — reuse the worker's filtered list + summary as-is
+          // (zero O(N) work on the main thread). This is the hot path for an active session.
+          withTail = indexMessages;
+          sourceSummary = { ...indexResult.summary, sourceIds };
+          responsePrompts = Array.isArray(indexResult.responsePrompts)
+            ? indexResult.responsePrompts
+            : [];
+        } else {
+          // Live prompts pending in the stream tail — fold them in on main (bounded: tail<=200).
+          withTail = (_deps._applySessionMessageExclusionsFromRows(
+            sessionId,
+            merge.messages,
+            indexExclusionRows,
+            { codexSynthetic: true },
+          ) || [])
+            .filter(m => String(m?.role || '').trim() === 'user');
+          sourceSummary = _deps._promptSummaryFromMessages(withTail, sourceIds);
+          responsePrompts = sourceSummary.responsePrompts;
+        }
+        const streamTailAdded = Math.max(0, withTail.length - indexMessages.length);
+        // The read-pool summary already counted filtered user prompts. Reuse it
+        // instead of reducing the full prompt array again on the main loop.
+        const indexPromptCount = Number(indexResult.summary?.userPromptCount || 0);
+        const indexFresh = indexRowsFreshness.fresh === true;
+        return {
+          source: streamTailAdded > 0
+            ? _deps._sourceWithStreamTail(indexFresh ? 'message-index' : 'message-index-stale', streamTailAdded)
+            : (indexFresh ? 'message-index' : 'message-index-stale'),
+          promptMessages: withTail,
+          responsePrompts,
+          promptFingerprint: sourceSummary.promptFingerprint,
+          lastPromptPreview: sourceSummary.lastPromptPreview,
+          userPromptCount: sourceSummary.userPromptCount,
+          sourceIds: sourceSummary.sourceIds,
+          streamTailAdded,
+          cacheDetails: {
+            cacheAvailable: true,
+            cacheFresh: indexFresh,
+            staleSourceIds: indexRowsFreshness.staleSourceIds || [],
+            missingSourceIds: indexRowsFreshness.presentSourceIds?.length ? [] : (indexRowsFreshness.sourceIds || []),
+          },
+          cacheAvailable: true,
+          cacheFresh: indexFresh,
+          freshness: indexRowsFreshness.state || (indexFresh ? 'fresh' : 'catching_up'),
+          indexPromptCount,
+          cachePromptCount: 0,
+        };
+      },
+      {
+        context: () => ({
+          sid: String(sessionId).slice(0, 8),
+          indexMessages: indexMessages.length,
+        }),
+      }
+    );
+  }
+
+  // Index empty: keep the request bounded to the in-memory stream tail and nudge
+  // the importer asynchronously. This is intentionally incomplete for one poll;
+  // synchronous discovery or full-history reconstruction would stall every tab.
+  setImmediate(() => {
+    _deps._resolveAllSessionFilesOffThread(sessionId, '', { origin: 'prompt-nudge:empty-index' }).then((filePaths) => {
+      if (filePaths.length === 0) return null;
+      return _deps._catchUpTranscriptStoreForSession(sessionId, filePaths, {
+        reason: 'prompt-index-empty',
+        scheduleOnly: true,
+        maxBytesPerFile: _deps.LARGE_SESSION_TAIL_READ_BYTES,
+      });
+    }).catch(() => {});
+  });
+  return _deps._perfTracker.runSyncProbed(
+    'prompts:stream-tail-degraded-respond',
+    () => {
+      const merge = _deps._mergeSessionMessagesWithStreamTail(sessionId, [], {
+        allowEmptyBase: true,
+        limit: 200,
+        eventFilter: (event) => String(_deps.streamEventToMessage(event)?.role || '').trim() === 'user',
+      });
+      const tailMessages = _deps._applySessionMessageExclusionsFromRows(
+        sessionId,
+        merge.messages || [],
+        indexExclusionRows,
+        { codexSynthetic: true },
+      ).filter((message) => String(message?.role || '').trim() === 'user');
+      const sourceIds = Array.from(new Set([
+        ...(indexSourceIds || []),
+        ...((merge.identity && merge.identity.conversationSourceIds) || []),
+      ]));
+      const sourceSummary = _deps._promptSummaryFromMessages(tailMessages, sourceIds);
+      const streamTailAdded = tailMessages.length;
+
+      return {
+        source: streamTailAdded > 0 ? 'stream-tail-degraded' : 'deferred',
+        promptMessages: tailMessages,
+        responsePrompts: sourceSummary.responsePrompts,
+        promptFingerprint: sourceSummary.promptFingerprint,
+        lastPromptPreview: sourceSummary.lastPromptPreview,
+        userPromptCount: sourceSummary.userPromptCount,
+        sourceIds: sourceSummary.sourceIds,
+        streamTailAdded,
+        cacheDetails: { cacheAvailable: false, cacheFresh: false, sourceIds },
+        cacheAvailable: false,
+        cacheFresh: false,
+        indexPromptCount: 0,
+        cachePromptCount: 0,
+        _deferred: streamTailAdded === 0,
+      };
+    },
+    {
+      context: () => ({
+        sid: String(sessionId).slice(0, 8),
+        streamTailOnly: true,
+      }),
+    }
+  );
+}
+
+async function _apiRecentSessionsLegacy(req, res, url, options = {}) {
+  const limit = parseInt(url.searchParams.get('limit') || '50', 10);
+  const forceRescan = url.searchParams.get('rescan') === '1';
+  // WP-3 (D-10): main's cheap registry snapshot for the DB-only projection below — the same input
+  // the read-pool op carries, so the legacy and published projections stamp identically. Deliberately
+  // read HERE, never in apiRecentSessions (tests/r4-9-recent-sessions-caps.test.js:144 pins that
+  // handler body to a pure published-buffer lookup).
+  const machineTags = _deps.remoteMachineCatalog.machineTagInputs();
+
+  // First access after (a cold) boot: seed the in-memory cache from the persisted snapshot so this
+  // request serves the last good list immediately instead of an empty one. It's marked stale, so
+  // the SWR path below still kicks an off-thread rebuild to refresh it.
+  if (!_deps._recentSessionsPersistLoaded) {
+    _deps._recentSessionsPersistLoaded = true;
+    if (!_deps._recentSessionsCache) _deps._loadPersistedRecentSessionsCache();
+  }
+
+  const now = Date.now();
+  let recentSessions;
+  let recentSessionsStale = false;
+  if (_deps._recentSessionsCache && (now - _deps._recentSessionsCacheTime) < _deps._RECENT_SESSIONS_CACHE_TTL && !forceRescan) {
+    recentSessions = _deps._recentSessionsCache;
+  } else if (!forceRescan) {
+    recentSessionsStale = true;
+    if (_deps._recentSessionsCache && _deps._recentSessionsCache.length > 0) {
+      // Stale-while-revalidate: hand back the last good value now (no multi-second
+      // getAllSessionsData scan on the request path) and refresh in the background.
+      recentSessions = _deps._recentSessionsCache;
+      _deps._scheduleRecentSessionsRebuild();
+    } else if (_deps._inRestoreStorm()) {
+      // Restore storm + cold cache: do NOT run the getAllSessionsData build on the request
+      // (main) thread — that's the freeze we're eliminating. Serve an empty list now and
+      // kick the off-thread rebuild; the UI re-polls and fills within a couple seconds.
+      recentSessions = [];
+      _deps._scheduleRecentSessionsRebuild();
+    } else {
+      // Cold/empty cache outside the restore-storm window. The synchronous getAllSessionsData
+      // build is ~700ms warm but 30s+ on cold Dropbox; running it on the request path froze the
+      // event loop (measured 31s), which both truncated this response ("No sessions found") AND
+      // tripped the restart watchdog — turning a slow boot into a freeze→restart→cold loop. NEVER
+      // build on the request path: serve whatever we have (stale or empty) and FORCE an off-thread
+      // rebuild (bypassing the breaker, since an empty cache must keep trying). The UI re-polls and
+      // the list fills once the read-pool finishes — off the main thread, no freeze.
+      recentSessions = (Array.isArray(_deps._recentSessionsCache) && _deps._recentSessionsCache.length > 0)
+        ? _deps._recentSessionsCache
+        : [];
+      _deps._scheduleRecentSessionsRebuild({ force: true });
+    }
+  } else {
+    recentSessionsStale = true;
+    recentSessions = Array.isArray(_deps._recentSessionsCache) ? _deps._recentSessionsCache : [];
+    _deps._scheduleRecentSessionsFullRescan(limit);
+  }
+
+  // R4-9: serve the cached serialized body when every stamped input is unchanged (see the cache
+  // definition for the key contract). Placed AFTER the SWR branch above so its rebuild-scheduling
+  // side effects still fire on every poll.
+  const _serializeCacheOn = _deps.CTM_RECENT_SERIALIZE_CACHE_ENABLED && !forceRescan && !options.catalogDegraded;
+  const _serializeKey = _serializeCacheOn
+    ? `${limit}|${_deps._recentSessionsCacheTime}|${_deps._recentSessionRowsMapCache.at}|${_deps._starredIdsCacheAt}|${recentSessionsStale ? 1 : 0}`
+    : '';
+  if (_serializeCacheOn && _deps._recentSessionsSerializedCache
+      && _deps._recentSessionsSerializedCache.key === _serializeKey
+      && (now - _deps._recentSessionsSerializedCache.at) < _deps._RECENT_SERIALIZE_CACHE_TTL_MS) {
+    res.writeHead(200, { 'Content-Type': 'application/json', 'X-Recent-Cache': 'hit' });
+    res.end(_deps._recentSessionsSerializedCache.buffer);
+    return;
+  }
+
+  // Work on a shallow copy so title/mapping enrichment does not mutate the cache.
+  let result = recentSessions.map(s => ({ ...s }));
+
+  // Merge titles, stars, and CTM -> agent mappings from the canonical
+  // ctm_sessions + agent_sessions catalog.
+  let sessionsMap = {};
+  let allSessionRows = [];
+  // Reuse the by-id lookup cached from the SAME getAllSessionsData rows the list build/rebuild
+  // already fetched (avoids a second main-thread catalog query on every poll — the per-poll
+  // double-query that showed as the residual getAllSessionsData main runs during the storm).
+  const _mapFresh = _deps._recentSessionRowsMapCache.map && (now - _deps._recentSessionRowsMapCache.at) < _deps._RECENT_SESSIONS_CACHE_TTL;
+  if (result.length === 0) {
+    // Nothing to enrich (e.g. the storm served an empty list while the off-thread rebuild
+    // runs) — skip the catalog query entirely rather than build a lookup for zero sessions.
+    sessionsMap = _mapFresh ? _deps._recentSessionRowsMapCache.map : {};
+    allSessionRows = _mapFresh ? (_deps._recentSessionRowsMapCache.rows || []) : [];
+  } else if (_mapFresh) {
+    sessionsMap = _deps._recentSessionRowsMapCache.map;
+    allSessionRows = _deps._recentSessionRowsMapCache.rows || [];
+  } else {
+    // Enrichment is optional presentation data. Keep the last published lookup and refresh it
+    // off-thread; a cold exact catalog query here blocked the request loop for up to 31 seconds.
+    sessionsMap = _deps._recentSessionRowsMapCache.map || {};
+    allSessionRows = _deps._recentSessionRowsMapCache.rows || [];
+    _deps._scheduleRecentSessionsRebuild({ force: true });
+  }
+
+  // Filter: remove scanned sessions whose DB row was deleted by ghost prevention.
+  // Small/empty files without a DB entry are ghosts or abandoned stubs.
+  result = result.filter(s => {
+    if (_deps._isProviderChildAgentRow(s)) return false;
+    const dbRow = sessionsMap[s.sessionId];
+    if (_deps._isProviderChildSessionRow(dbRow)) return false;
+    if (dbRow) return true; // Has a DB entry → keep
+    // No DB entry. Check if this file was intentionally cleaned up (not just missing).
+    // A session without a DB row but WITH a JSONL file on disk was cleaned up by ghost prevention.
+    // Keep it only if it's a substantial session (>2KB, has user messages) — small/empty files
+    // without DB entries are ghosts or abandoned stubs.
+    if (s.fileSize > 2048 || s.userMsgCount > 0) return true;
+    return false;
+  });
+
+  const existingSessionIds = new Set(result.map(s => s.sessionId));
+  const dbOnlyRows = allSessionRows.filter((row) => !_deps._isProviderChildSessionRow(row)
+    && !existingSessionIds.has(row.id)
+    && !_deps.dbRowAgentSessionIds(row).some((id) => existingSessionIds.has(id)));
+  const fileStats = await _deps._mainTranscriptReads.statPaths(_deps._recentTranscriptPathsForRows(dbOnlyRows));
+  if (!fileStats || [...fileStats.values()].some((st) => st.state === 'error')) recentSessionsStale = true;
+
+  for (const s of result) {
+    const dbRow = sessionsMap[s.sessionId];
+    if (dbRow && dbRow.title) {
+      s.aiTitle = dbRow.title;
+      s.userRenamed = !!dbRow.user_renamed;
+      if (s.userRenamed) s.title = dbRow.title;
+    }
+    if (dbRow) {
+      s.userMsgCount = _deps.maxUserMsgCount(s.userMsgCount, dbRow.user_msg_count);
+      s.lastMessageAt = dbRow.last_message_at || s.lastMessageAt || '';
+      s.lastActivityAt = s.lastMessageAt || s.lastActivityAt || '';
+      s.titleSource = dbRow.title_source || '';
+      s.titleStatus = dbRow.title_status || '';
+      s.titleStatusReason = dbRow.title_status_reason || '';
+      s.titleUpdatedAt = dbRow.title_updated_at || '';
+    }
+    // Carry starred flag from sessions table
+    if (dbRow) s.starred = !!dbRow.starred;
+    // Carry dual-ID mapping so frontend can resolve in both directions
+    if (dbRow) {
+      const agentSessions = _deps._apiAgentSessionsFromDbRow(dbRow, { useFileStats: false });
+      if (agentSessions.length > 0) s.agentSessions = agentSessions;
+      if (dbRow.agent_session_id && dbRow.agent_session_id !== dbRow.id) {
+        s.agentSessionId = dbRow.agent_session_id;
+      }
+      const agentSessionIds = _deps.dbRowAgentSessionIds(dbRow);
+      if (agentSessionIds.length > 0) s.agentSessionIds = agentSessionIds;
+      if (dbRow.id !== s.sessionId) {
+        // s.sessionId is the JSONL file ID; dbRow.id is the CTM tab ID
+        s.provisionalId = dbRow.id;
+      }
+    }
+    // Surface the multi-tier title fallback (ported from upstream
+    // claude-code-history-viewer — gap-reports/viewer-2026-04-23.md items
+    // I + J). pickDisplayTitle blends ctm_sessions.title (auto or user-
+    // renamed), rename_name from a /rename command, and the file-scan's
+    // firstMessage + the new last_user_content / first_assistant_text
+    // columns so post-compact continuations inherit a useful title.
+    const rowForTitle = {
+      user_renamed: s.userRenamed ? 1 : 0,
+      title: s.aiTitle || s.title || '',
+      rename_name: dbRow ? dbRow.rename_name : '',
+      first_message: s.firstMessage || '',
+      last_user_content: dbRow ? dbRow.last_user_content : '',
+      first_assistant_text: dbRow ? dbRow.first_assistant_text : '',
+    };
+    s.displayTitle = _deps.dbModule.pickDisplayTitle(rowForTitle);
+    s.renameName = (dbRow && dbRow.rename_name) || '';
+    _deps.sessionEmpty.applyRecentSessionEmptyState(s, dbRow);
+  }
+
+  // Include DB-only sessions only when they are backed by canonical session
+  // identity, or explicitly preserved by the user. Auto-title/import caches are
+  // not session identity and must not float into the recent timeline.
+  for (const row of allSessionRows) {
+    if (_deps._isProviderChildSessionRow(row)) continue;
+    if (existingSessionIds.has(row.id)) continue;
+    if (_deps.dbRowAgentSessionIds(row).some(agentId => existingSessionIds.has(agentId))) continue;
+    const session = _deps._recentSessionFromDbRow(row, { fileStats, machineTags });
+    if (!_deps._shouldIncludeDbOnlyRecentSession(row, session, fileStats)) continue;
+    result.push(session);
+    existingSessionIds.add(row.id);
+  }
+
+  result = _deps._dedupeRecentSessionsByCanonicalId(result);
+
+  // Tag all sessions with current hostname
+  for (const s of result) s.hostname = _deps.HOSTNAME;
+
+  result.sort((a, b) => _deps._recentSessionActivityMs(b) - _deps._recentSessionActivityMs(a));
+
+  // Slice to limit, but ensure starred/pinned sessions are always included
+  let sliced = result.slice(0, limit);
+  try {
+    const slicedIds = new Set(sliced.map(s => s.sessionId));
+    // Starred sessions from sessions table
+    const starredRows = _deps._getCachedStarredSessionIds();
+    const starredSet = new Set();
+    for (const r of starredRows) {
+      starredSet.add(r.id);
+      if (r.agent_session_id) starredSet.add(r.agent_session_id);
+    }
+    // Legacy: also check ui_pinned_sessions setting
+    const pinnedIds = _deps._controlSnapshot.getSetting('ui_pinned_sessions', []);
+    if (Array.isArray(pinnedIds)) {
+      for (const pid of pinnedIds) starredSet.add(pid);
+    }
+    for (const s of result) {
+      if (!slicedIds.has(s.sessionId) && (starredSet.has(s.sessionId) || s.starred)) {
+        sliced.push(s);
+        slicedIds.add(s.sessionId);
+      }
+    }
+  } catch (e) { console.error('[recent-sessions] starred filter error:', e.message); }
+
+  // Include the last project where the user intentionally created a session
+  // so the frontend can auto-select it as the default project filter
+  let lastActiveProject = null;
+  try { lastActiveProject = _deps._controlSnapshot.getSetting('last_active_project', null); } catch (e) { console.error('[recent-sessions] getSetting error:', e.message); }
+
+  // R4-9: probed serialize (was an unprobed multi-hundred-KB stringify → `(unknown)` blocks)
+  // + populate the serialized-response cache for the next poll.
+  const _serializedBody = _deps._perfTracker.runSyncProbed('apiRecentSessions:serialize',
+    () => Buffer.from(JSON.stringify({
+      sessions: sliced,
+      lastActiveProject,
+      stale: recentSessionsStale || !!options.catalogDegraded,
+      catalogDegraded: !!options.catalogDegraded,
+    }), 'utf8'),
+    { context: () => ({ sessions: sliced.length }) });
+  if (_serializeCacheOn) {
+    _deps._recentSessionsSerializedCache = { key: _serializeKey, at: Date.now(), buffer: _serializedBody };
+  }
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(_serializedBody);
+}
+
+// WP-0 (S-3/S-4, fleet-session-lists-hub-search-2026-11-01.html §5 D-3, §6.1): the owner contract.
+// `owner` is either absent (today's answer) or `self` (only rows THIS host owns). Anything else is
+// a client bug, never a query — both routes answer 400 { error: 'owner_invalid' }.
+const OWNER_FILTER_VALUES = Object.freeze(['', 'self']);
+
+function normalizeOwnerFilter(value) {
+  const owner = String(value == null ? '' : value).trim();
+  return { ok: OWNER_FILTER_VALUES.includes(owner), owner };
+}
+
+// The owner a catalog row names — the same projection mapRecentSessionRow adds
+// (lib/recent-catalog-query.js, S-1). A row that never went through that projection still answers
+// from the raw columns, so the search path never depends on which of the two produced it.
+function catalogRowOwner(row) {
+  if (!row) return '';
+  if (row.ownerInstanceId !== undefined && row.ownerInstanceId !== null) {
+    return String(row.ownerInstanceId).trim();
+  }
+  return String(row.execution_host_instance_id || row.current_owner_instance_id || '').trim();
+}
+
+/**
+ * WP-0 (S-4): project `ownerInstanceId` onto every search result and, when `ownerLocalIds` is
+ * given, drop the rows it proves foreign — an UNKNOWN owner (`''`) is always kept, so a row that
+ * predates ownership stamping can never vanish from a box's answer.
+ * @param {object[]} rows fused search results
+ * @param {{ownerLocalIds?:Iterable<string>|null, ownerFor?:(row)=>string}} opts
+ */
+function applyOwnerFilterToSearchResults(rows, { ownerLocalIds = null, ownerFor = null } = {}) {
+  const localIds = ownerLocalIds ? new Set(ownerLocalIds) : null;
+  const resolve = typeof ownerFor === 'function' ? ownerFor : () => '';
+  const projected = (Array.isArray(rows) ? rows : []).map((row) => ({
+    ...row,
+    ownerInstanceId: String(resolve(row) || '').trim(),
+  }));
+  return localIds
+    ? projected.filter((row) => !row.ownerInstanceId || localIds.has(row.ownerInstanceId))
+    : projected;
+}
+
+// The ids that count as THIS host's: the accessor the server's recent-catalog call site uses, so
+// both surfaces filter against one truth. `_deps.getInstanceIdentity` wins when the seam injects it
+// (that is how this module gets server state, and it is what lets a unit test stub it).
+function _localOwnerInstanceIds() {
+  const accessor = typeof _deps?.getInstanceIdentity === 'function'
+    ? _deps.getInstanceIdentity
+    : require('../instance-identity-access').getInstanceIdentity;
+  try {
+    const lineage = accessor({ required: false })?.lineage;
+    // Fail OPEN: with no identity yet this box cannot tell its rows from copies, so it serves them
+    // unfiltered rather than as "owns nothing" (which would silently hide every owned hit). The
+    // hub's merge still drops rows owned by its own lineage (fleet-session-lists D-4).
+    return lineage && lineage.size ? new Set(lineage) : null;
+  } catch (e) {
+    // HANDLE: an identity that cannot be derived serves the search unfiltered, never fails it.
+    console.error('[search] owner filter: instance identity unavailable, serving unfiltered:', e?.message || e);
+    return null;
+  }
+}
+
+async function buildSessionSearchResponse(query, options = {}) {
+  const q = String(query || '').trim();
+  const qLookup = _deps.SessionSearchUtils.normalizeSearchValue(q);
+  const limit = Math.min(Math.max(parseInt(options.limit || '50', 10) || 50, 1), 100);
+  if (!qLookup || qLookup.length < 2) return _deps._emptySessionSearchResponse(qLookup, limit);
+
+  const plan = _deps._sessionSearchPlan(qLookup, q);
+  if (plan.terms.length === 0) return _deps._emptySessionSearchResponse(qLookup, limit);
+
+  try {
+    _deps.requestConversationImport('session-search');
+
+    // Search is DB-only on the request path. Provider JSONL files are source
+    // logs consumed by import/watch/repair jobs; this route must not discover or
+    // parse them per keystroke.
+    const ftsCorpusPromise = _deps._searchSessionFtsCorpusOffThread(qLookup, plan, limit);
+    const catalog = await _deps._sessionCatalogForSearch();
+    const ftsCorpus = await ftsCorpusPromise;
+    const allSessionRows = catalog.rows;
+    const _searchSessionsMap = catalog.map;
+
+    // Search uses the durable DB corpus. The request path should not parse the
+    // JSONL filesystem on each keystroke; the background importer keeps these
+    // rows fresh and is woken above when search runs.
+    const { allSessions } = _deps._loadSearchCorpusSessions(
+      allSessionRows, _searchSessionsMap, ftsCorpus.conversationRows,
+    );
+    const sessionMap = _deps._buildSearchSessionMap(allSessions);
+
+    const stripTags = (s) => s.replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim();
+
+    // Build analysis lookup for enriching results
+    const analysisMap = new Map();
+    for (const a of ftsCorpus.analysisRows) {
+      const rowId = a.ctm_session_id || a.session_id;
+      if (!rowId) continue;
+      analysisMap.set(rowId, a);
+      const canonicalId = _deps._canonicalSearchSessionId(rowId, _searchSessionsMap);
+      if (canonicalId && !analysisMap.has(canonicalId)) analysisMap.set(canonicalId, a);
+    }
+
+    // --- Source 1: FTS5 on session_analyses ---
+    const ftsResults = _deps._analysisFtsSearchRows(ftsCorpus.analysisFtsRows);
+    const ftsScored = [];
+    for (let i = 0; i < ftsResults.length; i++) {
+      const r = ftsResults[i];
+      const sourceSessionId = r.session_id;
+      const dbRow = _searchSessionsMap ? _searchSessionsMap[sourceSessionId] : null;
+      const sessionId = _deps._canonicalSearchSessionId(sourceSessionId, _searchSessionsMap);
+      const a = analysisMap.get(sourceSessionId) || analysisMap.get(sessionId);
+      if (!a) continue;
+
+      // Find best highlighted field for display
+      let matchField = '';
+      let matchSnippet = '';
+      const highlights = [
+        ['title', r.h_title], ['summary', r.h_summary], ['topics', r.h_topics],
+        ['category', r.h_category], ['skills_used', r.h_skills],
+        ['first_message', r.h_first_message], ['project', r.h_project],
+      ];
+      for (const [field, hl] of highlights) {
+        if (hl && hl.includes('<mark>')) {
+          matchField = field;
+          // Extract snippet around first highlight
+          const markIdx = hl.indexOf('<mark>');
+          const start = Math.max(0, markIdx - 40);
+          const end = Math.min(hl.length, markIdx + 100);
+          matchSnippet = stripTags((start > 0 ? '...' : '') + hl.slice(start, end) + (end < hl.length ? '...' : ''));
+          break;
+        }
+      }
+      // session_analyses_fts is contentless, so SQLite can identify a matching
+      // row without returning highlight text. Recover field attribution from
+      // the durable analysis row using the exact terms FTS expanded.
+      if (!matchField) {
+        const expandedTerms = (r._fuzzyExpansions || []).flatMap(expansion => expansion?.variants || []);
+        const matchTerms = [...new Set([...(plan.terms || []), ...expandedTerms])]
+          .map(term => String(term || '').toLowerCase())
+          .filter(Boolean);
+        const analysisFields = [
+          ['title', a.title], ['summary', a.summary], ['topics', a.topics],
+          ['category', a.category], ['skills_used', a.skills_used],
+          ['first_message', a.first_message], ['project', a.project],
+        ];
+        for (const [field, value] of analysisFields) {
+          const text = String(value || '');
+          const lower = text.toLowerCase();
+          const term = matchTerms.find(candidate => lower.includes(candidate));
+          if (!term) continue;
+          const index = lower.indexOf(term);
+          const start = Math.max(0, index - 40);
+          const end = Math.min(text.length, index + term.length + 60);
+          matchField = field;
+          matchSnippet = stripTags((start > 0 ? '...' : '') + text.slice(start, end) + (end < text.length ? '...' : ''));
+          break;
+        }
+      }
+
+      const raw = sessionMap.get(sessionId) || sessionMap.get(sourceSessionId);
+      const titleFields = _deps._searchResultTitleFields({ analysis: a, raw, dbRow, stripTags });
+      const agentSessions = dbRow ? _deps._apiAgentSessionsFromDbRow(dbRow, { useFileStats: false }) : (raw?.agentSessions || []);
+      const primaryAgent = dbRow ? _deps._primaryApiAgentSession(dbRow, agentSessions) : null;
+      ftsScored.push({
+        id: sessionId,
+        sessionId,
+        source: 'analysisFts',
+        project: a.project || raw?.project || '',
+        projectEntry: raw?.projectEntry || '',
+        cwd: raw?.cwd || a.project || '',
+        firstMessage: a.first_message || raw?.firstMessage || '',
+        title: titleFields.title,
+        aiTitle: titleFields.aiTitle,
+        displayTitle: titleFields.displayTitle,
+        analysisTitle: titleFields.analysisTitle,
+        userRenamed: titleFields.userRenamed,
+        isEmpty: false,
+        userMsgCount: _deps.maxUserMsgCount(a.message_count, raw?.userMsgCount),
+        modifiedAt: raw?.modifiedAt || a.session_modified_at || '',
+        timestamp: raw?.modifiedAt || a.session_modified_at || '',
+        version: raw?.version || '',
+        gitBranch: raw?.gitBranch || '',
+        fileSize: raw?.fileSize || 0,
+        agent: dbRow?.provider || primaryAgent?.provider || raw?.agent || undefined,
+        provisionalId: dbRow?.id && dbRow.id !== sourceSessionId ? dbRow.id : undefined,
+        agentSessionIds: _deps.dbRowAgentSessionIds(dbRow),
+        agentSessionId: primaryAgent && primaryAgent.agentSessionId !== dbRow?.id ? primaryAgent.agentSessionId : undefined,
+        agentSessions,
+        _matchField: matchField,
+        _matchSnippet: matchSnippet,
+      });
+    }
+
+    // --- Source 3: FTS5 on session_messages ---
+    const msgResults = _deps._dedupeSearchRows(ftsCorpus.messageRows, 'session_id');
+    const msgBySession = _deps._groupMessageResults(msgResults, _searchSessionsMap, plan);
+
+    // --- Source 4: FTS5 on transcript_events ---
+    // This covers provider append-tail rows, including Codex rollout events, from
+    // SQLite. It must not fall back to scanning provider JSONL files.
+    const eventScored = _deps._scoreTranscriptEventFtsRows(ftsCorpus.eventRows, plan, limit, _searchSessionsMap, stripTags);
+
+    // --- Source 6: direct id matches across CTM ids + agent ids ---
+    const idScored = _deps.SessionSearchUtils.buildIdMatchResults(allSessions, qLookup);
+
+    // --- Source 5: exact session-id/URL references in prompts and transcripts ---
+    const referenceScored = _deps._sessionReferenceSearch(
+      q, limit, _searchSessionsMap, sessionMap, stripTags, ftsCorpus.referenceRows,
+    );
+
+    // --- Metadata LIKE search for exact title/path recovery ---
+    const likeScored = _deps._likeSearchMetadata(allSessions, plan.terms, stripTags, q, plan.phrases);
+
+    // --- Source 2: vector search over session analysis rows when cheaper
+    // sources do not already provide enough candidates. Semantic search is
+    // helpful for true "describe the thing I remember" queries, but local
+    // embedding initialization can be expensive; keyword/id/message hits should
+    // stay fast and local.
+    const cheapCandidateCount = ftsScored.length + msgResults.length + eventScored.length + referenceScored.length + idScored.length + likeScored.length;
+    const semanticResult = options.includeSemantic === false || !plan.descriptive || cheapCandidateCount >= _deps.CTM_SEARCH_SEMANTIC_MIN_LEXICAL_RESULTS
+      ? { vectorScored: [], semantic: _deps._skippedSessionSearchSemanticStatus() }
+      : await _deps._semanticSessionSearch(qLookup, limit, analysisMap, sessionMap, _searchSessionsMap, stripTags);
+    const vectorScored = semanticResult.vectorScored;
+
+    // --- Merge all sources using RRF ---
+    // WP-0 (S-4): with owner=self the owner filter runs BEFORE the final slice, so the fusion is
+    // asked for every ranked candidate it has (the sources are limit-bounded upstream) and the
+    // caller's limit is enforced on the FILTERED set — a foreign-owned hit can never starve an
+    // owned one out of the list. Without owner the merge is called exactly as before.
+    const ownerLocalIds = options.owner === 'self' ? _localOwnerInstanceIds() : null;
+    const merged = _deps._mergeSearchSources(
+      ftsScored, vectorScored, msgBySession, eventScored, referenceScored, idScored, likeScored,
+      ownerLocalIds ? Number.MAX_SAFE_INTEGER : limit,
+      analysisMap, sessionMap, stripTags, plan,
+    );
+    const ownerFor = (row) => {
+      const id = String(row?.sessionId || row?.id || '');
+      if (!id || !_searchSessionsMap || !Object.prototype.hasOwnProperty.call(_searchSessionsMap, id)) return '';
+      return catalogRowOwner(_searchSessionsMap[id]);
+    };
+    const projected = applyOwnerFilterToSearchResults(merged, { ownerLocalIds, ownerFor });
+    const results = ownerLocalIds ? projected.slice(0, limit) : projected;
+
+    return {
+      results,
+      total: results.length,
+      mode: 'smart',
+      query: { normalized: qLookup, terms: plan.terms, descriptive: plan.descriptive },
+      sources: {
+        analysisFts: ftsScored.length,
+        messageFts: msgResults.length,
+        transcriptEvents: eventScored.length,
+        references: referenceScored.length,
+        ids: idScored.length,
+        metadata: likeScored.length,
+        codex: 0,
+        semantic: vectorScored.length,
+      },
+      semantic: semanticResult.semantic,
+      degraded: ftsCorpus.degraded || { ftsCorpus: 'ok', message: null },
+      ftsLagRows: Math.max(0, Number(ftsCorpus.ftsLagRows) || 0),
+      ftsLagAlert: Number(ftsCorpus.ftsLagRows || 0)
+        >= (Number(process.env.CTM_FTS_LAG_ALERT_ROWS) || 50_000),
+      limit,
+    };
+  } catch (e) {
+    console.error('[search] Error:', e.message);
+    throw e;
+  }
+}
+
+function apiGenerateTitles(req, res) {
+  let body = '';
+  req.on('data', chunk => { body += chunk; if (body.length > 1024 * 1024) { req.destroy(); return; } });
+  req.on('end', async () => {
+    try {
+      const { sessions } = JSON.parse(body);
+      if (!Array.isArray(sessions) || sessions.length === 0) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'sessions array required' }));
+        return;
+      }
+
+      // Filter to sessions that don't already have titles (or user-renamed), skip CTM-internal sessions
+      // Build title lookup from sessions table (single source of truth)
+      const { rows: _allRows } = await _deps._readSessionCatalogOffThread('generate-titles');
+      const existingTitles = {};
+      for (const r of _allRows) {
+        if (r.title) existingTitles[r.id] = { title: r.title, userRenamed: !!r.user_renamed, titleSource: r.title_source || '' };
+        if (r.agent_session_id && r.title) existingTitles[r.agent_session_id] = { title: r.title, userRenamed: !!r.user_renamed, titleSource: r.title_source || '' };
+      }
+      const flattenExistingTitles = () => {
+        const flatTitles = {};
+        for (const [id, v] of Object.entries(existingTitles)) flatTitles[id] = v.title;
+        return flatTitles;
+      };
+      // AC-3g (session-rename-mirror WP-3, §5 D-1): a row at the 'provider_title' tier (the
+      // coding agent's own session name) is never overwritten by this tier-3 AI-title generator
+      // — same "lower tier never overwrites a higher one" rule as the `userRenamed` check right
+      // beside it. `existing.title` truthy already implies one of these two guards fired for
+      // every populated row (existingTitles is only ever populated when r.title is set), so this
+      // is belt-and-suspenders for the case a future caller narrows that population condition.
+      const candidates = sessions.filter(s => {
+        const existing = existingTitles[s.sessionId];
+        if (existing && (existing.userRenamed || existing.titleSource === 'provider_title' || existing.title)) return false;
+        return !!s.firstMessage;
+      });
+      // D-7 (WP-3): harness/provider boilerplate (<local-command-caveat>, <task-notification>,
+      // "# AGENTS.md instructions for", a compaction summary) is not a human prompt — the same
+      // predicate server/boot.js's background auto-title job gates its candidates on.
+      const needTitles = [];
+      for (const s of candidates) {
+        if (_deps.isCtmInternalSession(s.firstMessage)) {
+          _deps.persistTitleStatus(s.sessionId, 'skipped', 'ctm_internal');
+          continue;
+        }
+        if (!_deps.isHumanPromptCandidate(s.provider, s.firstMessage)) {
+          _deps.persistTitleStatus(s.sessionId, 'skipped', 'not_human_prompt');
+          continue;
+        }
+        needTitles.push(s);
+      }
+
+      if (needTitles.length === 0) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ titles: flattenExistingTitles(), generated: 0 }));
+        return;
+      }
+
+      // Batch up to 20 sessions at a time
+      const batch = needTitles.slice(0, 20);
+
+      // Title generation is a background enhancement served entirely through
+      // Wall-E's routing authority now (WP-2, D-1) — CTM no longer preflight-checks
+      // provider credentials itself; a credential-less setup surfaces as a normal
+      // callClaudeAsync failure below, classified by titleGenerationFailureInfo().
+
+      // Resume/continuation boilerplate is stripped by server/boot.js's cleanFirstMessage, shared
+      // with the background auto-title job (its `This session is being continued…` line is gone:
+      // isHumanPromptCandidate already rejects that compaction row).
+      const prompt = `Generate short, descriptive titles (max 60 chars) for these Claude Code sessions.
+Each session has an ID and the user's first message. Create a title that summarizes what the user was working on.
+
+IMPORTANT: Do NOT prefix titles with "Resume:", "Continue:", "Fix:", or similar action verbs. Just describe the topic/task directly.
+Good: "Shopping cart checkout flow redesign"
+Bad: "Resume: Update checkout page logic"
+
+Sessions:
+${batch.map((s, i) => `${i + 1}. [${s.sessionId}] ${_deps.cleanFirstMessage(s.firstMessage).slice(0, 300)}`).join('\n')}
+
+Return ONLY a JSON array of objects with "id" and "title" fields. No markdown fences.`;
+
+      let result = '';
+      try {
+        result = await _deps.callClaudeAsync(prompt, {
+          modelTier: 'fast',
+          maxTokens: 1200,
+          timeoutMs: 30000,
+          task: 'session-title',
+        });
+      } catch (err) {
+        const failure = _deps.titleGenerationFailureInfo(err);
+        for (const s of batch) {
+          _deps.persistTitleStatus(s.sessionId, 'failed', failure.reason);
+        }
+        console.warn('[titles] Skipping background title generation:', failure.detail || failure.reason);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          titles: flattenExistingTitles(),
+          generated: 0,
+          skipped: failure.reason,
+          titleStatus: {
+            status: 'failed',
+            reason: failure.reason,
+            provider: failure.provider,
+            model: failure.model,
+            userMessage: failure.userMessage,
+          },
+        }));
+        return;
+      }
+      const match = result.match(/\[[\s\S]*\]/);
+      if (match) {
+        let titles = [];
+        try {
+          titles = JSON.parse(match[0]);
+        } catch (err) {
+          for (const s of batch) {
+            _deps.persistTitleStatus(s.sessionId, 'failed', 'provider_response_invalid');
+          }
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({
+            titles: flattenExistingTitles(),
+            generated: 0,
+            skipped: 'provider_response_invalid',
+            titleStatus: {
+              status: 'failed',
+              reason: 'provider_response_invalid',
+              userMessage: 'AI title generation returned an unreadable response. Existing session names are still available.',
+            },
+          }));
+          return;
+        }
+        for (const t of titles) {
+          if (t.id && t.title) {
+            await _deps.dbModule.setSessionTitleNew(t.id, t.title, false, { source: 'ai_title', status: 'generated' });
+            existingTitles[t.id] = { title: t.title, userRenamed: false };
+          }
+        }
+      } else {
+        for (const s of batch) {
+          _deps.persistTitleStatus(s.sessionId, 'failed', 'provider_response_invalid');
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          titles: flattenExistingTitles(),
+          generated: 0,
+          skipped: 'provider_response_invalid',
+          titleStatus: {
+            status: 'failed',
+            reason: 'provider_response_invalid',
+            userMessage: 'AI title generation returned an unreadable response. Existing session names are still available.',
+          },
+        }));
+        return;
+      }
+
+      // Flatten to simple {id: title} for response
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ titles: flattenExistingTitles(), generated: batch.length }));
+    } catch (err) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err.message }));
+    }
+  });
+}
+
+module.exports = {
+  configure,
+  apiSessionMessages,
+  _computePromptMessagesFromFreshestSource,
+  _apiRecentSessionsLegacy,
+  applyOwnerFilterToSearchResults,
+  buildSessionSearchResponse,
+  catalogRowOwner,
+  normalizeOwnerFilter,
+  apiGenerateTitles,
+};