From 4fcef92a504c0d7f455161c75bb38c5ad56a5987 Mon Sep 17 00:00:00 2001
From: Yun Long <longdeqidao@gmail.com>
Date: Sun, 12 Jul 2026 19:30:54 +0800
Subject: [PATCH] fix(windows): Make it compatible with codex.cmd

---
 docs/cli.md                                   |  3 +-
 docs/cli.zh.md                                |  2 +-
 docs/config.md                                |  3 +-
 docs/config.zh.md                             |  2 +-
 internal/api/handler.go                       |  2 +-
 internal/codexcli/command.go                  | 30 ++++++++++
 internal/codexcli/command_nonwindows.go       | 12 ++++
 internal/codexcli/command_test.go             | 41 +++++++++++++
 internal/codexcli/command_windows.go          | 28 +++++++++
 internal/codexcli/command_windows_test.go     | 39 ++++++++++++
 internal/codexcli/installer_test.go           | 48 ++++++++++++++-
 internal/codexcli/locator.go                  | 30 ++++++----
 internal/codexcli/locator_test.go             | 59 +++++++++++++++++--
 internal/runtime/codex/appserver_manager.go   | 13 ++--
 .../runtime/codex/appserver_manager_test.go   |  4 +-
 internal/runtimecatalog/service_test.go       | 25 ++++++++
 16 files changed, 308 insertions(+), 33 deletions(-)
 create mode 100644 internal/codexcli/command.go
 create mode 100644 internal/codexcli/command_nonwindows.go
 create mode 100644 internal/codexcli/command_test.go
 create mode 100644 internal/codexcli/command_windows.go
 create mode 100644 internal/codexcli/command_windows_test.go

diff --git a/docs/cli.md b/docs/cli.md
index e80d5100..9b303498 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -377,8 +377,7 @@ Notes:
 
 - `--runtime codex` requires a local `codex` CLI that supports `app-server --listen stdio://`.
 - Binary lookup uses `PATH` by default and can be overridden with `CSGCLAW_CODEX_PATH`.
-  On Windows, use a native `codex.exe` rather than the PowerShell `codex.ps1` shim.
-  Legacy `codex.cmd` and `codex.bat` values fall back to a sibling or CSGClaw-managed native executable.
+  On Windows, native `codex.exe` and npm's `codex.cmd`/`codex.bat` shims are supported; the PowerShell `codex.ps1` shim is not.
 
 ### `csgclaw user`
 
diff --git a/docs/cli.zh.md b/docs/cli.zh.md
index 584ee7d7..30fdc9e2 100644
--- a/docs/cli.zh.md
+++ b/docs/cli.zh.md
@@ -376,7 +376,7 @@ csgclaw agent delete --all --force
 说明：
 
 - `--runtime codex` 依赖本地已安装且支持 `app-server --listen stdio://` 的 `codex` CLI。
-- 默认从 `PATH` 查找二进制，也可以用 `CSGCLAW_CODEX_PATH` 显式覆盖。Windows 下请使用 `codex.cmd` 或 `codex.exe`，不要使用 PowerShell 的 `codex.ps1` shim。
+- 默认从 `PATH` 查找二进制，也可以用 `CSGCLAW_CODEX_PATH` 显式覆盖。Windows 支持 `codex.cmd`、`codex.bat` 和 `codex.exe`，但不支持 PowerShell 的 `codex.ps1` shim。
 
 ### `csgclaw user`
 
diff --git a/docs/config.md b/docs/config.md
index ad815f06..f4d365f3 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -128,8 +128,7 @@ For complete Codex worker profiles, CSGClaw writes `~/.csgclaw/agents/<agent-nam
 When a worker uses the Codex runtime, CSGClaw launches the local `codex` CLI with `codex app-server --listen stdio://`. You can override the binary lookup with:
 
 - `CSGCLAW_CODEX_PATH` to point at a preinstalled `codex` binary.
-  On Windows, point it at a native `codex.exe`.
-  A legacy npm `codex.cmd` or `codex.bat` value makes CSGClaw look for a sibling native executable, then fall back to the CSGClaw-managed `codex.exe`; `codex.ps1` is not supported.
+  On Windows, native `codex.exe` and npm's `codex.cmd`/`codex.bat` shims are supported; `codex.ps1` is not. CSGClaw launches command shims through `cmd.exe` and prefers a sibling native executable when one exists.
 - `CSGCLAW_CODEX_ACP_PATH` as a temporary compatibility fallback to the same `codex` binary path during migration
 
 ## OpenClaw Runtime
diff --git a/docs/config.zh.md b/docs/config.zh.md
index 76237969..1ebd4c5b 100644
--- a/docs/config.zh.md
+++ b/docs/config.zh.md
@@ -127,7 +127,7 @@ bootstrap manager 当前固定使用 `picoclaw_sandbox`；`openclaw_sandbox` 支
 
 当 worker 使用 Codex runtime 时，CSGClaw 会通过 `codex app-server --listen stdio://` 启动本地 `codex` CLI。你可以通过下面的环境变量覆盖二进制查找行为：
 
-- `CSGCLAW_CODEX_PATH`：指定本地 `codex` 可执行文件路径。Windows 下优先指向 npm 的 `codex.cmd` shim 或原生 `codex.exe`，不要指向 `codex.ps1`。
+- `CSGCLAW_CODEX_PATH`：指定本地 `codex` 可执行文件路径。Windows 支持 npm 的 `codex.cmd`/`codex.bat` shim 和原生 `codex.exe`；CSGClaw 会通过 `cmd.exe` 启动命令 shim，但不支持 `codex.ps1`。
 - `CSGCLAW_CODEX_ACP_PATH`：迁移期间的兼容回退项，也指向同一个 `codex` 可执行文件路径
 
 ## OpenClaw Runtime
diff --git a/internal/api/handler.go b/internal/api/handler.go
index b85fd5ef..792dd562 100644
--- a/internal/api/handler.go
+++ b/internal/api/handler.go
@@ -550,7 +550,7 @@ func codexInstallGuidance(goos string) string {
 	case "darwin":
 		return "Install the Codex CLI for macOS, or set CSGCLAW_CODEX_PATH to the codex binary."
 	case "windows":
-		return "Install the Codex CLI for Windows, or set CSGCLAW_CODEX_PATH to codex.exe."
+		return "Install the Codex CLI for Windows, or set CSGCLAW_CODEX_PATH to codex.exe or the npm codex.cmd shim."
 	case "linux":
 		return "Install the Codex CLI for Linux, or set CSGCLAW_CODEX_PATH to the codex binary."
 	default:
diff --git a/internal/codexcli/command.go b/internal/codexcli/command.go
new file mode 100644
index 00000000..22aabb37
--- /dev/null
+++ b/internal/codexcli/command.go
@@ -0,0 +1,30 @@
+package codexcli
+
+import (
+	"fmt"
+	"path/filepath"
+	"strings"
+)
+
+func isWindowsCommandShimPath(path string) bool {
+	switch strings.ToLower(filepath.Ext(strings.TrimSpace(path))) {
+	case ".cmd", ".bat":
+		return true
+	default:
+		return false
+	}
+}
+
+// windowsBatchAppServerCommandLine builds the exact command line consumed by
+// cmd.exe. App-server arguments are fixed, so only the validated shim path is
+// interpolated into the shell command.
+func windowsBatchAppServerCommandLine(binaryPath string) (string, error) {
+	binaryPath = strings.TrimSpace(binaryPath)
+	if binaryPath == "" {
+		return "", fmt.Errorf("Codex command shim path is required")
+	}
+	if strings.ContainsAny(binaryPath, "\x00\r\n\"") || strings.Contains(binaryPath, "%") {
+		return "", fmt.Errorf("Codex command shim path %q contains characters that cannot be passed safely to cmd.exe", binaryPath)
+	}
+	return `/d /s /v:off /c ""` + binaryPath + `" ` + strings.Join(AppServerArgs(), " ") + `"`, nil
+}
diff --git a/internal/codexcli/command_nonwindows.go b/internal/codexcli/command_nonwindows.go
new file mode 100644
index 00000000..668069e7
--- /dev/null
+++ b/internal/codexcli/command_nonwindows.go
@@ -0,0 +1,12 @@
+//go:build !windows
+
+package codexcli
+
+import (
+	"context"
+	"os/exec"
+)
+
+func AppServerCommandContext(ctx context.Context, binaryPath string) (*exec.Cmd, error) {
+	return exec.CommandContext(ctx, binaryPath, AppServerArgs()...), nil
+}
diff --git a/internal/codexcli/command_test.go b/internal/codexcli/command_test.go
new file mode 100644
index 00000000..e2f3390e
--- /dev/null
+++ b/internal/codexcli/command_test.go
@@ -0,0 +1,41 @@
+package codexcli
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestWindowsBatchAppServerCommandLine(t *testing.T) {
+	path := `C:\Users\Jane Doe\AppData\Roaming\npm & tools\codex.cmd`
+	got, err := windowsBatchAppServerCommandLine(path)
+	if err != nil {
+		t.Fatalf("windowsBatchAppServerCommandLine() error = %v", err)
+	}
+	want := `/d /s /v:off /c ""C:\Users\Jane Doe\AppData\Roaming\npm & tools\codex.cmd" app-server --listen stdio://"`
+	if got != want {
+		t.Fatalf("windowsBatchAppServerCommandLine() = %q, want %q", got, want)
+	}
+}
+
+func TestWindowsBatchAppServerCommandLineRejectsUnsafePath(t *testing.T) {
+	for _, path := range []string{"", `C:\npm\%USER%\codex.cmd`, "C:\\npm\\codex.cmd\r\nwhoami"} {
+		t.Run(strings.ReplaceAll(path, "\\", "_"), func(t *testing.T) {
+			if _, err := windowsBatchAppServerCommandLine(path); err == nil {
+				t.Fatalf("windowsBatchAppServerCommandLine(%q) error = nil, want error", path)
+			}
+		})
+	}
+}
+
+func TestIsWindowsCommandShimPath(t *testing.T) {
+	for _, path := range []string{`C:\npm\codex.cmd`, `C:\npm\CODEX.BAT`} {
+		if !isWindowsCommandShimPath(path) {
+			t.Fatalf("isWindowsCommandShimPath(%q) = false, want true", path)
+		}
+	}
+	for _, path := range []string{`C:\npm\codex.exe`, `C:\npm\codex.ps1`, "/usr/bin/codex"} {
+		if isWindowsCommandShimPath(path) {
+			t.Fatalf("isWindowsCommandShimPath(%q) = true, want false", path)
+		}
+	}
+}
diff --git a/internal/codexcli/command_windows.go b/internal/codexcli/command_windows.go
new file mode 100644
index 00000000..6860efb2
--- /dev/null
+++ b/internal/codexcli/command_windows.go
@@ -0,0 +1,28 @@
+//go:build windows
+
+package codexcli
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"strings"
+	"syscall"
+)
+
+func AppServerCommandContext(ctx context.Context, binaryPath string) (*exec.Cmd, error) {
+	if !isWindowsCommandShimPath(binaryPath) {
+		return exec.CommandContext(ctx, binaryPath, AppServerArgs()...), nil
+	}
+	commandLine, err := windowsBatchAppServerCommandLine(binaryPath)
+	if err != nil {
+		return nil, err
+	}
+	commandProcessor := strings.TrimSpace(os.Getenv("ComSpec"))
+	if commandProcessor == "" {
+		commandProcessor = "cmd.exe"
+	}
+	cmd := exec.CommandContext(ctx, commandProcessor)
+	cmd.SysProcAttr = &syscall.SysProcAttr{CmdLine: commandLine}
+	return cmd, nil
+}
diff --git a/internal/codexcli/command_windows_test.go b/internal/codexcli/command_windows_test.go
new file mode 100644
index 00000000..0d88b2e3
--- /dev/null
+++ b/internal/codexcli/command_windows_test.go
@@ -0,0 +1,39 @@
+//go:build windows
+
+package codexcli
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestAppServerCommandContextRunsWindowsCommandShim(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), "npm shim & (test)")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatalf("MkdirAll() error = %v", err)
+	}
+	shimPath := filepath.Join(dir, "codex.cmd")
+	shim := "@echo off\r\nset /p input=\r\necho %1^|%2^|%3^|%input%\r\n"
+	if err := os.WriteFile(shimPath, []byte(shim), 0o755); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+
+	cmd, err := AppServerCommandContext(context.Background(), shimPath)
+	if err != nil {
+		t.Fatalf("AppServerCommandContext() error = %v", err)
+	}
+	cmd.Stdin = strings.NewReader("ping\n")
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+	if err := cmd.Run(); err != nil {
+		t.Fatalf("Run() error = %v; stderr=%s", err, stderr.String())
+	}
+	if got, want := strings.TrimSpace(stdout.String()), "app-server|--listen|stdio://|ping"; got != want {
+		t.Fatalf("stdout = %q, want %q", got, want)
+	}
+}
diff --git a/internal/codexcli/installer_test.go b/internal/codexcli/installer_test.go
index 898b3ba3..c9158fbf 100644
--- a/internal/codexcli/installer_test.go
+++ b/internal/codexcli/installer_test.go
@@ -133,11 +133,54 @@ func TestInstallerEnsureInstallsWindowsExecutable(t *testing.T) {
 	assertFileContent(t, target, string(testPEBinary("arm64")))
 }
 
-func TestInstallerEnsureUsesManagedExecutableForWindowsCommandShim(t *testing.T) {
+func TestInstallerEnsureUsesExistingWindowsCommandShim(t *testing.T) {
 	dir := t.TempDir()
 	shimPath := writeExecutable(t, filepath.Join(dir, "npm", "codex.cmd"), "@echo off\n")
 	managedPath := filepath.Join(dir, "managed", "codex.exe")
 	t.Setenv(EnvBinaryPath, shimPath)
+	var requests atomic.Int32
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requests.Add(1)
+		if r.URL.Path != "/windows/amd64" || r.URL.Query().Get("package") != "codex-cli" {
+			t.Errorf("request URL = %s, want /windows/amd64?package=codex-cli", r.URL.String())
+		}
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write(testPEBinary("amd64"))
+	}))
+	defer server.Close()
+
+	installer := NewInstaller(InstallerOptions{
+		Locator: Locator{
+			ManagedPath: managedPath,
+			LookPath: func(string) (string, error) {
+				return "", os.ErrNotExist
+			},
+		},
+		BaseURL: server.URL,
+		GOOS:    "windows",
+		GOARCH:  "amd64",
+	})
+	status, err := installer.Ensure(context.Background())
+	if err != nil {
+		t.Fatalf("Ensure() error = %v", err)
+	}
+	if !status.Installed || status.Path != shimPath {
+		t.Fatalf("Ensure() status = %+v, want installed command shim at %q", status, shimPath)
+	}
+	if got := requests.Load(); got != 0 {
+		t.Fatalf("download requests = %d, want 0", got)
+	}
+	if _, statErr := os.Stat(managedPath); !os.IsNotExist(statErr) {
+		t.Fatalf("Stat(%q) error = %v, want no managed executable", managedPath, statErr)
+	}
+	assertFileContent(t, shimPath, "@echo off\n")
+}
+
+func TestInstallerEnsureUsesManagedExecutableForMissingWindowsCommandShim(t *testing.T) {
+	dir := t.TempDir()
+	shimPath := filepath.Join(dir, "npm", "codex.cmd")
+	managedPath := filepath.Join(dir, "managed", "codex.exe")
+	t.Setenv(EnvBinaryPath, shimPath)
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path != "/windows/amd64" || r.URL.Query().Get("package") != "codex-cli" {
 			t.Errorf("request URL = %s, want /windows/amd64?package=codex-cli", r.URL.String())
@@ -163,10 +206,9 @@ func TestInstallerEnsureUsesManagedExecutableForWindowsCommandShim(t *testing.T)
 		t.Fatalf("Ensure() error = %v", err)
 	}
 	if !status.Installed || status.Path != managedPath {
-		t.Fatalf("Ensure() status = %+v, want installed at %q", status, managedPath)
+		t.Fatalf("Ensure() status = %+v, want managed executable at %q", status, managedPath)
 	}
 	assertFileContent(t, managedPath, string(testPEBinary("amd64")))
-	assertFileContent(t, shimPath, "@echo off\n")
 }
 
 func TestInstallerEnsureCoalescesConcurrentDownloads(t *testing.T) {
diff --git a/internal/codexcli/locator.go b/internal/codexcli/locator.go
index 2c780fdf..1b53b67a 100644
--- a/internal/codexcli/locator.go
+++ b/internal/codexcli/locator.go
@@ -45,18 +45,18 @@ func (l Locator) Locate() (string, error) {
 		} else if ok {
 			return path, nil
 		}
+		path, ok, err := l.executablePath(explicit)
+		if err != nil {
+			return "", err
+		}
+		if ok {
+			return path, nil
+		}
 		if !l.isWindowsCommandShim(explicit) {
-			path, ok, err := l.executablePath(explicit)
-			if err != nil {
-				return "", err
-			}
-			if ok {
-				return path, nil
-			}
 			return "", fmt.Errorf("codex binary %s: %w", explicit, os.ErrNotExist)
 		}
-		// Batch shims cannot be passed directly to CreateProcess. Continue to a
-		// native PATH or managed executable so startup installation can recover.
+		// A missing command shim can still recover through PATH or the managed
+		// native executable installed by CSGClaw.
 	}
 	if lookPath := l.lookPath(); lookPath != nil {
 		for _, name := range l.binaryNames() {
@@ -130,10 +130,14 @@ func (l Locator) executablePath(path string) (string, bool, error) {
 		return "", false, nil
 	}
 	if l.isWindows() {
-		if !strings.EqualFold(filepath.Ext(path), ".exe") {
-			return "", false, fmt.Errorf("codex binary %s is a script shim; set %s to a native codex.exe file", path, EnvBinaryPath)
+		switch strings.ToLower(filepath.Ext(path)) {
+		case ".exe", ".cmd", ".bat":
+			return path, true, nil
+		case ".ps1":
+			return "", false, fmt.Errorf("codex binary %s is a PowerShell shim; set %s to codex.cmd, codex.bat, or codex.exe", path, EnvBinaryPath)
+		default:
+			return "", false, fmt.Errorf("codex binary %s is not a supported Windows executable; set %s to codex.cmd, codex.bat, or codex.exe", path, EnvBinaryPath)
 		}
-		return path, true, nil
 	}
 	if info.Mode()&0o111 == 0 {
 		return "", false, nil
@@ -181,7 +185,7 @@ func (l Locator) stat(path string) (os.FileInfo, error) {
 
 func (l Locator) binaryNames() []string {
 	if l.isWindows() {
-		return []string{BinaryName + ".exe"}
+		return []string{BinaryName + ".exe", BinaryName + ".cmd", BinaryName + ".bat"}
 	}
 	return []string{BinaryName}
 }
diff --git a/internal/codexcli/locator_test.go b/internal/codexcli/locator_test.go
index 93bcb7bc..4f131b21 100644
--- a/internal/codexcli/locator_test.go
+++ b/internal/codexcli/locator_test.go
@@ -2,6 +2,7 @@ package codexcli
 
 import (
 	"errors"
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
@@ -159,7 +160,7 @@ func TestLocatorWindowsPathLookupUsesNativeExecutable(t *testing.T) {
 	}
 }
 
-func TestLocatorWindowsPathLookupIgnoresScriptShims(t *testing.T) {
+func TestLocatorWindowsPathLookupPrefersNativeExecutable(t *testing.T) {
 	dir := t.TempDir()
 	_ = writeExecutable(t, filepath.Join(dir, "bin", "codex.cmd"), "@echo off\n")
 	exeBinary := writeExecutable(t, filepath.Join(dir, "bin", "codex.exe"), "")
@@ -188,6 +189,34 @@ func TestLocatorWindowsPathLookupIgnoresScriptShims(t *testing.T) {
 	}
 }
 
+func TestLocatorWindowsPathLookupFallsBackToCommandShim(t *testing.T) {
+	dir := t.TempDir()
+	cmdBinary := writeExecutable(t, filepath.Join(dir, "bin", "codex.cmd"), "@echo off\n")
+	var names []string
+
+	locator := Locator{
+		GOOS: "windows",
+		LookPath: func(name string) (string, error) {
+			names = append(names, name)
+			if name == "codex.cmd" {
+				return cmdBinary, nil
+			}
+			return "", os.ErrNotExist
+		},
+	}
+
+	got, err := locator.Locate()
+	if err != nil {
+		t.Fatalf("Locate() error = %v", err)
+	}
+	if got != cmdBinary {
+		t.Fatalf("Locate() = %q, want %q", got, cmdBinary)
+	}
+	if want := []string{"codex.exe", "codex.cmd"}; fmt.Sprint(names) != fmt.Sprint(want) {
+		t.Fatalf("LookPath names = %+v, want %+v", names, want)
+	}
+}
+
 func TestLocatorWindowsExplicitPowerShellShimUsesNativeSibling(t *testing.T) {
 	dir := t.TempDir()
 	ps1Path := filepath.Join(dir, "codex.ps1")
@@ -224,16 +253,38 @@ func TestLocatorWindowsExplicitPowerShellShimReportsUnsupportedWhenNoSibling(t *
 	if err == nil {
 		t.Fatal("Locate() error = nil, want unsupported PowerShell shim error")
 	}
-	if !strings.Contains(err.Error(), "script shim") || !strings.Contains(err.Error(), "codex.exe") {
-		t.Fatalf("Locate() error = %v, want native executable guidance", err)
+	if !strings.Contains(err.Error(), "PowerShell shim") || !strings.Contains(err.Error(), "codex.cmd") {
+		t.Fatalf("Locate() error = %v, want command shim guidance", err)
 	}
 }
 
-func TestLocatorWindowsExplicitCommandShimFallsBackToManagedNativeExecutable(t *testing.T) {
+func TestLocatorWindowsExplicitCommandShimIsSupported(t *testing.T) {
 	dir := t.TempDir()
 	cmdPath := writeExecutable(t, filepath.Join(dir, "codex.cmd"), "@echo off\n")
 	managedPath := writeExecutable(t, filepath.Join(dir, "managed", "codex.exe"), "")
 
+	got, err := (Locator{
+		GOOS:         "windows",
+		ExplicitPath: cmdPath,
+		ManagedPath:  managedPath,
+		LookPath: func(string) (string, error) {
+			t.Fatal("LookPath should not be called for an existing explicit command shim")
+			return "", nil
+		},
+	}).Locate()
+	if err != nil {
+		t.Fatalf("Locate() error = %v", err)
+	}
+	if got != cmdPath {
+		t.Fatalf("Locate() = %q, want %q", got, cmdPath)
+	}
+}
+
+func TestLocatorWindowsMissingExplicitCommandShimFallsBackToManagedNativeExecutable(t *testing.T) {
+	dir := t.TempDir()
+	cmdPath := filepath.Join(dir, "missing", "codex.cmd")
+	managedPath := writeExecutable(t, filepath.Join(dir, "managed", "codex.exe"), "")
+
 	got, err := (Locator{
 		GOOS:         "windows",
 		ExplicitPath: cmdPath,
diff --git a/internal/runtime/codex/appserver_manager.go b/internal/runtime/codex/appserver_manager.go
index 2cf73a90..0bcf715a 100644
--- a/internal/runtime/codex/appserver_manager.go
+++ b/internal/runtime/codex/appserver_manager.go
@@ -24,7 +24,7 @@ var (
 	appServerFirstTurnNoProgressTimeout = 90 * time.Second
 )
 
-var appServerCommandContext = exec.CommandContext
+var appServerCommandContext = codexcli.AppServerCommandContext
 
 type appServerManager struct {
 	deps      managerDeps
@@ -60,12 +60,17 @@ func (m *appServerManager) Start(ctx context.Context, spec SessionSpec) (*Sessio
 		return nil, fmt.Errorf("open stderr log %s: %w", spec.StderrPath, err)
 	}
 
-	args := codexcli.AppServerArgs()
-	cmd := appServerCommandContext(ctx, spec.BinaryPath, args...)
+	cmd, err := appServerCommandContext(ctx, spec.BinaryPath)
+	if err != nil {
+		_ = stderrFile.Close()
+		return nil, fmt.Errorf("prepare codex app-server command: %w", err)
+	}
 	cmd.Dir = spec.WorkspaceDir
 	cmd.Env = buildSessionEnv(spec)
 	cmd.Stderr = stderrFile
-	cmd.SysProcAttr = newSessionSysProcAttr()
+	if sysProcAttr := newSessionSysProcAttr(); sysProcAttr != nil {
+		cmd.SysProcAttr = sysProcAttr
+	}
 
 	stdin, err := cmd.StdinPipe()
 	if err != nil {
diff --git a/internal/runtime/codex/appserver_manager_test.go b/internal/runtime/codex/appserver_manager_test.go
index 65bae08b..8da58243 100644
--- a/internal/runtime/codex/appserver_manager_test.go
+++ b/internal/runtime/codex/appserver_manager_test.go
@@ -897,9 +897,9 @@ func TestAppServerEventAdapterProtocolDetectionAndSubagentFilter(t *testing.T) {
 func withAppServerHelperCommand(t *testing.T, mode string) {
 	t.Helper()
 	original := appServerCommandContext
-	appServerCommandContext = func(ctx context.Context, _ string, _ ...string) *exec.Cmd {
+	appServerCommandContext = func(ctx context.Context, _ string) (*exec.Cmd, error) {
 		args := []string{"-test.run=TestAppServerManagerHelperProcess", "--", mode}
-		return exec.CommandContext(ctx, os.Args[0], args...)
+		return exec.CommandContext(ctx, os.Args[0], args...), nil
 	}
 	t.Cleanup(func() { appServerCommandContext = original })
 }
diff --git a/internal/runtimecatalog/service_test.go b/internal/runtimecatalog/service_test.go
index a4d58e28..af86ef50 100644
--- a/internal/runtimecatalog/service_test.go
+++ b/internal/runtimecatalog/service_test.go
@@ -44,6 +44,31 @@ func TestServiceListReportsMissingCodexFromEnvOverride(t *testing.T) {
 	}
 }
 
+func TestServiceListReportsWindowsCommandShimAsInstalled(t *testing.T) {
+	target := filepath.Join(t.TempDir(), "npm", "codex.cmd")
+	if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
+		t.Fatalf("MkdirAll() error = %v", err)
+	}
+	if err := os.WriteFile(target, []byte("@echo off\r\n"), 0o755); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+	installer := codexcli.NewInstaller(codexcli.InstallerOptions{
+		Locator: codexcli.Locator{GOOS: "windows", ExplicitPath: target},
+		GOOS:    "windows",
+		GOARCH:  "amd64",
+		BaseURL: "https://unused.invalid",
+	})
+	service := NewService(
+		WithCodexInstaller(installer),
+		WithPlatform("windows", "amd64"),
+	)
+
+	got := service.List()[0]
+	if !got.Installed || got.Status != string(codexcli.InstallStateInstalled) || got.Path != target {
+		t.Fatalf("Codex runtime = %+v, want installed command shim at %q", got, target)
+	}
+}
+
 func TestServiceInstallRejectsUnsupportedAndUnknownRuntimes(t *testing.T) {
 	service := NewService()
 	if _, err := service.Install(context.Background(), RuntimeClaudeCode); !errors.Is(err, ErrInstallUnsupported) {