The best way to control Claude Code, Codex and more from any computer or phone
fix(codex): preserve terminal connection failure categories (#30639)
Co-authored-by: Trevor Edwards <9443483+trevoedwards@users.noreply.github.com> Co-authored-by: maria-rcks <maria@kuuro.net> Co-authored-by: Julius Marminge <julius0216@outlook.com>
Trevor committed
Nov 14, 2026 at 16:54 UTC
6b9d90f1213723226b630ff883ea79b3299412f0
2 files changed
+270
-26
apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.test.ts
+193
-14
@@ -7006,6 +7006,37 @@ describe("CodexAdapterV2 post-settle continuation", () => {
7006
notification: false,
7007
expectedClass: "provider_error",
7008
},
7009
+ ...([false, true] as const).map(
7010
+ (notification) =>
7011
+ ({
7012
+ name: `disconnected-${notification ? "notification" : "completion"}`,
7013
+ code: "responseStreamDisconnected",
7014
+ errorInfo: { responseStreamDisconnected: { httpStatusCode: null } },
7015
+ notification,
7016
+ expectedClass: "transport_error",
7017
+ }) as const,
7018
+ ),
7019
+ {
7020
+ name: "connection-failed",
7021
+ code: "responseStreamConnectionFailed",
7022
+ errorInfo: { responseStreamConnectionFailed: { httpStatusCode: null } },
7023
+ notification: false,
7024
+ expectedClass: "transport_error",
7025
+ },
7026
+ {
7027
+ name: "http-connection-failed",
7028
+ code: "httpConnectionFailed",
7029
+ errorInfo: { httpConnectionFailed: { httpStatusCode: null } },
7030
+ notification: false,
7031
+ expectedClass: "transport_error",
7032
+ },
7033
+ {
7034
+ name: "http-provider-failure",
7035
+ code: "httpConnectionFailed",
7036
+ errorInfo: { httpConnectionFailed: { httpStatusCode: 503 } },
7037
+ notification: false,
7038
+ expectedClass: "provider_error",
7039
+ },
7040
{
7041
name: "chatgpt-workspace-limit",
7042
code: "other",
@@ -7040,6 +7071,14 @@ describe("CodexAdapterV2 post-settle continuation", () => {
7071
expectedCode: "subscription_sharing_usage_limit_exceeded",
7072
expectedMessage: "Usage settings",
7073
},
7074
+ {
7075
+ name: "terminal-disconnection",
7076
+ code: "responseStreamDisconnected",
7077
+ notification: false,
7078
+ terminalMessage: "Connection lost.",
7079
+ terminalErrorInfo: { responseStreamDisconnected: { httpStatusCode: null } },
7080
+ expectedClass: "transport_error",
7081
+ },
7082
{
7083
name: "sharing-code-mention-retry",
7084
code: "responseStreamDisconnected",
@@ -7049,6 +7088,71 @@ describe("CodexAdapterV2 post-settle continuation", () => {
7088
willRetry: true,
7089
expectedClass: "transport_error",
7090
},
7091
+ ...(
7092
+ [
7093
+ {
7094
+ name: "generic-disconnection",
7095
+ status: null,
7096
+ terminalMessage: "Connection lost.",
7097
+ expectedClass: "transport_error",
7098
+ },
7099
+ {
7100
+ name: "generic-replacement",
7101
+ status: null,
7102
+ terminalMessage: "A different failure.",
7103
+ expectedClass: "provider_error",
7104
+ },
7105
+ {
7106
+ name: "generic-http-status",
7107
+ status: 503,
7108
+ terminalMessage: "Connection lost.",
7109
+ expectedClass: "provider_error",
7110
+ },
7111
+ {
7112
+ name: "generic-truncated-replacement",
7113
+ status: null,
7114
+ details: `${"Connection lost. ".repeat(300)}Network cause.`,
7115
+ terminalMessage: `${"Connection lost. ".repeat(300)}Different cause.`,
7116
+ expectedClass: "provider_error",
7117
+ },
7118
+ {
7119
+ name: "generic-terminal-status",
7120
+ status: null,
7121
+ terminalMessage: "Connection lost.",
7122
+ terminalErrorInfo: { responseStreamDisconnected: { httpStatusCode: 503 } },
7123
+ expectedClass: "provider_error",
7124
+ },
7125
+ {
7126
+ name: "generic-exhaustion",
7127
+ status: null,
7128
+ terminalMessage: "Connection lost.",
7129
+ terminalErrorInfo: { responseTooManyFailedAttempts: { httpStatusCode: null } },
7130
+ completionErrorInfo: { responseTooManyFailedAttempts: { httpStatusCode: null } },
7131
+ expectedClass: "transport_error",
7132
+ },
7133
+ {
7134
+ name: "generic-blank-details",
7135
+ status: null,
7136
+ details: " ",
7137
+ terminalMessage: "Provider stopped this request.",
7138
+ expectedClass: "transport_error",
7139
+ },
7140
+ {
7141
+ name: "generic-exhaustion-status",
7142
+ status: null,
7143
+ terminalMessage: "Connection lost.",
7144
+ terminalErrorInfo: { responseTooManyFailedAttempts: { httpStatusCode: 503 } },
7145
+ completionErrorInfo: { responseTooManyFailedAttempts: { httpStatusCode: null } },
7146
+ expectedClass: "provider_error",
7147
+ },
7148
+ ] as const
7149
+ ).map((scenario) => ({
7150
+ ...scenario,
7151
+ code: "responseStreamDisconnected" as const,
7152
+ errorInfo: { responseStreamDisconnected: { httpStatusCode: scenario.status } },
7153
+ notification: true,
7154
+ details: "details" in scenario ? scenario.details : "Connection lost.",
7155
+ })),
7156
] as const)("classifies Codex terminal failures from $name evidence", (scenario) =>
7157
Effect.gen(function* () {
7158
const nativeThreadId = `native-limit-${scenario.name}`;
@@ -7172,7 +7276,10 @@ describe("CodexAdapterV2 post-settle continuation", () => {
7276
params: {
7277
threadId: nativeThreadId,
7278
turnId: nativeTurnId,
7175
- willRetry: scenario.name === "retry" || "willRetry" in scenario,
7279
+ willRetry:
7280
+ scenario.name === "retry" ||
7281
+ "willRetry" in scenario ||
7282
+ "terminalMessage" in scenario,
7283
error: {
7284
message,
7285
codexErrorInfo: errorInfo,
@@ -7188,6 +7295,27 @@ describe("CodexAdapterV2 post-settle continuation", () => {
7295
},
7296
]
7297
: []),
7298
+ ...("terminalMessage" in scenario
7299
+ ? [
7300
+ {
7301
+ type: "emit_inbound" as const,
7302
+ label: "error/terminal",
7303
+ frame: {
7304
+ method: "error",
7305
+ params: {
7306
+ threadId: nativeThreadId,
7307
+ turnId: nativeTurnId,
7308
+ willRetry: false,
7309
+ error: {
7310
+ message: scenario.terminalMessage,
7311
+ codexErrorInfo:
7312
+ "terminalErrorInfo" in scenario ? scenario.terminalErrorInfo : "other",
7313
+ },
7314
+ },
7315
+ },
7316
+ },
7317
+ ]
7318
+ : []),
7319
{
7320
type: "emit_inbound",
7321
label: "turn/completed",
@@ -7198,12 +7326,24 @@ describe("CodexAdapterV2 post-settle continuation", () => {
7326
turn: {
7327
...makeCodexReplayTurn({ id: nativeTurnId, status: "failed" }),
7328
error: {
7201
- message: scenario.name === "replacement" ? "A different failure." : message,
7202
- ...(scenario.notification &&
7203
- scenario.name !== "matching-details" &&
7204
- !("details" in scenario)
7205
- ? {}
7206
- : { codexErrorInfo: errorInfo }),
7329
+ message:
7330
+ "terminalMessage" in scenario
7331
+ ? scenario.terminalMessage
7332
+ : scenario.name === "replacement"
7333
+ ? "A different failure."
7334
+ : message,
7335
+ ...("terminalMessage" in scenario
7336
+ ? {
7337
+ codexErrorInfo:
7338
+ "completionErrorInfo" in scenario
7339
+ ? scenario.completionErrorInfo
7340
+ : "other",
7341
+ }
7342
+ : scenario.notification &&
7343
+ scenario.name !== "matching-details" &&
7344
+ !("details" in scenario)
7345
+ ? {}
7346
+ : { codexErrorInfo: errorInfo }),
7347
},
7348
},
7349
},
@@ -7361,34 +7501,66 @@ describe("CodexAdapterV2 post-settle continuation", () => {
7501
// regression: #17501 Codex 429 retry exhaustion classifies as a usage limit
7502
it.effect.each([
7503
{
7504
+ code: "responseTooManyFailedAttempts",
7505
notificationStatus: 500,
7506
completionStatus: 429,
7507
willRetry: false,
7508
expectedClass: "usage_limit",
7509
},
7510
{
7511
+ code: "responseTooManyFailedAttempts",
7512
notificationStatus: 429,
7513
completionStatus: 500,
7514
willRetry: true,
7515
expectedClass: "provider_error",
7516
},
7517
{
7518
+ code: "responseTooManyFailedAttempts",
7519
notificationStatus: 429,
7520
completionStatus: null,
7521
willRetry: false,
7522
expectedClass: "usage_limit",
7523
},
7524
{
7525
+ code: "responseTooManyFailedAttempts",
7526
notificationStatus: 429,
7527
completionStatus: null,
7528
willRetry: true,
7529
expectedClass: "usage_limit",
7530
},
7531
+ {
7532
+ code: "responseStreamDisconnected",
7533
+ notificationStatus: null,
7534
+ completionStatus: 503,
7535
+ willRetry: false,
7536
+ expectedClass: "provider_error",
7537
+ },
7538
+ {
7539
+ code: "responseStreamDisconnected",
7540
+ notificationStatus: 503,
7541
+ completionStatus: null,
7542
+ willRetry: false,
7543
+ expectedClass: "transport_error",
7544
+ },
7545
+ {
7546
+ code: "responseStreamDisconnected",
7547
+ notificationStatus: null,
7548
+ completionStatus: 503,
7549
+ willRetry: true,
7550
+ expectedClass: "provider_error",
7551
+ },
7552
+ {
7553
+ code: "responseStreamDisconnected",
7554
+ notificationStatus: null,
7555
+ completionStatus: null,
7556
+ willRetry: false,
7557
+ expectedClass: "transport_error",
7558
+ },
7559
] as const)(
7388
- "honors completion HTTP status from $notificationStatus to $completionStatus (retry: $willRetry)",
7389
- ({ notificationStatus, completionStatus, expectedClass, willRetry }) =>
7560
+ "honors $code completion HTTP status from $notificationStatus to $completionStatus (retry: $willRetry)",
7561
+ ({ code, notificationStatus, completionStatus, expectedClass, willRetry }) =>
7562
Effect.gen(function* () {
7391
- const name = `${notificationStatus}-${completionStatus}-${willRetry}`;
7563
+ const name = `${code}-${notificationStatus}-${completionStatus}-${willRetry}`;
7564
const nativeThreadId = `native-exhaustion-status-${name}`;
7565
const nativeTurnId = `turn-exhaustion-status-${name}`;
7566
const message = "Provider stopped this request.";
@@ -7409,7 +7581,7 @@ describe("CodexAdapterV2 post-settle continuation", () => {
7581
error: {
7582
message,
7583
codexErrorInfo: {
7412
- responseTooManyFailedAttempts: { httpStatusCode: notificationStatus },
7584
+ [code]: { httpStatusCode: notificationStatus },
7585
},
7586
additionalDetails,
7587
},
@@ -7428,7 +7600,7 @@ describe("CodexAdapterV2 post-settle continuation", () => {
7600
error: {
7601
message,
7602
codexErrorInfo: {
7431
- responseTooManyFailedAttempts: { httpStatusCode: completionStatus },
7603
+ [code]: { httpStatusCode: completionStatus },
7604
},
7605
},
7606
},
@@ -7452,9 +7624,16 @@ describe("CodexAdapterV2 post-settle continuation", () => {
7624
assert.equal(terminal?.status, "failed");
7625
if (terminal?.status !== "failed") return;
7626
assert.equal(terminal.failure.class, expectedClass);
7455
- assert.equal(terminal.failure.code, "responseTooManyFailedAttempts");
7627
+ assert.equal(terminal.failure.code, code);
7628
assert.equal(terminal.threadDisposition, "reusable");
7457
- const notificationClass = notificationStatus === 429 ? "usage_limit" : "provider_error";
7629
+ const notificationClass =
7630
+ code === "responseTooManyFailedAttempts"
7631
+ ? notificationStatus === 429
7632
+ ? "usage_limit"
7633
+ : "provider_error"
7634
+ : notificationStatus === null
7635
+ ? "transport_error"
7636
+ : "provider_error";
7637
assert.equal(
7638
terminal.failure.message,
7639
expectedClass === notificationClass ? additionalDetails : message,
apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts
+77
-12
@@ -1194,6 +1194,35 @@ function codexUsageLimitError(
1194
);
1195
}
1196
1197
+function codexTerminalFailureClass(
1198
+ errorInfo: CodexErrorInfo | null | undefined,
1199
+ code: string | null,
1200
+) {
1201
+ if (codexUsageLimitError(code, errorInfo)) return "usage_limit";
1202
+ if (typeof errorInfo === "object" && errorInfo !== null) {
1203
+ const transport =
1204
+ "responseStreamDisconnected" in errorInfo
1205
+ ? errorInfo.responseStreamDisconnected
1206
+ : "responseStreamConnectionFailed" in errorInfo
1207
+ ? errorInfo.responseStreamConnectionFailed
1208
+ : "httpConnectionFailed" in errorInfo
1209
+ ? errorInfo.httpConnectionFailed
1210
+ : undefined;
1211
+ if (transport !== undefined && transport.httpStatusCode == null) return "transport_error";
1212
+ }
1213
+ return "provider_error";
1214
+}
1215
+
1216
+function codexTerminalErrorNeedsEvidence(
1217
+ errorInfo: CodexErrorInfo | null | undefined,
1218
+ code: string | null,
1219
+) {
1220
+ return (
1221
+ code === "other" ||
1222
+ (code === "responseTooManyFailedAttempts" && codexExhaustionHttpStatus(errorInfo) === null)
1223
+ );
1224
+}
1225
+
1226
/**
1227
* ChatGPT sharing reports its own reason inside Codex's generic turn error, so
1228
* the code it names replaces Codex's, and clients pick a recovery from it. Its
@@ -1232,6 +1261,7 @@ interface ActiveCodexTurnContext {
1261
latestProviderFailure?: {
1262
readonly nativeMessage: string;
1263
readonly nativeCode: string | null;
1264
+ readonly errorInfo?: CodexErrorInfo | null;
1265
readonly failure: OrchestrationV2ProviderFailure;
1266
};
1267
readonly nativeStartReady?: Deferred.Deferred<void>;
@@ -1263,6 +1293,8 @@ interface ActiveCodexProviderRetry {
1293
readonly context?: ActiveCodexTurnContext;
1294
readonly nativeMessage: string;
1295
readonly nativeCode: string | null;
1296
+ readonly nativeDetails?: string;
1297
+ readonly errorInfo?: CodexErrorInfo | null;
1298
readonly retry: OrchestrationV2ProviderRetry;
1299
readonly failure: OrchestrationV2ProviderFailure;
1300
readonly startedAt: DateTime.Utc;
@@ -5116,13 +5148,17 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
5148
context.latestProviderFailure = {
5149
nativeMessage: payload.error.message,
5150
nativeCode: notificationCode,
5151
+ ...(payload.error.codexErrorInfo === undefined
5152
+ ? {}
5153
+ : { errorInfo: payload.error.codexErrorInfo }),
5154
failure: withCodexManagedFailure(
5155
makeProviderFailure({
5156
message: payload.error.additionalDetails?.trim() || payload.error.message,
5157
code: notificationCode,
5123
- class: codexUsageLimitError(notificationCode, payload.error.codexErrorInfo)
5124
- ? "usage_limit"
5125
- : "provider_error",
5158
+ class: codexTerminalFailureClass(
5159
+ payload.error.codexErrorInfo,
5160
+ notificationCode,
5161
+ ),
5162
}),
5163
payload.error,
5164
),
@@ -5163,6 +5199,12 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
5199
...(previous?.context === undefined ? {} : { context: previous.context }),
5200
nativeMessage: payload.error.message,
5201
nativeCode: code,
5202
+ nativeDetails: additionalDetails
5203
+ ? (payload.error.additionalDetails ?? additionalDetails)
5204
+ : payload.error.message,
5205
+ ...(payload.error.codexErrorInfo === undefined
5206
+ ? {}
5207
+ : { errorInfo: payload.error.codexErrorInfo }),
5208
retry,
5209
failure,
5210
startedAt: previous?.startedAt ?? updatedAt,
@@ -6267,19 +6309,20 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
6309
input.failureErrorInfo === undefined
6310
? undefined
6311
: codexErrorInfoCode(input.failureErrorInfo);
6270
- const failureClass = codexUsageLimitError(failureCode ?? null, input.failureErrorInfo)
6271
- ? "usage_limit"
6272
- : "provider_error";
6273
- // The notification carries the richer message, so it wins when the
6274
- // completion repeats it. An explicit exhaustion status on the
6275
- // completion still decides the class; a missing one is not evidence.
6276
- const exhaustionStatus = codexExhaustionHttpStatus(input.failureErrorInfo);
6277
- const failure =
6312
+ const failureClass = codexTerminalFailureClass(
6313
+ input.failureErrorInfo,
6314
+ failureCode ?? null,
6315
+ );
6316
+ // Retry exhaustion without a status cannot replace the notification's evidence.
6317
+ const completionHasClass =
6318
+ failureCode != null &&
6319
+ !codexTerminalErrorNeedsEvidence(input.failureErrorInfo, failureCode);
6320
+ let failure =
6321
previousFailure !== undefined &&
6322
(input.failureMessage === undefined ||
6323
input.failureMessage === previousFailure.nativeMessage) &&
6324
(failureCode === undefined || failureCode === previousFailure.nativeCode) &&
6282
- (exhaustionStatus === null || previousFailure.failure.class === failureClass)
6325
+ (!completionHasClass || previousFailure.failure.class === failureClass)
6326
? previousFailure.failure
6327
: withCodexManagedFailure(
6328
makeProviderFailure({
@@ -6289,6 +6332,28 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
6332
}),
6333
input.failureMessage,
6334
);
6335
+ const retry = input.providerRetry;
6336
+ const notification = input.context.latestProviderFailure;
6337
+ // Codex 0.164 reports an exhausted stream error as `other` with the same details.
6338
+ if (
6339
+ codexTerminalErrorNeedsEvidence(input.failureErrorInfo, failure.code) &&
6340
+ failure.class === "provider_error" &&
6341
+ (notification === undefined ||
6342
+ notification.failure.class === "transport_error" ||
6343
+ codexTerminalErrorNeedsEvidence(
6344
+ notification.errorInfo,
6345
+ notification.nativeCode,
6346
+ )) &&
6347
+ ((retry !== undefined &&
6348
+ input.failureMessage !== undefined &&
6349
+ input.failureMessage === retry.nativeDetails &&
6350
+ codexTerminalFailureClass(retry.errorInfo, retry.nativeCode) ===
6351
+ "transport_error") ||
6352
+ (notification?.failure.class === "transport_error" &&
6353
+ input.failureMessage === notification.nativeMessage))
6354
+ ) {
6355
+ failure = { ...failure, class: "transport_error" };
6356
+ }
6357
return {
6358
type: "turn.terminal",
6359
driver: CODEX_PROVIDER,