@rangojs/router 0.17.0 → 0.19.0

package/src/rsc/shell-capture.ts

@@ -6,21 +6,29 @@
  * from the route's `ppr` path option after the served response is built and calls
  * scheduleShellCapture. The capture then runs as a background task that re-derives
  * the page via `ctx.router.match()` under its OWN derived request context — fresh
- * handle store, `_shellCaptureRun: true` so loaders mask (loader-mask.ts) and every
- * loading() subtree postpones. The render is MIXED-CHAIN: cache()'d segments replay
- * from ring 3, uncached segments execute their handlers fresh. It drives the static
- * prerender to a quiescent shell, aborts to freeze the prelude + postponed state,
- * and stores the pair via putShell. Because it uses match() rather than the HTTP
- * pipeline, the middleware chain (auth, logging) never re-runs — it already ran for
- * the triggering request, and the derived context inherits its post-middleware
- * state (variables, cache store). Guarding is serve-time.
+ * handle store, `_shellCaptureRun: true` so live-lane loaders mask (loader-mask.ts)
+ * and postpone at their loading() or inline <Suspense> boundary. The match is
+ * MIXED-CHAIN: cache()'d segments replay from ring 3, uncached segments execute
+ * their handlers. The record-first step (settleCaptureRecord) waits for the
+ * handler layer, writes the doc record every HIT replays, and renders the
+ * capture's Flight payload from it; the static prerender runs to a quiescent
+ * shell, aborts to freeze the prelude + postponed state, and putShell stores the
+ * pair with the snapshot. Because it uses match() rather than the HTTP pipeline,
+ * the middleware chain (auth, logging) never re-runs — it already ran for the
+ * triggering request, and the derived context inherits its post-middleware state
+ * (variables, cache store). Guarding is serve-time.
  */
 
 import React from "react";
-import { isLoaderDataResult } from "../types.js";
-import { bufferToBase64 } from "../cache/cf/cf-base64.js";
+import { isLoaderDataResult, type MatchResult } from "../types.js";
+import { bytesToBase64 } from "../cache/cf/cf-base64.js";
+import { SHELL_BAKE_TAG_OWNER, getSegmentTags } from "../cache/cache-tag.js";
 import { reportCacheError } from "../cache/cache-error.js";
-import { runBackground } from "../cache/background-task.js";
+import {
+  raceDeadline,
+  runBackground,
+  settleGrowing,
+} from "../cache/background-task.js";
 import {
   CaptureQueueFullError,
   CaptureQueueWaitTimeoutError,
@@ -31,6 +39,8 @@ import {
   PPR_LANE_HINT,
   SHELL_CAPTURE_MAX_WAIT_MS,
   SHELL_CAPTURE_TASK_HARD_CAP_MS,
+  resetShellWarningsForTests,
+  warnOnce,
 } from "./shell-capture-constants.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import { observePhase, PHASES } from "../router/instrument.js";
@@ -41,18 +51,28 @@ import {
   wireRenderBarrier,
   UNTRACKED_BACKGROUND_TASK,
   type RequestContext,
+  type RouteRecordWindow,
 } from "../server/request-context.js";
+import {
+  DEFAULT_FUNCTION_TTL,
+  resolveSwrWindow,
+  resolveTtl,
+} from "../cache/cache-policy.js";
 import { createHandleStore, type HandleStore } from "../server/handle-store.js";
 import {
   maskNestedContainerThenables,
+  settleNestedThenables,
   type MaskReport,
 } from "../router/segment-resolution/mask-nested.js";
 import {
+  findEnclosingLoaderBody,
   getCurrentLoaderBodyId,
   isInsideLoaderScope,
 } from "../server/context.js";
 import { isThenable } from "../handles/is-thenable.js";
+import { requestHeaders } from "../server/request-headers.js";
 import type {
+  CachedEntryData,
   ShellCacheEntry,
   SegmentCacheStore,
   ShellSnapshotRecord,
@@ -64,11 +84,15 @@ import {
 import {
   RecordingShellStore,
   SnapshotOnlySegmentStore,
+  countSnapshotFamilies,
+  estimateShellEntryBytes,
   getRecordingStore,
+  hasDocRecord,
+  pruneShellSnapshot,
 } from "../cache/shell-snapshot.js";
 import type { HandlerContext } from "./handler-context.js";
 import type { SSRModule } from "./types.js";
-import { buildFullPayload } from "./full-payload.js";
+import { buildFullPayload, payloadInitialTheme } from "./full-payload.js";
 import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
 import { renderRscFlightStage } from "./render-pipeline.js";
 import { stripInternalParams } from "../router/handler-context.js";
@@ -89,21 +113,13 @@ import { stripInternalParams } from "../router/handler-context.js";
  *
  * K=2 gives a race window of ~two event-loop turns: shell work still producing
  * bytes keeps resetting the counter; anything not producing bytes within the
- * window (the masked loaders, and any genuinely pending I/O) becomes a hole. The
- * only residual is raw per-request I/O rendered directly in shell (not via a
- * loader) that resolves inside the window — a documented shell anti-pattern; put
- * per-request data in loaders. See docs/design/ppr-shell-resume.md.
+ * window (the masked loaders) becomes a hole. Handler output never races it: the
+ * capture's Flight input is the doc record's fragments, rendered after
+ * settleCaptureRecord waited for the handler layer. See
+ * docs/design/ppr-shell-resume.md.
  */
 const FLIGHT_QUIET_HOPS = 2;
 
-/**
- * Default capture budget. Canonical value, raise rationale, and ceiling math
- * live on the leaf module (shell-capture-constants.ts, importable from the ssr
- * graph too). Re-exported here so shell-build-manifest.ts's envelope math
- * keeps its existing import site and cannot drift from the capture.
- */
-export { SHELL_CAPTURE_MAX_WAIT_MS };
-
 /**
  * Upper bound on waiting for the capture's DEFERRED cache writes to settle before
  * draining the snapshot. Cache writes run under waitUntil (fire-and-forget on
@@ -140,33 +156,17 @@ const SHELL_CAPTURE_WRITE_BARRIER_MS = 1500;
 
 /**
  * Settle the tracked background tasks on `reqCtx._pendingBackgroundTasks`,
- * ITERATIVELY: a settled task can have scheduled a nested one (cache-store's
- * cacheRoute outer task schedules the actual store.set in a second waitUntil), so
- * each awaited batch may append more. Loop until no new tasks appear or the
- * deadline passes. The capture's own task never enters the list
- * (UNTRACKED_BACKGROUND_TASK), so the loop terminates.
+ * including nested ones a settled task scheduled (cache-store's cacheRoute
+ * outer task schedules the actual store.set in a second waitUntil), until the
+ * list stops growing or the timeout passes. The capture's own task never
+ * enters the list (UNTRACKED_BACKGROUND_TASK), so the wait terminates.
  */
 async function settleTrackedBackgroundTasks(
   reqCtx: RequestContext<any>,
   timeoutMs: number,
 ): Promise<void> {
   const tasks = reqCtx._pendingBackgroundTasks;
-  if (!tasks) return;
-  const deadline = Date.now() + timeoutMs;
-  let seen = 0;
-  while (tasks.length > seen) {
-    const remaining = deadline - Date.now();
-    if (remaining <= 0) return;
-    const batch = tasks.slice(seen);
-    seen = tasks.length;
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    const guard = new Promise<void>((resolve) => {
-      timer = setTimeout(resolve, remaining);
-      (timer as { unref?: () => void }).unref?.();
-    });
-    await Promise.race([Promise.allSettled(batch).then(() => {}), guard]);
-    if (timer) clearTimeout(timer);
-  }
+  if (tasks) await settleGrowing(tasks, Date.now() + timeoutMs);
 }
 
 /**
@@ -196,31 +196,18 @@ function delay(ms: number): Promise<void> {
  * Bound one capture task at {@link SHELL_CAPTURE_TASK_HARD_CAP_MS}. Rejects on
  * expiry so the caller's existing catch applies backoff + reporting and its
  * settle path releases the stampede guard and queue slot; resolves/rejects
- * transparently otherwise. The timer is unref'd so a pending cap never holds a
- * Node dev process open.
+ * transparently otherwise.
  */
-function raceTaskHardCap<T>(task: Promise<T>, key: string): Promise<T> {
-  return new Promise<T>((resolve, reject) => {
-    const timer = setTimeout(() => {
-      reject(
-        new Error(
-          `capture task for ${key} exceeded the ${SHELL_CAPTURE_TASK_HARD_CAP_MS}ms hard cap; ` +
-            `a handler is likely wedged on a never-settling await`,
-        ),
-      );
-    }, SHELL_CAPTURE_TASK_HARD_CAP_MS);
-    (timer as { unref?: () => void }).unref?.();
-    task.then(
-      (value) => {
-        clearTimeout(timer);
-        resolve(value);
-      },
-      (error: unknown) => {
-        clearTimeout(timer);
-        reject(error);
-      },
-    );
-  });
+async function raceTaskHardCap<T>(task: Promise<T>, key: string): Promise<T> {
+  const raced = await raceDeadline(
+    task,
+    Date.now() + SHELL_CAPTURE_TASK_HARD_CAP_MS,
+  );
+  if (raced.done) return raced.value;
+  throw new Error(
+    `capture task for ${key} exceeded the ${SHELL_CAPTURE_TASK_HARD_CAP_MS}ms hard cap; ` +
+      `a handler is likely wedged on a never-settling await`,
+  );
 }
 
 /**
@@ -240,6 +227,13 @@ function raceTaskHardCap<T>(task: Promise<T>, key: string): Promise<T> {
  * keeps a late-settling stale task from releasing its replacement's entry.
  */
 interface CaptureGuardToken {
+  /**
+   * The schedule time while the capture waits in the queue (which drops it at
+   * CAPTURE_QUEUE_WAIT_BUDGET_MS, under the cap), then the time its hard cap
+   * started. Stamped only at schedule time, a capture that had waited in the
+   * queue read as older than its cap while still inside it, and the next
+   * request scheduled a duplicate capture of the key.
+   */
   startedAt: number;
 }
 
@@ -313,7 +307,7 @@ function refusedCaptureCeilingMs(): number {
  */
 const refusedCaptures = new Map<string, { failures: number; until: number }>();
 
-/** True iff `key` is still inside its (exponential) backoff window. */
+/** A bake-lane container that settled with redirect() or notFound(). */
 function isSettledLoaderSignal(value: unknown): boolean {
   return (
     isLoaderDataResult(value) &&
@@ -322,6 +316,7 @@ function isSettledLoaderSignal(value: unknown): boolean {
   );
 }
 
+/** True iff `key` is still inside its (exponential) backoff window. */
 function isCaptureBackedOff(key: string): boolean {
   const entry = refusedCaptures.get(key);
   if (entry === undefined) return false;
@@ -353,14 +348,10 @@ function clearCaptureBackoff(key: string): void {
 }
 
 /**
- * Keys already warned about a refused (null) capture, so the eternal-MISS shape
- * logs once per key per isolate instead of on every request.
- */
-const warnedNullCaptures = new Set<string>();
-
-/**
- * Warn once per key that a capture produced no usable shell EVEN AFTER the
- * in-place retry (runShellCapture attempt 2). Naming both causes with the
+ * Warn once per key that a capture produced no usable shell: after the
+ * in-place retry (runShellCapture attempt 2), or after one attempt that ran
+ * out of its deadline (no retry: CaptureAttemptStats.noShellCause), with the
+ * terminal attempt's cause and pending component stacks. Naming both causes with the
  * distinguishing signal — does the route ever flip to HIT — is the whole point:
  * the pre-retry version blamed "a loader route without loading()" unconditionally
  * and misled users whose route DID have loading() and was merely cold. Because the
@@ -371,27 +362,57 @@ const warnedNullCaptures = new Set<string>();
  * The pointer is the shared PPR_LANE_HINT: the /ppr skill ships in the npm
  * tarball, so the path resolves for consumers (a05c8251 convention).
  */
-function warnNullCaptureOnce(key: string): void {
-  if (warnedNullCaptures.has(key)) return;
-  warnedNullCaptures.add(key);
-  console.warn(
-    `[rango] Shell capture for "${key}" produced no usable shell after an in-place ` +
-      "retry; nothing was stored, so this request stays on MISS. Causes, told apart " +
-      "by whether the route ever flips to HIT:\n" +
-      "  1. Cold-start warmup (dev module transform, or a cold worker): the capture raced " +
-      "an unfinished shell render. This SELF-HEALS — the route flips to HIT once a later " +
-      "request warms the modules.\n" +
-      "  2. Something suspends above <body> with no Suspense boundary and never settles " +
-      "within the capture window: a live loader (no ssr: false) read without loading() or " +
-      "an inline <Suspense>; a loader(Def, { ssr: false }) or top-level push (e.g. Meta) " +
-      "slower than ppr.captureTimeout; or a pending promise with no Suspense above it. The " +
-      "boundary belongs to the entry or component that owns the data.\n" +
+function warnNullCaptureOnce(
+  key: string,
+  retried: boolean,
+  attempt: CaptureAttemptStats,
+): void {
+  const cause = attempt.noShellCause;
+  const pendingStacks = attempt.pendingStacks;
+  warnOnce(
+    "capture-no-shell",
+    key,
+    () =>
+      `[rango] Shell capture for "${key}" produced no usable shell` +
+      (retried ? " after an in-place retry" : "") +
+      "; nothing was stored, so this request stays on MISS. " +
+      (cause
+        ? `Cause: ${cause}. Every capture waits for the handler layer to finish and ` +
+          'bakes it; make the slow part cheaper (cache() or "use cache"), raise ' +
+          "ppr.captureTimeout, or move it into a live loader (no ssr: false) read under " +
+          "loading() or an inline <Suspense>.\n"
+        : "Causes, told apart by whether the route ever flips to HIT:\n" +
+          "  1. Cold-start warmup (dev module transform, or a cold worker): the capture raced " +
+          "an unfinished shell render. This SELF-HEALS — the route flips to HIT once a later " +
+          "request warms the modules.\n" +
+          "  2. Something suspends above <body> with no Suspense boundary and never settles " +
+          "within the capture window: a live loader (no ssr: false) read without loading() or " +
+          "an inline <Suspense>, or a loader(Def, { ssr: false }) or top-level push (e.g. Meta) " +
+          "slower than ppr.captureTimeout. The boundary belongs to the entry or component " +
+          "that owns the data.\n") +
+      (pendingStacks && pendingStacks.length > 0
+        ? "Components still pending when the capture froze the shell (one of them " +
+          "suspended above <body>):\n" +
+          pendingStacks.map(formatPendingStack).join("\n") +
+          "\n"
+        : "") +
       PPR_LANE_HINT,
   );
 }
 
-/** Keys already warned about a deterministic capture refusal (once per key). */
-const warnedRefusedCaptures = new Set<string>();
+/** Stacks kept per attempt: the root pin is almost always among the first. */
+const MAX_PENDING_STACKS = 3;
+
+/** The first lines of one component stack, indented under the warning. */
+function formatPendingStack(stack: string): string {
+  return stack
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .slice(0, 8)
+    .map((line) => `    ${line}`)
+    .join("\n");
+}
 
 /**
  * Warn once per key that the capture was REFUSED for a deterministic reason
@@ -406,15 +427,81 @@ function warnCaptureRefusedOnce(
   reason: string,
   pointer: string = "See the /ppr skill (node_modules/@rangojs/router/skills/ppr/SKILL.md).",
 ): void {
-  if (warnedRefusedCaptures.has(key)) return;
-  warnedRefusedCaptures.add(key);
-  console.warn(
-    `[rango] Shell capture for "${key}" was refused: ${reason}\n` +
+  warnOnce(
+    "capture-refused",
+    key,
+    () =>
+      `[rango] Shell capture for "${key}" was refused: ${reason}\n` +
       "The route stays on MISS (axis 1) — the page keeps working, only the shell " +
       `cache is off. ${pointer}`,
   );
 }
 
+/**
+ * Refuse the capture when a capture guard tripped: a request-scoped read
+ * (cookies(), headers(), a { cache: false } variable) or ctx.dynamic() made
+ * anywhere the capture waited for — a handler, a promise it passes or pushes,
+ * an async server component, a bake-lane loader. The read throws where it
+ * happens, but the code can catch that throw, so the flag the guard sets on
+ * the capture context is what decides (server/context.ts
+ * guardIdentityRead). Returns true when it refused (and warned).
+ */
+function refuseOnCaptureGuard(
+  key: string,
+  derivedCtx: RequestContext<any>,
+): boolean {
+  if (derivedCtx._dynamic) {
+    // A build-time capture reports dynamic() as its own outcome
+    // (build-shell-capture.ts): the URL keeps runtime capture.
+    if (derivedCtx.build) return true;
+    warnCaptureRefusedOnce(
+      key,
+      "ctx.dynamic() was called while capturing the shared shell (in a handler, or " +
+        "in a promise or async component the capture waited for). A dynamic render " +
+        "has no shell; the route keeps serving axis 1 for requests that opt out.",
+    );
+    return true;
+  }
+  const trip = derivedCtx._shellCaptureGuardTripped;
+  if (!trip) return false;
+  // Name the recorded source instead of hardcoding a lane: a trip can come
+  // from a bake-lane SEGMENT loader or from handler/render code, including a
+  // loader a handler awaits (issue #672). The guard recorded the read and its
+  // fix (server/context.ts guardIdentityRead): cookies()/headers(), a
+  // { cache: false } variable, and the theme reads (#971).
+  const loaderId = derivedCtx._shellCaptureGuardTrippedLoaderId;
+  const origin = loaderId
+    ? `the loader "${loaderId}"`
+    : "handler/render code (no loader body was executing)";
+  warnCaptureRefusedOnce(
+    key,
+    `${origin} read ${trip.surface} during capture; request-scoped data must not ` +
+      `bake into the shared shell. ${trip.fix}`,
+    PPR_LANE_HINT,
+  );
+  return true;
+}
+
+/** The no-shell cause for handler output that missed the capture deadline. */
+const HANDLER_OUTPUT_TIMEOUT_REASON: string =
+  "the handler output (a promise it passes or pushes, or an async server " +
+  "component) did not settle within ppr.captureTimeout";
+
+/** The refusal for a capture that stored no doc record (a HIT needs it). */
+const NO_DOC_RECORD_REASON: string =
+  "the capture produced no doc segment record, so a HIT could not replay the " +
+  "handler layer. Either the route's cache() refused the write (cache(false), or " +
+  "a condition() that returned false for the capture), or rendering the handler " +
+  "output failed (see the cache-write error reported for this key).";
+
+/**
+ * Default limit (bytes) on a whole stored shell entry — prelude, postponed
+ * state, and snapshot — when the store declares none
+ * (SegmentCacheStore.maxShellEntryBytes). Cloudflare KV's 25 MiB value limit:
+ * the tightest common store tier a shell entry lands in.
+ */
+export const DEFAULT_SHELL_ENTRY_MAX_BYTES: number = 25 * 1024 * 1024;
+
 /**
  * Default cap (serialized UTF-8 bytes) on the capture data snapshot riding
  * inside a shell entry, when the route's `ppr` option does not set
@@ -424,75 +511,75 @@ function warnCaptureRefusedOnce(
  * while still fitting any sane pinned-ring payload. Applied ONLY in
  * captureAndStoreShell (the single defaulting site — resolvePprConfig passes
  * the option through undefaulted), so every producer and direct caller gets
- * the same policy. Over the cap the snapshot is skipped (shell still stored;
- * pinned reads drift — see PartialPrerenderProps.maxSnapshotBytes).
+ * the same policy. The doc record is exempt; over the cap the other records
+ * are dropped (shell still stored and replayed; the pins' loaders read the
+ * live store — see PartialPrerenderProps.maxSnapshotBytes).
  */
 export const DEFAULT_PPR_MAX_SNAPSHOT_BYTES: number = 8 * 1024 * 1024;
 
 /** Cached encoder for the snapshot byte measurement (one per module, not per capture). */
 const SNAPSHOT_BYTE_ENCODER = new TextEncoder();
 
-/** Keys already warned about an over-cap snapshot (once per key per isolate). */
-const warnedOverCapSnapshots = new Set<string>();
-
 /**
- * Warn once per key that the capture data snapshot exceeded the route's
- * `maxSnapshotBytes` cap and was skipped. The shell entry is still stored and
- * served — only the pinned-read replay is lost, so shell-baked cached content
- * can drift from the frozen prelude between capture and HIT and hydration
- * repairs it client-side (the pre-snapshot behavior). Once per key: the same
- * page recaptures on every TTL roll and would otherwise re-warn forever.
+ * Warn once per key that the capture's loader pins exceeded the route's
+ * `maxSnapshotBytes` cap and were dropped. The shell entry is still stored
+ * with its doc record and every HIT replays the handler layer; only the
+ * pinned loaders lose their captured values, so their cached data can drift
+ * from the frozen prelude and hydration repairs it client-side. Once per
+ * key: the same page recaptures on every TTL roll and would otherwise
+ * re-warn forever.
  */
 function warnSnapshotOverCapOnce(
   key: string,
   snapshotBytes: number,
   capBytes: number,
 ): void {
-  if (warnedOverCapSnapshots.has(key)) return;
-  warnedOverCapSnapshots.add(key);
-  console.warn(
-    `[rango] Shell capture for "${key}" recorded a ${snapshotBytes}-byte data ` +
-      `snapshot, over the ${capBytes}-byte cap — the snapshot was skipped and ` +
-      "the shell was stored without it. The page keeps serving, but cached " +
-      "content baked into the shell is no longer pinned: if it drifts before " +
-      "the shell's TTL, hydration repairs the mismatch client-side. Raise the " +
-      "cap via the route's ppr option ({ maxSnapshotBytes }) if the entry " +
-      "still fits your store's value limit (Cloudflare KV: 25 MiB per value), " +
-      "or shrink the cache()'d data the shell bakes.",
+  warnOnce(
+    "snapshot-over-cap",
+    key,
+    () =>
+      `[rango] Shell capture for "${key}" recorded ${snapshotBytes} bytes of ` +
+      `loader pins, over the ${capBytes}-byte cap — the pins were dropped and ` +
+      "the shell was stored with its doc record only. HITs still replay the " +
+      "handler layer, but ssr: false loaders now read the live store: if " +
+      "their data drifts before the shell's TTL, hydration repairs the " +
+      "mismatch client-side. Raise the cap via the route's ppr option " +
+      "({ maxSnapshotBytes }) if the entry still fits your store's value limit " +
+      "(Cloudflare KV: 25 MiB per value), or shrink the cache()'d data the " +
+      "loaders read.",
   );
 }
 
 /**
- * Dev warning threshold (ms) for the slowest bake-source settlement wait. Bake
- * time is by-design shell latency (top-level pushed handle promises and
- * bake-lane loader containers settle before the freeze), but it recurs on
- * EVERY capture of the route and occupies the per-isolate serialized capture
- * queue — silently: the served response's own timing never shows it (a route
- * can read 13ms TTFB while each of its captures holds the queue for seconds).
- * Past this threshold the source gets named once per key with the remedy
- * ladder.
+ * Dev warning threshold (ms) for the record-first settle
+ * (CaptureAttemptStats.recordSettleMs). Bake time is by-design shell latency
+ * (handler output, top-level pushed handle promises and bake-lane loader
+ * containers settle before the freeze), but it recurs on EVERY capture of the
+ * route and occupies the per-isolate serialized capture queue — silently: the
+ * served response's own timing never shows it (a route can read 13ms TTFB
+ * while each of its captures holds the queue for seconds). Past this
+ * threshold the cost gets named once per key with the remedy ladder.
  */
 const SHELL_CAPTURE_BAKE_WARN_MS = 2_000;
 
-/** Keys already warned about an expensive bake source (once per key). */
-const warnedBakeCosts = new Set<string>();
-
 /**
- * Dev-only, once per key: name the slowest bake source and the three remedies
- * in preference order. The doctrine ("nesting = liveness") makes the cost
- * legitimate, so this is a cost report with an exit, not a deprecation.
+ * Dev-only, once per key: name the bake cost and the three remedies in
+ * preference order. Handler output and bake-lane values are shell material
+ * by design, so this is a cost report with an exit, not a deprecation.
  */
 function warnBakeCostOnce(key: string, source: string, ms: number): void {
-  if (warnedBakeCosts.has(key)) return;
-  warnedBakeCosts.add(key);
-  console.warn(
-    `[rango] Shell capture for "${key}" waited ${ms}ms for ${source} to ` +
+  warnOnce(
+    "bake-cost",
+    key,
+    () =>
+      `[rango] Shell capture for "${key}" waited ${ms}ms for ${source} to ` +
       "settle before the shell could freeze. This cost recurs on every capture " +
       "of the route and occupies the per-isolate capture queue; the served " +
-      "response never shows it. To make the value per-request, nest it " +
-      "({ data: promise }) and read it with use() under Suspense; to keep it " +
-      "baked but cheap, wrap the work in cache(); for a loader(Def, { ssr: false }), " +
-      "drop ssr: false to move it to the live lane. " +
+      "response never shows it. To keep it baked but cheap, wrap the work in " +
+      'cache() or "use cache"; to make it per-request, load it in a live ' +
+      "loader (no ssr: false) read under loading() or an inline <Suspense>; for " +
+      "a loader(Def, { ssr: false }), return the slow part as a nested promise " +
+      "or drop ssr: false. " +
       PPR_LANE_HINT,
   );
 }
@@ -509,10 +596,13 @@ export interface ShellCaptureDebugEvent {
   key: string;
   /**
    * What happened:
-   * - stored / redirect / no-shell / refused: one capture ATTEMPT's outcome
-   *   (see CaptureAttemptOutcome for the semantics of each)
+   * - stored / redirect / no-shell / refused / expired: one capture
+   *   ATTEMPT's outcome (see CaptureAttemptOutcome for the semantics of each)
    * - error: the capture task failed with a genuine error (also routed through
    *   reportCacheError; the key is backed off)
+   * - skip-stored: a capture for the key stored after the scheduling request
+   *   read the store and missed (ShellCaptureDescriptor.storedSeqAtRead), so
+   *   the shell that request missed exists now
    * - skip-in-flight: scheduleShellCapture found a capture already running for
    *   the key (stampede guard) and scheduled nothing
    * - skip-backoff: the key is inside its refused-capture backoff window and
@@ -535,8 +625,10 @@ export interface ShellCaptureDebugEvent {
     | "redirect"
     | "no-shell"
     | "refused"
+    | "expired"
     | "error"
     | "skip-in-flight"
+    | "skip-stored"
     | "skip-backoff"
     | "skip-capacity"
     | "skip-inert-store"
@@ -580,14 +672,13 @@ export interface ShellCaptureDebugEvent {
    */
   queueAhead?: number;
   /**
-   * Ms the capture gate was HELD waiting for the slowest bake source — a
-   * top-level pushed handle promise or a bake-lane loader container — to
-   * settle, measured from capture start. Bake time is by-design shell latency
-   * (the hole doctrine: top-level promises bake), but it recurs on EVERY
-   * capture of the route and occupies the serialized queue; this field makes
-   * it attributable. Absent when nothing held the gate.
+   * How long the capture waited for its doc record: the handler layer's
+   * promises, async server components and handle pushes settling, then the
+   * record's encode (settleCaptureRecord). Part of the one capture deadline.
    */
-  bakeWaitMs?: number;
+  recordSettleMs?: number;
+  /** Bytes of the stored entry: prelude, postponed state, and snapshot. */
+  entryBytes?: number;
 }
 
 /**
@@ -643,8 +734,11 @@ export function describeShellCaptureEvent(
   if (event.queueAhead !== undefined) {
     parts.push(`queue-ahead=${event.queueAhead}`);
   }
-  if (event.bakeWaitMs !== undefined) {
-    parts.push(`bake=${event.bakeWaitMs}ms`);
+  if (event.recordSettleMs !== undefined) {
+    parts.push(`record=${event.recordSettleMs}ms`);
+  }
+  if (event.entryBytes !== undefined) {
+    parts.push(`entry=${event.entryBytes}b`);
   }
   return parts.join(" ");
 }
@@ -681,6 +775,7 @@ const TIMING_RECORDED_OUTCOMES = new Set<ShellCaptureDebugEvent["outcome"]>([
   "redirect",
   "no-shell",
   "refused",
+  "expired",
   "error",
 ]);
 
@@ -786,22 +881,13 @@ export interface FlightCaptureGate {
  * closing (no holes) fires quiesce immediately for the DATA variant — the
  * TransformStream then closes the readable, so fizz completes with postponed null.
  *
- * `holdUntil` keeps the gate from FREEZING before shell material with real latency
- * has emitted. The hole doctrine bakes TOP-LEVEL pushed handle promises into the
- * shell (resolvedHandleStream awaits them before the handles row emits), but a
- * pushed promise that takes longer than the quiet window would otherwise be frozen
- * out — the handles row would never reach fizz and the prelude would come back
- * trivial. While `holdUntil` is pending, byte-quiet detection keeps running but the
- * gate neither fires nor freezes; once it resolves, the quiet counter restarts so a
- * burst of rows unblocked by it (the resolved handles row) is still captured. It
- * never delays a HOLE from postponing: holes are pending promises that emit no
- * bytes, so holding the gate open longer only ever admits shell rows. Bounded by
- * captureShellHTML's maxWaitMs like every other quiesce input.
+ * Nothing the shell bakes can still be pending here: settleCaptureRecord already
+ * waited for the top-level handle promises and the bake-lane loader containers
+ * before the capture's Flight render began, so the handles row and the baked
+ * loader rows emit at once and only the holes stay silent.
  */
 export function gateFlightForCapture(
   source: ReadableStream<Uint8Array>,
-  quietHops: number = FLIGHT_QUIET_HOPS,
-  holdUntil?: Promise<unknown>,
 ): FlightCaptureGate {
   let resolveQuiet!: () => void;
   const quiesce = new Promise<void>((resolve) => {
@@ -813,32 +899,9 @@ export function gateFlightForCapture(
   let settled = false;
   let disposed = false;
   let frozen = false;
-  let held = holdUntil !== undefined;
-  let heldFirePending = false;
-
-  if (holdUntil !== undefined) {
-    const release = (): void => {
-      held = false;
-      if (heldFirePending && !settled && !disposed) {
-        // Quiet elapsed while held: restart the quiet count instead of firing
-        // immediately, so rows unblocked by the hold (the baked handles row)
-        // still flow before the freeze.
-        heldFirePending = false;
-        armed = false;
-        arm();
-      }
-    };
-    // Resolve OR reject releases the hold (a rejected handle value is dropped by
-    // resolveDeferredHandleValues; the capture must not hang on it).
-    holdUntil.then(release, release);
-  }
 
   const fire = (): void => {
     if (settled) return;
-    if (held) {
-      heldFirePending = true;
-      return;
-    }
     settled = true;
     frozen = true;
     resolveQuiet();
@@ -862,7 +925,7 @@ export function gateFlightForCapture(
       if (settled || disposed) return;
       if (bytesSeen === lastSeen) {
         quiet += 1;
-        if (quiet >= quietHops) {
+        if (quiet >= FLIGHT_QUIET_HOPS) {
           fire();
           return;
         }
@@ -948,16 +1011,13 @@ export interface ShellCaptureDescriptor {
   tags?: string[];
   /**
    * Per-route capture settle budget in ms (`ppr.captureTimeout`, resolved by
-   * resolvePprConfig). Feeds captureShellHTML's maxWaitMs — the ONE deadline
-   * bounding the whole capture, so it covers BOTH the fizz prerender AND the
-   * deferred-material settle window (the handlesBaked/loader-container
-   * holdUntil that keeps the gate from freezing while top-level pushes are
-   * pending). Undefined = SHELL_CAPTURE_MAX_WAIT_MS (15_000).
+   * resolvePprConfig): the ONE deadline bounding the whole capture — the match,
+   * the record-first settle (settleCaptureRecord), then the fizz prerender with
+   * what is left (captureShellHTML's maxWaitMs). Undefined =
+   * SHELL_CAPTURE_MAX_WAIT_MS (15_000).
    */
   captureTimeout?: number;
   store?: SegmentCacheStore<any>;
-  /** Gates the concise per-attempt capture breadcrumbs (INTERNAL_RANGO_DEBUG). */
-  debug?: boolean;
   /**
    * Cap (serialized UTF-8 bytes) on the entry's capture data snapshot; over it
    * the snapshot is skipped and the shell stored without it (reported once per
@@ -974,6 +1034,33 @@ export interface ShellCaptureDescriptor {
   debugSink?: (event: ShellCaptureDebugEvent) => void;
   /** Store the snapshot for navigation replay, never the captured HTML prelude. */
   navigationOnly?: true;
+  /**
+   * lastStoredCaptureSeq(key) when a document request read the store and
+   * missed. The request schedules its capture only after rendering the MISS,
+   * so a capture another request started can store in between; a later
+   * sequence number then skips the redundant one (`skip-stored`), which would
+   * re-render the page and drop the isolate's memo of the shell just stored.
+   */
+  storedSeqAtRead?: number;
+}
+
+/** Per key, the sequence number of its latest stored capture (bounded). */
+const storedCaptureSeqs = new Map<string, number>();
+const STORED_CAPTURE_SEQS_MAX = 1_000;
+let storedCaptureSeq = 0;
+
+/** The latest stored capture's sequence number for `key` in this isolate, or 0. */
+export function lastStoredCaptureSeq(key: string): number {
+  return storedCaptureSeqs.get(key) ?? 0;
+}
+
+function noteCaptureStored(key: string): void {
+  storedCaptureSeqs.delete(key);
+  if (storedCaptureSeqs.size >= STORED_CAPTURE_SEQS_MAX) {
+    const oldest = storedCaptureSeqs.keys().next().value;
+    if (oldest !== undefined) storedCaptureSeqs.delete(oldest);
+  }
+  storedCaptureSeqs.set(key, ++storedCaptureSeq);
 }
 
 /**
@@ -1011,6 +1098,13 @@ export function scheduleShellCapture(
     // new token, and the stale task's token-guarded release can no longer
     // touch it.
   }
+  if (
+    descriptor.storedSeqAtRead !== undefined &&
+    lastStoredCaptureSeq(key) > descriptor.storedSeqAtRead
+  ) {
+    publishCaptureDebugEvent(descriptor, { key, outcome: "skip-stored" });
+    return;
+  }
   // Refused/failed within the window → skip the doomed re-render (one probe per
   // key per window per isolate). Expired entries self-evict inside the check.
   if (isCaptureBackedOff(key)) {
@@ -1035,16 +1129,23 @@ export function scheduleShellCapture(
   const guardToken: CaptureGuardToken = { startedAt: Date.now() };
   inFlightCaptures.set(key, guardToken);
   const captureTask = async (span: TraceSpan) => {
+    // The guard's age counts from the task's start, not its scheduling: a
+    // capture queued behind others (up to CAPTURE_QUEUE_WAIT_BUDGET_MS) is
+    // not abandoned while its SSR setup loads.
+    guardToken.startedAt = Date.now();
     try {
-      const setupUrl = descriptor.navigationOnly
+      // A navigation-only capture renders under document request identity:
+      // its transport parameters and headers are stripped once, here, for the
+      // SSR setup and every attempt.
+      const captureUrl = descriptor.navigationOnly
         ? stripInternalParams(url)
         : url;
-      const setupRequest = descriptor.navigationOnly
-        ? createNavigationCaptureRequest(request, setupUrl)
+      const captureRequest = descriptor.navigationOnly
+        ? createNavigationCaptureRequest(request, captureUrl)
         : request;
       const resolvedSsrModule =
         typeof ssrModule === "function"
-          ? await ssrModule(setupRequest, setupUrl)
+          ? await ssrModule(captureRequest, captureUrl)
           : ssrModule;
       if (
         !resolvedSsrModule ||
@@ -1053,19 +1154,21 @@ export function scheduleShellCapture(
       ) {
         return;
       }
-      // Hard-capped: SHELL_CAPTURE_MAX_WAIT_MS arms only inside
-      // captureShellHTML, AFTER the capture's router.match() — a handler
-      // wedged on a never-settling upstream await has no deadline in force
-      // and would strand the stampede guard and the queue slot (production
-      // pilot). The cap rejects, riding the existing catch: backoff +
-      // reportCacheError + token-guarded release. The abandoned attempt keeps
-      // running until its context dies; nothing awaits it.
+      // Hard-capped: ppr.captureTimeout bounds the attempt, but a match that
+      // loses its deadline keeps running (no abort signal), and a handler
+      // wedged on a never-settling upstream await would strand the stampede
+      // guard and the queue slot (production pilot). The cap rejects, riding
+      // the existing catch: backoff + reportCacheError + token-guarded
+      // release. The abandoned attempt keeps running until its context dies;
+      // nothing awaits it. From here the guard's age counts from the cap's
+      // start, so a slow SSR setup does not shorten the capped run.
+      guardToken.startedAt = Date.now();
       const outcome = await raceTaskHardCap(
         runShellCapture(
           ctx,
-          request,
+          captureRequest,
           env,
-          url,
+          captureUrl,
           reqCtx,
           resolvedSsrModule,
           descriptor,
@@ -1077,8 +1180,13 @@ export function scheduleShellCapture(
       // any prior backoff; a `no-shell` (after the in-place retry) backs the key
       // off so the next requests don't re-probe it. A `redirect` has no shell but
       // is not a doomed render — leave the backoff untouched.
-      if (outcome === "stored") clearCaptureBackoff(key);
-      else if (outcome === "no-shell") {
+      if (outcome === "stored") {
+        clearCaptureBackoff(key);
+        // Only a document entry is the shell a document MISS read the store
+        // for: document serving reads a navigation-only entry as a MISS, even
+        // one a corrupt-snapshot heal stored under the document key.
+        if (!descriptor.navigationOnly) noteCaptureStored(key);
+      } else if (outcome === "no-shell") {
         markCaptureBackoff(key);
         publishCaptureDebugEvent(descriptor, {
           key,
@@ -1191,6 +1299,81 @@ export function scheduleShellCapture(
   runBackground(reqCtx, serializedTask);
 }
 
+/**
+ * The ttl/swr a shell is stored with: the route's ppr policy, capped by the
+ * route cache() records the capture replayed or wrote
+ * (RequestContext._routeRecordWindow). A HIT replays the capture's handler
+ * output, while a client navigation reads the route's cache() tier first, so
+ * a shell that outlived its record would show a document request other
+ * handler output than a navigation of the same URL. Freshness and total
+ * lifetime are capped separately, like the record's own SWR: the shell is
+ * fresh while the record is (at most `ttl`), and servable while the record
+ * is (at most `ttl + swr`), so a record already inside its swr window yields
+ * a shell that is stale from the start and serves while it recaptures.
+ *
+ * Whole seconds, rounded up (the SegmentCacheStore.putShell contract), so the
+ * shell may outlast the record by under a second. Null when the record's
+ * total lifetime has run out: the shell would be dead on arrival.
+ */
+export function capShellWindow(
+  ttl: number,
+  swr: number,
+  record: Pick<RouteRecordWindow, "freshUntil" | "staleUntil">,
+  now: number,
+): { ttl: number; swr: number } | null {
+  const total = Math.min(ttl + swr, (record.staleUntil - now) / 1000);
+  if (!(total > 0)) return null;
+  // At most `total`: freshUntil <= staleUntil and swr >= 0.
+  const fresh = Math.max(0, Math.min(ttl, (record.freshUntil - now) / 1000));
+  const wholeTtl = Math.ceil(fresh);
+  return { ttl: wholeTtl, swr: Math.ceil(total) - wholeTtl };
+}
+
+/**
+ * Warn once per route (dev and production) that no shell was stored because
+ * the route cache() entry ran out before the capture could store one
+ * (capShellWindow returned null) where a retry cannot help: the capture
+ * wrote the entry itself (`written`), or the in-place retry's entry ran out
+ * too, or no budget was left to retry. The key backs off like a refused
+ * capture.
+ */
+function warnRecordRanOutOnce(
+  route: string,
+  record: RouteRecordWindow,
+  detail: string,
+): void {
+  warnOnce(
+    "record-ran-out",
+    route,
+    () =>
+      `[rango] Route "${route}": its cache() entry (ttl ${record.ttl}, swr ` +
+      `${record.swr}) ran out before the shell capture could store a shell ` +
+      `(${detail}), so no shell is stored and the route renders without ` +
+      "one. A shell never outlives the route cache() entry it replays: give " +
+      "that cache() a ttl or swr longer than the capture takes, queue wait " +
+      "included.",
+  );
+}
+
+/**
+ * A terminal `expired`: warn once per route with the record the attempt ran
+ * out on, and return `no-shell` so the caller backs the key off.
+ */
+function expiredTerminal(
+  attempt: CaptureAttemptStats,
+  reason: string,
+): "no-shell" {
+  const expired = attempt.expired;
+  if (expired) {
+    warnRecordRanOutOnce(
+      expired.route,
+      expired.record,
+      `${reason}; the last attempt took ${expired.captureMs} ms`,
+    );
+  }
+  return "no-shell";
+}
+
 /**
  * The outcome of one capture attempt.
  * - `stored`: a usable shell was captured (and a putShell was attempted; a store
@@ -1198,13 +1381,30 @@ export function scheduleShellCapture(
  *   the capture itself worked).
  * - `redirect`: the matched route redirects, so there is no shell to capture.
  * - `no-shell`: captureShellHTML returned null because the prelude was unusable
- *   or its private capture abort landed before the shell completed. This is the
- *   only RETRYABLE outcome.
+ *   or its private capture abort landed before the shell completed, or the
+ *   capture ran out of ppr.captureTimeout. Retried once in place, when no
+ *   deadline ran out (CaptureAttemptStats.noShellCause).
+ * - `expired`: the route cache() record the capture read (not wrote) ran out
+ *   before the store (capShellWindow null): it was near its end (its age,
+ *   queue wait). Retried once in place, where a fresh match reads or renders
+ *   a newer record; an `expired` retry, or no hard-cap budget left for the
+ *   retry, is terminal `no-shell` (backoff, warned once per route).
+ */
+type CaptureAttemptOutcome =
+  | "stored"
+  | "redirect"
+  | "no-shell"
+  | "refused"
+  | "expired";
+
+/**
+ * What a capture task ends with (runShellCapture): a refusal and a terminal
+ * `expired` are `no-shell`, which the scheduler backs off.
  */
-type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
+type CaptureTaskOutcome = "stored" | "redirect" | "no-shell";
 
 function createNavigationCaptureRequest(request: Request, url: URL): Request {
-  const headers = new Headers(request.headers);
+  const headers = new Headers(requestHeaders(request));
   headers.set("accept", "text/html");
   for (const name of [
     "rsc-action",
@@ -1220,11 +1420,12 @@ function createNavigationCaptureRequest(request: Request, url: URL): Request {
 }
 
 /**
- * Per-attempt observability fields, filled along the capture path (barrier in
- * attemptCapture, the rest in captureAndStoreShell) and folded into the
- * attempt's {@link ShellCaptureDebugEvent} by runShellCapture. A plain mutable
- * bag, not a return value: captureAndStoreShell's outcome type stays a string
- * union its existing callers (producer B, tests) consume unchanged.
+ * One attempt's record, filled along the capture path (barrier and deadline
+ * causes in attemptCapture, the rest in captureAndStoreShell). runShellCapture
+ * folds the observability fields into the attempt's
+ * {@link ShellCaptureDebugEvent} and reads the rest to decide the retry and
+ * the warning. A plain mutable bag, not a return value: captureAndStoreShell's
+ * outcome type stays a string union producer B consumes unchanged.
  */
 type CaptureAttemptStats = Pick<
   ShellCaptureDebugEvent,
@@ -1235,8 +1436,24 @@ type CaptureAttemptStats = Pick<
   | "snapshotSkipped"
   | "untaggedBake"
   | "storeWrite"
-  | "bakeWaitMs"
->;
+  | "recordSettleMs"
+  | "entryBytes"
+> & {
+  /**
+   * Why a no-shell attempt ran out of ppr.captureTimeout (the match, the
+   * handler output, or the prerender after them). A set cause skips the
+   * in-place retry: the attempt's match may still be running.
+   */
+  noShellCause?: string;
+  /**
+   * Dev only: component stacks of the tasks still pending at a no-shell
+   * attempt's abort, reported through prerender's onError (captureShellHTML's
+   * onAbortedTask).
+   */
+  pendingStacks?: string[];
+  /** The route cache() record an `expired` attempt ran out on. */
+  expired?: { route: string; record: RouteRecordWindow; captureMs: number };
+};
 
 /**
  * Run the shell capture with a single in-place retry, then store the result.
@@ -1249,12 +1466,15 @@ type CaptureAttemptStats = Pick<
  * when we froze the shell; the attempt itself warmed the module graph, so a second
  * attempt a short beat later usually completes the shell in the SAME background
  * task. That kills the old multi-request warmup where the caller had to re-issue
- * several HTTP requests before a capture stuck. We retry ONLY on `no-shell`; a
- * genuine render error is NOT retried — it propagates to scheduleShellCapture's
- * reportCacheError. See docs/design/ppr-shell-resume.md.
+ * several HTTP requests before a capture stuck. We retry ONLY on `no-shell`
+ * that did not run out of ppr.captureTimeout (CaptureAttemptStats.noShellCause),
+ * and on `expired`; a genuine render error is NOT retried — it propagates to
+ * scheduleShellCapture's reportCacheError. See docs/design/ppr-shell-resume.md.
  *
- * `retryDelayMs` is a parameter (defaulting to the module const) so unit tests can
- * drive the retry without a real 400ms wall-clock wait.
+ * `request` and `url` are the capture's own identity (scheduleShellCapture
+ * strips a navigation-only capture's transport parameters). `retryDelayMs` is
+ * a parameter (defaulting to the module const) so unit tests can drive the
+ * retry without a real 400ms wall-clock wait.
  */
 async function runShellCapture(
   ctx: HandlerContext<any>,
@@ -1265,14 +1485,8 @@ async function runShellCapture(
   ssrModule: SSRModule,
   descriptor: ShellCaptureDescriptor,
   retryDelayMs: number = SHELL_CAPTURE_RETRY_DELAY_MS,
-): Promise<CaptureAttemptOutcome> {
-  const captureUrl = descriptor.navigationOnly ? stripInternalParams(url) : url;
-  const captureRequest = descriptor.navigationOnly
-    ? createNavigationCaptureRequest(request, captureUrl)
-    : request;
-  const log = descriptor.debug
-    ? (message: string) => console.log(message)
-    : () => {};
+): Promise<CaptureTaskOutcome> {
+  const key = descriptor.key;
 
   // One attempt + its structured debug event: the stats object rides through
   // attemptCapture/captureAndStoreShell collecting the observability fields
@@ -1281,49 +1495,82 @@ async function runShellCapture(
   // event — scheduleShellCapture's catch publishes the terminal `error` event.
   const timedAttempt = async (
     attempt: number,
-  ): Promise<CaptureAttemptOutcome> => {
+  ): Promise<{
+    outcome: CaptureAttemptOutcome;
+    stats: CaptureAttemptStats;
+  }> => {
     const stats: CaptureAttemptStats = {};
     const start = performance.now();
     const outcome = await attemptCapture(
       ctx,
-      captureRequest,
+      request,
       env,
-      captureUrl,
+      url,
       reqCtx,
       ssrModule,
       descriptor,
       stats,
     );
+    const { noShellCause, pendingStacks, expired, ...eventFields } = stats;
     publishCaptureDebugEvent(descriptor, {
-      key: descriptor.key,
+      key,
       outcome,
       attempt,
       attemptMs: Math.round(performance.now() - start),
-      ...stats,
+      ...eventFields,
     });
-    return outcome;
+    return { outcome, stats };
   };
 
+  const taskStartedAt = performance.now();
   const first = await timedAttempt(1);
   // "refused" is deterministic (identity guard / rejected bake-lane loader —
   // its own warning already fired): no retry, and the caller backs the key off
   // exactly like a structural no-shell.
-  if (first === "refused") return "no-shell";
-  // "stored" (success) or "redirect" (no shell exists): nothing to retry.
-  if (first !== "no-shell") return first;
-
-  // Attempt 1 produced no usable shell. Retry ONCE in place — the first attempt
-  // warmed the dev transform graph / cold worker, so attempt 2 typically completes
-  // the shell without another HTTP request. The concise line is gated on the
-  // middleware's debug flag (threaded via the descriptor) so it replaces the old
-  // full DOMException dump with one readable breadcrumb.
-  log(
-    `[ShellCache] capture attempt 1/2 for ${descriptor.key} aborted before shell completed (cold modules?) — retrying`,
-  );
-  await delay(retryDelayMs);
+  if (first.outcome === "refused") return "no-shell";
+  if (first.outcome === "stored" || first.outcome === "redirect") {
+    return first.outcome;
+  }
+  if (first.outcome === "expired") {
+    // The record attempt 1 read ran out mid-capture: a fresh match reads or
+    // renders a newer one. The whole task races SHELL_CAPTURE_TASK_HARD_CAP_MS,
+    // so a retry that could not finish inside it (barrier + captureTimeout)
+    // is not started.
+    const retryBudgetMs =
+      SHELL_CAPTURE_TASK_HARD_CAP_MS - (performance.now() - taskStartedAt);
+    const retryNeedsMs =
+      SHELL_CAPTURE_WRITE_BARRIER_MS +
+      (descriptor.captureTimeout ?? SHELL_CAPTURE_MAX_WAIT_MS);
+    if (retryBudgetMs < retryNeedsMs) {
+      return expiredTerminal(first.stats, "no time was left to retry");
+    }
+  } else {
+    // Attempt 1 ran out of ppr.captureTimeout (a cause is recorded): its
+    // handlers may still be running (a match is not cancellable), and a retry
+    // would start the same work beside them. A cold-module abort, the retry's
+    // reason, ends well inside the deadline.
+    if (first.stats.noShellCause !== undefined) {
+      warnNullCaptureOnce(key, false, first.stats);
+      return "no-shell";
+    }
+    // Attempt 1 produced no usable shell. Retry ONCE in place — the first
+    // attempt warmed the dev transform graph / cold worker, so attempt 2
+    // typically completes the shell without another HTTP request.
+    await delay(retryDelayMs);
+  }
+
+  // The retry is the last attempt, so none of its outcomes is retried: an
+  // `expired` retry is terminal like a no-shell one, not handed back to the
+  // scheduler (which would neither back the key off nor warn).
   const second = await timedAttempt(2);
-  if (second === "refused") return "no-shell";
-  if (second !== "no-shell") return second;
+  if (second.outcome === "expired") {
+    return expiredTerminal(
+      second.stats,
+      first.outcome === "expired" ? "twice in a row" : "on the in-place retry",
+    );
+  }
+  if (second.outcome === "refused") return "no-shell";
+  if (second.outcome !== "no-shell") return second.outcome;
 
   // Both attempts came back with no usable shell. Cold-start would have healed by
   // now, so the eternal-MISS structural shape (a boundary-less live-loader read;
@@ -1331,23 +1578,177 @@ async function runShellCapture(
   // warn once per key. Ordering matters: because the retry
   // absorbs cold-start, cold-start routes almost never reach this warning. The
   // caller (scheduleShellCapture) reads this `no-shell` return to back the key off.
-  log(
-    `[ShellCache] capture attempt 2/2 for ${descriptor.key} aborted — giving up until next request`,
-  );
-  warnNullCaptureOnce(descriptor.key);
+  warnNullCaptureOnce(key, true, second.stats);
   return "no-shell";
 }
 
-/** Fold the capture's handle-liveness record into the entry flag (true | undefined). */
-function handlerLayerIsLive(
-  liveness: RequestContext["_shellCaptureHandleLiveness"],
-): true | undefined {
-  if (!liveness) return undefined;
-  return liveness.holes ||
-    liveness.pendingPushes > 0 ||
-    liveness.handlerInvokedLoader
-    ? true
-    : undefined;
+/**
+ * What the record-first step produced ({@link settleCaptureRecord}):
+ * - `record`: the doc record settled; `match` carries its fragments in place
+ *   of the handler layer's elements, so the capture's Flight payload is the
+ *   bytes every HIT replays.
+ * - `prerender`: the prerender store supplied the handler layer (a
+ *   Prerender route); its HIT tail replays the same build-time segments, so
+ *   the capture renders the match as is.
+ * - `timeout`: handler output did not settle within the capture budget.
+ * - `refused`: a deterministic refusal (a capture guard tripped, the route
+ *   opted out, or the handler output failed); the warning already fired.
+ */
+export type CaptureRecordOutcome =
+  | { kind: "record" | "prerender"; match: MatchResult }
+  | { kind: "timeout"; reason: string }
+  | { kind: "refused" };
+
+/**
+ * Record-first capture: the doc record is both the settle signal and the
+ * parity source.
+ *
+ * Writing the record Flight-serializes every non-loader segment
+ * (serializeSegments), which runs each handler's async server components and
+ * waits for every promise the handler output carries — the capture's "is the
+ * handler layer done" signal. Live-lane loader data is not in the record
+ * (loader segments are excluded and their masked promises never settle), so
+ * the wait never depends on a hole.
+ *
+ * The capture then renders its OWN Flight payload from the record's
+ * fragments (fragmentSegments, the function a HIT tail uses) instead of from
+ * the elements the match produced. Server components therefore render once
+ * per capture, inside the record's encode: before this, the capture's Flight
+ * render and the record's encode each ran them, so an uncached async
+ * component showed one value in the prelude and another on every HIT.
+ *
+ * Order, all bounded by the one capture deadline (`ppr.captureTimeout`):
+ * top-level handle promises, the handler pushes' nested promises, and the
+ * bake-lane loader containers settle first (the record encodes the handles
+ * a HIT restores, and its handle encode has its own 5s timeout that must
+ * never be the one that fires); then the capture's onResponse callbacks fire
+ * with a synthetic 200 (the implicit doc scope's cacheRoute, an explicit
+ * scope's own write), and the deferred writes settle.
+ */
+export async function settleCaptureRecord(
+  match: MatchResult,
+  derivation: CaptureContextDerivation,
+  capture: Pick<ShellCaptureDescriptor, "key">,
+  deadline: number,
+): Promise<CaptureRecordOutcome> {
+  const { derivedCtx, freshHandleStore } = derivation;
+  const recording = getRecordingStore(derivedCtx._cacheStore);
+
+  // Seal so handleStore.settled resolves once the tracked handlers settle:
+  // cacheRoute waits for it, and so does the capture's quiesce. It gates only
+  // on tracked handlers, not on deferred handle values
+  // (ctx.use(Handle).defer()), so a defer whose resolver depends on a masked
+  // loader never settles and the wait below runs into the deadline instead.
+  freshHandleStore.seal();
+  const loaderRecords = derivedCtx._shellCaptureLoaderRecords;
+  const settled = await raceDeadline(
+    Promise.all([
+      freshHandleStore.getData().then(resolveDeferredHandleValues),
+      derivation.handlerPushesSettled(),
+      loaderRecords && loaderRecords.size > 0
+        ? Promise.allSettled([...loaderRecords.values()])
+        : undefined,
+    ]).catch(() => undefined),
+    deadline,
+  );
+  // Past the deadline the record cannot settle in time: stop before its
+  // write starts (no encode for a capture that already failed).
+  if (!settled.done) {
+    if (refuseOnCaptureGuard(capture.key, derivedCtx))
+      return { kind: "refused" };
+    return { kind: "timeout", reason: HANDLER_OUTPUT_TIMEOUT_REASON };
+  }
+
+  const callbacks = derivedCtx._onResponseCallbacks?.splice(0) ?? [];
+  if (callbacks.length > 0) {
+    const synthetic = new Response(null, { status: 200 });
+    for (const cb of callbacks) {
+      try {
+        cb(synthetic);
+      } catch {
+        // A capture-time cache write that throws is degradation, not failure.
+      }
+    }
+  }
+  const drained = recording
+    ? await recording.settleWrites(Math.max(0, deadline - Date.now()))
+    : true;
+
+  // Capture guards first: a tripped guard usually also fails the record,
+  // and its own message names the cause.
+  if (refuseOnCaptureGuard(capture.key, derivedCtx)) return { kind: "refused" };
+
+  const docKey = derivedCtx._shellImplicitCache?.docKey;
+  const record =
+    recording && docKey !== undefined ? recording.getRecord(docKey) : undefined;
+  if (
+    !record ||
+    !Array.isArray(record.segments) ||
+    record.segments.length === 0
+  ) {
+    // Post-match serve-source truth (cache-lookup.ts tryPrerenderLookup).
+    if (derivedCtx._pprReplayPostMatchReason === "prerender-store") {
+      return { kind: "prerender", match };
+    }
+    if (!drained) {
+      return { kind: "timeout", reason: HANDLER_OUTPUT_TIMEOUT_REASON };
+    }
+    warnCaptureRefusedOnce(capture.key, NO_DOC_RECORD_REASON);
+    return { kind: "refused" };
+  }
+
+  // A handle encode that timed out stores "" (handle-snapshot.ts
+  // encodeHandleValue). With every handler push settled above, that only
+  // happens for a promise the walk does not reach (inside a Map, Set, or class
+  // instance), which never settles in time on a retry either.
+  if (!record.handles && recordSegmentsHaveHandles(record, freshHandleStore)) {
+    warnCaptureRefusedOnce(
+      capture.key,
+      "a handle value the handler pushed did not finish encoding into the doc " +
+        "record. A promise inside a Map, Set, or class instance is not awaited " +
+        "before the encode; push plain objects and arrays.",
+    );
+    return { kind: "refused" };
+  }
+
+  const { fragmentSegments } = await import("../cache/segment-codec.js");
+  const fragments = new Map(
+    (await fragmentSegments(record.segments)).map((s) => [s.id, s]),
+  );
+  return {
+    kind: "record",
+    match: {
+      ...match,
+      segments: match.segments.map((segment) => {
+        const fragment =
+          segment.type === "loader" ? undefined : fragments.get(segment.id);
+        return fragment
+          ? {
+              ...segment,
+              component: fragment.component,
+              layout: fragment.layout,
+              loading: fragment.loading,
+            }
+          : segment;
+      }),
+    },
+  };
+}
+
+/** Whether the handle store holds handler pushes for the record's segments. */
+function recordSegmentsHaveHandles(
+  record: CachedEntryData,
+  handleStore: HandleStore,
+): boolean {
+  for (const segment of record.segments) {
+    const id = segment?.metadata?.id;
+    if (id === undefined) continue;
+    const data = handleStore.getDataForSegment(id, true);
+    for (const name in data) {
+      if (data[name]!.length > 0) return true;
+    }
+  }
+  return false;
 }
 
 /**
@@ -1365,8 +1766,8 @@ function handlerLayerIsLive(
  *   - _requestTags: a fresh Set. The capture collects its OWN shell tags here —
  *     non-loader tags only, since loaders are masked — which is exactly the tag
  *     set a shell entry should be invalidatable by (loader tags belong to holes).
- *   - _transitionWhen: a fresh [] so the capture's transition gating is its own.
  *   - _shellCaptureRun: true — the switch loaders/cookies/headers guards read.
+ *   - _dynamic / dynamic(): an own latch the capture reads.
  *   - _metricsStore: undefined so the capture never appends to the foreground's
  *     (already-finalized) metrics.
  *   - _renderBarrier family: an own barrier wired to the fresh handle store
@@ -1379,6 +1780,8 @@ function handlerLayerIsLive(
  * capture guard is load-bearing). Middleware is NOT re-run: it already ran for the
  * triggering request, and the derived context inherits its post-middleware state
  * (guarding is serve-time; the shell is never served without the full chain).
+ * After the match, {@link settleCaptureRecord} writes the doc record and the
+ * capture renders from it.
  *
  * A FRESH context (and match/render) per attempt is what makes the retry sound:
  * the second attempt is a clean capture, not a resumption of the first.
@@ -1406,23 +1809,68 @@ async function attemptCapture(
   await settleTrackedBackgroundTasks(reqCtx, SHELL_CAPTURE_WRITE_BARRIER_MS);
   stats.barrierWaitMs = Math.round(performance.now() - barrierStart);
 
-  const { derivedCtx, freshHandleStore } = deriveShellCaptureContext(
+  const derivation = deriveShellCaptureContext(
     reqCtx,
     descriptor,
     descriptor.navigationOnly ? { request, url } : undefined,
   );
+  const { derivedCtx, freshHandleStore } = derivation;
+  // The capture generation starts before matching or any snapshot read
+  // (ShellCacheEntry.createdAt): a tag invalidated after it wins.
   const captureStartedAt = Date.now();
 
   return runWithRequestContext(derivedCtx, async () => {
-    const match = await ctx.router.match(request, { env });
+    // One deadline for the whole capture (see
+    // PartialPrerenderProps.captureTimeout): the match (handlers, and the
+    // loaders they await), then the record, then the prerender with what is
+    // left. A match that loses it keeps running (no abort signal), so the
+    // attempt records a cause and runShellCapture does not retry it.
+    const deadline =
+      Date.now() + (descriptor.captureTimeout ?? SHELL_CAPTURE_MAX_WAIT_MS);
+    const matched = await raceDeadline(
+      ctx.router.match(request, { env }),
+      deadline,
+    );
+    if (!matched.done) {
+      stats.noShellCause =
+        "the handlers (or a loader a handler awaits) did not return within " +
+        "ppr.captureTimeout";
+      return "no-shell";
+    }
+    const match = matched.value;
     // A route that redirects has no shell to capture — bail (no store write, no
     // retry: a redirect is deterministic).
     if (match.redirect) return "redirect";
 
     setRequestContextParams(match.params, match.routeName);
 
-    const payload = buildFullPayload(
+    const settleStart = performance.now();
+    const settled = await settleCaptureRecord(
       match,
+      derivation,
+      descriptor,
+      deadline,
+    );
+    stats.recordSettleMs = Math.round(performance.now() - settleStart);
+    if (
+      process.env.NODE_ENV !== "production" &&
+      settled.kind === "record" &&
+      stats.recordSettleMs >= SHELL_CAPTURE_BAKE_WARN_MS
+    ) {
+      warnBakeCostOnce(
+        descriptor.key,
+        "the handler output (promises it passes or pushes, async server components)",
+        stats.recordSettleMs,
+      );
+    }
+    if (settled.kind === "refused") return "refused";
+    if (settled.kind === "timeout") {
+      stats.noShellCause = settled.reason;
+      return "no-shell";
+    }
+
+    const payload = buildFullPayload(
+      settled.match,
       ctx,
       url,
       derivedCtx,
@@ -1446,15 +1894,23 @@ async function attemptCapture(
     // content (and tags propagated by async cache()/"use cache" reads) lands after
     // this synchronous construction point, so snapshotting here dropped it — the
     // shell-tag snapshot must sit behind the quiesce gate (issue #676).
-    return captureAndStoreShell(
+    const outcome = await captureAndStoreShell(
       ssrModule,
       flightStage.stream,
-      freshHandleStore,
       derivedCtx,
-      descriptor,
-      stats,
+      {
+        ...descriptor,
+        captureTimeout: Math.max(1, deadline - Date.now()),
+      },
       captureStartedAt,
+      stats,
     );
+    if (outcome === "no-shell" && Date.now() >= deadline) {
+      stats.noShellCause =
+        "the shell render did not finish within what ppr.captureTimeout left " +
+        `after the handler output settled (${stats.recordSettleMs}ms)`;
+    }
+    return outcome;
   });
 }
 
@@ -1463,13 +1919,20 @@ async function attemptCapture(
  * shared by BOTH shell producers: the runtime background capture
  * (attemptCapture, producer A) and the build-time prerender shell capture
  * (prerender/build-shell-capture.ts, producer B — issue #699). One
- * implementation so the capture semantics — the nested-thenable mask funnel,
- * handler-liveness bookkeeping, snapshot recording, the implicit doc-cache
- * scope — cannot drift between producers.
+ * implementation so the capture semantics — the handle push funnel (handler
+ * pushes settled, loader pushes masked), the capture guards, snapshot
+ * recording, the implicit doc-cache scope — cannot drift between producers.
  */
 export interface CaptureContextDerivation {
   derivedCtx: RequestContext;
   freshHandleStore: HandleStore;
+  /**
+   * Resolves once every handler handle push has settled at any depth of
+   * plain objects and arrays (top-level promise, then the promises nested
+   * in what it resolved to). The record-first step awaits it before the doc
+   * record encodes its handles, so that encode never races a pending value.
+   */
+  handlerPushesSettled: () => Promise<void>;
 }
 
 /**
@@ -1487,52 +1950,75 @@ export function deriveShellCaptureContext(
 ): CaptureContextDerivation {
   const freshHandleStore = createHandleStore();
   freshHandleStore.onError = reqCtx._handleStore.onError;
-  // Shape = liveness for handles, exactly as for bake-lane loader containers
-  // (mask-nested.ts): nested thenables in a pushed handle container are
-  // per-request by declaration, so the CAPTURE's copy masks them — the
-  // consuming boundary postpones as a hole regardless of settle timing,
-  // instead of a fast-settling nested value baking into the shared shell. A
-  // TOP-LEVEL promise push keeps its documented bake contract (awaited
-  // pre-SSR, gate held open for it), but the container it RESOLVES to gets
-  // the same nested masking. Wrapping THIS store's push is the single funnel:
-  // the store exists only for this capture attempt, so every push wrapper
-  // (setupLoaderAccess, createUseFunction, prerender) inherits the policy and
-  // the foreground store is untouched.
-  // Shell fast path bookkeeping on the same funnel:
-  //  - handleLiveness: a nested thenable in a push made OUTSIDE a DSL loader
-  //    scope (attribution read synchronously at push time — handler bodies,
-  //    handler-invoked ctx.use(loader) callbacks, defers) declares
-  //    handler-layer per-request data. Its mask is a hole only a handler
-  //    re-run can fill, so the entry must not serve handler-free
-  //    (ShellCacheEntry.handlerLiveHoles). Still-pending top-level handler
-  //    pushes at the putShell barrier count too — their liveness is unknowable.
-  //  - loader-push tag: DSL-loader pushes re-run fresh on every HIT, so their
-  //    captured values must NOT enter a segment record's handle snapshot
-  //    (replay would duplicate the fresh push, and their masked nested
-  //    promises would stall the Flight handle encode to its timeout). The
-  //    store tags them by array position (HandleStore.push loaderPush), which
-  //    covers primitives, and only the captureHandles cache-write call site
-  //    excludes tagged pushes — every other getDataForSegment consumer (the
-  //    render-barrier snapshot, prerender) sees every push. Unflagged loaders
-  //    never execute at capture; the tagged pushes come from loaders an
-  //    ssr:false loader awaits via ctx.use and from loader-cache replays
-  //    (loader-cache.ts replayLoaderHandles), both re-run on a HIT.
-  //    EXCEPTION — bake-lane { ssr: false } loaders: they execute at capture
-  //    (fresh.ts awaits them), their pushes are in the captured HTML (<head>
-  //    title/meta, useHandle echoes), and the stored snapshot carries the same
-  //    values so a HIT's handle data is guaranteed to match its own prelude.
-  //    They still re-run on every HIT (resolveLoaderData, loader-cache.ts), so
-  //    each kept push carries its loader as `owner` (HandleStore.push): the
-  //    record stores it (CachedEntryData.handleOwners), the HIT restores it
-  //    through pushReplayed, and the re-run's live pushes replace the
-  //    restored copies in place. Only settled, thenable-free pushes
-  //    qualify — a deferred (thenable) push or one with masked nested promises
-  //    keeps the exclusion so the handle encode cannot stall on a
-  //    never-resolving mask.
-  const handleLiveness = {
-    holes: false,
-    pendingPushes: 0,
-    handlerInvokedLoader: false,
+  // The capture handle store's push is the single funnel every push wrapper
+  // (setupLoaderAccess, createUseFunction, prerender) goes through; the store
+  // exists only for this capture attempt, so the foreground store is
+  // untouched. Two lanes:
+  //  - HANDLER pushes (outside a DSL loader scope: handler bodies, handler-
+  //    invoked ctx.use(loader) bodies, defers) are handler output, baked like
+  //    everything else the handler layer produces. They pass through
+  //    unmasked; settleHandlerPush tracks each one so the record-first step
+  //    (settleCaptureRecord) can wait for its promises, top-level and nested,
+  //    before the doc record encodes the handles a HIT replays. A route
+  //    cache() record's restore (handle-snapshot.ts restoreHandles) lands
+  //    here too: a value it restores through pushReplayed keeps that loader
+  //    as owner, so a HIT restores it as that loader's (pushRestored).
+  //  - DSL-LOADER pushes. Only bake-lane { ssr: false } loaders and the
+  //    loaders they await via ctx.use execute at capture (live loaders are
+  //    masked), their pushes are in the captured HTML (<head> title/meta,
+  //    useHandle echoes), and a HIT does not run a promise-free bake-lane
+  //    loader (loader-cache.ts), so the stored record carries them: each
+  //    settled, thenable-free push from a loader body keeps that loader as
+  //    `owner` (HandleStore.push), the record stores it
+  //    (CachedEntryData.handleOwners), and the HIT restores it through
+  //    pushRestored. Those copies stand: a promise-carrying bake-lane loader
+  //    that runs on the HIT reads the store, so its settled pushes (and those
+  //    replayed inside its body) are dropped and only its thenable ones are
+  //    added. A loader the route also runs on the live lane is a hole: its
+  //    live run replaces its copies (pushReplayed, #936), those of the
+  //    dependencies it awaits included (they are credited to it). Nested
+  //    thenables stay masked (the promise shape is the liveness
+  //    declaration, mask-nested.ts). A deferred (thenable) push,
+  //    one with masked nested promises, or one outside a loader body (a
+  //    loader-cache replay names its loader: pushReplayed below) stays
+  //    tagged (HandleStore.push loaderPush) so the
+  //    handle encode cannot stall on a never-resolving mask; only the
+  //    captureHandles cache-write call site excludes tagged pushes, and the
+  //    loader records then carry `runs: 1` so a HIT runs those bodies for
+  //    them.
+  const handlerPushSettles: Promise<void>[] = [];
+  // A replay (a loader-cache HIT, loader-cache.ts replayLoaderHandles, or a
+  // route cache() record's owned values, restoreHandles) re-pushes a loader's
+  // recorded values through pushReplayed, which calls push() outside any
+  // loader body: name that loader for the funnel so the record keeps them
+  // under it too.
+  let replayOwner: string | undefined;
+  // The live-lane loader whose body a push is made in, at any depth, unless
+  // a bake-lane loader's body is nearer (createMatchContextForFull sets the
+  // lanes before any loader runs).
+  // A replay of a live-lane loader's push (a "use cache" or loader cache()
+  // hit a recapture makes inside a bake-lane body) is that hole's too.
+  const liveLaneOwner = (): string | undefined => {
+    const lanes = derivedCtx._shellCaptureLoaderLanes;
+    if (!lanes) return undefined;
+    return (
+      findEnclosingLoaderBody(
+        (id) => lanes.get(id) === "live",
+        (id) => lanes.get(id) === "bake",
+      ) ??
+      (replayOwner !== undefined && lanes.get(replayOwner) === "live"
+        ? replayOwner
+        : undefined)
+    );
+  };
+  const rawPushReplayed = freshHandleStore.pushReplayed.bind(freshHandleStore);
+  freshHandleStore.pushReplayed = (handleName, segmentId, value, loaderId) => {
+    replayOwner = loaderId;
+    try {
+      rawPushReplayed(handleName, segmentId, value, loaderId);
+    } finally {
+      replayOwner = undefined;
+    }
   };
   const rawCapturePush = freshHandleStore.push.bind(freshHandleStore);
   freshHandleStore.push = (
@@ -1540,49 +2026,63 @@ export function deriveShellCaptureContext(
     segmentId: string,
     value: unknown,
   ) => {
-    const pushedInLoaderScope = isInsideLoaderScope();
-    // Single walk: the mask reports whether it masked any nested thenable
-    // (the liveness declaration) while building the capture copy.
+    if (!isInsideLoaderScope()) {
+      handlerPushSettles.push(settleNestedThenables(value));
+      rawCapturePush(handleName, segmentId, value, false, replayOwner);
+      return;
+    }
     let maskedNestedThenable = false;
-    const maskWithLiveness = (v: unknown): unknown => {
+    const mask = (v: unknown): unknown => {
       const report: MaskReport = { thenable: false };
       const masked = maskNestedContainerThenables(v, undefined, report);
-      if (report.thenable) {
-        maskedNestedThenable = true;
-        if (!pushedInLoaderScope) handleLiveness.holes = true;
-      }
+      if (report.thenable) maskedNestedThenable = true;
       return masked;
     };
     let masked: unknown;
-    let loaderPush = pushedInLoaderScope;
+    let loaderPush = true;
     let owner: string | undefined;
     if (isThenable(value)) {
-      if (!pushedInLoaderScope) {
-        handleLiveness.pendingPushes++;
-        const settle = () => handleLiveness.pendingPushes--;
-        value.then(settle, settle);
-      }
       // Deferred (thenable) loader pushes always keep the tag — the
-      // bake-lane carve-out below is for settled values only.
-      masked = value.then(maskWithLiveness);
+      // carve-out below is for settled values only.
+      masked = value.then(mask);
     } else {
-      masked = maskWithLiveness(value);
-      if (loaderPush && !maskedNestedThenable) {
-        // Bake-lane { ssr: false } loader pushes are shell material (see the
-        // funnel comment above): untagged, the stored snapshot keeps them
-        // when settled and thenable-free; everything else stays tagged.
-        const bodyLoaderId = getCurrentLoaderBodyId();
-        loaderPush =
-          bodyLoaderId === undefined ||
-          derivedCtx._awaitBeforeFlushLoaderIds?.has(bodyLoaderId) !== true;
+      masked = mask(value);
+      if (!maskedNestedThenable) {
+        // A settled, thenable-free push from a loader body is shell
+        // material (see the funnel comment above): only bake-lane loaders
+        // and the loaders they await run at capture, and a HIT does not run
+        // a promise-free bake-lane loader (loader-cache.ts), so the record
+        // keeps the push under the loader that made it. A push under a
+        // live-lane loader's body, at any depth, is that hole's output: it
+        // is credited to the hole, whose live run replaces it on a HIT and
+        // a navigation. The first loader around the push that the route
+        // registers decides: a bake-lane one keeps the push under the
+        // innermost body, and a dependency on neither lane is walked past. A
+        // replay of a hole's push is that hole's, unless a live-lane body
+        // around it takes it first.
+        const bodyLoaderId =
+          liveLaneOwner() ?? getCurrentLoaderBodyId() ?? replayOwner;
+        loaderPush = bodyLoaderId === undefined;
         if (!loaderPush) owner = bodyLoaderId;
       }
     }
+    // A push the record cannot keep reaches a HIT only from a live run of
+    // its loader, so the loader records ask for one (runs: 1).
+    if (loaderPush) derivedCtx._shellCaptureUnrecordedLoaderPush = true;
     rawCapturePush(handleName, segmentId, masked, loaderPush, owner);
   };
 
+  // The capture reuses the record keys its request resolved (CacheScope
+  // resolveKeyFrom), read through the prototype: the map must exist on the
+  // request before the derivation, or the capture would start its own and
+  // run key() under the capture guard.
+  reqCtx._resolvedCacheKeys ??= new Map();
   const derivedCtx: RequestContext = Object.assign(Object.create(reqCtx), {
     _handleStore: freshHandleStore,
+    // The capture notes the route records it reads or writes itself; the
+    // foreground's (a partial request's `partial:` record, say) are not the
+    // ones this shell is captured from.
+    _routeRecordWindow: undefined,
   });
   if (identity) {
     derivedCtx.request = identity.request;
@@ -1609,11 +2109,20 @@ export function deriveShellCaptureContext(
   // the whole capture snapshot in memory. Capture registrations die with this
   // context; module-singleton stores stay registered by normal renders.
   derivedCtx._explicitTaggedStores = new Set();
-  derivedCtx._transitionWhen = [];
   // Own list: the capture's render errors refuse the capture only, and the
   // foreground's never reach it.
   derivedCtx._renderErrors = [];
   derivedCtx._shellCaptureRun = true;
+  // Own dynamic() latch. The inherited method writes the FOREGROUND context
+  // (its closure), which already served, and nothing read it for a runtime
+  // capture: handler code that opts out after an await (a handler promise the
+  // capture now waits for) must refuse THIS capture instead
+  // (settleCaptureRecord and captureAndStoreShell read _dynamic). The ppr
+  // header latch is left alone: a capture's response is never sent.
+  derivedCtx._dynamic = false;
+  derivedCtx.dynamic = (): void => {
+    derivedCtx._dynamic = true;
+  };
   // Own-property reset: an inherited flag would make serializeSegments store
   // a double-encoded fragment. No current arming site reaches a capture
   // render (kept as defense-in-depth for a future one).
@@ -1624,32 +2133,32 @@ export function deriveShellCaptureContext(
   // foreground rango.request span ended (orphan spans in the trace).
   // _tracing is otherwise inherited through Object.create(reqCtx).
   derivedCtx._tracing = undefined;
-  // Bake-lane loader containers (loaders on entries with no renderable
-  // loading() execute during capture — docs/design/loader-container-bake.md).
-  // resolveLoaderData registers each container promise here; the drain in
-  // captureAndStoreShell elides + pins them into the snapshot's loader family.
+  // Bake-lane (`ssr: false`) loader containers, which execute during capture
+  // (docs/design/loader-container-bake.md). resolveLoaderData registers each
+  // container promise here; settleCaptureRecord waits for them, and the drain
+  // in captureAndStoreShell elides + pins them into the snapshot's loader
+  // family.
   derivedCtx._shellCaptureLoaderRecords = new Map();
-  // Own onResponse list so the capture's match-middleware callbacks (the ring-3
-  // segment cache write registers here) are ISOLATED from the foreground's shared
-  // array AND can be fired by captureAndStoreShell. The segment write is gated
-  // behind onResponse, which the capture never triggers (it builds no Response) —
-  // without firing it, a ring-3 cache() MISS at capture renders fresh into the
-  // prelude but is never written, so it is never recorded and drifts on a HIT.
+  // Own onResponse list so the capture's match-middleware callbacks (the doc
+  // record registers here) are ISOLATED from the foreground's shared array AND
+  // can be fired by settleCaptureRecord. The segment write is gated behind
+  // onResponse, which the capture never triggers (it builds no Response):
+  // without the synthetic fire, no doc record is written.
   derivedCtx._onResponseCallbacks = [];
 
-  // Capture data snapshot: read every cache-store hit/write through a recording
-  // wrapper on the DERIVED context's store (own property, so the shared
-  // reqCtx._cacheStore is untouched — the snapshot is per-capture). Its records
-  // ride inside the ShellCacheEntry so a HIT can reproduce the shell's cached
-  // content byte-identically. See cache/shell-snapshot.ts and the design doc.
+  // Capture data snapshot: route the capture's cache-store calls through a
+  // recording wrapper on the DERIVED context's store (own property, so the
+  // shared reqCtx._cacheStore is untouched — the snapshot is per-capture). It
+  // records the doc segment record, which rides inside the ShellCacheEntry
+  // with the bake-lane loader pins; no cache read is recorded. See
+  // cache/shell-snapshot.ts and the design doc.
   //
-  // Cache writes are deferred (waitUntil): a MISS-at-capture value's setItem/set
-  // — hence its record — would otherwise land after the shell quiesces. Override
-  // the derived context's waitUntil to COLLECT those write promises (still
-  // forwarding to the parent so the write persists and the worker stays alive),
-  // then captureAndStoreShell awaits them before draining. Reads that HIT are
-  // recorded synchronously during the render and need none of this.
-  derivedCtx._shellCaptureHandleLiveness = handleLiveness;
+  // Cache writes are deferred (waitUntil): the doc record's write would
+  // otherwise land after the match returns. Override the derived context's
+  // waitUntil to COLLECT those write promises (still forwarding to the parent
+  // so the write persists and the worker stays alive), then
+  // settleCaptureRecord and captureAndStoreShell await them before reading
+  // the record and draining.
   if (reqCtx._cacheStore) {
     const recordingStore = new RecordingShellStore(reqCtx._cacheStore);
     derivedCtx._cacheStore = recordingStore;
@@ -1658,12 +2167,13 @@ export function deriveShellCaptureContext(
       recordingStore.trackWrite(p);
       reqCtx.waitUntil(() => p);
     };
-    // Shell fast path (capture side): the implicit doc-cache scope makes the
+    // The doc record (capture side): the implicit doc-cache scope makes the
     // capture's match write ALL matched non-loader segments as one doc-keyed
     // segment record — into the snapshot only (SnapshotOnlySegmentStore), so
     // the record dies with the shell entry and the next capture's lookup
-    // still misses (handlers re-run on recapture). Routes deriving their own
-    // cache scope are untouched (resolveShellImplicitCacheScope).
+    // still misses (handlers re-run on recapture). A route deriving its own
+    // cache() scope keeps it, and recordShellCaptureDocRecord (cache-store.ts)
+    // writes the same record for it.
     derivedCtx._shellImplicitCache = {
       ttl: descriptor.ttl,
       swr: descriptor.swr,
@@ -1672,17 +2182,26 @@ export function deriveShellCaptureContext(
     };
   }
 
-  return { derivedCtx, freshHandleStore };
+  return {
+    derivedCtx,
+    freshHandleStore,
+    handlerPushesSettled: () =>
+      Promise.all(handlerPushSettles).then(() => undefined),
+  };
 }
 
 /**
- * Seal handles, derive the quiesce signal, prerender + abort via the SSR module's
- * captureShellHTML, and store the result. Returns the attempt outcome (the caller
- * owns retry/warn decisions — this function no longer warns). Never throws out of
- * the store write: a failed putShell is routed through reportCacheError so the
- * background task stays best-effort, and the attempt still counts as `stored` (the
- * capture worked; only the store I/O failed). `ssrModule.captureShellHTML` MUST be
- * present (eligibility is checked before scheduling).
+ * Derive the quiesce signal, prerender + abort via the SSR module's
+ * captureShellHTML, and store the result. Runs after settleCaptureRecord (both
+ * producers), which sealed the capture's handle store (`reqCtx._handleStore`)
+ * and waited for everything the shell bakes. Returns the attempt outcome (the
+ * caller owns retry/warn decisions). Never throws out of the store write: a
+ * failed putShell is routed through reportCacheError so the background task
+ * stays best-effort, and the attempt still counts as `stored` (the capture
+ * worked; only the store I/O failed). `ssrModule.captureShellHTML` MUST be
+ * present (eligibility is checked before scheduling). `captureStartedAt` is the
+ * capture generation's start, stamped before the match (ShellCacheEntry
+ * .createdAt).
  *
  * A `no-shell` result from captureShellHTML is the only retryable outcome. Every
  * captureShellHTML error propagates to reportCacheError and is NOT retried. The
@@ -1692,117 +2211,45 @@ export function deriveShellCaptureContext(
 async function captureAndStoreShell(
   ssrModule: SSRModule,
   rscStream: ReadableStream<Uint8Array>,
-  handleStore: HandleStore,
   reqCtx: RequestContext<any>,
   capture: ShellCaptureDescriptor,
-  stats?: CaptureAttemptStats,
-  captureStartedAt: number = Date.now(),
+  captureStartedAt: number,
+  stats: CaptureAttemptStats = {},
 ): Promise<Exclude<CaptureAttemptOutcome, "redirect">> {
   const captureShellHTML = ssrModule.captureShellHTML!;
 
-  // Seal the handle store so the payload's handles generator (resolvedHandleStream
-  // -> handleStore.stream()) converges and completes even though masked loaders
-  // never resolve. handleStore.settled gates ONLY on tracked HANDLER promises
-  // (handleStore.track, via trackHandler) — NOT on deferred handle VALUES pushed
-  // through ctx.use(Handle).defer(), which are plain pushed promises. So seal()
-  // does not reject or hang on outstanding defers: settled resolves once the
-  // handlers settle, and each deferred slot resolves on its own createDeferred
-  // timeout (defer.ts, default 10s) or when its resolver fires. A defer whose
-  // resolver depends on a masked loader can never fire, so it stays pending until
-  // that 10s timeout — longer than maxWaitMs (5s). At the abort the handles
-  // generator has not yielded, SsrRoot suspends at the root (consumeAsyncGenerator
-  // sits above every boundary), the prelude comes back trivial, and
-  // captureShellHTML's sanity gate returns null: the designed fail-safe no-op, not
-  // an error. This mirrors the matchForPrerender (router/prerender-match.ts)
-  // seal+settled regime, which also excludes loaders. See
-  // docs/design/ppr-shell-resume.md ("Loaders and handles").
-  handleStore.seal();
-
-  // Handles contract, shell half ("nesting = liveness"): TOP-LEVEL pushed handle
-  // promises are BAKED into the shell — resolvedHandleStream awaits them before
-  // the payload's handles row emits. A pushed promise with real latency would lose
-  // the byte-quiet race (the pending handles row emits no bytes, the gate freezes,
-  // the row is dropped, SsrRoot suspends at the root), so the gate is HELD open
-  // until the same await completes: handlesBaked mirrors resolvedHandleStream's
-  // resolution (getData waits the tracked-handler barrier; resolveDeferredHandleValues
-  // awaits the top-level thenables). NESTED promises inside pushed containers are
-  // shallow-skipped by isThenable and never hold the gate — they stay holes.
-  // Bounded by maxWaitMs like every quiesce input (a defer hanging on a masked
-  // loader still ends in the sanity-gate refusal).
-  const handlesBaked = handleStore.getData().then(resolveDeferredHandleValues);
-  // Bake-lane loader containers hold the gate the same way (loader-container-
-  // bake): a boundary-less container with real latency (a 100ms layout loader)
-  // would otherwise lose the 2-hop byte-quiet race — the pending loaderData row
-  // emits no bytes, the gate freezes, and the awaiting tree pins above <body>.
-  // The records map is fully populated before this point (loader promises are
-  // created during the capture's match()), so the hold covers every bake-lane
-  // container. allSettled: a REJECTED container releases the hold (the drain
-  // below refuses the capture); nested promises INSIDE a container never hold
-  // the gate — they stay holes. Bounded by maxWaitMs like every quiesce input.
-  const loaderRecordsForHold = reqCtx._shellCaptureLoaderRecords;
-  const holdUntil =
-    loaderRecordsForHold && loaderRecordsForHold.size > 0
-      ? Promise.allSettled([handlesBaked, ...loaderRecordsForHold.values()])
-      : handlesBaked;
-  // Bake-cost attribution: record how long each bake source held the gate,
-  // measured from capture start. Side-channel observers only — holdUntil and
-  // its consumers are untouched, and a rejected source is recorded the same
-  // (allSettled swallows it; the drain below owns the refusal). Folded into
-  // stats.bakeWaitMs (+ a once-per-key dev warning) after a successful
-  // capture; on a refusal the other warnings own the story.
-  const bakeStart = performance.now();
-  const bakeWaits: { source: string; ms: number }[] = [];
-  const observeBake = (source: string, promise: Promise<unknown>): void => {
-    const record = (): void => {
-      bakeWaits.push({
-        source,
-        ms: Math.round(performance.now() - bakeStart),
-      });
-    };
-    promise.then(record, record);
-  };
-  observeBake("top-level pushed handle promises", handlesBaked);
-  if (loaderRecordsForHold) {
-    for (const [loaderId, promise] of loaderRecordsForHold) {
-      observeBake(`bake-lane segment loader "${loaderId}"`, promise);
-    }
-  }
-  const gate = gateFlightForCapture(rscStream, undefined, holdUntil);
+  const gate = gateFlightForCapture(rscStream);
   // Quiesce = handles settled AND the Flight shell rows went task-quiet. Either
   // half stalling is bounded by captureShellHTML's maxWaitMs.
-  const quiesce = Promise.all([handleStore.settled, gate.quiesce]).then(
+  const quiesce = Promise.all([reqCtx._handleStore.settled, gate.quiesce]).then(
     () => {},
   );
 
-  // Deterministic identity-guard refusal, checked at BOTH exits below: the
-  // guard error either rejects the prerender itself (boundary-less segment —
-  // lands in the catch) or is swallowed into per-loader error UI (the render
-  // completes — caught after the try). One helper so the message and the
-  // "refused" mapping cannot drift between the two sites.
-  const refuseOnGuardTrip = (): "refused" | undefined => {
-    const fnName = reqCtx._shellCaptureGuardTripped;
-    if (!fnName) return undefined;
-    // Name the recorded source instead of hardcoding a lane. Under the
-    // consumption-lane rule, handler-INVOKED loader bodies are exempt from
-    // the guard (their value is a baked shared copy, mirroring cache()), so a
-    // trip can only come from a bake-lane SEGMENT loader or from non-loader
-    // handler/render code — the old blanket "bake-lane loader" attribution
-    // sent a live-lane debugging session down the wrong lane (issue #672).
-    const loaderId = reqCtx._shellCaptureGuardTrippedLoaderId;
-    const origin = loaderId
-      ? `segment loader "${loaderId}"`
-      : "handler/render code (no loader body was executing)";
-    warnCaptureRefusedOnce(
-      capture.key,
-      `${origin} called ${fnName}() during capture; identity must not bake into the shared shell. ` +
-        "Segment loader: drop ssr: false and read it under loading() or an inline <Suspense> " +
-        "(a nested promise does not help: its body still runs at capture). Handler/render " +
-        "code: read it in a live loader and consume it with useLoader. Exception: " +
-        "await ctx.use(loader) in a HANDLER bakes as a capture-time copy.",
-      PPR_LANE_HINT,
-    );
-    return "refused";
-  };
+  // Deterministic capture-guard refusal (refuseOnCaptureGuard), checked at
+  // BOTH exits below: the guard error either rejects the prerender itself
+  // (boundary-less segment — lands in the catch) or is swallowed into
+  // per-loader error UI (the render completes — caught after the try).
+  const refuseOnGuardTrip = (): "refused" | undefined =>
+    refuseOnCaptureGuard(capture.key, reqCtx) ? "refused" : undefined;
+
+  // Dev diagnostics for a no-shell attempt (warnNullCaptureOnce): the stacks of
+  // the tasks React reports as still pending at the capture's abort. React's
+  // componentStack is computed on read, so it is read only while there is room.
+  let pendingStacks: string[] | undefined;
+  let onAbortedTask:
+    | ((errorInfo: { componentStack?: string } | undefined) => void)
+    | undefined;
+  if (process.env.NODE_ENV !== "production") {
+    const stacks: string[] = [];
+    pendingStacks = stacks;
+    onAbortedTask = (errorInfo) => {
+      if (stacks.length >= MAX_PENDING_STACKS) return;
+      const componentStack = errorInfo?.componentStack;
+      if (componentStack && !stacks.includes(componentStack)) {
+        stacks.push(componentStack);
+      }
+    };
+  }
 
   try {
     // captureShellHTML CONSUMES the (gated) stream — it is not also SSR'd.
@@ -1821,6 +2268,7 @@ async function captureAndStoreShell(
           onError: (error) => {
             reqCtx._renderErrors?.push(error);
           },
+          onAbortedTask,
         }),
       );
     } catch (error) {
@@ -1848,71 +2296,24 @@ async function captureAndStoreShell(
     if (refused) return refused;
 
     if (result === null) {
+      stats.pendingStacks = pendingStacks;
       return "no-shell";
     }
-    if (stats) stats.preludeBytes = result.prelude.length;
-
-    // Every bake source has settled by here (quiesce gates on holdUntil).
-    // Surface the slowest one: sub-ms settles are noise, threshold-crossers
-    // get the dev warning with the remedy ladder.
-    let slowestBake: { source: string; ms: number } | undefined;
-    for (const wait of bakeWaits) {
-      if (!slowestBake || wait.ms > slowestBake.ms) slowestBake = wait;
-    }
-    if (slowestBake && slowestBake.ms > 0) {
-      if (stats) stats.bakeWaitMs = slowestBake.ms;
-      if (
-        process.env.NODE_ENV !== "production" &&
-        slowestBake.ms >= SHELL_CAPTURE_BAKE_WARN_MS
-      ) {
-        warnBakeCostOnce(capture.key, slowestBake.source, slowestBake.ms);
-      }
-    }
-
-    // Store per the flag's key/ttl/swr/tags, into the flag's store: the middleware
-    // threads the SAME store it resolved for its getShell read (options.store ??
-    // _cacheStore), so a store-attached middleware writes captures where it reads
-    // them. The _cacheStore fallback covers a flag armed without a store (tests).
-    // reactVersion is read from the same React.version import the middleware
-    // validates reads against, so capture and serve always agree.
-    // Fire the capture's isolated onResponse callbacks with a synthetic 200 so
-    // the ring-3 segment cache write (cacheScope.cacheRoute, registered via
-    // onResponse by the cache-store match-middleware and gated on a 200) runs
-    // DURING capture, routed through the recording store. The foreground path
-    // never fires for the capture — it builds no Response — so without this a
-    // cache() SEGMENT that MISSED at capture would be rendered fresh into the
-    // prelude yet never written, hence never recorded, and would drift on a HIT
-    // (an item-family "use cache" write already runs inline during the render, so
-    // it needs none of this; only segment writes are onResponse-gated). The
-    // derived context's own _onResponseCallbacks holds only capture match-
-    // middleware callbacks (HTTP middleware never runs for a capture), so firing
-    // them is safe. Best-effort: a throwing callback must not fail the capture.
-    const responseCallbacks = reqCtx._onResponseCallbacks;
-    if (responseCallbacks && responseCallbacks.length > 0) {
-      const synthetic = new Response(null, { status: 200 });
-      for (const cb of responseCallbacks) {
-        try {
-          cb(synthetic);
-        } catch {
-          // A capture-time cache write that throws is degradation, not failure.
-        }
-      }
-    }
-
-    // Drain the capture data snapshot from the recording store on the derived
-    // context. Await the deferred cache writes first so a MISS-at-capture value
-    // (setItem/set scheduled under waitUntil, including the segment write just
-    // fired) is pinned, not just read-hits. When no recording store is installed
-    // (unit tests that call this directly), there is simply no snapshot.
+    stats.preludeBytes = result.prelude.length;
+
+    // Drain the doc record from the recording store on the derived context.
+    // The capture's own deferred cache writes ("use cache" and loader
+    // cache() misses made while it rendered) settle first, bounded, so the
+    // next HIT's holes find them in the store. When no recording store is
+    // installed (unit tests that call this directly), the snapshot starts
+    // empty.
     const recording = getRecordingStore(reqCtx._cacheStore);
-    let snapshot: ShellSnapshotRecord[] | undefined;
+    let snapshot: ShellSnapshotRecord[] = [];
     if (recording) {
       const settleStart = performance.now();
       await recording.settleWrites(SHELL_SNAPSHOT_WRITE_SETTLE_MS);
-      if (stats) {
-        stats.writeSettleMs = Math.round(performance.now() - settleStart);
-      }
-      snapshot = recording.drainSnapshot();
+      stats.writeSettleMs = Math.round(performance.now() - settleStart);
+      snapshot = recording.drainSnapshot() ?? [];
     }
 
     // Pin the bake-lane loader containers (loader family). Settled containers
@@ -1934,6 +2335,8 @@ async function captureAndStoreShell(
       let serializeContainer:
         | typeof import("../cache/segment-codec.js").serializeResult
         | undefined;
+      // Capture-wide, read once: every record of this snapshot agrees.
+      const runs: 0 | 1 = reqCtx._shellCaptureUnrecordedLoaderPush ? 1 : 0;
       for (const [segmentKey, containerPromise] of loaderRecords) {
         const elided = await elideLoaderContainer(containerPromise);
         if (elided.state === "rejected") {
@@ -1979,14 +2382,18 @@ async function captureAndStoreShell(
             reqCtx._renderErrors?.push(error);
           });
           if (serialized !== null) {
-            (snapshot ??= []).push({
+            snapshot.push({
               family: "loader",
               key: segmentKey,
               // The hole bit rides with the record so the HIT overlay knows
               // without rescanning whether the pin can resolve immediately
               // (holes: 0) or must wait for the fresh run's live promises
               // (holes: 1). See ShellSnapshotLoaderValue.
-              value: { value: serialized, holes: elided.hasHole ? 1 : 0 },
+              value: {
+                value: serialized,
+                holes: elided.hasHole ? 1 : 0,
+                runs,
+              },
             });
           }
         } catch {
@@ -2006,50 +2413,114 @@ async function captureAndStoreShell(
     const renderErrors = reqCtx._renderErrors;
     if (renderErrors && renderErrors.length > 0) throw renderErrors[0];
 
-    // Snapshot size guard (issue #651): the snapshot duplicates every pinned
-    // cache value inside the shell entry, so a page over a large cache()
-    // segment can push the stored envelope toward store value limits (KV caps
-    // a value at 25 MiB) with no signal — the kv.put rejects deep inside
-    // waitUntil. Measure the serialized snapshot (UTF-8 bytes of the JSON that
-    // rides in the envelope) AFTER the loader family is appended, and over the
-    // cap store the shell WITHOUT it: pinned reads then fall back to the live
-    // store on a HIT (documented drift — hydration repairs a mismatch
-    // client-side, the pre-snapshot behavior), which beats losing the whole
-    // entry to a store-side write rejection. Reported once per key.
-    if (snapshot && snapshot.length > 0) {
-      const snapshotBytes = SNAPSHOT_BYTE_ENCODER.encode(
-        JSON.stringify(snapshot),
-      ).length;
-      if (stats) stats.snapshotBytes = snapshotBytes;
+    // Store only what a HIT reads (issue #941): the doc record and, for a
+    // document entry, the bake-lane loader pins. Before the size guards, so
+    // they measure what is stored.
+    const docKey = reqCtx._shellImplicitCache?.docKey;
+    let prunedRecords: string | undefined;
+    const { kept, pruned } = pruneShellSnapshot(
+      snapshot,
+      capture.navigationOnly === true,
+      docKey,
+    );
+    if (pruned.length > 0) {
+      prunedRecords = countSnapshotFamilies(pruned);
+      snapshot = kept;
+    }
+
+    // Snapshot size guard (issue #651): `maxSnapshotBytes` bounds the loader
+    // pins; over it they are dropped and the entry keeps its doc record, so
+    // every HIT still replays the handler layer (the pins' loaders then run
+    // on the HIT: documented drift, repaired client-side). The doc record is
+    // exempt: without it a HIT could not serve at all. The whole entry is
+    // bounded separately below, by the store's value limit.
+    if (snapshot.length > 0) {
+      const docRecord =
+        docKey !== undefined
+          ? snapshot.find((r) => r.family === "segment" && r.key === docKey)
+          : undefined;
+      const pins = docRecord
+        ? snapshot.filter((r) => r !== docRecord)
+        : snapshot;
+      const pinBytes =
+        pins.length > 0
+          ? SNAPSHOT_BYTE_ENCODER.encode(JSON.stringify(pins)).length
+          : 0;
+      stats.snapshotBytes = pinBytes;
       const cap = capture.maxSnapshotBytes ?? DEFAULT_PPR_MAX_SNAPSHOT_BYTES;
-      if (snapshotBytes > cap) {
-        warnSnapshotOverCapOnce(capture.key, snapshotBytes, cap);
-        snapshot = undefined;
-        if (stats) stats.snapshotSkipped = true;
+      if (pinBytes > cap) {
+        warnSnapshotOverCapOnce(capture.key, pinBytes, cap);
+        snapshot = docRecord ? [docRecord] : [];
+        stats.snapshotSkipped = true;
       }
     }
 
-    // Shell tags snapshot at the WRITE BARRIER, not at stream construction: by
-    // here the capture has quiesced and the deferred cache writes were awaited, so
-    // tags recorded AFTER an await in async shell content (and by async
-    // cache()/"use cache" reads propagating through recordRequestTags) are
-    // included — issue #676. Loaders are masked, so loader cache tags — which
-    // belong to the holes, not the shell — never execute during capture and cannot
-    // contribute. Union with the route's static ppr.tags (capture.tags); the
-    // collected set is authoritative, the option only adds what the render cannot
-    // know.
-    const collected = [...reqCtx._requestTags];
+    // settleCaptureRecord refused every capture without a doc record except a
+    // prerender-served one (the prerender store supplies its handler layer on
+    // every HIT), and the record survives the drain, the pruning and the size
+    // cap above.
+    const storedDocKey = hasDocRecord(snapshot, docKey) ? docKey : undefined;
+
+    // Shell tags: what the shell renders from, and nothing else. The handler
+    // layer is the doc record, whose tags are what its content recorded (the
+    // handlers, the server components its serialization rendered, the loaders
+    // they consumed, the handle values; cache-scope.ts collectRecordTags), or
+    // what a replayed route cache() record carried (recordSegmentTags). So a
+    // capture that rendered fresh and one that replayed the route's record
+    // store the same tags. Bake-lane loaders add theirs (SHELL_BAKE_TAG_OWNER):
+    // their data is in the shell, and no handler reads it. A live-lane loader
+    // never runs at capture, and one whose cache() config tags are recorded
+    // anyway is a hole's, so request-level tags are not the source. Read at
+    // the write barrier: the record settled and the deferred writes were
+    // awaited, so a tag recorded after an await (#676) is in. A capture
+    // without a doc record (the prerender store served its match) keeps the
+    // request-level set. Union with the route's static ppr.tags.
+    const docRecordValue = storedDocKey
+      ? (snapshot.find((r) => r.family === "segment" && r.key === storedDocKey)
+          ?.value as CachedEntryData | undefined)
+      : undefined;
+    const collected = docRecordValue
+      ? [
+          ...(docRecordValue.tags ?? []),
+          ...getSegmentTags(reqCtx, SHELL_BAKE_TAG_OWNER),
+        ]
+      : [...reqCtx._requestTags];
     const union = new Set<string>([...(capture.tags ?? []), ...collected]);
     const shellTags = union.size > 0 ? [...union] : undefined;
 
+    // Whole-entry guard: the prelude, postponed state, snapshot, and tags
+    // travel in one stored value. Over the store's limit (Cloudflare KV:
+    // 25 MiB) the write would fail inside waitUntil and every MISS would
+    // recapture, so refuse here (the key backs off) instead. Measured as the
+    // stores write it (estimateShellEntryBytes): the postponed state rides a
+    // JSON head as an escaped string.
+    const entryBytes = estimateShellEntryBytes({
+      // A navigation-only entry stores no document half.
+      preludeBytes: capture.navigationOnly ? 0 : result.prelude.length,
+      postponed: capture.navigationOnly ? undefined : result.postponed,
+      snapshot,
+      tags: shellTags,
+      docKey: storedDocKey,
+      prunedRecords: snapshot.length > 0 ? prunedRecords : undefined,
+    });
+    stats.entryBytes = entryBytes;
+    const entryLimit =
+      (capture.store ?? reqCtx._cacheStore)?.maxShellEntryBytes ??
+      DEFAULT_SHELL_ENTRY_MAX_BYTES;
+    if (entryBytes > entryLimit) {
+      warnCaptureRefusedOnce(
+        capture.key,
+        `the shell entry is ${entryBytes} bytes (prelude, postponed state, ` +
+          `snapshot, and head), over the store's ${entryLimit}-byte value limit. ` +
+          "Shrink the page the shell bakes, or move large regions under a live " +
+          "loader's boundary.",
+      );
+      return "refused";
+    }
+
     // Missing tags are valid: the shell follows TTL/SWR-only invalidation. Expose
     // that choice only to operators who enabled structured capture diagnostics.
-    if (
-      capture.debugSink &&
-      stats &&
-      bakedLoaderMaterial &&
-      shellTags === undefined
-    ) {
+    if (capture.debugSink && bakedLoaderMaterial && shellTags === undefined) {
       stats.untaggedBake = true;
     }
 
@@ -2065,48 +2536,76 @@ async function captureAndStoreShell(
           ...(capture.navigationOnly
             ? {}
             : {
-                // slice() copies just this view's bytes into a fresh
-                // ArrayBuffer, so a prelude that is a subarray of a larger
-                // backing buffer encodes only its own region — bufferToBase64
-                // reads the whole ArrayBuffer it is handed.
-                prelude: bufferToBase64(
-                  result.prelude.slice().buffer as ArrayBuffer,
-                ),
+                // bytesToBase64 encodes the view's own region, so a prelude
+                // that is a subarray of a larger buffer encodes correctly.
+                prelude: bytesToBase64(result.prelude),
                 postponed: result.postponed,
               }),
           reactVersion: React.version,
           buildVersion: capture.buildVersion,
           // The theme this capture's payload was built with (buildFullPayload
-          // reads reqCtx.theme off the derived context). The serve tail replays
-          // it so the resume tree matches the frozen prelude — see
-          // ShellCacheEntry.initialTheme.
-          initialTheme: reqCtx.theme,
+          // reads payloadInitialTheme off the derived context: the no-cookie
+          // default, #971). The serve tail replays it so the resume tree
+          // matches the frozen prelude — see ShellCacheEntry.initialTheme.
+          initialTheme: payloadInitialTheme(reqCtx),
           snapshot,
+          prunedRecords: snapshot.length > 0 ? prunedRecords : undefined,
           // The canonical doc segment record's key, published by the doc
-          // scope's cacheRoute during this capture's match (undefined when no
-          // doc record was recorded — the entry then never claims navigation
-          // replayability). Only meaningful alongside a snapshot.
-          docKey: snapshot ? reqCtx._shellImplicitCache?.docKey : undefined,
+          // scope's cacheRoute during this capture's match. Every HIT tail
+          // looks the record up by this key (serveShellHit fixedDocKey);
+          // undefined only for a prerender-served entry.
+          docKey: storedDocKey,
           navigationOnly: capture.navigationOnly,
-          // Handler-layer liveness folded at the barrier: nested thenables in
-          // handler-scoped pushes, handler pushes still pending (liveness
-          // unknowable), or a handler-invoked loader execution — any of them
-          // refuses the FAST PATH, not the capture. See
-          // _shellCaptureHandleLiveness.
-          handlerLiveHoles: handlerLayerIsLive(
-            reqCtx._shellCaptureHandleLiveness,
-          ),
-          transitionWhen: reqCtx._transitionWhen?.length ? true : undefined,
           createdAt: captureStartedAt,
         };
+        // Capped to the route record the capture used: the policy the
+        // store would apply (resolveTtl/resolveSwrWindow, as putShell does),
+        // made explicit.
+        const record = reqCtx._routeRecordWindow;
+        let window: { ttl?: number; swr?: number } = {
+          ttl: capture.ttl,
+          swr: capture.swr,
+        };
+        if (record) {
+          const capped = capShellWindow(
+            resolveTtl(capture.ttl, store.defaults, DEFAULT_FUNCTION_TTL),
+            resolveSwrWindow(capture.swr, store.defaults),
+            record,
+            Date.now(),
+          );
+          if (!capped) {
+            // Dead on arrival, not stored. A record this attempt wrote ran
+            // out between its write and the store, which a retry repeats:
+            // warn, refuse, back off. A record it read was near its end (its
+            // age, queue wait): `expired` retries on a fresh match.
+            const route = reqCtx._routeName ?? capture.key;
+            if (record.written) {
+              const sinceWriteMs =
+                Date.now() - (record.freshUntil - record.ttl * 1000);
+              warnRecordRanOutOnce(
+                route,
+                record,
+                `${sinceWriteMs} ms after this capture wrote it`,
+              );
+              return "refused";
+            }
+            stats.expired = {
+              route,
+              record,
+              captureMs: Date.now() - captureStartedAt,
+            };
+            return "expired";
+          }
+          window = capped;
+        }
         const storeWrite = await store.putShell(
           capture.key,
           entry,
-          capture.ttl,
-          capture.swr,
+          window.ttl,
+          window.swr,
           shellTags,
         );
-        if (stats && storeWrite) stats.storeWrite = storeWrite;
+        if (storeWrite) stats.storeWrite = storeWrite;
         if (storeWrite === "invalidated") {
           warnCaptureRefusedOnce(
             capture.key,
@@ -2176,3 +2675,18 @@ export {
   REFUSED_CAPTURE_MAX_MS,
   REFUSED_CAPTURE_DEV_MAX_MS,
 };
+
+/**
+ * @internal Reset this module's per-isolate state: the capture stampede
+ * guard, the refused-capture backoff, the once-per-key warnings (the shell
+ * path's one registry), the stored-capture sequence and the buffered debug
+ * events. Tests only (testing/serve-shell-request.ts resetShellTestState),
+ * between requests, never while a capture runs.
+ */
+export function resetShellCaptureStateForTests(): void {
+  inFlightCaptures.clear();
+  refusedCaptures.clear();
+  resetShellWarningsForTests();
+  storedCaptureSeqs.clear();
+  lastCaptureEventsForTiming.clear();
+}