@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/server/management/shared.ts

@@ -35,12 +35,13 @@ import { clearThreadAccountMap } from "../../codex/routing";
 import { primeCodexPoolQuotas } from "../../codex/auth-api";
 import { DEFAULT_PROVIDER_CONTEXT_CAP, globalContextCapValue, providerContextCap, providerContextCaps, setAllProviderContextCaps, setGlobalContextCapValue, setProviderContextCap } from "../../providers/context-cap";
 import { resolveCodexHomeDir } from "../../codex/home";
-import { readUsageEntries } from "../../usage/log";
+import { isKnownRequestFailureCause, isKnownRequestFailureStage, readUsageEntries } from "../../usage/log";
 import { getUsageDebugLogEntries } from "../../usage/debug";
 import { cacheObservationFromUsage, parseRange, parseUsageSurface, summarizeUsage } from "../../usage/summary";
 import { stripCodexRuntimeProviderFields } from "../../codex/auth-context";
 import { getProviderRegistryEntry, providerMatchesRegistryTransport } from "../../providers/registry";
 import { getDebugLogEntries } from "../../lib/debug-log-buffer";
+import { resendPermission } from "../../lib/request-failure-model";
 import { getInjectionDebugLogEntries } from "../../lib/injection-debug-log";
 import {
   clearDebugSettings,
@@ -210,12 +211,27 @@ export function costResult(entry: MetricSource): CostResult {
  * a Logs-page metric, and widening a separate endpoint's response shape is not this change's
  * business. Flipping it on later is one argument.
  */
+
+/**
+ * Whether this proxy could have sent the row again, derived at READ time from the stage and
+ * cause the recorder stored.
+ *
+ * Deliberately not persisted. The verdict is a function of two tables that this build owns, and
+ * a row written months ago must not be able to assert a permission the current tables would
+ * refuse -- the whole point of INV-RESEND-01 is that the refusal rules are one statement, and a
+ * stored verdict would be a second one with no way to correct it.
+ */
+function resendVerdict(row: { failureStage?: string; failureCause?: string }): { resendPermission?: string } {
+  if (!isKnownRequestFailureStage(row.failureStage) || !isKnownRequestFailureCause(row.failureCause)) return {};
+  return { resendPermission: resendPermission(row.failureStage, row.failureCause) };
+}
 export function requestLogDto(
   entry: RequestLogEntry,
   { includeDecodeRate = true }: { includeDecodeRate?: boolean } = {},
 ): Record<string, unknown> {
   return {
     ...entry,
+    ...resendVerdict(entry),
     displayMetrics: {
       tokPerSecond: tokPerSecondResult(entry),
       // The parent uses the REQUEST's own TTFT. A combo parent must not borrow an attempt's,
@@ -227,6 +243,7 @@ export function requestLogDto(
       ? {
         attempts: entry.attempts.map(attempt => ({
           ...attempt,
+          ...resendVerdict(attempt),
           displayMetrics: {
             tokPerSecond: tokPerSecondResult(attempt),
             // Each attempt measures its own attempt-relative TTFT.
@@ -245,12 +262,19 @@ export function requestLogDto(
  * share the same fetch, the same per-provider cache (dedups Codex's frequent /v1/models polling),
  * and the same stale fallback when a provider blips, instead of a parallel uncached copy.
  */
-export async function fetchAllModels(config: OcxConfig): Promise<CatalogModel[]> {
+export async function fetchAllModels(
+  config: OcxConfig,
+  /** Filled with each provider's content revision as of the moment its rows were chosen. */
+  providerContentRevisions?: Map<string, string>,
+): Promise<CatalogModel[]> {
   const { gatherRoutedModels } = await import("../../codex/catalog");
   const baseline = captureInitialSelectionBaseline(config);
-  if (!baseline) return gatherRoutedModels(config);
+  if (!baseline) return gatherRoutedModels(config, providerContentRevisions ? { providerContentRevisions } : undefined);
   const outcomes: Array<{ provider: string; state: "authoritative" | "degraded" }> = [];
-  const models = await gatherRoutedModels(config, { providerModelOutcomes: outcomes });
+  const models = await gatherRoutedModels(config, {
+    providerModelOutcomes: outcomes,
+    ...(providerContentRevisions ? { providerContentRevisions } : {}),
+  });
   finalizeInitialModelSelection(config, baseline, uniqueCatalogModelsForPublicList(models),
     outcomes.filter(outcome => outcome.state === "authoritative").map(outcome => outcome.provider));
   return models;

package/src/server/management/system-restart.ts

@@ -36,6 +36,7 @@ import { isServiceViable } from "../../service";
 import { readRuntimePort } from "../../config/process-state";
 import { withProcessRuntimeProvenance } from "../../lib/bun-runtime";
 import { selfLaunchArgv } from "../../lib/self-launch-argv";
+import { spendLedgerRestartEnvironment } from "../../lib/spend-ledger-owner";
 import {
   MEMORY_DRAIN_RESTART_MS,
   REPLACEMENT_READY_TIMEOUT_MS,
@@ -225,8 +226,12 @@ function spawnDetachedStart(
   return new Promise<void>((resolve, reject) => {
     let child: ReturnType<typeof spawn>;
     try {
-      const env: NodeJS.ProcessEnv = { ...process.env };
-      delete env.OCX_SERVICE;
+      const sourceEnv: NodeJS.ProcessEnv = { ...process.env };
+      delete sourceEnv.OCX_SERVICE;
+      const env = spendLedgerRestartEnvironment(
+        sourceEnv,
+        waitForHealthBeforeParentExit ? undefined : process.pid,
+      );
       child = spawn(process.execPath, launchArgs, {
         detached: true,
         stdio: "ignore",

package/src/server/management/system-routes.ts

@@ -39,6 +39,7 @@ import {
 } from "../../lib/codex-restart-contract";
 import { jsonResponse } from "../auth-cors";
 import { getInspectionCounters } from "../relay";
+import { spendLedgerDiagnosticsSnapshot } from "../../lib/spend-reservation-ledger";
 import type {
   performCodexRestart,
   readCodexAppServerState,
@@ -60,6 +61,7 @@ export async function handleSystemRoutes(ctx: ManagementContext): Promise<Respon
       version,
       uptime: process.uptime(),
       pid: process.pid,
+      spendLedger: spendLedgerDiagnosticsSnapshot(),
     });
   }
   if (url.pathname === "/api/system/memory" && req.method === "GET") {

package/src/server/management/usage-aggregate-cache.ts

@@ -66,6 +66,7 @@ const pinnedAggregates = new Set<RetainedUsageAggregate>();
 let baseFlight: Promise<UsageAggregateResult> | null = null;
 const filteredFlights = new Map<string, Promise<UsageAggregateResult>>();
 const retainedFilteredAggregates = new Map<string, RetainedUsageAggregate>();
+const MAX_CONCURRENT_FILTERED_AGGREGATES = 4;
 
 function currentTimeZone(): string {
   return Intl.DateTimeFormat().resolvedOptions().timeZone;
@@ -283,6 +284,9 @@ export async function getFilteredUsageAggregate(filter: {
   ]);
   const existing = filteredFlights.get(key);
   if (existing) return existing;
+  if (filteredFlights.size >= MAX_CONCURRENT_FILTERED_AGGREGATES) {
+    throw new Error("too many concurrent filtered usage aggregates");
+  }
 
   const flight = refreshFilteredAggregate(key, normalizedFilter, fixedWindow);
   filteredFlights.set(key, flight);

package/src/server/management/usage-timeline-routes.ts

@@ -0,0 +1,44 @@
+import { readUsageSnapshotForManagement } from "../../usage/log";
+import { createTimelineAccumulator, parseTimelineQuery } from "../../usage/timeline";
+import { jsonResponse } from "../auth-cors";
+import type { ManagementContext } from "./context";
+
+const TIMELINE_CACHE_TTL_MS = 15_000;
+const cache = new Map<string, { expiresAt: number; promise: Promise<ReturnType<ReturnType<typeof createTimelineAccumulator>["finish"]>> }>();
+
+export async function handleUsageTimelineRoutes(ctx: ManagementContext): Promise<Response | undefined> {
+  const { req, url } = ctx;
+  if (url.pathname !== "/api/usage/timeline" || req.method !== "GET") return undefined;
+  const query = parseTimelineQuery(url.searchParams, Date.now());
+  if ("error" in query) return jsonResponse(query, 400, req, ctx.config);
+  const bucketMs = query.bucketMinutes * 60_000;
+  const roundedNow = Math.floor(query.now / bucketMs) * bucketMs;
+  const normalized = { ...query, now: roundedNow };
+  const key = JSON.stringify(normalized);
+  const current = Date.now();
+  const cached = cache.get(key);
+  if (cached && cached.expiresAt > current) return jsonResponse(await cached.promise, 200, req, ctx.config);
+  let promise: Promise<ReturnType<ReturnType<typeof createTimelineAccumulator>["finish"]>>;
+  promise = (async () => {
+    const accumulator = createTimelineAccumulator(normalized);
+    const snapshot = await readUsageSnapshotForManagement(ctx.config.managementUsageMaxReadBytes);
+    for (const entry of snapshot.entries) accumulator.add(entry);
+    return {
+      ...accumulator.finish(),
+      truncated: snapshot.truncatedPrefixBytes > 0 || snapshot.entriesTruncated,
+    };
+  })().catch(error => {
+    const entry = cache.get(key);
+    if (entry?.promise === promise) cache.delete(key);
+    throw error;
+  });
+  cache.set(key, { expiresAt: current + TIMELINE_CACHE_TTL_MS, promise });
+  try {
+    return jsonResponse(await promise, 200, req, ctx.config);
+  } finally {
+    setTimeout(() => {
+      const entry = cache.get(key);
+      if (entry?.promise === promise && entry.expiresAt <= Date.now()) cache.delete(key);
+    }, TIMELINE_CACHE_TTL_MS + 1);
+  }
+}

package/src/server/management-api.ts

@@ -1,6 +1,5 @@
 import { remoteWorkspaceEnabled } from "../remote-control/workspace-activation";
 import { randomUUID } from "node:crypto";
-import { readFileSync } from "node:fs";
 import type { CatalogModel } from "../codex/catalog";
 import { catalogModelSlug, invalidateCodexModelsCache, nativeContextLimits, nativeModelRows, uniqueCatalogModelsForPublicList } from "../codex/catalog";
 import {
@@ -63,6 +62,7 @@ import { handleLogsUsageRoutes } from "./management/logs-usage-routes";
 import { handleStorageLogGuardRoutes } from "./management/storage-log-guard-routes";
 import { handleRequestHistoryRoutes } from "./management/request-history-routes";
 import { handleRoutingAnalyticsRoutes } from "./management/routing-analytics-routes";
+import { handleMetricsRoutes } from "./management/metrics-routes";
 import { handleProviderRoutes } from "./management/provider-routes";
 import { handleModelRoutes } from "./management/model-routes";
 import { handleAgentSettingsRoutes } from "./management/agent-settings-routes";
@@ -70,6 +70,8 @@ import { handleOauthAccountRoutes } from "./management/oauth-account-routes";
 import { handleComboRoutes } from "./management/combo-routes";
 import { handleSystemRoutes } from "./management/system-routes";
 import { handleSidebarRoutes } from "./management/sidebar-routes";
+import { handleUsageTimelineRoutes } from "./management/usage-timeline-routes";
+import { handleCompanionRoutes } from "./management/companion-routes";
 import { handleCodexPromptRoutes } from "./management/codex-prompt-routes";
 import { handleIntegrationRoutes } from "./management/integration-routes";
 import { handleNativeIntegrationRoutes } from "./management/native-integration-routes";
@@ -83,15 +85,11 @@ import type { CatalogDisposition, ConvergeCodex } from "../codex/convergence-typ
 import { normalizeCatalogDisposition } from "../codex/catalog-refresh-status";
 import { managementBodyTooLargeResponse } from "./management/body";
 import { handleSessionRoutes } from "./management/session-routes";
+import { packageVersion } from "../lib/package-version";
 
 // installed npm version instead of a stale hardcode.
-export const VERSION = (() => {
-  try {
-    return JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version as string;
-  } catch {
-    return "0.0.0";
-  }
-})();
+const MANAGEMENT_VERSION_FALLBACK = "0.0.0";
+export const VERSION = packageVersion(MANAGEMENT_VERSION_FALLBACK);
 
 const managementConvergenceBindings = new WeakMap<object, Readonly<{
   factory: (config: Readonly<OcxConfig>) => ConvergeCodex;
@@ -265,7 +263,7 @@ export async function handleManagementAPI(
     } catch { /* best-effort */ }
   }
   const ctx: ManagementContext = { req, url, config, deps, version: VERSION, principal, sessionControl, convergeCodexCatalog, syncClaudeAgentDefsBestEffort };
-  let routed: Response | null;
+  let routed: Response | null | undefined;
   try {
     routed = handleSessionRoutes(ctx)
     ??     (await handleRemoteWorkspaceRoutesOnDemand(ctx))
@@ -276,6 +274,7 @@ export async function handleManagementAPI(
     ??     (await handleQuotaResetRoutesOnDemand(ctx))
     ??     (await handleWorkflowBudgetRoutesOnDemand(ctx))
     ??     (await handleGrokCouponRoutesOnDemand(ctx))
+    ??     handleMetricsRoutes(ctx)
     ??     (await handleRoutingAnalyticsRoutes(ctx))
     ??     (await handleRoutingProfileRoutesOnDemand(ctx))
     ??     (await handleProviderRoutes(ctx))
@@ -289,6 +288,8 @@ export async function handleManagementAPI(
     ??     (await handleComboRoutes(ctx))
     ??     (await handleSystemRoutes(ctx))
     ??     (await handleLabRoutesOnDemand(ctx))
+      ?? (await handleUsageTimelineRoutes(ctx))
+      ?? (await handleCompanionRoutes(ctx))
       ?? (await handleSidebarRoutes(ctx));
   } catch (error) {
     const tooLarge = managementBodyTooLargeResponse(error, req, config);

package/src/server/management-auth.ts

@@ -12,7 +12,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
-import { adminApiTokenFilePath } from "../lib/admin-secrets";
+import { adminApiTokenFilePath, opencodeCatalogToken } from "../lib/admin-secrets";
 import {
   LOCAL_MANAGEMENT_CAPABILITY_HEADER,
   LOCAL_MANAGEMENT_CAPABILITY_EXPIRES_AT_HEADER,
@@ -297,6 +297,7 @@ export function createManagementSessionControl(state: ManagementAuthState): Mana
  */
 export type ManagementPrincipal =
   | "admin-token"
+  | "opencode-catalog-token"
   | "gui-session"
   | "gui-pair-capability"
   | "local-read-capability"
@@ -484,6 +485,16 @@ function requestManagementCredential(req: Request): string | null {
     || null;
 }
 
+function isOpencodeCatalogRequest(req: Request): boolean {
+  if (req.method !== "GET") return false;
+  try {
+    const url = new URL(req.url);
+    return url.pathname === "/api/models" && url.search === "";
+  } catch {
+    return false;
+  }
+}
+
 function resolveManagementAdmission(
   req: Request,
   state: ManagementAuthState,
@@ -500,6 +511,9 @@ function resolveManagementAdmission(
   else if (state.available) {
     const actual = requestManagementCredential(req);
     if (actual && equalSecret(actual, state.token)) principal = "admin-token";
+    else if (actual && isOpencodeCatalogRequest(req) && equalSecret(actual, opencodeCatalogToken(state.token))) {
+      principal = "opencode-catalog-token";
+    }
     else if (config && authorizeGuiSessionRequest(req, config, state).ok) principal = "gui-session";
   }
   if (principal) admittedManagementRequests.set(req, principal);

package/src/server/proxy-liveness.ts

@@ -32,6 +32,8 @@ export interface HealthzIdentity {
   guiPairCapability?: unknown;
 }
 
+export type EndpointLiveness = "live" | "dead" | "unknown";
+
 export interface LivenessIo {
   fetchFn?: typeof fetch;
   readPidFn?: () => number | null;
@@ -85,6 +87,11 @@ export const START_OWNERSHIP_LIVENESS: Pick<LivenessIo, "timeoutMs" | "attempts"
   attempts: 3,
 };
 
+type LivenessFetch = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
 export interface LiveProxy {
   pid: number | null;
   port: number;
@@ -148,6 +155,74 @@ export function isOpencodexHealthz(body: HealthzIdentity | null): boolean {
   return body.status === "ok" && typeof body.version === "string" && typeof body.uptime === "number";
 }
 
+/**
+ * "Nothing is listening" is narrower than "the probe failed". Only a connect-phase refusal
+ * proves the endpoint is free; a timeout, reset, or other transport failure leaves the
+ * question open.
+ */
+export function isConnectionRefused(error: unknown): boolean {
+  const visit = (current: unknown, depth: number): boolean => {
+    if (depth >= 4) return false;
+    if (current === null || (typeof current !== "object" && typeof current !== "function")) return false;
+    const record = current as { code?: unknown; cause?: unknown; errors?: unknown };
+    if (record.code === "ECONNREFUSED" || record.code === "ConnectionRefused") return true;
+    if (typeof record.code === "string" && record.code.endsWith("ECONNREFUSED")) return true;
+    if (Array.isArray(record.errors) && record.errors.length > 0) {
+      // One connect attempt fanned out over several addresses reports a single AggregateError.
+      // Only a unanimous refusal proves the endpoint is free: a bundle that mixes ECONNREFUSED
+      // with a timeout means one address answered nothing at all, and an address whose state is
+      // unreadable is unknown, not absence. Collapsing it to "refused" is how a second runtime
+      // gets started on a port that already has one.
+      return record.errors.every(error => visit(error, depth + 1));
+    }
+    return visit(record.cause, depth + 1);
+  };
+  return visit(error, 0);
+}
+
+async function classifyHealthz(
+  url: string,
+  fetchFn: LivenessFetch,
+  timeoutMs: number,
+): Promise<EndpointLiveness> {
+  try {
+    const response = await fetchFn(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (response.status !== 200) return "unknown";
+    const body = (await response.json().catch(() => undefined)) as HealthzIdentity | null | undefined;
+    if (body === undefined) return "unknown";
+    return isOpencodexHealthz(body) ? "live" : "dead";
+  } catch (error) {
+    return isConnectionRefused(error) ? "dead" : "unknown";
+  }
+}
+
+/**
+ * Tri-state probe of one endpoint, the in-process counterpart of
+ * `src/update/proxy-liveness-probe.mjs`. Only a connect-phase refusal or a clean 200 that is
+ * not ours proves "dead"; a timeout, reset, non-200 or unreadable body leaves the question
+ * open. Loopback endpoints are checked on both IPv4 and IPv6 because a listener may bind only
+ * one family. Runs in-process because a compiled standalone binary cannot fork `execPath -e`.
+ */
+export async function probeEndpointLiveness(
+  endpoint: { port: number; hostname?: string },
+  io: Pick<LivenessIo, "fetchFn" | "timeoutMs"> = {},
+): Promise<EndpointLiveness> {
+  if (!Number.isFinite(endpoint.port) || endpoint.port <= 0 || endpoint.port > 65535) return "dead";
+  const fetchFn = io.fetchFn ?? directLocalHttpFetch;
+  const timeoutMs = io.timeoutMs ?? 1500;
+  let sawUnknown = false;
+  for (const hostname of loopbackProbeHosts(endpoint.hostname)) {
+    const result = await classifyHealthz(
+      `http://${hostname}:${endpoint.port}/healthz`,
+      fetchFn,
+      timeoutMs,
+    );
+    if (result === "live") return "live";
+    if (result === "unknown") sawUnknown = true;
+  }
+  return sawUnknown ? "unknown" : "dead";
+}
+
 /** Identity-checked /healthz probe; null when unreachable, non-OK, or not our proxy. */
 export async function proxyIdentityAt(
   port: number,

package/src/server/readiness.ts

@@ -3,10 +3,30 @@
  *
  * `GET /healthz` answers "is the process alive and serving HTTP?" the instant the
  * listener binds. Readiness is stricter: the proxy is "ready" only after the
- * post-startup Codex catalog/config sync (`syncModelsToCodex`) has settled with
- * `ok=true` and no catalog-sync warning. Until then the process is live (Codex can
- * open a socket) but not ready (a request would race the sync or hit a stale
- * catalog), so clients should back off.
+ * post-startup Codex catalog/config sync (`syncModelsToCodex`) has SETTLED and
+ * reported `ok=true`. Until it settles the process is live (Codex can open a
+ * socket) but not ready — a request would race the sync — so clients back off.
+ *
+ * What readiness is NOT (#5181): it is not a verdict on the local Codex client's
+ * artifacts. A nonempty `warning` used to be terminal here, which made a
+ * degradation of files written into the local Codex home permanently un-ready a
+ * proxy that was serving every other provider correctly. In a single-replica
+ * Kubernetes deployment that removed the only Service endpoint.
+ *
+ * `ok` and `warning` are separate fields in the sync result because they answer
+ * separate questions, and the gate must not conflate them. `ok` is the sync's own
+ * verdict on whether the essential work — config injection, and the write
+ * admission that precedes it — succeeded. `warning` names a degradation the sync
+ * itself decided to continue past: no catalog source so Codex keeps its native
+ * catalog, combos omitted from the catalog, a conversation-history relabel left
+ * to Codex's own writer, or a caught catalog-refresh exception after which
+ * injection still runs and still reports its own `ok`. None of those stops this
+ * process from accepting HTTP or routing to a provider, so none of them may close
+ * the gate.
+ *
+ * That boundary is not new, only extended: the Claude Code roster reconciliation
+ * in `src/cli/claude-agent-startup-sync.ts` already delays the ready transition
+ * without being allowed to fail it, on the same reasoning.
  *
  * Design contract (per P1 review):
  *  - NO module-global mutable state. Each `startServer` invocation gets its own
@@ -65,8 +85,11 @@ export interface SyncOutcomeLike {
 
 /**
  * Drive the gate from the post-startup sync. Awaits `syncFn`; the gate goes to
- * `ready` ONLY on `ok=true` with no nonempty warning. A throw, `null`, `ok=false`,
- * or a nonempty warning transitions to `failed`. Used directly by `handleStart`
+ * `ready` on `ok=true`. A throw, `null`, or `ok !== true` transitions to
+ * `failed`; a nonempty `warning` does not, because the sync that produced it
+ * still reported the essential work done (see the file header, #5181). A throw
+ * and `null` stay terminal because neither is a classified outcome: the startup
+ * path did not reach a verdict, so the gate cannot claim one. Used by `handleStart`
  * so the startup transition is unit-testable without spawning the proxy. Returns
  * the raw sync outcome so a caller that also needs the #1046 write flags (did the
  * sync actually write the catalog/cache?) can keep them without a second call.
@@ -90,10 +113,6 @@ export async function runStartupReadinessSync(
     gate.markFailed();
     return result;
   }
-  if (result.warning !== undefined && result.warning !== "") {
-    gate.markFailed();
-    return result;
-  }
   gate.markReady();
   return result;
 }

package/src/server/relay-eager.ts

@@ -30,6 +30,7 @@ import {
   createSseTerminalOutputBoundary,
   doneFrame,
   failedTailFrame,
+  refusalFailedTailFrame,
   upstreamErrorTailFrame,
 } from "./relay";
 import {
@@ -127,6 +128,23 @@ export function relaySseEagerBounded(
       return null;
     }
   };
+  /**
+   * Same tail, except that a refusal the boundary already captured outranks the
+   * read failure that followed it — the upstream ended the turn before the
+   * socket did (#5176).
+   */
+  const encodeTerminalTail = (error: unknown): Uint8Array | null => {
+    const refusalCode = terminalBoundary.upstreamRefusalCode();
+    const refusalMessage = terminalBoundary.upstreamError();
+    if (refusalCode === undefined || refusalMessage === undefined) {
+      return encodeFailedTail(error);
+    }
+    try {
+      return refusalFailedTailFrame(terminalEncoder, refusalMessage, refusalCode);
+    } catch {
+      return null;
+    }
+  };
   const rewriteDecoder = activeRewrite ? new TextDecoder() : null;
   const rewriteEncoder = activeRewrite ? new TextEncoder() : null;
   const rewriteBudget = opts?.rewriteBudget;
@@ -313,7 +331,11 @@ export function relaySseEagerBounded(
             const upstreamError = terminalBoundary.upstreamError() ?? opts?.upstreamError;
             const upstreamErrorFrame = upstreamError === undefined
               ? adapterEofFrame
-              : upstreamErrorTailFrame(terminalEncoder, upstreamError);
+              : upstreamErrorTailFrame(
+                terminalEncoder,
+                upstreamError,
+                terminalBoundary.upstreamRefusalCode(),
+              );
             queuedBytes += upstreamErrorFrame.byteLength + terminalSentinel.byteLength;
             try {
               controllerRef?.enqueue(upstreamErrorFrame);
@@ -439,7 +461,7 @@ export function relaySseEagerBounded(
         // getters, toString) that re-entrantly cancel the client or abort the
         // upstream. Build the tail FIRST, then re-check eligibility before
         // committing to the synthetic terminal (adversarial review blocker).
-        const tail = encodeFailedTail(err);
+        const tail = encodeTerminalTail(err);
         if (tail && canDeliver()) {
           // Inspection and client framing have separate bounded parsers. If
           // inspection resynchronized after an oversized frame and observed a