@bitkyc08/opencodex 2.82.0 → 2.83.0

package/src/server/management/grok-coupon-routes.ts

@@ -11,6 +11,7 @@
 
 import { jsonResponse } from "../auth-cors";
 import type { ManagementContext } from "./context";
+import { ConfigMutationLockError } from "../../config/mutation-lock";
 import { isCodexResetCreditOperationId } from "../../codex/reset-credit-recovery";
 import { getValidAccessSnapshotForAccount } from "../../oauth";
 import { listAccounts, captureOAuthAccountSelection } from "../../oauth/store";
@@ -20,8 +21,12 @@ import {
   type GrokResetCoupon,
 } from "../../grok/reset-coupons";
 import {
+  getGrokResetCouponOperationAccountId,
+  markGrokResetCouponAttempt,
   openGrokResetCouponOperation,
   recordGrokResetCouponSettlement,
+  readGrokResetCouponTerminalReplay,
+  settleGrokResetCouponPreflightRefusal,
   type GrokResetCouponOperationRecord,
 } from "../../grok/reset-coupon-ledger";
 
@@ -41,6 +46,11 @@ export interface GrokConsumeCouponRequestBody {
   operationId?: string;
 }
 
+// A recent attempt can still be in flight. Older attempts may be inspected,
+// but a remaining token is not proof that the original request cannot land.
+const GROK_COUPON_ATTEMPT_STALE_MS = 90_000;
+const grokCouponInFlightAttempts = new Set<string>();
+
 function resolveTargetAccountId(requestedAccountId?: string): string {
   if (requestedAccountId && requestedAccountId.trim() !== "") {
     return requestedAccountId.trim();
@@ -130,6 +140,10 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
 
     const { accountId: rawAccountId, tokenId: requestedTokenId, operationId } = body;
 
+    if (requestedTokenId !== undefined && (typeof requestedTokenId !== "string" || requestedTokenId.trim() === "")) {
+      return jsonResponse({ error: { code: "invalid_token_id", message: "tokenId must be a non-empty string" } }, 400, req, config);
+    }
+
     if (operationId !== undefined && !isCodexResetCreditOperationId(operationId)) {
       return jsonResponse(
         { error: { code: "invalid_operation_id", message: "operationId must be a valid UUIDv4" } },
@@ -139,9 +153,16 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
       );
     }
 
+    let recordedAccountId: string | undefined;
+    if (rawAccountId === undefined && operationId !== undefined) {
+      try { recordedAccountId = getGrokResetCouponOperationAccountId(operationId); }
+      catch {
+        return jsonResponse({ error: { code: "ledger_unavailable", message: "Coupon ledger could not be read or locked; no redemption was attempted" } }, 503, req, config);
+      }
+    }
     let accountId: string;
     try {
-      accountId = resolveTargetAccountId(rawAccountId);
+      accountId = resolveTargetAccountId(rawAccountId ?? recordedAccountId);
     } catch (err) {
       return jsonResponse(
         { error: { code: "no_account", message: err instanceof Error ? err.message : String(err) } },
@@ -165,26 +186,106 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
 
     // Journaling and Idempotency settlement check
     const effectiveOpId = operationId ?? crypto.randomUUID();
-    const opRecord = openGrokResetCouponOperation({
-      accountId,
-      tokenId: requestedTokenId,
-      operationId: effectiveOpId,
-    });
+    if (grokCouponInFlightAttempts.has(effectiveOpId)) return jsonResponse({ error: {
+      code: "attempt_in_progress", message: "This operation still has an active request; retry later",
+    } }, 409, req, config);
+    let opRecord: GrokResetCouponOperationRecord;
+    try {
+      opRecord = openGrokResetCouponOperation({ accountId, tokenId: requestedTokenId, operationId: effectiveOpId });
+    } catch {
+      return jsonResponse({ error: { code: "ledger_unavailable", message: "Coupon ledger could not be read or locked; no redemption was attempted" } }, 503, req, config);
+    }
+
+    let resolvedTokenId = requestedTokenId ?? opRecord.tokenId;
+    let resolvedTokenValidityEnd: number | undefined;
 
     if (opRecord.kind === "replay") {
-      return jsonResponse(
-        {
-          code: opRecord.code,
-          replayed: true,
-          tokenId: opRecord.tokenId,
-          settledAt: opRecord.settledAt,
-        },
-        200,
-        req,
-        config,
-      );
+      if (opRecord.code !== undefined) {
+        return jsonResponse(
+          {
+            code: opRecord.code,
+            replayed: true,
+            tokenId: opRecord.tokenId,
+            settledAt: opRecord.settledAt,
+          },
+          200,
+          req,
+          config,
+        );
+      }
+      if (opRecord.tokenId === undefined) {
+        // Legacy opens may already have dispatched without recording a token.
+        return jsonResponse({ operationId: effectiveOpId, error: {
+          code: "attempt_unresolved", message: "The prior operation has no recorded token; preserve this operationId and do not create a replacement attempt",
+        } }, 409, req, config);
+      }
+      // "attempted" with no recorded outcome: the spend call fired (or the
+      // process died right after the mark) but nothing was settled. Never
+      // replay this as a success — reconcile against upstream instead. A
+      // Remaining-token availability cannot identify the original request's
+      // outcome, and a listed token cannot rule out delayed completion.
+      if (requestedTokenId !== undefined && requestedTokenId !== opRecord.tokenId) {
+        // The retry names a different coupon than the one marked: spending
+        // either of them would surprise the caller — refuse and let them
+        // retry with the recorded token and preserve the operationId.
+        return jsonResponse(
+          {
+            error: {
+              code: "operation_token_mismatch",
+              message: "Operation was attempted with a different coupon; preserve the operationId and retry with the recorded tokenId",
+            },
+          },
+          409,
+          req,
+          config,
+        );
+      }
+      if (
+        opRecord.attemptedAt === undefined ||
+        Date.now() - opRecord.attemptedAt < GROK_COUPON_ATTEMPT_STALE_MS
+      ) {
+        // A fresh attempt may still be in flight in the original request —
+        // no additional upstream inspection is needed until that window ends.
+        // Older attempts are inspected without another redemption.
+        return jsonResponse(
+          { operationId: effectiveOpId,
+            error: {
+              code: "attempt_in_progress",
+              message: "A redemption attempt for this operation is recent and may still be running; retry later",
+            },
+          },
+          409,
+          req,
+          config,
+        );
+      }
+      let remainingTokens: GrokResetCoupon[];
+      try {
+        const remaining = await getGrokRemainingResets({ accessToken: tokenSnapshot.accessToken });
+        remainingTokens = remaining.tokens;
+      } catch (err) {
+        return jsonResponse(
+          { operationId: effectiveOpId, error: { code: "attempt_reconcile_failed", message: err instanceof Error ? err.message : String(err) } },
+          502,
+          req,
+          config,
+        );
+      }
+      // Availability cannot identify which request consumed a coupon. Even a
+      // missing, still-valid token does not confirm this operation succeeded.
+      const listed = remainingTokens.some((t) => t.tokenId === opRecord.tokenId);
+      return jsonResponse({ operationId: effectiveOpId, error: {
+        code: "attempt_unresolved",
+        message: listed
+          ? "The prior redemption may still complete; its listed coupon will not be redeemed again"
+          : "The coupon is no longer listed, but this operation's outcome is unconfirmed; no redemption will be repeated",
+      } }, 409, req, config);
     }
 
+    if (opRecord.kind === "token-mismatch") return jsonResponse({ error: {
+      code: "operation_token_mismatch", message: "Operation ID was previously registered with a different coupon",
+    } }, 409, req, config);
+
     if (opRecord.kind === "identity-mismatch") {
       return jsonResponse(
         {
@@ -213,16 +314,48 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
       );
     }
 
-    let resolvedTokenId = requestedTokenId;
-    if (!resolvedTokenId) {
+    const settlePreflightRefusal = (code: string, tokenId?: string): Response | null => {
+      try {
+        const result = settleGrokResetCouponPreflightRefusal({
+          operationId: effectiveOpId, accountId, tokenId, code,
+          status: "failed", expectedStatus: "open",
+        });
+        if (result.kind === "recorded") return null;
+        if (result.kind === "replay") return jsonResponse({
+          code: result.code, replayed: true, tokenId: result.tokenId, settledAt: result.settledAt,
+        }, 200, req, config);
+        return jsonResponse({ error: {
+          code: "operation_state_changed",
+          message: "Another request changed this operation during inspection; retry the same operationId to read its durable state",
+        } }, 409, req, config);
+      } catch {
+        return jsonResponse({ error: {
+          code: "ledger_unavailable", message: "Coupon refusal could not be recorded; no redemption was attempted",
+        } }, 503, req, config);
+      }
+    };
+
+    {
+      // Always consult the upstream list: it resolves the token when the
+      // caller omits one, and — for an explicit tokenId — proves the coupon
+      // still exists. Captured validity remains journal metadata, never proof
+      // that this operation succeeded during a later reconciliation.
+      let tokens: GrokResetCoupon[];
       try {
         const remaining = await getGrokRemainingResets({ accessToken: tokenSnapshot.accessToken });
-        if (!remaining.tokens || remaining.tokens.length === 0) {
-          recordGrokResetCouponSettlement({
-            operationId: effectiveOpId,
-            code: "no_coupons_available",
-            status: "failed",
-          });
+        tokens = remaining.tokens ?? [];
+      } catch (err) {
+        return jsonResponse(
+          { error: { code: "fetch_resets_failed", message: err instanceof Error ? err.message : String(err) } },
+          502,
+          req,
+          config,
+        );
+      }
+      if (!resolvedTokenId) {
+        if (tokens.length === 0) {
+          const changed = settlePreflightRefusal("no_coupons_available");
+          if (changed) return changed;
           return jsonResponse(
             { error: { code: "no_coupons_available", message: "No reset coupons available to redeem" } },
             400,
@@ -230,29 +363,131 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
             config,
           );
         }
-        resolvedTokenId = remaining.tokens[0].tokenId;
-      } catch (err) {
+        resolvedTokenId = tokens[0].tokenId;
+      }
+      const match = tokens.find((t) => t.tokenId === resolvedTokenId);
+      if (!match) {
+        // The requested coupon is already consumed or expired upstream —
+        // redeeming it would only surface an upstream error.
+        const changed = settlePreflightRefusal("coupon_unavailable", resolvedTokenId);
+        if (changed) return changed;
         return jsonResponse(
-          { error: { code: "fetch_resets_failed", message: err instanceof Error ? err.message : String(err) } },
-          502,
+          {
+            error: {
+              code: "coupon_unavailable",
+              message: "The requested reset coupon is no longer available upstream",
+            },
+          },
+          409,
           req,
           config,
         );
       }
+      const parsedEnd = Date.parse(match.validityEnd);
+      if (!Number.isNaN(parsedEnd)) resolvedTokenValidityEnd = parsedEnd;
+    }
+
+    if (resolvedTokenId === undefined) {
+      // Unreachable: every path above either resolves a token or returns.
+      return jsonResponse(
+        { error: { code: "token_unresolved", message: "No reset coupon token could be resolved" } },
+        500,
+        req,
+        config,
+      );
+    }
+
+    if (grokCouponInFlightAttempts.has(effectiveOpId)) {
+      // The original request holding this operation is still running in this
+      // process — its upstream spend has not concluded, so nothing may spend
+      // on this operationId again regardless of how stale the mark looks.
+      return jsonResponse(
+        {
+          error: {
+            code: "attempt_in_progress",
+            message: "A redemption attempt for this operation is still running; retry later",
+          },
+        },
+        409,
+        req,
+        config,
+      );
     }
 
+    grokCouponInFlightAttempts.add(effectiveOpId);
     try {
-      const redeemResult = await redeemGrokResetCoupon({
-        accessToken: tokenSnapshot.accessToken,
-        tokenId: resolvedTokenId,
-      });
+      // Record the attempt BEFORE the spend call: a crash between redemption
+      // and settlement must still leave the operation non-open so a retry can
+      // never execute it again. The atomic claim admits exactly one contender;
+      // a failed mark write aborts here while nothing has been spent.
+      try {
+        const claimed = markGrokResetCouponAttempt(effectiveOpId, resolvedTokenId, undefined, undefined, resolvedTokenValidityEnd);
+        if (!claimed) {
+          // A concurrent request may already have reached a definitive outcome;
+          // replay it rather than holding the caller on a finished operation.
+          // A failed read proves nothing about the winner, so it stays uncertain:
+          // reporting a definitive error here would let the caller open a
+          // replacement operation while this one may already have spent.
+          let winner: ReturnType<typeof readGrokResetCouponTerminalReplay> = null;
+          try { winner = readGrokResetCouponTerminalReplay(effectiveOpId, accountId, resolvedTokenId); } catch { winner = null; }
+          if (winner) return jsonResponse({
+            code: winner.code, replayed: true, tokenId: winner.tokenId, settledAt: winner.settledAt,
+          }, 200, req, config);
+          return jsonResponse({ error: {
+            code: "attempt_in_progress", message: "Another request already claimed this operation; no redemption was attempted",
+          } }, 409, req, config);
+        }
+      } catch (err) {
+        return jsonResponse(
+          { error: { code: "attempt_mark_failed", message: err instanceof Error ? err.message : String(err) } },
+          500,
+          req,
+          config,
+        );
+      }
 
-      recordGrokResetCouponSettlement({
-        operationId: effectiveOpId,
-        tokenId: resolvedTokenId,
-        code: "redeemed",
-        status: "success",
-      });
+      try {
+        await redeemGrokResetCoupon({
+          accessToken: tokenSnapshot.accessToken,
+          tokenId: resolvedTokenId,
+        });
+      } catch (err) {
+        // A transport error cannot prove that the irreversible request failed.
+        // Keep "attempted" so a later retry can inspect without dispatching again.
+        return jsonResponse(
+          { operationId: effectiveOpId, accountId, tokenId: resolvedTokenId, error: {
+            code: "attempt_unresolved",
+            message: "Redemption delivery is unconfirmed; reuse this operationId to inspect its state and do not create a replacement attempt",
+          } },
+          502,
+          req,
+          config,
+        );
+      }
+
+      // A confirmed redemption remains successful even when settlement fails.
+      // The existing claim protects retries if settlement does not land.
+      let settlementRecorded = false;
+      for (let attempt = 0; attempt < 5; attempt += 1) {
+        try {
+          settlementRecorded = recordGrokResetCouponSettlement({
+            operationId: effectiveOpId,
+            accountId,
+            tokenId: resolvedTokenId,
+            code: "redeemed",
+            status: "success",
+            expectedStatus: "attempted",
+          });
+          break;
+        } catch (error) {
+          // Retry only transient acquisition contention, never an unsafe or
+          // unreadable ledger, a changed claim, or the upstream redemption.
+          const cause = error instanceof ConfigMutationLockError ? error.cause : undefined;
+          if (!cause || typeof cause !== "object" || !("code" in cause)
+            || cause.code !== "SQLITE_BUSY" || attempt === 4) break;
+          await Bun.sleep(20);
+        }
+      }
 
       return jsonResponse(
         {
@@ -262,24 +497,14 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
           tokenId: resolvedTokenId,
           accountId,
           operationId: effectiveOpId,
+          settlementRecorded,
         },
         200,
         req,
         config,
       );
-    } catch (err) {
-      recordGrokResetCouponSettlement({
-        operationId: effectiveOpId,
-        tokenId: resolvedTokenId,
-        code: "redeem_failed",
-        status: "failed",
-      });
-      return jsonResponse(
-        { error: { code: "redeem_failed", message: err instanceof Error ? err.message : String(err) } },
-        502,
-        req,
-        config,
-      );
+    } finally {
+      grokCouponInFlightAttempts.delete(effectiveOpId);
     }
   }
 

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

@@ -14,6 +14,7 @@ import { projectLinkStatus, type LinkStatusDto } from "../../link/status-project
 import { isLinkPort } from "../../link/ports";
 import { joinHome, type ClientLinkJoinDeps } from "../../client/link-join";
 import { clientLinkTunnelStatus } from "../../client/link-tunnel";
+import { withConfigMutationLockSync } from "../../config/mutation-lock";
 import type { ManagementContext } from "./context";
 import { readManagementJsonBodyOr } from "./body";
 import { issueApiKeyInProcess, revokeApiKeyInProcess, type IssuedApiKey } from "./oauth-account-routes";
@@ -228,10 +229,12 @@ async function compensateNewLink(ctx: ManagementContext, state: LinkRouteState,
   if (!revoked) {
     try { await state.supervisor.stopLink(record.id); } catch { /* retain the record and failure marker */ }
     try {
-      const current = readStoreFor(ctx);
-      if (!current.links.some(link => link.id === record.id)) {
-        writeStoreFor(ctx, { ...current, links: [...current.links, record] });
-      }
+      withConfigMutationLockSync(() => {
+        const current = readStoreFor(ctx);
+        if (!current.links.some(link => link.id === record.id)) {
+          writeStoreFor(ctx, { ...current, links: [...current.links, record] });
+        }
+      });
     } catch {
       // The in-memory marker still makes the residual visible when persistence is unavailable.
     }
@@ -239,11 +242,16 @@ async function compensateNewLink(ctx: ManagementContext, state: LinkRouteState,
   }
   try { await state.supervisor.stopLink(record.id); } catch { return compensationFailure(ctx, state, record, "stop"); }
   try {
-    const current = readStoreFor(ctx);
-    const next = { ...current, links: current.links.filter(link => link.id !== record.id) };
-    if (next.links.length !== current.links.length) {
-      writeStoreFor(ctx, next);
-    }
+    // Read→filter→write stays one section of the shared mutation lock: a sibling
+    // route's create must not land between the read and the rename and vanish.
+    const next = withConfigMutationLockSync(() => {
+      const current = readStoreFor(ctx);
+      const filtered = { ...current, links: current.links.filter(link => link.id !== record.id) };
+      if (filtered.links.length !== current.links.length) {
+        writeStoreFor(ctx, filtered);
+      }
+      return filtered;
+    });
     clearCompensationFailed(record.id, compensationPath());
     state.compensationFailures?.delete(record.id);
     if (next.links.length === 0) await state.listener.close();
@@ -362,14 +370,20 @@ async function apply(ctx: ManagementContext, state: LinkRouteState): Promise<Res
   const record = { id, alias: body.alias, direction: "hub-initiated" as const, hostKeyFingerprint: confirmed.fingerprint, tunnelPort: remotePort, apiKeyId: issued.id, createdAt: new Date((ctx.deps.now ?? Date.now)()).toISOString() };
   let store: LinkStore;
   try {
-    const current = readStoreFor(ctx);
-    if (current.links.some(link => link.alias === body.alias && link.direction === "hub-initiated")) {
+    // Duplicate-check and append under one mutation-lock section: two writers
+    // racing this check could otherwise both pass it and append, losing one link.
+    const writeOutcome = withConfigMutationLockSync((): "dup" | "written" => {
+      const current = readStoreFor(ctx);
+      if (current.links.some(link => link.alias === body.alias && link.direction === "hub-initiated")) return "dup";
+      store = { ...current, links: [...current.links, record] };
+      writeStoreFor(ctx, store);
+      return "written";
+    });
+    if (writeOutcome === "dup") {
       const compensation = await compensateNewLink(ctx, state, record);
       if (compensation) return compensation;
       return fail("link_exists", "A link for this alias already exists.", 409);
     }
-    store = { ...current, links: [...current.links, record] };
-    writeStoreFor(ctx, store);
     await state.listener.ensureStarted();
     if (state.listener.status().state !== "listening") {
       const compensation = await compensateNewLink(ctx, state, record);
@@ -430,13 +444,18 @@ async function issue(ctx: ManagementContext): Promise<Response> {
   const record = { id, alias: body.alias, direction: "client-initiated" as const, hostKeyFingerprint: null, tunnelPort: body.tunnelPort, apiKeyId: issued.id, createdAt: new Date((ctx.deps.now ?? Date.now)()).toISOString() };
   let failureCode = "link_issue_failed";
   try {
-    const current = readStoreFor(ctx);
-    if (current.links.some(link => link.id === id)) throw new Error("link id collision");
-    if (current.links.some(link => link.alias === body.alias && link.direction === "client-initiated")) {
+    // Same atomic duplicate-check+append as the hub-initiated branch.
+    const writeOutcome = withConfigMutationLockSync((): "dup" | "written" => {
+      const current = readStoreFor(ctx);
+      if (current.links.some(link => link.id === id)) throw new Error("link id collision");
+      if (current.links.some(link => link.alias === body.alias && link.direction === "client-initiated")) return "dup";
+      writeStoreFor(ctx, { ...current, links: [...current.links, record] });
+      return "written";
+    });
+    if (writeOutcome === "dup") {
       const compensation = await compensateNewLink(ctx, state, record);
       return compensation ?? fail("link_exists", "A link for this alias already exists.", 409);
     }
-    writeStoreFor(ctx, { ...current, links: [...current.links, record] });
     await state.listener.ensureStarted();
     if (state.listener.status().state !== "listening") {
       failureCode = "listener_unavailable";
@@ -538,9 +557,12 @@ async function remove(ctx: ManagementContext, state: LinkRouteState, id: string)
   if (!revokeKeyIdempotent(ctx, record.apiKeyId)) return fail("key_revoke_failed", "The link key could not be revoked.", 502);
   let next: LinkStore;
   try {
-    const latest = readStoreFor(ctx);
-    next = { ...latest, links: latest.links.filter(link => link.id !== id) };
-    if (next.links.length !== latest.links.length) writeStoreFor(ctx, next);
+    next = withConfigMutationLockSync(() => {
+      const latest = readStoreFor(ctx);
+      const filtered = { ...latest, links: latest.links.filter(link => link.id !== id) };
+      if (filtered.links.length !== latest.links.length) writeStoreFor(ctx, filtered);
+      return filtered;
+    });
     clearCompensationFailed(id, compensationPath());
   } catch { return fail("link_remove_failed", "The link record could not be removed.", 503); }
   state.compensationFailures?.delete(id);

package/src/server/management/route-registry.ts

@@ -361,8 +361,8 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "GET", path: "/api/protocols", module: "server/management/protocol-routes", mutates: false },
   { method: "POST", path: "/api/protocols/plan", module: "server/management/protocol-routes", mutates: false },
   { method: "PATCH", path: "/api/protocols/settings", module: "server/management/protocol-routes", mutates: true },
-  { method: "GET", path: "/api/workflow-budget", module: "server/management/workflow-budget-routes", mutates: false, exempt: { reason: "deferred-verb", why: "Reading a root's live budget is owed a CLI verb -- an operator staring at a 429 is usually already in a terminal -- but the ledger is process memory with no local transport to read it through, so the verb has to be an HTTP call the CLI does not yet make.", owner: "260915_workflow_budget_window wfc", ownerDoc: "devlog/_plan/260915_workflow_budget_window/030_wfc_diff_plan.md" } },
-  { method: "POST", path: "/api/workflow-budget/clear", module: "server/management/workflow-budget-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Clearing one root is owed the same verb as the read above and for the same reason. It is deliberately not shipped as a verb in this work-phase: the read comes first, because an operator who cannot see which ceiling fired has no basis for deciding to forgive it.", owner: "260915_workflow_budget_window wfc", ownerDoc: "devlog/_plan/260915_workflow_budget_window/030_wfc_diff_plan.md" } },
+  { method: "GET", path: "/api/workflow-budget", module: "server/management/workflow-budget-routes", mutates: false, exempt: { reason: "deferred-verb", why: "Reading a root's live budget is owed a CLI verb -- an operator staring at a 429 is usually already in a terminal -- but the ledger is process memory with no local transport to read it through, so the verb has to be an HTTP call the CLI does not yet make.", owner: "260915_workflow_budget_window wfc", ownerDoc: "devlog/_fin/260915_workflow_budget_window/030_wfc_diff_plan.md" } },
+  { method: "POST", path: "/api/workflow-budget/clear", module: "server/management/workflow-budget-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Clearing one root is owed the same verb as the read above and for the same reason. It is deliberately not shipped as a verb in this work-phase: the read comes first, because an operator who cannot see which ceiling fired has no basis for deciding to forgive it.", owner: "260915_workflow_budget_window wfc", ownerDoc: "devlog/_fin/260915_workflow_budget_window/030_wfc_diff_plan.md" } },
   // server/management/request-history-routes
   { method: "GET", path: "/api/request-history", module: "server/management/request-history-routes", mutates: false },
   // server/management/routing-analytics-routes

package/src/server/relay-eager.ts

@@ -338,6 +338,8 @@ export function relaySseEagerBounded(
                 upstreamError,
                 terminalBoundary.upstreamRefusalCode(),
                 opts?.maskCredential,
+                terminalBoundary.upstreamErrorType(),
+                terminalBoundary.upstreamErrorCode(),
               );
             queuedBytes += upstreamErrorFrame.byteLength + terminalSentinel.byteLength;
             try {

package/src/server/relay.ts

@@ -6,13 +6,14 @@ import {
   isCyberPolicyCode,
   isCyberPolicyMessage,
   isTerminalRefusalCode,
+  recognizedUpstreamError,
   safetyRefusalCodeFromMessage,
   terminalRefusalFallbackMessage,
   upstreamErrorMessageFromPayload,
 } from "../lib/errors";
 import { redactSecretString } from "../lib/redact";
 import { isTranslatorBudgetExceededError } from "../lib/translator-budget";
-import { carryReplayRefusal } from "../lib/upstream-retry";
+import { carryReplayRefusal, isReplayRefusalResponse } from "../lib/upstream-retry";
 import { isUsageDebugEnabled } from "../usage/debug";
 import {
   addRequestLog,
@@ -168,25 +169,28 @@ export function failedTailFrame(encoder: TextEncoder, err: unknown, maskCredenti
  * classifies this terminal by `error.code` alone and retries everything outside
  * its fatal set (codex-rs/codex-api/src/sse/responses.rs:423-450), so stamping
  * `upstream_server_error` on a refusal delivered it as a retryable disconnect
- * and drove the reconnect loop in #5176. Without a refusal code the terminal is
- * unchanged: a genuine transport failure stays retryable, which is what it is.
+ * and drove the reconnect loop in #5176. Without a refusal code the terminal
+ * carries only recognized rate-limit/overload classes; unknown codes stay generic.
  */
 export function upstreamErrorTailFrame(
   encoder: TextEncoder,
   message: string,
   refusalCode?: string,
   maskCredential?: (text: string) => string,
+  errorType?: string,
+  errorCode?: string,
 ): Uint8Array {
   return encoder.encode(
-    `event: response.failed\ndata: ${upstreamErrorFailedPayload(message, refusalCode, maskCredential)}\n\n`,
+    `event: response.failed\ndata: ${upstreamErrorFailedPayload(message, refusalCode, maskCredential, errorType, errorCode)}\n\n`,
   );
 }
 
-function upstreamErrorFailedPayload(message: string, refusalCode?: string, maskCredential?: (text: string) => string): string {
+function upstreamErrorFailedPayload(message: string, refusalCode?: string, maskCredential?: (text: string) => string, errorType?: string, errorCode?: string): string {
   const diagnostic = redactSecretString(message);
+  const recognized = recognizedUpstreamError({ type: errorType, code: errorCode });
   const error = {
-    type: refusalCode === undefined ? "upstream_error" : "invalid_request_error",
-    code: refusalCode === undefined ? "upstream_server_error" : (maskCredential?.(refusalCode) ?? refusalCode),
+    type: refusalCode === undefined ? (recognized?.type ?? "upstream_error") : "invalid_request_error",
+    code: refusalCode === undefined ? (recognized?.code ?? "upstream_server_error") : (maskCredential?.(refusalCode) ?? refusalCode),
     message: (maskCredential?.(diagnostic) ?? diagnostic).slice(0, MAX_TAIL_ERROR_MESSAGE_CHARS),
   };
   return JSON.stringify({
@@ -549,6 +553,8 @@ export function relaySseWithFailedTail(
                   upstreamError,
                   terminalBoundary.upstreamRefusalCode(),
                   opts?.maskCredential,
+                  terminalBoundary.upstreamErrorType(),
+                  terminalBoundary.upstreamErrorCode(),
                 ));
               controller.enqueue(doneFrame(encoder));
             }
@@ -898,6 +904,11 @@ export function responseWithDeferredRequestLog(
   logCtx: RequestLogContext,
   addLog: (entry: RequestLogEntry) => void = addRequestLog,
 ): Response {
+  // A synthetic 429 is a transport verdict, not evidence that the provider declined the turn.
+  if (isReplayRefusalResponse(response)) {
+    logCtx.causeHint = "transport-ambiguous";
+    logCtx.terminalSource = "synthetic";
+  }
   const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
   if (isUsageDebugEnabled() && !logCtx.usageDebugContentType && contentType) {
     logCtx.usageDebugContentType = contentType;

package/src/server/request-log-failure-attribution.ts

@@ -21,6 +21,8 @@ export interface FinalRequestAttributionFacts {
   readonly closeReason?: "terminal" | "client_cancel" | "non_stream" | "body_stall" | "body_overflow" | undefined;
   readonly transportPhase?: "pre_headers" | "mid_stream" | "terminal_sse" | undefined;
   readonly terminalSource?: "upstream" | "synthetic" | undefined;
+  /** A failure cause proved by the transport's in-process verdict. */
+  readonly causeHint?: RequestFailureCause | undefined;
   /** The REQUEST's first-output observation, not the final attempt's. See below. */
   readonly outputObserved: boolean;
   readonly locallyAnswered: boolean;
@@ -53,6 +55,7 @@ export function attributeFinalRequest(facts: FinalRequestAttributionFacts): Stam
     ...(facts.closeReason ? { closeReason: facts.closeReason } : {}),
     ...(facts.transportPhase ? { transportPhase: facts.transportPhase } : {}),
     ...(facts.terminalSource ? { terminalSource: facts.terminalSource } : {}),
+    ...(facts.causeHint ? { causeHint: facts.causeHint } : {}),
     ...(facts.attempt?.streamAborted === true ? { streamAborted: true } : {}),
     outputObserved: facts.outputObserved,
     // The one fact that can raise a stage above `semantic-output`, and the reason it is counted