ompchamber 3.1.1 → 3.3.0

package/src/server/lib/omp/session/telemetry/scan.ts

@@ -1,18 +1,100 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The JSONL pass behind both telemetry endpoints.
+ *
+ * `visit` is called per entry and may return `false` to stop early. The parse
+ * itself is cached by `(path, size, mtimeMs)`, because `/api/telemetry/context`
+ * and `/api/telemetry/raw-messages` are two polling endpoints that parse the
+ * SAME file — measured 70.6 ms and 64.2 ms on an 11 MB session, per request,
+ * with no cache between them. One parse now serves both until the file moves.
+ *
+ * The cache is keyed on the raw `stat.mtimeMs`, never a `Date`: `getTime()`
+ * truncates the fractional millisecond APFS reports, which is what made the
+ * session-scan cache miss on every call (see files.ts).
+ */
+
 import { parseJsonlLenient } from '@/shared/lib/omp/session/jsonl';
 import type { OmpMessageEntry } from '@/shared/types/omp/session';
 
-/** Streaming JSONL pass for the telemetry builders; `visit` returns `false` to stop early. */
-export async function scanSessionEntries(
-  filePath: string,
-  visit: (entry: OmpMessageEntry, index: number) => boolean | void,
-): Promise<void> {
+/** Sessions larger than this are not cached; a transcript past it is pathological. */
+const MAX_CACHED_SESSION_BYTES = 64 * 1024 * 1024;
+/** Bound on remembered transcripts, so a long session list cannot retain them all. */
+const MAX_CACHED_SESSIONS = 16;
+
+interface CachedEntries {
+  size: number;
+  mtimeMs: number;
+  entries: OmpMessageEntry[];
+}
+
+interface ScanCacheHost {
+  entries: Map<string, CachedEntries>;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __ompChamberTelemetryScanCache: ScanCacheHost | undefined;
+}
+
+function cache(): Map<string, CachedEntries> {
+  globalThis.__ompChamberTelemetryScanCache ??= { entries: new Map() };
+  return globalThis.__ompChamberTelemetryScanCache.entries;
+}
+
+/**
+ * Every entry of `filePath`, parsed once per file version.
+ *
+ * Callers must treat the returned array (and its entries) as immutable — the
+ * same array is handed to the next caller, and the builders only read.
+ */
+export async function loadSessionEntries(filePath: string): Promise<OmpMessageEntry[]> {
+  let size: number;
+  let mtimeMs: number;
+  try {
+    const stat = await Bun.file(filePath).stat();
+    size = stat.size;
+    mtimeMs = stat.mtimeMs;
+  } catch {
+    return [];
+  }
+
+  const slot = cache();
+  const cached = slot.get(filePath);
+  if (cached && cached.size === size && cached.mtimeMs === mtimeMs) {
+    // Refresh insertion order so the bound evicts the least recently used.
+    slot.delete(filePath);
+    slot.set(filePath, cached);
+    return cached.entries;
+  }
+
   let body: string;
   try {
     body = await Bun.file(filePath).text();
   } catch {
-    return;
+    return [];
   }
-  const records = parseJsonlLenient<OmpMessageEntry>(body);
+  const entries = parseJsonlLenient<OmpMessageEntry>(body);
+  if (size <= MAX_CACHED_SESSION_BYTES) {
+    slot.set(filePath, { size, mtimeMs, entries });
+    while (slot.size > MAX_CACHED_SESSIONS) {
+      const oldest = slot.keys().next().value;
+      if (oldest === undefined) break;
+      slot.delete(oldest);
+    }
+  }
+  return entries;
+}
+
+/** JSONL pass for the telemetry builders; `visit` returns `false` to stop early. */
+export async function scanSessionEntries(
+  filePath: string,
+  visit: (entry: OmpMessageEntry, index: number) => boolean | void,
+): Promise<void> {
+  const records = await loadSessionEntries(filePath);
   for (let index = 0; index < records.length; index++) {
     const entry = records[index];
     if (!entry) continue;

package/src/server/lib/omp/session/telemetry-raw.ts

@@ -7,6 +7,10 @@
  * Server-side pagination for the raw messages panel. Scans the session JSONL
  * like ./telemetry.ts but materializes at most one page of `RawMessageItem`s,
  * so the payload-heavy entries never leave the server in bulk.
+ *
+ * The sliding window keeps MATCHES, and only the page that is returned is
+ * built — building every match to discard all but one page cost 48.9 ms on an
+ * 11 MB session against 1.9 ms for the page itself.
  */
 
 import type { RawMessageItem } from '@/shared/types/context';
@@ -33,14 +37,20 @@ export async function computeRawMessagesPage(
   role: RawMessageRole = 'all',
 ): Promise<RawMessagesPage> {
   const windowSize = Math.max(1, page) * pageSize;
-  const window: RawMessageItem[] = [];
+  // The window holds the last `windowSize` MATCHES, not built items. Building
+  // every match and discarding all but one page was the whole cost of this
+  // endpoint: on an 11 MB session, `buildRawItem` over all 1017 matches took
+  // 48.9 ms while building only the 50 that are returned took 1.9 ms — the scan
+  // that collects them is 0.2 ms.
+  const window: { entry: OmpMessageEntry; msg: OmpMessage; index: number }[] = [];
+  let head = 0;
   let total = 0;
   let filteredTotal = 0;
-  let header: OmpMessageEntry | undefined;
+  let cwd = '';
 
   await scanSessionEntries(filePath, (entry, index) => {
-    if (entry.type === 'session' && !header) {
-      header = entry;
+    if (entry.type === 'session') {
+      if (!cwd) cwd = entry.cwd ?? '';
       return;
     }
     if (entry.type !== 'message' || !entry.message) return;
@@ -54,8 +64,8 @@ export async function computeRawMessagesPage(
     if (role !== 'all' && msgRole !== role) return;
     filteredTotal++;
 
-    if (window.length >= windowSize) window.shift();
-    window.push(buildRawItem(entry, msg, header?.cwd ?? '', index));
+    window.push({ entry, msg, index });
+    if (window.length - head > windowSize) head++;
   });
 
   // `window` holds the last `windowSize` matches, oldest→newest, where
@@ -63,9 +73,15 @@ export async function computeRawMessagesPage(
   // rows: skip the (page-1) newest chunks, take one, flip for display. Both
   // bounds clamp at 0 so out-of-range pages return an empty list.
   const skipNewest = (Math.max(1, page) - 1) * pageSize;
-  const end = Math.max(0, window.length - skipNewest);
+  const live = window.length - head;
+  const end = Math.max(0, live - skipNewest);
   const start = Math.max(0, end - pageSize);
-  const items = window.slice(start, end).reverse();
+  const items: RawMessageItem[] = [];
+  for (let i = head + start; i < head + end; i++) {
+    const match = window[i];
+    items.push(buildRawItem(match.entry, match.msg, cwd, match.index));
+  }
+  items.reverse();
   return { items, total, filteredTotal };
 }
 

package/src/server/lib/omp/session/usage/aggregate.ts

@@ -23,7 +23,10 @@ export type UsageWindow =
   | { kind: 'custom'; from: string; to: string }
   | { kind: 'all' };
 
-const PRESET_DAYS: Record<Exclude<TimeRangeType, 'custom' | 'all'>, number> = { today: 1, '7d': 7, '30d': 30, '90d': 90 };
+const PRESET_DAYS: Record<Exclude<TimeRangeType, 'custom' | 'all' | 'today'>, number> = { '7d': 7, '30d': 30, '90d': 90 };
+
+/** Every range the tokens endpoint reports, in display order. */
+export const PRESET_RANGES: Exclude<TimeRangeType, 'custom'>[] = ['today', '7d', '30d', '90d', 'all'];
 
 const TTL_MS = 60_000;
 const cache = new Map<string, { at: number; data: UsageAggregate }>();
@@ -75,49 +78,65 @@ function bump(map: Map<string, { tokens: number; cost: number }>, key: string, t
   map.set(key, current);
 }
 
-function inRange(timestampIso: string | undefined, window: UsageWindow, now: number): boolean {
-  if (window.kind === 'all') return true;
-  if (!timestampIso) return true; // keep entries without timestamps (conservative)
-  const ts = Date.parse(timestampIso);
-  if (Number.isNaN(ts)) return true;
-  if (window.kind === 'custom') {
-    const from = Date.parse(`${window.from}T00:00:00`);
-    const to = Date.parse(`${window.to}T23:59:59.999`);
-    if (Number.isNaN(from) || Number.isNaN(to) || from > to) return true;
-    return ts >= from && ts <= to;
-  }
-  if (window.range === 'today') {
-    const d = new Date(ts);
-    const n = new Date(now);
-    return d.getFullYear() === n.getFullYear() && d.getMonth() === n.getMonth() && d.getDate() === n.getDate();
-  }
-  if (window.range === 'all') return true;
-  return now - ts <= PRESET_DAYS[window.range] * 24 * 60 * 60 * 1000;
-}
-
 function cacheKey(window: UsageWindow): string {
   if (window.kind === 'all') return 'all';
   if (window.kind === 'custom') return `custom:${window.from}:${window.to}`;
   return window.range;
 }
 
-/** Aggregate all omp session files within a time window. Cached for 60s. */
-export async function aggregateUsage(window: UsageWindow): Promise<UsageAggregate> {
-  const key = cacheKey(window);
-  const cached = cache.get(key);
-  if (cached && Date.now() - cached.at < TTL_MS) return cached.data;
+/**
+ * One usage record, with everything a window needs to decide whether it counts.
+ *
+ * The scan that produces these is the expensive part — measured 795 ms over 455
+ * transcripts / 327 MB — so it runs ONCE and every window is derived from the
+ * same array. Aggregating per window re-read the whole tree for each of the five
+ * presets plus the active window, which is why `/api/telemetry/tokens` took
+ * 3.3 s cold.
+ */
+interface UsageRecord {
+  /** Epoch ms of the entry's timestamp, or undefined when it has none. */
+  at: number | undefined;
+  /** `YYYY-MM-DD` of `at`, or undefined. */
+  day: string | undefined;
+  model: string;
+  project: string;
+  cost: number;
+  costInput: number;
+  costOutput: number;
+  costCacheRead: number;
+  costCacheWrite: number;
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  reasoning: number;
+  total: number;
+}
+
+interface UsageScan {
+  at: number;
+  records: UsageRecord[];
+  /** Transcripts visited, counted once for every window. */
+  scannedTranscripts: number;
+}
+
+let scanCache: UsageScan | null = null;
+
+/** Every usage record in the sessions tree, read at most once per TTL. */
+async function scanUsage(): Promise<UsageScan> {
+  if (scanCache && Date.now() - scanCache.at < TTL_MS) return scanCache;
 
   const sessionsRoot = getSessionsDir();
-  const aggregate = emptyAggregate();
-  const now = Date.now();
+  const records: UsageRecord[] = [];
+  let scannedTranscripts = 0;
   let projectDirs: string[] = [];
   try {
     projectDirs = (await fs.promises.readdir(sessionsRoot, { withFileTypes: true }))
       .filter((d) => d.isDirectory() || d.isFile())
       .map((d) => d.name);
   } catch {
-    cache.set(key, { at: Date.now(), data: aggregate });
-    return aggregate;
+    scanCache = { at: Date.now(), records, scannedTranscripts };
+    return scanCache;
   }
 
   for (const project of projectDirs) {
@@ -136,37 +155,33 @@ export async function aggregateUsage(window: UsageWindow): Promise<UsageAggregat
     }
 
     for (const file of files) {
-      aggregate.scannedTranscripts++;
+      scannedTranscripts++;
       try {
         const ufile = Bun.file(file);
         if ((await ufile.stat()).size > 64 * 1024 * 1024) continue;
         const entries = parseJsonlLenient<OmpMessageEntry>(await ufile.text());
         for (const entry of entries) {
           if (entry.type !== 'message' || !entry.message?.usage) continue;
-          const ts = entry.timestamp;
-          if (!inRange(ts, window, now)) continue;
           const usage = entry.message.usage;
-          const cost = usage.cost?.total ?? 0;
-          const total = usage.totalTokens ?? (usage.input ?? 0) + (usage.output ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
-          aggregate.usageRecords++;
-          aggregate.costTotal += cost;
-          aggregate.costInput += usage.cost?.input ?? 0;
-          aggregate.costOutput += usage.cost?.output ?? 0;
-          aggregate.costCacheRead += usage.cost?.cacheRead ?? 0;
-          aggregate.costCacheWrite += usage.cost?.cacheWrite ?? 0;
-          aggregate.inputTokens += usage.input ?? 0;
-          aggregate.outputTokens += usage.output ?? 0;
-          aggregate.cacheReadTokens += usage.cacheRead ?? 0;
-          aggregate.cacheWriteTokens += usage.cacheWrite ?? 0;
-          aggregate.reasoningTokens += usage.reasoningTokens ?? 0;
-          if (ts) {
-            const day = ts.slice(0, 10);
-            aggregate.activeDays.add(day);
-            bump(aggregate.byDay, day, total, cost);
-          }
-          const model = entry.message.model || 'unknown';
-          bump(aggregate.byModel, model, total, cost);
-          bump(aggregate.byProject, project, total, cost);
+          const ts = entry.timestamp;
+          const parsed = ts ? Date.parse(ts) : Number.NaN;
+          records.push({
+            at: Number.isNaN(parsed) ? undefined : parsed,
+            day: ts ? ts.slice(0, 10) : undefined,
+            model: entry.message.model || 'unknown',
+            project,
+            cost: usage.cost?.total ?? 0,
+            costInput: usage.cost?.input ?? 0,
+            costOutput: usage.cost?.output ?? 0,
+            costCacheRead: usage.cost?.cacheRead ?? 0,
+            costCacheWrite: usage.cost?.cacheWrite ?? 0,
+            input: usage.input ?? 0,
+            output: usage.output ?? 0,
+            cacheRead: usage.cacheRead ?? 0,
+            cacheWrite: usage.cacheWrite ?? 0,
+            reasoning: usage.reasoningTokens ?? 0,
+            total: usage.totalTokens ?? (usage.input ?? 0) + (usage.output ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0),
+          });
         }
       } catch {
         // Unreadable transcript — skip rather than failing the whole report.
@@ -174,8 +189,108 @@ export async function aggregateUsage(window: UsageWindow): Promise<UsageAggregat
     }
   }
 
-  const data = aggregate;
+  scanCache = { at: Date.now(), records, scannedTranscripts };
+  return scanCache;
+}
+
+/** Fold the scanned records that fall inside `window` into an aggregate. */
+function foldWindow(records: readonly UsageRecord[], window: UsageWindow, now: number, scannedTranscripts: number): UsageAggregate {
+  const aggregate = emptyAggregate();
+  aggregate.scannedTranscripts = scannedTranscripts;
+  const bounds = windowBounds(window, now);
+  for (const record of records) {
+    // An entry with no usable timestamp is kept by EVERY window — a missing
+    // date is not evidence of age, and this matches the previous per-record
+    // behaviour.
+    if (record.at !== undefined && (record.at < bounds.from || record.at > bounds.to)) continue;
+    aggregate.usageRecords++;
+    aggregate.costTotal += record.cost;
+    aggregate.costInput += record.costInput;
+    aggregate.costOutput += record.costOutput;
+    aggregate.costCacheRead += record.costCacheRead;
+    aggregate.costCacheWrite += record.costCacheWrite;
+    aggregate.inputTokens += record.input;
+    aggregate.outputTokens += record.output;
+    aggregate.cacheReadTokens += record.cacheRead;
+    aggregate.cacheWriteTokens += record.cacheWrite;
+    aggregate.reasoningTokens += record.reasoning;
+    if (record.day) {
+      aggregate.activeDays.add(record.day);
+      bump(aggregate.byDay, record.day, record.total, record.cost);
+    }
+    bump(aggregate.byModel, record.model, record.total, record.cost);
+    bump(aggregate.byProject, record.project, record.total, record.cost);
+  }
+  return aggregate;
+}
+
+interface WindowBounds {
+  /** Inclusive epoch-ms bounds; `-Infinity`/`Infinity` for an unbounded side. */
+  from: number;
+  to: number;
+}
+
+/**
+ * Epoch-ms bounds for a window, computed once per fold.
+ *
+ * `today` is a local CALENDAR day (`setHours(0,0,0,0)`), not "the last 24h":
+ * the panel's "today" tab counts the day the user is in, and the previous
+ * implementation compared year/month/date for the same reason.
+ */
+function windowBounds(window: UsageWindow, now: number): WindowBounds {
+  if (window.kind === 'custom') {
+    const from = Date.parse(`${window.from}T00:00:00`);
+    const to = Date.parse(`${window.to}T23:59:59.999`);
+    if (Number.isNaN(from) || Number.isNaN(to) || from > to) return { from: -Infinity, to: Infinity };
+    return { from, to };
+  }
+  if (window.kind === 'all') return { from: -Infinity, to: Infinity };
+  switch (window.range) {
+    case 'all':
+      return { from: -Infinity, to: Infinity };
+    case 'today': {
+      const start = new Date(now);
+      start.setHours(0, 0, 0, 0);
+      const end = new Date(start);
+      end.setDate(end.getDate() + 1);
+      return { from: start.getTime(), to: end.getTime() - 1 };
+    }
+    default:
+      return { from: now - PRESET_DAYS[window.range] * 24 * 60 * 60 * 1000, to: Infinity };
+  }
+}
+
+/** Aggregate all omp session files within a time window. Cached for 60s. */
+export async function aggregateUsage(window: UsageWindow): Promise<UsageAggregate> {
+  const key = cacheKey(window);
+  const cached = cache.get(key);
+  if (cached && Date.now() - cached.at < TTL_MS) return cached.data;
+
+  const scan = await scanUsage();
+  const data = foldWindow(scan.records, window, Date.now(), scan.scannedTranscripts);
   if (cache.size > 20) cache.clear();
   cache.set(key, { at: Date.now(), data });
   return data;
 }
+
+/**
+ * Aggregate EVERY preset range plus `window` from one scan.
+ *
+ * The tokens endpoint needs all six, and folding them from one scan costs the
+ * fold (linear in records) rather than six more tree reads.
+ */
+export async function aggregateUsageWindows(
+  window: UsageWindow,
+): Promise<{ ranges: Record<Exclude<TimeRangeType, 'custom'>, UsageAggregate>; active: UsageAggregate }> {
+  const scan = await scanUsage();
+  const now = Date.now();
+  const ranges = {} as Record<Exclude<TimeRangeType, 'custom'>, UsageAggregate>;
+  for (const range of PRESET_RANGES) {
+    ranges[range] = foldWindow(scan.records, { kind: 'preset', range }, now, scan.scannedTranscripts);
+  }
+  const active = foldWindow(scan.records, window, now, scan.scannedTranscripts);
+  // Cache each fold under its own key so a later single-window call reuses it.
+  for (const range of PRESET_RANGES) cache.set(range, { at: now, data: ranges[range] });
+  cache.set(cacheKey(window), { at: now, data: active });
+  return { ranges, active };
+}

package/src/server/lib/terminal/runtime.server.ts

@@ -273,6 +273,9 @@ export function forgetTerminal(id: string): void {
   if (!session) return;
   sessions.delete(id);
   clearPendingResize(id);
+  // Close each viewer's socket, not just forget it: the record is going away,
+  // so a socket left open would sit on a terminal that can never answer it.
+  for (const viewer of session.viewers) viewer.drop();
   session.viewers.clear();
   if (session.status === 'running') signalGroup(session, 'SIGKILL');
   closeTerminalStream(session);

package/src/server/lib/terminal/session.server.ts

@@ -41,7 +41,15 @@ export const TERMINATION_GRACE_MS = 1000;
 
 /** A socket attached to a terminal. Output is raw PTY bytes; control is JSON. */
 export interface TerminalViewer {
-  send(frame: string | Uint8Array): void;
+  /**
+   * Deliver one frame. Returns false when the viewer could not accept it —
+   * the socket's send buffer is over its high-water mark — which the session
+   * treats as "this viewer is gone": a PTY producer cannot be paused, so the
+   * alternative is buffering unbounded output in a socket nobody is reading.
+   */
+  send(frame: string | Uint8Array): boolean;
+  /** Detach this viewer. Called when `send` reports it cannot keep up. */
+  drop(): void;
 }
 
 export interface TerminalSession {
@@ -63,6 +71,25 @@ export interface TerminalSession {
   lastActivity: number;
 }
 
+/**
+ * Deliver `frame` to every viewer, dropping the ones that cannot keep up.
+ *
+ * `Bun.ServerWebSocket.send` returns the bytes queued, or `-1` when the socket
+ * is over its high-water mark and the frame was NOT sent (verified on 1.4.2:
+ * 40 sends of 1 MiB to a socket nobody reads all return `-1`). A viewer that
+ * reports `-1` is closed rather than skipped — skipping would leave xterm's
+ * parser mid-sequence, so the honest outcome is a reconnect that replays the
+ * scrollback. The PTY cannot be paused, so this is the only backpressure a
+ * terminal has.
+ */
+export function fanOut(session: TerminalSession, frame: string | Uint8Array): void {
+  for (const viewer of session.viewers) {
+    if (viewer.send(frame)) continue;
+    session.viewers.delete(viewer);
+    viewer.drop();
+  }
+}
+
 /** A rejected attach, carrying the code the client shows to the user. */
 export class TerminalRuntimeError extends Error {
   constructor(
@@ -118,7 +145,7 @@ export async function createSession(request: AttachRequest): Promise<TerminalSes
     data(_term, bytes) {
       session.history.append(bytes);
       session.lastActivity = Date.now();
-      for (const viewer of session.viewers) viewer.send(bytes);
+      fanOut(session, bytes);
     },
   });
   session.term = term;
@@ -145,7 +172,7 @@ export async function createSession(request: AttachRequest): Promise<TerminalSes
     session.signal = proc.signalCode ?? null;
     session.lastActivity = Date.now();
     const frame = JSON.stringify({ t: 'exit', exitCode: session.exitCode, signal: session.signal });
-    for (const viewer of session.viewers) viewer.send(frame);
+    fanOut(session, frame);
   });
 
   return session;

package/src/server/plugins/shell.server.ts

@@ -19,22 +19,58 @@
  * own routing table rather than Elysia's (verified against Bun 1.4.2). Fetching
  * our own listener is the supported way to obtain the markup.
  *
- * The server reference is injected rather than imported to avoid a cycle:
- * `index.ts` owns the listener and imports `ssrRoutes`, which reaches here.
+ * The listener reference is shared with the dev asset proxy, which needs the
+ * same URL to reach the routes Bun's own table owns — see `lifecycle/listener`.
  */
 
+import { describeShellBuildFailure } from '@/server/lib/bundler/build-errors.server';
 import { SHELL_ROUTE } from '@/server/lib/lifecycle/shell-route';
+import { listenerUrl } from '@/server/lib/lifecycle/listener';
 
-type ShellSource = { url: URL } | null;
-
-let source: ShellSource = null;
+export type ShellRender = { ok: true; html: string } | { ok: false; reason: string };
 
-/** Called by the server entry once its listener is up. */
-export function setShellSource(server: { url: URL }): void {
-  source = server;
+/**
+ * Why the route refused, in the terms of the edit that broke it.
+ *
+ * A status alone is the least useful half of the answer: the route answers 500
+ * because Bun could not bundle the page, and the file, line and message are in
+ * the response — but only inside Bun's "Build Failed" page, which carries them
+ * as a binary payload the page decodes at runtime. So the entrypoint is rebuilt
+ * to obtain them in readable form. See `bundler/build-errors.server` for why
+ * that probe agrees with the route.
+ *
+ * Runs only on a failure, on a page that is already broken.
+ */
+async function shellFailureReason(status: number, markupInvalid = false): Promise<string> {
+  const detail = await describeShellBuildFailure();
+  if (detail) {
+    const reason = markupInvalid ? 'The shell route answered with markup that is not the shell.' : `Shell route answered ${status}.`;
+    return `${reason}\n\nThe client bundle does not build:\n\n${detail}`;
+  }
+  // Markup that is not the shell while the bundle builds cleanly means the
+  // route is serving a CACHED failure: Bun caches the HTML route's output once
+  // in production and never rebuilds it, so the empty body a failed first
+  // request left behind outlives the fix. There is nothing to point at in the
+  // source, and no amount of reloading helps — only a restart does.
+  return 'The shell route answered with markup that is not the shell, and the client bundle builds cleanly.\n\n'
+    + 'In production Bun caches the HTML route\'s output, so a build failure on the first request is cached as an empty page. Restart the server to rebuild it.';
 }
 
-export type ShellRender = { ok: true; html: string } | { ok: false; reason: string };
+/**
+ * The bootstrap marker the SSR route substitutes, and therefore the one string
+ * that proves the markup came from `index.html`.
+ *
+ * A status check alone is not enough, and the gap is not theoretical: with
+ * `development: false` Bun caches the route's output, and a build that failed on
+ * the FIRST request leaves it caching an EMPTY body answered `200`. Every later
+ * request then looks successful, and the substitution below finds nothing to
+ * replace — so the browser gets a blank page with a 200 and no way to tell why.
+ * Measured on Bun 1.4.2: request 1 `500` + empty, requests 2..n `200` + empty,
+ * and it stayed empty after the source was fixed, because the cached output is
+ * never rebuilt in production. The marker turns that into the same actionable
+ * page the development path already produces.
+ */
+export const SHELL_MARKER = '<!--app-bootstrap-->';
 
 /**
  * The current shell markup, or a reason it could not be produced.
@@ -44,11 +80,14 @@ export type ShellRender = { ok: true; html: string } | { ok: false; reason: stri
  * thing that could serve markup pointing at a previous build's asset hashes.
  */
 export async function renderShell(): Promise<ShellRender> {
-  if (!source) return { ok: false, reason: 'The HTTP listener is not up yet.' };
+  const base = listenerUrl();
+  if (!base) return { ok: false, reason: 'The HTTP listener is not up yet.' };
   try {
-    const response = await fetch(new URL(SHELL_ROUTE, source.url));
-    if (!response.ok) return { ok: false, reason: `Shell route answered ${response.status}.` };
-    return { ok: true, html: await response.text() };
+    const response = await fetch(new URL(SHELL_ROUTE, base));
+    if (!response.ok) return { ok: false, reason: await shellFailureReason(response.status) };
+    const html = await response.text();
+    if (!html.includes(SHELL_MARKER)) return { ok: false, reason: await shellFailureReason(response.status, true) };
+    return { ok: true, html };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     return { ok: false, reason: message };