create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/api/diagnostics.js

@@ -8,12 +8,64 @@
 // legitimately reaches deep into server.js internals (perf tracker, main-DB
 // census, event-loop lag state, etc.) — the handler body stays put, only the
 // route registration/dispatch wiring moves here.
+//
+// Landing-throughput WP-5 shard S4 (design doc §5 D-10 "move-only", §6 "Shard
+// module seam", §8 WP-5, §9 S-21..S-27): two more handlers move out of server.js
+// VERBATIM -- apiDiagnosticsClientHealth (POST /api/diagnostics/client-health)
+// and apiDiagnosticsPerfSummary (GET /api/diagnostics/perf-summary). Each 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`. Their route-table entries now call the
+// module-local declarations directly (setup.js's apiSetupTestKey precedent) rather
+// than a configured handler. Injected deps, per function:
+//   apiDiagnosticsClientHealth: RESUME_CLIENT_BEACON_METRICS, _clientHealthReports,
+//     _ctmDbWorker, _ctmReadPool, _ctmWorktreeWorker, _eventLoopIncidents,
+//     _mainloopDiagLogger, _providerIdFromCmd, _recentClientHealthIncidents,
+//     _recentClientHealthLifecycleEvents, _resumeClientMetricRollup,
+//     _stateSyncClientLedger, _typingInteractionTelemetryEnabled,
+//     correlateClientHealthIncident, firstMissingStateSyncBoundary,
+//     formatInputPerformanceHeadline, readJsonRequestBody, recordSessionDiagnostic,
+//     routeKeyboardIncidentToMainloopDiag, sanitizeClientHealthEnvelope,
+//     sanitizeClientHealthLifecycleEnvelope, sanitizeClientHealthMemorySample,
+//     sanitizeProcessLanes, sanitizeResumeClientMetric, sendJsonResponse, sessions,
+//     summarizePerformanceEvidence, telemetry
+//   apiDiagnosticsPerfSummary: CTM_BROWSER_QOS_V2_ENABLED,
+//     CTM_STREAM_STATUS_PATCH_V2_ENABLED, _controlSnapshot,
+//     _conversationUpdateOutboxBackoff, _ctmDbWorker, _ctmReadPool,
+//     _degradedOperations, _desktopIndex, _eventLoopIncidents,
+//     _exitedSnapshotBudget, _heartbeatDirtyQueue, _historyBreakerSnapshot,
+//     _historyWindowBudget, _loadPressure, _mainDbCensus, _msgResponseCache,
+//     _perfTracker, _readPerfCertificationLedger, _recentCatalogBuildInFlight,
+//     _recentCatalogGeneration, _recentCatalogMetrics, _recentCatalogPublished,
+//     _reclaimRecorder, _runtimeEventBuffer, _sessionResourceSampler,
+//     _stateSyncClientLedger, _stateSyncUnknownSubscriptionRejected, _syncIoCensus,
+//     _terminalSnapshotBudget, _terminalTailState, _transcriptRoots, _trimCadence,
+//     _typingInteractionTelemetryEnabled, _typingInteractionTraces,
+//     _visibleRevisionWatchdogEnabled, _walCheckpointMetrics, buildMemoryLedger,
+//     buildPerfSummary, dbModule, errorSink, fetchMcpGatewayLedgerStatus,
+//     getBackgroundLlmRouteStats, getBroadcastReasonStats, getMainThreadWriteEscapeStats, getWorkerLoopLag,
+//     headlessWorker, sessionDiagnostics, sessionHostManager
+// Eight of those are MUTABLE server.js bindings, so server.js injects them as
+// getters (D-10 rule 2), never copied at configure() time: _ctmDbWorker,
+// _ctmReadPool, _ctmWorktreeWorker, _recentCatalogBuildInFlight,
+// _recentCatalogGeneration, _recentCatalogPublished,
+// _stateSyncUnknownSubscriptionRejected, _transcriptRoots. Everything else
+// (functions, const objects never reassigned) is passed by value. `configure`
+// therefore keeps the caller's options object by reference instead of
+// destructuring it -- destructuring would invoke each getter once and freeze a
+// null snapshot of the worker clients (session-messages.js's seam is the
+// precedent).
 
 
 const { registerApiRoutes } = require('../api-router');
 const { buildRestartReceipts, readRestartLedgerEntries } = require('../restart-ledger');
 const { causalTraceDiagnostics } = require('../../../shared/causal-trace');
 const { readContextBudgetRecord } = require('../context-budget-record');
+// WP-3 (box-idle-sleep-remote-typing-freezes-2026-11-01.html §8 WP-3): the frame-receipt exit
+// counters live in lib/ws/state-sync.js and are read through its own getter -- this route takes a
+// direct module dependency, never a server.js one (the counters are module-level, so the numbers are
+// process-lifetime regardless of which server instance reads them).
+const { getFrameReceiptExitCounts } = require('../ws/state-sync');
 const os = require('os');
 
 // WP-0b (attributable restarts, round-2 R1 residual): unlike every other handler in this
@@ -63,6 +115,27 @@ async function apiContextBudget(req, res, url) {
   }
 }
 
+// WP-3 (box-idle-sleep-remote-typing-freezes-2026-11-01.html §5 D-7, §6 WP-3, §8 WP-3, §11 A-5):
+// read-only readout of lib/ws/state-sync.js's process-lifetime frame-receipt exit counters. Like
+// apiDiagnosticsRestarts/apiContextBudget above, it owns its FULL body here -- it needs no server.js
+// internals, only the state-sync module's getter, so there is nothing to gain from the usual
+// dispatch-only split. `since` is process start in ms (the counters are module-level and the module
+// loads at boot), so a reader can age the numbers without a second request. Pure observation: this
+// handler neither reads nor touches the per-peer rate limiter or any receipt handling.
+async function apiDiagnosticsReceiptExits(req, res, url) {
+  try {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      ok: true,
+      counts: getFrameReceiptExitCounts(),
+      since: Date.now() - Math.round(process.uptime() * 1000),
+    }));
+  } catch (e) {
+    res.writeHead(500, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ ok: false, error: e.message }));
+  }
+}
+
 function causalTraceDiagnosticPayload(traceIdInput) {
   const traceId = String(traceIdInput || '');
   if (!/^[0-9a-f]{32}$/.test(traceId) || /^0+$/.test(traceId)) {
@@ -73,72 +146,8 @@ function causalTraceDiagnosticPayload(traceIdInput) {
 
 let _deps = null;
 
-function configure({
-  apiDiagnosticsClientFreeze,
-  apiDiagnosticsClientHealthPing,
-  apiDiagnosticsLifecycle,
-  apiDiagnosticsSessionResources,
-  apiDiagnosticsSessionDiagnostics,
-  apiDiagnosticsClientHealthRecent,
-  apiDiagnosticsResumeMetrics,
-  apiDiagnosticsRestartOutcomes,
-  apiDiagnosticsTestBlockMain,
-  pairableOrigins,
-  apiDiagnosticsTestCodexBurst,
-  apiDiagnosticsClientHealth,
-  apiDiagnosticsWriteLock,
-  apiDiagnosticsVersion,
-  apiDiagnosticsDbOwner,
-  apiDiagnosticsConversationFreshness,
-  apiDiagnosticsConversationImport,
-  apiDiagnosticsDbCensus,
-  apiDiagnosticsMainDbTop,
-  apiDiagnosticsUploads,
-  apiDiagnosticsTestDbOwnerWedge,
-  apiDiagnosticsPerfSummary,
-  apiDiagnosticsMainDbBudget,
-  apiDiagnosticsFsCensus,
-  apiDiagnosticsEventLoop,
-  apiDiagnosticsRestoreAdmission,
-  apiDiagnosticsMainWatchdog,
-  apiDiagnosticsWatcher,
-  apiDiagnosticsRenderChurn,
-  apiDiagnosticsSessionViewers,
-  apiDiagnosticsSubmissions,
-} = {}) {
-  _deps = {
-    apiDiagnosticsClientFreeze,
-    apiDiagnosticsClientHealthPing,
-    apiDiagnosticsLifecycle,
-    apiDiagnosticsSessionResources,
-    apiDiagnosticsSessionDiagnostics,
-    apiDiagnosticsClientHealthRecent,
-    apiDiagnosticsResumeMetrics,
-    apiDiagnosticsRestartOutcomes,
-    apiDiagnosticsTestBlockMain,
-    pairableOrigins,
-    apiDiagnosticsTestCodexBurst,
-    apiDiagnosticsClientHealth,
-    apiDiagnosticsWriteLock,
-    apiDiagnosticsVersion,
-    apiDiagnosticsDbOwner,
-    apiDiagnosticsConversationFreshness,
-    apiDiagnosticsConversationImport,
-    apiDiagnosticsDbCensus,
-    apiDiagnosticsMainDbTop,
-    apiDiagnosticsUploads,
-    apiDiagnosticsTestDbOwnerWedge,
-    apiDiagnosticsPerfSummary,
-    apiDiagnosticsMainDbBudget,
-    apiDiagnosticsFsCensus,
-    apiDiagnosticsEventLoop,
-    apiDiagnosticsRestoreAdmission,
-    apiDiagnosticsMainWatchdog,
-    apiDiagnosticsWatcher,
-    apiDiagnosticsRenderChurn,
-    apiDiagnosticsSessionViewers,
-    apiDiagnosticsSubmissions,
-  };
+function configure(deps = {}) {
+  _deps = deps;
 }
 
 // RL-WP-4 (render-lane design D-6): a test harness DECLARES the origins a hermetic server may
@@ -202,7 +211,7 @@ function register() {
     { method: 'POST', path: '/api/diagnostics/test/pairable-origins', handler: (req, res, url) => apiDiagnosticsTestPairableOriginsSet(req, res, url) },
     { method: 'DELETE', path: '/api/diagnostics/test/pairable-origins', handler: (req, res, url) => apiDiagnosticsTestPairableOriginsClear(req, res, url) },
     { method: 'POST', path: '/api/diagnostics/test/codex-burst', handler: (req, res, url) => _deps.apiDiagnosticsTestCodexBurst(req, res, url) },
-    { method: 'POST', path: '/api/diagnostics/client-health', handler: (req, res, url) => _deps.apiDiagnosticsClientHealth(req, res, url) },
+    { method: 'POST', path: '/api/diagnostics/client-health', handler: (req, res, url) => apiDiagnosticsClientHealth(req, res, url) },
     { method: 'GET', path: '/api/diagnostics/write-lock', handler: (req, res, url) => _deps.apiDiagnosticsWriteLock(req, res, url) },
     { method: 'GET', path: '/api/diagnostics/version', handler: (req, res, url) => _deps.apiDiagnosticsVersion(req, res, url) },
     { method: 'GET', path: '/api/diagnostics/db-owner', handler: (req, res, url) => _deps.apiDiagnosticsDbOwner(req, res, url) },
@@ -212,7 +221,7 @@ function register() {
     { method: 'GET', path: '/api/diagnostics/main-db-top', handler: (req, res, url) => _deps.apiDiagnosticsMainDbTop(req, res, url) },
     { method: 'GET', path: '/api/diagnostics/uploads', handler: (req, res, url) => _deps.apiDiagnosticsUploads(req, res, url) },
     { method: 'POST', path: '/api/diagnostics/test/db-owner-wedge', handler: (req, res, url) => _deps.apiDiagnosticsTestDbOwnerWedge(req, res, url) },
-    { method: 'GET', path: '/api/diagnostics/perf-summary', handler: (req, res, url) => _deps.apiDiagnosticsPerfSummary(req, res, url) },
+    { method: 'GET', path: '/api/diagnostics/perf-summary', handler: (req, res, url) => apiDiagnosticsPerfSummary(req, res, url) },
     { method: 'GET', path: '/api/diagnostics/main-db-budget', handler: (req, res, url) => _deps.apiDiagnosticsMainDbBudget(req, res, url) },
     { method: 'GET', path: '/api/diagnostics/fs-census', handler: (req, res, url) => _deps.apiDiagnosticsFsCensus(req, res, url) },
     { method: 'GET', path: '/api/diagnostics/event-loop', handler: (req, res, url) => _deps.apiDiagnosticsEventLoop(req, res, url) },
@@ -223,8 +232,479 @@ function register() {
     { method: 'GET', path: '/api/diagnostics/session-viewers', handler: (req, res, url) => _deps.apiDiagnosticsSessionViewers(req, res, url) },
     { method: 'GET', path: '/api/diagnostics/submissions', handler: (req, res, url) => _deps.apiDiagnosticsSubmissions(req, res, url) },
     { method: 'GET', path: '/api/diagnostics/restarts', handler: (req, res, url) => apiDiagnosticsRestarts(req, res, url) },
+    // WP-3 (box-idle-sleep-remote-typing-freezes-2026-11-01.html §8 WP-3): process-lifetime
+    // frame-receipt exit counters (read-only; the next live measurement names where a hub-typed
+    // keystroke's `painted` receipt dies on the box).
+    { method: 'GET', path: '/api/diagnostics/receipt-exits', handler: (req, res, url) => apiDiagnosticsReceiptExits(req, res, url) },
     { method: 'GET', path: '/api/context-budget', handler: (req, res, url) => apiContextBudget(req, res, url) },
   ]);
 }
 
-module.exports = { apiDiagnosticsTestPairableOriginsSet, apiDiagnosticsTestPairableOriginsClear, causalTraceDiagnosticPayload, apiContextBudget, configure, register };
+async function apiDiagnosticsClientHealth(req, res, url) {
+    try {
+      // Fresh-load LoAF evidence can contain up to 20 frames x 8 bounded script
+      // descriptors. Admit that bounded pre-sanitization shape, then let
+      // sanitizeClientHealthEnvelope enforce the retained field and string caps.
+      const raw = await _deps.readJsonRequestBody(req, { limitBytes: 128 * 1024 });
+      // Layered-resume and switch beacons use a compact metric shape on the existing endpoint.
+      if (raw && typeof raw === 'object' && _deps.RESUME_CLIENT_BEACON_METRICS.has(raw.metric)) {
+        const metric = _deps.sanitizeResumeClientMetric(raw);
+        if (!metric) {
+          return _deps.sendJsonResponse(res, 400, { ok: false, error: 'sessionId and ms are required' });
+        }
+        const { sessionId, ms } = metric;
+        const rateKey = `resume-metric:${sessionId}`;
+        const now = Date.now();
+        const prior = _deps._clientHealthReports.get(rateKey) || { windowStartedAt: now, count: 0, events: new Set() };
+        if (now - prior.windowStartedAt >= 60_000) {
+          prior.windowStartedAt = now;
+          prior.count = 0;
+          prior.events.clear();
+        }
+        if (prior.count >= 240) return _deps.sendJsonResponse(res, 429, { ok: false, error: 'client-health rate limit exceeded' });
+        prior.count += 1;
+        _deps._clientHealthReports.set(rateKey, prior);
+        if (_deps._clientHealthReports.size > 500) _deps._clientHealthReports.delete(_deps._clientHealthReports.keys().next().value);
+        _deps._resumeClientMetricRollup.add(metric, now);
+        _deps.recordSessionDiagnostic(sessionId, 'resume-client-metric', metric);
+        try {
+          _deps.telemetry.track(metric.metric, {
+            duration_ms: ms,
+            l0_outcome: metric.l0Outcome,
+            switch_path: metric.switchPath,
+            hot_reject_reason: metric.hotRejectReason,
+            kind: metric.kind,
+            frozen_frame_path: metric.path,
+            frozen_frame_font_faithful: metric.fontFaithful,
+            frozen_frame_cover_ms: metric.coverMs,
+            frozen_frame_max_age_hit: metric.maxAgeHit,
+            frozen_frame_activation_epoch: metric.activationEpoch,
+          });
+        } catch {}
+        return _deps.sendJsonResponse(res, 200, { ok: true });
+      }
+      // WP-1 (design/ctm-memory-footprint-round2-2026-08-14 §6): Poisson-sampled renderer
+      // memory beacon riding this same channel. Unprotected 'client-memory' event — the
+      // default 120/session ring + DB caps are fine for a trend metric (no db.js change).
+      // Kept ahead of the lifecycle branch below (own recordType tag, own rate key) so
+      // neither route's dedupe/count bookkeeping observes the other's traffic.
+      if (raw?.recordType === 'client-memory') {
+        const memorySample = _deps.sanitizeClientHealthMemorySample(raw);
+        if (!memorySample) {
+          return _deps.sendJsonResponse(res, 400, { ok: false, error: 'invalid client-memory sample' });
+        }
+        const rateKey = `client-memory:${memorySample.sessionId}`;
+        const now = Date.now();
+        const prior = _deps._clientHealthReports.get(rateKey) || { windowStartedAt: now, count: 0, events: new Set() };
+        if (now - prior.windowStartedAt >= 60_000) {
+          prior.windowStartedAt = now;
+          prior.count = 0;
+          prior.events.clear();
+        }
+        if (prior.count >= 20) return _deps.sendJsonResponse(res, 429, { ok: false, error: 'client-health rate limit exceeded' });
+        prior.count += 1;
+        _deps._clientHealthReports.set(rateKey, prior);
+        if (_deps._clientHealthReports.size > 500) _deps._clientHealthReports.delete(_deps._clientHealthReports.keys().next().value);
+        _deps.recordSessionDiagnostic(memorySample.sessionId, 'client-memory', memorySample.sample);
+        return _deps.sendJsonResponse(res, 200, { ok: true, recordType: 'client-memory' });
+      }
+      if (raw?.recordType === 'lifecycle') {
+        const lifecycle = _deps.sanitizeClientHealthLifecycleEnvelope(raw);
+        if (!lifecycle) {
+          return _deps.sendJsonResponse(res, 400, { ok: false, error: 'invalid lifecycle envelope' });
+        }
+        const rateKey = `lifecycle:${lifecycle.tabIdHash}:${lifecycle.runIdHash}`;
+        const now = Date.now();
+        const prior = _deps._clientHealthReports.get(rateKey) || { windowStartedAt: now, count: 0, events: new Set() };
+        if (now - prior.windowStartedAt >= 60_000) {
+          prior.windowStartedAt = now;
+          prior.count = 0;
+          prior.events.clear();
+        }
+        const duplicate = prior.events.has(lifecycle.eventId)
+          || _deps._recentClientHealthLifecycleEvents.has(lifecycle.eventId);
+        if (!duplicate && prior.count >= 20) {
+          return _deps.sendJsonResponse(res, 429, { ok: false, error: 'client-health rate limit exceeded' });
+        }
+        if (!duplicate) prior.count += 1;
+        prior.events.add(lifecycle.eventId);
+        _deps._clientHealthReports.set(rateKey, prior);
+        if (_deps._clientHealthReports.size > 500) _deps._clientHealthReports.delete(_deps._clientHealthReports.keys().next().value);
+        _deps._recentClientHealthLifecycleEvents.upsert(lifecycle);
+        return _deps.sendJsonResponse(res, 200, { ok: true, duplicate, recordType: 'lifecycle' });
+      }
+      const envelope = _deps.sanitizeClientHealthEnvelope(raw);
+      if (!envelope.tabId || !envelope.runId || !envelope.incidentId) {
+        return _deps.sendJsonResponse(res, 400, { ok: false, error: 'tabId, runId, and incidentId are required' });
+      }
+      const rateKey = `${envelope.tabId}:${envelope.runId}`;
+      const now = Date.now();
+      const prior = _deps._clientHealthReports.get(rateKey) || { windowStartedAt: now, count: 0, events: new Set() };
+      if (now - prior.windowStartedAt >= 60_000) {
+        prior.windowStartedAt = now;
+        prior.count = 0;
+        prior.events.clear();
+      }
+      const eventKey = `${envelope.incidentId}:${envelope.phase}`;
+      if (prior.events.has(eventKey)) return _deps.sendJsonResponse(res, 200, { ok: true, duplicate: true });
+      if (prior.count >= 20) return _deps.sendJsonResponse(res, 429, { ok: false, error: 'client-health rate limit exceeded' });
+      prior.count += 1;
+      prior.events.add(eventKey);
+      _deps._clientHealthReports.set(rateKey, prior);
+      if (_deps._clientHealthReports.size > 500) _deps._clientHealthReports.delete(_deps._clientHealthReports.keys().next().value);
+
+      for (const row of envelope.stateSync) _deps._stateSyncClientLedger.mergeClientSnapshot(row);
+      const correlated = _deps.correlateClientHealthIncident(envelope.incident, _deps._eventLoopIncidents, envelope.clock);
+      // S-30: `latestForSession` now throws on an empty clientId -- an untrusted client-health
+      // payload can omit both `row.clientId` and `websocket.clientId`; treat that as "no row"
+      // rather than let a malformed beat 500 this endpoint.
+      const mergedRows = envelope.stateSync
+        .map((row) => {
+          const beatClientId = String(row.clientId || envelope.websocket.clientId || '');
+          return beatClientId ? _deps._stateSyncClientLedger.latestForSession(row.sessionId, beatClientId) : null;
+        })
+        .filter(Boolean);
+      const firstMissingBoundary = mergedRows.map(row => ({
+        sessionId: row.sessionId,
+        clientId: row.clientId,
+        socketGeneration: row.socketGeneration,
+        boundary: row.firstMissingBoundary || _deps.firstMissingStateSyncBoundary(row),
+      })).find(row => row.boundary) || null;
+      const processLanes = _deps.sanitizeProcessLanes({
+        readPool: _deps._ctmReadPool?.getStatus?.() || null,
+        worktreeWorker: _deps._ctmWorktreeWorker?.getStatus?.() || null,
+        dbOwner: _deps._ctmDbWorker?.getStatus?.() || null,
+      });
+      const performanceSummary = _deps.summarizePerformanceEvidence(envelope.performance);
+      if (envelope.incident.kind === 'interaction_stall' && envelope.phase === 'detected') {
+        const diagnosticSessionId = envelope.activeSessionId
+          || envelope.deliveryGap?.sessionId
+          || envelope.stateSync[0]?.sessionId
+          || '';
+        const diagnosticSession = diagnosticSessionId ? _deps.sessions.get(diagnosticSessionId) : null;
+        const interactionStallMs = Math.max(
+          Number(envelope.incident.mainGapMs || 0),
+          Number(performanceSummary.inputDelayMs || 0),
+        );
+        if (diagnosticSessionId) _deps.recordSessionDiagnostic(diagnosticSessionId, 'interaction-stall', {
+          durationMs: interactionStallMs,
+          provider: diagnosticSession?._providerId || _deps._providerIdFromCmd(diagnosticSession?.cmd || ''),
+          activeTab: diagnosticSessionId === envelope.activeSessionId,
+          kind: envelope.incident.kind,
+        });
+        // WP-3 (docs/mainloop-composer-freeze-2026-08-20.html §5 D-6, §6, §8 WP-3): the client
+        // floor dropped 500ms -> 200ms (public/js/client-health-core.js); a keyboard incident
+        // that clears the NEW 200ms bar but not the old 500ms one is exactly the class this WP
+        // exists to make visible, so it gets its own [mainloop-diag] line independent of the
+        // per-session recordSessionDiagnostic row above.
+        _deps.routeKeyboardIncidentToMainloopDiag(_deps._mainloopDiagLogger, {
+          kind: envelope.incident.kind,
+          ms: interactionStallMs,
+        });
+      }
+      const inputPerformanceHeadline = _deps.formatInputPerformanceHeadline(performanceSummary, {
+        enabled: _deps._typingInteractionTelemetryEnabled,
+      });
+      // S-6: renderCount/sincePaint above only count terminal render spans — indistinguishable
+      // from "just painted" when a tab never rendered a span at all. paint.count is the true
+      // rAF-presented counter the paint-drought classifier itself uses (client-health-core.js).
+      const paintSnapshot = envelope.paint || { count: 0, lastPresentedAtMs: 0 };
+      const paintSincePresentedMs = paintSnapshot.lastPresentedAtMs > 0
+        ? Math.max(0, Math.round(now - paintSnapshot.lastPresentedAtMs))
+        : 0;
+      console.warn(
+        `[client-health] incident=${envelope.incidentId} phase=${envelope.phase} domain=${correlated.domain} kind=${correlated.kind} `
+        + `serverIncident=${correlated.serverIncidentId || 'none'} tab=${envelope.tabId.slice(0, 16)} `
+        + `run=${envelope.runId.slice(0, 16)} boundary=${firstMissingBoundary?.boundary || 'none'} `
+        + `clientBoundary=${envelope.deliveryGap?.boundary || 'none'} `
+        + `wsBuffered=${envelope.websocket.bufferedAmount} worktreeQueued=${processLanes.worktreeWorker?.queued || 0} `
+        + `clientBuild=${String(envelope.clientBuild?.loadedAsset || envelope.clientBuild?.assetEpoch || 'unknown').slice(0, 16)} `
+        + `renderer=${envelope.renderer.webglContexts}webgl/${envelope.renderer.activeTerminals}active/`
+        + `${envelope.renderer.hiddenTerminals}hidden/${envelope.renderer.sessions}sess `
+        + inputPerformanceHeadline
+        + `loaf=${performanceSummary.loafMs}/${performanceSummary.blockingMs}/${performanceSummary.pauseMs}ms `
+        + `loafScript=${performanceSummary.scriptSource || 'none'}:${performanceSummary.scriptFunction || 'anonymous'}`
+        + `@${performanceSummary.scriptCharPos}(offset-advisory)/${performanceSummary.scriptMs}ms `
+        + `renderSpan=${performanceSummary.renderSpan || 'none'}/${performanceSummary.renderSpanMs}ms `
+        + `renderCount=${envelope.performance.renderSpanCount} sincePaint=${Math.round(envelope.performance.msSinceLastPaint)}ms `
+        + `paint=${paintSnapshot.count}/${paintSincePresentedMs}ms `
+        + `wake=${Number(envelope.incident.wake || 0)}`,
+      );
+      _deps._recentClientHealthIncidents.push(Object.freeze({
+        receivedAt: now,
+        incidentId: envelope.incidentId,
+        tabId: envelope.tabId,
+        runId: envelope.runId,
+        phase: envelope.phase,
+        classification: correlated.kind,
+        incidentDomain: correlated.domain,
+        serverIncidentId: correlated.serverIncidentId || '',
+        firstMissingBoundary,
+        clientDeliveryGap: envelope.deliveryGap,
+        mainGapMs: envelope.incident.mainGapMs,
+        workerTickDeltaMs: envelope.incident.workerTickDeltaMs,
+        lifecycle: envelope.lifecycle,
+        wake: envelope.wake,
+        websocket: envelope.websocket,
+        clientBuild: envelope.clientBuild,
+        collector: envelope.performance.collector,
+        performance: envelope.performance,
+        renderer: envelope.renderer,
+        stateSync: mergedRows,
+        processLanes,
+      }));
+      if (_deps._recentClientHealthIncidents.length > 100) {
+        _deps._recentClientHealthIncidents.splice(0, _deps._recentClientHealthIncidents.length - 100);
+      }
+      return _deps.sendJsonResponse(res, 200, {
+        ok: true,
+        schemaVersion: 1,
+        classification: correlated.kind,
+        incidentDomain: correlated.domain,
+        serverIncidentId: correlated.serverIncidentId || '',
+        firstMissingBoundary,
+        clientDeliveryGap: envelope.deliveryGap,
+      });
+    } catch (error) {
+      return _deps.sendJsonResponse(res, 400, { ok: false, error: error.message });
+    }
+  }
+
+async function apiDiagnosticsPerfSummary(req, res, url) {
+    try {
+      const censusLimit = Math.max(1, Math.min(256, Number(url?.searchParams?.get('censusLimit')) || 10));
+      const eventLoop = _deps._perfTracker.getEventLoopStats();
+      const pressure = _deps._loadPressure.getStatus();
+      const readPool = _deps._ctmReadPool?.getStatus?.() || null;
+      const dbOwner = _deps._ctmDbWorker?.getStatus?.() || null;
+      const providerIndex = _deps._desktopIndex.status();
+      const processTreeRssBytes = Math.round(
+        (Number(_deps._sessionResourceSampler.snapshot?.processTree?.rssMB) || 0) * 1024 * 1024,
+      );
+      // (a) physical footprint + (b) mirror visibility (design doc §6a/§6b). Both are
+      // async and spawned off the main thread (footprint via child_process; the mirrors
+      // report via IPC round-trip to the pooled host process) — AC-0d never blocks the
+      // main thread synchronously for these. Both resolve to an empty/null value on
+      // any failure so perf-summary never 500s because a diagnostic sample was slow.
+      //
+      // D-1 (§8 WP-0): prefer the 60s sweep's own main-process footprint sample
+      // (_sampleLifecycleResources -> _sessionResourceSampler.snapshot.platform.main) --
+      // it is already fresh (sampled at most one sweep interval ago) whenever the sweep has
+      // run at least once recently, so most perf-summary polls no longer need a second
+      // on-demand footprint round trip for the same pid. Falls back to sampling on demand only
+      // when the cached sample is missing or older than 2 sweep intervals (sweep stalled,
+      // or this is the very first request before any sweep has run).
+      let physFootprintBytes = null;
+      const sweepSnapshot = _deps._sessionResourceSampler.snapshot;
+      const sweepIntervalMs = Math.max(1, Number(_deps._sessionResourceSampler.intervalMs) || 60_000);
+      const sweepAgeMs = Date.now() - (Number(sweepSnapshot?.sampledAt) || 0);
+      const sweepFootprintMB = sweepSnapshot?.platform?.main?.footprintMB;
+      if (sweepFootprintMB != null && sweepAgeMs <= sweepIntervalMs * 2) {
+        physFootprintBytes = Math.round(sweepFootprintMB * 1024 * 1024);
+      } else {
+        try {
+          const footprintMB = await _deps._sessionResourceSampler.sampleFootprintMB(process.pid);
+          physFootprintBytes = footprintMB == null ? null : Math.round(footprintMB * 1024 * 1024);
+        } catch (error) {
+          _deps.errorSink.report('diagnostics:physical-footprint-sample', error);
+        }
+      }
+      let mirrors = [];
+      try {
+        mirrors = await _deps.sessionHostManager.requestPoolMirrorsReport();
+      } catch (error) {
+        console.warn(`[diagnostics] mirrors report failed: ${error.message}`);
+      }
+      // WP-3/S5: pool gauges the pooled-host process alone can answer (frame-emitter
+      // session count, archive-store pending backlog) -- same IPC round trip shape as the
+      // mirrors report above, same zeroed-not-thrown failure posture.
+      // No try/catch: requestPoolPoolsReport rides _poolRequest, which RESOLVES to its
+      // zeroed emptyResult on timeout / no pool / send failure (lib/session-host-manager.js
+      // "never rejects" contract) -- a catch here would be a new bare-console tail for a
+      // path that cannot reject (G-2 count-ceiling, tests/db-owner-log-discipline.test.js).
+      const poolsFromHost = await _deps.sessionHostManager.requestPoolPoolsReport();
+      // WP-6 (§7 "Ledger visibility", §8 WP-6/AC-6a): the gateway's own
+      // /_status, normalized for the ledger by fetchMcpGatewayLedgerStatus()
+      // above. Same shape whether the gateway is up or down (zeroed, never
+      // thrown) -- there is nothing to catch here, matching the
+      // poolsFromHost "never rejects" contract just above.
+      const mcpGatewayStatus = await _deps.fetchMcpGatewayLedgerStatus();
+      // D-1 (§8 WP-0): sum of every footprint the sweep actually sampled this pass (main,
+      // pooled session-host, desktop index, and every live session) -- `null`, not 0, when
+      // the sweep has not sampled anything yet (first request before any sweep, or
+      // FOOTPRINT_TRUTH disabled) so the ledger cannot mistake "unsampled" for "0 bytes".
+      // There is no true tree-wide footprint measurement (`treeFootprintBytes`) to compare it
+      // against, so that field is left for a caller with that data; the RSS-based
+      // unattributedTreeRssBytes estimate keeps its current meaning until one exists.
+      let knownFootprintMB = 0;
+      let knownFootprintSamples = 0;
+      for (const entry of Object.values(sweepSnapshot?.platform || {})) {
+        if (entry?.footprintMB != null) { knownFootprintMB += Number(entry.footprintMB); knownFootprintSamples += 1; }
+      }
+      for (const session of sweepSnapshot?.sessions || []) {
+        if (session?.footprintMB != null) { knownFootprintMB += Number(session.footprintMB); knownFootprintSamples += 1; }
+      }
+      const knownFootprintBytes = knownFootprintSamples > 0 ? Math.round(knownFootprintMB * 1024 * 1024) : null;
+      // WP-4 (§8 WP-4): the same sweep-sampled pool-host footprint D-1 already folds into
+      // knownFootprintBytes above, handed to the ledger a second time so it can compute
+      // poolHostBaseMB (footprint minus every mirror's attributed bytes) -- null, not 0,
+      // when the sweep has not sampled the pool host this pass.
+      const poolHostFootprintMB = sweepSnapshot?.platform?.['session-host-pool']?.footprintMB ?? null;
+      const memory = _deps.buildMemoryLedger({
+        processMemory: process.memoryUsage(),
+        processTreeRssBytes,
+        physFootprintBytes,
+        footprints: { knownFootprintBytes, treeFootprintBytes: null },
+        mirrors,
+        poolHostFootprintMB,
+        caches: {
+          messageResponses: _deps._msgResponseCache.status(),
+          terminalSnapshots: _deps._terminalSnapshotBudget.status(),
+          exitedTerminalSnapshots: _deps._exitedSnapshotBudget.status(),
+          // WP-3/S5: same budget primitive as the two above, previously absent from the
+          // ledger entirely (§1d: "8 MB, same primitive as the ledgered budgets").
+          historyWindow: _deps._historyWindowBudget.status(),
+        },
+        // WP-3/S5: pools the ledger previously could not see at all. archivePending* comes
+        // from the pooled host process (main process holds no archive-store instance of its
+        // own -- the store lives in lib/headless-term-service.js, WP-1B). frameEmitterSessions
+        // rides the same round trip. sessionDiagnosticsSessions/terminalTailSessions are
+        // in-heap and read directly.
+        pools: {
+          archivePending: {
+            rows: poolsFromHost.archivePendingRows,
+            bytes: poolsFromHost.archivePendingBytes,
+            dropped: poolsFromHost.archiveDroppedRows,
+          },
+          frameEmitterSessions: poolsFromHost.frameEmitterSessions,
+          sessionDiagnosticsSessions: _deps.sessionDiagnostics.size(),
+          terminalTailSessions: _deps._terminalTailState.size,
+          // WP-6/AC-6a: {reachable, servers: {<name>: {state, pid, rssBytes,
+          // toolCalls, sessions, adopted}}, totalRssBytes, warmChildren} --
+          // zeroed (never thrown) when the gateway is unreachable.
+          mcpGateway: mcpGatewayStatus,
+        },
+        workers: {
+          readPool: (readPool?.workers || []).map((worker) => ({
+            kind: 'thread',
+            ...(worker.memory || {}),
+            openConnections: worker.openConnections,
+          })),
+          dbOwner: dbOwner?.memory ? {
+            kind: 'thread',
+            ...dbOwner.memory,
+            heapStatistics: dbOwner.heapStatistics || null,
+            openConnections: Number(dbOwner.openConnections) || 0,
+          } : null,
+          providerIndex: providerIndex.memory ? {
+            ...providerIndex.memory,
+            openConnections: 0,
+          } : null,
+          bulkService: readPool?.bulkService?.memory ? {
+            ...readPool.bulkService.memory,
+            openConnections: Number(readPool.bulkService.worker?.openConnections) || 0,
+          } : null,
+        },
+      });
+      const payload = _deps.buildPerfSummary({
+        eventLoop,
+        pressure,
+        headlessWorker: _deps.getWorkerLoopLag(), // WP-0 D-4
+        perfCertificationLedger: _deps._readPerfCertificationLedger(),
+        backgroundLlmRouteStats: _deps.getBackgroundLlmRouteStats(),
+        // `?censusLimit=N` widens both tripwire tables. The default of 10 is right for the
+        // dashboard, but it hid the real volume offender during the 2026-09-12 main-loop
+        // investigation: the fs-watcher scan's existence-check entry (tens of thousands of
+        // calls, but few ms) ranks by sumMs and fell off the list between two reads, so the
+        // biggest call-COUNT source on the main thread was invisible. Capped at 256,
+        // matching the tripwire's own TRIPWIRE_MAX_KEYS.
+        mainDb: _deps._mainDbCensus.getTripwireTop({ limit: censusLimit }),
+        syncIo: _deps._syncIoCensus.getTripwireTop({ limit: censusLimit }),
+        transcriptRoots: _deps._transcriptRoots,
+        wal: {
+          ..._deps._walCheckpointMetrics,
+          truncateSuccessRatio: _deps._walCheckpointMetrics.truncateAttempts > 0
+            ? _deps._walCheckpointMetrics.truncateSuccesses / _deps._walCheckpointMetrics.truncateAttempts
+            : null,
+        },
+        dbOwner,
+        readPool, mainTimers: { cpuByTimer: _deps._perfTracker.getTimerCpuStats?.() || {} }, broadcast: { byReason: _deps.getBroadcastReasonStats?.()?.byReason || {} }, // WP-0 M-1 (hub-local-cpu-memory-burn §7) + WP-0 M-2 (§3.2/§7): folded onto this line, not a new one, so the moved-body line budget is unchanged
+        writeLock: _deps.dbModule.getWriteLockStats?.() || null,
+        mainWriteEscapes: _deps.getMainThreadWriteEscapeStats(),
+        degraded: _deps._degradedOperations.getStatus(),
+        memory: { ...memory, retireNoReclaim: _deps._reclaimRecorder.getRetireNoReclaim(), reclaimRing: _deps._reclaimRecorder.getReclaimRing(), trimCadence: _deps._trimCadence.getStatus() }, // WP-6 D-9/AC-6a + WP-3 §6.3: folded onto this line -- handleApi is a frozen-length function (lint/file-size.config.json)
+        providerIndex: _deps._desktopIndex.status(),
+        typingInteractions: _deps._typingInteractionTelemetryEnabled
+          ? _deps._typingInteractionTraces.snapshot()
+          : { interactions: [], providers: {} },
+        codexInputTraces: _deps._typingInteractionTelemetryEnabled
+          ? _deps._typingInteractionTraces.publicSnapshot({
+            contextFor: ({ startedAt, endedAt }) => ({
+              eventLoopMaxMs: Number(_deps._eventLoopIncidents.correlate({ startedAt, endedAt })?.blockedMs || 0),
+            }),
+          })
+          : { interactions: [], providers: { codex: { count: 0 } } },
+        typingLatencyFlags: {
+          typingE2eTelemetry: _deps._typingInteractionTelemetryEnabled,
+          codexInputTrace: _deps._typingInteractionTelemetryEnabled,
+          streamStatusPatchV2: _deps.CTM_STREAM_STATUS_PATCH_V2_ENABLED,
+          stateSyncClientLedgerV2: true,
+          stateSyncInteractiveSupersede: true,
+          browserQosV2: _deps.CTM_BROWSER_QOS_V2_ENABLED,
+          stateSyncAtomicHandoffLease: true,
+          visibleRevisionWatchdog: _deps._visibleRevisionWatchdogEnabled,
+        },
+      });
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        ok: true,
+        ...payload,
+        recentCatalog: {
+          ..._deps._recentCatalogMetrics,
+          generation: _deps._recentCatalogGeneration,
+          publishedGeneration: _deps._recentCatalogPublished.generation,
+          publishedBytes: _deps._recentCatalogPublished.bytes,
+          variants: _deps._recentCatalogPublished.variants.size,
+          buildInFlight: _deps._recentCatalogBuildInFlight,
+        },
+        heartbeatProjection: _deps._heartbeatDirtyQueue.status(),
+        mainDbRequestGuard: _deps._mainDbCensus.getRequestGuard(),
+        controlSnapshot: _deps._controlSnapshot.status(),
+        runtimeEvents: _deps._runtimeEventBuffer.getStatus(),
+        conversationPublication: _deps._conversationUpdateOutboxBackoff.getStatus(),
+        historyBreakers: _deps._historyBreakerSnapshot(),
+        stateSyncLifecycle: {
+          unknownSessionSubscriptionRejections: _deps._stateSyncUnknownSubscriptionRejected,
+          ledgerCausalityRepairs: Number(_deps._stateSyncClientLedger.stats?.().causalityRepairs || 0),
+          pendingClients: (() => {
+            const stats = _deps.headlessWorker.getStatus?.().legacy || {};
+            return {
+              sessions: Number(stats.pendingStateSyncSessions || 0),
+              clients: Number(stats.pendingStateSyncClients || 0),
+              oldestAgeMs: Number(stats.pendingStateSyncOldestAgeMs || 0),
+              counters: {
+                ...(stats.pendingStateSyncCounters || {}),
+                unknownServerRejected: _deps._stateSyncUnknownSubscriptionRejected,
+              },
+            };
+          })(),
+          stallWarnings: (() => {
+            const stats = _deps.headlessWorker.getStatus?.().legacy || {};
+            return {
+              identities: Number(stats.stalledWarningIdentities || 0),
+              counters: stats.stalledWarningCounters || {},
+            };
+          })(),
+        },
+      }));
+    } catch (e) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: e.message }));
+    }
+    return;
+  }
+
+// WP-5 shard S4: the two verbatim bodies below are appended here by
+// bin/move-only-check.js's proof (identical to server.js's declarations up to
+// the `_deps.` prefix).
+module.exports = { apiDiagnosticsTestPairableOriginsSet, apiDiagnosticsTestPairableOriginsClear, causalTraceDiagnosticPayload, apiContextBudget, apiDiagnosticsClientHealth, apiDiagnosticsPerfSummary, configure, register };