@rangojs/router 0.28.0 → 0.30.0

package/src/router/match-middleware/background-revalidation.ts

@@ -113,7 +113,7 @@ import { getContext } from "../../server/context.js";
 import { executionStart } from "../../cache/tag-invalidation.js";
 import {
   createRequestContext,
-  runWithRequestContext,
+  runAsBackgroundWork,
   type RequestContext,
 } from "../../server/request-context.js";
 import { deriveRenderPass } from "../../server/render-pass.js";
@@ -141,8 +141,9 @@ import {
  * each field and why. The DSL store below has `metrics` unset too (track()
  * reads that one), so nothing lands on the foreground's perf timeline;
  * ctx.Store.run closes over ctx.Store, so the derived store needs its own run.
- * runWithRequestContext also re-establishes the request ALS, which a waitUntil
- * task on workerd loses; the DSL store is a different ALS (build context).
+ * runAsBackgroundWork also re-establishes the request ALS, which a waitUntil
+ * task on workerd loses, and marks the pass's onError reports `background`;
+ * the DSL store is a different ALS (build context).
  */
 export async function rerenderAndCacheRoute<TEnv>(
   ctx: MatchContext<TEnv>,
@@ -172,7 +173,7 @@ export async function rerenderAndCacheRoute<TEnv>(
       store.parent,
       fn,
     );
-  return runWithRequestContext(renderCtx, async () => {
+  return runAsBackgroundWork(renderCtx, async () => {
     const handlerContext = routerCtx.createHandlerContext(
       ctx.matched.params,
       ctx.request,

package/src/router/match-middleware/cache-lookup.ts

@@ -431,13 +431,15 @@ async function* serveStoredSegments<TEnv>(
   // route is the same case, served from the overlay first (an overlay entry
   // is newer than the build one, and may be the only one). Passthrough
   // routes keep a liveHandler, so a live render (rendersLive) re-renders
-  // them fresh. A thrown action's boundary pass walks live too
-  // (ActionContext.boundary).
+  // them fresh. A pass cut at an error boundary walks live too
+  // (ActionContext.boundary, a follow-up's held one): the evicted handler is
+  // under the cut.
   if (
     (prerenderStoreShortCircuits(ctx.matched.pr, ctx.request) ||
       overlayEligible) &&
     (!rendersLive(ctx) || !isPassthroughPrerenderRoute) &&
-    !ctx.actionContext?.boundary
+    !ctx.actionContext?.boundary &&
+    !ctx.heldBoundary
   ) {
     await ensurePrerenderDeps();
     stored = await readPrerenderSource(

package/src/router/navigation-snapshot.ts

@@ -18,6 +18,13 @@ export interface NavigationSnapshot {
   filteredSegmentIds: string[];
 
   stale: boolean;
+  /**
+   * The id of an action's error boundary on screen that a stale request holds
+   * (`_rsc_boundary`, the action follow-up): read only beside `stale`, so it
+   * has every stale guarantee (a live render, no route-cache or document-cache
+   * read or store, no PPR replay).
+   */
+  heldBoundary?: string;
 
   isSameRouteNavigation: boolean;
 
@@ -136,6 +143,8 @@ export async function resolveNavigation(
   const clientSegmentIds =
     url.searchParams.get(WIRE.segments)?.split(",").filter(Boolean) || [];
   const stale = url.searchParams.get(WIRE.stale) === "true";
+  const heldBoundary =
+    (stale && url.searchParams.get(WIRE.boundary)) || undefined;
   const previousUrl = getNavigationContextHeader(request, url.origin);
   const interceptSourceUrl = getInterceptSourceHeader(request);
   const isHmr = !!requestHeaders(request).get("X-RSC-HMR");
@@ -198,6 +207,7 @@ export async function resolveNavigation(
     clientSegmentSet,
     filteredSegmentIds,
     stale,
+    heldBoundary,
     isSameRouteNavigation,
     effectiveFromUrl,
     effectiveFromMatch,

package/src/router/segment-resolution/helpers.ts

@@ -204,15 +204,49 @@ export interface ErrorReportContext {
   routeKey?: string;
   env?: any;
   isPartial?: boolean;
-  requestStartTime?: number;
   telemetry?: TelemetrySink;
 }
 
+type Thrower = { id: string; type: ErrorInfo["segmentType"] };
+
+/**
+ * Note that `id` threw `error`, for an error its owning entry's boundary
+ * catches (a parallel slot's sync throw, an orphan layout's): onError names
+ * the segment that threw, as a streamed slot's rejection does. Kept on the
+ * request context, never the module: a reused error object (a constant, a
+ * memoized rejection) can be thrown by another request, or by a Prerender
+ * pass that rethrows before catchSegmentError reads it. Returns `error`, to
+ * rethrow.
+ */
+export function noteThrower(
+  error: unknown,
+  id: string,
+  type: ErrorInfo["segmentType"],
+): unknown {
+  const reqCtx = _getRequestContext();
+  if (reqCtx && error !== null && typeof error === "object") {
+    (reqCtx._throwers ??= new WeakMap()).set(error, { id, type });
+  }
+  return error;
+}
+
+/** The segment noteThrower recorded for `error`, read once. */
+function takeThrower(error: unknown): Thrower | undefined {
+  const throwers = _getRequestContext()?._throwers;
+  if (!throwers || error === null || typeof error !== "object") return;
+  const noted = throwers.get(error) as Thrower | undefined;
+  throwers.delete(error);
+  return noted;
+}
+
 /**
  * Handle a caught error during segment resolution by creating an
  * error or not-found segment with the nearest boundary.
  *
  * Called by resolveWithErrorBoundary to produce error/notFound segments.
+ * `entry` is where the boundary is looked up; `thrower` names the segment
+ * that threw when it is not `entry` (an intercept's slot, under its declaring
+ * entry), for the report, the server print and the client's ErrorInfo.
  */
 export function catchSegmentError<TEnv>(
   error: unknown,
@@ -221,7 +255,11 @@ export function catchSegmentError<TEnv>(
   deps: SegmentResolutionDeps<TEnv>,
   report?: ErrorReportContext,
   pathname?: string,
+  thrower?: Thrower,
 ): ResolvedSegment {
+  const named = thrower ?? takeThrower(error);
+  const segmentId = named?.id ?? entry.shortCode;
+  const segmentType: ErrorInfo["segmentType"] = named?.type ?? entry.type;
   const reportError = (
     handledByBoundary: boolean,
     metadata?: Record<string, unknown>,
@@ -232,13 +270,12 @@ export function catchSegmentError<TEnv>(
       url: report.url,
       routeKey: report.routeKey,
       params,
-      segmentId: entry.shortCode,
-      segmentType: entry.type as any,
+      segmentId,
+      segmentType: segmentType as any,
       env: report.env,
       isPartial: report.isPartial,
       handledByBoundary,
       metadata,
-      requestStartTime: report.requestStartTime,
     });
     if (report.telemetry) {
       const errorObj =
@@ -247,8 +284,8 @@ export function catchSegmentError<TEnv>(
         type: "handler.error",
         timestamp: performance.now(),
         requestId: report.request ? getRequestId(report.request) : undefined,
-        segmentId: entry.shortCode,
-        segmentType: entry.type,
+        segmentId,
+        segmentType,
         error: errorObj,
         handledByBoundary,
         pathname,
@@ -274,8 +311,8 @@ export function catchSegmentError<TEnv>(
 
     const notFoundInfo = createNotFoundInfo(
       error,
-      entry.shortCode,
-      entry.type,
+      segmentId,
+      segmentType,
       pathname,
     );
 
@@ -285,7 +322,7 @@ export function catchSegmentError<TEnv>(
     });
 
     debugLog("segment", "notFound boundary handled error", {
-      segmentId: entry.shortCode,
+      segmentId,
       message: notFoundInfo.message,
     });
 
@@ -302,19 +339,18 @@ export function catchSegmentError<TEnv>(
   // The client gets the masked ErrorInfo; the original prints here.
   printServerError(
     error,
-    { label: "Handler error", name: entry.shortCode, pathname },
+    { label: "Handler error", name: segmentId, pathname },
     _getRequestContext(),
   );
 
   const fallback = deps.findNearestErrorBoundary(entry);
-  const segmentType: ErrorInfo["segmentType"] = entry.type;
-  const errorInfo = createErrorInfo(error, entry.shortCode, segmentType);
+  const errorInfo = createErrorInfo(error, segmentId, segmentType);
   const effectiveFallback = fallback ?? DefaultErrorFallback;
 
   reportError(!!effectiveFallback);
 
   debugLog("segment", "error boundary handled error", {
-    segmentId: entry.shortCode,
+    segmentId,
     boundary: fallback ? "custom" : "default",
     message: errorInfo.message,
   });

package/src/router/segment-resolution/loader-cache.ts

@@ -72,6 +72,7 @@ import { runIdentityExempt } from "../../cache/cache-exec-scope.js";
 import {
   getRequestContext,
   _getRequestContext,
+  runAsBackgroundWork,
   type RequestContext,
 } from "../../server/request-context.js";
 import { observePhase, PHASES } from "../instrument.js";
@@ -92,7 +93,6 @@ import { isWarmReplace, noteWarmWrite } from "../../prerender/warm-request.js";
 import {
   executionStart,
   predatesInvalidation,
-  runAsBackgroundRefresh,
 } from "../../cache/tag-invalidation.js";
 import {
   maskNestedContainerThenables,
@@ -815,10 +815,11 @@ function executeLoaderData<TEnv>(
       // under the ended foreground phases. Inside the request context so
       // observePhase can read tracing on workerd (ALS detaches in waitUntil).
       // No visitor made the invalidations it runs: they set no fresh-reads
-      // cookie (runAsBackgroundRefresh).
+      // cookie, and onError marks its errors `background`
+      // (runAsBackgroundWork).
       wrapBackground: (run) => {
         revalidating = true;
-        return runAsBackgroundRefresh(requestCtxForExecute, () =>
+        return runAsBackgroundWork(requestCtxForExecute, () =>
           observePhase(PHASES.background("loader-revalidation"), run),
         );
       },

package/src/router/segment-resolution/resolution-pass.ts

@@ -51,6 +51,8 @@ export interface ResolutionPassInput<TEnv = any> {
   readonly routeKey: string;
   readonly actionContext?: ActionContext;
   readonly stale?: boolean;
+  /** NavigationSnapshot.heldBoundary: the walk cuts there, sending no segment. */
+  readonly heldBoundary?: string;
   /**
    * No loader is started and no loader segment is emitted: build time
    * (prerender-match.ts) and the background re-render of a route record

package/src/router/segment-resolution/revalidation.ts

@@ -62,6 +62,7 @@ import {
   resolveLayoutComponent,
   resolveWithErrorBoundary,
   buildLoaderErrorContext,
+  noteThrower,
 } from "./helpers.js";
 import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { isLayoutLoaderCopy } from "../../client-urls/layout-loader-copies.js";
@@ -801,28 +802,34 @@ async function resolveParallelSlotComponent<TEnv>(
               handler,
               slotContext,
             );
-      if (hasLoadingFallback) {
-        const result = run();
-        if (result instanceof Promise) {
-          warnOnStreamedResponse(result, parallelId);
-          result.finally(doneHandler).catch(() => {});
-          component = trackStreamedHandler(deps, result, {
-            boundaryEntry,
-            segmentId: parallelId,
-            segmentType: "parallel",
-            context,
-            routeKey,
-            params,
-            recover: !pass.throwOnError,
-          });
+      // A throw before the slot streams reaches the owning entry's boundary.
+      try {
+        if (hasLoadingFallback) {
+          const result = run();
+          if (result instanceof Promise) {
+            warnOnStreamedResponse(result, parallelId);
+            result.finally(doneHandler).catch(() => {});
+            component = trackStreamedHandler(deps, result, {
+              boundaryEntry,
+              segmentId: parallelId,
+              segmentType: "parallel",
+              context,
+              routeKey,
+              params,
+              isPartial: reportsPartial(pass),
+              recover: !pass.throwOnError,
+            });
+          } else {
+            doneHandler();
+            component = result as ReactNode;
+          }
         } else {
+          // A static value (a Promise included) goes to render as is.
+          component = typeof handler === "function" ? await run() : handler;
           doneHandler();
-          component = result as ReactNode;
         }
-      } else {
-        // A static value (a Promise included) goes to render as is.
-        component = typeof handler === "function" ? await run() : handler;
-        doneHandler();
+      } catch (error) {
+        throw noteThrower(error, parallelId, "parallel");
       }
     }
   }
@@ -1180,6 +1187,7 @@ async function resolveRouteComponent<TEnv>(
           context,
           routeKey,
           params,
+          isPartial: reportsPartial(pass),
           recover: !pass.throwOnError,
         }),
       };
@@ -1504,6 +1512,9 @@ export async function resolveOrphanLayout<TEnv>(
       const doneHandler = track(`handler:${orphan.id}`, 2);
       try {
         component = await resolveLayoutComponent(orphan, context);
+      } catch (error) {
+        // Its owning entry's boundary catches it.
+        throw noteThrower(error, orphan.shortCode, orphan.type);
       } finally {
         internal._currentSegmentId = pinned;
       }
@@ -1598,6 +1609,15 @@ export interface RevalidatingWalkOptions {
   readonly chain?: readonly EntryData[];
 }
 
+/**
+ * The onError `isPartial` of an error the walk catches. FRESH: a full match
+ * reports it unset. A re-render a navigation started reports it true
+ * (partialRequest).
+ */
+function reportsPartial(pass: ResolutionPass<any>): true | undefined {
+  return pass.client !== FRESH || pass.partialRequest ? true : undefined;
+}
+
 /** An entry's error or not-found segment, as its whole result. */
 function boundaryResult(seg: ResolvedSegment): SegmentRevalidationResult {
   return { segments: [seg], matchedIds: [seg.id] };
@@ -1633,14 +1653,12 @@ export async function resolveAllSegments<TEnv>(
   try {
     telemetry = getRouterContext()?.telemetry;
   } catch {}
-  // FRESH: a full match reports an entry's error without isPartial, and a
-  // build-time pass rethrows it (throwOnError). A re-render a navigation
-  // started reports it with isPartial (partialRequest).
+  // A build-time pass rethrows an entry's error (throwOnError).
   const report = {
     request,
     url: context.url,
     routeKey,
-    isPartial: pass.client !== FRESH || pass.partialRequest ? true : undefined,
+    isPartial: reportsPartial(pass),
     telemetry,
   };
   const fillMatch = {
@@ -1650,16 +1668,19 @@ export async function resolveAllSegments<TEnv>(
   };
 
   const boundary = pass.actionContext?.boundary;
-  const boundaryId = boundary?.id;
+  const cutId = boundary?.id ?? pass.heldBoundary;
+  let cut = false;
   for (const entry of entries) {
-    if (entry.shortCode === boundaryId) {
+    if (entry.shortCode === cutId) {
       // The outlet's loader ids stay claimed. _handlerRan makes the browser
-      // clear the outlet's handle values.
-      allSegments.push({ ...boundary!, _handlerRan: true });
-      matchedIds.push(boundaryId);
+      // clear the outlet's handle values. A held boundary sends no segment:
+      // the client keeps its own, with its handle values.
+      if (boundary) allSegments.push({ ...boundary, _handlerRan: true });
+      matchedIds.push(cutId);
       entry.loader?.forEach((loaderEntry, i) =>
         matchedIds.push(`${entry.shortCode}D${i}.${loaderEntry.loader.$$id}`),
       );
+      cut = true;
       break;
     }
     if (entry.type === "route" && interceptResult) {
@@ -1721,6 +1742,14 @@ export async function resolveAllSegments<TEnv>(
     }
   }
 
+  // A held boundary that names no entry (HMR rewrote the routes since the
+  // page rendered): the page renders whole, as without one.
+  if (pass.heldBoundary && !cut && process.env.NODE_ENV !== "production") {
+    console.warn(
+      `[@rangojs/router] A refetch held the error boundary "${pass.heldBoundary}", ` +
+        `which is not on the route's chain (${routeKey}): the page renders whole.`,
+    );
+  }
   deliverStartedLoaders(context, allSegments);
   return { segments: allSegments, matchedIds };
 }

package/src/router/segment-resolution/streamed-handler-boundary.ts

@@ -44,6 +44,8 @@ export interface StreamedHandlerOptions<TEnv> {
   context: HandlerContext<any, TEnv>;
   routeKey?: string;
   params: Record<string, string>;
+  /** onError's `isPartial`, as the walk reports a sync handler's error. */
+  isPartial: true | undefined;
   /** False where the rejection must reach the caller (prerender, intercept background re-render). */
   recover: boolean;
 }
@@ -64,6 +66,7 @@ export function trackStreamedHandler<TEnv>(
   const tracked = deps.trackHandler(result as Promise<ReactNode>, {
     segmentId,
     segmentType,
+    isPartial: options.isPartial,
   });
   observeStreamedHandler(
     tracked,

package/src/router/types.ts

@@ -57,7 +57,6 @@ export interface SegmentResolutionDeps<TEnv = any> {
       params?: Record<string, string>;
       env?: TEnv;
       isPartial?: boolean;
-      requestStartTime?: number;
     },
     /** An `ssr: false` loader on a document or capture render. */
     useDefaultErrorBoundary?: boolean,
@@ -67,6 +66,7 @@ export interface SegmentResolutionDeps<TEnv = any> {
     errorContext?: {
       segmentId?: string;
       segmentType?: string;
+      isPartial?: boolean;
     },
   ) => Promise<T>;
   findNearestErrorBoundary: (

package/src/router.ts

@@ -44,6 +44,7 @@ import { createHandleStore, type HandleStore } from "./server/handle-store.js";
 import {
   getRequestContext,
   _getRequestContext,
+  reportedErrorsOf,
 } from "./server/request-context.js";
 import type {
   ErrorPhase,
@@ -315,7 +316,8 @@ export function createRouter<TEnv = any>(
    * Wrapper for invokeOnError that binds the router's onError callback.
    * Uses the shared utility from router/error-handling.ts for consistent behavior.
    *
-   * Deduplicates via per-request WeakSet stored on the ALS request context.
+   * Deduplicates via per-request WeakSet stored on the ALS request context
+   * (background work keeps its own, reportedErrorsOf).
    * A closure-level WeakSet would silently swallow errors if the same object
    * instance is thrown across separate requests (e.g. a singleton error).
    */
@@ -325,7 +327,8 @@ export function createRouter<TEnv = any>(
     context: Parameters<typeof invokeOnError<TEnv>>[3],
   ): void {
     if (error != null && typeof error === "object") {
-      const reportedErrors = _getRequestContext()?._reportedErrors;
+      const reqCtx = _getRequestContext();
+      const reportedErrors = reqCtx && reportedErrorsOf(reqCtx);
       if (reportedErrors) {
         if (reportedErrors.has(error)) return;
         reportedErrors.add(error);
@@ -488,6 +491,7 @@ export function createRouter<TEnv = any>(
     errorContext?: {
       segmentId?: string;
       segmentType?: string;
+      isPartial?: boolean;
     },
   ): Promise<T> => {
     // One ALS read serves both the store lookup and the onError closure.
@@ -520,6 +524,7 @@ export function createRouter<TEnv = any>(
           env: reqCtx.env as TEnv,
           segmentId: errorContext?.segmentId,
           segmentType: errorContext?.segmentType as any,
+          isPartial: errorContext?.isPartial,
           handledByBoundary: true,
         });
       });
@@ -542,7 +547,6 @@ export function createRouter<TEnv = any>(
       params?: Record<string, string>;
       env?: TEnv;
       isPartial?: boolean;
-      requestStartTime?: number;
     },
     useDefaultErrorBoundary?: boolean,
   ): Promise<LoaderDataResult<T>> {
@@ -592,7 +596,6 @@ export function createRouter<TEnv = any>(
               env: errorContext.env,
               isPartial: errorContext.isPartial,
               handledByBoundary: ctx.handledByBoundary,
-              requestStartTime: errorContext.requestStartTime,
             });
             if (emitTelemetry) {
               const errorObj =

package/src/rsc/request-stages.ts

@@ -22,6 +22,7 @@ import type { MiddlewareEntry } from "../router/middleware-types.js";
 import {
   _getRequestContext,
   getRequestContext,
+  reportedErrorsOf,
   setRequestContextParams,
   type RequestContext,
 } from "../server/request-context.js";
@@ -158,8 +159,9 @@ export function createErrorReporter<TEnv>(router: {
     // case — the error is from a cancelled stream, not a real failure.
     const reqCtx = _getRequestContext();
     if (error != null && typeof error === "object" && reqCtx) {
-      if (reqCtx._reportedErrors.has(error)) return;
-      reqCtx._reportedErrors.add(error);
+      const reportedErrors = reportedErrorsOf(reqCtx);
+      if (reportedErrors.has(error)) return;
+      reportedErrors.add(error);
     }
     invokeOnError(router.onError, error, phase, context, "RSC");
   };

package/src/rsc/shell-capture.ts

@@ -48,6 +48,7 @@ import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import type { TraceSpan } from "../router/tracing.js";
 import {
+  runAsBackgroundWork,
   runWithRequestContext,
   setRequestContextParams,
   UNTRACKED_BACKGROUND_TASK,
@@ -1279,69 +1280,73 @@ export function planShellCapture(input: ShellCaptureInput): void {
   // (observed in production: ~24s of zero I/O before capture start).
   // observePhase reads tracing off the ALS context captured when runBackground
   // registered the task — the foreground request context, tracing intact.
+  // onError marks every error of the capture `background`, the task's own
+  // failure (captureTask's catch) included.
   const serializedTask = async () => {
-    await observePhase(PHASES.background("shell-capture"), async (span) => {
-      span.setAttribute("rango.shell_key", key);
-      // A production page can enqueue several navigation-only captures through
-      // viewport prefetching. Let a later document MISS overtake that queued
-      // speculative work so it can become a shell HIT before the 15s queue
-      // budget expires. Never preempts the active capture. Priority and the
-      // backlog ahead at enqueue ride the span (and the skip event below), so
-      // a skip-queue-timeout diagnoses itself instead of needing a trace dive.
-      const queuePriority = descriptor.navigationOnly
-        ? ("navigation" as const)
-        : ("document" as const);
-      const depths = captureQueueDepths();
-      const queueAhead =
-        (depths.running ? 1 : 0) +
-        depths.document +
-        (queuePriority === "navigation" ? depths.navigation : 0);
-      span.setAttribute("rango.background.queue_priority", queuePriority);
-      span.setAttribute("rango.background.queue_ahead", queueAhead);
-      const queueStart = performance.now();
-      try {
-        await enqueueSerializedCapture(
-          () => {
+    await runAsBackgroundWork(reqCtx, () =>
+      observePhase(PHASES.background("shell-capture"), async (span) => {
+        span.setAttribute("rango.shell_key", key);
+        // A production page can enqueue several navigation-only captures through
+        // viewport prefetching. Let a later document MISS overtake that queued
+        // speculative work so it can become a shell HIT before the 15s queue
+        // budget expires. Never preempts the active capture. Priority and the
+        // backlog ahead at enqueue ride the span (and the skip event below), so
+        // a skip-queue-timeout diagnoses itself instead of needing a trace dive.
+        const queuePriority = descriptor.navigationOnly
+          ? ("navigation" as const)
+          : ("document" as const);
+        const depths = captureQueueDepths();
+        const queueAhead =
+          (depths.running ? 1 : 0) +
+          depths.document +
+          (queuePriority === "navigation" ? depths.navigation : 0);
+        span.setAttribute("rango.background.queue_priority", queuePriority);
+        span.setAttribute("rango.background.queue_ahead", queueAhead);
+        const queueStart = performance.now();
+        try {
+          await enqueueSerializedCapture(
+            () => {
+              span.setAttribute(
+                "rango.background.queue_wait_ms",
+                Math.round(performance.now() - queueStart),
+              );
+              return captureTask(span);
+            },
+            { priority: queuePriority },
+          );
+        } catch (error) {
+          if (error instanceof CaptureQueueFullError) {
+            releaseCaptureGuard(key, guardToken);
+            span.setAttribute("rango.background.outcome", "skip-capacity");
+            publishCaptureDebugEvent(descriptor, {
+              key,
+              outcome: "skip-capacity",
+            });
+            return;
+          }
+          if (error instanceof CaptureQueueWaitTimeoutError) {
+            // Dropped unrun after waiting past the queue budget: no backoff (the
+            // route is not doomed, the isolate was busy) — a later request
+            // re-probes the key.
+            releaseCaptureGuard(key, guardToken);
+            span.setAttribute("rango.background.outcome", "skip-queue-timeout");
             span.setAttribute(
               "rango.background.queue_wait_ms",
-              Math.round(performance.now() - queueStart),
+              Math.round(error.waitedMs),
             );
-            return captureTask(span);
-          },
-          { priority: queuePriority },
-        );
-      } catch (error) {
-        if (error instanceof CaptureQueueFullError) {
-          releaseCaptureGuard(key, guardToken);
-          span.setAttribute("rango.background.outcome", "skip-capacity");
-          publishCaptureDebugEvent(descriptor, {
-            key,
-            outcome: "skip-capacity",
-          });
-          return;
-        }
-        if (error instanceof CaptureQueueWaitTimeoutError) {
-          // Dropped unrun after waiting past the queue budget: no backoff (the
-          // route is not doomed, the isolate was busy) — a later request
-          // re-probes the key.
-          releaseCaptureGuard(key, guardToken);
-          span.setAttribute("rango.background.outcome", "skip-queue-timeout");
-          span.setAttribute(
-            "rango.background.queue_wait_ms",
-            Math.round(error.waitedMs),
-          );
-          publishCaptureDebugEvent(descriptor, {
-            key,
-            outcome: "skip-queue-timeout",
-            queueWaitMs: Math.round(error.waitedMs),
-            queuePriority,
-            queueAhead,
-          });
-          return;
+            publishCaptureDebugEvent(descriptor, {
+              key,
+              outcome: "skip-queue-timeout",
+              queueWaitMs: Math.round(error.waitedMs),
+              queuePriority,
+              queueAhead,
+            });
+            return;
+          }
+          throw error;
         }
-        throw error;
-      }
-    });
+      }),
+    );
   };
   // The capture's own task must NOT enter reqCtx._pendingBackgroundTasks: the
   // capture drains that list before rendering (the write-barrier ordering edge),