Resolve version-manager shims to stable paths for Codex CLI launches

When the resolved path for the Codex CLI is a version-manager shim (e.g.,
asdf or mise), this change resolves it to the underlying installed
executable. This ensures that child subprocess launches remain stable
and do not depend on the specific working directory where the shim was
originally invoked.

Key changes include:
- Refactored CLI resolution to return a CommandSpec instead of just a path.
- Updated internal launchers to utilize the resolved CommandSpec.
- Added a connection test verifying that shim-based paths correctly
  resolve to stable locations.
- Improved cleanup logic in Codex.Exec to avoid unnecessary waits after
  final stream events.

Author: nshkrdotcom

README.md

@@ -75,6 +75,9 @@ resolution follows this order:
 3. `System.find_executable("codex")`
 
 Make sure the binary at the resolved location is executable and kept up to date.
+When the resolved path is a version-manager shim (for example `asdf`/`mise`), the SDK
+stabilizes it to the underlying installed executable when possible so child subprocess
+launches do not depend on the child working directory.
 
 For authentication, sign in with your ChatGPT account (this stores credentials for the CLI):
 

guides/05-app-server-transport.md

@@ -30,6 +30,8 @@ instead of relying on a pre-existing CLI login:
   initialization and optionally auto-answers refresh requests
 
 The SDK resolves the `codex` executable via `codex_path_override` → `CODEX_PATH` → `System.find_executable("codex")`.
+When that path is a version-manager shim, the SDK resolves it to a stable installed
+binary when possible before launching the child process.
 
 If you need the literal command surface instead of the managed JSON-RPC connection,
 `Codex.CLI.app_server/1` launches a raw `codex app-server` subprocess session and

lib/codex/app_server/connection.ex

@@ -121,10 +121,10 @@ defmodule Codex.AppServer.Connection do
     init_params =
       initialize_params(client_name, client_version, client_title, experimental_api)
 
-    with {:ok, binary_path} <- build_command(codex_opts),
+    with {:ok, command_spec} <- build_command(codex_opts),
          {:ok, cwd} <- normalize_cwd(Keyword.get(opts, :cwd)),
          {:ok, env} <- build_env(codex_opts, opts),
-         invocation <- Command.new(binary_path, app_server_args(codex_opts), cwd: cwd, env: env),
+         invocation <- Command.new(command_spec, app_server_args(codex_opts), cwd: cwd, env: env),
          {:ok, raw_session} <-
            RawSession.start_link(
              invocation,
@@ -556,7 +556,7 @@ defmodule Codex.AppServer.Connection do
     end
   end
 
-  defp build_command(%Options{} = opts), do: Options.codex_path(opts)
+  defp build_command(%Options{} = opts), do: Options.codex_command_spec(opts)
 
   defp resolve_transport(opts) do
     opts

lib/codex/cli.ex

@@ -33,11 +33,11 @@ defmodule Codex.CLI do
     cwd = resolve_cwd(opts)
 
     with {:ok, codex_opts} <- normalize_codex_opts(opts),
-         {:ok, binary_path} <- Options.codex_path(codex_opts),
+         {:ok, command_spec} <- Options.codex_command_spec(codex_opts),
          {:ok, env_spec} <- build_env_spec(codex_opts, opts),
          {:ok, result} <-
            Command.run(
-             Command.new(binary_path, normalize_args(args),
+             Command.new(command_spec, normalize_args(args),
                cwd: cwd,
                env: env_spec.env,
                clear_env?: env_spec.clear_env?
@@ -58,7 +58,7 @@ defmodule Codex.CLI do
     cwd = resolve_cwd(opts)
 
     with {:ok, codex_opts} <- normalize_codex_opts(opts),
-         {:ok, binary_path} <- Options.codex_path(codex_opts),
+         {:ok, command_spec} <- Options.codex_command_spec(codex_opts),
          {:ok, env_spec} <- build_env_spec(codex_opts, opts) do
       session_opts = [
         receiver: Keyword.get(opts, :receiver, self()),
@@ -68,7 +68,7 @@ defmodule Codex.CLI do
         env: build_session_env(env_spec)
       ]
 
-      Session.start(binary_path, normalize_args(args), session_opts)
+      Session.start(command_spec, normalize_args(args), session_opts)
     end
   end
 

lib/codex/cli/session.ex

@@ -22,7 +22,7 @@ defmodule Codex.CLI.Session do
   Use `collect/2` to accumulate output until the process exits.
   """
 
-  alias CliSubprocessCore.{Command, RawSession}
+  alias CliSubprocessCore.{Command, CommandSpec, RawSession}
   alias CliSubprocessCore.Transport.Info
   alias Codex.Config.Defaults
   alias Codex.ProcessExit
@@ -53,11 +53,13 @@ defmodule Codex.CLI.Session do
         }
 
   @doc """
-  Starts a raw subprocess session for `binary_path` and `args`.
+  Starts a raw subprocess session for a resolved Codex program and `args`.
   """
-  @spec start(String.t(), [String.t()], keyword()) :: {:ok, t()} | {:error, term()}
-  def start(binary_path, args, opts \\ [])
-      when is_binary(binary_path) and is_list(args) and is_list(opts) do
+  @spec start(String.t() | CommandSpec.t(), [String.t()], keyword()) ::
+          {:ok, t()} | {:error, term()}
+  def start(binary_or_spec, args, opts \\ [])
+      when (is_binary(binary_or_spec) or is_struct(binary_or_spec, CommandSpec)) and is_list(args) and
+             is_list(opts) do
     receiver = Keyword.get(opts, :receiver, self())
     pty? = Keyword.get(opts, :pty, false)
     stdin? = Keyword.get(opts, :stdin, false)
@@ -66,7 +68,7 @@ defmodule Codex.CLI.Session do
 
     with {:ok, {env, clear_env?}} <- normalize_env_spec(Keyword.get(opts, :env)),
          invocation <-
-           Command.new(binary_path, args,
+           Command.new(binary_or_spec, args,
              cwd: Keyword.get(opts, :cwd),
              env: env,
              clear_env?: clear_env?
@@ -87,7 +89,7 @@ defmodule Codex.CLI.Session do
       {:ok,
        %__MODULE__{
          args: args,
-         command: [binary_path | args],
+         command: Command.argv(invocation),
          os_pid: os_pid,
          pid: pid,
          raw_session: raw_session,

lib/codex/exec.ex

@@ -258,7 +258,7 @@ defmodule Codex.Exec do
   defp safe_stop(%{session: session, session_ref: session_ref} = state) when is_pid(session) do
     maybe_unregister_cancellation(state)
     _ = RuntimeExec.close(session)
-    await_session_down_or_demonitor(state.session_monitor_ref, session)
+    maybe_await_session_down(state.session_monitor_ref, session)
     flush_session_messages(session_ref, state.session_event_tag)
     :ok
   rescue
@@ -318,6 +318,18 @@ defmodule Codex.Exec do
 
   defp await_session_down_or_demonitor(_ref, _session), do: :ok
 
+  defp maybe_await_session_down(ref, session)
+       when is_reference(ref) and is_pid(session) do
+    if Process.alive?(session) do
+      await_session_down_or_demonitor(ref, session)
+    else
+      Process.demonitor(ref, [:flush])
+      :ok
+    end
+  end
+
+  defp maybe_await_session_down(_ref, _session), do: :ok
+
   defp flush_session_messages(ref, session_event_tag)
        when is_reference(ref) and is_atom(session_event_tag) do
     receive do

lib/codex/options.ex

@@ -6,7 +6,7 @@ defmodule Codex.Options do
   """
 
   require Bitwise
-  alias CliSubprocessCore.ModelInput
+  alias CliSubprocessCore.{CommandSpec, ModelInput, ProviderCLI}
   alias Codex.Auth
   alias Codex.Config.BaseURL
   alias Codex.Config.OptionNormalizers
@@ -127,37 +127,49 @@ defmodule Codex.Options do
   end
 
   @doc """
-  Determines the executable path to `codex-rs`.
+  Determines a stable command spec for launching `codex`.
 
   Order of precedence:
   1. Explicit override on the struct.
   2. `CODEX_PATH` environment variable.
   3. `System.find_executable("codex")`.
   """
-  @spec codex_path(t()) :: {:ok, String.t()} | {:error, term()}
-  def codex_path(%__MODULE__{codex_path_override: override}) when is_binary(override) do
-    validate_executable(override)
+  @spec codex_command_spec(t()) :: {:ok, CommandSpec.t()} | {:error, term()}
+  def codex_command_spec(%__MODULE__{codex_path_override: override}) when is_binary(override) do
+    with {:ok, path} <- validate_executable(override) do
+      ProviderCLI.resolve(:codex, command: path)
+    end
   end
 
-  def codex_path(%__MODULE__{} = opts) do
+  def codex_command_spec(%__MODULE__{} = _opts) do
     env_path = System.get_env("CODEX_PATH")
 
-    path =
-      if env_path && env_path != "" do
-        env_path
-      else
-        System.find_executable("codex")
+    if is_binary(env_path) and env_path != "" do
+      with {:ok, path} <- validate_executable(env_path) do
+        ProviderCLI.resolve(:codex, command: path)
+      end
+    else
+      case ProviderCLI.resolve(:codex) do
+        {:ok, spec} -> {:ok, spec}
+        {:error, %ProviderCLI.Error{kind: :cli_not_found}} -> {:error, :codex_binary_not_found}
+        {:error, reason} -> {:error, reason}
       end
-
-    case path do
-      nil -> {:error, :codex_binary_not_found}
-      path -> validate_executable(path)
     end
-    |> add_override_ref(opts)
   end
 
-  defp add_override_ref(result, %__MODULE__{codex_path_override: nil}), do: result
-  defp add_override_ref(result, _opts), do: result
+  @doc """
+  Determines the stable executable path to `codex`.
+
+  This returns the resolved program from `codex_command_spec/1`. Internal
+  launchers should prefer `codex_command_spec/1` so argv prefixes remain
+  available when needed.
+  """
+  @spec codex_path(t()) :: {:ok, String.t()} | {:error, term()}
+  def codex_path(%__MODULE__{} = opts) do
+    with {:ok, %CommandSpec{program: program}} <- codex_command_spec(opts) do
+      {:ok, program}
+    end
+  end
 
   defp fetch_api_key(attrs) do
     case normalize_string(pick(attrs, [:api_key, "api_key"], Auth.api_key())) do

lib/codex/plugins.ex

@@ -11,6 +11,34 @@ defmodule Codex.Plugins do
 
   alias Codex.Plugins.{Manifest, Marketplace, Reader, Scaffold, Writer}
 
+  @type scaffold_result :: %{
+          scope: Codex.Plugins.Paths.scope(),
+          plugin_name: String.t(),
+          plugin_root: String.t(),
+          manifest_path: String.t(),
+          manifest: Manifest.t(),
+          skill_paths: [String.t()],
+          marketplace_path: String.t() | nil,
+          marketplace: Marketplace.t() | nil,
+          created_paths: [String.t()]
+        }
+
+  @type scaffold_error ::
+          {:plugin_io, %{action: atom(), path: String.t(), reason: term()}}
+          | {:invalid_plugin_json, %{path: String.t(), reason: String.t(), raw_reason: term()}}
+          | {:plugin_file_exists, %{path: String.t()}}
+          | {:repo_root_not_found, %{cwd: String.t()}}
+          | {:invalid_plugin_scope, %{scope: term()}}
+          | {:invalid_plugin_name, %{name: term(), message: String.t()}}
+          | {:invalid_plugin_root, %{path: String.t(), message: String.t()}}
+          | {:invalid_marketplace_path, %{path: String.t(), message: String.t()}}
+          | {:invalid_marketplace_source_path,
+             %{path: String.t(), source_path: String.t(), message: String.t()}}
+          | {:plugin_conflict, %{path: String.t(), plugin_name: String.t()}}
+          | {:invalid_plugin_manifest, CliSubprocessCore.Schema.error_detail()}
+          | {:invalid_plugin_marketplace, CliSubprocessCore.Schema.error_detail()}
+          | {:invalid_plugin_marketplace_plugin, CliSubprocessCore.Schema.error_detail()}
+
   @doc """
   Builds and validates a manifest struct.
   """
@@ -93,7 +121,7 @@ defmodule Codex.Plugins do
   @doc """
   Scaffolds a minimal local plugin tree.
   """
-  @spec scaffold(keyword()) :: {:ok, map()} | {:error, term()}
+  @spec scaffold(keyword()) :: {:ok, scaffold_result()} | {:error, scaffold_error()}
   def scaffold(opts), do: Scaffold.scaffold(opts)
 
   defp to_validation_result({:ok, _struct}), do: :ok

lib/codex/plugins/errors.ex

@@ -1,47 +1,80 @@
 defmodule Codex.Plugins.Errors do
   @moduledoc false
 
-  @spec io(atom(), Path.t(), term()) :: {:plugin_io, map()}
-  def io(action, path, reason) when is_atom(action) do
+  @type io_error :: {:plugin_io, %{action: atom(), path: String.t(), reason: term()}}
+  @type invalid_json_error ::
+          {:invalid_plugin_json, %{path: String.t(), reason: String.t(), raw_reason: term()}}
+  @type file_exists_error :: {:plugin_file_exists, %{path: String.t()}}
+  @type repo_root_not_found_error :: {:repo_root_not_found, %{cwd: String.t()}}
+  @type invalid_scope_error :: {:invalid_plugin_scope, %{scope: term()}}
+  @type invalid_plugin_name_error ::
+          {:invalid_plugin_name, %{name: term(), message: String.t()}}
+  @type invalid_plugin_root_error ::
+          {:invalid_plugin_root, %{path: String.t(), message: String.t()}}
+  @type invalid_marketplace_path_error ::
+          {:invalid_marketplace_path, %{path: String.t(), message: String.t()}}
+  @type invalid_marketplace_source_path_error ::
+          {:invalid_marketplace_source_path,
+           %{path: String.t(), source_path: String.t(), message: String.t()}}
+  @type plugin_conflict_error ::
+          {:plugin_conflict, %{path: String.t(), plugin_name: String.t()}}
+
+  @type t ::
+          io_error()
+          | invalid_json_error()
+          | file_exists_error()
+          | repo_root_not_found_error()
+          | invalid_scope_error()
+          | invalid_plugin_name_error()
+          | invalid_plugin_root_error()
+          | invalid_marketplace_path_error()
+          | invalid_marketplace_source_path_error()
+          | plugin_conflict_error()
+
+  @spec io(atom(), String.t(), term()) :: io_error()
+  def io(action, path, reason) when is_atom(action) and is_binary(path) do
     {:plugin_io, %{action: action, path: Path.expand(path), reason: reason}}
   end
 
-  @spec invalid_json(Path.t(), term()) :: {:invalid_plugin_json, map()}
-  def invalid_json(path, reason) do
+  @spec invalid_json(String.t(), term()) :: invalid_json_error()
+  def invalid_json(path, reason) when is_binary(path) do
     {:invalid_plugin_json,
      %{path: Path.expand(path), reason: format_reason(reason), raw_reason: reason}}
   end
 
-  @spec file_exists(Path.t()) :: {:plugin_file_exists, map()}
-  def file_exists(path), do: {:plugin_file_exists, %{path: Path.expand(path)}}
+  @spec file_exists(String.t()) :: file_exists_error()
+  def file_exists(path) when is_binary(path),
+    do: {:plugin_file_exists, %{path: Path.expand(path)}}
 
-  @spec repo_root_not_found(Path.t()) :: {:repo_root_not_found, map()}
-  def repo_root_not_found(path), do: {:repo_root_not_found, %{cwd: Path.expand(path)}}
+  @spec repo_root_not_found(String.t()) :: repo_root_not_found_error()
+  def repo_root_not_found(path) when is_binary(path),
+    do: {:repo_root_not_found, %{cwd: Path.expand(path)}}
 
-  @spec invalid_scope(term()) :: {:invalid_plugin_scope, map()}
+  @spec invalid_scope(term()) :: invalid_scope_error()
   def invalid_scope(scope), do: {:invalid_plugin_scope, %{scope: scope}}
 
-  @spec invalid_plugin_name(term(), String.t()) :: {:invalid_plugin_name, map()}
+  @spec invalid_plugin_name(term(), String.t()) :: invalid_plugin_name_error()
   def invalid_plugin_name(name, message),
     do: {:invalid_plugin_name, %{name: name, message: message}}
 
-  @spec invalid_plugin_root(Path.t(), String.t()) :: {:invalid_plugin_root, map()}
-  def invalid_plugin_root(path, message),
+  @spec invalid_plugin_root(String.t(), String.t()) :: invalid_plugin_root_error()
+  def invalid_plugin_root(path, message) when is_binary(path),
     do: {:invalid_plugin_root, %{path: Path.expand(path), message: message}}
 
-  @spec invalid_marketplace_path(Path.t(), String.t()) :: {:invalid_marketplace_path, map()}
-  def invalid_marketplace_path(path, message),
+  @spec invalid_marketplace_path(String.t(), String.t()) :: invalid_marketplace_path_error()
+  def invalid_marketplace_path(path, message) when is_binary(path),
     do: {:invalid_marketplace_path, %{path: Path.expand(path), message: message}}
 
-  @spec invalid_marketplace_source_path(Path.t(), String.t(), String.t()) ::
-          {:invalid_marketplace_source_path, map()}
-  def invalid_marketplace_source_path(path, source_path, message) do
+  @spec invalid_marketplace_source_path(String.t(), String.t(), String.t()) ::
+          invalid_marketplace_source_path_error()
+  def invalid_marketplace_source_path(path, source_path, message)
+      when is_binary(path) and is_binary(source_path) do
     {:invalid_marketplace_source_path,
      %{path: Path.expand(path), source_path: source_path, message: message}}
   end
 
-  @spec plugin_conflict(Path.t(), String.t()) :: {:plugin_conflict, map()}
-  def plugin_conflict(path, plugin_name) do
+  @spec plugin_conflict(String.t(), String.t()) :: plugin_conflict_error()
+  def plugin_conflict(path, plugin_name) when is_binary(path) and is_binary(plugin_name) do
     {:plugin_conflict, %{path: Path.expand(path), plugin_name: plugin_name}}
   end