The best way to control Claude Code, Codex and more from any computer or phone
fix(codex): recover CLI version after failed app-server probe (#21443)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: GPT-6.1 Sol <noreply@openai.com> Co-authored-by: maria-rcks <maria@kuuro.net>
Victor Vogel committed
Oct 30, 2026 at 15:26 UTC
65117965b41d9e8815466090076930ae9a5415d8
2 files changed
+210
-7
apps/server/src/provider/CodexProvider.ts
+60
-7
@@ -39,7 +39,9 @@ import { codexAppServerArgs, resolveCodexLaunchArgs } from "./codexLaunchArgs.ts
39
import {
40
buildServerProvider,
41
COMPACT_SLASH_COMMAND,
42
+ DEFAULT_TIMEOUT_MS,
43
providerModelsFromSettings,
44
+ spawnAndCollect,
45
type ServerProviderDraft,
46
} from "@t3tools/provider-core/server/snapshotProbe";
47
import { expandHomePath } from "@t3tools/provider-core/server/pathExpansion";
@@ -75,6 +77,9 @@ const CODEX_CLIENT_NAME = "T3 Code";
77
// Handshake plus account/models/skills requests can exceed the shared 10s probe budget.
78
const CODEX_AUTH_PROBE_TIMEOUT_MS = 20_000;
79
const CODEX_DISCOVERY_MARGIN_MS = 250;
80
+// `codex-cli 0.159.0`, `codex-cli 0.160.0-alpha.1` or the npm CLI's bare `0.1.4161006`.
81
+// Keep a prerelease suffix so compatibility stays unknown for it, as it does for `initialize`.
82
+const CODEX_CLI_VERSION_PATTERN = /(?:^|\s)v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)(?=\s|$)/u;
83
84
const CODEX_PRESENTATION = {
85
displayName: "Codex",
@@ -459,22 +464,29 @@ export function buildCodexInitializeParams(): CodexSchema.V1InitializeParams {
464
};
465
}
466
462
-export const withCodexAppServerClient = Effect.fn("withCodexAppServerClient")(function* (input: {
463
- readonly binaryPath: string;
467
+const codexProcessEnvironment = Effect.fn("codexProcessEnvironment")(function* (input: {
468
readonly homePath?: string | undefined;
465
- readonly launchArgs?: string | undefined;
466
- readonly cwd: string;
469
readonly environment?: NodeJS.ProcessEnv | undefined;
470
}) {
471
// Expand CODEX_HOME explicitly: spawn passes a literal ~ that Codex rejects.
472
const resolvedHomePath = input.homePath
473
? expandHomePath(input.homePath, yield* HostProcess.HomeDirectory)
474
: undefined;
473
- const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
474
- const environment = {
475
+ return {
476
...codexAppServerEnvironment(input.environment),
477
...(resolvedHomePath ? { CODEX_HOME: resolvedHomePath } : {}),
478
};
479
+});
480
+
481
+export const withCodexAppServerClient = Effect.fn("withCodexAppServerClient")(function* (input: {
482
+ readonly binaryPath: string;
483
+ readonly homePath?: string | undefined;
484
+ readonly launchArgs?: string | undefined;
485
+ readonly cwd: string;
486
+ readonly environment?: NodeJS.ProcessEnv | undefined;
487
+}) {
488
+ const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
489
+ const environment = yield* codexProcessEnvironment(input);
490
const spawnCommand = yield* resolveSpawnCommand(
491
input.binaryPath,
492
codexAppServerArgs(input.launchArgs),
@@ -594,6 +606,39 @@ const probeCodexAppServerProvider = Effect.fn("probeCodexAppServerProvider")(fun
606
} satisfies CodexAppServerProviderSnapshot;
607
});
608
609
+// Old CLIs can exit before initialize reports the version needed for compatibility advice.
610
+const probeCodexCliVersion = Effect.fn("probeCodexCliVersion")(
611
+ function* (input: {
612
+ readonly binaryPath: string;
613
+ readonly homePath?: string | undefined;
614
+ readonly cwd: string;
615
+ readonly environment?: NodeJS.ProcessEnv | undefined;
616
+ }) {
617
+ const environment = yield* codexProcessEnvironment(input);
618
+ const spawnCommand = yield* resolveSpawnCommand(input.binaryPath, ["--version"], {
619
+ env: environment,
620
+ extendEnv: true,
621
+ });
622
+ const result = yield* spawnAndCollect(
623
+ input.binaryPath,
624
+ ChildProcess.make(spawnCommand.command, spawnCommand.args, {
625
+ cwd: input.cwd,
626
+ env: environment,
627
+ extendEnv: true,
628
+ forceKillAfter: CODEX_APP_SERVER_PROBE_FORCE_KILL_AFTER,
629
+ shell: spawnCommand.shell,
630
+ }),
631
+ );
632
+ if (result.code !== 0) return null;
633
+ return CODEX_CLI_VERSION_PATTERN.exec(result.stdout)?.[1] ?? null;
634
+ },
635
+ Effect.timeoutOption(Duration.millis(DEFAULT_TIMEOUT_MS)),
636
+ Effect.map(Option.getOrNull),
637
+ Effect.catch((cause) =>
638
+ Effect.logDebug("Codex --version fallback failed.", { cause }).pipe(Effect.as(null)),
639
+ ),
640
+);
641
+
642
export const probeCodexSkillsForCwd = Effect.fn("probeCodexSkillsForCwd")(function* (input: {
643
readonly binaryPath: string;
644
readonly homePath?: string;
@@ -739,6 +784,14 @@ export const checkCodexProviderStatus = Effect.fn("checkCodexProviderStatus")(fu
784
if (Result.isFailure(probeResult)) {
785
const error = probeResult.failure;
786
const installed = !isCodexAppServerSpawnError(error);
787
+ const version = installed
788
+ ? yield* probeCodexCliVersion({
789
+ binaryPath: codexSettings.binaryPath,
790
+ homePath: codexSettings.homePath,
791
+ cwd: process.cwd(),
792
+ environment: resolvedEnvironment,
793
+ })
794
+ : null;
795
return buildServerProvider({
796
presentation: CODEX_PRESENTATION,
797
enabled: codexSettings.enabled,
@@ -747,7 +800,7 @@ export const checkCodexProviderStatus = Effect.fn("checkCodexProviderStatus")(fu
800
skills: [],
801
probe: {
802
installed,
750
- version: null,
803
+ version,
804
status: "error",
805
auth: { status: "unknown" },
806
message: installed
apps/server/src/provider/ProviderRegistry.test.ts
+150
@@ -1,3 +1,7 @@
1
+import * as HostProcess from "@t3tools/shared/HostProcess";
2
+import * as CodexErrors from "effect-codex-app-server/errors";
3
+import * as Path from "effect/Path";
4
+import * as FileSystem from "effect/FileSystem";
5
import { vi } from "vite-plus/test";
6
import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
7
import * as CodexInstallation from "./CodexInstallation.ts";
@@ -88,6 +92,7 @@ const disabledDefaultSlots = (
92
);
93
94
const defaultClaudeSettings: ClaudeSettings = Schema.decodeSync(ClaudeSettings)({});
95
+const decodeCodexSettings = Schema.decodeSync(CodexSettings);
96
const defaultCodexSettings: CodexSettings = Schema.decodeSync(CodexSettings)({});
97
98
process.env.T3CODE_CURSOR_ENABLED = "1";
@@ -216,6 +221,20 @@ function layerMockSpawner(
221
);
222
}
223
224
+// A Codex CLI on disk whose `app-server` and `--version` behave as `script` says.
225
+const writeFakeCodexCli = Effect.fn("writeFakeCodexCli")(function* (script: string) {
226
+ const fs = yield* FileSystem.FileSystem;
227
+ const path = yield* Path.Path;
228
+ const directory = yield* fs.makeTempDirectoryScoped({ prefix: "t3-fake-codex-" });
229
+ const binaryPath = path.join(directory, "codex");
230
+ yield* fs.writeFileString(binaryPath, `#!/bin/sh\n${script}\n`);
231
+ yield* fs.chmod(binaryPath, 0o755);
232
+ return { directory, binaryPath };
233
+});
234
+
235
+// The npm `@openai/codex` 0.1 CLI treats `app-server` as a prompt and exits 1.
236
+const OBSOLETE_CODEX_APP_SERVER = `echo "Missing OpenAI API key." >&2; exit 1`;
237
+
238
const codexModelCapabilities = createModelCapabilities({
239
optionDescriptors: [
240
selectDescriptor("reasoningEffort", "Reasoning", [
@@ -427,6 +446,137 @@ it.layer(
446
assert.strictEqual(status.auth.status, "unknown");
447
}),
448
);
449
+
450
+ it.effect("reads the version of a Codex CLI too old to run app-server (#20351)", () =>
451
+ Effect.gen(function* () {
452
+ if ((yield* HostProcess.Platform) === "win32") return;
453
+ const codexHome = yield* FileSystem.FileSystem.pipe(
454
+ Effect.flatMap((fs) => fs.makeTempDirectoryScoped({ prefix: "t3-codex-home-" })),
455
+ );
456
+ const { binaryPath } = yield* writeFakeCodexCli(
457
+ [
458
+ `if [ "$1" = "--version" ]; then`,
459
+ // The fallback runs with the provider's environment and CODEX_HOME.
460
+ ` [ "$CODEX_HOME" = "${codexHome}" ] && [ "$FAKE_CODEX_ENV" = "kept" ] || exit 2`,
461
+ ` echo 0.1.4161006; exit 0`,
462
+ `fi`,
463
+ OBSOLETE_CODEX_APP_SERVER,
464
+ ].join("\n"),
465
+ );
466
+ const settings = decodeCodexSettings({ binaryPath, homePath: codexHome });
467
+
468
+ const status = yield* checkCodexProviderStatus(settings, undefined, {
469
+ ...process.env,
470
+ FAKE_CODEX_ENV: "kept",
471
+ });
472
+
473
+ assert.strictEqual(status.status, "error");
474
+ assert.strictEqual(status.installed, true);
475
+ assert.strictEqual(status.version, "0.1.4161006");
476
+ assert.match(status.message ?? "", /^Codex app-server provider probe failed: /);
477
+ const classified = withBundledCompatibility({
478
+ ...status,
479
+ instanceId: ProviderInstanceId.make("codex"),
480
+ driver: ProviderDriverKind.make("codex"),
481
+ });
482
+ assert.strictEqual(classified.compatibilityAdvisory?.status, "broken");
483
+ }),
484
+ );
485
+
486
+ it.effect("keeps a prerelease --version unclassified instead of reading it as stable", () =>
487
+ Effect.gen(function* () {
488
+ if ((yield* HostProcess.Platform) === "win32") return;
489
+ const { binaryPath } = yield* writeFakeCodexCli(
490
+ [
491
+ `[ "$1" = "--version" ] && { echo "codex-cli 0.159.0-alpha.1"; exit 0; }`,
492
+ OBSOLETE_CODEX_APP_SERVER,
493
+ ].join("\n"),
494
+ );
495
+
496
+ const status = yield* checkCodexProviderStatus(decodeCodexSettings({ binaryPath }));
497
+
498
+ assert.strictEqual(status.version, "0.159.0-alpha.1");
499
+ const classified = withBundledCompatibility({
500
+ ...status,
501
+ instanceId: ProviderInstanceId.make("codex"),
502
+ driver: ProviderDriverKind.make("codex"),
503
+ });
504
+ assert.strictEqual(classified.compatibilityAdvisory?.status, "unknown");
505
+ }),
506
+ );
507
+
508
+ it.effect("keeps the probe failure without a version when --version also fails", () =>
509
+ Effect.gen(function* () {
510
+ if ((yield* HostProcess.Platform) === "win32") return;
511
+ const { binaryPath } = yield* writeFakeCodexCli(
512
+ [
513
+ `[ "$1" = "--version" ] && { echo "codex 0.1.0" >&2; exit 3; }`,
514
+ OBSOLETE_CODEX_APP_SERVER,
515
+ ].join("\n"),
516
+ );
517
+
518
+ const status = yield* checkCodexProviderStatus(decodeCodexSettings({ binaryPath }));
519
+
520
+ assert.strictEqual(status.status, "error");
521
+ assert.strictEqual(status.installed, true);
522
+ assert.strictEqual(status.version, null);
523
+ assert.match(status.message ?? "", /^Codex app-server provider probe failed: /);
524
+ }),
525
+ );
526
+
527
+ it.effect("bounds a hanging Codex --version fallback and releases its process scope", () =>
528
+ Effect.gen(function* () {
529
+ const started = yield* Deferred.make<void>();
530
+ const released = yield* Deferred.make<void>();
531
+ const spawner = ChildProcessSpawner.make(() =>
532
+ Effect.gen(function* () {
533
+ yield* Effect.addFinalizer(() => Deferred.succeed(released, undefined));
534
+ return ChildProcessSpawner.makeHandle({
535
+ ...mockHandle({ stdout: "", stderr: "", code: 0 }),
536
+ exitCode: Deferred.succeed(started, undefined).pipe(Effect.andThen(Effect.never)),
537
+ });
538
+ }),
539
+ );
540
+ const fiber = yield* checkCodexProviderStatus(defaultCodexSettings, () =>
541
+ Effect.fail(new CodexErrors.CodexAppServerProcessExitedError({ code: 1 })),
542
+ ).pipe(
543
+ Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
544
+ Effect.forkChild,
545
+ );
546
+ yield* Deferred.await(started);
547
+ yield* TestClock.adjust("4 seconds");
548
+ const status = yield* Fiber.join(fiber);
549
+ assert.strictEqual(status.version, null);
550
+ assert.strictEqual(status.status, "error");
551
+ assert.strictEqual(status.installed, true);
552
+ assert.match(status.message ?? "", /^Codex app-server provider probe failed: /);
553
+ assert.isTrue(yield* Deferred.isDone(released));
554
+ }),
555
+ );
556
+
557
+ it.effect("does not run --version when the Codex executable cannot start", () =>
558
+ Effect.gen(function* () {
559
+ if ((yield* HostProcess.Platform) === "win32") return;
560
+ const fs = yield* FileSystem.FileSystem;
561
+ const path = yield* Path.Path;
562
+ const { directory, binaryPath } = yield* writeFakeCodexCli(
563
+ `touch "$(dirname "$0")/ran"; echo 0.1.4161006`,
564
+ );
565
+
566
+ const status = yield* checkCodexProviderStatus(decodeCodexSettings({ binaryPath }), () =>
567
+ Effect.fail(
568
+ new CodexErrors.CodexAppServerSpawnError({
569
+ command: `${binaryPath} app-server`,
570
+ cause: new Error("spawn ENOENT"),
571
+ }),
572
+ ),
573
+ );
574
+
575
+ assert.strictEqual(status.installed, false);
576
+ assert.strictEqual(status.version, null);
577
+ assert.isFalse(yield* fs.exists(path.join(directory, "ran")));
578
+ }),
579
+ );
580
});
581
582
describe("ProviderRegistry.layer", () => {