The best way to control Claude Code, Codex and more from any computer or phone
fix: Intel Mac installs and broken Codex versions fail with clear next steps (#27281)
maria committed
Oct 30, 2026 at 20:28 UTC
797bcb08e689dba47441e10c77e4149741c8e826
7 files changed
+110
-10
apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.test.ts
+53
@@ -22,6 +22,7 @@ import {
22
type ProviderApprovalDecision,
23
ProviderInstanceId,
24
ProviderSessionId,
25
+ ProviderSetupError,
26
ProviderThreadId,
27
ProviderTurnId,
28
RunAttemptId,
@@ -66,6 +67,8 @@ import * as Orchestrator from "../Orchestrator.ts";
67
import * as ProviderReplayHarness from "../testkit/ProviderReplayHarness.ts";
68
import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
69
import type * as ProviderContinuationRequests from "@t3tools/provider-core/server/ProviderContinuationRequests";
70
+import * as ModelManifest from "../../provider/ModelManifest.ts";
71
+import { resolveProviderCompatibility } from "../../provider/providerCompatibility.ts";
72
import * as CodexAdapterV2 from "./CodexAdapterV2.ts";
73
import { withCodexReplayChildMetadata } from "./CodexAdapterV2.testkit.ts";
74
import * as CodexAdapterV2Testkit from "./CodexAdapterV2.testkit.ts";
@@ -876,6 +879,7 @@ describe("CodexAdapterV2 session initialize", () => {
879
const openReplaySession = (
880
transcript: CodexReplay.CodexAppServerReplayTranscript,
881
beforeEmitInbound?: CodexReplay.CodexAppServerReplayDriver["beforeEmitInbound"],
882
+ compatibility?: CodexAdapterV2.CodexAdapterV2Options["compatibility"],
883
) =>
884
Effect.gen(function* () {
885
const driver = yield* CodexReplay.makeReplayDriver(
@@ -887,6 +891,7 @@ describe("CodexAdapterV2 session initialize", () => {
891
instanceId: CodexAdapterV2.CODEX_DEFAULT_INSTANCE_ID,
892
settings: DEFAULT_CODEX_SETTINGS,
893
environment: {},
894
+ ...(compatibility === undefined ? {} : { compatibility }),
895
clientFactory: {
896
open: (openInput) =>
897
Layer.build(CodexReplay.layerReplayWithDriver(driver)).pipe(
@@ -1018,6 +1023,54 @@ describe("CodexAdapterV2 session initialize", () => {
1023
),
1024
);
1025
1026
+ it.effect("refuses to open a session on a Codex version marked broken", () =>
1027
+ Effect.gen(function* () {
1028
+ const [initialize] = replayPreamble("broken-version");
1029
+ const failure = yield* openReplaySession(
1030
+ makeCodexReplayTranscript({
1031
+ scenario: "broken-version",
1032
+ entries: [
1033
+ initialize!,
1034
+ {
1035
+ type: "emit_inbound",
1036
+ label: "initialize",
1037
+ frame: {
1038
+ id: 1,
1039
+ result: {
1040
+ userAgent: "T3 Code/0.144.3 (Mac OS 15.5.0; x86_64) unknown (T3 Code; 0.1.5)",
1041
+ codexHome: "/tmp/codex-home",
1042
+ platformFamily: "unix",
1043
+ platformOs: "macos",
1044
+ },
1045
+ },
1046
+ },
1047
+ ],
1048
+ }),
1049
+ undefined,
1050
+ (version) =>
1051
+ Effect.succeed(
1052
+ resolveProviderCompatibility(
1053
+ ModelManifest.BUNDLED_MODEL_MANIFEST.compatibility,
1054
+ CodexAdapterV2.CODEX_DRIVER_KIND,
1055
+ version,
1056
+ ),
1057
+ ),
1058
+ ).pipe(Effect.flip);
1059
+
1060
+ assert.instanceOf(failure, ProviderAdapter.ProviderAdapterOpenSessionError);
1061
+ assert.instanceOf(failure.cause, ProviderSetupError);
1062
+ assert.equal(
1063
+ failure.cause.message,
1064
+ "Codex 0.144.3 does not work with this T3 Code release. Update Codex to >=0.159.0, then retry.",
1065
+ );
1066
+ }).pipe(
1067
+ Effect.scoped,
1068
+ Effect.provide(
1069
+ Layer.mergeAll(IdAllocator.layer, McpProviderSessions.layer, NodeServices.layer),
1070
+ ),
1071
+ ),
1072
+ );
1073
+
1074
it.effect("completes the handshake after a caller is interrupted mid-initialize", () =>
1075
Effect.gen(function* () {
1076
const initializeAwaitingResponse = yield* Deferred.make<void>();
apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts
+25
-4
@@ -36,7 +36,8 @@ import {
36
OrchestrationV2ProviderGoal,
37
parseGoalCommand,
38
ProviderDriverKind,
39
- type ProviderSetupError,
39
+ ProviderSetupError,
40
+ type ServerProviderCompatibilityAdvisory,
41
} from "@t3tools/contracts";
42
import { SKILL_MENTION_PATTERN } from "@t3tools/shared/composerInlineTokens";
43
import { AgentScope } from "@t3tools/shared/AgentScope";
@@ -1549,7 +1550,7 @@ export type CodexAdapterV2DriverEnv =
1550
1551
export const createCodexAdapterV2 = Effect.fn("CodexAdapterV2.createCodexAdapterV2")(function* (
1552
{ instanceId, environment, enabled, config }: ProviderAdapterDriverCreateInput<CodexSettings>,
1552
- hooks: Pick<CodexAdapterV2Options, "onUsageLimits" | "resolveRuntime"> = {},
1553
+ hooks: Pick<CodexAdapterV2Options, "onUsageLimits" | "resolveRuntime" | "compatibility"> = {},
1554
) {
1555
const clientFactory = yield* CodexAppServerClientFactory;
1556
const continuationRequests = yield* ProviderContinuationRequests.ProviderContinuationRequests;
@@ -1600,6 +1601,9 @@ export interface CodexAdapterV2Options {
1601
readonly clientFactory: CodexAppServerClientFactoryShape;
1602
readonly onUsageLimits?: ManagedServerProvider["applyUsageLimits"];
1603
readonly resolveRuntime?: Effect.Effect<CodexEffectiveRuntime, ProviderSetupError, Scope.Scope>;
1604
+ readonly compatibility?: (
1605
+ version: string,
1606
+ ) => Effect.Effect<ServerProviderCompatibilityAdvisory | undefined>;
1607
readonly crypto: Crypto.Crypto;
1608
readonly fileSystem: FileSystem.FileSystem;
1609
readonly idAllocator: IdAllocator.IdAllocatorV2["Service"];
@@ -1706,24 +1710,41 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
1710
return;
1711
}
1712
1709
- yield* client
1713
+ const userAgent = yield* client
1714
.request("initialize", {
1715
clientInfo: buildCodexInitializeParams().clientInfo,
1716
capabilities: CODEX_CLIENT_CAPABILITIES,
1717
})
1718
.pipe(
1719
+ Effect.map((response) => response.userAgent),
1720
Effect.catchTags({
1721
// Interruption can leave Codex initialized before the local flag is set.
1722
CodexAppServerRequestError: (error) =>
1723
error.code === -32600 && error.errorMessage === "Already initialized"
1719
- ? Effect.void
1724
+ ? Effect.succeed(null)
1725
: Effect.fail(error),
1726
}),
1727
);
1728
+ const version = userAgent && /\/(\S+)/u.exec(userAgent)?.[1];
1729
+ const advisory =
1730
+ version && adapterOptions.compatibility
1731
+ ? yield* adapterOptions.compatibility(version)
1732
+ : undefined;
1733
+ if (advisory?.status === "broken") {
1734
+ const target =
1735
+ advisory.recommendedVersion ?? advisory.recommendedRange ?? "a newer version";
1736
+ return yield* new ProviderSetupError({
1737
+ instanceId: adapterOptions.instanceId,
1738
+ operation: "runtime",
1739
+ detail: `Codex ${version} does not work with this T3 Code release. Update Codex to ${target}, then retry.`,
1740
+ });
1741
+ }
1742
yield* client.notify("initialized", undefined);
1743
yield* Ref.set(initialized, true);
1744
}),
1745
);
1746
+ // A failed open is discarded, so the next turn spawns the updated binary.
1747
+ if (adapterOptions.compatibility !== undefined) yield* ensureInitialized;
1748
const now = yield* DateTime.now;
1749
const session = providerSession({
1750
providerSessionId: input.providerSessionId,
apps/server/src/provider/CodexInstallation.ts
+9
-1
@@ -1,5 +1,9 @@
1
// @effect-diagnostics nodeBuiltinImport:off - Effect has no incremental digest.
2
-import { ProviderDriverKind, type ProviderInstallState } from "@t3tools/contracts";
2
+import {
3
+ ProviderDriverKind,
4
+ type ProviderInstallState,
5
+ type ServerProviderCompatibilityAdvisory,
6
+} from "@t3tools/contracts";
7
import { cliArchiveTarCommand } from "@t3tools/shared/cliRelease";
8
import * as HostProcess from "@t3tools/shared/HostProcess";
9
import { resolveCommandPath, resolveSpawnCommand } from "@t3tools/shared/shell";
@@ -125,6 +129,9 @@ interface CodexInstallationService {
129
readonly managedDirectory: string;
130
readonly resolve: () => Effect.Effect<CodexExecutable, CodexInstallationError>;
131
readonly acquire: () => Effect.Effect<CodexExecutable, CodexInstallationError, Scope.Scope>;
132
+ readonly compatibility: (
133
+ version: string,
134
+ ) => Effect.Effect<ServerProviderCompatibilityAdvisory | undefined>;
135
readonly start: Effect.Effect<ProviderInstallState, CodexInstallationError>;
136
readonly cancel: (
137
operationId: string,
@@ -796,6 +803,7 @@ export const makeCodexInstallation = Effect.fn("makeCodexInstallation")(function
803
managedDirectory,
804
resolve,
805
acquire,
806
+ compatibility,
807
start,
808
cancel,
809
state: SubscriptionRef.get(state),
apps/server/src/provider/Drivers/CodexDriver.ts
+5
-1
@@ -147,6 +147,7 @@ export const CodexDriver: ProviderDriver<
147
const pathService = yield* Path.Path;
148
const httpClient = yield* HttpClient.HttpClient;
149
const latestVersions = yield* ProviderLatestVersions.ProviderLatestVersions;
150
+ const installation = yield* CodexInstallation.CodexInstallation;
151
const modelCatalog = yield* ModelCatalog.ModelCatalog;
152
const currentCatalog = modelCatalog.current(DRIVER_KIND);
153
const processEnv = yield* mergeProviderInstanceEnvironment(environment);
@@ -199,7 +200,10 @@ export const CodexDriver: ProviderDriver<
200
enabled,
201
config,
202
},
202
- { onUsageLimits: (update) => snapshot.applyUsageLimits(update) },
203
+ {
204
+ onUsageLimits: (update) => snapshot.applyUsageLimits(update),
205
+ compatibility: installation.compatibility,
206
+ },
207
).pipe(
208
Effect.mapError(
209
(cause) =>
packages/provider-core/src/server/failure.test.ts
+12
-2
@@ -2,6 +2,8 @@ import { assert, it } from "@effect/vitest";
2
import {
3
NodeId,
4
ProviderDriverKind,
5
+ ProviderInstanceId,
6
+ ProviderSetupError,
7
ProviderThreadId,
8
ProviderTurnId,
9
RunId,
@@ -83,8 +85,16 @@ it("does not expose arbitrary cause messages and preserves explicit messages", (
85
}
86
});
87
86
-it("preserves actionable handoff errors wrapped by turn startup", () => {
87
- for (const error of [new ContextHandoffBudgetError(), new ContextHandoffBackgroundWorkError()]) {
88
+it("preserves actionable T3 errors wrapped by turn startup", () => {
89
+ for (const error of [
90
+ new ContextHandoffBudgetError(),
91
+ new ContextHandoffBackgroundWorkError(),
92
+ new ProviderSetupError({
93
+ instanceId: ProviderInstanceId.make("codex"),
94
+ operation: "runtime",
95
+ detail: "Codex 0.144.3 does not work with this T3 Code release.",
96
+ }),
97
+ ]) {
98
const cause = new ProviderAdapter.ProviderAdapterTurnStartError({
99
driver: ProviderDriverKind.make("codex"),
100
threadId: ThreadId.make("thread:handoff-error"),
packages/provider-core/src/server/failure.ts
+1
@@ -108,6 +108,7 @@ function curatedCauseMessages(cause: unknown): {
108
case "ClaudeSettingsLaunchArgError":
109
case "ClaudeMcpRegistrationTimeoutError":
110
case "CursorModelUnavailableError":
111
+ case "ProviderSetupError":
112
return { known: stringField(cause, "message"), category: categoryMessage() };
113
case "ContextHandoffDeliveryUncertainError":
114
return {
scripts/install.sh
+5
-2
@@ -133,6 +133,9 @@ case "$(uname -m)" in
133
x86_64 | amd64) arch="x64" ;;
134
*) fail "unsupported architecture $(uname -m)" ;;
135
esac
136
+if [ "${platform}-${arch}" = darwin-x64 ]; then
137
+ fail "there is no t3 CLI for Intel Macs. Install the desktop app from https://t3.codes/download, or run a server from source: https://github.com/${repo}/blob/main/docs/user/install.md#intel-macs"
138
+fi
139
command -v tar >/dev/null 2>&1 || fail "tar is required"
140
if command -v sha256sum >/dev/null 2>&1; then
141
checksum() { sha256sum "$1" | cut -d' ' -f1; }
@@ -206,11 +209,11 @@ else
209
elif [ "$fetch_status" -ne 0 ]; then
210
fail "could not download the release checksums"
211
fi
212
+ expected="$(grep " \*\{0,1\}${archive}\$" "${staging}/SHA256SUMS" | cut -d' ' -f1)"
213
+ [ -n "$expected" ] || fail "t3 ${version} has no release archive for ${platform}-${arch}"
214
download "${base_url}/v${version}/${archive}" "${staging}/${archive}"
215
216
step "Verifying the download..."
212
- expected="$(grep " \*\{0,1\}${archive}\$" "${staging}/SHA256SUMS" | cut -d' ' -f1)"
213
- [ -n "$expected" ] || fail "${archive} is not listed in SHA256SUMS"
217
actual="$(checksum "${staging}/${archive}")"
218
[ "$actual" = "$expected" ] || fail "checksum mismatch for ${archive}"
219